agentplane 0.3.12 → 0.3.14

package/dist/commands/pr/open.js

@@ -3,6 +3,8 @@ import { mapBackendError } from "../../cli/error-map.js";
 import { exitCodeForError } from "../../cli/exit-codes.js";
 import { createCliEmitter } from "../../cli/output.js";
 import { CliError } from "../../shared/errors.js";
+import { execFileAsync, gitEnv } from "../shared/git.js";
+import { gitBranchUpstream, gitCurrentBranch } from "../shared/git-ops.js";
 import { loadCommandContext } from "../shared/task-backend.js";
 import { maybeAutoCommitTaskPrArtifacts } from "./internal/auto-commit.js";
 import { syncPrArtifacts } from "./internal/sync.js";
@@ -16,6 +18,41 @@ function prOpenOutcomeDetails(meta, openOutcome) {
     }
     return "local PR artifacts synced; remote PR creation staged";
 }
+async function pushTaskBranchUpstreamIfConfigured(opts) {
+    const upstream = await gitBranchUpstream(opts.gitRoot, opts.branch);
+    const trimmed = upstream?.trim() ?? "";
+    if (!trimmed) {
+        const currentBranch = await gitCurrentBranch(opts.gitRoot).catch(() => "");
+        if (currentBranch.trim() !== opts.branch.trim())
+            return false;
+        try {
+            await execFileAsync("git", ["remote", "get-url", "origin"], {
+                cwd: opts.gitRoot,
+                env: gitEnv(),
+            });
+        }
+        catch {
+            return false;
+        }
+        await execFileAsync("git", ["push", "--no-verify", "-u", "origin", `HEAD:${opts.branch}`], {
+            cwd: opts.gitRoot,
+            env: gitEnv(),
+        });
+        return true;
+    }
+    const slashIndex = trimmed.indexOf("/");
+    if (slashIndex <= 0 || slashIndex === trimmed.length - 1)
+        return false;
+    const remote = trimmed.slice(0, slashIndex);
+    const upstreamBranch = trimmed.slice(slashIndex + 1);
+    if (!remote || !upstreamBranch)
+        return false;
+    await execFileAsync("git", ["push", "--no-verify", remote, `HEAD:${upstreamBranch}`], {
+        cwd: opts.gitRoot,
+        env: gitEnv(),
+    });
+    return true;
+}
 export async function cmdPrOpen(opts) {
     try {
         const output = createCliEmitter();
@@ -27,25 +64,43 @@ export async function cmdPrOpen(opts) {
                 message: "Invalid value for --author.",
             });
         }
-        const { meta, prDir, resolved, openOutcome } = await syncPrArtifacts({
-            ctx: opts.ctx,
+        const commandCtx = opts.ctx ??
+            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
+        const initialSync = await syncPrArtifacts({
+            ctx: commandCtx,
             cwd: opts.cwd,
             rootOverride: opts.rootOverride,
             taskId: opts.taskId,
             mode: "open",
             author,
             branch: opts.branch,
-            remoteMode: opts.syncOnly ? "sync-only" : "auto",
+            remoteMode: "sync-only",
         });
-        const commandCtx = opts.ctx ??
-            (await loadCommandContext({ cwd: opts.cwd, rootOverride: opts.rootOverride ?? null }));
-        if (meta.branch) {
+        if (initialSync.meta.branch) {
             await maybeAutoCommitTaskPrArtifacts({
                 ctx: commandCtx,
                 taskId: opts.taskId,
-                branch: meta.branch,
+                branch: initialSync.meta.branch,
+            });
+        }
+        if (!opts.syncOnly && initialSync.meta.branch) {
+            await pushTaskBranchUpstreamIfConfigured({
+                gitRoot: commandCtx.resolvedProject.gitRoot,
+                branch: initialSync.meta.branch,
             });
         }
+        const { meta, prDir, resolved, openOutcome } = opts.syncOnly
+            ? initialSync
+            : await syncPrArtifacts({
+                ctx: commandCtx,
+                cwd: opts.cwd,
+                rootOverride: opts.rootOverride,
+                taskId: opts.taskId,
+                mode: "open",
+                author,
+                branch: opts.branch,
+                remoteMode: "auto",
+            });
         output.success("pr open", path.relative(resolved.gitRoot, prDir), prOpenOutcomeDetails(meta, openOutcome ?? null));
         return 0;
     }

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

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

package/dist/commands/pr/pr.command.js

@@ -34,7 +34,7 @@ export const prSpec = {
 export const prOpenSpec = {
     id: ["pr", "open"],
     group: "PR",
-    summary: "Create PR artifacts for a task.",
+    summary: "Create PR artifacts for a task and, unless --sync-only is set, publish/link the remote GitHub PR.",
     args: [{ name: "task-id", required: true, valueHint: "<task-id>" }],
     options: [
         {
@@ -57,7 +57,12 @@ export const prOpenSpec = {
             description: "Only write local PR artifacts; do not create a remote GitHub PR.",
         },
     ],
-    examples: [{ cmd: "agentplane pr open 202602030608-F1Q8AB --author CODER", why: "Open." }],
+    examples: [
+        {
+            cmd: "agentplane pr open 202602030608-F1Q8AB --author CODER",
+            why: "Sync local artifacts, publish the task branch to origin if needed, and create/link the GitHub PR.",
+        },
+    ],
     validateRaw: (raw) => {
         const author = typeof raw.opts.author === "string" ? raw.opts.author.trim() : "";
         if (!author) {

package/dist/commands/recipes/active.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesActiveParsed = {
+    full: boolean;
+};
+export declare const recipesActiveSpec: CommandSpec<RecipesActiveParsed>;
+export declare const runRecipesActive: CommandHandler<RecipesActiveParsed>;
+//# sourceMappingURL=active.command.d.ts.map

package/dist/commands/recipes/active.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/active.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEpD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAS9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAC2B,CAAC"}

package/dist/commands/recipes/active.command.js

@@ -0,0 +1,12 @@
+import { cmdRecipeActiveParsed } from "../recipes.js";
+export const recipesActiveSpec = {
+    id: ["recipes", "active"],
+    group: "Recipes",
+    summary: "List active project overlays.",
+    options: [
+        { kind: "boolean", name: "full", default: false, description: "Print full JSON payload." },
+    ],
+    examples: [{ cmd: "agentplane recipes active", why: "Show overlays active for the project." }],
+    parse: (raw) => ({ full: raw.opts.full === true }),
+};
+export const runRecipesActive = (ctx, parsed) => cmdRecipeActiveParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, full: parsed.full });

package/dist/commands/recipes/add.command.d.ts

@@ -0,0 +1,8 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesAddParsed = {
+    recipeRef: string;
+    mode?: "copy" | "link";
+};
+export declare const recipesAddSpec: CommandSpec<RecipesAddParsed>;
+export declare const runRecipesAdd: CommandHandler<RecipesAddParsed>;
+//# sourceMappingURL=add.command.d.ts.map

package/dist/commands/recipes/add.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/add.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,gBAAgB,CAyBxD,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,cAAc,CAAC,gBAAgB,CAMvD,CAAC"}

package/dist/commands/recipes/add.command.js

@@ -0,0 +1,33 @@
+import { cmdRecipeAddParsed } from "../recipes.js";
+export const recipesAddSpec = {
+    id: ["recipes", "add"],
+    group: "Recipes",
+    summary: "Vendor a cached recipe into the current project.",
+    args: [{ name: "recipe", required: true, valueHint: "<id|id@version>" }],
+    options: [
+        {
+            kind: "string",
+            name: "mode",
+            valueHint: "<copy|link>",
+            choices: ["copy", "link"],
+            description: "Materialization mode for the project-local package.",
+        },
+    ],
+    examples: [
+        { cmd: "agentplane recipes add tdd", why: "Vendor the latest cached recipe into the project." },
+        {
+            cmd: "agentplane recipes add tdd@1.2.0 --mode link",
+            why: "Link a cached recipe into the project for local recipe development.",
+        },
+    ],
+    parse: (raw) => ({
+        recipeRef: String(raw.args.recipe ?? "").trim(),
+        mode: raw.opts.mode === "copy" || raw.opts.mode === "link" ? raw.opts.mode : undefined,
+    }),
+};
+export const runRecipesAdd = (ctx, parsed) => cmdRecipeAddParsed({
+    cwd: ctx.cwd,
+    rootOverride: ctx.rootOverride,
+    recipeRef: parsed.recipeRef,
+    mode: parsed.mode,
+});

package/dist/commands/recipes/detach.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesDetachParsed = {
+    id: string;
+};
+export declare const recipesDetachSpec: CommandSpec<RecipesDetachParsed>;
+export declare const runRecipesDetach: CommandHandler<RecipesDetachParsed>;
+//# sourceMappingURL=detach.command.d.ts.map

package/dist/commands/recipes/detach.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detach.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/detach.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAY9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CAK7D,CAAC"}

package/dist/commands/recipes/detach.command.js

@@ -0,0 +1,19 @@
+import { cmdRecipeDetachParsed } from "../recipes.js";
+export const recipesDetachSpec = {
+    id: ["recipes", "detach"],
+    group: "Recipes",
+    summary: "Convert a linked vendored recipe into a project-local copy.",
+    args: [{ name: "id", required: true, valueHint: "<id>" }],
+    examples: [
+        {
+            cmd: "agentplane recipes detach tdd",
+            why: "Freeze a linked recipe into a portable project copy before sharing the repo.",
+        },
+    ],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesDetach = (ctx, parsed) => cmdRecipeDetachParsed({
+    cwd: ctx.cwd,
+    rootOverride: ctx.rootOverride,
+    id: parsed.id,
+});

package/dist/commands/recipes/disable.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesDisableParsed = {
+    id: string;
+};
+export declare const recipesDisableSpec: CommandSpec<RecipesDisableParsed>;
+export declare const runRecipesDisable: CommandHandler<RecipesDisableParsed>;
+//# sourceMappingURL=disable.command.d.ts.map

package/dist/commands/recipes/disable.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disable.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/disable.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAOhE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACsB,CAAC"}

package/dist/commands/recipes/disable.command.js

@@ -0,0 +1,10 @@
+import { cmdRecipeDisableParsed } from "../recipes.js";
+export const recipesDisableSpec = {
+    id: ["recipes", "disable"],
+    group: "Recipes",
+    summary: "Disable an active project overlay for the current project.",
+    args: [{ name: "id", required: true, valueHint: "<recipe-id>" }],
+    examples: [{ cmd: "agentplane recipes disable tdd", why: "Deactivate an overlay." }],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesDisable = (ctx, parsed) => cmdRecipeDisableParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: parsed.id });

package/dist/commands/recipes/enable.command.d.ts

@@ -0,0 +1,7 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesEnableParsed = {
+    id: string;
+};
+export declare const recipesEnableSpec: CommandSpec<RecipesEnableParsed>;
+export declare const runRecipesEnable: CommandHandler<RecipesEnableParsed>;
+//# sourceMappingURL=enable.command.d.ts.map

package/dist/commands/recipes/enable.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enable.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/enable.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjD,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,mBAAmB,CAO9D,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,mBAAmB,CACuB,CAAC"}

package/dist/commands/recipes/enable.command.js

@@ -0,0 +1,10 @@
+import { cmdRecipeEnableParsed } from "../recipes.js";
+export const recipesEnableSpec = {
+    id: ["recipes", "enable"],
+    group: "Recipes",
+    summary: "Enable an installed project overlay for the current project.",
+    args: [{ name: "id", required: true, valueHint: "<recipe-id>" }],
+    examples: [{ cmd: "agentplane recipes enable tdd", why: "Activate an installed overlay." }],
+    parse: (raw) => ({ id: String(raw.args.id ?? "").trim() }),
+};
+export const runRecipesEnable = (ctx, parsed) => cmdRecipeEnableParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: parsed.id });

package/dist/commands/recipes/explain-active.command.d.ts

@@ -0,0 +1,5 @@
+import type { CommandHandler, CommandSpec } from "../../cli/spec/spec.js";
+export type RecipesExplainActiveParsed = Record<string, never>;
+export declare const recipesExplainActiveSpec: CommandSpec<RecipesExplainActiveParsed>;
+export declare const runRecipesExplainActive: CommandHandler<RecipesExplainActiveParsed>;
+//# sourceMappingURL=explain-active.command.d.ts.map

package/dist/commands/recipes/explain-active.command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explain-active.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain-active.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAI1E,MAAM,MAAM,0BAA0B,GAAG,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AAE/D,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,0BAA0B,CAQ5E,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC,0BAA0B,CACC,CAAC"}

package/dist/commands/recipes/explain-active.command.js

@@ -0,0 +1,11 @@
+import { cmdRecipeExplainActiveParsed } from "../recipes.js";
+export const recipesExplainActiveSpec = {
+    id: ["recipes", "explain-active"],
+    group: "Recipes",
+    summary: "Print the compiled active overlay bundle.",
+    examples: [
+        { cmd: "agentplane recipes explain-active", why: "Inspect compiled overlay runtime data." },
+    ],
+    parse: () => ({}),
+};
+export const runRecipesExplainActive = (ctx) => cmdRecipeExplainActiveParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride });

package/dist/commands/recipes/explain.command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAOhE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACiB,CAAC"}
+{"version":3,"file":"explain.command.d.ts","sourceRoot":"","sources":["../../../src/commands/recipes/explain.command.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAG1E,MAAM,MAAM,oBAAoB,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAElD,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,oBAAoB,CAShE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,oBAAoB,CACiB,CAAC"}

package/dist/commands/recipes/explain.command.js

@@ -2,9 +2,11 @@ import { cmdRecipeExplainParsed } from "../recipes.js";
 export const recipesExplainSpec = {
     id: ["recipes", "explain"],
     group: "Recipes",
-    summary: "Show detailed info for an installed recipe.",
+    summary: "Show detailed info for a vendored recipe.",
     args: [{ name: "id", required: true, valueHint: "<id>" }],
-    examples: [{ cmd: "agentplane recipes explain viewer", why: "Show detailed recipe info." }],
+    examples: [
+        { cmd: "agentplane recipes explain viewer", why: "Show detailed project-local recipe info." },
+    ],
     parse: (raw) => ({ id: String(raw.args.id ?? "") }),
 };
 export const runRecipesExplain = (ctx, p) => cmdRecipeExplainParsed({ cwd: ctx.cwd, rootOverride: ctx.rootOverride, id: p.id });

package/dist/commands/recipes/impl/apply.d.ts

@@ -1,4 +1,4 @@
-import type { RecipeConflictMode, RecipeManifest } from "./types.js";
+import { type RecipeConflictMode, type RecipeManifest } from "@agentplaneorg/recipes";
 export declare function moveRecipeDir(opts: {
     from: string;
     to: string;

package/dist/commands/recipes/impl/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../../src/commands/recipes/impl/apply.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErE,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAkBD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4BhB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAgDhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../../../src/commands/recipes/impl/apply.ts"],"names":[],"mappings":"AAGA,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AAWhC,wBAAsB,aAAa,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAarF;AAyBD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmChB;AAED,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,kBAAkB,CAAC;CAChC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuDhB;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,QAAQ,EAAE,cAAc,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BhB"}

package/dist/commands/recipes/impl/apply.js

@@ -1,5 +1,6 @@
-import { cp, mkdir, readFile, readdir, rename, rm } from "node:fs/promises";
+import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { normalizeAgentId, readScenarioDefinition, } from "@agentplaneorg/recipes";
 import { exitCodeForError } from "../../../cli/exit-codes.js";
 import { fileExists, getPathKind } from "../../../cli/fs-utils.js";
 import { invalidFieldMessage, missingFileMessage } from "../../../cli/output.js";
@@ -7,8 +8,6 @@ import { CliError } from "../../../shared/errors.js";
 import { isRecord } from "../../../shared/guards.js";
 import { writeJsonStableIfChanged } from "../../../shared/write-if-changed.js";
 import { RECIPES_SCENARIOS_DIR_NAME, RECIPES_SCENARIOS_INDEX_NAME } from "./constants.js";
-import { readScenarioDefinition } from "./scenario.js";
-import { normalizeAgentId } from "./normalize.js";
 export async function moveRecipeDir(opts) {
     await mkdir(path.dirname(opts.to), { recursive: true });
     try {
@@ -24,22 +23,29 @@ export async function moveRecipeDir(opts) {
         throw err;
     }
 }
-async function readRecipeJsonObject(recipeDir, relativePath, label) {
+function isMarkdownAssetPath(relativePath) {
+    const normalized = relativePath.trim().toLowerCase();
+    return normalized.endsWith(".md") || normalized.endsWith(".markdown");
+}
+async function readRecipeMarkdownAsset(recipeDir, relativePath, label) {
     const sourcePath = path.join(recipeDir, relativePath);
     if (!(await fileExists(sourcePath))) {
         throw new Error(missingFileMessage(label, relativePath));
     }
-    const raw = JSON.parse(await readFile(sourcePath, "utf8"));
-    if (!isRecord(raw)) {
-        throw new Error(invalidFieldMessage(label, "JSON object", relativePath));
+    if (!isMarkdownAssetPath(relativePath)) {
+        throw new Error(invalidFieldMessage(label, "markdown file (*.md)", relativePath));
+    }
+    const raw = await readFile(sourcePath, "utf8");
+    if (!raw.trim()) {
+        throw new Error(invalidFieldMessage(label, "non-empty markdown document", relativePath));
     }
 }
 export async function validateRecipeAssets(opts) {
     for (const skill of opts.manifest.skills ?? []) {
-        await readRecipeJsonObject(opts.recipeDir, skill.file, "recipe skill file");
+        await readRecipeMarkdownAsset(opts.recipeDir, skill.file, "recipe skill file");
     }
     for (const agent of opts.manifest.agents ?? []) {
-        await readRecipeJsonObject(opts.recipeDir, agent.file, "recipe agent file");
+        await readRecipeMarkdownAsset(opts.recipeDir, agent.file, "recipe agent file");
     }
     for (const tool of opts.manifest.tools ?? []) {
         const entrypointPath = path.join(opts.recipeDir, tool.entrypoint);
@@ -47,6 +53,12 @@ export async function validateRecipeAssets(opts) {
             throw new Error(missingFileMessage("recipe tool entrypoint", tool.entrypoint));
         }
     }
+    for (const prompt of opts.manifest.prompts ?? []) {
+        const sourcePath = path.join(opts.recipeDir, prompt.file);
+        if (!(await fileExists(sourcePath))) {
+            throw new Error(missingFileMessage("overlay prompt file", prompt.file));
+        }
+    }
     for (const scenario of opts.manifest.scenarios ?? []) {
         const sourcePath = path.join(opts.recipeDir, scenario.file);
         if (!(await fileExists(sourcePath))) {
@@ -75,13 +87,16 @@ export async function applyRecipeAgents(opts) {
         if (!(await fileExists(sourcePath))) {
             throw new Error(missingFileMessage("recipe agent file", rawFile));
         }
-        const rawAgent = JSON.parse(await readFile(sourcePath, "utf8"));
-        if (!isRecord(rawAgent)) {
-            throw new Error(invalidFieldMessage("recipe agent file", "JSON object", rawFile));
+        if (!isMarkdownAssetPath(rawFile)) {
+            throw new Error(invalidFieldMessage("recipe agent file", "markdown file (*.md)", rawFile));
+        }
+        const rawAgent = await readFile(sourcePath, "utf8");
+        if (!rawAgent.trim()) {
+            throw new Error(invalidFieldMessage("recipe agent file", "non-empty markdown document", rawFile));
         }
         const baseId = `${opts.manifest.id}__${agentId}`;
         let targetId = baseId;
-        let targetPath = path.join(agentsDir, `${targetId}.json`);
+        let targetPath = path.join(agentsDir, `${targetId}.md`);
         if (await getPathKind(targetPath)) {
             if (opts.onConflict === "fail") {
                 throw new CliError({
@@ -94,13 +109,16 @@ export async function applyRecipeAgents(opts) {
                 let counter = 1;
                 while (await getPathKind(targetPath)) {
                     targetId = `${baseId}__${counter}`;
-                    targetPath = path.join(agentsDir, `${targetId}.json`);
+                    targetPath = path.join(agentsDir, `${targetId}.md`);
                     counter += 1;
                 }
             }
         }
-        rawAgent.id = targetId;
-        await writeJsonStableIfChanged(targetPath, rawAgent);
+        const namespacedHeader = `# Agent: ${targetId}\n\n`;
+        const content = rawAgent.startsWith("# Agent:")
+            ? rawAgent
+            : `${namespacedHeader}${rawAgent.trimStart()}`;
+        await writeFile(targetPath, content, "utf8");
     }
 }
 export async function applyRecipeScenarios(opts) {

package/dist/commands/recipes/impl/commands/active.d.ts

@@ -0,0 +1,6 @@
+export declare function cmdRecipeActiveParsed(opts: {
+    cwd: string;
+    rootOverride?: string;
+    full: boolean;
+}): Promise<number>;
+//# sourceMappingURL=active.d.ts.map

package/dist/commands/recipes/impl/commands/active.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"active.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/active.ts"],"names":[],"mappings":"AAWA,wBAAsB,qBAAqB,CAAC,IAAI,EAAE;IAChD,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,OAAO,CAAC;CACf,GAAG,OAAO,CAAC,MAAM,CAAC,CAqClB"}

package/dist/commands/recipes/impl/commands/active.js

@@ -0,0 +1,47 @@
+import { resolveProject } from "@agentplaneorg/core";
+import { mapCoreError } from "../../../../cli/error-map.js";
+import { createCliEmitter, emptyStateMessage } from "../../../../cli/output.js";
+import { CliError } from "../../../../shared/errors.js";
+import { readActiveRecipeIds } from "../overlay-project.js";
+import { readProjectInstalledRecipes } from "../project-installed-recipes.js";
+const output = createCliEmitter();
+export async function cmdRecipeActiveParsed(opts) {
+    try {
+        const project = await resolveProject({
+            cwd: opts.cwd,
+            rootOverride: opts.rootOverride ?? null,
+        });
+        const [activeIds, installed] = await Promise.all([
+            readActiveRecipeIds(project),
+            readProjectInstalledRecipes(project),
+        ]);
+        const active = activeIds
+            .map((id) => installed.recipes.find((entry) => entry.id === id))
+            .filter(Boolean);
+        if (active.length === 0) {
+            output.line(emptyStateMessage("active overlays"));
+            return 0;
+        }
+        if (opts.full) {
+            output.json({
+                schema_version: 1,
+                active: active.map((entry) => ({
+                    id: entry.id,
+                    version: entry.version,
+                    kind: entry.manifest.kind,
+                    summary: entry.manifest.summary,
+                })),
+            });
+            return 0;
+        }
+        for (const entry of active) {
+            output.line(`${entry.id}@${entry.version} [${entry.manifest.kind}]`);
+        }
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof CliError)
+            throw err;
+        throw mapCoreError(err, { command: "recipes active", root: opts.rootOverride ?? null });
+    }
+}

package/dist/commands/recipes/impl/commands/add.d.ts

@@ -0,0 +1,8 @@
+export declare function cmdRecipeAddParsed(opts: {
+    cwd: string;
+    rootOverride?: string;
+    recipeRef: string;
+    mode?: "copy" | "link";
+    activate?: boolean;
+}): Promise<number>;
+//# sourceMappingURL=add.d.ts.map

package/dist/commands/recipes/impl/commands/add.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"add.d.ts","sourceRoot":"","sources":["../../../../../src/commands/recipes/impl/commands/add.ts"],"names":[],"mappings":"AAuCA,wBAAsB,kBAAkB,CAAC,IAAI,EAAE;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmFlB"}