jishushell 0.6.5 → 0.7.3

package/dist/services/legacy-migrator/executor.js

@@ -0,0 +1,637 @@
+/**
+ * legacy-migrator/executor.ts
+ *
+ * Apply a migration plan to disk. This is the only module in the codebase
+ * allowed to:
+ *
+ *   - Stop a legacy instance via runtime drivers.
+ *   - Rewrite `instance.json` / `manifest.json` / `definition.yaml` /
+ *     `resolved-spec.yaml` from official builtin AppDefinitions.
+ *   - Rename `instances/<id>` → `apps/<id>`.
+ *
+ * Every disruptive step requires the caller to pass `confirm: true`.
+ * Without confirmation the executor refuses to mutate anything.
+ */
+import { createHash } from "node:crypto";
+import { chownSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { parse, stringify } from "yaml";
+import { APPS_DIR, JISHUSHELL_HOME } from "../../config.js";
+import { ensureDirHost } from "../../utils/fs.js";
+import { safeReadJson, safeWriteJson } from "../../utils/safe-json.js";
+import { buildCanonicalAppInstance, buildCanonicalManifest } from "../app-common/instance-store.js";
+import { resolveIntegrationsFromSpec } from "../app-common/integration-refs.js";
+import { materializeAppSpecForInstance } from "../app-common/spec-materializer.js";
+import { allocateCanonicalRuntimeHostPorts, buildCanonicalRuntimeFromSpec, commitCanonicalRuntimeHostPorts, releaseCanonicalRuntimeHostPorts, stripCanonicalRuntimeHostPortSeeds, } from "../app-common/runtime-facts.js";
+import { resolveServiceUser } from "../instances/manager.js";
+import { resolveNomadJobId } from "../runtime/job-id.js";
+import { DEFINITION_FILENAME, INSTANCE_METADATA_FILENAME, MANIFEST_FILENAME, RESOLVED_SPEC_FILENAME, } from "../app-common/paths.js";
+const SCHEMA_VERSION = 2;
+const MIGRATION_ID = "legacy-migrator-step-13";
+const LEGACY_APP_SPEC_FILENAME = "app-spec.yaml";
+const ANYTHINGLLM_INSTANCE_ID = "anythingllm-container";
+const ANYTHINGLLM_KNOWLEDGE_CAPABILITY = "knowledge-anythingllm";
+const OPENCLAW_KNOWLEDGE_SLOT = "KNOWLEDGE_BASE_URL";
+function sha256(text) {
+    return createHash("sha256").update(text).digest("hex");
+}
+function positiveInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535)
+        return value;
+    if (typeof value !== "string" || !value.trim())
+        return null;
+    const trimmed = value.trim();
+    if (!/^\d+$/.test(trimmed))
+        return null;
+    const parsed = Number.parseInt(trimmed, 10);
+    return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : null;
+}
+function readLegacyPrimaryHostPort(rawMeta) {
+    const runtime = rawMeta?.runtime && typeof rawMeta.runtime === "object" && !Array.isArray(rawMeta.runtime)
+        ? rawMeta.runtime
+        : {};
+    const env = runtime.env && typeof runtime.env === "object" && !Array.isArray(runtime.env)
+        ? runtime.env
+        : {};
+    for (const candidate of [
+        runtime.hostPort,
+        runtime.host_port,
+        runtime.gateway_port,
+        env.OPENCLAW_GATEWAY_PORT,
+    ]) {
+        const port = positiveInteger(candidate);
+        if (port)
+            return port;
+    }
+    const args = Array.isArray(runtime.args) ? runtime.args : [];
+    for (let index = 0; index < args.length; index++) {
+        const current = typeof args[index] === "string" ? args[index] : "";
+        if (current === "--port") {
+            const port = positiveInteger(args[index + 1]);
+            if (port)
+                return port;
+        }
+        const inline = /^--port=(\d+)$/.exec(current);
+        if (inline) {
+            const port = positiveInteger(inline[1]);
+            if (port)
+                return port;
+        }
+    }
+    return null;
+}
+function runtimePortKey(port) {
+    return [
+        typeof port.taskName === "string" ? port.taskName : "",
+        typeof port.name === "string" ? port.name : "",
+        Number.isInteger(port.containerPort) ? String(port.containerPort) : "",
+    ].join("\0");
+}
+function buildLegacyHostPortMap(rawMeta) {
+    const runtime = rawMeta?.runtime && typeof rawMeta.runtime === "object" && !Array.isArray(rawMeta.runtime)
+        ? rawMeta.runtime
+        : {};
+    const ports = Array.isArray(runtime.ports) ? runtime.ports : [];
+    const byKey = new Map();
+    for (const port of ports) {
+        if (!port || typeof port !== "object")
+            continue;
+        const hostPort = positiveInteger(port.hostPort);
+        if (!hostPort)
+            continue;
+        byKey.set(runtimePortKey(port), hostPort);
+    }
+    return byKey;
+}
+function preserveLegacyHostPorts(runtime, rawMeta) {
+    if (!Array.isArray(runtime.ports) || runtime.ports.length === 0)
+        return runtime;
+    const legacyPorts = buildLegacyHostPortMap(rawMeta);
+    const legacyPrimary = readLegacyPrimaryHostPort(rawMeta);
+    let primaryUsed = false;
+    return {
+        ...runtime,
+        ports: runtime.ports.map((port) => {
+            if (!port || typeof port !== "object")
+                return port;
+            if ((port.visibility ?? "external") === "internal")
+                return port;
+            const current = positiveInteger(port.hostPort);
+            const mapped = legacyPorts.get(runtimePortKey(port));
+            if (current)
+                return port;
+            if (mapped)
+                return { ...port, hostPort: mapped };
+            if (!primaryUsed && legacyPrimary) {
+                primaryUsed = true;
+                return { ...port, hostPort: legacyPrimary };
+            }
+            return port;
+        }),
+    };
+}
+function chownTreeToServiceUser(path) {
+    const serviceUser = resolveServiceUser();
+    if (!serviceUser)
+        return;
+    try {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            return;
+        chownSync(path, serviceUser.uid, serviceUser.gid);
+        if (!stat.isDirectory())
+            return;
+        for (const entry of readdirSync(path)) {
+            chownTreeToServiceUser(join(path, entry));
+        }
+    }
+    catch {
+        // Best effort: ownership repair must not hide the migration outcome.
+    }
+}
+async function loadBuiltinTemplate(builtinId) {
+    const { listBuiltinAppSpecs } = await import("../app-common/service.js");
+    const entry = listBuiltinAppSpecs().find((item) => item.id === builtinId);
+    if (!entry?.yaml) {
+        throw new Error(`Builtin AppDefinition '${builtinId}' is not bundled with this Core release.`);
+    }
+    return { id: entry.id, fileName: entry.fileName, yaml: entry.yaml };
+}
+function readJsonFile(path) {
+    return safeReadJson(path, path);
+}
+function hasAnythingllmCredentials() {
+    return existsSync(join(JISHUSHELL_HOME, "provider-credentials", ANYTHINGLLM_INSTANCE_ID, "credentials.json"))
+        || existsSync(join(APPS_DIR, ANYTHINGLLM_INSTANCE_ID, "credentials.json"));
+}
+function isOpenClawBuiltin(builtinId) {
+    return builtinId === "openclaw-container"
+        || builtinId === "openclaw-binary"
+        || builtinId === "openclaw-with-ollama-container"
+        || builtinId === "openclaw-with-searxng-container";
+}
+function materializeLegacyOpenClawKnowledgeDefault(builtinId, connections) {
+    if (!isOpenClawBuiltin(builtinId))
+        return connections;
+    if (Object.prototype.hasOwnProperty.call(connections, OPENCLAW_KNOWLEDGE_SLOT)) {
+        return connections;
+    }
+    if (!hasAnythingllmCredentials())
+        return connections;
+    // Legacy migration boundary only: older OpenClaw instances treated missing
+    // KNOWLEDGE_BASE_URL as "use AnythingLLM if its Core-managed credentials
+    // exist". Runtime no longer guesses that. When the historical condition is
+    // safely observable here, write the choice as canonical `instance.connections`.
+    return {
+        ...connections,
+        [OPENCLAW_KNOWLEDGE_SLOT]: {
+            kind: "single",
+            providerId: ANYTHINGLLM_INSTANCE_ID,
+            capability: ANYTHINGLLM_KNOWLEDGE_CAPABILITY,
+        },
+    };
+}
+async function tryStopInstance(instanceId) {
+    try {
+        // Compatibility boundary only: the instance is legacy by definition, so
+        // stopping it must not require canonical execution-owner metadata.
+        const { stopGenericAppSpecJob } = await import("../runtime/drivers/nomad.js");
+        const result = await stopGenericAppSpecJob(instanceId, true);
+        if (result.ok || (result.error && (result.error.includes("not running") || result.error.includes("not found")))) {
+            return { stopped: true };
+        }
+        // Legacy OpenClaw/Hermes jobs may have used an integration-prefixed job id
+        // even when canonical instance metadata is missing. Try those known
+        // prefixes before surfacing a warning.
+        const fallbackPrefixes = ["openclaw-", "hermes-"];
+        for (const prefix of fallbackPrefixes) {
+            const fallbackId = resolveNomadJobId(instanceId, prefix);
+            if (fallbackId === instanceId)
+                continue;
+            const fallback = await stopGenericAppSpecJob(fallbackId, true);
+            if (fallback.ok || (fallback.error && (fallback.error.includes("not running") || fallback.error.includes("not found")))) {
+                return { stopped: true };
+            }
+        }
+        if (result.error && result.error.includes("missing canonical execution owner")) {
+            return { stopped: false, warning: `Nomad stop returned: legacy runtime still active under a non-canonical job id for '${instanceId}'` };
+        }
+        if (result.ok || (result.error && (result.error.includes("not running") || result.error.includes("not found")))) {
+            return { stopped: true };
+        }
+        return { stopped: false, warning: `Nomad stop returned: ${result.error}` };
+    }
+    catch (error) {
+        return { stopped: false, warning: `Nomad stop threw: ${error?.message ?? error}` };
+    }
+}
+function rewriteInstanceMeta(params) {
+    const raw = params.rawMeta ?? {};
+    const now = new Date().toISOString();
+    const createdAt = (typeof raw.createdAt === "string" && raw.createdAt.trim())
+        ? raw.createdAt
+        : (typeof raw.created_at === "string" && raw.created_at.trim()) ? raw.created_at : now;
+    // The migrator may read legacy discriminators, but its output must go
+    // through the same canonical builder as every normal create/install path.
+    const stripped = { ...raw };
+    delete stripped._engine;
+    const status = stripped.status && typeof stripped.status === "object" && !Array.isArray(stripped.status)
+        ? stripped.status
+        : {};
+    if (status.phase === "needs-migration" || status.reason === "needs-migration") {
+        delete stripped.status;
+    }
+    const lastError = stripped.lastError && typeof stripped.lastError === "object" && !Array.isArray(stripped.lastError)
+        ? stripped.lastError
+        : {};
+    if (lastError.message === "Instance is already running") {
+        delete stripped.lastError;
+    }
+    const desiredState = raw.desiredState === "running" || raw.desiredState === "stopped"
+        ? raw.desiredState
+        : "stopped";
+    const integrationKind = resolveIntegrationsFromSpec(params.spec)[0]?.kind;
+    const canonicalPaths = (() => {
+        if (raw.paths
+            && typeof raw.paths === "object"
+            && !Array.isArray(raw.paths)
+            && typeof raw.paths.instanceDir === "string"
+            && typeof raw.paths.integrationHome === "string") {
+            return raw.paths;
+        }
+        if (integrationKind === "openclaw") {
+            const integrationHome = typeof raw.openclaw_home === "string" && raw.openclaw_home.trim()
+                ? raw.openclaw_home.trim()
+                : join(APPS_DIR, params.instanceId, "openclaw-home");
+            return {
+                instanceDir: join(APPS_DIR, params.instanceId),
+                integrationHome,
+                primaryConfig: join(integrationHome, ".openclaw", "openclaw.json"),
+                secretEnv: join(APPS_DIR, params.instanceId, "model.env"),
+            };
+        }
+        if (integrationKind === "hermes") {
+            const integrationHome = join(APPS_DIR, params.instanceId, "agent-home");
+            return {
+                instanceDir: join(APPS_DIR, params.instanceId),
+                integrationHome,
+                primaryConfig: join(integrationHome, "config.yaml"),
+                secretEnv: join(integrationHome, ".env"),
+            };
+        }
+        return undefined;
+    })();
+    const migrationsApplied = Array.isArray(raw.migrationsApplied)
+        ? raw.migrationsApplied.filter((entry) => typeof entry === "string")
+        : [];
+    if (!migrationsApplied.includes(MIGRATION_ID))
+        migrationsApplied.push(MIGRATION_ID);
+    const rawConnections = raw.connections && typeof raw.connections === "object" && !Array.isArray(raw.connections)
+        ? { ...raw.connections }
+        : {};
+    const connections = materializeLegacyOpenClawKnowledgeDefault(params.builtinId, rawConnections);
+    return buildCanonicalAppInstance({
+        raw: {
+            ...stripped,
+            createdAt,
+            updatedAt: now,
+            connections,
+            migrationsApplied,
+            ...(canonicalPaths ? { paths: canonicalPaths } : {}),
+        },
+        id: params.instanceId,
+        name: typeof raw.name === "string" && raw.name.trim() ? raw.name : params.instanceId,
+        description: typeof raw.description === "string" ? raw.description : params.spec.description ?? "",
+        spec: params.spec,
+        definitionDigest: params.definitionDigest,
+        desiredState,
+        runtime: raw.runtime && typeof raw.runtime === "object" && !Array.isArray(raw.runtime)
+            ? { ...raw.runtime }
+            : {},
+        source: "builtin:legacy-migrator",
+        materializedIntegrations: integrationKind ? [{ kind: integrationKind }] : [],
+    });
+}
+function normalizeManifestResources(existing) {
+    if (Array.isArray(existing.resources)) {
+        return existing.resources.filter((entry) => entry && typeof entry === "object"
+            && (entry.kind === "image" || entry.kind === "binary" || entry.kind === "managed-file")
+            && typeof entry.ref === "string");
+    }
+    if (!Array.isArray(existing.artifacts))
+        return [];
+    return existing.artifacts.flatMap((entry) => {
+        if (!entry || typeof entry.path !== "string")
+            return [];
+        if (entry.type === "image" || entry.type === "binary")
+            return [{ kind: entry.type, ref: entry.path }];
+        if (entry.type === "dir")
+            return [{ kind: "managed-file", ref: entry.path }];
+        return [];
+    });
+}
+function normalizeOwnedResources(existing) {
+    return Array.isArray(existing.ownedResources)
+        ? existing.ownedResources.filter((entry) => entry && typeof entry === "object"
+            && (entry.kind === "image" || entry.kind === "binary" || entry.kind === "managed-file")
+            && typeof entry.ref === "string")
+        : [];
+}
+function rewriteManifest(params) {
+    const existing = params.existing ?? {};
+    const installedAt = typeof existing.installedAt === "string" && existing.installedAt.trim()
+        ? existing.installedAt
+        : typeof existing.installed_at === "string" && existing.installed_at.trim()
+            ? existing.installed_at
+            : new Date().toISOString();
+    return buildCanonicalManifest({
+        instanceId: params.instanceId,
+        spec: params.spec,
+        definitionYaml: params.definitionYaml,
+        resolvedSpecYaml: params.resolvedYaml,
+        installedAt,
+        resources: normalizeManifestResources(existing),
+        ownedResources: normalizeOwnedResources(existing),
+        source: typeof existing.source === "string" && existing.source.trim()
+            ? existing.source.trim()
+            : "legacy-migrator",
+    });
+}
+async function migrateOneEntry(entry, confirm, options = {}) {
+    const report = {
+        id: entry.id,
+        classification: entry.classification,
+        outcome: "failed",
+        detail: entry.detail,
+    };
+    if (entry.classification === "migrated") {
+        return { ...report, outcome: "skipped-already-migrated" };
+    }
+    if (entry.classification === "unsupported") {
+        return {
+            ...report,
+            outcome: "unsupported",
+            ...(entry.unsupportedReason ? { unsupportedReason: entry.unsupportedReason } : {}),
+        };
+    }
+    if (!entry.builtinId && !entry.preserveCanonicalSpec) {
+        return { ...report, errors: ["Missing builtinId on a migratable entry."] };
+    }
+    if (!confirm) {
+        return { ...report, errors: ["Refused to mutate without explicit confirm:true."] };
+    }
+    const errors = [];
+    let newDir;
+    let runtimePortAllocations = [];
+    try {
+        if (entry.preserveCanonicalSpec) {
+            const definitionYaml = readFileSync(join(entry.sourceDir, DEFINITION_FILENAME), "utf-8");
+            const resolvedYaml = readFileSync(join(entry.sourceDir, RESOLVED_SPEC_FILENAME), "utf-8");
+            const parsedSpec = parse(resolvedYaml);
+            if (!parsedSpec || typeof parsedSpec.id !== "string") {
+                throw new Error("Canonical resolved-spec.yaml is not a valid AppSpec");
+            }
+            const spec = materializeAppSpecForInstance(parsedSpec, entry.id);
+            const materializedResolvedYaml = stringify(spec);
+            writeFileSync(join(entry.sourceDir, RESOLVED_SPEC_FILENAME), materializedResolvedYaml, { mode: 0o644 });
+            const manifestPath = join(entry.sourceDir, MANIFEST_FILENAME);
+            const existingManifest = readJsonFile(manifestPath);
+            const manifest = rewriteManifest({
+                instanceId: entry.id,
+                spec,
+                definitionYaml,
+                resolvedYaml: materializedResolvedYaml,
+                existing: existingManifest,
+            });
+            safeWriteJson(manifestPath, manifest, true);
+            const instancePath = join(entry.sourceDir, INSTANCE_METADATA_FILENAME);
+            const existingInstance = readJsonFile(instancePath);
+            const runtimeSeed = rewriteInstanceMeta({
+                instanceId: entry.id,
+                builtinId: (entry.builtinId ?? spec.id),
+                spec,
+                rawMeta: existingInstance,
+                definitionDigest: sha256(definitionYaml),
+            });
+            const runtimeTemplate = buildCanonicalRuntimeFromSpec(spec, entry.id);
+            const runtimeWithLegacyPorts = preserveLegacyHostPorts(runtimeTemplate, existingInstance);
+            const allocatedRuntime = await allocateCanonicalRuntimeHostPorts(entry.id, runtimeWithLegacyPorts, {
+                ignoreIncompleteCanonicalInstanceIds: options.ignoreIncompleteCanonicalInstanceIds,
+                preserveExistingHostPorts: true,
+            });
+            runtimePortAllocations = allocatedRuntime.allocations;
+            const canonicalInstance = buildCanonicalAppInstance({
+                raw: runtimeSeed,
+                id: entry.id,
+                name: runtimeSeed.name,
+                description: runtimeSeed.description,
+                spec,
+                definitionDigest: sha256(definitionYaml),
+                desiredState: runtimeSeed.desiredState === "running" || runtimeSeed.desiredState === "stopped"
+                    ? runtimeSeed.desiredState
+                    : "stopped",
+                runtime: stripCanonicalRuntimeHostPortSeeds(allocatedRuntime.runtime),
+            });
+            safeWriteJson(instancePath, canonicalInstance, true);
+            commitCanonicalRuntimeHostPorts(runtimePortAllocations);
+            runtimePortAllocations = [];
+            rmSync(join(entry.sourceDir, LEGACY_APP_SPEC_FILENAME), { force: true });
+            chownTreeToServiceUser(entry.sourceDir);
+            return {
+                ...report,
+                outcome: "migrated",
+                newDir: entry.sourceDir,
+            };
+        }
+        // 1. Stop the workload if it looks alive. Failure here is recorded as a
+        //    warning — we still proceed with metadata rewrite, because the
+        //    legacy job is being replaced with a fresh definition anyway.
+        if (entry.requiresStop) {
+            const stop = await tryStopInstance(entry.id);
+            if (!stop.stopped && stop.warning)
+                errors.push(`stop: ${stop.warning}`);
+        }
+        // 2. Load the builtin template and parse the spec for digests.
+        const template = await loadBuiltinTemplate(entry.builtinId);
+        const parsedSpec = parse(template.yaml);
+        if (!parsedSpec || typeof parsedSpec.id !== "string") {
+            throw new Error(`Builtin template '${entry.builtinId}' is not a valid AppSpec`);
+        }
+        const spec = materializeAppSpecForInstance(parsedSpec, entry.id);
+        const resolvedYaml = stringify(spec);
+        const definitionDigest = sha256(template.yaml);
+        // 3. Decide target directory. If source is `instances/<id>`, target is
+        //    `apps/<id>` (legacy rename). Otherwise it's already `apps/<id>`.
+        const targetDir = join(APPS_DIR, entry.id);
+        if (entry.requiresRename) {
+            ensureDirHost(APPS_DIR);
+            if (existsSync(targetDir)) {
+                throw new Error(`Cannot rename ${entry.sourceDir} → ${targetDir}: target already exists. Resolve manually.`);
+            }
+            renameSync(entry.sourceDir, targetDir);
+            newDir = targetDir;
+        }
+        else {
+            // Source already lives in apps/<id>; normalize in place. Compatibility
+            // upgrade is forward-only and does not create backup mirrors.
+            newDir = entry.sourceDir;
+        }
+        // 4. Rewrite the canonical spec snapshots. `app-spec.yaml` is accepted
+        //    only as migration input; it is never generated as migration output.
+        ensureDirHost(newDir);
+        writeFileSync(join(newDir, DEFINITION_FILENAME), template.yaml, { mode: 0o644 });
+        writeFileSync(join(newDir, RESOLVED_SPEC_FILENAME), resolvedYaml, { mode: 0o644 });
+        // 5. Rewrite canonical instance.json.
+        const rawMeta = readJsonFile(join(newDir, INSTANCE_METADATA_FILENAME));
+        const runtimeSeed = rewriteInstanceMeta({
+            instanceId: entry.id,
+            builtinId: entry.builtinId,
+            spec,
+            rawMeta,
+            definitionDigest,
+        });
+        const runtimeTemplate = buildCanonicalRuntimeFromSpec(spec, entry.id);
+        const canonicalRuntimeWithLegacyPorts = preserveLegacyHostPorts(runtimeTemplate, rawMeta);
+        const allocatedRuntime = await allocateCanonicalRuntimeHostPorts(entry.id, canonicalRuntimeWithLegacyPorts, {
+            ignoreIncompleteCanonicalInstanceIds: options.ignoreIncompleteCanonicalInstanceIds,
+            preserveExistingHostPorts: true,
+        });
+        runtimePortAllocations = allocatedRuntime.allocations;
+        const canonicalMeta = buildCanonicalAppInstance({
+            raw: runtimeSeed,
+            id: entry.id,
+            name: runtimeSeed.name,
+            description: runtimeSeed.description,
+            spec,
+            definitionDigest,
+            desiredState: runtimeSeed.desiredState === "running" || runtimeSeed.desiredState === "stopped"
+                ? runtimeSeed.desiredState
+                : "stopped",
+            runtime: stripCanonicalRuntimeHostPortSeeds(allocatedRuntime.runtime),
+        });
+        safeWriteJson(join(newDir, INSTANCE_METADATA_FILENAME), canonicalMeta, true);
+        commitCanonicalRuntimeHostPorts(runtimePortAllocations);
+        runtimePortAllocations = [];
+        // 6. Rewrite manifest.json (canonical AppManifest shape).
+        const existingManifest = readJsonFile(join(newDir, MANIFEST_FILENAME));
+        const manifest = rewriteManifest({
+            instanceId: entry.id,
+            spec,
+            definitionYaml: template.yaml,
+            resolvedYaml,
+            existing: existingManifest,
+        });
+        safeWriteJson(join(newDir, MANIFEST_FILENAME), manifest, true);
+        // Remove the consumed legacy mirror only after every canonical file has
+        // been written successfully. Compatibility upgrade is forward-only; user
+        // data stays in place and old compatibility mirrors are not retained.
+        rmSync(join(newDir, LEGACY_APP_SPEC_FILENAME), { force: true });
+        chownTreeToServiceUser(newDir);
+        return {
+            ...report,
+            outcome: "migrated",
+            ...(newDir ? { newDir } : {}),
+            ...(errors.length ? { errors } : {}),
+        };
+    }
+    catch (error) {
+        if (runtimePortAllocations.length > 0) {
+            releaseCanonicalRuntimeHostPorts(runtimePortAllocations);
+        }
+        errors.push(error?.message ?? String(error));
+        return {
+            ...report,
+            outcome: "failed",
+            ...(newDir ? { newDir } : {}),
+            errors,
+        };
+    }
+}
+export async function executeMigrationPlan(plan, options) {
+    const startedAt = new Date().toISOString();
+    const entries = [];
+    const repairBatchIds = new Set(plan.entries
+        .filter((entry) => entry.classification === "migratable")
+        .map((entry) => entry.id));
+    for (const planEntry of plan.entries) {
+        if (options.onlyMigratable && planEntry.classification !== "migratable") {
+            if (planEntry.classification === "migrated") {
+                entries.push({
+                    id: planEntry.id,
+                    classification: planEntry.classification,
+                    outcome: "skipped-already-migrated",
+                    detail: planEntry.detail,
+                });
+            }
+            else {
+                entries.push({
+                    id: planEntry.id,
+                    classification: planEntry.classification,
+                    outcome: "unsupported",
+                    detail: planEntry.detail,
+                    ...(planEntry.unsupportedReason ? { unsupportedReason: planEntry.unsupportedReason } : {}),
+                });
+            }
+            continue;
+        }
+        entries.push(await migrateOneEntry(planEntry, options.confirm, {
+            ignoreIncompleteCanonicalInstanceIds: repairBatchIds,
+        }));
+    }
+    const summary = {
+        total: entries.length,
+        migrated: entries.filter((e) => e.outcome === "migrated").length,
+        skipped: entries.filter((e) => e.outcome === "skipped-already-migrated").length,
+        unsupported: entries.filter((e) => e.outcome === "unsupported").length,
+        failed: entries.filter((e) => e.outcome === "failed").length,
+    };
+    return {
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        dryRun: options.confirm === false,
+        entries,
+        summary,
+    };
+}
+// Surface a stamp so external tools (panel, CLI) can detect whether the
+// migrator has ever run on this host without re-walking the filesystem.
+const MIGRATION_STAMP_FILENAME = "legacy-migrator.json";
+export function writeMigrationStamp(report) {
+    ensureDirHost(APPS_DIR);
+    const stampPath = join(APPS_DIR, MIGRATION_STAMP_FILENAME);
+    safeWriteJson(stampPath, {
+        schemaVersion: 1,
+        migrationId: MIGRATION_ID,
+        finishedAt: report.finishedAt,
+        summary: report.summary,
+    }, true);
+    chownTreeToServiceUser(stampPath);
+}
+export function readMigrationStamp() {
+    try {
+        const raw = readFileSync(join(APPS_DIR, MIGRATION_STAMP_FILENAME), "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed.finishedAt === "string" && parsed.summary && typeof parsed.summary === "object") {
+            return { finishedAt: parsed.finishedAt, summary: parsed.summary };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// Re-export so consumers can build a fresh dir reliably.
+export { MIGRATION_ID, MIGRATION_STAMP_FILENAME, SCHEMA_VERSION };
+// Helper used by tests + CLI to materialise an apps/ root before first use.
+export function ensureAppsRoot() {
+    ensureDirHost(APPS_DIR);
+}
+// Internal helper kept exported so that the CLI can derive a stable
+// directory listing for plan diff reporting without re-implementing it.
+export function makeFreshDir(instanceId) {
+    const dir = join(APPS_DIR, instanceId);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    return dir;
+}
+//# sourceMappingURL=executor.js.map