@deksden-com/dd-flow-cli 0.3.0 → 0.3.1

package/dist/services/migrations.js

@@ -0,0 +1,231 @@
+import fs from "node:fs";
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { requireProjectByRoot } from "./projects.js";
+import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
+export function planMigration(context, input) {
+    const rootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd: process.cwd() });
+    if (!rootResolution.root) {
+        throw new AppError("not_found", `Project root does not exist: ${input.projectRoot}`, 1);
+    }
+    const project = requireProjectByRoot(context, rootResolution.root);
+    const versionStatus = getProjectVersionStatus({
+        projectRoot: rootResolution.root,
+        rootSource: rootResolution.root_source
+    });
+    const sourceVersion = input.sourceVersion ?? versionStatus?.memory_bank.version ?? "unknown";
+    const targetVersion = input.targetVersion ?? versionStatus?.memory_bank.version ?? "unknown";
+    const chain = adjacentMigrationChain(sourceVersion, targetVersion);
+    const activeState = activeStateSummary(context, project.id);
+    const backup = backupEvidence(input);
+    const blockers = [
+        ...(chain.status === "unsupported" ? [`unsupported migration path: ${chain.reason}`] : []),
+        ...(backup.status === "missing" ? ["backup evidence is required before runtime/home migration"] : []),
+        ...(input.allowActive ? [] : activeStateBlockers(activeState))
+    ];
+    const status = blockers.length > 0 ? "blocked" : chain.steps.length === 0 ? "noop" : "ready";
+    return {
+        ok: true,
+        schema_id: "dd-flow/mb-upgrade-migration-report@1",
+        generated_at: context.now(),
+        project: {
+            id: project.id,
+            root: project.root,
+            memory_bank_version: versionStatus?.memory_bank.version ?? null
+        },
+        run: {
+            id: input.runId ?? null,
+            flow_kind: "mb-upgrade"
+        },
+        migration: {
+            mode: "mb-upgrade-only",
+            status,
+            source_memory_bank_version: sourceVersion,
+            target_memory_bank_version: targetVersion,
+            adjacent_only: true,
+            chain: chain.steps,
+            blocked_reasons: blockers
+        },
+        engine: {
+            router_version: null,
+            selected_engine_version: null,
+            source_engine_available: "unknown",
+            target_engine_available: "unknown"
+        },
+        backup,
+        active_state: activeState,
+        primary_data: [
+            "project registry records",
+            "protocol runtime",
+            "run indexes",
+            "queues/lanes/sessions/locks when their contracts change",
+            "flow-pack manifests and compatibility metadata"
+        ],
+        derived_artifacts: [
+            "project dashboard artifacts",
+            "global dashboard data/render outputs",
+            "project summary outputs after PRT-059",
+            "cached indexes that can be rebuilt"
+        ],
+        verification: {
+            post_upgrade_required: true,
+            commands: [
+                "dd-flow migration verify --file <report> --json",
+                "dd-flow dashboard refresh --project <project>",
+                "dd-flow status --project-root <project-root> --json"
+            ]
+        }
+    };
+}
+export function verifyMigrationReport(_context, input) {
+    const filePath = path.resolve(input.file);
+    const report = readJsonObject(filePath);
+    const schemaId = stringValue(report.schema_id);
+    if (schemaId !== "dd-flow/mb-upgrade-migration-report@1") {
+        throw new AppError("validation", "Migration report schema_id is not dd-flow/mb-upgrade-migration-report@1", 2, {
+            file: filePath,
+            schema_id: schemaId
+        });
+    }
+    const migration = recordValue(report.migration);
+    const backup = recordValue(report.backup);
+    const chain = Array.isArray(migration?.chain) ? migration.chain : [];
+    const backupStatus = stringValue(backup?.status);
+    const blockedReasons = Array.isArray(migration?.blocked_reasons) ? migration.blocked_reasons.map(String) : [];
+    const errors = [];
+    if (!migration)
+        errors.push("migration block is required");
+    if (!backup)
+        errors.push("backup block is required");
+    if (backupStatus !== "present" && backupStatus !== "planned")
+        errors.push("backup.status must be present or planned");
+    if (migration?.adjacent_only !== true)
+        errors.push("migration.adjacent_only must be true");
+    if (chain.some((step) => !isAdjacentStep(step)))
+        errors.push("all migration.chain entries must be adjacent steps with from/to/status");
+    if (stringValue(migration?.status) === "ready" && blockedReasons.length > 0) {
+        errors.push("ready migration report must not contain blocked reasons");
+    }
+    if (errors.length > 0) {
+        throw new AppError("migration_report_invalid", "Migration report is not acceptable", 2, { file: filePath, errors });
+    }
+    return {
+        ok: true,
+        file: filePath,
+        schema_id: schemaId,
+        verdict: blockedReasons.length > 0 ? "blocked_report_valid" : "accepted",
+        checks: {
+            backup: backupStatus,
+            adjacent_chain_steps: chain.length,
+            blocked_reasons: blockedReasons.length
+        }
+    };
+}
+function backupEvidence(input) {
+    if (!input.backupPath) {
+        return {
+            status: "missing",
+            path: null,
+            created_at: null,
+            rollback_route: "required before applying runtime/home migration"
+        };
+    }
+    return {
+        status: fs.existsSync(path.resolve(input.backupPath)) ? "present" : "planned",
+        path: path.resolve(input.backupPath),
+        created_at: input.backupCreatedAt ?? null,
+        rollback_route: "restore backup before retrying migration"
+    };
+}
+function adjacentMigrationChain(source, target) {
+    if (source === target)
+        return { status: "ok", steps: [] };
+    const sourceParts = parseSemver(source);
+    const targetParts = parseSemver(target);
+    if (!sourceParts || !targetParts) {
+        return { status: "unsupported", reason: "source or target version is not semver", steps: [] };
+    }
+    if (sourceParts.major !== targetParts.major) {
+        return { status: "unsupported", reason: "major version migration requires explicit future migration units", steps: [] };
+    }
+    if (targetParts.minor < sourceParts.minor || (targetParts.minor === sourceParts.minor && targetParts.patch < sourceParts.patch)) {
+        return { status: "unsupported", reason: "downgrade migrations are not supported", steps: [] };
+    }
+    const steps = [];
+    let current = { ...sourceParts };
+    while (compareParts(current, targetParts) < 0) {
+        const next = nextAdjacent(current, targetParts);
+        steps.push({
+            id: `${formatParts(current)}-to-${formatParts(next)}`,
+            from: formatParts(current),
+            to: formatParts(next),
+            status: "planned"
+        });
+        current = next;
+    }
+    return { status: "ok", steps };
+}
+function activeStateSummary(context, projectId) {
+    return {
+        protocols: context.db.all("SELECT id, status, stage FROM protocols WHERE project_id = ? AND status NOT IN ('closed', 'cancelled') ORDER BY updated_at DESC", [projectId]),
+        runs: context.db.all("SELECT id, status, verdict FROM flow_runs WHERE project_id = ? AND status NOT IN ('done', 'cancelled', 'failed') ORDER BY updated_at DESC", [projectId]),
+        merge_queue: context.db.all("SELECT protocol_id, status FROM merge_queue WHERE project_id = ? AND status IN ('ready', 'claimed', 'requeued') ORDER BY updated_at DESC", [projectId]),
+        lane_locks: context.db.all("SELECT lane, worker_id, status FROM lane_locks WHERE project_id = ? AND status = 'active' ORDER BY updated_at DESC", [projectId])
+    };
+}
+function activeStateBlockers(active) {
+    const blockers = [];
+    if (active.protocols.length > 0)
+        blockers.push(`active protocols: ${active.protocols.map((item) => item.id).join(", ")}`);
+    if (active.runs.length > 0)
+        blockers.push(`active runs: ${active.runs.map((item) => item.id).join(", ")}`);
+    if (active.merge_queue.length > 0)
+        blockers.push(`active merge queue items: ${active.merge_queue.map((item) => item.protocol_id).join(", ")}`);
+    if (active.lane_locks.length > 0)
+        blockers.push(`active lane locks: ${active.lane_locks.map((item) => `${item.lane}:${item.worker_id}`).join(", ")}`);
+    return blockers;
+}
+function readJsonObject(filePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    }
+    catch (error) {
+        throw new AppError("invalid_json", `Cannot read migration report: ${filePath}`, 2, { cause: String(error) });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new AppError("validation", "Migration report must be a JSON object", 2, { file: filePath });
+    }
+    return parsed;
+}
+function isAdjacentStep(value) {
+    const step = recordValue(value);
+    return Boolean(step && stringValue(step.from) && stringValue(step.to) && stringValue(step.status));
+}
+function recordValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function parseSemver(value) {
+    const match = value.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)/);
+    if (!match?.[1] || !match[2] || !match[3])
+        return null;
+    return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+function compareParts(left, right) {
+    if (left.major !== right.major)
+        return left.major - right.major;
+    if (left.minor !== right.minor)
+        return left.minor - right.minor;
+    return left.patch - right.patch;
+}
+function nextAdjacent(current, target) {
+    if (current.minor < target.minor)
+        return { major: current.major, minor: current.minor + 1, patch: 0 };
+    return { major: current.major, minor: current.minor, patch: Math.min(current.patch + 1, target.patch) };
+}
+function formatParts(parts) {
+    return `${parts.major}.${parts.minor}.${parts.patch}`;
+}

package/dist/services/project-summary.js

@@ -0,0 +1,122 @@
+import fs from "node:fs";
+import path from "node:path";
+import { isActiveProtocolStatus, isActiveQueueStatus } from "../domain/contracts.js";
+import { ensureDir } from "../storage/paths.js";
+import { getCliVersionReport } from "./build-info.js";
+import { projectDashboardHtmlPath, projectSummaryJsonPath } from "./config.js";
+import { queueForProject } from "./merge-queue.js";
+import { activeFlowSessionsForProject } from "./sessions.js";
+import { getProjectVersionStatus } from "./version-status.js";
+export function projectSummaryPath(context, projectId) {
+    return projectSummaryJsonPath(context, projectId);
+}
+export function buildProjectSummary(context, project) {
+    const versionStatus = getProjectVersionStatus({ projectRoot: fs.existsSync(project.root) ? project.root : null, rootSource: "explicit" });
+    const protocols = protocolsForProject(context, project.id);
+    const activeProtocols = protocols.filter((protocol) => isActiveProtocolStatus(protocol.status));
+    const queue = queueForProject(context, project.id);
+    const locks = context.db.all("SELECT lane, worker_id, status, expires_at FROM lane_locks WHERE project_id = ? AND status = 'active'", [project.id]);
+    const waiters = context.db.all("SELECT id, status FROM lane_waiters WHERE project_id = ? AND status = 'queued'", [project.id]);
+    const sessions = activeFlowSessionsForProject(context, project.id);
+    const openDefs = protocols.reduce((count, protocol) => count + jsonArray(protocol.active_def_json).length + jsonArray(protocol.blockers_json).length, 0);
+    const cli = getCliVersionReport().cli;
+    return {
+        schema_id: "dd-flow/project-summary@1",
+        schema_version: "1.0.0",
+        generated_at: context.now(),
+        project_id: project.id,
+        name: path.basename(project.root) || project.id,
+        root: project.root,
+        root_exists: fs.existsSync(project.root),
+        status: project.status,
+        memorybank_version: versionStatus?.memory_bank.version ?? null,
+        memorybank_status: versionStatus?.memory_bank.status ?? "missing",
+        flow_pack_status: versionStatus?.flow_pack.status ?? "missing",
+        required_engine_range: null,
+        cli_version: cli.version,
+        engine_version: null,
+        engine_status: "unknown",
+        summary_path: projectSummaryPath(context, project.id),
+        dashboard_path: projectDashboardHtmlPath(context, project.id),
+        protocol_counts: {
+            active: activeProtocols.length,
+            waiting: protocols.filter((protocol) => protocol.status === "waiting_for_user").length,
+            done: protocols.filter((protocol) => protocol.status === "closed").length,
+            total: protocols.length
+        },
+        active_protocols: activeProtocols.slice(0, 6).map((protocol) => ({
+            id: protocol.id,
+            stage: protocol.stage,
+            status: protocol.status,
+            next_action: protocol.next_action,
+            updated_at: protocol.updated_at
+        })),
+        waiting_items: protocols
+            .filter((protocol) => protocol.status === "waiting_for_user")
+            .slice(0, 6)
+            .map((protocol) => ({ id: protocol.id, stage: protocol.stage, next_action: protocol.next_action })),
+        resource_summary: {
+            queue: queue.filter((job) => isActiveQueueStatus(job.status)).length,
+            locks: locks.length,
+            waiters: waiters.length,
+            sessions: sessions.length,
+            open_defs: openDefs
+        },
+        warnings: fs.existsSync(project.root) ? [] : [{ code: "project_root_missing", path: project.root }],
+        last_activity_at: latestActivity(project, protocols)
+    };
+}
+export function publishProjectSummary(context, input) {
+    const summary = buildProjectSummary(context, input.project);
+    const output = projectSummaryPath(context, input.project.id);
+    if (input.write ?? true) {
+        writeJsonFile(output, summary);
+    }
+    return { ok: true, project_id: input.project.id, project_root: input.project.root, summary_path: output, summary };
+}
+export function readPublishedProjectSummary(context, project) {
+    const file = projectSummaryPath(context, project.id);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function projectRegistrySummary(context, project) {
+    const published = readPublishedProjectSummary(context, project);
+    const versionStatus = getProjectVersionStatus({ projectRoot: fs.existsSync(project.root) ? project.root : null, rootSource: "explicit" });
+    return {
+        project_id: project.id,
+        project_root: project.root,
+        memorybank_version: published?.memorybank_version ?? versionStatus?.memory_bank.version ?? null,
+        required_engine_range: published?.required_engine_range ?? null,
+        last_seen_cli_version: published?.cli_version ?? null,
+        last_seen_engine_version: published?.engine_version ?? null,
+        summary_path: projectSummaryPath(context, project.id),
+        last_activity_at: published?.last_activity_at ?? project.updated_at,
+        status: project.status,
+        summary_status: published ? "present" : "missing"
+    };
+}
+function protocolsForProject(context, projectId) {
+    return context.db.all(`SELECT id, status, stage, next_action, blockers_json, active_def_json, updated_at
+     FROM protocols WHERE project_id = ? ORDER BY updated_at DESC`, [projectId]);
+}
+function jsonArray(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    catch {
+        return [];
+    }
+}
+function latestActivity(project, protocols) {
+    return protocols.reduce((latest, protocol) => (protocol.updated_at > latest ? protocol.updated_at : latest), project.updated_at);
+}
+function writeJsonFile(file, value) {
+    ensureDir(path.dirname(file));
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}

package/dist/services/projects.js

@@ -8,6 +8,8 @@ import { activeCodexSessionBindingsForProject, activeFlowSessionBindingsForProje
 import { dashboardMarkdownPath, globalDashboardMarkdownPath, readProjectConfig } from "./config.js";
 import { loadProjectFlowContract } from "../domain/flow-contract.js";
 import { buildStaticFlowGuidance } from "./flow-guidance.js";
+import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
+import { buildProjectSummary, projectRegistrySummary, readPublishedProjectSummary } from "./project-summary.js";
 export function registerProject(context, input) {
     const root = resolveProjectRoot(input.root);
     const existing = findProjectByRoot(context, root);
@@ -89,10 +91,26 @@ export function resolveProject(context, input) {
     }
     const details = { input: input.idOrAlias };
     if (!isFullEntityId(input.idOrAlias) && !isShortEntityId(input.idOrAlias)) {
-        details.expected = "Use full id PRJ-NNN-slug, short alias PRJ-NNN, or --root for root-based commands.";
+        details.expected = "Use full id PRJ-NNN-slug, short alias PRJ-NNN, slug, root path, or --root for root-based commands.";
     }
     throw new AppError("not_found", `Project is not registered: ${input.idOrAlias}`, 1, details);
 }
+export function requireProjectByReference(context, reference) {
+    const candidates = resolveProjectCandidates(context, reference);
+    if (candidates.length === 1) {
+        return candidates[0];
+    }
+    if (candidates.length > 1) {
+        throw new AppError("ambiguous_alias", `Project reference is ambiguous: ${reference}`, 1, {
+            input: reference,
+            candidates: candidates.map(projectSummary)
+        });
+    }
+    throw new AppError("not_found", `Project is not registered: ${reference}`, 1, {
+        input: reference,
+        expected: "Use full id PRJ-NNN-slug, short alias PRJ-NNN, slug, or project root path."
+    });
+}
 export function migrateProjectIds(context, input) {
     const root = resolveProjectRoot(input.root);
     const existing = findProjectByRoot(context, root);
@@ -160,10 +178,18 @@ export function getProjectStatus(context, input) {
     const protocols = context.db.all(`SELECT id, status, stage, next_action, updated_at
      FROM protocols
      WHERE project_id = ?
-     ORDER BY updated_at DESC`, [project.id]).map((protocol) => ({
-        ...protocol,
-        flow_guidance: buildStaticFlowGuidance({ stage: String(protocol.stage), contract: flowContract })
-    }));
+     ORDER BY updated_at DESC`, [project.id]).map((protocol) => {
+        const lifecycle = normalizeProtocolLifecycle({
+            rawStage: String(protocol.stage),
+            rawStatus: String(protocol.status),
+            flowContract
+        });
+        return {
+            ...protocol,
+            lifecycle,
+            flow_guidance: buildStaticFlowGuidance({ stage: String(protocol.stage), status: String(protocol.status), contract: flowContract })
+        };
+    });
     const mergeQueue = context.db.all(`SELECT protocol_id, status, claimed_by_session_id, claimed_at, attempts_count, last_reason, completed_at,
        created_at, updated_at
      FROM merge_queue
@@ -177,6 +203,8 @@ export function getProjectStatus(context, input) {
     return {
         ok: true,
         project,
+        registry_summary: projectRegistrySummary(context, project),
+        project_summary: readPublishedProjectSummary(context, project) ?? buildProjectSummary(context, project),
         config,
         dashboard: {
             project_markdown_path: dashboardMarkdownPath(project.root, config),
@@ -251,13 +279,17 @@ function typedProjectMetadata(project) {
     return { shortId: parsed.shortId, slug: parsed.slug };
 }
 function resolveProjectCandidates(context, idOrAlias) {
+    if (looksLikePathReference(idOrAlias)) {
+        const byRoot = findProjectByRoot(context, normalizeStoredRoot(idOrAlias));
+        return byRoot ? [byRoot] : [];
+    }
     if (isShortEntityId(idOrAlias)) {
         return context.db.all("SELECT * FROM projects WHERE short_id = ? ORDER BY id ASC", [idOrAlias]);
     }
     if (isFullEntityId(idOrAlias)) {
         return context.db.all("SELECT * FROM projects WHERE id = ? ORDER BY id ASC", [idOrAlias]);
     }
-    return [];
+    return context.db.all("SELECT * FROM projects WHERE slug = ? ORDER BY id ASC", [idOrAlias]);
 }
 function resolveSingleProject(context, idOrAlias) {
     return resolveProject(context, { idOrAlias }).project;
@@ -272,6 +304,9 @@ function projectSummary(project) {
         state_root: project.state_root
     };
 }
+function looksLikePathReference(value) {
+    return path.isAbsolute(value) || value.startsWith(".") || value.includes("/") || value.includes("\\");
+}
 function projectReferenceTables() {
     return [
         "protocols",

package/dist/services/protocol-lifecycle.js

@@ -0,0 +1,144 @@
+import { defaultFlowContract, flowContractForState, normalizeStage } from "../domain/flow-contract.js";
+export function normalizeProtocolLifecycle(input) {
+    const source = input.state ? "runtime_state" : input.rawStage || input.rawStatus ? "protocol_record" : "missing";
+    const contract = input.flowContract ?? (input.state ? flowContractForState(input.state) : defaultFlowContract);
+    const rawStage = nonEmpty(input.state?.stage) ?? nonEmpty(input.rawStage) ?? "unregistered";
+    const rawStatus = nonEmpty(input.state?.status) ?? nonEmpty(input.rawStatus) ?? "unknown";
+    const normalizedRawStage = safeNormalizeStage(rawStage, contract);
+    const diagnostics = [];
+    const mapped = mapLegacyLifecycle(normalizedRawStage, rawStatus, input.queueStatus ?? null, contract);
+    if (normalizedRawStage !== rawStage) {
+        diagnostics.push({
+            code: "lifecycle_legacy_alias_normalized",
+            severity: "info",
+            raw_stage: rawStage,
+            normalized_stage: normalizedRawStage
+        });
+    }
+    if (mapped.stage === "unknown") {
+        diagnostics.push({
+            code: "lifecycle_stage_unknown",
+            severity: "warning",
+            raw_stage: rawStage,
+            raw_status: rawStatus
+        });
+    }
+    if (["blocked", "waiting_for_user"].includes(normalizedRawStage) && !mapped.status_reason) {
+        diagnostics.push({
+            code: "lifecycle_return_stage_missing",
+            severity: "warning",
+            raw_stage: rawStage,
+            summary: `${normalizedRawStage} is a status-like legacy stage without explicit return_to_stage metadata.`
+        });
+    }
+    return {
+        flow: nonEmpty(input.flow) ?? "mb_sdlc",
+        stage: mapped.stage,
+        substage: mapped.substage,
+        status: mapped.status,
+        status_reason: mapped.status_reason,
+        terminal: mapped.terminal,
+        legacy_stage: mapped.legacy_stage,
+        legacy_status: mapped.legacy_status,
+        raw_stage: rawStage,
+        raw_status: rawStatus,
+        queue_status: input.queueStatus ?? null,
+        source,
+        diagnostics
+    };
+}
+export function lifecycleIsTerminalSuccess(lifecycle) {
+    return lifecycle.terminal && lifecycle.status === "done";
+}
+export function lifecycleIsTerminalFailure(lifecycle) {
+    return lifecycle.terminal && ["cancelled", "failed"].includes(lifecycle.status);
+}
+export function lifecycleLegacyStage(lifecycle) {
+    return lifecycle.legacy_stage ?? lifecycle.raw_stage;
+}
+function mapLegacyLifecycle(stage, rawStatus, queueStatus, contract) {
+    if (stage === "registered") {
+        return mapped("protocol", null, "registered", "registered", rawStatus, false);
+    }
+    if (stage === "priming" || stage === "prime") {
+        return mapped("specify", "priming", statusFromRaw(rawStatus, "in_progress"), stage, rawStatus, false);
+    }
+    if (stage === "specify") {
+        return mapped("specify", null, statusFromRaw(rawStatus, "in_progress"), null, null, false);
+    }
+    if (stage === "plan") {
+        return mapped("plan", null, statusFromRaw(rawStatus, "in_progress"), null, null, false);
+    }
+    if (stage === "implementation") {
+        return mapped("code", "implementation", statusFromRaw(rawStatus, "in_progress"), "implementation", rawStatus, false);
+    }
+    if (stage === "readiness") {
+        return mapped("code", "readiness", rawStatus === "running" ? "readiness" : statusFromRaw(rawStatus, "readiness"), "readiness", rawStatus, false);
+    }
+    if (stage === "ready_for_merge") {
+        const status = queueStatus && ["ready", "requeued"].includes(queueStatus) ? "ready_for_merge" : "ready_for_merge";
+        return mapped("code", null, status, "ready_for_merge", rawStatus, false);
+    }
+    if (stage === "queued_for_merge") {
+        return mapped("merge", null, queueStatus === "claimed" ? "claimed" : "queued", "queued_for_merge", rawStatus, false);
+    }
+    if (stage === "integration") {
+        return mapped("merge", "integration", queueStatus === "claimed" ? "in_progress" : statusFromRaw(rawStatus, "in_progress"), "integration", rawStatus, false);
+    }
+    if (stage === "blocked") {
+        return mapped("unknown", null, "blocked", "blocked", rawStatus, false);
+    }
+    if (stage === "waiting_for_user") {
+        return mapped("unknown", null, "waiting_for_user", "waiting_for_user", rawStatus, false);
+    }
+    if (stage === "closed") {
+        return mapped("closed", null, "done", "closed", rawStatus, true);
+    }
+    if (stage === "cancelled") {
+        return mapped("closed", null, "cancelled", "cancelled", rawStatus, true);
+    }
+    if (contract.stages[stage]?.terminal) {
+        return mapped(stage, null, statusFromRaw(rawStatus, "done"), stage, rawStatus, true);
+    }
+    if (contract.stages[stage]) {
+        return mapped(stage, null, statusFromRaw(rawStatus, "in_progress"), null, null, false);
+    }
+    return mapped("unknown", null, statusFromRaw(rawStatus, "unknown"), stage, rawStatus, false);
+}
+function mapped(stage, substage, status, legacyStage, legacyStatus, terminal) {
+    return {
+        stage,
+        substage,
+        status,
+        status_reason: null,
+        terminal,
+        legacy_stage: legacyStage,
+        legacy_status: legacyStatus
+    };
+}
+function statusFromRaw(rawStatus, fallback) {
+    if (rawStatus === "running")
+        return fallback;
+    if (rawStatus === "closed")
+        return "done";
+    if (rawStatus === "registered")
+        return "registered";
+    if (rawStatus === "waiting_user")
+        return "waiting_for_user";
+    if (rawStatus === "active")
+        return "in_progress";
+    if (rawStatus === "unknown")
+        return fallback;
+    return rawStatus || fallback;
+}
+function safeNormalizeStage(stage, contract) {
+    try {
+        return normalizeStage(stage, contract);
+    }
+    catch {
+        return stage;
+    }
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}