refactor: Phase 2 single parse authority and session lifecycle

Add poste run --describe as the sole HTTP block metadata source, wire
Lua through describe.lua, and clear request-scoped state via HTTP/SQL
sessions on each run_* entry so prior request data cannot leak.

Author: beyondlex

.opencode/skills/http/SKILL.md

@@ -62,7 +62,9 @@ crosses protocols.
 | `context_detector.lua` | Detect context at cursor (within `###` block, inside `{%`, etc.) |
 | `data.lua` | Dynamic data definitions for the HTTP script API |
 | `highlights.lua` | Syntax highlighting for HTTP result buffers |
-| `cache.lua` | Response caching (ETag, Last-Modified) |
+| `cache.lua` | UI buffer index (line types, block bounds); semantic via describe |
+| `describe.lua` | Single parse authority — `poste run --describe` |
+| `session.lua` | Per-request session lifecycle (clears request-scoped state) |
 | `boundary_indicator.lua` | `###` block boundary indicator line |
 | `history.lua` | Request history: floating UI, persistence, navigation |
 

LEARNINGS.md

@@ -3,7 +3,9 @@
 Agent self-evolution log. When you fix a non-obvious bug or encounter a
 pitfall, log it here. Check this file before starting any task.
 
-- 2026-07-08: infra — Added `tools/relation-check.sh` for pre-flight code relation scanning. Run before modifying HTTP Lua code. Covers: `nvim_buf_set_lines` + `sanitize_lines` coverage, state field lifecycle (SET/READ/CLEAR), format function callers, pre-render consistency. Replaces the need for a manually-synced relation map. See `tools/relation-check.sh`.
+- 2026-07-19: Phase2 F1 — HTTP method/path/headers must not be re-parsed in Lua (`run.lua` / `indicators.extract_request_block` for semantics). Use `poste run --describe` via `lua/poste/http/describe.lua`. `cache.lua` keeps only UI line_type/bounds; semantic blocks via `cache.get_semantic_blocks()`. See `crates/poste-core/src/parser/mod.rs` `describe_blocks`, `crates/poste-cli/src/run.rs --describe`.
+- 2026-07-19: Phase2 F5 — Request-scoped state (`last_response`, `last_responses`, `response_index`, `_json` filter fields, `pending_request`, assertions/logs) must be cleared at every `run_*` entry via `http/session.begin()` / `sql/session.begin()`. Persistent: `global_vars`, `script_variables`, `http_history`, `current_env`, SQL connection/database. See `lua/poste/http/session.lua`.
+- 2026-07-08: infra — Added `tools/relation-check.sh` for pre-flight code relation scanning. Run before modifying HTTP Lua code. Covers: `nvim_buf_set_lines` + `sanitize_lines` coverage, state field lifecycle (SET/READ/CLEAR), format function callers, pre-render consistency, session lifecycle. See `tools/relation-check.sh`.
 
 - 2026-07-05: HTTP Verbose tab shows `{{base_url}}/users/42` instead of resolved URL. Fix: `build_pending_request` in `run.lua:212` only resolved `@var` definitions but not `{{var}}` from env.json. Added env.json var resolution with iterative chaining. See `lua/poste/http/run.lua:212`.
 - 2026-07-05: Picker forced to snacks.nvim. Removed auto-detection (telescope/fzf/mini/snacks chain). `select.lua` now requires snacks as hard dependency, with built-in float + vim.ui.select fallbacks. Normalizes items to `{key, name, description}` format. See `lua/poste/select.lua`.

crates/poste-cli/src/run.rs

@@ -9,15 +9,19 @@ pub struct RunArgs {
     /// File path (used for env.json discovery and extension detection;
     /// with --stdin the file does not need to exist on disk)
     pub file: String,
-    /// Line number
-    #[arg(short, long)]
+    /// Line number (required for execution; ignored with --describe unless filtering)
+    #[arg(short, long, default_value = "1")]
     pub line: usize,
     /// Environment name
     #[arg(short, long, default_value = "dev")]
     pub env: String,
     /// Output as JSON (for Neovim plugin consumption)
     #[arg(long)]
     pub json: bool,
+    /// Describe all request blocks as JSON metadata (no execution).
+    /// Single source of truth for block name/line/method/path/headers.
+    #[arg(long)]
+    pub describe: bool,
     /// Read request content from stdin instead of from the file
     #[arg(long)]
     pub stdin: bool,
@@ -97,6 +101,15 @@ pub async fn execute(args: RunArgs) -> Result<()> {
         std::fs::read_to_string(&canonical)?
     };
 
+    // --describe: emit block metadata JSON and exit (no network I/O).
+    // Always returns a JSON array of BlockMeta — single parse authority for Lua.
+    if args.describe {
+        let parser = poste_core::Parser::new(env_vars);
+        let blocks = parser.describe_blocks(&content, &file_ext)?;
+        println!("{}", serde_json::to_string(&blocks)?);
+        return Ok(());
+    }
+
     // Parse the request
     let parser = poste_core::Parser::new(env_vars.clone());
     let mut request = parser.parse_at_line(&content, args.line, &file_ext)?;

crates/poste-core/src/lib.rs

@@ -11,5 +11,5 @@ pub mod sql_parser;
 
 pub use env::{substitute_vars, Environment};
 pub use formatter::{Formatter, Region, ScriptStyle, ScriptType, Tokenizer, VarStyle};
-pub use parser::{Parser, VarResolver};
+pub use parser::{BlockMeta, Parser, VarResolver};
 pub use request::{replace_database_in_url, Protocol, Request};

crates/poste-core/src/parser/mod.rs

@@ -1,12 +1,42 @@
 use crate::request::{Protocol, Request};
 use anyhow::Result;
 use regex::Regex;
+use serde::{Deserialize, Serialize};
 use std::collections::HashMap;
 use std::sync::OnceLock;
 
 pub mod vars;
 pub use vars::VarResolver;
 
+/// Structured metadata for a single `###` request block.
+/// Emitted by `poste run --describe` so Lua does not re-parse HTTP semantics.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct BlockMeta {
+    /// Request name from the `### Name` line (empty string if unnamed).
+    pub name: String,
+    /// 1-indexed start line of the block (`###` line, or 1 if no separator).
+    pub line: usize,
+    /// 1-indexed inclusive end line of the block content.
+    pub end_line: usize,
+    /// HTTP method / Redis command / SCRIPT / first token of request line.
+    pub method: String,
+    /// URL path (HTTP) or remainder of the request line (other protocols).
+    pub path: String,
+    /// Request headers as `[name, value]` pairs (HTTP only; empty otherwise).
+    pub headers: Vec<(String, String)>,
+    /// Request body after headers (may be empty).
+    pub body: String,
+    /// Full first request line (e.g. `GET https://example.com/users`).
+    pub request_line: String,
+}
+
+/// A raw `###` block with absolute line numbers (1-indexed).
+struct RawBlock {
+    start_line: usize,
+    end_line: usize,
+    content: String,
+}
+
 pub struct Parser {
     env: HashMap<String, String>,
 }
@@ -27,43 +57,187 @@ impl Parser {
         }
     }
 
+    /// Split content into raw blocks by `###` markers, tracking 1-indexed lines.
+    fn split_raw_blocks(content: &str) -> Vec<RawBlock> {
+        let mut blocks = Vec::new();
+        let mut current = String::new();
+        let mut start_line: usize = 1;
+        let mut line_no: usize = 0;
+
+        for line in content.lines() {
+            line_no += 1;
+            if line.trim().starts_with("###") && !current.is_empty() {
+                blocks.push(RawBlock {
+                    start_line,
+                    end_line: line_no - 1,
+                    content: std::mem::take(&mut current),
+                });
+                start_line = line_no;
+            }
+            current.push_str(line);
+            current.push('\n');
+        }
+        if !current.is_empty() {
+            blocks.push(RawBlock {
+                start_line,
+                end_line: line_no.max(1),
+                content: current,
+            });
+        }
+        blocks
+    }
+
     /// Parse a request file and extract the request at the given line.
     /// `file_ext` is the file extension (without dot), used for protocol detection.
     pub fn parse_at_line(&self, content: &str, line_num: usize, file_ext: &str) -> Result<Request> {
         let protocol = Self::detect_protocol(file_ext);
-
-        // Extract file-level variables (before first ###)
         let file_vars = self.extract_file_variables(content);
+        let blocks = Self::split_raw_blocks(content);
 
-        // Split content into request blocks by ### markers
-        let mut blocks = Vec::new();
-        let mut current_block = String::new();
-
-        for line in content.lines() {
-            if line.trim().starts_with("###") && !current_block.is_empty() {
-                blocks.push(current_block.clone());
-                current_block.clear();
+        for block in &blocks {
+            if line_num >= block.start_line && line_num <= block.end_line {
+                return self.parse_block(&block.content, protocol, &file_vars);
             }
-            current_block.push_str(line);
-            current_block.push('\n');
-        }
-        if !current_block.is_empty() {
-            blocks.push(current_block);
+            // Fallback: cursor on inter-block separator falls into the next block
+            // only when line_num matches start; otherwise use cumulative range like before.
         }
 
-        // Find the block containing the cursor line
-        let mut current_line = 0;
+        // Preserve prior semantics: first block whose cumulative end >= line_num.
+        let mut current_line = 0usize;
         for block in &blocks {
-            let block_lines = block.lines().count();
+            let block_lines = block.content.lines().count();
             if current_line + block_lines >= line_num {
-                return self.parse_block(block, protocol, &file_vars);
+                return self.parse_block(&block.content, protocol, &file_vars);
             }
             current_line += block_lines;
         }
 
         anyhow::bail!("No request found at line {}", line_num);
     }
 
+    /// Describe all request blocks in `content` as structured metadata.
+    ///
+    /// This is the single parse authority for block name/line/method/path/headers.
+    /// Variable substitution uses the same rules as `parse_at_line`.
+    pub fn describe_blocks(&self, content: &str, file_ext: &str) -> Result<Vec<BlockMeta>> {
+        let protocol = Self::detect_protocol(file_ext);
+        let file_vars = self.extract_file_variables(content);
+        let raw_blocks = Self::split_raw_blocks(content);
+        let mut out = Vec::with_capacity(raw_blocks.len());
+
+        for raw in raw_blocks {
+            // Skip pure preamble (file-level vars only, no ### and no request line)
+            let has_separator = raw.content.lines().any(|l| l.trim().starts_with("###"));
+            let request = match self.parse_block(&raw.content, protocol.clone(), &file_vars) {
+                Ok(r) => r,
+                Err(_) if !has_separator => continue, // file preamble without a request
+                Err(e) => return Err(e),
+            };
+
+            let body_str = request.body_str();
+            let (method, path, headers, body, request_line) =
+                Self::extract_request_parts(body_str, &protocol);
+
+            // File-level preamble parses as empty Request — skip unless it has a real request
+            if request_line.is_empty() && !has_separator {
+                continue;
+            }
+
+            out.push(BlockMeta {
+                name: request.name.unwrap_or_default(),
+                line: raw.start_line,
+                end_line: raw.end_line,
+                method,
+                path,
+                headers,
+                body,
+                request_line,
+            });
+        }
+
+        Ok(out)
+    }
+
+    /// Split a resolved request body into method / path / headers / body parts.
+    fn extract_request_parts(
+        body: &str,
+        protocol: &Protocol,
+    ) -> (String, String, Vec<(String, String)>, String, String) {
+        let lines: Vec<&str> = body.lines().collect();
+        if lines.is_empty() {
+            return (
+                String::new(),
+                String::new(),
+                Vec::new(),
+                String::new(),
+                String::new(),
+            );
+        }
+
+        // Find first non-empty non-comment line as the request line
+        let mut idx = 0usize;
+        while idx < lines.len() {
+            let t = lines[idx].trim();
+            if t.is_empty() || t.starts_with('#') {
+                idx += 1;
+                continue;
+            }
+            break;
+        }
+        if idx >= lines.len() {
+            return (
+                String::new(),
+                String::new(),
+                Vec::new(),
+                String::new(),
+                String::new(),
+            );
+        }
+
+        let request_line = lines[idx].trim().to_string();
+        let (method, path) = match request_line.split_once(char::is_whitespace) {
+            Some((m, rest)) => (m.to_string(), rest.trim().to_string()),
+            None => (request_line.clone(), String::new()),
+        };
+
+        let mut headers = Vec::new();
+        let mut body_start = idx + 1;
+
+        if matches!(protocol, Protocol::Http) {
+            let mut i = idx + 1;
+            while i < lines.len() {
+                let t = lines[i].trim();
+                if t.is_empty() {
+                    body_start = i + 1;
+                    break;
+                }
+                if let Some((k, v)) = lines[i].split_once(':') {
+                    headers.push((k.trim().to_string(), v.trim().to_string()));
+                    body_start = i + 1;
+                } else {
+                    // Non-header line without blank separator — treat as body start
+                    body_start = i;
+                    break;
+                }
+                i += 1;
+                if i == lines.len() {
+                    body_start = i;
+                }
+            }
+        } else {
+            // Non-HTTP: everything after request line is body
+            body_start = idx + 1;
+        }
+
+        let body = if body_start < lines.len() {
+            lines[body_start..].join("\n")
+        } else {
+            String::new()
+        };
+
+        (method, path, headers, body, request_line)
+    }
+
     fn parse_block(
         &self,
         block: &str,
@@ -877,4 +1051,70 @@ X-Val: {{a}}
         let body = req.body_str();
         assert!(body.contains("X-Val: {{b}}") || body.contains("X-Val: {{a}}"));
     }
+
+    // ---- describe_blocks (Phase 2 single parse authority) ----
+
+    #[test]
+    fn test_describe_blocks_basic() {
+        let parser = Parser::new(HashMap::new());
+        let content = r#"@base = http://example.com
+
+### Get Users
+GET {{base}}/api/users
+Accept: application/json
+
+### Create User
+POST {{base}}/api/users
+Content-Type: application/json
+
+{"name": "Ada"}
+"#;
+        let blocks = parser.describe_blocks(content, "http").unwrap();
+        assert_eq!(blocks.len(), 2);
+
+        assert_eq!(blocks[0].name, "Get Users");
+        assert_eq!(blocks[0].line, 3);
+        assert_eq!(blocks[0].method, "GET");
+        assert_eq!(blocks[0].path, "http://example.com/api/users");
+        assert_eq!(blocks[0].headers.len(), 1);
+        assert_eq!(blocks[0].headers[0].0, "Accept");
+        assert_eq!(blocks[0].headers[0].1, "application/json");
+        assert_eq!(blocks[0].request_line, "GET http://example.com/api/users");
+
+        assert_eq!(blocks[1].name, "Create User");
+        assert_eq!(blocks[1].method, "POST");
+        assert!(blocks[1].body.contains(r#""name": "Ada""#));
+        assert_eq!(blocks[1].headers[0].0, "Content-Type");
+    }
+
+    #[test]
+    fn test_describe_blocks_line_numbers() {
+        let parser = Parser::new(HashMap::new());
+        let content = "### A\nGET /a\n\n### B\nGET /b\n";
+        let blocks = parser.describe_blocks(content, "http").unwrap();
+        assert_eq!(blocks.len(), 2);
+        assert_eq!(blocks[0].line, 1);
+        assert_eq!(blocks[0].end_line, 3); // includes blank line before next ###
+        assert_eq!(blocks[1].line, 4);
+        assert_eq!(blocks[1].method, "GET");
+        assert_eq!(blocks[1].path, "/b");
+    }
+
+    #[test]
+    fn test_describe_blocks_skips_preamble_only() {
+        let parser = Parser::new(HashMap::new());
+        // Content with only file-level vars and no ### — no blocks
+        let content = "@x = 1\n@y = 2\n";
+        let blocks = parser.describe_blocks(content, "http").unwrap();
+        assert!(blocks.is_empty());
+    }
+
+    #[test]
+    fn test_describe_blocks_script() {
+        let parser = Parser::new(HashMap::new());
+        let content = "### Setup\nSCRIPT\n";
+        let blocks = parser.describe_blocks(content, "http").unwrap();
+        assert_eq!(blocks.len(), 1);
+        assert_eq!(blocks[0].method, "SCRIPT");
+    }
 }