blockend-cli 2.1.1 → 2.2.0

package/README.md

@@ -48,26 +48,35 @@ Detects the framework, language, package manager, Redis, and import alias, then
 npx blockend-cli add [block] [options]
 ```
 
-| Option    | Alias | Description                                                  |
-| --------- | ----- | ------------------------------------------------------------ |
-| `[block]` |       | Registry key, such as `rate-limiter` or `logger`.            |
-| `--yes`   | `-y`  | Skip prompts, install dependencies, and overwrite conflicts. |
-| `--json`  |       | Write machine-readable output.                               |
-| `--multi` | `-m`  | Select multiple blocks.                                      |
+| Option     | Alias | Description                                                  |
+| ---------- | ----- | ------------------------------------------------------------ |
+| `[block]`  |       | Registry key, such as `rate-limiter` or `logger`.            |
+| `--yes`    | `-y`  | Skip prompts, install dependencies, and overwrite conflicts. |
+| `--json`   |       | Write machine-readable output.                               |
+| `--multi`  | `-m`  | Select multiple blocks.                                      |
+| `--recipe` |       | Add every block in a published recipe, in integration order. |
 
 Without a block name, the CLI opens a selector. For blocks with storage options, it asks for a variant. In interactive mode, `includeRedis: true` selects the Redis variant when one exists. With `--yes`, it selects memory when available, otherwise the first variant.
 
 `add --yes` without a block name is an error.
 
+`--recipe` installs a curated, ordered stack from the registry in one command:
+
+```bash
+npx blockend-cli add --recipe authenticated-api
+```
+
+It installs the recipe's required blocks in integration order. Optional blocks are offered interactively and skipped with `--yes` or `--json`. `--recipe` cannot be combined with `--multi` or a positional block name.
+
 Dependency installation runs `pnpm add` when `packageManager` is `pnpm`, and `npm install` for every other value. Yarn and bun projects should decline the install prompt and add the listed packages themselves.
 
 ### `list`
 
 ```bash
-npx blockend-cli list [--json]
+npx blockend-cli list [--json] [--recipes]
 ```
 
-Lists blocks compatible with the framework in `blockend.json`.
+Lists blocks compatible with the framework in `blockend.json`. With `--recipes`, it lists published recipes instead and does not require `blockend.json`.
 
 ### `detect`
 

package/dist/block-install/index.d.ts

@@ -1,9 +1,10 @@
-export type { AdapterConfig, AppliedBlock, ApplyBlockOptions, AssetMapping, AvailableBlock, BlockPlan, BlockPlanError, BlockPlanErrorCode, BlockPlanResult, BlockManifest, BlockendConfig, EnvironmentConfig, FrameworkName, InstalledBlockRecord, PlanBlockOptions, PreviewBlockOptions, PreviewFile, RegistryManifest, RegistrySource } from "./types.js";
+export type { AdapterConfig, AppliedBlock, ApplyBlockOptions, AssetMapping, AvailableBlock, BlockPlan, BlockPlanError, BlockPlanErrorCode, BlockPlanResult, BlockManifest, BlockendConfig, EnvironmentConfig, FrameworkName, InstalledBlockRecord, PlanBlockOptions, PreviewBlockOptions, PreviewFile, Recipe, RecipeCollection, RegistryManifest, RegistrySource } from "./types.js";
 export { createGitHubRegistrySource, createStaticRegistrySource, loadRegistry, type GitHubRegistrySourceOptions } from "./registry.js";
 export { listAvailableBlocks, planBlock } from "./plan.js";
 export { previewBlock } from "./preview.js";
 export { applyBlock } from "./apply.js";
 export { findUp } from "./config.js";
+export { findRecipe, loadRecipeCollection, orderRecipeBlocks } from "./recipes.js";
 export { resolvePreferredVariant, selectVariant } from "./variants.js";
 export { getMissingDependencies, getVersionConflicts, parseDepSpec, semverSatisfies } from "./deps.js";
 export { rewriteFileImports } from "./imports.js";

package/dist/block-install/recipes.d.ts

@@ -0,0 +1,6 @@
+import { type Recipe, type RecipeCollection } from "@blockend/registry";
+import type { RegistrySource } from "./types.js";
+export declare const RECIPE_COLLECTION_PATH = "registry/recipes.json";
+export declare function loadRecipeCollection(source: RegistrySource): Promise<RecipeCollection>;
+export declare function findRecipe(collection: RecipeCollection, slug: string): Recipe | undefined;
+export declare function orderRecipeBlocks(recipe: Recipe, selectedOptional?: string[]): string[];

package/dist/block-install/types.d.ts

@@ -1,10 +1,12 @@
-import type { AdapterConfig as RegistryAdapterConfig, AssetMapping as RegistryAssetMapping, BlockManifest as RegistryBlockManifest, EnvironmentConfig as RegistryEnvironmentConfig, FrameworkName as RegistryFrameworkName, RegistryManifest as RegistryManifestType } from "@blockend/registry";
+import type { AdapterConfig as RegistryAdapterConfig, AssetMapping as RegistryAssetMapping, BlockManifest as RegistryBlockManifest, EnvironmentConfig as RegistryEnvironmentConfig, FrameworkName as RegistryFrameworkName, Recipe as RegistryRecipe, RecipeCollection as RegistryRecipeCollection, RegistryManifest as RegistryManifestType } from "@blockend/registry";
 export type AssetMapping = RegistryAssetMapping;
 export type AdapterConfig = RegistryAdapterConfig;
 export type EnvironmentConfig = RegistryEnvironmentConfig;
 export type FrameworkName = RegistryFrameworkName;
 export type BlockManifest = RegistryBlockManifest;
 export type RegistryManifest = RegistryManifestType;
+export type Recipe = RegistryRecipe;
+export type RecipeCollection = RegistryRecipeCollection;
 export interface RegistrySource {
     fetchRegistry(): Promise<RegistryManifest>;
     fetchFile(sourcePath: string): Promise<string>;

package/dist/commands/add.d.ts

@@ -2,4 +2,5 @@ export declare function addCommand(blockName: string | undefined, options?: {
     yes?: boolean;
     json?: boolean;
     multi?: boolean;
+    recipe?: string;
 }): Promise<void>;

package/dist/commands/list.d.ts

@@ -1,3 +1,4 @@
 export declare function listCommand(options?: {
     json?: boolean;
+    recipes?: boolean;
 }): Promise<void>;

package/dist/index.js

@@ -195,6 +195,17 @@ ${formatIssues(result.error.issues)}`,
   }
   return result.data;
 }
+function parseRecipeCollection(input) {
+  const result = RecipeCollectionSchema.safeParse(input);
+  if (!result.success) {
+    throw new RegistryParseError(
+      `Invalid recipe collection:
+${formatIssues(result.error.issues)}`,
+      result.error.issues
+    );
+  }
+  return result.data;
+}
 
 // src/block-install/registry.ts
 var DEFAULT_REPO_OWNER = "codewithnuh";
@@ -534,6 +545,32 @@ async function applyBlock(plan, options) {
   };
 }
 
+// src/block-install/recipes.ts
+var RECIPE_COLLECTION_PATH = "registry/recipes.json";
+async function loadRecipeCollection(source) {
+  const raw = await source.fetchFile(RECIPE_COLLECTION_PATH);
+  try {
+    return parseRecipeCollection(JSON.parse(raw));
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`Recipe collection is not valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+function findRecipe(collection, slug) {
+  return collection.recipes.find((recipe) => recipe.slug === slug);
+}
+function orderRecipeBlocks(recipe, selectedOptional = []) {
+  const selected = /* @__PURE__ */ new Set([...recipe.includedBlocks, ...selectedOptional]);
+  const ordered = recipe.integrationOrder.filter((slug) => selected.has(slug));
+  const placed = new Set(ordered);
+  const missing = [...recipe.includedBlocks, ...recipe.optionalBlocks].filter(
+    (slug) => selected.has(slug) && !placed.has(slug)
+  );
+  return [...ordered, ...missing];
+}
+
 // src/block-install/deps.ts
 function parseDepSpec(dep) {
   const atIndex = dep.lastIndexOf("@");
@@ -620,7 +657,7 @@ function failureMessage(code, blockName) {
   if (code === "no-adapter") return `No adapter for "${blockName}"`;
   return `No variants for "${blockName}"`;
 }
-async function addSingleBlock(targetBlock, context) {
+async function addSingleBlock(targetBlock, context, options = {}) {
   const { yes = false, json = false } = context.options;
   const {
     registry,
@@ -635,9 +672,12 @@ async function addSingleBlock(targetBlock, context) {
     rewriteStrategy
   } = context;
   const s = spinner();
+  const reportError = (message) => {
+    if (!options.suppressErrorOutput) outputError(json, message);
+  };
   const initialPlan = await planBlock(registry, targetBlock, envKey);
   if (!initialPlan.ok) {
-    outputError(json, initialPlan.error.message);
+    reportError(initialPlan.error.message);
     return {
       success: false,
       filesWritten: [],
@@ -666,7 +706,7 @@ async function addSingleBlock(targetBlock, context) {
       variant: selectedVariant
     });
     if (!selectedPlan.ok) {
-      outputError(json, selectedPlan.error.message);
+      reportError(selectedPlan.error.message);
       return {
         success: false,
         filesWritten: [],
@@ -678,7 +718,7 @@ async function addSingleBlock(targetBlock, context) {
   const targetFolder = path5.resolve(blocksRootAbsolute, targetBlock);
   const packageJsonPath = await findUp("package.json", rootDir);
   if (!packageJsonPath) {
-    outputError(json, "Could not locate package.json.");
+    reportError("Could not locate package.json.");
     return { success: false, filesWritten: [], message: "package.json not found" };
   }
   const packageJsonDir = dirname4(packageJsonPath);
@@ -686,7 +726,7 @@ async function addSingleBlock(targetBlock, context) {
   try {
     packageJson = JSON.parse(await fs5.readFile(packageJsonPath, "utf-8"));
   } catch (err) {
-    outputError(json, "Failed to parse package.json.");
+    reportError("Failed to parse package.json.");
     if (!json) log.error(pc.dim(String(err)));
     return { success: false, filesWritten: [], message: "Failed to parse package.json" };
   }
@@ -748,7 +788,7 @@ async function addSingleBlock(targetBlock, context) {
         if (!json) {
           s.stop("Installation failed.");
           log.error(pc.dim(String(err)));
-        } else outputError(json, "Dependency installation failed.");
+        } else reportError("Dependency installation failed.");
         return { success: false, filesWritten: [], message: "Dependency installation failed" };
       }
     }
@@ -791,12 +831,64 @@ async function addSingleBlock(targetBlock, context) {
     if (!json) {
       s.stop("Failed.");
       log.error(pc.dim(String(err)));
-    } else outputError(json, "Fatal error while writing block files.");
+    } else reportError("Fatal error while writing block files.");
     return { success: false, filesWritten: [], message: `Failed to add ${targetBlock}` };
   }
 }
+async function addRecipe(recipeSlug, context) {
+  const { yes = false, json = false } = context.options;
+  const { source } = context;
+  let recipe;
+  try {
+    const collection = await loadRecipeCollection(source);
+    recipe = findRecipe(collection, recipeSlug);
+  } catch (err) {
+    outputError(json, "Failed to load the recipe collection from the registry.");
+    if (!json) log.error(pc.dim(String(err)));
+    process.exitCode = 1;
+    return;
+  }
+  if (!recipe) {
+    outputError(json, `Recipe "${recipeSlug}" not found in the registry.`);
+    process.exitCode = 1;
+    return;
+  }
+  let selectedOptional = [];
+  if (recipe.optionalBlocks.length > 0 && !yes && !json) {
+    const picked = await multiselect({
+      message: `Optional blocks to include with ${pc.cyan(recipeSlug)}:`,
+      options: recipe.optionalBlocks.map((block) => ({ value: block, label: block })),
+      required: false
+    });
+    handleCancel(picked);
+    selectedOptional = picked;
+  }
+  const blocks = orderRecipeBlocks(recipe, selectedOptional);
+  if (!json) log.info(`
+Adding ${blocks.length} block(s) from recipe "${recipe.title}"...
+`);
+  const added = [];
+  const failed = [];
+  for (const block of blocks) {
+    const result = await addSingleBlock(block, context, { suppressErrorOutput: json });
+    if (result.success) added.push(block);
+    else failed.push({ block, message: result.message });
+  }
+  if (failed.length > 0) process.exitCode = 1;
+  if (json) {
+    process.stdout.write(
+      JSON.stringify({ success: failed.length === 0, recipe: recipeSlug, blocks: added, failed }) + "\n"
+    );
+  } else {
+    outro(
+      pc.green(`
+\u2728 ${added.length} of ${blocks.length} block(s) added from "${recipe.title}"`) + (failed.length ? `
+${pc.yellow(`Skipped: ${failed.map((entry) => entry.block).join(", ")}`)}` : "")
+    );
+  }
+}
 async function addCommand(blockName, options = {}) {
-  const { yes = false, json = false, multi = false } = options;
+  const { yes = false, json = false, multi = false, recipe } = options;
   if (!json) {
     console.log("");
     intro(`${pc.bgCyan(pc.black(" blockend "))} ${pc.dim("add")}`);
@@ -852,10 +944,22 @@ async function addCommand(blockName, options = {}) {
     rewriteStrategy,
     options
   };
-  if (yes && !blockName) {
+  if (yes && !blockName && !recipe) {
     outputError(json, "Block name required with --yes. Usage: blockend add <block> --yes");
     return;
   }
+  if (recipe && multi) {
+    outputError(json, "Use either --recipe or --multi, not both.");
+    return;
+  }
+  if (recipe && blockName) {
+    outputError(json, "Provide either a block name or --recipe, not both.");
+    return;
+  }
+  if (recipe) {
+    await addRecipe(recipe, context);
+    return;
+  }
   if (multi && !blockName) {
     const available = await listAvailableBlocks(registry, envKey);
     if (available.length === 0) {
@@ -1428,8 +1532,60 @@ import fs7 from "fs/promises";
 import pc5 from "picocolors";
 import { outro as outro4, spinner as spinner3 } from "@clack/prompts";
 async function listCommand(options = {}) {
-  const { json = false } = options;
+  const { json = false, recipes: listRecipes = false } = options;
   const cwd = process.cwd();
+  const source = createGitHubRegistrySource();
+  const s = spinner3();
+  if (listRecipes) {
+    if (!json) s.start("Fetching published recipes...");
+    try {
+      const collection = await loadRecipeCollection(source);
+      if (!json) s.stop(pc5.green("\u2714 Synced published recipes."));
+      const recipes = collection.recipes.map((recipe) => ({
+        slug: recipe.slug,
+        title: recipe.title,
+        outcome: recipe.outcome,
+        includedBlocks: recipe.includedBlocks,
+        optionalBlocks: recipe.optionalBlocks
+      }));
+      if (json) {
+        process.stdout.write(JSON.stringify({ success: true, recipes }) + "\n");
+      } else {
+        console.log(`
+Published recipes:`);
+        if (recipes.length === 0) {
+          console.log(pc5.dim("  No recipes published yet."));
+        } else {
+          recipes.forEach((recipe) => {
+            console.log(`
+  ${pc5.cyan(recipe.slug)} ${pc5.dim(`\u2014 ${recipe.title}`)}`);
+            console.log(`    ${pc5.dim(recipe.outcome)}`);
+            console.log(
+              `    Blocks: ${recipe.includedBlocks.map((block) => pc5.yellow(block)).join(", ")}`
+            );
+            if (recipe.optionalBlocks.length > 0) {
+              console.log(
+                `    Optional: ${recipe.optionalBlocks.map((block) => pc5.yellow(block)).join(", ")}`
+              );
+            }
+          });
+          console.log(`
+${pc5.dim("  Add one with: blockend add --recipe <slug>")}
+`);
+        }
+      }
+    } catch (error) {
+      if (json) {
+        process.stdout.write(
+          JSON.stringify({ success: false, error: "Failed to fetch recipes from GitHub." }) + "\n"
+        );
+      } else {
+        s.stop(pc5.red("\u2716 Failed to fetch the recipe collection from GitHub."));
+        console.error(pc5.dim(String(error)));
+      }
+    }
+    return;
+  }
   const configPath = await findUp("blockend.json", cwd);
   if (!configPath) {
     if (json) {
@@ -1456,8 +1612,6 @@ async function listCommand(options = {}) {
     return;
   }
   const envKey = String(config.environment);
-  const source = createGitHubRegistrySource();
-  const s = spinner3();
   if (!json) {
     s.start("Syncing registry metadata blocks...");
   }
@@ -1557,7 +1711,7 @@ async function mcpStartCommand() {
   const server = new McpServer({
     name: "blockend",
     version: "0.1.0",
-    description: "Blockend MCP server \u2014 install production-ready backend blocks into any project"
+    description: "Blockend MCP server \u2014 install production-ready backend blocks or whole recipes into any project"
   });
   async function safeExec(command, args, options) {
     try {
@@ -1578,6 +1732,21 @@ async function mcpStartCommand() {
       return { content: [{ type: "text", text: result.text }], isError: result.isError };
     }
   );
+  server.tool(
+    "list_recipes",
+    "Lists published Blockend recipes: curated, ordered stacks of blocks with the blocks each one installs",
+    {},
+    async () => {
+      const result = await safeExec("npx", [
+        "--no-install",
+        "blockend",
+        "list",
+        "--recipes",
+        "--json"
+      ]);
+      return { content: [{ type: "text", text: result.text }], isError: result.isError };
+    }
+  );
   server.tool(
     "add_block",
     "Installs a Blockend block into a project.",
@@ -1687,6 +1856,22 @@ async function mcpStartCommand() {
       };
     }
   );
+  server.tool(
+    "add_recipe",
+    "Installs every block in a published recipe, in the recipe's integration order. Optional blocks are skipped in non-interactive mode. Use list_recipes to discover recipe slugs.",
+    {
+      recipe: z2.string().describe("Recipe slug, e.g. production-api-foundation, authenticated-api"),
+      projectPath: z2.string().describe("Absolute path to the project root where blockend should install")
+    },
+    async ({ recipe, projectPath }) => {
+      const result = await safeExec(
+        "npx",
+        ["--no-install", "blockend", "add", "--recipe", recipe, "--yes", "--json"],
+        { cwd: projectPath }
+      );
+      return { content: [{ type: "text", text: result.text }], isError: result.isError };
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }
@@ -2491,10 +2676,15 @@ var list = defineCommand({
       type: "boolean",
       default: false,
       description: "Output machine-readable blocks configuration array stream"
+    },
+    recipes: {
+      type: "boolean",
+      default: false,
+      description: "List published recipes instead of blocks"
     }
   },
   async run({ args }) {
-    await listCommand({ json: args.json });
+    await listCommand({ json: args.json, recipes: args.recipes });
   }
 });
 var add = defineCommand({
@@ -2524,10 +2714,19 @@ var add = defineCommand({
       alias: "m",
       default: false,
       description: "Select and add multiple blocks at once via interactive multiselect"
+    },
+    recipe: {
+      type: "string",
+      description: "Add every block in a published recipe, in its integration order (see 'blockend list --recipes')"
     }
   },
   async run({ args }) {
-    await addCommand(args.block, { yes: args.yes, json: args.json, multi: args.multi });
+    await addCommand(args.block, {
+      yes: args.yes,
+      json: args.json,
+      multi: args.multi,
+      recipe: args.recipe
+    });
   }
 });
 var detect = defineCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockend-cli",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Blockend CLI — shadcn/ui-style backend blocks for TypeScript. Generate production-ready rate limiting, validation, logging, and error handling as source code into Express, Fastify, Hono, or Next.js projects. You own the code. Ships an MCP server for AI coding assistants.",
   "type": "module",
   "main": "./dist/index.js",