@warren-dean/code-kit 0.19.0 → 0.21.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/checks.mjs

@@ -16,13 +16,14 @@ function directories(check, files, root) {
 }
 
 /**
- * The first failure as { title, output }, or null. `actor` decides `owners`; the lead always may. A
+ * The first failure as { check, title, output }, or null. `actor` decides `owners`; the lead always may. A
  * command that isn't installed skips the rest of the check, unless `ifMissing` is "fail", and is
  * added to `skipped` as { check, command, where }, so a pass never hides a check that didn't run.
  */
 function runCheck(check, files, root, actor, skipped) {
   if (check.owners && !(actor.kind === 'lead' || check.owners.includes(actor.lane))) {
     return {
+      check: check.name,
       title: `The ${actor.label} changed ${check.name} files it does not own:`,
       output: files.join('\n'),
     };
@@ -39,6 +40,7 @@ function runCheck(check, files, root, actor, skipped) {
       if (res.status === 127) {
         if (check.ifMissing === 'fail')
           return {
+            check: check.name,
             title: `${check.name}: \`${command}\` is not installed${where}. Install it so the check can run.`,
           };
         skipped.push({ check: check.name, command, where: where.replace(/^ in /, '') || null });
@@ -46,10 +48,12 @@ function runCheck(check, files, root, actor, skipped) {
       }
       if (res.error || res.status === null)
         return {
+          check: check.name,
           title: `${check.name}: \`${command}\` did not finish${where} (${res.error?.code ?? res.signal}).`,
         };
       if (res.status !== 0)
         return {
+          check: check.name,
           title: `${check.name}: \`${command}\` fails${where}. Fix it:`,
           output: res.stdout + res.stderr,
         };

package/hooks/lib/config.mjs

@@ -174,7 +174,7 @@ export function validate(c) {
   );
   // A brownfield project may have no specs yet: then there is no spec-check gate.
   need(c.docs === undefined || isObj(c.docs), '"docs" must be an object');
-  for (const k of ['specs', 'principles', 'plan', 'decisions'])
+  for (const k of ['specs', 'principles', 'plan', 'decisions', 'standards'])
     need(c.docs?.[k] === undefined || isStr(c.docs[k]), `"docs.${k}" must be a path`);
   need(isObj(c.lead) && isList(c.lead?.paths), '"lead.paths" must be a list of globs');
   need(

package/hooks/lib/instructions.mjs

@@ -5,9 +5,16 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  appliesTo,
+  laneLayers,
+  projectStandards,
+  standardLine,
+  standardsFile,
+} from './standards.mjs';
 
 /** The version of code-kit's instructions: raised whenever the templates' rules change. */
-export const INSTRUCTIONS_VERSION = 5;
+export const INSTRUCTIONS_VERSION = 6;
 
 const TEMPLATES = fileURLToPath(new URL('../../templates/', import.meta.url));
 const BEGIN = (v) => `<!-- code-kit:begin v${v} -->`;
@@ -25,8 +32,20 @@ function fill(text, facts) {
     .replace(/\n{3,}/g, '\n\n');
 }
 
-/** What the templates need from the project: everything the config and the repository say. */
-function factsOf(root, config) {
+/** The standards that apply (spec 22), or none when the file can't be read. */
+function standardsOf(root, config) {
+  try {
+    return projectStandards(root, config).standards;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * What the templates need from the project: everything the config and the repository say. With `lane`,
+ * the standards are the ones for that lane's layers (STD-3).
+ */
+function factsOf(root, config, lane = null) {
   const delegated = new Set(config.approvals?.delegate?.protected ?? []);
   const kept = [];
   for (const p of config.protected ?? []) {
@@ -45,9 +64,24 @@ function factsOf(root, config) {
     'docs.specs': config.docs?.specs ?? 'the specs',
     'docs.plan': config.docs?.plan ?? 'the plan',
     'docs.principles': config.docs?.principles ?? "the project's principles",
+    'docs.standards': standardsFile(config),
+    standards: laneStandards(root, config, lane),
+    'standards.all': standardsOf(root, config)
+      .map((s) => `${s.id} ${s.title}`)
+      .join('; '),
   };
 }
 
+/** A lane's standards as the lines of a nested list, or '' when none apply. */
+function laneStandards(root, config, lane) {
+  if (!lane) return '';
+  const layers = (config.layers ?? []).length ? laneLayers(config.lanes?.[lane], config) : null;
+  const lines = standardsOf(root, config)
+    .filter((s) => appliesTo(s, layers))
+    .map((s) => `\n  - ${standardLine(s)}`);
+  return lines.join('');
+}
+
 const marked = (body) => `${BEGIN(INSTRUCTIONS_VERSION)}\n${body.trim()}\n${END}`;
 
 /** The lead's section of CLAUDE.md, between its markers. */
@@ -55,10 +89,10 @@ export function leadSection(root, config) {
   return marked(fill(readFileSync(join(TEMPLATES, 'claude-md.md'), 'utf8'), factsOf(root, config)));
 }
 
-/** A lane agent's "Always:" rules, between their markers. */
-export function agentRules(root, config) {
+/** A lane agent's "Always:" rules, between their markers: with `lane`, its layers' standards too. */
+export function agentRules(root, config, lane = null) {
   const template = readFileSync(join(TEMPLATES, 'agent.md'), 'utf8');
-  return marked(fill(template.slice(template.indexOf('Always:')), factsOf(root, config)));
+  return marked(fill(template.slice(template.indexOf('Always:')), factsOf(root, config, lane)));
 }
 
 /** Whether two renderings say the same, whatever their whitespace and list indentation. */
@@ -87,17 +121,16 @@ function stateOf(text, block, legacy) {
  */
 export function instructionsState(root, config) {
   const lead = leadSection(root, config);
-  const rules = agentRules(root, config);
   const files = [
     { file: 'CLAUDE.md', kind: 'lead', block: lead, legacy: LEAD_LEGACY },
-    ...[...new Set(Object.values(config.lanes ?? {}).map((l) => l.agent))]
-      .map((agent) => ({
-        file: `.claude/agents/${agent}.md`,
+    ...Object.entries(config.lanes ?? {})
+      .filter(([, l]) => existsSync(join(root, `.claude/agents/${l.agent}.md`)))
+      .map(([name, l]) => ({
+        file: `.claude/agents/${l.agent}.md`,
         kind: 'lane',
-        block: rules,
+        block: agentRules(root, config, name),
         legacy: AGENT_LEGACY,
-      }))
-      .filter((f) => existsSync(join(root, f.file))),
+      })),
   ];
   return files.map(({ file, kind, block, legacy }) => {
     const path = join(root, file);

package/hooks/lib/layers.mjs

@@ -55,3 +55,14 @@ export function layerProblems(rel, source, config) {
   }
   return problems;
 }
+
+/**
+ * The rule a layer problem broke, read back from its sentence (as layerProblems words it):
+ * { kind: 'layers', from, to } or { kind: 'layers', from, package }. Null for any other text.
+ */
+export function brokenLayerRule(problem) {
+  const pkg = String(problem).match(/ \(([^()]+)\) may not import the package (\S+)\.$/);
+  if (pkg) return { kind: 'layers', from: pkg[1], package: pkg[2] };
+  const layer = String(problem).match(/ \(([^()]+)\) imports \S+ \(([^()]+)\); /);
+  return layer ? { kind: 'layers', from: layer[1], to: layer[2] } : null;
+}

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/rules.mjs

@@ -31,6 +31,7 @@ import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { DEPENDENCY_APPROVAL, isDependencyFile } from './dependencies.mjs';
 import { globToRegExp, matchesAny } from './glob.mjs';
+import { noteFor } from './standards.mjs';
 
 export const APPROVAL_LOG = '.claude/approval-log.jsonl';
 export const APPROVALS_DIR = '.claude/approvals';
@@ -763,7 +764,7 @@ export function writeProblem(actor, rel, root, config) {
       decidedBy(guarded.approval, config) === 'lead'
         ? "the lead's approval"
         : "a person's approval";
-    return `${rel} is ${guarded.why} and needs ${who}. ${askHowTo(guarded.approval, actor, root, config)}`;
+    return `${rel} is ${guarded.why} and needs ${who}.${noteFor(root, config, { kind: 'protected', name: guarded.approval, glob: guarded.glob })} ${askHowTo(guarded.approval, actor, root, config)}`;
   }
   if (matchesAny(rel, config.anyActor)) return null;
   if (actor.kind === 'readonly') return readonlyProblem(actor, rel);