@warren-dean/code-kit 0.18.0 → 0.20.0

package/hooks/lib/adapters/hub/index.mjs

@@ -0,0 +1,25 @@
+// code-kit hub as a team provider adapter (code-kit spec 21, HUBR-6): chosen by
+// `"team": { "provider": { "hub": "<https address>" } }`, with GitHub as its fallback. Its client
+// (client.mjs) is code-kit's provider command, the session's live link (the event stream and the team's
+// state on disk) and the person's sign-in. In preview (HUBR-8): nothing outside this folder names it,
+// and code-kit only says its name for a project whose config does.
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { recordPresence, startDaemon, stopDaemon } from './client.mjs';
+
+const CLIENT = join(dirname(fileURLToPath(import.meta.url)), 'client.mjs');
+const quoted = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;
+
+export default {
+  key: 'hub',
+  label: 'code-kit hub',
+  command: (url) => `node ${quoted(CLIENT)} --url ${quoted(url)}`,
+  session: {
+    start: (root, session, watch, url) => startDaemon(root, session, watch, url),
+    end: (root, session) => stopDaemon(root, session),
+  },
+  presence: (root, session, agents) => recordPresence(root, session, agents),
+  run: (args, url) =>
+    spawnSync(process.execPath, [CLIENT, '--url', url, ...args], { stdio: 'inherit' }).status ?? 1,
+};

package/hooks/lib/adapters/index.mjs

@@ -18,9 +18,44 @@
 //             files(root, paths) → { [path]: { rules } }, open: { command } (its view of a file) }
 //
 // The core only ever calls applyAdapters() and activeAdapters(); it never names a tool.
+//
+// Team provider adapters (HUBR-6) are the other kind: a hosted team provider's client, chosen when the
+// config's `team.provider` names it, as `{ "<key>": "<its https address>" }`. Each says:
+//
+//   key       the provider's key in `team.provider`
+//   label     what code-kit calls it, only when a config names it (HUBR-8)
+//   command   (url) => the provider command code-kit runs for each operation (TEAM-2)
+//   session   { start(root, session, watch, url), end(root, session) }: the session's live link
+//   presence  (root, session, agents) => void: the session's agents, for the provider
+//   run       (args, url) => exit code: the client's own commands (sign in, connect, status), for
+//             `code-kit team provider …`
+//
+// The core only ever calls providerAdapterOf(); it never names a provider.
 import contextGraph from './context-graph.mjs';
+import hub from './hub/index.mjs';
 
 export const ADAPTERS = [contextGraph];
+export const PROVIDERS = [hub];
+
+const isAddress = (v) => typeof v === 'string' && /^https?:\/\/[^\s]+$/.test(v);
+
+/**
+ * The team provider adapter `team.provider` names, with its address: { adapter, url }, or null when the
+ * provider isn't an adapter's (GitHub, or a command). `{ problem }` when it names one wrongly.
+ */
+export function providerAdapterOf(provider) {
+  if (provider === null || typeof provider !== 'object' || Array.isArray(provider)) return null;
+  const adapter = PROVIDERS.find((p) => p.key in provider);
+  if (!adapter) return null;
+  const extra = Object.keys(provider).filter((k) => k !== adapter.key && k !== 'fallback');
+  if (
+    !isAddress(provider[adapter.key]) ||
+    extra.length ||
+    ![undefined, 'github'].includes(provider.fallback)
+  )
+    return { problem: true };
+  return { adapter, url: provider[adapter.key].replace(/\/$/, '') };
+}
 
 /** Adapters detected in `root` and not switched off by the config's `adapters` map. */
 export function activeAdapters(raw, root) {

package/hooks/lib/harness.mjs

@@ -47,12 +47,13 @@ export const SETTINGS = {
     about: 'A background reviewer for each finished branch',
   },
   'agents.reviewer.model': {
-    default: null,
+    default: 'sonnet',
     problem: (v) =>
       v === null || (typeof v === 'string' && v.length > 0)
         ? null
         : `must be a model (${MODELS.join(', ')}, or an id), or null for the session's`,
-    about: "The reviewer's model; none means the session's",
+    about:
+      "The reviewers' model (code-kit's reviewer and the security reviewer); none means the session's",
   },
   'agents.lanes.model': {
     default: null,
@@ -63,12 +64,26 @@ export const SETTINGS = {
     about:
       "The lane agents' model, set as each is dispatched; none means the session's. A lane's agent file with its own model keeps it",
   },
+  'agents.lanes.contextLimit': {
+    default: 250000,
+    problem: (v) =>
+      Number.isInteger(v) && v >= 0 ? null : 'must be a whole number of tokens, 0 for no limit',
+    about:
+      "The context a lane agent may reach before it's asked to wrap up and hand its story to a fresh agent; 0 for no limit",
+  },
   'background.pauseAtPercent': {
     default: 80,
     problem: (v) =>
       Number.isFinite(v) && v > 0 && v <= 100 ? null : 'must be a percentage from 1 to 100',
     about: "The plan's 5-hour use at which background agents pause",
   },
+  'compact.at': {
+    default: 40,
+    problem: (v) =>
+      Number.isFinite(v) && v >= 0 && v <= 100 ? null : 'must be a percentage from 0 (off) to 100',
+    about:
+      "How full the lead's context may get, as a share of its window, before it's compacted between turns; 0 for never",
+  },
   'compact.milestone': {
     default: 'ask',
     problem: (v) => (COMPACT.includes(v) ? null : `must be one of ${COMPACT.join(', ')}`),

package/hooks/lib/instructions.mjs

@@ -7,7 +7,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 /** The version of code-kit's instructions: raised whenever the templates' rules change. */
-export const INSTRUCTIONS_VERSION = 4;
+export const INSTRUCTIONS_VERSION = 5;
 
 const TEMPLATES = fileURLToPath(new URL('../../templates/', import.meta.url));
 const BEGIN = (v) => `<!-- code-kit:begin v${v} -->`;

package/hooks/lib/next.mjs

@@ -1,7 +1,7 @@
 // What to do next, from the project's state alone: no docs → spec-design; a spec still being shaped →
 // spec-design; a ready spec or existing code without the kit → init; then, from the plan and git:
 // review finished stories, dispatch ready ones, wait on running ones, or plan the next milestone.
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, posix } from 'node:path';
 import { loadConfig, mergeDelegation } from './config.mjs';
@@ -254,6 +254,12 @@ export function nextStep(root, base) {
     attention.push(
       `${unbuildable.join(', ')} can't be dispatched until the plan's gaps are fixed.`,
     );
+  // LEAN-6: worktrees whose story is merged and which hold nothing uncommitted are only disk space.
+  const leftovers = mergedWorktrees(root, config);
+  if (leftovers)
+    attention.push(
+      `${leftovers} worktree${leftovers === 1 ? ' is' : 's are'} merged and clean; \`code-kit worktrees prune\` removes them, keeping their reports.`,
+    );
   // ONB-8: code-kit's own instructions to the lead and the lanes, brought up to date before the next step:
   // a newer code-kit's rules reach the agents only through them.
   const instructions = instructionsState(root, config);
@@ -485,3 +491,23 @@ export function missingSkills(root) {
   }
   return out;
 }
+
+/** LEAN-6: how many of the project's worktrees have a merged branch and nothing uncommitted. */
+function mergedWorktrees(root, config) {
+  const list = git(root, 'worktree', 'list', '--porcelain');
+  if (!list) return 0;
+  const from = config.branches?.protected?.[0];
+  if (!from || !git(root, 'rev-parse', '--verify', '-q', from)) return 0;
+  let n = 0;
+  for (const block of list.split('\n\n').slice(1)) {
+    const path = /^worktree (.+)$/m.exec(block)?.[1];
+    const branch = /^branch refs\/heads\/(.+)$/m.exec(block)?.[1];
+    if (!path || !branch) continue;
+    const merged =
+      spawnSync('git', ['merge-base', '--is-ancestor', branch, from], { cwd: root }).status === 0;
+    if (!merged) continue;
+    const status = spawnSync('git', ['-C', path, 'status', '--porcelain'], { encoding: 'utf8' });
+    if (status.status === 0 && !status.stdout.trim()) n++;
+  }
+  return n;
+}

package/hooks/lib/plan.mjs

@@ -86,6 +86,30 @@ export function readStories(root, planPath) {
   return stories;
 }
 
+/**
+ * HUBR-5: each milestone in the plan, in order: [{ name, target }], `name` the `## ` heading a story sits
+ * under, `target` the date a `**Target:** YYYY-MM-DD` line under that heading gives, before its first
+ * story, or null.
+ */
+export function readMilestones(root, planPath) {
+  const found = [];
+  for (const file of markdownFiles(root, planPath)) {
+    let current = null;
+    for (const line of readFileSync(join(root, file), 'utf8').split('\n')) {
+      const heading = line.match(/^##\s+(.+?)\s*$/);
+      if (heading) {
+        current = { name: heading[1], target: null, open: true };
+        found.push(current);
+        continue;
+      }
+      if (/^###\s/.test(line) && current) current.open = false;
+      const target = line.match(/^\*\*Target:\*\*\s*(\d{4}-\d{2}-\d{2})\s*$/i);
+      if (target && current?.open && !current.target) current.target = target[1];
+    }
+  }
+  return found.map(({ name, target }) => ({ name, target }));
+}
+
 export const storyBranch = (story) => `${story.lane}/${story.id.toLowerCase()}`;
 
 /** Requirement IDs each tracked test file names: { id: [file, ...] }. */

package/hooks/lib/snapshot.mjs

@@ -0,0 +1,352 @@
+// HUBR-2: what a project reports to its team provider (docs/specs/21-hub-adapter-and-reports.md): a
+// snapshot of facts code-kit already has (status, timeline, trail, journal's approvals, the merge queue,
+// usage, the rules), as metadata only. SNAPSHOT_SCHEMA is the allow-list: every field a snapshot may
+// hold, and what kind of value it is. A provider validates against the same list, and `validSnapshot`
+// refuses anything else, so file contents, diffs, prompts and messages have nowhere to go.
+import { createHash } from 'node:crypto';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { APPROVAL_LOG } from './rules.mjs';
+import { approverOf } from './journal.mjs';
+import { readQueue } from './queue.mjs';
+import { sendBacks } from './reviews.mjs';
+import { readMilestones, specCheckRows } from './plan.mjs';
+import { storyTimes } from './timeline.mjs';
+import { trail } from './storymap.mjs';
+
+export const SNAPSHOT_VERSION = 1;
+
+/** A story's stage, as a report names it. */
+export const STAGES = [
+  'planned',
+  'claimed',
+  'building',
+  'review',
+  'sent-back',
+  'queued',
+  'merged',
+  'done',
+];
+export const AGENT_KINDS = ['lead', 'lane', 'reviewer', 'security-reviewer', 'background'];
+
+/**
+ * The allow-list. A leaf is a kind: `id` (ST-4, API-2), `handle` (a GitHub login), `name` (a lane, a
+ * layer, a milestone, an approval: one line, at most 120 characters), `title` (one line, at most 200),
+ * `line` (a send-back's reason: one line, at most 200), `path` (a file path or glob: one line, at most
+ * 300), `ms` (a time in milliseconds), `date` (YYYY-MM-DD), `count` (a whole number, 0 or more),
+ * `bool`, `enum:a|b`. A trailing `?` allows null. An array holds one shape; an object holds only the
+ * keys it lists.
+ */
+export const SNAPSHOT_SCHEMA = {
+  version: 'count',
+  project: { repository: 'name?', base: 'name', codeKit: 'name', at: 'ms' },
+  milestones: [{ name: 'name', target: 'date?', stories: ['id'] }],
+  stories: [
+    {
+      id: 'id',
+      title: 'title',
+      lane: 'name?',
+      milestone: 'name?',
+      requirements: ['id'],
+      dependsOn: ['id'],
+      stage: `enum:${STAGES.join('|')}`,
+      since: {
+        building: 'ms?',
+        review: 'ms?',
+        sentBack: 'ms?',
+        queued: 'ms?',
+        merged: 'ms?',
+      },
+      claimedBy: 'handle?',
+    },
+  ],
+  sendBacks: [{ story: 'id', at: 'ms', reason: 'line?' }],
+  requirements: [
+    {
+      id: 'id',
+      stories: ['id'],
+      built: ['path'],
+      tested: ['path'],
+      check: 'enum:done|partial|missing|conflicts|none',
+    },
+  ],
+  approvals: [{ what: 'name', path: 'path?', who: 'enum:person|lead', at: 'ms', branch: 'name?' }],
+  usage: [
+    {
+      story: 'id?',
+      kind: `enum:${AGENT_KINDS.join('|')}`,
+      input: 'count',
+      output: 'count',
+      cache: 'count',
+    },
+  ],
+  rules: {
+    layers: [{ name: 'name', mayImport: ['name'] }],
+    protected: [{ glob: 'path', approval: 'name' }],
+    delegated: { protected: ['name'], dependencies: 'bool', merge: 'bool' },
+    designGate: 'bool',
+  },
+};
+
+const ONE_LINE = (max) => (v) => typeof v === 'string' && v.length <= max && !/[\r\n]/.test(v);
+const KINDS = {
+  id: (v) => typeof v === 'string' && /^[A-Za-z][A-Za-z0-9]*-\d+$/.test(v),
+  handle: (v) => typeof v === 'string' && /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/.test(v),
+  name: ONE_LINE(120),
+  title: ONE_LINE(200),
+  line: ONE_LINE(200),
+  path: ONE_LINE(300),
+  ms: (v) => Number.isInteger(v) && v > 0,
+  date: (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v),
+  count: (v) => Number.isInteger(v) && v >= 0,
+  bool: (v) => typeof v === 'boolean',
+};
+
+/** What's wrong with a snapshot against the allow-list, as `path: problem` lines; empty when valid. */
+export function snapshotProblems(value, shape = SNAPSHOT_SCHEMA, at = 'snapshot') {
+  if (typeof shape === 'string') {
+    const optional = shape.endsWith('?');
+    const kind = optional ? shape.slice(0, -1) : shape;
+    if (value === null || value === undefined) return optional ? [] : [`${at}: missing`];
+    if (kind.startsWith('enum:'))
+      return kind.slice(5).split('|').includes(value) ? [] : [`${at}: not one of ${kind.slice(5)}`];
+    return KINDS[kind](value) ? [] : [`${at}: not a ${kind}`];
+  }
+  if (Array.isArray(shape)) {
+    if (!Array.isArray(value)) return [`${at}: not a list`];
+    return value.flatMap((v, i) => snapshotProblems(v, shape[0], `${at}[${i}]`));
+  }
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    return [`${at}: not an object`];
+  const extra = Object.keys(value).filter((k) => !(k in shape));
+  return [
+    ...extra.map((k) => `${at}.${k}: not a field a report may hold`),
+    ...Object.entries(shape).flatMap(([k, s]) => snapshotProblems(value[k], s, `${at}.${k}`)),
+  ];
+}
+
+/** The snapshot's hash, leaving out when it was made: equal snapshots aren't sent twice. */
+export function snapshotHash(snapshot, parts = null) {
+  const { project, ...rest } = snapshot;
+  const kept = parts ? Object.fromEntries(parts.map((p) => [p, rest[p]])) : rest;
+  return createHash('sha256')
+    .update(JSON.stringify({ project: { ...project, at: 0 }, ...kept }))
+    .digest('hex');
+}
+
+/** The parts whose change is sent at once (HUBR-3); usage alone waits for the ten minutes. */
+export const EVENT_PARTS = [
+  'milestones',
+  'stories',
+  'sendBacks',
+  'requirements',
+  'approvals',
+  'rules',
+];
+
+const git = (root, ...args) => {
+  try {
+    return execFileSync('git', ['-C', root, ...args], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+};
+
+/** owner/name of the repository's GitHub origin, or null. */
+export function repositoryOf(root) {
+  const remote = git(root, 'config', '--get', 'remote.origin.url');
+  const m = remote.match(/github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+
+/** The main checkout, where the lanes' worktrees share their state. */
+export function mainCheckout(root) {
+  const common = git(root, 'rev-parse', '--path-format=absolute', '--git-common-dir');
+  return common ? dirname(common) : root;
+}
+
+export const USAGE_DIR = '.claude/state/usage';
+
+/** The usage every session recorded (USE-1's ledgers, written by the mod): [{ story, kind, … }]. */
+export function recordedUsage(root) {
+  const dir = join(mainCheckout(root), USAGE_DIR);
+  const sums = new Map();
+  let files = [];
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith('.json'));
+  } catch {
+    return [];
+  }
+  for (const f of files) {
+    let entries = [];
+    try {
+      entries = Object.values(JSON.parse(readFileSync(join(dir, f), 'utf8')).entries ?? {});
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!AGENT_KINDS.includes(e.kind)) continue;
+      const story = KINDS.id(e.story) ? e.story : null;
+      const key = `${story}|${e.kind}`;
+      const was = sums.get(key) ?? { story, kind: e.kind, input: 0, output: 0, cache: 0 };
+      for (const k of ['input', 'output', 'cache'])
+        was[k] += Number.isInteger(e[k]) && e[k] > 0 ? e[k] : 0;
+      sums.set(key, was);
+    }
+  }
+  return [...sums.values()];
+}
+
+/** The spec-check report's status for each requirement of a story, from its branch's report. */
+function checkedRows(root, story) {
+  const name = `${story.branch.replace(/[^\w.-]+/g, '_')}.md`;
+  for (const dir of [story.worktree, root].filter(Boolean)) {
+    const file = join(dir, '.claude/state/spec-check', name);
+    if (existsSync(file)) return specCheckRows(readFileSync(file, 'utf8'));
+  }
+  return [];
+}
+
+const CHECKS = ['done', 'partial', 'missing', 'conflicts'];
+
+/**
+ * The snapshot (HUBR-2) from what code-kit already computed: `status` is buildStatus's, `base` the
+ * branch stories merge into, `claims` the team's claims as last read, `version` code-kit's.
+ */
+export function buildSnapshot({
+  root,
+  config,
+  status,
+  base,
+  claims = [],
+  version,
+  now = Date.now(),
+}) {
+  const times = new Map(storyTimes(root, status.stories, base).map((t) => [t.id, t]));
+  const queued = new Map(
+    readQueue(root)
+      .filter((e) => e.state === 'waiting' || e.state === 'merging')
+      .map((e) => [e.branch, Date.parse(e.passed)]),
+  );
+  const backs = sendBacks(root);
+  const claimed = new Map(claims.map((c) => [c.story, c.by]));
+  const ms = (v) => (Number.isInteger(v) && v > 0 ? v : null);
+  const line = (s) => (s ? String(s).replace(/\s+/g, ' ').trim().slice(0, 200) || null : null);
+
+  const stories = status.stories.map((s) => {
+    const t = times.get(s.id) ?? {};
+    const myBacks = backs.filter((b) => b.branch === s.branch);
+    const lastBack = myBacks.length ? Date.parse(myBacks.at(-1).at) : null;
+    let stage = 'planned';
+    if (s.state === 'done') stage = s.status === 'done' ? 'done' : 'merged';
+    else if (s.state === 'sent back') stage = 'sent-back';
+    else if (s.state === 'review') stage = queued.has(s.branch) ? 'queued' : 'review';
+    else if (s.state === 'in progress') stage = 'building';
+    else if (claimed.has(s.id)) stage = 'claimed';
+    const reached = STAGES.indexOf(stage);
+    return {
+      id: s.id,
+      title: line(s.title) ?? s.id,
+      lane: s.lane || null,
+      milestone: s.milestone ? line(s.milestone).slice(0, 120) : null,
+      requirements: s.requirements,
+      dependsOn: s.dependsOn,
+      stage,
+      since: {
+        building: reached >= STAGES.indexOf('building') ? ms(t.started) : null,
+        review:
+          reached >= STAGES.indexOf('review') && stage !== 'sent-back' ? ms(t.lastCommit) : null,
+        sentBack: ms(lastBack),
+        queued: stage === 'queued' ? ms(queued.get(s.branch)) : null,
+        merged: ms(t.merged),
+      },
+      claimedBy: claimed.get(s.id) ?? null,
+    };
+  });
+
+  const targets = Object.fromEntries(
+    readMilestones(root, config.docs.plan).map((m) => [m.name, m.target]),
+  );
+  const milestones = [...new Set(status.stories.map((s) => s.milestone).filter(Boolean))].map(
+    (m) => ({
+      name: line(m).slice(0, 120),
+      target: targets[m] ?? null,
+      stories: status.stories.filter((s) => s.milestone === m).map((s) => s.id),
+    }),
+  );
+
+  const byBranch = new Map(status.stories.map((s) => [s.branch, s.id]));
+  const sendBackList = backs
+    .filter((b) => byBranch.has(b.branch) && ms(Date.parse(b.at)))
+    .map((b) => ({ story: byBranch.get(b.branch), at: Date.parse(b.at), reason: line(b.reason) }));
+
+  const checks = new Map();
+  for (const s of status.stories)
+    if (s.branchExists)
+      for (const row of checkedRows(root, s))
+        if (CHECKS.includes(row.status)) checks.set(row.requirement, row.status);
+  const requirements = trail(root, status, base).map((r) => ({
+    id: r.id,
+    stories: r.stories.map((s) => s.id),
+    built: r.files.filter((f) => KINDS.path(f)),
+    tested: r.tests.filter((f) => KINDS.path(f)),
+    check: checks.get(r.id) ?? 'none',
+  }));
+
+  const approvals = [];
+  const seen = new Set();
+  for (const raw of git(root, 'show', `${base}:${APPROVAL_LOG}`).split('\n').filter(Boolean)) {
+    let e;
+    try {
+      e = JSON.parse(raw);
+    } catch {
+      continue;
+    }
+    if (!e.approval || e.approval === 'lead') continue;
+    const at = Date.parse(e.grantedAt ?? e.at);
+    const key = `${e.approval}|${e.file ?? ''}|${at}`;
+    if (seen.has(key) || !ms(at) || !KINDS.name(e.approval)) continue;
+    seen.add(key);
+    approvals.push({
+      what: e.approval,
+      path: KINDS.path(e.file) ? e.file : null,
+      who: approverOf(e),
+      at,
+      branch: KINDS.name(e.branch) ? e.branch : null,
+    });
+  }
+
+  const delegate = config.approvals?.delegate ?? null;
+  const snapshot = {
+    version: SNAPSHOT_VERSION,
+    project: {
+      repository: repositoryOf(root),
+      base,
+      codeKit: String(version),
+      at: now,
+    },
+    milestones,
+    stories,
+    sendBacks: sendBackList,
+    requirements,
+    approvals,
+    usage: recordedUsage(root),
+    rules: {
+      layers: (config.layers ?? []).map((l) => ({ name: l.name, mayImport: l.mayImport ?? [] })),
+      protected: (config.protected ?? [])
+        .filter((p) => KINDS.path(p.glob) && KINDS.name(p.approval))
+        .map((p) => ({ glob: p.glob, approval: p.approval })),
+      delegated: {
+        protected: delegate?.protected ?? [],
+        dependencies: Boolean(delegate?.dependencies),
+        merge: Boolean(delegate?.merge),
+      },
+      designGate: Boolean(config.designGate),
+    },
+  };
+  return snapshot;
+}