@genrtl/grtl 0.2.0 → 0.4.0

package/README.md

@@ -1,69 +1,89 @@
-# @genrtl/grtl
-
-CLI and coding-agent integration for the GenRTL RTL engineering knowledge
-service.
-
-## Install
-
-```bash
-npm install --global @genrtl/grtl
-export GRTL_API_KEY="gtr_live_your_api_key"
-```
-
-PowerShell:
-
-```powershell
-$env:GRTL_API_KEY = "gtr_live_your_api_key"
-```
-
-## Agent Setup
-
-Install a Skill that tells the agent to call the `grtl` CLI:
+# @genrtl/grtl
+
+CLI and coding-agent integration for the GenRTL RTL engineering knowledge
+service.
+
+## Install
+
+```bash
+npm install --global @genrtl/grtl
+export GRTL_API_KEY="gtr_live_your_api_key"
+```
+
+PowerShell:
+
+```powershell
+$env:GRTL_API_KEY = "gtr_live_your_api_key"
+```
+
+## Agent Setup
+
+Install a Skill that tells the agent to call the `grtl` CLI:
+
+```bash
+grtl setup --cli --codex
+grtl setup --cli --cursor --project
+```
+
+Configure hosted MCP and install a Skill for the four MCP tools:
+
+```bash
+grtl setup --mcp --codex
+grtl setup --mcp --cursor --project
+```
+
+Without `--cli` or `--mcp`, setup asks which mode to install.
+
+For Codex, Skills are installed under `.agents/skills` for project setup or
+`~/.agents/skills` for global setup. MCP mode also updates
+`.codex/config.toml` or `~/.codex/config.toml`.
+
+The hosted MCP endpoint is:
+
+```text
+https://genrtl.com/api/mcp
+```
+
+## Knowledge Commands
+
+```bash
+grtl knowledge-search "AXI stream backpressure design"
+grtl spec2rtl-search "Design an APB register block"
+grtl spec2plan-search "Plan an APB register block implementation"
+grtl verification-search "Verify an async FIFO"
+grtl debug-search "Explain this Vivado CDC warning"
+```
+
+Use `--json` for structured output. `--type` accepts `spec2rtl`, `spec2plan`, `verification`, or `debug`; other filters include
+`--domain`, `--tool`, `--tool-version`, `--error-type`, `--severity`,
+`--interface`, `--target`, `--tag`, `--top-k`, `--min-score`, and
+`--workspace-id`.
 
-```bash
-grtl setup --cli --codex
-grtl setup --cli --cursor --project
-```
+## CBB Installation
 
-Configure hosted MCP and install a Skill for the four MCP tools:
+Install an exact reusable RTL CBB version into the current project:
 
 ```bash
-grtl setup --mcp --codex
-grtl setup --mcp --cursor --project
+grtl cbb install cbb_uart@1.2.0
+grtl cbb install cbb_uart@1.2.0 --target rtl/vendor/uart
 ```
 
-Without `--cli` or `--mcp`, setup asks which mode to install.
+The command calls the hosted `genrtl_cbb_acquire` MCP tool with
+`GRTL_API_KEY`, downloads the short-lived ZIP artifact, verifies its size and
+SHA-256, safely extracts it, and atomically installs it. The default target is
+`rtl/cbb/<cbb_id>_<version>`.
 
-For Codex, Skills are installed under `.agents/skills` for project setup or
-`~/.agents/skills` for global setup. MCP mode also updates
-`.codex/config.toml` or `~/.codex/config.toml`.
-
-The hosted MCP endpoint is:
-
-```text
-https://genrtl.com/api/mcp
-```
-
-## Knowledge Commands
-
-```bash
-grtl knowledge-search "AXI stream backpressure design"
-grtl spec2rtl-search "Design an APB register block"
-grtl verification-search "Verify an async FIFO"
-grtl debug-search "Explain this Vivado CDC warning"
-```
-
-Use `--json` for structured output. Available filters include `--type`,
-`--domain`, `--tool`, `--tool-version`, `--error-type`, `--severity`,
-`--interface`, `--target`, `--tag`, `--top-k`, `--min-score`, and
-`--workspace-id`.
+Installed packages are recorded in `.genrtl/cbb-lock.json`. Existing targets
+are left untouched unless `--force` is provided; replacement occurs only after
+the new archive has been fully verified and extracted. Use `--json` for
+machine-readable output.
 
 ## Development
-
-```bash
-pnpm install
-pnpm --filter @genrtl/grtl lint:check
-pnpm --filter @genrtl/grtl typecheck
-pnpm --filter @genrtl/grtl test
-pnpm --filter @genrtl/grtl build
-```
+
+```bash
+pnpm install
+pnpm --filter @genrtl/grtl lint:check
+pnpm --filter @genrtl/grtl typecheck
+pnpm --filter @genrtl/grtl test
+pnpm --filter @genrtl/grtl build
+```

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { Command as Command2 } from "commander";
-import pc6 from "picocolors";
+import pc7 from "picocolors";
 import figlet from "figlet";
 
 // src/commands/setup.ts
@@ -376,6 +376,7 @@ var FALLBACK_MCP = `Use GenRTL MCP tools for grounded RTL engineering knowledge.
 Choose one tool:
 - \`genrtl_knowledge_search\` for cross-domain RTL questions
 - \`genrtl_spec2rtl_search\` for requirements and RTL design
+- \`genrtl_spec2plan_search\` for implementation planning from a specification
 - \`genrtl_verification_search\` for testbenches and verification
 - \`genrtl_debug_search\` for lint, CDC, compile, synthesis, and RTL bugs
 
@@ -385,6 +386,7 @@ var FALLBACK_CLI = `Use the \`grtl\` CLI for grounded RTL engineering knowledge.
 Choose one command:
 - \`npx @genrtl/grtl@latest knowledge-search "<query>"\`
 - \`npx @genrtl/grtl@latest spec2rtl-search "<query>"\`
+- \`npx @genrtl/grtl@latest spec2plan-search "<query>"\`
 - \`npx @genrtl/grtl@latest verification-search "<query>"\`
 - \`npx @genrtl/grtl@latest debug-search "<query>"\`
 
@@ -411,6 +413,7 @@ Choose exactly one MCP tool:
 
 - \`genrtl_knowledge_search\` for cross-domain RTL questions.
 - \`genrtl_spec2rtl_search\` for requirements, protocols, control logic, or algorithm-to-RTL work.
+- \`genrtl_spec2plan_search\` for turning a specification into an actionable implementation plan.
 - \`genrtl_verification_search\` for testbenches and verification.
 - \`genrtl_debug_search\` for lint, CDC, compile, synthesis, or RTL bugs.
 
@@ -431,6 +434,7 @@ Choose exactly one command:
 
 - \`grtl knowledge-search "<query>" --json\` for cross-domain RTL questions.
 - \`grtl spec2rtl-search "<query>" --json\` for requirements, protocols, control logic, or algorithm-to-RTL work.
+- \`grtl spec2plan-search "<query>" --json\` for turning a specification into an actionable implementation plan.
 - \`grtl verification-search "<query>" --json\` for testbenches and verification.
 - \`grtl debug-search "<query>" --json\` for lint, CDC, compile, synthesis, or RTL bugs.
 
@@ -855,6 +859,9 @@ import { InvalidArgumentError } from "commander";
 import pc4 from "picocolors";
 import ora2 from "ora";
 
+// src/utils/knowledge-api.ts
+import { randomUUID } from "crypto";
+
 // src/constants.ts
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
@@ -897,7 +904,7 @@ function getStructuredMcpError(content) {
     code: typeof errorContent.code === "string" ? errorContent.code : void 0
   };
 }
-async function callGenrtlKnowledgeTool(toolName, input) {
+async function callGenrtlMcpTool(toolName, input) {
   const apiKey = getApiKey();
   if (!apiKey) {
     throw new Error("Authentication required. Set GRTL_API_KEY or GENRTL_API_KEY.");
@@ -929,14 +936,18 @@ async function callGenrtlKnowledgeTool(toolName, input) {
   if (!result) throw new Error("GenRTL MCP returned an empty result.");
   if (result.isError) {
     const structuredError = getStructuredMcpError(result.structuredContent);
-    const message = structuredError?.error || getMcpErrorMessage(result.content) || "GenRTL knowledge search failed.";
+    const message = structuredError?.error || getMcpErrorMessage(result.content) || "GenRTL MCP tool call failed.";
     throw new Error(structuredError?.code ? `${message} (${structuredError.code})` : message);
   }
   if (!result.structuredContent) {
-    throw new Error("GenRTL MCP response did not include structured knowledge results.");
+    throw new Error("GenRTL MCP response did not include structured results.");
   }
   return result.structuredContent;
 }
+async function callGenrtlKnowledgeTool(toolName, input) {
+  const requestInput = input.idempotency_key ? input : { ...input, idempotency_key: randomUUID() };
+  return callGenrtlMcpTool(toolName, requestInput);
+}
 
 // src/commands/knowledge.ts
 var isTTY = process.stdout.isTTY;
@@ -951,6 +962,11 @@ var TOOL_COMMANDS = [
     alias: "spec2rtl-search",
     description: "Search Spec2RTL knowledge cards"
   },
+  {
+    name: "genrtl_spec2plan_search",
+    alias: "spec2plan-search",
+    description: "Search Spec2Plan knowledge cards"
+  },
   {
     name: "genrtl_verification_search",
     alias: "verification-search",
@@ -988,7 +1004,7 @@ function buildKnowledgeSearchInput(query, options) {
   }
   const filters = {};
   if (options.type?.length) {
-    const allowed = /* @__PURE__ */ new Set(["spec2rtl", "verification", "debug"]);
+    const allowed = /* @__PURE__ */ new Set(["spec2rtl", "spec2plan", "verification", "debug"]);
     const invalid = options.type.find((type) => !allowed.has(type));
     if (invalid) {
       throw new InvalidArgumentError(`Invalid knowledge type: ${invalid}`);
@@ -1065,7 +1081,7 @@ function printKnowledgeResult(result) {
   }
 }
 function addSearchOptions(command) {
-  return command.argument("<query>", "Natural-language RTL engineering question or diagnostic").option("--type <type...>", "Knowledge types: spec2rtl, verification, debug").option("--domain <domain>", "Filter by engineering domain").option("--tool <tool>", "Filter by EDA tool").option("--tool-version <version>", "Filter by EDA tool version").option("--error-type <type>", "Filter by error type").option("--severity <severity>", "Filter by severity").option("--interface <interface>", "Filter by hardware interface").option("--target <target>", "Filter by target: fpga, asic, or both").option("--tag <tag...>", "Filter by one or more tags").option("--top-k <count>", "Maximum results (1-20)", parseInteger).option("--min-score <score>", "Minimum similarity score (0-1)", parseNumber).option("--workspace-id <id>", "GenRTL workspace ID").option("--json", "Output the structured MCP result as JSON");
+  return command.argument("<query>", "Natural-language RTL engineering question or diagnostic").option("--type <type...>", "Knowledge types: spec2rtl, spec2plan, verification, debug").option("--domain <domain>", "Filter by engineering domain").option("--tool <tool>", "Filter by EDA tool").option("--tool-version <version>", "Filter by EDA tool version").option("--error-type <type>", "Filter by error type").option("--severity <severity>", "Filter by severity").option("--interface <interface>", "Filter by hardware interface").option("--target <target>", "Filter by target: fpga, asic, or both").option("--tag <tag...>", "Filter by one or more tags").option("--top-k <count>", "Maximum results (1-20)", parseInteger).option("--min-score <score>", "Minimum similarity score (0-1)", parseNumber).option("--workspace-id <id>", "GenRTL workspace ID").option("--json", "Output the structured MCP result as JSON");
 }
 function registerKnowledgeCommands(program2) {
   for (const tool of TOOL_COMMANDS) {
@@ -1076,23 +1092,485 @@ function registerKnowledgeCommands(program2) {
   }
 }
 
+// src/commands/cbb.ts
+import ora3 from "ora";
+import pc5 from "picocolors";
+
+// src/utils/cbb-install.ts
+import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createWriteStream } from "fs";
+import {
+  access as access3,
+  mkdir as mkdir4,
+  mkdtemp,
+  open,
+  readFile as readFile3,
+  realpath,
+  rename,
+  rm as rm2,
+  writeFile as writeFile4
+} from "fs/promises";
+import { dirname as dirname6, isAbsolute, join as join4, relative, resolve as resolve3, sep } from "path";
+import { Transform } from "stream";
+import { pipeline } from "stream/promises";
+import yauzl from "yauzl";
+var MAX_ARCHIVE_BYTES = 512 * 1024 * 1024;
+var MAX_EXTRACTED_BYTES = 512 * 1024 * 1024;
+var MAX_ENTRY_BYTES = 128 * 1024 * 1024;
+var MAX_COMPRESSION_RATIO = 200;
+var MAX_ZIP_ENTRIES = 1e4;
+function pathExists2(path) {
+  return access3(path).then(
+    () => true,
+    () => false
+  );
+}
+function safePathPart(value) {
+  return value.replace(/[^A-Za-z0-9._-]+/g, "_");
+}
+function parseCbbSpec(spec) {
+  const separator = spec.lastIndexOf("@");
+  if (separator <= 0 || separator === spec.length - 1) {
+    throw new Error("CBB must use the form <cbb_id>@<version>.");
+  }
+  const cbbId = spec.slice(0, separator).trim();
+  const version = spec.slice(separator + 1).trim();
+  if (!cbbId || !version) {
+    throw new Error("CBB must use the form <cbb_id>@<version>.");
+  }
+  return { cbbId, version };
+}
+function defaultCbbTarget(cbbId, version) {
+  return `rtl/cbb/${safePathPart(cbbId)}_${safePathPart(version)}`;
+}
+function normalizeRelativeTarget(value) {
+  const slashPath = value.trim().replace(/\\/g, "/").replace(/\/+/g, "/");
+  if (!slashPath || slashPath.includes("\0") || slashPath.startsWith("/") || /^[A-Za-z]:/.test(slashPath)) {
+    throw new Error("Target must be a non-empty project-relative path.");
+  }
+  const parts = slashPath.split("/").filter((part) => part && part !== ".");
+  if (parts.length === 0 || parts.some(
+    (part) => part === ".." || part.length > 255 || part.includes(":") || part.endsWith(".") || part.endsWith(" ") || windowsReservedName(part)
+  )) {
+    throw new Error("Target must not escape the project directory.");
+  }
+  return parts.join("/");
+}
+function resolveProjectTarget(projectRoot, targetDir) {
+  const targetPath = resolve3(projectRoot, ...targetDir.split("/"));
+  const relativePath = relative(projectRoot, targetPath);
+  if (!relativePath || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+    throw new Error("Target must resolve inside the project directory.");
+  }
+  return targetPath;
+}
+async function readLockfile(projectRoot) {
+  const lockPath = join4(projectRoot, ".genrtl", "cbb-lock.json");
+  if (!await pathExists2(lockPath)) {
+    return { schema_version: 1, packages: {} };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile3(lockPath, "utf8"));
+  } catch {
+    throw new Error(`Invalid CBB lockfile: ${lockPath}`);
+  }
+  if (!parsed || typeof parsed !== "object" || parsed.schema_version !== 1 || !parsed.packages || typeof parsed.packages !== "object") {
+    throw new Error(`Unsupported CBB lockfile format: ${lockPath}`);
+  }
+  return parsed;
+}
+async function prepareCbbInstall(projectRootInput, targetInput, cbbId, version, force) {
+  const projectRoot = await realpath(resolve3(projectRootInput));
+  const targetDir = normalizeRelativeTarget(targetInput);
+  const targetPath = resolveProjectTarget(projectRoot, targetDir);
+  if (!force && await pathExists2(targetPath)) {
+    throw new Error(`Target already exists: ${targetPath}. Use --force to replace it.`);
+  }
+  await readLockfile(projectRoot);
+  const projectHash = createHash("sha256").update(projectRoot).digest("hex");
+  const operationHash = createHash("sha256").update(`${projectRoot}\0${targetDir}\0${cbbId}\0${version}`).digest("hex");
+  return {
+    projectRoot,
+    targetDir,
+    targetPath,
+    workspaceId: `cli:${projectHash.slice(0, 40)}`,
+    jobId: `cbb-install:${safePathPart(cbbId)}@${safePathPart(version)}:${operationHash.slice(0, 16)}`,
+    idempotencyKey: `grtl-cbb-install:${operationHash}`
+  };
+}
+async function writeAll(file, chunk) {
+  let offset = 0;
+  while (offset < chunk.byteLength) {
+    const { bytesWritten } = await file.write(chunk, offset, chunk.byteLength - offset, null);
+    if (bytesWritten <= 0) throw new Error("Failed to write downloaded artifact.");
+    offset += bytesWritten;
+  }
+}
+async function downloadArtifact(descriptor, archivePath) {
+  if (!Number.isSafeInteger(descriptor.file_size) || descriptor.file_size <= 0 || descriptor.file_size > MAX_ARCHIVE_BYTES) {
+    throw new Error("CBB archive size is invalid or exceeds the 512 MiB limit.");
+  }
+  if (!/^[a-fA-F0-9]{64}$/.test(descriptor.sha256)) {
+    throw new Error("CBB archive SHA256 is invalid.");
+  }
+  const response = await fetch(descriptor.artifact_url, {
+    redirect: "follow",
+    headers: { Accept: "application/zip, application/octet-stream" }
+  });
+  if (!response.ok || !response.body) {
+    const message = (await response.text().catch(() => "")).slice(0, 500);
+    throw new Error(
+      `CBB download failed with HTTP ${response.status}${message ? `: ${message}` : ""}`
+    );
+  }
+  const contentLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(contentLength) && contentLength > MAX_ARCHIVE_BYTES) {
+    throw new Error("CBB download exceeds the 512 MiB limit.");
+  }
+  const hash = createHash("sha256");
+  const file = await open(archivePath, "wx");
+  let downloaded = 0;
+  try {
+    const reader = response.body.getReader();
+    while (true) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      downloaded += value.byteLength;
+      if (downloaded > MAX_ARCHIVE_BYTES || downloaded > descriptor.file_size) {
+        await reader.cancel();
+        throw new Error("CBB download exceeded the declared archive size.");
+      }
+      hash.update(value);
+      await writeAll(file, value);
+    }
+  } finally {
+    await file.close();
+  }
+  if (downloaded !== descriptor.file_size) {
+    throw new Error(
+      `CBB archive size mismatch: expected ${descriptor.file_size}, received ${downloaded}.`
+    );
+  }
+  const actualSha256 = hash.digest("hex");
+  if (actualSha256 !== descriptor.sha256.toLowerCase()) {
+    throw new Error("CBB archive SHA256 verification failed.");
+  }
+}
+function windowsReservedName(part) {
+  const stem = part.split(".")[0].toUpperCase();
+  return /^(CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])$/.test(stem);
+}
+function validateZipEntryPath(entryName) {
+  const slashPath = entryName.replace(/\\/g, "/");
+  if (!slashPath || slashPath.includes("\0") || slashPath.startsWith("/") || /^[A-Za-z]:/.test(slashPath) || slashPath.length > 4096) {
+    throw new Error(`Unsafe ZIP entry path: ${entryName}`);
+  }
+  const directory = slashPath.endsWith("/");
+  const parts = slashPath.split("/").filter(Boolean);
+  if (parts.length === 0 || parts.some(
+    (part) => part === "." || part === ".." || part.length > 255 || part.includes(":") || part.endsWith(".") || part.endsWith(" ") || windowsReservedName(part)
+  )) {
+    throw new Error(`Unsafe ZIP entry path: ${entryName}`);
+  }
+  return `${parts.join("/")}${directory ? "/" : ""}`;
+}
+function openZip(path) {
+  return new Promise((resolvePromise, reject) => {
+    yauzl.open(path, { lazyEntries: true, autoClose: true }, (error, zipFile) => {
+      if (error || !zipFile) reject(error || new Error("Unable to open ZIP archive."));
+      else resolvePromise(zipFile);
+    });
+  });
+}
+function entryFileType(entry) {
+  return entry.externalFileAttributes >>> 16 & 61440;
+}
+function extractEntry(zipFile, entry, outputPath, extractedBytes) {
+  return new Promise((resolvePromise, reject) => {
+    zipFile.openReadStream(entry, (error, stream) => {
+      if (error || !stream) {
+        reject(error || new Error(`Unable to read ZIP entry: ${entry.fileName}`));
+        return;
+      }
+      let entryBytes = 0;
+      const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+          entryBytes += chunk.length;
+          extractedBytes.value += chunk.length;
+          if (entryBytes > MAX_ENTRY_BYTES || extractedBytes.value > MAX_EXTRACTED_BYTES) {
+            callback(new Error("CBB archive exceeds safe extraction limits."));
+            return;
+          }
+          callback(null, chunk);
+        }
+      });
+      pipeline(stream, limiter, createWriteStream(outputPath, { flags: "wx", mode: 420 })).then(
+        () => {
+          if (entryBytes !== entry.uncompressedSize) {
+            reject(new Error(`ZIP entry size mismatch: ${entry.fileName}`));
+          } else {
+            resolvePromise();
+          }
+        },
+        reject
+      );
+    });
+  });
+}
+async function extractZipSafely(archivePath, destination) {
+  const zipFile = await openZip(archivePath);
+  if (zipFile.entryCount > MAX_ZIP_ENTRIES) {
+    zipFile.close();
+    throw new Error(`CBB archive contains more than ${MAX_ZIP_ENTRIES} entries.`);
+  }
+  await mkdir4(destination, { recursive: true });
+  const destinationRoot = `${resolve3(destination)}${sep}`;
+  const seenPaths = /* @__PURE__ */ new Set();
+  const extractedBytes = { value: 0 };
+  await new Promise((resolvePromise, reject) => {
+    let settled = false;
+    const fail = (error) => {
+      if (settled) return;
+      settled = true;
+      zipFile.close();
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    zipFile.on("error", fail);
+    zipFile.on("end", () => {
+      if (settled) return;
+      settled = true;
+      resolvePromise();
+    });
+    zipFile.on("entry", (entry) => {
+      void (async () => {
+        if ((entry.generalPurposeBitFlag & 1) !== 0) {
+          throw new Error(`Encrypted ZIP entries are not supported: ${entry.fileName}`);
+        }
+        const normalizedName = validateZipEntryPath(entry.fileName);
+        const collisionKey = normalizedName.toLowerCase();
+        if (seenPaths.has(collisionKey)) {
+          throw new Error(`Duplicate ZIP entry path: ${entry.fileName}`);
+        }
+        seenPaths.add(collisionKey);
+        if (entry.uncompressedSize > MAX_ENTRY_BYTES || extractedBytes.value + entry.uncompressedSize > MAX_EXTRACTED_BYTES) {
+          throw new Error("CBB archive exceeds safe extraction limits.");
+        }
+        if (entry.compressedSize > 0 && entry.uncompressedSize > 1024 * 1024 && entry.uncompressedSize / entry.compressedSize > MAX_COMPRESSION_RATIO) {
+          throw new Error(`Suspicious ZIP compression ratio: ${entry.fileName}`);
+        }
+        const fileType = entryFileType(entry);
+        if (fileType === 40960) {
+          throw new Error(`Symbolic links are not allowed in CBB archives: ${entry.fileName}`);
+        }
+        const isDirectory = normalizedName.endsWith("/") || fileType === 16384;
+        if (fileType !== 0 && fileType !== 16384 && fileType !== 32768) {
+          throw new Error(`Special files are not allowed in CBB archives: ${entry.fileName}`);
+        }
+        const outputPath = resolve3(destination, ...normalizedName.split("/").filter(Boolean));
+        if (!outputPath.startsWith(destinationRoot)) {
+          throw new Error(`ZIP entry escapes the target directory: ${entry.fileName}`);
+        }
+        if (isDirectory) {
+          await mkdir4(outputPath, { recursive: true });
+        } else {
+          await mkdir4(dirname6(outputPath), { recursive: true });
+          await extractEntry(zipFile, entry, outputPath, extractedBytes);
+        }
+        zipFile.readEntry();
+      })().catch(fail);
+    });
+    zipFile.readEntry();
+  });
+}
+async function validatePackageManifest(stagingPath, cbbId, version) {
+  for (const filename of ["manifest.json", "cbb.json", "CBB.json"]) {
+    const manifestPath = join4(stagingPath, filename);
+    if (!await pathExists2(manifestPath)) continue;
+    let manifest;
+    try {
+      manifest = JSON.parse(await readFile3(manifestPath, "utf8"));
+    } catch {
+      throw new Error(`Invalid package manifest: ${filename}`);
+    }
+    if (!manifest || typeof manifest !== "object") {
+      throw new Error(`Invalid package manifest: ${filename}`);
+    }
+    const record = manifest;
+    const manifestId = typeof record.id === "string" ? record.id : typeof record.cbb_id === "string" ? record.cbb_id : void 0;
+    if (manifestId && manifestId !== cbbId) {
+      throw new Error(`CBB manifest ID mismatch: expected ${cbbId}, found ${manifestId}.`);
+    }
+    if (typeof record.version === "string" && record.version !== version) {
+      throw new Error(
+        `CBB manifest version mismatch: expected ${version}, found ${record.version}.`
+      );
+    }
+    return;
+  }
+}
+async function writeLockfile(projectRoot, cbbId, entry) {
+  const lockfile = await readLockfile(projectRoot);
+  lockfile.packages[cbbId] = entry;
+  const lockDir = join4(projectRoot, ".genrtl");
+  const lockPath = join4(lockDir, "cbb-lock.json");
+  const tempPath = join4(lockDir, `.cbb-lock-${randomUUID2()}.tmp`);
+  const backupPath = join4(lockDir, `.cbb-lock-${randomUUID2()}.bak`);
+  await mkdir4(lockDir, { recursive: true });
+  await writeFile4(tempPath, `${JSON.stringify(lockfile, null, 2)}
+`, "utf8");
+  const hadLockfile = await pathExists2(lockPath);
+  try {
+    if (hadLockfile) await rename(lockPath, backupPath);
+    await rename(tempPath, lockPath);
+    if (hadLockfile) await rm2(backupPath, { force: true });
+  } catch (error) {
+    await rm2(tempPath, { force: true }).catch(() => {
+    });
+    if (hadLockfile && await pathExists2(backupPath)) {
+      await rename(backupPath, lockPath).catch(() => {
+      });
+    }
+    throw error;
+  }
+}
+async function installCbbArtifact(descriptor, plan, force) {
+  if (descriptor.format !== "zip") {
+    throw new Error(`Unsupported CBB artifact format: ${descriptor.format}`);
+  }
+  const targetParent = dirname6(plan.targetPath);
+  await mkdir4(targetParent, { recursive: true });
+  const tempRoot = await mkdtemp(join4(targetParent, ".grtl-cbb-"));
+  const archivePath = join4(tempRoot, "artifact.zip");
+  const stagingPath = join4(tempRoot, "content");
+  const backupPath = `${plan.targetPath}.grtl-backup-${randomUUID2()}`;
+  let backupCreated = false;
+  let installed = false;
+  try {
+    await downloadArtifact(descriptor, archivePath);
+    await extractZipSafely(archivePath, stagingPath);
+    await validatePackageManifest(stagingPath, descriptor.cbb_id, descriptor.version);
+    if (await pathExists2(plan.targetPath)) {
+      if (!force) {
+        throw new Error(`Target already exists: ${plan.targetPath}. Use --force to replace it.`);
+      }
+      await rename(plan.targetPath, backupPath);
+      backupCreated = true;
+    }
+    await rename(stagingPath, plan.targetPath);
+    installed = true;
+    await writeLockfile(plan.projectRoot, descriptor.cbb_id, {
+      version: descriptor.version,
+      target: plan.targetDir,
+      sha256: descriptor.sha256.toLowerCase(),
+      file_size: descriptor.file_size,
+      receipt_id: descriptor.receipt_id,
+      installed_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    if (backupCreated) {
+      await rm2(backupPath, { recursive: true, force: true }).catch(() => {
+      });
+    }
+    return {
+      cbb_id: descriptor.cbb_id,
+      version: descriptor.version,
+      target: plan.targetDir,
+      target_path: plan.targetPath,
+      sha256: descriptor.sha256.toLowerCase(),
+      file_size: descriptor.file_size,
+      receipt_id: descriptor.receipt_id,
+      trace_id: descriptor.trace_id
+    };
+  } catch (error) {
+    if (installed) {
+      await rm2(plan.targetPath, { recursive: true, force: true }).catch(() => {
+      });
+    }
+    if (backupCreated && await pathExists2(backupPath)) {
+      await rename(backupPath, plan.targetPath).catch(() => {
+      });
+    }
+    throw error;
+  } finally {
+    await rm2(tempRoot, { recursive: true, force: true }).catch(() => {
+    });
+  }
+}
+
+// src/commands/cbb.ts
+async function installCbb(spec, options) {
+  trackEvent("command", { name: "cbb-install" });
+  const spinner = process.stdout.isTTY && !options.json ? ora3("Preparing CBB installation...").start() : null;
+  try {
+    const { cbbId, version } = parseCbbSpec(spec);
+    const target = options.target || defaultCbbTarget(cbbId, version);
+    const plan = await prepareCbbInstall(
+      options.projectRoot || process.cwd(),
+      target,
+      cbbId,
+      version,
+      options.force || false
+    );
+    spinner && (spinner.text = "Acquiring CBB artifact...");
+    const acquireInput = {
+      cbb_id: cbbId,
+      version,
+      target_dir: plan.targetDir,
+      workspace_id: plan.workspaceId,
+      job_id: plan.jobId,
+      idempotency_key: plan.idempotencyKey
+    };
+    const descriptor = await callGenrtlMcpTool(
+      "genrtl_cbb_acquire",
+      acquireInput
+    );
+    if (descriptor.cbb_id !== cbbId || descriptor.version !== version) {
+      throw new Error("GenRTL returned a CBB artifact that does not match the request.");
+    }
+    spinner && (spinner.text = "Downloading and verifying CBB artifact...");
+    const result = await installCbbArtifact(descriptor, plan, options.force || false);
+    spinner?.succeed(`Installed ${cbbId}@${version}`);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    log.blank();
+    log.success(`Installed ${pc5.bold(`${cbbId}@${version}`)}`);
+    log.item(`Target: ${result.target_path}`);
+    log.item(`SHA256: ${result.sha256}`);
+    log.item(`Lockfile: ${plan.projectRoot}/.genrtl/cbb-lock.json`);
+    log.blank();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    spinner?.fail(message);
+    if (!spinner) log.error(message);
+    process.exitCode = 1;
+  }
+}
+function registerCbbCommands(program2) {
+  const cbb = program2.command("cbb").description("Discover and install reusable RTL CBBs");
+  cbb.command("install").description("Acquire, verify, and install a CBB ZIP into the current project").argument("<cbb>", "CBB coordinate in the form <cbb_id>@<version>").option("-t, --target <dir>", "Project-relative target directory").option("--project-root <dir>", "Project root (default: current directory)").option("-f, --force", "Replace an existing target after successful verification").option("--json", "Output the installation result as JSON").action(async (spec, options) => {
+    await installCbb(spec, options);
+  });
+}
+
 // src/commands/upgrade.ts
 import { confirm } from "@inquirer/prompts";
 import { spawn } from "child_process";
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 
 // src/utils/update-check.ts
 import { homedir as homedir2 } from "os";
-import { dirname as dirname6, join as join4 } from "path";
-import { mkdir as mkdir4, readFile as readFile3, writeFile as writeFile4 } from "fs/promises";
+import { dirname as dirname7, join as join5 } from "path";
+import { mkdir as mkdir5, readFile as readFile4, writeFile as writeFile5 } from "fs/promises";
 var DEFAULT_CACHE_TTL_MS = 24 * 60 * 60 * 1e3;
-var UPDATE_STATE_FILE = join4(homedir2(), ".genrtl", "cli-state.json");
+var UPDATE_STATE_FILE = join5(homedir2(), ".genrtl", "cli-state.json");
 function getStateFilePath(stateFile) {
   return stateFile ?? UPDATE_STATE_FILE;
 }
 async function readUpdateState(stateFile) {
   try {
-    const raw = await readFile3(getStateFilePath(stateFile), "utf-8");
+    const raw = await readFile4(getStateFilePath(stateFile), "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
@@ -1100,8 +1578,8 @@ async function readUpdateState(stateFile) {
 }
 async function writeUpdateState(state, stateFile) {
   const path = getStateFilePath(stateFile);
-  await mkdir4(dirname6(path), { recursive: true });
-  await writeFile4(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
+  await mkdir5(dirname7(path), { recursive: true });
+  await writeFile5(path, JSON.stringify(state, null, 2) + "\n", "utf-8");
 }
 function compareVersions(a, b) {
   const normalize = (version) => version.split("-", 1)[0].split(".").map((part) => Number.parseInt(part, 10) || 0);
@@ -1277,20 +1755,20 @@ function registerUpgradeCommand(program2) {
   });
 }
 function runCommand(command, args) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     const child = spawn(command, args, {
       stdio: "inherit",
       shell: process.platform === "win32"
     });
     child.on("error", reject);
-    child.on("close", (code) => resolve3(code));
+    child.on("close", (code) => resolve4(code));
   });
 }
 async function runUpgradePlan(plan) {
   return runCommand(plan.command, plan.args);
 }
 function showUpgradeFailureHelp(plan) {
-  log.info(`Try rerunning: ${pc5.cyan(plan.displayCommand)}`);
+  log.info(`Try rerunning: ${pc6.cyan(plan.displayCommand)}`);
   const isGlobalNpmInstall = (plan.installMethod === "npm-global" || plan.installMethod === "unknown") && plan.command === "npm" && plan.args.includes("-g");
   const isGlobalAltInstall = (plan.installMethod === "pnpm-global" || plan.installMethod === "bun-global") && plan.args.includes("-g");
   if (isGlobalNpmInstall) {
@@ -1317,8 +1795,8 @@ async function maybeShowUpgradeNotice(options = {}) {
   log.blank();
   if (info.upgradePlan.needsExplicitVersion) {
     log.box([
-      `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
-      `${pc5.white("Use")} ${pc5.yellow(pc5.bold(info.upgradePlan.displayCommand))} ${pc5.white("to run the latest version")}`
+      `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
+      `${pc6.white("Use")} ${pc6.yellow(pc6.bold(info.upgradePlan.displayCommand))} ${pc6.white("to run the latest version")}`
     ]);
     await markUpdateNotificationShown(info.latestVersion);
     log.blank();
@@ -1326,18 +1804,18 @@ async function maybeShowUpgradeNotice(options = {}) {
   }
   if (!info.upgradePlan.canRun) {
     log.box([
-      `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
-      `${pc5.white("Run")} ${pc5.yellow(pc5.bold("grtl upgrade"))} ${pc5.white("for update steps")}`,
-      `${pc5.white("Or run")} ${pc5.yellow(info.upgradePlan.displayCommand)}`
+      `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
+      `${pc6.white("Run")} ${pc6.yellow(pc6.bold("grtl upgrade"))} ${pc6.white("for update steps")}`,
+      `${pc6.white("Or run")} ${pc6.yellow(info.upgradePlan.displayCommand)}`
     ]);
     await markUpdateNotificationShown(info.latestVersion);
     log.blank();
     return;
   }
   log.box([
-    `${pc5.white(pc5.bold("Update available:"))} ${pc5.green(pc5.bold(`v${info.currentVersion}`))} ${pc5.dim("->")} ${pc5.green(pc5.bold(`v${info.latestVersion}`))}`,
-    `${pc5.white("Run")} ${pc5.yellow(pc5.bold("grtl upgrade"))} ${pc5.white("to update now")}`,
-    `${pc5.white("Or run")} ${pc5.yellow(info.upgradePlan.displayCommand)}`
+    `${pc6.white(pc6.bold("Update available:"))} ${pc6.green(pc6.bold(`v${info.currentVersion}`))} ${pc6.dim("->")} ${pc6.green(pc6.bold(`v${info.latestVersion}`))}`,
+    `${pc6.white("Run")} ${pc6.yellow(pc6.bold("grtl upgrade"))} ${pc6.white("to update now")}`,
+    `${pc6.white("Or run")} ${pc6.yellow(info.upgradePlan.displayCommand)}`
   ]);
   await markUpdateNotificationShown(info.latestVersion);
   log.blank();
@@ -1348,28 +1826,28 @@ async function upgradeCommand(options) {
   const plan = info?.upgradePlan ?? getUpgradePlan();
   if (!info) {
     log.warn("Couldn't check for updates right now.");
-    log.info(`Try again later or run ${pc5.cyan(plan.displayCommand)} manually.`);
+    log.info(`Try again later or run ${pc6.cyan(plan.displayCommand)} manually.`);
     return;
   }
   if (!info.updateAvailable) {
-    log.success(`grtl is up to date (${pc5.bold(`v${VERSION}`)})`);
+    log.success(`grtl is up to date (${pc6.bold(`v${VERSION}`)})`);
     return;
   }
   log.blank();
   log.info(
-    `Update available: ${pc5.bold(`v${info.currentVersion}`)} ${pc5.dim("->")} ${pc5.bold(`v${info.latestVersion}`)}`
+    `Update available: ${pc6.bold(`v${info.currentVersion}`)} ${pc6.dim("->")} ${pc6.bold(`v${info.latestVersion}`)}`
   );
   if (plan.needsExplicitVersion) {
     log.info(`You're using an ephemeral runner (${plan.installMethod}).`);
-    log.info(`Use ${pc5.cyan(plan.displayCommand)} to run the latest version immediately.`);
-    log.info(`Or install globally with ${pc5.cyan("npm install -g @genrtl/grtl@latest")}.`);
+    log.info(`Use ${pc6.cyan(plan.displayCommand)} to run the latest version immediately.`);
+    log.info(`Or install globally with ${pc6.cyan("npm install -g @genrtl/grtl@latest")}.`);
     return;
   }
   if (!plan.canRun) {
-    log.info(`Run ${pc5.cyan(plan.displayCommand)} to update your installed version.`);
+    log.info(`Run ${pc6.cyan(plan.displayCommand)} to update your installed version.`);
     return;
   }
-  log.info(`Upgrade command: ${pc5.cyan(plan.displayCommand)}`);
+  log.info(`Upgrade command: ${pc6.cyan(plan.displayCommand)}`);
   if (options.check) {
     return;
   }
@@ -1389,7 +1867,7 @@ async function upgradeCommand(options) {
   if (exitCode === 0) {
     log.blank();
     log.success("Upgrade complete.");
-    log.info(`Run ${pc5.cyan("grtl --version")} to verify the installed version.`);
+    log.info(`Run ${pc6.cyan("grtl --version")} to verify the installed version.`);
     return;
   }
   log.blank();
@@ -1400,8 +1878,8 @@ async function upgradeCommand(options) {
 
 // src/index.ts
 var brand = {
-  primary: pc6.green,
-  dim: pc6.dim
+  primary: pc7.green,
+  dim: pc7.dim
 };
 var program = new Command2();
 program.name("grtl").description("GenRTL CLI - Search RTL engineering knowledge and configure GenRTL").version(VERSION).option("--base-url <url>").hook("preAction", (thisCommand) => {
@@ -1423,15 +1901,20 @@ Examples:
   ${brand.primary("npx @genrtl/grtl setup --cli --codex --project")}
   ${brand.primary("GRTL_API_KEY=your_key npx @genrtl/grtl setup --mcp --codex --project")}
 
-  ${brand.dim("# Search the same four tools exposed by the GenRTL MCP server")}
+  ${brand.dim("# Search the same five tools exposed by the GenRTL MCP server")}
   ${brand.primary('npx @genrtl/grtl knowledge-search "AXI stream backpressure design"')}
   ${brand.primary('npx @genrtl/grtl spec2rtl-search "Generate an APB register block"')}
+  ${brand.primary('npx @genrtl/grtl spec2plan-search "Plan an APB register block implementation"')}
   ${brand.primary('npx @genrtl/grtl verification-search "Verify an async FIFO"')}
   ${brand.primary('npx @genrtl/grtl debug-search "Explain this Vivado CDC warning"')}
+
+  ${brand.dim("# Acquire and install a reusable RTL CBB")}
+  ${brand.primary("npx @genrtl/grtl cbb install cbb_uart@1.2.0")}
 `
 );
 registerSetupCommand(program);
 registerKnowledgeCommands(program);
+registerCbbCommands(program);
 registerUpgradeCommand(program);
 program.action(() => {
   console.log("");

package/package.json

@@ -1,21 +1,21 @@
-{
+{
   "name": "@genrtl/grtl",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "CLI, MCP, and coding-agent Skills for GenRTL RTL engineering knowledge",
   "type": "module",
   "bin": {
     "grtl": "dist/index.js"
   },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src --fix",
-    "lint:check": "eslint src",
-    "format": "prettier --write src",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --fix",
+    "lint:check": "eslint src",
+    "format": "prettier --write src",
     "format:check": "prettier --check src",
     "clean": "rm -rf dist node_modules",
     "test": "vitest run",
@@ -25,28 +25,32 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
+    "boxen": "^8.0.1",
     "commander": "^13.1.0",
     "figlet": "^1.9.4",
+    "open": "^10.2.0",
     "ora": "^9.0.0",
-    "picocolors": "^1.1.1"
-  },
-  "devDependencies": {
-    "@types/figlet": "^1.7.0",
-    "@types/node": "^22.19.1",
-    "@typescript-eslint/eslint-plugin": "^8.28.0",
-    "@typescript-eslint/parser": "^8.28.0",
-    "eslint": "^9.34.0",
-    "eslint-plugin-prettier": "^5.2.5",
-    "prettier": "^3.6.2",
-    "tsup": "^8.5.0",
-    "typescript": "^5.8.2",
-    "typescript-eslint": "^8.28.0",
-    "vitest": "^4.0.13"
-  },
-  "keywords": [
-    "genrtl",
-    "cli",
-    "ai",
+    "picocolors": "^1.1.1",
+    "yauzl": "^3.2.0"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/node": "^22.19.1",
+    "@types/yauzl": "^2.10.3",
+    "@typescript-eslint/eslint-plugin": "^8.28.0",
+    "@typescript-eslint/parser": "^8.28.0",
+    "eslint": "^9.34.0",
+    "eslint-plugin-prettier": "^5.2.5",
+    "prettier": "^3.6.2",
+    "tsup": "^8.5.0",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.28.0",
+    "vitest": "^4.0.13"
+  },
+  "keywords": [
+    "genrtl",
+    "cli",
+    "ai",
     "rtl",
     "systemverilog",
     "verilog",
@@ -54,9 +58,9 @@
     "mcp"
   ],
   "author": "xroting",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
     "url": "git+https://github.com/xroting/grtl.git",
     "directory": "packages/cli"
   },