rvlib-shipkit 0.38.1 → 1.0.1

package/src/core/migrate-layout.ts

@@ -0,0 +1,616 @@
+// layout-sweep: skip
+// Carry a repo from the old root layout to `.shipkit/` (core/layout.ts), and
+// repair a contract folder typed under a wrong name, in ONE pass and ONE commit.
+//
+// Nothing here is a decision, so no human is asked: `.rv-<x>/` became
+// `.shipkit/<x>/`, `asks/`, `hooks/` and the `tmp/` scratch moved in, the
+// generated files moved out of the root. A typo (`rv-reflections`, `.rv-reflection`) is the same
+// move, because a folder under a name no scanner reads is silence.
+//
+// The invariant a reader breaks first: A MOVE NEVER CHANGES WHAT GIT TRACKS.
+// A tracked file stays tracked under its new name (added with -f, because
+// `.shipkit/*` is ignored and only some children are re-included), an
+// untracked file moves on disk and stays untracked. The one exception is a
+// typo folder, whose files git only tracked because the missing dot kept the
+// ignore rule from matching: those leave the index when the target is ignored.
+//
+// A file carrying the SWEEP_SKIP marker is never rewritten: it names the old
+// layout on purpose (this module, its tests, the legacy lines of SK004).
+//
+// Refusals, every one retried by the next run and printed by the caller:
+// a target that already holds files (merging decides which file wins), a
+// tracked path to move or rewrite that carries uncommitted edits (the commit
+// would take them along), a merge or rebase in progress, a nested repo.
+import { accessSync, constants, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join, posix } from 'path'
+import type { RepoConfig } from '../repo-config.ts'
+import { gitBin } from './git-bin.ts'
+import { probeGitRoot } from './git-root.ts'
+import { LAYOUT, MACHINE_PRIVATE, SHIPKIT_DIR } from './layout.ts'
+import { machineCommit } from './machine-commit.ts'
+import { nestedIn } from './nesting.ts'
+
+/** the prefix every contract folder carried before `.shipkit/` */
+export const LEGACY_CONTRACT_PREFIX = '.rv-'
+
+const CONFIG_FILE = 'repo.config.ts'
+
+/** what one pass did, in words: the folders it moved and the root files it
+ *  dropped. Empty when it did neither, so no caller prints a sentence with a
+ *  hole where the list should be */
+export function layoutSummary(r: { moved: LayoutMove[]; removed: string[] }): string {
+    const list = (xs: string[]): string => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`)
+    const folders = r.moved.filter((m) => m.kind !== 'cache').map((m) => `${m.from}/`)
+    const parts = [
+        ...(folders.length > 0 ? [`move ${list(folders)} under ${SHIPKIT_DIR}/`] : []),
+        ...(r.removed.length > 0 ? [`drop the root ${list(r.removed)}, which shipkit writes under ${SHIPKIT_DIR}/`] : []),
+    ]
+    return parts.join(', and ')
+}
+
+/** the contract names a typo is matched against */
+const KNOWN = ['identity', 'assets', 'comfy', 'private', 'reflections', 'social', 'journal', 'domain', 'itch', 'steam', 'discord'] as const
+
+/** root files shipkit used to generate on every run */
+export const LEGACY_GENERATED = ['STATUS.md', 'STATUS.md.lock', 'STATUS.full.md', 'STATUS.full.md.lock'] as const
+
+/** the root scratch folder, `.shipkit/tmp/` now */
+export const LEGACY_TMP = 'tmp'
+
+const LEGACY_CACHE = `${LEGACY_TMP}/.shipkit`
+
+/** a lease a killed run left in the old scratch: never worth a refusal, the
+ *  one at the target is the live one */
+const STALE_LEASE = /^shipkit-[^/]+\.lock$/
+
+/** what the old policy block kept out of git, rendered by SK004 while a repo
+ *  still holds `.rv-*` folders so none of them is exposed before it moves */
+export const LEGACY_VENUES = ['.rv-itch/', '.rv-steam/', '.rv-discord/']
+export const LEGACY_IGNORED = ['.rv-private/', '.rv-reflections/', '.rv-social/', '.rv-journal/', '.rv-domain/', '.rv-assets/out/', ...LEGACY_VENUES]
+
+/** the shape of a name, ignoring the leading dots, the separators, the case and
+ *  a trailing plural. `rv-reflections`, `rv_reflection` and `RV-Reflections`
+ *  are the same intent, `reflections` and `docs` are not */
+const shapeOf = (s: string): string => s.toLowerCase().replace(/^\.+/, '').replace(/[-_.]/g, '').replace(/s$/, '')
+
+const LEGACY_NAME = /^\.rv-([a-z0-9][a-z0-9-]*)$/
+
+export type MoveKind = 'contract' | 'typo' | 'asks' | 'hooks' | 'cache' | 'tmp'
+/** a move onto a folder that already exists, whose files collide nowhere.
+ *  `drop`: stale leases left behind rather than moved over the live ones */
+export type MergeMove = LayoutMove & { merge: true; drop?: string[] }
+export type LayoutMove = { from: string; to: string; kind: MoveKind }
+export type LayoutRefusal = { from: string; to: string; reason: string }
+export type LayoutPlan = { moves: LayoutMove[]; refusals: LayoutRefusal[] }
+
+export type PlanInput = {
+    /** directory names at the repo root */
+    rootDirs: string[]
+    /** names already under `.shipkit/` */
+    shipkitEntries?: string[]
+    /** repo.config sets `asks.dir`, so the queue lives where the repo said */
+    asksDirSet?: boolean
+    /** core.hooksPath points at `hooks/` and its pre-commit is shipkit's */
+    hooksOurs?: boolean
+    /** `tmp/.shipkit` exists */
+    legacyCache?: boolean
+    /** a clone or a worktree sits somewhere under `tmp/` */
+    tmpHoldsRepo?: boolean
+}
+
+/** a `.git` anywhere under a folder: a clone or a linked worktree, whose
+ *  registration names its path, so moving it breaks it */
+export function holdsRepo(dir: string): boolean {
+    try {
+        for (const e of readdirSync(dir, { withFileTypes: true })) {
+            if (e.name === '.git') return true
+            if (e.isDirectory() && e.name !== 'node_modules' && holdsRepo(join(dir, e.name))) return true
+        }
+    } catch { /* unreadable: the move itself reports it */ }
+    return false
+}
+
+/** PURE: what to move, given what sits in a repo root */
+export function planLayoutMigration(i: PlanInput): LayoutPlan {
+    const taken = new Set((i.shipkitEntries ?? []).map((e) => `${SHIPKIT_DIR}/${e}`))
+    const moves: LayoutMove[] = []
+    const refusals: LayoutRefusal[] = []
+    const add = (from: string, to: string, kind: MoveKind): void => {
+        const twin = moves.find((m) => m.to === to)
+        if (taken.has(to)) {
+            refusals.push({ from, to, reason: `${twin != null ? `${twin.from}/ moves there too` : 'the target already exists'}, and merging them decides which file wins` })
+            return
+        }
+        taken.add(to)
+        moves.push({ from, to, kind })
+    }
+    // exact legacy names first, so a typo beside its correct twin is the one refused
+    const dirs = [...i.rootDirs].sort((a, b) => Number(!LEGACY_NAME.test(a)) - Number(!LEGACY_NAME.test(b)) || a.localeCompare(b))
+    for (const d of dirs) {
+        const m = LEGACY_NAME.exec(d)
+        // a legacy name one plural or separator off a known one lands on the known one
+        if (m != null) { add(d, `${SHIPKIT_DIR}/${KNOWN.find((k) => shapeOf(k) === shapeOf(m[1]!)) ?? m[1]}`, 'contract'); continue }
+        if (d === SHIPKIT_DIR) continue
+        const typo = KNOWN.find((k) => shapeOf(d) === shapeOf(`rv${k}`))
+        if (typo != null) add(d, `${SHIPKIT_DIR}/${typo}`, 'typo')
+    }
+    if (i.rootDirs.includes('asks') && i.asksDirSet !== true) add('asks', LAYOUT.asks, 'asks')
+    if (i.rootDirs.includes('hooks') && i.hooksOurs === true) add('hooks', LAYOUT.hooks, 'hooks')
+    // a cache is never worth a refusal: a warm one at the target wins. It
+    // leaves the scratch before the scratch itself moves
+    if (i.legacyCache === true) {
+        if (taken.has(LAYOUT.cache)) moves.push({ from: LEGACY_CACHE, to: LAYOUT.cache, kind: 'cache' })
+        else add(LEGACY_CACHE, LAYOUT.cache, 'cache')
+    }
+    // every repo's scratch, shipkit's own logs and the repo's plans alike
+    if (i.rootDirs.includes(LEGACY_TMP)) {
+        if (i.tmpHoldsRepo === true) refusals.push({ from: LEGACY_TMP, to: LAYOUT.tmp, reason: 'a git checkout sits under it, and a moved worktree loses its registration' })
+        else add(LEGACY_TMP, LAYOUT.tmp, 'tmp')
+    }
+    return { moves, refusals }
+}
+
+/** the text rewrite a contract move implies: `.rv-<x>` → its target
+ *  (`.shipkit/<x>` unless `targets` says otherwise), never a machine-global
+ *  `~/.rv-<x>`, never a longer name that merely starts the same.
+ *
+ *  `at` is the file's own path before and after the move. A relative path
+ *  (`../.rv-identity/brand.ts`) that resolved to a moved folder is recomputed
+ *  from the file's new place, so two folders that moved together still find
+ *  each other (`../identity/brand.ts`). */
+export function sweepText(text: string, targets: Record<string, string> | 'all', at?: { from: string; to: string }): string {
+    const names = targets === 'all' ? null : Object.keys(targets)
+    if (names != null && names.length === 0) return text
+    const alt = names == null ? '[a-z0-9][a-z0-9-]*' : names.map((n) => n.slice(LEGACY_CONTRACT_PREFIX.length).replace(/[-]/g, '\\-')).join('|')
+    const re = new RegExp(`(?<!~/)(?<![\\w.-])((?:\\.\\.?/)*)\\.rv-(${alt})(?![\\w-])`, 'g')
+    return text.replace(re, (_m, prefix: string, x: string) => {
+        const legacy = `${LEGACY_CONTRACT_PREFIX}${x}`
+        const target = (targets === 'all' ? undefined : targets[legacy]) ?? `${SHIPKIT_DIR}/${x}`
+        if (prefix === '' || at == null || posix.normalize(posix.join(posix.dirname(at.from), prefix + legacy)) !== legacy) return prefix + target
+        return relativeFrom(at.to, target)
+    })
+}
+
+/** a relative specifier from one repo path to another, always starting with `./` or `../` */
+const relativeFrom = (file: string, target: string): string => {
+    const rel = posix.relative(posix.dirname(file), target)
+    return rel.startsWith('../') ? rel : `./${rel}`
+}
+
+/** the same for a path built at run time from the file's own folder:
+ *  `join(import.meta.dir, '..', 'public/x.png')` resolved to the repo root from
+ *  `.rv-identity/`, and must climb one more level from `.shipkit/identity/`.
+ *  Only the leading `'.'` and `'..'` arguments are rewritten */
+function rebaseDirJoins(text: string, at: { from: string; to: string }, moves: LayoutMove[]): string {
+    return text.replace(/\b(join|resolve)\((\s*)(import\.meta\.dirname|import\.meta\.dir|__dirname)((?:\s*,\s*(['"])\.\.?\5)+)/g, (m, fn: string, sp: string, base: string, segs: string) => {
+        const q = /['"]/.exec(segs)![0]
+        const parts = [...segs.matchAll(/(['"])(\.\.?)\1/g)].map((x) => x[2]!)
+        const target = movedTo(moves, posix.normalize(posix.join(posix.dirname(at.from), ...parts)))
+        if (target.startsWith('../')) return m
+        const rel = posix.relative(posix.dirname(at.to), target)
+        const next = rel === '' ? [] : rel.split('/')
+        if (next.some((x) => x !== '..') || next.join('/') === parts.filter((x) => x !== '.').join('/')) return m
+        return `${fn}(${sp}${base}${next.map((x) => `, ${q}${x}${q}`).join('')}`
+    })
+}
+
+/** PURE: a file that moved keeps pointing at what it pointed at. Only what is
+ *  a path by its SHAPE is touched: an import or require specifier, a markdown
+ *  link, and `join(import.meta.dir, '..')`. Any other string is left alone,
+ *  because `'../'` in `p.replace('../', '')` is not a path. Each path is
+ *  resolved from where the file WAS, carried through the moves, and written
+ *  from where it IS; one that still resolves the same way stays byte for byte */
+export function rebaseRelative(text: string, at: { from: string; to: string }, moves: LayoutMove[]): string {
+    if (at.from === at.to) return text
+    const rebase = (spec: string): string => {
+        const target = movedTo(moves, posix.normalize(posix.join(posix.dirname(at.from), spec)))
+        if (target.startsWith('../')) return spec
+        return posix.normalize(posix.join(posix.dirname(at.to), spec)) === target ? spec : relativeFrom(at.to, target)
+    }
+    return rebaseDirJoins(text, at, moves)
+        .replace(/(\bfrom\s+|\bimport\s+|\bimport\s*\(\s*|\brequire\s*\(\s*)(['"])(\.\.?\/[^'"\s]+)\2/g, (_m, lead: string, q: string, spec: string) => `${lead}${q}${rebase(spec)}${q}`)
+        .replace(/(\]\()(\.\.?\/[^)\s#]+)/g, (_m, lead: string, spec: string) => `${lead}${rebase(spec)}`)
+}
+
+/** one repo.config.ts value that names a moved folder, as a path: the folder
+ *  then a slash, behind an optional `!`, `/` or `./`. A word, a bare folder
+ *  name and a longer name that merely starts the same stay as they are */
+function rebasePathValue(v: string, moves: LayoutMove[]): string {
+    const m = /^(!?(?:\/|\.\/)?)(.*)$/s.exec(v)!
+    const rest = m[2]!
+    const hit = moves.find((x) => rest.startsWith(`${x.from}/`))
+    return hit == null ? v : `${m[1]}${hit.to}${rest.slice(hit.from.length)}`
+}
+
+/** PURE: repo.config.ts source with every quoted path that names a moved
+ *  folder rewritten (`leakAllow` paths, `blockedPaths`, `gitignore` lines, a
+ *  prose include, any other value): each of them is a repo path by contract */
+export function sweepConfigSource(text: string, moves: LayoutMove[]): string {
+    if (moves.length === 0) return text
+    return text.replace(/(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g, (lit, q: string, body: string) => {
+        if (q === '`' && body.includes('${')) return lit
+        const next = rebasePathValue(body, moves)
+        return next === body ? lit : `${q}${next}${q}`
+    })
+}
+
+/** PURE: the loaded config with the same rewrite, so what this pass renders
+ *  from it (the ignore block) reads the values the file now holds. Only plain
+ *  objects and arrays are copied; functions and class instances are kept */
+export function rebaseConfigPaths<T>(v: T, moves: LayoutMove[]): T {
+    if (typeof v === 'string') return rebasePathValue(v, moves) as T
+    if (Array.isArray(v)) return v.map((x) => rebaseConfigPaths(x, moves)) as T
+    if (v != null && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype)
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, rebaseConfigPaths(x, moves)])) as T
+    return v
+}
+
+/** PURE: the .gitignore after the move. Old names turn into new ones, except
+ *  the folders still on disk (`keep`), whose lines keep guarding them. A
+ *  negation of one FILE inside a folder (`!.shipkit/social/README.md`) is dead
+ *  under `.shipkit/*`, because git never looks inside an excluded folder, so
+ *  the folder is re-included and re-ignored first, and the file comes back */
+export function sweepGitignore(text: string, keep: string[] = []): string {
+    const out: string[] = []
+    const have = new Set(text.split('\n'))
+    for (const line of text.split('\n')) {
+        const kept = keep.some((k) => new RegExp(`(?<![\\w-])${k.replace(/[.]/g, '\\.')}(?![\\w-])`).test(line))
+        const next = kept ? line : sweepText(line, 'all')
+        const deep = /^!\.shipkit\/([^/]+)\/(.+)$/.exec(next)
+        if (!kept && next !== line && deep != null) {
+            for (const pre of [`!${SHIPKIT_DIR}/${deep[1]}/`, `${SHIPKIT_DIR}/${deep[1]}/*`])
+                if (!have.has(pre)) { out.push(pre); have.add(pre) }
+        }
+        out.push(next)
+    }
+    return out.join('\n')
+}
+
+/** the relative file paths under a folder */
+const filesUnder = (dir: string, pre = ''): string[] => {
+    const out: string[] = []
+    for (const e of readdirSync(join(dir, pre), { withFileTypes: true })) {
+        const rel = pre === '' ? e.name : `${pre}/${e.name}`
+        if (e.isDirectory()) out.push(...filesUnder(dir, rel))
+        else out.push(rel)
+    }
+    return out
+}
+
+/** a target that already exists is the normal case in a checkout that pulled
+ *  the move: the tracked files arrived, the untracked ones (drafts, private
+ *  notes) stayed behind in the old folder. When no file name exists on both
+ *  sides, merging decides nothing, so it moves. A real collision stays refused */
+function mergeWhereNothingCollides(root: string, plan: LayoutPlan): LayoutPlan {
+    const moves: LayoutMove[] = [...plan.moves]
+    const refusals: LayoutRefusal[] = []
+    for (const r of plan.refusals) {
+        const from = join(root, r.from)
+        const to = join(root, r.to)
+        const twin = moves.some((m) => m.to === r.to)
+        const scratch = r.from === LEGACY_TMP
+        let clash = true
+        let drop: string[] = []
+        try {
+            const both = twin || !isDir(from) || !isDir(to) ? null : filesUnder(from).filter((f) => existsSync(join(to, f)))
+            drop = scratch && both != null ? both.filter((f) => STALE_LEASE.test(f)) : []
+            clash = both == null || both.length > drop.length
+        } catch { clash = true }
+        if (clash) refusals.push(r)
+        else moves.push({ from: r.from, to: r.to, kind: scratch ? 'tmp' : LEGACY_NAME.test(r.from) ? 'contract' : 'typo', merge: true, ...(drop.length > 0 ? { drop } : {}) } as MergeMove)
+    }
+    return { moves, refusals }
+}
+
+/** move every entry of one folder into another that holds none of the same names */
+function mergeInto(from: string, to: string): void {
+    for (const e of readdirSync(from, { withFileTypes: true })) {
+        const src = join(from, e.name)
+        const dst = join(to, e.name)
+        if (e.isDirectory() && isDir(dst)) mergeInto(src, dst)
+        else renameSync(src, dst)
+    }
+    rmSync(from, { recursive: true, force: true })
+}
+
+/** where a repo-relative path sat before the moves */
+const movedFrom = (moves: LayoutMove[], rel: string): string => {
+    const m = moves.find((x) => rel === x.to || rel.startsWith(`${x.to}/`))
+    return m == null ? rel : m.from + rel.slice(m.to.length)
+}
+
+const canWrite = (p: string): boolean => { try { accessSync(p, constants.W_OK); return true } catch { return false } }
+
+/** where a repo-relative path sits once the moves are made */
+const movedTo = (moves: LayoutMove[], rel: string): string => {
+    const m = moves.find((x) => rel === x.from || rel.startsWith(`${x.from}/`))
+    return m == null ? rel : m.to + rel.slice(m.from.length)
+}
+
+const isChangelog = (rel: string): boolean => /(^|\/)changelog\.md$/i.test(rel)
+
+/** a file that names the old layout on purpose carries this, and the sweep leaves it alone */
+export const SWEEP_SKIP = 'layout-sweep: skip'
+
+export type LayoutResult = {
+    moved: LayoutMove[]
+    refusals: LayoutRefusal[]
+    /** tracked files whose text the sweep rewrote */
+    swept: string[]
+    /** legacy generated files removed from the root */
+    removed: string[]
+    /** why nothing happened, when nothing could */
+    deferred?: string
+    /** the commit, when one landed */
+    commit?: string
+    /** moved, and the commit did not land: the dirt is this run's */
+    uncommitted?: true
+    /** the paths the commit would have carried, for the one who lands it by hand */
+    pending?: string[]
+}
+
+const git = (root: string, args: string[]): { code: number; out: string } => {
+    const r = Bun.spawnSync([gitBin(), ...args], { cwd: root })
+    return { code: r.exitCode, out: `${r.stdout.toString()}${r.stderr.toString()}` }
+}
+
+const dirsIn = (root: string): string[] => {
+    try { return readdirSync(root, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name) } catch { return [] }
+}
+
+const isDir = (p: string): boolean => { try { return statSync(p).isDirectory() } catch { return false } }
+
+/** does core.hooksPath point at the legacy `hooks/`, holding a shipkit pre-commit */
+export function legacyHooksOurs(root: string): boolean {
+    const r = git(root, ['config', 'core.hooksPath'])
+    const v = r.out.trim().replace(/\/+$/, '')
+    if (v !== 'hooks' && v !== join(root, 'hooks')) return false
+    try { return readFileSync(join(root, 'hooks', 'pre-commit'), 'utf8').includes('shipkit') } catch { return false }
+}
+
+/** a checkout that received the move through a merge, not through this pass,
+ *  still has core.hooksPath on the vanished `hooks/`, and git runs no hook
+ *  from a folder that is not there: the commit gates go dark in silence */
+function repointStaleHooks(root: string): void {
+    const v = git(root, ['config', 'core.hooksPath']).out.trim().replace(/\/+$/, '')
+    if (v !== 'hooks' && v !== join(root, 'hooks')) return
+    if (existsSync(join(root, 'hooks')) || !existsSync(join(root, LAYOUT.hooks, 'pre-commit'))) return
+    git(root, ['config', 'core.hooksPath', LAYOUT.hooks])
+}
+
+/** the machine-global private folder moves the same way, once per machine.
+ *  The old path stays as a symlink to the new one, so a repo still on an
+ *  older shipkit keeps reading its keyword list. The link goes once
+ *  `shipkit fleet` shows no repo on a version that reads it */
+export function moveMachinePrivate(home: string): void {
+    if (home === '') return
+    const old = join(home, '.rv-private')
+    const next = join(home, MACHINE_PRIVATE)
+    try {
+        if (!lstatSync(old).isDirectory() || existsSync(next)) return
+        mkdirSync(dirname(next), { recursive: true })
+        renameSync(old, next)
+        symlinkSync(posix.relative(home, next), old)
+    } catch { /* absent, or a link already: nothing to move */ }
+}
+
+/** what the planner reads off disk and config */
+export function readPlanInput(root: string, config?: RepoConfig): PlanInput {
+    return {
+        rootDirs: dirsIn(root),
+        shipkitEntries: isDir(join(root, SHIPKIT_DIR)) ? readdirSync(join(root, SHIPKIT_DIR)) : [],
+        asksDirSet: config?.asks?.dir != null,
+        hooksOurs: existsSync(join(root, 'hooks')) && legacyHooksOurs(root),
+        legacyCache: isDir(join(root, LEGACY_CACHE)),
+        tmpHoldsRepo: isDir(join(root, LEGACY_TMP)) && holdsRepo(join(root, LEGACY_TMP)),
+    }
+}
+
+/** a repo still carrying the old layout: the names a check reports */
+export function legacyLayoutLeft(root: string, config?: RepoConfig): string[] {
+    const plan = planLayoutMigration(readPlanInput(root, config))
+    return [...plan.moves.filter((m) => m.kind !== 'cache').map((m) => `${m.from}/`), ...plan.refusals.map((r) => `${r.from}/`)]
+}
+
+const lsFiles = (root: string, paths: string[]): string[] => {
+    if (paths.length === 0) return []
+    const r = git(root, ['ls-files', '-z', '--', ...paths])
+    return r.code === 0 ? r.out.split('\0').filter((l) => l !== '') : []
+}
+
+/** tracked text files naming a legacy folder, CHANGELOG files left as history */
+function sweepTargets(root: string, legacyNames: string[]): string[] {
+    if (legacyNames.length === 0) return []
+    const r = git(root, ['grep', '-lIz', '-F', ...legacyNames.flatMap((n) => ['-e', n])])
+    if (r.code !== 0) return []
+    return r.out.split('\0').filter((l) => l !== '' && !isChangelog(l) && l !== '.gitignore')
+}
+
+/** tracked paths among these with staged or unstaged edits */
+function dirtyAmong(root: string, paths: string[]): string[] {
+    if (paths.length === 0) return []
+    const r = git(root, ['status', '--porcelain', '-z', '--untracked-files=no', '--', ...paths])
+    return r.out.split('\0').filter((l) => l.length > 3).map((l) => l.slice(3))
+}
+
+function inProgress(root: string): string | null {
+    const g = probeGitRoot(root).root
+    if (g == null) return null
+    for (const f of ['MERGE_HEAD', 'REBASE_HEAD', 'CHERRY_PICK_HEAD', 'rebase-merge', 'rebase-apply'])
+        if (existsSync(join(g.gitDir, f))) return `a ${f.toLowerCase().replace(/_head$/, '').replace(/-.*/, '')} is in progress`
+    if (git(root, ['symbolic-ref', '--quiet', 'HEAD']).code !== 0) return 'HEAD is detached'
+    return null
+}
+
+export type MigrateOpts = {
+    config?: RepoConfig
+    /** re-render the SK004 block into this .gitignore text (SK004 owns the
+     *  block). `legacy`: an old folder is still on disk, so its name stays
+     *  ignored. `config`: the repo config with its paths already moved, which
+     *  is what the block must be rendered from */
+    renderGitignore?: (text: string, legacy: boolean, config?: RepoConfig) => string
+}
+
+/** tracked symlinks, with where each points */
+function trackedLinks(root: string): { rel: string; target: string }[] {
+    const r = git(root, ['ls-files', '-s', '-z'])
+    if (r.code !== 0) return []
+    const out: { rel: string; target: string }[] = []
+    for (const row of r.out.split('\0')) {
+        if (!row.startsWith('120000 ')) continue
+        const rel = row.slice(row.indexOf('\t') + 1)
+        try { out.push({ rel, target: readlinkSync(join(root, rel)) }) } catch { /* gone from disk: nothing to relink */ }
+    }
+    return out
+}
+
+/**
+ * Apply the plan. Returns what moved, what the sweep rewrote and whether the
+ * commit landed. Never throws: a permission error or a race leaves the repo
+ * where it was, and the next run tries again.
+ */
+export function migrateLayout(root: string, o: MigrateOpts = {}): LayoutResult {
+    repointStaleHooks(root)
+    moveMachinePrivate(homedir())
+    const input = readPlanInput(root, o.config)
+    const plan = mergeWhereNothingCollides(root, planLayoutMigration(input))
+    const legacyStatus = LEGACY_GENERATED.filter((f) => existsSync(join(root, f)))
+    const out: LayoutResult = { moved: [], refusals: plan.refusals, swept: [], removed: [] }
+    if (plan.moves.length === 0 && legacyStatus.length === 0) return out
+
+    const inGit = probeGitRoot(root).root != null
+    if (inGit) {
+        if (nestedIn(root) != null) return { ...out, deferred: 'this repo is a folder of a larger git repo, whose index is not shipkit\'s to rewrite' }
+        const busy = inProgress(root)
+        if (busy != null) return { ...out, deferred: busy }
+    }
+
+    const contractNames = plan.moves.filter((m) => m.kind === 'contract').map((m) => m.from)
+    const targets = Object.fromEntries(plan.moves.filter((m) => m.kind === 'contract').map((m) => [m.from, m.to]))
+    const sources = plan.moves.filter((m) => m.kind !== 'cache').map((m) => m.from)
+    const tracked = inGit ? lsFiles(root, [...sources, ...legacyStatus]) : []
+    // a moved file is rebased whether or not it names an old folder, and
+    // repo.config.ts whenever one of its values names one
+    const configNames = inGit && lsFiles(root, [CONFIG_FILE]).length > 0 && sweepConfigSource(readFileSync(join(root, CONFIG_FILE), 'utf8'), plan.moves) !== readFileSync(join(root, CONFIG_FILE), 'utf8') ? [CONFIG_FILE] : []
+    // a legacy generated file is dropped, never rewritten: a rewrite would
+    // write it back after the drop, and the commit would keep it
+    const dropped = new Set<string>(legacyStatus)
+    const swept = inGit ? [...new Set([...sweepTargets(root, contractNames), ...tracked.filter((t) => /\.(m?[jt]sx?|json|md)$/.test(t)), ...configNames])].filter((f) => !dropped.has(f)) : []
+    const links = inGit ? trackedLinks(root) : []
+    // commit the ignore file when git tracks it, or when this pass creates it:
+    // it is what keeps the moved private folders out. An existing untracked
+    // one is the repo's choice, and naming it in the pathspec refuses the commit
+    const giExisted = existsSync(join(root, '.gitignore'))
+    const giTracked = inGit && lsFiles(root, ['.gitignore']).length > 0
+    if (inGit) {
+        const dirty = dirtyAmong(root, [...tracked, ...swept, ...links.map((l) => l.rel), '.gitignore'])
+        if (dirty.length > 0) return { ...out, deferred: `${dirty.slice(0, 3).join(', ')}${dirty.length > 3 ? ` +${dirty.length - 3}` : ''} carries uncommitted edits, and the move commit would take them along` }
+    }
+
+    // every rewrite is computed, and every write is checked, BEFORE anything
+    // moves: a move that stops part way leaves no old folder for the next run
+    // to find, so there is no resuming it, only not starting it
+    const moves = plan.moves.filter((m) => m.kind !== 'cache' || !existsSync(join(root, m.to)))
+    const writes: { now: string; text: string }[] = []
+    for (const rel of swept) {
+        const text = readFileSync(join(root, rel), 'utf8')
+        if (text.includes(SWEEP_SKIP)) continue
+        const now = movedTo(moves, rel)
+        const paths = rel === CONFIG_FILE ? sweepConfigSource(text, moves) : text
+        const next = sweepText(rebaseRelative(paths, { from: rel, to: now }, moves), targets, { from: rel, to: now })
+        if (next !== text) writes.push({ now, text: next })
+    }
+    const relinks: { now: string; target: string }[] = []
+    for (const l of links) {
+        const now = movedTo(moves, l.rel)
+        if (l.target.startsWith('/')) continue
+        const was = posix.normalize(posix.join(posix.dirname(l.rel), l.target))
+        const target = movedTo(moves, was)
+        if (target === was && now === l.rel) continue
+        const next = posix.relative(posix.dirname(now), target)
+        if (next !== l.target) relinks.push({ now, target: next })
+    }
+    const unwritable = [
+        ...writes.map((w) => join(root, movedFrom(moves, w.now))),
+        ...moves.flatMap((m) => [join(root, m.from), dirname(join(root, m.from))]),
+        join(root, '.gitignore'),
+    ].filter((p) => existsSync(p) && !canWrite(p))
+    if (unwritable.length > 0) return { ...out, deferred: `${unwritable.slice(0, 3).map((p) => p.slice(root.length + 1) || '.').join(', ')} is not writable, so the move would stop part way` }
+
+    const gi = join(root, '.gitignore')
+    const giOriginal = existsSync(gi) ? readFileSync(gi, 'utf8') : ''
+    const config = o.config == null ? undefined : rebaseConfigPaths(o.config, moves)
+    const render = (text: string, legacy: boolean): string => (o.renderGitignore != null ? o.renderGitignore(text, legacy, config) : text)
+    const stillOld = (): string[] => dirsIn(root).filter((d) => d.startsWith(LEGACY_CONTRACT_PREFIX))
+    try {
+        // 1. both layouts ignored while any folder is in flight
+        const giBoth = render(sweepGitignore(giOriginal, dirsIn(root).filter((d) => d.startsWith(LEGACY_CONTRACT_PREFIX))), true)
+        if (giBoth !== giOriginal) writeFileSync(gi, giBoth)
+
+        // 2. the folders
+        mkdirSync(join(root, SHIPKIT_DIR), { recursive: true })
+        for (const m of plan.moves) {
+            const from = join(root, m.from)
+            const to = join(root, m.to)
+            if (m.kind === 'cache' && existsSync(to)) { rmSync(from, { recursive: true, force: true }); continue }
+            mkdirSync(dirname(to), { recursive: true })
+            if ('merge' in m) {
+                for (const f of (m as MergeMove).drop ?? []) rmSync(join(from, f), { force: true })
+                mergeInto(from, to)
+            }
+            else renameSync(from, to)
+            out.moved.push(m)
+        }
+        for (const f of legacyStatus) { rmSync(join(root, f), { force: true }); out.removed.push(f) }
+
+        // 3. the text and the links that named the old folders
+        for (const w of writes) { writeFileSync(join(root, w.now), w.text); out.swept.push(w.now) }
+        for (const l of relinks) { rmSync(join(root, l.now), { force: true }); symlinkSync(l.target, join(root, l.now)); out.swept.push(l.now) }
+
+        // 4. the old names leave the ignore file only with their folders
+        const left = stillOld()
+        const giFinal = render(sweepGitignore(giOriginal, left), left.length > 0)
+        if (giFinal !== readFileSync(gi, 'utf8')) writeFileSync(gi, giFinal)
+    } catch (e) {
+        // whatever moved is under .shipkit/, whatever did not is still old:
+        // both stay ignored, and nothing pretends a later run finishes it
+        try { writeFileSync(gi, render(sweepGitignore(giOriginal, stillOld()), true)) } catch { /* the message below says what to check */ }
+        return { ...out, deferred: `the move stopped part way (${(e as Error).message.slice(0, 120)}). What moved is under ${SHIPKIT_DIR}/ and both layouts stay ignored: finish the rest by hand, then commit` }
+    }
+
+    const hooksMoved = out.moved.some((m) => m.kind === 'hooks')
+    if (hooksMoved && inGit) git(root, ['config', 'core.hooksPath', LAYOUT.hooks])
+    if (!inGit) return out
+
+    // 4. the index: every tracked file keeps its tracking under the new name
+    const renamed = (rel: string): string | null => {
+        for (const m of out.moved) if (rel === m.from || rel.startsWith(`${m.from}/`)) return m.kind === 'typo' ? null : m.to + rel.slice(m.from.length)
+        return null
+    }
+    const typoTracked = tracked.filter((rel) => out.moved.some((m) => m.kind === 'typo' && rel.startsWith(`${m.from}/`)))
+    const typoKept = typoTracked
+        .map((rel) => { const m = out.moved.find((x) => rel.startsWith(`${x.from}/`))!; return m.to + rel.slice(m.from.length) })
+        .filter((to) => git(root, ['check-ignore', '-q', '--no-index', to]).code !== 0)
+    const added = [...tracked.map(renamed).filter((p): p is string => p != null), ...typoKept]
+    if (tracked.length > 0) git(root, ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...tracked])
+    if (added.length > 0) git(root, ['add', '-f', '--', ...added])
+    const giNew = !giExisted && existsSync(join(root, '.gitignore'))
+    if (giNew) git(root, ['add', '--', '.gitignore'])
+    // a swept file inside a moved folder is committed only when it stayed tracked
+    const inMoved = (p: string): boolean => out.moved.some((m) => p.startsWith(`${m.to}/`))
+    const sweptTracked = out.swept.filter((p) => !inMoved(p) || added.includes(p))
+    // the ignore file rides only when this pass changed it: a second move of a
+    // recreated tmp/ changes nothing git tracks, and an empty commit is no failure
+    const giChanged = giNew || (giTracked && readFileSync(join(root, '.gitignore'), 'utf8') !== giOriginal)
+    const touched = [...new Set([...tracked, ...added, ...sweptTracked, ...(giChanged ? ['.gitignore'] : [])])]
+    if (touched.length === 0) return out
+    // the title names what this commit carries; a pass that did neither has
+    // nothing tracked to land and returned above
+    const what = layoutSummary(out)
+    if (what === '') return out
+    const landed = machineCommit({ anchor: root, message: `chore(machine): ${what}`, paths: touched.map((p) => join(root, p)) })
+    if (!landed) return { ...out, uncommitted: true, pending: touched }
+    out.commit = git(root, ['rev-parse', '--short', 'HEAD']).out.trim()
+    return out
+}

package/src/core/motherhome.ts

@@ -10,11 +10,12 @@
 // path no longer exists are pruned on every write. Churn control: a row
 // rewrites only when its DATA changes or its last-seen day is older than
 // 7 days. Never fails the calling command.
-import { existsSync, readFileSync, statSync } from 'fs'
+import { existsSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
 import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
+import { isLinkedWorktree } from './git-root.ts'
 import { machineCommit } from './machine-commit.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
@@ -69,13 +70,6 @@ function consumptionMode(root: string): string {
     } catch { return '?' }
 }
 
-/** a LINKED worktree, where `.git` is a file pointing at the main checkout
- *  rather than a directory. Cheap on purpose: this runs on every check pass in
- *  every repo, and spawning git to learn it would cost more than the write. */
-function isLinkedWorktree(root: string): boolean {
-    try { return statSync(join(root, '.git')).isFile() } catch { return false }
-}
-
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {