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

package/dist/services/status.js

@@ -0,0 +1,306 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { getCanonStatus } from "./canon.js";
+import { getCliBuildInfo } from "./build-info.js";
+import { getProjectVersionStatus, resolveStatusProjectRoot } from "./version-status.js";
+import { findProjectByRoot } from "./projects.js";
+export function getRuntimeStatus(context, input = {}) {
+    const cwd = process.cwd();
+    const projectRootResolution = resolveStatusProjectRoot({ requestedRoot: input.projectRoot, cwd });
+    const projectRoot = projectRootResolution.root;
+    const project = projectRoot ? findProjectByRoot(context, projectRoot) : undefined;
+    const canonStatus = getCanonStatus(context);
+    const canon = asRecord(canonStatus)?.canon;
+    const resolvedCanonForProject = canonForProjectStatus(canon);
+    const projectVersionStatus = getProjectVersionStatus({
+        projectRoot,
+        rootSource: projectRootResolution.root_source,
+        canon: resolvedCanonForProject
+    });
+    const cli = getCliBuildInfo();
+    const compatibilityManifest = resolvedCanonForProject ? readCompatibilityManifest(canon) : null;
+    const cliCompatibility = cliCompatibilityVerdict(cli, compatibilityManifest);
+    const registry = input.checkRegistry ? checkNpmRegistry(context, cli.package_name) : undefined;
+    return {
+        ok: true,
+        schema_id: "dd-flow/status-report@1",
+        dd_flow_home: context.ddFlowHome,
+        cwd,
+        cli: {
+            ...cli,
+            compatibility: cliCompatibility,
+            ...(registry ? { registry } : {})
+        },
+        project: {
+            requested_root: projectRootResolution.requested_root,
+            root: projectRoot,
+            root_source: projectRootResolution.root_source,
+            registered: Boolean(project),
+            id: project?.id ?? null,
+            status: project?.status ?? null,
+            memory_bank: projectVersionStatus?.memory_bank ?? null,
+            flow_pack: projectVersionStatus?.flow_pack ?? null,
+            drift: projectVersionStatus?.drift ?? null
+        },
+        canon: {
+            ...(asRecord(canonStatus) ?? {}),
+            resolved: canon ?? null,
+            compatibility: cliCanonCompatibility(cli, resolvedCanonForProject?.metadata.version ?? null)
+        }
+    };
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function readCompatibilityManifest(canon) {
+    const record = asRecord(canon);
+    const memorybankRoot = stringValue(record?.memorybank_root);
+    if (!memorybankRoot)
+        return null;
+    const file = path.join(memorybankRoot, "dd-flow", "compatibility.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        const root = asRecord(parsed);
+        const cli = asRecord(root?.dd_flow_cli);
+        if (!root || !cli)
+            return null;
+        return {
+            schema_id: stringValue(root.schema_id),
+            memory_bank_version: stringValue(root.memory_bank_version),
+            dd_flow_cli: {
+                package_name: stringValue(cli.package_name),
+                min_version: stringValue(cli.min_version),
+                recommended_version: stringValue(cli.recommended_version),
+                status_contract: stringValue(cli.status_contract),
+                version_contract: stringValue(cli.version_contract),
+                flow_contract: stringValue(cli.flow_contract)
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function cliCompatibilityVerdict(cli, manifest) {
+    if (!manifest) {
+        return {
+            verdict: "unknown",
+            reason: "compatibility_manifest_missing",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            update_command: null
+        };
+    }
+    const expectedPackage = manifest.dd_flow_cli.package_name;
+    if (expectedPackage && expectedPackage !== cli.package_name) {
+        return {
+            verdict: "incompatible",
+            reason: "package_name_mismatch",
+            package_name: cli.package_name,
+            expected_package_name: expectedPackage,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: manifest.dd_flow_cli.min_version,
+            recommended_version: manifest.dd_flow_cli.recommended_version,
+            update_command: updateCommand(expectedPackage, manifest.dd_flow_cli.recommended_version ?? manifest.dd_flow_cli.min_version)
+        };
+    }
+    const minVersion = manifest.dd_flow_cli.min_version;
+    const recommendedVersion = manifest.dd_flow_cli.recommended_version;
+    const installed = parseSemver(cli.version);
+    const min = minVersion ? parseSemver(minVersion) : null;
+    const recommended = recommendedVersion ? parseSemver(recommendedVersion) : null;
+    if (!installed || (minVersion && !min) || (recommendedVersion && !recommended)) {
+        return {
+            verdict: "unknown",
+            reason: "invalid_semver",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: null
+        };
+    }
+    if (min && compareSemver(installed, min) < 0) {
+        return {
+            verdict: "incompatible",
+            reason: "installed_below_min_version",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: updateCommand(cli.package_name, recommendedVersion ?? minVersion)
+        };
+    }
+    if (recommended && compareSemver(installed, recommended) < 0) {
+        return {
+            verdict: "outdated",
+            reason: "installed_below_recommended_version",
+            package_name: cli.package_name,
+            installed_version: cli.version,
+            memory_bank_version: manifest.memory_bank_version,
+            min_version: minVersion,
+            recommended_version: recommendedVersion,
+            update_command: updateCommand(cli.package_name, recommendedVersion)
+        };
+    }
+    return {
+        verdict: "ok",
+        reason: "installed_satisfies_memory_bank_compatibility",
+        package_name: cli.package_name,
+        installed_version: cli.version,
+        memory_bank_version: manifest.memory_bank_version,
+        min_version: minVersion,
+        recommended_version: recommendedVersion,
+        status_contract: manifest.dd_flow_cli.status_contract,
+        version_contract: manifest.dd_flow_cli.version_contract,
+        flow_contract: manifest.dd_flow_cli.flow_contract,
+        update_command: null
+    };
+}
+function updateCommand(packageName, version) {
+    return `pnpm add -g ${packageName}${version ? `@${version}` : "@latest"}`;
+}
+function checkNpmRegistry(context, packageName) {
+    const cachePath = path.join(context.ddFlowHome, "cache", "npm", `${safeCacheName(packageName)}.json`);
+    const cached = readRegistryCache(cachePath);
+    const now = new Date().toISOString();
+    if (cached && Date.now() - cached.checkedAtMs < 15 * 60 * 1000) {
+        return { ...cached.payload, source: "npm_cache" };
+    }
+    const result = spawnSync("npm", ["view", packageName, "version", "--json"], { encoding: "utf8", timeout: 5000 });
+    if (result.status !== 0) {
+        return {
+            package_name: packageName,
+            latest: null,
+            checked_at: now,
+            source: "npm",
+            status: "degraded",
+            reason: result.error ? String(result.error) : result.stderr.trim() || "npm_view_failed"
+        };
+    }
+    const latest = parseRegistryVersion(result.stdout);
+    const payload = {
+        package_name: packageName,
+        latest,
+        checked_at: now,
+        source: "npm",
+        status: latest ? "ok" : "degraded",
+        ...(latest ? {} : { reason: "npm_view_returned_no_version" })
+    };
+    writeRegistryCache(cachePath, payload);
+    return payload;
+}
+function readRegistryCache(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        const record = asRecord(parsed);
+        const payload = asRecord(record?.payload);
+        const checkedAt = stringValue(record?.checked_at);
+        if (!payload || !checkedAt)
+            return null;
+        const checkedAtMs = Date.parse(checkedAt);
+        return Number.isNaN(checkedAtMs) ? null : { checkedAtMs, payload };
+    }
+    catch {
+        return null;
+    }
+}
+function writeRegistryCache(file, payload) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, `${JSON.stringify({ checked_at: payload.checked_at, payload }, null, 2)}\n`);
+    }
+    catch {
+        // Registry cache is best effort; status remains valid without it.
+    }
+}
+function parseRegistryVersion(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return typeof parsed === "string" && parsed.length > 0 ? parsed : null;
+    }
+    catch {
+        const trimmed = value.trim().replace(/^"|"$/g, "");
+        return trimmed.length > 0 ? trimmed : null;
+    }
+}
+function safeCacheName(value) {
+    return value.replace(/[^a-zA-Z0-9_.-]+/g, "_");
+}
+function canonForProjectStatus(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.root !== "string")
+        return null;
+    const metadata = asRecord(record.metadata);
+    const status = metadata?.status;
+    if (metadata && (status === "present" || status === "degraded" || status === "unknown")) {
+        return {
+            root: record.root,
+            metadata: {
+                version: stringValue(metadata.version),
+                commit: stringValue(metadata.commit),
+                flow_contract: stringValue(metadata.flow_contract),
+                status,
+                diagnostics: Array.isArray(metadata.diagnostics) ? metadata.diagnostics.filter((item) => typeof item === "string") : []
+            }
+        };
+    }
+    const version = stringValue(record.version);
+    const commit = stringValue(record.commit);
+    const flowContract = stringValue(record.flow_contract);
+    const diagnostics = [
+        ...(version ? [] : ["canon_version_unknown"]),
+        ...(commit ? [] : ["canon_commit_unknown"]),
+        ...(flowContract ? [] : ["flow_contract_unknown"])
+    ];
+    return {
+        root: record.root,
+        metadata: {
+            version,
+            commit,
+            flow_contract: flowContract,
+            status: diagnostics.length === 0 ? "present" : "degraded",
+            diagnostics
+        }
+    };
+}
+function cliCanonCompatibility(cli, resolvedCanonVersion) {
+    const builtWithVersion = cli.build.built_with_canon.version;
+    if (!builtWithVersion || !resolvedCanonVersion) {
+        return { cli_built_with_resolved_canon: "unknown", reason: "version_missing" };
+    }
+    const built = parseSemver(builtWithVersion);
+    const resolved = parseSemver(resolvedCanonVersion);
+    if (!built || !resolved)
+        return { cli_built_with_resolved_canon: "unknown", reason: "invalid_semver" };
+    const comparison = compareSemver(built, resolved);
+    if (comparison === 0)
+        return { cli_built_with_resolved_canon: "same", reason: "semver_equal" };
+    return {
+        cli_built_with_resolved_canon: comparison < 0 ? "behind" : "ahead",
+        reason: comparison < 0 ? "cli_built_with_older_canon" : "cli_built_with_newer_canon"
+    };
+}
+function parseSemver(version) {
+    const match = version.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)(?:[-+].*)?$/);
+    if (!match?.[1] || !match[2] || !match[3])
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareSemver(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const leftPart = left[index] ?? 0;
+        const rightPart = right[index] ?? 0;
+        const diff = leftPart - rightPart;
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}

package/dist/services/version-status.js

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { parse as parseYaml } from "yaml";
+const canonicalOnlyFlowNames = ["mb-init.md", "mb-upgrade.md", "mb-upgrade-review.md", "mb-distill.md"];
+export function resolveStatusProjectRoot(input) {
+    if (input.requestedRoot) {
+        const absolute = path.resolve(input.requestedRoot);
+        return { requested_root: absolute, root: existingDirectoryRealpath(absolute), root_source: "explicit" };
+    }
+    const gitRoot = nearestGitRoot(input.cwd);
+    if (gitRoot) {
+        return { requested_root: path.resolve(input.cwd), root: gitRoot, root_source: "git" };
+    }
+    const cwdRoot = existingDirectoryRealpath(input.cwd);
+    return { requested_root: path.resolve(input.cwd), root: cwdRoot, root_source: "cwd" };
+}
+export function getProjectVersionStatus(input) {
+    if (!input.projectRoot)
+        return null;
+    const memoryBank = readMemoryBankMetadata(input.projectRoot);
+    const flowPack = readFlowPackMetadata(input.projectRoot, memoryBank.root);
+    const memoryBankDrift = compareMemoryBankVersion(memoryBank.version, input.canon?.metadata.version ?? null, memoryBank.status);
+    const flowPackDrift = compareFlowPackCommit(flowPack.source_commit, input.canon?.metadata.commit ?? null, input.canon?.root ?? null, flowPack.status);
+    const overall = overallDrift(memoryBankDrift, flowPackDrift, memoryBank.status, flowPack.status);
+    return {
+        root: input.projectRoot,
+        root_source: input.rootSource,
+        memory_bank: memoryBank,
+        flow_pack: flowPack,
+        drift: {
+            memory_bank_version: memoryBankDrift,
+            flow_pack_commit: flowPackDrift,
+            overall,
+            next_action: nextAction(overall, memoryBank.status, flowPack.status)
+        }
+    };
+}
+function readMemoryBankMetadata(projectRoot) {
+    const dotRoot = path.join(projectRoot, ".memory-bank");
+    const legacyRoot = path.join(projectRoot, "memory-bank");
+    const root = fs.existsSync(dotRoot) && fs.statSync(dotRoot).isDirectory() ? dotRoot : fs.existsSync(legacyRoot) && fs.statSync(legacyRoot).isDirectory() ? legacyRoot : null;
+    const folderName = root ? path.basename(root) : null;
+    if (!root) {
+        return { root: null, folder_name: null, version: null, source: null, status: "missing", reason: "no_memory_bank" };
+    }
+    const indexPath = path.join(root, "index.md");
+    const indexVersion = fs.existsSync(indexPath) ? readMemoryBankVersionFromIndex(indexPath) : null;
+    if (indexVersion) {
+        return { root, folder_name: folderName, version: indexVersion, source: path.relative(projectRoot, indexPath), status: "present" };
+    }
+    const mbbPath = path.join(root, "mbb", "index.md");
+    const mbbVersion = fs.existsSync(mbbPath) ? readMemoryBankCanonTextVersion(mbbPath) : null;
+    if (mbbVersion) {
+        return { root, folder_name: folderName, version: mbbVersion, source: path.relative(projectRoot, mbbPath), status: "present" };
+    }
+    return { root, folder_name: folderName, version: null, source: null, status: "unknown", reason: "memory_bank_version_missing" };
+}
+function readFlowPackMetadata(projectRoot, memoryBankRoot) {
+    if (!memoryBankRoot) {
+        return {
+            manifest_path: null,
+            schema_id: null,
+            pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
+            source_commit: null,
+            canon_version_at_source_commit: null,
+            status: "missing",
+            reason: "no_memory_bank",
+            canonical_only_files: []
+        };
+    }
+    const flowRoot = path.join(memoryBankRoot, "dd-flow");
+    const manifestPath = path.join(flowRoot, "manifest.json");
+    const canonicalOnlyFiles = canonicalOnlyFlowNames.filter((file) => fs.existsSync(path.join(flowRoot, file)));
+    if (!fs.existsSync(manifestPath)) {
+        return {
+            manifest_path: path.relative(projectRoot, manifestPath),
+            schema_id: null,
+            pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
+            source_commit: null,
+            canon_version_at_source_commit: null,
+            status: "missing",
+            reason: "flow_pack_manifest_missing",
+            canonical_only_files: canonicalOnlyFiles
+        };
+    }
+    let manifest;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            throw new Error("manifest is not an object");
+        manifest = parsed;
+    }
+    catch {
+        return {
+            manifest_path: path.relative(projectRoot, manifestPath),
+            schema_id: null,
+            pack_version: null,
+            canon_root: null,
+            canon_memory_bank_root: null,
+            canon_flow_root: null,
+            source_commit: null,
+            canon_version_at_source_commit: null,
+            status: "invalid",
+            reason: "flow_pack_manifest_invalid_json",
+            canonical_only_files: canonicalOnlyFiles
+        };
+    }
+    const schemaId = stringOrNull(manifest.schema_id);
+    const canonVersion = stringOrNull(manifest.canon_version_at_source_commit) ?? stringOrNull(manifest.canon_version);
+    const sourceCommit = stringOrNull(manifest.source_commit);
+    const canonRoot = stringOrNull(manifest.canon_root);
+    const canonMemoryBankRoot = stringOrNull(manifest.canon_memory_bank_root);
+    const canonFlowRoot = stringOrNull(manifest.canon_flow_root);
+    const status = schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && canonMemoryBankRoot && canonFlowRoot
+        ? "present"
+        : schemaId === "dd-flow/project-flow-pack-manifest@1" ||
+            (schemaId === "dd-flow/project-flow-pack-manifest@2" && canonVersion && (!canonMemoryBankRoot || !canonFlowRoot))
+            ? "degraded"
+            : "invalid";
+    const reason = status === "degraded" && schemaId === "dd-flow/project-flow-pack-manifest@2"
+        ? "flow_pack_manifest_missing_explicit_canon_roots"
+        : status === "degraded"
+            ? "legacy_flow_pack_manifest"
+            : status === "invalid"
+                ? "flow_pack_manifest_schema_unknown"
+                : undefined;
+    return {
+        manifest_path: path.relative(projectRoot, manifestPath),
+        schema_id: schemaId,
+        pack_version: stringOrNull(manifest.pack_version),
+        canon_root: canonRoot,
+        canon_memory_bank_root: canonMemoryBankRoot,
+        canon_flow_root: canonFlowRoot,
+        source_commit: sourceCommit,
+        canon_version_at_source_commit: canonVersion,
+        status,
+        ...(reason ? { reason } : {}),
+        canonical_only_files: canonicalOnlyFiles
+    };
+}
+function readMemoryBankVersionFromIndex(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const match = text.match(/^---\n([\s\S]*?)\n---/);
+    if (!match?.[1])
+        return null;
+    try {
+        const parsed = parseYaml(match[1]);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const value = parsed.memory_bank_version;
+            return typeof value === "string" && value.length > 0 ? value : null;
+        }
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+function readMemoryBankCanonTextVersion(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const ru = text.match(/Текущая версия канона Memory Bank:\s*`([^`]+)`/);
+    if (ru?.[1])
+        return ru[1];
+    const en = text.match(/Memory Bank canon version:\s*`?([0-9]+\.[0-9]+\.[0-9][^`\s]*)`?/i);
+    return en?.[1] ?? null;
+}
+function compareMemoryBankVersion(current, target, artifactStatus) {
+    if (artifactStatus === "missing")
+        return { status: "missing", confidence: "none", reason: "memory_bank_missing", current, target };
+    if (!current)
+        return { status: "unknown", confidence: "none", reason: "memory_bank_version_missing", current, target };
+    if (!target)
+        return { status: "unknown", confidence: "none", reason: "canon_version_unknown", current, target };
+    const currentSemver = parseSemver(current);
+    const targetSemver = parseSemver(target);
+    if (!currentSemver || !targetSemver)
+        return { status: "invalid", confidence: "none", reason: "invalid_semver", current, target };
+    const comparison = compareSemver(currentSemver, targetSemver);
+    if (comparison === 0)
+        return { status: "same", confidence: "semver", reason: "semver_equal", current, target };
+    return { status: comparison < 0 ? "behind" : "ahead", confidence: "semver", reason: comparison < 0 ? "semver_older" : "semver_newer", current, target };
+}
+function compareFlowPackCommit(current, target, canonRoot, artifactStatus) {
+    if (artifactStatus === "missing")
+        return { status: "missing", confidence: "none", reason: "flow_pack_manifest_missing", current, target };
+    if (artifactStatus === "invalid")
+        return { status: "invalid", confidence: "none", reason: "flow_pack_manifest_invalid", current, target };
+    if (!current)
+        return { status: "unknown", confidence: "none", reason: "flow_pack_source_commit_missing", current, target };
+    if (!target)
+        return { status: "unknown", confidence: "none", reason: "canon_commit_unknown", current, target };
+    if (current === target)
+        return { status: "same", confidence: "exact", reason: "commit_equal", current, target };
+    if (!canonRoot || !fs.existsSync(path.join(canonRoot, ".git"))) {
+        return { status: "unknown", confidence: "none", reason: "git_history_unavailable", current, target };
+    }
+    const projectAncestor = gitSuccess(canonRoot, ["merge-base", "--is-ancestor", current, target]);
+    if (projectAncestor)
+        return { status: "behind", confidence: "git_ancestry", reason: "source_commit_ancestor_of_canon", current, target };
+    const canonAncestor = gitSuccess(canonRoot, ["merge-base", "--is-ancestor", target, current]);
+    if (canonAncestor)
+        return { status: "ahead", confidence: "git_ancestry", reason: "source_commit_descendant_of_canon", current, target };
+    const currentExists = gitSuccess(canonRoot, ["cat-file", "-e", `${current}^{commit}`]);
+    const targetExists = gitSuccess(canonRoot, ["cat-file", "-e", `${target}^{commit}`]);
+    return {
+        status: currentExists && targetExists ? "diverged" : "unknown",
+        confidence: currentExists && targetExists ? "git_ancestry" : "none",
+        reason: currentExists && targetExists ? "git_histories_diverged" : "source_commit_not_in_resolved_canon",
+        current,
+        target
+    };
+}
+function overallDrift(memoryBank, flowPack, memoryStatus, flowStatus) {
+    if (memoryStatus === "missing")
+        return "not_applicable";
+    if (memoryBank.status === "invalid" || flowPack.status === "invalid")
+        return "invalid";
+    if (memoryBank.status === "missing" || flowPack.status === "missing")
+        return "missing";
+    if (memoryBank.status === "ahead" || flowPack.status === "ahead")
+        return "ahead";
+    if (memoryBank.status === "behind" || flowPack.status === "behind")
+        return "behind";
+    if (memoryBank.status === "diverged" || flowPack.status === "diverged")
+        return "diverged";
+    if (memoryBank.status === "same" && (flowPack.status === "same" || flowStatus === "degraded"))
+        return flowStatus === "degraded" ? "unknown" : "same";
+    return "unknown";
+}
+function nextAction(overall, memoryStatus, flowStatus) {
+    if (overall === "same")
+        return "no_action";
+    if (overall === "not_applicable" && memoryStatus === "missing")
+        return "run_mb_init_if_project_needs_memory_bank";
+    if (overall === "behind" || flowStatus === "degraded")
+        return "run_canonical_mb_upgrade";
+    if (overall === "missing")
+        return "run_canonical_mb_upgrade_or_repair_manifest";
+    if (overall === "invalid")
+        return "repair_memory_bank_markers_or_manifest";
+    return "inspect_status_reasons";
+}
+function nearestGitRoot(cwd) {
+    const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
+    if (result.status !== 0)
+        return null;
+    const stdout = result.stdout.trim();
+    return stdout ? existingDirectoryRealpath(stdout) : null;
+}
+function existingDirectoryRealpath(root) {
+    const absolute = path.resolve(root);
+    if (!fs.existsSync(absolute) || !fs.statSync(absolute).isDirectory())
+        return null;
+    return fs.realpathSync(absolute);
+}
+function stringOrNull(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function parseSemver(version) {
+    const match = version.match(/^([0-9]+)\.([0-9]+)\.([0-9]+)(?:[-+].*)?$/);
+    if (!match?.[1] || !match[2] || !match[3])
+        return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareSemver(left, right) {
+    for (let index = 0; index < 3; index += 1) {
+        const leftPart = left[index] ?? 0;
+        const rightPart = right[index] ?? 0;
+        const diff = leftPart - rightPart;
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function gitSuccess(cwd, args) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+    return result.status === 0;
+}

package/dist/storage/database.js

@@ -194,6 +194,13 @@ function migrate(db) {
       FOREIGN KEY(project_id) REFERENCES projects(id)
     );
 
+    CREATE TABLE IF NOT EXISTS runtime_config (
+      key TEXT PRIMARY KEY,
+      value_json TEXT NOT NULL,
+      created_at TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    );
+
     CREATE TABLE IF NOT EXISTS flow_sessions (
       session_id TEXT NOT NULL,
       project_id TEXT NOT NULL,
@@ -236,6 +243,9 @@ function migrate(db) {
       runtime_path TEXT NOT NULL,
       run_dir TEXT NOT NULL,
       run_index_path TEXT NOT NULL,
+      run_home_path TEXT,
+      layout_version TEXT,
+      artifact_root_kind TEXT,
       index_json TEXT NOT NULL,
       created_at TEXT NOT NULL,
       updated_at TEXT NOT NULL,
@@ -311,6 +321,9 @@ function migrate(db) {
     ensureColumn(db, "flow_sessions", "next_action", "ALTER TABLE flow_sessions ADD COLUMN next_action TEXT");
     ensureColumn(db, "flow_sessions", "metadata_json", "ALTER TABLE flow_sessions ADD COLUMN metadata_json TEXT NOT NULL DEFAULT '{}'");
     ensureColumn(db, "flow_sessions", "run_id", "ALTER TABLE flow_sessions ADD COLUMN run_id TEXT");
+    ensureColumn(db, "flow_runs", "run_home_path", "ALTER TABLE flow_runs ADD COLUMN run_home_path TEXT");
+    ensureColumn(db, "flow_runs", "layout_version", "ALTER TABLE flow_runs ADD COLUMN layout_version TEXT");
+    ensureColumn(db, "flow_runs", "artifact_root_kind", "ALTER TABLE flow_runs ADD COLUMN artifact_root_kind TEXT");
 }
 function ensureColumn(db, table, column, sql) {
     const columns = db.prepare(`PRAGMA table_info(${table})`).all();

package/dist/storage/paths.js

@@ -33,12 +33,30 @@ export function runtimeRunDir(ddFlowHome, projectId, runId) {
 export function runtimeRunJsonPath(ddFlowHome, projectId, runId) {
     return path.join(runtimeRunDir(ddFlowHome, projectId, runId), "run.json");
 }
+export function projectRunHome(ddFlowHome, projectId, runId) {
+    return path.join(projectHome(ddFlowHome, projectId), "runs", runId);
+}
+export function projectRunJsonPath(ddFlowHome, projectId, runId) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), "run.json");
+}
+export function projectRunIndexPath(ddFlowHome, projectId, runId) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), "run-index.json");
+}
+export function projectRunStageDir(ddFlowHome, projectId, runId, stageDir) {
+    return path.join(projectRunHome(ddFlowHome, projectId, runId), stageDir);
+}
 export function userFacingRunDir(workspaceRoot, runId) {
     return path.join(workspaceRoot, ".tasks", "dd-flow-runs", runId);
 }
+export function legacyWorkspaceRunDir(workspaceRoot, runId) {
+    return userFacingRunDir(workspaceRoot, runId);
+}
 export function userFacingRunIndexPath(workspaceRoot, runId) {
     return path.join(userFacingRunDir(workspaceRoot, runId), "run-index.json");
 }
+export function userFacingRunStageDir(workspaceRoot, runId, stageDir) {
+    return path.join(userFacingRunDir(workspaceRoot, runId), stageDir);
+}
 export function stateJsonPath(projectRoot, protocolId) {
     return path.join(protocolDir(projectRoot, protocolId), "state.json");
 }
@@ -54,3 +72,6 @@ export function projectRuntimeRoot(ddFlowHome, projectId) {
 export function projectCheckoutRoot(ddFlowHome, projectId) {
     return path.join(projectHome(ddFlowHome, projectId), "checkouts");
 }
+export function projectFeatureWorktreePath(ddFlowHome, projectId, runOrProtocolId, repoName) {
+    return path.join(projectCheckoutRoot(ddFlowHome, projectId), "worktrees", runOrProtocolId, repoName);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deksden-com/dd-flow-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Mechanical runtime CLI for dd-flow workflows.",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
   },
   "license": "MIT",
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && node scripts/copy-assets.mjs",
+    "build": "tsc -p tsconfig.build.json && node scripts/generate-build-info.mjs && node scripts/copy-assets.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --max-warnings=0",
     "test": "vitest run",