skillwiki 0.9.18 → 0.9.20

package/dist/cli.js

@@ -2866,9 +2866,9 @@ ${content}
 
 // src/commands/lint.ts
 import { existsSync as existsSync6 } from "fs";
-import { readFile as readFile17 } from "fs/promises";
+import { readFile as readFile17, readdir as readdir5 } from "fs/promises";
 import { createHash as createHash5 } from "crypto";
-import { join as join23 } from "path";
+import { join as join23, relative as relative3, sep as sep3 } from "path";
 
 // src/commands/sparse-community.ts
 async function runSparseCommunity(input) {
@@ -3714,6 +3714,7 @@ var ERROR_ORDER = ["sensitive_content", "broken_wikilinks", "invalid_frontmatter
 var WARNING_ORDER = ["raw_body_duplicate", "raw_subdirectory_duplicate", "file_source_url", "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", "missing_diagram"];
 var INFO_ORDER = ["bridges", "sparse_community", "page_structure", "topic_map_recommended", "frontmatter_wikilink", "wikilink_citation", "missing_tldr", "stale_sections", "cli_refs"];
 var KNOWN_BUCKETS = [...ERROR_ORDER, ...WARNING_ORDER, ...INFO_ORDER];
+var CLI_REFS_TYPED_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
@@ -3786,6 +3787,63 @@ function summarizeLintOutput(output, examplesLimit = 3) {
     humanHint: lines.join("\n")
   };
 }
+async function walkMarkdownFiles(absDir, vaultRoot) {
+  const entries = await readdir5(absDir, { withFileTypes: true });
+  const pages = [];
+  for (const entry of entries) {
+    const absPath = join23(absDir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === ".git" || entry.name === "node_modules") continue;
+      pages.push(...await walkMarkdownFiles(absPath, vaultRoot));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      pages.push({ absPath, relPath: relative3(vaultRoot, absPath).split(sep3).join("/") });
+    }
+  }
+  return pages;
+}
+async function collectCliRefsPages(vault) {
+  if (!existsSync6(join23(vault, "SCHEMA.md"))) {
+    return err("VAULT_PATH_INVALID", { root: vault, reason: "SCHEMA.md missing" });
+  }
+  const pages = [];
+  for (const dir of CLI_REFS_TYPED_DIRS) {
+    const absDir = join23(vault, dir);
+    if (!existsSync6(absDir)) continue;
+    pages.push(...await walkMarkdownFiles(absDir, vault));
+  }
+  return ok(pages);
+}
+async function runCliRefsOnly(input) {
+  const pages = await collectCliRefsPages(input.vault);
+  if (!pages.ok) {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: pages };
+  }
+  const cliRefFlags = [];
+  const cliSurface = buildCliSurface();
+  for (const page of pages.data) {
+    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})`);
+    }
+  }
+  const infoOut = cliRefFlags.length > 0 ? [{ kind: "cli_refs", items: cliRefFlags }] : [];
+  const summary = { errors: 0, warnings: 0, info: cliRefFlags.length };
+  const exitCode = cliRefFlags.length > 0 ? ExitCode.LINT_HAS_WARNINGS : ExitCode.OK;
+  const output = {
+    vault: { path: input.vault, source: input.source ?? "resolved" },
+    summary,
+    by_severity: { error: [], warning: [], info: infoOut },
+    fixed: [],
+    unresolved: [],
+    humanHint: `--only cli_refs
+${cliRefFlags.length === 0 ? "0 violations" : `  cli_refs: ${cliRefFlags.length}`}`
+  };
+  return {
+    exitCode,
+    result: ok(input.summary ? summarizeLintOutput(output, input.examplesLimit) : output)
+  };
+}
 async function runLint(input) {
   if (input.only && !KNOWN_BUCKETS.includes(input.only)) {
     return {
@@ -3793,6 +3851,9 @@ async function runLint(input) {
       result: { ok: false, error: "UNKNOWN_BUCKET", detail: `Unknown bucket "${input.only}". Valid: ${KNOWN_BUCKETS.join(", ")}` }
     };
   }
+  if (input.only === "cli_refs") {
+    return runCliRefsOnly(input);
+  }
   const shouldFix = (bucket) => !!input.fix && (!input.only || input.only === bucket);
   const buckets = {};
   const fixed = [];
@@ -5806,6 +5867,8 @@ function checkVaultGitAhead(resolvedPath) {
   );
 }
 function checkVaultGitBehind(resolvedPath) {
+  const staleRemote = checkStaleRemoteMain(resolvedPath);
+  if (staleRemote) return staleRemote;
   return checkVaultGitComparison(
     resolvedPath,
     "vault_git_behind",
@@ -5815,6 +5878,47 @@ function checkVaultGitBehind(resolvedPath) {
     "0 commits behind origin/main"
   );
 }
+function gitRefHash(resolvedPath, ref) {
+  try {
+    const out = execSync2(`git rev-parse --verify ${ref}`, {
+      cwd: resolvedPath,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 2e3
+    }).trim();
+    return out || void 0;
+  } catch {
+    return void 0;
+  }
+}
+function remoteMainHash(resolvedPath) {
+  try {
+    const out = execSync2("git ls-remote origin refs/heads/main", {
+      cwd: resolvedPath,
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 3e3
+    }).trim();
+    const hash = out.split(/\s+/)[0];
+    return /^[0-9a-f]{40}$/i.test(hash) ? hash : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function checkStaleRemoteMain(resolvedPath) {
+  if (resolvedPath === void 0) return void 0;
+  if (!existsSync11(join29(resolvedPath, ".git"))) return void 0;
+  const localOrigin = gitRefHash(resolvedPath, "origin/main");
+  if (!localOrigin) return void 0;
+  const remoteMain = remoteMainHash(resolvedPath);
+  if (!remoteMain || remoteMain === localOrigin) return void 0;
+  return check(
+    "warn",
+    "vault_git_behind",
+    "Vault commits behind",
+    `Remote main differs from local origin/main (${remoteMain.slice(0, 8)} != ${localOrigin.slice(0, 8)}) \u2014 run git fetch before trusting behind count`
+  );
+}
 function checkVaultGitComparison(resolvedPath, id, label, range, nonZeroSuffix, zeroDetail) {
   if (resolvedPath === void 0) {
     return check("pass", id, label, "No vault path \u2014 check skipped");
@@ -6254,6 +6358,53 @@ function vaultSyncChecks(input) {
   const packagedSnapshotPath = join29(shareDir, "wiki-snapshot.sh");
   const legacySnapshotPath = "/root/.hermes/scripts/wiki-snapshot-v3.sh";
   const snapshotPath = input.snapshotScriptPath ?? (existsSync11(packagedSnapshotPath) ? packagedSnapshotPath : legacySnapshotPath);
+  function snapshotLastStatusCheck() {
+    const snapshotLog = join29(logDir, "wiki-snapshot.log");
+    try {
+      const logContent = readFileSync7(snapshotLog, "utf8");
+      const lines = logContent.trim().split("\n").filter(Boolean);
+      if (lines.length === 0) {
+        return check(
+          "warn",
+          "vault_sync_last_push_age",
+          "Vault sync last snapshot status",
+          "Snapshot log file is empty"
+        );
+      }
+      const lastLine = [...lines].reverse().find(
+        (line) => /ERROR|Status: complete|Push successful|No changes to commit/.test(line)
+      ) ?? lines[lines.length - 1];
+      if (/ERROR/.test(lastLine)) {
+        return check(
+          "error",
+          "vault_sync_last_push_age",
+          "Vault sync last snapshot status",
+          `Last snapshot failed: ${lastLine.slice(0, 160)}`
+        );
+      }
+      if (/Status: complete|Push successful|No changes to commit/.test(lastLine)) {
+        return check(
+          "pass",
+          "vault_sync_last_push_age",
+          "Vault sync last snapshot status",
+          lastLine.slice(0, 160)
+        );
+      }
+      return check(
+        "warn",
+        "vault_sync_last_push_age",
+        "Vault sync last snapshot status",
+        `Last snapshot log entry: ${lastLine.slice(0, 160)}`
+      );
+    } catch {
+      return check(
+        "warn",
+        "vault_sync_last_push_age",
+        "Vault sync last snapshot status",
+        `Snapshot log not found at ${snapshotLog}`
+      );
+    }
+  }
   if (input.vaultSyncRole === "snapshotter") {
     const c12 = existsSync11(snapshotPath) ? check("pass", "vault_sync_installed", "Vault sync installed", `Found snapshot script: ${snapshotPath}`) : check("error", "vault_sync_installed", "Vault sync installed", `Snapshot script not found at ${snapshotPath}`);
     const serviceScope = input.vaultSyncServiceScope ?? "user";
@@ -6279,12 +6430,7 @@ function vaultSyncChecks(input) {
         c22 = check("error", "vault_sync_jobs_enabled", "Vault sync jobs enabled", `wiki-snapshot.timer check failed (${serviceScope})`);
       }
     }
-    const c32 = check(
-      "pass",
-      "vault_sync_last_push_age",
-      "Vault sync last push recency",
-      "Snapshotter host \u2014 leaf wiki-push log not applicable"
-    );
+    const c32 = snapshotLastStatusCheck();
     const cFetch2 = check(
       "pass",
       "vault_sync_last_fetch_status",
@@ -7916,13 +8062,13 @@ async function runSelfUpdate(input) {
 }
 
 // src/commands/transcripts.ts
-import { readdir as readdir5, stat as stat8, readFile as readFile22 } from "fs/promises";
+import { readdir as readdir6, stat as stat8, readFile as readFile22 } from "fs/promises";
 import { join as join34 } from "path";
 async function runTranscripts(input) {
   const dir = join34(input.vault, "raw", "transcripts");
   let entries;
   try {
-    entries = await readdir5(dir, { withFileTypes: true });
+    entries = await readdir6(dir, { withFileTypes: true });
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: { ok: false, error: "VAULT_PATH_INVALID", detail: `raw/transcripts/ not found: ${dir}` } };
   }
@@ -7947,14 +8093,14 @@ async function runTranscripts(input) {
 }
 
 // src/commands/project-index.ts
-import { readdir as readdir6, readFile as readFile23, writeFile as writeFile11, mkdir as mkdir10 } from "fs/promises";
+import { readdir as readdir7, readFile as readFile23, writeFile as writeFile11, mkdir as mkdir10 } from "fs/promises";
 import { join as join35, dirname as dirname13 } from "path";
 var LAYER2_DIRS = ["entities", "concepts", "comparisons", "queries", "meta"];
 async function runProjectIndex(input) {
   const slug = input.slug;
   const projectDir = join35(input.vault, "projects", slug);
   try {
-    await readdir6(projectDir);
+    await readdir7(projectDir);
   } catch {
     return {
       exitCode: ExitCode.PROJECT_NOT_FOUND,
@@ -7965,7 +8111,7 @@ async function runProjectIndex(input) {
   const entries = [];
   const compoundDir = join35(input.vault, "projects", slug, "compound");
   try {
-    const compoundFiles = await readdir6(compoundDir, { withFileTypes: true });
+    const compoundFiles = await readdir7(compoundDir, { withFileTypes: true });
     for (const entry of compoundFiles) {
       if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
       const filePath = join35(compoundDir, entry.name);
@@ -7988,7 +8134,7 @@ async function runProjectIndex(input) {
   for (const dir of LAYER2_DIRS) {
     let files;
     try {
-      files = await readdir6(join35(input.vault, dir), { withFileTypes: true });
+      files = await readdir7(join35(input.vault, dir), { withFileTypes: true });
     } catch {
       continue;
     }
@@ -8091,7 +8237,7 @@ ${entries.map((e) => `  ${e.type}: [[${e.page.replace(/\.md$/, "")}]] \u2014 ${e
 }
 
 // src/commands/compound.ts
-import { writeFile as writeFile12, mkdir as mkdir11, readdir as readdir7, unlink as unlink4 } from "fs/promises";
+import { writeFile as writeFile12, mkdir as mkdir11, readdir as readdir8, unlink as unlink4 } from "fs/promises";
 import { join as join36 } from "path";
 import { existsSync as existsSync14 } from "fs";
 import { readFile as readFile24 } from "fs/promises";
@@ -8328,7 +8474,7 @@ no compound directory found`
   }
   let dirents;
   try {
-    dirents = await readdir7(compoundDir, { withFileTypes: true });
+    dirents = await readdir8(compoundDir, { withFileTypes: true });
   } catch {
     return {
       exitCode: ExitCode.OK,
@@ -8460,7 +8606,7 @@ ${input.text.trim()}
 
 // src/commands/session-brief.ts
 import { mkdir as mkdir13, readFile as readFile25, writeFile as writeFile14 } from "fs/promises";
-import { join as join38, relative as relative3, sep as sep3 } from "path";
+import { join as join38, relative as relative4, sep as sep4 } from "path";
 var MAX_WORDS = 900;
 async function runSessionBrief(input) {
   const scan = await scanVault(input.vault);
@@ -8564,7 +8710,7 @@ async function readProjectSlug(file) {
   return void 0;
 }
 function inferProjectFromPath(vault, cwd) {
-  const rel = relative3(vault, cwd).split(sep3).join("/");
+  const rel = relative4(vault, cwd).split(sep4).join("/");
   const match = rel.match(/^projects\/([^/]+)(?:\/|$)/);
   return match?.[1];
 }
@@ -8853,8 +8999,8 @@ function dateFromPath(path) {
 
 // src/commands/memory.ts
 import { createHash as createHash8 } from "crypto";
-import { mkdir as mkdir14, readFile as readFile26, readdir as readdir8, stat as stat9, writeFile as writeFile15 } from "fs/promises";
-import { basename as basename2, extname, join as join39, relative as relative4, sep as sep4 } from "path";
+import { mkdir as mkdir14, readFile as readFile26, readdir as readdir9, stat as stat9, writeFile as writeFile15 } from "fs/promises";
+import { basename as basename2, extname, join as join39, relative as relative5, sep as sep5 } from "path";
 async function runMemoryTopics(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
@@ -9041,7 +9187,7 @@ async function collectImportFiles(source) {
   return files.sort((a, b) => a.localeCompare(b));
 }
 async function walkImportFiles(dir, out) {
-  const entries = await readdir8(dir, { withFileTypes: true });
+  const entries = await readdir9(dir, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.name === ".git" || entry.name === "node_modules") continue;
     const path = join39(dir, entry.name);
@@ -9094,7 +9240,7 @@ async function buildImportEntry(file, sourceRoot, project, today, maxBytes) {
   const redacted = redactSensitiveContent(extracted, { file });
   const privacy = redacted.findings.length > 0 ? "sensitive" : "local";
   const sourceSlug = slugify3(basename2(file, extname(file)));
-  const relSource = relative4(sourceRoot, file).split(sep4).join("/");
+  const relSource = relative5(sourceRoot, file).split(sep5).join("/");
   const entry = {
     ...baseEntry,
     status: "ready",
@@ -9166,7 +9312,7 @@ function hiddenString(entry, key) {
   return entry[key] ?? "";
 }
 function classifyImportSource(file) {
-  const rel = file.split(sep4).join("/");
+  const rel = file.split(sep5).join("/");
   const name = basename2(file);
   if (rel.includes("/.codex/memories/")) return "codex-memory";
   if (rel.includes("/.codex/rules/")) return "codex-rule";
@@ -10413,7 +10559,7 @@ function runSyncUnlock(input) {
 
 // src/commands/backup.ts
 import { statSync as statSync5, readdirSync as readdirSync3, readFileSync as readFileSync12, mkdirSync as mkdirSync7, writeFileSync as writeFileSync8 } from "fs";
-import { join as join43, relative as relative5, dirname as dirname14 } from "path";
+import { join as join43, relative as relative6, dirname as dirname14 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -10441,7 +10587,7 @@ function* walkMarkdown(dir, base) {
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
-      yield relative5(base, full).replace(/\\/g, "/");
+      yield relative6(base, full).replace(/\\/g, "/");
     }
   }
 }

package/package.json

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

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

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.9.18",
+  "version": "0.9.20",
   "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.9.18",
+  "version": "0.9.20",
   "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.9.18",
+  "version": "0.9.20",
   "private": true,
   "files": [
     "wiki-*",