diffwiki 0.14.0 → 0.15.0

package/dist/bin.js

@@ -2,6 +2,8 @@
 
 // src/cli.ts
 import { spawn as spawn4 } from "child_process";
+import path4 from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command, Option } from "commander";
 import {
   addExternalCollection,
@@ -23,7 +25,13 @@ import {
   registerPlugin,
   removeArticle,
   removePlugin,
+  repairPlugins,
   removeTags,
+  seedTemplates,
+  listTemplates,
+  readContextCollections,
+  setContextCollections,
+  resolveDefaultSearchMode,
   resolveCwdCollection,
   resolveEditorCommand,
   resolveEditTarget,
@@ -350,7 +358,8 @@ async function tagsAction(fn, target, tags) {
   console.log(`${article.path} \u2192 tags: ${article.tags.join(", ") || "(none)"}`);
 }
 async function indexAction(opts) {
-  const provider = await loadSearchProvider();
+  const { engine } = await resolveDefaultSearchMode();
+  const provider = await loadSearchProvider(engine);
   if (!provider) {
     const installable = (await listSearchModes()).filter((m) => m.plugin !== "native");
     console.log(
@@ -363,10 +372,16 @@ async function indexAction(opts) {
 }
 async function queryAction(term, opts) {
   const names = opts.collection ? opts.collection.split(",").map((s) => s.trim()).filter(Boolean) : void 0;
+  const expansions = [
+    ...(opts.lex ?? []).map((query) => ({ type: "lex", query })),
+    ...(opts.vec ?? []).map((query) => ({ type: "vec", query })),
+    ...(opts.hyde ?? []).map((query) => ({ type: "hyde", query }))
+  ];
   const queryOpts = {
     engine: opts.engine,
     collection: names && names.length === 1 ? names[0] : names,
-    type: opts.type
+    type: opts.type,
+    ...expansions.length > 0 ? { expansions } : {}
   };
   const outcome = await search(term, queryOpts);
   const hits = outcome.hits;
@@ -456,7 +471,19 @@ async function configGetAction(key) {
   const value = await getConfigValue(key);
   console.log(value ?? "(unset)");
 }
-async function doctorAction() {
+async function doctorAction(opts) {
+  if (opts.fix) {
+    console.log("Repairing plugins (installing missing tools)\u2026");
+    const repairs = await repairPlugins();
+    for (const r of repairs) {
+      for (const step of r.setup.steps) {
+        console.log(
+          `${icon(step.ok ? "ok" : "warn")} ${r.name} \xB7 ${step.step}${step.message ? ` \u2014 ${step.message}` : ""}`
+        );
+      }
+    }
+    console.log("");
+  }
   const diagnostics = await doctor();
   for (const d of diagnostics) {
     console.log(`${icon(d.level)} ${d.message}`);
@@ -465,6 +492,69 @@ async function doctorAction() {
     process.exitCode = 1;
   }
 }
+function bundledTemplatesDir() {
+  return path4.resolve(path4.dirname(fileURLToPath4(import.meta.url)), "..", "templates");
+}
+async function templatesInitAction() {
+  const { seeded, skipped, dir } = await seedTemplates(bundledTemplatesDir());
+  console.log(`Templates \u2192 ${dir}`);
+  if (seeded.length > 0) console.log(`  seeded: ${seeded.join(", ")}`);
+  if (skipped.length > 0) console.log(`  kept existing (user overrides): ${skipped.join(", ")}`);
+  if (seeded.length === 0 && skipped.length === 0) console.log("  (no bundled templates found)");
+}
+async function templatesListAction(opts) {
+  const infos = await listTemplates(bundledTemplatesDir());
+  if (infos.length === 0) {
+    console.log("No bundled templates found.");
+    return;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(infos, null, 2));
+    return;
+  }
+  for (const t of infos) {
+    const budget = t.budget ? `  [${t.budget[0]}\u2013${t.budget[1]} tok]` : "";
+    console.log(`${t.shape}	${t.purpose}${budget}`);
+  }
+}
+var parseNames = (csv) => csv.split(",").map((s) => s.trim()).filter(Boolean);
+async function warnUnknownCollections(names) {
+  const known = new Set((await listCollections2()).map((c) => c.name));
+  const unknown = names.filter((n) => !known.has(n));
+  if (unknown.length > 0) {
+    console.error(`! not in your collections: ${unknown.join(", ")} (see: diffwiki collection list)`);
+  }
+}
+function reportContext(collections, file) {
+  console.log(`context.collections = [${collections.join(", ")}] \u2192 ${file}`);
+}
+async function contextShowAction() {
+  const cols = await readContextCollections(process.cwd());
+  if (cols.length === 0) {
+    console.log("No recall context set. Set one: diffwiki context set <a,b,c>");
+    return;
+  }
+  for (const c of cols) console.log(c);
+}
+async function contextSetAction(names) {
+  const cols = parseNames(names);
+  const file = await setContextCollections(process.cwd(), cols);
+  await warnUnknownCollections(cols);
+  reportContext(cols, file);
+}
+async function contextAddAction(names) {
+  const merged = await readContextCollections(process.cwd());
+  for (const n of parseNames(names)) if (!merged.includes(n)) merged.push(n);
+  const file = await setContextCollections(process.cwd(), merged);
+  await warnUnknownCollections(merged);
+  reportContext(merged, file);
+}
+async function contextRemoveAction(names) {
+  const drop = new Set(parseNames(names));
+  const kept = (await readContextCollections(process.cwd())).filter((c) => !drop.has(c));
+  const file = await setContextCollections(process.cwd(), kept);
+  reportContext(kept, file);
+}
 async function lintAction(opts) {
   const result = await lintCollections(opts.collections);
   for (const file of result.files) {
@@ -573,7 +663,7 @@ function createProgram() {
   registerTagsSub("remove", "Remove from an article's tags", removeTags);
   registerTagsSub("set", "Replace an article's tags", setTags);
   const searchCmd = program.command("search").description("Search articles and manage the index");
-  searchCmd.command("query").alias("q").description("Search articles via the resolved search engine (native fallback if none)").option("--engine <name>", "search engine/plugin (default: config defaultSearch, else native)").option("-c, --collection <names>", "limit to a collection (comma-separated for a set)").option("-t, --type <type>", "search type (engine-defined, e.g. keyword|semantic|hybrid)").argument("[term]", "search term", "").action(
+  searchCmd.command("query").alias("q").description("Search articles via the resolved search engine (native fallback if none)").option("--engine <name>", "search engine/plugin (default: config defaultSearch, else native)").option("-c, --collection <names>", "limit to a collection (comma-separated for a set)").option("-t, --type <type>", "search type (engine-defined, e.g. keyword|semantic|hybrid)").option("--lex <query>", "BM25 keyword variant (repeatable)", collect, []).option("--vec <query>", "semantic variant \u2014 a natural-language question (repeatable)", collect, []).option("--hyde <query>", "hypothetical-answer passage variant (repeatable)", collect, []).argument("[term]", "search term (used as ranking intent when variants are given)", "").action(
     withErrors(
       (term, opts) => queryAction(term, opts)
     )
@@ -600,10 +690,18 @@ function createProgram() {
   ui.command("down").description("Stop the running diffwiki UI").action(withErrors(downAction));
   ui.command("status").description("Show whether the diffwiki UI is running").action(withErrors(statusAction));
   ui.command("open").description("Open the diffwiki UI in the browser (starting it if needed)").option("-p, --port <port>", "port to serve on", "4321").action(withErrors((opts) => openAction(opts)));
+  const context = program.command("context").description("Manage recall/search context (diffwiki.yaml \u2192 context.collections)");
+  context.command("show").description("Print the current recall-context collections").action(withErrors(contextShowAction));
+  context.command("set").description("Replace the recall-context collections").argument("<names>", "comma-separated collection names").action(withErrors((names) => contextSetAction(names)));
+  context.command("add").description("Add collections to the recall context").argument("<names>", "comma-separated collection names").action(withErrors((names) => contextAddAction(names)));
+  context.command("remove").description("Remove collections from the recall context").argument("<names>", "comma-separated collection names").action(withErrors((names) => contextRemoveAction(names)));
+  const templates = program.command("templates").description("Manage authoring templates (~/.diffwiki/templates)");
+  templates.command("init").description("Seed ~/.diffwiki/templates from the bundled templates (never overwrites your own)").action(withErrors(templatesInitAction));
+  templates.command("list").description("List templates with their shape + purpose (read from each template\u2019s frontmatter)").option("--json", "output as JSON").action(withErrors((opts) => templatesListAction(opts)));
   const config = program.command("config").description("Read and write diffwiki config");
   config.command("set").description("Set a config value (e.g. defaultCollection, or defaultSearch <engine[:type]>)").argument("<key>", "config key").argument("<value>", "config value").action(withErrors((key, value) => configSetAction(key, value)));
   config.command("get").description("Read a config value").argument("<key>", "config key").action(withErrors((key) => configGetAction(key)));
-  program.command("doctor").description("Diagnose configuration issues").action(withErrors(doctorAction));
+  program.command("doctor").description("Diagnose configuration issues").option("--fix", "attempt to repair issues (re-provision plugins, auto-installing missing tools)").action(withErrors((opts) => doctorAction(opts)));
   program.command("lint").description("Lint articles against the template shapes (frontmatter, budgets, references)").option("-c, --collections <scope>", "current | all | comma-separated names", "current").action(withErrors((opts) => lintAction(opts)));
   return program;
 }
@@ -611,14 +709,14 @@ function createProgram() {
 // src/logging.ts
 import { mkdirSync } from "fs";
 import os from "os";
-import path4 from "path";
+import path5 from "path";
 import { configureSync, getConfig } from "@logtape/logtape";
 import { getRotatingFileSink } from "@logtape/file";
 import { resolveLogLevel } from "diffwiki-core";
 var configured = false;
 function diffwikiHome() {
   const override = process.env.DIFFWIKI_HOME;
-  return override && override.length > 0 ? override : path4.join(os.homedir(), ".diffwiki");
+  return override && override.length > 0 ? override : path5.join(os.homedir(), ".diffwiki");
 }
 function resolveCliLevel(argv) {
   if (argv.includes("-v") || argv.includes("--verbose")) return "debug";
@@ -635,9 +733,9 @@ function configureCliLogging(argv = process.argv) {
   if (configured || getConfig() != null) return;
   configured = true;
   const level = resolveCliLevel(argv);
-  const logsDir = path4.join(diffwikiHome(), "logs");
+  const logsDir = path5.join(diffwikiHome(), "logs");
   mkdirSync(logsDir, { recursive: true });
-  const logFile = path4.join(logsDir, "diffwiki.log");
+  const logFile = path5.join(logsDir, "diffwiki.log");
   const stderrSink = (record) => {
     process.stderr.write(formatLine(record) + "\n");
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "diffwiki command-line interface",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,8 @@
     "diffwiki": "./dist/bin.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "publishConfig": {
     "access": "public"
@@ -17,7 +18,7 @@
     "@logtape/logtape": "^2.2.4",
     "@logtape/file": "^2.2.4",
     "commander": "^13.0.0",
-    "diffwiki-core": "0.14.0"
+    "diffwiki-core": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/templates/guide-template.md

@@ -0,0 +1,68 @@
+---
+shape: guide
+purpose: Teaches the reasoning behind a topic — connects related patterns and explains why they work.
+budget: [1500, 5000]
+---
+
+<!--
+Use this shape to teach. A guide explains the reasoning, trade-offs, and mental model behind a set of related patterns. It answers "why" and "how does this fit together" — not "what steps do I follow". If the reader needs a procedure, use recipe-with-steps. If they need a lookup, use reference.
+
+Authoring rules:
+  - Adhere to the template structure
+  - One H2 per concept or insight; each section covers one idea
+  - State trade-offs and limits, not just the happy path
+  - Show, don't tell: replace prose explanations with Mermaid diagrams, tables, and code examples wherever possible. A sequence diagram beats three paragraphs of data-flow description. A comparison table beats a list of trade-offs.
+  - Soft-wrap prose
+  - Use inline references as needed for other wiki articles and external sources
+  - Do not copy over html comments or the template specific yaml frontmatter above this section. Write a diffwiki article yaml frontmatter as shown below this comment.
+  - Use concise descriptive titles in article frontmatter
+  - Tag programming languages, frameworks, topics of relevance to support vector embedding/search
+  - Default to public audience and draft status unless user specifies otherwise
+-->
+
+---
+
+title: TITLE
+tags:
+
+- guide
+- TAG1
+- TAG2
+- ...
+  audience: public
+  status: draft
+
+---
+
+One to three sentences. State the insight or principle this guide teaches and name the concrete systems or patterns it covers. State what the guide does not cover and link to the adjacent recipe or reference: see [<related>](./<related>.md).
+
+## <The core concept — concrete noun, not "Overview">
+
+State what this concept is and why it matters. Name the constraint or trade-off that makes it non-obvious.
+
+```<lang>
+<illustrative example — under ~40 lines>
+```
+
+Explain what the example demonstrates. Point to the part that carries the lesson.
+
+## <Second concept or pattern>
+
+State how this concept relates to the previous one. Describe the trade-off or decision point a reader faces between the two.
+
+If the relationship needs a diagram:
+
+```mermaid
+graph LR
+    A[Concept A] --> B[Concept B]
+    B --> C[Outcome]
+```
+
+## <When this breaks / limits>
+
+State the condition under which the pattern fails. One paragraph per failure mode. Link to the recipe that handles each case: see [<recipe>](../<collection>/<slug>.md).
+
+## References
+
+- [<Primary source>](<url>) — <one-line reason>
+- [<Related recipe or guide>](../<collection>/<slug>.md) — <one-line reason>

package/templates/recipe-template.md

@@ -0,0 +1,58 @@
+---
+shape: recipe
+purpose: One contained pattern with a single canonical example.
+budget: [300, 1000]
+---
+
+<!--
+Use this shape when the recipe is one contained pattern: intro + a single canonical example + notes. No ordered steps. If the recipe has ordered steps, use `recipe-with-steps-template.md` instead.
+
+Authoring rules:
+  - Adhere to the template structure
+  - Soft-wrap prose
+  - Use inline references as needed for other wiki articles and external sources
+  - Do not copy over html comments or the template specific yaml frontmatter above this section. Write a diffwiki article yaml frontmatter as shown below this comment.
+  - Use concise descriptive titles in article frontmatter
+  - Tag programming languages, frameworks, topics of relevance to support vector embedding/search
+  - Default to public audience and draft status unless user specifies otherwise
+-->
+
+---
+
+title: TITLE
+tags:
+
+- recipe
+- TAG1
+- TAG2
+- ...
+  audience: public
+  status: draft
+
+---
+
+Write two to four sentences of intro prose. Describe what the recipe covers, utilizing concrete symbols and verbs a reader would search for. Mention adjacent phrasings when possible so vector search hits from alternative wording.
+
+## Recipe
+
+State the pattern in one sentence — what the code does and when to reach for it.
+
+```<lang>
+<code — the canonical example, under ~70 lines>
+```
+
+Follow-up notes only if the code isn't self-explanatory. Cover variations, edge cases, related recipes, etc.
+
+## Troubleshooting
+
+<!-- Optional. Include only if there are real, specific problems users hit. Skip if you'd otherwise write generic warnings. -->
+
+- <Symptom> — <root cause> — <fix>.
+- <Symptom> — <root cause> — <fix>.
+
+## References
+
+<!-- Do not omit even if references are also inline -->
+
+- [<Name>](url) — <one-line reason (optional)>
+- [<Related recipe>](../<collection>/<slug>.md) — <one-line reason (optional)>

package/templates/recipe-with-steps-template.md

@@ -0,0 +1,76 @@
+---
+shape: recipe-with-steps
+purpose: An ordered sequence — do X, then Y, then Z.
+budget: [500, 1500]
+---
+
+<!--
+Use this shape when the recipe is an ordered sequence — install X, then configure Y, then run Z. If there are no ordered steps, use `recipe-template.md` (simple) instead.
+
+Authoring rules:
+  - Adhere to the template structure
+  - Number every step: `### Step 1 — <verb + object>`, and keep each step self-contained
+  - If the sequence grows past ~7 steps, split into two recipes
+  - Soft-wrap prose
+  - Use inline references as needed for other wiki articles and external sources
+  - Do not copy over html comments or the template specific yaml frontmatter above this section. Write a diffwiki article yaml frontmatter as shown below this comment.
+  - Use concise descriptive titles in article frontmatter
+  - Tag programming languages, frameworks, topics of relevance to support vector embedding/search
+  - Default to public audience and draft status unless user specifies otherwise
+-->
+
+---
+
+title: TITLE
+tags:
+
+- recipe
+- TAG1
+- TAG2
+- ...
+  audience: public
+  status: draft
+
+---
+
+Write two to four sentences of intro prose. State what the recipe accomplishes end-to-end, utilizing concrete tools and commands a reader would search for. Mention adjacent phrasings when possible so vector search hits from alternative wording.
+
+## Recipe
+
+One sentence framing the whole sequence — what state the reader is in when they start, and what state they're in when the last step succeeds.
+
+### Step 1 — <verb + object>
+
+One-sentence goal for the step.
+
+```<lang>
+<code — under ~70 lines>
+```
+
+Optional one-line verification (`<cmd> should print <result>`) or an inline link to the sub-topic.
+
+### Step 2 — <verb + object>
+
+One-sentence goal.
+
+```<lang>
+<code>
+```
+
+### Step 3 — <verb + object>
+
+<...>
+
+## Troubleshooting
+
+<!-- Optional. Only real, specific problems. Cross-link to steps by name so retrieval keeps the connection. -->
+
+- <Symptom during step N> — <root cause> — <fix>.
+- <Symptom during step N> — <root cause> — <fix>.
+
+## References
+
+<!-- Do not omit even if references are also inline -->
+
+- [<Name>](url) — <one-line reason (optional)>
+- [<Related recipe>](../<collection>/<slug>.md) — <one-line reason (optional)>

package/templates/reference-template.md

@@ -0,0 +1,70 @@
+---
+shape: reference
+purpose: Authoritative description of commands, flags, config keys, types, or API endpoints — consult while working, not read linearly.
+budget: [300, 2000]
+---
+
+<!--
+Use this shape for lookup tables: CLI flags, config keys, environment variables, type definitions, API endpoints, error codes. A reference entry describes one item — its name, type, default, and effect. It does not explain why, teach, or walk through steps.
+
+Authoring rules:
+  - Adhere to the template structure
+  - Organize entries by the system's own structure (group flags by command, keys by section) — not by frequency of use
+  - One entry per item; keep descriptions to one sentence
+  - Mark required entries explicitly; note all defaults
+  - Add a minimal example only when the effect is not clear from the description alone
+  - Do not add prose narration between entries
+  - Soft-wrap prose in the intro and Notes sections only
+  - Do not copy over html comments or the template specific yaml frontmatter above this section. Write a diffwiki article yaml frontmatter as shown below this comment.
+  - Use concise descriptive titles in article frontmatter
+  - Tag the system, language, or framework this reference covers
+  - Default to public audience and draft status unless user specifies otherwise
+-->
+
+---
+
+title: TITLE
+tags:
+
+- reference
+- TAG1
+- TAG2
+- ...
+  audience: public
+  status: draft
+
+---
+
+One sentence: what system this page covers and the version or scope it applies to. Link to the upstream docs: [<System name>](<official-url>).
+
+## <Command / Section / Group>
+
+One sentence on what this command or group does.
+
+| Flag / Key | Type | Default | Description |
+|---|---|---|---|
+| `<name>` | `<type>` | `<default>` | <one-sentence description> |
+| `<name>` | `<type>` | — | **Required.** <one-sentence description> |
+
+Minimal example where the flag combination is not obvious from the table:
+
+```<lang>
+<example>
+```
+
+## <Second command / section>
+
+<same pattern>
+
+## Notes
+
+<!-- Optional. Warnings, known limits, version-specific behavior, or gotchas that apply across the whole reference — not to a single entry. -->
+
+- <Warning or limit> — <what breaks and what to do instead>.
+
+## References
+
+<!-- Do not omit even if references are also inline -->
+
+- [<Official docs>](<url>) — <one-line reason (optional)>
+- [<Related recipe>](../<collection>/<slug>.md) — <one-line reason (optional)>

package/templates/session-transcript-template.md

@@ -0,0 +1,26 @@
+---
+shape: session-transcript
+purpose: dw-learn capture into the hidden transcripts collection (not linted).
+---
+<!-- SESSION TRANSCRIPT. The agent fills this by introspecting its own session.
+Goes into the hidden `transcripts` collection with `--audience system`; NOT linted
+as a knowledge entry. Terse and factual — raw material for dw-learn, not a doc.
+Title (passed to the CLI) is "<project>/<date>-<short-id>"; tags are
+[transcript, <tool>, <project>]. Do not write frontmatter — the CLI owns it. -->
+
+**Tool:** <claude-code|codex|opencode|goose|pi> · **Project:** <repo-or-path> · **Date:** <YYYY-MM-DD> · **Session:** <id-if-known>
+
+## Worked on
+- <goal — what was attempted and the outcome>
+
+## Issues & learnings
+- <problem — root cause — how it was resolved (or that it's unresolved)>
+
+## Decisions & patterns
+- <architectural decision or reusable pattern observed — and why>
+
+## Key tool actions
+- <notable commands, files created/changed, workflows — the reproducible bits>
+
+## Open threads
+- <unfinished work, follow-ups, questions for next time>