@gotgenes/pi-permission-system 16.2.0 → 16.2.1

package/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.2.0...pi-permission-system-v16.2.1) (2026-06-27)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** floor opaque bash -c/eval wrappers to ask ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e69493c](https://github.com/gotgenes/pi-packages/commit/e69493c00a04fdcdc1a972ef04ffee5839c93d2a))
+* **pi-permission-system:** strip env-var assignment prefix from bash command units ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1c99fb3](https://github.com/gotgenes/pi-packages/commit/1c99fb3835442dce3cb01b89f26db0a39084b7af))
+
+
+### Documentation
+
+* **pi-permission-system:** document env-prefix stripping and opaque bash-wrapper floor ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([40c0012](https://github.com/gotgenes/pi-packages/commit/40c001270249ace6a9d471c92063f9f09aa67238))
+* **pi-permission-system:** note opaque-wrapper sentinel in README and skill ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([e226fe7](https://github.com/gotgenes/pi-packages/commit/e226fe7a49218fac73f2dcb8c84cb13608d48fa0))
+* **pi-permission-system:** note prefix strip and opaque flag in commands() JSDoc ([#481](https://github.com/gotgenes/pi-packages/issues/481)) ([1892098](https://github.com/gotgenes/pi-packages/commit/18920980e0b17b6dd5e51a75fd103663f9313b32))
+
 ## [16.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v16.1.0...pi-permission-system-v16.2.0) (2026-06-26)
 
 

package/README.md

@@ -19,7 +19,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an opaque `bash -c`/`eval` wrapper — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
 - **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "16.2.0",
+  "version": "16.2.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/access-intent/bash/command-enumeration.ts

@@ -18,6 +18,12 @@ export interface BashCommand {
    * for a current-shell (top-level) command.
    */
   readonly context?: BashCommandContext;
+  /**
+   * True when this is an opaque-payload wrapper (`bash -c`/`eval`) whose inner
+   * program is not re-parsed; its decision is floored to at least `ask` so it
+   * cannot ride a permissive `allow`.
+   */
+  readonly opaque?: boolean;
 }
 
 // ── Command enumeration ──────────────────────────────────────────────────────
@@ -75,6 +81,9 @@ const NESTED_EXECUTION_CONTEXTS = new Map<string, BashCommandContext>([
  *
  * The enclosing command/subshell is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
+ *
+ * Each emitted command unit has any leading `variable_assignment` prefix
+ * stripped (so an env-var prefix cannot defeat a command-pattern rule).
  */
 export function collectCommands(node: TSNode): BashCommand[] {
   const out: BashCommand[] = [];
@@ -93,7 +102,9 @@ function collectCommandsInto(
   if (COMMAND_ENUM_SKIP.has(node.type)) return;
 
   if (node.type === "command") {
-    out.push(makeUnit(node.text, context));
+    out.push(
+      makeUnit(commandUnitText(node), context, isOpaqueWrapperCommand(node)),
+    );
     // A command's text already contains any substitution; descend its subtree
     // to ALSO emit the inner commands of command/process substitutions.
     collectSubstitutionCommands(node, out);
@@ -119,8 +130,74 @@ function collectCommandsInto(
 function makeUnit(
   text: string,
   context: BashCommandContext | undefined,
+  opaque = false,
 ): BashCommand {
-  return context ? { text, context } : { text };
+  const unit: BashCommand = context ? { text, context } : { text };
+  return opaque ? { ...unit, opaque } : unit;
+}
+
+/**
+ * Shell command names whose `-c` flag introduces an opaque inline program.
+ */
+const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
+
+/**
+ * True when a `command` node is an opaque-payload wrapper: a shell
+ * (`bash`/`sh`/`dash`/`zsh`/`ksh`) invoked with a `-c` flag, or `eval`. Its
+ * inner program is a quoted argument the enumerator does not re-parse, so the
+ * wrapper's decision is later floored to at least `ask`.
+ *
+ * The command name is matched on its basename (so `/bin/bash -c …` counts), and
+ * a `-c` flag is recognized within a short-flag cluster (`-c`, `-ec`, `-xc`).
+ * A leading `variable_assignment` prefix is skipped, matching `commandUnitText`.
+ */
+function isOpaqueWrapperCommand(node: TSNode): boolean {
+  let commandName: string | undefined;
+  let sawShortFlagC = false;
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (child.type === "variable_assignment") continue;
+    if (commandName === undefined) {
+      commandName = basename(child.text);
+      continue;
+    }
+    const text = child.text;
+    if (text === "--") break;
+    if (text.startsWith("-") && !text.startsWith("--") && text.includes("c")) {
+      sawShortFlagC = true;
+    }
+  }
+  if (commandName === undefined) return false;
+  if (commandName === "eval") return true;
+  return SHELL_WRAPPER_NAMES.has(commandName) && sawShortFlagC;
+}
+
+/** The final path segment of a command name (`/bin/bash` → `bash`). */
+function basename(name: string): string {
+  const slash = name.lastIndexOf("/");
+  return slash === -1 ? name : name.slice(slash + 1);
+}
+
+/**
+ * The command-pattern text of a `command` node, with any leading
+ * `variable_assignment` prefix stripped.
+ *
+ * An env-var prefix (`AWS_PROFILE=prod aws …`, `PGPASSWORD=…`) is part of the
+ * `command` node's text but must not defeat a rule that gates the underlying
+ * command, so matching targets the text from the first non-assignment child
+ * (the `command_name`) onward, sliced verbatim to preserve spacing. A pure
+ * assignment (`FOO=bar`, no `command_name`) runs no command and is returned
+ * unchanged.
+ */
+function commandUnitText(node: TSNode): string {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (child?.isNamed && child.type !== "variable_assignment") {
+      return node.text.slice(child.startIndex - node.startIndex);
+    }
+  }
+  return node.text;
 }
 
 function descendCommandChildren(

package/src/access-intent/bash/parser.ts

@@ -8,6 +8,8 @@ import { memoizeAsyncWithRetry } from "#src/async-cache";
 export interface TSNode {
   readonly type: string;
   readonly text: string;
+  /** Absolute byte offset of this node's start in the parsed source. */
+  readonly startIndex: number;
   readonly childCount: number;
   /** False for anonymous tokens (operators, delimiters); true for named nodes. */
   readonly isNamed: boolean;

package/src/access-intent/bash/program.ts

@@ -61,6 +61,9 @@ export class BashProgram {
    * Splits on the shell chain operators (`&&`, `||`, `;`, `|`, `&`, newlines);
    * quotes, command substitution, and subshells are respected by the parser and
    * are NOT split — a subshell or other compound statement is emitted whole.
+   * Each unit has any leading `variable_assignment` prefix stripped, and an
+   * opaque-payload wrapper (`bash -c`/`eval`) is flagged `opaque` so its decision
+   * is floored to `ask`.
    * May be empty (e.g. an empty command or a comment-only line); callers fall
    * back to the whole command so the surface is never evaluated weaker than
    * before.

package/src/builtin-tool-input-formatters.ts

@@ -5,12 +5,12 @@
  * through exactly the same path a third-party extension would use.
  */
 
-import { toRecord } from "./common";
 import type {
   ToolInputFormatter,
   ToolInputFormatterRegistry,
 } from "./tool-input-formatter-registry";
 import { truncateInlineText } from "./tool-input-preview";
+import { toRecord } from "./value-guards";
 
 /** Maximum total length of the generated argument summary (before "with " prefix). */
 const MCP_ARGS_SUMMARY_MAX_LENGTH = 160;

package/src/config-loader.ts

@@ -1,12 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
 import { normalize } from "node:path";
-import {
-  isDenyWithReason,
-  isPermissionState,
-  normalizeOptionalPositiveInt,
-  normalizeOptionalStringArray,
-  toRecord,
-} from "./common";
 import {
   getGlobalConfigPath,
   getLegacyExtensionConfigPath,
@@ -16,6 +9,13 @@ import {
 } from "./config-paths";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
+import {
+  isDenyWithReason,
+  isPermissionState,
+  normalizeOptionalPositiveInt,
+  normalizeOptionalStringArray,
+  toRecord,
+} from "./value-guards";
 
 /**
  * Unified config shape combining runtime knobs and flat permission policy.

package/src/forwarded-permissions/permission-forwarder.ts

@@ -5,7 +5,6 @@ import {
   getActiveAgentNameFromSystemPrompt,
   type SessionEntryView,
 } from "#src/active-agent";
-import { toRecord } from "#src/common";
 import type { ConfigReader } from "#src/config-store";
 import type {
   PermissionDecisionUi,
@@ -31,6 +30,7 @@ import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import { toRecord } from "#src/value-guards";
 import { shouldAutoApprovePermissionState } from "#src/yolo-mode";
 
 import {

package/src/handlers/gates/bash-command.ts

@@ -19,6 +19,12 @@ import type { PermissionCheckResult } from "#src/types";
  * `commandContext` (set only for a nested command), so the prompt,
  * session-approval suggestion, and decision event scope to that command.
  *
+ * An opaque-payload wrapper unit (`bash -c`/`eval`, flagged `opaque` by the
+ * enumerator) has its inner program hidden behind a quoted argument, so an
+ * `allow` is floored up to a synthetic `ask` (the `<opaque-bash-wrapper>`
+ * pattern) to keep it from riding a permissive rule; an explicit `deny`/`ask`
+ * on the wrapper is left untouched (`deny > ask > allow`).
+ *
  * When `commands` is empty there are two cases. A trivially-empty command (an
  * empty, whitespace-only, or comment-only line) has genuinely nothing to gate,
  * so the whole `command` is resolved as before. A non-empty command that parsed
@@ -56,12 +62,20 @@ export function resolveBashCommandCheck(
   }
 
   const results = commands.map((cmd) => {
-    const result = resolver.resolve({
+    const base = resolver.resolve({
       kind: "tool",
       surface: "bash",
       input: { command: cmd.text },
       agentName,
     });
+    const result =
+      cmd.opaque && base.state === "allow"
+        ? {
+            ...base,
+            state: "ask" as const,
+            matchedPattern: "<opaque-bash-wrapper>",
+          }
+        : base;
     return cmd.context ? { ...result, commandContext: cmd.context } : result;
   });
   return (

package/src/handlers/gates/bash-external-directory.ts

@@ -1,8 +1,8 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import type { GateResult } from "./descriptor";
 import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";

package/src/handlers/gates/bash-path.ts

@@ -1,9 +1,9 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { formatPathAskPrompt } from "./path";

package/src/handlers/gates/skill-read.ts

@@ -1,8 +1,8 @@
-import { toRecord } from "#src/common";
 import { normalizePathForComparison } from "#src/path-utils";
 import { formatSkillPathAskPrompt } from "#src/permission-prompts";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
+import { toRecord } from "#src/value-guards";
 import type { GateDescriptor } from "./descriptor";
 import type { ToolCallContext } from "./types";
 

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -1,5 +1,4 @@
 import { BashProgram } from "#src/access-intent/bash/program";
-import { getNonEmptyString, toRecord } from "#src/common";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -8,6 +7,7 @@ import {
   ToolPreviewFormatter,
   type ToolPreviewFormatterOptions,
 } from "#src/tool-preview-formatter";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
 import { resolveBashCommandCheck } from "./bash-command";
 import { describeBashExternalDirectoryGate } from "./bash-external-directory";
 import { describeBashPathGate } from "./bash-path";

package/src/handlers/permission-gate-handler.ts

@@ -2,8 +2,6 @@ import type {
   ExtensionContext,
   InputEventResult,
 } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import {
   formatMissingToolNameReason,
   formatUnknownToolReason,
@@ -14,6 +12,7 @@ import {
   getToolNameFromValue,
   type ToolRegistry,
 } from "#src/tool-registry";
+import { toRecord } from "#src/value-guards";
 import type { GateRunner } from "./gates/runner";
 import type {
   GateNotifier,

package/src/handlers/tool-call-boundary.ts

@@ -1,8 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import { toRecord } from "#src/common";
 import type { DecisionRecorder } from "#src/decision-audit";
 import type { DecisionReporter } from "#src/decision-reporter";
+import { toRecord } from "#src/value-guards";
 import type { GateOutcome } from "./gates/types";
 
 /** The SDK-facing result shape for a `tool_call` handler. */

package/src/input-normalizer.ts

@@ -1,7 +1,7 @@
 import { stripBashCommentLines } from "./bash-arity";
-import { getNonEmptyString, toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * Construct a surface-appropriate input object from a raw value string.

package/src/mcp-targets.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /**
  * An ordered accumulator that owns the uniqueness invariant.

package/src/normalize.ts

@@ -1,6 +1,6 @@
-import { isDenyWithReason, isPermissionState } from "./common";
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
+import { isDenyWithReason, isPermissionState } from "./value-guards";
 
 /**
  * Convert a flat permission config into a Ruleset.

package/src/path-utils.ts

@@ -8,9 +8,9 @@ import {
 } from "node:path";
 
 import { canonicalizePath } from "./canonicalize-path";
-import { getNonEmptyString, toRecord } from "./common";
 import { expandHomePath } from "./expand-home";
 import type { ToolAccessExtractorLookup } from "./tool-access-extractor-registry";
+import { getNonEmptyString, toRecord } from "./value-guards";
 import { wildcardMatch } from "./wildcard-matcher";
 
 export function normalizePathForComparison(

package/src/permission-manager.ts

@@ -1,6 +1,5 @@
 import { join } from "node:path";
 import type { ResolvedAccessIntent } from "./access-intent/access-intent";
-import { isPermissionState } from "./common";
 import {
   getGlobalConfigPath,
   getProjectAgentsDir,
@@ -28,6 +27,7 @@ import type {
   PermissionCheckResult,
   PermissionState,
 } from "./types";
+import { isPermissionState } from "./value-guards";
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([
   "bash",

package/src/permission-prompts.ts

@@ -1,8 +1,8 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { matchQualifier } from "./denial-messages";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
 import type { ToolPreviewFormatter } from "./tool-preview-formatter";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 // NOTE: formatDenyReason, formatUserDeniedReason, and
 // formatPermissionHardStopHint have been moved to denial-messages.ts.

package/src/policy-loader.ts

@@ -1,8 +1,6 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-
-import { extractFrontmatter, parseSimpleYamlMap, toRecord } from "./common";
 import {
   loadUnifiedConfig,
   normalizeUnifiedConfig,
@@ -10,6 +8,8 @@ import {
 } from "./config-loader";
 import { getGlobalConfigPath } from "./config-paths";
 import type { ScopeConfig } from "./types";
+import { toRecord } from "./value-guards";
+import { extractFrontmatter, parseSimpleYamlMap } from "./yaml-frontmatter";
 
 // ---------------------------------------------------------------------------
 // File-stamp helper

package/src/tool-input-prompt-formatters.ts

@@ -1,5 +1,5 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { countTextLines, formatCount } from "./tool-input-preview";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export function getPromptPath(input: Record<string, unknown>): string | null {
   return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);

package/src/tool-preview-formatter.ts

@@ -1,4 +1,3 @@
-import { getNonEmptyString, toRecord } from "./common";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
@@ -15,6 +14,7 @@ import {
   getPromptPath,
 } from "./tool-input-prompt-formatters";
 import type { PermissionCheckResult } from "./types";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 export interface ToolPreviewFormatterOptions {
   toolInputPreviewMaxLength: number;

package/src/tool-registry.ts

@@ -1,4 +1,4 @@
-import { getNonEmptyString, toRecord } from "./common";
+import { getNonEmptyString, toRecord } from "./value-guards";
 
 /** Narrow interface for the Pi tool API subset used by handler classes. */
 export interface ToolRegistry {

package/src/{common.ts → value-guards.ts}

@@ -53,69 +53,3 @@ export function isDenyWithReason(value: unknown): value is DenyWithReason {
     (record.reason === undefined || typeof record.reason === "string")
   );
 }
-
-type StackNode = { indent: number; target: Record<string, unknown> };
-
-export function parseSimpleYamlMap(input: string): Record<string, unknown> {
-  const root: Record<string, unknown> = {};
-  const stack: StackNode[] = [{ indent: -1, target: root }];
-
-  const lines = input.split(/\r?\n/);
-  for (const rawLine of lines) {
-    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
-      continue;
-    }
-
-    const indent = rawLine.length - rawLine.trimStart().length;
-    const line = rawLine.trim();
-    const separatorIndex = line.indexOf(":");
-    if (separatorIndex <= 0) {
-      continue;
-    }
-
-    const key = line
-      .slice(0, separatorIndex)
-      .trim()
-      .replace(/^['"]|['"]$/g, "");
-    const rawValue = line.slice(separatorIndex + 1).trim();
-
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-
-    const current = stack[stack.length - 1].target;
-
-    if (!rawValue) {
-      const child: Record<string, unknown> = {};
-      current[key] = child;
-      stack.push({ indent, target: child });
-      continue;
-    }
-
-    let scalar = rawValue;
-    if (
-      (scalar.startsWith('"') && scalar.endsWith('"')) ||
-      (scalar.startsWith("'") && scalar.endsWith("'"))
-    ) {
-      scalar = scalar.slice(1, -1);
-    }
-
-    current[key] = scalar;
-  }
-
-  return root;
-}
-
-export function extractFrontmatter(markdown: string): string {
-  const normalized = markdown.replace(/\r\n/g, "\n");
-  if (!normalized.startsWith("---\n")) {
-    return "";
-  }
-
-  const end = normalized.indexOf("\n---", 4);
-  if (end === -1) {
-    return "";
-  }
-
-  return normalized.slice(4, end);
-}

package/src/yaml-frontmatter.ts

@@ -0,0 +1,65 @@
+type StackNode = { indent: number; target: Record<string, unknown> };
+
+export function parseSimpleYamlMap(input: string): Record<string, unknown> {
+  const root: Record<string, unknown> = {};
+  const stack: StackNode[] = [{ indent: -1, target: root }];
+
+  const lines = input.split(/\r?\n/);
+  for (const rawLine of lines) {
+    if (!rawLine.trim() || rawLine.trimStart().startsWith("#")) {
+      continue;
+    }
+
+    const indent = rawLine.length - rawLine.trimStart().length;
+    const line = rawLine.trim();
+    const separatorIndex = line.indexOf(":");
+    if (separatorIndex <= 0) {
+      continue;
+    }
+
+    const key = line
+      .slice(0, separatorIndex)
+      .trim()
+      .replace(/^['"]|['"]$/g, "");
+    const rawValue = line.slice(separatorIndex + 1).trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const current = stack[stack.length - 1].target;
+
+    if (!rawValue) {
+      const child: Record<string, unknown> = {};
+      current[key] = child;
+      stack.push({ indent, target: child });
+      continue;
+    }
+
+    let scalar = rawValue;
+    if (
+      (scalar.startsWith('"') && scalar.endsWith('"')) ||
+      (scalar.startsWith("'") && scalar.endsWith("'"))
+    ) {
+      scalar = scalar.slice(1, -1);
+    }
+
+    current[key] = scalar;
+  }
+
+  return root;
+}
+
+export function extractFrontmatter(markdown: string): string {
+  const normalized = markdown.replace(/\r\n/g, "\n");
+  if (!normalized.startsWith("---\n")) {
+    return "";
+  }
+
+  const end = normalized.indexOf("\n---", 4);
+  if (end === -1) {
+    return "";
+  }
+
+  return normalized.slice(4, end);
+}

package/test/access-intent/bash/node-text.test.ts

@@ -10,6 +10,7 @@ function makeNode(type: string, text: string, children: TSNode[] = []): TSNode {
   return {
     type,
     text,
+    startIndex: 0,
     childCount: children.length,
     isNamed: true,
     child: (i) => children[i] ?? null,