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

package/dist/services/engines.js

@@ -0,0 +1,532 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { getCliBuildInfo } from "./build-info.js";
+import { AppError } from "../shared/errors.js";
+import { ensureDir, engineStoreRoot, engineVersionRoot, resolveProjectRoot } from "../storage/paths.js";
+import { classifyCliOperation } from "./cli-operation-classifier.js";
+export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
+const routerNativeFamilies = new Set(["engine", "version", "schema"]);
+const sourceFile = fileURLToPath(import.meta.url);
+export function isEngineMode(env) {
+    return env.DD_FLOW_ENGINE_MODE === "1";
+}
+export function isRouterNativeCommand(args) {
+    const first = args[0];
+    if (!first || first === "--version")
+        return true;
+    if (first === "--help" || first === "-h")
+        return true;
+    if (args.includes("--help") || args.includes("-h"))
+        return true;
+    return routerNativeFamilies.has(first);
+}
+export function installCurrentEngine(context, input = {}) {
+    const build = getCliBuildInfo();
+    const packageRoot = findPackageRoot(path.dirname(sourceFile));
+    if (!packageRoot) {
+        throw new AppError("engine_install_failed", "Cannot locate package root for current dd-flow engine", 1);
+    }
+    const target = engineVersionRoot(context.ddFlowHome, build.package_name, build.version);
+    const manifestPath = path.join(target, "engine.json");
+    const existing = readManifest(manifestPath);
+    if (existing && !input.force && manifestHealthy(existing)) {
+        return {
+            ok: true,
+            action: "engine_install",
+            changed: false,
+            engine: manifestSummary(existing),
+            path: target
+        };
+    }
+    const lockDir = `${target}.lock`;
+    acquireInstallLock(lockDir);
+    try {
+        const afterLock = readManifest(manifestPath);
+        if (afterLock && !input.force && manifestHealthy(afterLock)) {
+            return {
+                ok: true,
+                action: "engine_install",
+                changed: false,
+                engine: manifestSummary(afterLock),
+                path: target
+            };
+        }
+        const parent = path.dirname(target);
+        ensureDir(parent);
+        const tmp = path.join(parent, `.${path.basename(target)}.tmp-${process.pid}-${Date.now()}`);
+        fs.rmSync(tmp, { recursive: true, force: true });
+        ensureDir(tmp);
+        copyPackageSnapshot(packageRoot, tmp);
+        const manifest = buildManifest(context, build.package_name, build.version, packageRoot, target, tmp);
+        fs.writeFileSync(path.join(tmp, "engine.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+        fs.rmSync(target, { recursive: true, force: true });
+        fs.renameSync(tmp, target);
+        const installed = requireManifest(path.join(target, "engine.json"));
+        return {
+            ok: true,
+            action: "engine_install",
+            changed: true,
+            engine: manifestSummary(installed),
+            path: target
+        };
+    }
+    finally {
+        fs.rmSync(lockDir, { recursive: true, force: true });
+    }
+}
+export function listEngines(context) {
+    const root = engineStoreRoot(context.ddFlowHome);
+    const engines = readInstalledManifests(root).map(manifestSummary);
+    return { ok: true, schema_id: "dd-flow/engine-list@1", engine_store: root, engines };
+}
+export function engineInfo(context, input) {
+    const build = getCliBuildInfo();
+    const packageName = input.packageName ?? build.package_name;
+    const version = input.version ?? build.version;
+    const manifest = requireManifest(path.join(engineVersionRoot(context.ddFlowHome, packageName, version), "engine.json"));
+    return { ok: true, schema_id: "dd-flow/engine-info@1", engine: manifest };
+}
+export function resolveEngine(context, input = {}) {
+    installCurrentEngine(context);
+    const selection = selectEngine(context, input);
+    if (selection.status === "missing") {
+        return { ok: false, error: missingEngineError(selection), selection, exit_code: 1 };
+    }
+    return { ok: true, schema_id: "dd-flow/engine-resolve@1", selection };
+}
+export function doctorEngines(context, input = {}) {
+    installCurrentEngine(context);
+    const root = engineStoreRoot(context.ddFlowHome);
+    const installed = readInstalledManifests(root);
+    const checks = installed.map((manifest) => ({
+        engine: manifestSummary(manifest),
+        status: manifestHealthy(manifest) ? "ok" : "corrupt",
+        diagnostics: manifestDiagnostics(manifest)
+    }));
+    const selection = selectEngine(context, input);
+    return {
+        ok: checks.every((check) => check.status === "ok") && selection.status !== "missing",
+        schema_id: "dd-flow/engine-doctor@1",
+        engine_store: root,
+        checks,
+        selection,
+        exit_code: checks.every((check) => check.status === "ok") && selection.status !== "missing" ? 0 : 1
+    };
+}
+export function routeArgsThroughEngine(context, args, io, stdin, env) {
+    if (isEngineMode(env) || isRouterNativeCommand(args))
+        return Promise.resolve(null);
+    installCurrentEngine(context);
+    const selection = selectEngine(context, { projectRoot: projectRootFromArgs(args) });
+    if (selection.status === "missing") {
+        const classification = classifyCliOperation(args, env);
+        if (classification.mode === "read_only_diagnostics" || classification.mode === "mb_upgrade") {
+            return Promise.resolve(null);
+        }
+        throw new AppError("missing_engine", "Required dd-flow engine is not installed", 1, missingEngineDetails(selection, classification));
+    }
+    if (!selection.selected)
+        return Promise.resolve(null);
+    const current = getCliBuildInfo();
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+        return Promise.resolve({ routed: true, exitCode: 0, inProcess: true });
+    }
+    const entrypoint = resolveManifestEntrypoint(selection.selected);
+    return spawnEngine(selection.selected, entrypoint, args, io, stdin, env, current.version);
+}
+export function engineRoutingMetadata(env) {
+    if (env.DD_FLOW_ENGINE_MODE !== "1")
+        return null;
+    return {
+        mode: "engine",
+        engine_home: env.DD_FLOW_ENGINE_HOME ?? null,
+        routed_from: env.DD_FLOW_ROUTED_FROM ?? null
+    };
+}
+export function selectEngine(context, input) {
+    const compatibility = readCompatibilityForProject(input.projectRoot);
+    const build = getCliBuildInfo();
+    const packageName = stringValue(compatibility?.engine?.package_name) ?? build.package_name;
+    const requiredRange = stringValue(compatibility?.engine?.version_range) ?? `>=${build.version} <9999.0.0`;
+    const recommended = stringValue(compatibility?.engine?.recommended_version) ?? build.version;
+    const installHintTemplate = stringValue(compatibility?.engine?.old_engine_install_hint) ?? `npx ${packageName}@<version> engine install`;
+    const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
+        .filter((manifest) => manifest.package_name === packageName)
+        .filter((manifest) => satisfiesRange(manifest.package_version, requiredRange))
+        .filter((manifest) => manifestHealthy(manifest))
+        .sort((a, b) => compareSemverStrings(b.package_version, a.package_version));
+    const selected = manifests[0] ?? null;
+    return {
+        status: selected ? "selected" : "missing",
+        package_name: packageName,
+        required_range: requiredRange,
+        recommended_version: recommended,
+        selected,
+        install_hint: selected ? null : installHintTemplate.replace("<version>", recommended),
+        project_root: input.projectRoot ? path.resolve(input.projectRoot) : null,
+        memory_bank_version: compatibility?.memory_bank_version ?? null,
+        diagnostics: selected ? [] : [`No installed engine satisfies ${packageName} ${requiredRange}`]
+    };
+}
+function readCompatibilityForProject(projectRoot) {
+    let resolvedProjectRoot = null;
+    if (projectRoot) {
+        try {
+            resolvedProjectRoot = resolveProjectRoot(projectRoot);
+        }
+        catch {
+            return null;
+        }
+    }
+    const roots = resolvedProjectRoot ? [path.join(resolvedProjectRoot, ".memory-bank", "dd-flow", "compatibility.json")] : [];
+    for (const file of roots) {
+        try {
+            return JSON.parse(fs.readFileSync(file, "utf8"));
+        }
+        catch {
+            // Best effort; caller falls back to current package.
+        }
+    }
+    return null;
+}
+function projectRootFromArgs(args) {
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if ((arg === "--project-root" || arg === "--root") && args[index + 1])
+            return args[index + 1];
+        if (arg?.startsWith("--project-root="))
+            return arg.slice("--project-root=".length);
+        if (arg?.startsWith("--root="))
+            return arg.slice("--root=".length);
+    }
+    return undefined;
+}
+function buildManifest(context, packageName, version, packageRoot, snapshotRoot, checksumRoot) {
+    return {
+        schema_id: engineManifestSchemaId,
+        package_name: packageName,
+        package_version: version,
+        engine_id: "dd-flow-engine",
+        engine_version: version,
+        installed_at: context.now(),
+        install_source: inferInstallSource(packageRoot, context.ddFlowHome),
+        package_root: snapshotRoot,
+        snapshot_root: snapshotRoot,
+        entrypoint: path.join("dist", "cli.js"),
+        supports_memorybank: [`>=0.0.0 <9999.0.0`],
+        supports_contracts: {
+            compatibility: ["dd-flow/compatibility@1"],
+            version: ["dd-flow/version-report@1"],
+            status: ["dd-flow/status-report@1"]
+        },
+        integrity: {
+            source: "package_snapshot",
+            checksum: fileListChecksum(checksumRoot),
+            mode: "file_list"
+        }
+    };
+}
+function copyPackageSnapshot(packageRoot, target) {
+    for (const item of ["dist", "package.json", "README.md", "CHANGELOG.md"]) {
+        const from = path.join(packageRoot, item);
+        if (!fs.existsSync(from))
+            continue;
+        const to = path.join(target, item);
+        const stat = fs.statSync(from);
+        if (stat.isDirectory())
+            copyDir(from, to);
+        else {
+            ensureDir(path.dirname(to));
+            fs.copyFileSync(from, to);
+        }
+    }
+}
+function inferInstallSource(packageRoot, ddFlowHome) {
+    const normalized = path.resolve(packageRoot);
+    if (normalized.includes(`${path.sep}_npx${path.sep}`) || normalized.includes(`${path.sep}.npm${path.sep}_npx${path.sep}`)) {
+        return "npx_package";
+    }
+    if (isInside(path.resolve(ddFlowHome), normalized))
+        return "bundled_package";
+    if (hasAncestorFile(normalized, ".git"))
+        return "local_development";
+    return "bundled_package";
+}
+function hasAncestorFile(start, name) {
+    let current = path.resolve(start);
+    while (true) {
+        if (fs.existsSync(path.join(current, name)))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+function copyDir(from, to) {
+    ensureDir(to);
+    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
+        const source = path.join(from, entry.name);
+        const target = path.join(to, entry.name);
+        if (entry.isDirectory())
+            copyDir(source, target);
+        else if (entry.isFile())
+            fs.copyFileSync(source, target);
+    }
+}
+function acquireInstallLock(lockDir) {
+    ensureDir(path.dirname(lockDir));
+    try {
+        fs.mkdirSync(lockDir, { recursive: false });
+    }
+    catch {
+        const stat = fs.existsSync(lockDir) ? fs.statSync(lockDir) : null;
+        if (stat && Date.now() - stat.mtimeMs > 120_000) {
+            fs.rmSync(lockDir, { recursive: true, force: true });
+            fs.mkdirSync(lockDir, { recursive: false });
+            return;
+        }
+        throw new AppError("engine_install_locked", "Another dd-flow engine install is in progress", 1, { lock_dir: lockDir });
+    }
+}
+function readInstalledManifests(root) {
+    if (!fs.existsSync(root))
+        return [];
+    const manifests = [];
+    for (const packageDir of fs.readdirSync(root)) {
+        const packageRoot = path.join(root, packageDir);
+        if (!fs.statSync(packageRoot).isDirectory())
+            continue;
+        for (const versionDir of fs.readdirSync(packageRoot)) {
+            const manifest = readManifest(path.join(packageRoot, versionDir, "engine.json"));
+            if (manifest)
+                manifests.push(manifest);
+        }
+    }
+    return manifests;
+}
+function requireManifest(file) {
+    const manifest = readManifest(file);
+    if (!manifest)
+        throw new AppError("engine_not_found", `Engine manifest not found: ${file}`, 1, { manifest: file });
+    return manifest;
+}
+function readManifest(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        if (record.schema_id !== engineManifestSchemaId)
+            return null;
+        return record;
+    }
+    catch {
+        return null;
+    }
+}
+function manifestHealthy(manifest) {
+    return manifestDiagnostics(manifest).length === 0;
+}
+function manifestDiagnostics(manifest) {
+    const diagnostics = [];
+    if (manifest.schema_id !== engineManifestSchemaId)
+        diagnostics.push("schema_id_mismatch");
+    if (!manifest.package_name || !manifest.package_version)
+        diagnostics.push("package_identity_missing");
+    const snapshotRoot = path.resolve(manifest.snapshot_root || manifest.package_root || "");
+    if (!snapshotRoot || !fs.existsSync(snapshotRoot))
+        diagnostics.push("snapshot_root_missing");
+    const entrypoint = safeResolveManifestEntrypoint(manifest);
+    if (!entrypoint)
+        diagnostics.push("entrypoint_outside_snapshot");
+    else if (!fs.existsSync(entrypoint))
+        diagnostics.push("entrypoint_missing");
+    return diagnostics;
+}
+function manifestSummary(manifest) {
+    return {
+        schema_id: manifest.schema_id,
+        package_name: manifest.package_name,
+        package_version: manifest.package_version,
+        engine_version: manifest.engine_version,
+        install_source: manifest.install_source,
+        entrypoint: manifest.entrypoint,
+        snapshot_root: manifest.snapshot_root,
+        resolved_entrypoint: safeResolveManifestEntrypoint(manifest),
+        installed_at: manifest.installed_at,
+        healthy: manifestHealthy(manifest),
+        diagnostics: manifestDiagnostics(manifest)
+    };
+}
+function resolveManifestEntrypoint(manifest) {
+    const resolved = safeResolveManifestEntrypoint(manifest);
+    if (!resolved) {
+        throw new AppError("unhealthy_engine", "Selected dd-flow engine entrypoint escapes its snapshot", 1, {
+            engine: manifestSummary(manifest)
+        });
+    }
+    return resolved;
+}
+function safeResolveManifestEntrypoint(manifest) {
+    const snapshotRoot = path.resolve(manifest.snapshot_root || manifest.package_root);
+    const candidate = path.isAbsolute(manifest.entrypoint)
+        ? path.resolve(manifest.entrypoint)
+        : path.resolve(snapshotRoot, manifest.entrypoint);
+    if (!isInside(snapshotRoot, candidate))
+        return null;
+    return candidate;
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function spawnEngine(manifest, entrypoint, args, io, stdin, env, routedFromVersion) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [entrypoint, ...args], {
+            env: {
+                ...process.env,
+                ...env,
+                DD_FLOW_ENGINE_MODE: "1",
+                DD_FLOW_ENGINE_HOME: manifest.snapshot_root,
+                DD_FLOW_ROUTED_FROM: routedFromVersion
+            },
+            stdio: ["pipe", "pipe", "pipe"]
+        });
+        const forwardSignal = (signal) => {
+            if (!child.killed)
+                child.kill(signal);
+        };
+        process.once("SIGINT", forwardSignal);
+        process.once("SIGTERM", forwardSignal);
+        child.stdout.on("data", (chunk) => io.stdout.write(chunk));
+        child.stderr.on("data", (chunk) => io.stderr.write(chunk));
+        child.on("error", (error) => {
+            process.off("SIGINT", forwardSignal);
+            process.off("SIGTERM", forwardSignal);
+            reject(new AppError("engine_dispatch_failed", `Failed to execute selected dd-flow engine: ${error.message}`, 1, {
+                engine: manifestSummary(manifest),
+                cause: String(error)
+            }));
+        });
+        child.on("close", (code, signal) => {
+            process.off("SIGINT", forwardSignal);
+            process.off("SIGTERM", forwardSignal);
+            if (signal)
+                resolve({ routed: true, exitCode: 128 + signalNumber(signal), inProcess: false });
+            else
+                resolve({ routed: true, exitCode: code ?? 1, inProcess: false });
+        });
+        if (stdin)
+            stdin.pipe(child.stdin);
+        else
+            child.stdin.end();
+    });
+}
+function signalNumber(signal) {
+    if (signal === "SIGINT")
+        return 2;
+    if (signal === "SIGTERM")
+        return 15;
+    return 1;
+}
+function missingEngineError(selection, classification = classifyCliOperation(["unknown"])) {
+    return {
+        code: "missing_engine",
+        message: `No installed dd-flow engine satisfies ${selection.package_name} ${selection.required_range ?? ""}`.trim(),
+        details: missingEngineDetails(selection, classification)
+    };
+}
+function missingEngineDetails(selection, classification) {
+    return {
+        package_name: selection.package_name,
+        required_range: selection.required_range,
+        recommended_version: selection.recommended_version,
+        install_hint: selection.install_hint,
+        project_root: selection.project_root,
+        memory_bank_version: selection.memory_bank_version,
+        diagnostics: selection.diagnostics,
+        compatibility: missingEngineCompatibilityReport(selection, classification)
+    };
+}
+function missingEngineCompatibilityReport(selection, classification) {
+    const build = getCliBuildInfo();
+    return {
+        verdict: "incompatible",
+        memorybank_version: selection.memory_bank_version,
+        router_version: build.version,
+        cli_version: build.version,
+        engine_version: null,
+        engine_resolution: selection.status,
+        required_engine_range: selection.required_range,
+        recommended_engine_version: selection.recommended_version,
+        allowed_modes: ["read_only_diagnostics", "mb_upgrade"],
+        operation_mode: classification.mode,
+        blocked_operation: classification.mode === "normal_write" ? classification.operation : null,
+        install_hint: selection.install_hint,
+        project_root: selection.project_root,
+        diagnostics: selection.diagnostics
+    };
+}
+function findPackageRoot(start) {
+    let current = path.resolve(start);
+    while (true) {
+        if (fs.existsSync(path.join(current, "package.json")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+function fileListChecksum(root) {
+    const files = [];
+    collectFiles(root, root, files);
+    return Buffer.from(files.sort().join("\n")).toString("base64url");
+}
+function collectFiles(root, current, files) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+        if (entry.name === "engine.json")
+            continue;
+        const full = path.join(current, entry.name);
+        if (entry.isDirectory())
+            collectFiles(root, full, files);
+        else if (entry.isFile())
+            files.push(path.relative(root, full));
+    }
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function satisfiesRange(version, range) {
+    const parts = range.split(/\s+/).filter(Boolean);
+    return parts.every((part) => {
+        if (part.startsWith(">="))
+            return compareSemverStrings(version, part.slice(2)) >= 0;
+        if (part.startsWith(">"))
+            return compareSemverStrings(version, part.slice(1)) > 0;
+        if (part.startsWith("<="))
+            return compareSemverStrings(version, part.slice(2)) <= 0;
+        if (part.startsWith("<"))
+            return compareSemverStrings(version, part.slice(1)) < 0;
+        return version === part;
+    });
+}
+function compareSemverStrings(left, right) {
+    const a = parseSemver(left);
+    const b = parseSemver(right);
+    if (!a || !b)
+        return left.localeCompare(right);
+    for (const index of [0, 1, 2]) {
+        const diff = a[index] - b[index];
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+function parseSemver(value) {
+    const match = value.match(/^(\d+)\.(\d+)\.(\d+)/);
+    return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}

package/dist/services/flow-guidance.js

@@ -1,10 +1,13 @@
 import path from "node:path";
 import { defaultFlowContract, flowContractForState } from "../domain/flow-contract.js";
+import { normalizeProtocolLifecycle } from "./protocol-lifecycle.js";
 export function buildProtocolFlowGuidance(input) {
     const contract = flowContractForState(input.state);
+    const lifecycle = normalizeProtocolLifecycle({ state: input.state, queueStatus: input.queueStatus ?? null, flowContract: contract });
     const stageChain = latestRunStageChain(input.latestRun);
     return buildFlowGuidance({
         currentStage: input.state.stage,
+        lifecycle,
         contract,
         stageChain,
         runId: stringValue(input.latestRun?.id),
@@ -17,6 +20,7 @@ export function buildRunFlowGuidance(input) {
     const currentStage = input.protocolStage ?? inferStageFromRun(input.stageRuns);
     return buildFlowGuidance({
         currentStage,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: currentStage, rawStatus: "running", flowContract: contract }),
         contract,
         stageChain: chain,
         runId: input.runId ?? null,
@@ -25,9 +29,11 @@ export function buildRunFlowGuidance(input) {
     });
 }
 export function buildStaticFlowGuidance(input) {
+    const contract = input.contract ?? defaultFlowContract;
     return buildFlowGuidance({
         currentStage: input.stage,
-        contract: input.contract ?? defaultFlowContract,
+        lifecycle: normalizeProtocolLifecycle({ rawStage: input.stage, rawStatus: input.status ?? "running", queueStatus: input.queueStatus ?? null, flowContract: contract }),
+        contract,
         stageChain: [],
         runId: null,
         queueStatus: input.queueStatus ?? null
@@ -148,6 +154,7 @@ function buildFlowGuidance(input) {
 function guidance(input, value) {
     return {
         current_stage: input.currentStage,
+        ...(input.lifecycle ? { lifecycle: input.lifecycle } : {}),
         allowed_next_stages: input.contract.transitions[input.currentStage] ?? [],
         recommended_next_action: value.action,
         recommended_prompt: value.prompt,

package/dist/services/hooks.js

@@ -801,7 +801,7 @@ function mergeQueueMutation(command) {
     return match?.[1] ?? null;
 }
 function mergeLaneLockMutation(command) {
-    return /\bdd-flow\s+lane\s+lock\s+(acquire|heartbeat|release|wait)\b/.test(command) && /(?:--lane(?:\s+|=)(?:"merge"|'merge'|merge)\b)/.test(command);
+    return /\bdd-flow\s+lane\s+lock\s+(acquire|heartbeat|release|wait|wait-acquire)\b/.test(command) && /(?:--lane(?:\s+|=)(?:"merge"|'merge'|merge)\b)/.test(command);
 }
 function selfWorktreeRemovalTarget(command, cwd) {
     if (!/\bgit\s+worktree\s+remove\b/.test(command)) {