skillwiki 0.4.4 → 0.5.0

package/dist/cli.js

@@ -10,7 +10,7 @@ import {
 // src/cli.ts
 import { readFileSync as readFileSync10 } from "fs";
 import { join as join38 } from "path";
-import { Command } from "commander";
+import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
 var ExitCode = {
@@ -2442,6 +2442,147 @@ async function runRawBodyDedup(vault) {
   };
 }
 
+// src/utils/cli-surface.ts
+import { Command } from "commander";
+function buildCliSurface() {
+  const program2 = new Command();
+  program2.name("skillwiki");
+  program2.option("--human", "render terminal-readable output instead of JSON");
+  program2.command("hash");
+  program2.command("fetch-guard");
+  program2.command("validate").option("--apply").option("--vault <dir>").option("--wiki <name>");
+  program2.command("graph");
+  program2.command("canvas");
+  program2.command("overlap").option("--wiki <name>");
+  program2.command("query").option("--limit <n>").option("--wiki <name>");
+  program2.command("orphans").option("--wiki <name>");
+  program2.command("audit");
+  program2.command("install").option("--target <dir>").option("--dry-run").option("--skills-root <dir>").option("--symlink");
+  program2.command("path").option("--vault <dir>").option("--target <dir>").option("--wiki <name>").option("--init-time").option("--explain");
+  program2.command("lang").option("--lang <code>").option("--explain");
+  program2.command("init").option("--target <dir>").requiredOption("--domain <text>").option("--taxonomy <csv>").option("--lang <code>").option("--force").option("--no-env").option("--profile <name>");
+  program2.command("links").option("--wiki <name>");
+  program2.command("tag-audit").option("--wiki <name>");
+  program2.command("index-check").option("--wiki <name>");
+  program2.command("index-link-format").option("--wiki <name>");
+  program2.command("topic-map-check").option("--threshold <n>").option("--wiki <name>");
+  program2.command("stale").option("--archive").option("--days <n>").option("--force-scan").option("--wiki <name>");
+  program2.command("claim").option("--project <slug>").option("--slug <slug>").option("--wiki <name>");
+  program2.command("pagesize").option("--lines <n>").option("--wiki <name>");
+  program2.command("log-rotate").option("--threshold <n>").option("--apply").option("--wiki <name>");
+  program2.command("lint").option("--days <n>").option("--lines <n>").option("--log-threshold <n>").option("--fix").option("--wiki <name>");
+  program2.command("config");
+  program2.command("doctor");
+  program2.command("status").option("--wiki <name>");
+  program2.command("archive").option("--wiki <name>");
+  program2.command("drift").option("--apply").option("--new <date>").option("--wiki <name>");
+  program2.command("dedup").option("--apply").option("--wiki <name>");
+  program2.command("migrate-citations").option("--dry-run").option("--wiki <name>");
+  program2.command("frontmatter-fix").option("--dry-run").option("--wiki <name>");
+  program2.command("update").option("--tag <tag>");
+  program2.command("self-update").option("--check");
+  program2.command("transcripts").option("--since <date>").option("--wiki <name>");
+  program2.command("project-index").option("--apply").option("--wiki <name>");
+  program2.command("compound");
+  program2.command("tag-sync").option("--dry-run").option("--wiki <name>");
+  program2.command("sync");
+  program2.command("backup");
+  program2.command("seed").option("--wiki <name>");
+  program2.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--wiki <name>");
+  program2.command("ingest").requiredOption("--vault <path>").requiredOption("--type <type>").requiredOption("--title <title>").option("--tags <csv>").option("--provenance <provenance>").option("--dry-run");
+  const graphCmd = program2.commands.find((c) => c.name() === "graph");
+  graphCmd.command("build").option("--out <path>").option("--wiki <name>");
+  const canvasCmd2 = program2.commands.find((c) => c.name() === "canvas");
+  canvasCmd2.command("generate").option("--graph-path <path>").option("--wiki <name>");
+  const configCmd2 = program2.commands.find((c) => c.name() === "config");
+  configCmd2.command("get");
+  configCmd2.command("set");
+  configCmd2.command("list").option("--profiles");
+  configCmd2.command("path");
+  const compoundCmd2 = program2.commands.find((c) => c.name() === "compound");
+  compoundCmd2.command("promote").requiredOption("--project <slug>").option("--dry-run").option("--wiki <name>");
+  compoundCmd2.command("list").requiredOption("--project <slug>").option("--wiki <name>");
+  compoundCmd2.command("delete").requiredOption("--project <slug>").option("--wiki <name>");
+  const syncCmd2 = program2.commands.find((c) => c.name() === "sync");
+  syncCmd2.command("status").option("--wiki <name>");
+  syncCmd2.command("push").option("--wiki <name>");
+  syncCmd2.command("pull").option("--wiki <name>");
+  const backupCmd2 = program2.commands.find((c) => c.name() === "backup");
+  backupCmd2.command("sync").option("--dry-run").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--prune").option("--wiki <name>");
+  backupCmd2.command("restore").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--target <dir>").option("--wiki <name>");
+  const surface = /* @__PURE__ */ new Map();
+  const rootFlags = new Set(program2.options.map((o) => o.long ?? o.short).filter((f) => f != null));
+  function walk2(cmd, prefix, parentFlags) {
+    const key = prefix ? `${prefix}.${cmd.name()}` : cmd.name();
+    const flags = /* @__PURE__ */ new Set([...parentFlags, ...cmd.options.map((o) => o.long ?? o.short).filter((f) => f != null)]);
+    surface.set(key, flags);
+    for (const sub of cmd.commands) {
+      walk2(sub, key, flags);
+    }
+  }
+  for (const cmd of program2.commands) {
+    walk2(cmd, "", rootFlags);
+  }
+  return surface;
+}
+var CLI_REF_RE = /`skillwiki\s+([a-z][a-z0-9-]*(?:\s+[a-z][a-z0-9-]*)?)((?:\s+--[a-z][a-z0-9-]*(?:\s+(?!--)\S+)?)*)`/g;
+function validateCliRefs(text, page, surface) {
+  const violations = [];
+  const allKeys = new Set(surface.keys());
+  const parentKeys = /* @__PURE__ */ new Set();
+  for (const key of allKeys) {
+    const dotIdx = key.indexOf(".");
+    if (dotIdx >= 0) parentKeys.add(key.slice(0, dotIdx));
+  }
+  for (const match of text.matchAll(CLI_REF_RE)) {
+    const fullMatch = match[0];
+    const cmdPart = match[1];
+    const flagTokens = [...fullMatch.matchAll(/--([a-z][a-z0-9-]*)/g)].map((m) => `--${m[1]}`);
+    const words = cmdPart.split(/\s+/);
+    let resolvedKey;
+    if (words.length >= 2) {
+      const twoWordKey = `${words[0]}.${words[1]}`;
+      if (allKeys.has(twoWordKey)) {
+        resolvedKey = twoWordKey;
+      }
+    }
+    if (!resolvedKey) {
+      if (words.length >= 2) {
+        const oneWordKey2 = words[0];
+        const parentHasSubcommands = [...allKeys].some((k) => k.startsWith(oneWordKey2 + "."));
+        if (parentHasSubcommands) {
+          violations.push({ page, ref: fullMatch.replace(/^`|`$/g, ""), reason: "unknown_command" });
+          continue;
+        }
+      }
+      const oneWordKey = words[0];
+      if (allKeys.has(oneWordKey)) {
+        resolvedKey = oneWordKey;
+      }
+    }
+    if (!resolvedKey) {
+      violations.push({ page, ref: fullMatch.replace(/^`|`$/g, ""), reason: "unknown_command" });
+      continue;
+    }
+    const validFlags = surface.get(resolvedKey);
+    const dotIdx = resolvedKey.indexOf(".");
+    let allValidFlags = validFlags;
+    if (dotIdx >= 0) {
+      const parentKey = resolvedKey.slice(0, dotIdx);
+      const parentFlags = surface.get(parentKey);
+      if (parentFlags) {
+        allValidFlags = /* @__PURE__ */ new Set([...validFlags, ...parentFlags]);
+      }
+    }
+    for (const flag of flagTokens) {
+      if (!allValidFlags.has(flag)) {
+        violations.push({ page, ref: fullMatch.replace(/^`|`$/g, ""), reason: "unknown_flag" });
+      }
+    }
+  }
+  return violations;
+}
+
 // src/commands/lint.ts
 var STRUCT_MIN_BODY_LINES = 60;
 var STRUCT_MIN_SECTIONS = 3;
@@ -2475,7 +2616,7 @@ function extractSourceEntries(rawFm) {
 }
 var ERROR_ORDER = ["broken_wikilinks", "invalid_frontmatter", "raw_dedup", "broken_sources", "tag_not_in_taxonomy"];
 var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "index_incomplete", "index_link_format", "stale_page", "page_too_large", "log_rotate_needed", "orphans", "compound_refs", "legacy_citation_style", "orphaned_citations", "duplicate_frontmatter", "work_item_health", "orphaned_project_pages", "missing_overview"];
-var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram"];
+var INFO_ORDER = ["bridges", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "missing_diagram", "cli_refs"];
 async function runLint(input) {
   const buckets = {};
   const fixed = [];
@@ -2688,6 +2829,17 @@ async function runLint(input) {
       }
     }
     if (orphanedProjectPages.length > 0) buckets.orphaned_project_pages = orphanedProjectPages;
+    const cliRefFlags = [];
+    const cliSurface = buildCliSurface();
+    const allScanPages = [...scan.data.typedKnowledge, ...scan.data.raw, ...scan.data.workItems, ...scan.data.compound];
+    for (const page of allScanPages) {
+      const text = await readPage(page);
+      const violations = validateCliRefs(text, page.relPath, cliSurface);
+      for (const v of violations) {
+        cliRefFlags.push(`${v.page}: ${v.ref} (${v.reason})`);
+      }
+    }
+    if (cliRefFlags.length > 0) buckets.cli_refs = cliRefFlags;
     if (input.fix && legacyPages.length > 0) {
       const FENCE_RE2 = /```[\s\S]*?```/g;
       const INLINE_MARKER = /\^\[raw\/[^\]]+\]/g;
@@ -6172,7 +6324,7 @@ async function postCommit(vault, exitCode) {
 
 // src/cli.ts
 var pkg = JSON.parse(readFileSync10(new URL("../package.json", import.meta.url), "utf8"));
-var program = new Command();
+var program = new Command2();
 program.name("skillwiki").description("Deterministic helpers for CodeWiki skills").version(pkg.version);
 program.option("--human", "render terminal-readable output instead of JSON");
 async function emit(r, vault) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "private": true,
   "files": [
     "wiki-*",