@interf/compiler 0.16.0 → 0.21.0

package/dist/cli/commands/method.js

@@ -2,6 +2,7 @@
  * `interf method` — manage methods on the connected instance.
  *
  *   interf method ls                          # list methods (instance-wide)
+ *   interf method show <method-id>            # show a Build Plan summary
  *   interf method install <path>              # install a method package
  *   interf method draft <prep-id>             # start a method-authoring run
  *   interf method improve <prep-id>           # start a method-improvement run
@@ -9,6 +10,10 @@
 import chalk from "chalk";
 import { resolve } from "node:path";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection } from "../../packages/engine/connection-config.js";
+import { methodResourcePath, preparationResourcePath, preparationSubresourcePath, } from "../../packages/engine/routes.js";
+import { MethodAuthoringArtifactRequirementSchema, } from "../../packages/engine/lib/schema.js";
+import { artifactRequirementsFromRequestedArtifacts, formatRequestedArtifactsForPrompt, } from "../../packages/engine/requested-artifacts.js";
+import { slugify } from "../../packages/contracts/utils/naming.js";
 function resolveConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -39,6 +44,220 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+const MethodAuthoringArtifactRequirementsCliSchema = MethodAuthoringArtifactRequirementSchema.array();
+function parseJsonOption(label, value, parse) {
+    if (!value)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid JSON for ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+    try {
+        return parse(parsed);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+function buildPreparationReviewUrl(url, prepId) {
+    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=build-plan`;
+}
+function buildRunUrl(url, prepId, runId) {
+    if (!runId)
+        return null;
+    return `${url}/?section=preparations&preparation=${encodeURIComponent(prepId)}&preparationTab=runs&run=${encodeURIComponent(runId)}`;
+}
+function defaultMethodIdForPreparation(prepId) {
+    return slugify(`${prepId}-build-plan`) || "build-plan";
+}
+function labelFromMethodId(methodId) {
+    const label = methodId
+        .split("-")
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(" ");
+    return label || "Build Plan";
+}
+function renderMethodSummary(method) {
+    const id = method.method_id ?? method.id ?? "(?)";
+    console.log();
+    console.log(`  ${chalk.bold(method.label ?? id)}`);
+    console.log(chalk.dim(`    id: ${id}`));
+    if (method.hint)
+        console.log(chalk.dim(`    hint: ${method.hint}`));
+    if (method.purpose?.task_hint)
+        console.log(chalk.dim(`    purpose: ${method.purpose.task_hint}`));
+    if (method.source_kind)
+        console.log(chalk.dim(`    source: ${method.source_kind}`));
+    const artifacts = method.artifacts ?? [];
+    if (artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        for (const artifact of artifacts) {
+            const shape = artifact.shape?.path
+                ? chalk.dim(` -> ${artifact.shape.path}`)
+                : "";
+            console.log(`      ${chalk.bold(artifact.id)}${shape}`);
+            console.log(chalk.dim(`        ${artifact.description}`));
+            const checks = artifact.checks ?? [];
+            for (const check of checks.slice(0, 3)) {
+                const required = check.required === false ? "soft" : "required";
+                console.log(chalk.dim(`        - ${check.description ?? check.kind} (${required})`));
+            }
+        }
+    }
+    const stages = method.stages ?? [];
+    if (stages.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Stages"));
+        for (const stage of stages) {
+            const role = stage.role ? chalk.dim(` [${stage.role}]`) : "";
+            console.log(`      ${chalk.bold(stage.label)}${role}`);
+            if (stage.description)
+                console.log(chalk.dim(`        ${stage.description}`));
+            const reads = stage.reads?.length ? stage.reads.join(", ") : "source";
+            const writes = stage.writes?.length ? stage.writes.join(", ") : "(none declared)";
+            console.log(chalk.dim(`        reads: ${reads}`));
+            console.log(chalk.dim(`        writes: ${writes}`));
+        }
+    }
+    if (method.active_for_preparations?.length) {
+        console.log();
+        console.log(chalk.dim(`    used by: ${method.active_for_preparations.join(", ")}`));
+    }
+    console.log();
+    console.log(chalk.dim("  Run with --json for the raw Build Plan record."));
+    console.log();
+}
+function preparationChecks(preparation) {
+    return asArray(preparation.checks).length
+        ? asArray(preparation.checks)
+        : asArray(preparation.preparation?.checks);
+}
+function preparationRequestedArtifacts(preparation) {
+    return preparation.requested_artifacts?.length
+        ? preparation.requested_artifacts
+        : preparation.preparation?.requested_artifacts ?? [];
+}
+function preparationSourceProfile(preparation) {
+    return preparation.source_profile ?? preparation.preparation?.source_profile ?? null;
+}
+function selectedMethodId(preparation) {
+    return preparation.method_id ?? preparation.preparation?.method ?? null;
+}
+function sourceFolderPathFromPreparation(preparation, sourceFiles) {
+    if (preparation.source?.kind === "local-folder" && preparation.source.locator)
+        return preparation.source.locator;
+    if (sourceFiles?.source_files?.[0]?.source_folder_path)
+        return sourceFiles.source_files[0].source_folder_path;
+    return preparation.source_path ?? null;
+}
+function buildTaskPrompt(args, preparation, prepId, mode) {
+    const about = (preparation.about ?? preparation.preparation?.about)?.trim();
+    const requestedArtifacts = formatRequestedArtifactsForPrompt(preparationRequestedArtifacts(preparation));
+    const sections = [
+        `${mode === "improve" ? "Improve" : "Draft"} a Build Plan for Preparation "${prepId}".`,
+        args.task?.trim() ? `Agent job:\n${args.task.trim()}` : null,
+        about ? `Preparation context:\n${about}` : null,
+        requestedArtifacts ? `Requested Artifacts saved on the Preparation:\n${requestedArtifacts}` : null,
+        args.artifacts?.trim() ? `Additional Artifact notes:\n${args.artifacts.trim()}` : null,
+        args.readyWhen?.trim() ? `Ready when:\n${args.readyWhen.trim()}` : null,
+        "Return a Method package that declares the verifiable Artifacts, the stages that build them, and the checks that prove the portable context is ready for agent work.",
+    ].filter((section) => Boolean(section));
+    return sections.join("\n\n");
+}
+async function readPreparationContext(url, token, prepId) {
+    const fetched = await callJson(`${url}${preparationResourcePath(prepId)}`, token);
+    if (fetched.status !== 200 || !fetched.body) {
+        console.error(chalk.red(`Failed to read Preparation ${prepId} (HTTP ${fetched.status}).`));
+        if (fetched.raw)
+            console.error(fetched.raw);
+        process.exit(1);
+    }
+    let sourceFiles = null;
+    const sourcePath = sourceFolderPathFromPreparation(fetched.body, sourceFiles);
+    if (!sourcePath) {
+        const listed = await callJson(`${url}${preparationSubresourcePath(prepId, "sourceFiles")}`, token);
+        if (listed.status === 200)
+            sourceFiles = listed.body;
+    }
+    const sourceFolderPath = sourceFolderPathFromPreparation(fetched.body, sourceFiles);
+    if (!sourceFolderPath) {
+        console.error(chalk.red(`Preparation ${prepId} has no readable local Source binding.`));
+        process.exit(1);
+    }
+    return {
+        preparation: fetched.body,
+        sourceFolderPath,
+        checks: preparationChecks(fetched.body),
+    };
+}
+async function startBuildPlanRun(args, mode) {
+    const { url, token } = resolveConnection(args);
+    const { preparation, sourceFolderPath, checks } = await readPreparationContext(url, token, args.prepId);
+    const existingMethod = selectedMethodId(preparation);
+    const methodId = args.method ?? (mode === "improve" ? existingMethod : defaultMethodIdForPreparation(args.prepId));
+    const requestedArtifacts = preparationRequestedArtifacts(preparation);
+    const explicitArtifactRequirements = parseJsonOption("--artifact-requirements-json", args.artifactRequirementsJson, (input) => MethodAuthoringArtifactRequirementsCliSchema.parse(input));
+    const artifactRequirements = explicitArtifactRequirements
+        ?? artifactRequirementsFromRequestedArtifacts(requestedArtifacts);
+    if (!methodId) {
+        console.error(chalk.red(`Preparation ${args.prepId} has no selected Build Plan to improve.`));
+        console.error(chalk.dim(`Draft one first: interf method draft ${args.prepId} --task "..."`));
+        process.exit(1);
+    }
+    const body = {
+        preparation: args.prepId,
+        source_folder_path: sourceFolderPath,
+        ...(args.baseMethod ? { base_method_id: args.baseMethod } : {}),
+        ...(args.referenceMethod ? { reference_method_id: args.referenceMethod } : {}),
+        ...(mode === "improve" && !args.referenceMethod && existingMethod ? { reference_method_id: existingMethod } : {}),
+        method_id: methodId,
+        label: args.label ?? labelFromMethodId(methodId),
+        hint: args.hint ?? `Build Plan for Preparation ${args.prepId}.`,
+        task_prompt: buildTaskPrompt(args, preparation, args.prepId, mode),
+        checks,
+        requested_artifacts: requestedArtifacts,
+        source_profile: preparationSourceProfile(preparation),
+        artifact_requirements: artifactRequirements,
+    };
+    const endpoint = mode === "improve" ? "methodImprovementRuns" : "methodAuthoringRuns";
+    const { status, body: run, raw } = await callJson(`${url}${preparationSubresourcePath(args.prepId, endpoint)}`, token, { method: "POST", body: JSON.stringify(body) });
+    if (status !== 202 && status !== 201 && status !== 200) {
+        console.error(chalk.red(`Failed to start Build Plan ${mode} run (HTTP ${status}).`));
+        if (raw)
+            console.error(raw);
+        process.exit(1);
+    }
+    const runUrl = buildRunUrl(url, args.prepId, run?.run_id);
+    const reviewUrl = buildPreparationReviewUrl(url, args.prepId);
+    if (args.json) {
+        console.log(JSON.stringify({
+            run_id: run?.run_id ?? null,
+            status: run?.status ?? null,
+            preparation: args.prepId,
+            method_id: methodId,
+            run_url: runUrl,
+            review_url: reviewUrl,
+        }, null, 2));
+        return;
+    }
+    console.log(chalk.green(`Build Plan ${mode} run ${chalk.bold(run?.run_id ?? "(?)")} started.`));
+    console.log(chalk.dim(`  Build Plan: ${methodId}`));
+    if (runUrl)
+        console.log(chalk.dim(`  watch: ${runUrl}`));
+    console.log(chalk.dim(`  review after it finishes: ${reviewUrl}`));
+}
 export const methodCommand = {
     command: "method <subcommand>",
     describe: "Manage methods on the connected instance",
@@ -83,27 +302,54 @@ export const methodCommand = {
         }
         console.log(chalk.green(`Installed method from ${absolute}.`));
     })
-        .command("draft <prep-id>", "Start a method-authoring run for a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        .command("show <method-id>", "Show a Build Plan / Method package", (y) => y
+        .positional("method-id", { type: "string", demandOption: true, describe: "Build Plan / Method package id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/method-authoring-runs`, token, { method: "POST", body: JSON.stringify({}) });
-        if (status !== 201 && status !== 200) {
-            console.error(chalk.red(`Failed to start method-authoring run (HTTP ${status}).`));
+        const { status, body, raw } = await callJson(`${url}${methodResourcePath(args.methodId)}`, token);
+        if (status !== 200 || !body) {
+            console.error(chalk.red(`Failed to read Build Plan ${args.methodId} (HTTP ${status}).`));
             if (raw)
                 console.error(raw);
             process.exit(1);
         }
-        console.log(chalk.green(`Method-authoring run ${chalk.bold(body?.run_id ?? "(?)")} started.`));
-    })
-        .command("improve <prep-id>", "Start a method-improvement run for a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
-        const { url, token } = resolveConnection(args);
-        const { status, body, raw } = await callJson(`${url}/v1/preparations/${encodeURIComponent(args.prepId)}/method-improvement-runs`, token, { method: "POST", body: JSON.stringify({}) });
-        if (status !== 201 && status !== 200) {
-            console.error(chalk.red(`Failed to start method-improvement run (HTTP ${status}).`));
-            if (raw)
-                console.error(raw);
-            process.exit(1);
+        if (args.json) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
         }
-        console.log(chalk.green(`Method-improvement run ${chalk.bold(body?.run_id ?? "(?)")} started.`));
+        renderMethodSummary(body);
+    })
+        .command("draft <prep-id>", "Start a Build Plan draft run for a preparation", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("task", { type: "string", describe: "Agent job this Build Plan should support" })
+        .option("artifacts", { type: "string", describe: "Requested Artifacts and why the agent needs them" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("ready-when", { type: "string", describe: "Proof or readiness expectations for the Build Plan" })
+        .option("method", { type: "string", describe: "Build Plan / Method id to write" })
+        .option("label", { type: "string", describe: "Human-readable Build Plan label" })
+        .option("hint", { type: "string", describe: "Short Build Plan hint for reviewers" })
+        .option("base-method", { type: "string", describe: "Existing Method id to use as a starting point" })
+        .option("reference-method", { type: "string", describe: "Existing Method id to reference while drafting" })
+        .option("json", { type: "boolean", default: false, describe: "Print machine-readable run metadata" }), async (args) => {
+        await startBuildPlanRun(args, "draft");
+    })
+        .command("improve <prep-id>", "Start a Build Plan improvement run for a preparation", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("task", { type: "string", describe: "Change request for the selected Build Plan" })
+        .option("artifacts", { type: "string", describe: "Requested Artifact changes and why they matter" })
+        .option("artifact-requirements-json", { type: "string", describe: "JSON array of exact Artifact output requirements for the Build Plan" })
+        .option("ready-when", { type: "string", describe: "Proof or readiness expectations to add or change" })
+        .option("method", { type: "string", describe: "Build Plan / Method id to update" })
+        .option("label", { type: "string", describe: "Human-readable Build Plan label" })
+        .option("hint", { type: "string", describe: "Short Build Plan hint for reviewers" })
+        .option("base-method", { type: "string", describe: "Existing Method id to use as a starting point" })
+        .option("reference-method", { type: "string", describe: "Existing Method id to reference while improving" })
+        .option("json", { type: "boolean", default: false, describe: "Print machine-readable run metadata" }), async (args) => {
+        await startBuildPlanRun(args, "improve");
     })
         .demandCommand(1)
         .strict(),

package/dist/cli/commands/prep.js

@@ -2,7 +2,7 @@
  * `interf prep` — preparation CRUD against a connected instance.
  *
  *   interf prep ls
- *   interf prep create <id> --source <path> --method <id> [--about <text>]
+ *   interf prep create <id> --source <path> [--method <id>] [--about <text>]
  *   interf prep show <id>
  *   interf prep rm <id>
  *
@@ -14,6 +14,8 @@ import { resolve } from "node:path";
 import chalk from "chalk";
 import { CONNECT_OR_ERROR_HINT, readActiveConnection, } from "../../packages/engine/connection-config.js";
 import { preparationResourcePath } from "../../packages/engine/routes.js";
+import { requestedArtifactCheckLabel } from "../../packages/engine/requested-artifacts.js";
+import { RequestedArtifactSchema, SourceProfileSchema, } from "../../packages/project/lib/schema.js";
 function requireConnection(args) {
     const conn = readActiveConnection({
         urlOverride: args.url,
@@ -45,6 +47,87 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+const RequestedArtifactsCliSchema = RequestedArtifactSchema.array();
+function parseJsonOption(label, value, parse) {
+    if (!value)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid JSON for ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+    try {
+        return parse(parsed);
+    }
+    catch (error) {
+        console.error(chalk.red(`Invalid ${label}.`));
+        console.error(chalk.dim(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+function statusColor(status) {
+    if (status === "ready")
+        return chalk.green;
+    if (status === "failed")
+        return chalk.red;
+    if (status === "skipped")
+        return chalk.dim;
+    return chalk.yellow;
+}
+function renderPreparationSummary(prep) {
+    console.log();
+    console.log(`  ${chalk.bold(prep.name)}`);
+    console.log(chalk.dim(`    Build Plan: ${prep.method_id ?? "(not selected)"}`));
+    if (prep.source_path)
+        console.log(chalk.dim(`    source:  ${prep.source_path}`));
+    if (prep.portable_context_path) {
+        console.log(chalk.dim(`    output:  ${prep.portable_context_path}`));
+    }
+    if (prep.readiness?.status) {
+        const aggColor = prep.readiness.ready ? chalk.green : chalk.yellow;
+        console.log(`    readiness: ${aggColor(prep.readiness.status)}${prep.readiness.summary ? chalk.dim(` (${prep.readiness.summary})`) : ""}`);
+    }
+    if (prep.artifacts && prep.artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        const idWidth = Math.max(...prep.artifacts.map((entry) => entry.artifact_id.length), 8);
+        for (const artifact of prep.artifacts) {
+            const colored = statusColor(artifact.status)(artifact.status);
+            const stages = artifact.built_by_stages && artifact.built_by_stages.length > 0
+                ? chalk.dim(` ← ${artifact.built_by_stages.join(", ")}`)
+                : "";
+            console.log(`      ${artifact.artifact_id.padEnd(idWidth)}  ${colored}${stages}`);
+        }
+    }
+    if (prep.requested_artifacts && prep.requested_artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Requested Artifacts"));
+        for (const artifact of prep.requested_artifacts) {
+            console.log(`      ${chalk.bold(artifact.title)}`);
+            if (artifact.purpose ?? artifact.description) {
+                console.log(chalk.dim(`        ${artifact.purpose ?? artifact.description}`));
+            }
+            const checks = artifact.checks ?? [];
+            for (const check of checks.slice(0, 4)) {
+                console.log(chalk.dim(`        - ${requestedArtifactCheckLabel(check)}`));
+            }
+        }
+    }
+    if (prep.latest_compile_run_id) {
+        console.log();
+        console.log(chalk.dim(`    latest compile run: ${prep.latest_compile_run_id}`));
+    }
+    if (prep.latest_test_run_id) {
+        console.log(chalk.dim(`    latest check run:   ${prep.latest_test_run_id}`));
+    }
+    console.log();
+    console.log(chalk.dim(`  Run with --json for the raw resource record.`));
+    console.log();
+}
 export const prepCommand = {
     command: "prep <subcommand>",
     describe: "Manage preparations on the connected instance",
@@ -62,7 +145,7 @@ export const prepCommand = {
         }
         const preparations = body.preparations ?? [];
         if (preparations.length === 0) {
-            console.log(chalk.dim("  No preparations yet. Create one with `interf prep create <id> --source <path> --method <method-id>`."));
+            console.log(chalk.dim("  No preparations yet. Create one with `interf prep create <id> --source <path>`."));
             return;
         }
         console.log();
@@ -70,26 +153,34 @@ export const prepCommand = {
         console.log();
         for (const prep of preparations) {
             const sourceLabel = prep.source?.locator ?? prep.source_path ?? "(no source)";
-            const method = prep.method_id ?? "(no method)";
+            const method = prep.method_id ?? "(no Build Plan)";
             const readiness = prep.readiness?.status ?? "—";
+            const requested = prep.requested_artifacts?.length ?? 0;
             console.log(`  ${prep.id}`);
             console.log(chalk.dim(`    source: ${sourceLabel}`));
-            console.log(chalk.dim(`    method: ${method}`));
+            console.log(chalk.dim(`    Build Plan: ${method}`));
+            console.log(chalk.dim(`    requested Artifacts: ${requested}`));
             console.log(chalk.dim(`    readiness: ${readiness}`));
         }
     })
-        .command("create <prep-id>", "Create a preparation (method binding optional — set later if you don't have one yet)", (y) => y
+        .command("create <prep-id>", "Create a Preparation (Build Plan optional — select or draft it later)", (y) => y
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id (lowercase, dash-separated)" })
-        .option("source", { type: "string", demandOption: true, describe: "Path to the Source Folder" })
-        .option("method", { type: "string", describe: "Method id (e.g. interf-default). Optional — bind later via `interf prep set-method`." })
-        .option("about", { type: "string", describe: "One-line description of the agent work" }), async (args) => {
+        .option("source", { type: "string", demandOption: true, describe: "Path to the Source" })
+        .option("method", { type: "string", describe: "Build Plan / Method package id. Optional — bind later via `interf prep set-method`." })
+        .option("about", { type: "string", describe: "One-line description of the agent work" })
+        .option("requested-artifacts-json", { type: "string", describe: "JSON array of requested Artifacts for this Preparation" })
+        .option("source-profile-json", { type: "string", describe: "JSON object describing the agent's advisory source profile" }), async (args) => {
         const { url, token } = requireConnection(args);
         const sourceAbs = resolve(process.cwd(), args.source);
+        const requestedArtifacts = parseJsonOption("--requested-artifacts-json", args.requestedArtifactsJson, (input) => RequestedArtifactsCliSchema.parse(input));
+        const sourceProfile = parseJsonOption("--source-profile-json", args.sourceProfileJson, (input) => SourceProfileSchema.parse(input));
         const requestBody = {
             id: args.prepId,
             source: { kind: "local-folder", locator: sourceAbs },
             ...(args.method ? { method_id: args.method } : {}),
             about: args.about,
+            ...(requestedArtifacts ? { requested_artifacts: requestedArtifacts } : {}),
+            ...(sourceProfile ? { source_profile: sourceProfile } : {}),
             checks: [],
         };
         const { status, body, raw } = await callJson(`${url}/v1/preparations`, token, { method: "POST", body: JSON.stringify(requestBody) });
@@ -101,17 +192,17 @@ export const prepCommand = {
         }
         console.log(chalk.green(`Created preparation ${chalk.bold(args.prepId)}.`));
         if (!args.method) {
-            console.log(chalk.dim(`  no method bound yet — pick or draft one before compiling:`));
+            console.log(chalk.dim(`  no Build Plan selected yet — pick or draft one before compiling:`));
             console.log(chalk.dim(`    interf prep set-method ${args.prepId} <method-id>`));
             console.log(chalk.dim(`    interf method draft ${args.prepId}`));
         }
-        if (body?.portable_context?.value) {
+        if (body?.method_id && body?.portable_context?.value) {
             console.log(chalk.dim(`  portable context (locator): ${body.portable_context.value}`));
         }
     })
-        .command("set-method <prep-id> <method-id>", "Bind a method to a preparation (or change which method it uses)", (y) => y
+        .command("set-method <prep-id> <method-id>", "Select a Build Plan / Method package for a Preparation", (y) => y
         .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
-        .positional("method-id", { type: "string", demandOption: true, describe: "Method id to bind" }), async (args) => {
+        .positional("method-id", { type: "string", demandOption: true, describe: "Build Plan / Method package id to select" }), async (args) => {
         const { url, token } = requireConnection(args);
         const { status, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token, { method: "PATCH", body: JSON.stringify({ method_id: args.methodId }) });
         if (status !== 200) {
@@ -120,9 +211,15 @@ export const prepCommand = {
                 console.error(raw);
             process.exit(1);
         }
-        console.log(chalk.green(`Bound ${chalk.bold(args.methodId)} to ${chalk.bold(args.prepId)}.`));
+        console.log(chalk.green(`Selected Build Plan ${chalk.bold(args.methodId)} for ${chalk.bold(args.prepId)}.`));
     })
-        .command("show <prep-id>", "Show a preparation's full record", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
+        .command("show <prep-id>", "Show a preparation's full record", (y) => y
+        .positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = requireConnection(args);
         const { status, body, raw } = await callJson(`${url}${preparationResourcePath(args.prepId)}`, token);
         if (status !== 200) {
@@ -131,7 +228,11 @@ export const prepCommand = {
                 console.error(raw);
             process.exit(1);
         }
-        console.log(JSON.stringify(body, null, 2));
+        if (args.json || !body) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        renderPreparationSummary(body);
     })
         .command("rm <prep-id>", "Delete a preparation", (y) => y.positional("prep-id", { type: "string", demandOption: true, describe: "Preparation id" }), async (args) => {
         const { url, token } = requireConnection(args);

package/dist/cli/commands/runs.js

@@ -40,6 +40,90 @@ async function callJson(url, token, init = {}) {
     }
     return { status: response.status, body, raw };
 }
+function runStatusColor(status) {
+    if (status === "succeeded" || status === "completed")
+        return chalk.green;
+    if (status === "failed" || status === "cancelled")
+        return chalk.red;
+    if (status === "running")
+        return chalk.yellow;
+    return chalk.dim;
+}
+function renderRunStatus(run) {
+    const status = run.status ?? (run.trace?.run?.error ? "failed" : "unknown");
+    const color = runStatusColor(status);
+    console.log();
+    console.log(`  ${chalk.bold(run.title ?? run.run_id)} ${color(`(${status})`)}`);
+    console.log(chalk.dim(`    run: ${run.run_id}`));
+    if (run.run_type)
+        console.log(chalk.dim(`    type: ${run.run_type}`));
+    if (run.preparation)
+        console.log(chalk.dim(`    preparation: ${run.preparation}`));
+    if (run.method)
+        console.log(chalk.dim(`    Build Plan: ${run.method}`));
+    if (run.agent_label)
+        console.log(chalk.dim(`    agent: ${run.agent_label}`));
+    if (run.started_at)
+        console.log(chalk.dim(`    started: ${run.started_at}`));
+    if (run.finished_at)
+        console.log(chalk.dim(`    finished: ${run.finished_at}`));
+    if (run.output_path ?? run.portable_context_path) {
+        console.log(chalk.dim(`    output: ${run.output_path ?? run.portable_context_path}`));
+    }
+    if (run.trace?.run?.error?.message) {
+        console.log();
+        console.log(chalk.red("    Error"));
+        console.log(chalk.dim(`      ${run.trace.run.error.message}`));
+    }
+    const readiness = run.readiness;
+    if (readiness?.status) {
+        console.log();
+        const readinessColor = readiness.ready ? chalk.green : chalk.yellow;
+        console.log(`    readiness: ${readinessColor(readiness.status)}${readiness.summary ? chalk.dim(` (${readiness.summary})`) : ""}`);
+    }
+    const metrics = run.metrics ?? [];
+    if (metrics.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Metrics"));
+        for (const metric of metrics.slice(0, 8)) {
+            const value = metric.value !== undefined ? `${metric.value}${metric.unit ? ` ${metric.unit}` : ""}` : "";
+            console.log(chalk.dim(`      ${metric.label ?? "metric"}: ${value}`));
+        }
+    }
+    const artifacts = run.artifacts ?? [];
+    if (artifacts.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Artifacts"));
+        for (const artifact of artifacts.slice(0, 12)) {
+            const stage = artifact.stage_id ? chalk.dim(` ← ${artifact.stage_id}`) : "";
+            console.log(`      ${artifact.label ?? artifact.role}: ${chalk.dim(artifact.path)}${stage}`);
+        }
+        if (artifacts.length > 12)
+            console.log(chalk.dim(`      ... ${artifacts.length - 12} more`));
+    }
+    const proof = run.proof ?? [];
+    if (proof.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Proof"));
+        for (const check of proof.slice(0, 12)) {
+            const marker = check.ok ? chalk.green("pass") : chalk.red("fail");
+            console.log(`      ${marker} ${check.label}${check.detail ? chalk.dim(` — ${check.detail}`) : ""}`);
+        }
+        if (proof.length > 12)
+            console.log(chalk.dim(`      ... ${proof.length - 12} more`));
+    }
+    const events = run.trace?.events ?? [];
+    if (events.length > 0) {
+        console.log();
+        console.log(chalk.bold("    Recent trace"));
+        for (const event of events.slice(-6)) {
+            console.log(chalk.dim(`      ${event.createdAt ?? ""} ${event.eventType ?? "event"}`.trim()));
+        }
+    }
+    console.log();
+    console.log(chalk.dim("  Run with --json for the raw run resource."));
+    console.log();
+}
 export const runsCommand = {
     command: "runs <subcommand>",
     describe: "Inspect runs on the connected instance",
@@ -48,10 +132,7 @@ export const runsCommand = {
         .option("token", { type: "string", describe: "Override the active bearer token" })
         .command("ls", "List runs (optionally filtered by preparation)", (y) => y.option("prep", { type: "string", describe: "Filter by preparation id" }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const path = args.prep
-            ? `/v1/preparations/${encodeURIComponent(args.prep)}/runs`
-            : "/v1/runs";
-        const { status, body, raw } = await callJson(`${url}${path}`, token);
+        const { status, body, raw } = await callJson(`${url}/v1/runs`, token);
         if (status !== 200) {
             console.error(chalk.red(`Failed to list runs (HTTP ${status}).`));
             if (raw)
@@ -60,12 +141,15 @@ export const runsCommand = {
         }
         const runs = body?.runs
             ?? (body?.compile_runs ?? []).map((r) => r.run).filter(Boolean);
-        if (runs.length === 0) {
+        const visibleRuns = args.prep
+            ? runs.filter((run) => run.preparation === args.prep)
+            : runs;
+        if (visibleRuns.length === 0) {
             console.log(chalk.dim("  No runs."));
             return;
         }
         console.log();
-        for (const run of runs) {
+        for (const run of visibleRuns) {
             console.log(`  ${chalk.bold(run.run_id)} ${chalk.dim(`(${run.status ?? "?"})`)}`);
             if (run.preparation)
                 console.log(chalk.dim(`    prep: ${run.preparation}`));
@@ -74,14 +158,24 @@ export const runsCommand = {
         }
         console.log();
     })
-        .command("status <run-id>", "Show full record for a run", (y) => y.positional("run-id", { type: "string", demandOption: true, describe: "Run id" }), async (args) => {
+        .command("status <run-id>", "Show full record for a run", (y) => y
+        .positional("run-id", { type: "string", demandOption: true, describe: "Run id" })
+        .option("json", {
+        type: "boolean",
+        default: false,
+        describe: "Print the raw JSON record instead of the formatted summary",
+    }), async (args) => {
         const { url, token } = resolveConnection(args);
-        const { status, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}`, token);
+        const { status, body, raw } = await callJson(`${url}/v1/runs/${encodeURIComponent(args.runId)}`, token);
         if (status !== 200) {
             console.error(chalk.red(`Failed to read run ${args.runId} (HTTP ${status}).`));
             process.exit(1);
         }
-        console.log(raw);
+        if (args.json || !body) {
+            console.log(raw);
+            return;
+        }
+        renderRunStatus(body);
     })
         .command("cancel <run-id>", "Cancel a running run", (y) => y.positional("run-id", { type: "string", demandOption: true, describe: "Run id" }), async (args) => {
         const { url, token } = resolveConnection(args);