superwiki 0.1.0

package/skills/sw-init/assets/sw.mjs

@@ -0,0 +1,523 @@
+#!/usr/bin/env node
+// Generated by scripts/build.mjs from src/core.js and src/cli.js. Do not edit.
+// Superwiki core: vault model, derived task state and lint. Pure: no fs, no DOM.
+// Runs in Node (docs/.sw/sw.mjs) and inlined in the viewer, so both report the same findings.
+
+export const STATUSES = ['todo', 'in-progress', 'done', 'cancelled'];
+export const VAULT_FOLDERS = ['wiki', 'tasks', 'plans'];
+const ROOT_PAGES = ['index', 'log'];
+
+// ---------- Frontmatter (the YAML subset Superwiki writes: scalars, [inline, lists], "- block" lists) ----------
+function scalar(s) {
+  let v = String(s).trim();
+  if (v.length > 1 && v.startsWith('"') && v.endsWith('"')) v = v.slice(1, -1).replace(/\\(["\\])/g, '$1');
+  else if (v.length > 1 && v.startsWith("'") && v.endsWith("'")) v = v.slice(1, -1).replace(/''/g, "'");
+  if (v.startsWith('[[') && v.endsWith(']]')) v = v.slice(2, -2).trim();
+  return v;
+}
+
+function stripComment(line) {
+  return /["']/.test(line) ? line : line.replace(/(^|\s)#.*$/, '');
+}
+
+export function parseFrontmatter(text) {
+  const src = String(text ?? '').replace(/^/, '');
+  const m = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(src);
+  if (!m) return { data: null, body: src, bodyLine: 1 };
+  const data = {};
+  let key = null;
+  for (const raw of m[1].split(/\r?\n/)) {
+    const line = stripComment(raw);
+    if (!line.trim()) continue;
+    const item = /^\s*-\s+(.*)$/.exec(line);
+    if (item && key) {
+      if (!Array.isArray(data[key])) data[key] = [];
+      data[key].push(scalar(item[1]));
+      continue;
+    }
+    const kv = /^([A-Za-z_][\w-]*):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    key = kv[1];
+    const v = kv[2].trim();
+    if (v === '') data[key] = null;
+    else if (v.startsWith('[') && v.endsWith(']') && !v.startsWith('[[')) {
+      data[key] = v.slice(1, -1).split(',').map(scalar).filter(Boolean);
+    } else data[key] = scalar(v);
+  }
+  return { data, body: src.slice(m[0].length), bodyLine: m[0].split('\n').length };
+}
+
+export function asList(v) {
+  if (v == null || v === '') return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+// ---------- Wikilinks ----------
+const WIKILINK = /(!?)\[\[([^\[\]|#]+)(#[^\[\]|]*)?(?:\|([^\[\]]*))?\]\]/g;
+const isAttachment = target => /\.[A-Za-z0-9]{2,5}$/.test(target) && !/\.md$/i.test(target);
+
+// Links in a markdown body. Fenced and inline code is skipped; `line` is 1-based within the body.
+export function extractWikilinks(body) {
+  const out = [];
+  let fenced = false;
+  String(body ?? '').split(/\r?\n/).forEach((raw, i) => {
+    if (/^\s*(```|~~~)/.test(raw)) { fenced = !fenced; return; }
+    if (fenced) return;
+    const line = raw.replace(/`[^`]*`/g, '');
+    for (const m of line.matchAll(WIKILINK)) {
+      const target = m[2].trim().replace(/\.md$/i, '');
+      if (m[1] === '!' || isAttachment(m[2].trim())) continue;
+      out.push({ target, heading: m[3] ? m[3].slice(1) : null, alias: m[4] ?? null, line: i + 1 });
+    }
+  });
+  return out;
+}
+
+// ---------- Vault ----------
+const key = name => String(name).toLowerCase();
+const areaOf = id => (String(id).includes('-') ? String(id).slice(0, String(id).lastIndexOf('-')) : '');
+
+// files: [{ path, text }] with paths relative to docs/ ("wiki/foo.md"). Anything outside
+// index.md, log.md, wiki/, tasks/ and plans/ belongs to other tools and is ignored.
+export function buildVault(files) {
+  const pages = [];
+  const names = new Map();
+  for (const f of files) {
+    const path = String(f.path).replace(/\\/g, '/').replace(/^\.?\//, '');
+    if (!/\.md$/i.test(path)) continue;
+    const parts = path.split('/');
+    const name = parts[parts.length - 1].replace(/\.md$/i, '');
+    let folder;
+    if (parts.length === 1) { if (!ROOT_PAGES.includes(name)) continue; folder = 'root'; }
+    else if (VAULT_FOLDERS.includes(parts[0])) folder = parts[0];
+    else continue;
+    const fm = parseFrontmatter(f.text);
+    const page = { path, folder, name, nested: parts.length > 2, data: fm.data || {}, hasFrontmatter: !!fm.data, body: fm.body, bodyLine: fm.bodyLine, links: extractWikilinks(fm.body), inbound: [] };
+    pages.push(page);
+    if (!names.has(key(name))) names.set(key(name), []);
+    names.get(key(name)).push(page);
+  }
+  pages.sort((a, b) => a.path.localeCompare(b.path));
+  const vault = { pages, names, tasks: new Map(), plans: new Map(), index: null, log: null };
+  vault.index = pages.find(p => p.folder === 'root' && p.name === 'index') || null;
+  vault.log = pages.find(p => p.folder === 'root' && p.name === 'log') || null;
+  for (const p of pages) for (const l of p.links) {
+    const t = resolve(vault, l.target);
+    if (t && t !== p && !t.inbound.includes(p)) t.inbound.push(p);
+  }
+  for (const p of pages) {
+    if (p.folder === 'plans') vault.plans.set(key(p.name.replace(/-plan$/i, '')), p);
+    if (p.folder !== 'tasks') continue;
+    const d = p.data;
+    const id = String(d.id || p.name);
+    vault.tasks.set(key(id), {
+      id, page: p, area: areaOf(id), title: d.title || '', status: d.status || '',
+      deps: asList(d.deps).map(String), softDeps: asList(d.soft_deps).map(String),
+      milestone: d.milestone || '', priority: d.priority == null || d.priority === '' ? null : Number(d.priority),
+      started: d.started || '', finished: d.finished || '',
+      state: null, wave: 0, dependents: [], plan: null,
+    });
+  }
+  derive(vault);
+  return vault;
+}
+
+export function resolve(vault, target) {
+  const hit = vault.names.get(key(String(target).split('/').pop().replace(/\.md$/i, '')));
+  return hit ? hit[0] : null;
+}
+
+export const taskOf = (vault, id) => vault.tasks.get(key(id)) || null;
+
+// state: done | cancelled | progress | ready | blocked. wave: longest hard-dependency chain below the task.
+function derive(vault) {
+  const depth = new Map();
+  const waveOf = (t, trail) => {
+    if (depth.has(t)) return depth.get(t);
+    if (trail.has(t)) return 0;
+    trail.add(t);
+    let w = 0;
+    for (const id of t.deps) { const d = taskOf(vault, id); if (d) w = Math.max(w, waveOf(d, trail) + 1); }
+    trail.delete(t);
+    depth.set(t, w);
+    return w;
+  };
+  for (const t of vault.tasks.values()) {
+    t.plan = vault.plans.get(key(t.id)) || null;
+    t.wave = waveOf(t, new Set());
+    const open = t.deps.filter(id => taskOf(vault, id)?.status !== 'done');
+    t.openDeps = open;
+    t.openSoftDeps = t.softDeps.filter(id => taskOf(vault, id)?.status !== 'done');
+    t.state = t.status === 'done' ? 'done' : t.status === 'cancelled' ? 'cancelled' : t.status === 'in-progress' ? 'progress' : open.length ? 'blocked' : 'ready';
+    for (const id of [...t.deps, ...t.softDeps]) {
+      const d = taskOf(vault, id);
+      if (d && !d.dependents.includes(t.id)) d.dependents.push(t.id);
+    }
+  }
+}
+
+function cycles(vault) {
+  const found = [];
+  const seen = new Set();
+  const state = new Map();
+  const visit = (t, trail) => {
+    state.set(t, 1);
+    trail.push(t.id);
+    for (const id of [...t.deps, ...t.softDeps]) {
+      const d = taskOf(vault, id);
+      if (!d) continue;
+      if (state.get(d) === 1) {
+        const loop = trail.slice(trail.indexOf(d.id));
+        const sig = [...loop].sort().join(',');
+        if (!seen.has(sig)) { seen.add(sig); found.push([...loop, d.id]); }
+      } else if (!state.get(d)) visit(d, trail);
+    }
+    trail.pop();
+    state.set(t, 2);
+  };
+  for (const t of vault.tasks.values()) if (!state.get(t)) visit(t, []);
+  return found;
+}
+
+// ---------- Lint ----------
+// Finding: { level: 'error' | 'warn', code, path, message }.
+export function lint(vault) {
+  const out = [];
+  const add = (level, code, path, message) => out.push({ level, code, path, message });
+
+  for (const [, list] of vault.names) {
+    if (list.length > 1) add('error', 'duplicate-name', list[0].path, `file name is not unique: ${list.map(p => p.path).join(', ')}`);
+  }
+  if (!vault.index) add('error', 'missing-index', 'index.md', 'docs/index.md is missing');
+
+  for (const p of vault.pages) {
+    if (p.nested) add('warn', 'nested-page', p.path, `${p.folder}/ is flat; move the file up`);
+    // The log is history: entries keep the names pages had when they were written.
+    if (p !== vault.log) for (const l of p.links) {
+      if (!resolve(vault, l.target)) add('error', 'broken-link', p.path, `line ${p.bodyLine + l.line - 1}: [[${l.target}]] has no target`);
+    }
+    if (p.folder === 'wiki') {
+      if (!p.data.type) add('error', 'missing-field', p.path, 'frontmatter `type` is missing');
+      if (!p.data.summary) add('warn', 'missing-field', p.path, 'frontmatter `summary` is missing');
+      if (vault.index && !vault.index.links.some(l => resolve(vault, l.target) === p)) add('warn', 'not-in-index', p.path, 'page is not listed in index.md');
+      // A source summary is reachable from the index and need not be cited yet; ingest stays a three-file change.
+      if (p.data.type !== 'source' && !p.inbound.some(q => q !== vault.index && q !== vault.log)) add('warn', 'orphan-page', p.path, 'no page links here');
+    }
+    if (p.folder === 'plans') {
+      const id = /-plan$/i.test(p.name) ? p.name.replace(/-plan$/i, '') : null;
+      if (!id) add('error', 'plan-name', p.path, 'plan files are named <ID>-plan.md');
+      else if (!taskOf(vault, id)) add('error', 'orphan-plan', p.path, `no task ${id} for this plan`);
+      else if (p.data.task && key(p.data.task) !== key(id)) add('error', 'plan-task-mismatch', p.path, `frontmatter task ${p.data.task} does not match file name`);
+      if (p.data.type !== 'plan') add('warn', 'missing-field', p.path, 'frontmatter `type: plan` is missing');
+    }
+  }
+
+  for (const t of vault.tasks.values()) {
+    const path = t.page.path;
+    if (t.page.data.type !== 'task') add('warn', 'missing-field', path, 'frontmatter `type: task` is missing');
+    if (!t.page.data.id) add('error', 'missing-field', path, 'frontmatter `id` is missing');
+    else if (key(t.id) !== key(t.page.name)) add('error', 'id-mismatch', path, `id ${t.id} does not match file name`);
+    if (!/^[A-Za-z][A-Za-z0-9]*-\d+$/.test(t.id)) add('error', 'bad-id', path, `id ${t.id} is not <AREA>-<number>`);
+    if (!t.title) add('error', 'missing-field', path, 'frontmatter `title` is missing');
+    if (!STATUSES.includes(t.status)) add('error', 'bad-status', path, `status "${t.status}" is not one of ${STATUSES.join(', ')}`);
+    for (const id of [...t.deps, ...t.softDeps]) {
+      const d = taskOf(vault, id);
+      if (!d) add('error', 'unknown-dep', path, `depends on ${id}, which does not exist`);
+      else if (d.status === 'cancelled' && t.status !== 'cancelled' && t.status !== 'done') add('warn', 'cancelled-dep', path, `depends on cancelled task ${id}`);
+    }
+    const hardOpen = t.openDeps.filter(id => taskOf(vault, id));
+    const softOpen = t.openSoftDeps.filter(id => taskOf(vault, id));
+    if (t.status === 'in-progress' && hardOpen.length) add('error', 'started-before-deps', path, `in-progress but not done: ${hardOpen.join(', ')}`);
+    if (t.status === 'done' && (hardOpen.length || softOpen.length)) add('error', 'done-before-deps', path, `done but not done: ${[...hardOpen, ...softOpen].join(', ')}`);
+    if ((t.status === 'in-progress' || t.status === 'done') && !t.started) add('warn', 'missing-date', path, '`started` is empty');
+    if (t.status === 'done' && !t.finished) add('warn', 'missing-date', path, '`finished` is empty');
+  }
+  for (const loop of cycles(vault)) add('error', 'dep-cycle', taskOf(vault, loop[0]).page.path, `dependency cycle: ${loop.join(' -> ')}`);
+
+  const rank = { error: 0, warn: 1 };
+  return out.sort((a, b) => rank[a.level] - rank[b.level] || a.path.localeCompare(b.path) || a.code.localeCompare(b.code));
+}
+
+// ---------- Queries ----------
+const STATES = ['ready', 'progress', 'blocked', 'done', 'cancelled'];
+const idOrder = (a, b) => a.area.localeCompare(b.area) || Number(a.id.split('-').pop()) - Number(b.id.split('-').pop());
+// Runnable order: fewest unfinished layers first, then explicit priority, then id.
+export const taskOrder = (a, b) => a.wave - b.wave || (a.priority ?? Infinity) - (b.priority ?? Infinity) || idOrder(a, b);
+
+export function summary(vault) {
+  const zero = () => Object.fromEntries([['total', 0], ...STATES.map(s => [s, 0])]);
+  const areas = new Map();
+  const total = zero();
+  for (const t of [...vault.tasks.values()].sort(idOrder)) {
+    if (!areas.has(t.area)) areas.set(t.area, zero());
+    for (const c of [areas.get(t.area), total]) { c.total++; c[t.state]++; }
+  }
+  return { areas, total, wikiPages: vault.pages.filter(p => p.folder === 'wiki').length };
+}
+
+export function tasksIn(vault, state) {
+  return [...vault.tasks.values()].filter(t => t.state === state).sort(taskOrder);
+}
+
+// Numbers are never reused: cancelled tasks stay on disk and keep theirs.
+export function nextId(vault, area) {
+  let max = 0;
+  let width = 2;
+  for (const t of vault.tasks.values()) {
+    if (key(t.area) !== key(area)) continue;
+    const n = t.id.split('-').pop();
+    if (/^\d+$/.test(n)) { max = Math.max(max, Number(n)); width = Math.max(width, n.length); }
+  }
+  return `${area}-${String(max + 1).padStart(width, '0')}`;
+}
+
+// Hard dependents that become ready the moment this task is done.
+export function unblockedBy(vault, id) {
+  const t = taskOf(vault, id);
+  if (!t) return [];
+  return t.dependents.map(d => taskOf(vault, d))
+    .filter(d => d && d.status === 'todo' && d.deps.includes(t.id) && d.openDeps.every(o => o === t.id))
+    .map(d => d.id);
+}
+
+// Keyword search over the vault. Pages matching more distinct terms come first; then lessons; a hit
+// in the name, title or summary outweighs hits in the body. Returns [{ page, score, line }].
+export function search(vault, query, limit = 8) {
+  const terms = [...new Set(String(query).toLowerCase().split(/[^\p{L}\p{N}_-]+/u).filter(w => w.length > 1))];
+  if (!terms.length) return [];
+  // A term matches at the start of a word, so "sync" finds "syncing" but "hang" does not find "change".
+  const res = terms.map(t => new RegExp(`(?<![\\p{L}\\p{N}])${t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`, 'u'));
+  const out = [];
+  for (const p of vault.pages) {
+    if (p === vault.index || p === vault.log) continue;
+    const head = `${p.name} ${p.data.title || ''} ${p.data.summary || ''}`.toLowerCase();
+    const body = p.body.toLowerCase();
+    let matched = 0;
+    let score = 0;
+    for (const re of res) {
+      const inHead = re.test(head);
+      const hits = Math.min((body.match(new RegExp(re.source, 'gu')) || []).length, 5);
+      if (inHead || hits) matched++;
+      score += (inHead ? 5 : 0) + hits;
+    }
+    if (!matched) continue;
+    const line = p.body.split(/\r?\n/).find(l => res.some(re => re.test(l.toLowerCase()))) || '';
+    out.push({ page: p, matched, score, line: line.trim().slice(0, 140) });
+  }
+  // Among pages matching the same number of terms, a recorded lesson is the most useful thing to read first.
+  const lesson = h => (h.page.data.type === 'lesson' ? 1 : 0);
+  return out.sort((a, b) => b.matched - a.matched || lesson(b) - lesson(a) || b.score - a.score || a.page.path.localeCompare(b.page.path)).slice(0, limit);
+}
+
+// Superwiki CLI. Lives in a project at docs/.sw/sw.mjs; prints short answers so agents do not read the vault to get them.
+import { readFileSync, readdirSync, existsSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+import { basename, dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+
+const HELP = `sw <command> [--docs <dir>] [--json]
+
+  status          task counts per area and wiki page count
+  ready           tasks that can start now, and tasks in progress
+  check <ID>      can this task start / finish? lists what is open
+  explain <ID>    a task's dependencies, what it blocks and unblocks, its plan and linked pages
+  search <words>  pages and log entries that mention the words, best match first
+  next-id <AREA>  next free task id for an area (numbers are never reused)
+  lint            structural checks; exit code 1 on errors
+  serve [--open]  start (or reuse) a local viewer at http://127.0.0.1:<port>/ that reads the files live
+  snapshot        write docs/.sw/data.js so docs/viewer.html opens as a file, frozen at this moment`;
+
+function docsDir(args) {
+  const i = args.indexOf('--docs');
+  if (i >= 0) return resolvePath(args[i + 1] || '.');
+  const own = join(dirname(fileURLToPath(import.meta.url)), '..');
+  if (existsSync(join(own, 'index.md'))) return own;
+  return resolvePath('docs');
+}
+
+function walk(dir, rel, out) {
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    if (e.name.startsWith('.')) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, `${rel}${e.name}/`, out);
+    else if (e.name.endsWith('.md')) out.push({ path: rel + e.name, text: readFileSync(p, 'utf8') });
+  }
+}
+
+export function loadVault(docs) {
+  const files = [];
+  for (const name of ['index.md', 'log.md']) {
+    // log.md only ever grows; its links are not worth the read, so only its presence is recorded.
+    if (existsSync(join(docs, name))) files.push({ path: name, text: name === 'log.md' ? '' : readFileSync(join(docs, name), 'utf8') });
+  }
+  for (const f of VAULT_FOLDERS) if (existsSync(join(docs, f))) walk(join(docs, f), `${f}/`, files);
+  return buildVault(files);
+}
+
+// Everything the viewer shows, as one object: the same pages the CLI reads, plus the log's text.
+export function vaultData(docs) {
+  const files = [];
+  for (const name of ['index.md', 'log.md']) if (existsSync(join(docs, name))) files.push({ path: name, text: readFileSync(join(docs, name), 'utf8') });
+  for (const f of VAULT_FOLDERS) if (existsSync(join(docs, f))) walk(join(docs, f), `${f}/`, files);
+  let config = {};
+  try { config = JSON.parse(readFileSync(join(docs, '.sw', 'config.json'), 'utf8')); } catch {}
+  return { name: config.name || basename(dirname(docs)), generated: new Date().toISOString(), config, files };
+}
+// "<" is escaped so page text can never close the script element the viewer loads this with.
+export const dataScript = data => `window.SW_DATA = ${JSON.stringify(data).replace(/</g, '\\u003c')};\n`;
+
+// The viewer cannot read files from a file:// page without the user picking a folder. Served from
+// localhost it can: every Refresh asks this process, which reads the files as they are now.
+const IDLE_MS = 2 * 60 * 60 * 1000;
+function serve(docs, argv) {
+  const statePath = join(docs, '.sw', 'server.json');
+  const state = () => { try { return JSON.parse(readFileSync(statePath, 'utf8')); } catch { return null; } };
+  const alive = async url => { try { return (await (await fetch(`${url}.sw/ping`)).text()) === docs; } catch { return false; } };
+
+  if (!argv.includes('--foreground')) {
+    (async () => {
+      let url = state()?.url;
+      if (!url || !(await alive(url))) {
+        url = null;
+        spawn(process.execPath, [fileURLToPath(import.meta.url), 'serve', '--foreground', '--docs', docs], { detached: true, stdio: 'ignore' }).unref();
+        for (let i = 0; i < 50 && !url; i++) {
+          await new Promise(r => setTimeout(r, 100));
+          const u = state()?.url;
+          if (u && (await alive(u))) url = u;
+        }
+      }
+      if (!url) { console.error('could not start the viewer server; use `snapshot` and open docs/viewer.html instead'); process.exitCode = 1; return; }
+      console.log(url);
+      if (argv.includes('--open')) {
+        const [bin, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]];
+        spawn(bin, args, { detached: true, stdio: 'ignore' }).unref();
+      }
+    })();
+    return;
+  }
+
+  let last = Date.now();
+  const server = createServer((req, res) => {
+    last = Date.now();
+    const port = server.address().port;
+    // Only this machine's browser, addressed by its loopback name, gets an answer.
+    if (![`127.0.0.1:${port}`, `localhost:${port}`].includes(req.headers.host)) { res.writeHead(403).end(); return; }
+    const path = (req.url || '/').split('?')[0];
+    const send = (type, body) => { res.writeHead(200, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store' }); res.end(body); };
+    if (path === '/' || path === '/viewer.html') return existsSync(join(docs, 'viewer.html')) ? send('text/html', readFileSync(join(docs, 'viewer.html'))) : res.writeHead(404).end('docs/viewer.html is missing; run sw-init');
+    if (path === '/.sw/data.js') return send('text/javascript', dataScript({ ...vaultData(docs), live: true }));
+    if (path === '/.sw/ping') return send('text/plain', docs);
+    res.writeHead(404).end();
+  });
+  server.listen(0, '127.0.0.1', () => {
+    mkdirSync(join(docs, '.sw'), { recursive: true });
+    writeFileSync(statePath, JSON.stringify({ url: `http://127.0.0.1:${server.address().port}/`, pid: process.pid }) + '\n');
+  });
+  setInterval(() => { if (Date.now() - last > IDLE_MS) process.exit(0); }, 60 * 1000);
+}
+
+const line = t => `${t.id}  ${t.title}${t.milestone ? `  [${t.milestone}]` : ''}${t.priority != null ? `  p${t.priority}` : ''}`;
+
+function main(argv) {
+  const args = argv.filter(a => a !== '--json');
+  const json = argv.includes('--json');
+  const di = args.indexOf('--docs');
+  if (di >= 0) args.splice(di, 2);
+  const [cmd, arg] = args;
+  if (!cmd || cmd === 'help' || cmd === '--help') { console.log(HELP); return 0; }
+  const docs = docsDir(argv);
+  if (!existsSync(docs)) { console.error(`no docs folder at ${docs}; run sw-init or pass --docs`); return 2; }
+  const vault = loadVault(docs);
+  const print = (data, text) => console.log(json ? JSON.stringify(data, null, 2) : text);
+
+  if (cmd === 'status') {
+    const s = summary(vault);
+    const row = (name, c) => `${name.padEnd(8)} total ${c.total}  ready ${c.ready}  in-progress ${c.progress}  blocked ${c.blocked}  done ${c.done}  cancelled ${c.cancelled}`;
+    const rows = [...s.areas].map(([a, c]) => row(a || '(none)', c));
+    if (s.areas.size > 1) rows.push(row('all', s.total));
+    print({ areas: Object.fromEntries(s.areas), total: s.total, wikiPages: s.wikiPages }, [...(rows.length ? rows : ['no tasks']), `wiki pages ${s.wikiPages}`].join('\n'));
+    return 0;
+  }
+  if (cmd === 'ready') {
+    const prog = tasksIn(vault, 'progress');
+    const ready = tasksIn(vault, 'ready');
+    const pick = t => ({ id: t.id, title: t.title, milestone: t.milestone, priority: t.priority });
+    print({ inProgress: prog.map(pick), ready: ready.map(pick) }, [`in progress (${prog.length})`, ...prog.map(line), `ready (${ready.length})`, ...ready.map(line)].join('\n'));
+    return 0;
+  }
+  if (cmd === 'check') {
+    const t = arg && taskOf(vault, arg);
+    if (!t) { console.error(`no task ${arg ?? ''}`); return 2; }
+    const known = ids => ids.filter(id => taskOf(vault, id));
+    const data = { id: t.id, status: t.status, canStart: t.status === 'todo' && !t.openDeps.length, canFinish: !t.openDeps.length && !t.openSoftDeps.length, openDeps: t.openDeps, openSoftDeps: known(t.openSoftDeps), plan: t.plan ? `docs/${t.plan.path}` : null };
+    print(data, [`${t.id}  ${t.status}  ${t.title}`, t.status === 'todo' ? `can start: ${data.canStart ? 'yes' : `no  open deps: ${t.openDeps.join(', ')}`}` : `can start: n/a, status is ${t.status}${t.openDeps.length ? `  open deps: ${t.openDeps.join(', ')}` : ''}`, `can finish: ${data.canFinish ? 'yes' : 'no'}${data.openSoftDeps.length ? `  open soft deps: ${data.openSoftDeps.join(', ')}` : ''}`, `plan: ${data.plan ?? 'none'}`].join('\n'));
+    return 0;
+  }
+  if (cmd === 'explain') {
+    const t = arg && taskOf(vault, arg);
+    if (!t) { console.error(`no task ${arg ?? ''}`); return 2; }
+    const ref = id => { const d = taskOf(vault, id); return d ? `${d.id} (${d.state}) ${d.title}` : `${id} (unknown)`; };
+    const list = (label, ids) => (ids.length ? [`${label}:`, ...ids.map(id => `  ${ref(id)}`)] : [`${label}: none`]);
+    const linked = [...new Set(t.page.links.map(l => resolve(vault, l.target)).filter(p => p && p.folder === 'wiki'))];
+    const unblocks = unblockedBy(vault, t.id);
+    const data = { id: t.id, title: t.title, status: t.status, state: t.state, milestone: t.milestone, priority: t.priority, started: t.started, finished: t.finished, deps: t.deps, softDeps: t.softDeps, dependents: t.dependents, unblocks, plan: t.plan ? `docs/${t.plan.path}` : null, linked: linked.map(p => ({ path: `docs/${p.path}`, type: p.data.type || '', summary: p.data.summary || '' })) };
+    print(data, [
+      `${t.id}  ${t.title}`,
+      `state: ${t.state} (status: ${t.status})${t.milestone ? `  milestone: ${t.milestone}` : ''}${t.priority != null ? `  priority: ${t.priority}` : ''}${t.started ? `  started: ${t.started}` : ''}${t.finished ? `  finished: ${t.finished}` : ''}`,
+      ...list('depends on', t.deps), ...(t.softDeps.length ? list('soft depends on', t.softDeps) : []),
+      ...list('blocks', t.dependents),
+      `finishing it makes ready: ${unblocks.join(', ') || 'nothing yet'}`,
+      `task: docs/${t.page.path}`, `plan: ${data.plan ?? 'none'}`,
+      ...(linked.length ? ['linked pages:', ...linked.map(p => `  docs/${p.path}  [${p.data.type || '?'}]  ${p.data.summary || ''}`)] : ['linked pages: none']),
+    ].join('\n'));
+    return 0;
+  }
+  if (cmd === 'search') {
+    const query = args.slice(1).join(' ');
+    if (!query.trim()) { console.error('usage: sw search <words>'); return 2; }
+    const hits = search(vault, query);
+    // The log is not loaded into the vault; scan it here and report the entries, not the lines.
+    const terms = query.toLowerCase().split(/\s+/).filter(w => w.length > 1);
+    const entries = [];
+    if (existsSync(join(docs, 'log.md'))) {
+      let head = null;
+      for (const l of readFileSync(join(docs, 'log.md'), 'utf8').split(/\r?\n/)) {
+        if (l.startsWith('## [')) { head = { title: l.slice(3), text: '', hit: false }; entries.push(head); }
+        else if (head && l.trim() && !head.text) head.text = l.trim().slice(0, 160);
+        if (head && terms.some(t => l.toLowerCase().includes(t))) head.hit = true;
+      }
+    }
+    const logHits = entries.filter(e => e.hit).map(e => `${e.title}${e.text ? `\n    ${e.text}` : ''}`);
+    // Plans have no summary; their first heading says what they are.
+    const about = p => p.data.summary || p.data.title || (p.body.match(/^#+\s+(.*)$/m) || [])[1] || '';
+    const label = p => (p.folder === 'tasks' ? `task ${taskOf(vault, p.data.id || p.name)?.state ?? ''}` : p.data.type || p.folder);
+    print({ pages: hits.map(h => ({ path: `docs/${h.page.path}`, type: label(h.page), summary: about(h.page), termsMatched: h.matched, line: h.line })), log: logHits.slice(-6) },
+      [`pages (${hits.length}), best match first; a page matching one common word is a weak match`, ...hits.map(h => `docs/${h.page.path}  [${label(h.page)}]  ${about(h.page)}${h.line ? `\n    ${h.line}` : ''}`), `log entries (${logHits.length}${logHits.length > 6 ? ', last 6 shown' : ''})`, ...logHits.slice(-6)].join('\n'));
+    return 0;
+  }
+  if (cmd === 'next-id') {
+    if (!arg || !/^[A-Za-z][A-Za-z0-9]*$/.test(arg)) { console.error('usage: sw next-id <AREA>'); return 2; }
+    print({ id: nextId(vault, arg) }, nextId(vault, arg));
+    return 0;
+  }
+  if (cmd === 'snapshot') {
+    const data = vaultData(docs);
+    mkdirSync(join(docs, '.sw'), { recursive: true });
+    writeFileSync(join(docs, '.sw', 'data.js'), dataScript(data));
+    console.log(`snapshot: ${data.files.length} files -> docs/.sw/data.js`);
+    return 0;
+  }
+  if (cmd === 'serve') { serve(docs, argv); return null; }
+  if (cmd === 'lint') {
+    const found = lint(vault);
+    const errors = found.filter(f => f.level === 'error').length;
+    print(found, [...found.map(f => `${f.level === 'error' ? 'E' : 'W'} ${f.code}  docs/${f.path}  ${f.message}`), `${errors} errors, ${found.length - errors} warnings`].join('\n'));
+    return errors ? 1 : 0;
+  }
+  console.error(`unknown command ${cmd}\n\n${HELP}`);
+  return 2;
+}
+
+// realpath: the script may be reached through a symlinked path (macOS /tmp, linked skills folders).
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) { const code = main(process.argv.slice(2)); if (code != null) process.exitCode = code; }

package/skills/sw-init/assets/templates/page.md

@@ -0,0 +1,18 @@
+---
+type: concept
+summary: One line; this is what index.md shows.
+sources: []
+updated: YYYY-MM-DD
+---
+
+# Page title
+
+Body. Link other pages as [[file-name]]. Cite sources as [title](../raw/file.md).
+
+<!--
+type is free text. Common values: source (summary of one raw file), entity, concept,
+decision (dated; say what it supersedes), analysis (an answer worth keeping),
+lesson (a problem that happened: Symptom, Cause, Fix, How to notice it earlier).
+File name: lowercase-with-hyphens.md, unique across the vault. Decisions: YYYY-MM-DD-topic.md.
+Delete this comment.
+-->

package/skills/sw-init/assets/templates/plan.md

@@ -0,0 +1,25 @@
+---
+type: plan
+task: T-01
+updated: YYYY-MM-DD
+---
+
+# Plan: T-01
+
+## Approach
+
+The chosen approach in a few sentences, and what was ruled out.
+
+## Steps
+
+1. Step with the files it touches and how to verify it.
+
+## Verification
+
+Commands or checks that prove the task's "Done when" list.
+
+<!--
+File: docs/plans/<ID>-plan.md, one plan per task. Rewrite in place; git keeps old versions.
+Design shared by several tasks is a `type: decision` wiki page that the plans link to.
+Delete this comment.
+-->

package/skills/sw-init/assets/templates/task.md

@@ -0,0 +1,33 @@
+---
+type: task
+id: T-01
+title: Short imperative title
+status: todo
+deps: []
+soft_deps: []
+milestone:
+priority:
+started:
+finished:
+---
+
+## Goal
+
+What exists when this is done, and why it matters.
+
+## Done when
+
+- Checkable condition.
+
+## Sources
+
+- [[page-name]]
+
+## Notes
+
+<!--
+id: from `node docs/.sw/sw.mjs next-id <AREA>`; the file is docs/tasks/<id>.md.
+status: todo | in-progress | done | cancelled. Cancelled tasks stay; ids are never reused.
+deps: must be done before this starts. soft_deps: may start, cannot finish before them.
+Steps go in docs/plans/<id>-plan.md, not here. Delete this comment.
+-->