@detergent-software/conductor 1.0.0-dev.5 → 1.0.0-dev.6

package/build/upgrade.js.map

@@ -1 +1 @@
-{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../src/upgrade.ts"],"names":[],"mappings":"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"}

package/mod/.claude-plugin/marketplace.json

@@ -0,0 +1,6 @@
+{
+  "name": "conductor",
+  "description": "The conductor mod, shipped inside @detergent-software/conductor and installed by `conduct install-mod`.",
+  "owner": { "name": "Emergent Software" },
+  "plugins": [{ "name": "conductor", "source": "./" }]
+}

package/mod/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "conductor",
+  "version": "1.0.0",
+  "description": "The conductor console's plumbing: a status line in every session, and in the console the inbox band, the fleet pane, zero-token commands, Remote Control pushes and escalation wake-ups.",
+  "author": { "name": "Emergent Software" },
+  "types": "./types/index.d.ts"
+}

package/mod/README.md

@@ -0,0 +1,17 @@
+# Conductor mod
+
+A Claude Code plugin (a hooks module) that does the conductor console's plumbing in code, so it costs no tokens: a status line in every session and, in the console (`CONDUCTOR_CONSOLE=1`), the inbox band, the fleet pane, `/conductor` `/inbox` `/approve` `/revise` `/attach`, toasts, Remote Control pushes, and the one model wake-up for an escalation. What it shows and does is in the conductor README's *Mod* section (`apps/conductor/README.md`).
+
+Install it with the daemon's CLI, which ships this folder:
+
+```text
+conduct install-mod
+```
+
+| File | Holds |
+|---|---|
+| `hooks/register.tsx` | the hooks: session start, commands, the band, the pane, the event stream; only its top-level functions take `$` |
+| `hooks/model.ts` | the logic without the engine: parsing the daemon's answers, what the status line, band and pane show, what each event asks for |
+| `types/index.d.ts` | the `$.state` contract (`conductor.snapshot`, `confirming`, `expanded`) |
+| `tests/conductor.test.tsx` | `claude plugin test`: the hooks against the engine, the daemon faked beneath them |
+| `tests/model.spec.ts` | vitest (`pnpm -C apps/conductor test`, in CI): `model.ts` |

package/mod/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/mod/hooks/model.ts

@@ -0,0 +1,282 @@
+// The conductor mod's logic, with nothing of the engine in it: what the daemon's answers mean, what
+// the status line, band and pane show, and what each event asks the mod to do. register.tsx does
+// the engine's part (only its top-level functions may take `$`); vitest tests this file in CI
+// (apps/conductor/mod/tests/model.spec.ts).
+import type { ConductorInboxItem, ConductorSnapshot, ConductorWorker } from '../types';
+
+// A daemon API answer: its status and parsed JSON body.
+export type ApiAnswer = { body: unknown; status: number };
+
+// One line of `conduct events --follow`: an event of the log (with its id), or the stream's state.
+export type StreamLine = { data: Record<string, unknown>; id: number | null; kind: string; subject: string | null };
+
+// What an event asks of the mod. Only `escalate` wakes the console's model.
+export type Reaction =
+  | { kind: 'disconnected' }
+  | { kind: 'escalate'; text: string }
+  | { kind: 'ignore' }
+  | { kind: 'push'; message: string }
+  | { kind: 'refresh'; toast: string | null }
+  | { kind: 'send'; text: string; to: string };
+
+// A band entry and the act its press does.
+export type BandEntry = { act: 'approve' | 'copy' | 'pane'; hotkey: string; id: number; label: string; text: string };
+
+export type ProjectGroup = { project: string; rows: ConductorWorker[]; running: number };
+
+// A lookup by the item key, or an inbox id written #12; a message when it doesn't resolve to one.
+export type Found<T> = { error: string; found?: undefined } | { error?: undefined; found: T };
+
+const BAND_LIMIT = 5;
+
+// `conductor 3▶ 2⏸ ✉2`, or undefined (the line cleared) when no daemon answers.
+export function statusText(snapshot: ConductorSnapshot | null): string | undefined {
+  if (snapshot === null || snapshot.error !== null) return undefined;
+  const running = snapshot.workers.filter((w) => w.status === 'running').length;
+  const parked = snapshot.workers.filter((w) => w.status === 'parked').length;
+  return `conductor ${running}▶ ${parked}⏸ ✉${snapshot.inbox.length}`;
+}
+
+// The band's buttons: a plan approves (behind a confirm), an npm OTP copies its command, the rest
+// open the pane, where each item's commands and links are.
+export function bandEntries(inbox: readonly ConductorInboxItem[]): BandEntry[] {
+  return inbox.slice(0, BAND_LIMIT).map((item, i) => {
+    const key = item.item ?? `#${item.id}`;
+    const hotkey = String(i + 1);
+    if (item.kind === 'plan' && item.item !== null) return { act: 'approve', hotkey, id: item.id, label: `approve ${key}`, text: item.text };
+    const command = item.commands[0];
+    if (item.kind === 'npm-otp' && command !== undefined) return { act: 'copy', hotkey, id: item.id, label: `copy OTP line ${key}`, text: command };
+    return { act: 'pane', hotkey, id: item.id, label: `${item.kind} ${key}`, text: item.text };
+  });
+}
+
+// The fleet by project, running workers first within each, projects by name.
+export function projectGroups(workers: readonly ConductorWorker[]): ProjectGroup[] {
+  const byProject = new Map<string, ConductorWorker[]>();
+  for (const w of workers) byProject.set(w.project, [...(byProject.get(w.project) ?? []), w]);
+  return [...byProject.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([project, rows]) => ({
+      project,
+      rows: [...rows].sort((a, b) => Number(b.status === 'running') - Number(a.status === 'running') || a.name.localeCompare(b.name)),
+      running: rows.filter((w) => w.status === 'running').length,
+    }));
+}
+
+// A worker row's glyph: ▶ running, ⏸ parked, ✖ failed or stopped, · otherwise (launching, exited).
+export function glyph(status: string): string {
+  if (status === 'running') return '▶';
+  if (status === 'parked') return '⏸';
+  if (status === 'failed' || status === 'stopped-unexpectedly') return '✖';
+  return '·';
+}
+
+// What a worker waits on or does: its open wait, else the session's activity.
+export function workerDoing(w: ConductorWorker): string {
+  return w.waits[0] ?? w.activity;
+}
+
+// The open plan of `ref` (as `conduct approve` finds it): an item key, or an inbox id as #12.
+export function findPlan(inbox: readonly ConductorInboxItem[], ref: string): Found<ConductorInboxItem> {
+  const byId = /^#(\d+)$/.exec(ref.trim());
+  if (byId) {
+    const item = inbox.find((i) => i.id === Number(byId[1]));
+    return item ? { found: item } : { error: `no open inbox item ${ref}` };
+  }
+  if (/^\d+$/.test(ref.trim())) return { error: `"${ref}" is ambiguous: name the item, such as ATK-${ref.trim()}, or the inbox id as #${ref.trim()}` };
+  const plans = inbox.filter((i) => i.kind === 'plan' && i.item?.toUpperCase() === ref.trim().toUpperCase());
+  if (plans.length === 1 && plans[0]) return { found: plans[0] };
+  if (plans.length === 0) return { error: `no plan of ${ref} waits in the inbox` };
+  return { error: `several plans of ${ref} wait: name one as ${plans.map((p) => `#${p.id}`).join(' or ')}` };
+}
+
+// A worker in flight by name or item; a name match wins, as `conduct attach` finds it.
+export function findWorker(workers: readonly ConductorWorker[], ref: string): Found<ConductorWorker> {
+  const byName = workers.filter((w) => w.name === ref);
+  const matches = byName.length > 0 ? byName : workers.filter((w) => w.item.toUpperCase() === ref.toUpperCase());
+  if (matches.length === 1 && matches[0]) return { found: matches[0] };
+  if (matches.length === 0) return { error: `no worker "${ref}" in flight` };
+  return { error: `"${ref}" names several workers: ${matches.map((w) => `${w.name} in ${w.project}`).join(', ')}` };
+}
+
+// `/inbox`'s answer: one line per item, then its commands and links.
+export function inboxText(inbox: readonly ConductorInboxItem[], now: number): string {
+  if (inbox.length === 0) return 'The inbox is empty.';
+  return inbox
+    .flatMap((i) => [
+      `#${i.id}  ${i.kind}  ${i.item ?? ''}${i.project ? ` (${i.project})` : ''}  ${age(i.raisedAt, now)}`,
+      `    ${i.text}`,
+      ...i.commands.map((c) => `    $ ${c}`),
+      ...i.links.map((l) => `    ${l}`),
+    ])
+    .join('\n');
+}
+
+// "now", "12m", "3h", "2d".
+export function age(iso: string, now: number): string {
+  const minutes = Math.floor((now - Date.parse(iso)) / 60_000);
+  if (!(minutes >= 1)) return 'now';
+  if (minutes < 60) return `${minutes}m`;
+  if (minutes < 24 * 60) return `${Math.floor(minutes / 60)}h`;
+  return `${Math.floor(minutes / (24 * 60))}d`;
+}
+
+// 950, 42k, 6.1M.
+export function tokens(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${Math.round(n / 1000)}k`;
+  return `${(n / 1_000_000).toFixed(1)}M`;
+}
+
+export function spendToday(workers: readonly ConductorWorker[]): number {
+  return workers.reduce((sum, w) => sum + w.spendToday, 0);
+}
+
+// One line of the follow stream, or null for anything that isn't an event object.
+export function parseLine(line: string): null | StreamLine {
+  let value: unknown;
+  try {
+    value = JSON.parse(line);
+  } catch {
+    return null;
+  }
+  if (!isRecord(value) || typeof value.kind !== 'string') return null;
+  return {
+    data: isRecord(value.data) ? value.data : {},
+    id: typeof value.id === 'number' ? value.id : null,
+    kind: value.kind,
+    subject: typeof value.subject === 'string' ? value.subject : null,
+  };
+}
+
+// What an event asks of the mod. Remote Control pushes, escalations and worker messages are
+// contracts the daemon's notifier (ATK-313) and rules (ATK-315) emit; the mod only carries them out.
+export function reaction(line: StreamLine): Reaction {
+  const text = (key: string): null | string => {
+    const value = line.data[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : null;
+  };
+  switch (line.kind) {
+    case 'conduct.connected':
+      return { kind: 'refresh', toast: null };
+    case 'conduct.disconnected':
+      return { kind: 'disconnected' };
+    case 'console.escalated': {
+      const ask = text('text');
+      return ask === null ? { kind: 'ignore' } : { kind: 'escalate', text: `[conductor] escalation${line.subject ? ` on ${line.subject}` : ''}: ${ask}` };
+    }
+    case 'inbox.raised': {
+      const ask = text('text');
+      return { kind: 'refresh', toast: ask === null ? null : `conductor: ${line.subject ? `${line.subject} · ` : ''}${ask}` };
+    }
+    case 'notify.requested': {
+      const message = text('message');
+      return line.data.channel === 'remote-control' && message !== null ? { kind: 'push', message } : { kind: 'ignore' };
+    }
+    case 'watcher.stats':
+      return { kind: 'ignore' };
+    case 'worker.message-requested': {
+      const to = text('to');
+      const message = text('message');
+      return to === null || message === null ? { kind: 'ignore' } : { kind: 'send', text: message, to };
+    }
+    default:
+      return { kind: 'refresh', toast: null };
+  }
+}
+
+// GET /fleet's body, kept to the fields the mod draws; null when it isn't one.
+export function parseFleet(body: unknown): ConductorWorker[] | null {
+  if (!isRecord(body) || !Array.isArray(body.workers)) return null;
+  return body.workers.flatMap((w): ConductorWorker[] => {
+    if (!isRecord(w) || typeof w.id !== 'number' || typeof w.name !== 'string' || typeof w.status !== 'string') return [];
+    const spend = isRecord(w.spend) && typeof w.spend.today === 'number' ? w.spend.today : 0;
+    const waits = Array.isArray(w.waits)
+      ? w.waits.flatMap((x) => (isRecord(x) && typeof x.condition === 'string' && x.resolvedAt === null ? [x.condition] : []))
+      : [];
+    return [
+      {
+        activity: typeof w.activity === 'string' ? w.activity : w.status,
+        id: w.id,
+        item: typeof w.item === 'string' ? w.item : w.name,
+        name: w.name,
+        phase: typeof w.phase === 'string' ? w.phase : null,
+        project: typeof w.project === 'string' ? w.project : '?',
+        spendToday: spend,
+        status: w.status,
+        updatedAt: typeof w.updatedAt === 'string' ? w.updatedAt : '',
+        waits,
+      },
+    ];
+  });
+}
+
+// GET /inbox's body; null when it isn't one.
+export function parseInbox(body: unknown): ConductorInboxItem[] | null {
+  if (!isRecord(body) || !Array.isArray(body.items)) return null;
+  return body.items.flatMap((i): ConductorInboxItem[] => {
+    if (!isRecord(i) || typeof i.id !== 'number' || typeof i.kind !== 'string' || typeof i.text !== 'string') return [];
+    return [
+      {
+        commands: strings(i.commands),
+        id: i.id,
+        item: typeof i.item === 'string' ? i.item : null,
+        kind: i.kind,
+        links: strings(i.links),
+        project: typeof i.project === 'string' ? i.project : null,
+        raisedAt: typeof i.raisedAt === 'string' ? i.raisedAt : '',
+        text: i.text,
+      },
+    ];
+  });
+}
+
+// The error an API answer carries (`{ error, details }`), as one line.
+export function errorOf(answer: ApiAnswer): string {
+  const { body } = answer;
+  if (isRecord(body) && typeof body.error === 'string') return [body.error, ...strings(body.details)].join('; ');
+  return `the conductor answered ${answer.status}`;
+}
+
+// POST /inbox/:id/resolve's answer as the line to show, as `conduct approve|revise|done` says it.
+export function answerText(action: 'approve' | 'done' | 'revise', id: number, answer: ApiAnswer): string {
+  if (answer.status !== 200) return `not ${action === 'done' ? 'done' : `${action}d`}: ${errorOf(answer)}`;
+  const body = isRecord(answer.body) ? answer.body : {};
+  const key = isRecord(body.item) && typeof body.item.item === 'string' ? body.item.item : `#${id}`;
+  if (action === 'done') return `done: ${key}`;
+  const comment = isRecord(body.comment) ? body.comment : {};
+  const where = typeof comment.url === 'string' ? comment.url : typeof comment.id === 'string' ? comment.id : 'comment posted';
+  return `${action === 'approve' ? 'approved' : 'asked for a revision of'} ${key}: ${where}`;
+}
+
+// The daemon's home as the CLI finds it (apps/conductor/src/paths.ts): CONDUCTOR_HOME, else
+// .conductor under USERPROFILE or HOME.
+export function homeOf(env: { conductorHome?: string; home?: string; userProfile?: string }): null | string {
+  if (env.conductorHome) return env.conductorHome;
+  const user = env.userProfile || env.home;
+  return user ? `${user.replace(/[\\/]+$/, '')}/.conductor` : null;
+}
+
+// The port and token files' text as an endpoint; null unless both are whole.
+export function endpointOf(portText: string, tokenText: string): { port: number; token: string } | null {
+  const port = Number(portText.trim());
+  const token = tokenText.trim();
+  return Number.isInteger(port) && port > 0 && /^[0-9a-f]{64}$/.test(token) ? { port, token } : null;
+}
+
+// GET /fleet and GET /inbox as one snapshot; `error` set when the daemon didn't answer both.
+export function snapshotOf(fleet: ApiAnswer, inbox: ApiAnswer, readAt: number): ConductorSnapshot {
+  const workers = fleet.status === 200 ? parseFleet(fleet.body) : null;
+  if (workers === null) return { error: errorOf(fleet), inbox: [], readAt, workers: [] };
+  const items = inbox.status === 200 ? parseInbox(inbox.body) : null;
+  if (items === null) return { error: errorOf(inbox), inbox: [], readAt, workers: [] };
+  return { error: null, inbox: items, readAt, workers };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function strings(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((v): v is string => typeof v === 'string') : [];
+}