afterimage-cli 0.0.0-stage → 0.1.1

package/src/cli/commands/init.js

@@ -0,0 +1,307 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { configName, readConfig, writeConfig } from '../config.js';
+import { detectProject } from '../detect.js';
+import { dependsOn, planNetlify, planVercel } from '../hosts.js';
+import { parseJson, readJsonText, readText, writer } from '../project-files.js';
+
+export const usage = 'afterimage init [--source <folder>] [--build "<command>"] [--agent claude|cursor] [--no-input]';
+export const summary = 'Set up Afterimage in this project: config, scripts, git rules and host config.';
+// What both "afterimage init --help" and "afterimage help init" print.
+export const help = `Usage: ${usage}\n\n${summary}\n\n  --source <folder>      the folder that holds the prototype, or that your build writes to\n  --build "<command>"    the command that builds it, when there is one\n  --agent claude|cursor  also copy Afterimage's skill (Claude Code) or rule (Cursor) into this project\n  --no-input             ask nothing, even in a terminal, and print what is left to do instead\n`;
+// Read by the docs tests, which check every flag the agent files name.
+export const options = { source: { type: 'string' }, build: { type: 'string' }, agent: { type: 'string' }, 'no-input': { type: 'boolean' }, help: { type: 'boolean', short: 'h' } };
+
+const scripts = {
+  'afterimage:save': 'afterimage save',
+  'afterimage:dev': 'afterimage dev',
+  'afterimage:build': 'afterimage build'
+};
+
+// The skill and the Cursor rule the package ships, found from this file so they work from node_modules and a checkout.
+const packagedAgentsDir = fileURLToPath(new URL('../../../agents/', import.meta.url));
+
+// Where each agent reads Afterimage's instructions from. Init only writes there when --agent asks it to.
+const agents = {
+  claude: { from: 'skill', to: '.claude/skills/afterimage', what: 'skill', loads: 'Claude Code loads the skill in a new session, or after /reload-skills.' },
+  cursor: { from: 'cursor/afterimage.mdc', to: '.cursor/rules/afterimage.mdc', what: 'rule', loads: null }
+};
+
+const skillHint = [
+  'To let your coding agent save and compare versions, run one of:',
+  ...Object.entries(agents).map(([name, agent]) => `  npx afterimage init --agent ${name}   copies the ${agent.what} to ${agent.to}${agent.what === 'skill' ? '/' : ''}`)
+].join('\n');
+
+const nextStep = 'Next: npx afterimage save "First version"';
+
+async function isFolder(file) {
+  try {
+    return (await fs.stat(file)).isDirectory();
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+// package.json keeps its own look (indent, line ending, final newline) so the diff in git is only the keys we add.
+function writePackageText(original, value) {
+  const indent = original?.match(/^([ \t]+)"/m)?.[1] ?? '  ';
+  const eol = original?.includes('\r\n') ? '\r\n' : '\n';
+  const text = JSON.stringify(value, null, indent).replace(/\n/g, eol);
+  return original === null || /\n$/.test(original) ? text + eol : text;
+}
+
+// The code Node's own aborted prompts use. An ask function rejects with it when the user cancels.
+const abortCode = 'ABORT_ERR';
+
+// Reads one answer from the terminal. A closed stdin (Ctrl-D, EOF) counts as no answer instead of hanging, and
+// Ctrl-C aborts the whole init. Tests pass their own ctx.ask.
+async function askInTerminal(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const closed = new Promise(resolve => rl.once('close', () => resolve('')));
+  const interrupted = new Promise((_, reject) => rl.once('SIGINT', () => reject(Object.assign(new Error('Prompt cancelled.'), { code: abortCode }))));
+  try {
+    return await Promise.race([rl.question(`${question} `), closed, interrupted]);
+  } finally {
+    rl.close();
+  }
+}
+
+const needSource = reason => new Error(`${reason}\nSay where the prototype is: afterimage init --source <folder>\nAdd --build "<command>" if a build command produces that folder.`);
+
+// Decides source, build and type for a fresh config. Flags win over detection. A given source keeps detection's type
+// when it names the same folder; otherwise the type is 'plain' for a folder of static files (no build) and 'unknown'
+// when a custom build produces it.
+async function chooseSetup(cwd, flags, { isTTY, ask }) {
+  const detection = await detectProject(cwd);
+  // What would give the project a static build to save. For Astro with @astrojs/vercel that is only about saving: the
+  // adapter still writes .vercel/output, so deploying the history on Vercel needs it removed too (planVercel says so).
+  const serverFix = {
+    'next-server': "output: 'export' in next.config",
+    'astro-server': await dependsOn(cwd, '@astrojs/vercel')
+      ? "output: 'static' in the astro config (to save its static build; the history can only deploy on Vercel without @astrojs/vercel)"
+      : "output: 'static' in the astro config",
+    'sveltekit-server': 'the adapter in svelte.config to @sveltejs/adapter-static (npm install -D @sveltejs/adapter-static)'
+  }[detection.type];
+  if (serverFix && !flags.source) {
+    throw new Error(`${detection.reason}\nSet ${serverFix} and run "afterimage init" again, or pass --source <folder> if a build writes static files somewhere else.`);
+  }
+  let source = flags.source;
+  if (!source && detection.source === null) {
+    if (!isTTY) throw needSource(detection.reason);
+    source = (await ask('Which folder holds your prototype, or which folder does your build write to?')).trim();
+    if (!source) throw needSource(detection.reason);
+  }
+  if (!source) {
+    return { source: detection.source, build: flags.build ?? detection.build, type: detection.type };
+  }
+  source = projectRelative(cwd, source);
+  const matches = detection.source !== null && source === projectRelative(cwd, detection.source);
+  const build = flags.build ?? (matches ? detection.build : null);
+  return { source, build, type: matches ? detection.type : build ? 'unknown' : 'plain' };
+}
+
+// Forward slashes, relative to the project, '.' for the project root. Anything outside the project is refused.
+function projectRelative(cwd, folder) {
+  const relative = path.relative(cwd, path.resolve(cwd, folder)).replace(/\\/g, '/');
+  if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative)) {
+    throw new Error(`${folder} is outside this project. Pick a folder inside it.`);
+  }
+  return relative || '.';
+}
+
+// Every step is split in two. A plan only reads and asks, and returns { change, notes, apply }. Nothing is written
+// until every plan has succeeded, so a bad input leaves the project exactly as it was.
+
+async function planConfig(cwd, flags, ctx) {
+  const before = await readText(path.join(cwd, configName));
+  if (before !== null && !flags.source && flags.build === undefined) {
+    return { config: await readConfig(cwd), change: null, notes: [], apply: null };
+  }
+  const existing = before === null ? null : await readConfig(cwd);
+  let config;
+  if (existing) {
+    config = { ...existing, source: flags.source ? projectRelative(cwd, flags.source) : existing.source, build: flags.build ?? existing.build };
+  } else {
+    const chosen = await chooseSetup(cwd, flags, ctx);
+    config = { source: projectRelative(cwd, chosen.source), build: chosen.build, history: 'afterimage', out: '.afterimage/site', exclude: [], type: chosen.type };
+  }
+  if (!config.build && !await isFolder(path.resolve(cwd, config.source))) {
+    throw new Error(`${config.source} does not exist yet. If a build creates it, run init again with --build "<command>"; otherwise check the folder name.`);
+  }
+  if (existing && existing.source === config.source && existing.build === config.build) {
+    return { config, change: null, notes: [], apply: null };
+  }
+  const detail = `source ${config.source}${config.build ? `, build "${config.build}"` : ''}`;
+  return {
+    config,
+    change: `${existing ? 'Updated' : 'Created'} ${configName} (${detail})`,
+    notes: [],
+    apply: () => writeConfig(cwd, config)
+  };
+}
+
+async function planPackage(cwd) {
+  const file = path.join(cwd, 'package.json');
+  const { bom, body: before } = await readJsonText(file);
+  const manifest = before === null ? { private: true, scripts: {} } : parseJson(before, 'package.json');
+  if (manifest.scripts !== undefined && (!manifest.scripts || typeof manifest.scripts !== 'object' || Array.isArray(manifest.scripts))) {
+    throw new Error('package.json "scripts" must be an object.\nFix it, then run "afterimage init" again.');
+  }
+  const existing = manifest.scripts ?? {};
+  const added = Object.keys(scripts).filter(name => !Object.hasOwn(existing, name));
+  const notes = [];
+  if (Object.hasOwn(existing, 'afterimage:build') && existing['afterimage:build'] !== scripts['afterimage:build']) {
+    notes.push(`package.json already has "afterimage:build": "${existing['afterimage:build']}". The host config runs that script, so it should be "${scripts['afterimage:build']}".`);
+  }
+  if (!added.length) return { change: null, notes, apply: null };
+  manifest.scripts = { ...existing, ...Object.fromEntries(added.map(name => [name, scripts[name]])) };
+  const what = `added ${plural(added.length, 'script')}`;
+  return {
+    change: `${before === null ? 'Created' : 'Updated'} package.json (${what})`,
+    notes,
+    apply: writer(file, bom + writePackageText(before, manifest))
+  };
+}
+
+// Adds each line that is not already there, in the file's own line ending.
+async function planLines(cwd, name, lines, isPresent) {
+  const file = path.join(cwd, name);
+  const before = await readText(file);
+  const present = (before ?? '').split(/\r?\n/);
+  const added = lines.filter(line => !present.some(existing => isPresent(existing, line)));
+  if (!added.length) return { change: null, notes: [], apply: null };
+  const eol = before?.includes('\r\n') ? '\r\n' : '\n';
+  const gap = before && !/\n$/.test(before) ? eol : '';
+  return {
+    change: before === null ? `Created ${name}` : `Updated ${name} (added ${added.join(', ')})`,
+    notes: [],
+    apply: writer(file, `${before ?? ''}${gap}${added.join(eol)}${eol}`)
+  };
+}
+
+// A rule counts as present when the pattern is there with -text, however the rest of the line reads.
+const hasTextRule = (existing, rule) => {
+  const [pattern] = rule.split(' ');
+  const tokens = existing.trim().split(/\s+/);
+  return tokens[0] === pattern && tokens.includes('-text');
+};
+const stripSlashes = line => line.trim().replace(/^\/+|\/+$/g, '');
+const hasIgnore = (existing, line) => stripSlashes(existing) === stripSlashes(line);
+
+// Every file of the package's copy for this agent, as [package path, project path], forward slashes.
+async function agentFiles({ from, to }) {
+  const source = path.join(packagedAgentsDir, from);
+  if (!(await fs.stat(source)).isDirectory()) return [[from, to]];
+  const names = (await fs.readdir(source, { recursive: true, withFileTypes: true })).filter(entry => entry.isFile());
+  return names.map(entry => {
+    const relative = path.relative(source, path.join(entry.parentPath, entry.name)).replace(/\\/g, '/');
+    return [`${from}/${relative}`, `${to}/${relative}`];
+  }).sort(([a], [b]) => (a < b ? -1 : 1));
+}
+
+// A checkout with autocrlf can turn the copy's line endings, which is still the same copy, so it is not asked about.
+const sameText = (a, b) => a.replace(/\r\n/g, '\n') === b.replace(/\r\n/g, '\n');
+
+async function planAgent(cwd, name, { isTTY, ask }) {
+  if (!name) return { change: null, notes: [], apply: null };
+  const changes = [];
+  const notes = [];
+  const writes = [];
+  for (const [from, to] of await agentFiles(agents[name])) {
+    const text = await fs.readFile(path.join(packagedAgentsDir, from), 'utf8');
+    const before = await readText(path.join(cwd, to));
+    if (before !== null && sameText(before, text)) continue;
+    if (before !== null) {
+      // The file is the person's now; they may have edited it.
+      const agreed = isTTY && /^y(es)?$/i.test((await ask(`${to} differs from Afterimage's copy. Replace it? (y/N)`)).trim());
+      if (!agreed) {
+        notes.push(`${to} differs from Afterimage's copy, so Afterimage left it as it is. To replace it, run "npx afterimage init --agent ${name}" in a terminal and answer y.`);
+        continue;
+      }
+    }
+    changes.push(`${before === null ? 'Created' : 'Updated'} ${to}`);
+    writes.push([path.join(cwd, to), text]);
+  }
+  return {
+    change: changes.join('\n') || null,
+    notes,
+    apply: writes.length ? async () => {
+      for (const [file, text] of writes) {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, text);
+      }
+    } : null
+  };
+}
+
+export async function run(args, ctx) {
+  const { cwd, stdout, stderr } = ctx;
+
+  let parsed;
+  try {
+    parsed = parseArgs({ args, options });
+  } catch (error) {
+    if (!error.code?.startsWith('ERR_PARSE_ARGS')) throw error;
+    stderr.write(`${error.message}\nUsage: ${usage}\n`);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(help);
+    return 0;
+  }
+  const flags = { source: parsed.values.source, build: parsed.values.build };
+  if (flags.source !== undefined && !flags.source.trim()) {
+    stderr.write(`--source needs a folder.\nUsage: ${usage}\n`);
+    return 2;
+  }
+  const agent = parsed.values.agent;
+  if (agent !== undefined && !Object.hasOwn(agents, agent)) {
+    stderr.write(`--agent needs claude or cursor.\nUsage: ${usage}\n`);
+    return 2;
+  }
+  // Prompts only happen with a real terminal. An agent's terminal can look like one, so --no-input rules them out.
+  // Tests inject both pieces.
+  const isTTY = !parsed.values['no-input'] && (ctx.isTTY ?? Boolean(process.stdin.isTTY));
+  const prompt = { isTTY, ask: ctx.ask ?? askInTerminal };
+
+  // Plan first, write after. package.json is read before the config step so a bad one stops init before any question,
+  // and detection (which reads package.json) still sees the project as it was.
+  let plans;
+  try {
+    const packagePlan = await planPackage(cwd);
+    const configPlan = await planConfig(cwd, flags, prompt);
+    plans = [
+      configPlan,
+      packagePlan,
+      await planLines(cwd, '.gitattributes', [`${configPlan.config.history}/** -text`], hasTextRule),
+      // The save's lock and stage folders too, which a killed save can leave in the history folder.
+      await planLines(cwd, '.gitignore', ['.afterimage/', `${configPlan.config.history}/.afterimage-*`, 'node_modules/'], hasIgnore),
+      await planVercel(cwd, prompt),
+      await planNetlify(cwd),
+      await planAgent(cwd, agent, prompt)
+    ];
+  } catch (error) {
+    // Ctrl-C at a prompt. Nothing has been written yet, so stopping here is clean. 130 is the shell's code for SIGINT.
+    if (error?.code !== abortCode) throw error;
+    stderr.write('Stopped. Nothing was changed.\n');
+    return 130;
+  }
+  for (const plan of plans) await plan.apply?.();
+
+  const changes = plans.map(plan => plan.change).filter(Boolean);
+  const notes = plans.flatMap(plan => plan.notes);
+
+  if (changes.length) stdout.write(`${changes.join('\n')}\n`);
+  else stdout.write(notes.length ? 'No files changed. Still left for you:\n' : 'Everything is already set up. Nothing changed.\n');
+  if (notes.length) stdout.write(`${changes.length ? '\n' : ''}${notes.join('\n\n')}\n`);
+  // With --agent the copy is in place, and a fresh one needs loading; without it, say how to add it.
+  const agentLine = agent ? plans.at(-1).change && agents[agent].loads : skillHint;
+  stdout.write(`\n${agentLine ? `${agentLine}\n` : ''}${nextStep}\n`);
+  return 0;
+}

package/src/cli/commands/save.js

@@ -0,0 +1,60 @@
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { readConfig, sourceExcludes } from '../config.js';
+import { saveVersion } from '../history.js';
+import { runBuild } from '../run-build.js';
+
+export const usage = 'afterimage save "Name" [--note "..."]';
+export const summary = 'Build the prototype and save it as the next version.';
+// What both "afterimage save --help" and "afterimage help save" print.
+export const help = `Usage: ${usage}\n\n${summary}\n\n  --note "..."  a note on the version, up to 500 characters; repeat it for more than one\n`;
+// Read by the docs tests, which check every flag the agent files name.
+export const options = { note: { type: 'string', multiple: true }, help: { type: 'boolean', short: 'h' } };
+
+export async function run(args, { cwd, stdout, stderr, buildStdio, largeHistory = 100_000_000 }) {
+  let parsed;
+  try {
+    parsed = parseArgs({ args, allowPositionals: true, options });
+  } catch (error) {
+    if (!error.code?.startsWith('ERR_PARSE_ARGS')) throw error;
+    stderr.write(`${error.message}\nUsage: ${usage}\n`);
+    return 2;
+  }
+  if (parsed.values.help) {
+    stdout.write(help);
+    return 0;
+  }
+  const [name, ...extra] = parsed.positionals;
+  if (!name || extra.length) {
+    stderr.write(`${extra.length ? 'Save takes one name. Put it in quotes.' : 'Save needs a name for the version.'}\nUsage: ${usage}\n`);
+    return 2;
+  }
+
+  const config = await readConfig(cwd);
+  if (config.build) await runBuild(config.build, cwd, { stdio: buildStdio });
+  const { version, unchanged, bytes, history } = await saveVersion(
+    { historyDir: path.resolve(cwd, config.history), sourceDir: path.resolve(cwd, config.source), exclude: await sourceExcludes(cwd, config) },
+    { name, notes: parsed.values.note ?? [] }
+  );
+  if (unchanged) {
+    stdout.write(`Nothing changed since ${version.id} "${version.name}". Nothing was saved.\n`);
+    return 0;
+  }
+  stdout.write(`Saved ${version.id} "${version.name}".\n`);
+  stdout.write(`${version.id} adds ${formatSize(bytes)}. History: ${history.versions} ${history.versions === 1 ? 'version' : 'versions'}, ${formatSize(history.bytes)}.\n`);
+  // Every version is a full copy and every deploy carries all of them, so growth is said out loud rather than capped.
+  if (history.bytes >= largeHistory) {
+    stdout.write(`The history is ${formatSize(history.bytes)}, and every deploy carries all of it. Large images and video are the usual cause: ${sizeDocs}\n`);
+  }
+  return 0;
+}
+
+export const sizeDocs = 'https://github.com/uxlucas/Afterimage/blob/main/docs/limits.md#history-size';
+
+// Decimal units, as macOS Finder and npm count them.
+export function formatSize(bytes) {
+  if (bytes < 1000) return `${bytes} ${bytes === 1 ? 'byte' : 'bytes'}`;
+  if (bytes < 999_500) return `${Math.round(bytes / 1000)} KB`;
+  if (bytes < 999_950_000) return `${(bytes / 1_000_000).toFixed(1)} MB`;
+  return `${(bytes / 1_000_000_000).toFixed(1)} GB`;
+}

package/src/cli/config.js

@@ -0,0 +1,88 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export const configName = 'afterimage.config.json';
+
+const defaults = { source: '.', build: null, history: 'afterimage', out: '.afterimage/site', exclude: [], type: 'unknown' };
+
+// Names that are the project's own files, not the prototype. They only matter when the prototype is the project root.
+// The host configs are the ones init writes, and the lockfiles are every package manager's.
+const projectNames = [
+  'node_modules', 'afterimage', '.afterimage', 'package.json', 'package-lock.json', configName, 'vercel.json', 'netlify.toml',
+  'npm-shrinkwrap.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'
+];
+// And the project's own docs next to them: a README, a LICENSE, a CHANGELOG, a CONTRIBUTING guide and an agent's
+// instructions (CLAUDE.md, AGENTS.md, GEMINI.md), as files, in any case, bare or with a text extension. Left in, they
+// would be saved into every version and published at the live root. A page or a folder with one of these names
+// (license.html, agents/) can be part of the prototype, so it stays.
+const projectDoc = /^(readme|license|changelog|contributing|claude|agents|gemini)(\.(md|markdown|txt|rst))?$/i;
+
+// Same shape readSnapshot expects: forward slashes, no leading ./, no trailing slash. "x/../site" is "site" and "src/.." is ".".
+const cleanPath = value => {
+  const cleaned = path.posix.normalize(value.replace(/\\/g, '/')).replace(/\/+$/, '').replace(/^\.\//, '');
+  return cleaned || '.';
+};
+
+// Afterimage only works inside the project, so an absolute path or one that climbs out of it is a mistake.
+const leavesProject = cleaned => cleaned.startsWith('/') || /^[a-zA-Z]:/.test(cleaned) || cleaned === '..' || cleaned.startsWith('../');
+
+function validate(raw) {
+  const fail = problem => { throw new Error(`${configName} ${problem}.`); };
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) fail('must be a JSON object');
+  const config = { ...defaults, ...raw };
+  for (const key of ['source', 'history', 'out']) {
+    if (typeof config[key] !== 'string' || !config[key]) fail(`needs "${key}" to be a non-empty string`);
+  }
+  if (config.build !== null && typeof config.build !== 'string') fail('needs "build" to be a string or null');
+  if (typeof config.type !== 'string') fail('needs "type" to be a string');
+  if (!Array.isArray(config.exclude) || config.exclude.some(entry => typeof entry !== 'string')) fail('needs "exclude" to be a list of strings');
+  const [source, history, out] = ['source', 'history', 'out'].map(key => {
+    const cleaned = cleanPath(config[key]);
+    if (leavesProject(cleaned)) fail(`needs "${key}" to be a folder inside the project, not an absolute path or one that starts with ".."`);
+    return cleaned;
+  });
+  return { source, build: config.build, history, out, exclude: [...config.exclude], type: config.type };
+}
+
+export async function readConfig(projectDir) {
+  let text;
+  try {
+    text = await fs.readFile(path.join(projectDir, configName), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') throw new Error(`No ${configName} here. Run "afterimage init" first.`);
+    throw error;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${configName} is not valid JSON: ${error.message}`);
+  }
+  return validate(raw);
+}
+
+export async function writeConfig(projectDir, config) {
+  await fs.writeFile(path.join(projectDir, configName), `${JSON.stringify(validate(config), null, 2)}\n`);
+}
+
+// What the store leaves out when the prototype is the project root. A build folder has none of the project-level
+// names inside it, so only the user's own excludes apply there, plus the history and out folders if a hand-written
+// config puts them inside it. rootFiles are the files (not folders) at the top of the project as they are spelled on
+// disk, so the docs among them are left out by their own spelling.
+export function projectExcludes(config, rootFiles = []) {
+  const source = cleanPath(config.source);
+  if (source !== '.' && source !== '') {
+    const inside = [config.history, config.out].map(cleanPath).filter(dir => dir.startsWith(`${source}/`));
+    return [...new Set([...inside.map(dir => dir.slice(source.length + 1)), ...config.exclude])];
+  }
+  const docs = rootFiles.filter(name => projectDoc.test(name));
+  return [...new Set([...projectNames, ...docs, config.history, config.out, ...config.exclude].map(cleanPath))];
+}
+
+// projectExcludes for the project as it is on disk now.
+export async function sourceExcludes(projectDir, config) {
+  const atRoot = cleanPath(config.source) === '.';
+  if (!atRoot) return projectExcludes(config);
+  const entries = await fs.readdir(path.resolve(projectDir, config.source), { withFileTypes: true });
+  return projectExcludes(config, entries.filter(entry => entry.isFile()).map(entry => entry.name));
+}

package/src/cli/detect.js

@@ -0,0 +1,96 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const found = (type, source, build, reason) => ({ type, source, build, reason });
+const unknown = reason => found('unknown', null, null, reason);
+
+async function readText(file) {
+  try {
+    // A byte order mark (common from Windows editors) would make a valid package.json fail JSON.parse.
+    return (await fs.readFile(file, 'utf8')).replace(/^/, '');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// Framework configs are code, so they are only searched as text and never run.
+async function readFirst(projectDir, names) {
+  for (const name of names) {
+    const text = await readText(path.join(projectDir, name));
+    if (text !== null) return text;
+  }
+  return null;
+}
+
+// wrapped: the folder has a package.json that only holds afterimage-cli (see detectProject).
+async function detectPlain(projectDir, wrapped = false) {
+  const entries = await fs.readdir(projectDir, { withFileTypes: true });
+  if (entries.some(entry => entry.isFile() && entry.name === 'index.html')) {
+    return found('plain', '.', null, 'Found index.html at the top of this folder; it is the prototype.');
+  }
+  const folders = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    if (await readText(path.join(projectDir, entry.name, 'index.html')) !== null) folders.push(entry.name);
+  }
+  if (folders.length === 1) return found('plain', folders[0], null, `Found index.html in ${folders[0]}/; it is the prototype.`);
+  if (folders.length > 1) return unknown(`Found index.html in ${folders.length} folders (${folders.join(', ')}), so there is no single prototype folder.`);
+  return unknown(wrapped ? 'Found a package.json with no framework and no build, and no index.html here.' : 'Found no package.json and no index.html here.');
+}
+
+// Astro's own server adapters, named in the message when the project depends on one.
+const astroAdapters = ['@astrojs/vercel', '@astrojs/node', '@astrojs/netlify', '@astrojs/cloudflare'];
+
+export async function detectProject(projectDir) {
+  const packageText = await readText(path.join(projectDir, 'package.json'));
+  if (packageText === null) return detectPlain(projectDir);
+
+  let manifest;
+  try {
+    manifest = JSON.parse(packageText);
+  } catch {
+    return unknown('package.json is not valid JSON, so the framework could not be read.');
+  }
+  const dependencies = { ...manifest?.dependencies, ...manifest?.devDependencies };
+  const has = name => name in dependencies;
+
+  if (has('next')) {
+    const config = await readFirst(projectDir, ['next.config.js', 'next.config.mjs', 'next.config.cjs', 'next.config.ts', 'next.config.mts']);
+    if (config !== null && /\boutput\s*:\s*['"`]export['"`]/.test(config)) {
+      return found('next-static', 'out', 'npm run build', "Found next with output: 'export'; it builds to out/.");
+    }
+    return found('next-server', null, null, "Found next without output: 'export' in next.config, so it needs a server and has no static build to save.");
+  }
+  if (has('@sveltejs/kit')) {
+    // Every other adapter (adapter-auto, -node, -vercel, -netlify) builds for a server, so there is nothing to save.
+    if (!has('@sveltejs/adapter-static')) {
+      return found('sveltekit-server', null, null, 'Found SvelteKit without @sveltejs/adapter-static, so it has no static build to save.');
+    }
+    const config = await readFirst(projectDir, ['svelte.config.js', 'svelte.config.mjs', 'svelte.config.cjs', 'svelte.config.ts']);
+    const pages = config?.match(/\bpages\s*:\s*['"`]([^'"`]+)['"`]/)?.[1] ?? 'build';
+    return found('sveltekit-static', pages, 'npm run build', `Found SvelteKit with adapter-static; it builds to ${pages}/.`);
+  }
+  if (has('astro')) {
+    // An adapter (@astrojs/vercel, -node, -netlify, -cloudflare, or any other in the config) builds for a server: unless
+    // the config says output: 'static', there is no dist/ of plain pages to save. With output: 'static' the pages are in
+    // dist/ and can be saved. That is all it settles for @astrojs/vercel: it still writes .vercel/output on every build,
+    // which Vercel deploys in place of the Afterimage site (init says so).
+    const config = (await readFirst(projectDir, ['astro.config.mjs', 'astro.config.js', 'astro.config.cjs', 'astro.config.ts', 'astro.config.mts'])) ?? '';
+    const named = astroAdapters.find(has);
+    const inConfig = /\badapter\s*:/.test(config);
+    const serverOutput = /\boutput\s*:\s*['"`]server['"`]/.test(config);
+    if ((named || inConfig || serverOutput) && !/\boutput\s*:\s*['"`]static['"`]/.test(config)) {
+      const reason = named ? `Found astro with ${named}, a server adapter, without output: 'static' in the astro config`
+        : inConfig ? "Found an adapter in the astro config, which builds for a server, without output: 'static'"
+          : "Found astro with output: 'server' in the astro config";
+      return found('astro-server', null, null, `${reason}, so it has no static build to save.`);
+    }
+    return found('astro', 'dist', 'npm run build', 'Found astro in package.json; it builds to dist/.');
+  }
+  if (has('vite')) return found('vite', 'dist', 'npm run build', 'Found vite in package.json; it builds to dist/.');
+  // A plain HTML folder gets a package.json from the setup prompt (npm init -y, then the install). One that holds
+  // nothing but afterimage-cli and has no build is still that folder, so it is read the way a folder without one is.
+  if (Object.keys(dependencies).every(name => name === 'afterimage-cli') && !manifest?.scripts?.build) return detectPlain(projectDir, true);
+  return unknown('Found a package.json, but no framework Afterimage recognises (vite, next, astro or SvelteKit).');
+}

package/src/cli/errors.js

@@ -0,0 +1,5 @@
+// Errors the user can act on (a bad name, a lock, a failed build) print as one message. These built-in types mean a
+// bug in Afterimage itself, so they keep their stack for the bug report.
+const programmerErrors = [TypeError, ReferenceError, SyntaxError, RangeError, EvalError];
+
+export const isUserError = error => error instanceof Error && !programmerErrors.some(type => error instanceof type);