@dashclaw/cli 0.2.0 → 0.3.1

package/lib/codex/notify.js

@@ -0,0 +1,203 @@
+// cli/lib/codex/notify.js
+//
+// `dashclaw codex notify` — Codex legacy `notify` config target.
+//
+// Codex CLI supports a `notify` config that runs an external command after
+// each agent turn completes. Codex appends a JSON payload as the FINAL argv
+// argument:
+//
+//   notify = ["node", "/path/to/dashclaw.js", "codex", "notify"]
+//
+// then on each turn-complete, Codex spawns:
+//
+//   node /path/to/dashclaw.js codex notify '{"type":"agent-turn-complete", ...}'
+//
+// This module:
+//   1. Extracts the JSON payload from the last argv arg.
+//   2. Validates it's an `agent-turn-complete` event.
+//   3. POSTs a record to /api/actions/by-tool-use-id (the same endpoint the
+//      PostToolUse Python hook uses for its terminal patch) with an action
+//      shape that represents the turn as a single observable unit.
+//
+// Failure mode: Codex spawns notify fire-and-forget with stdio nulled. We
+// MUST exit 0 on any failure so we don't surface error output to the user.
+// All errors are logged to stderr and swallowed by the spawn.
+
+import { request } from 'node:http';
+import { request as requestHttps } from 'node:https';
+
+const TURN_COMPLETE_TYPE = 'agent-turn-complete';
+
+/**
+ * Parse the Codex notify payload from argv. Codex appends the JSON as the
+ * final argv slot. We accept either:
+ *  - argv last arg is a JSON string → parse it
+ *  - argv last arg is empty + stdin has JSON → read stdin
+ *
+ * Returns the parsed object, or null if no valid payload was found.
+ */
+export function parseNotifyPayload(argv) {
+  if (!Array.isArray(argv) || argv.length === 0) return null;
+  const last = argv[argv.length - 1];
+  if (typeof last !== 'string' || last.length === 0) return null;
+  if (last[0] !== '{') return null;
+  try {
+    return JSON.parse(last);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Map a Codex turn-complete payload to a DashClaw action_record shape.
+ * We declare the turn as a single coarse action so it shows up in the
+ * decision ledger. Token/cost data is not in the notify payload — it will
+ * be back-filled by the Phase 3 JSONL ingest path.
+ */
+export function buildActionFromNotify(payload, { agentId = 'codex' } = {}) {
+  const lastMessage = payload.last_assistant_message || '';
+  const summary = lastMessage.length > 200
+    ? lastMessage.slice(0, 197) + '...'
+    : lastMessage;
+
+  return {
+    agent_id: agentId,
+    action_type: 'agent_turn',
+    declared_goal: `Codex turn ${payload.turn_id || '?'} (${payload.thread_id || 'thread'})`,
+    outcome: 'success',
+    metadata: {
+      source: 'codex-notify',
+      thread_id: payload.thread_id,
+      turn_id: payload.turn_id,
+      cwd: payload.cwd,
+      client: payload.client || 'codex',
+      input_message_count: Array.isArray(payload.input_messages)
+        ? payload.input_messages.length
+        : 0,
+      last_assistant_summary: summary,
+    },
+  };
+}
+
+/**
+ * Send an action record to DashClaw. Returns:
+ *  - { status: 'sent', actionId }   on 2xx
+ *  - { status: 'skipped', reason }  on local-validation skip
+ *  - { status: 'error', reason }    on network/4xx/5xx
+ *
+ * Never throws. All errors are returned in the result object so the caller
+ * can decide whether to swallow them.
+ */
+export async function postNotifyAction({ baseUrl, apiKey, action, timeoutMs = 5000 }) {
+  if (!baseUrl || !apiKey) {
+    return { status: 'skipped', reason: 'missing_config' };
+  }
+
+  let url;
+  try {
+    url = new URL('/api/actions', baseUrl);
+  } catch (err) {
+    return { status: 'error', reason: 'invalid_base_url', detail: err.message };
+  }
+
+  const body = JSON.stringify(action);
+  const headers = {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body).toString(),
+    'x-api-key': apiKey,
+  };
+
+  return new Promise((resolve) => {
+    const lib = url.protocol === 'https:' ? requestHttps : request;
+    const req = lib(
+      {
+        method: 'POST',
+        host: url.hostname,
+        port: url.port || (url.protocol === 'https:' ? 443 : 80),
+        path: url.pathname + url.search,
+        headers,
+      },
+      (res) => {
+        let chunks = '';
+        res.setEncoding('utf8');
+        res.on('data', (c) => { chunks += c; });
+        res.on('end', () => {
+          if (res.statusCode >= 200 && res.statusCode < 300) {
+            let parsed = null;
+            try { parsed = JSON.parse(chunks); } catch { /* keep null */ }
+            resolve({
+              status: 'sent',
+              actionId: parsed?.action_id || parsed?.id || null,
+            });
+          } else {
+            resolve({
+              status: 'error',
+              reason: `http_${res.statusCode}`,
+              detail: chunks.slice(0, 200),
+            });
+          }
+        });
+      },
+    );
+
+    req.on('error', (err) => {
+      resolve({ status: 'error', reason: 'network', detail: err.message });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy();
+      resolve({ status: 'error', reason: 'timeout' });
+    });
+
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Run the notify command. This is the CLI entrypoint.
+ *
+ * IMPORTANT: must always exit 0 (the caller calls process.exit(0)).
+ * Codex spawns notify with stdio nulled and treats any failure as silent.
+ * We log to stderr (which Codex discards by design) for diagnostics.
+ *
+ * Options:
+ *   argv      — argv array (defaults to process.argv.slice(2))
+ *   baseUrl   — DashClaw instance URL
+ *   apiKey    — DashClaw API key
+ *   agentId   — agent identity (default: codex)
+ *   logger    — { warn, info } for diagnostic output
+ *   skipPost  — if true, do everything except the HTTP call (testing)
+ */
+export async function runCodexNotify({
+  argv = process.argv.slice(2),
+  baseUrl,
+  apiKey,
+  agentId = 'codex',
+  logger = console,
+  skipPost = false,
+} = {}) {
+  const payload = parseNotifyPayload(argv);
+  if (!payload) {
+    logger.warn('codex-notify: no JSON payload in argv, exiting 0');
+    return { status: 'skipped', reason: 'no_payload' };
+  }
+  if (payload.type !== TURN_COMPLETE_TYPE) {
+    logger.warn(`codex-notify: unknown payload type "${payload.type}", exiting 0`);
+    return { status: 'skipped', reason: 'unknown_type', type: payload.type };
+  }
+
+  const action = buildActionFromNotify(payload, { agentId });
+
+  if (skipPost) {
+    return { status: 'dry_run', action };
+  }
+
+  const result = await postNotifyAction({ baseUrl, apiKey, action });
+  if (result.status === 'sent') {
+    logger.info?.(`codex-notify: recorded action ${result.actionId || '(unknown id)'}`);
+  } else if (result.status === 'error') {
+    logger.warn(`codex-notify: ${result.reason}${result.detail ? ' — ' + result.detail : ''}`);
+  }
+  return result;
+}

package/lib/config.js

@@ -0,0 +1,160 @@
+// cli/lib/config.js
+// Config resolution: env vars -> ~/.dashclaw/config.json -> interactive prompt.
+import readline from 'node:readline';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, unlinkSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { bold, dim, green, red, yellow } from './render.js';
+
+const CONFIG_DIR = resolve(homedir(), '.dashclaw');
+const CONFIG_PATH = resolve(CONFIG_DIR, 'config.json');
+
+export function configPath() {
+  return CONFIG_PATH;
+}
+
+export function readConfigFile() {
+  if (!existsSync(CONFIG_PATH)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function writeConfigFile(config) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+
+export function clearConfigFile() {
+  if (existsSync(CONFIG_PATH)) {
+    unlinkSync(CONFIG_PATH);
+    return true;
+  }
+  return false;
+}
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((res) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      res(answer.trim());
+    });
+  });
+}
+
+function askSecret(question) {
+  return new Promise((res) => {
+    const stdin = process.stdin;
+    process.stdout.write(question);
+    const wasRaw = stdin.isRaw;
+    if (stdin.setRawMode) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    let input = '';
+    const onData = (char) => {
+      const str = String(char);
+      for (const c of str) {
+        if (c === '\n' || c === '\r' || c === '\u0004') {
+          if (stdin.setRawMode) stdin.setRawMode(wasRaw);
+          stdin.pause();
+          stdin.removeListener('data', onData);
+          process.stdout.write('\n');
+          res(input.trim());
+          return;
+        }
+        if (c === '\u0003') {
+          if (stdin.setRawMode) stdin.setRawMode(wasRaw);
+          stdin.pause();
+          process.stdout.write('\n');
+          process.exit(130);
+        }
+        if (c === '\u007f' || c === '\b') {
+          if (input.length > 0) {
+            input = input.slice(0, -1);
+            process.stdout.write('\b \b');
+          }
+        } else if (c >= ' ') {
+          input += c;
+          process.stdout.write('*');
+        }
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+/**
+ * Resolve config from env, then file, then interactive prompt.
+ * @returns {Promise<{ baseUrl, apiKey, agentId, source } | null>}
+ *   Returns null if missing and stdin is not a TTY (so caller can error out).
+ */
+export async function resolveConfig({ env = process.env, interactive = true } = {}) {
+  let baseUrl = env.DASHCLAW_BASE_URL;
+  let apiKey = env.DASHCLAW_API_KEY;
+  let agentId = env.DASHCLAW_AGENT_ID;
+  let source = 'env';
+
+  if (!baseUrl || !apiKey) {
+    const file = readConfigFile();
+    if (!baseUrl && file.baseUrl) {
+      baseUrl = file.baseUrl;
+      source = 'file';
+    }
+    if (!apiKey && file.apiKey) {
+      apiKey = file.apiKey;
+      source = 'file';
+    }
+    if (!agentId && file.agentId) agentId = file.agentId;
+  }
+
+  if (baseUrl && apiKey) {
+    return { baseUrl, apiKey, agentId: agentId || 'cli-operator', source };
+  }
+
+  if (!interactive || !process.stdin.isTTY) {
+    return null;
+  }
+
+  console.log();
+  console.log(bold('DashClaw CLI — first-time setup'));
+  console.log(dim(`Saved values go to ${CONFIG_PATH} (mode 600). Env vars always override.`));
+  console.log();
+
+  if (!baseUrl) {
+    baseUrl = await ask('DashClaw instance URL (e.g. https://your-dashclaw.vercel.app): ');
+    if (!baseUrl) {
+      console.error(red('Aborted — baseUrl is required.'));
+      process.exit(1);
+    }
+    baseUrl = baseUrl.replace(/\/+$/, '');
+  }
+
+  if (!apiKey) {
+    apiKey = await askSecret('API key (oc_live_...): ');
+    if (!apiKey) {
+      console.error(red('Aborted — API key is required.'));
+      process.exit(1);
+    }
+  }
+
+  agentId = agentId || 'cli-operator';
+
+  const saveAnswer = await ask(`Save to ${CONFIG_PATH}? [Y/n] `);
+  if (saveAnswer.toLowerCase() !== 'n' && saveAnswer.toLowerCase() !== 'no') {
+    try {
+      writeConfigFile({ baseUrl, apiKey, agentId });
+      console.log(green(`  \u2192 Saved. Remove with: dashclaw logout`));
+    } catch (err) {
+      console.error(yellow(`  Warning: could not write config file: ${err.message}`));
+    }
+  } else {
+    console.log(dim('  Not saved. Values apply to this invocation only.'));
+  }
+  console.log();
+
+  return { baseUrl, apiKey, agentId, source: 'prompted' };
+}

package/lib/doctor.js

@@ -0,0 +1,209 @@
+// cli/lib/doctor.js
+import { bold, dim, green, yellow, red } from './render.js';
+
+// Brand orange (256-color ANSI). Used sparingly — header + key accents only.
+const BRAND = (s) => `\x1b[38;5;208m${s}\x1b[0m`;
+
+const ICONS = {
+  pass: green('\u2713'),
+  warn: yellow('\u26a0'),
+  fail: red('\u2717'),
+};
+
+const CATEGORY_LABELS = {
+  database: 'Database',
+  config: 'Configuration',
+  auth: 'Authentication',
+  deployment: 'Deployment',
+  sdk: 'SDK Connectivity',
+  governance: 'Governance',
+  shape: 'Shape (generated)',
+  drift: 'Drift',
+};
+
+const CATEGORY_ORDER = ['database', 'config', 'auth', 'deployment', 'sdk', 'governance', 'shape', 'drift'];
+
+// Next-step guidance by check ID, used when the check has no auto-fix.
+// Keep each line short and actionable.
+const GUIDANCE = {
+  db_connection: 'Check DATABASE_URL and that Postgres is reachable from your deployment.',
+  env_NEXTAUTH_URL: 'Set NEXTAUTH_URL to your deployment URL (e.g. https://your.vercel.app).',
+  env_CRON_SECRET: 'Set CRON_SECRET to protect /api/cron/* endpoints.',
+  auth_signin: 'Configure an OAuth provider (GitHub/Google) or set DASHCLAW_LOCAL_ADMIN_PASSWORD.',
+  deploy_nextauth_url: 'Set NEXTAUTH_URL to match your deployment domain.',
+  deploy_cors: 'Set ALLOWED_ORIGIN if your agents run from a different domain.',
+  sdk_reachable: 'Check DASHCLAW_BASE_URL and confirm your instance is deployed and awake.',
+  sdk_auth: 'API key rejected — verify DASHCLAW_API_KEY matches the key on your instance.',
+  gov_actions: 'Send your first governed action with claw.guard() via the SDK.',
+  gov_stale: "Agents haven't reported in 7 days — check your agent pairings.",
+};
+
+function hr(width = 72) {
+  return dim('\u2500'.repeat(width));
+}
+
+/**
+ * Return an actionable next-step string for a non-passing check, or null.
+ */
+function nextStepFor(check, { noFix }) {
+  if (!check || check.status === 'pass') return null;
+
+  // Auto-fixable check: direct the user to the fix.
+  if (check.fix?.type === 'auto') {
+    if (noFix) {
+      return `${check.fix.description}. Re-run without ${bold('--no-fix')} to apply.`;
+    }
+    // Fix was attempted (or will run in this invocation); describe what it does.
+    return check.fix.description + '.';
+  }
+
+  // Fall back to the guidance table for warn/fail without an auto-fix.
+  return GUIDANCE[check.id] || null;
+}
+
+/**
+ * Run doctor via the API and render results.
+ * @param {{ baseUrl: string, apiKey: string, json?: boolean, noFix?: boolean, category?: string }} options
+ */
+export async function runDoctor({ baseUrl, apiKey, json, noFix, category }) {
+  const base = baseUrl.replace(/\/+$/, '');
+  const headers = { 'Content-Type': 'application/json', 'x-api-key': apiKey };
+
+  let url = `${base}/api/doctor?include_fixes=true`;
+  if (category) url += `&category=${encodeURIComponent(category)}`;
+
+  let res;
+  try {
+    res = await fetch(url, { headers });
+  } catch (err) {
+    console.error(red(`\nError: Could not reach DashClaw at ${base}`));
+    console.error(dim(`  ${err.cause?.code || err.message}`));
+    console.error(dim(`  Check DASHCLAW_BASE_URL and confirm your instance is running.\n`));
+    process.exit(1);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    console.error(red(`\nError: API key rejected by ${base} (${res.status}).`));
+    console.error(dim(`  Check DASHCLAW_API_KEY matches the key on your instance.\n`));
+    process.exit(1);
+  }
+
+  if (!res.ok && res.status !== 503) {
+    const errText = await res.text().catch(() => '');
+    console.error(red(`Doctor check failed (${res.status}): ${errText}`));
+    process.exit(1);
+  }
+
+  const result = await res.json();
+
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(result.status === 'healthy' ? 0 : 1);
+  }
+
+  // --- Header ----------------------------------------------------------------
+  const hostLabel = base.replace(/^https?:\/\//, '');
+  console.log();
+  console.log(`  ${BRAND('[DashClaw]')} ${bold('Doctor')}   ${dim(hostLabel)}`);
+  console.log();
+
+  // --- Grouped checks --------------------------------------------------------
+  const grouped = {};
+  for (const check of result.checks) {
+    if (!grouped[check.category]) grouped[check.category] = [];
+    grouped[check.category].push(check);
+  }
+
+  for (const cat of CATEGORY_ORDER) {
+    const checks = grouped[cat];
+    if (!checks || checks.length === 0) continue;
+
+    console.log(`  ${bold(CATEGORY_LABELS[cat] || cat)}`);
+    for (const check of checks) {
+      const icon = ICONS[check.status] || '?';
+      const titleStyled = check.status === 'pass' ? check.title : bold(check.title);
+      console.log(`  ${icon} ${titleStyled}`);
+
+      if (check.status !== 'pass') {
+        console.log(`    ${dim(check.message)}`);
+        const tip = nextStepFor(check, { noFix });
+        if (tip) {
+          console.log(`    ${dim('\u2192')} ${tip}`);
+        }
+      }
+    }
+    console.log();
+  }
+
+  // --- Auto-fix (remote fixes only; local-only fixes blocked by API) --------
+  let fixCount = 0;
+  let latestRecheck = null;
+  if (!noFix) {
+    const fixable = result.checks.filter((c) => c.status === 'fail' && c.fix?.type === 'auto');
+    if (fixable.length > 0) {
+      console.log(`  ${bold('Applying auto-fixes...')}`);
+      for (const check of fixable) {
+        try {
+          const fixRes = await fetch(`${base}/api/doctor/fix`, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify({ action: check.fix.action }),
+          });
+          const fixResult = await fixRes.json();
+          if (fixResult.applied) {
+            console.log(`  ${green('\u2192')} Fixed: ${fixResult.description}`);
+            fixCount++;
+            if (fixResult.recheck) latestRecheck = fixResult.recheck;
+          } else {
+            console.log(`  ${dim('\u2192')} Skipped: ${fixResult.description}`);
+          }
+        } catch (err) {
+          console.log(`  ${red('\u2717')} Fix "${check.fix.action}" failed: ${err.cause?.code || err.message}`);
+        }
+      }
+      console.log();
+    }
+  }
+
+  // --- Summary ---------------------------------------------------------------
+  const reporting = latestRecheck || result;
+  const { pass, warn, fail } = reporting.summary;
+
+  console.log(hr());
+  console.log();
+
+  const segments = [
+    green(`${pass} passed`),
+    warn > 0 ? yellow(`${warn} warning${warn !== 1 ? 's' : ''}`) : dim('0 warnings'),
+    fail > 0 ? red(`${fail} failed`) : dim('0 failed'),
+  ];
+  console.log(`  ${segments.join('   ' + dim('\u00b7') + '   ')}`);
+  console.log();
+
+  // --- Contextual footer -----------------------------------------------------
+  const healthy = reporting.status === 'healthy';
+
+  if (fixCount > 0) {
+    console.log(`  ${green('\u2713')} ${fixCount} issue${fixCount !== 1 ? 's' : ''} auto-fixed this run.`);
+  }
+
+  if (noFix) {
+    const autoFixable = result.checks.filter(
+      (c) => c.status !== 'pass' && c.fix?.type === 'auto',
+    ).length;
+    if (autoFixable > 0) {
+      console.log(
+        `  ${BRAND('\u2192')} ${autoFixable} issue${autoFixable !== 1 ? 's' : ''} can be auto-fixed. Run: ${bold('dashclaw doctor')}`,
+      );
+    }
+  }
+
+  if (!healthy) {
+    console.log(`  ${dim('Docs:')} ${base}/setup`);
+  } else {
+    console.log(`  ${green('\u2713')} ${bold('All systems healthy')} — ${dim('ready to govern actions')}`);
+  }
+  console.log();
+
+  process.exit(healthy ? 0 : 1);
+}

package/lib/posture.js

@@ -0,0 +1,45 @@
+// cli/lib/posture.js
+//
+// Direct-API helpers for the `dashclaw posture` / `dashclaw next` commands.
+// Like the other CLI command groups, these call the live endpoints via
+// apiRequest (fetch + x-api-key) rather than the published SDK, so the CLI never
+// depends on a possibly-stale `dashclaw` package for newly-added routes.
+//
+// Resolve is DRAFT-ONLY: the CLI can create an inactive policy draft, snooze, or
+// accept risk — it can NEVER activate enforcement. An operator (or agent) can
+// prepare a fix; only a human activates it at /policies. Mirrors the API + MCP
+// ceiling so agents can never self-escalate their own governance.
+
+import { apiRequest } from './api.js';
+
+/** GET /api/posture — score + dimensions + findings + summary + trend. */
+export async function fetchPosture(config) {
+  return apiRequest(config, 'GET', '/api/posture');
+}
+
+/** GET /api/posture/findings — the prioritized queue (+ optional filters). */
+export async function fetchFindings(config, { status, dimension } = {}) {
+  return apiRequest(config, 'GET', '/api/posture/findings', { query: { status, dimension } });
+}
+
+/** The single top open finding (the `next` gap), or null when the queue is clear. */
+export async function fetchNext(config) {
+  const data = await fetchFindings(config);
+  return (data && Array.isArray(data.findings) && data.findings[0]) || null;
+}
+
+const RESOLVE_ACTIONS = new Set(['create_draft', 'snooze', 'accept_risk']);
+
+/**
+ * POST /api/posture/findings/<key>/resolve — DRAFT-ONLY actions.
+ * `create_draft` (default) inserts an inactive policy draft; snooze/accept_risk
+ * record state. None of these activate enforcement.
+ */
+export async function resolveFinding(config, key, action = 'create_draft', note) {
+  if (!RESOLVE_ACTIONS.has(action)) {
+    throw new Error(`Invalid resolve action "${action}". Draft-only: ${[...RESOLVE_ACTIONS].join(', ')}.`);
+  }
+  return apiRequest(config, 'POST', `/api/posture/findings/${encodeURIComponent(key)}/resolve`, {
+    body: { action, note },
+  });
+}

package/package.json

@@ -1,18 +1,21 @@
-{
-  "name": "@dashclaw/cli",
-  "version": "0.2.0",
-  "description": "DashClaw terminal approval client",
-  "type": "module",
-  "bin": {
-    "dashclaw": "./bin/dashclaw.js"
-  },
-  "files": ["bin/", "lib/"],
-  "engines": { "node": ">=18.0.0" },
-  "dependencies": {
-    "dashclaw": "^2.2.1"
-  },
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "@dashclaw/cli",
+  "version": "0.3.1",
+  "description": "DashClaw terminal client — approve agent actions and diagnose your instance",
+  "type": "module",
+  "bin": {
+    "dashclaw": "./bin/dashclaw.js"
+  },
+  "files": ["bin/", "lib/", "README.md"],
+  "engines": { "node": ">=18.0.0" },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
+  },
+  "dependencies": {
+    "dashclaw": "^2.2.1"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}