cawdev-cli 0.9.0

package/runner/sign-in.mjs

@@ -0,0 +1,210 @@
+// Signing in — R81, and the reason this file exists is what it does NOT do.
+//
+// There is no password field here. The CLI asks the platform for a code, opens
+// R55's sign-in page in a browser, and waits until a person approves it. A
+// password belongs on a page a browser has told you the origin of; typing one
+// into a full-screen ANSI app is asking somebody to trust a rendering.
+//
+// What comes back is a PERSON'S SESSION, and person-actions keep going over
+// HTTP with it. R52's split is untouched: the socket says what this machine is
+// doing, and anything that CHANGES something is you.
+
+import { spawn } from 'node:child_process';
+import { hostname, userInfo } from 'node:os';
+import { loadSession, saveSession } from './session-store.mjs';
+
+/**
+ * A cookie jar and the CSRF dance, in the smallest form that works.
+ *
+ * The API uses a session cookie plus a double-submit CSRF cookie, because it
+ * was built for a browser. A client that is not a browser has to do by hand
+ * what Angular's HttpClient does for free: read `XSRF-TOKEN` and echo it back
+ * as `X-XSRF-TOKEN`.
+ */
+export class Session {
+  constructor(url) {
+    this.url = String(url).replace(/\/+$/, '');
+    this.cookies = new Map();
+    this.email = null;
+  }
+
+  get signedIn() {
+    return this.email !== null;
+  }
+
+  #cookieHeader() {
+    return [...this.cookies].map(([name, value]) => `${name}=${value}`).join('; ');
+  }
+
+  #remember(response) {
+    // Node exposes repeated Set-Cookie headers through getSetCookie().
+    for (const cookie of response.headers.getSetCookie?.() ?? []) {
+      const [pair] = cookie.split(';');
+      const at = pair.indexOf('=');
+      if (at > 0) {
+        this.cookies.set(pair.slice(0, at).trim(), pair.slice(at + 1).trim());
+      }
+    }
+  }
+
+  async request(path, { method = 'GET', body } = {}) {
+    const response = await fetch(`${this.url}${path}`, {
+      method,
+      headers: {
+        ...(body ? { 'content-type': 'application/json' } : {}),
+        ...(this.cookies.size ? { cookie: this.#cookieHeader() } : {}),
+        // Sent on every write. The server checks it against the cookie; a
+        // missing one is a 403 that looks exactly like "wrong password".
+        ...(this.cookies.has('XSRF-TOKEN')
+          ? { 'x-xsrf-token': this.cookies.get('XSRF-TOKEN') }
+          : {}),
+      },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    this.#remember(response);
+    const text = await response.text();
+    if (!response.ok) {
+      const failure = new Error(messageIn(text) ?? `${method} ${path} failed: HTTP ${response.status}`);
+      failure.status = response.status;
+      throw failure;
+    }
+    return text ? JSON.parse(text) : null;
+  }
+
+  /** One open GET, purely to be handed the CSRF cookie before the first POST. */
+  async prime() {
+    await this.request('/api/health').catch(() => undefined);
+  }
+
+  /** Whether the stored cookies still mean anything. */
+  async resume() {
+    try {
+      const me = await this.request('/api/auth/me');
+      // `?? null`, because `signedIn` is `email !== null` and an answer with no
+      // email would set it to `undefined` — which passes that test. Nothing on
+      // the real API answers 200 without one; a proxy in front of it might, and
+      // R93's walk now takes its FIRST decision off this flag.
+      this.email = me?.email ?? null;
+      return this.email !== null;
+    } catch {
+      this.email = null;
+      return false;
+    }
+  }
+
+  async signOut() {
+    await this.request('/api/auth/logout', { method: 'POST' }).catch(() => undefined);
+    this.cookies.clear();
+    this.email = null;
+  }
+}
+
+function messageIn(text) {
+  try {
+    return JSON.parse(text).message ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The session stored for this instance, if there is one and it still works.
+ *
+ * A stored cookie that the platform no longer honours is not an error worth
+ * saying anything about — it is what an expired session looks like, and the
+ * answer is the same as having none.
+ */
+export async function storedSession(url) {
+  const session = new Session(url);
+  const stored = await loadSession(session.url);
+  if (!stored) {
+    return session;
+  }
+  session.cookies = stored.cookies;
+  await session.resume();
+  return session;
+}
+
+/**
+ * How this machine describes itself on the approval page.
+ *
+ * Display text, and the page treats it as such. It is here so the person
+ * approving has something to compare against the terminal in front of them.
+ */
+export function describeThisMachine() {
+  try {
+    return `${userInfo().username}@${hostname()}`;
+  } catch {
+    return hostname();
+  }
+}
+
+/**
+ * Sign in through the browser, and remember it.
+ *
+ * @param session the jar to fill
+ * @param say where to print the code and the URL — the caller owns the screen
+ * @param open false to print the URL without launching anything
+ */
+export async function signInThroughBrowser(session, say, { open = true } = {}) {
+  await session.prime();
+  const started = await session.request('/api/auth/cli/start', {
+    method: 'POST',
+    body: { client: describeThisMachine() },
+  });
+
+  const url = `${session.url}${started.verifyPath}`;
+  say({ kind: 'opening', url, code: started.code });
+  if (open) {
+    openInBrowser(url);
+  }
+
+  const deadline = new Date(started.expiresAt).getTime();
+  while (Date.now() < deadline) {
+    await new Promise((done) => setTimeout(done, 1500));
+    let answer;
+    try {
+      answer = await session.request('/api/auth/cli/collect', {
+        method: 'POST',
+        body: { code: started.code, secret: started.secret },
+      });
+    } catch (failure) {
+      // A 404 is the grant having expired or been collected already; anything
+      // else is the platform having a moment and is worth another poll.
+      if (failure.status === 404) break;
+      continue;
+    }
+    if (answer.status === 'APPROVED') {
+      session.email = answer.user.email;
+      await saveSession(session.url, { email: session.email, cookies: session.cookies });
+      return { signedIn: true, email: session.email };
+    }
+    if (answer.status === 'REFUSED') {
+      return { signedIn: false, refused: true };
+    }
+  }
+  return { signedIn: false, expired: true };
+}
+
+/**
+ * Hand the URL to whatever the desktop uses.
+ *
+ * Detached and silenced, because the browser's own stderr has no business in
+ * the middle of a transcript. A failure here is not fatal and is not even
+ * reported: the URL has already been printed, and "open failed" on a machine
+ * with no desktop is noise about something that was never going to work.
+ */
+export function openInBrowser(url) {
+  const [command, args] = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  try {
+    const child = spawn(command, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => undefined);
+    child.unref();
+  } catch {
+    // Printed already.
+  }
+}

package/runner/stub-agent.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+// A stand-in for `claude`, for exercising the runner without spending anybody's
+// Claude usage.
+//
+// Point the runner at it with an ABSOLUTE path and no args:
+//
+//   { "agentCommand": "/…/tools/runner/stub-agent.mjs", "agentArgs": [] }
+//
+// Not `node` with the script as an argument: the runner puts `--mcp-config`
+// first (see runner.mjs), so node would be handed a flag it does not know and
+// exit with "bad option". The shebang runs it instead, and the cawdev flags
+// land in its argv where it ignores them — which is exactly what `claude` does
+// with the ones it does not need either.
+//
+// Absolute, because the child's cwd is the working copy, not this repository.
+//
+// It behaves like the real thing in the ways that matter to the runner: it is
+// spawned in the working copy with CAWDEV_TOKEN in its environment, it talks to
+// the platform through the same MCP tools, and — since the stage walk hung on
+// exactly this — it does NOT exit when its turn ends. What it does *not* do is
+// think: it follows a fixed script, which is exactly what a test wants.
+//
+// That last point used to read "and it exits", and the claim was the problem.
+// The real CLI is spawned with `--input-format stream-json` and its stdin held
+// open (R22), so when a turn finishes it sits there waiting for the next one
+// and leaves only when its input closes. A stub that called process.exit()
+// instead modelled away the single fact the daemon's stage walk depends on, and
+// a walk that waited for a process which was never going to leave looked
+// perfectly healthy against it. So: say the turn is over, then wait to be
+// dismissed. CAWDEV_STUB_EXIT=1 restores the old, less honest behaviour for
+// anything that genuinely wants a one-shot process.
+//
+// The script is chosen by CAWDEV_STUB_SCRIPT:
+//   report-and-finish  (default) progress, then done
+//   ask-then-finish              ask a question, wait for the answer, then done
+//   permission-then-finish       ask permission for a command, wait, then done
+//   crash                        exit non-zero without reporting
+//   hang                         never say anything, for testing cancellation
+//   usage-limit                  say the window is closed, end the turn with
+//                                SUCCESS, and then LINGER — which is what the
+//                                real CLI did, and the reason a limited run sat
+//                                RUNNING for forty-three minutes holding the
+//                                machine's only slot
+//
+// It announces a session id on `init`, like the real CLI, so R69's resume path
+// has something to record and hand back.
+
+const url = (process.env.CAWDEV_URL ?? 'http://localhost:4200').replace(/\/+$/, '');
+const token = process.env.CAWDEV_TOKEN;
+const project = process.env.CAWDEV_PROJECT;
+const script = process.env.CAWDEV_STUB_SCRIPT ?? 'report-and-finish';
+
+// The real CLI leaves when its input closes, and not before. Modelling that is
+// the whole reason this file is not three lines shorter.
+function leave(code = 0) {
+  if (code !== 0 || process.env.CAWDEV_STUB_EXIT) {
+    process.exit(code);
+  }
+  process.stdin.on('end', () => process.exit(0));
+  process.stdin.on('close', () => process.exit(0));
+  process.stdin.resume();
+}
+
+function say(text) {
+  // The real CLI emits stream-json; the runner only reads `result` events, so
+  // this is enough to look like one.
+  process.stdout.write(`${JSON.stringify({ type: 'result', result: text })}\n`);
+}
+
+// R69. The real CLI announces its session id on `init`, and that is the handle
+// `--resume` takes — so the stub announces one too, or the whole resume path is
+// untested by anything that runs against the stub.
+//
+// A resumed stub keeps the id it was resumed with. The real CLI is free to hand
+// back a different one, which the runner reports either way; keeping it here
+// makes the stub's own script readable, and the runner's "always report the
+// latest" rule is exercised by the platform's tests rather than guessed at.
+const resumed = process.argv[process.argv.indexOf('--resume') + 1];
+const sessionId =
+  process.argv.includes('--resume') && resumed ? resumed : `stub-${Date.now().toString(36)}`;
+process.stdout.write(
+  `${JSON.stringify({
+    type: 'system',
+    subtype: 'init',
+    session_id: sessionId,
+    model: 'stub',
+    cwd: process.cwd(),
+  })}\n`,
+);
+
+async function api(path, { method = 'GET', body } = {}) {
+  const response = await fetch(`${url}${path}`, {
+    method,
+    headers: {
+      authorization: `Bearer ${token}`,
+      ...(body ? { 'content-type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await response.text();
+  if (!response.ok) {
+    throw new Error(`${method} ${path} -> ${response.status}: ${text}`);
+  }
+  return text ? JSON.parse(text) : null;
+}
+
+const identity = await api('/api/agent/whoami');
+const runId = identity.runId;
+if (!runId) {
+  console.error('stub-agent: no run on this token');
+  process.exit(2);
+}
+
+const report = (kind, body) =>
+  api(`/api/projects/${project}/runs/${runId}/messages`, {
+    method: 'POST',
+    body: { kind, body },
+  });
+
+if (script === 'crash') {
+  say('about to crash');
+  process.exit(3);
+}
+
+if (script === 'hang') {
+  say('hanging around');
+  // Long enough for a cancellation test, and harmless if one never comes.
+  setTimeout(() => process.exit(0), 10 * 60 * 1000);
+} else if (script === 'usage-limit') {
+  // The exact sentence, middle dot and all, because that is what made the
+  // matcher's earlier patterns miss it. And then it STAYS — no exit, no error
+  // code, nothing for a close handler to read. A stub that exited here would
+  // model away the one fact that made this a forty-three minute hang rather
+  // than a run that ended badly.
+  say("You've hit your session limit · resets 4am (Africa/Tunis)");
+  setTimeout(() => process.exit(0), 10 * 60 * 1000);
+} else {
+  await report('PROGRESS', `Stub agent, script "${script}", in ${process.cwd()}.`);
+
+  if (script === 'ask-then-finish') {
+    const question = await api(`/api/projects/${project}/runs/${runId}/questions`, {
+      method: 'POST',
+      body: { question: 'Stub agent asking: shall I carry on?', options: ['Yes', 'No'] },
+    });
+
+    // The same wait the MCP server does, in miniature.
+    let answer = null;
+    const deadline = Date.now() + 60_000;
+    while (!answer && Date.now() < deadline) {
+      const response = await fetch(
+        `${url}/api/projects/${project}/runs/${runId}/questions/${question.id}/answer?wait=5`,
+        { headers: { authorization: `Bearer ${token}` } },
+      );
+      if (response.status === 200) {
+        answer = (await response.json()).answer;
+      }
+    }
+    if (!answer) {
+      await report('BLOCKED', 'Nobody answered the stub agent.');
+      say('nobody answered');
+      // Straight out, unlike the finish below: this is the stub giving up, and
+      // there is nothing after it worth staying open for.
+      process.exit(0);
+    }
+    await report('PROGRESS', `Got the answer: ${answer}`);
+  }
+
+  if (script === 'permission-then-finish') {
+    // R51's loop, in miniature: the real CLI does this through
+    // --permission-prompt-tool, which calls the MCP server, which calls these
+    // same two endpoints. Exercising it here costs nothing and is the only way
+    // to test the whole path — inbox, decision, release — without a live
+    // model deciding for itself that it does not need Maven after all.
+    const asked = await api(`/api/projects/${project}/runs/${runId}/approvals`, {
+      method: 'POST',
+      body: {
+        toolName: 'Bash',
+        toolInput: JSON.stringify({ command: 'mvn --version' }),
+        summary: 'mvn --version',
+        suggestion: 'Bash(mvn *)',
+        toolUseId: 'stub-tool-use',
+      },
+    });
+
+    let decision = null;
+    const until = Date.now() + 60_000;
+    while (!decision && Date.now() < until) {
+      const response = await fetch(
+        `${url}/api/projects/${project}/runs/${runId}/approvals/${asked.id}/decision?wait=5`,
+        { headers: { authorization: `Bearer ${token}` } },
+      );
+      if (response.status === 200) {
+        decision = await response.json();
+      }
+    }
+    if (!decision) {
+      await report('BLOCKED', 'Nobody decided the stub agent\'s permission request.');
+      say('nobody decided');
+      process.exit(0);
+    }
+    if (decision.state !== 'ALLOWED') {
+      await report('BLOCKED', `Refused (${decision.state}): ${decision.reason ?? 'no reason given'}`);
+      say('refused');
+      process.exit(0);
+    }
+    await report('PROGRESS', 'Allowed. Pretending to run mvn --version.');
+  }
+
+  await report('DONE', 'Stub agent finished. No code was written, which is the point.');
+  say('done');
+  leave();
+}

package/runner/token-store.mjs

@@ -0,0 +1,107 @@
+// Where this machine keeps its runner token — and why it is not in the config.
+//
+// R93 promised that no token is ever typed. It kept that promise for a machine
+// with NO config, by writing one into the config it generated. A machine that
+// already HAD a config fell through: `cawdev` started a daemon, `readConfig`
+// refused to boot, and the log said "mint one in the console under Agent
+// tokens" — the hand-carried secret R93 exists to abolish, reached by a
+// different door.
+//
+// **The fix cannot be "write it into whichever config we found."** A config
+// names working copies and permissions, so it is the kind of file people keep
+// beside the code and commit — `tools/runner/macbook-laptop.json` in this very
+// repository is tracked. Putting a credential in one is how a
+// `runner:operate` token ends up in a git history, and CLAUDE.md's rule that
+// secrets are gitignored is not a rule about `.env` in particular.
+//
+// So the credential lives on its own, here, the way `session.json` does and for
+// the same reason: what a person is and what a machine may do are two
+// different secrets with two different lifetimes, and R52's rule that a run's
+// credential can never be borrowed for a decision is exactly why they are not
+// one file.
+//
+// Keyed by URL, because one machine can point at more than one cawdev and a
+// token minted against one instance is not a credential at another.
+//
+// A token IN a config still works and is read first — R93's own generated file
+// is that shape, it is written 0600 under `~/.cawdev`, and breaking every
+// machine set up before this would be a poor way to remove some friction.
+//
+// Zero dependencies, like everything in tools/.
+
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+/** Beside the session and the sockets: one directory a person can delete. */
+export function tokenFile() {
+  return join(homedir(), '.cawdev', 'token.json');
+}
+
+function key(url) {
+  return String(url).replace(/\/+$/, '');
+}
+
+async function readAll() {
+  try {
+    const parsed = JSON.parse(await readFile(tokenFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch {
+    // No file, unreadable, or half-written. The answer to all three is the
+    // same — this machine has not minted one yet — and that is a state
+    // `cawdev` knows how to leave.
+    return {};
+  }
+}
+
+/** The token stored for one instance, or null. */
+export async function loadToken(url) {
+  const stored = (await readAll())[key(url)];
+  return typeof stored?.token === 'string' && stored.token ? stored.token : null;
+}
+
+/**
+ * The instances this machine holds a token for.
+ *
+ * For one message and it earns its place there: a token filed under a URL the
+ * daemon does not use is invisible, and "no token for X" with no further help
+ * sends somebody to mint a second one that lands in the same wrong place.
+ */
+export async function storedUrls() {
+  return Object.keys(await readAll());
+}
+
+/**
+ * Remember the token this machine minted for itself.
+ *
+ * 0700 on the directory and 0600 forced **after** the write, because
+ * `writeFile`'s mode is masked by the umask and is ignored outright for a file
+ * that already exists — so asking for 0600 and getting 0644 is the ordinary
+ * outcome rather than the unusual one.
+ */
+export async function saveToken(url, token, { name = null } = {}) {
+  const all = await readAll();
+  all[key(url)] = { token, name, mintedAt: new Date().toISOString() };
+  await mkdir(dirname(tokenFile()), { recursive: true, mode: 0o700 });
+  await writeFile(tokenFile(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  await chmod(tokenFile(), 0o600).catch(() => undefined);
+}
+
+/**
+ * Forget one instance's token.
+ *
+ * This does NOT revoke it — the platform is where a token dies, and a CLI that
+ * pretended otherwise would leave a live credential behind a reassuring
+ * message. Removing the file is removing this machine's copy, and the caller
+ * says so.
+ */
+export async function clearToken(url) {
+  const all = await readAll();
+  if (!(key(url) in all)) {
+    return;
+  }
+  delete all[key(url)];
+  await mkdir(dirname(tokenFile()), { recursive: true, mode: 0o700 });
+  await writeFile(tokenFile(), `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600 });
+  await chmod(tokenFile(), 0o600).catch(() => undefined);
+}