peaks-loop 4.1.1 → 4.1.3

package/dist/services/preferences/preferences-service.js

@@ -9,7 +9,6 @@ export function preferencesPath(projectRoot) {
 export function loadPreferences(projectRoot) {
     const filePath = preferencesPath(projectRoot);
     if (!existsSync(filePath)) {
-        // Slice 2026-07-22-orchestrator-memory-preflight: when
         // .peaks/preferences.json is missing, this returns a clone of
         // DEFAULT_PREFERENCES, which now carries the `memoryPreflight`
         // block (see preferences-types.ts). Partial overlays fall through
@@ -33,7 +32,6 @@ export function loadPreferences(projectRoot) {
         raw.schema_version !== PREFERENCES_SCHEMA_VERSION) {
         throw new Error(`PREFERENCES_SCHEMA_MISMATCH: expected schema_version=${PREFERENCES_SCHEMA_VERSION} in ${filePath}, got ${raw?.schema_version}`);
     }
-    // Slice 2026-06-24-audit-5th-p2: fail fast on any fanout mode value
     // outside the closed set `['fan-out']`. The previous 'serial' opt-out
     // was removed by user direction — a saved `defaultMode = 'serial'`
     // (or a hand-edited unknown value) now throws at load rather than
@@ -58,7 +56,6 @@ export function savePreferences(projectRoot, overrides) {
     const filePath = preferencesPath(projectRoot);
     const current = loadPreferences(projectRoot);
     const merged = mergePreferences(current, overrides);
-    // Slice 2026-06-23-audit-4th #A2: use tmp + rename so a crash
     // mid-write cannot leave a zero-byte or half-written preferences
     // file. Before the fix, a power-cut or OOM-kill between
     // writeFileSync's open and the final byte would leave
@@ -86,7 +83,6 @@ function mergePreferences(base, overrides) {
     // Shallow merge at the top level, BUT merge the `fanout` object
     // deeply so a partial override like `{"fanout": {"perTouchpoint": {...}}}`
     // does not silently drop `defaultMode`. Slice
-    // 2026-06-23-audit-p0-cleanup: today the fanout schema is 1 level
     // deep, so shallow merge happens to be safe — but the field is
     // likely to grow (perTouchpoint / perRole are obvious next additions),
     // and a future bug fix should not silently regress opt-out callers
@@ -142,7 +138,6 @@ export function migratePreferences(projectRoot, opts = {}) {
         raw.fanout !== null &&
         !Array.isArray(raw.fanout) &&
         raw.fanout.defaultMode === 'serial') {
-        // Slice 2026-06-24-audit-5th-p2: 2.8.3-era preferences.json files
         // that opted into serial dispatch must be migrated to fan-out on
         // load. The user's directive ("禁止单 sub-agent") makes the serial
         // opt-out a breaking change for any project that used it.

package/dist/services/preferences/preferences-types.d.ts

@@ -3,7 +3,6 @@
  * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
  * NOT in `~/.peaks/config.json` (which is slim global).
  *
- * Spec reference: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §8.4
  */
 export declare const PREFERENCES_SCHEMA_VERSION = "2.0.0";
 /**
@@ -33,7 +32,6 @@ export interface ClassifyRuleOverrides {
 export interface SwarmSpeculativePreferences {
     /** Whether speculative dispatch is enabled. Default: true */
     readonly enabled: boolean;
-    /** Max concurrent speculative sub-agents. Default: 3 (slice 2026-06-24-efficiency-4p-bundle, G3/P1.1) */
     readonly maxConcurrent: number;
     /** Min hit rate below which speculative auto-disables. Default: 0.5 */
     readonly minHitRate: number;
@@ -47,7 +45,6 @@ export interface ProjectPreferences {
      */
     readonly schema_version: typeof PREFERENCES_SCHEMA_VERSION;
     /**
-     * Slice 2026-06-28-code-mode-bypass-fix: economyMode is a
      * **MODEL-SELECTION** knob only — it chooses between the cheap
      * configured provider (`getConfiguredExecutionModelId`) and the
      * strongest planner/reviewer model (`getStrongestModelId(...)`). It does
@@ -69,7 +66,6 @@ export interface ProjectPreferences {
      */
     readonly economyMode: boolean;
     /**
-     * Slice 2026-06-28: swarmMode controls whether the swarm subgraph
      * (peaks-rd/qa worker graph) is generated at all. It does NOT
      * control fan-out. Fan-out is governed by the slice DAG + the
      * `fanout.defaultMode` preference; swarmMode only decides the
@@ -105,7 +101,6 @@ export interface ProjectPreferences {
      */
     readonly agentShieldEnabled: boolean;
     /**
-     * Slice 2026-06-24-audit-5th-p2: fan-out is now a HARD constraint.
      * The previous opt-out (`defaultMode = 'serial'`) is removed by user
      * direction. Single-sub-agent dispatch is no longer permitted when
      * the slice DAG has ≥ 2 leaves at the same topological level; the
@@ -119,7 +114,6 @@ export interface ProjectPreferences {
      */
     readonly fanout: FanoutPreference;
     /**
-     * Slice 2026-07-22-orchestrator-memory-preflight: orchestrator-side memory
      * preflight knobs. Optional — `resolveMemoryPreflightConfig` (see
      * src/services/context/memory-preflight-config.ts) merges over a hard-coded
      * default block when this key is absent, so legacy preferences.json files
@@ -132,31 +126,23 @@ export interface ProjectPreferences {
         /** Back-compat hot item cap; `hotItemCap` overrides it when set. */
         readonly listCap?: number;
         readonly contentCacheBytes?: number;
-        /** Slice 2026-09-09-memory-retrieval: hard byte cap on the block. */
         readonly maxBytes?: number;
-        /** Slice 2026-09-09-memory-retrieval: max hot items (default 10). */
         readonly hotItemCap?: number;
-        /** Slice 2026-09-09-memory-retrieval: max warm items (default 4; 0 disables). */
         readonly warmItemCap?: number;
-        /** Slice 2026-09-09-memory-retrieval: min task-token hits for warm eligibility. */
         readonly warmMinTokenHits?: number;
-        /** Slice 2026-09-09-memory-retrieval: soft selection wall-clock budget (ms). */
         readonly selectionTimeBudgetMs?: number;
-        /** Slice 2026-09-09-memory-retrieval: inline memo bodies (default false). */
         readonly includeBodies?: boolean;
     };
 }
 export type FanoutMode = 'fan-out';
 export declare const FANOUT_MODES: readonly FanoutMode[];
 /**
- * Runtime type guard for `FanoutMode`. Slice 2026-06-24-audit-5th-p2
  * narrowed the closed set from `['fan-out','serial']` to `['fan-out']`
  * — stale preferences.json files with `"serial"` must now fail-fast at
  * load (see `preferences-service.ts`) instead of being silently coerced.
  */
 export declare function isFanoutMode(value: unknown): value is FanoutMode;
 export interface FanoutPreference {
-    /** Hard-coded mode. Slice 2026-06-24-audit-5th-p2 removed the serial opt-out. */
     readonly defaultMode: FanoutMode;
 }
 export declare const DEFAULT_PREFERENCES: ProjectPreferences;

package/dist/services/preferences/preferences-types.js

@@ -3,12 +3,10 @@
  * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
  * NOT in `~/.peaks/config.json` (which is slim global).
  *
- * Spec reference: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §8.4
  */
 export const PREFERENCES_SCHEMA_VERSION = '2.0.0';
 export const FANOUT_MODES = ['fan-out'];
 /**
- * Runtime type guard for `FanoutMode`. Slice 2026-06-24-audit-5th-p2
  * narrowed the closed set from `['fan-out','serial']` to `['fan-out']`
  * — stale preferences.json files with `"serial"` must now fail-fast at
  * load (see `preferences-service.ts`) instead of being silently coerced.
@@ -38,7 +36,6 @@ export const DEFAULT_PREFERENCES = {
     fanout: {
         defaultMode: 'fan-out'
     },
-    // Slice 2026-07-22-orchestrator-memory-preflight: defaults aligned with
     // memory-preflight-config.ts::DEFAULTS. Kept in sync manually because
     // loadPreferences() returns DEFAULT_PREFERENCES verbatim when the on-disk
     // file is absent, and partial overlays rely on memoryPreflight being
@@ -48,7 +45,6 @@ export const DEFAULT_PREFERENCES = {
         maxTokens: 1200,
         listCap: 12,
         contentCacheBytes: 6000,
-        // Slice 2026-09-09-memory-retrieval tiered budget (see
         // memory-preflight-config.ts::DEFAULTS).
         maxBytes: 4800,
         hotItemCap: 10,

package/dist/services/progress/progress-service.js

@@ -31,7 +31,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { getSessionIdCanonical } from '../session/session-manager.js';
 import { findProjectRoot } from '../config/config-safety.js';
-// As of slice 2026-06-06-sub-agent-spawn-bug-and-decouple, the per-session
 // sub-agent state files live under `.peaks/_sub_agents/<sid>/`, NOT under
 // `.peaks/_runtime/<sid>/system/`. The new path mirrors the existing `_runtime/`
 // and `_dogfood/` convention (leading underscore = meta-classification, not

package/dist/services/qa/bdd-test-style-verifier.d.ts

@@ -1,7 +1,6 @@
 /**
  * src/services/qa/bdd-test-style-verifier.ts
  *
- * rid-2026-08-05-bdd-test-style Slice B — peaks-qa verification-time
  * BDD test-style verifier. This is the read-only, post-edit companion
  * to the `scripts/migrate-to-bdd.mjs` AST migrator shipped in Slice A.
  *

package/dist/services/qa/bdd-test-style-verifier.js

@@ -1,7 +1,6 @@
 /**
  * src/services/qa/bdd-test-style-verifier.ts
  *
- * rid-2026-08-05-bdd-test-style Slice B — peaks-qa verification-time
  * BDD test-style verifier. This is the read-only, post-edit companion
  * to the `scripts/migrate-to-bdd.mjs` AST migrator shipped in Slice A.
  *

package/dist/services/qa/browser-event-logger.d.ts

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G4.
  *
  * BrowserEventLogger
  *

package/dist/services/qa/browser-event-logger.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G4.
  *
  * BrowserEventLogger
  *

package/dist/services/qa/browser-restart-detector.d.ts

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G1.
  *
  * BrowserRestartDetector
  *

package/dist/services/qa/browser-restart-detector.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G1.
  *
  * BrowserRestartDetector
  *

package/dist/services/qa/browser-reuse-hint.d.ts

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G2.
  *
  * The browser-context reuse hint is appended to the sub-agent prompt
  * whenever a peaks-qa-dispatched sub-agent (peaks-ui or general-purpose

package/dist/services/qa/browser-reuse-hint.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-playwright-restart-loop — G2.
  *
  * The browser-context reuse hint is appended to the sub-agent prompt
  * whenever a peaks-qa-dispatched sub-agent (peaks-ui or general-purpose

package/dist/services/qa/qa-business-review-state.js

@@ -60,8 +60,6 @@ export function getQaReviewDir(projectRoot, sessionId) {
     //
     // It does NOT cover the rid axis: the request id is joined one function later,
     // in `getQaReviewPath` below. Corrected 2026-09-14 (repair R1) — this comment
-    // previously said "one guard here covers the whole family", and the security
-    // audit of `2026-09-14-cli-id-escape-instrumentation` (F1b) measured that claim
     // false: `qa-business-review '../../../../…/EVILQA3'` wrote a `.json` file
     // outside the project root under `ok: true`.
     if (isUnsafePathInput(sessionId)) {

package/dist/services/qa/screenshot-archive-service.d.ts

@@ -1,5 +1,4 @@
 /**
- * rid-012 (2026-07-27) — screenshot archive service.
  *
  * Purpose: enforce the peaks-qa SKILL.md "Hard contracts for browser
  * validation" Contract 1 — every Playwright screenshot MUST land under

package/dist/services/qa/screenshot-archive-service.js

@@ -1,5 +1,4 @@
 /**
- * rid-012 (2026-07-27) — screenshot archive service.
  *
  * Purpose: enforce the peaks-qa SKILL.md "Hard contracts for browser
  * validation" Contract 1 — every Playwright screenshot MUST land under

package/dist/services/rd/impl.js

@@ -1,6 +1,5 @@
 /**
  * Per spec §4.3 战术审计 (peaks-rd/战术) — impl.json writer + TACT.sig computation.
- * Spec anchor: docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md §4.3
  * (R1-W3 consolidation; previously referenced as §4.2 which is `peaks-mut`).
  *
  * Hard constraints:

package/dist/services/rd/rd-service.d.ts

@@ -17,7 +17,6 @@ export type RdModelRole = 'strongest' | 'execution';
 export type RdSwarmPlanRequest = {
     skill: RdSkill;
     /**
-     * Slice 2026-06-29-change-id-root-removal: change-id is metadata-only.
      * It is no longer used for filesystem routing (the session-axis
      * `getSessionDir` is the canonical authority), but it is retained
      * on the request type for trace correlation and to avoid sweeping
@@ -32,7 +31,6 @@ export type RdSwarmPlanRequest = {
     workspace?: WorkspaceConfig;
     requiresTechApproval?: boolean;
     executionModelId?: string;
-    /** Project root for the missing-standards diagnostic (slice 2026-06-16-peaks-rd-no-gates). */
     projectRoot?: string;
     /** Opt-in strict mode: hard-fail when project-local standards are missing. */
     strictStandards?: boolean;
@@ -64,7 +62,6 @@ export type RdConflictGroup = {
 export type RdPlanResult = {
     available: true;
     /**
-     * Slice 2026-06-29-change-id-root-removal: change-id is metadata-only.
      * It is no longer emitted in the planner envelope at runtime, but
      * retained on the result type for trace correlation and to avoid
      * breaking 30+ tests that assert against it.
@@ -89,7 +86,6 @@ export type RdPlanResult = {
         skipReason?: string;
         /** Gate list (code-review / security / performance) reflecting standards availability. */
         standardsGates?: ReadonlyArray<RdStandardGate>;
-        /** Diagnostic line emitted to stderr when standards are missing (slice 2026-06-16-peaks-rd-no-gates). */
         standardsDiagnostic?: string;
         /** When `--strict-standards` is on AND standards are missing, the stable error code. */
         standardsErrorCode?: typeof import('./standards-diagnostic.js').EPEAKS_NO_STANDARDS;
@@ -118,7 +114,6 @@ export type RdPlanResult = {
         skipReason?: string;
         /** Gate list (code-review / security / performance) reflecting standards availability. */
         standardsGates?: ReadonlyArray<RdStandardGate>;
-        /** Diagnostic line emitted to stderr when standards are missing (slice 2026-06-16-peaks-rd-no-gates). */
         standardsDiagnostic?: string;
         /** When `--strict-standards` is on AND standards are missing, the stable error code. */
         standardsErrorCode?: typeof import('./standards-diagnostic.js').EPEAKS_NO_STANDARDS;

package/dist/services/rd/rd-service.js

@@ -19,7 +19,6 @@ const RD_FIXED_TASK_BOUNDARY = RD_IMPLEMENTATION_BAND_START;
 const RD_QUALITY_GATE_BAND_SIZE = 5;
 const RD_TASK_ID_PAD_WIDTH = 3;
 /**
- * 2.0.1-bug1: the slim 2.0 `~/.peaks/config.json` no longer carries a
  * `providers` block (legacy model config lives in
  * `.peaks/preferences.json` per spec §10.4). `buildPlan` is a pure
  * planner function and historically took its execution model from a
@@ -242,7 +241,6 @@ function getConcreteTargetAreas(request, artifactWorkspacePath, hasApprovedTechA
         !hasPlannerArtifactWorkspace(request, artifactWorkspacePath)) {
         return [];
     }
-    // Slice 2026-06-29-change-id-root-removal: read path now resolves via
     // the session-axis `getSessionDir(root, sessionId)` (the change-id
     // identifier is reused as the session-dir name for tech-artifact
     // reads, matching the test helper `writeApprovedTechArtifacts` and
@@ -268,7 +266,6 @@ function buildStandardsOverlay(request) {
         projectRoot: request.projectRoot,
         strict: request.strictStandards === true
     });
-    // Slice 2026-06-16-peaks-rd-no-gates — Repair cycle 1:
     // thread BOTH diagnostic and errorCode so strict-mode callers still
     // surface `EPEAKS_NO_STANDARDS`. The pre-fix version early-returned
     // on `diagnostic !== null` and dropped `errorCode` (QA#4 AC3 violation).
@@ -279,12 +276,10 @@ function buildStandardsOverlay(request) {
         : withDiagnostic;
 }
 function buildPlan(request, standardsOverlay) {
-    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
     // no structural validation gate fires here.
     const goal = normalizeGoal(request.goal);
     const swarmMode = request.swarmMode ?? true;
     const executionModelId = request.executionModelId?.trim() || resolveExecutionModelId();
-    // Slice 2026-07-09 add-zcode-adapter (A.3): strongest planner/reviewer
     // model is resolved dynamically (config.model → env-var fallback).
     const strongestModelId = getStrongestModelId();
     const { workerTarget, blockedReasons } = resolveWorkerTarget(request.maxWorkers);

package/dist/services/rd/reviewer-dispatch-policy.d.ts

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-24-efficiency-4p-bundle / G4 (P1.3) — karpathy-skip policy
  * Slice v2.12.0 Group B (Tier 4) — collapse 5-way → 3-way fanout.
  *
  * Background — peaks-rd's "Parallel review fan-out" (SKILL.md §130) is
@@ -34,9 +33,7 @@
  * reason every export below sat at zero importers until slice F2.
  *
  * Pinning is half-done. The two test files this block used to cite —
- * `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts` (the 5 → 3
  * element pinning) and
- * `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (the 8
  * back-compat cases) — were both deleted in `f17aa377`. The **predicate
  * half** was re-pinned by `tests/unit/rd/reviewer-dispatch-policy.test.ts`
  * (`7191140f`, 6 cases: `RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`).
@@ -44,7 +41,6 @@
  * membership, `reviewerListFor`, `karpathySlotIndex`,
  * `shouldDispatchKarpathy` — still has no pin.
  *
- * Slice F2 (rid-f2-ac1-wiring) gave this module its FIRST caller in
  * `src/cli/commands/sub-agent-shared.ts` (`deprecatedReviewerWarnings`),
  * invoked from the dispatch chokepoint in
  * `src/cli/commands/dispatch-commands.ts` and pinned by

package/dist/services/rd/reviewer-dispatch-policy.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-24-efficiency-4p-bundle / G4 (P1.3) — karpathy-skip policy
  * Slice v2.12.0 Group B (Tier 4) — collapse 5-way → 3-way fanout.
  *
  * Background — peaks-rd's "Parallel review fan-out" (SKILL.md §130) is
@@ -34,9 +33,7 @@
  * reason every export below sat at zero importers until slice F2.
  *
  * Pinning is half-done. The two test files this block used to cite —
- * `tests/unit/rd/karpathy-skip-on-config-docs-chore.test.ts` (the 5 → 3
  * element pinning) and
- * `tests/unit/rd/deprecated-reviewer-back-compat.test.ts` (the 8
  * back-compat cases) — were both deleted in `f17aa377`. The **predicate
  * half** was re-pinned by `tests/unit/rd/reviewer-dispatch-policy.test.ts`
  * (`7191140f`, 6 cases: `RD_DEPRECATED_REVIEWERS` + `isDeprecatedReviewer`).
@@ -44,7 +41,6 @@
  * membership, `reviewerListFor`, `karpathySlotIndex`,
  * `shouldDispatchKarpathy` — still has no pin.
  *
- * Slice F2 (rid-f2-ac1-wiring) gave this module its FIRST caller in
  * `src/cli/commands/sub-agent-shared.ts` (`deprecatedReviewerWarnings`),
  * invoked from the dispatch chokepoint in
  * `src/cli/commands/dispatch-commands.ts` and pinned by

package/dist/services/rd/standards-diagnostic.js

@@ -1,5 +1,4 @@
 /**
- * Slice 2026-06-16-peaks-rd-no-gates — missing-project-standards diagnostic
  * + JSON gate list shape for the RD bootstrap path.
  *
  * Background: when `peaks-rd` (or `peaks-qa` / `peaks-code`) starts in a

package/dist/services/rd/tactical-stage.js

@@ -1,7 +1,6 @@
 /**
  * Per spec §4.3 战术审计 (peaks-rd/战术) — orchestrator.
  * Runs AST gate first; only writes TACT.sig if gate passes.
- * Spec anchor: docs/superpowers/specs/2026-06-21-context-audit-redesign-design.md §4.3
  * (R1-W3 consolidation; previously referenced as §4.2 which is `peaks-mut`).
  */
 import { dirname } from 'node:path';

package/dist/services/rd-swarm/rd-swarm-types.d.ts

@@ -2,7 +2,6 @@
  * rd-swarm-types — the pure declaration surface of the RD swarm dry-run
  * planner (`rd-swarm-service.ts`).
  *
- * Slice rid-013 owns the planner behavior; this module owns only the graph
  * shapes (wave names, task records, conflict groups, and the task-graph
  * envelope). `rd-swarm-service.ts` imports and re-exports every name here, so
  * importers keep resolving them from the original path.

package/dist/services/rd-swarm/rd-swarm-types.js

@@ -2,7 +2,6 @@
  * rd-swarm-types — the pure declaration surface of the RD swarm dry-run
  * planner (`rd-swarm-service.ts`).
  *
- * Slice rid-013 owns the planner behavior; this module owns only the graph
  * shapes (wave names, task records, conflict groups, and the task-graph
  * envelope). `rd-swarm-service.ts` imports and re-exports every name here, so
  * importers keep resolving them from the original path.

package/dist/services/readonly-surface/argv-guard.d.ts

@@ -0,0 +1,32 @@
+import type { PlaceholderSpec, ReadOnlyWhitelistEntry } from './readonly-whitelist.js';
+/** Upper bound on any single placeholder value, whatever its type. */
+export declare const READONLY_VALUE_MAX_LENGTH = 200;
+export type GuardRejection = {
+    readonly ok: false;
+    readonly param: string;
+    readonly code: GuardRejectionCode;
+    readonly message: string;
+};
+export type GuardRejectionCode = 'NOT_A_STRING' | 'EMPTY' | 'TOO_LONG' | 'FLAG_SHAPED' | 'CONTROL_CHARACTER' | 'WHITESPACE' | 'PATTERN_MISMATCH' | 'NOT_IN_ENUM' | 'NOT_AN_INTEGER' | 'OUT_OF_RANGE' | 'NOT_ABSOLUTE';
+export type GuardResult = {
+    readonly ok: true;
+    readonly value: string;
+} | GuardRejection;
+/** The process options that keep the array from being re-parsed by a shell. */
+export declare function readonlySpawnOptions(): {
+    readonly shell: false;
+};
+/** Validate one placeholder value against its spec. */
+export declare function validatePlaceholderValue(param: string, spec: PlaceholderSpec, raw: unknown): GuardResult;
+export type BuildArgvResult = {
+    readonly ok: true;
+    readonly argv: string[];
+} | GuardRejection;
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export declare function buildArgv(entry: ReadOnlyWhitelistEntry, values: Readonly<Record<string, string>>): BuildArgvResult;

package/dist/services/readonly-surface/argv-guard.js

@@ -0,0 +1,164 @@
+/**
+ * Parameter-injection guard for the read-only surface.
+ *
+ * THE ATTACK. An argv template has placeholder slots (`request show <rid>`). If a
+ * placeholder value is pasted into a command LINE, the value `--apply` stops being
+ * a request id and becomes a flag - the semantics of the call are inverted by its
+ * own data. Two independent defences, both required (spec §8.1):
+ *
+ *   1. TYPE WHITELIST - every placeholder declares a type, and the value must
+ *      satisfy it. No type admits a leading `-`, so a flag-shaped value is never a
+ *      legal value of any placeholder.
+ *   2. ARRAY PASSING - `buildArgv` returns `string[]`. The caller passes the array
+ *      to the process API with shell parsing disabled (`readonlySpawnOptions`), so
+ *      no value is ever re-tokenized by a shell.
+ *
+ * Defence 2 alone is not enough: `spawn(..., {shell:false})` still hands `--apply`
+ * to the CLI as a real flag. Defence 1 alone is not enough: a caller that joins
+ * the array into a string reintroduces the shell. Hence both.
+ */
+import { isAbsolute } from 'node:path';
+/** Fallback pattern for a `slug` placeholder that declares none. */
+const DEFAULT_SLUG_PATTERN = '^[a-z0-9][a-z0-9-]*$';
+/** Upper bound on any single placeholder value, whatever its type. */
+export const READONLY_VALUE_MAX_LENGTH = 200;
+/** The process options that keep the array from being re-parsed by a shell. */
+export function readonlySpawnOptions() {
+    return { shell: false };
+}
+function reject(param, code, message) {
+    return { ok: false, param, code, message };
+}
+/**
+ * Control characters, matched by Unicode category rather than by a literal range:
+ * a hand-written `\x00-\x1f` class is a lint error (`no-control-regex`) precisely
+ * because such a range in a pattern is usually a bug, and `\p{Cc}` says what is
+ * meant without spelling out code points.
+ */
+function hasControlCharacter(value) {
+    return /\p{Cc}/u.test(value);
+}
+/**
+ * The rules that hold for EVERY type, before any type-specific rule runs. A
+ * leading `-` is refused here, so no type can carry a flag into the argv.
+ */
+function precheckCommon(param, raw) {
+    if (typeof raw !== 'string') {
+        return reject(param, 'NOT_A_STRING', `Parameter ${param} must be a string.`);
+    }
+    if (raw.length === 0)
+        return reject(param, 'EMPTY', `Parameter ${param} must not be empty.`);
+    if (raw.length > READONLY_VALUE_MAX_LENGTH) {
+        return reject(param, 'TOO_LONG', `Parameter ${param} exceeds ${READONLY_VALUE_MAX_LENGTH} characters.`);
+    }
+    if (raw.startsWith('-')) {
+        return reject(param, 'FLAG_SHAPED', `Parameter ${param} must not look like a flag: ${raw}`);
+    }
+    if (hasControlCharacter(raw)) {
+        return reject(param, 'CONTROL_CHARACTER', `Parameter ${param} must not contain control characters.`);
+    }
+    return { ok: true, value: raw };
+}
+function checkToken(param, value) {
+    if (/\s/.test(value)) {
+        return reject(param, 'WHITESPACE', `Parameter ${param} must be a single token.`);
+    }
+    return { ok: true, value };
+}
+function checkSlug(param, value, spec) {
+    const asToken = checkToken(param, value);
+    if (!asToken.ok)
+        return asToken;
+    const pattern = new RegExp(spec.pattern ?? DEFAULT_SLUG_PATTERN);
+    if (!pattern.test(value)) {
+        return reject(param, 'PATTERN_MISMATCH', `Parameter ${param} must match ${pattern.source}: ${value}`);
+    }
+    return { ok: true, value };
+}
+function checkEnum(param, value, spec) {
+    if (spec.values === undefined || !spec.values.includes(value)) {
+        return reject(param, 'NOT_IN_ENUM', `Parameter ${param} must be one of: ${(spec.values ?? []).join(', ')}`);
+    }
+    return { ok: true, value };
+}
+function checkInteger(param, value, spec) {
+    if (!/^[0-9]+$/.test(value)) {
+        return reject(param, 'NOT_AN_INTEGER', `Parameter ${param} must be an integer: ${value}`);
+    }
+    const parsed = Number.parseInt(value, 10);
+    const min = spec.min ?? 0;
+    const max = spec.max ?? Number.MAX_SAFE_INTEGER;
+    if (parsed < min || parsed > max) {
+        return reject(param, 'OUT_OF_RANGE', `Parameter ${param} must be between ${min} and ${max}.`);
+    }
+    return { ok: true, value };
+}
+function checkPath(param, value) {
+    // Spaces are legal in a path and irrelevant under array passing; the absolute
+    // check is what keeps `--apply` and a bare word out.
+    if (!isAbsolute(value)) {
+        return reject(param, 'NOT_ABSOLUTE', `Parameter ${param} must be an absolute path.`);
+    }
+    return { ok: true, value };
+}
+const TYPE_CHECKS = {
+    token: (param, value) => checkToken(param, value),
+    slug: (param, value, spec) => checkSlug(param, value, spec),
+    enum: (param, value, spec) => checkEnum(param, value, spec),
+    integer: (param, value, spec) => checkInteger(param, value, spec),
+    path: (param, value) => checkPath(param, value)
+};
+/** Validate one placeholder value against its spec. */
+export function validatePlaceholderValue(param, spec, raw) {
+    const prechecked = precheckCommon(param, raw);
+    if (!prechecked.ok)
+        return prechecked;
+    return TYPE_CHECKS[spec.type](param, prechecked.value, spec);
+}
+function missingParam(param) {
+    return reject(param, 'EMPTY', `Parameter ${param} was not supplied.`);
+}
+/** A value is required for every placeholder present in the template. */
+function resolveParamValue(param, declared, values) {
+    if (declared === undefined)
+        return missingParam(param);
+    const supplied = values[param];
+    // Every placeholder in this surface is required (introspected), and a missing
+    // OPTIONAL value could only be honoured by also dropping the flag literal the
+    // loop has already pushed. Refusing is the honest answer.
+    if (supplied === undefined)
+        return missingParam(param);
+    return validatePlaceholderValue(param, declared, supplied);
+}
+function unknownParams(entry, values) {
+    for (const name of Object.keys(values)) {
+        if (!(name in entry.params)) {
+            return reject(name, 'NOT_A_STRING', `Entry ${entry.id} declares no parameter ${name}.`);
+        }
+    }
+    return undefined;
+}
+/**
+ * Render a whitelist entry into a concrete argv ARRAY.
+ *
+ * The output is never a string: literals and validated values are pushed as
+ * separate elements, so no value can contribute token boundaries. A parameter the
+ * entry does not declare is refused rather than appended.
+ */
+export function buildArgv(entry, values) {
+    const unexpected = unknownParams(entry, values);
+    if (unexpected !== undefined)
+        return unexpected;
+    const argv = [];
+    for (const segment of entry.argv) {
+        if (segment.kind === 'literal') {
+            argv.push(segment.value);
+            continue;
+        }
+        const resolved = resolveParamValue(segment.name, entry.params[segment.name], values);
+        if (!resolved.ok)
+            return resolved;
+        argv.push(resolved.value);
+    }
+    return { ok: true, argv };
+}