create-ailk 0.7.0 → 0.9.0

package/templates/.claude/skills/update-page/scripts/update-page.ts

@@ -0,0 +1,640 @@
+#!/usr/bin/env -S pnpm exec tsx
+/**
+ * update-page — move a page from `/old` to `/new` on this site, safely.
+ *
+ *   pnpm exec tsx .claude/skills/update-page/scripts/update-page.ts plan  --from /meet --to /schedule [--name "Title"] [--json]
+ *   pnpm exec tsx .claude/skills/update-page/scripts/update-page.ts apply --from /meet --to /schedule [--name "Title"] --confirm <hash>
+ *
+ * `plan` writes nothing: it prints every file it would create / move / modify /
+ * delete, the notes a reader should see, and a plan hash. `apply` re-plans
+ * and writes ONLY when the hash it computes equals `--confirm` — so a plan the
+ * user never saw cannot be applied, and a file that changed between plan and
+ * apply invalidates the hash.
+ *
+ * Exit codes: 0 done · 1 hash mismatch or missing (nothing written) · 2 usage ·
+ * 3 refused (one line naming the reason; nothing written).
+ *
+ * What a move touches (spec docs/specs/6937-an-update-page-skill-renames-spec.md):
+ *   - the page's content file(s) in every locale, and their `slug:`;
+ *   - the page's own route directory, when it has one (an `add-page` route),
+ *     and the `getPage("old")` literal inside its page.tsx;
+ *   - exact internal links to `/old` in content and the site nav;
+ *   - the page's row in `.ailk-site-manifest.json`;
+ *   - a permanent redirect `/old` → `/new`, kept in a managed block inside
+ *     `apps/web/next.config.mjs`'s `redirects()`.
+ *
+ * Only `node:` built-ins plus the site's own `@working-theory/templates/routes`
+ * (resolved from `apps/web`, never a new dependency).
+ */
+import { createHash } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmdirSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+export type ChangeKind = "create" | "move" | "modify" | "delete";
+
+export interface Change {
+  kind: ChangeKind;
+  /** Site-relative path the change lands at (for `move`, the destination). */
+  path: string;
+  /** For `move`: the site-relative path being moved away from. */
+  from?: string;
+  /** New file contents for `create` / `move` / `modify`. Absent for `delete`. */
+  content?: string;
+}
+
+export interface RouteRowLike {
+  route: string;
+  module: string;
+  legacyRoutes?: readonly string[];
+}
+
+export interface Deps {
+  /** `routeFor(type, slug)` from `@working-theory/templates/routes`. */
+  routeFor: (type: string, slug?: string) => string;
+  /** `ROUTES` from the same module (only `route` and `module` are read). */
+  routes: readonly RouteRowLike[];
+}
+
+export interface RenameRequest {
+  from: string;
+  to: string;
+  name?: string;
+}
+
+export type Plan =
+  | { ok: true; changes: Change[]; notes: string[]; hash: string }
+  | { ok: false; reason: string };
+
+// ── Small helpers ────────────────────────────────────────────────────────────
+
+const SEGMENT = /^\/[a-z0-9]+(-[a-z0-9]+)*$/;
+const WEB_APP = join("apps", "web", "app");
+const NAV_CONFIG = join("apps", "web", "lib", "nav-config.ts");
+const NEXT_CONFIG = join("apps", "web", "next.config.mjs");
+
+function rel(root: string, abs: string): string {
+  return relative(root, abs).split(sep).join("/");
+}
+
+function isDir(p: string): boolean {
+  return existsSync(p) && statSync(p).isDirectory();
+}
+
+function listDirs(p: string): string[] {
+  return isDir(p)
+    ? readdirSync(p).filter((n) => isDir(join(p, n)))
+    : [];
+}
+
+function walkFiles(dir: string, out: string[] = []): string[] {
+  if (!isDir(dir)) return out;
+  for (const name of readdirSync(dir)) {
+    const abs = join(dir, name);
+    if (statSync(abs).isDirectory()) walkFiles(abs, out);
+    else out.push(abs);
+  }
+  return out;
+}
+
+/** The frontmatter block (between the first two `---` lines), or undefined. */
+function frontmatter(text: string): string | undefined {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  return m?.[1];
+}
+
+/** A top-level scalar `key: value` from a frontmatter block, quotes stripped. */
+function fmValue(fm: string, key: string): string | undefined {
+  const m = new RegExp(`^${key}\\s*:\\s*(["']?)([^"'\\r\\n]+?)\\1\\s*$`, "m").exec(fm);
+  return m?.[2]?.trim();
+}
+
+/** Replace a top-level scalar `key: value` in the frontmatter, keeping its quoting. */
+function fmReplace(text: string, key: string, next: string): string {
+  const fm = frontmatter(text);
+  if (fm === undefined) return text;
+  const re = new RegExp(`^(${key}\\s*:\\s*)(["']?)([^"'\\r\\n]+?)(\\2)(\\s*)$`, "m");
+  const replaced = fm.replace(re, (_m, pre: string, q: string, _v: string, q2: string, ws: string) => {
+    const quote = q === "" && /[:#{}\[\],&*?|<>=!%@`]/.test(next) ? '"' : q;
+    return `${pre}${quote}${next}${quote === "" ? q2 : quote}${ws}`;
+  });
+  return text.replace(fm, replaced);
+}
+
+function firstSegment(route: string): string {
+  return route.replace(/^\//, "").split("/")[0] ?? "";
+}
+
+/** Does a route directory serve `/x`? Route groups `(g)` add no URL segment. */
+function routeDirFor(root: string, x: string): string | undefined {
+  const bases = [join(root, WEB_APP, "[locale]"), join(root, WEB_APP)];
+  for (const base of bases) {
+    const direct = join(base, x);
+    if (isDir(direct)) return rel(root, direct);
+    for (const g of listDirs(base).filter((n) => /^\(.*\)$/.test(n))) {
+      const inGroup = join(base, g, x);
+      if (isDir(inGroup)) return rel(root, inGroup);
+    }
+  }
+  return undefined;
+}
+
+interface ContentFile {
+  /** Site-relative path. */
+  path: string;
+  locale?: string;
+  type: string;
+  slug: string;
+  text: string;
+}
+
+/**
+ * Every content page on the site, in both layouts: `content/<locale>/<Type>/<slug>.mdx`
+ * (a locale directory is lowercase) and add-page's literal `content/<Type>/<slug>.mdx`
+ * (a Type directory is Capitalised).
+ */
+function contentFiles(root: string): ContentFile[] {
+  const out: ContentFile[] = [];
+  const contentRoot = join(root, "content");
+  const read = (abs: string, locale: string | undefined, typeDir: string) => {
+    const text = readFileSync(abs, "utf8");
+    const fm = frontmatter(text);
+    if (fm === undefined) return;
+    const type = fmValue(fm, "type");
+    const slug = fmValue(fm, "slug");
+    if (type === undefined || slug === undefined || type !== typeDir) return;
+    out.push({ path: rel(root, abs), locale, type, slug, text });
+  };
+  for (const a of listDirs(contentRoot)) {
+    if (/^[A-Z]/.test(a)) {
+      for (const f of readdirSync(join(contentRoot, a)).filter((n) => n.endsWith(".mdx"))) {
+        read(join(contentRoot, a, f), undefined, a);
+      }
+    } else {
+      for (const t of listDirs(join(contentRoot, a))) {
+        for (const f of readdirSync(join(contentRoot, a, t)).filter((n) => n.endsWith(".mdx"))) {
+          read(join(contentRoot, a, t, f), a, t);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+/** The scaffold's module set, from `architecture.yaml`'s `# Modules:` line. */
+function siteModules(root: string): Set<string> {
+  const p = join(root, "architecture.yaml");
+  if (!existsSync(p)) return new Set();
+  const m = /^# Modules: (.+)$/m.exec(readFileSync(p, "utf8"));
+  return new Set((m?.[1] ?? "").split(",").map((s) => s.trim()).filter(Boolean));
+}
+
+// ── The managed redirects() block ────────────────────────────────────────────
+
+// This file runs two ways: as a CommonJS module under the site's jest (where
+// `__dirname` exists) and as a script under `pnpm exec tsx` (where argv[1] is
+// this file). Either way the template sits beside it.
+const HERE =
+  typeof __dirname !== "undefined" ? __dirname : dirname(process.argv[1] ?? ".");
+const TEMPLATE_PATH = join(HERE, "..", "templates", "redirects.mjs.tmpl");
+const PRISTINE_RE = /^([ \t]*)async redirects\(\) \{\r?\n[ \t]*return legacyRedirects\(\);\r?\n[ \t]*\},[ \t]*\r?\n/m;
+const ROW_RE = /^[ \t]*\{ from: "([^"]+)", to: "([^"]+)" \},[ \t]*$/;
+
+export interface RenameRow {
+  from: string;
+  to: string;
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+export function renderManagedRedirects(rows: readonly RenameRow[]): string {
+  const template = readFileSync(TEMPLATE_PATH, "utf8");
+  const lines = rows.map((r) => `      { from: "${r.from}", to: "${r.to}" },`).join("\n");
+  return template.replace("{{ROWS}}", lines);
+}
+
+/** The template as a regex with the rows region captured. */
+function managedRe(): RegExp {
+  const template = readFileSync(TEMPLATE_PATH, "utf8");
+  const [head, tail] = template.split("{{ROWS}}");
+  return new RegExp(`${escapeRe(head ?? "")}([\\s\\S]*?)${escapeRe(tail ?? "")}`);
+}
+
+type RedirectsState =
+  | { kind: "pristine"; match: string }
+  | { kind: "managed"; match: string; rows: RenameRow[] }
+  | { kind: "edited" };
+
+function readRedirectsState(text: string): RedirectsState {
+  const pristine = PRISTINE_RE.exec(text);
+  if (pristine !== null) return { kind: "pristine", match: pristine[0] };
+  const managed = managedRe().exec(text);
+  if (managed !== null) {
+    const rows: RenameRow[] = [];
+    for (const line of (managed[1] ?? "").split(/\r?\n/)) {
+      if (line.trim() === "") continue;
+      const m = ROW_RE.exec(line);
+      if (m === null) return { kind: "edited" };
+      rows.push({ from: m[1] as string, to: m[2] as string });
+    }
+    // The whole method must be exactly what we would render for those rows.
+    if (managed[0] !== renderManagedRedirects(rows)) return { kind: "edited" };
+    return { kind: "managed", match: managed[0], rows };
+  }
+  return { kind: "edited" };
+}
+
+/** D4 row maintenance: no chains, no self-loops, renaming back removes the old row. */
+export function nextRenameRows(rows: readonly RenameRow[], from: string, to: string): RenameRow[] {
+  const out = rows
+    .map((r) => (r.to === from ? { from: r.from, to } : r))
+    .filter((r) => r.from !== to)
+    .filter((r) => r.from !== r.to);
+  out.push({ from, to });
+  return out;
+}
+
+// ── Plan ─────────────────────────────────────────────────────────────────────
+
+function refuse(reason: string): Plan {
+  return { ok: false, reason };
+}
+
+/** The exact-link pattern (D5): `/s` bounded by a quote or paren on both sides. */
+function linkRe(s: string): RegExp {
+  return new RegExp(`(["'(])\\/${escapeRe(s)}(["')#?])`, "g");
+}
+
+export function planRename(siteDir: string, req: RenameRequest, deps: Deps): Plan {
+  const root = siteDir;
+  const { from, to } = req;
+  if (!SEGMENT.test(from) || !SEGMENT.test(to)) {
+    return refuse("routes must be one lowercase segment (e.g. /meet → /schedule)");
+  }
+  if (from === to) return refuse("the new route is the same as the old one");
+  const s = from.slice(1);
+  const t = to.slice(1);
+
+  // D2 rule 2 — the page's content files.
+  const all = contentFiles(root);
+  const pages = all.filter((f) => f.slug === s && deps.routeFor(f.type, s) === from);
+  const oldDir = routeDirFor(root, s);
+  if (pages.length === 0) {
+    if (oldDir !== undefined) {
+      return refuse(`${from} is a code route with no page content to move (${oldDir})`);
+    }
+    return refuse(`no page at ${from}`);
+  }
+  const types = new Set(pages.map((p) => p.type));
+  if (types.size > 1) {
+    return refuse(`${from} has pages of more than one type (${[...types].join(", ")}); move them one at a time`);
+  }
+  const type = pages[0]!.type;
+
+  // D2 rule 3 — the type must not fix the URL.
+  if (deps.routeFor(type, "probe") !== "/probe") {
+    return refuse(
+      `a ${type} page's URL is fixed by its type (${type} always lives at ${deps.routeFor(type, s)})`,
+    );
+  }
+
+  // D2 rule 4 — the page must actually be served at /s by a route we may move.
+  const routesSegments = new Map<string, RouteRowLike>();
+  for (const r of deps.routes) {
+    const seg = firstSegment(r.route);
+    if (seg !== "" && !routesSegments.has(seg)) routesSegments.set(seg, r);
+  }
+  const servedByCatchRoute = type === "LandingPage" && oldDir === undefined;
+  const servedByOwnDir = oldDir !== undefined && !routesSegments.has(s);
+  if (!servedByCatchRoute && !servedByOwnDir) {
+    return refuse(`${from} is served by a route the scaffold ships (its type's route is fixed)`);
+  }
+
+  // D2 — the new route must be free.
+  const newDir = routeDirFor(root, t);
+  if (newDir !== undefined) return refuse(`${to} already exists: route directory ${newDir}`);
+  const clash = all.find((f) => deps.routeFor(f.type, f.slug) === to);
+  if (clash !== undefined) return refuse(`${to} already exists: ${clash.path}`);
+  if (isDir(join(root, "content", t))) {
+    return refuse(`${to} already exists: content locale directory content/${t}/`);
+  }
+
+  // D4 — the redirects() method must be one we recognise.
+  const nextConfigAbs = join(root, NEXT_CONFIG);
+  if (!existsSync(nextConfigAbs)) return refuse(`${NEXT_CONFIG} not found`);
+  const nextConfig = readFileSync(nextConfigAbs, "utf8");
+  if (!/^const enabledLocalesAtBuild\b/m.test(nextConfig) || !/^const defaultLocaleAtBuild\b/m.test(nextConfig)) {
+    return refuse(
+      `${NEXT_CONFIG} no longer defines enabledLocalesAtBuild / defaultLocaleAtBuild — the managed redirects block cannot read the site's locales; stop and report this`,
+    );
+  }
+  const state = readRedirectsState(nextConfig);
+  if (state.kind === "edited") {
+    return refuse(
+      `${NEXT_CONFIG} redirects() has been edited — add { source: '${from}', destination: '${to}', permanent: true } yourself`,
+    );
+  }
+
+  // D3 — the manifest row.
+  const manifestRel = existsSync(join(root, ".ailk-site-manifest.json"))
+    ? ".ailk-site-manifest.json"
+    : existsSync(join(root, "TEMPLATE-MANIFEST.json"))
+      ? "TEMPLATE-MANIFEST.json"
+      : undefined;
+  const rowRe = new RegExp(`("route"\\s*:\\s*")${escapeRe(from)}(")`, "g");
+  let manifestText: string | undefined;
+  if (manifestRel !== undefined) {
+    manifestText = readFileSync(join(root, manifestRel), "utf8");
+    const hits = manifestText.match(rowRe)?.length ?? 0;
+    if (hits > 1) return refuse(`${manifestRel} has ${hits} rows for ${from}; expected one`);
+    if (hits === 0) manifestText = undefined;
+  }
+
+  // ── Build the changes ────────────────────────────────────────────────────
+  const changes: Change[] = [];
+  const notes: string[] = [];
+  const link = linkRe(s);
+  const rewriteLinks = (text: string): string => text.replace(link, `$1${to}$2`);
+  const rewrittenContentPaths: string[] = [];
+  const movedPaths = new Set(pages.map((p) => p.path));
+
+  // The page's own content files move (and get their links rewritten too).
+  for (const p of pages) {
+    let text = fmReplace(p.text, "slug", t);
+    if (req.name !== undefined) {
+      if (p.locale === undefined || p.locale === "en") text = fmReplace(text, "title", req.name);
+      else notes.push(`${p.path}: title left as translated (--name sets the en title only)`);
+    }
+    text = rewriteLinks(text);
+    const dest = p.path.replace(new RegExp(`/${escapeRe(s)}\\.mdx$`), `/${t}.mdx`);
+    changes.push({ kind: "move", from: p.path, path: dest, content: text });
+    if (link.test(p.text)) rewrittenContentPaths.push(dest);
+    link.lastIndex = 0;
+  }
+
+  // Other content files with an exact link to /s.
+  for (const f of all) {
+    if (movedPaths.has(f.path)) continue;
+    link.lastIndex = 0;
+    if (!link.test(f.text)) continue;
+    link.lastIndex = 0;
+    changes.push({ kind: "modify", path: f.path, content: rewriteLinks(f.text) });
+    rewrittenContentPaths.push(f.path);
+  }
+
+  // The nav.
+  const navAbs = join(root, NAV_CONFIG);
+  let navChanged = false;
+  if (existsSync(navAbs)) {
+    const nav = readFileSync(navAbs, "utf8");
+    link.lastIndex = 0;
+    if (link.test(nav)) {
+      link.lastIndex = 0;
+      changes.push({ kind: "modify", path: NAV_CONFIG, content: rewriteLinks(nav) });
+      navChanged = true;
+      const label = /labelKey:\s*"([^"]+)"[^}]*path:\s*"\/[^"]*"/g;
+      for (const m of nav.matchAll(label)) {
+        if (m[0].includes(`"${from}"`)) notes.push(`nav: the item labelled \`${m[1]}\` now points at ${to}`);
+      }
+    }
+  }
+
+  // The page's own route directory (case 3).
+  if (oldDir !== undefined) {
+    const oldAbs = join(root, oldDir);
+    const newAbs = join(dirname(oldAbs), t);
+    for (const fileAbs of walkFiles(oldAbs)) {
+      const inner = relative(oldAbs, fileAbs);
+      let text = readFileSync(fileAbs, "utf8");
+      if (inner === "page.tsx") {
+        const getPage = new RegExp(`getPage\\("${escapeRe(s)}"\\)`, "g");
+        text = text.replace(getPage, `getPage("${t}")`);
+        const others = text.match(new RegExp(`"${escapeRe(s)}"`, "g"))?.length ?? 0;
+        if (others > 0) notes.push(`${rel(root, join(newAbs, inner))}: ${others} other "${s}" literal(s) left as-is — check them by hand`);
+      }
+      changes.push({ kind: "move", from: rel(root, fileAbs), path: rel(root, join(newAbs, inner)), content: text });
+    }
+  }
+
+  // The manifest row.
+  if (manifestText !== undefined && manifestRel !== undefined) {
+    changes.push({ kind: "modify", path: manifestRel, content: manifestText.replace(rowRe, `$1${to}$2`) });
+  } else {
+    notes.push(`no manifest row for ${from} — .ailk-site-manifest.json is unchanged`);
+  }
+
+  // The redirect.
+  const rows = nextRenameRows(state.kind === "managed" ? state.rows : [], from, to);
+  changes.push({ kind: "modify", path: NEXT_CONFIG, content: nextConfig.replace(state.match, renderManagedRedirects(rows)) });
+
+  // Reported, not rewritten: links in code.
+  for (const dir of [join(root, WEB_APP), join(root, "apps", "web", "lib"), join(root, "apps", "web", "components")]) {
+    for (const fileAbs of walkFiles(dir)) {
+      const r = rel(root, fileAbs);
+      if (r === NAV_CONFIG || !/\.(tsx?|mjs|js)$/.test(r)) continue;
+      const text = readFileSync(fileAbs, "utf8");
+      link.lastIndex = 0;
+      const n = text.match(link)?.length ?? 0;
+      if (n > 0) notes.push(`${r}: ${n} link(s) to ${from} left as-is (code; the redirect covers them)`);
+    }
+  }
+
+  // Fixed children left behind.
+  const children = new Set<string>();
+  const hubRow = deps.routes.find((r) => r.route === from || r.route.startsWith(`${from}/`));
+  if (hubRow !== undefined) children.add(`${from}/…`);
+  if (manifestText !== undefined) {
+    for (const m of manifestText.matchAll(/"route"\s*:\s*"([^"]+)"/g)) {
+      if ((m[1] ?? "").startsWith(`${from}/`)) children.add(m[1] as string);
+    }
+  }
+  if (children.size > 0) {
+    notes.push(`the pages under ${from} (${[...children].join(", ")}) keep their URLs — only ${from} itself moves`);
+  }
+
+  // D9 — what a later add-module run will do differently.
+  const modules = siteModules(root);
+  const sRow = routesSegments.get(s);
+  if (sRow !== undefined && oldDir === undefined) {
+    notes.push(
+      `${from} belongs to the ${sRow.module} module's routes. If they are added later, the redirect ${from} → ${to} will hide its ${from} page; remove the \`${from}\` row from the \`ailk:page-renames\` block in apps/web/next.config.mjs first.`,
+    );
+  }
+  const tRow = routesSegments.get(t);
+  if (tRow !== undefined && newDir === undefined) {
+    notes.push(
+      `${to} belongs to the ${tRow.module} module's routes. If they are added later, its ${to} directory will take precedence over this page, which will stop being served; rename it again first.`,
+    );
+  }
+  const seeds = new Map<string, string[]>();
+  for (const c of changes) {
+    if (c.content === undefined || !c.path.endsWith(".mdx") || !rewrittenContentPaths.includes(c.path)) continue;
+    const fm = frontmatter(c.content);
+    if (fm === undefined) continue;
+    const ty = fmValue(fm, "type");
+    const sl = fmValue(fm, "slug");
+    if (ty === undefined || sl === undefined) continue;
+    const row = routesSegments.get(firstSegment(deps.routeFor(ty, sl)));
+    if (row === undefined || modules.has(row.module)) continue;
+    const list = seeds.get(row.module) ?? [];
+    list.push(c.path);
+    seeds.set(row.module, list);
+  }
+  for (const [module, paths] of seeds) {
+    notes.push(
+      `add-module ${module} will keep these edited placeholder files and list them for review instead of replacing them: ${paths.join(", ")}`,
+    );
+  }
+  if (navChanged) {
+    notes.push("add-module will no longer regenerate the nav; it will list it for manual review");
+  }
+
+  changes.sort((a, b) => a.path.localeCompare(b.path));
+  return { ok: true, changes, notes, hash: hashChanges(changes) };
+}
+
+export function hashChanges(changes: readonly Change[]): string {
+  const canonical = JSON.stringify(
+    [...changes]
+      .sort((a, b) => a.path.localeCompare(b.path))
+      .map((c) => ({ kind: c.kind, path: c.path, from: c.from ?? null, content: c.content ?? null })),
+  );
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+// ── Apply ────────────────────────────────────────────────────────────────────
+
+export function applyPlan(siteDir: string, plan: Extract<Plan, { ok: true }>): void {
+  const touchedDirs = new Set<string>();
+  for (const c of plan.changes) {
+    const abs = join(siteDir, c.path);
+    if (c.kind === "delete") {
+      unlinkSync(abs);
+      continue;
+    }
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, c.content ?? "");
+    if (c.kind === "move" && c.from !== undefined) {
+      const fromAbs = join(siteDir, c.from);
+      unlinkSync(fromAbs);
+      touchedDirs.add(dirname(fromAbs));
+    }
+  }
+  // Remove directories a route move emptied.
+  for (const d of [...touchedDirs].sort((a, b) => b.length - a.length)) {
+    let cur = d;
+    while (isDir(cur) && readdirSync(cur).length === 0 && cur !== siteDir) {
+      rmdirSync(cur);
+      cur = dirname(cur);
+    }
+  }
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────
+
+interface Args {
+  cmd: "plan" | "apply";
+  from: string;
+  to: string;
+  name?: string;
+  root: string;
+  confirm?: string;
+  json: boolean;
+}
+
+function parseArgs(argv: string[]): Args | string {
+  const cmd = argv[0];
+  if (cmd !== "plan" && cmd !== "apply") return "usage: update-page plan|apply --from /old --to /new [--name \"Title\"] [--root <site>] [--confirm <hash>] [--json]";
+  const a: Partial<Args> = { cmd, root: process.cwd(), json: false };
+  for (let i = 1; i < argv.length; i++) {
+    const k = argv[i];
+    const v = argv[i + 1];
+    if (k === "--json") { a.json = true; continue; }
+    if (v === undefined) return `missing value for ${k}`;
+    if (k === "--from") a.from = v;
+    else if (k === "--to") a.to = v;
+    else if (k === "--name") a.name = v;
+    else if (k === "--root") a.root = v;
+    else if (k === "--confirm") a.confirm = v;
+    else return `unknown argument ${k}`;
+    i++;
+  }
+  if (a.from === undefined || a.to === undefined) return "--from and --to are required";
+  return a as Args;
+}
+
+async function loadDeps(root: string): Promise<Deps> {
+  const req = createRequire(join(root, "apps", "web", "package.json"));
+  const mod = (await import(pathToFileURL(req.resolve("@working-theory/templates/routes")).href)) as {
+    routeFor: Deps["routeFor"];
+    ROUTES: readonly RouteRowLike[];
+  };
+  return { routeFor: mod.routeFor, routes: mod.ROUTES };
+}
+
+function printPlan(plan: Extract<Plan, { ok: true }>): void {
+  for (const c of plan.changes) {
+    const line = c.kind === "move" ? `move    ${c.from} -> ${c.path}` : `${c.kind.padEnd(7)} ${c.path}`;
+    console.log(line);
+  }
+  if (plan.notes.length > 0) {
+    console.log("");
+    for (const n of plan.notes) console.log(`note: ${n}`);
+  }
+  console.log("");
+  console.log(`hash: ${plan.hash}`);
+}
+
+async function main(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+  if (typeof args === "string") {
+    console.error(args);
+    return 2;
+  }
+  const deps = await loadDeps(args.root);
+  const plan = planRename(args.root, { from: args.from, to: args.to, ...(args.name !== undefined && { name: args.name }) }, deps);
+  if (!plan.ok) {
+    console.error(`refused: ${plan.reason}`);
+    return 3;
+  }
+  if (args.cmd === "plan") {
+    if (args.json) console.log(JSON.stringify(plan, null, 2));
+    else printPlan(plan);
+    return 0;
+  }
+  if (args.confirm === undefined || args.confirm !== plan.hash) {
+    console.error(
+      args.confirm === undefined
+        ? "apply needs --confirm <hash> from a plan the user has seen; nothing written"
+        : "the plan has changed since that hash was printed; run plan again and confirm the new hash; nothing written",
+    );
+    return 1;
+  }
+  applyPlan(args.root, plan);
+  console.log(`applied ${plan.changes.length} change(s): ${args.from} -> ${args.to}`);
+  return 0;
+}
+
+if (/update-page\.(ts|js)$/.test(process.argv[1] ?? "")) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err: unknown) => {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(2);
+    },
+  );
+}

package/templates/.claude/skills/update-page/templates/redirects.mjs.tmpl

@@ -0,0 +1,31 @@
+  // Page renames — managed by the `update-page` skill. Edit ONLY the rows
+  // between the begin/end markers (one `{ from, to }` per line); the skill
+  // rewrites them on the next rename and refuses to touch any other edit.
+  async redirects() {
+    const renames = [
+      // ailk:page-renames:begin
+{{ROWS}}
+      // ailk:page-renames:end
+    ];
+    const locales = String(enabledLocalesAtBuild ?? "")
+      .split(",")
+      .map((l) => l.trim())
+      .filter((l) => l !== "" && l !== defaultLocaleAtBuild);
+    const renamed = renames.flatMap(({ from, to }) => [
+      { source: from, destination: to, permanent: true },
+      ...(locales.length > 0
+        ? [
+            {
+              source: `/:locale(${locales.join("|")})${from}`,
+              destination: `/:locale${to}`,
+              permanent: true,
+            },
+          ]
+        : []),
+    ]);
+    const owned = new Set(renames.map((r) => r.to));
+    return [
+      ...renamed,
+      ...legacyRedirects().filter((r) => !owned.has(r.source)),
+    ];
+  },