@namewta/speculo 0.6.1 → 0.7.0

package/dist/src/migrate.js

@@ -1,939 +0,0 @@
-import { cp, mkdir, readdir, readFile, rename, rm, writeFile, } from "node:fs/promises";
-import { basename, dirname, join, relative, resolve } from "node:path";
-import { pathExists } from "./utils.js";
-const V2_MARKERS = [
-    "dev-status.json",
-    "doc-status.json",
-    "person-status.json",
-    ".config",
-    "archive",
-    "dev",
-    "doc",
-];
-const TRANSITIONAL_DOCS_STATE = join("commands", ".config", "docs-sync-state.json");
-const SPECDEV_STATUS = join("specdev", "status.json");
-const COMMAND_RUN_RE = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
-const LEGACY_ROOT_ENTRIES = new Set([
-    "AGENTS.md",
-    ".config",
-    "archive",
-    "commands",
-    "dev",
-    "doc",
-    "person",
-    "dev-status.json",
-    "doc-status.json",
-    "person-status.json",
-    ".DS_Store",
-]);
-const CHANGE_NAME_RE = /^(\d{4})-(\d{2})-(\d{2})-([a-z0-9]+(?:-[a-z0-9]+)*)$/;
-function validateSpecdevStatusV4(status) {
-    const errors = [];
-    const expectedTopLevel = ["active", "archived", "schema_version", "workflow"];
-    const actualTopLevel = Object.keys(status).sort();
-    if (JSON.stringify(actualTopLevel) !== JSON.stringify(expectedTopLevel)) {
-        errors.push("top-level fields must be schema_version, workflow, active, and archived");
-    }
-    if (status.schema_version !== 4 || status.workflow !== "specdev") {
-        errors.push("schema_version must be 4 and workflow must be specdev");
-    }
-    if (!Array.isArray(status.active) || !Array.isArray(status.archived)) {
-        errors.push("active and archived must be arrays");
-        return errors;
-    }
-    const activeNames = new Set();
-    for (const entry of status.active) {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            errors.push("active entries must be objects");
-            continue;
-        }
-        const value = entry;
-        const allowed = new Set([
-            "change",
-            "current_work",
-            "works_run",
-            "claimed_investigations",
-        ]);
-        if (Object.keys(value).some((key) => !allowed.has(key))) {
-            errors.push("active entries contain unsupported fields");
-        }
-        if (typeof value.change !== "string" || !CHANGE_NAME_RE.test(value.change)) {
-            errors.push("active change names must use YYYY-MM-DD-kebab format");
-            continue;
-        }
-        if (activeNames.has(value.change)) {
-            errors.push("active change names must be unique: " + value.change);
-        }
-        activeNames.add(value.change);
-        if (value.current_work !== null &&
-            (typeof value.current_work !== "string" ||
-                !value.current_work.startsWith("specdev/"))) {
-            errors.push("current_work must be null or a specdev work id: " + value.change);
-        }
-        if (!Array.isArray(value.works_run) ||
-            value.works_run.some((work) => typeof work !== "string" || !work.startsWith("specdev/")) ||
-            new Set(value.works_run).size !== value.works_run.length) {
-            errors.push("works_run must contain unique specdev work ids: " + value.change);
-        }
-        if (value.claimed_investigations !== undefined) {
-            if (Array.isArray(value.claimed_investigations)) {
-                const allowedClaimKeys = new Set(["id", "owner", "session", "claimed_at"]);
-                if (value.claimed_investigations.some((claim) => claim &&
-                    typeof claim === "object" &&
-                    !Array.isArray(claim) &&
-                    Object.keys(claim).some((key) => !allowedClaimKeys.has(key)))) {
-                    errors.push("investigation claims contain unsupported fields: " + value.change);
-                }
-            }
-            const claimErrors = [];
-            mergeClaims([], value.claimed_investigations, value.change, claimErrors);
-            if (claimErrors.length > 0)
-                errors.push(...claimErrors);
-        }
-    }
-    const archivedNames = new Set();
-    for (const change of status.archived) {
-        if (typeof change !== "string" || !CHANGE_NAME_RE.test(change)) {
-            errors.push("archived change names must use YYYY-MM-DD-kebab format");
-            continue;
-        }
-        if (archivedNames.has(change)) {
-            errors.push("archived change names must be unique: " + change);
-        }
-        if (activeNames.has(change)) {
-            errors.push("change appears in both active and archived: " + change);
-        }
-        archivedNames.add(change);
-    }
-    return errors;
-}
-function installRoot(target) {
-    return join(resolve(target), "speculo");
-}
-function stateRoot(target) {
-    return join(installRoot(target), ".speculo");
-}
-async function directoryNames(path) {
-    if (!(await pathExists(path)))
-        return [];
-    const entries = await readdir(path, { withFileTypes: true });
-    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-}
-async function readStatus(path, blockers) {
-    if (!(await pathExists(path))) {
-        blockers.push("Missing change status: " + path);
-        return undefined;
-    }
-    try {
-        return JSON.parse(await readFile(path, "utf8"));
-    }
-    catch {
-        blockers.push("Invalid change status JSON: " + path);
-        return undefined;
-    }
-}
-async function readJsonObject(path, blockers, label) {
-    if (!(await pathExists(path)))
-        return undefined;
-    try {
-        const value = JSON.parse(await readFile(path, "utf8"));
-        if (!value || typeof value !== "object" || Array.isArray(value)) {
-            blockers.push(label + " must be a JSON object: " + path);
-            return undefined;
-        }
-        return value;
-    }
-    catch {
-        blockers.push("Invalid " + label + " JSON: " + path);
-        return undefined;
-    }
-}
-function mergeClaims(target, source, change, blockers) {
-    if (source === undefined)
-        return;
-    if (!Array.isArray(source)) {
-        blockers.push("Invalid claimed_investigations for active change: " + change);
-        return;
-    }
-    const byId = new Map(target.map((claim) => [String(claim.id), claim]));
-    for (const claim of source) {
-        if (!claim || typeof claim !== "object" || Array.isArray(claim)) {
-            blockers.push("Invalid investigation claim for active change: " + change);
-            continue;
-        }
-        const value = claim;
-        if (typeof value.id !== "string" ||
-            typeof value.owner !== "string" ||
-            typeof value.claimed_at !== "string" ||
-            (value.session !== undefined &&
-                value.session !== null &&
-                typeof value.session !== "string")) {
-            blockers.push("Invalid investigation claim fields for active change: " + change);
-            continue;
-        }
-        const normalized = {
-            id: value.id,
-            owner: value.owner,
-            claimed_at: value.claimed_at,
-        };
-        if (value.session !== undefined)
-            normalized.session = value.session;
-        const existing = byId.get(value.id);
-        if (existing && JSON.stringify(existing) !== JSON.stringify(normalized)) {
-            blockers.push("Conflicting investigation claim " + value.id + " for active change: " + change);
-            continue;
-        }
-        if (!existing) {
-            target.push(normalized);
-            byId.set(value.id, normalized);
-        }
-    }
-}
-export async function migrateSpecdevStatusV3(status, root, blockers = []) {
-    if (status.schema_version !== 3 || status.workflow !== "specdev") {
-        blockers.push("SpecDev status migration requires schema_version 3 and workflow specdev");
-    }
-    if (!Array.isArray(status.active)) {
-        blockers.push("SpecDev v3 status active must be an array");
-    }
-    if (!Array.isArray(status.work_history)) {
-        blockers.push("SpecDev v3 status work_history must be an array");
-    }
-    if (!Array.isArray(status.completed)) {
-        blockers.push("SpecDev v3 status completed must be an array");
-    }
-    const activeByChange = new Map();
-    for (const entry of Array.isArray(status.active) ? status.active : []) {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            blockers.push("SpecDev v3 status contains an invalid active entry");
-            continue;
-        }
-        const value = entry;
-        if (typeof value.change !== "string" || !CHANGE_NAME_RE.test(value.change)) {
-            blockers.push("Invalid active change name in SpecDev v3 status");
-            continue;
-        }
-        if (value.current_work !== null &&
-            (typeof value.current_work !== "string" ||
-                !value.current_work.startsWith("specdev/"))) {
-            blockers.push("Invalid current_work for active change: " + value.change);
-            continue;
-        }
-        if (!Array.isArray(value.works_run) ||
-            value.works_run.some((work) => typeof work !== "string" || !work.startsWith("specdev/"))) {
-            blockers.push("Invalid works_run for active change: " + value.change);
-            continue;
-        }
-        const existing = activeByChange.get(value.change);
-        if (existing &&
-            existing.current_work !== value.current_work &&
-            existing.current_work !== null &&
-            value.current_work !== null) {
-            blockers.push("Conflicting current_work values for active change: " + value.change);
-            continue;
-        }
-        const migrated = existing ?? {
-            change: value.change,
-            current_work: value.current_work,
-            works_run: [],
-        };
-        if (migrated.current_work === null && typeof value.current_work === "string") {
-            migrated.current_work = value.current_work;
-        }
-        migrated.works_run = [
-            ...new Set([...migrated.works_run, ...value.works_run]),
-        ];
-        const claims = migrated.claimed_investigations ?? [];
-        mergeClaims(claims, value.claimed_investigations, value.change, blockers);
-        if (claims.length > 0 || value.claimed_investigations !== undefined) {
-            migrated.claimed_investigations = claims;
-        }
-        activeByChange.set(value.change, migrated);
-    }
-    const archived = [];
-    const archivedNames = new Set();
-    for (const entry of Array.isArray(status.completed) ? status.completed : []) {
-        if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
-            blockers.push("SpecDev v3 status contains an invalid completed entry");
-            continue;
-        }
-        const change = entry.change;
-        if (typeof change !== "string" || !CHANGE_NAME_RE.test(change)) {
-            blockers.push("Invalid archived change name in SpecDev v3 status");
-            continue;
-        }
-        if (!archivedNames.has(change)) {
-            const archivePath = join(root, "specdev", "archive", monthFromName(change), change);
-            if (!(await pathExists(archivePath))) {
-                blockers.push("Archived change directory is missing: " + archivePath);
-            }
-            archived.push(change);
-            archivedNames.add(change);
-        }
-    }
-    for (const change of activeByChange.keys()) {
-        if (archivedNames.has(change)) {
-            blockers.push("SpecDev change appears in both active and archived: " + change);
-        }
-    }
-    const migrated = {
-        schema_version: 4,
-        workflow: "specdev",
-        active: [...activeByChange.values()],
-        archived,
-    };
-    blockers.push(...validateSpecdevStatusV4(migrated).map((issue) => "Migrated SpecDev status would be invalid: " + issue));
-    return migrated;
-}
-async function validateLegacyIndex(path, blockers) {
-    if (!(await pathExists(path)))
-        return;
-    try {
-        const value = JSON.parse(await readFile(path, "utf8"));
-        if (!value ||
-            typeof value !== "object" ||
-            !Array.isArray(value.active)) {
-            blockers.push("Invalid legacy workflow index shape: " + path);
-        }
-    }
-    catch {
-        blockers.push("Invalid legacy workflow index JSON: " + path);
-    }
-}
-async function readLegacyDocsSyncState(path, blockers) {
-    if (!(await pathExists(path)))
-        return undefined;
-    try {
-        const value = JSON.parse(await readFile(path, "utf8"));
-        if (!value || typeof value !== "object" || Array.isArray(value)) {
-            blockers.push("Invalid legacy docs-sync state shape: " + path);
-            return undefined;
-        }
-        const state = value;
-        for (const key of ["tracked_docs", "tracked_assets", "synced_docs", "synced_assets"]) {
-            const entries = state[key];
-            if (entries !== undefined &&
-                (!Array.isArray(entries) || entries.some((entry) => typeof entry !== "string"))) {
-                blockers.push("Invalid legacy docs-sync " + key + ": " + path);
-            }
-        }
-        for (const key of ["last_sync_sha", "previous_sync_sha"]) {
-            const sha = state[key];
-            if (sha !== undefined && sha !== null && typeof sha !== "string") {
-                blockers.push("Invalid legacy docs-sync " + key + ": " + path);
-            }
-        }
-        return state;
-    }
-    catch {
-        blockers.push("Invalid legacy docs-sync state JSON: " + path);
-        return undefined;
-    }
-}
-function legacyName(source, originalName) {
-    const match = originalName.match(CHANGE_NAME_RE);
-    if (!match)
-        return originalName;
-    return match[1] + "-" + match[2] + "-" + match[3] +
-        "-legacy-" + source + "-" + match[4];
-}
-function monthFromName(name) {
-    return name.slice(0, 7);
-}
-async function collectActiveChanges(root, workflow, blockers) {
-    const workflowRoot = join(root, workflow);
-    const names = await directoryNames(workflowRoot);
-    const changes = [];
-    for (const name of names) {
-        if (!CHANGE_NAME_RE.test(name)) {
-            blockers.push("Malformed legacy change directory: " + join(workflowRoot, name));
-            continue;
-        }
-        const status = await readStatus(join(workflowRoot, name, ".status.json"), blockers);
-        if (!status)
-            continue;
-        if (workflow === "person") {
-            changes.push({
-                sourceWorkflow: workflow,
-                sourcePath: join(workflowRoot, name),
-                originalName: name,
-                destinationRelative: join("person", "changes", name),
-                archived: false,
-                status,
-            });
-        }
-        else {
-            const destinationName = legacyName(workflow, name);
-            changes.push({
-                sourceWorkflow: workflow,
-                sourcePath: join(workflowRoot, name),
-                originalName: name,
-                destinationRelative: join("specdev", "archive", monthFromName(name), destinationName),
-                archived: true,
-                status,
-            });
-        }
-    }
-    return changes;
-}
-async function collectArchivedChanges(root, workflow, blockers) {
-    const workflowArchive = join(root, "archive", workflow);
-    const months = await directoryNames(workflowArchive);
-    const changes = [];
-    for (const month of months) {
-        if (!/^\d{4}-\d{2}$/.test(month)) {
-            blockers.push("Malformed legacy archive month: " + join(workflowArchive, month));
-            continue;
-        }
-        for (const name of await directoryNames(join(workflowArchive, month))) {
-            if (!CHANGE_NAME_RE.test(name)) {
-                blockers.push("Malformed legacy archived change: " +
-                    join(workflowArchive, month, name));
-                continue;
-            }
-            const status = await readStatus(join(workflowArchive, month, name, ".status.json"), blockers);
-            if (!status)
-                continue;
-            if (workflow === "person") {
-                changes.push({
-                    sourceWorkflow: workflow,
-                    sourcePath: join(workflowArchive, month, name),
-                    originalName: name,
-                    destinationRelative: join("person", "archive", month, name),
-                    archived: true,
-                    status,
-                });
-            }
-            else {
-                const destinationName = legacyName(workflow, name);
-                changes.push({
-                    sourceWorkflow: workflow,
-                    sourcePath: join(workflowArchive, month, name),
-                    originalName: name,
-                    destinationRelative: join("specdev", "archive", month, destinationName),
-                    archived: true,
-                    status,
-                });
-            }
-        }
-    }
-    return changes;
-}
-export async function detectLegacyState(target) {
-    const root = stateRoot(target);
-    if (!(await pathExists(root)))
-        return false;
-    for (const marker of V2_MARKERS) {
-        if (await pathExists(join(root, marker)))
-            return true;
-    }
-    if (await pathExists(join(root, TRANSITIONAL_DOCS_STATE)))
-        return true;
-    if ((await legacyCommandRunNames(root)).length > 0)
-        return true;
-    const statusPath = join(root, SPECDEV_STATUS);
-    if (!(await pathExists(statusPath)))
-        return false;
-    try {
-        const value = JSON.parse(await readFile(statusPath, "utf8"));
-        if (!value || typeof value !== "object" || Array.isArray(value))
-            return true;
-        const status = value;
-        return status.schema_version !== 4 || validateSpecdevStatusV4(status).length > 0;
-    }
-    catch {
-        return true;
-    }
-}
-async function detectV2State(target) {
-    const root = stateRoot(target);
-    if (!(await pathExists(root)))
-        return false;
-    for (const marker of V2_MARKERS) {
-        if (await pathExists(join(root, marker)))
-            return true;
-    }
-    return false;
-}
-async function legacyCommandRunNames(root) {
-    const commandsRoot = join(root, "commands");
-    if (!(await pathExists(commandsRoot)))
-        return [];
-    const entries = await readdir(commandsRoot, { withFileTypes: true });
-    return entries
-        .filter((entry) => entry.isDirectory() && COMMAND_RUN_RE.test(entry.name))
-        .map((entry) => entry.name)
-        .sort();
-}
-export async function planMigration(target) {
-    const resolvedTarget = resolve(target);
-    const root = stateRoot(resolvedTarget);
-    const blockers = [];
-    const actions = [];
-    const changes = [];
-    const v2Detected = await detectV2State(resolvedTarget);
-    const transitionalDetected = (await pathExists(join(root, TRANSITIONAL_DOCS_STATE))) ||
-        (await legacyCommandRunNames(root)).length > 0;
-    const specdevStatus = await readJsonObject(join(root, SPECDEV_STATUS), blockers, "SpecDev status");
-    const statusVersion = specdevStatus?.schema_version;
-    const statusV3Detected = statusVersion === 3;
-    if (specdevStatus &&
-        statusVersion !== 3 &&
-        statusVersion !== 4) {
-        blockers.push("Unsupported SpecDev status schema_version: " + String(statusVersion));
-    }
-    if (specdevStatus && statusVersion === 4) {
-        blockers.push(...validateSpecdevStatusV4(specdevStatus).map((issue) => "Invalid SpecDev status v4: " + issue));
-    }
-    const sourceLayout = v2Detected
-        ? "v2"
-        : transitionalDetected
-            ? "transitional-v3"
-            : statusV3Detected
-                ? "specdev-status-v3"
-                : "none";
-    const legacyDetected = sourceLayout !== "none" || blockers.length > 0;
-    if (!legacyDetected) {
-        return {
-            target: resolvedTarget,
-            legacyDetected,
-            sourceLayout,
-            actions,
-            blockers,
-            changes,
-        };
-    }
-    if (!(await pathExists(root))) {
-        blockers.push("Missing legacy state root: " + root);
-        return {
-            target: resolvedTarget,
-            legacyDetected,
-            sourceLayout,
-            actions,
-            blockers,
-            changes,
-        };
-    }
-    if (sourceLayout === "transitional-v3" ||
-        sourceLayout === "specdev-status-v3") {
-        const oldState = join(root, TRANSITIONAL_DOCS_STATE);
-        const newState = join(root, "commands", "docs-sync", "state.json");
-        if (await pathExists(oldState)) {
-            await readLegacyDocsSyncState(oldState, blockers);
-            if (await pathExists(newState)) {
-                blockers.push("Docs-sync state destination already exists: " + newState);
-            }
-            actions.push({
-                kind: "move-docs-sync-state",
-                from: ".speculo/" + TRANSITIONAL_DOCS_STATE,
-                to: ".speculo/commands/docs-sync/state.json",
-                detail: "Move the transitional v3 baseline into its command namespace",
-            });
-        }
-        for (const name of await legacyCommandRunNames(root)) {
-            const destination = join(root, "commands", "_legacy", name);
-            if (await pathExists(destination)) {
-                blockers.push("Legacy command report destination exists: " + destination);
-            }
-            actions.push({
-                kind: "preserve-command-report",
-                from: ".speculo/commands/" + name,
-                to: ".speculo/commands/_legacy/" + name,
-                detail: "Preserve the old report directory without rewriting history",
-            });
-        }
-        if (statusV3Detected && specdevStatus) {
-            await migrateSpecdevStatusV3(specdevStatus, root, blockers);
-            actions.push({
-                kind: "migrate-specdev-status",
-                from: ".speculo/specdev/status.json (schema v3)",
-                to: ".speculo/specdev/status.json (schema v4)",
-                detail: "Reduce the global index to active and archived changes",
-            });
-        }
-        return {
-            target: resolvedTarget,
-            legacyDetected,
-            sourceLayout,
-            actions,
-            blockers,
-            changes,
-        };
-    }
-    const rootEntries = await readdir(root);
-    for (const entry of rootEntries) {
-        if (!LEGACY_ROOT_ENTRIES.has(entry)) {
-            blockers.push("Unknown legacy state entry requires manual handling: " + join(root, entry));
-        }
-    }
-    for (const workflow of ["dev", "doc", "person"]) {
-        await validateLegacyIndex(join(root, workflow + "-status.json"), blockers);
-    }
-    await readLegacyDocsSyncState(join(root, "dev", "docs-sync-state.json"), blockers);
-    for (const workflow of ["dev", "doc", "person"]) {
-        changes.push(...await collectActiveChanges(root, workflow, blockers));
-        changes.push(...await collectArchivedChanges(root, workflow, blockers));
-    }
-    const destinations = new Set();
-    for (const change of changes) {
-        if (destinations.has(change.destinationRelative)) {
-            blockers.push("Migration destination collision: " + change.destinationRelative);
-        }
-        destinations.add(change.destinationRelative);
-        actions.push({
-            kind: change.archived ? "archive-change" : "preserve-active-change",
-            from: relative(installRoot(resolvedTarget), change.sourcePath),
-            to: join(".speculo", change.destinationRelative),
-            detail: change.sourceWorkflow + "/" + change.originalName,
-        });
-    }
-    if (await pathExists(join(root, ".config"))) {
-        actions.push({
-            kind: "move-config",
-            from: ".speculo/.config",
-            to: ".speculo/specdev/.config",
-            detail: "Move shared v2 configuration into the SpecDev workflow",
-        });
-    }
-    if (await pathExists(join(root, "dev", "docs-sync-state.json"))) {
-        actions.push({
-            kind: "move-docs-sync-state",
-            from: ".speculo/dev/docs-sync-state.json",
-            to: ".speculo/commands/docs-sync/state.json",
-            detail: "Move docs-sync baseline to the global command namespace",
-        });
-    }
-    for (const legacyPath of [
-        "workflows/dev",
-        "workflows/doc",
-    ]) {
-        if (await pathExists(join(installRoot(resolvedTarget), legacyPath))) {
-            actions.push({
-                kind: "remove-legacy-asset",
-                from: legacyPath,
-                detail: "Remove framework-managed v2 asset after state migration",
-            });
-        }
-    }
-    return {
-        target: resolvedTarget,
-        legacyDetected,
-        sourceLayout,
-        actions,
-        blockers,
-        changes,
-    };
-}
-async function copyDirectoryContents(source, destination) {
-    if (!(await pathExists(source)))
-        return;
-    await mkdir(destination, { recursive: true });
-    const entries = await readdir(source, { withFileTypes: true });
-    for (const entry of entries) {
-        await cp(join(source, entry.name), join(destination, entry.name), {
-            recursive: entry.isDirectory(),
-            force: true,
-        });
-    }
-}
-function migratedStatus(change, destinationName, destinationRelative, now) {
-    const status = { ...change.status };
-    delete status.category;
-    status.schema_version = 1;
-    status.workflow = change.sourceWorkflow === "person" ? "person" : "specdev";
-    status.name = destinationName;
-    status.updated_at = now;
-    if (change.archived) {
-        status.change_status = "archived";
-        status.current_phase = "migration-archive";
-        status.archived = true;
-        status.archive_path = "speculo/.speculo/" +
-            destinationRelative.replaceAll("\\", "/");
-        if (change.sourceWorkflow !== "person") {
-            status.legacy_source = {
-                workflow: change.sourceWorkflow,
-                original_name: change.originalName,
-                original_status: change.status.change_status ?? "unknown",
-            };
-        }
-        const history = Array.isArray(status.phase_history)
-            ? [...status.phase_history]
-            : [];
-        history.push({
-            phase: "migration-archive",
-            entered_at: now,
-            completed_at: now,
-            status: "completed",
-        });
-        status.phase_history = history;
-    }
-    return status;
-}
-function migratedDocsSyncState(legacy) {
-    const tracked = Array.isArray(legacy.tracked_assets)
-        ? legacy.tracked_assets
-        : Array.isArray(legacy.tracked_docs) ? legacy.tracked_docs : [];
-    const synced = Array.isArray(legacy.synced_assets)
-        ? legacy.synced_assets
-        : Array.isArray(legacy.synced_docs) ? legacy.synced_docs : [];
-    const lastSyncSha = typeof legacy.last_sync_sha === "string"
-        ? legacy.last_sync_sha
-        : null;
-    const previousSyncSha = typeof legacy.previous_sync_sha === "string"
-        ? legacy.previous_sync_sha
-        : null;
-    const totalSyncs = typeof legacy.total_syncs === "number" &&
-        Number.isInteger(legacy.total_syncs) &&
-        legacy.total_syncs >= 0
-        ? legacy.total_syncs
-        : 0;
-    return {
-        schema_version: 4,
-        command: "docs-sync",
-        state_path: "speculo/.speculo/commands/docs-sync/state.json",
-        baseline: {
-            mode: "explicit",
-            sha: lastSyncSha,
-        },
-        last_range: {
-            from_sha: previousSyncSha,
-            to_sha: lastSyncSha,
-        },
-        project_targets: [],
-        pending_legacy_targets: [...new Set(tracked)],
-        scope_revision: 0,
-        scope_confirmed_at: null,
-        last_sync_run_at: typeof legacy.last_sync_run_at === "string"
-            ? legacy.last_sync_run_at
-            : null,
-        total_syncs: totalSyncs,
-        synced_assets: synced,
-    };
-}
-function reportMarkdown(plan, now) {
-    const lines = [
-        "# Speculo Migration Report",
-        "",
-        "- Generated: " + now,
-        "- Target: " + plan.target,
-        "- Source layout: " + plan.sourceLayout,
-        "- Actions: " + plan.actions.length,
-        "",
-        "## Actions",
-        "",
-    ];
-    for (const action of plan.actions) {
-        lines.push("- " + action.kind + ": " +
-            (action.from ? action.from : "") +
-            (action.to ? " -> " + action.to : "") +
-            " — " + action.detail);
-    }
-    lines.push("", "## Follow-up", "", "Run `speculo init <target>` and select specdev/person as needed.", "Legacy dev/doc active work is historical archive and is not resumed automatically.", "");
-    return lines.join("\n");
-}
-async function preserveLegacyCommandEntries(source, destination) {
-    if (!(await pathExists(source)))
-        return;
-    const entries = await readdir(source, { withFileTypes: true });
-    for (const entry of entries) {
-        if (entry.name === ".config" || entry.name === "_legacy")
-            continue;
-        await mkdir(destination, { recursive: true });
-        await cp(join(source, entry.name), join(destination, entry.name), {
-            recursive: entry.isDirectory(),
-            force: false,
-            errorOnExist: true,
-        });
-    }
-    await copyDirectoryContents(join(source, "_legacy"), destination);
-}
-async function writeMigrationReport(stage, plan, now) {
-    const reportRoot = join(stage, "commands", "migrate");
-    await mkdir(reportRoot, { recursive: true });
-    const stem = now.slice(0, 10) + "-workspace-migration";
-    let reportPath = join(reportRoot, stem + ".md");
-    let suffix = 1;
-    while (await pathExists(reportPath)) {
-        reportPath = join(reportRoot, stem + "-" + String(suffix).padStart(2, "0") + ".md");
-        suffix += 1;
-    }
-    await writeFile(reportPath, reportMarkdown(plan, now));
-}
-async function buildMigratedState(plan, packageRoot, stage) {
-    const root = stateRoot(plan.target);
-    const now = new Date().toISOString();
-    const templateRoot = join(packageRoot, "template");
-    if (plan.sourceLayout === "transitional-v3" ||
-        plan.sourceLayout === "specdev-status-v3") {
-        await cp(root, stage, { recursive: true, force: true });
-        const workspaceDestination = join(stage, "workspace.json");
-        if (!(await pathExists(workspaceDestination))) {
-            await cp(join(templateRoot, ".speculo", "workspace.json"), workspaceDestination, { force: false, errorOnExist: true });
-        }
-        const commandsRoot = join(stage, "commands");
-        const legacyRoot = join(commandsRoot, "_legacy");
-        for (const name of await legacyCommandRunNames(stage)) {
-            await mkdir(legacyRoot, { recursive: true });
-            await rename(join(commandsRoot, name), join(legacyRoot, name));
-        }
-        const oldState = join(stage, TRANSITIONAL_DOCS_STATE);
-        if (await pathExists(oldState)) {
-            const legacy = JSON.parse(await readFile(oldState, "utf8"));
-            const destination = join(commandsRoot, "docs-sync", "state.json");
-            await mkdir(dirname(destination), { recursive: true });
-            await writeFile(destination, JSON.stringify(migratedDocsSyncState(legacy), null, 2) + "\n");
-            await rm(oldState, { force: true });
-            const oldConfigDir = dirname(oldState);
-            if ((await readdir(oldConfigDir)).length === 0) {
-                await rm(oldConfigDir, { recursive: true, force: true });
-            }
-        }
-        const statusPath = join(stage, SPECDEV_STATUS);
-        if (await pathExists(statusPath)) {
-            const status = JSON.parse(await readFile(statusPath, "utf8"));
-            if (status.schema_version === 3) {
-                const migrationBlockers = [];
-                const migrated = await migrateSpecdevStatusV3(status, stage, migrationBlockers);
-                if (migrationBlockers.length > 0) {
-                    throw new Error([
-                        "SpecDev status changed after migration preview:",
-                        ...migrationBlockers.map((item) => "- " + item),
-                    ].join("\n"));
-                }
-                await writeFile(statusPath, JSON.stringify(migrated, null, 2) + "\n");
-            }
-        }
-        await writeMigrationReport(stage, plan, now);
-        return;
-    }
-    await cp(join(templateRoot, ".speculo"), stage, {
-        recursive: true,
-        force: true,
-    });
-    await cp(join(templateRoot, "workflows", "specdev", "_state"), join(stage, "specdev"), { recursive: true, force: true });
-    await cp(join(templateRoot, "workflows", "person", "_state"), join(stage, "person"), { recursive: true, force: true });
-    await preserveLegacyCommandEntries(join(root, "commands"), join(stage, "commands", "_legacy"));
-    await copyDirectoryContents(join(root, ".config"), join(stage, "specdev", ".config"));
-    const docsSyncSource = join(root, "dev", "docs-sync-state.json");
-    if (await pathExists(docsSyncSource)) {
-        const legacyDocsSync = JSON.parse(await readFile(docsSyncSource, "utf8"));
-        const docsSync = migratedDocsSyncState(legacyDocsSync);
-        const destination = join(stage, "commands", "docs-sync", "state.json");
-        await mkdir(dirname(destination), { recursive: true });
-        await writeFile(destination, JSON.stringify(docsSync, null, 2) + "\n");
-    }
-    const personActive = [];
-    const specdevArchived = [];
-    for (const change of plan.changes) {
-        const destination = join(stage, change.destinationRelative);
-        await mkdir(dirname(destination), { recursive: true });
-        await cp(change.sourcePath, destination, {
-            recursive: true,
-            force: false,
-            errorOnExist: true,
-        });
-        const destinationName = basename(destination);
-        const status = migratedStatus(change, destinationName, change.destinationRelative, now);
-        await writeFile(join(destination, ".status.json"), JSON.stringify(status, null, 2) + "\n");
-        if (change.sourceWorkflow === "person" &&
-            !change.archived &&
-            status.change_status === "active") {
-            personActive.push({
-                name: destinationName,
-                current_phase: status.current_phase ?? "00-init",
-                updated_at: status.updated_at,
-            });
-        }
-        if (change.sourceWorkflow !== "person" && change.archived) {
-            specdevArchived.push(destinationName);
-        }
-    }
-    await writeFile(join(stage, "specdev", "status.json"), JSON.stringify({
-        schema_version: 4,
-        workflow: "specdev",
-        active: [],
-        archived: [...new Set(specdevArchived)],
-    }, null, 2) + "\n");
-    await writeFile(join(stage, "person", "status.json"), JSON.stringify({ schema_version: 1, workflow: "person", active: personActive }, null, 2) + "\n");
-    await writeMigrationReport(stage, plan, now);
-}
-async function moveLegacyAssetsToBackup(root, backup) {
-    const moved = [];
-    for (const relativePath of [
-        "workflows/dev",
-        "workflows/doc",
-    ]) {
-        const source = join(root, relativePath);
-        if (!(await pathExists(source)))
-            continue;
-        const destination = join(backup, relativePath);
-        await mkdir(dirname(destination), { recursive: true });
-        await rename(source, destination);
-        moved.push({ source, backup: destination });
-    }
-    return moved;
-}
-async function restoreLegacyAssets(moved) {
-    for (const item of [...moved].reverse()) {
-        if (!(await pathExists(item.backup)))
-            continue;
-        await mkdir(dirname(item.source), { recursive: true });
-        await rename(item.backup, item.source);
-    }
-}
-export async function migrateSpeculo(targetArg = ".", options = {}) {
-    const target = resolve(targetArg);
-    const packageRoot = resolve(options.packageRoot ?? process.cwd());
-    const plan = await planMigration(target);
-    if (plan.blockers.length > 0) {
-        throw new Error(["Speculo migration blocked:", ...plan.blockers.map((item) => "- " + item)]
-            .join("\n"));
-    }
-    if (!plan.legacyDetected || !options.apply) {
-        return {
-            target,
-            legacyDetected: plan.legacyDetected,
-            applied: false,
-            actions: plan.actions,
-        };
-    }
-    const root = installRoot(target);
-    const state = stateRoot(target);
-    const stage = join(root, ".speculo-migrate-stage");
-    const backup = join(root, ".speculo-migrate-backup");
-    const assetBackup = join(root, ".speculo-migrate-assets");
-    await rm(stage, { recursive: true, force: true });
-    await rm(backup, { recursive: true, force: true });
-    await rm(assetBackup, { recursive: true, force: true });
-    await buildMigratedState(plan, packageRoot, stage);
-    let stateMoved = false;
-    let newStateInstalled = false;
-    let movedAssets = [];
-    try {
-        movedAssets = await moveLegacyAssetsToBackup(root, assetBackup);
-        await rename(state, backup);
-        stateMoved = true;
-        await rename(stage, state);
-        newStateInstalled = true;
-    }
-    catch (error) {
-        if (newStateInstalled && (await pathExists(state))) {
-            await rm(state, { recursive: true, force: true });
-        }
-        if (stateMoved && (await pathExists(backup))) {
-            await rename(backup, state);
-        }
-        await restoreLegacyAssets(movedAssets);
-        await rm(stage, { recursive: true, force: true });
-        throw error;
-    }
-    await rm(backup, { recursive: true, force: true });
-    await rm(assetBackup, { recursive: true, force: true });
-    return {
-        target,
-        legacyDetected: true,
-        applied: true,
-        actions: plan.actions,
-    };
-}
-//# sourceMappingURL=migrate.js.map