skillwiki 0.9.20 → 0.9.21

package/dist/cli.js

@@ -3527,8 +3527,8 @@ function buildCliSurface() {
   backupCmd2.command("restore").option("--bucket <name>").option("--endpoint <url>").option("--region <region>").option("--target <dir>").option("--wiki <name>");
   const memoryCmd2 = program2.commands.find((c) => c.name() === "memory");
   memoryCmd2.command("topics").option("--project <slug>").option("--limit <n>").option("--wiki <name>");
-  memoryCmd2.command("index").requiredOption("--project <slug>").option("--wiki <name>");
-  memoryCmd2.command("recall").requiredOption("--project <slug>").requiredOption("--topic <slug>").option("--limit <n>").option("--wiki <name>");
+  memoryCmd2.command("index").requiredOption("--project <slug>").option("--check").option("--if-stale").option("--wiki <name>");
+  memoryCmd2.command("recall").requiredOption("--project <slug>").requiredOption("--topic <slug>").option("--scope <scope>").option("--limit <n>").option("--wiki <name>");
   memoryCmd2.command("import").requiredOption("--from <path>").requiredOption("--project <slug>").option("--dry-run").option("--apply").option("--max-bytes <n>").option("--wiki <name>");
   const fleetCmd2 = program2.commands.find((c) => c.name() === "fleet");
   fleetCmd2.command("validate");
@@ -9044,24 +9044,34 @@ async function runMemoryTopics(input) {
 async function runMemoryIndex(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
-  const warnings = [];
-  const sourcePages = dedupePages(scan.data.allMarkdown);
-  const sources = [];
-  for (const page of sourcePages) {
-    const source = await readMemorySource(page, input.project, warnings);
-    if (source) sources.push(source);
+  const state = await buildMemoryIndexState(scan.data.allMarkdown, input.project);
+  let status;
+  if (input.check || input.ifStale) {
+    const checked = await checkMemoryIndex(input.vault, input.project, state);
+    if (!checked.ok) return checked.error;
+    status = checked.data;
+    if (input.check || !status.stale) {
+      return {
+        exitCode: ExitCode.OK,
+        result: ok({
+          ...status,
+          files_written: [],
+          warnings: state.warnings,
+          humanHint: renderMemoryIndexStatusHint(status)
+        })
+      };
+    }
   }
   const generatedAt = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d{3}Z$/, "Z");
-  const topics = buildTopics(input.project, sources);
   const relCachePath = memoryCacheRelPath(input.project);
   const absCachePath = join39(input.vault, relCachePath);
   await mkdir14(join39(input.vault, ".skillwiki", "memory", input.project), { recursive: true });
   await writeFile15(absCachePath, `${JSON.stringify({
     generated_at: generatedAt,
     project: input.project,
-    topics,
-    sources,
-    warnings
+    topics: state.topics,
+    sources: state.sources,
+    warnings: state.warnings
   }, null, 2)}
 `, "utf8");
   return {
@@ -9069,18 +9079,31 @@ async function runMemoryIndex(input) {
     result: ok({
       project: input.project,
       generated_at: generatedAt,
-      topic_count: topics.length,
-      source_count: sources.length,
-      topics,
+      cache_present: status?.cache_present ?? true,
+      stale: status?.stale ?? false,
+      drift: status?.drift ?? emptyMemoryIndexDrift(),
+      topic_count: state.topics.length,
+      source_count: state.sources.length,
+      topics: state.topics,
       files_written: [relCachePath],
-      warnings,
-      humanHint: `indexed ${sources.length} memory sources into ${topics.length} topics for ${input.project}`
+      warnings: state.warnings,
+      humanHint: `indexed ${state.sources.length} memory sources into ${state.topics.length} topics for ${input.project}`
     })
   };
 }
 async function runMemoryRecall(input) {
   const scan = await scanVault(input.vault);
   if (!scan.ok) return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  const scope = normalizeRecallScope(input.scope);
+  if (input.scope && !scope) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", {
+        path: "memory recall --scope",
+        message: `invalid memory recall scope: ${String(input.scope)}`
+      })
+    };
+  }
   const cacheText = await readMemoryCache(input.vault, input.project);
   if (!cacheText) {
     return {
@@ -9088,6 +9111,7 @@ async function runMemoryRecall(input) {
       result: ok({
         project: input.project,
         topic: input.topic,
+        ...scope ? { scope } : {},
         sources: [],
         humanHint: `no memory topics cache found for project ${input.project}`
       })
@@ -9106,12 +9130,13 @@ async function runMemoryRecall(input) {
     };
   }
   const limit = normalizeLimit(input.limit);
-  const sources = normalizeSources(parsed.sources).filter((source) => source.topics.includes(input.topic)).filter((source) => source.memory_privacy !== "secret-blocked").sort(compareSources).slice(0, limit);
+  const sources = normalizeSources(parsed.sources).filter((source) => source.topics.includes(input.topic)).filter((source) => source.memory_privacy !== "secret-blocked").filter((source) => source.memory_status !== "archived" && source.memory_status !== "rejected").filter((source) => recallScopeMatches(source, input.project, scope)).sort((a, b) => compareRecallSources(a, b, input.project, scope)).slice(0, limit);
   return {
     exitCode: ExitCode.OK,
     result: ok({
       project: input.project,
       topic: input.topic,
+      ...scope ? { scope } : {},
       sources,
       humanHint: renderRecallHint(input.topic, sources)
     })
@@ -9172,6 +9197,115 @@ async function runMemoryImport(input) {
     })
   };
 }
+async function buildMemoryIndexState(pages, project) {
+  const warnings = [];
+  const sourcePages = dedupePages(pages);
+  const sources = [];
+  for (const page of sourcePages) {
+    const source = await readMemorySource(page, project, warnings);
+    if (source) sources.push(source);
+  }
+  return {
+    sources,
+    topics: buildTopics(project, sources),
+    warnings
+  };
+}
+async function checkMemoryIndex(vault, project, current) {
+  const relCachePath = memoryCacheRelPath(project);
+  const cacheText = await readIfExists3(join39(vault, relCachePath));
+  if (!cacheText) {
+    return {
+      ok: true,
+      data: {
+        project,
+        cache_present: false,
+        stale: true,
+        topic_count: current.topics.length,
+        source_count: current.sources.length,
+        topics: current.topics,
+        drift: emptyMemoryIndexDrift(),
+        files_written: [],
+        warnings: current.warnings,
+        humanHint: ""
+      }
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(cacheText);
+  } catch (e) {
+    return {
+      ok: false,
+      error: {
+        exitCode: ExitCode.WRITE_FAILED,
+        result: err("WRITE_FAILED", {
+          path: relCachePath,
+          message: `invalid memory topics cache: ${String(e)}`
+        })
+      }
+    };
+  }
+  const cachedSources = normalizeSources(parsed.sources);
+  const cachedTopics = normalizeTopics(parsed.topics);
+  const drift = compareMemorySources(current.sources, cachedSources);
+  const stale = drift.missing_sources.length > 0 || drift.removed_sources.length > 0 || drift.changed_sources.length > 0 || !sameStringSet(current.topics.map((topic) => topic.name), cachedTopics.map((topic) => topic.name));
+  return {
+    ok: true,
+    data: {
+      project,
+      generated_at: stringField2(parsed.generated_at) || void 0,
+      cache_present: true,
+      stale,
+      topic_count: current.topics.length,
+      source_count: current.sources.length,
+      topics: current.topics,
+      drift,
+      files_written: [],
+      warnings: current.warnings,
+      humanHint: ""
+    }
+  };
+}
+function compareMemorySources(current, cached) {
+  const currentByPath = new Map(current.map((source) => [source.path, source]));
+  const cachedByPath = new Map(cached.map((source) => [source.path, source]));
+  const missing_sources = current.filter((source) => !cachedByPath.has(source.path)).map((source) => source.path).sort((a, b) => a.localeCompare(b));
+  const removed_sources = cached.filter((source) => !currentByPath.has(source.path)).map((source) => source.path).sort((a, b) => a.localeCompare(b));
+  const changed_sources = current.filter((source) => {
+    const cachedSource = cachedByPath.get(source.path);
+    return !!cachedSource && !sameMemorySource(source, cachedSource);
+  }).map((source) => source.path).sort((a, b) => a.localeCompare(b));
+  return { missing_sources, removed_sources, changed_sources };
+}
+function sameMemorySource(a, b) {
+  return a.hash === b.hash && a.updated === b.updated && (a.project ?? "") === (b.project ?? "") && (a.memory_kind ?? "") === (b.memory_kind ?? "") && (a.memory_scope ?? "") === (b.memory_scope ?? "") && (a.memory_policy ?? "") === (b.memory_policy ?? "") && a.memory_privacy === b.memory_privacy && a.memory_status === b.memory_status && sameStringSet(a.topics, b.topics);
+}
+function sameStringSet(a, b) {
+  if (a.length !== b.length) return false;
+  const left = [...a].sort((x, y) => x.localeCompare(y));
+  const right = [...b].sort((x, y) => x.localeCompare(y));
+  return left.every((value, index) => value === right[index]);
+}
+function emptyMemoryIndexDrift() {
+  return {
+    missing_sources: [],
+    removed_sources: [],
+    changed_sources: []
+  };
+}
+function renderMemoryIndexStatusHint(status) {
+  if (!status.cache_present) {
+    return `memory index cache missing for ${status.project}; rebuild with memory index --project ${status.project}`;
+  }
+  if (!status.stale) {
+    return `memory index cache current for ${status.project}: ${status.source_count} sources, ${status.topic_count} topics`;
+  }
+  const changed = status.drift.changed_sources.length;
+  const missing = status.drift.missing_sources.length;
+  const removed = status.drift.removed_sources.length;
+  return `memory index cache stale for ${status.project}: ${missing} missing, ${removed} removed, ${changed} changed sources`;
+}
 async function readIfExists3(path) {
   try {
     return await readFile26(path, "utf8");
@@ -9401,6 +9535,26 @@ function compareTopics(a, b) {
 function compareSources(a, b) {
   return b.updated.localeCompare(a.updated) || a.path.localeCompare(b.path);
 }
+function normalizeRecallScope(value) {
+  if (!value) return void 0;
+  return isRecallScope(value) ? value : void 0;
+}
+function isRecallScope(value) {
+  return value === "project" || value === "global" || value === "cross-agent" || value === "all";
+}
+function recallScopeMatches(source, project, scope) {
+  if (!scope || scope === "all") return true;
+  if (scope === "project") return isProjectMemorySource(source, project);
+  return source.memory_scope === scope;
+}
+function compareRecallSources(a, b, project, scope) {
+  if (scope !== "all") return compareSources(a, b);
+  return b.updated.localeCompare(a.updated) || Number(isProjectMemorySource(b, project)) - Number(isProjectMemorySource(a, project)) || a.path.localeCompare(b.path);
+}
+function isProjectMemorySource(source, project) {
+  const scope = source.memory_scope || "project";
+  return scope === "project" && (!source.project || source.project === project);
+}
 function renderHumanHint(topics) {
   if (topics.length === 0) return "no memory topics found";
   return topics.map((topic) => {
@@ -11231,7 +11385,7 @@ async function postCommit(vault, exitCode) {
   if (!porcelain || porcelain.trim().length === 0) return;
   const { gitStrict: gitStrict2 } = await import("./git-M4WGJ5G3.js");
   try {
-    gitStrict2(vault, ["add", "-A", "--", ...VAULT_COMMIT_PATHSPEC]);
+    gitStrict2(vault, ["add", "-A", "--", "."]);
     for (const generatedPath of VAULT_GENERATED_COMMIT_PATHS) {
       try {
         gitStrict2(vault, ["reset", "HEAD", "--", generatedPath]);
@@ -11656,21 +11810,24 @@ memoryCmd.command("topics [vault]").description("list topic-oriented memory from
     limit: opts.limit
   }), v.vault, { postCommit: false });
 });
-memoryCmd.command("index [vault]").description("build the derived project memory topic cache").requiredOption("--project <slug>", "project slug").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+memoryCmd.command("index [vault]").description("build the derived project memory topic cache").requiredOption("--project <slug>", "project slug").option("--check", "report whether the local project memory cache is missing or stale without writing", false).option("--if-stale", "rebuild the local project memory cache only when it is missing or stale", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runMemoryIndex({
     vault: v.vault,
-    project: opts.project
-  }), v.vault);
+    project: opts.project,
+    check: !!opts.check,
+    ifStale: !!opts.ifStale
+  }), v.vault, { postCommit: !opts.check });
 });
-memoryCmd.command("recall [vault]").description("recall bounded source summaries for a memory topic").requiredOption("--project <slug>", "project slug").requiredOption("--topic <slug>", "memory topic slug").option("--limit <n>", "maximum sources to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+memoryCmd.command("recall [vault]").description("recall bounded source summaries for a memory topic").requiredOption("--project <slug>", "project slug").requiredOption("--topic <slug>", "memory topic slug").option("--scope <scope>", "memory scope: project, global, cross-agent, or all").option("--limit <n>", "maximum sources to return", (s) => parseInt(s, 10), 10).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
   const v = await resolveVaultArg(vault, opts.wiki);
   if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
   else emit(await runMemoryRecall({
     vault: v.vault,
     project: opts.project,
     topic: opts.topic,
+    scope: opts.scope,
     limit: opts.limit
   }), v.vault, { postCommit: false });
 });

package/package.json

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

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

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