@etiquekit/etq 1.0.11 → 1.0.13

package/packages/control/src/cli/argv.ts

@@ -0,0 +1,155 @@
+import {
+  ACTION_CLASSES,
+  PROJECTION_POLICIES,
+  SUPERVISION_COMMANDS,
+  TURN_RESULTS,
+  ALLOWED_COMMAND_IDS,
+  type ActionClass,
+  type AllowedCommandId,
+  type ProjectionPolicy,
+  type SupervisionCommand,
+  type TurnResult,
+  type Surface,
+} from '../../../protocol/src/index';
+
+/**
+ * Argv parsing + per-flag coercion helpers. Extracted from the former
+ * monolithic `cli.ts`. No I/O, no side effects — pure string-shape checks.
+ */
+
+export interface ParsedArgv {
+  positionals: string[];
+  flags: Record<string, string | boolean>;
+}
+
+export function parseArgs(argv: string[]): ParsedArgv {
+  const positionals: string[] = [];
+  const flags: Record<string, string | boolean> = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (!next || next.startsWith('--')) {
+      flags[key] = true;
+      continue;
+    }
+    flags[key] = next;
+    i += 1;
+  }
+  return { positionals, flags };
+}
+
+export function parseSurfaces(
+  raw: string | boolean | undefined,
+  availableSurfaces: string[],
+): Surface[] {
+  if (!raw || raw === true) {
+    return [...availableSurfaces];
+  }
+  const values = String(raw).split(',').map((value) => value.trim()).filter(Boolean);
+  return values.map((value) => {
+    if (!availableSurfaces.includes(value)) {
+      throw new Error(`unknown surface: ${value}`);
+    }
+    return value;
+  });
+}
+
+export function parseList(raw: string | boolean | undefined): string[] {
+  if (!raw || raw === true) {
+    return [];
+  }
+  return String(raw).split(',').map((value) => value.trim()).filter(Boolean);
+}
+
+export function requireString(
+  flags: Record<string, string | boolean>,
+  key: string,
+): string {
+  const v = flags[key];
+  if (typeof v !== 'string' || v.length === 0) {
+    throw new Error(`--${key} is required`);
+  }
+  return v;
+}
+
+export function optionalString(
+  flags: Record<string, string | boolean>,
+  key: string,
+): string | undefined {
+  const v = flags[key];
+  return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+
+export function parseInt32(raw: string | boolean | undefined, key: string): number {
+  if (typeof raw !== 'string') {
+    throw new Error(`--${key} is required and must be an integer`);
+  }
+  const n = Number.parseInt(raw, 10);
+  if (!Number.isFinite(n)) {
+    throw new Error(`--${key} must be an integer (got ${raw})`);
+  }
+  return n;
+}
+
+export function parseAllowedCommands(
+  raw: string | boolean | undefined,
+  key: string,
+): AllowedCommandId[] {
+  const values = parseList(raw);
+  const bad = values.filter((v) => !(ALLOWED_COMMAND_IDS as readonly string[]).includes(v));
+  if (bad.length > 0) {
+    throw new Error(`--${key} contains unknown operation IDs: ${bad.join(', ')}`);
+  }
+  return values as AllowedCommandId[];
+}
+
+export function parseActionClass(
+  raw: string | boolean | undefined,
+  key: string,
+): ActionClass {
+  if (typeof raw !== 'string' || !(ACTION_CLASSES as readonly string[]).includes(raw)) {
+    throw new Error(`--${key} must be one of: ${ACTION_CLASSES.join(', ')}`);
+  }
+  return raw as ActionClass;
+}
+
+export function parseProjectionPolicy(
+  raw: string | boolean | undefined,
+): ProjectionPolicy {
+  if (raw === undefined || raw === true) return 'on_state_change';
+  if (!(PROJECTION_POLICIES as readonly string[]).includes(raw as string)) {
+    throw new Error(`--projection-policy must be one of: ${PROJECTION_POLICIES.join(', ')}`);
+  }
+  return raw as ProjectionPolicy;
+}
+
+export function parseTurnResult(raw: string | boolean | undefined): TurnResult {
+  if (typeof raw !== 'string' || !(TURN_RESULTS as readonly string[]).includes(raw)) {
+    throw new Error(`--result must be one of: ${TURN_RESULTS.join(', ')}`);
+  }
+  return raw as TurnResult;
+}
+
+export function parseSupervisionCommandName(raw: string | undefined): SupervisionCommand {
+  if (!raw || !(SUPERVISION_COMMANDS as readonly string[]).includes(raw)) {
+    throw new Error(`<command> must be one of: ${SUPERVISION_COMMANDS.join(', ')}`);
+  }
+  return raw as SupervisionCommand;
+}
+
+export function requirePositional(
+  positionals: string[],
+  index: number,
+  name: string,
+): string {
+  const value = positionals[index];
+  if (!value) {
+    throw new Error(`<${name}> positional argument is required`);
+  }
+  return value;
+}

package/packages/control/src/cli/commands/console.ts

@@ -0,0 +1,200 @@
+import { resolve } from 'node:path';
+import { optionalString, parseInt32 } from '../argv';
+import { renderLocalBoard } from './local-workflow';
+import { buildConsoleReadModel, type ConsoleReadModel } from '../../parity/surfaces';
+
+const CONSOLE_VERBS = new Set(['snapshot', 'serve', 'board']);
+
+export function isConsoleCommand(command: string): boolean {
+  return command === 'console';
+}
+
+function parsePort(raw: string | boolean | undefined): number {
+  if (raw === undefined) return 4173;
+  const port = parseInt32(raw, 'port');
+  if (port < 1 || port > 65535) throw new Error('--port must be between 1 and 65535');
+  return port;
+}
+
+function renderSnapshot(model: ConsoleReadModel): string {
+  return [
+    'console_read_model:',
+    `  generated_at: ${model.generated_at}`,
+    `  ledger_entries: ${model.counts.ledger_entries}`,
+    `  receipts: ${model.counts.receipts}`,
+    `  tasks: ${model.counts.tasks}`,
+    `  outbox_items: ${model.counts.outbox_items}`,
+    `  provisioning_events: ${model.counts.provisioning_events}`,
+    `  owner_cards: ${model.counts.owner_cards}`,
+    `  harness_inventory_items: ${model.harness_maintenance.counts.inventory_items}`,
+    `  harness_pruning_receipts: ${model.harness_maintenance.counts.pruning_receipts}`,
+    `  harness_validation_errors: ${model.harness_maintenance.counts.validation_errors}`,
+    `  read_only: ${String(model.authority_boundary.read_only)}`,
+  ].join('\n');
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+function html(model: ConsoleReadModel): string {
+  const seat = model.seat_readiness?.seat ? String(model.seat_readiness.seat) : 'none';
+  const ledger = model.recent_ledger.length > 0
+    ? model.recent_ledger.map((line) => `<li>${escapeHtml(line.replace(/^- /, ''))}</li>`).join('')
+    : '<li>No ledger entries found.</li>';
+  const provisioning = model.provisioning_events.length > 0
+    ? model.provisioning_events.map((event) => (
+      `<li><strong>${escapeHtml(event.target.cluster_name)}</strong> ${escapeHtml(event.event_kind)}`
+      + ` — <code>${escapeHtml(event.plan_ref)}</code></li>`
+    )).join('')
+    : '<li>No provisioning events found.</li>';
+  const ownerCards = model.owner_cards.cards.length > 0
+    ? model.owner_cards.cards.map((card) => (
+      `<li><strong>${escapeHtml(card.seat_id)}</strong> owned by <code>${escapeHtml(card.accountability.owner_principal)}</code>`
+      + ` — ${escapeHtml(card.job)}`
+      + ` — review stale: ${escapeHtml(String(card.review.is_stale))}`
+      + ` — warnings: ${escapeHtml(card.warnings.join(', ') || 'none')}</li>`
+    )).join('')
+    : '<li>No owner cards found.</li>';
+  const ownerCardErrors = model.owner_cards.validation_errors.length > 0
+    ? model.owner_cards.validation_errors.map((entry) => (
+      `<li><code>${escapeHtml(entry.ref)}</code> — ${escapeHtml(entry.reason)}</li>`
+    )).join('')
+    : '<li>No owner card validation errors found.</li>';
+  const harnessReceipts = model.harness_maintenance.pruning_receipts.length > 0
+    ? model.harness_maintenance.pruning_receipts.map((receipt) => (
+      `<li><strong>${escapeHtml(receipt.object_id)}</strong> ${escapeHtml(receipt.proposed_disposition)}`
+      + ` — canary ${escapeHtml(receipt.canary_verdict)}`
+      + ` — <code>${escapeHtml(receipt.receipt_ref)}</code></li>`
+    )).join('')
+    : '<li>No harness pruning receipts found.</li>';
+  const harnessErrors = model.harness_maintenance.validation_errors.length > 0
+    ? model.harness_maintenance.validation_errors.map((entry) => (
+      `<li><code>${escapeHtml(entry.ref)}</code> — ${escapeHtml(entry.reason)}</li>`
+    )).join('')
+    : '<li>No harness validation errors found.</li>';
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Etiquette Console</title>
+  <style>
+    body { margin: 0; font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; color: #1f2937; background: #f8fafc; }
+    main { max-width: 980px; margin: 0 auto; padding: 32px 20px 48px; }
+    h1 { font-size: 30px; margin: 0 0 8px; letter-spacing: 0; }
+    .subtle { color: #64748b; margin: 0 0 24px; }
+    .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; margin: 18px 0 28px; }
+    .metric { border: 1px solid #dbe3ef; border-radius: 8px; padding: 14px; background: #fff; }
+    .metric span { display: block; font-size: 13px; color: #64748b; }
+    .metric strong { display: block; font-size: 28px; margin-top: 4px; }
+    section { margin-top: 28px; }
+    code { background: #e2e8f0; padding: 2px 5px; border-radius: 4px; }
+    ul { padding-left: 20px; }
+    .boundary { border-left: 4px solid #2563eb; padding: 10px 14px; background: #eff6ff; }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>Etiquette Console</h1>
+    <p class="subtle">Read-only workspace view generated ${escapeHtml(model.generated_at)}.</p>
+    <div class="grid">
+      <div class="metric"><span>Ledger entries</span><strong>${model.counts.ledger_entries}</strong></div>
+      <div class="metric"><span>Receipts</span><strong>${model.counts.receipts}</strong></div>
+      <div class="metric"><span>Tasks</span><strong>${model.counts.tasks}</strong></div>
+      <div class="metric"><span>Outbox items</span><strong>${model.counts.outbox_items}</strong></div>
+      <div class="metric"><span>Provisioning events</span><strong>${model.counts.provisioning_events}</strong></div>
+      <div class="metric"><span>Owner cards</span><strong>${model.counts.owner_cards}</strong></div>
+      <div class="metric"><span>Harness inventory</span><strong>${model.harness_maintenance.counts.inventory_items}</strong></div>
+      <div class="metric"><span>Pruning receipts</span><strong>${model.harness_maintenance.counts.pruning_receipts}</strong></div>
+      <div class="metric"><span>Harness errors</span><strong>${model.harness_maintenance.counts.validation_errors}</strong></div>
+    </div>
+    <section class="boundary">
+      <strong>Authority boundary:</strong> this console cannot emit events, attach grants, merge, or close work.
+    </section>
+    <section>
+      <h2>Seat readiness</h2>
+      <p>Current seat: <code>${escapeHtml(seat)}</code></p>
+    </section>
+    <section>
+      <h2>Seat ownership</h2>
+      <ul>${ownerCards}</ul>
+      <h3>Validation</h3>
+      <ul>${ownerCardErrors}</ul>
+    </section>
+    <section>
+      <h2>Recent ledger</h2>
+      <ul>${ledger}</ul>
+    </section>
+    <section>
+      <h2>Provisioning</h2>
+      <ul>${provisioning}</ul>
+    </section>
+    <section>
+      <h2>Harness maintenance</h2>
+      <p>Keep ${model.harness_maintenance.counts.keep}; consolidate ${model.harness_maintenance.counts.consolidate}; quarantine ${model.harness_maintenance.counts.quarantine}; blocked ${model.harness_maintenance.counts.blocked}; delete-ready ${model.harness_maintenance.counts['delete-ready']}.</p>
+      <h3>Pruning receipts</h3>
+      <ul>${harnessReceipts}</ul>
+      <h3>Validation</h3>
+      <ul>${harnessErrors}</ul>
+    </section>
+  </main>
+</body>
+</html>`;
+}
+
+async function runServer(projectRoot: string, host: string, port: number): Promise<never> {
+  const server = Bun.serve({
+    hostname: host,
+    port,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method !== 'GET') {
+        return Response.json({ error: 'method_not_allowed' }, { status: 405 });
+      }
+      if (url.pathname === '/api/read-model') {
+        return Response.json(await buildConsoleReadModel(projectRoot));
+      }
+      if (url.pathname !== '/' && url.pathname !== '/index.html') {
+        return Response.json({ error: 'not_found' }, { status: 404 });
+      }
+      const model = await buildConsoleReadModel(projectRoot);
+      return new Response(html(model), {
+        headers: { 'content-type': 'text/html; charset=utf-8' },
+      });
+    },
+  });
+  console.log(`etiquette console listening on http://${server.hostname}:${server.port}/`);
+  console.log('boundary: read-only GET surface; no grants, events, merge, or close');
+  return new Promise<never>(() => {
+    // Keep the CLI process alive for the HTTP console.
+  });
+}
+
+export async function dispatchConsole(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !CONSOLE_VERBS.has(verb)) {
+    throw new Error(`console verb must be one of: ${[...CONSOLE_VERBS].join(', ')}`);
+  }
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+
+  if (verb === 'snapshot') {
+    const model = await buildConsoleReadModel(projectRoot, optionalString(flags, 'at'));
+    console.log(flags.json ? JSON.stringify(model, null, 2) : renderSnapshot(model));
+    return;
+  }
+
+  if (verb === 'board') {
+    console.log(await renderLocalBoard(projectRoot, optionalString(flags, 'seat')));
+    return;
+  }
+
+  await runServer(projectRoot, optionalString(flags, 'host') ?? '127.0.0.1', parsePort(flags.port));
+}

package/packages/control/src/cli/commands/dispatch-core.ts

@@ -0,0 +1,89 @@
+import { resolve } from 'node:path';
+import { optionalString, requireString } from '../argv';
+import { evaluateOperationalDispatch } from '../../dispatch/decision';
+import { recordOperationalDispatch } from '../../dispatch/record';
+import { loadSandboxReceipt } from '../../rubric/loader';
+import { evaluateSeatReadiness, readSeatReadiness } from '../../seat/readiness';
+import { evaluateWorkflowCheck } from '../../workflow/evaluator';
+import { loadWorkflowEnvelope, loadWorkflowMode } from '../../workflow/loader';
+
+const CORE_DISPATCH_VERBS = new Set(['check', 'record']);
+
+export function isCoreDispatchCommand(command: string): boolean {
+  return command === 'dispatch';
+}
+
+function renderDecision(result: ReturnType<typeof evaluateOperationalDispatch>): string {
+  return [
+    'operational_dispatch_decision:',
+    `  task_ref: ${result.task_ref}`,
+    `  seat: ${result.seat}`,
+    `  decision: ${result.decision}`,
+    `  reasons: ${result.reasons.join(', ') || 'none'}`,
+    `  warnings: ${result.warnings.join(', ') || 'none'}`,
+    `  profile_hint: ${result.profile_hint ?? 'none'}`,
+    `  seat_routing: ${result.inputs.seat_readiness.routing_recommendation}`,
+    `  workflow_recommendation: ${result.inputs.workflow_check.recommendation}`,
+    `  rubric_receipt_accepted: ${String(result.inputs.rubric_receipt.accepted)}`,
+    `  can_dispatch: ${String(result.authority_boundary.can_dispatch)}`,
+    `  can_authorize: ${String(result.authority_boundary.can_authorize)}`,
+    `  consumer_is_engine: ${String(result.authority_boundary.consumer_is_engine)}`,
+  ].join('\n');
+}
+
+function renderRecord(result: Awaited<ReturnType<typeof recordOperationalDispatch>>): string {
+  return [
+    'operational_dispatch_record:',
+    `  record_id: ${result.record.record_id}`,
+    `  task_ref: ${result.record.task_ref}`,
+    `  seat: ${result.record.seat}`,
+    `  decision: ${result.record.decision}`,
+    `  reasons: ${result.record.reasons.join(', ') || 'none'}`,
+    `  warnings: ${result.record.warnings.join(', ') || 'none'}`,
+    `  receipt_ref: ${result.record.receipt_ref}`,
+    `  ledger_ref: ${result.record.ledger_ref}`,
+    `  can_execute: ${String(result.record.authority_boundary.can_execute)}`,
+  ].join('\n');
+}
+
+export async function dispatchCoreDispatch(
+  positionals: string[],
+  flags: Record<string, string | boolean>,
+): Promise<void> {
+  const verb = positionals[1];
+  if (!verb || !CORE_DISPATCH_VERBS.has(verb)) {
+    throw new Error(`core dispatch verb must be one of: ${[...CORE_DISPATCH_VERBS].join(', ')}`);
+  }
+
+  const json = Boolean(flags.json);
+  const projectRoot = resolve(optionalString(flags, 'project') ?? process.cwd());
+  const mode = await loadWorkflowMode(resolve(requireString(flags, 'mode')));
+  const envelope = await loadWorkflowEnvelope(resolve(requireString(flags, 'task')));
+  const readiness = evaluateSeatReadiness(
+    await readSeatReadiness(projectRoot, optionalString(flags, 'state')),
+    optionalString(flags, 'at'),
+  );
+  const receiptPath = optionalString(flags, 'sandbox-receipt');
+  const sandboxReceipt = receiptPath ? await loadSandboxReceipt(resolve(receiptPath)) : null;
+  const result = evaluateOperationalDispatch({
+    seat: readiness,
+    mode,
+    envelope,
+    workflow: evaluateWorkflowCheck(mode, envelope),
+    sandboxReceipt,
+    requestedStrategy: optionalString(flags, 'strategy'),
+  });
+
+  if (verb === 'record') {
+    const recorded = await recordOperationalDispatch({
+      projectRoot,
+      decision: result,
+      recordedBy: optionalString(flags, 'recorded-by'),
+      at: optionalString(flags, 'at'),
+    });
+    console.log(json ? JSON.stringify(recorded.record, null, 2) : renderRecord(recorded));
+    return;
+  }
+
+  console.log(json ? JSON.stringify(result, null, 2) : renderDecision(result));
+}