@unpolarize/knowledge-planning 0.1.0 → 0.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@unpolarize/knowledge-planning",
-  "version": "0.1.0",
-  "description": "Durable, git-backed, life-wide planning system: typed entities (Domain/Project/CatalogEntry/Idea/Plan/Task/DailyPlan/Reflection/Insight/KnowledgeRef/Edge) over a markdown SSOT, a node:sqlite projection, a graph/board exporter, and a CLI. Wires ~/docs knowledge (blocked_by edges) and the portable sessions.git corpus (planning_refs).",
+  "version": "0.2.0",
+  "description": "KP (Knowledge Planning) \u2014 a durable, git-backed planning CLI and library over a markdown SSOT (tasks, ideas, plans, thoughts; kanban, calendar, sessions links). Point it at any store directory.",
   "type": "module",
   "license": "MIT",
   "publishConfig": {
@@ -12,30 +12,40 @@
     "url": "git+https://github.com/unpolarize/knowledge-planning.git"
   },
   "files": [
-    "src",
-    "README.md"
+    "dist",
+    "README.md",
+    "LICENSE"
   ],
   "bin": {
-    "knowledge-planning": "./src/cli/index.ts",
-    "kp": "./src/cli/index.ts"
+    "knowledge-planning": "./dist/cli.js",
+    "kp": "./dist/cli.js"
   },
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
   "scripts": {
     "kp": "node ./src/cli/index.ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "yaml": "^2.9.0",
     "zod": "^3.25.0"
   },
   "devDependencies": {
+    "@types/node": "^22.20.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
     "vitest": "^2.1.8"
   },
   "engines": {
     "node": ">=22"
-  }
+  },
+  "types": "./dist/index.d.ts"
 }

package/src/cli/commands.test.ts

@@ -1,105 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { Store } from '../store/store.ts';
-import { PlanningIndex } from '../index/db.ts';
-import * as cmd from './commands.ts';
-
-let dir: string;
-let kb: string;
-let sessions: string;
-
-beforeEach(() => {
-  dir = mkdtempSync(join(tmpdir(), 'kp-cmd-'));
-  kb = mkdtempSync(join(tmpdir(), 'kp-cmdkb-'));
-  sessions = mkdtempSync(join(tmpdir(), 'kp-cmdsess-'));
-});
-afterEach(() => {
-  for (const d of [dir, kb, sessions]) rmSync(d, { recursive: true, force: true });
-});
-
-describe('cli commands', () => {
-  it('captures an idea', () => {
-    const s = new Store(dir);
-    const res = cmd.cmdCapture(s, 'Memory maps in CB', 'tech');
-    expect(res.id).toBe('ideas/memory-maps-in-cb');
-    expect(new Store(dir).get(res.id)?.object.status).toBe('capture');
-  });
-
-  it('promotes an idea to a plan and marks lineage', () => {
-    const s = new Store(dir);
-    cmd.cmdCapture(s, 'Knowledge planning MVP', 'tech');
-    const res = cmd.cmdPromote(s, 'ideas/knowledge-planning-mvp');
-    const fresh = new Store(dir);
-    expect(fresh.get(res.planId)?.type).toBe('plan');
-    expect(fresh.get('ideas/knowledge-planning-mvp')?.data.status).toBe('done');
-    expect(fresh.get('ideas/knowledge-planning-mvp')?.data.promoted_to).toBe(res.planId);
-  });
-
-  it('links a session both ways (linked_sessions + planning_refs)', () => {
-    const s = new Store(dir);
-    s.write({ id: 'ideas/mm', type: 'idea', title: 'MM' });
-    const uuid = '4992a4a4-5632-4048-a55e-ab2be5857f2e';
-    const envDir = join(sessions, 'hosts/h1/2026-06', uuid);
-    mkdirSync(envDir, { recursive: true });
-    writeFileSync(
-      join(envDir, 'session.json'),
-      JSON.stringify({ schema: 'session-store/session@1', session_id: uuid, host: 'h1', agent: 'claude-code' }),
-    );
-
-    const res = cmd.cmdLinkSession(s, sessions, 'ideas/mm', uuid);
-    expect(res.envelopeUpdated).toBe(true);
-
-    const env = JSON.parse(readFileSync(join(envDir, 'session.json'), 'utf8'));
-    expect(env.planning_refs).toContain('ideas/mm');
-    expect(new Store(dir).get('ideas/mm')?.object.linked_sessions).toContain(uuid);
-  });
-
-  it('baselines on first run, then ingests only new substantial bullets', () => {
-    const s = new Store(dir);
-    const base = '- brainstorm a thing\n- [ ] call the contractor\n';
-    // first run: no prior snapshot → baseline, ingest nothing (never flood a brain-dump)
-    const b = cmd.cmdIngestGdoc(s, base, { prevText: null });
-    expect(b.baselined).toBe(true);
-    expect(b.created.length).toBe(0);
-    // next run: one new substantial bullet added → only it ingests ('tiny' filtered by minLen)
-    const r = cmd.cmdIngestGdoc(s, base + '- a brand new idea here\n- tiny\n', { prevText: base, domain: 'tech' });
-    expect(r.baselined).toBe(false);
-    expect(r.created).toEqual(['ideas/a-brand-new-idea-here']);
-    expect(new Store(dir).get('ideas/a-brand-new-idea-here')?.object.status).toBe('capture');
-  });
-
-  it('caps new captures per run', () => {
-    const s = new Store(dir);
-    const lines = Array.from({ length: 10 }, (_, i) => `- new substantial bullet number ${i}`).join('\n');
-    const r = cmd.cmdIngestGdoc(s, lines, { prevText: '', max: 3 });
-    expect(r.created.length).toBe(3);
-    expect(r.capped).toBe(7);
-  });
-
-  it('ingests insight bullets into an Insight object', () => {
-    const s = new Store(dir);
-    const res = cmd.cmdInsightIngest(s, '- ship the daemon\n- [ ] email outreach\n', 'daily-digest', 'raw/x.md');
-    expect(res.suggested).toBe(2);
-    expect(new Store(dir).get(res.id)?.type).toBe('insight');
-  });
-
-  it('renders list / daily / blocked / graph as strings', () => {
-    const s = new Store(dir);
-    s.write({ id: 'ideas/a', type: 'idea', title: 'A', status: 'capture' });
-    s.write({ id: 'daily/2026-06-21', type: 'daily_plan', date: '2026-06-21' }, '## Top 3\n- [ ] ship');
-    s.write({ id: 'tasks/t', type: 'task', title: 'Ship', status: 'today', daily: 'daily/2026-06-21' });
-    s.write({
-      id: 'plans/r',
-      type: 'plan',
-      title: 'R',
-      blocked_by: [{ path: 'knowledge/x.md', reason: 'decide' }],
-    });
-    const idx = new PlanningIndex(s);
-    expect(cmd.cmdList(s, { status: 'capture' })).toContain('ideas/a');
-    expect(cmd.cmdDaily(s, idx, '2026-06-21', false)).toContain('Ship');
-    expect(cmd.cmdBlocked(idx, kb)).toContain('plans/r');
-    expect(cmd.cmdGraph(s, kb, true)).toContain('"nodes"');
-  });
-});

package/src/cli/commands.ts

@@ -1,341 +0,0 @@
-import { join } from 'node:path';
-import { Store } from '../store/store.ts';
-import { PlanningIndex, persistIndex } from '../index/db.ts';
-import { buildGraph } from '../graph/graph.ts';
-import { extractBullets, toSeeds, slugify } from '../migrate/gdoc.ts';
-import { findSessionEnvelope, addPlanningRef } from './sessions.ts';
-import { inspectKnowledgeRef, resolveKnowledgeRef, readTitle } from '../kb-bridge/kb-bridge.ts';
-import { existsSync } from 'node:fs';
-import type { Config } from '../types.ts';
-
-export const today = (): string => new Date().toISOString().slice(0, 10);
-
-export interface ListOpts {
-  status?: string;
-  type?: string;
-}
-
-export function cmdList(store: Store, opts: ListOpts): string {
-  let rows = store.all();
-  if (opts.type) rows = rows.filter((d) => d.type === opts.type);
-  if (opts.status) rows = rows.filter((d) => (d.object as { status?: string }).status === opts.status);
-  if (rows.length === 0) return '(no matching objects)';
-  return rows
-    .sort((a, b) => a.type.localeCompare(b.type) || a.id.localeCompare(b.id))
-    .map((d) => {
-      const o = d.object as { title?: string; status?: string };
-      return `${pad(d.type, 12)} ${pad(o.status ?? '-', 10)} ${d.id}${o.title ? `  — ${o.title}` : ''}`;
-    })
-    .join('\n');
-}
-
-export function cmdDaily(store: Store, idx: PlanningIndex, date: string, carryOver: boolean): string {
-  const board = idx.dailyBoard(date);
-  const lines: string[] = [`# Daily — ${date}`];
-  if (!board.daily_id) lines.push(`(no daily plan file at daily/${date}; run /planning-daily or 'kp capture')`);
-  if (board.body.trim()) lines.push('', board.body.trim());
-  lines.push('', '## Tasks by lane');
-  for (const [lane, rows] of Object.entries(board.lanes)) {
-    if (rows.length === 0) continue;
-    lines.push(`  ${lane}:`);
-    for (const r of rows) lines.push(`    - [${r.status === 'done' ? 'x' : ' '}] ${r.title ?? r.id}  (${r.id})`);
-  }
-  if (carryOver) {
-    const prev = previousDay(date);
-    const prevBoard = idx.dailyBoard(prev);
-    const unfinished = [...prevBoard.lanes.today, ...prevBoard.lanes.in_progress, ...prevBoard.lanes.inbox];
-    if (unfinished.length) {
-      lines.push('', `## Carry-over from ${prev}`);
-      for (const r of unfinished) lines.push(`    - ${r.title ?? r.id}  (${r.id})`);
-    }
-  }
-  return lines.join('\n');
-}
-
-export function cmdBlocked(idx: PlanningIndex, kbRoot: string): string {
-  const blocked = idx.blockedByKnowledge(kbRoot).filter((b) => b.status !== 'resolved');
-  if (blocked.length === 0) return '(nothing blocked by knowledge)';
-  return blocked
-    .map((b) => {
-      const flag = !b.exists ? 'MISSING' : b.resolvable ? 'RESOLVABLE (decision recorded)' : 'open';
-      return `${flag.padEnd(30)} ${b.id}\n    → ${b.path}${b.reason ? `\n    reason: ${b.reason}` : ''}`;
-    })
-    .join('\n');
-}
-
-export function cmdGraph(store: Store, kbRoot: string, json: boolean): string {
-  const g = buildGraph(store, kbRoot);
-  if (json) return JSON.stringify(g, null, 2);
-  return `graph: ${g.nodes.length} nodes, ${g.edges.length} edges\n  by type: ${countBy(g.nodes.map((n) => n.type))}`;
-}
-
-export function cmdReindex(store: Store, root: string): string {
-  const res = persistIndex(store, join(root, '.index/planning.db'));
-  const warnings = store.getWarnings();
-  return `reindexed → ${join(root, '.index/planning.db')}\n  ${res.objects} objects, ${res.edges} edges${
-    warnings.length ? `\n  ${warnings.length} warning(s):\n    ${warnings.join('\n    ')}` : ''
-  }`;
-}
-
-export interface CaptureResult {
-  id: string;
-}
-
-export function cmdCapture(store: Store, text: string, domain?: string): CaptureResult {
-  const id = uniqueId(store, `ideas/${slugify(text)}`);
-  store.write({ id, type: 'idea', title: text, status: 'capture', domain, created: today() });
-  return { id };
-}
-
-export interface PromoteResult {
-  ideaId: string;
-  planId: string;
-}
-
-export function cmdPromote(store: Store, ideaId: string, toId?: string): PromoteResult {
-  const idea = store.get(ideaId);
-  if (!idea || idea.type !== 'idea') throw new Error(`not an idea: ${ideaId}`);
-  const o = idea.object as {
-    title?: string;
-    domain?: string;
-    project?: string;
-    blocked_by?: unknown[];
-    cites?: string[];
-  };
-  const planId = toId ?? uniqueId(store, `plans/${ideaId.split('/').pop()}`);
-  const isLife = o.domain && o.domain !== 'tech';
-  store.write(
-    {
-      id: planId,
-      type: 'plan',
-      title: o.title ?? planId,
-      status: 'plan',
-      kind: isLife ? 'life' : 'dev',
-      domain: o.domain,
-      project: o.project,
-      promoted_from: ideaId,
-      blocked_by: o.blocked_by ?? [],
-      cites: o.cites ?? [],
-      created: today(),
-    },
-    `# ${o.title ?? planId}\n\n## Goal\n\n_(promoted from [[${ideaId}]])_\n\n## Steps\n\n- [ ] …\n`,
-  );
-  store.patch(ideaId, (d) => {
-    d.status = 'done';
-    d.promoted_to = planId;
-  });
-  store.appendEdge({ kind: 'promoted_to', from: ideaId, to: planId, created_at: new Date().toISOString() });
-  return { ideaId, planId };
-}
-
-export interface LinkResult {
-  objectId: string;
-  uuid: string;
-  envelopeUpdated: boolean;
-  envelopePath?: string;
-}
-
-export function cmdLinkSession(store: Store, sessionsRoot: string, objectId: string, uuid: string): LinkResult {
-  const obj = store.get(objectId);
-  if (!obj) throw new Error(`object not found: ${objectId}`);
-  store.patch(objectId, (d) => {
-    const refs = new Set((d.linked_sessions as string[]) ?? []);
-    refs.add(uuid);
-    d.linked_sessions = [...refs];
-  });
-  store.appendEdge({ kind: 'evidence', from: `session:${uuid}`, to: objectId, created_at: new Date().toISOString() });
-  const envelopePath = findSessionEnvelope(sessionsRoot, uuid);
-  let envelopeUpdated = false;
-  if (envelopePath) envelopeUpdated = addPlanningRef(envelopePath, objectId);
-  return { objectId, uuid, envelopeUpdated, envelopePath };
-}
-
-export interface InsightResult {
-  id: string;
-  suggested: number;
-}
-
-/** Ingest digest/brief bullets (a markdown file) into an Insight with suggested tasks. */
-export function cmdInsightIngest(store: Store, text: string, source: string, sourceRef?: string): InsightResult {
-  const bullets = extractBullets(text).filter((b) => b.text.length > 3);
-  const date = today();
-  const id = uniqueId(store, `insights/${date}-${slugify(source)}`);
-  const suggested = bullets.map((b) => b.text);
-  store.write(
-    {
-      id,
-      type: 'insight',
-      title: `${source} — ${date}`,
-      source,
-      source_ref: sourceRef,
-      generated_at: new Date().toISOString(),
-      status: 'new',
-    },
-    `# ${source} — ${date}\n\n## Suggested\n\n${suggested.map((s) => `- [ ] ${s}`).join('\n')}\n`,
-  );
-  return { id, suggested: suggested.length };
-}
-
-/** Rich detail for one object: body + resolved references + parent/children + lineage. */
-export function cmdShow(store: Store, kbRoot: string, id: string): unknown {
-  const doc = store.get(id);
-  if (!doc) throw new Error(`object not found: ${id}`);
-  const o = doc.object as Record<string, unknown>;
-  const all = store.all();
-  const ref = (oid: string) => {
-    const d = store.get(oid);
-    return d ? { id: d.id, type: d.type, title: (d.object as { title?: string }).title ?? d.id, status: (d.object as { status?: string }).status } : { id: oid, missing: true };
-  };
-  const cites = (o.cites as string[] | undefined ?? []).map((p) => {
-    const abs = resolveKnowledgeRef(p, kbRoot);
-    return { path: p, exists: existsSync(abs), title: existsSync(abs) ? readTitle(abs) : undefined };
-  });
-  const blocked_by = (doc.object.blocked_by ?? []).map((r) => inspectKnowledgeRef(id, r, kbRoot));
-  // children: objects that point at this one as their project or plan parent
-  const children = all
-    .filter((d) => {
-      const c = d.object as Record<string, unknown>;
-      return d.id !== id && (c.project === id || c.plan === id || c.daily === id);
-    })
-    .map((d) => ref(d.id));
-  const parentId = (o.plan as string) || (o.project as string) || undefined;
-  return {
-    id: doc.id,
-    type: doc.type,
-    relpath: doc.relpath,
-    path: doc.path,
-    frontmatter: o,
-    title: o.title ?? doc.id,
-    status: o.status,
-    domain: o.domain,
-    body: doc.body,
-    cites,
-    blocked_by,
-    depends_on: (o.depends_on as string[] | undefined ?? []).map(ref),
-    related: (o.related as string[] | undefined ?? []).map(ref),
-    linked_sessions: (o.linked_sessions as string[] | undefined ?? []),
-    parent: parentId ? ref(parentId) : null,
-    children,
-    promoted_to: o.promoted_to ? ref(o.promoted_to as string) : null,
-    promoted_from: o.promoted_from ? ref(o.promoted_from as string) : null,
-  };
-}
-
-/** One-shot JSON snapshot for external consumers (the CSV planning mode). */
-export function cmdExport(store: Store, idx: PlanningIndex, config: Config, date: string): unknown {
-  return {
-    generated_at: new Date().toISOString(),
-    root: store.root,
-    kb_root: config.kb_root,
-    sessions_root: config.sessions_root,
-    counts: idx.counts(),
-    objects: idx.all(),
-    inbox: idx.listByStatus('capture'),
-    board: idx.dailyBoard(date),
-    blocked: idx.blockedByKnowledge(config.kb_root).filter((b) => b.status !== 'resolved'),
-    graph: buildGraph(store, config.kb_root),
-  };
-}
-
-/** Set an object's status (board lane moves, idea accept/park). */
-export function cmdSetStatus(store: Store, id: string, status: string): void {
-  if (!store.get(id)) throw new Error(`object not found: ${id}`);
-  store.patch(id, (d) => {
-    d.status = status;
-    d.updated = today();
-  });
-}
-
-export interface IngestResult {
-  created: string[];
-  skipped: number;
-  newBullets: number;
-  baselined: boolean;
-  capped: number;
-}
-
-/**
- * Ingest the synced Google-Doc todo mirror into the planning inbox: checkbox items →
- * inbox tasks, plain bullets → capture ideas.
- *
- * Safe by construction for a large brain-dump outline (the real doc is thousands of
- * nested bullets), per the design's "diff triggers append of NEW bullets, human approves":
- *  - **Diff-based:** ingests only bullets absent from `prevText` (the prior snapshot).
- *  - **Baseline first run:** when `prevText` is null (no snapshot yet), ingest nothing —
- *    just establish the baseline so a years-long doc never floods the store.
- *  - **Filtered:** only substantial (`minLen`) top-level bullets (`depth <= 2`).
- *  - **Capped:** at most `max` new captures per run (the rest wait for the next run).
- *  - **Deduped:** an id that already exists is skipped.
- * Captures land as `capture`/`inbox` (triage state); the human promotes/parks them.
- */
-export function cmdIngestGdoc(
-  store: Store,
-  text: string,
-  opts: { domain?: string; source?: string; prevText?: string | null; max?: number; minLen?: number } = {},
-): IngestResult {
-  const minLen = opts.minLen ?? 12;
-  const max = opts.max ?? 25;
-  const source = opts.source ?? 'gdoc';
-  if (opts.prevText == null) {
-    return { created: [], skipped: 0, newBullets: 0, baselined: true, capped: 0 };
-  }
-  const prevSet = new Set(extractBullets(opts.prevText).map((b) => b.text));
-  const fresh = extractBullets(text).filter((b) => b.text.length >= minLen && b.depth <= 2 && !prevSet.has(b.text));
-  const seeds = toSeeds(fresh.slice(0, max), { domain: opts.domain, source });
-  const created: string[] = [];
-  let skipped = 0;
-  for (const seed of seeds) {
-    if (store.get(seed.id)) {
-      skipped++;
-      continue;
-    }
-    store.write(
-      { id: seed.id, type: seed.type, title: seed.title, status: seed.status, domain: seed.domain, source: seed.source, created: today() },
-      seed.title,
-    );
-    created.push(seed.id);
-  }
-  return { created, skipped, newBullets: fresh.length, baselined: false, capped: Math.max(0, fresh.length - seeds.length) };
-}
-
-export function cmdDoctor(store: Store, idx: PlanningIndex, config: Config): string {
-  const counts = idx.counts();
-  const blocked = idx.blockedByKnowledge(config.kb_root).filter((b) => b.status !== 'resolved');
-  const warnings = store.getWarnings();
-  return [
-    `store root: ${store.root}`,
-    `kb_root:    ${config.kb_root}`,
-    `sessions:   ${config.sessions_root}`,
-    `objects:    ${Object.entries(counts).map(([k, v]) => `${k}=${v}`).join(' ') || '(none)'}`,
-    `fts5:       ${idx.fts ? 'yes' : 'no (LIKE fallback)'}`,
-    `blocked:    ${blocked.length} (${blocked.filter((b) => b.resolvable).length} resolvable, ${blocked.filter((b) => !b.exists).length} missing)`,
-    `warnings:   ${warnings.length}${warnings.length ? '\n  ' + warnings.join('\n  ') : ''}`,
-  ].join('\n');
-}
-
-// --- helpers ---------------------------------------------------------------
-
-function pad(s: string, n: number): string {
-  return (s ?? '').padEnd(n).slice(0, n);
-}
-
-function countBy(items: string[]): string {
-  const m: Record<string, number> = {};
-  for (const i of items) m[i] = (m[i] ?? 0) + 1;
-  return Object.entries(m)
-    .map(([k, v]) => `${k}=${v}`)
-    .join(' ');
-}
-
-function uniqueId(store: Store, base: string): string {
-  if (!store.get(base)) return base;
-  let n = 2;
-  while (store.get(`${base}-${n}`)) n++;
-  return `${base}-${n}`;
-}
-
-function previousDay(date: string): string {
-  const d = new Date(date + 'T00:00:00Z');
-  d.setUTCDate(d.getUTCDate() - 1);
-  return d.toISOString().slice(0, 10);
-}