agentplane 0.3.6 → 0.3.8

package/dist/commands/release/apply.command.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { loadConfig, resolveProject } from "@agentplaneorg/core";
+import { createCliEmitter } from "../../cli/output.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { usageError } from "../../cli/spec/errors.js";
 import { withDiagnosticContext } from "../../shared/diagnostics.js";
@@ -7,9 +8,11 @@ import { CliError } from "../../shared/errors.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
 import { GitContext } from "../shared/git-context.js";
 import { ensureNetworkApproved } from "../shared/network-approval.js";
+import { runOperatorPipeline } from "../shared/operator-pipeline.js";
 import { cleanHookEnv, maybePersistExpectedCliVersion, maybeRefreshGeneratedReference, maybeUpdateBunLockfile, replaceAgentplanePackageMetadata, replacePackageVersionInFile, } from "./apply.mutation.js";
 import { ensureCleanTrackedTree, ensureNpmVersionsAvailable, ensureRemoteExists, ensureRemoteTagDoesNotExist, ensureTagDoesNotExist, fileExists, loadReleasePlan, readCoreDependencyVersion, readPackageVersion, runReleasePrepublishGate, validateReleaseNotes, } from "./apply.preflight.js";
 import { pushReleaseRefs, writeReleaseApplyReport } from "./apply.reporting.js";
+const output = createCliEmitter();
 async function resolveReleasePlanInputs(opts) {
     const { planDir, plan, minBullets } = await loadReleasePlan({
         gitRoot: opts.gitRoot,
@@ -118,7 +121,7 @@ async function applyReleaseMutation(opts) {
     await opts.git.stage(stagePaths);
     const staged = await opts.git.statusStagedPaths();
     if (staged.length === 0) {
-        process.stdout.write("No changes to commit.\n");
+        output.line("No changes to commit.");
         return { releaseCommit };
     }
     const subject = `✨ release: ${opts.nextTag}`;
@@ -135,13 +138,13 @@ async function finalizeReleaseApply(opts) {
         cwd: opts.gitRoot,
         env: gitEnv(),
     });
-    process.stdout.write(`Release tag created: ${opts.plan.nextTag}\n`);
+    output.line(`Release tag created: ${opts.plan.nextTag}`);
     if (opts.push) {
         await pushReleaseRefs(opts.gitRoot, opts.remote, opts.plan.nextTag);
-        process.stdout.write(`Pushed: ${opts.remote} HEAD + ${opts.plan.nextTag}\n`);
+        output.line(`Pushed: ${opts.remote} HEAD + ${opts.plan.nextTag}`);
     }
     else {
-        process.stdout.write(`Next: git push <remote> HEAD && git push <remote> ${opts.plan.nextTag}\n`);
+        output.line(`Next: git push <remote> HEAD && git push <remote> ${opts.plan.nextTag}`);
     }
     const reportPath = await writeReleaseApplyReport(opts.gitRoot, {
         applied_at: new Date().toISOString(),
@@ -161,7 +164,7 @@ async function finalizeReleaseApply(opts) {
         commit: opts.releaseCommit,
         push: { requested: opts.push, remote: opts.remote, performed: opts.push },
     });
-    process.stdout.write(`Release report: ${path.relative(opts.gitRoot, reportPath)}\n`);
+    output.line(`Release report: ${path.relative(opts.gitRoot, reportPath)}`);
     return 0;
 }
 export const releaseApplySpec = {
@@ -250,58 +253,76 @@ export const runReleaseApply = async (ctx, flags) => {
             message: "Release publish is mandatory. Run `agentplane release apply --push --yes`.",
         });
     }
-    const resolved = await resolveProject({ cwd: ctx.cwd, rootOverride: ctx.rootOverride ?? null });
-    const gitRoot = resolved.gitRoot;
-    const { planDir, plan, notesPath } = await resolveReleasePlanInputs({
-        gitRoot,
-        planOverride: flags.plan,
-    });
-    if ((plan.bump === "minor" || plan.bump === "major") && flags.yes !== true) {
-        throw usageError({
-            spec: releaseApplySpec,
-            command: "release apply",
-            message: `Bump '${plan.bump}' requires explicit approval. Re-run with --yes.`,
-        });
-    }
-    const corePkgPath = path.join(gitRoot, "packages", "core", "package.json");
-    const agentplanePkgPath = path.join(gitRoot, "packages", "agentplane", "package.json");
-    await ensureReleasePlanMatchesRepoState({
-        gitRoot,
-        plan,
-        corePkgPath,
-        agentplanePkgPath,
-    });
-    let npmVersionChecked = false;
-    if (flags.push) {
-        npmVersionChecked = await runPushPreflight({
-            agentplaneDir: resolved.agentplaneDir,
-            gitRoot,
+    return await runOperatorPipeline({
+        init: async () => {
+            const resolved = await resolveProject({
+                cwd: ctx.cwd,
+                rootOverride: ctx.rootOverride ?? null,
+            });
+            const gitRoot = resolved.gitRoot;
+            const { planDir, plan, notesPath } = await resolveReleasePlanInputs({
+                gitRoot,
+                planOverride: flags.plan,
+            });
+            return {
+                resolved,
+                gitRoot,
+                planDir,
+                plan,
+                notesPath,
+                corePkgPath: path.join(gitRoot, "packages", "core", "package.json"),
+                agentplanePkgPath: path.join(gitRoot, "packages", "agentplane", "package.json"),
+                npmVersionChecked: false,
+            };
+        },
+        preflight: async (state) => {
+            if ((state.plan.bump === "minor" || state.plan.bump === "major") && flags.yes !== true) {
+                throw usageError({
+                    spec: releaseApplySpec,
+                    command: "release apply",
+                    message: `Bump '${state.plan.bump}' requires explicit approval. Re-run with --yes.`,
+                });
+            }
+            await ensureReleasePlanMatchesRepoState({
+                gitRoot: state.gitRoot,
+                plan: state.plan,
+                corePkgPath: state.corePkgPath,
+                agentplanePkgPath: state.agentplanePkgPath,
+            });
+            if (flags.push) {
+                state.npmVersionChecked = await runPushPreflight({
+                    agentplaneDir: state.resolved.agentplaneDir,
+                    gitRoot: state.gitRoot,
+                    remote: flags.remote,
+                    nextTag: state.plan.nextTag,
+                    nextVersion: state.plan.nextVersion,
+                    yes: flags.yes,
+                });
+            }
+        },
+        execute: async (state) => {
+            const git = new GitContext({ gitRoot: state.gitRoot });
+            return await applyReleaseMutation({
+                agentplaneDir: state.resolved.agentplaneDir,
+                gitRoot: state.gitRoot,
+                git,
+                notesPath: state.notesPath,
+                corePkgPath: state.corePkgPath,
+                agentplanePkgPath: state.agentplanePkgPath,
+                nextTag: state.plan.nextTag,
+                nextVersion: state.plan.nextVersion,
+            });
+        },
+        finalize: async (state, mutation) => await finalizeReleaseApply({
+            gitRoot: state.gitRoot,
+            planDir: state.planDir,
+            notesPath: state.notesPath,
+            plan: state.plan,
+            npmVersionChecked: state.npmVersionChecked,
+            releaseCommit: mutation.releaseCommit,
+            push: flags.push,
             remote: flags.remote,
-            nextTag: plan.nextTag,
-            nextVersion: plan.nextVersion,
-            yes: flags.yes,
-        });
-    }
-    const git = new GitContext({ gitRoot });
-    const { releaseCommit } = await applyReleaseMutation({
-        agentplaneDir: resolved.agentplaneDir,
-        gitRoot,
-        git,
-        notesPath,
-        corePkgPath,
-        agentplanePkgPath,
-        nextTag: plan.nextTag,
-        nextVersion: plan.nextVersion,
-    });
-    return await finalizeReleaseApply({
-        gitRoot,
-        planDir,
-        notesPath,
-        plan,
-        npmVersionChecked,
-        releaseCommit,
-        push: flags.push,
-        remote: flags.remote,
+        }),
     });
 };
 export { pushReleaseRefs } from "./apply.reporting.js";

package/dist/commands/release/plan.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/plan.command.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1E,KAAK,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AA4IjD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CA4E1D,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,iBAAiB,CAqE5D,CAAC"}
+{"version":3,"file":"plan.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/plan.command.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAO1E,KAAK,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAE5C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,CAAC;AA4IjD,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,iBAAiB,CA4E1D,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,iBAAiB,CAqE5D,CAAC"}

package/dist/commands/release/plan.command.js

@@ -1,10 +1,12 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { resolveProject } from "@agentplaneorg/core";
+import { createCliEmitter } from "../../cli/output.js";
 import { usageError } from "../../cli/spec/errors.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { CliError } from "../../shared/errors.js";
 import { execFileAsync, gitEnv } from "../shared/git.js";
+const output = createCliEmitter();
 function parseSemver(version) {
     const m = /^(\d+)\.(\d+)\.(\d+)$/u.exec(version.trim());
     if (!m)
@@ -229,8 +231,10 @@ export const runReleasePlan = async (ctx, flags) => {
     await writeFile(path.join(baseDir, "changes.json"), JSON.stringify(changes, null, 2) + "\n", "utf8");
     await writeFile(path.join(baseDir, "changes.md"), changesMarkdown(changes), "utf8");
     await writeFile(path.join(baseDir, "instructions.md"), releaseInstructions({ nextTag, prevTag, bump: flags.bump, minBullets }), "utf8");
-    process.stdout.write(`Release plan written: ${path.relative(gitRoot, baseDir)}\n`);
-    process.stdout.write(`Next tag: ${nextTag}\n`);
-    process.stdout.write(`Hint: Create a DOCS task to write docs/releases/${nextTag}.md based on this plan.\n`);
+    output.lines([
+        `Release plan written: ${path.relative(gitRoot, baseDir)}`,
+        `Next tag: ${nextTag}`,
+        `Hint: Create a DOCS task to write docs/releases/${nextTag}.md based on this plan.`,
+    ]);
     return 0;
 };

package/dist/commands/release/release.command.d.ts

@@ -1,5 +1,5 @@
 import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
-export type ReleaseGroupParsed = Record<string, never>;
-export declare const releaseSpec: CommandSpec<ReleaseGroupParsed>;
-export declare const runRelease: CommandHandler<ReleaseGroupParsed>;
+import { type GroupCommandParsed } from "../../cli/group-command.js";
+export declare const releaseSpec: CommandSpec<GroupCommandParsed>;
+export declare const runRelease: CommandHandler<GroupCommandParsed>;
 //# sourceMappingURL=release.command.d.ts.map

package/dist/commands/release/release.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"release.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/release.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAEvD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAYvD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAGzD,CAAC"}
+{"version":3,"file":"release.command.d.ts","sourceRoot":"","sources":["../../../src/commands/release/release.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,4BAA4B,CAAC;AAEpC,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAOvD,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAMzD,CAAC"}

package/dist/commands/release/release.command.js

@@ -1,18 +1,16 @@
-import { usageError } from "../../cli/spec/errors.js";
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../../cli/group-command.js";
 export const releaseSpec = {
     id: ["release"],
     group: "Release",
     summary: "Prepare a release (agent-assisted notes + version bump workflow).",
     synopsis: ["agentplane release <command> [args] [options]"],
-    validateRaw: (raw) => {
-        if (raw.extra.length > 0) {
-            throw usageError({ spec: releaseSpec, message: `Unknown subcommand: ${raw.extra[0]}` });
-        }
-        throw usageError({ spec: releaseSpec, message: "Missing subcommand." });
-    },
-    parse: () => ({}),
+    args: [{ name: "cmd", required: false, variadic: true, valueHint: "<command>" }],
+    parse: (raw) => parseGroupCommand(raw),
 };
-export const runRelease = () => {
-    // Unreachable (validateRaw always throws).
-    return Promise.resolve(2);
+export const runRelease = async (_ctx, p) => {
+    throwGroupCommandUsage({
+        spec: releaseSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["release"]),
+    });
 };

package/dist/commands/release.test-helpers.d.ts

@@ -0,0 +1,20 @@
+export declare function writePackageJson(root: string, relDir: string, data: Record<string, unknown>): Promise<void>;
+export declare function writeReleaseNotes(root: string, version: string, body?: string): Promise<void>;
+export declare function seedReleaseWorkspace(root: string, opts?: {
+    coreVersion?: string;
+    cliVersion?: string;
+    dependencyVersion?: string;
+    writeNotes?: boolean;
+    notesVersion?: string;
+    notesBody?: string;
+}): Promise<void>;
+export declare function initReleaseWorkspace(opts?: {
+    prefix?: string;
+    coreVersion?: string;
+    cliVersion?: string;
+    dependencyVersion?: string;
+    writeNotes?: boolean;
+    notesVersion?: string;
+    notesBody?: string;
+}): Promise<string>;
+//# sourceMappingURL=release.test-helpers.d.ts.map

package/dist/commands/release.test-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.test-helpers.d.ts","sourceRoot":"","sources":["../../src/commands/release.test-helpers.ts"],"names":[],"mappings":"AAIA,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,IAAI,SAAc,GACjB,OAAO,CAAC,IAAI,CAAC,CAIf;AAED,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;IACJ,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,oBAAoB,CACxC,IAAI,GAAE;IACJ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACf,GACL,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/commands/release.test-helpers.js

@@ -0,0 +1,37 @@
+import { mkdir, mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+export async function writePackageJson(root, relDir, data) {
+    const dir = path.join(root, relDir);
+    await mkdir(dir, { recursive: true });
+    await writeFile(path.join(dir, "package.json"), `${JSON.stringify(data, null, 2)}\n`, "utf8");
+}
+export async function writeReleaseNotes(root, version, body = "# Notes\n") {
+    const releasesDir = path.join(root, "docs", "releases");
+    await mkdir(releasesDir, { recursive: true });
+    await writeFile(path.join(releasesDir, `v${version}.md`), body, "utf8");
+}
+export async function seedReleaseWorkspace(root, opts = {}) {
+    const coreVersion = opts.coreVersion ?? "1.2.3";
+    const cliVersion = opts.cliVersion ?? coreVersion;
+    const dependencyVersion = opts.dependencyVersion ?? coreVersion;
+    await writePackageJson(root, "packages/core", {
+        name: "@agentplaneorg/core",
+        version: coreVersion,
+    });
+    await writePackageJson(root, "packages/agentplane", {
+        name: "agentplane",
+        version: cliVersion,
+        dependencies: {
+            "@agentplaneorg/core": dependencyVersion,
+        },
+    });
+    if (opts.writeNotes) {
+        await writeReleaseNotes(root, opts.notesVersion ?? cliVersion, opts.notesBody);
+    }
+}
+export async function initReleaseWorkspace(opts = {}) {
+    const root = await mkdtemp(path.join(tmpdir(), opts.prefix ?? "agentplane-release-"));
+    await seedReleaseWorkspace(root, opts);
+    return root;
+}

package/dist/commands/runtime.command.d.ts

@@ -1,11 +1,14 @@
 import type { CommandHandler, CommandSpec } from "../cli/spec/spec.js";
+import { type GroupCommandParsed } from "../cli/group-command.js";
 import { type RepoCliVersionExpectation } from "../shared/repo-cli-version.js";
 import { type RuntimeSourceInfo } from "../shared/runtime-source.js";
 export type FrameworkDevWorkflow = {
     available: boolean;
-    rebuildCommands: string[];
+    bootstrapCommand: string;
+    manualRepairCommands: string[];
+    repoLocalVerifyCommand: string;
     reinstallScript: string;
-    verifyCommand: string;
+    globalVerifyCommand: string;
     forceGlobalExample: string;
     recommendation: string | null;
 };
@@ -13,16 +16,13 @@ export type RuntimeExplainPayload = RuntimeSourceInfo & {
     frameworkDev: FrameworkDevWorkflow;
     repoCliExpectation: RepoCliVersionExpectation;
 };
-export type RuntimeGroupParsed = {
-    cmd: string[];
-};
 export type RuntimeExplainParsed = {
     json: boolean;
 };
-export declare const runtimeSpec: CommandSpec<RuntimeGroupParsed>;
+export declare const runtimeSpec: CommandSpec<GroupCommandParsed>;
 export declare const runtimeExplainSpec: CommandSpec<RuntimeExplainParsed>;
 export declare function buildFrameworkDevWorkflow(report: RuntimeSourceInfo): FrameworkDevWorkflow;
 export declare function renderRuntimeExplainText(report: RuntimeSourceInfo, repoCliExpectation: RepoCliVersionExpectation): string;
-export declare const runRuntime: CommandHandler<RuntimeGroupParsed>;
+export declare const runRuntime: CommandHandler<GroupCommandParsed>;
 export declare const runRuntimeExplain: CommandHandler<RuntimeExplainParsed>;
 //# sourceMappingURL=runtime.command.d.ts.map

package/dist/commands/runtime.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.command.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.command.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGvE,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAErC,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG;IACtD,YAAY,EAAE,oBAAoB,CAAC;IACnC,kBAAkB,EAAE,yBAAyB,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,GAAG,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AACnD,MAAM,MAAM,oBAAoB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAQvD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAoBhE,CAAC;AAMF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAsCzF;AAgBD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,EACzB,kBAAkB,EAAE,yBAAyB,GAC5C,MAAM,CA2CR;AAyBD,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAazD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CAkBlE,CAAC"}
+{"version":3,"file":"runtime.command.d.ts","sourceRoot":"","sources":["../../src/commands/runtime.command.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,yBAAyB,EAC/B,MAAM,+BAA+B,CAAC;AASvC,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,6BAA6B,CAAC;AAIrC,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG,iBAAiB,GAAG;IACtD,YAAY,EAAE,oBAAoB,CAAC;IACnC,kBAAkB,EAAE,yBAAyB,CAAC;CAC/C,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAErD,eAAO,MAAM,WAAW,EAAE,WAAW,CAAC,kBAAkB,CAQvD,CAAC;AAEF,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAoBhE,CAAC;AAMF,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,iBAAiB,GAAG,oBAAoB,CAkCzF;AAgBD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,EACzB,kBAAkB,EAAE,yBAAyB,GAC5C,MAAM,CA+CR;AAyBD,eAAO,MAAM,UAAU,EAAE,cAAc,CAAC,kBAAkB,CAQzD,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CAkBlE,CAAC"}

package/dist/commands/runtime.command.js

@@ -1,8 +1,10 @@
 import { loadConfig, resolveProject } from "@agentplaneorg/core";
-import { usageError } from "../cli/spec/errors.js";
-import { suggestOne } from "../cli/spec/suggest.js";
+import { createCliEmitter } from "../cli/output.js";
+import { loadDirectSubcommandNames, parseGroupCommand, throwGroupCommandUsage, } from "../cli/group-command.js";
 import { evaluateRepoCliVersionExpectation, } from "../shared/repo-cli-version.js";
+import { FRAMEWORK_DEV_BOOTSTRAP_COMMAND, FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE, FRAMEWORK_DEV_GLOBAL_VERIFY_COMMAND, FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS, FRAMEWORK_DEV_REINSTALL_SCRIPT, FRAMEWORK_DEV_REPO_LOCAL_VERIFY_COMMAND, } from "../../bin/framework-dev-contract.js";
 import { describeRuntimeMode, resolveRuntimeSourceInfo, } from "../shared/runtime-source.js";
+const output = createCliEmitter();
 export const runtimeSpec = {
     id: ["runtime"],
     group: "Diagnostics",
@@ -10,7 +12,7 @@ export const runtimeSpec = {
     synopsis: ["agentplane runtime <explain> [options]"],
     args: [{ name: "cmd", required: false, variadic: true, valueHint: "<cmd>" }],
     examples: [{ cmd: "agentplane runtime explain", why: "Show active runtime details." }],
-    parse: (raw) => ({ cmd: (raw.args.cmd ?? []) }),
+    parse: (raw) => parseGroupCommand(raw),
 };
 export const runtimeExplainSpec = {
     id: ["runtime", "explain"],
@@ -38,36 +40,33 @@ function renderPath(value) {
 }
 export function buildFrameworkDevWorkflow(report) {
     const available = report.framework.inFrameworkCheckout;
-    const reinstallScript = "scripts/reinstall-global-agentplane.sh";
-    const rebuildCommands = [
-        "bun run --filter=@agentplaneorg/core build",
-        "bun run --filter=agentplane build",
-    ];
-    const verifyCommand = "agentplane runtime explain";
-    const forceGlobalExample = "AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 agentplane <command>";
     if (!available) {
         return {
             available,
-            rebuildCommands,
-            reinstallScript,
-            verifyCommand,
-            forceGlobalExample,
+            bootstrapCommand: FRAMEWORK_DEV_BOOTSTRAP_COMMAND,
+            manualRepairCommands: [...FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS],
+            repoLocalVerifyCommand: FRAMEWORK_DEV_REPO_LOCAL_VERIFY_COMMAND,
+            reinstallScript: FRAMEWORK_DEV_REINSTALL_SCRIPT,
+            globalVerifyCommand: FRAMEWORK_DEV_GLOBAL_VERIFY_COMMAND,
+            forceGlobalExample: FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE,
             recommendation: null,
         };
     }
     const recommendation = report.mode === "repo-local" || report.mode === "repo-local-handoff"
-        ? "Rebuild local packages after source changes; use the reinstall helper only when you need the global PATH command updated from this checkout."
+        ? "Run the framework bootstrap after fresh clones or dependency drift; use the reinstall helper only when the global PATH command itself should resolve this checkout."
         : report.mode === "global-in-framework"
-            ? "Reinstall or update the global agentplane CLI from this checkout so the wrapper can hand off to the repo-local binary."
+            ? "Bootstrap the framework checkout first so the installed wrapper can hand off cleanly to the repo-local runtime."
             : report.mode === "global-forced-in-framework"
                 ? "Unset AGENTPLANE_USE_GLOBAL_IN_FRAMEWORK=1 unless you intentionally need the global installed CLI inside the framework checkout."
-                : "Use runtime explain after rebuild/reinstall to confirm which binary and package roots are active.";
+                : "Use the framework bootstrap command first, then verify the repo-local runtime and global wrapper explicitly.";
     return {
         available,
-        rebuildCommands,
-        reinstallScript,
-        verifyCommand,
-        forceGlobalExample,
+        bootstrapCommand: FRAMEWORK_DEV_BOOTSTRAP_COMMAND,
+        manualRepairCommands: [...FRAMEWORK_DEV_MANUAL_REPAIR_COMMANDS],
+        repoLocalVerifyCommand: FRAMEWORK_DEV_REPO_LOCAL_VERIFY_COMMAND,
+        reinstallScript: FRAMEWORK_DEV_REINSTALL_SCRIPT,
+        globalVerifyCommand: FRAMEWORK_DEV_GLOBAL_VERIFY_COMMAND,
+        forceGlobalExample: FRAMEWORK_DEV_FORCE_GLOBAL_EXAMPLE,
         recommendation,
     };
 }
@@ -110,7 +109,7 @@ export function renderRuntimeExplainText(report, repoCliExpectation) {
         lines.push(`Handoff from: ${report.handoffFromBinaryPath}`);
     }
     if (frameworkDev.available) {
-        lines.push("", "Framework dev workflow:", "1. Rebuild local packages after source changes:", ...frameworkDev.rebuildCommands.map((command) => `   - ${command}`), "2. If the global PATH install should resolve this checkout:", `   - ${frameworkDev.reinstallScript}`, "3. Re-verify the active runtime:", `   - ${frameworkDev.verifyCommand}`, "4. Optional: force the global installed CLI inside this checkout:", `   - ${frameworkDev.forceGlobalExample}`);
+        lines.push("", "Framework dev workflow:", "1. Canonical bootstrap:", `   - ${frameworkDev.bootstrapCommand}`, "2. Manual fallback:", ...frameworkDev.manualRepairCommands.map((command) => `   - ${command}`), "3. Verify the repo-local runtime directly:", `   - ${frameworkDev.repoLocalVerifyCommand}`, "4. If the global PATH install should resolve this checkout:", `   - ${frameworkDev.reinstallScript}`, "5. Re-verify the global wrapper:", `   - ${frameworkDev.globalVerifyCommand}`, "6. Optional: force the global installed CLI inside this checkout:", `   - ${frameworkDev.forceGlobalExample}`);
         if (frameworkDev.recommendation) {
             lines.push(`Recommendation: ${frameworkDev.recommendation}`);
         }
@@ -136,17 +135,14 @@ async function resolveRepoCliExpectation(opts) {
         };
     }
 }
-export const runRuntime = (_ctx, p) => {
-    const input = p.cmd.join(" ");
-    const suggestion = suggestOne(input, ["explain"]);
-    const suffix = suggestion ? ` Did you mean: ${suggestion}?` : "";
-    const msg = p.cmd.length === 0 ? "Missing subcommand." : `Unknown subcommand: ${p.cmd[0]}.`;
-    return Promise.reject(usageError({
+export const runRuntime = async (_ctx, p) => {
+    throwGroupCommandUsage({
         spec: runtimeSpec,
+        cmd: p.cmd,
+        subcommands: await loadDirectSubcommandNames(["runtime"]),
         command: "runtime",
-        message: `${msg}${suffix}`,
-        context: { command: "runtime" },
-    }));
+        contextCommand: "runtime",
+    });
 };
 export const runRuntimeExplain = (ctx, p) => {
     const report = resolveRuntimeSourceInfo({
@@ -160,10 +156,10 @@ export const runRuntimeExplain = (ctx, p) => {
     }).then((repoCliExpectation) => {
         const payload = { ...buildRuntimeExplainPayload(report), repoCliExpectation };
         if (p.json) {
-            process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+            output.json(payload);
             return 0;
         }
-        process.stdout.write(`${renderRuntimeExplainText(report, repoCliExpectation)}\n`);
+        output.line(renderRuntimeExplainText(report, repoCliExpectation));
         return 0;
     });
 };

package/dist/commands/scenario/execute.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type ScenarioExecuteParsed = {
+    recipeId: string;
+    scenarioId: string;
+};
+export declare const scenarioExecuteSpec: CommandSpec<ScenarioExecuteParsed>;
+export declare const runScenarioExecute: CommandHandler<ScenarioExecuteParsed>;
+//# sourceMappingURL=execute.command.d.ts.map

package/dist/commands/scenario/execute.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execute.command.d.ts","sourceRoot":"","sources":["../../../src/commands/scenario/execute.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAa1E,MAAM,MAAM,qBAAqB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAG7E,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,qBAAqB,CAyBlE,CAAC;AAgBF,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,qBAAqB,CAuEpE,CAAC"}

package/dist/commands/scenario/execute.command.js

@@ -0,0 +1,117 @@
+import { usageError } from "../../cli/spec/errors.js";
+import { exitCodeForError } from "../../cli/exit-codes.js";
+import { mapBackendError } from "../../cli/error-map.js";
+import { createCliEmitter } from "../../cli/output.js";
+import { loadCommandContext } from "../shared/task-backend.js";
+import { executeTaskRunnerExecution } from "../../runner/usecases/task-run.js";
+import { materializeRecipeScenarioTask } from "../../runner/usecases/scenario-materialize-task.js";
+import { cmdTaskPlanApprove } from "../task/plan.js";
+import { cmdTaskStartReady } from "../task/start-ready.js";
+import { CliError } from "../../shared/errors.js";
+const output = createCliEmitter();
+export const scenarioExecuteSpec = {
+    id: ["scenario", "execute"],
+    group: "Scenario",
+    summary: "Materialize a recipe-backed task and execute it through the shared runner flow.",
+    description: "Resolves a recipe scenario, materializes a task from its explicit task_template, and executes the shared runner with recipe context bundled alongside the created task.",
+    args: [{ name: "id", required: true, valueHint: "<recipe:scenario>" }],
+    examples: [
+        {
+            cmd: "agentplane scenario execute viewer:demo",
+            why: "Create a task from the scenario template and execute it through the configured runner.",
+        },
+    ],
+    parse: (raw) => {
+        const id = String(raw.args.id ?? "");
+        const [recipeId, scenarioId] = id.split(":", 2);
+        if (!recipeId || !scenarioId) {
+            throw usageError({
+                spec: scenarioExecuteSpec,
+                command: "scenario execute",
+                message: `Invalid scenario id: ${id} (expected: <recipe:scenario>)`,
+            });
+        }
+        return { recipeId, scenarioId };
+    },
+};
+function renderScenarioExecuteStartBody(parsed, taskId) {
+    return (`Start: execute recipe scenario ${parsed.recipeId}:${parsed.scenarioId} through the shared runner ` +
+        `using materialized task ${taskId} and its explicit task_template.`);
+}
+function renderScenarioExecutePlanApprovalNote(parsed) {
+    return (`Materialized from recipe scenario ${parsed.recipeId}:${parsed.scenarioId} ` +
+        "for immediate shared-runner execution.");
+}
+export const runScenarioExecute = async (ctx, parsed) => {
+    try {
+        const commandCtx = await loadCommandContext({
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? null,
+        });
+        const materialized = await materializeRecipeScenarioTask({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? null,
+            recipe_id: parsed.recipeId,
+            scenario_id: parsed.scenarioId,
+        });
+        await cmdTaskPlanApprove({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? undefined,
+            taskId: materialized.task_id,
+            by: "ORCHESTRATOR",
+            note: renderScenarioExecutePlanApprovalNote(parsed),
+        });
+        await cmdTaskStartReady({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? undefined,
+            taskId: materialized.task_id,
+            author: materialized.task.owner,
+            body: renderScenarioExecuteStartBody(parsed, materialized.task_id),
+            force: false,
+            yes: false,
+            quiet: true,
+        });
+        const executed = await executeTaskRunnerExecution({
+            ctx: commandCtx,
+            cwd: ctx.cwd,
+            rootOverride: ctx.rootOverride ?? null,
+            task_id: materialized.task_id,
+            run_id: materialized.run_id,
+            recipe: materialized.recipe_context,
+            target: {
+                kind: "recipe_scenario",
+                recipe_id: parsed.recipeId,
+                scenario_id: parsed.scenarioId,
+                task_id: materialized.task_id,
+            },
+        });
+        output.info(`scenario executed: ${parsed.recipeId}:${parsed.scenarioId}`);
+        output.line(`task_id: ${materialized.task_id}`);
+        output.line(`run_id: ${executed.invocation.run_id}`);
+        output.line(`state: ${executed.bundle.execution.artifact_paths.state_path}`);
+        output.line(`events: ${executed.bundle.execution.artifact_paths.events_path}`);
+        output.line(`status: ${executed.result.status}`);
+        output.line(`runner_exit_code: ${executed.result.exit_code ?? "null"}`);
+        if (executed.result.stdout_summary) {
+            output.line(`stdout: ${executed.result.stdout_summary}`);
+        }
+        if (executed.result.stderr_summary) {
+            output.line(`stderr: ${executed.result.stderr_summary}`, "stderr");
+        }
+        return executed.result.status === "success"
+            ? 0
+            : (executed.result.exit_code ?? exitCodeForError("E_RUNTIME"));
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapBackendError(err, {
+            command: scenarioExecuteSpec.id.join(" "),
+            recipe_id: parsed.recipeId,
+            scenario_id: parsed.scenarioId,
+        });
+    }
+};

package/dist/commands/scenario/impl/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/scenario/impl/commands.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAkB3E,KAAK,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AAmKF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,GACb,oBAAoB,CAQtB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BlB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAsClB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA2ChE;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;CACvD,GAAG,OAAO,CAAC,MAAM,CAAC,CAqClB"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/scenario/impl/commands.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAkB3E,KAAK,iBAAiB,GAAG,MAAM,GAAG,MAAM,CAAC;AAEzC,KAAK,oBAAoB,GAAG;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB,CAAC;AA2KF,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EAAE,GACb,oBAAoB,CAQtB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,MAAM,CAAC,CA4BlB;AAED,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAqClB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,OAAO,EAAE,iBAAiB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA2ChE;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,CAAC;CACvD,GAAG,OAAO,CAAC,MAAM,CAAC,CAuClB"}