skillwiki 0.4.4 → 0.5.1

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 = [];
@@ -2600,7 +2741,7 @@ async function runLint(input) {
       const hasOverview = /^## Overview/m.test(body);
       if (!hasOverview) noOverview.push(page.relPath);
       const bodyFirst15 = body.split("\n").slice(0, 15).join("\n");
-      if (!/^##\s+TL;\s*DR/m.test(bodyFirst15)) missingTldrFlags.push(page.relPath);
+      if (!/^>\s*\*\*TL;DR:?\*\*/m.test(bodyFirst15) && !/^##\s+TL;\s*DR/m.test(bodyFirst15)) missingTldrFlags.push(page.relPath);
       const fmData = extractFrontmatter(text);
       const pageTags = fmData.ok && Array.isArray(fmData.data.tags) ? fmData.data.tags : [];
       if (pageTags.includes("architecture") && !body.includes("```mermaid")) {
@@ -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;
@@ -2834,16 +2986,26 @@ ${trimmedBody}`;
           }
           const body = split.data.body;
           const rawFm = split.data.rawFrontmatter;
-          const trimmedBody = body.replace(/^\n+/, "");
+          const lines = body.split("\n");
+          let insertIndex = 0;
+          for (let i = 0; i < lines.length; i++) {
+            if (/^# /.test(lines[i])) {
+              insertIndex = i + 1;
+              while (insertIndex < lines.length && lines[insertIndex].trim() === "") {
+                insertIndex++;
+              }
+              break;
+            }
+          }
+          if (insertIndex === 0) {
+            lines.splice(0, 0, "", "> **TL;DR:** ");
+          } else {
+            lines.splice(insertIndex, 0, "> **TL;DR:** ");
+          }
+          const trimmedFm = rawFm.endsWith("\n") ? rawFm : rawFm + "\n";
           const newContent = `---
-${rawFm}
----
-
-## TL;DR
-
-- Pending summary.
-
-${trimmedBody}`;
+${trimmedFm}---
+${lines.join("\n")}`;
           await writeFile8(absPath, newContent, "utf8");
           fixed.push(relPath);
         } catch {
@@ -6172,7 +6334,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.1",
   "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.1",
   "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.1",
   "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.1",
   "private": true,
   "files": [
     "wiki-*",

package/skills/wiki-crystallize/SKILL.md

@@ -16,7 +16,7 @@ Standard four reads. If cwd is inside `projects/{slug}/`, also read project READ
 1. Identify type: entity / concept / comparison / query / summary.
 2. Set `provenance:`. Default `research`. If in project context: `project` with `provenance_projects: ["[[slug]]"]`.
 3. Compose the page with citations pre-attached. Reuse existing `raw/` sources where possible. Every page MUST include:
-- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 4. `skillwiki validate <page>`. If non-zero, STOP.
 5. Apply writes: page → `index.md` → `log.md`.

package/skills/wiki-ingest/SKILL.md

@@ -21,7 +21,7 @@ Run `skillwiki lang` at the start. Generate page-body prose, narrative sections,
 2. **Fetch.** Use `web_fetch` (or read local file) under Layer 2 controls (the CLI Layer 2 fetcher applies in tests; in skill runtime use `web_fetch` directly and treat any error as STOP).
 3. **Hash.** Write the raw file (frontmatter + body). Run `skillwiki hash <raw-file>` and embed the result in raw frontmatter `sha256:`.
 4. **Generate page(s).** Compose typed-knowledge page(s) with citations pre-attached (`^[raw/...]` markers). Every page MUST include:
-- `## TL;DR` as the first section after frontmatter — a 1–3 bullet summary of the page's key takeaway.
+- `> **TL;DR:**` blockquote as the first content after the title heading — a one-sentence summary of the page's key takeaway (under 200 chars). See SCHEMA.md `## TL;DR Convention`.
 - For pages tagged `architecture` or explaining workflows/systems: include a Mermaid diagram (`graph TB` or `sequenceDiagram`) in the body. Follow Obsidian-compatible Mermaid rules (see SCHEMA.md `## Mermaid Diagrams`).
 5. **Validate.** For each generated page: run `skillwiki validate <page>`. If exit ≠ 0, STOP — do not write index/log.
 6. **Apply writes in order.** raw → page(s) → `index.md` → `log.md`.