@sitecoreai-labs/sitecoreai-cli 0.2.0 → 0.2.1

package/dist/mcp/tools/brief-recipe.js

@@ -2,19 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerBriefRecipeTools = void 0;
 /**
- * Brief-type recipe surface — the MCP projection of the `brief-type`
- * recipe kind. Two workflow-shaped tools:
+ * Brief recipe surface — the MCP projection of both brief recipe kinds.
+ * Two workflow-shaped tools, each discriminating on `kind`:
  *
  *   - `brief_recipe_inspect` — read. `verb=pull` captures a live brief
- *     type as a declarative recipe; `verb=diff` plans the convergence of
- *     a brief type onto a given recipe. Neither writes.
+ *     type OR brief instance as a declarative recipe; `verb=diff` plans
+ *     the convergence of the named resource onto a given recipe.
  *
- *   - `brief_recipe_push` — write. Converges a brief type onto a recipe,
- *     gated by `allowWrite`; `whatIf` returns the plan without writing.
+ *   - `brief_recipe_push` — write. Converges a brief type or brief
+ *     instance onto a recipe, gated by `allowWrite`; `whatIf` returns
+ *     the plan without writing.
  *
- * The `recipe` input field IS `BriefTypeRecipeSchema` — the single
- * source of truth feeds the agent-facing tool surface for free. See
- * docs/recipe-sync-architecture.md.
+ * `kind: 'brief-type'` is the legacy default (kept for back-compat with
+ * the pre-instance surface). `kind: 'brief'` operates on populated
+ * brief instances. The matching recipe schema becomes the input shape
+ * for `recipe` automatically — the schema is the single source of truth.
+ *
+ * See docs/recipe-sync-architecture.md.
  */
 const zod_1 = require("zod");
 const recipe_1 = require("../../brief/recipe");
@@ -31,53 +35,81 @@ const planSummaryText = (plan) => {
     const tally = (0, sync_1.summarizePlan)(plan);
     return `Plan: ${tally.create} create, ${tally.update} update, ${tally.delete} delete, ${tally.noop} unchanged.`;
 };
+/** Map the MCP `kind` discriminator to the underlying `RecipeKind`. */
+const recipeKindFor = (kind) => {
+    const resolved = kind ?? "brief-type";
+    return resolved === "brief"
+        ? recipe_1.briefInstanceKind
+        : recipe_1.briefTypeKind;
+};
 const registerBriefRecipeTools = (registry) => {
     registry.registerTool({
         name: "brief_recipe_inspect",
         description: descriptions_1.TOOL_DESCRIPTIONS.brief_recipe_inspect,
         auth: "read",
         annotations: {
-            title: "Pull or diff a brief type as a declarative recipe",
+            title: "Pull or diff a brief type or brief instance as a declarative recipe",
             readOnlyHint: true,
             destructiveHint: false,
             openWorldHint: true,
         },
         inputSchema: {
+            kind: zod_1.z
+                .enum(["brief-type", "brief"])
+                .default("brief-type")
+                .describe("Which recipe kind to operate on. 'brief-type' (default — the schema template) or 'brief' (a populated brief instance)."),
             verb: zod_1.z
                 .enum(["pull", "diff"])
-                .describe("pull: capture the live brief type named `name` as a recipe. diff: compare `recipe` against the live brief type and return the plan."),
-            name: zod_1.z.string().optional().describe("Brief type codename. Required for verb='pull'."),
-            recipe: recipe_1.briefTypeKind.schema
+                .describe("pull: capture the live resource named `name` as a recipe. diff: compare `recipe` against the live resource and return the plan."),
+            name: zod_1.z
+                .string()
+                .optional()
+                .describe("Brief-type codename or brief display name. Required for verb='pull'."),
+            recipe: zod_1.z
+                .union([recipe_1.briefTypeKind.schema, recipe_1.briefInstanceKind.schema])
                 .optional()
-                .describe("A brief-type recipe. Required for verb='diff'."),
+                .describe("A brief-type recipe or brief-instance recipe (matching `kind`). Required for verb='diff'."),
             ...common_1.environmentBindingShape,
         },
         handler: async (input, context) => {
             const ctx = syncContextFrom(context, input.environmentName);
+            const kind = recipeKindFor(input.kind);
+            const humanKind = input.kind === "brief" ? "brief" : "brief type";
             if (input.verb === "pull") {
                 if (!input.name) {
                     throw (0, errors_1.createScaiError)("verb='pull' requires `name`.", "INPUT_INVALID");
                 }
-                const recipe = await (0, sync_1.syncPull)(recipe_1.briefTypeKind, { kind: recipe_1.briefTypeKind.name, id: input.name }, ctx);
+                const recipe = await (0, sync_1.syncPull)(kind, { kind: kind.name, id: input.name }, ctx);
                 return {
                     content: [
                         {
                             type: "text",
                             text: recipe
-                                ? `Captured "${input.name}" as a recipe.`
-                                : `No brief type named "${input.name}".`,
+                                ? `Captured ${humanKind} "${input.name}" as a recipe.`
+                                : `No ${humanKind} named "${input.name}".`,
                         },
                     ],
-                    structuredContent: { verb: input.verb, found: recipe !== null, recipe },
+                    structuredContent: {
+                        kind: input.kind ?? "brief-type",
+                        verb: input.verb,
+                        found: recipe !== null,
+                        recipe,
+                    },
                 };
             }
             if (!input.recipe) {
                 throw (0, errors_1.createScaiError)("verb='diff' requires `recipe`.", "INPUT_INVALID");
             }
-            const plan = await (0, sync_1.syncDiff)(recipe_1.briefTypeKind, input.recipe, { kind: recipe_1.briefTypeKind.name, id: input.recipe.name }, ctx);
+            const recipe = input.recipe;
+            const plan = await (0, sync_1.syncDiff)(kind, recipe, { kind: kind.name, id: recipe.name }, ctx);
             return {
                 content: [{ type: "text", text: planSummaryText(plan) }],
-                structuredContent: { verb: input.verb, plan, summary: (0, sync_1.summarizePlan)(plan) },
+                structuredContent: {
+                    kind: input.kind ?? "brief-type",
+                    verb: input.verb,
+                    plan,
+                    summary: (0, sync_1.summarizePlan)(plan),
+                },
             };
         },
     });
@@ -86,13 +118,19 @@ const registerBriefRecipeTools = (registry) => {
         description: descriptions_1.TOOL_DESCRIPTIONS.brief_recipe_push,
         auth: "write",
         annotations: {
-            title: "Push a brief-type recipe — converge the type onto the recipe",
+            title: "Push a brief-type or brief recipe — converge the resource onto the recipe",
             readOnlyHint: false,
             destructiveHint: true,
             openWorldHint: true,
         },
         inputSchema: {
-            recipe: recipe_1.briefTypeKind.schema.describe("The brief-type recipe to converge onto. The brief type is identified by `recipe.name`."),
+            kind: zod_1.z
+                .enum(["brief-type", "brief"])
+                .default("brief-type")
+                .describe("Which recipe kind to push. 'brief-type' (default — the schema template) or 'brief' (a populated brief instance)."),
+            recipe: zod_1.z
+                .union([recipe_1.briefTypeKind.schema, recipe_1.briefInstanceKind.schema])
+                .describe("The recipe to converge onto. Schema must match `kind`. The resource is identified by `recipe.name`."),
             prune: zod_1.z
                 .boolean()
                 .default(false)
@@ -103,14 +141,20 @@ const registerBriefRecipeTools = (registry) => {
         },
         handler: async (input, context, extra) => {
             const ctx = syncContextFrom(context, input.environmentName, extra.signal);
+            const kind = recipeKindFor(input.kind);
+            const recipe = input.recipe;
             const mode = input.whatIf ? "what-if" : "apply";
-            const outcome = await (0, sync_1.syncPush)(recipe_1.briefTypeKind, input.recipe, { kind: recipe_1.briefTypeKind.name, id: input.recipe.name }, ctx, { mode, prune: input.prune });
+            const outcome = await (0, sync_1.syncPush)(kind, recipe, { kind: kind.name, id: recipe.name }, ctx, {
+                mode,
+                prune: input.prune,
+            });
             const text = outcome.result
                 ? `Applied ${outcome.result.applied.length} change(s); ${outcome.result.skipped.length} skipped.`
                 : planSummaryText(outcome.plan);
             return {
                 content: [{ type: "text", text }],
                 structuredContent: {
+                    kind: input.kind ?? "brief-type",
                     mode,
                     plan: outcome.plan,
                     summary: (0, sync_1.summarizePlan)(outcome.plan),

package/dist/mcp/tools/brief.js

@@ -186,21 +186,21 @@ const registerBriefTools = (registry) => {
                 .describe("Which Brief resource the verb targets. 'brief-type' supports create/update/delete; 'brief' supports set-status/delete; 'comment' supports create."),
             verb: zod_1.z
                 .enum(["create", "update", "delete", "set-status"])
-                .describe("Mutation verb. brief-type: create (POST), update (PUT-replace), delete (irreversible). brief: set-status, delete. comment: create."),
+                .describe("Mutation verb. brief-type: create (POST), update (PUT-replace), delete (irreversible). brief: create (POST), update (partial PUT), set-status, delete. comment: create."),
             briefTypeId: zod_1.z
                 .string()
                 .uuid()
                 .optional()
-                .describe("Brief type UUID. Required for brief-type verb='update' and verb='delete'."),
+                .describe("Brief type UUID. Required for brief-type verb='update' and verb='delete', and for brief verb='create' (the type to build the brief against)."),
             briefId: zod_1.z
                 .string()
                 .uuid()
                 .optional()
-                .describe("Brief UUID. Required for resource='brief' verb='set-status'."),
+                .describe("Brief UUID. Required for resource='brief' verbs 'update', 'set-status', and 'delete'."),
             status: zod_1.z
                 .enum(["Draft", "InReview", "Approved", "Canceled", "Archived"])
                 .optional()
-                .describe("Target brief status for verb='set-status'. Wire form — 'InReview' is the 'In Review' UI label. A brief must leave 'Draft' before it can be linked to a campaign."),
+                .describe("Target brief status. Required for verb='set-status'; optional on brief 'create'/'update' (defaults to server 'Draft' on create). Wire form — 'InReview' is the 'In Review' UI label. A brief must leave 'Draft' before it can be linked to a campaign."),
             commentText: zod_1.z
                 .string()
                 .optional()
@@ -221,7 +221,19 @@ const registerBriefTools = (registry) => {
                     .describe("Field definitions (RichText | DateTime | Timeline | Budget). Use brief_inspect verb='type' on an existing type for a worked example."),
             })
                 .optional()
-                .describe("Full BriefType body for verb='create' or verb='update'. Required on writes; ignored on delete."),
+                .describe("Full BriefType body for resource='brief-type' verb='create' or verb='update'. Required on brief-type writes; ignored on delete."),
+            brief: zod_1.z
+                .object({
+                name: zod_1.z.string().min(1).describe("Brief display name."),
+                locale: zod_1.z.string().optional().describe("BCP-47-ish locale, e.g. 'en-us'."),
+                fields: zod_1.z
+                    .record(zod_1.z.string(), zod_1.z.unknown())
+                    .optional()
+                    .describe("Field values keyed by BriefField.name; the per-field shape follows the brief type's field definitions."),
+                isTemplate: zod_1.z.boolean().optional().describe("Whether the brief is a template."),
+            })
+                .optional()
+                .describe("Brief body. Required for resource='brief' verb='create' (with `briefTypeId`); optional for verb='update' (any subset of name/locale/fields/isTemplate plus the top-level `status`)."),
             ...common_1.environmentBindingShape,
             ...common_1.allowWriteShape,
             ...common_1.whatIfShape,
@@ -230,6 +242,71 @@ const registerBriefTools = (registry) => {
             const taskOpts = baseTaskOptions(context.configPath, input.environmentName ?? context.envName);
             const whatIf = input.whatIf;
             if (input.resource === "brief") {
+                if (input.verb === "create") {
+                    if (!input.brief) {
+                        throw (0, errors_1.createScaiError)("verb='create' on resource='brief' requires `brief`.", "INPUT_INVALID");
+                    }
+                    if (!input.briefTypeId) {
+                        throw (0, errors_1.createScaiError)("verb='create' on resource='brief' requires `briefTypeId`.", "INPUT_INVALID");
+                    }
+                    const createInput = {
+                        name: input.brief.name,
+                        briefTypeId: input.briefTypeId,
+                        ...(input.brief.locale !== undefined && { locale: input.brief.locale }),
+                        ...(input.brief.fields !== undefined && { fields: input.brief.fields }),
+                        ...(input.brief.isTemplate !== undefined && { isTemplate: input.brief.isTemplate }),
+                    };
+                    const result = await (0, tasks_1.runBriefCreate)({
+                        ...taskOpts,
+                        input: createInput,
+                        whatIf,
+                    });
+                    const isPlan = "plan" in result;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: isPlan
+                                    ? `Plan: create brief '${input.brief.name}'.`
+                                    : `Created brief '${input.brief.name}'.`,
+                            },
+                        ],
+                        structuredContent: { resource: input.resource, verb: input.verb, result },
+                    };
+                }
+                if (input.verb === "update") {
+                    if (!input.briefId) {
+                        throw (0, errors_1.createScaiError)("verb='update' on resource='brief' requires `briefId`.", "INPUT_INVALID");
+                    }
+                    const patch = {
+                        ...(input.brief?.name !== undefined && { name: input.brief.name }),
+                        ...(input.brief?.locale !== undefined && { locale: input.brief.locale }),
+                        ...(input.brief?.fields !== undefined && { fields: input.brief.fields }),
+                        ...(input.brief?.isTemplate !== undefined && { isTemplate: input.brief.isTemplate }),
+                        ...(input.status !== undefined && { status: input.status }),
+                    };
+                    if (Object.keys(patch).length === 0) {
+                        throw (0, errors_1.createScaiError)("verb='update' on resource='brief' requires at least one field in `brief` or a top-level `status`.", "INPUT_INVALID");
+                    }
+                    const result = await (0, tasks_1.runBriefUpdate)({
+                        ...taskOpts,
+                        briefId: input.briefId,
+                        patch,
+                        whatIf,
+                    });
+                    const isPlan = "plan" in result;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: isPlan
+                                    ? `Plan: update brief ${input.briefId} (${Object.keys(patch).join(", ")}).`
+                                    : `Updated brief ${input.briefId}.`,
+                            },
+                        ],
+                        structuredContent: { resource: input.resource, verb: input.verb, result },
+                    };
+                }
                 if (input.verb === "set-status") {
                     if (!input.briefId) {
                         throw (0, errors_1.createScaiError)("verb='set-status' requires `briefId`.", "INPUT_INVALID");
@@ -277,7 +354,7 @@ const registerBriefTools = (registry) => {
                         structuredContent: { resource: input.resource, verb: input.verb, result },
                     };
                 }
-                throw (0, errors_1.createScaiError)("resource='brief' supports verb='set-status' and verb='delete'.", "INPUT_INVALID");
+                throw (0, errors_1.createScaiError)("resource='brief' supports verbs 'create', 'update', 'set-status', and 'delete'.", "INPUT_INVALID");
             }
             if (input.resource === "comment") {
                 if (input.verb !== "create") {

package/dist/sync/aggregate-kinds.js

@@ -29,4 +29,5 @@ const recipe_2 = require("../brief/recipe");
 exports.ENUMERABLE_RECIPE_KINDS = [
     recipe_1.brandKitKind,
     recipe_2.briefTypeKind,
+    recipe_2.briefInstanceKind,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sitecoreai-labs/sitecoreai-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "SitecoreAI developer toolkit — a native TypeScript CLI, SDK, and MCP server for deploy, serialization, recipes, publishing, and content operations.",
   "license": "MIT",
   "type": "commonjs",