@adammcarter/use-cases 0.1.0

package/packages/cli/dist/commands/matrix.js

@@ -0,0 +1,237 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createCliResult, errorEnvelope, loadUseCaseMatrix, mutateUseCaseMatrix, queryUseCases, replayEvidence, resolveContextOrError, toEvidenceStatusResult, toMatrixListResult, toMatrixValidationResult } from "../runtime.js";
+import { componentFlag, dataRootFlag, jsonFlag, repoFlag, workspaceFlags } from "./common.js";
+// Shared post-mutation result mapping (the legacy writeMutationResult), returning
+// the envelope + exit code instead of writing: ok unless blocked; a path-escape
+// diagnostic maps to exit 4, any other block to exit 1.
+function mutationOutput(command, result, context) {
+    const ok = result.status !== "blocked";
+    const envelope = createCliResult(command, result, {
+        ok,
+        complete: ok,
+        diagnostics: result.diagnostics,
+        workspaceRoot: context.workspace_root,
+        dataRoot: context.data_root,
+        componentId: context.component_id
+    });
+    if (ok) {
+        return { envelope, exitCode: 0 };
+    }
+    const pathEscape = result.diagnostics.some((item) => item.code === "matrix.mutation_path_escape");
+    return { envelope, exitCode: pathEscape ? 4 : 1 };
+}
+export const matrixValidateCommand = {
+    path: ["matrix", "validate"],
+    command: "matrix.validate",
+    summary: "Validate the use-case matrix.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "matrix.validate");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const snapshot = loadUseCaseMatrix({ context: context.context });
+        return {
+            envelope: createCliResult("matrix.validate", toMatrixValidationResult(snapshot), {
+                ok: true,
+                complete: snapshot.complete,
+                diagnostics: snapshot.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: snapshot.complete ? 0 : 1
+        };
+    }
+};
+export const matrixListCommand = {
+    path: ["matrix", "list"],
+    command: "matrix.list",
+    summary: "Query and list use cases.",
+    flags: [
+        ...workspaceFlags,
+        { key: "value", name: "--value", kind: "string", repeatable: true, valueName: "<tier>", summary: "Filter by value tier (repeatable)." },
+        { key: "journeyRole", name: "--journey-role", kind: "string", repeatable: true, valueName: "<role>", summary: "Filter by journey role (repeatable)." },
+        { key: "lifecycle", name: "--lifecycle", kind: "string", repeatable: true, valueName: "<state>", summary: "Filter by lifecycle (repeatable)." },
+        { key: "host", name: "--host", kind: "string", repeatable: true, valueName: "<surface>", summary: "Filter by host surface (repeatable)." },
+        { key: "tag", name: "--tag", kind: "string", repeatable: true, valueName: "<tag>", summary: "Filter by tag (repeatable)." },
+        { key: "changedPath", name: "--changed-path", kind: "string", repeatable: true, valueName: "<path>", summary: "Filter by changed path (repeatable)." },
+        { key: "strict", name: "--strict", kind: "boolean", summary: "Fail when the matrix is incomplete." }
+    ],
+    handler: ({ argv, flags }) => {
+        const strict = flags.strict;
+        const context = resolveContextOrError(argv, "matrix.list");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const snapshot = loadUseCaseMatrix({ context: context.context });
+        const selected = queryUseCases(snapshot, {
+            valueTiers: flags.value,
+            journeyRoles: flags.journeyRole,
+            lifecycles: flags.lifecycle,
+            hostSurfaces: flags.host,
+            tagsAny: flags.tag,
+            changedPaths: flags.changedPath
+        });
+        const ok = strict ? snapshot.complete : true;
+        return {
+            envelope: createCliResult("matrix.list", toMatrixListResult(snapshot, selected), {
+                ok,
+                complete: snapshot.complete,
+                diagnostics: snapshot.diagnostics,
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: ok ? 0 : 3
+        };
+    }
+};
+export const matrixStatusCommand = {
+    path: ["matrix", "status"],
+    command: "matrix.status",
+    summary: "Compose matrix and evidence completeness.",
+    flags: workspaceFlags,
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "matrix.status");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const matrix = loadUseCaseMatrix({ context: context.context });
+        const evidence = replayEvidence({ context: context.context });
+        const data = {
+            schema_version: 1,
+            complete: matrix.complete && evidence.complete,
+            matrix: toMatrixValidationResult(matrix),
+            evidence: toEvidenceStatusResult(evidence)
+        };
+        return {
+            envelope: createCliResult("matrix.status", data, {
+                ok: data.complete,
+                complete: data.complete,
+                diagnostics: [...matrix.diagnostics, ...evidence.diagnostics],
+                workspaceRoot: context.context.workspace_root,
+                dataRoot: context.context.data_root,
+                componentId: context.context.component_id
+            }),
+            exitCode: data.complete ? 0 : 1
+        };
+    }
+};
+export const matrixUpsertCommand = {
+    path: ["matrix", "upsert"],
+    command: "matrix.upsert",
+    summary: "Add or update a single use-case row.",
+    flags: [
+        ...workspaceFlags,
+        { key: "file", name: "--file", kind: "string", required: true, valueName: "<path>", summary: "Target use-case file (inside use-cases/)." },
+        { key: "useCaseJson", name: "--use-case-json", kind: "string", valueName: "<json>", summary: "Inline JSON for the use-case row." },
+        { key: "useCaseFile", name: "--use-case-file", kind: "string", valueName: "<path>", summary: "Read the use-case JSON from a file (alternative to --use-case-json)." },
+        { key: "expectedHash", name: "--expected-hash", kind: "string", valueName: "<hash>", summary: "Optimistic-concurrency guard for updates." }
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "matrix.upsert");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const targetFile = flags.file;
+        const inlineJson = flags.useCaseJson;
+        const useCaseFile = flags.useCaseFile;
+        if (!targetFile || (!inlineJson && !useCaseFile)) {
+            return {
+                envelope: errorEnvelope("matrix.upsert", "cli_invalid_arguments", "Missing --file or one of --use-case-json / --use-case-file."),
+                exitCode: 2
+            };
+        }
+        if (inlineJson && useCaseFile) {
+            return {
+                envelope: errorEnvelope("matrix.upsert", "cli_invalid_arguments", "Use only one of --use-case-json or --use-case-file."),
+                exitCode: 2
+            };
+        }
+        let useCaseJson;
+        if (useCaseFile) {
+            // --use-case-file is a read-only one-shot input (stdin-from-a-file), so it
+            // is intentionally NOT containment-restricted: agents pass scratch JSON from
+            // /tmp. A non-JSON target simply fails JSON.parse below.
+            const useCaseFilePath = resolve(process.cwd(), useCaseFile);
+            try {
+                useCaseJson = readFileSync(useCaseFilePath, "utf8");
+            }
+            catch {
+                return {
+                    envelope: errorEnvelope("matrix.upsert", "matrix.use_case_file_unreadable", `Could not read --use-case-file: ${useCaseFilePath}`),
+                    exitCode: 2
+                };
+            }
+        }
+        else {
+            useCaseJson = inlineJson;
+        }
+        let useCase;
+        try {
+            useCase = JSON.parse(useCaseJson);
+        }
+        catch (error) {
+            return {
+                envelope: errorEnvelope("matrix.upsert", "matrix.mutation_invalid_json", error instanceof Error ? error.message : String(error)),
+                exitCode: 2
+            };
+        }
+        const result = mutateUseCaseMatrix({
+            context: context.context,
+            operation: "upsert",
+            targetFile,
+            useCase,
+            expectedSemanticHash: flags.expectedHash ?? undefined,
+            actor: "agent"
+        });
+        return mutationOutput("matrix.upsert", result, context.context);
+    }
+};
+export const matrixRemoveCommand = {
+    path: ["matrix", "remove"],
+    command: "matrix.remove",
+    summary: "Soft-remove a use-case row.",
+    flags: [
+        repoFlag,
+        dataRootFlag,
+        componentFlag,
+        { key: "useCase", name: "--use-case", kind: "string", required: true, valueName: "<id>", summary: "Use-case id to remove." },
+        { key: "reason", name: "--reason", kind: "string", required: true, valueName: "<text>", summary: "Why the row is being removed." },
+        { key: "expectedHash", name: "--expected-hash", kind: "string", valueName: "<hash>", summary: "Optimistic-concurrency guard." },
+        jsonFlag
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "matrix.remove");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const useCaseId = flags.useCase;
+        const reason = flags.reason;
+        if (!useCaseId || !reason) {
+            return {
+                envelope: errorEnvelope("matrix.remove", "cli_invalid_arguments", "Missing --use-case or --reason."),
+                exitCode: 2
+            };
+        }
+        const result = mutateUseCaseMatrix({
+            context: context.context,
+            operation: "remove",
+            useCaseId,
+            reason,
+            expectedSemanticHash: flags.expectedHash ?? undefined,
+            actor: "agent"
+        });
+        return mutationOutput("matrix.remove", result, context.context);
+    }
+};
+export const matrixCommands = [
+    matrixValidateCommand,
+    matrixListCommand,
+    matrixStatusCommand,
+    matrixUpsertCommand,
+    matrixRemoveCommand
+];
+//# sourceMappingURL=matrix.js.map

package/packages/cli/dist/commands/matrix.js.map

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

package/packages/cli/dist/commands/migrate.d.ts

@@ -0,0 +1,4 @@
+import type { CliCommand } from "../command/types.js";
+export declare const migrateTestMatrixCommand: CliCommand;
+export declare const migrateCommands: CliCommand[];
+//# sourceMappingURL=migrate.d.ts.map

package/packages/cli/dist/commands/migrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/commands/migrate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAwBtD,eAAO,MAAM,wBAAwB,EAAE,UA8DtC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,UAAU,EAA+B,CAAC"}

package/packages/cli/dist/commands/migrate.js

@@ -0,0 +1,82 @@
+import { valueAfter } from "../args/parse.js";
+import { createCliResult, errorEnvelope, migrateTestMatrix, resolveContextOrError } from "../runtime.js";
+import { workspaceFlags } from "./common.js";
+// Local port of the legacy migrationDiagnostics helper: map migration warnings to
+// the standard diagnostic shape (unchanged from legacy.ts).
+function migrationDiagnostics(result) {
+    return result.warnings.map((warning) => ({
+        code: warning.code,
+        severity: "warning",
+        message: warning.message,
+        source_path: warning.row_ref,
+        json_pointer: null,
+        entity_id: null,
+        related_ids: []
+    }));
+}
+export const migrateTestMatrixCommand = {
+    path: ["migrate", "test-matrix"],
+    command: "migrate.test-matrix",
+    summary: "Migrate a legacy TEST-MATRIX into the use-case matrix.",
+    flags: [
+        ...workspaceFlags,
+        { key: "source", name: "--source", kind: "string", required: true, valueName: "<path>", summary: "Legacy TEST-MATRIX source file." },
+        { key: "out", name: "--out", kind: "string", valueName: "<dir>", summary: "Output directory for the migrated use-case files." },
+        { key: "dryRun", name: "--dry-run", kind: "boolean", summary: "Preview the migration without writing (default)." },
+        { key: "write", name: "--write", kind: "boolean", summary: "Write the migrated use-case files to disk." }
+    ],
+    handler: ({ argv }) => {
+        const context = resolveContextOrError(argv, "migrate.test-matrix");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const sourcePath = valueAfter(argv, "--source");
+        if (!sourcePath) {
+            return {
+                envelope: errorEnvelope("migrate.test-matrix", "migration_source_required", "Missing --source."),
+                exitCode: 2
+            };
+        }
+        const selectedModes = [
+            argv.includes("--dry-run") ? "dry_run" : null,
+            argv.includes("--write") ? "write" : null
+        ].filter((value) => value !== null);
+        if (selectedModes.length > 1) {
+            return {
+                envelope: errorEnvelope("migrate.test-matrix", "migration_mode_conflict", "Use only one of --dry-run or --write."),
+                exitCode: 2
+            };
+        }
+        const mode = selectedModes[0] ?? "dry_run";
+        try {
+            const result = migrateTestMatrix({
+                context: context.context,
+                sourcePath,
+                outDir: valueAfter(argv, "--out") ?? undefined,
+                mode
+            });
+            const hasConflict = result.would_write.some((operation) => operation.action === "conflict");
+            return {
+                envelope: createCliResult("migrate.test-matrix", result, {
+                    ok: !hasConflict,
+                    complete: result.warnings.length === 0 && !hasConflict,
+                    diagnostics: migrationDiagnostics(result),
+                    workspaceRoot: context.context.workspace_root,
+                    dataRoot: context.context.data_root,
+                    componentId: context.context.component_id
+                }),
+                exitCode: hasConflict ? 1 : 0
+            };
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "internal_error";
+            const exitCode = code === "migration_unsafe_output_path" || code === "migration_unsafe_source_path" ? 4 : 1;
+            return {
+                envelope: errorEnvelope("migrate.test-matrix", code, error instanceof Error ? error.message : String(error)),
+                exitCode
+            };
+        }
+    }
+};
+export const migrateCommands = [migrateTestMatrixCommand];
+//# sourceMappingURL=migrate.js.map

package/packages/cli/dist/commands/migrate.js.map

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

package/packages/cli/dist/commands/plan.d.ts

@@ -0,0 +1,6 @@
+import type { CliCommand } from "../command/types.js";
+export declare const planShowcaseCommand: CliCommand;
+export declare const planWalkthroughCommand: CliCommand;
+export declare const planCardsCommand: CliCommand;
+export declare const planCommands: CliCommand[];
+//# sourceMappingURL=plan.d.ts.map

package/packages/cli/dist/commands/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/commands/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,qBAAqB,CAAC;AAoElF,eAAO,MAAM,mBAAmB,EAAE,UAMjC,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,UAMpC,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,UA2D9B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,UAAU,EAAoE,CAAC"}

package/packages/cli/dist/commands/plan.js

@@ -0,0 +1,129 @@
+import { containedPathOrError, createCliResult, errorEnvelope, loadPresentationPlanFile, loadUseCaseMatrix, renderCard, replayEvidence, resolveContextOrError, selectShowcasePlan, selectWalkthroughPlan } from "../runtime.js";
+import { repoFlag, dataRootFlag, componentFlag, jsonFlag, workspaceFlags } from "./common.js";
+// Shared port of the legacy `runPlan(argv, mode)` — builds the same request, calls
+// the same selector, and surfaces matrix+evidence diagnostics in the envelope
+// regardless of outcome. Returns envelope + exit code instead of writing stdout.
+function planOutput(argv, flags, mode) {
+    const context = resolveContextOrError(argv, `plan.${mode}`);
+    if (context.kind === "error") {
+        return { envelope: context.envelope, exitCode: context.exitCode };
+    }
+    const ctx = context.context;
+    const matrix = loadUseCaseMatrix({ context: ctx });
+    const evidence = replayEvidence({ context: ctx });
+    const request = {
+        audience: flags.audience ?? "reviewer",
+        timeboxSeconds: flags.timebox ?? (mode === "showcase" ? 600 : 1800),
+        maxItems: flags.maxItems,
+        hostSurface: (flags.host ?? "unknown"),
+        changedPaths: flags.changedPath,
+        generatedAt: flags.generatedAt,
+        strict: flags.strict
+    };
+    const result = mode === "showcase"
+        ? selectShowcasePlan({ context: ctx, matrix, evidence, request })
+        : selectWalkthroughPlan({ context: ctx, matrix, evidence, request });
+    const ok = result.outcome !== "integrity_blocked";
+    const complete = result.plan?.complete ?? (result.outcome === "no_eligible_items" && matrix.complete && evidence.complete);
+    const envelope = createCliResult(`plan.${mode}`, result, {
+        ok,
+        complete,
+        diagnostics: [...matrix.diagnostics, ...evidence.diagnostics],
+        workspaceRoot: ctx.workspace_root,
+        dataRoot: ctx.data_root,
+        componentId: ctx.component_id
+    });
+    if (result.outcome === "integrity_blocked") {
+        return { envelope, exitCode: 3 };
+    }
+    if (result.outcome === "no_eligible_items") {
+        return { envelope, exitCode: 1 };
+    }
+    return { envelope, exitCode: 0 };
+}
+const planRequestFlags = [
+    { key: "audience", name: "--audience", kind: "string", valueName: "<role>", summary: "Audience role for the plan (default reviewer)." },
+    { key: "timebox", name: "--timebox", kind: "integer", valueName: "<seconds>", summary: "Timebox budget in seconds." },
+    { key: "maxItems", name: "--max-items", kind: "integer", valueName: "<n>", summary: "Cap the number of selected items." },
+    { key: "host", name: "--host", kind: "string", valueName: "<surface>", summary: "Host surface to plan for (default unknown)." },
+    { key: "changedPath", name: "--changed-path", kind: "string", repeatable: true, valueName: "<path>", summary: "Bias selection toward changed paths (repeatable)." },
+    { key: "generatedAt", name: "--generated-at", kind: "string", valueName: "<iso>", summary: "Override the generated-at timestamp." },
+    { key: "strict", name: "--strict", kind: "boolean", summary: "Fail when the matrix/evidence is incomplete." }
+];
+export const planShowcaseCommand = {
+    path: ["plan", "showcase"],
+    command: "plan.showcase",
+    summary: "Select a showcase presentation plan.",
+    flags: [...workspaceFlags, ...planRequestFlags],
+    handler: ({ argv, flags }) => planOutput(argv, flags, "showcase")
+};
+export const planWalkthroughCommand = {
+    path: ["plan", "walkthrough"],
+    command: "plan.walkthrough",
+    summary: "Select a walkthrough presentation plan.",
+    flags: [...workspaceFlags, ...planRequestFlags],
+    handler: ({ argv, flags }) => planOutput(argv, flags, "walkthrough")
+};
+export const planCardsCommand = {
+    path: ["plan", "cards"],
+    command: "plan.cards",
+    summary: "Render presentation cards from a saved plan file.",
+    flags: [
+        repoFlag,
+        dataRootFlag,
+        componentFlag,
+        { key: "planFile", name: "--plan-file", kind: "string", required: true, valueName: "<path>", summary: "Saved presentation plan file (inside the workspace)." },
+        jsonFlag
+    ],
+    handler: ({ argv, flags }) => {
+        const context = resolveContextOrError(argv, "plan.cards");
+        if (context.kind === "error") {
+            return { envelope: context.envelope, exitCode: context.exitCode };
+        }
+        const ctx = context.context;
+        const planFile = flags.planFile;
+        if (!planFile) {
+            return {
+                envelope: errorEnvelope("plan.cards", "cli_invalid_arguments", "Missing --plan-file."),
+                exitCode: 2
+            };
+        }
+        const contained = containedPathOrError("plan.cards", ctx.workspace_root, planFile);
+        if (contained.kind === "error") {
+            return { envelope: contained.envelope, exitCode: contained.exitCode };
+        }
+        const planPath = contained.path;
+        try {
+            const plan = loadPresentationPlanFile(planPath);
+            const data = {
+                schema_version: 1,
+                plan_id: plan.plan_id,
+                cards: plan.selected_items.map((item) => ({
+                    plan_item_id: item.plan_item_id,
+                    use_case_id: item.use_case_id,
+                    presentation_format: item.presentation_format,
+                    text: renderCard(item)
+                }))
+            };
+            return {
+                envelope: createCliResult("plan.cards", data, {
+                    ok: true,
+                    complete: true,
+                    workspaceRoot: ctx.workspace_root,
+                    dataRoot: ctx.data_root,
+                    componentId: ctx.component_id
+                }),
+                exitCode: 0
+            };
+        }
+        catch (error) {
+            const code = error instanceof Error && "code" in error ? String(error.code) : "internal_error";
+            return {
+                envelope: errorEnvelope("plan.cards", code, error instanceof Error ? error.message : String(error)),
+                exitCode: 1
+            };
+        }
+    }
+};
+export const planCommands = [planShowcaseCommand, planWalkthroughCommand, planCardsCommand];
+//# sourceMappingURL=plan.js.map

package/packages/cli/dist/commands/plan.js.map

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

package/packages/cli/dist/commands/recover.d.ts

@@ -0,0 +1,4 @@
+import type { CliCommand } from "../command/types.js";
+export declare const recoverCommand: CliCommand;
+export declare const recoverCommands: CliCommand[];
+//# sourceMappingURL=recover.d.ts.map

package/packages/cli/dist/commands/recover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/commands/recover.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,UAAU,EAA8B,MAAM,qBAAqB,CAAC;AA6GlF,eAAO,MAAM,cAAc,EAAE,UAmR5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,UAAU,EAAqB,CAAC"}