@deksden-com/dd-flow-cli 0.9.0-beta.9 → 0.9.0-beta.90

package/dist/services/engines.js

@@ -12,6 +12,7 @@ import { requireProtocol } from "./protocols.js";
 import { resolveCanonRootBeforeContext } from "./canon.js";
 import { appendAudit } from "./audit.js";
 import { findProjectByRoot } from "./projects.js";
+import { parseCommandArgs } from "./lifecycle-command.js";
 import { allRunEngineBindings, locateRunRoot, readRunEngineBinding, runEngineBindingSchemaId, writeRunEngineBinding } from "./run-engine-bindings.js";
 export const engineManifestSchemaId = "dd-flow/engine-manifest@1";
 const routerNativeFamilies = new Set(["engine", "version", "schema"]);
@@ -117,7 +118,7 @@ export function installCurrentEngine(context, input = {}) {
 }
 export function listEngines(context) {
     const root = engineStoreRoot(context.ddFlowHome);
-    const engines = readInstalledManifests(root).map(manifestSummary);
+    const engines = readInstalledManifests(root).map(manifest => manifestSummary(manifest));
     return { ok: true, schema_id: "dd-flow/engine-list@1", engine_store: root, engines };
 }
 export function engineInfo(context, input) {
@@ -138,11 +139,10 @@ export function resolveEngine(context, input = {}) {
 export function doctorEngines(context, input = {}) {
     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 checks = installed.map(manifest => {
+        const diagnostics = manifestDiagnostics(manifest);
+        return { engine: manifestSummary(manifest, diagnostics), status: diagnostics.length ? "corrupt" : "ok", diagnostics };
+    });
     const classification = input.classification ?? classifyCliOperation(["engine", "doctor"], input.env ?? context.env);
     const selection = selectEngine(context, input, {}, classification);
     return {
@@ -174,13 +174,16 @@ export function routeArgsThroughEngine(context, args, io, stdin, env, resolvedPr
     if (!selection.selected)
         return Promise.resolve(null);
     const current = getCliBuildInfo();
-    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version) {
+    const currentRoot = findPackageRoot(path.dirname(sourceFile));
+    if (selection.selected.package_name === current.package_name && selection.selected.package_version === current.version
+        && currentRoot !== null && fs.realpathSync(selection.selected.snapshot_root) === fs.realpathSync(currentRoot)) {
         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 bindRunEngine(context, input) {
+export function prepareRunEngineBind(context, input) {
+    const reason = requiredText(input.reason, "reason");
     const projectRoot = resolveProjectRoot(input.projectRoot);
     const located = locateRunRoot(context.db, projectRoot, input.runId);
     if (!located)
@@ -190,19 +193,31 @@ export function bindRunEngine(context, input) {
         packageName: input.packageName ?? getCliBuildInfo().package_name,
         packageVersion: input.engineVersion,
         ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
-    });
+    }, { checkEntrypoint: false });
     const requested = engineIdentity(manifest);
     if (existing) {
         if (sameEngineIdentity(existing.engine, requested))
-            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+            return { kind: "replay", binding: existing };
         throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, {
             run_id: located.run_id,
             current: existing.engine,
             requested
         });
     }
+    return { kind: "create", projectRoot, located, manifest, requested, reason, entrypoint: resolveManifestEntrypoint(manifest) };
+}
+export function bindRunEngine(context, input, prepared = prepareRunEngineBind(context, input)) {
+    if (prepared.kind === "replay")
+        return { ok: true, action: "run_engine_bind", changed: false, binding: prepared.binding };
+    const { projectRoot, located, manifest, requested, reason, entrypoint } = prepared;
+    const existing = readRunEngineBinding(located.binding_path, { allowMissing: true });
+    if (existing) {
+        if (sameEngineIdentity(existing.engine, requested))
+            return { ok: true, action: "run_engine_bind", changed: false, binding: existing };
+        throw new AppError("run_engine_binding_immutable", "RUN engine binding cannot be changed", 1, { run_id: located.run_id, current: existing.engine, requested });
+    }
     const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
-    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
+    const probe = spawnSync(process.execPath, [entrypoint, ...probeArgs], {
         cwd: manifest.snapshot_root,
         env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
         encoding: "utf8",
@@ -223,7 +238,7 @@ export function bindRunEngine(context, input) {
         project_root: projectRoot,
         bound_at: context.now(),
         source: "legacy_recovery",
-        reason: requiredText(input.reason, "reason"),
+        reason,
         engine: requested,
         probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` }
     };
@@ -252,6 +267,38 @@ export function bindCurrentEngineToRun(context, input) {
     };
     return writeRunEngineBinding(path.join(input.runRoot, "engine-binding.json"), binding).binding;
 }
+/** Forks are a new execution authority.  The source binding stays immutable;
+ * this replaces only the copied binding after proving the selected engine can
+ * read the copied RUN. */
+export function upgradeForkedRunEngine(context, input) {
+    const projectRoot = resolveProjectRoot(input.projectRoot);
+    const located = locateRunRoot(context.db, projectRoot, input.runId);
+    if (!located)
+        throw new AppError("not_found", `Forked RUN is not registered: ${input.runId}`, 1);
+    const manifest = requireBoundManifest(context.ddFlowHome, {
+        packageName: getCliBuildInfo().package_name,
+        packageVersion: input.engineVersion,
+        ...(input.integrityChecksum ? { integrityChecksum: input.integrityChecksum } : {})
+    });
+    const requested = engineIdentity(manifest);
+    readRunEngineBinding(located.binding_path);
+    const lineage = path.join(located.run_root, "fork-lineage.json");
+    if (!fs.existsSync(lineage))
+        throw new AppError("fork_lineage_missing", "Engine upgrade is permitted only for a derived RUN", 1, { run_id: located.run_id });
+    const probeArgs = ["run", "status", located.run_id, "--project-root", projectRoot, "--json"];
+    const probe = spawnSync(process.execPath, [resolveManifestEntrypoint(manifest), ...probeArgs], {
+        cwd: manifest.snapshot_root,
+        env: { ...process.env, ...context.env, DD_FLOW_HOME: context.ddFlowHome, DD_FLOW_ENGINE_MODE: "1", DD_FLOW_ENGINE_HOME: manifest.snapshot_root },
+        encoding: "utf8", timeout: 30_000
+    });
+    if (probe.status !== 0)
+        throw new AppError("fork_engine_probe_failed", "Selected engine cannot read the forked RUN", 1, { run_id: located.run_id, engine: manifestSummary(manifest), stderr: probe.stderr.slice(0, 2000) });
+    const binding = { schema_id: runEngineBindingSchemaId, run_id: located.run_id, project_root: projectRoot, bound_at: context.now(), source: "fork_upgrade", reason: requiredText(input.reason, "reason"), engine: requested, probe: { status: "passed", command: `dd-flow ${probeArgs.join(" ")}` } };
+    const temporary = `${located.binding_path}.fork-${process.pid}-${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(binding, null, 2)}\n`);
+    fs.renameSync(temporary, located.binding_path);
+    return binding;
+}
 function boundRunEngineForArgs(context, args, projectRoot) {
     const runId = runIdForArgs(args);
     if (!runId || !projectRoot)
@@ -274,6 +321,8 @@ function runIdForArgs(args) {
     const [family, command, ...rest] = args;
     const parsed = parseLightArgs(rest);
     if (family === "run" && command !== "start" && command !== "list") {
+        if (["drive", "control", "recovery", "capacity"].includes(command ?? ""))
+            return option(parsed, "run");
         if (command === "flags")
             return positional(parsed, 1);
         return positional(parsed, 0);
@@ -290,7 +339,7 @@ function runIdForArgs(args) {
         return option(parsed, "run");
     return null;
 }
-function requireBoundManifest(ddFlowHome, input) {
+function requireBoundManifest(ddFlowHome, input, options = {}) {
     const manifest = input.snapshotRoot
         ? requireManifest(path.join(input.snapshotRoot, "engine.json"))
         : findInstalledManifest(ddFlowHome, {
@@ -303,7 +352,7 @@ function requireBoundManifest(ddFlowHome, input) {
         || manifest.package_version !== input.packageVersion
         || input.integrityChecksum !== undefined && manifest.integrity.checksum !== input.integrityChecksum
         || input.snapshotRoot !== undefined && path.resolve(manifest.snapshot_root) !== path.resolve(input.snapshotRoot)
-        || !manifestHealthy(manifest)) {
+        || manifestDiagnostics(manifest, options).length !== 0) {
         throw new AppError("run_engine_binding_invalid", "RUN engine binding points to a missing or unhealthy engine snapshot", 1, {
             package_name: input.packageName,
             package_version: input.packageVersion,
@@ -344,7 +393,7 @@ function executionManifest(context) {
     return requireManifest(path.join(String(installed.path), "engine.json"));
 }
 function requiredText(value, label) {
-    const normalized = value.trim();
+    const normalized = typeof value === "string" ? value.trim() : "";
     if (!normalized)
         throw new AppError("usage", `Missing required value: ${label}`, 2);
     return normalized;
@@ -383,11 +432,7 @@ export function selectEngine(context, input, options = {}, classification = inpu
     const manifests = readInstalledManifests(engineStoreRoot(context.ddFlowHome))
         .filter((manifest) => manifest.package_name === packageName)
         .filter((manifest) => requiredRange !== null && satisfiesRange(manifest.package_version, requiredRange))
-        .filter((manifest) => options.allowCurrentInProcess
-        && manifest.package_name === build.package_name
-        && manifest.package_version === build.version
-        ? true
-        : manifestHealthy(manifest))
+        .filter((manifest) => manifestHealthy(manifest))
         .sort((a, b) => {
         const versionOrder = compareSemverStrings(b.package_version, a.package_version);
         if (versionOrder !== 0)
@@ -560,35 +605,11 @@ function canonCompatibilitySha(memorybankRoot) {
         return null;
     }
 }
-function parseLightArgs(args) {
-    const positional = [];
-    const options = new Map();
-    for (let index = 0; index < args.length; index += 1) {
-        const value = args[index];
-        if (value?.startsWith("--")) {
-            const equal = value.indexOf("=");
-            if (equal > 2) {
-                const key = value.slice(2, equal);
-                options.set(key, [...(options.get(key) ?? []), value.slice(equal + 1)]);
-                continue;
-            }
-            const key = value.slice(2);
-            const next = args[index + 1];
-            if (!next || next.startsWith("--"))
-                options.set(key, [...(options.get(key) ?? []), ""]);
-            else {
-                options.set(key, [...(options.get(key) ?? []), next]);
-                index += 1;
-            }
-        }
-        else if (value)
-            positional.push(value);
-    }
-    return { positional, options };
-}
+const parseLightArgs = parseCommandArgs;
 function option(parsed, key) {
     const values = parsed.options.get(key);
-    return values?.[values.length - 1] || null;
+    const value = values?.[values.length - 1];
+    return value && value !== "__dd_flow_flag__" ? value : null;
 }
 function positional(parsed, index) {
     return parsed.positional[index] ?? null;
@@ -620,23 +641,37 @@ function buildManifest(context, packageName, version, packageRoot, snapshotRoot,
     };
 }
 function copyPackageSnapshot(packageRoot, target) {
+    for (const [relative, source] of packageSnapshotFiles(packageRoot)) {
+        const destination = path.join(target, relative);
+        ensureDir(path.dirname(destination));
+        fs.copyFileSync(source, destination);
+    }
+}
+/** The same source inventory drives validation and copying; no staging writes. */
+function packageSnapshotFiles(packageRoot) {
+    const files = new Map();
+    const collect = (source, relative, skipNodeModules = false) => {
+        if (!fs.statSync(source).isDirectory()) {
+            files.set(relative, source);
+            return;
+        }
+        for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+            if (skipNodeModules && entry.name === "node_modules")
+                continue;
+            const child = path.join(source, entry.name), name = path.join(relative, entry.name);
+            if (entry.isDirectory())
+                collect(child, name, skipNodeModules);
+            else if (entry.isFile())
+                files.set(name, child);
+        }
+    };
     for (const item of ["dist", "package.json", "README.md", "CHANGELOG.md", "tools"]) {
         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);
-        }
+        collect(from, item);
     }
-    copyProductionDependencies(packageRoot, target);
-}
-function copyProductionDependencies(packageRoot, target) {
-    const queue = [{ sourceRoot: packageRoot, targetRoot: target, ancestors: new Set() }];
+    const queue = [{ sourceRoot: packageRoot, targetRoot: "", ancestors: new Set() }];
     const copied = new Set();
     while (queue.length > 0) {
         const current = queue.shift();
@@ -651,12 +686,35 @@ function copyProductionDependencies(packageRoot, target) {
             if (copied.has(copyKey))
                 continue;
             copied.add(copyKey);
-            copyDir(sourceRoot, targetRoot, true);
+            collect(sourceRoot, targetRoot, true);
             if (current.ancestors.has(sourceRoot))
                 continue;
             queue.push({ sourceRoot, targetRoot, ancestors: new Set([...current.ancestors, sourceRoot]) });
         }
     }
+    return files;
+}
+export function prepareForkEngine(engineVersion, integrityChecksum) {
+    const build = getCliBuildInfo();
+    if (engineVersion !== build.version)
+        throw new AppError("fork_engine_unavailable", "Fork installs the invoking CLI engine; invoke the requested version to upgrade the fork", 2, { requested: engineVersion, available: build.version });
+    const packageRoot = findPackageRoot(path.dirname(sourceFile));
+    if (!packageRoot || !fs.existsSync(path.join(packageRoot, "dist", "cli.js")))
+        throw new AppError("harness_runtime_unbuilt", "Build the CLI before preparing a fork", 1);
+    const files = packageSnapshotFiles(packageRoot);
+    if (integrityChecksum !== undefined) {
+        const checksum = crypto.createHash("sha256");
+        for (const [relative, source] of [...files].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)) {
+            if (path.basename(relative) === "engine.json")
+                continue;
+            checksum.update(relative);
+            checksum.update("\0");
+            checksum.update(fs.readFileSync(source));
+            checksum.update("\0");
+        }
+        if (checksum.digest("hex") !== integrityChecksum)
+            throw new AppError("fork_engine_unavailable", "Requested engine checksum differs from the invoking CLI artifact", 2, { requested: integrityChecksum });
+    }
 }
 function readProductionDependencies(packageRoot) {
     try {
@@ -713,19 +771,6 @@ function hasAncestorFile(start, name) {
         current = parent;
     }
 }
-function copyDir(from, to, skipNodeModules = false) {
-    ensureDir(to);
-    for (const entry of fs.readdirSync(from, { withFileTypes: true })) {
-        if (skipNodeModules && entry.name === "node_modules")
-            continue;
-        const source = path.join(from, entry.name);
-        const target = path.join(to, entry.name);
-        if (entry.isDirectory())
-            copyDir(source, target, skipNodeModules);
-        else if (entry.isFile())
-            fs.copyFileSync(source, target);
-    }
-}
 function acquireInstallLock(lockDir) {
     ensureDir(path.dirname(lockDir));
     try {
@@ -847,7 +892,7 @@ function manifestDiagnostics(manifest, options = {}) {
     }
     return diagnostics;
 }
-function manifestSummary(manifest) {
+function manifestSummary(manifest, diagnostics = manifestDiagnostics(manifest, { checkEntrypoint: false })) {
     return {
         schema_id: manifest.schema_id,
         package_name: manifest.package_name,
@@ -859,8 +904,8 @@ function manifestSummary(manifest) {
         snapshot_root: manifest.snapshot_root,
         resolved_entrypoint: safeResolveManifestEntrypoint(manifest),
         installed_at: manifest.installed_at,
-        healthy: manifestHealthy(manifest),
-        diagnostics: manifestDiagnostics(manifest)
+        healthy: diagnostics.length === 0,
+        diagnostics
     };
 }
 function resolveManifestEntrypoint(manifest) {