pactwright 0.0.1

package/dist/cli.js

@@ -0,0 +1,561 @@
+#!/usr/bin/env node
+import { formatProblem, PactwrightError } from "./errors.js";
+import { lifecycleNext, lifecycleStatus, } from "./lifecycle/engine.js";
+import { noExecutor, runLifecycle } from "./lifecycle/run.js";
+import { recordStage } from "./lifecycle/record.js";
+import { loadContext } from "./context.js";
+import { loadConfig } from "./config/config.js";
+import { CORE_DELIVERY_SUITE } from "./eval/core-suite.js";
+import { evalPassed, runEval } from "./eval/runner.js";
+import { addExtension, removeExtension, upgradeExtension, } from "./extension/manage.js";
+import { initProject } from "./init.js";
+import { syncProject } from "./sync.js";
+import { loadProject } from "./loader.js";
+import { resolvePack } from "./pack/resolve.js";
+import { validateProject } from "./validate.js";
+import { findProjectRoot, projectPaths } from "./project.js";
+import { runtimeVersion } from "./version.js";
+const HELP = `Usage: pactwright <command> [options]
+
+Commands:
+  init [--json]                              Create the Pactwright-owned core structure
+                                             (.pactwright, specs, .claude directories) in the
+                                             current directory and resolve the lock; existing
+                                             paths are left untouched
+  sync [--json]                              Render the Pactwright-managed .claude/ adapter
+                                             surface from config + lock (deterministic; only
+                                             files carrying the Pactwright banner are written
+                                             or removed, so user-authored files are kept)
+  validate [--json]                          Validate the Delivery Graph and typed-edge store
+  context <node-id> [--history] [--json]     Print the current core Delivery lineage of a node
+  lifecycle status [--intent <id>] [--json]  Report stage, completed stages, gates and lineage
+  lifecycle next   [--intent <id>] [--json]  Report the next permitted core Delivery action
+  lifecycle run    [--intent <id>] [--json]  Run automatic stages until a gate, completion,
+                                             a stage failure or a validation error
+  lifecycle record <stage> --file <yaml>     Record the content of a graph-marking stage
+                                             (capture-intent, approve-contract, write-brief,
+                                             prepare-evidence) after the runtime checks the
+                                             transition
+  extension add <id|package> [--json]        Enable an extension (and its dependencies),
+                                             validate the capability union and update
+                                             config and lock
+  extension remove <id> [--json]             Disable and remove an extension; blocked while
+                                             enabled extensions depend on it, and canonical
+                                             extension data is preserved
+  extension upgrade <id> [--json]            Re-resolve an extension and update the lock
+  eval [--json]                              Run the core Delivery evaluation suite against
+                                             the selected agent pack (deterministic assertions
+                                             and semantic dimensions reported separately)
+
+Options:
+  -h, --help     Show this help
+  -v, --version  Print the runtime version
+`;
+function parseOptions(args, allow = {}) {
+    let intent;
+    let file;
+    let json = false;
+    let history = false;
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--history" && allow.history === true)
+            history = true;
+        else if (arg === "--intent" && allow.intent === true) {
+            intent = args[i + 1];
+            if (intent === undefined || intent.startsWith("--"))
+                return "--intent needs an intent id";
+            i += 1;
+        }
+        else if (arg === "--file" && allow.file === true) {
+            file = args[i + 1];
+            if (file === undefined || file.startsWith("--"))
+                return "--file needs a path";
+            i += 1;
+        }
+        else if (arg.startsWith("--"))
+            return `unknown option "${arg}"`;
+        else
+            positional.push(arg);
+    }
+    return {
+        json,
+        history,
+        positional,
+        ...(intent === undefined ? {} : { intent }),
+        ...(file === undefined ? {} : { file }),
+    };
+}
+const out = (text) => void process.stdout.write(text);
+const err = (text) => void process.stderr.write(text);
+function printProblems(error, json) {
+    if (json) {
+        out(`${JSON.stringify({ problems: error.problems }, null, 2)}\n`);
+        return;
+    }
+    out("Validation problems:\n");
+    for (const problem of error.problems)
+        out(`  - ${formatProblem(problem)}\n`);
+}
+function formatStatus(entry) {
+    const lines = [];
+    lines.push(entry.intent === undefined ? "No active lineage" : `Intent: ${entry.intent}`);
+    lines.push(`  state: ${entry.state}`);
+    lines.push(`  current stage: ${entry.currentStage ?? "none (core Delivery lifecycle complete or terminal)"}`);
+    lines.push(`  completed stages: ${entry.completed.length === 0 ? "none" : entry.completed.join(", ")}`);
+    if (entry.blockedStage !== undefined) {
+        lines.push(`  blocked stage: ${entry.blockedStage} (required actor: ${entry.requiredActor})`);
+    }
+    if (entry.lineage !== undefined) {
+        const { decision, contract, brief, evidence } = entry.lineage;
+        const chain = [entry.lineage.intent, decision, contract, brief, evidence]
+            .filter((node) => node !== undefined)
+            .map((node) => node.id);
+        lines.push(`  current lineage: ${chain.join(" → ")}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatNext(action) {
+    const who = action.intent === undefined ? "No active lineage" : `Intent: ${action.intent}`;
+    const stage = action.stage === undefined
+        ? "next stage: none"
+        : `next stage: ${action.stage} (${action.execution}${action.actor ? `, actor ${action.actor}` : ""}${action.gate ? ", human gate" : ""})`;
+    return `${who}\n  ${stage}\n  ${action.reason}\n`;
+}
+function formatRun(result) {
+    const lines = [];
+    lines.push(result.intent === undefined ? "No active lineage" : `Intent: ${result.intent}`);
+    lines.push(`  executed: ${result.executed.length === 0 ? "none" : result.executed.join(", ")}`);
+    switch (result.stop) {
+        case "completed":
+            lines.push("  stopped: lifecycle complete or no automatic stage to run");
+            break;
+        case "human-gate":
+            lines.push(`  stopped: human gate at ${result.stage} (required actor: ${result.requiredActor})`);
+            break;
+        case "stage-failed":
+            lines.push(`  stopped: stage ${result.stage} failed: ${result.message}`);
+            break;
+        case "validation-error":
+            lines.push(`  stopped: validation error: ${result.message}`);
+            break;
+    }
+    return `${lines.join("\n")}\n`;
+}
+function record(args) {
+    const options = parseOptions(args, { file: true });
+    if (typeof options === "string" ||
+        options.positional.length !== 1 ||
+        options.file === undefined) {
+        const why = typeof options === "string"
+            ? options
+            : options.positional.length === 0
+                ? "record needs a <stage>"
+                : options.positional.length > 1
+                    ? `unexpected argument "${options.positional[1]}"`
+                    : "record needs --file <yaml>";
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    try {
+        const root = findProjectRoot();
+        const result = recordStage(root, options.positional[0], options.file);
+        if (options.json) {
+            const created = result.created.map((node) => ({ id: node.id, type: node.type }));
+            out(`${JSON.stringify({ stage: result.stage, created }, null, 2)}\n`);
+        }
+        else {
+            out(result.created.map((node) => `created ${node.type} ${node.id}\n`).join(""));
+        }
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        printProblems(error, options.json);
+        return 1;
+    }
+}
+async function lifecycle(sub, args) {
+    if (sub === "record")
+        return record(args);
+    const options = parseOptions(args, { intent: true });
+    if (typeof options === "string" || options.positional.length > 0) {
+        const why = typeof options === "string" ? options : `unexpected argument "${options.positional[0]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    if (sub === "run") {
+        // `runLifecycle` loads the project itself and reports load problems as a
+        // validation-error stop; only the root is resolved here.
+        let root;
+        try {
+            root = findProjectRoot();
+        }
+        catch (error) {
+            if (!(error instanceof PactwrightError))
+                throw error;
+            printProblems(error, options.json);
+            return 1;
+        }
+        const results = await runLifecycle({
+            root,
+            execute: noExecutor,
+            ...(options.intent === undefined ? {} : { intentId: options.intent }),
+        });
+        out(options.json ? `${JSON.stringify(results, null, 2)}\n` : results.map(formatRun).join(""));
+        return results.some((r) => r.stop === "stage-failed" || r.stop === "validation-error") ? 1 : 0;
+    }
+    if (sub !== "status" && sub !== "next") {
+        err(`pactwright: unknown lifecycle command "${sub ?? ""}"\n\n${HELP}`);
+        return 1;
+    }
+    try {
+        const project = loadProject();
+        if (sub === "status") {
+            const status = lifecycleStatus(project, options.intent);
+            out(options.json
+                ? `${JSON.stringify(status, null, 2)}\n`
+                : `${status.lineages.map(formatStatus).join("")}Validation problems: none\n`);
+        }
+        else {
+            const actions = lifecycleNext(project, options.intent);
+            out(options.json ? `${JSON.stringify(actions, null, 2)}\n` : actions.map(formatNext).join(""));
+        }
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        printProblems(error, options.json);
+        return 1;
+    }
+}
+function initCommand(args) {
+    const options = parseOptions(args);
+    if (typeof options === "string" || options.positional.length > 0) {
+        const why = typeof options === "string" ? options : `unexpected argument "${options.positional[0]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    // Init is the one command that must not search for an enclosing project:
+    // it creates the project in the current directory.
+    const report = initProject();
+    if (options.json) {
+        out(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        for (const entry of report.entries) {
+            out(entry.action === "created" ? `created ${entry.path}\n` : `skipped ${entry.path} (exists)\n`);
+        }
+        if (report.problems.length > 0) {
+            out("Validation problems:\n");
+            for (const problem of report.problems)
+                out(`  - ${formatProblem(problem)}\n`);
+        }
+    }
+    return report.ok ? 0 : 1;
+}
+function formatExtensionReport(report) {
+    const lines = [];
+    for (const change of report.changes) {
+        const version = change.action === "upgraded" && change.previousVersion !== undefined
+            ? ` ${change.previousVersion} → ${change.version ?? "?"}`
+            : change.version !== undefined
+                ? ` ${change.version}`
+                : "";
+        lines.push(`${change.action} ${change.id}${version}`);
+    }
+    for (const profile of report.githubProfiles) {
+        lines.push(`github profile "${profile}" requires provisioning (not performed: deferred)`);
+    }
+    if (report.preserved.length > 0) {
+        lines.push("preserved canonical extension data (delete separately if unwanted):");
+        for (const path of report.preserved)
+            lines.push(`  - ${path}`);
+    }
+    return lines.map((line) => `${line}\n`).join("");
+}
+const EXTENSION_OPERATIONS = {
+    add: addExtension,
+    remove: removeExtension,
+    upgrade: upgradeExtension,
+};
+function extensionOperation(sub) {
+    // `Object.hasOwn`, not a bare lookup: `sub` is user input, and an inherited
+    // member like "constructor" would otherwise pass an `=== undefined` guard
+    // and be called as if it were an extension operation.
+    return sub !== undefined && Object.hasOwn(EXTENSION_OPERATIONS, sub)
+        ? EXTENSION_OPERATIONS[sub]
+        : undefined;
+}
+function extensionCommand(sub, args) {
+    // The verb is checked before the arguments, so an unknown verb is named as
+    // such rather than being reported as a missing extension id.
+    const operation = extensionOperation(sub);
+    if (operation === undefined) {
+        err(`pactwright: unknown extension command "${sub ?? ""}"\n\n${HELP}`);
+        return 1;
+    }
+    const options = parseOptions(args);
+    if (typeof options === "string" || options.positional.length !== 1) {
+        const why = typeof options === "string"
+            ? options
+            : options.positional.length === 0
+                ? `extension ${sub} needs an extension id`
+                : `unexpected argument "${options.positional[1]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    let root;
+    try {
+        root = findProjectRoot();
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        printProblems(error, options.json);
+        return 1;
+    }
+    const report = operation(root, options.positional[0]);
+    if (options.json) {
+        out(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        out(formatExtensionReport(report));
+        if (report.problems.length > 0) {
+            // A successful command can still carry an advisory, so the heading
+            // follows the outcome rather than the presence of problems.
+            out(report.ok ? "Notes:\n" : "Validation problems:\n");
+            for (const problem of report.problems)
+                out(`  - ${formatProblem(problem)}\n`);
+        }
+    }
+    return report.ok ? 0 : 1;
+}
+function syncCommand(args) {
+    const options = parseOptions(args);
+    if (typeof options === "string" || options.positional.length > 0) {
+        const why = typeof options === "string" ? options : `unexpected argument "${options.positional[0]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    let root;
+    try {
+        root = findProjectRoot();
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        printProblems(error, options.json);
+        return 1;
+    }
+    const report = syncProject(root);
+    if (options.json) {
+        out(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        for (const path of report.changed)
+            out(`wrote ${path}\n`);
+        for (const path of report.unchanged)
+            out(`unchanged ${path}\n`);
+        for (const path of report.removed)
+            out(`removed ${path}\n`);
+        for (const path of report.kept)
+            out(`kept ${path} (not pactwright-generated)\n`);
+        for (const path of report.conflicts)
+            out(`conflict ${path} (not pactwright-generated)\n`);
+        if (report.problems.length > 0) {
+            out("Validation problems:\n");
+            for (const problem of report.problems)
+                out(`  - ${formatProblem(problem)}\n`);
+        }
+    }
+    return report.ok ? 0 : 1;
+}
+function validate(args) {
+    const options = parseOptions(args);
+    if (typeof options === "string" || options.positional.length > 0) {
+        const why = typeof options === "string" ? options : `unexpected argument "${options.positional[0]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    const report = validateProject();
+    if (options.json) {
+        out(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else if (report.ok) {
+        const s = report.summary;
+        out(`Valid: ${s.nodes} nodes, ${s.edges} edges, ${s.lineages} lineages (revision ${s.revision})\n`);
+    }
+    else {
+        out("Validation problems:\n");
+        for (const problem of report.problems)
+            out(`  - ${formatProblem(problem)}\n`);
+    }
+    return report.ok ? 0 : 1;
+}
+function formatRecord(node, extra = []) {
+    const lines = [`## ${node.type} ${node.id}`, `title: ${node.title}`, `created: ${node.created}`];
+    if (node.type === "decision") {
+        lines.push(`decided_by: ${String(node.frontmatter["decided_by"])}`);
+        lines.push(`outcome: ${String(node.frontmatter["outcome"])}`);
+    }
+    lines.push(...extra, "", node.body, "");
+    return `${lines.join("\n")}\n`;
+}
+function formatHistory(record) {
+    const by = record.supersededBy.length === 0 ? "none" : record.supersededBy.join(", ");
+    return formatRecord(record.node, [`superseded by: ${by}`]);
+}
+function formatContext(context) {
+    const parts = [`# Delivery context for ${context.requested}`, ""];
+    parts.push(`intent: ${context.intent}`, `state: ${context.state}`);
+    if (!context.requestedIsCurrent) {
+        parts.push(`note: ${context.requested} is superseded; the current lineage is shown`);
+    }
+    parts.push("", ...context.lineage.map((node) => formatRecord(node)));
+    if (context.history !== undefined) {
+        parts.push("# History (superseded records)", "");
+        parts.push(context.history.length === 0 ? "none\n" : context.history.map(formatHistory).join(""));
+    }
+    return `${parts.join("\n")}`;
+}
+function formatEvalCase(entry) {
+    const lines = [];
+    const agent = entry.agent === undefined ? "" : ` (agent: ${entry.agent})`;
+    lines.push(`${entry.id} — ${entry.title}`);
+    lines.push(`  capability: ${entry.capability}${agent}`);
+    if (entry.error !== undefined)
+        lines.push(`  error: ${entry.error}`);
+    if (entry.deterministic.length > 0) {
+        lines.push("  deterministic:");
+        for (const assertion of entry.deterministic) {
+            lines.push(`    ${assertion.passed ? "pass" : "FAIL"}  ${assertion.id}: ${assertion.detail}`);
+        }
+    }
+    if (entry.semantic.length > 0) {
+        lines.push("  semantic (requires judgement; reported separately, never auto-scored):");
+        for (const dimension of entry.semantic) {
+            lines.push(dimension.judged
+                ? `    judged    ${dimension.id}: ${dimension.verdict}${dimension.rationale === undefined ? "" : ` — ${dimension.rationale}`}`
+                : `    unjudged  ${dimension.id}: ${dimension.reason}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function formatEvalReport(report) {
+    const assertions = report.cases.flatMap((entry) => entry.deterministic);
+    const failed = assertions.filter((assertion) => !assertion.passed).length;
+    const dimensions = report.cases.flatMap((entry) => entry.semantic);
+    const judged = dimensions.filter((dimension) => dimension.judged).length;
+    const errors = report.cases.filter((entry) => entry.error !== undefined).length;
+    return [
+        `Evaluating ${report.pack.name}@${report.pack.version} (runtime ${report.runtime}, suite ${report.suite})`,
+        "",
+        ...report.cases.map(formatEvalCase),
+        `Deterministic assertions: ${assertions.length - failed} passed, ${failed} failed${errors === 0 ? "" : `; ${errors} case(s) not evaluated`}.`,
+        `Semantic dimensions: ${judged} judged, ${dimensions.length - judged} unjudged. No aggregate quality score is calculated.`,
+        "",
+    ].join("\n");
+}
+/**
+ * `pactwright eval` runs inside or outside a project: inside one it
+ * evaluates the configured pack; outside it evaluates the default
+ * `@pactwright/standard` pack, since evaluation is independent from any
+ * project's Delivery (Distribution §16).
+ */
+async function evalCommand(args) {
+    const options = parseOptions(args);
+    if (typeof options === "string" || options.positional.length > 0) {
+        const why = typeof options === "string" ? options : `unexpected argument "${options.positional[0]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    let root;
+    let config;
+    try {
+        root = findProjectRoot();
+        const loaded = loadConfig(projectPaths(root).config);
+        if (loaded.value === undefined) {
+            printProblems(PactwrightError.fromProblems("invalid-config", loaded.problems), options.json);
+            return 1;
+        }
+        config = loaded.value;
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        root = process.cwd();
+        config = {
+            version: 1,
+            agentPack: { source: "@pactwright/standard" },
+            adapter: { type: "claude-code" },
+            extensions: {},
+            github: { enabled: false },
+        };
+    }
+    const resolved = resolvePack({ root, config });
+    if (resolved.value === undefined) {
+        printProblems(PactwrightError.fromProblems("pack-unresolved", resolved.problems), options.json);
+        return 1;
+    }
+    const report = await runEval({ pack: resolved.value, suite: CORE_DELIVERY_SUITE });
+    out(options.json ? `${JSON.stringify(report, null, 2)}\n` : formatEvalReport(report));
+    return evalPassed(report) ? 0 : 1;
+}
+function contextCommand(args) {
+    const options = parseOptions(args, { history: true });
+    if (typeof options === "string" || options.positional.length !== 1) {
+        const why = typeof options === "string"
+            ? options
+            : options.positional.length === 0
+                ? "context needs a <node-id>"
+                : `unexpected argument "${options.positional[1]}"`;
+        err(`pactwright: ${why}\n\n${HELP}`);
+        return 1;
+    }
+    try {
+        const context = loadContext(loadProject(), options.positional[0], {
+            history: options.history,
+        });
+        out(options.json ? `${JSON.stringify(context, null, 2)}\n` : formatContext(context));
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof PactwrightError))
+            throw error;
+        printProblems(error, options.json);
+        return 1;
+    }
+}
+export async function main(argv) {
+    const [first, ...rest] = argv;
+    if (first === undefined || first === "--help" || first === "-h" || first === "help") {
+        out(HELP);
+        return first === undefined ? 1 : 0;
+    }
+    if (first === "--version" || first === "-v" || first === "version") {
+        out(`${runtimeVersion()}\n`);
+        return 0;
+    }
+    if (first === "init")
+        return initCommand(rest);
+    if (first === "sync")
+        return syncCommand(rest);
+    if (first === "extension")
+        return extensionCommand(rest[0], rest.slice(1));
+    if (first === "lifecycle")
+        return lifecycle(rest[0], rest.slice(1));
+    if (first === "validate")
+        return validate(rest);
+    if (first === "context")
+        return contextCommand(rest);
+    if (first === "eval")
+        return evalCommand(rest);
+    err(`pactwright: unknown command "${first}"\n\n${HELP}`);
+    return 1;
+}
+process.exitCode = await main(process.argv.slice(2));

package/dist/config/config.d.ts

@@ -0,0 +1,55 @@
+import type { Problem } from "../errors.js";
+/** One configured extension: desired state only (Distribution §4). */
+export interface ConfigExtension {
+    /** A disabled extension keeps its graph types registered but contributes no behaviour. */
+    readonly enabled: boolean;
+    /** Package name or project-relative path the extension resolves from. */
+    readonly source: string;
+}
+/** `.pactwright/config.yml` — desired installation state (Distribution §3). */
+export interface PactwrightConfig {
+    readonly version: 1;
+    readonly agentPack: {
+        readonly source: string;
+        readonly version?: string;
+    };
+    readonly adapter: {
+        readonly type: "claude-code";
+    };
+    /** Extension id → desired extension state (Distribution §4). */
+    readonly extensions: Readonly<Record<string, ConfigExtension>>;
+    readonly github: {
+        readonly enabled: boolean;
+    };
+}
+export declare const CONFIG_VERSION = 1;
+export declare const ADAPTER_TYPES: readonly ["claude-code"];
+export interface ParseResult<T> {
+    readonly value: T | undefined;
+    readonly problems: readonly Problem[];
+}
+export declare function parseConfig(raw: unknown, path: string): ParseResult<PactwrightConfig>;
+export declare function loadConfig(path: string): ParseResult<PactwrightConfig>;
+/**
+ * Serialises a configuration in the canonical `.pactwright/config.yml`
+ * shape — the exact bytes `pactwright init` writes for the default state.
+ * This is the fallback whenever the previous file cannot be edited in place;
+ * it re-emits from parsed values, so comments and incidental layout are not
+ * carried over. `rewriteConfig` is what the commands normally use.
+ */
+export declare function serialiseConfig(config: PactwrightConfig): string;
+/**
+ * The previous configuration text with only its `extensions:` block replaced
+ * (Distribution §3). `extension add` and `remove` change nothing else, so
+ * every other byte — comments, key order, spacing a team chose — survives.
+ *
+ * Falls back to a full `serialiseConfig` rewrite whenever the edit cannot be
+ * made confidently, including when the spliced result does not parse back to
+ * the intended configuration. The fallback is today's behaviour, so the worst
+ * case is losing comments rather than corrupting the file — which matters
+ * because `removeExtension` never rolls its write back.
+ *
+ * Comments *inside* the extensions block are part of the replaced region and
+ * are not preserved.
+ */
+export declare function rewriteConfig(previous: string, config: PactwrightConfig): string;