@unpolarize/knowledge-planning 0.1.0 → 0.2.0

package/src/kb-bridge/kb-bridge.ts

@@ -1,63 +0,0 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
-import { parseMarkdown } from '../schema/frontmatter.ts';
-import type { KnowledgeRef } from '../schema/entities.ts';
-
-/** Resolve a KnowledgeRef path (relative to ~/docs) to an absolute path. */
-export function resolveKnowledgeRef(refPath: string, kbRoot: string): string {
-  return isAbsolute(refPath) ? refPath : join(kbRoot, refPath);
-}
-
-/** Best-effort article title: frontmatter `title`, first alias, or first `# ` heading. */
-export function readTitle(absPath: string): string | undefined {
-  if (!existsSync(absPath)) return undefined;
-  const { data, body } = parseMarkdown(readFileSync(absPath, 'utf8'));
-  if (typeof data.title === 'string') return data.title;
-  if (Array.isArray(data.aliases) && typeof data.aliases[0] === 'string') return data.aliases[0];
-  const m = body.match(/^#\s+(.+)$/m);
-  return m ? m[1].trim() : undefined;
-}
-
-/**
- * Operational definition of "this knowledge is decided", so a `blocked_by` edge is
- * resolved against an artifact rather than by hand: the referenced KB article carries
- * a non-empty `decision:` frontmatter field OR a `## Decision` section in its body.
- */
-export function hasDecision(absPath: string): boolean {
-  if (!existsSync(absPath)) return false;
-  const { data, body } = parseMarkdown(readFileSync(absPath, 'utf8'));
-  if (data.decision != null && String(data.decision).trim() !== '') return true;
-  return /^#{1,6}\s+decision\b/im.test(body);
-}
-
-export interface BlockedInspection {
-  id: string; // owning object id
-  path: string; // KB-relative ref path
-  abs: string;
-  exists: boolean;
-  decided: boolean;
-  status: 'open' | 'resolved';
-  reason?: string;
-  title?: string;
-  /** the article records a decision but the edge is still open → safe to flip */
-  resolvable: boolean;
-}
-
-/** Inspect one blocked_by KnowledgeRef against the KB. */
-export function inspectKnowledgeRef(ownerId: string, ref: KnowledgeRef, kbRoot: string): BlockedInspection {
-  const abs = resolveKnowledgeRef(ref.path, kbRoot);
-  const exists = existsSync(abs);
-  const decided = exists && hasDecision(abs);
-  const status = ref.status ?? 'open';
-  return {
-    id: ownerId,
-    path: ref.path,
-    abs,
-    exists,
-    decided,
-    status,
-    reason: ref.reason,
-    title: exists ? readTitle(abs) : undefined,
-    resolvable: decided && status !== 'resolved',
-  };
-}

package/src/migrate/gdoc.test.ts

@@ -1,28 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { extractBullets, toSeeds, slugify } from './gdoc.ts';
-
-describe('migrate/gdoc', () => {
-  it('extracts plain bullets and checkbox items', () => {
-    const bullets = extractBullets('- idea one\n  - nested idea\n- [ ] do thing\n- [x] done thing\nnot a bullet\n');
-    expect(bullets.length).toBe(4);
-    expect(bullets[1]?.depth).toBe(1);
-    expect(bullets[2]?.checked).toBe(false);
-    expect(bullets[3]?.checked).toBe(true);
-  });
-
-  it('maps checkbox items → tasks and plain bullets → capture ideas', () => {
-    const seeds = toSeeds(extractBullets('- brainstorm memory maps\n- [ ] call contractor\n- [x] shipped MVP\n'));
-    expect(seeds.find((s) => s.type === 'idea' && s.status === 'capture')).toBeTruthy();
-    expect(seeds.find((s) => s.type === 'task' && s.status === 'inbox')).toBeTruthy();
-    expect(seeds.find((s) => s.type === 'task' && s.status === 'done')).toBeTruthy();
-  });
-
-  it('de-duplicates generated ids', () => {
-    const seeds = toSeeds(extractBullets('- same thing\n- same thing\n'));
-    expect(new Set(seeds.map((s) => s.id)).size).toBe(2);
-  });
-
-  it('slugifies titles', () => {
-    expect(slugify('Memory Maps in CB!')).toBe('memory-maps-in-cb');
-  });
-});

package/src/migrate/gdoc.ts

@@ -1,68 +0,0 @@
-/**
- * Migrate scattered capture (the synced Google Doc → raw/google-docs/personal-todo-notes.md,
- * notes.md bullets) into seed planning objects. Checkbox items become Tasks; plain
- * bullets become capture Ideas. Returns seed frontmatter — the caller decides whether
- * to write them (so migration is reviewable, not destructive).
- */
-
-export interface Bullet {
-  text: string;
-  checked?: boolean;
-  depth: number;
-}
-
-export function extractBullets(text: string): Bullet[] {
-  const out: Bullet[] = [];
-  for (const line of text.split('\n')) {
-    const m = line.match(/^(\s*)[-*+]\s+(\[([ xX])\]\s+)?(.+?)\s*$/);
-    if (!m) continue;
-    const indent = m[1].replace(/\t/g, '  ').length;
-    const checked = m[3] !== undefined ? /[xX]/.test(m[3]) : undefined;
-    out.push({ text: m[4].trim(), checked, depth: Math.floor(indent / 2) });
-  }
-  return out;
-}
-
-export function slugify(s: string): string {
-  return (
-    s
-      .toLowerCase()
-      .replace(/[`*_~]/g, '')
-      .replace(/[^a-z0-9]+/g, '-')
-      .replace(/^-+|-+$/g, '')
-      .slice(0, 48) || 'item'
-  );
-}
-
-export interface SeedObject {
-  id: string;
-  type: 'idea' | 'task';
-  title: string;
-  status: string;
-  domain?: string;
-  source?: string;
-}
-
-/** Map bullets to seed objects, de-duplicating ids. */
-export function toSeeds(bullets: Bullet[], opts: { domain?: string; source?: string } = {}): SeedObject[] {
-  const seeds: SeedObject[] = [];
-  const seen = new Set<string>();
-  for (const b of bullets) {
-    if (!b.text || b.text.length < 3) continue;
-    const isTask = b.checked !== undefined;
-    const base = `${isTask ? 'tasks' : 'ideas'}/${slugify(b.text)}`;
-    let id = base;
-    let n = 2;
-    while (seen.has(id)) id = `${base}-${n++}`;
-    seen.add(id);
-    seeds.push({
-      id,
-      type: isTask ? 'task' : 'idea',
-      title: b.text,
-      status: isTask ? (b.checked ? 'done' : 'inbox') : 'capture',
-      domain: opts.domain,
-      source: opts.source,
-    });
-  }
-  return seeds;
-}

package/src/schema/entities.test.ts

@@ -1,60 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { parseObject, safeParseObject } from './entities.ts';
-import { parseMarkdown, serializeMarkdown } from './frontmatter.ts';
-
-describe('frontmatter', () => {
-  it('round-trips frontmatter + body and strips empty arrays', () => {
-    const md = serializeMarkdown(
-      { id: 'ideas/x', type: 'idea', title: 'X', tags: [], cites: [] },
-      'Body text.\n',
-    );
-    const { data, body } = parseMarkdown(md);
-    expect(data.id).toBe('ideas/x');
-    expect(data.type).toBe('idea');
-    expect(body.trim()).toBe('Body text.');
-    expect(md).not.toContain('tags:'); // empty arrays stripped
-  });
-
-  it('returns empty data when there is no frontmatter', () => {
-    const { data, body } = parseMarkdown('# just a heading\n');
-    expect(data).toEqual({});
-    expect(body).toContain('heading');
-  });
-
-  it('preserves nested blocked_by structure through serialize→parse', () => {
-    const md = serializeMarkdown(
-      {
-        id: 'plans/reloc',
-        type: 'plan',
-        blocked_by: [{ path: 'knowledge/life/relocation/x.md', reason: 'tax compare', status: 'open' }],
-      },
-      '',
-    );
-    const { data } = parseMarkdown(md);
-    const obj = parseObject(data);
-    expect(obj.blocked_by[0]?.path).toContain('relocation');
-    expect(obj.blocked_by[0]?.status).toBe('open');
-  });
-});
-
-describe('entities', () => {
-  it('applies idea defaults', () => {
-    const obj = parseObject({ id: 'ideas/memory-maps', type: 'idea' });
-    expect(obj.type).toBe('idea');
-    if (obj.type === 'idea') expect(obj.status).toBe('capture');
-  });
-
-  it('defaults blocked_by KnowledgeRef status to open', () => {
-    const obj = parseObject({
-      id: 'plans/reloc',
-      type: 'plan',
-      blocked_by: [{ path: 'knowledge/life/relocation/x.md', reason: 'need decision' }],
-    });
-    expect(obj.blocked_by[0]?.status).toBe('open');
-  });
-
-  it('discriminates by type and rejects unknown types', () => {
-    expect(safeParseObject({ id: 'x', type: 'nonsense' }).success).toBe(false);
-    expect(safeParseObject({ id: 'p', type: 'project' }).success).toBe(true);
-  });
-});

package/src/schema/entities.ts

@@ -1,233 +0,0 @@
-import { z } from 'zod';
-
-/**
- * Knowledge-Planning entity model.
- *
- * Every object is a markdown file whose YAML frontmatter validates against one of
- * these schemas, discriminated by `type`. Objects are addressable by a stable `id`
- * (used in wikilinks, session `planning_refs`, and CLI args). Schemas are versioned
- * `knowledge-planning/<type>@N` so consumers can migrate the way the session store's
- * `session-store/*@1` records do.
- *
- * Schemas are `.passthrough()` on purpose: this is a personal, evolving corpus, so
- * unknown frontmatter keys survive a parse→serialize round-trip rather than being
- * dropped. Relationship fields default to `[]` for uniform indexing; the serializer
- * (frontmatter.ts) strips empties so files stay clean.
- */
-
-export const SCHEMA_VERSION = 1;
-export const ns = (t: string): string => `knowledge-planning/${t}@${SCHEMA_VERSION}`;
-
-export const OBJECT_TYPES = [
-  'domain',
-  'project',
-  'catalog_entry',
-  'idea',
-  'plan',
-  'task',
-  'daily_plan',
-  'reflection',
-  'insight',
-] as const;
-export type ObjectType = (typeof OBJECT_TYPES)[number];
-
-// Lifecycle vocabularies (kanban lanes).
-export const IDEA_STATUS = ['capture', 'refine', 'accepted', 'plan', 'parked', 'done'] as const;
-export const PLAN_STATUS = ['plan', 'prototype', 'implement', 'validate', 'done', 'parked'] as const;
-export const TASK_STATUS = ['inbox', 'today', 'in_progress', 'done', 'deferred'] as const;
-export const SESSION_PHASE = ['backlog', 'planning', 'implementing', 'validating', 'complete'] as const;
-export const INSIGHT_STATUS = ['new', 'accepted', 'parked'] as const;
-
-/** A pointer into ~/docs knowledge — the target of `blocked_by` / `cites` edges. */
-export const KnowledgeRefSchema = z
-  .object({
-    path: z.string().min(1),
-    reason: z.string().optional(),
-    status: z.enum(['open', 'resolved']).default('open'),
-    title: z.string().optional(),
-  })
-  .passthrough();
-export type KnowledgeRef = z.infer<typeof KnowledgeRefSchema>;
-
-// Relationship frontmatter fields shared by all objects (typed edges live here +
-// optionally in edges.jsonl; the index unions both).
-const baseShape = {
-  schema: z.string().optional(),
-  id: z.string().min(1),
-  title: z.string().optional(),
-  status: z.string().optional(),
-  created: z.string().optional(),
-  updated: z.string().optional(),
-  domain: z.string().optional(),
-  project: z.string().optional(),
-  priority: z.string().optional(),
-  tags: z.array(z.string()).default([]),
-  cites: z.array(z.string()).default([]),
-  blocked_by: z.array(KnowledgeRefSchema).default([]),
-  depends_on: z.array(z.string()).default([]),
-  related: z.array(z.string()).default([]),
-  linked_sessions: z.array(z.string()).default([]),
-};
-
-export const DomainSchema = z
-  .object({ ...baseShape, type: z.literal('domain'), name: z.string().optional() })
-  .passthrough();
-
-export const ProjectSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('project'),
-    catalog_slug: z.string().optional(),
-    kb_paths: z.array(z.string()).default([]),
-    repos: z.array(z.string()).default([]),
-    status: z.string().default('active'),
-  })
-  .passthrough();
-
-export const CatalogEntrySchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('catalog_entry'),
-    catalog_slug: z.string().optional(),
-    kb_paths: z.array(z.string()).default([]),
-    status: z.string().default('active'),
-  })
-  .passthrough();
-
-export const IdeaSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('idea'),
-    status: z.enum(IDEA_STATUS).default('capture'),
-    promoted_to: z.string().optional(),
-  })
-  .passthrough();
-
-export const PlanSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('plan'),
-    status: z.enum(PLAN_STATUS).default('plan'),
-    kind: z.enum(['dev', 'life']).default('dev'),
-    phase: z.enum(SESSION_PHASE).optional(),
-    promoted_from: z.string().optional(),
-  })
-  .passthrough();
-
-export const TaskSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('task'),
-    status: z.enum(TASK_STATUS).default('inbox'),
-    plan: z.string().optional(),
-    daily: z.string().optional(),
-    scheduled_for: z.string().optional(),
-    dispatch_task_id: z.string().optional(),
-  })
-  .passthrough();
-
-export const DailyPlanSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('daily_plan'),
-    date: z.string().min(1),
-    domain_focus: z.array(z.string()).default([]),
-    carry_over_from: z.string().optional(),
-  })
-  .passthrough();
-
-export const ReflectionSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('reflection'),
-    date: z.string().min(1),
-    daily_plan: z.string().optional(),
-    domains: z.array(z.string()).default([]),
-  })
-  .passthrough();
-
-export const InsightSchema = z
-  .object({
-    ...baseShape,
-    type: z.literal('insight'),
-    source: z.string().min(1),
-    source_ref: z.string().optional(),
-    generated_at: z.string().optional(),
-    confidence: z.string().optional(),
-    suggested_tasks: z.array(z.string()).default([]),
-    status: z.enum(INSIGHT_STATUS).default('new'),
-  })
-  .passthrough();
-
-export const SCHEMA_BY_TYPE = {
-  domain: DomainSchema,
-  project: ProjectSchema,
-  catalog_entry: CatalogEntrySchema,
-  idea: IdeaSchema,
-  plan: PlanSchema,
-  task: TaskSchema,
-  daily_plan: DailyPlanSchema,
-  reflection: ReflectionSchema,
-  insight: InsightSchema,
-} as const;
-
-export const ObjectSchema = z.discriminatedUnion('type', [
-  DomainSchema,
-  ProjectSchema,
-  CatalogEntrySchema,
-  IdeaSchema,
-  PlanSchema,
-  TaskSchema,
-  DailyPlanSchema,
-  ReflectionSchema,
-  InsightSchema,
-]);
-
-export type Domain = z.infer<typeof DomainSchema>;
-export type Project = z.infer<typeof ProjectSchema>;
-export type CatalogEntry = z.infer<typeof CatalogEntrySchema>;
-export type Idea = z.infer<typeof IdeaSchema>;
-export type Plan = z.infer<typeof PlanSchema>;
-export type Task = z.infer<typeof TaskSchema>;
-export type DailyPlan = z.infer<typeof DailyPlanSchema>;
-export type Reflection = z.infer<typeof ReflectionSchema>;
-export type Insight = z.infer<typeof InsightSchema>;
-export type PlanningObject = z.infer<typeof ObjectSchema>;
-
-// Explicit edges (edges.jsonl, append-only + rebuildable from frontmatter).
-export const EDGE_KINDS = [
-  'depends_on',
-  'blocks',
-  'blocked_by',
-  'implements',
-  'cites',
-  'translates_to',
-  'promoted_to',
-  'parent_of',
-  'related',
-  'evidence',
-  'surfaced_on',
-  'scheduled_for',
-] as const;
-export type EdgeKind = (typeof EDGE_KINDS)[number];
-
-export const EdgeSchema = z
-  .object({
-    kind: z.enum(EDGE_KINDS),
-    from: z.string().min(1),
-    to: z.string().min(1),
-    reason: z.string().optional(),
-    status: z.enum(['open', 'resolved']).optional(),
-    created_at: z.string().optional(),
-  })
-  .passthrough();
-export type Edge = z.infer<typeof EdgeSchema>;
-
-/** Validate a parsed frontmatter object against the schema for its `type`. */
-export function parseObject(data: unknown): PlanningObject {
-  return ObjectSchema.parse(data);
-}
-
-export function safeParseObject(data: unknown) {
-  return ObjectSchema.safeParse(data);
-}

package/src/schema/frontmatter.ts

@@ -1,44 +0,0 @@
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
-
-/** A markdown document split into YAML frontmatter (`data`) and `body`. */
-export interface MarkdownDoc {
-  data: Record<string, unknown>;
-  body: string;
-}
-
-const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
-
-/** Split `---\n…\n---\n` frontmatter from the body. No frontmatter → `data: {}`. */
-export function parseMarkdown(content: string): MarkdownDoc {
-  const m = content.match(FRONTMATTER_RE);
-  if (!m) return { data: {}, body: content };
-  const parsed = parseYaml(m[1]) ?? {};
-  const data = typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : {};
-  return { data, body: content.slice(m[0].length) };
-}
-
-/** Drop `undefined`/`null` and empty arrays so serialized frontmatter stays clean. */
-function clean(value: unknown): unknown {
-  if (Array.isArray(value)) return value.map(clean).filter((v) => v !== undefined && v !== null);
-  if (value && typeof value === 'object') {
-    const out: Record<string, unknown> = {};
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-      const cv = clean(v);
-      if (cv === undefined || cv === null) continue;
-      if (Array.isArray(cv) && cv.length === 0) continue;
-      out[k] = cv;
-    }
-    return out;
-  }
-  return value;
-}
-
-/** Serialize frontmatter + body back to a markdown string. */
-export function serializeMarkdown(data: Record<string, unknown>, body = ''): string {
-  const cleaned = clean(data) as Record<string, unknown>;
-  const fm = stringifyYaml(cleaned, { lineWidth: 0 }).trimEnd();
-  const block = `---\n${fm}\n---\n`;
-  const trimmed = body.replace(/^\n+/, '');
-  if (!trimmed.trim()) return block;
-  return `${block}\n${trimmed.replace(/\n*$/, '\n')}`;
-}

package/src/schema/index.ts

@@ -1,2 +0,0 @@
-export * from './entities.ts';
-export * from './frontmatter.ts';

package/src/store/store.test.ts

@@ -1,64 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, rmSync, existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { Store } from './store.ts';
-
-let dir: string;
-beforeEach(() => {
-  dir = mkdtempSync(join(tmpdir(), 'kp-store-'));
-});
-afterEach(() => {
-  rmSync(dir, { recursive: true, force: true });
-});
-
-describe('Store', () => {
-  it('writes and reloads objects keyed by id', () => {
-    const s = new Store(dir);
-    s.write({ id: 'projects/code-build', type: 'project', title: 'Code Build', repos: ['gh:cb'] }, 'CB body');
-    s.write({ id: 'ideas/memory-maps', type: 'idea', title: 'Memory maps', project: 'projects/code-build' }, 'desc');
-
-    // project is a container → folder/index.md
-    expect(existsSync(join(dir, 'projects/code-build/index.md'))).toBe(true);
-    expect(existsSync(join(dir, 'ideas/memory-maps.md'))).toBe(true);
-
-    const fresh = new Store(dir);
-    expect(fresh.get('ideas/memory-maps')?.object.title).toBe('Memory maps');
-    expect(fresh.byType('project').length).toBe(1);
-    expect(fresh.get('projects/code-build')?.body.trim()).toBe('CB body');
-  });
-
-  it('derives frontmatter edges (blocked_by + parent_of)', () => {
-    const s = new Store(dir);
-    s.write({ id: 'projects/cb', type: 'project', title: 'CB' });
-    s.write({ id: 'ideas/mm', type: 'idea', title: 'MM', project: 'projects/cb' });
-    s.write({
-      id: 'plans/reloc',
-      type: 'plan',
-      title: 'Reloc',
-      kind: 'life',
-      blocked_by: [{ path: 'knowledge/life/relocation/x.md', reason: 'tax compare' }],
-    });
-    const edges = new Store(dir).frontmatterEdges();
-    expect(edges.some((e) => e.kind === 'blocked_by' && e.to.includes('relocation'))).toBe(true);
-    expect(edges.some((e) => e.kind === 'parent_of' && e.to === 'ideas/mm')).toBe(true);
-  });
-
-  it('appends and reads explicit edges', () => {
-    const s = new Store(dir);
-    s.appendEdge({ kind: 'translates_to', from: 'plans/a', to: 'plans/b' });
-    expect(new Store(dir).fileEdges().length).toBe(1);
-    expect(new Store(dir).fileEdges()[0]?.kind).toBe('translates_to');
-  });
-
-  it('patches frontmatter in place', () => {
-    const s = new Store(dir);
-    s.write({ id: 'ideas/x', type: 'idea', title: 'X' }, 'body');
-    s.patch('ideas/x', (d) => {
-      d.status = 'accepted';
-    });
-    const reloaded = new Store(dir).get('ideas/x');
-    expect(reloaded?.data.status).toBe('accepted');
-    expect(reloaded?.body.trim()).toBe('body'); // body preserved
-  });
-});