diffwiki 0.17.3 → 0.18.0-rc.202611121225.38e2b9e

package/dist/bin.js

@@ -7,6 +7,7 @@ import { ensureHome } from "diffwiki-core";
 import { spawn as spawn4 } from "child_process";
 import path5 from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
+import { readFile } from "fs/promises";
 import { Command, Option } from "commander";
 import {
   addExternalCollection,
@@ -14,6 +15,13 @@ import {
   collectionGitStatus,
   createArticle,
   createCollection,
+  createMetaRecord,
+  initMeta,
+  reindexMeta,
+  findCollection,
+  parseFrontmatter,
+  CollectionNotFoundError,
+  DiffwikiError as DiffwikiError2,
   doctor,
   getConfigValue,
   initRepoWiki,
@@ -38,10 +46,9 @@ import {
   resolveCwdCollection,
   resolveEditorCommand,
   resolveEditTarget,
-  setArticleMeta,
   setConfigValue,
   setTags,
-  updateArticleBody
+  updateArticle
 } from "diffwiki-core";
 
 // src/version.ts
@@ -359,15 +366,18 @@ async function createArticleAction(target, opts) {
 async function updateArticleAction(target, opts) {
   const tagList = splitTags(opts.tag);
   const hasMeta = opts.audience !== void 0 || opts.status !== void 0;
-  if (opts.body === void 0 && tagList.length === 0 && !hasMeta) {
-    console.error("Nothing to update \u2014 pass -b/--body, -t/--tag, --audience, and/or --status.");
+  if (opts.title === void 0 && opts.body === void 0 && tagList.length === 0 && !hasMeta) {
+    console.error("Nothing to update \u2014 pass --title, -b/--body, -t/--tag, --audience, and/or --status.");
     process.exitCode = 1;
     return;
   }
-  let article;
-  if (opts.body !== void 0) article = await updateArticleBody(target, opts.body);
-  if (tagList.length > 0) article = await setTags(target, tagList);
-  if (hasMeta) article = await setArticleMeta(target, { audience: opts.audience, status: opts.status });
+  const article = await updateArticle(target, {
+    title: opts.title,
+    body: opts.body,
+    ...tagList.length ? { tags: tagList } : {},
+    audience: opts.audience,
+    status: opts.status
+  });
   console.log(`Updated ${article.path}`);
 }
 async function removeArticleAction(target) {
@@ -524,9 +534,9 @@ async function templatesInitAction() {
   if (seeded.length === 0 && skipped.length === 0) console.log("  (no bundled templates found)");
 }
 async function templatesListAction(opts) {
-  const infos = await listTemplates(bundledTemplatesDir());
+  const infos = await listTemplates(bundledTemplatesDir(), opts.category);
   if (infos.length === 0) {
-    console.log("No bundled templates found.");
+    console.log("No templates found.");
     return;
   }
   if (opts.json) {
@@ -538,6 +548,38 @@ async function templatesListAction(opts) {
     console.log(`${t.shape}	${t.purpose}${budget}`);
   }
 }
+function reportMeta(result, opts) {
+  if (opts.json) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`Metadata: ${result.created.length} mirrors created, ${result.kept.length} kept.`);
+    for (const file of result.index_paths) console.log(file);
+  }
+  for (const warning of result.warnings) console.error(`! ${warning}`);
+  for (const error of result.errors) console.error(`\u2716 ${error}`);
+  if (result.errors.length) process.exitCode = 1;
+}
+async function metaInitAction(name, opts) {
+  const entries = name ? [await findCollection(name)] : await listCollections2();
+  if (entries.some((entry) => !entry)) throw new CollectionNotFoundError(name);
+  reportMeta(await initMeta(entries.filter((entry) => entry !== void 0)), opts);
+}
+async function metaNewAction(target, opts) {
+  const colon = target.indexOf(":");
+  const name = colon < 0 ? target : target.slice(0, colon);
+  const articlePath = colon < 0 ? void 0 : target.slice(colon + 1);
+  const entry = await findCollection(name);
+  if (!entry) throw new CollectionNotFoundError(name);
+  const template = (await listTemplates(bundledTemplatesDir(), "meta")).find((item) => item.shape === opts.template);
+  if (!template) throw new DiffwikiError2(`Metadata template ${opts.template} not found. Run: diffwiki templates init`);
+  try {
+    const { body } = parseFrontmatter(await readFile(template.path, "utf8"));
+    const record = await createMetaRecord(entry, articlePath, opts.template, body.replace(/<!--[\s\S]*?-->/g, ""));
+    console.log(opts.json ? JSON.stringify(record, null, 2) : record.path);
+  } catch (err) {
+    if (err instanceof DiffwikiError2) throw err;
+    throw new DiffwikiError2(`Cannot capture ${target}: ${String(err)}`);
+  }
+}
 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));
@@ -702,8 +744,8 @@ function createProgram() {
       "deprecated"
     ])
   ).action(withErrors((target, opts) => createArticleAction(target, opts)));
-  article.command("update").description("Update an article's body, tags, audience, and/or status").argument("<target>", '"collection:slug"').option("-b, --body <markdown>", "replace the article body").option("-t, --tag <tag>", "replace all tags (repeatable, comma-separated)", collect, []).addOption(new Option("--audience <audience>", "set visibility").choices(["public", "private", "system"])).addOption(new Option("--status <status>", "set publish status").choices(["draft", "published", "deprecated"])).action(withErrors((target, opts) => updateArticleAction(target, opts)));
-  article.command("remove").description("Delete an article").argument("<target>", '"collection:slug"').action(withErrors((target) => removeArticleAction(target)));
+  article.command("update").description("Update an article's display title, body, tags, audience, and/or status").argument("<target>", '"collection:slug"').option("--title <title>", "set the display title without renaming the file").option("-b, --body <markdown>", "replace the article body").option("-t, --tag <tag>", "replace all tags (repeatable, comma-separated)", collect, []).addOption(new Option("--audience <audience>", "set visibility").choices(["public", "private", "system"])).addOption(new Option("--status <status>", "set publish status").choices(["draft", "published", "deprecated"])).action(withErrors((target, opts) => updateArticleAction(target, opts)));
+  article.command("remove").description("Delete an article").argument("<target>", '"[collection:]slug"').action(withErrors((target) => removeArticleAction(target)));
   article.command("edit").description("Open an article in your editor \u2014 GUI not required").argument("<target>", '"collection:slug"').option("--editor <cmd>", "editor command (overrides config `editor`, $VISUAL, $EDITOR)").action(withErrors((target, opts) => editAction(target, opts.editor)));
   const tags = program.command("tags").description("Manage an article's tags");
   const registerTagsSub = (name, description, fn) => {
@@ -745,9 +787,21 @@ function createProgram() {
   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 meta = program.command("meta").description("Capture raw sources beside collection and article paths");
+  meta.command("init").description("Create missing source manifests for existing articles").argument("[collection]", "limit to one registered collection").option("--json", "output paths and diagnostics as JSON").action(withErrors(metaInitAction));
+  meta.command("new").description("Create a source-record template for a collection or exact article filename").argument("<target>", "collection or collection:relative-file.md").addOption(
+    new Option("--template <kind>", "source template").choices(["history", "external-source-extract", "dream-learning"]).makeOptionMandatory()
+  ).option("--json", "output the record and index paths as JSON").action(withErrors(metaNewAction));
+  meta.command("reindex").description("Refresh generated source listings from current metadata files").argument("[collection]", "limit to one metadata collection").option("--json", "output paths and diagnostics as JSON").action(
+    withErrors(
+      async (name, opts) => reportMeta(await reindexMeta(name), opts)
+    )
+  );
   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)));
+  templates.command("list").description("List templates with their shape + purpose (read from each template\u2019s frontmatter)").addOption(
+    new Option("--category <category>", "template category").choices(["article", "meta", "all"]).default("article")
+  ).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)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffwiki",
-  "version": "0.17.3",
+  "version": "0.18.0-rc.202611121225.38e2b9e",
   "description": "diffwiki command-line interface",
   "license": "MIT",
   "type": "module",
@@ -18,7 +18,7 @@
     "@logtape/logtape": "^2.2.4",
     "@logtape/file": "^2.2.4",
     "commander": "^13.0.0",
-    "diffwiki-core": "0.17.3"
+    "diffwiki-core": "0.18.0-rc.202611121225.38e2b9e"
   },
   "devDependencies": {
     "@types/node": "^22.0.0"

package/templates/collection-index-template.md

@@ -18,7 +18,7 @@ Authoring rules:
   - No prose paragraphs, no examples, no code blocks
   - Keep descriptions to a single clause — enough to distinguish siblings
   - 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
+  - Use concise descriptive titles in article frontmatter. An index.md filename must not become the display title "index" or a path ending in /index.
   - Tag the collection topic and add collection-index tag
   - Default to public audience and published status for index files
 -->

package/templates/dream-learning-template.md

@@ -0,0 +1,30 @@
+---
+shape: dream-learning
+category: meta
+purpose: Keep one dream change inspectable through its raw evidence and observed result.
+---
+
+## Run
+
+- Tool: dw-dream
+- Run / original event time: unknown
+
+## Raw user requests
+
+Not captured. Quote the request and include its session/message location. Do not infer preferences.
+
+## Raw session/tool outputs
+
+Not captured. Include speaker, command, output, exit status, and source locations. Label assistant text as generated and unverified.
+
+## Source snippets
+
+Not captured. Preserve the relevant original code or document excerpts and their locations.
+
+## Source record links
+
+None captured. Link preserved primary evidence from every affected page.
+
+## Change and result
+
+Not captured. Include affected paths, the exact patch or action, and the observed result. Record partial failures plainly.

package/templates/external-source-extract-template.md

@@ -0,0 +1,29 @@
+---
+shape: external-source-extract
+category: meta
+purpose: Store retrieved documentation, web page, or paper excerpts with their origin.
+---
+
+## Source
+
+- Requested URL: unknown
+- Resolved URL: unknown
+- Title / author / publisher: unknown
+- Published date / document version: unknown
+- Retrieved at (UTC): unknown
+- Heading / page / line locator: unknown
+
+## Exact excerpt
+
+Not captured. Quote the retrieved text with enough context. Do not substitute a summary.
+
+## Capture details
+
+- Format / extraction method: unknown
+- Coverage / omitted sections / truncation: unknown
+- Retrieval failure or redactions: unknown
+- Original attachment path / checksum, if retained: unknown
+
+## Source record links
+
+None captured. Link related records without replacing their original text.

package/templates/history-template.md

@@ -0,0 +1,37 @@
+---
+shape: history
+category: meta
+purpose: Preserve original user requests, verbatim harness sessions, human review feedback, session outputs, and source code.
+---
+
+## Raw harness session and artifacts
+
+Not captured. Record the harness name, raw session transcript path, and relative links to verbatim session logs or artifacts stored under `.meta/attachments/<record-id>/`.
+
+## Raw user requests
+
+Not captured. Include exact quotations, speaker, original time, and session/message location when known.
+
+## Stated rationale
+
+Not captured. Quote the user's explanation. Do not infer a reason.
+
+## Human review and plan feedback (.difflab & forge PR/MR comments)
+
+Not captured. Include verbatim human reviewer comments from `.difflab/plans/*/revisions/*.md` (`## Feedback`), `.difflab/reviews/*/REVIEW.md`, and directly on the forge (`gh`/`glab` PR/MR review comments when not in local `.difflab` files) with file/revision/thread locators. Exclude AI-generated review comments.
+
+## Raw session/tool outputs
+
+Not captured. Include the command, output, exit status, and source location. Label assistant text as generated and unverified.
+
+## Source snippets
+
+Not captured. Preserve code and whitespace. Include repository, file, symbol/lines, commit when known, and local changes.
+
+## Source record links
+
+None captured. Link any shared collection evidence, attachments, or earlier records.
+
+## Change and result
+
+Not captured. Name affected files and the observed result. Keep capture time separate from the original event time.

package/templates/session-transcript-template.md

@@ -2,25 +2,33 @@
 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.
+<!-- SESSION TRANSCRIPT. Summarizes the session while verbatim raw harness logs,
+session artifacts, and .difflab review/plan files are stored in
+~/.diffwiki/meta/transcripts/ via `diffwiki meta new "transcripts:<project>/<file>.md" --template history`.
 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.
+as a knowledge entry. Do not invent dialogue, causes, preferences, or lessons.
 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>
+**Tool:** <claude-code|antigravity|codex|cursor|opencode|goose|pi|aider> · **Project:** <repo-or-path> · **Date:** <YYYY-MM-DD> · **Session:** <id-if-known>
 
-## Worked on
-- <goal — what was attempted and the outcome>
+## Session summary
+- <1-3 bullet summary of the goal, approach, and outcome>
 
-## Issues & learnings
-- <problem — root cause — how it was resolved (or that it's unresolved)>
+## Raw user requests
+- <exact quotation, original time, session/message location>
 
-## Decisions & patterns
-- <architectural decision or reusable pattern observed — and why>
+## Reviews and plan feedback (.difflab & human reviewer comments)
+- <summary and exact quotes of HUMAN feedback from .difflab/plans/*/revisions/*.md (## Feedback), .difflab/reviews/*/REVIEW.md, and human review comments made directly on the forge (GitHub/GitLab PR/MR review threads via `gh`/`glab`) when not already in local .difflab files; exclude AI-generated review comments; or "None in this session.">
 
-## Key tool actions
-- <notable commands, files created/changed, workflows — the reproducible bits>
+## Raw session outputs
+- <speaker/role, exact output, source message location; label assistant text generated/unverified>
 
-## Open threads
-- <unfinished work, follow-ups, questions for next time>
+## Commands and results
+- <command, exact relevant stdout/stderr, exit status, original event time>
+
+## Source snippets
+- <original code/document excerpt, repository, file/lines, commit/version, local changes>
+
+## Source locations and gaps
+- <links to verbatim raw harness session log and session/.difflab artifacts in ~/.diffwiki/meta/transcripts/.meta/; omitted/redacted/unavailable material>