cawdev-cli 0.9.0 → 1.0.0-beta

package/runner/configure.mjs

@@ -0,0 +1,412 @@
+// `cawdev config` — R283, and the granular half of R93's setup walk.
+//
+// `--setup` answers every question a machine has at once: which projects,
+// which checkouts, which agents. That is right for a fresh laptop and wrong
+// for the ordinary case afterwards — "this machine should also serve one more
+// project" does not need to re-ask about the other three. So this file is the
+// same questions, one at a time, on a config that already exists.
+//
+// **Every change here writes the FILE and nothing else.** A daemon already
+// running keeps the config it booted with — `cawdev --setup` already says so,
+// and this repeats it rather than inventing a second story. The one exception
+// is `reloadIfRunning`: `agentCommands` and `acceptsRulesFromConsole` are read
+// fresh off the live `config` object on every use in runner.mjs (a spawn, or
+// the next heartbeat), so a SIGHUP that re-reads the file is enough to apply
+// them without a restart — see runner.mjs's own handler for why that is a
+// signal and not a command sent over R52's read-only socket.
+//
+// R288: the same functions have a SECOND door — the attached terminal's `c`
+// key — and that is why every question here comes in through a parameter.
+// `ask.line` and `pick` are the two shapes a question takes (a line, or one
+// row of a Select); the shell subcommand hands in readline and `askOne`, the
+// UI hands in its own raw-mode line editor and its own picker, and the
+// function between them cannot tell which. One implementation of each change,
+// so the two doors cannot disagree about what a change does.
+//
+// Zero dependencies, like everything in tools/.
+
+import { connect as connectTo } from 'node:net';
+import { mkdir, readFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { painter } from '../lib/ansi.mjs';
+import { probeSocket, socketPathFor } from './control.mjs';
+import {
+  askOne, cloneInto, confirm, defaultRunnerName,
+  findAgents, mintRunnerToken, servable, writeRunnerConfig,
+} from './bootstrap.mjs';
+import {
+  TYPE_A_PATH, absolute, describe, inspectPath, suggestProjectPaths, suggestWorkspacePaths, usable,
+} from './paths.mjs';
+import { Select } from './select.mjs';
+import { storedSession } from './sign-in.mjs';
+import { loadTokenRecord, saveToken } from './token-store.mjs';
+
+/**
+ * The config as an object, or null if it will not parse.
+ *
+ * Null rather than a throw: an unreadable config is the daemon's complaint to
+ * make — it names the file and the parse error — and swallowing it here to
+ * offer a setup walk would replace a precise message with a wrong guess about
+ * what somebody wants. Here rather than in cawdev.mjs since R288, because the
+ * attached UI reads the file too and cawdev.mjs imports attach.mjs.
+ */
+export async function readConfigFile(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Every slug a config file already serves, whatever shape each entry is. */
+export function slugsOf(file) {
+  return Object.keys(file.projects ?? {});
+}
+
+/** The agents a config file says this machine spawns — runner.mjs's own reading. */
+export function agentsOf(file) {
+  return file.agentCommands ?? (file.agentCommand ? [file.agentCommand] : ['claude']);
+}
+
+/** The checkout path(s) one project entry names, whatever shape it is. */
+export function pathsOf(entry) {
+  if (typeof entry === 'string') return [entry];
+  if (Array.isArray(entry?.workspaces)) return entry.workspaces;
+  if (entry?.path) return [entry.path];
+  return [];
+}
+
+/**
+ * Turn one project entry into the `{workspaces: [...]}` shape — R47's third
+ * form — adding a path without disturbing whatever else the entry already
+ * carried (`allowedTools`, `browser`, …).
+ */
+function withWorkspace(entry, path) {
+  if (entry == null) {
+    return { workspaces: [path] };
+  }
+  if (typeof entry === 'string') {
+    return { workspaces: [entry, path] };
+  }
+  if (Array.isArray(entry.workspaces)) {
+    return { ...entry, workspaces: [...entry.workspaces, path] };
+  }
+  if (entry.path) {
+    const { path: only, ...rest } = entry;
+    return { ...rest, workspaces: [only, path] };
+  }
+  return { ...entry, workspaces: [path] };
+}
+
+/**
+ * This token's public id, so its grants can be WIDENED in place — R173's own
+ * mechanism, `PUT /api/tokens/{id}/grants` — instead of minting a second token
+ * and leaving the first live on the Tokens page for somebody to notice.
+ *
+ * Three places to look, in the order a machine would actually have it: the
+ * config file itself (`tokenId`, set by `--setup` since R283), the token
+ * store (same field, for a top-up token minted by `mintForThisMachine`), and,
+ * failing both — every token minted before this card — a lookup by the label
+ * `mintRunnerToken` always uses. Null when none of the three finds it, which
+ * is not an error: the caller falls back to minting a fresh one.
+ */
+export async function resolveTokenId(session, file, url) {
+  if (file.tokenId) return file.tokenId;
+  const stored = await loadTokenRecord(url);
+  if (stored?.id) return stored.id;
+  const label = `${file.name ?? defaultRunnerName()} (runner)`;
+  const tokens = await session.request('/api/tokens');
+  return (Array.isArray(tokens) ? tokens : [])
+    .find((each) => each.label === label && !each.revoked)?.id ?? null;
+}
+
+/**
+ * Where should a checkout go — R289, and the step that used to be an empty
+ * line asking for an absolute path.
+ *
+ * The suggestions come first, each with what is THERE right now (`describe`
+ * over `inspectPath`), and the last row is a line to type on. This is the
+ * plain form the shell subcommand uses; attach.mjs supplies its own through
+ * the same `askPath` parameter, with the line pre-filled and tab-completed.
+ * Both return an absolute path with `~` expanded, and the caller inspects it
+ * AGAIN before acting — the preview is a courtesy, the check is the rule.
+ */
+export async function plainAskPath({ ask, say, pick = askOne, question, suggestions, slug, gitUrl, inspect = inspectPath }) {
+  const rows = [];
+  for (const each of suggestions) {
+    const seen = await inspect(each.path, { gitUrl });
+    rows.push({ id: each.path, label: each.path, hint: `${each.why} · ${describe(seen, slug)}` });
+  }
+  rows.push({ id: TYPE_A_PATH, label: 'Type a path', hint: '~ works' });
+  const picked = await pick(ask, say, new Select({ title: question, rows }));
+  if (picked.row.id !== TYPE_A_PATH) {
+    return picked.row.id;
+  }
+  const typed = String(await ask.line(`  path [${suggestions[0]?.path ?? ''}] `)).trim();
+  return absolute(typed || suggestions[0]?.path || '');
+}
+
+/**
+ * The path a checkout goes in, checked, and cloned into if there is nothing
+ * there — the half of the two add-commands that is the same. A checkout of this
+ * repository already at the path is taken as it is; anything else that exists
+ * is refused in words rather than cloned over or beside.
+ */
+async function settleCheckout({ path, slug, gitUrl, ask, say, ink, clone, inspect }) {
+  const seen = await inspect(path, { gitUrl });
+  if (!usable(seen)) {
+    throw new Error(`${path} is ${describe(seen, slug)}. Nothing changed.`);
+  }
+  if (seen.kind === 'checkout') {
+    if (seen.matches === null && !await confirm(ask, `Use ${path} as a checkout of ${slug}`)) {
+      throw new Error('Nothing changed.');
+    }
+    say(`  ${ink.success('✓')} ${ink.muted('Using the checkout already at')} ${ink.text(path)}`);
+    return;
+  }
+  if (!gitUrl) {
+    throw new Error(`${path} is ${describe(seen, slug)}, and there is no git URL to clone from — `
+      + 'sign in first, or point at a checkout you have already made.');
+  }
+  if (!await confirm(ask, `Clone ${gitUrl} into ${path}`)) {
+    throw new Error('Nothing changed.');
+  }
+  say(`  ${ink.muted('Cloning')} ${ink.accent(gitUrl)} ${ink.muted('into')} ${ink.text(path)}`);
+  await mkdir(dirname(path), { recursive: true });
+  await clone(gitUrl, path);
+}
+
+/**
+ * Add one project this session can serve to an already-configured machine.
+ *
+ * Clones it, then widens the existing token's grants to cover it — via
+ * {@link resolveTokenId}, or by minting a fresh token when that comes back
+ * empty (an older machine's first run through this command, which is also
+ * what teaches it the id for next time).
+ */
+export async function addProject({
+  configPath, file, url, session: given = null,
+  ask, say, ink = painter(3),
+  pick = askOne,
+  askPath = plainAskPath,
+  inspect = inspectPath,
+  clone = cloneInto,
+  write = writeRunnerConfig,
+} = {}) {
+  const session = given ?? (await storedSession(url));
+  if (!session.signedIn) {
+    throw new Error('Not signed in on this machine. Run `cawdev --setup` first.');
+  }
+
+  const already = new Set(slugsOf(file));
+  const projects = servable(await session.request('/api/projects'))
+    .filter((project) => !already.has(project.slug));
+  if (!projects.length) {
+    throw new Error('Every project you can serve is already configured on this machine.');
+  }
+
+  let project = projects[0];
+  if (projects.length > 1) {
+    const picked = await pick(ask, say, new Select({
+      title: 'Which project should this machine also serve?',
+      rows: projects.map((candidate) => ({
+        id: candidate.slug, label: candidate.name, hint: candidate.slug,
+      })),
+    }));
+    project = projects.find((candidate) => candidate.slug === picked.row.id);
+  }
+
+  const path = await askPath({
+    ask, say, pick, inspect,
+    question: `Where should ${project.slug} live on this machine?`,
+    suggestions: suggestProjectPaths(file, project.slug),
+    slug: project.slug,
+    gitUrl: project.gitUrl ?? null,
+  });
+  await settleCheckout({ path, slug: project.slug, gitUrl: project.gitUrl ?? null, ask, say, ink, clone, inspect });
+
+  const grants = {};
+  for (const slug of [...already, project.slug]) {
+    grants[slug] = ['runner:operate'];
+  }
+  const tokenId = await resolveTokenId(session, file, url);
+  const next = { ...file, projects: { ...file.projects, [project.slug]: path } };
+  if (tokenId) {
+    await session.request(`/api/tokens/${tokenId}/grants`, { method: 'PUT', body: { grants } });
+    next.tokenId = tokenId;
+    say(`  ${ink.success('✓')} ${ink.muted('Widened this machine\'s token to also cover')} ${ink.text(project.slug)}`);
+  } else {
+    const minted = await mintRunnerToken(session, Object.keys(grants), file.name ?? defaultRunnerName());
+    next.token = minted.secret;
+    next.tokenId = minted.id;
+    say(`  ${ink.warn('!')} ${ink.muted('Could not find the existing token to widen — minted a new one.')}`);
+    say(`  ${ink.muted('Revoke the old one on the Tokens page if you like; nothing here needs it any more.')}`);
+  }
+
+  await write(configPath, next);
+  say(`  ${ink.success('✓')} ${ink.muted('Now serving')} ${ink.text(project.slug)} ${ink.muted('at')} ${ink.accent(path)}`);
+  return next;
+}
+
+/** Add another checkout for a project this machine already serves — R47. */
+export async function addWorkspace({
+  configPath, file,
+  ask, say, ink = painter(3),
+  pick = askOne,
+  askPath = plainAskPath,
+  inspect = inspectPath,
+  clone = cloneInto,
+  write = writeRunnerConfig,
+  session: given = null,
+  url,
+} = {}) {
+  const slugs = slugsOf(file);
+  if (!slugs.length) {
+    throw new Error('This machine serves no projects yet — add one first.');
+  }
+
+  const slug = slugs.length === 1 ? slugs[0]
+    : (await pick(ask, say, new Select({
+      title: 'Add a workspace to which project?',
+      rows: slugs.map((each) => ({ id: each, label: each })),
+    }))).row.id;
+
+  // The git URL first, because the suggestions are described against it —
+  // "already a checkout of cawdev" is only sayable when the remote is known.
+  let gitUrl = null;
+  const session = given ?? (await storedSession(url));
+  if (session.signedIn) {
+    const projects = await session.request('/api/projects');
+    gitUrl = (Array.isArray(projects) ? projects : []).find((p) => p.slug === slug)?.gitUrl ?? null;
+  }
+
+  const existing = pathsOf(file.projects[slug]).map((each) => absolute(each));
+  const path = await askPath({
+    ask, say, pick, inspect,
+    question: `Where should the second checkout of ${slug} live?`,
+    suggestions: suggestWorkspacePaths(file, slug),
+    slug,
+    gitUrl,
+  });
+  if (existing.includes(path)) {
+    throw new Error(`${path} is already a workspace of ${slug}.`);
+  }
+  await settleCheckout({ path, slug, gitUrl, ask, say, ink, clone, inspect });
+
+  const next = { ...file, projects: { ...file.projects, [slug]: withWorkspace(file.projects[slug], path) } };
+  await write(configPath, next);
+  const count = pathsOf(next.projects[slug]).length;
+  say(`  ${ink.success('✓')} ${ink.muted(`${slug} now has ${count} checkout${count === 1 ? '' : 's'}, `
+    + `so ${count} coding run${count === 1 ? '' : 's'} at once`)}`);
+  return next;
+}
+
+/** Turn one agent this machine spawns on or off. */
+export async function setAgentEnabled({
+  file, configPath, enabled, command,
+  ask, say, ink = painter(3),
+  write = writeRunnerConfig,
+  agent = findAgents,
+} = {}) {
+  const current = agentsOf(file);
+  let next;
+  if (enabled) {
+    if (current.includes(command)) {
+      say(`  ${ink.muted(command)} ${ink.muted('is already enabled on this machine.')}`);
+      return file;
+    }
+    const [found] = await agent([command]);
+    if (!found) {
+      throw new Error(`${command} is not on this machine's PATH. Install it before enabling it here.`);
+    }
+    const label = command === 'agy' ? 'Antigravity CLI' : 'Claude Code';
+    if (!await confirm(ask, `Is ${label} signed in on this machine?`)) {
+      throw new Error(`Sign in first — run \`${command}\` once in a terminal and follow it.`);
+    }
+    next = { ...file, agentCommands: [...current, command] };
+  } else {
+    if (!current.includes(command)) {
+      say(`  ${ink.muted(command)} ${ink.muted('was already not enabled here.')}`);
+      return file;
+    }
+    const remaining = current.filter((each) => each !== command);
+    if (!remaining.length) {
+      throw new Error('This machine must spawn at least one agent — enable another before disabling this one.');
+    }
+    next = { ...file, agentCommands: remaining };
+  }
+  await write(configPath, next);
+  say(`  ${ink.success('✓')} ${ink.muted('This machine spawns:')} ${ink.text(next.agentCommands.join(', '))}`);
+  return next;
+}
+
+/** Turn `acceptsRulesFromConsole` on or off — R126. */
+export async function setAcceptsRulesFromConsole({
+  file, configPath, enabled,
+  ask, say, ink = painter(3),
+  write = writeRunnerConfig,
+} = {}) {
+  if (enabled && !await confirm(ask,
+    'Turning this on lets anyone able to write to your cawdev widen what an unattended '
+      + 'agent may run in your checkouts. Are you sure')) {
+    throw new Error('Nothing changed.');
+  }
+  const next = { ...file, acceptsRulesFromConsole: enabled };
+  await write(configPath, next);
+  say(`  ${ink.success('✓')} ${ink.muted('acceptsRulesFromConsole is now')} ${ink.text(String(enabled))}`);
+  return next;
+}
+
+/**
+ * The pid of a daemon running on this exact config, or null.
+ *
+ * The socket is keyed by NAME (R52), not by config path, so a machine
+ * renamed between `--setup` and now would miss its own daemon — an edge case
+ * left alone deliberately: naming this wrong points the reload at nobody's
+ * process rather than somebody else's.
+ */
+async function livePidFor(name) {
+  const path = socketPathFor(name);
+  if (!(await probeSocket(path))) return null;
+  return new Promise((done) => {
+    const client = connectTo(path);
+    let buffer = '';
+    const finish = (pid) => {
+      clearTimeout(timer);
+      try { client.destroy(); } catch { /* already gone */ }
+      done(pid);
+    };
+    const timer = setTimeout(() => finish(null), 1000);
+    client.setEncoding('utf8');
+    client.on('data', (chunk) => {
+      buffer += chunk;
+      const newline = buffer.indexOf('\n');
+      if (newline === -1) return;
+      try {
+        finish(JSON.parse(buffer.slice(0, newline))?.runner?.pid ?? null);
+      } catch {
+        finish(null);
+      }
+    });
+    client.on('error', () => finish(null));
+  });
+}
+
+/**
+ * SIGHUP a daemon already running on this config, so `agentCommands` and
+ * `acceptsRulesFromConsole` take effect without a restart. Never a socket
+ * command — see this file's header and runner.mjs's handler for why.
+ */
+export async function reloadIfRunning(name, say, ink = painter(3), { pidOf = livePidFor, kill = process.kill } = {}) {
+  const pid = await pidOf(name);
+  if (!pid) return false;
+  try {
+    kill(pid, 'SIGHUP');
+    say(`  ${ink.success('✓')} ${ink.muted(`Told the running daemon (pid ${pid}) to re-read this — no restart needed.`)}`);
+    return true;
+  } catch (failure) {
+    say(`  ${ink.warn('!')} ${ink.muted(`Could not signal the running daemon (${failure.message}) — restart it to pick this up.`)}`);
+    return false;
+  }
+}

package/runner/paths.mjs

@@ -0,0 +1,254 @@
+// Where a checkout goes, and what is there already — R289.
+//
+// R288 put the config screen inside the terminal and the first use of it found
+// the path step unusable: an empty line, an absolute path to retype, no
+// completion, `~` silently wrong, and a clone into whatever was typed. This file
+// is the part of the fix that can be READ without a terminal: what to suggest,
+// how to complete, and what a path IS right now — the same answers whether they
+// are drawn as a picker in attach.mjs or printed as a numbered list by the shell
+// subcommand.
+//
+// Pure where it can be (`expandHome`, `completePath`, `sameRepository`,
+// `describe`) and injectable where it cannot (`inspectPath` reads the disk and
+// asks git), because a path check that can only be tested against the real
+// filesystem is one that gets tested once.
+//
+// Zero dependencies, like everything in tools/.
+
+import { spawn } from 'node:child_process';
+import { readdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+/** The row a picker ends with: not one of the suggestions, a line to type on. */
+export const TYPE_A_PATH = 'type-a-path';
+
+/**
+ * `~` and `~/…` as the shell reads them.
+ *
+ * `path.resolve` does not know about `~`: it treated `~/code/x` as a relative
+ * path and produced `<cwd>/~/code/x`, which is the bug that started this card.
+ * Only the leading tilde, and only the current user's — `~bob` is a shell
+ * feature nobody types into a config screen, and guessing at it is how a path
+ * lands in somebody else's home.
+ */
+export function expandHome(path, home = homedir()) {
+  const text = String(path ?? '').trim();
+  if (text === '~') return home;
+  if (text.startsWith('~/')) return join(home, text.slice(2));
+  return text;
+}
+
+/** Absolute, with `~` expanded first — the one spelling every path here ends in. */
+export function absolute(path, home = homedir()) {
+  return resolve(expandHome(path, home));
+}
+
+/**
+ * The checkout paths a config file names, whatever shape each entry is.
+ * Mirrors configure.mjs's `pathsOf` on purpose rather than importing it —
+ * that module imports this one.
+ */
+function pathsIn(file) {
+  return Object.values(file?.projects ?? {}).flatMap((entry) => {
+    if (typeof entry === 'string') return [entry];
+    if (Array.isArray(entry?.workspaces)) return entry.workspaces;
+    if (entry?.path) return [entry.path];
+    return [];
+  });
+}
+
+/**
+ * Where a NEW project's checkout would plausibly go on this machine.
+ *
+ * Beside the checkouts it already serves first — somebody with everything
+ * under `~/Documents/Dev/agents-workspace/test/` wants the next one there too,
+ * not under a default they never chose — then the default root. Deduplicated
+ * and in that order, so the first row is the best guess and enter takes it.
+ */
+export function suggestProjectPaths(file, slug, { home = homedir() } = {}) {
+  const seen = new Set();
+  const out = [];
+  const add = (path, why) => {
+    const full = absolute(path, home);
+    if (seen.has(full)) return;
+    seen.add(full);
+    out.push({ path: full, why });
+  };
+  for (const existing of pathsIn(file)) {
+    add(join(dirname(absolute(existing, home)), slug), `beside ${basename(existing)}`);
+  }
+  add(join(home, 'cawdev', slug), 'the default');
+  return out;
+}
+
+/**
+ * Where ANOTHER checkout of a project this machine already serves would go —
+ * R47's second workspace. `<first>-2`, then `-3`, skipping the numbers the
+ * config already uses; then the default root's version of the same.
+ */
+export function suggestWorkspacePaths(file, slug, { home = homedir() } = {}) {
+  const entry = file?.projects?.[slug];
+  const existing = pathsIn({ projects: { [slug]: entry } }).map((path) => absolute(path, home));
+  const taken = new Set(existing);
+  const out = [];
+  const seen = new Set();
+  const add = (path, why) => {
+    if (seen.has(path) || taken.has(path)) return;
+    seen.add(path);
+    out.push({ path, why });
+  };
+  const base = existing[0] ?? join(home, 'cawdev', slug);
+  for (let n = 2; n < 100 && out.length < 1; n++) {
+    add(`${base}-${n}`, `next to ${basename(base)}`);
+  }
+  add(`${join(home, 'cawdev', slug)}-${existing.length + 1}`, 'under the default root');
+  return out;
+}
+
+/**
+ * Tab, on a path — pure over the names in the directory being typed in.
+ *
+ * `text` is what is on the line; `entries` are the DIRECTORY names in the
+ * folder that text points into (its own folder if it ends in `/`, its parent
+ * otherwise). Returns the directories that match what has been typed so far,
+ * as full paths, and what the line should become: one match completes whole
+ * with a trailing `/`, several complete as far as they agree, none leave the
+ * line alone. What every shell does, so nobody has to be taught it.
+ */
+export function completePath(text, entries, home = homedir()) {
+  const raw = String(text ?? '');
+  const expanded = expandHome(raw, home);
+  const endsWithSlash = expanded.endsWith('/');
+  const dir = endsWithSlash ? expanded : dirname(expanded);
+  const prefix = endsWithSlash ? '' : basename(expanded);
+  const matches = (entries ?? [])
+    .filter((name) => name.startsWith(prefix) && (prefix.startsWith('.') || !name.startsWith('.')))
+    .sort()
+    .map((name) => join(dir, name));
+  if (!matches.length) {
+    return { dir, matches, completed: raw };
+  }
+  if (matches.length === 1) {
+    return { dir, matches, completed: `${matches[0]}/` };
+  }
+  const names = matches.map((path) => basename(path));
+  let common = names[0];
+  for (const name of names.slice(1)) {
+    let i = 0;
+    while (i < common.length && common[i] === name[i]) i += 1;
+    common = common.slice(0, i);
+  }
+  const completed = common.length > prefix.length ? join(dir, common) : expanded;
+  return { dir, matches, completed };
+}
+
+/** The directory names in `dir`, or none when it cannot be read. */
+export async function listDirectories(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Two remotes naming the same repository — `git@github.com:o/r.git` and
+ * `https://github.com/o/r` are one repository, and a checkout cloned over ssh
+ * must not be refused because the platform stored the https form.
+ */
+export function sameRepository(a, b) {
+  const key = (url) => String(url ?? '')
+    .trim()
+    .toLowerCase()
+    .replace(/^[a-z+]+:\/\//, '')
+    .replace(/^[^@/]+@/, '')
+    .replace(/^([^:/]+):(?!\/\/)/, '$1/')
+    .replace(/\.git$/, '')
+    .replace(/\/+$/, '');
+  return Boolean(a && b) && key(a) === key(b);
+}
+
+/** `git -C path remote get-url origin`, or null when there is none. */
+export function originOf(path) {
+  return new Promise((done) => {
+    let out = '';
+    const child = spawn('git', ['-C', path, 'remote', 'get-url', 'origin'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+    child.stdout.on('data', (chunk) => { out += chunk; });
+    child.on('error', () => done(null));
+    child.on('close', (code) => done(code === 0 ? out.trim() || null : null));
+  });
+}
+
+/**
+ * What a path IS, right now — the preview under the line and the check before
+ * anything is cloned, one function so they cannot disagree.
+ *
+ *   missing     nothing there; a clone would create it
+ *   empty       a directory with nothing in it; a clone would fill it
+ *   checkout    a git checkout whose origin is this project's repository
+ *   other-repo  a git checkout of something else
+ *   not-empty   a directory holding things that are not this project
+ *   file        not a directory at all
+ *
+ * `gitUrl` may be null (nobody signed in to ask the platform); then any
+ * checkout is `checkout` with `matches: null`, and the caller says so.
+ */
+export async function inspectPath(path, { gitUrl = null } = {}, {
+  statOf = stat, list = readdir, remoteOf = originOf,
+} = {}) {
+  let info;
+  try {
+    info = await statOf(path);
+  } catch {
+    return { kind: 'missing' };
+  }
+  if (!info.isDirectory()) {
+    return { kind: 'file' };
+  }
+  let names;
+  try {
+    names = await list(path);
+  } catch (failure) {
+    return { kind: 'unreadable', error: failure.message };
+  }
+  if (!names.length) {
+    return { kind: 'empty' };
+  }
+  if (names.includes('.git')) {
+    const remote = await remoteOf(path);
+    if (!gitUrl) {
+      return { kind: 'checkout', remote, matches: null };
+    }
+    return sameRepository(remote, gitUrl)
+      ? { kind: 'checkout', remote, matches: true }
+      : { kind: 'other-repo', remote };
+  }
+  return { kind: 'not-empty' };
+}
+
+/** One line for a person, about an inspection — the preview and the refusal. */
+export function describe(inspection, slug = 'this project') {
+  switch (inspection?.kind) {
+    case 'missing': return 'new folder — will clone here';
+    case 'empty': return 'empty folder — will clone here';
+    case 'checkout':
+      return inspection.matches === null
+        ? `a checkout (${inspection.remote ?? 'no origin'}) — cannot check it is ${slug} without signing in`
+        : `already a checkout of ${slug} — used as it is`;
+    case 'other-repo': return `a checkout of ${inspection.remote ?? 'something else'}, not ${slug}`;
+    case 'not-empty': return 'exists and is not empty';
+    case 'file': return 'a file, not a folder';
+    case 'unreadable': return `cannot be read (${inspection.error})`;
+    default: return '';
+  }
+}
+
+/** Whether a path in this state may be used — cloned into, or taken as is. */
+export function usable(inspection) {
+  return ['missing', 'empty', 'checkout'].includes(inspection?.kind);
+}