afterimage-cli 0.0.0-stage → 0.1.1

package/src/cli/history.js

@@ -0,0 +1,232 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { validateManifest } from '../engine/manifest.js';
+import { injectFrameScript } from '../runtime/map.js';
+import { retryLocked } from './retry.js';
+
+// Finder, Explorer and macOS file copies leave these in any folder they touch. They are never part of a
+// prototype, so they are skipped rather than saved or treated as an error.
+export const isSystemFile = name => ['.DS_Store', 'Thumbs.db', 'desktop.ini'].includes(name) || name.startsWith('._');
+
+// An exclude is a path relative to the folder being read. It matches that file, or anything under that folder.
+const isExcluded = (relative, exclude) => exclude.some(entry => relative === entry || relative.startsWith(`${entry}/`));
+const cleanExclude = entry => entry.replace(/^\.\//, '').replace(/\/+$/, '');
+
+// Every file under directory, by forward-slash path in name order, minus OS clutter, excludes and whatever
+// skip(name, entry) leaves out. skip may also throw, to refuse a file outright.
+async function readFiles(directory, exclude, skip) {
+  const excluded = exclude.map(cleanExclude);
+  const files = new Map();
+  async function visit(relative = '') {
+    const folder = path.join(directory, relative);
+    if (!(await fs.lstat(folder)).isDirectory()) throw new Error(`Expected a regular directory: ${folder}`);
+    for (const entry of (await fs.readdir(folder, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const name = relative ? `${relative}/${entry.name}` : entry.name;
+      // Excludes come first so a project can leave out a folder (a linked node_modules, say) without it being inspected.
+      if (isSystemFile(entry.name) || isExcluded(name, excluded) || skip(name, entry)) continue;
+      if (entry.isSymbolicLink()) throw new Error(`Remove the link from the public prototype, or add it to exclude: ${name}`);
+      if (entry.isDirectory()) await visit(name);
+      else if (entry.isFile()) files.set(name, await fs.readFile(path.join(directory, name)));
+      else throw new Error(`Not a regular file or folder: ${name}. Add it to exclude if it is not part of the prototype.`);
+    }
+  }
+  await visit();
+  if (!files.has('index.html')) throw new Error(`Missing index.html in ${directory}`);
+  return files;
+}
+
+// What a saved version keeps: every file the prototype has, whatever its type, except hidden files and folders (an
+// .env, a .git) and source maps, which are build output nobody browses in a saved version.
+// Strict is for saved snapshots: anything save would have skipped means the folder was edited after saving, and a
+// deploy copying it would publish that file.
+export function readSnapshot(directory, { exclude = [], strict = false } = {}) {
+  return readFiles(directory, exclude, (name, entry) => {
+    const hidden = entry.name.startsWith('.');
+    if (!hidden && !(entry.isFile() && path.extname(name).toLowerCase() === '.map')) return false;
+    if (strict) throw new Error(`Unexpected ${hidden ? 'hidden file' : 'file'} in a saved version: ${name}`);
+    return true;
+  });
+}
+
+// What the live root gets: the app's own output as it is, source maps, dotfiles and host files (_redirects,
+// .well-known/) included, because the app's own build ships them. A repository or installed packages are never site
+// files. A plain folder (the project root, or any folder no build writes) also holds hidden files of its own (.env,
+// .gitignore, .vscode/), which must never go public, so there only .well-known/ is kept.
+export function readApp(directory, { exclude = [], plain = false } = {}) {
+  return readFiles(directory, exclude, (name, entry) => {
+    if (entry.isDirectory() && (entry.name === '.git' || entry.name === 'node_modules')) return true;
+    return plain && entry.name.startsWith('.') && name !== '.well-known';
+  });
+}
+
+export function fingerprint(files) {
+  const entries = [...files].map(([name, bytes]) => [name, createHash('sha256').update(bytes).digest('hex')]);
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex');
+}
+
+// Every saved page loads the frame runtime first, so a built app finds its files and its routes inside the viewer
+// (src/runtime/sw.js says how). latin1 turns each byte into one character and back, so only the inserted tag
+// changes. A UTF-16 page would be corrupted by single-byte text, so it is saved as it is. The entry page, index.html at
+// the top, is a page however bare it is.
+function withFrameScript(files, id) {
+  const isUtf16 = bytes => (bytes[0] === 0xff && bytes[1] === 0xfe) || (bytes[0] === 0xfe && bytes[1] === 0xff);
+  return new Map([...files].map(([name, bytes]) => [name, path.extname(name).toLowerCase() === '.html' && !isUtf16(bytes)
+    ? Buffer.from(injectFrameScript(bytes.toString('latin1'), id, name === 'index.html' ? { page: true } : undefined), 'latin1')
+    : bytes]));
+}
+
+const manifestPath = historyDir => path.join(historyDir, 'versions.json');
+
+// No versions.json means nothing has been saved yet, which is a normal state and not an error.
+export async function readHistory(historyDir) {
+  let text;
+  try {
+    text = await fs.readFile(manifestPath(historyDir), 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  return validateManifest(JSON.parse(text));
+}
+
+const snapshotBytes = files => [...files.values()].reduce((total, bytes) => total + bytes.length, 0);
+
+export async function verifyHistory(historyDir) {
+  return (await checkHistory(historyDir)).manifest;
+}
+
+// Checks every saved version against its fingerprint, and adds up their bytes on the way, which a save reports.
+async function checkHistory(historyDir) {
+  const manifest = await readHistory(historyDir);
+  let bytes = 0;
+  const versionsDir = path.join(historyDir, 'versions');
+  let directories = [];
+  try {
+    directories = await fs.readdir(versionsDir);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  const expected = new Set((manifest?.versions ?? []).map(version => version.id));
+  for (const name of directories) {
+    if (!expected.has(name) && !isSystemFile(name)) throw new Error(`Unlisted snapshot found at ${path.join(versionsDir, name)}. Resolve it before saving or deploying.`);
+  }
+  for (const version of manifest?.versions ?? []) {
+    const files = await readSnapshot(path.join(versionsDir, version.id), { strict: true });
+    if (fingerprint(files) !== version.sha256) {
+      throw new Error(`${version.id} has changed since it was saved. Restore its original files; saved versions are never edited.`);
+    }
+    bytes += snapshotBytes(files);
+  }
+  return { manifest, bytes };
+}
+
+const lockName = '.afterimage-save.lock';
+const stagePrefix = '.afterimage-stage-';
+const busy = () => new Error(`Another save is active. If it crashed, delete ${lockName} in the history folder once no save is running.`);
+
+// Whether the save that wrote a lock is still running. Only a lock this code wrote, naming a process that no longer
+// exists (ESRCH), counts as dead; anything else (unreadable, another user's process) is left to its owner.
+function holderAlive(text) {
+  let pid;
+  try {
+    pid = JSON.parse(text)?.pid;
+  } catch {
+    return true;
+  }
+  if (!Number.isSafeInteger(pid) || pid <= 0) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== 'ESRCH';
+  }
+}
+
+// One save at a time. A save that was killed (Ctrl-C, an agent's timeout) never reaches its cleanup and leaves its lock
+// and stage folder behind; once its process is gone, both are cleared and this save goes ahead.
+async function takeLock(historyDir, lockPath) {
+  try {
+    return await fs.open(lockPath, 'wx');
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+  }
+  if (holderAlive(await fs.readFile(lockPath, 'utf8').catch(() => ''))) throw busy();
+  for (const name of await fs.readdir(historyDir)) {
+    if (name.startsWith(stagePrefix)) await fs.rm(path.join(historyDir, name), { recursive: true, force: true });
+  }
+  await fs.rm(lockPath, { force: true });
+  try {
+    return await fs.open(lockPath, 'wx');
+  } catch (error) {
+    if (error.code === 'EEXIST') throw busy();
+    throw error;
+  }
+}
+
+export async function saveVersion({ historyDir, sourceDir, exclude = [] }, { name, notes = [] }) {
+  if (typeof name !== 'string' || !name.trim() || name.length > 120 ||
+      !Array.isArray(notes) || notes.some(note => typeof note !== 'string' || !note.trim() || note.length > 500)) {
+    throw new Error('Provide a version name up to 120 characters and notes up to 500 characters each.');
+  }
+  await fs.mkdir(historyDir, { recursive: true });
+  const lockPath = path.join(historyDir, lockName);
+  const lock = await takeLock(historyDir, lockPath);
+  const stage = path.join(historyDir, `${stagePrefix}${randomUUID()}`);
+  let destination;
+  let promoted = false;
+  let committed = false;
+  try {
+    await lock.writeFile(JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+    const checked = await checkHistory(historyDir);
+    const manifest = checked.manifest ?? { schemaVersion: 1, versions: [] };
+    const latest = manifest.versions[0];
+    const source = await readSnapshot(sourceDir, { exclude });
+    const sourceSha = fingerprint(source);
+    // The latest version's bytes carry its own id in the tag, so the same build is compared as it would have been
+    // saved then. A version saved without the runtime (Northwind) matches the source as it is.
+    if (latest && (fingerprint(withFrameScript(source, latest.id)) === latest.sha256 || sourceSha === latest.sha256)) {
+      return { version: latest, unchanged: true };
+    }
+    const number = latest ? Number(latest.id.slice(1)) + 1 : 1;
+    if (!Number.isSafeInteger(number)) throw new Error('Version number exceeds the supported range.');
+    const files = withFrameScript(source, `v${number}`);
+    const sha256 = fingerprint(files);
+    const version = {
+      id: `v${number}`, name: name.trim(), label: `Version ${number}`,
+      file: `versions/v${number}/index.html`, notes: notes.map(note => note.trim()),
+      savedAt: new Date().toISOString(), sha256,
+    };
+    const stagedSnapshot = path.join(stage, 'snapshot');
+    await fs.mkdir(stagedSnapshot, { recursive: true });
+    for (const [name, bytes] of files) {
+      const target = path.join(stagedSnapshot, name);
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, bytes, { flag: 'wx' });
+    }
+    if (fingerprint(await readSnapshot(sourceDir, { exclude })) !== sourceSha) {
+      throw new Error('The prototype changed during the save. Run the command again after editing stops.');
+    }
+    manifest.versions.unshift(version);
+    const stagedManifest = path.join(stage, 'versions.json');
+    await fs.writeFile(stagedManifest, JSON.stringify(manifest, null, 2) + '\n');
+    await fs.mkdir(path.join(historyDir, 'versions'), { recursive: true });
+    destination = path.join(historyDir, 'versions', version.id);
+    await retryLocked(() => fs.rename(stagedSnapshot, destination));
+    promoted = true;
+    // Publish the manifest last so readers never see a half-written snapshot.
+    await retryLocked(() => fs.rename(stagedManifest, manifestPath(historyDir)));
+    committed = true;
+    const bytes = snapshotBytes(files);
+    return { version, unchanged: false, bytes, history: { versions: manifest.versions.length, bytes: checked.bytes + bytes } };
+  } finally {
+    // Cleanup never replaces the outcome: a committed save is reported as saved, a failed one by its own error. What
+    // a failed step leaves behind is safe: an unlisted snapshot stops the next save by name, and the next save clears
+    // a lock and stage folder whose process is gone.
+    const quietly = step => step().catch(() => {});
+    if (promoted && !committed) await quietly(() => fs.rm(destination, { recursive: true, force: true }));
+    await quietly(() => fs.rm(stage, { recursive: true, force: true }));
+    await quietly(() => lock.close());
+    await quietly(() => fs.unlink(lockPath));
+  }
+}

package/src/cli/hosts.js

@@ -0,0 +1,194 @@
+// The host config for Vercel and Netlify. init plans it with its other steps: a plan only reads and asks, and returns
+// { change, notes, apply }.
+import path from 'node:path';
+import { parseJson, readJsonText, readText, writer } from './project-files.js';
+
+// What a host runs to deploy the history. It goes through the package script so the local bin resolves on any host.
+const hostBuild = 'npm run afterimage:build';
+const hostOutput = '.afterimage/site';
+
+// Clean URLs for the live app at the root, on Vercel: /about is answered from about.html (Next's and SvelteKit's static
+// exports write that and link to /about). Vercel only does so by default for a framework it builds itself (Next.js, until
+// framework: null, below), and not for a plain folder. cleanUrls: true would give the same, site-wide, and
+// redirect /afterimage/versions/vN/index.html to a path that is no longer inside the version folder, which the frame
+// runtime and the viewer cannot follow. A rewrite is not a redirect, only applies where no file has the path (Vercel
+// checks the filesystem first), and this one leaves /afterimage/ out altogether. tests/e2e/harness.mjs reads it.
+export const cleanUrlRewrite = { source: '/:path((?!afterimage/|afterimage$).+)', destination: '/:path*.html' };
+
+// What vercel.json needs for the history to deploy, and for the live app to stay as it is.
+//
+// Next.js: "framework": null ("Other") makes Vercel serve the output folder as plain files. With Next.js detected, Vercel's
+// own builder takes over: @vercel/next finds .next/export-detail.json after the build and serves the export's folder (out/),
+// not outputDirectory, so /afterimage/ would not deploy. Vercel detects the framework from package.json, so this is keyed
+// on a dependency on next and not on the type init chose. It costs the live app the builder's _next/static caching and its
+// .html stripping, which nextStaticCache and the rewrite below bring back. Other presets (Vite, Astro, SvelteKit) run in
+// @vercel/static-build, which uses outputDirectory ahead of the preset's own folder, and null would cost them their cache
+// headers or SPA fallback, so they are left as they are.
+// Source: https://github.com/vercel/vercel/blob/main/packages/next/src/index.ts
+const hostSettings = (next) => (next ? { framework: null, buildCommand: hostBuild, outputDirectory: hostOutput } : { buildCommand: hostBuild, outputDirectory: hostOutput });
+
+// /afterimage without its slash is answered by Vercel with the viewer's page and a 200, and the viewer's relative assets
+// then load from the root. The redirect adds the slash. Vercel's redirect source matches that path exactly, so /afterimage/
+// is not caught and nothing loops.
+export const slashRedirect = { source: '/afterimage', destination: '/afterimage/' };
+
+// The long cache on a Next.js app's hashed files (/_next/static: content-hashed names, or the build id in the path), which
+// Vercel's Next.js builder and Netlify's Next.js runtime set and which framework: null and NETLIFY_NEXT_PLUGIN_SKIP give up.
+// Both hosts then serve them with max-age=0 (seen on real deploys, docs/checking-a-deploy.md). The source matches the live
+// app's paths only: a version's copies, under /afterimage/versions/vN/_next/static/, keep the host's default.
+const immutable = 'public, max-age=31536000, immutable';
+export const nextStaticCache = { source: '/_next/static/(.*)', headers: [{ key: 'Cache-Control', value: immutable }] };
+// Any rule of the project's own for those paths counts, whatever it sets.
+const isStaticCache = rule => typeof rule?.source === 'string' && rule.source.trim().startsWith('/_next/static/');
+
+// A rule counts as ours when it points at <path>.html and keeps /afterimage out, however the rest is spelled.
+const isCleanUrlRewrite = rule => typeof rule?.destination === 'string' && /^\/:\w+\*?\.html$/.test(rule.destination) && typeof rule.source === 'string' && rule.source.includes('afterimage');
+const fromAfterimage = rule => typeof rule?.source === 'string' && rule.source.trim().replace(/\/+$/, '') === slashRedirect.source;
+// Ours is a redirect from /afterimage to /afterimage/. One from there to anywhere else is the project's, and shadows the history.
+const isSlashRedirect = rule => fromAfterimage(rule) && typeof rule.destination === 'string' && rule.destination.trim() === slashRedirect.destination;
+
+const cleanUrlsNote = 'vercel.json has "cleanUrls": true. It also redirects the history\'s own pages (/afterimage/versions/vN/index.html), so the history will not open. Remove it: Afterimage\'s rewrite gives the live app clean URLs without touching /afterimage/.';
+// @astrojs/vercel writes Vercel's own .vercel/output on every build, whatever the output mode (astro:build:done, no check
+// of the environment): https://github.com/withastro/astro/blob/main/packages/integrations/vercel/src/index.ts. After a
+// build Vercel's static builder deploys that folder in place of outputDirectory, so /afterimage/ would not be there. Not
+// tried on a real deploy; the files are the project's, so init only says so.
+const astroVercelNote = 'package.json depends on @astrojs/vercel. The adapter writes its own .vercel/output on every build, and Vercel deploys that folder instead of the Afterimage site, so /afterimage/ will not be there. A static site does not need the adapter: remove @astrojs/vercel (and its adapter line in the astro config) to deploy the history on Vercel.';
+const trailingSlashNote = value => `vercel.json has "trailingSlash": ${value}. It redirects paths under /afterimage/ ${value ? 'to a trailing slash, so a version\'s pages are never asked for the way the worker expects' : 'away from the trailing slash, so the viewer\'s relative files load from the wrong folder'}, and the history will not open. Remove it. Afterimage left the rest of vercel.json as it was.`;
+
+// Whether a list in vercel.json (rewrites, redirects) needs our entry added after the project's own, which keep their order.
+// → { add } or { note } when the value is not a list, or neither when the entry is already there.
+function planList(settings, key, entry, isPresent, purpose) {
+  const list = settings[key];
+  if (list === undefined) return { add: [entry] };
+  if (!Array.isArray(list)) return { note: `vercel.json "${key}" is not a list, so Afterimage left it alone. Add this to it ${purpose}:\n${JSON.stringify(entry, null, 2)}` };
+  return list.some(isPresent) ? {} : { add: [...list, entry] };
+}
+
+// What init asks before it switches the settings vercel.json already has (differs) to Afterimage's. One yes switches
+// every key, so a question about only one would hide the other change.
+function switchQuestion(settings, differs) {
+  if (differs.includes('framework')) {
+    const found = [
+      settings.buildCommand != null && settings.buildCommand !== hostBuild && `builds with ${settings.buildCommand}`,
+      settings.outputDirectory != null && settings.outputDirectory !== hostOutput && `serves ${settings.outputDirectory}`,
+      `uses the ${settings.framework} framework preset, which can serve its own build instead of the history`
+    ].filter(Boolean);
+    return `vercel.json ${found.join(', ')}. Switch to Afterimage's settings? (y/N)`;
+  }
+  if (differs.length === 2) return `vercel.json builds with ${settings.buildCommand} and serves ${settings.outputDirectory}. Switch both to Afterimage's? (y/N)`;
+  if (differs[0] === 'buildCommand') return `vercel.json already builds with ${settings.buildCommand}. Switch it to Afterimage's build? (y/N)`;
+  return `vercel.json already serves ${settings.outputDirectory}. Switch it to Afterimage's output? (y/N)`;
+}
+
+export async function planVercel(cwd, { isTTY, ask }) {
+  const file = path.join(cwd, 'vercel.json');
+  const { bom, body: before } = await readJsonText(file);
+  const settings = before === null ? {} : parseJson(before, 'vercel.json');
+  const next = await usesNext(cwd);
+  const wanted = hostSettings(next);
+  const notes = [];
+  if (await dependsOn(cwd, '@astrojs/vercel')) notes.push(astroVercelNote);
+
+  // null means "use the default" in vercel.json, so it is as free as a missing key. For framework it is the wanted
+  // value itself ("Other"), so only a framework that is named differs.
+  const differs = ['buildCommand', 'outputDirectory'].filter(key => settings[key] != null && settings[key] !== wanted[key]);
+  if (Object.hasOwn(wanted, 'framework') && typeof settings.framework === 'string') differs.push('framework');
+  const set = Object.keys(wanted).filter(key => (key === 'framework' ? !Object.hasOwn(settings, key) : settings[key] == null));
+
+  // cleanUrls and trailingSlash redirect paths under /afterimage/ site-wide. They are the person's, so they stay and are
+  // called out. A trailingSlash also makes both entries below pointless (or, set to false, loop with the redirect).
+  const lists = {};
+  if (settings.cleanUrls === true) notes.push(cleanUrlsNote);
+  if (typeof settings.trailingSlash === 'boolean') {
+    notes.push(trailingSlashNote(settings.trailingSlash));
+  } else {
+    if (settings.cleanUrls !== true) lists.rewrites = planList(settings, 'rewrites', cleanUrlRewrite, isCleanUrlRewrite, 'for clean URLs on the live app');
+    const shadowing = Array.isArray(settings.redirects) && settings.redirects.find(rule => fromAfterimage(rule) && !isSlashRedirect(rule));
+    if (shadowing) {
+      // A second redirect from the same path would never run, so none is added.
+      notes.push(`vercel.json redirects ${shadowing.source} to ${shadowing.destination}, which shadows the history: the viewer cannot open there. Afterimage left it alone. Remove it, or point it at ${slashRedirect.destination}.`);
+    } else {
+      lists.redirects = planList(settings, 'redirects', slashRedirect, isSlashRedirect, 'so /afterimage opens the viewer');
+    }
+  }
+  if (next) lists.headers = planList(settings, 'headers', nextStaticCache, isStaticCache, "for the long cache on the live app's /_next/static");
+  const added = {};
+  for (const [key, plan] of Object.entries(lists)) {
+    if (plan.note) notes.push(plan.note);
+    if (plan.add) {
+      added[key] = plan.add;
+      set.push(key);
+    }
+  }
+  if (!differs.length && !set.length) return { change: null, notes, apply: null };
+
+  if (differs.length) {
+    const agreed = isTTY && /^y(es)?$/i.test((await ask(switchQuestion(settings, differs))).trim());
+    if (!agreed) {
+      // Values to set, and entries to add to lists the project may already have: pasting must never replace its own rules.
+      const lines = [`Left vercel.json as it is. To deploy the history with Afterimage, set:\n${JSON.stringify(wanted, null, 2).slice(2, -2)}`];
+      for (const [key, entry] of [['rewrites', cleanUrlRewrite], ['redirects', slashRedirect], ['headers', nextStaticCache]]) {
+        if (key in added) lines.push(`and add this to "${key}", keeping the rules already there:\n${JSON.stringify(entry, null, 2)}`);
+      }
+      return { change: null, notes: [lines.join('\n'), ...notes], apply: null };
+    }
+    set.unshift(...differs.filter(key => !set.includes(key)));
+  }
+  const order = [...Object.keys(wanted), 'rewrites', 'redirects', 'headers'];
+  const text = JSON.stringify({ ...settings, ...wanted, ...added }, null, 2);
+  return {
+    change: before === null ? 'Created vercel.json' : `Updated vercel.json (set ${order.filter(key => set.includes(key)).join(', ')})`,
+    notes,
+    apply: writer(file, `${bom}${text}\n`)
+  };
+}
+
+// Whether the project depends on Next.js, however init was told where its prototype is. Netlify and Vercel detect the
+// framework from package.json, not from what Afterimage decided.
+export async function dependsOn(cwd, name) {
+  const { body } = await readJsonText(path.join(cwd, 'package.json'));
+  try {
+    const manifest = JSON.parse(body ?? '{}');
+    return name in { ...manifest?.dependencies, ...manifest?.devDependencies };
+  } catch {
+    return false;
+  }
+}
+
+const usesNext = cwd => dependsOn(cwd, 'next');
+
+// Netlify's Next.js runtime (OpenNext), which Netlify installs for a Next.js project, treats a static export as its own
+// to deploy: after the build it copies the export's folder (out/) over the publish directory, so /afterimage/ would not
+// deploy. NETLIFY_NEXT_PLUGIN_SKIP makes it step aside. Read in opennextjs-netlify's source (src/index.ts,
+// src/build/content/static.ts), not tried on a real deploy. Netlify answers /about from about.html on its own.
+const skipRuntime = 'NETLIFY_NEXT_PLUGIN_SKIP';
+// nextStaticCache, for Netlify. Its paths match the live app's only, as on Vercel.
+const netlifyStaticCache = `[[headers]]\n  for = "/_next/static/*"\n  [headers.values]\n    Cache-Control = "${immutable}"\n`;
+
+export async function planNetlify(cwd) {
+  const file = path.join(cwd, 'netlify.toml');
+  const before = await readText(file);
+  const next = await usesNext(cwd);
+  if (before === null) {
+    const nextOnly = next ? `\n[build.environment]\n  ${skipRuntime} = "true"\n\n${netlifyStaticCache}` : '';
+    return { change: 'Created netlify.toml', notes: [], apply: writer(file, `[build]\n  command = "${hostBuild}"\n  publish = "${hostOutput}"\n${nextOnly}`) };
+  }
+  // TOML is not parsed or rewritten here: a hand edit is safer than a guessed merge.
+  const hasCommand = new RegExp(`^\\s*command\\s*=\\s*["']${hostBuild}["']`, 'm').test(before);
+  const hasPublish = new RegExp(`^\\s*publish\\s*=\\s*["']${hostOutput.replace('.', '\\.')}["']`, 'm').test(before);
+  const hasSkip = new RegExp(`^\\s*${skipRuntime}\\s*=\\s*["']?(true|1)["']?\\s*$`, 'm').test(before);
+  // Any [[headers]] rule of the project's own for those paths counts, whatever it sets.
+  const hasCache = /^\s*for\s*=\s*["']\/_next\/static\//m.test(before);
+  const wantsSkip = next && !hasSkip;
+  const wantsCache = next && !hasCache;
+  if (hasCommand && hasPublish && !wantsSkip && !wantsCache) return { change: null, notes: [], apply: null };
+  const lines = [];
+  if (!hasCommand || !hasPublish) lines.push(`Under [build], set:\n  command = "${hostBuild}"\n  publish = "${hostOutput}"`);
+  if (wantsSkip) lines.push(`Under [build.environment], set (so Netlify's Next.js runtime leaves the history in place instead of deploying out/):\n  ${skipRuntime} = "true"`);
+  if (wantsCache) lines.push(`To keep the long cache on the live app's /_next/static, which the runtime would have set, add:\n${netlifyStaticCache.trimEnd()}`);
+  return {
+    change: null,
+    notes: [`netlify.toml already exists, so Afterimage left it alone. ${lines.join('\n')}`],
+    apply: null
+  };
+}

package/src/cli/main.js

@@ -0,0 +1,47 @@
+import * as init from './commands/init.js';
+import * as save from './commands/save.js';
+import * as build from './commands/build.js';
+import * as dev from './commands/dev.js';
+import { isUserError } from './errors.js';
+
+// One entry per command. Each module exports run(args, ctx) → exit code, a one-line usage, a summary, its help (what
+// both "afterimage help <command>" and "<command> --help" print) and its options.
+export const commands = { init, save, dev, build };
+
+function overview() {
+  const lines = Object.values(commands).map(command => `  ${command.usage}\n      ${command.summary}`);
+  return `Usage: afterimage <command>\n\nCommands:\n${lines.join('\n')}\n\nRun "afterimage help <command>" for one command.\n`;
+}
+
+// Usage mistakes exit 2, failures exit 1, success 0.
+export async function main(argv, ctx) {
+  const { stdout, stderr } = ctx;
+  const [first, ...rest] = argv;
+  if (first === undefined || first === '--help' || first === '-h') {
+    stdout.write(overview());
+    return 0;
+  }
+  if (first === 'help') {
+    if (rest.length === 0) {
+      stdout.write(overview());
+      return 0;
+    }
+    const command = Object.hasOwn(commands, rest[0]) ? commands[rest[0]] : null;
+    if (!command) {
+      stderr.write(`Unknown command "${rest[0]}".\n\n${overview()}`);
+      return 2;
+    }
+    stdout.write(command.help);
+    return 0;
+  }
+  if (!Object.hasOwn(commands, first)) {
+    stderr.write(`Unknown command "${first}".\n\n${overview()}`);
+    return 2;
+  }
+  try {
+    return await commands[first].run(rest, ctx);
+  } catch (error) {
+    stderr.write(isUserError(error) ? `${error.message}\n` : `${error?.stack ?? error}\n`);
+    return 1;
+  }
+}

package/src/cli/project-files.js

@@ -0,0 +1,38 @@
+// Reading and writing the project's own files, for init and the host config it plans.
+import fs from 'node:fs/promises';
+
+// Windows editors often save JSON with a byte order mark. JSON.parse rejects it, so it is split off and put back.
+const bomMark = '';
+
+export async function readText(file) {
+  try {
+    return await fs.readFile(file, 'utf8');
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+}
+
+// → { bom, body } with body null when the file does not exist.
+export async function readJsonText(file) {
+  const raw = await readText(file);
+  if (raw === null) return { bom: '', body: null };
+  const bom = raw.startsWith(bomMark) ? bomMark : '';
+  return { bom, body: raw.slice(bom.length) };
+}
+
+export function parseJson(text, name) {
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${name} is not valid JSON: ${error.message}\nFix it, then run "afterimage init" again.`);
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`${name} must be a JSON object.\nFix it, then run "afterimage init" again.`);
+  }
+  return value;
+}
+
+// A step's write, run only once every step has been planned.
+export const writer = (file, text) => () => fs.writeFile(file, text);

package/src/cli/retry.js

@@ -0,0 +1,16 @@
+// A file that something else holds open (a static server, an indexer, Windows antivirus scanning a file just written)
+// often frees itself within a moment, so an operation that hits one is tried once more before giving up.
+const lockedCodes = new Set(['EPERM', 'EBUSY', 'EACCES']);
+
+export const isLocked = error => lockedCodes.has(error?.code);
+
+// Runs operation, and once more after delayMs when it fails on a locked file. The second failure is thrown as it is.
+export async function retryLocked(operation, delayMs = 250) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (!isLocked(error)) throw error;
+    await new Promise(resolve => setTimeout(resolve, delayMs));
+    return operation();
+  }
+}

package/src/cli/run-build.js

@@ -0,0 +1,23 @@
+import { spawn } from 'node:child_process';
+
+// The command is the user's own (from afterimage.config.json), so it runs through the platform shell like an npm script.
+// Tests pass 'ignore' or 'pipe' so a build's output does not land in the test report.
+// Each caller says what a failed build leaves undone: "Nothing was saved." for save, "Nothing was built." for build.
+//
+// The build runs without the VERCEL variable, and with everything else as it was (VERCEL_URL and the rest stay).
+// Vercel sets VERCEL while it builds, and some tools take it as a cue to write for Vercel's own deployment instead of
+// plain files: SvelteKit's adapter-static then writes .vercel/output and never its usual folder
+// (https://github.com/sveltejs/kit/blob/main/packages/adapter-static/platforms.js). Afterimage saves and deploys the
+// plain static build, so the build must behave the same on a host as on a laptop.
+export function runBuild(command, cwd, { stdio = 'inherit', closing = 'Nothing was saved.' } = {}) {
+  const { VERCEL, ...env } = process.env;
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, { shell: true, cwd, stdio, env });
+    child.on('error', error => reject(new Error(`The build could not start: ${error.message}. ${closing}`)));
+    child.on('close', (code, signal) => {
+      if (code === 0) resolve();
+      else if (code === null) reject(new Error(`The build was stopped by ${signal}. ${closing}`));
+      else reject(new Error(`The build failed (exit code ${code}). ${closing}`));
+    });
+  });
+}