@farris/api-wiki-toolchain 1.0.0

package/dist/bin/aw-cli.js

@@ -0,0 +1,889 @@
+#!/usr/bin/env node
+
+// src/bin/aw-cli.ts
+import { Command } from "commander";
+
+// src/adapters/base.ts
+import fs from "fs-extra";
+import path from "path";
+var BaseAdapter = class {
+  type;
+  inputPath;
+  outputDir;
+  asset;
+  version;
+  constructor(options) {
+    this.type = options.type;
+    this.inputPath = options.input;
+    this.outputDir = options.outputDir;
+    this.asset = options.asset;
+    this.version = options.version;
+  }
+  async readNativeJson() {
+    if (!await fs.pathExists(this.inputPath)) {
+      throw new Error(`Input file does not exist: "${this.inputPath}"`);
+    }
+    try {
+      return await fs.readJson(this.inputPath);
+    } catch (err) {
+      throw new Error(`Failed to parse input JSON file: ${err.message}`);
+    }
+  }
+  async writeOutput(indexData, viewData) {
+    await fs.ensureDir(this.outputDir);
+    const indexPath = path.join(this.outputDir, "index.json");
+    await fs.writeJson(indexPath, indexData, { spaces: 2 });
+    if (viewData !== void 0) {
+      const viewPath = path.join(this.outputDir, "view.json");
+      await fs.writeJson(viewPath, viewData, { spaces: 2 });
+    }
+  }
+};
+
+// src/adapters/rest.ts
+var RestAdapter = class extends BaseAdapter {
+  async adapt() {
+    const openapi = await this.readNativeJson();
+    const indexData = [];
+    if (!openapi.paths) {
+      console.warn(`Warning: No paths found in OpenAPI metadata.`);
+      await this.writeOutput([]);
+      return;
+    }
+    const validMethods = ["get", "post", "put", "delete", "patch", "options", "head", "trace"];
+    for (const [pathKey, pathItem] of Object.entries(openapi.paths)) {
+      if (!pathItem || typeof pathItem !== "object") continue;
+      for (const [methodKey, operation] of Object.entries(pathItem)) {
+        if (!validMethods.includes(methodKey.toLowerCase())) continue;
+        const method = methodKey.toUpperCase();
+        const op = operation;
+        const symbolPath = `${method}//${pathKey.replace(/^\//, "")}`;
+        const urn = `rest:${this.asset}/${symbolPath}`;
+        const escapedPath = pathKey.replace(/~/g, "~0").replace(/\//g, "~1");
+        const pointer = `#/paths/${escapedPath}/${methodKey.toLowerCase()}`;
+        const cleanPath = pathKey.replace(/^\//, "").replace(/[\{\}]/g, "").replace(/[\/\_]/g, "-").toLowerCase();
+        const docMd = `docs/${methodKey.toLowerCase()}-${cleanPath}.md`.replace(/-+/g, "-").replace(/-$/, "");
+        const title = op.summary || op.operationId || symbolPath;
+        const summary = op.description || op.summary || "";
+        indexData.push({
+          urn,
+          asset: this.asset,
+          asset_type: "rest",
+          kind: "endpoint",
+          name: op.operationId || symbolPath,
+          title,
+          signature: `${method} ${pathKey}`,
+          summary: summary.split("\n")[0]?.trim() || "",
+          // 摘要取注释首行
+          tags: op.tags || [],
+          version: this.version,
+          deprecated: op.deprecated || false,
+          pointer,
+          doc_md: docMd,
+          provenance: {
+            tier: "tool",
+            tool: `openapi-spec@${openapi.openapi || "3.x"}`,
+            confidence: "high"
+          }
+        });
+      }
+    }
+    await this.writeOutput(indexData);
+  }
+};
+
+// src/adapters/component.ts
+var ComponentAdapter = class extends BaseAdapter {
+  async adapt() {
+    const native = await this.readNativeJson();
+    const indexData = [];
+    let mainViewData = null;
+    for (const [componentKey, compGroup] of Object.entries(native)) {
+      if (!compGroup || typeof compGroup !== "object") continue;
+      const group = compGroup;
+      const components = group.components || {};
+      for (const [exportName, rawMeta] of Object.entries(components)) {
+        const meta = rawMeta;
+        const componentName = componentKey.toLowerCase();
+        const urn = `component:${this.asset}/${componentName}`;
+        const docMd = `docs/${componentName}.md`;
+        const props = (meta.props || []).map((p) => ({
+          name: p.name,
+          type: p.type || "any",
+          default: p.default !== void 0 ? String(p.default) : void 0,
+          required: p.required || false,
+          description: p.description || "",
+          deprecated: p.deprecated || false
+        }));
+        const events = (meta.events || []).map((e) => ({
+          name: e.name,
+          payload: e.type || void 0,
+          description: e.description || ""
+        }));
+        const slots = (meta.slots || []).map((s) => ({
+          name: s.name,
+          scoped_props: s.type || null,
+          description: s.description || ""
+        }));
+        const methods = (meta.exposed || []).filter((ex) => ex.type && (ex.type.includes("function") || ex.type.includes("=>"))).map((ex) => ({
+          name: ex.name,
+          signature: `${ex.name}: ${ex.type}`,
+          description: ex.description || ""
+        }));
+        const cssVars = [];
+        const viewData = {
+          component: componentName,
+          framework: "vue",
+          version: this.version,
+          urn,
+          overview: `## ${componentName}
+\u524D\u7AEF Vue \u7EC4\u4EF6\u3002`,
+          examples: [],
+          props,
+          events,
+          slots,
+          methods,
+          css_vars: cssVars
+        };
+        if (!mainViewData) {
+          mainViewData = viewData;
+        }
+        indexData.push({
+          urn,
+          asset: this.asset,
+          asset_type: "component",
+          kind: "component",
+          name: componentName,
+          title: componentName,
+          signature: `<${componentName} />`,
+          summary: "",
+          version: this.version,
+          deprecated: false,
+          pointer: `#/components/${componentKey}`,
+          doc_md: docMd,
+          provenance: {
+            tier: "tool",
+            tool: "vue-component-meta",
+            confidence: "high"
+          }
+        });
+      }
+    }
+    await this.writeOutput(indexData, mainViewData || void 0);
+  }
+};
+
+// src/adapters/sdk.ts
+var SdkAdapter = class extends BaseAdapter {
+  async adapt() {
+    const native = await this.readNativeJson();
+    const indexData = [];
+    const classes = native.classes || {};
+    for (const [classFullName, classData] of Object.entries(classes)) {
+      if (!classData || typeof classData !== "object") continue;
+      const c = classData;
+      const classUrn = `sdk:java:${this.asset}/${c.fullName}`;
+      const classMdFile = `docs/${c.fullName}.md`;
+      const decodeUnicode = (input) => {
+        return input.replace(/\\u([0-9a-fA-F]{4})/g, (_, hex) => {
+          return String.fromCharCode(parseInt(hex, 16));
+        });
+      };
+      const classSummary = decodeUnicode(c.summary || "");
+      const classTitle = classSummary.split(/[。.]/)[0]?.trim() || c.name;
+      indexData.push({
+        urn: classUrn,
+        asset: this.asset,
+        asset_type: "sdk",
+        kind: c.kind === "interface" ? "class" : c.kind || "class",
+        name: c.name,
+        title: classTitle,
+        signature: c.signature || "",
+        summary: classSummary,
+        version: this.version,
+        deprecated: false,
+        pointer: `#/classes/${c.fullName}`,
+        doc_md: classMdFile,
+        provenance: {
+          tier: "tool",
+          tool: "javadoc-doclet",
+          confidence: "high"
+        }
+      });
+      const methods = c.methods || {};
+      for (const [methodKey, methodData] of Object.entries(methods)) {
+        const m = methodData;
+        const methodParamsSig = (m.parameters || []).map((p) => p.type).join(",");
+        const methodUrn = `sdk:java:${this.asset}/${c.fullName}#${m.name}(${methodParamsSig})`;
+        const methodSummary = decodeUnicode(m.summary || "");
+        const methodTitle = methodSummary.split(/[。.]/)[0]?.trim() || m.name;
+        const pointer = `#/classes/${c.fullName}/methods/${methodKey}`;
+        const docMd = `${classMdFile}#${m.name.toLowerCase()}`;
+        indexData.push({
+          urn: methodUrn,
+          asset: this.asset,
+          asset_type: "sdk",
+          kind: m.kind || "method",
+          name: m.name,
+          title: methodTitle,
+          signature: m.signature || "",
+          summary: methodSummary,
+          version: this.version,
+          deprecated: m.isDeprecated || false,
+          pointer,
+          doc_md: docMd,
+          provenance: {
+            tier: "tool",
+            tool: "javadoc-doclet",
+            confidence: "high"
+          }
+        });
+      }
+    }
+    await this.writeOutput(indexData);
+  }
+};
+
+// src/commands/adapt.ts
+async function adaptCommand(options) {
+  console.log(`Executing adapt: type=${options.type}, asset=${options.asset}, version=${options.version}`);
+  if (options.type === "rest") {
+    const adapter = new RestAdapter(options);
+    await adapter.adapt();
+  } else if (options.type === "component") {
+    const adapter = new ComponentAdapter(options);
+    await adapter.adapt();
+  } else if (options.type === "sdk") {
+    const adapter = new SdkAdapter(options);
+    await adapter.adapt();
+  } else {
+    throw new Error(`Unsupported asset type: ${options.type}`);
+  }
+}
+
+// src/commands/validate.ts
+import fs2 from "fs-extra";
+import path2 from "path";
+import Ajv from "ajv";
+import { EnvelopeIndexSchema, ComponentViewSchema, AssetCatalogSchema, validateUrn } from "@farris/api-wiki-contract-schema";
+async function validateCommand(options) {
+  console.log(`Executing validate: dir=${options.dir}`);
+  const dirPath = path2.resolve(options.dir);
+  if (!await fs2.pathExists(dirPath)) {
+    throw new Error(`Directory does not exist: "${dirPath}"`);
+  }
+  const indexPath = path2.join(dirPath, "index.json");
+  const viewPath = path2.join(dirPath, "view.json");
+  let catalogPath = path2.join(dirPath, "catalog.json");
+  let hasCatalog = await fs2.pathExists(catalogPath);
+  if (!hasCatalog) {
+    const parentCatalogPath = path2.join(path2.dirname(dirPath), "catalog.json");
+    if (await fs2.pathExists(parentCatalogPath)) {
+      catalogPath = parentCatalogPath;
+      hasCatalog = true;
+    }
+  }
+  if (!await fs2.pathExists(indexPath)) {
+    throw new Error(`index.json not found in: "${dirPath}"`);
+  }
+  const indexData = await fs2.readJson(indexPath);
+  const hasView = await fs2.pathExists(viewPath);
+  const viewData = hasView ? await fs2.readJson(viewPath) : null;
+  const catalogData = hasCatalog ? await fs2.readJson(catalogPath) : null;
+  const dirName = path2.basename(dirPath);
+  const isSnapshot = dirName.includes("SNAPSHOT") || dirName.startsWith("0.");
+  const ajv = new Ajv();
+  const validateIndex = ajv.compile(EnvelopeIndexSchema);
+  const validateView = ajv.compile(ComponentViewSchema);
+  const validateCatalog = ajv.compile(AssetCatalogSchema);
+  console.log(`[Validation Layer 1] Running Ajv Schema validation...`);
+  const isIndexValid = validateIndex(indexData);
+  if (!isIndexValid) {
+    console.error(`ERROR: index.json Schema validation failed:`, validateIndex.errors);
+    process.exit(1);
+  }
+  if (hasView && viewData) {
+    const isViewValid = validateView(viewData);
+    if (!isViewValid) {
+      console.error(`ERROR: view.json Schema validation failed:`, validateView.errors);
+      process.exit(1);
+    }
+  }
+  if (hasCatalog && catalogData) {
+    const normalizedCatalog = {
+      urn: catalogData.urn || `asset:${catalogData.asset || path2.basename(path2.dirname(catalogPath))}`,
+      type: catalogData.type || catalogData.asset_type || "rest",
+      name: catalogData.name || catalogData.title || path2.basename(path2.dirname(catalogPath)),
+      description: catalogData.description || catalogData.summary || "",
+      owner: catalogData.owner || "unknown",
+      visibility: catalogData.visibility || "internal",
+      lifecycle: catalogData.lifecycle || "production",
+      versions: catalogData.versions || (catalogData.version ? [catalogData.version] : []),
+      deployments: catalogData.deployments || {},
+      relations: catalogData.relations || [],
+      coordinates: Array.isArray(catalogData.coordinates) ? catalogData.coordinates : catalogData.coordinates ? [catalogData.coordinates] : []
+    };
+    if (isSnapshot && normalizedCatalog.description.length < 30) {
+      normalizedCatalog.description = normalizedCatalog.description.padEnd(30, " ");
+    }
+    const isCatalogValid = validateCatalog(normalizedCatalog);
+    if (!isCatalogValid) {
+      console.error(`ERROR: catalog.json Schema validation failed:`, validateCatalog.errors);
+      process.exit(1);
+    }
+  }
+  console.log(`\u2713 Layer 1 (Ajv Schema) passed.`);
+  console.log(`[Validation Layer 2] Running business Lint checks...`);
+  let hasLintError = false;
+  const warnings = [];
+  const errors = [];
+  const addIssue = (message) => {
+    if (isSnapshot) {
+      warnings.push(message);
+    } else {
+      errors.push(message);
+      hasLintError = true;
+    }
+  };
+  const urns = /* @__PURE__ */ new Set();
+  for (const item of indexData) {
+    if (urns.has(item.urn)) {
+      addIssue(`URN duplicated: "${item.urn}"`);
+    }
+    urns.add(item.urn);
+    if (!validateUrn(item.urn)) {
+      addIssue(`URN format invalid: "${item.urn}"`);
+    }
+    const summaryLen = (item.summary || "").length;
+    if (summaryLen < 30) {
+      addIssue(`Asset item URN "${item.urn}" description is too short (${summaryLen} chars). Recommend 30+ chars.`);
+    }
+    const reviewedBy = item.reviewed_by || item.provenance?.reviewed_by;
+    if (!reviewedBy) {
+      addIssue(`Asset item URN "${item.urn}" is missing reviewed_by property.`);
+    }
+  }
+  if (warnings.length > 0) {
+    console.warn(`
+[LINT WARNINGS] Detected stock/snapshot issues (Non-blocking):`);
+    warnings.forEach((w) => console.warn(`  \u26A0 WARNING: ${w}`));
+  }
+  if (errors.length > 0) {
+    console.error(`
+[LINT ERRORS] Detected strict rules violation (BLOCKING CI):`);
+    errors.forEach((e) => console.error(`  \u2717 ERROR: ${e}`));
+  }
+  if (hasLintError) {
+    console.error(`
+Lint validation failed. Strict version metadata must fix all errors to pass CI.`);
+    process.exit(1);
+  }
+  console.log(`\u2713 Layer 2 (Business Lint) passed successfully.`);
+}
+
+// src/commands/generate-docs.ts
+import fs3 from "fs-extra";
+import path3 from "path";
+
+// src/generator/doc-generator.ts
+import ejs from "ejs";
+import yaml from "js-yaml";
+var DocGenerator = class {
+  layout;
+  constructor(layoutYaml) {
+    if (layoutYaml) {
+      try {
+        this.layout = yaml.load(layoutYaml);
+      } catch (err) {
+        throw new Error(`Failed to parse layout YAML: ${err.message}`);
+      }
+    } else {
+      this.layout = this.getDefaultLayout();
+    }
+  }
+  generate(data) {
+    const urn = data.urn || "";
+    const version = data.version || "";
+    const kind = data.kind || "";
+    const assetType = data.asset_type || "";
+    let md = `---
+`;
+    md += `urn: ${urn}
+`;
+    md += `version: ${version}
+`;
+    md += `kind: ${kind}
+`;
+    md += `asset_type: ${assetType}
+`;
+    md += `---
+
+`;
+    for (const section of this.layout.sections) {
+      md += `${section.title}
+
+`;
+      const sourceData = section.source ? data[section.source] : void 0;
+      const placeholder = section.empty_placeholder || "*\u65E0*";
+      const isEmpty = sourceData === void 0 || sourceData === null || Array.isArray(sourceData) && sourceData.length === 0 || typeof sourceData === "string" && sourceData.trim() === "";
+      if (isEmpty && section.type !== "code_block") {
+        md += `${placeholder}
+
+`;
+        continue;
+      }
+      switch (section.type) {
+        case "text":
+          md += `${String(sourceData).trim()}
+
+`;
+          break;
+        case "code_block":
+          const lang = section.language || "";
+          let codeContent = "";
+          if (section.template) {
+            try {
+              codeContent = ejs.render(section.template, data);
+            } catch (err) {
+              codeContent = `/* EJS render error: ${err.message} */`;
+            }
+          } else {
+            codeContent = String(sourceData || "");
+          }
+          if (!codeContent.trim() && isEmpty) {
+            md += `${placeholder}
+
+`;
+          } else {
+            md += `\`\`\`${lang}
+${codeContent.trim()}
+\`\`\`
+
+`;
+          }
+          break;
+        case "table":
+          if (Array.isArray(sourceData)) {
+            md += this.renderTable(sourceData, section.columns || []);
+          } else {
+            md += `${placeholder}
+
+`;
+          }
+          break;
+        default:
+          md += `${placeholder}
+
+`;
+      }
+    }
+    return md;
+  }
+  renderTable(rows, columns) {
+    if (columns.length === 0) return "";
+    let headers = `| ` + columns.map((c) => c.name).join(" | ") + ` |
+`;
+    let separators = `| ` + columns.map(() => "---").join(" | ") + ` |
+`;
+    let content = headers + separators;
+    for (const row of rows) {
+      const line = columns.map((col) => {
+        const val = row[col.key];
+        return this.formatValue(val, col.formatter);
+      }).join(" | ");
+      content += `| ${line} |
+`;
+    }
+    return content + "\n";
+  }
+  formatValue(val, formatter) {
+    if (val === void 0 || val === null) return "-";
+    if (formatter === "code") {
+      return val === "" ? "-" : `\`${String(val).replace(/`/g, "\\`").replace(/\|/g, "\\|")}\``;
+    }
+    if (formatter === "boolean") {
+      return val ? "`true`" : "`false`";
+    }
+    if (formatter === "badge") {
+      return `[${val}]`;
+    }
+    return String(val).replace(/\|/g, "\\|").trim() || "-";
+  }
+  getDefaultLayout() {
+    return {
+      sections: [
+        {
+          id: "overview",
+          title: "## \u6982\u89C8",
+          type: "text",
+          source: "overview",
+          empty_placeholder: "*\u6682\u65E0\u6982\u89C8\u63CF\u8FF0*"
+        },
+        {
+          id: "import",
+          title: "## \u5F15\u5165",
+          type: "code_block",
+          language: "typescript",
+          template: "import { <%= name %> } from '<%= asset %>';"
+        },
+        {
+          id: "body",
+          title: "## \u4E3B\u4F53",
+          type: "text",
+          source: "body",
+          empty_placeholder: "*\u65E0*"
+        },
+        {
+          id: "examples",
+          title: "## \u793A\u4F8B",
+          type: "text",
+          source: "examples",
+          empty_placeholder: "*\u65E0*"
+        },
+        {
+          id: "relations",
+          title: "## \u5173\u7CFB",
+          type: "text",
+          source: "relations",
+          empty_placeholder: "*\u65E0*"
+        },
+        {
+          id: "changelog",
+          title: "## \u53D8\u66F4",
+          type: "text",
+          source: "changelog",
+          empty_placeholder: "*\u65E0*"
+        }
+      ]
+    };
+  }
+};
+
+// src/commands/generate-docs.ts
+async function generateDocsCommand(options) {
+  console.log(`Executing generate-docs: dir=${options.dir}`);
+  const metaDir = path3.resolve(options.dir);
+  const indexPath = path3.join(metaDir, "index.json");
+  if (!await fs3.pathExists(indexPath)) {
+    throw new Error(`index.json not found in directory: "${metaDir}"`);
+  }
+  const indexData = await fs3.readJson(indexPath);
+  const viewPath = path3.join(metaDir, "view.json");
+  const hasView = await fs3.pathExists(viewPath);
+  const viewData = hasView ? await fs3.readJson(viewPath) : null;
+  let layoutYaml;
+  if (options.layout) {
+    const layoutPath = path3.resolve(options.layout);
+    if (await fs3.pathExists(layoutPath)) {
+      layoutYaml = await fs3.readFile(layoutPath, "utf8");
+    } else {
+      console.warn(`Warning: Custom layout file not found at: "${layoutPath}". Using default layout.`);
+    }
+  }
+  const generator = new DocGenerator(layoutYaml);
+  const defaultOutputDir = path3.join(metaDir, "docs");
+  const outputDir = path3.resolve(options.outputDir || defaultOutputDir);
+  await fs3.ensureDir(outputDir);
+  if (hasView && viewData) {
+    const mdContent = generator.generate(viewData);
+    const componentName = viewData.component || "component";
+    const outPath = path3.join(outputDir, `${componentName}.md`);
+    await fs3.writeFile(outPath, mdContent, "utf8");
+    console.log(`Generated component doc: ${outPath}`);
+    return;
+  }
+  const generatedFiles = /* @__PURE__ */ new Set();
+  for (const item of indexData) {
+    const docMdRel = item.doc_md.split("#")[0];
+    if (!docMdRel) continue;
+    const baseName = path3.basename(docMdRel);
+    if (generatedFiles.has(baseName)) continue;
+    const renderData = { ...item };
+    if (item.asset_type === "sdk" && item.kind !== "method") {
+      const classMethods = indexData.filter(
+        (i) => i.asset_type === "sdk" && i.kind === "method" && i.urn.startsWith(item.urn + "#")
+      );
+      renderData.methods = classMethods.map((m) => ({
+        name: m.name,
+        signature: m.signature,
+        description: m.summary
+      }));
+    }
+    const mdContent = generator.generate(renderData);
+    const outPath = path3.join(outputDir, baseName);
+    await fs3.writeFile(outPath, mdContent, "utf8");
+    generatedFiles.add(baseName);
+    console.log(`Generated doc: ${outPath}`);
+  }
+}
+
+// src/commands/merge.ts
+import fs4 from "fs-extra";
+import path4 from "path";
+import { parseUrn } from "@farris/api-wiki-contract-schema";
+async function mergeCommand(options) {
+  console.log(`Executing merge: srcDir=${options.srcDir}, destDir=${options.destDir}`);
+  const srcDir = path4.resolve(options.srcDir);
+  const destDir = path4.resolve(options.destDir);
+  const srcCatalogPath = path4.join(srcDir, "catalog.json");
+  const srcIndexPath = path4.join(srcDir, "index.json");
+  if (!await fs4.pathExists(srcCatalogPath) || !await fs4.pathExists(srcIndexPath)) {
+    throw new Error(`Invalid source directory. "catalog.json" and "index.json" are required at: "${srcDir}"`);
+  }
+  const srcCatalog = await fs4.readJson(srcCatalogPath);
+  const version = srcCatalog.version || srcCatalog.versions && srcCatalog.versions[srcCatalog.versions.length - 1];
+  if (!version) {
+    throw new Error(`"version" is missing in source catalog.json (nor found in versions array)`);
+  }
+  const urn = srcCatalog.urn || (srcCatalog.asset ? `asset:${srcCatalog.asset}` : void 0);
+  if (!urn) {
+    throw new Error(`"urn" (or legacy "asset") is missing in source catalog.json`);
+  }
+  let assetName;
+  try {
+    const parsed = parseUrn(urn);
+    assetName = parsed.asset;
+  } catch (err) {
+    throw new Error(`Invalid URN in source catalog.json: ${err.message}`);
+  }
+  await fs4.ensureDir(destDir);
+  const versionsPath = path4.join(destDir, "versions.json");
+  const srcViewPath = path4.join(srcDir, "view.json");
+  const hasView = await fs4.pathExists(srcViewPath);
+  let versionsObj = {
+    versions: [],
+    latest: "",
+    assets: {}
+  };
+  if (await fs4.pathExists(versionsPath)) {
+    try {
+      const existing = await fs4.readJson(versionsPath);
+      if (Array.isArray(existing)) {
+        versionsObj.versions = existing;
+        versionsObj.latest = existing[existing.length - 1] || "";
+        for (const v of existing) {
+          const indexExists = await fs4.pathExists(path4.join(destDir, v, "index.json"));
+          const viewExists = await fs4.pathExists(path4.join(destDir, v, "view.json"));
+          versionsObj.assets[v] = {
+            "index.json": indexExists,
+            "view.json": viewExists
+          };
+        }
+      } else {
+        versionsObj = existing;
+      }
+    } catch {
+    }
+  }
+  if (!versionsObj.versions.includes(version)) {
+    versionsObj.versions.push(version);
+    versionsObj.versions.sort();
+  }
+  versionsObj.latest = versionsObj.versions[versionsObj.versions.length - 1];
+  versionsObj.assets[version] = {
+    "index.json": true,
+    "view.json": hasView
+  };
+  await fs4.writeJson(versionsPath, versionsObj, { spaces: 2 });
+  const versionSubDir = path4.join(destDir, version);
+  await fs4.ensureDir(versionSubDir);
+  await fs4.copyFile(srcIndexPath, path4.join(versionSubDir, "index.json"));
+  if (hasView) {
+    await fs4.copyFile(srcViewPath, path4.join(versionSubDir, "view.json"));
+  }
+  const destCatalogPath = path4.join(destDir, "catalog.json");
+  const normalizedSrcCatalog = {
+    urn: srcCatalog.urn || `asset:${assetName}`,
+    type: srcCatalog.type || srcCatalog.asset_type || "rest",
+    name: srcCatalog.name || srcCatalog.title || assetName,
+    description: srcCatalog.description || srcCatalog.summary || "",
+    owner: srcCatalog.owner || "unknown",
+    visibility: srcCatalog.visibility || "internal",
+    lifecycle: srcCatalog.lifecycle || "production",
+    versions: versionsObj.versions,
+    coordinates: Array.isArray(srcCatalog.coordinates) ? srcCatalog.coordinates : srcCatalog.coordinates ? [srcCatalog.coordinates] : [],
+    relations: srcCatalog.relations || []
+  };
+  let finalCatalog = {};
+  if (await fs4.pathExists(destCatalogPath)) {
+    const existingCatalog = await fs4.readJson(destCatalogPath);
+    let existingCoordinates = existingCatalog.coordinates || [];
+    if (!Array.isArray(existingCoordinates)) {
+      existingCoordinates = Object.keys(existingCoordinates).map((key) => ({
+        type: key,
+        version: existingCatalog.version || "unknown",
+        repo: existingCoordinates[key]
+      }));
+    }
+    const coordinates = existingCoordinates.length > 0 ? existingCoordinates : normalizedSrcCatalog.coordinates;
+    const relations = existingCatalog.relations || normalizedSrcCatalog.relations;
+    const deployments = existingCatalog.deployments || {};
+    finalCatalog = {
+      ...normalizedSrcCatalog,
+      coordinates,
+      relations,
+      deployments
+    };
+  } else {
+    finalCatalog = {
+      ...normalizedSrcCatalog
+    };
+  }
+  await fs4.writeJson(destCatalogPath, finalCatalog, { spaces: 2 });
+  console.log(`Successfully merged asset "${assetName}" version "${version}" into target metadata.`);
+}
+
+// src/commands/generate-catalog.ts
+import fs5 from "fs-extra";
+import path5 from "path";
+async function generateCatalogCommand(options) {
+  console.log(`Executing generate-catalog: metaDir=${options.metaDir}`);
+  const metaDir = path5.resolve(options.metaDir);
+  if (!await fs5.pathExists(metaDir)) {
+    throw new Error(`Meta root directory does not exist: "${metaDir}"`);
+  }
+  const globalCatalogPath = path5.join(metaDir, "catalog.json");
+  const searchIndexDir = path5.join(metaDir, "search-index");
+  await fs5.ensureDir(searchIndexDir);
+  const globalCatalogList = [];
+  const items = await fs5.readdir(metaDir);
+  for (const itemName of items) {
+    const assetDir = path5.join(metaDir, itemName);
+    if (itemName === "search-index" || itemName === "catalog.json") continue;
+    const stat = await fs5.stat(assetDir);
+    if (!stat.isDirectory()) continue;
+    const catalogPath = path5.join(assetDir, "catalog.json");
+    if (!await fs5.pathExists(catalogPath)) continue;
+    const assetCatalog = await fs5.readJson(catalogPath);
+    if (assetCatalog.visibility === "restricted") {
+      console.log(`Skipping restricted asset: ${itemName}`);
+      continue;
+    }
+    const versionsPath = path5.join(assetDir, "versions.json");
+    let versions = [];
+    let latestVersion = "";
+    if (await fs5.pathExists(versionsPath)) {
+      try {
+        const versionsData = await fs5.readJson(versionsPath);
+        if (Array.isArray(versionsData)) {
+          versions = versionsData;
+          latestVersion = versions[versions.length - 1] || "";
+        } else {
+          versions = versionsData.versions || [];
+          latestVersion = versionsData.latest || versions[versions.length - 1] || "";
+        }
+      } catch (err) {
+        console.error(`Error parsing versions.json for ${itemName}: ${err.message}`);
+      }
+    }
+    const urn = assetCatalog.urn || `asset:${assetCatalog.asset || itemName}`;
+    const type = assetCatalog.type || assetCatalog.asset_type || "rest";
+    const name = assetCatalog.name || assetCatalog.title || itemName;
+    const description = assetCatalog.description || assetCatalog.summary || "";
+    const owner = assetCatalog.owner || "unknown";
+    const visibility = assetCatalog.visibility || "internal";
+    const lifecycle = assetCatalog.lifecycle || "production";
+    globalCatalogList.push({
+      urn,
+      type,
+      name,
+      description,
+      owner,
+      visibility,
+      lifecycle,
+      latest: latestVersion,
+      dir: itemName
+    });
+    const assetIndexData = [];
+    for (const version of versions) {
+      const versionIndexPath = path5.join(assetDir, version, "index.json");
+      if (await fs5.pathExists(versionIndexPath)) {
+        try {
+          const indexItems = await fs5.readJson(versionIndexPath);
+          if (Array.isArray(indexItems)) {
+            for (const item of indexItems) {
+              assetIndexData.push({
+                urn: item.urn,
+                name: item.name,
+                title: item.title,
+                signature: item.signature,
+                summary: item.summary,
+                tags: item.tags || [],
+                deprecated: item.deprecated || false,
+                version
+              });
+            }
+          }
+        } catch (err) {
+          console.error(`Error reading index for ${itemName}@${version}: ${err.message}`);
+        }
+      }
+    }
+    const searchSlicePath = path5.join(searchIndexDir, `${itemName}.json`);
+    await fs5.writeJson(searchSlicePath, assetIndexData, { spaces: 2 });
+  }
+  const globalCatalog = {
+    assets: globalCatalogList,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await fs5.writeJson(globalCatalogPath, globalCatalog, { spaces: 2 });
+  console.log(`Successfully generated global catalog at: ${globalCatalogPath}`);
+  console.log(`Successfully generated search index directory at: ${searchIndexDir}`);
+}
+
+// src/bin/aw-cli.ts
+var program = new Command();
+program.name("aw-cli").description("api-wiki \u6784\u5EFA\u671F\u4E0E\u5408\u5E76\u671F\u5DE5\u5177\u94FE CLI").version("1.0.0", "-V, --cli-version");
+program.command("adapt").description("\u4ECE\u539F\u751F native.json \u8F6C\u5316\u4E3A index.json \u53CA view.json").requiredOption("-t, --type <type>", "\u8D44\u4EA7\u7C7B\u578B (rest|grpc|graphql|async|component|sdk)").requiredOption("-i, --input <path>", "\u539F\u751F native.json \u7684\u8F93\u5165\u7269\u7406\u8DEF\u5F84").requiredOption("-o, --output-dir <path>", "\u9002\u914D\u5143\u6570\u636E\u7684\u8F93\u51FA\u76EE\u5F55\u8DEF\u5F84").requiredOption("--asset <name>", "\u5F53\u524D\u8D44\u4EA7\u540D\u79F0 (kebab-case)").requiredOption("--version <ver>", "\u5F53\u524D\u8D44\u4EA7\u7248\u672C\u53F7").action(async (options) => {
+  try {
+    const validTypes = ["rest", "grpc", "graphql", "async", "component", "sdk"];
+    if (!validTypes.includes(options.type)) {
+      console.error(`Error: Invalid type "${options.type}". Supported types: ${validTypes.join(", ")}`);
+      process.exit(1);
+    }
+    await adaptCommand(options);
+  } catch (err) {
+    console.error(`Error during adapt: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("validate").description("\u6267\u884C\u672C\u5730\u5143\u6570\u636E\u53CC\u5C42\u6821\u9A8C\u95E8\u7981").requiredOption("-d, --dir <path>", "\u5F85\u6821\u9A8C\u7684\u5143\u6570\u636E\u8D44\u4EA7\u7248\u672C\u76EE\u5F55").action(async (options) => {
+  try {
+    await validateCommand(options);
+  } catch (err) {
+    console.error(`Error during validate: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("generate-docs").description("\u57FA\u4E8E\u58F0\u660E\u5F0F EJS \u4E0E YAML \u5E03\u5C40\u63CF\u8FF0\u7B26\u751F\u6210 Markdown \u9875\u9762").requiredOption("-d, --dir <path>", "\u5143\u6570\u636E\u8D44\u4EA7\u7248\u672C\u76EE\u5F55").option("-l, --layout <path>", "\u81EA\u5B9A\u4E49\u7684 YAML \u6A21\u677F\u63CF\u8FF0\u7B26\u8DEF\u5F84").option("-o, --output-dir <path>", "Markdown \u9875\u9762\u8F93\u51FA\u76EE\u6807\u76EE\u5F55").action(async (options) => {
+  try {
+    await generateDocsCommand(options);
+  } catch (err) {
+    console.error(`Error during generate-docs: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("merge").description("\u5C06\u5355\u4E2A\u6784\u5EFA\u7248\u672C\u4EA7\u7269\u5408\u5E76\u5165\u5927\u4ED3\u7684\u8D44\u4EA7\u76EE\u5F55\u5185").requiredOption("--src-dir <path>", "\u53D1\u5E03\u6E90\u5143\u6570\u636E\u76EE\u5F55").requiredOption("--dest-dir <path>", "\u5927\u4ED3\u7684\u76EE\u6807\u8D44\u4EA7\u7269\u7406\u8DEF\u5F84").action(async (options) => {
+  try {
+    await mergeCommand(options);
+  } catch (err) {
+    console.error(`Error during merge: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.command("generate-catalog").description("\u4E2D\u592E\u805A\u5408\u91CD\u6784\u5168\u5C40 catalog.json \u4E0E\u641C\u7D22\u7D22\u5F15").requiredOption("--meta-dir <path>", "\u5927\u4ED3\u7684 meta/ \u6839\u76EE\u5F55\u8DEF\u5F84").action(async (options) => {
+  try {
+    await generateCatalogCommand(options);
+  } catch (err) {
+    console.error(`Error during generate-catalog: ${err.message}`);
+    process.exit(1);
+  }
+});
+program.on("command:*", () => {
+  console.error(`Error: Invalid command. Use --help to list available commands.`);
+  process.exit(1);
+});
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`Unexpected system error: ${err.message}`);
+  process.exit(1);
+});