@aperant/framework 0.6.2

package/src/cli/config/upgrade-gitignore.mjs

@@ -0,0 +1,332 @@
+/**
+ * upgrade-gitignore.mjs — rewrite `.aperant/.gitignore` to the post-C31
+ * template (R6), now policy-driven (C35).
+ *
+ * C31/R6 rationale: state.json, team-status/, events/ are per-machine
+ * coordination data — committing them leaks PIDs + hostnames + incarnation
+ * counters and causes merge conflicts in the normal dev loop. INDEX.md and
+ * ROADMAP.md are derived from JSON source of truth; committing them creates
+ * a two-way write path that drifts. R6 pulled all of them behind the
+ * deny-by-default wall.
+ *
+ * C35 layered a share-policy on top of that baseline so users can deliberately
+ * opt into sharing roadmap/**, team.json, decisions/, digests/, and per-task
+ * artifacts. See:
+ *   - spec.md §4 for the artifact taxonomy (ephemeral / derived / shared-
+ *     source / durable-source / local-private).
+ *   - spec.md §5 for the signature change: buildAperantGitignoreTemplate now
+ *     takes a resolved policy and emits the matching allow rules inline.
+ *   - share-policy.mjs for the resolver + matcher that drive this template
+ *     and audit in lockstep. If you add a new shared-source file, add it in
+ *     BOTH places or the audit will report ghost violations.
+ *
+ * C36 completed the folder reshape: the durable-source context payload now
+ * lives under `context/installed/` (the template's allow-rule below) and
+ * runtime decision ledgers live under `context/notes/` (deny-by-default —
+ * no rule emitted, the wildcard ignore catches them). The retired `plans/`
+ * directory is not referenced anywhere. Solo default still emits the same
+ * skeleton of durable-source allow rules — the legacy plural-contexts rule
+ * was replaced in place by `!context/installed/**`, not layered on.
+ *
+ * This helper is NON-DESTRUCTIVE:
+ *   - Backs up the old file to `.aperant/.gitignore.pre-c31.backup`.
+ *   - Writes the new template.
+ *   - Greps `git ls-files` for any currently-tracked files that WOULD become
+ *     ignored and prints the suggested `git rm --cached -- <file>` list.
+ *   - Never runs git commands on the user's behalf; the user decides when to
+ *     untrack the files.
+ *
+ * The init.mjs writer consumes `buildAperantGitignoreTemplate(policy)` for
+ * new installs so the two surfaces can never drift.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { copyFileSync, existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { DEFAULT_SHARE_POLICY, resolveSharePolicy } from './share-policy.mjs'
+
+/**
+ * The canonical .aperant/.gitignore template for the R6 layout, specialized
+ * by a resolved share policy (C35).
+ *
+ * No-arg form expands DEFAULT_SHARE_POLICY (the `solo` preset) so existing
+ * callers that don't know about the policy surface still produce the exact
+ * bytes the R6 tests pin.
+ *
+ * @param {ReturnType<typeof resolveSharePolicy>} [policy]
+ * @returns {string}
+ *
+ * @internal
+ */
+export function buildAperantGitignoreTemplate(policy = DEFAULT_SHARE_POLICY) {
+	const lines = [
+		'# ━━━ Aperant Framework — deny by default, allow durable/reviewable files ━━━',
+		'#',
+		'# Everything is ignored unless explicitly allowed below. New files',
+		'# default to private — safer than allowlisting ignores.',
+		'#',
+		'# File classes (see spec §13.3 for the full taxonomy — C35):',
+		'#   durable-source (always committed): config.json, .gitignore, axes.json,',
+		'#     features/, prompts/, templates/, workflows/*.md, context/installed/, standards/ —',
+		'#     framework scaffolding that ships with the repo. Runtime workflow run',
+		'#     files (workflows/*.json + workflows/archive/) are ephemeral.',
+		'#   shared-source (committed iff matching share.* toggle is on):',
+		'#     team.json, roadmap/**, decisions/*.md, digests/*.md, tasks/*/** —',
+		'#     the allow rules below are emitted only when the policy opts in.',
+		'#   ephemeral/coordination (always ignored): state.json, active.json (legacy, removed in C34 — rule kept as defense in depth), events/,',
+		'#     locks/, team-status/, paused/, pending-effects.jsonl — per-machine',
+		'#     lifecycle data; committing leaks PIDs + hostnames.',
+		'#   derived/regenerated (always ignored): tasks/INDEX.md, roadmap/**/ROADMAP.md,',
+		'#     decisions/INDEX.md — humans read the Markdown, machines write the JSON.',
+		'',
+		'# Ignore everything by default',
+		'*',
+		'',
+		'# ── Durable / reviewable (committed — installed by apt-tools init) ─',
+		'',
+		'!.gitignore',
+		'!config.json',
+		'!axes.json',
+		'',
+		'# Feature registry (created by /apt:scan)',
+		'!features/',
+		'!features/**',
+		'',
+		'# Agent prompts and templates',
+		'!prompts/',
+		'!prompts/**',
+		'!templates/',
+		'!templates/**',
+		'',
+		'# Workflow definitions (framework-distributed markdown only — runtime',
+		'# workflow run files are ephemeral. apt-tools workflow create writes',
+		'# .aperant/workflows/{id}.json per-review/per-task; those must stay ignored.',
+		'# A bare `!workflows/**` would un-ignore them and pollute git status.)',
+		'!workflows/',
+		'!workflows/*.md',
+		'',
+		'# Planning context (installed payload — runtime notes under context/notes/ stay ignored)',
+		'# Re-include the parent `context/` directory so git descends into it; the',
+		'# `!context/installed/**` pattern only works when its parent is not ignored.',
+		'# `context/notes/` stays deny-by-default — no rule below negates it.',
+		'!context/',
+		'!context/installed/',
+		'!context/installed/**',
+		'',
+		'# Standards',
+		'!standards/',
+		'!standards/**',
+		'',
+		'# ── Shared team files (committed to git) ──────────────────────────',
+		'',
+	]
+
+	// ── Shared-source: team.json (share.team.roster) ────────────────────────
+	if (policy.team.roster) {
+		lines.push('# Team configuration (members auto-detected from git)')
+		lines.push('!team.json # class: shared-source')
+		lines.push('')
+	}
+
+	// ── Shared-source: tasks (share.tasks) ──────────────────────────────────
+	// When tasks are shared, expose per-task directories but keep the derived
+	// INDEX.md explicitly denied (it is regenerated from task records).
+	if (policy.tasks) {
+		lines.push('# Task specs + plans (the per-task directory content, not the INDEX)')
+		lines.push('!tasks/')
+		lines.push('tasks/*')
+		lines.push('# Re-allow per-task directories; INDEX.md is derived and stays ignored.')
+		lines.push('!tasks/*/ # class: shared-source')
+		lines.push('!tasks/*/** # class: shared-source')
+		lines.push('')
+	}
+
+	// ── Shared-source: roadmap (share.roadmap) ──────────────────────────────
+	if (policy.roadmap) {
+		lines.push('# Roadmap JSON (source of truth — ROADMAP.md is derived, below)')
+		lines.push('!roadmap/')
+		lines.push('!roadmap/** # class: shared-source')
+		lines.push('# Derived markdown views of roadmap JSON — regenerated on every sync.')
+		lines.push('roadmap/**/ROADMAP.md')
+		lines.push('')
+	}
+
+	// ── Shared-source: decisions (share.decisions) ──────────────────────────
+	if (policy.decisions) {
+		lines.push('# Decision records (output of /apt:discuss + /apt:roundtable)')
+		lines.push('!decisions/')
+		lines.push('!decisions/*.md # class: shared-source')
+		lines.push('# INDEX.md is derived and regenerated on every drain.')
+		lines.push('decisions/INDEX.md')
+		lines.push('')
+	}
+
+	// ── Shared-source: digests (share.digests, already inherited) ──────────
+	if (policy.digests) {
+		lines.push('# Weekly narrative digests (apt-team-docs-narrator output)')
+		lines.push('!digests/')
+		lines.push('!digests/*.md # class: shared-source')
+		lines.push('# Ephemeral helpers stay denied regardless of share.digests.')
+		lines.push('digests/.last-run.json')
+		lines.push('digests/errors.log')
+		lines.push('')
+	}
+
+	lines.push('# ── Ephemeral coordination (R2/R6/R10 — per-machine, never committed)')
+	lines.push('# Listed explicitly so future maintainers cannot accidentally un-ignore')
+	lines.push('# them with a broad `!foo/**` allow rule. These files hold PIDs,')
+	lines.push('# hostnames, and liveness counters that are meaningless across machines.')
+	lines.push('state.json')
+	// active.json was the pre-C34 cross-agent shim; no current apt-tools build
+	// writes it. The rule stays as defense in depth against older binaries.
+	lines.push('active.json')
+	lines.push('events/')
+	lines.push('locks/')
+	lines.push('team-status/')
+	lines.push('')
+	lines.push('# ── Derived markdown indexes (regenerated from JSON) ──────────────')
+	lines.push('tasks/INDEX.md')
+	lines.push('')
+
+	return lines.join('\n')
+}
+
+/**
+ * Run the gitignore upgrade on an existing project. Non-destructive.
+ *
+ * C35: accepts an optional pre-resolved `policy`. When omitted, reads
+ * `.aperant/config.json` from the project root and resolves via share-policy
+ * — so existing callers that don't pass a policy pick up whatever the user
+ * saved via `/apt:setup`. Falls back to DEFAULT_SHARE_POLICY (solo) if
+ * config is missing.
+ *
+ * @param {string} projectRoot
+ * @param {{ dryRun?: boolean, policy?: ReturnType<typeof resolveSharePolicy> }} [opts]
+ * @returns {{
+ *   status: 'ok' | 'noop',
+ *   dryRun: boolean,
+ *   backupPath: string | null,
+ *   gitignorePath: string,
+ *   trackedButIgnored: string[],
+ *   suggestedUntrack: string | null,
+ *   replaced: boolean,
+ *   policy: ReturnType<typeof resolveSharePolicy>,
+ * }}
+ *
+ * @internal
+ */
+export function runGitignoreUpgrade(projectRoot, opts = {}) {
+	const dryRun = opts.dryRun === true
+	const aperantDir = resolve(projectRoot, '.aperant')
+	const gitignorePath = join(aperantDir, '.gitignore')
+	const backupPath = join(aperantDir, '.gitignore.pre-c31.backup')
+
+	const policy = opts.policy ?? loadPolicyFromConfig(aperantDir)
+
+	const next = buildAperantGitignoreTemplate(policy)
+	const current = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : ''
+	const alreadyUpgraded = current === next
+
+	// Detect files that would become ignored. We check the canonical list
+	// (state.json, active.json, tasks/INDEX.md, roadmap/**/ROADMAP.md) against
+	// `git ls-files` output — never fails the upgrade on git errors.
+	const trackedButIgnored = findTrackedFilesThatWillBeIgnored(projectRoot)
+	const suggestedUntrack =
+		trackedButIgnored.length > 0
+			? `git rm --cached -- ${trackedButIgnored.map((f) => JSON.stringify(f)).join(' ')}`
+			: null
+
+	if (alreadyUpgraded) {
+		return {
+			status: 'noop',
+			dryRun,
+			backupPath: null,
+			gitignorePath,
+			trackedButIgnored,
+			suggestedUntrack,
+			replaced: false,
+			policy,
+		}
+	}
+
+	if (dryRun) {
+		return {
+			status: 'ok',
+			dryRun: true,
+			backupPath: null,
+			gitignorePath,
+			trackedButIgnored,
+			suggestedUntrack,
+			replaced: false,
+			policy,
+		}
+	}
+
+	if (existsSync(gitignorePath)) {
+		copyFileSync(gitignorePath, backupPath)
+	}
+	writeFileSync(gitignorePath, next, 'utf-8')
+
+	return {
+		status: 'ok',
+		dryRun: false,
+		backupPath: existsSync(backupPath) ? backupPath : null,
+		gitignorePath,
+		trackedButIgnored,
+		suggestedUntrack,
+		replaced: true,
+		policy,
+	}
+}
+
+function loadPolicyFromConfig(aperantDir) {
+	const configPath = join(aperantDir, 'config.json')
+	if (!existsSync(configPath)) return resolveSharePolicy({})
+	try {
+		const config = JSON.parse(readFileSync(configPath, 'utf-8'))
+		return resolveSharePolicy(config)
+	} catch {
+		return resolveSharePolicy({})
+	}
+}
+
+function findTrackedFilesThatWillBeIgnored(projectRoot) {
+	const candidates = ['.aperant/state.json', '.aperant/active.json', '.aperant/tasks/INDEX.md']
+	// roadmap/**/ROADMAP.md — enumerate via git ls-files below.
+	const tracked = new Set()
+	try {
+		const out = execFileSync('git', ['ls-files', '-z', '--', '.aperant/'], {
+			cwd: projectRoot,
+			encoding: 'utf-8',
+		})
+		for (const entry of out.split('\0')) {
+			if (!entry) continue
+			tracked.add(entry)
+		}
+	} catch {
+		// Not a git repo, or no tracked files — return empty list.
+		return []
+	}
+
+	const hits = []
+	for (const c of candidates) {
+		if (tracked.has(c)) hits.push(c)
+	}
+	// Roadmap derived markdown: any tracked `.aperant/roadmap/.../ROADMAP.md`.
+	for (const entry of tracked) {
+		if (/^\.aperant\/roadmap\/.*ROADMAP\.md$/.test(entry)) hits.push(entry)
+	}
+	// Ephemeral directories — anything tracked under events/, locks/,
+	// team-status/ shouldn't exist, but surface them if it does.
+	for (const entry of tracked) {
+		if (/^\.aperant\/(events|locks|team-status)\//.test(entry)) hits.push(entry)
+	}
+	// Workflows: framework-distributed `.md` definitions are durable, but
+	// runtime workflow run files (workflows/*.json) and the archive subtree
+	// are ephemeral. If older clients tracked them under the broader
+	// `!workflows/**` rule, surface them so users can `git rm --cached`.
+	for (const entry of tracked) {
+		if (/^\.aperant\/workflows\//.test(entry) && !/\.md$/.test(entry)) hits.push(entry)
+	}
+	return hits.sort()
+}

package/src/cli/config/upgrade-layout.mjs

@@ -0,0 +1,346 @@
+/**
+ * upgrade-layout.mjs — C36 migration from the pre-C36 .aperant/ folder shape
+ * to the normalized layout:
+ *
+ *   .aperant/contexts/*         → .aperant/context/installed/*   (durable-source)
+ *   .aperant/context/*.md       → .aperant/context/notes/*.md    (local-private ledgers)
+ *   .aperant/plans/             → removed (must be empty; error if not)
+ *
+ * Contract (mirrors upgrade-gitignore.mjs):
+ *   - Deterministic: sibling files sorted; destination paths computed purely.
+ *   - Idempotent: a second run finds no sources → status:'noop', moves:[].
+ *   - Non-destructive: refuses to delete a non-empty plans/ (status:'conflict').
+ *   - Atomic-per-file: each renameSync is individually atomic; on cross-device
+ *     (EXDEV) we fall back to copyFileSync + unlinkSync. Aborts on first
+ *     failure without attempting rollback — each successful rename is durable,
+ *     so a re-run picks up whatever remains.
+ *   - Collision-safe: every destination path is checked for pre-existence
+ *     before any write; emits status:'conflict' if any destination exists.
+ *
+ * After the physical moves succeed, cascades to runGitignoreUpgrade so the
+ * .aperant/.gitignore picks up the new allowlist (`!context/installed/**`).
+ *
+ * @internal
+ */
+
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	renameSync,
+	rmdirSync,
+	statSync,
+	unlinkSync,
+} from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseFlags } from '../util/args.mjs'
+import { withFileLock } from '../util/fs-lock.mjs'
+import { err, exitWith, ok } from '../util/result.mjs'
+import { runGitignoreUpgrade } from './upgrade-gitignore.mjs'
+
+/**
+ * List plain files at the top level of `dir`. Returns [] if the directory
+ * does not exist. Ignores subdirectories (they may be the new-shape
+ * children we are migrating INTO).
+ */
+function listTopLevelFiles(dir) {
+	if (!existsSync(dir)) return []
+	const out = []
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry)
+		try {
+			if (statSync(full).isFile()) out.push(entry)
+		} catch {
+			/* skip unreadable entries */
+		}
+	}
+	return out.sort()
+}
+
+/**
+ * Plain-file count at `dir` (recursive). Used for the non-empty `plans/`
+ * conflict check — we refuse to silently delete anything.
+ */
+function countFilesRecursive(dir) {
+	if (!existsSync(dir)) return 0
+	let n = 0
+	for (const entry of readdirSync(dir)) {
+		const full = join(dir, entry)
+		try {
+			const s = statSync(full)
+			if (s.isFile()) n += 1
+			else if (s.isDirectory()) n += countFilesRecursive(full)
+		} catch {
+			/* skip */
+		}
+	}
+	return n
+}
+
+/**
+ * Plan the migration without touching the disk. Pure function — returns the
+ * set of moves, directory removals, and any conflicts detected up front.
+ *
+ * @returns {{
+ *   moves: Array<{from: string, to: string, reason: string}>,
+ *   removeDirs: string[],
+ *   conflicts: Array<{kind: string, path: string, detail?: string}>,
+ *   collisions: string[],
+ * }}
+ */
+function planMigration(aperantDir) {
+	const moves = []
+	const removeDirs = []
+	const conflicts = []
+	const collisions = []
+
+	// (1) .aperant/contexts/* → .aperant/context/installed/*
+	const oldContextsDir = join(aperantDir, 'contexts')
+	const newInstalledDir = join(aperantDir, 'context', 'installed')
+	for (const f of listTopLevelFiles(oldContextsDir)) {
+		const from = join(oldContextsDir, f)
+		const to = join(newInstalledDir, f)
+		if (existsSync(to)) collisions.push(to)
+		moves.push({ from, to, reason: 'contexts→context/installed' })
+	}
+	if (existsSync(oldContextsDir)) removeDirs.push(oldContextsDir)
+
+	// (2) .aperant/context/*.md (top-level files) → .aperant/context/notes/*.md
+	//     Leave context/installed/ and context/notes/ subdirs untouched.
+	const contextDir = join(aperantDir, 'context')
+	const newNotesDir = join(contextDir, 'notes')
+	for (const f of listTopLevelFiles(contextDir)) {
+		const from = join(contextDir, f)
+		const to = join(newNotesDir, f)
+		if (existsSync(to)) collisions.push(to)
+		moves.push({ from, to, reason: 'context/→context/notes' })
+	}
+
+	// (3) .aperant/plans/ — must be empty; refuse to delete otherwise.
+	const plansDir = join(aperantDir, 'plans')
+	if (existsSync(plansDir)) {
+		const filesInPlans = countFilesRecursive(plansDir)
+		if (filesInPlans > 0) {
+			conflicts.push({
+				kind: 'plans-non-empty',
+				path: plansDir,
+				detail: `${filesInPlans} file(s) present — relocate manually before re-running upgrade-layout`,
+			})
+		} else {
+			removeDirs.push(plansDir)
+		}
+	}
+
+	return { moves, removeDirs, conflicts, collisions }
+}
+
+/**
+ * Rename a single file, falling back to copy+unlink on EXDEV (cross-device).
+ */
+function renameWithExdevFallback(from, to) {
+	try {
+		renameSync(from, to)
+	} catch (e) {
+		if (e && e.code === 'EXDEV') {
+			copyFileSync(from, to)
+			unlinkSync(from)
+			return
+		}
+		throw e
+	}
+}
+
+/**
+ * Main entry. Wrapped in a file lock keyed on
+ * `.aperant/config.lock-upgrade-layout` so concurrent callers serialize.
+ *
+ * @param {string} projectRoot
+ * @param {{ dryRun?: boolean }} [opts]
+ * @returns {{
+ *   status: 'ok' | 'noop' | 'conflict',
+ *   dryRun: boolean,
+ *   moves: Array<{from: string, to: string, ok: boolean, error?: string}>,
+ *   removedDirs: string[],
+ *   conflicts: Array<{kind: string, path: string, detail?: string}>,
+ *   collisions: string[],
+ *   gitignoreResult: object | null,
+ *   message: string,
+ * }}
+ */
+export function runLayoutUpgrade(projectRoot, opts = {}) {
+	const dryRun = opts.dryRun === true
+	const targetDir = resolve(projectRoot)
+	const aperantDir = join(targetDir, '.aperant')
+	const lockPath = join(aperantDir, 'config.lock-upgrade-layout')
+
+	// Ensure the lock file's parent exists even on a freshly-cloned repo that
+	// has no .aperant/ yet — withFileLock would otherwise reject on mkdir.
+	if (!existsSync(aperantDir)) {
+		return {
+			status: 'noop',
+			dryRun,
+			moves: [],
+			removedDirs: [],
+			conflicts: [],
+			collisions: [],
+			gitignoreResult: null,
+			message: 'No .aperant/ directory — nothing to migrate.',
+		}
+	}
+
+	return withFileLock(
+		lockPath,
+		() => {
+			const plan = planMigration(aperantDir)
+
+			// Conflict: non-empty plans/. Refuse to proceed.
+			if (plan.conflicts.length > 0) {
+				return {
+					status: 'conflict',
+					dryRun,
+					moves: [],
+					removedDirs: [],
+					conflicts: plan.conflicts,
+					collisions: plan.collisions,
+					gitignoreResult: null,
+					message:
+						'Migration blocked: non-empty plans/ directory. Relocate its contents manually before re-running.',
+				}
+			}
+
+			// Collision: a destination file already exists. Refuse to clobber.
+			if (plan.collisions.length > 0) {
+				return {
+					status: 'conflict',
+					dryRun,
+					moves: [],
+					removedDirs: [],
+					conflicts: [],
+					collisions: plan.collisions,
+					gitignoreResult: null,
+					message: 'Migration blocked: destination path(s) already exist.',
+				}
+			}
+
+			// Nothing to do — idempotent second run.
+			if (plan.moves.length === 0 && plan.removeDirs.length === 0) {
+				const gi = dryRun ? null : runGitignoreUpgrade(targetDir)
+				return {
+					status: 'noop',
+					dryRun,
+					moves: [],
+					removedDirs: [],
+					conflicts: [],
+					collisions: [],
+					gitignoreResult: gi,
+					message: 'No legacy paths detected — layout already at C36 shape.',
+				}
+			}
+
+			// Dry-run: report the plan and exit.
+			if (dryRun) {
+				return {
+					status: 'ok',
+					dryRun: true,
+					moves: plan.moves.map((m) => ({ from: m.from, to: m.to, ok: false })),
+					removedDirs: plan.removeDirs,
+					conflicts: [],
+					collisions: [],
+					gitignoreResult: null,
+					message: `Dry run: would move ${plan.moves.length} file(s) and remove ${plan.removeDirs.length} empty dir(s).`,
+				}
+			}
+
+			// Apply: mkdir parents, rename each file, then rmdir empty legacy dirs.
+			const performedMoves = []
+			let failingMove = null
+			try {
+				for (const m of plan.moves) {
+					failingMove = m
+					const destParent = join(m.to, '..')
+					mkdirSync(destParent, { recursive: true })
+					renameWithExdevFallback(m.from, m.to)
+					performedMoves.push({ from: m.from, to: m.to, ok: true })
+					failingMove = null
+				}
+			} catch (e) {
+				return {
+					status: 'conflict',
+					dryRun,
+					moves: performedMoves.concat([
+						{
+							from: failingMove?.from ?? 'unknown',
+							to: failingMove?.to ?? 'unknown',
+							ok: false,
+							error: String(e?.message ?? e),
+						},
+					]),
+					removedDirs: [],
+					conflicts: [],
+					collisions: [],
+					gitignoreResult: null,
+					message:
+						'Migration aborted mid-apply. Each completed rename is atomic; re-run upgrade-layout to resume.',
+				}
+			}
+
+			const removedDirs = []
+			for (const d of plan.removeDirs) {
+				try {
+					// Only remove if now empty (post-move) — preserves safety for
+					// any stray subdirs we did not explicitly migrate.
+					if (existsSync(d) && readdirSync(d).length === 0) {
+						rmdirSync(d)
+						removedDirs.push(d)
+					}
+				} catch {
+					/* non-fatal; user can clean up by hand */
+				}
+			}
+
+			// Cascade: rewrite .aperant/.gitignore to the new allowlist.
+			const gitignoreResult = runGitignoreUpgrade(targetDir)
+
+			return {
+				status: 'ok',
+				dryRun: false,
+				moves: performedMoves,
+				removedDirs,
+				conflicts: [],
+				collisions: [],
+				gitignoreResult,
+				message: `Migrated ${performedMoves.length} file(s); removed ${removedDirs.length} empty legacy dir(s).`,
+			}
+		},
+		{ projectRoot: targetDir },
+	)
+}
+
+export { listTopLevelFiles as _listTopLevelFilesForTests, planMigration as _planMigrationForTests }
+
+/**
+ * CLI entry wrapper mirroring cmdConfigUpgradeGitignore's shape.
+ */
+export function cmdConfigUpgradeLayout(projectDir, extraArgs = []) {
+	if (!projectDir) {
+		return err('Usage: apt-tools config upgrade-layout <project-dir> [--dry-run]')
+	}
+	const targetDir = resolve(projectDir)
+	const flags = parseFlags(extraArgs)
+	const dryRun = flags.has('dry-run')
+	const result = runLayoutUpgrade(targetDir, { dryRun })
+	const envelope = {
+		status: result.status,
+		command: 'config-upgrade-layout',
+		projectDir: targetDir,
+		dryRun: result.dryRun,
+		moves: result.moves,
+		removedDirs: result.removedDirs,
+		conflicts: result.conflicts,
+		collisions: result.collisions,
+		gitignoreResult: result.gitignoreResult,
+		message: result.message,
+	}
+	return result.status === 'conflict' ? exitWith(envelope, 2) : ok(envelope)
+}