@adammcarter/use-cases 0.1.0

package/packages/cli/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@adammcarter/use-cases-cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "CLI for @adammcarter/use-cases.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adammcarter/use-cases.git",
+    "directory": "packages/cli"
+  },
+  "bin": {
+    "uc": "./dist/index.js",
+    "use-cases": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "package.json"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "private": true,
+  "dependencies": {
+    "@adammcarter/use-cases-core": "workspace:*"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc -b --pretty false",
+    "prepublishOnly": "tsc -b"
+  }
+}

package/packages/core/README.md

@@ -0,0 +1,37 @@
+# @adammcarter/use-cases-core
+
+Core domain library for **use-cases** — a repo-local, agent-facing
+assurance system for keeping product claims, code spans, demonstrations,
+evidence, and release decisions aligned.
+
+This package ships the schemas, types, and engine used by the `cli` and `mcp`
+workspaces. All three are **internal** and ship bundled inside the
+[`use-cases`](https://www.npmjs.com/package/use-cases) package rather
+than published separately. The bundled JSON Schemas (under `dist/schemas/v1/`)
+use the stable `https://use-cases.dev/schemas/v1/...` `$id` namespace.
+
+## Install
+
+Internal — not published separately. Install the umbrella package:
+
+```bash
+npm i -g use-cases
+```
+
+## Usage
+
+```ts
+import { getVersionInfo } from "@adammcarter/use-cases-core";
+
+getVersionInfo(); // { name: "@adammcarter/use-cases", version: "1.0.0" }
+```
+
+## Stability
+
+Only the **documented** TypeScript exports are part of the public, SemVer-governed
+surface. See the
+[stability & versioning policy](https://github.com/adammcarter/use-cases/blob/main/docs/reference/stability.md).
+
+## License
+
+[MIT](https://github.com/adammcarter/use-cases/blob/main/LICENSE)

package/packages/core/dist/capsules/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./loadCapsule.js";
+export * from "./runCapsule.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/core/dist/capsules/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/capsules/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/packages/core/dist/capsules/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./loadCapsule.js";
+export * from "./runCapsule.js";
+//# sourceMappingURL=index.js.map

package/packages/core/dist/capsules/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capsules/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC"}

package/packages/core/dist/capsules/loadCapsule.d.ts

@@ -0,0 +1,11 @@
+import type { ResolvedWorkspaceContext } from "../roots.js";
+import type { CapsulePlanResult, CapsuleSnapshot } from "./types.js";
+export declare function demoCapsulesRoot(context: ResolvedWorkspaceContext): string;
+export declare function loadDemoCapsules(options: {
+    context: ResolvedWorkspaceContext;
+}): CapsuleSnapshot;
+export declare function planDemoCapsule(options: {
+    context: ResolvedWorkspaceContext;
+    capsuleId: string;
+}): CapsulePlanResult;
+//# sourceMappingURL=loadCapsule.d.ts.map

package/packages/core/dist/capsules/loadCapsule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadCapsule.d.ts","sourceRoot":"","sources":["../../src/capsules/loadCapsule.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAY5D,OAAO,KAAK,EAAqB,iBAAiB,EAAE,eAAe,EAAkC,MAAM,YAAY,CAAC;AAIxH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,wBAAwB,GAAG,MAAM,CAE1E;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,wBAAwB,CAAA;CAAE,GAAG,eAAe,CA4ChG;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE;IAAE,OAAO,EAAE,wBAAwB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,iBAAiB,CA8CpH"}

package/packages/core/dist/capsules/loadCapsule.js

@@ -0,0 +1,167 @@
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { extname, isAbsolute, join, relative, sep } from "node:path";
+import { computeSemanticHash, diagnostic, parseYamlToJson, validateBySchemaId } from "../schema/index.js";
+import { loadUseCaseMatrix } from "../useCases/loadUseCaseMatrix.js";
+import { replayEvidence } from "../evidence/index.js";
+import { selectShowcasePlan, selectWalkthroughPlan } from "../presentation/index.js";
+const DEMO_CAPSULE_SCHEMA_ID = "https://use-cases.dev/schemas/v1/demo-capsule.schema.json";
+export function demoCapsulesRoot(context) {
+    return join(context.data_root, "demo-capsules");
+}
+export function loadDemoCapsules(options) {
+    const diagnostics = [];
+    const files = [];
+    const capsules = [];
+    const root = demoCapsulesRoot(options.context);
+    if (!existsSync(root)) {
+        return { schema_version: 1, complete: true, files, capsules, diagnostics };
+    }
+    const seen = new Map();
+    const rootRealPath = realpathSync(root);
+    for (const entry of listCapsuleEntries(root, root, options.context.data_root, rootRealPath, diagnostics, files)) {
+        const result = validateCapsuleFile(entry.filePath, entry.sourcePath);
+        files.push(result.file);
+        diagnostics.push(...result.diagnostics);
+        if (!result.capsule) {
+            continue;
+        }
+        const duplicatePath = seen.get(result.capsule.capsule.capsule_id);
+        if (duplicatePath) {
+            diagnostics.push(diagnostic("capsule.duplicate_id", `Duplicate capsule id '${result.capsule.capsule.capsule_id}'.`, result.capsule.path, result.capsule.capsule.capsule_id, [duplicatePath]));
+            files[files.length - 1] = { ...files[files.length - 1], status: "schema_error" };
+            continue;
+        }
+        seen.set(result.capsule.capsule.capsule_id, result.capsule.path);
+        capsules.push(result.capsule);
+    }
+    return {
+        schema_version: 1,
+        complete: diagnostics.every((item) => item.severity !== "error"),
+        files,
+        capsules,
+        diagnostics
+    };
+}
+export function planDemoCapsule(options) {
+    const snapshot = loadDemoCapsules({ context: options.context });
+    const capsule = snapshot.capsules.find((candidate) => candidate.capsule.capsule_id === options.capsuleId) ?? null;
+    if (!snapshot.complete) {
+        return {
+            schema_version: 1,
+            outcome: "integrity_blocked",
+            capsule,
+            plan_result: null,
+            diagnostics: snapshot.diagnostics
+        };
+    }
+    if (!capsule) {
+        return {
+            schema_version: 1,
+            outcome: "capsule_not_found",
+            capsule: null,
+            plan_result: null,
+            diagnostics: [
+                diagnostic("capsule.not_found", `Capsule '${options.capsuleId}' was not found.`, null, options.capsuleId)
+            ]
+        };
+    }
+    const matrix = loadUseCaseMatrix({ context: options.context });
+    const evidence = replayEvidence({ context: options.context });
+    const request = {
+        audience: capsule.capsule.audience,
+        timeboxSeconds: capsule.capsule.timebox_seconds,
+        maxItems: capsule.capsule.items.length,
+        requestedUseCaseIds: capsule.capsule.items.map((item) => item.use_case_id),
+        generatedAt: "2026-06-25T12:00:00.000Z",
+        freshnessEvaluatedAt: "2026-06-25T12:00:00.000Z"
+    };
+    const planResult = capsule.capsule.mode === "showcase"
+        ? selectShowcasePlan({ context: options.context, matrix, evidence, request })
+        : selectWalkthroughPlan({ context: options.context, matrix, evidence, request });
+    return {
+        schema_version: 1,
+        outcome: "generated",
+        capsule,
+        plan_result: planResult,
+        diagnostics: [...snapshot.diagnostics, ...matrix.diagnostics, ...evidence.diagnostics]
+    };
+}
+function validateCapsuleFile(filePath, sourcePath) {
+    const source = readFileSync(filePath, "utf8");
+    const fileHash = computeSemanticHash(source);
+    const parsed = parseCapsuleSource(source, sourcePath, extname(filePath));
+    if (!parsed.ok) {
+        return {
+            file: { path: sourcePath, status: "parse_error", file_hash: fileHash },
+            capsule: null,
+            diagnostics: parsed.diagnostics
+        };
+    }
+    const validation = validateBySchemaId(DEMO_CAPSULE_SCHEMA_ID, parsed.value, sourcePath);
+    if (!validation.ok) {
+        return {
+            file: { path: sourcePath, status: "schema_error", file_hash: fileHash },
+            capsule: null,
+            diagnostics: validation.diagnostics
+        };
+    }
+    return {
+        file: { path: sourcePath, status: "loaded", file_hash: fileHash },
+        capsule: {
+            capsule: parsed.value,
+            path: sourcePath,
+            semantic_hash: computeSemanticHash(parsed.value)
+        },
+        diagnostics: []
+    };
+}
+function parseCapsuleSource(source, sourcePath, extension) {
+    if (extension === ".json") {
+        try {
+            return { ok: true, value: JSON.parse(source), diagnostics: [] };
+        }
+        catch (error) {
+            return {
+                ok: false,
+                diagnostics: [diagnostic("parse_error", error instanceof Error ? error.message : String(error), sourcePath)]
+            };
+        }
+    }
+    return parseYamlToJson(source, sourcePath);
+}
+function listCapsuleEntries(root, current, dataRoot, rootRealPath, diagnostics, files) {
+    const entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    const results = [];
+    for (const entry of entries) {
+        const fullPath = join(current, entry.name);
+        const sourcePath = relative(dataRoot, fullPath).split(sep).join("/");
+        const stat = lstatSync(fullPath);
+        if (stat.isSymbolicLink()) {
+            files.push({ path: sourcePath, status: "symlink_rejected" });
+            diagnostics.push(diagnostic("capsule.symlink_rejected", "Symlinks under demo-capsules are not followed.", sourcePath));
+            continue;
+        }
+        if (stat.isDirectory()) {
+            results.push(...listCapsuleEntries(root, fullPath, dataRoot, rootRealPath, diagnostics, files));
+            continue;
+        }
+        if (!stat.isFile()) {
+            files.push({ path: sourcePath, status: "io_error" });
+            diagnostics.push(diagnostic("capsule.io_error", "Only regular files are supported under demo-capsules.", sourcePath));
+            continue;
+        }
+        if (![".yml", ".yaml", ".json"].includes(extname(fullPath))) {
+            continue;
+        }
+        const realPath = realpathSync(fullPath);
+        const rel = relative(rootRealPath, realPath);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            files.push({ path: sourcePath, status: "path_escape" });
+            diagnostics.push(diagnostic("capsule.path_escape", "Capsule file escapes demo-capsules root.", sourcePath));
+            continue;
+        }
+        results.push({ filePath: fullPath, sourcePath });
+    }
+    return results;
+}
+//# sourceMappingURL=loadCapsule.js.map

package/packages/core/dist/capsules/loadCapsule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loadCapsule.js","sourceRoot":"","sources":["../../src/capsules/loadCapsule.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/capsules/runCapsule.d.ts

@@ -0,0 +1,3 @@
+import type { DemoCapsuleRunOptions, DemoCapsuleRunResult } from "./types.js";
+export declare function runDemoCapsule(options: DemoCapsuleRunOptions): DemoCapsuleRunResult;
+//# sourceMappingURL=runCapsule.d.ts.map

package/packages/core/dist/capsules/runCapsule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runCapsule.d.ts","sourceRoot":"","sources":["../../src/capsules/runCapsule.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAIV,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAqBpB,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,oBAAoB,CA0OnF"}

package/packages/core/dist/capsules/runCapsule.js

@@ -0,0 +1,333 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, realpathSync } from "node:fs";
+import { isAbsolute, relative, resolve } from "node:path";
+import { diagnostic } from "../schema/index.js";
+import { redactSecrets } from "../redact.js";
+import { appendShowcaseAction, appendShowcaseObservation, appendShowcaseVerdict, finishShowcaseRun, readShowcaseEvents, replayShowcaseRun, startShowcaseRun } from "../showcase/index.js";
+import { planDemoCapsule } from "./loadCapsule.js";
+const DEFAULT_RECORDED_AT = "2026-06-25T12:00:00.000Z";
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+const MAX_COMMAND_TIMEOUT_MS = 300_000;
+const MAX_CAPTURED_OUTPUT_BYTES = 16_384;
+const COMMAND_MAX_BUFFER_BYTES = 1_048_576;
+export function runDemoCapsule(options) {
+    const actorType = options.actorType ?? "agent";
+    const hostSurface = options.hostSurface ?? "codex.cli";
+    const recordedAt = options.recordedAt ?? DEFAULT_RECORDED_AT;
+    const planResult = planDemoCapsule({ context: options.context, capsuleId: options.capsuleId });
+    if (planResult.outcome !== "generated" || !planResult.capsule || !planResult.plan_result?.plan) {
+        return blocked(options.capsuleId, planResult.plan_result, planResult.diagnostics);
+    }
+    if (!planResult.plan_result.plan.complete) {
+        return blocked(options.capsuleId, planResult.plan_result, [
+            diagnostic("capsule.plan_incomplete", "Capsule plan must be complete before it can be performed.", null, options.capsuleId),
+            ...planResult.diagnostics
+        ]);
+    }
+    const plannedSteps = plannedCapsuleSteps(planResult);
+    if ("diagnostics" in plannedSteps) {
+        return blocked(options.capsuleId, planResult.plan_result, plannedSteps.diagnostics);
+    }
+    const commandSteps = plannedSteps.filter((entry) => entry.step.kind === "command");
+    if (options.executeCommands && commandSteps.length > 0 && !planResult.capsule.capsule.permissions.command_execution) {
+        return blocked(options.capsuleId, planResult.plan_result, [
+            diagnostic("capsule.command_execution_not_permitted", "Capsule does not permit command execution.", planResult.capsule.path, options.capsuleId)
+        ]);
+    }
+    const resolvedCommands = options.executeCommands ? resolveCommandSteps(options, commandSteps) : [];
+    if ("diagnostics" in resolvedCommands) {
+        return blocked(options.capsuleId, planResult.plan_result, resolvedCommands.diagnostics);
+    }
+    if (options.executeCommands && commandSteps.length > 0) {
+        const timeoutMs = options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_COMMAND_TIMEOUT_MS) {
+            return blocked(options.capsuleId, planResult.plan_result, [
+                diagnostic("capsule.command_timeout_invalid", `Command timeout must be between 1 and ${MAX_COMMAND_TIMEOUT_MS} milliseconds.`, planResult.capsule.path, options.capsuleId)
+            ]);
+        }
+    }
+    const baseKey = options.idempotencyKey ?? `capsule:${options.capsuleId}:${Date.now()}`;
+    const start = startShowcaseRun({
+        context: options.context,
+        plan: planResult.plan_result.plan,
+        controlMode: commandSteps.length > 0 ? "script_led" : "agent_led",
+        actorType,
+        hostSurface,
+        idempotencyKey: `${baseKey}:start`,
+        recordedAt
+    });
+    const runId = start.run_id;
+    const eventsWritten = [...start.appended_event_ids];
+    const pendingSteps = [];
+    const commandResults = [];
+    const commandByStep = new Map(commandSteps.map((step, index) => [stepKey(step), resolvedCommands[index]]));
+    for (const entry of plannedSteps) {
+        const stepId = `${entry.itemIndex}.${entry.stepIndex}`;
+        if (entry.step.kind === "instruction") {
+            eventsWritten.push(...appendShowcaseAction({
+                context: options.context,
+                runId,
+                planItemId: entry.planItemId,
+                action: {
+                    kind: "instruction",
+                    text: entry.step.text,
+                    source: "demo_capsule",
+                    item_index: entry.itemIndex,
+                    step_index: entry.stepIndex
+                },
+                actorType,
+                hostSurface,
+                idempotencyKey: `${baseKey}:action:${stepId}`,
+                recordedAt
+            }).appended_event_ids);
+            continue;
+        }
+        if (entry.step.kind === "observation") {
+            eventsWritten.push(...appendShowcaseAction({
+                context: options.context,
+                runId,
+                planItemId: entry.planItemId,
+                action: {
+                    kind: "expected_observation_prompt",
+                    text: entry.step.text,
+                    source: "demo_capsule",
+                    item_index: entry.itemIndex,
+                    step_index: entry.stepIndex
+                },
+                actorType,
+                hostSurface,
+                idempotencyKey: `${baseKey}:expected-observation:${stepId}`,
+                recordedAt
+            }).appended_event_ids);
+            pendingSteps.push({
+                item_index: entry.itemIndex,
+                step_index: entry.stepIndex,
+                use_case_id: entry.useCaseId,
+                reason: "runtime_observation_required"
+            });
+            continue;
+        }
+        if (!options.executeCommands) {
+            pendingSteps.push({
+                item_index: entry.itemIndex,
+                step_index: entry.stepIndex,
+                use_case_id: entry.useCaseId,
+                reason: "command_execution_not_requested"
+            });
+            continue;
+        }
+        const resolvedCommand = commandByStep.get(stepKey(entry));
+        if (!resolvedCommand) {
+            continue;
+        }
+        if (hasCommittedEvent(options.context, runId, `${baseKey}:command-verdict:${stepId}`)) {
+            continue;
+        }
+        const commandResult = runCommandStep(resolvedCommand, options.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+        commandResults.push(commandResult);
+        eventsWritten.push(...appendShowcaseAction({
+            context: options.context,
+            runId,
+            planItemId: entry.planItemId,
+            action: {
+                kind: "command",
+                executable: entry.step.executable,
+                argv: entry.step.argv,
+                working_directory: entry.step.working_directory,
+                source: "demo_capsule",
+                item_index: entry.itemIndex,
+                step_index: entry.stepIndex
+            },
+            actorType: "script",
+            hostSurface,
+            idempotencyKey: `${baseKey}:command-action:${stepId}`,
+            recordedAt
+        }).appended_event_ids);
+        const observation = appendShowcaseObservation({
+            context: options.context,
+            runId,
+            planItemId: entry.planItemId,
+            text: commandObservationText(commandResult),
+            actorType: "script",
+            hostSurface,
+            idempotencyKey: `${baseKey}:command-observation:${stepId}`,
+            recordedAt
+        });
+        eventsWritten.push(...observation.appended_event_ids);
+        eventsWritten.push(...appendShowcaseVerdict({
+            context: options.context,
+            runId,
+            planItemId: entry.planItemId,
+            verdict: commandResult.matched_expected_exit_code ? "pass" : "fail",
+            observationEventIds: observation.appended_event_ids,
+            actorType: "script",
+            hostSurface,
+            idempotencyKey: `${baseKey}:command-verdict:${stepId}`,
+            recordedAt
+        }).appended_event_ids);
+    }
+    for (const item of planResult.capsule.capsule.items) {
+        const itemHasPending = pendingSteps.some((step) => step.use_case_id === item.use_case_id);
+        const itemHasCommandVerdict = commandResults.some((result) => result.use_case_id === item.use_case_id);
+        const itemHasFailure = commandResults.some((result) => result.use_case_id === item.use_case_id && !result.matched_expected_exit_code);
+        if (!itemHasPending && !itemHasCommandVerdict && !itemHasFailure) {
+            const status = replayShowcaseRun({ context: options.context, runId });
+            const planItem = status.items.find((candidate) => planResult.plan_result?.plan?.selected_items.some((selected) => selected.plan_item_id === candidate.plan_item_id && selected.use_case_id === item.use_case_id));
+            if (planItem?.latest_observation_event_id) {
+                eventsWritten.push(...appendShowcaseVerdict({
+                    context: options.context,
+                    runId,
+                    planItemId: planItem.plan_item_id,
+                    verdict: "pass",
+                    observationEventIds: [planItem.latest_observation_event_id],
+                    actorType,
+                    hostSurface,
+                    idempotencyKey: `${baseKey}:item-verdict:${item.use_case_id}`,
+                    recordedAt
+                }).appended_event_ids);
+            }
+        }
+    }
+    let status = replayShowcaseRun({ context: options.context, runId });
+    if (pendingSteps.length === 0 && status.unresolved_failure_count === 0) {
+        const finish = finishShowcaseRun({
+            context: options.context,
+            runId,
+            actorType,
+            hostSurface,
+            idempotencyKey: `${baseKey}:finish`,
+            recordedAt
+        });
+        eventsWritten.push(...finish.appended_event_ids);
+        status = finish.status;
+    }
+    const complete = pendingSteps.length === 0 &&
+        status.execution_status === "completed" &&
+        (status.run_outcome === "passed" || status.run_outcome === "passed_with_waivers");
+    return {
+        schema_version: 1,
+        outcome: "performed",
+        complete,
+        capsule_id: options.capsuleId,
+        run_id: runId,
+        events_written: [...new Set(eventsWritten)],
+        pending_steps: pendingSteps,
+        command_results: commandResults,
+        status,
+        plan_result: planResult.plan_result,
+        diagnostics: planResult.diagnostics
+    };
+}
+function plannedCapsuleSteps(planResult) {
+    const plan = planResult.plan_result?.plan;
+    const capsule = planResult.capsule?.capsule;
+    if (!plan || !capsule) {
+        return { diagnostics: [diagnostic("capsule.plan_missing", "Capsule plan is missing.", null)] };
+    }
+    const planItemByUseCase = new Map(plan.selected_items.map((item) => [item.use_case_id, item.plan_item_id]));
+    const steps = [];
+    const diagnostics = [];
+    capsule.items.forEach((item, itemIndex) => {
+        const planItemId = planItemByUseCase.get(item.use_case_id);
+        if (!planItemId) {
+            diagnostics.push(diagnostic("capsule.plan_item_missing", `Capsule use case '${item.use_case_id}' was not selected in the generated plan.`, null, item.use_case_id));
+            return;
+        }
+        item.runbook.forEach((step, stepIndex) => {
+            steps.push({ itemIndex, stepIndex, useCaseId: item.use_case_id, planItemId, step });
+        });
+    });
+    return diagnostics.length > 0 ? { diagnostics } : steps;
+}
+function resolveCommandSteps(options, commandSteps) {
+    const diagnostics = [];
+    const workspaceRealPath = realpathSync(options.context.workspace_root);
+    const resolved = commandSteps.map((entry) => {
+        const requested = entry.step.working_directory || ".";
+        const candidate = isAbsolute(requested)
+            ? resolve(requested)
+            : resolve(options.context.workspace_root, requested);
+        const checked = existsSync(candidate) ? realpathSync(candidate) : candidate;
+        const rel = relative(workspaceRealPath, checked);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            diagnostics.push(diagnostic("capsule.command_cwd_escape", "Command working_directory must stay inside repo.", null, entry.useCaseId));
+        }
+        return { ...entry, cwd: checked };
+    });
+    return diagnostics.length > 0 ? { diagnostics } : resolved;
+}
+function runCommandStep(step, timeoutMs) {
+    const result = spawnSync(step.step.executable, step.step.argv, {
+        cwd: step.cwd,
+        encoding: "utf8",
+        env: commandEnvironment(),
+        shell: false,
+        timeout: timeoutMs,
+        maxBuffer: COMMAND_MAX_BUFFER_BYTES
+    });
+    const exitCode = result.status;
+    return {
+        item_index: step.itemIndex,
+        step_index: step.stepIndex,
+        use_case_id: step.useCaseId,
+        executable: step.step.executable,
+        argv: step.step.argv,
+        working_directory: step.step.working_directory,
+        exit_code: exitCode,
+        signal: result.signal,
+        stdout: sanitizeCommandOutput(result.stdout ?? ""),
+        stderr: sanitizeCommandOutput(result.stderr ?? result.error?.message ?? ""),
+        expected_exit_codes: step.step.expected_exit_codes,
+        matched_expected_exit_code: typeof exitCode === "number" && step.step.expected_exit_codes.includes(exitCode)
+    };
+}
+function commandObservationText(result) {
+    return [
+        `Command exited ${result.exit_code ?? "null"}${result.signal ? ` with signal ${result.signal}` : ""}.`,
+        `Expected exit codes: ${result.expected_exit_codes.join(", ") || "<none>"}.`,
+        `stdout:\n${result.stdout || "<empty>"}`,
+        `stderr:\n${result.stderr || "<empty>"}`
+    ].join("\n");
+}
+function blocked(capsuleId, planResult, diagnostics) {
+    return {
+        schema_version: 1,
+        outcome: "blocked",
+        complete: false,
+        capsule_id: capsuleId,
+        run_id: null,
+        events_written: [],
+        pending_steps: [],
+        command_results: [],
+        status: null,
+        plan_result: planResult,
+        diagnostics
+    };
+}
+function stepKey(step) {
+    return `${step.itemIndex}:${step.stepIndex}`;
+}
+function hasCommittedEvent(context, runId, idempotencyKey) {
+    return readShowcaseEvents(context, runId).events.some((event) => event.idempotency_key === idempotencyKey);
+}
+function commandEnvironment() {
+    return copyDefinedEnv(["PATH", "HOME", "TMPDIR", "TEMP", "TMP", "SystemRoot", "WINDIR"]);
+}
+function copyDefinedEnv(keys) {
+    const env = {};
+    for (const key of keys) {
+        if (process.env[key] !== undefined) {
+            env[key] = process.env[key];
+        }
+    }
+    return env;
+}
+function sanitizeCommandOutput(value) {
+    return truncateOutput(redactSecrets(value));
+}
+function truncateOutput(value) {
+    return value.length > MAX_CAPTURED_OUTPUT_BYTES
+        ? `${value.slice(0, MAX_CAPTURED_OUTPUT_BYTES)}\n[truncated]`
+        : value;
+}
+//# sourceMappingURL=runCapsule.js.map