@coulb/crux-cli 0.1.0

package/lib/cancel.js

@@ -0,0 +1,125 @@
+'use strict';
+
+/**
+ * Cancel tombstones: the one thing that can tell a supervisor "this worker's silence was on purpose".
+ *
+ * The supervisor's contract is that silence is the bug — a headless worker whose process ends having
+ * printed nothing gets "**Worker failed** … it crashed, was killed, or never started" on the thread
+ * and a push to the human's phone {@see ../lib/spawn workerReport}. That is right, and it is not
+ * being weakened here. The problem is that a lead stopping a worker ON PURPOSE — the plan changed
+ * mid-flight, the brief is now wrong, `solo processes stop` — produces *the identical observation*:
+ * process gone, buffer empty. From the supervisor's side a deliberate kill and a crash are the same
+ * event. So the supervisor cried wolf, and a crash note that cries wolf is worse than no crash note,
+ * because the real ones start getting ignored.
+ *
+ * The missing piece is not a smarter supervisor. It is a way for the killer to leave a note. So
+ * `crux cancel` writes a TOMBSTONE before it stops the process, and the supervisor — which is
+ * already awake and polling — finds it when the process ends and reports a cancellation instead of a
+ * death. Three things make that safe:
+ *
+ *   ORDER. The tombstone is written BEFORE the kill. Written after, it would race a supervisor that
+ *   polls every 5s, and lose often enough to report a crash anyway.
+ *
+ *   KEY. `<item>:<solo-process>`, not `<item>`. The case that makes this mandatory is real: thread
+ *   #74 was cancelled and RE-SPAWNED onto a new Solo process minutes later. An item-keyed tombstone
+ *   left behind by the first worker would have silenced the *second* one's genuine crash. A
+ *   tombstone may only ever excuse the exact process it was written for.
+ *
+ *   TTL. Solo process ids are not promised to be unique forever, and a tombstone whose supervisor
+ *   never came (it died; the kill never landed) would otherwise sit there for good. One that is
+ *   older than {@see TOMBSTONE_TTL_MS} is ignored on sight and pruned on the next write, so the
+ *   worst a stale tombstone can do is nothing.
+ *
+ * Consumption is exactly-once: {@see takeTombstone} deletes under the same lock that reads. A second
+ * supervisor on the same process finds nothing, which is the correct answer — the cancellation has
+ * already been reported, and re-reporting it would be a second lie in the other direction.
+ */
+
+const os = require('os');
+const path = require('path');
+const { readJson, updateJson } = require('./store');
+
+/** Beside the tail cursor, and overridable for the same reason: tests must not touch the real fleet's. */
+const CANCEL_FILE =
+  process.env.CRUX_CANCEL_FILE || path.join(os.homedir(), '.config', 'crux', 'cancelled.json');
+
+/**
+ * How long a tombstone may excuse a worker's silence.
+ *
+ * Generously longer than the seconds a supervisor actually needs (it polls every 5s and the kill has
+ * already landed), because expiring one too early would resurrect the very bug this kills. But finite,
+ * because an unconsumed tombstone is a loaded gun pointed at whatever process id comes round again.
+ */
+const TOMBSTONE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** A tombstone excuses ONE worker: this item, on this Solo process. Never an item alone. */
+function tombstoneKey(item, procId) {
+  return `${item}:${procId}`;
+}
+
+/** Unparseable timestamps count as expired — a corrupt record must not be able to silence anything. */
+function expired(record, now) {
+  const at = Date.parse(record?.at ?? '');
+  return !Number.isFinite(at) || now - at > TOMBSTONE_TTL_MS;
+}
+
+function prune(map, now) {
+  for (const [key, record] of Object.entries(map)) {
+    if (expired(record, now)) delete map[key];
+  }
+}
+
+/**
+ * Record that this worker is about to be stopped on purpose. Called BEFORE the kill — see the header.
+ *
+ * Throws if it cannot write, and `crux cancel` lets that be fatal: a cancel whose tombstone did not
+ * land is a cancel that will be reported as a crash, so it is better to stop before killing anything
+ * than to kill the worker and then lie about why it died.
+ */
+function writeTombstone({ item, process: procId, note = null, actor = null, now = Date.now() }) {
+  const key = tombstoneKey(item, procId);
+
+  updateJson(CANCEL_FILE, (map) => {
+    prune(map, now);
+    map[key] = {
+      item: Number(item),
+      process: String(procId),
+      note: typeof note === 'string' && note.trim() !== '' ? note.trim() : null,
+      actor: typeof actor === 'string' && actor.trim() !== '' ? actor.trim() : null,
+      at: new Date(now).toISOString(),
+    };
+  });
+
+  return key;
+}
+
+/**
+ * The tombstone for this exact worker, consumed — or null if its silence was never explained.
+ *
+ * Null is the load-bearing return: it means CRASH, and the supervisor must go on reporting a crash
+ * loudly. Every failure here (no file, unreadable file, a lock we could not take) therefore returns
+ * null rather than throwing, which fails toward the noisy answer. A supervisor that cannot read the
+ * tombstones must still be able to say a worker died.
+ *
+ * The pre-check is unlocked on purpose: the overwhelmingly common call is a worker that finished
+ * normally, and there is nothing to consume. Reading first means that path never takes the lock and
+ * never creates the file. It cannot race, because the tombstone is durably written before the kill
+ * that produces the very process-death this is called in response to.
+ */
+function takeTombstone(item, procId, now = Date.now()) {
+  const key = tombstoneKey(item, procId);
+  if (readJson(CANCEL_FILE)[key] === undefined) return null;
+
+  try {
+    return updateJson(CANCEL_FILE, (map) => {
+      const found = map[key];
+      delete map[key];
+      prune(map, now);
+      return found !== undefined && !expired(found, now) ? found : null;
+    });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { CANCEL_FILE, TOMBSTONE_TTL_MS, tombstoneKey, writeTombstone, takeTombstone };

package/lib/cursor.js

@@ -0,0 +1,51 @@
+'use strict';
+
+/**
+ * The durable tail cursor: one JSON map, shared by every `crux tail` on the machine.
+ *
+ * Write-then-rename already made each *write* atomic. It did not make the *read-modify-write*
+ * safe, and seven leads share this file: each reads the whole map, edits its own key, and writes
+ * it all back. Two tails interleaving that sequence lose the other's advance — last writer wins
+ * and the loser's cursor rolls backwards. Delivery is at-least-once, so the consequence is a
+ * replay rather than data loss, but a lead reprocessing an item is exactly the double-processing
+ * the fleet is trying to avoid. So the whole sequence is serialised under a lock {@see ./store}.
+ */
+
+const os = require('os');
+const path = require('path');
+const { LOCK_STALE_MS, withFileLock, readJson, updateJson } = require('./store');
+
+/** Overridable so the concurrency test does not fight the real fleet's cursor file. */
+const CURSOR_FILE = process.env.CRUX_CURSOR_FILE || path.join(os.homedir(), '.config', 'crux', 'tail-cursor.json');
+const CURSOR_LOCK = `${CURSOR_FILE}.lock`;
+
+/**
+ * Cursors are keyed by exactly what identifies a stream — including the server, since a cursor is
+ * a position in *that* server's ledger. A `--unrouted` tail, a `--project crux` tail, and a tail
+ * against a local dev API all keep their own position in the one file.
+ */
+function cursorKey({ url, topics, project, status }) {
+  return `${url}|topics=${topics}|project=${project || ''}|status=${status || ''}`;
+}
+
+function readCursors() {
+  return readJson(CURSOR_FILE);
+}
+
+function withCursorLock(fn) {
+  return withFileLock(CURSOR_FILE, fn);
+}
+
+/** Advance one stream's cursor without clobbering any other's. */
+function saveCursor(key, cursor) {
+  try {
+    updateJson(CURSOR_FILE, (cursors) => {
+      cursors[key] = cursor;
+    });
+  } catch (e) {
+    // A tail that cannot persist its cursor still works; it just replays on restart.
+    console.error(`crux tail: could not save cursor: ${e.message}`);
+  }
+}
+
+module.exports = { CURSOR_FILE, CURSOR_LOCK, LOCK_STALE_MS, cursorKey, readCursors, saveCursor, withCursorLock };

package/lib/discover.js

@@ -0,0 +1,422 @@
+'use strict';
+
+/**
+ * `crux discover` — step zero. Point it at a repo, answer a few questions, and you have a crux
+ * project: registered with the API, and declared in the local swarm config so `crux swarm up` knows
+ * where its lead runs.
+ *
+ * Everything in this file is PURE: no processes, no network, no prompts, no clock. It decides what
+ * SHOULD be written; `crux.js` reads the disk, asks the questions, and does the writes. That split is
+ * what makes the refusals testable, and — exactly as in `lib/swarm.js` — the refusals are the product.
+ *
+ * ## The rule the whole file is organised around
+ *
+ * **Do not ask what you can read.** A repo already knows what it is called (its remote, its
+ * `package.json`, its directory), what it is (its manifest), and roughly what it is about (its
+ * README). Every one of those is a question a stranger should never be asked, because being asked it
+ * is what makes a tool feel like a form. `crux discover` + Enter + Enter + Enter is the common case,
+ * and `--yes` is the same run with the Enters implied.
+ *
+ * ## And the rule that keeps it honest
+ *
+ * A second run must not create a second project, and it must not report success while doing nothing.
+ * {@see planWrite} therefore returns TWO independent verdicts — one for the API project, one for the
+ * local config entry — because the interesting states are the ones where those disagree: a project
+ * that exists in the feed but has no repo on this machine (the router creates projects; it cannot
+ * know where their code lives) is a real, useful thing for discover to do, and reporting it as
+ * "already a crux project, nothing to do" would be a lie of exactly the shape we removed from
+ * `crux accept` tonight.
+ */
+
+const path = require('path');
+
+/**
+ * The colours a project may be.
+ *
+ * Deliberately the INTERSECTION of what the two surfaces render, not the union. The app's
+ * `projectHues` (app/src/theme.ts) knows twenty Tailwind hue names; the web's project chip
+ * (`components/project-chip.blade.php`) special-cases six and falls through to zinc for everything
+ * else. So a project set to `teal` is coloured on your phone and grey on the web — a difference
+ * nobody would connect back to the moment they typed "teal" at a prompt. Offer only what is true on
+ * both, and refuse the rest by name rather than accept it and quietly grey it out.
+ */
+const PALETTE = ['emerald', 'violet', 'sky', 'amber', 'rose', 'pink', 'zinc'];
+
+/** Words that survive in a keyword list but carry no routing signal. */
+const STOPWORDS = new Set([
+  'the', 'a', 'an', 'and', 'or', 'of', 'for', 'to', 'my', 'our', 'new',
+  'app', 'application', 'project', 'repo', 'repository', 'src', 'code',
+  'main', 'master', 'dev', 'test', 'demo', 'com', 'io', 'git',
+]);
+
+/** How many keywords the router gets. Beyond this they stop discriminating and start colliding. */
+const MAX_KEYWORDS = 8;
+
+/** `Acme Importer` / `@acme/importer` / `acme_importer` → `acme-importer`. */
+function slugify(text) {
+  return String(text ?? '')
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+}
+
+/**
+ * The project name out of a git remote, an npm/composer name, or a directory.
+ *
+ * `git@github.com:acme/orbit.git`, `https://github.com/acme/orbit`, `@acme/orbit`, `acme/orbit` —
+ * every one of them is the project "orbit", and none of them is a question worth asking a human.
+ * Returns null rather than guess at something that is not a remote.
+ */
+function repoFromRemote(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  const cleaned = url.trim().replace(/\.git$/, '').replace(/\/+$/, '');
+  const last = cleaned.split(/[/:]/).filter(Boolean).pop();
+  return last && !/^(https?|ssh|git)$/i.test(last) ? last : null;
+}
+
+/** The owner/org in a remote (`acme` in `github.com:acme/orbit`), which is a keyword worth having. */
+function ownerFromRemote(url) {
+  if (typeof url !== 'string' || url.trim() === '') return null;
+  const cleaned = url.trim().replace(/\.git$/, '').replace(/\/+$/, '');
+  const parts = cleaned.split(/[/:]/).filter(Boolean);
+  const owner = parts.at(-2);
+  return owner && !/^(https?|ssh|git|github\.com|gitlab\.com|bitbucket\.org)$/i.test(owner) ? owner : null;
+}
+
+/** `@acme/orbit` → `orbit`; `acme/orbit` (composer) → `orbit`. A scope is a vendor, not a name. */
+function unscope(name) {
+  if (typeof name !== 'string' || name === '') return null;
+  const bare = name.replace(/^@/, '').split('/').pop();
+  return bare || null;
+}
+
+/**
+ * What the project is CALLED, in the order a human would guess it.
+ *
+ * The remote comes first because it is the name the rest of the world uses for this code — a
+ * directory can be `orbit-2`, a `package.json` can still say `orbit-old`, but `origin` is the name
+ * on the tin. The manifest is next (it is at least maintained), and the directory is the floor.
+ */
+function deriveName({ remote, manifestName, dirName }) {
+  return repoFromRemote(remote) || unscope(manifestName) || dirName || null;
+}
+
+/** `acme-importer` → `Acme Importer`. A name is read by a person; the slug is the machine's copy. */
+function titleCase(name) {
+  return String(name ?? '')
+    .split(/[\s\-_.]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+/**
+ * The name as a HUMAN would write it — the project's label in the feed, the app and the web.
+ *
+ * A remote and a directory are both lowercase-with-dashes because that is what filesystems and URLs
+ * want, and shipping `orbit` as a display name next to `Crux` and `ACME` reads like a placeholder
+ * somebody forgot to fill in. So it is title-cased — unless the README says the name outright, in
+ * which case that wins: a repo whose heading reads `# ACME` has already told us its capitalisation,
+ * and no rule of ours is going to beat `ACME` → `Acme`.
+ */
+function deriveDisplayName({ name, title, slug }) {
+  if (title && slugify(title) === slug) return title;
+  return titleCase(name) || name;
+}
+
+/**
+ * What KIND of thing this repo is — for the lead's brief, and for the router's keywords.
+ *
+ * This is not trivia. A lead that knows it is standing in a Laravel app writes a better brief for its
+ * workers, asks better questions, and stops guessing at the test command; and "laravel" in the
+ * keyword list is what routes a captured "the queue worker is dying" to this project rather than the
+ * Go service next door. Read the manifests — every one of them is a file that already exists.
+ *
+ * @param {object} files the manifests that were found, already parsed where they are JSON
+ * @returns {{key: string, label: string, keywords: string[]}|null} null when nothing identifies it
+ */
+function detectStack(files = {}) {
+  const { composer, pkg, goMod, cargo, gemfile, python } = files;
+
+  if (composer) {
+    const deps = { ...(composer.require || {}), ...(composer['require-dev'] || {}) };
+    if (deps['laravel/framework']) return { key: 'laravel', label: 'a Laravel app', keywords: ['laravel', 'php'] };
+    if (deps['symfony/framework-bundle']) return { key: 'symfony', label: 'a Symfony app', keywords: ['symfony', 'php'] };
+    return { key: 'php', label: 'a PHP project', keywords: ['php'] };
+  }
+
+  if (pkg) {
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.expo || deps['react-native']) {
+      return { key: 'react-native', label: 'a React Native app', keywords: ['react-native', 'mobile'] };
+    }
+    if (deps.next) return { key: 'next', label: 'a Next.js app', keywords: ['next', 'react', 'node'] };
+    if (deps.react) return { key: 'react', label: 'a React app', keywords: ['react', 'node'] };
+    if (deps.express || deps.fastify || deps.hono) {
+      return { key: 'node-service', label: 'a Node service', keywords: ['node', 'api'] };
+    }
+    // A `bin` is the difference between a library and something you TYPE, and it is the one thing a
+    // package.json states outright rather than implies.
+    if (pkg.bin) return { key: 'node-cli', label: 'a Node CLI', keywords: ['cli', 'node'] };
+    return { key: 'node', label: 'a Node project', keywords: ['node'] };
+  }
+
+  if (goMod) return { key: 'go', label: 'a Go service', keywords: ['go'] };
+  if (cargo) return { key: 'rust', label: 'a Rust project', keywords: ['rust'] };
+  if (gemfile) {
+    return /['"]rails['"]/.test(gemfile)
+      ? { key: 'rails', label: 'a Rails app', keywords: ['rails', 'ruby'] }
+      : { key: 'ruby', label: 'a Ruby project', keywords: ['ruby'] };
+  }
+  if (python) return { key: 'python', label: 'a Python project', keywords: ['python'] };
+
+  return null;
+}
+
+/** The `# Title` of a README — the one line of prose a repo reliably has. */
+function readmeTitle(readme) {
+  if (typeof readme !== 'string') return null;
+  const match = /^#\s+(.+?)\s*$/m.exec(readme);
+  if (!match) return null;
+  // Strip the markdown a title picks up: `crux swarm`, **bold**, [links](…).
+  const title = match[1]
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/[`*_]/g, '')
+    .trim();
+  return title || null;
+}
+
+/**
+ * The keywords the router will use to place a captured item into this project.
+ *
+ * These matter more than they look: they are the entire reason a thought typed into a phone at
+ * midnight ("the acme importer keeps timing out") lands on the right thread instead of the unrouted
+ * queue. Derived from every name this project already answers to — its slug, its title, its remote,
+ * its owner, and what it is built with — because those are exactly the words a human reaches for.
+ * Stopwords go, because "app" routes nothing.
+ */
+function deriveKeywords({ slug, name, remote, stack, title }) {
+  const words = [
+    slug,
+    ...String(name ?? '').split(/[\s\-_/]+/),
+    repoFromRemote(remote),
+    ownerFromRemote(remote),
+    ...(stack ? stack.keywords : []),
+    ...String(title ?? '').split(/[\s\-_/]+/),
+  ];
+
+  const seen = new Set();
+  const keywords = [];
+  for (const raw of words) {
+    const word = slugify(raw);
+    if (!word || word.length < 2 || STOPWORDS.has(word) || seen.has(word)) continue;
+    seen.add(word);
+    keywords.push(word);
+    if (keywords.length === MAX_KEYWORDS) break;
+  }
+  return keywords;
+}
+
+/**
+ * A colour, without asking — but never the same one for everything.
+ *
+ * `zinc` is the API's default and it is grey; a fleet of grey projects is a fleet you cannot tell
+ * apart at a glance, which is the entire job of the colour. So the default is derived from the slug:
+ * stable (the same project is the same colour on every machine and every re-run, so `--yes` twice is
+ * genuinely idempotent), and spread across the palette. Zinc stays available — it is just never
+ * assigned by default.
+ */
+function colorFor(slug) {
+  const hues = PALETTE.filter((c) => c !== 'zinc');
+  let hash = 0;
+  for (const char of String(slug ?? '')) hash = (hash * 31 + char.charCodeAt(0)) % 100_000;
+  return hues[hash % hues.length];
+}
+
+/** The one-line summary the router renders into its prompt, and the lead reads in its brief. */
+function describe({ name, stack, title }) {
+  if (title && slugify(title) !== slugify(name)) return `${name} — ${title}`.slice(0, 255);
+  if (stack) return `${name} — ${stack.label}.`.slice(0, 255);
+  return `${name} — a git repo.`.slice(0, 255);
+}
+
+/** The fields the API stores. Compared, not just sent — see {@see planWrite}. */
+function projectPayload({ slug, name, color, description, keywords }) {
+  return { slug, name, color, description, keywords };
+}
+
+/** Which of the API's fields this run would actually change. Empty means the POST is a no-op. */
+function changedFields(existing, payload) {
+  if (!existing) return Object.keys(payload);
+
+  const changed = [];
+  for (const [key, value] of Object.entries(payload)) {
+    const before = existing[key] ?? null;
+    if (key === 'keywords') {
+      const a = JSON.stringify(before ?? []);
+      const b = JSON.stringify(value ?? []);
+      if (a !== b) changed.push(key);
+      continue;
+    }
+    if ((before ?? null) !== (value ?? null)) changed.push(key);
+  }
+  return changed;
+}
+
+/**
+ * Decide what this run writes, and what it refuses.
+ *
+ * Two verdicts, because there are two places and they can disagree — and every interesting state
+ * lives in the disagreement:
+ *
+ *   project: create | update | unchanged     the crux project, in the API
+ *   config:  add    | unchanged              `swarm.projects.<slug>.repo`, on this machine
+ *
+ * The pair is what lets the caller tell the truth afterwards. A project the router already created
+ * has no repo on this machine, so discover has real work to do (`config: add`) even though the
+ * project itself is `unchanged` — and a run that said "already a crux project, nothing to do" there
+ * would be the `crux accept` bug wearing a different hat: success reported, nothing done, and
+ * `crux swarm up` still unable to find the repo.
+ *
+ * Refusals name the fix, always. There are exactly two, and both are the same underlying mistake —
+ * a slug and a repo that do not agree about each other — caught from either side.
+ *
+ * @param {object} input
+ * @param {string} input.slug the chosen slug
+ * @param {string} input.repo the resolved repo path
+ * @param {object} input.payload what we would POST {@see projectPayload}
+ * @param {Array<object>} input.registry every project the API has (GET /api/projects)
+ * @param {Record<string, {repo?: string}>} input.configProjects the config's `swarm.projects`
+ * @param {(a: string, b: string) => boolean} [input.samePath] injected: realpath is I/O
+ */
+function planWrite({ slug, repo, payload, registry, configProjects, samePath = (a, b) => a === b }) {
+  // This repo is already SOMEONE ELSE's project. Carrying on would give one directory two crux
+  // projects, two leads, and two streams — and the second lead would look, to everything downstream,
+  // exactly as legitimate as the first. This is the refusal that makes "run it twice" safe even when
+  // the second run answers the name prompt differently.
+  for (const [other, entry] of Object.entries(configProjects ?? {})) {
+    if (other === slug || typeof entry?.repo !== 'string') continue;
+    if (!samePath(entry.repo, repo)) continue;
+    return {
+      refusal:
+        `${repo} is already the crux project "${other}" (swarm.projects.${other}.repo in the config), ` +
+        `so discovering it as "${slug}" would give one repo two projects and two leads.\n` +
+        `       To edit that project instead: crux discover ${repo} --slug ${other}\n` +
+        `       To really move it: remove swarm.projects.${other} from the config first.`,
+    };
+  }
+
+  const declared = configProjects?.[slug]?.repo;
+
+  // The slug is taken, by a repo that is not this one. The project may be perfectly healthy — it is
+  // the NAME that collides — so the fix is a different slug, not a different repo.
+  if (typeof declared === 'string' && !samePath(declared, repo)) {
+    const existing = registry.find((p) => p.slug === slug);
+    return {
+      refusal:
+        `the slug "${slug}"${existing ? ` (the crux project "${existing.name}")` : ''} already has a ` +
+        `lead running in ${declared}, which is not ${repo}.\n` +
+        `       Pick another slug:  crux discover ${repo} --slug <other-slug>\n` +
+        `       Or, if the project really moved, point swarm.projects.${slug}.repo at the new path.`,
+    };
+  }
+
+  const existing = registry.find((p) => p.slug === slug) ?? null;
+  const changed = changedFields(existing, payload);
+
+  return {
+    refusal: null,
+    existing,
+    changed,
+    project: !existing ? 'create' : changed.length ? 'update' : 'unchanged',
+    config: typeof declared !== 'string' ? 'add' : 'unchanged',
+  };
+}
+
+/**
+ * Add (or correct) one project's repo in the leads config, in place, preserving everything else.
+ *
+ * The shape is not invented here — it is read back out by `swarmCandidates()` in crux.js as
+ * `config.swarm.projects[slug].repo`, tilde-expanded, and handed to the backend as the lead's
+ * working directory. The two are tested against each other (test/discover.test.js) precisely so they
+ * cannot drift: a config discover writes that swarm cannot read is a `swarm up` that says "no repo
+ * path for acme" about a repo the user just typed in.
+ *
+ * `brief` (extra lead context) is a sibling key a human may have hand-written, so it is preserved.
+ */
+function mergeConfig(config, slug, repo) {
+  const next = { ...config };
+  next.swarm = { ...(next.swarm ?? {}) };
+  next.swarm.projects = { ...(next.swarm.projects ?? {}) };
+  next.swarm.projects[slug] = { ...(next.swarm.projects[slug] ?? {}), repo };
+  return next;
+}
+
+/**
+ * Write down the backend crux worked out for itself — and NOTHING the user already stated.
+ *
+ * `crux swarm up` on a fresh machine used to be a coin flip: the shipped config said `solo`, most
+ * strangers do not run Solo, and the ones who fell through to `exec` got "the exec backend needs a
+ * command template" one command after discover had cheerfully told them to run it. So discover now
+ * settles it — but settling it in memory would be no better than the old default. The value has to
+ * land in the file, where the user can READ what their leads are started with and change it.
+ *
+ * Every key here is one {@see ../lib/orchestrator.resolveBackend} has already established is ABSENT
+ * (it only ever reports what it had to derive), and the guard below is the second lock on the same
+ * door: a `swarm.backend` or a `swarm.exec.command` a human typed is theirs, and a "helpful" tool
+ * that rewrites it has taken their orchestrator away from them without asking.
+ */
+function mergeBackend(config, writes) {
+  if (!writes || Object.keys(writes).length === 0) return config;
+
+  const next = { ...config };
+  next.swarm = { ...(next.swarm ?? {}) };
+  let touched = false;
+
+  if (typeof writes.backend === 'string' && typeof next.swarm.backend !== 'string') {
+    next.swarm.backend = writes.backend;
+    touched = true;
+  }
+
+  // The templates are a PAIR — `command` forks, `stop` is how you name what it forked into — so they
+  // are written together or not at all. Half a pair is the dead-pid refusal in `planDown`.
+  if (writes.exec && typeof next.swarm.exec?.command !== 'string') {
+    next.swarm.exec = { ...(next.swarm.exec ?? {}), ...writes.exec };
+    touched = true;
+  }
+
+  return touched ? next : config;
+}
+
+/** `/Users/you/src/acme` → `~/src/acme`, for output a human reads. */
+function tildify(file, home) {
+  if (typeof file !== 'string' || typeof home !== 'string' || home === '') return file;
+  return file === home || file.startsWith(`${home}${path.sep}`) ? `~${file.slice(home.length)}` : file;
+}
+
+module.exports = {
+  MAX_KEYWORDS,
+  PALETTE,
+  STOPWORDS,
+  changedFields,
+  colorFor,
+  describe,
+  deriveDisplayName,
+  deriveKeywords,
+  deriveName,
+  detectStack,
+  titleCase,
+  mergeBackend,
+  mergeConfig,
+  ownerFromRemote,
+  planWrite,
+  projectPayload,
+  readmeTitle,
+  repoFromRemote,
+  slugify,
+  tildify,
+  unscope,
+};