@deksden-com/dd-flow-cli 0.9.0-beta.15 → 0.9.0-beta.150

package/dist/cli/diagnostic-invocation.js

@@ -0,0 +1,46 @@
+import path from "node:path";
+import { AppError } from "../shared/errors.js";
+import { diagnosticFlowStages } from "../domain/diagnostic-flows.js";
+import { prepareCommandRoute } from "./command-inputs.js";
+function refuse(message) { throw new AppError("usage", message, 2, { effect: "no_effect" }); }
+/** Parser only: no files, operator settings, project mutation or runtime state. */
+export function prepareDiagnosticInvocation(args) {
+    const route = prepareCommandRoute(args), options = route.parsed.options;
+    const flowId = route.key === "flow mb-audit" ? "mb-audit"
+        : ["review", "flow project-review"].includes(route.key) ? "project-review" : refuse("Use flow mb-audit or review / flow project-review");
+    const value = (key) => options.get(key)?.[0];
+    const projectRoot = value("project-root"), requestId = value("request-id");
+    if (!path.isAbsolute(projectRoot) || path.resolve(projectRoot) !== projectRoot
+        || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,95}$/.test(requestId))
+        refuse("Use a canonical absolute project root and a bounded request ID");
+    if (value("profile") && value("profile-file"))
+        refuse("Use either --profile or --profile-file");
+    if (options.has("detach") && options.has("prepare-only"))
+        refuse("--detach and --prepare-only are exclusive");
+    const execution = {};
+    if (value("profile"))
+        execution.rootProfile = value("profile");
+    const stageProfiles = {};
+    for (const assignment of options.get("stage-profile") ?? []) {
+        const match = /^([^=]+)=([^=]+)$/.exec(assignment);
+        if (!match || !diagnosticFlowStages[flowId].includes(match[1]) || Object.hasOwn(stageProfiles, match[1]))
+            refuse("--stage-profile requires one known stage=profile assignment per stage");
+        stageProfiles[match[1]] = match[2];
+    }
+    if (Object.keys(stageProfiles).length)
+        execution.stageProfiles = stageProfiles;
+    const workProfiles = options.get("work-profile");
+    if (workProfiles) {
+        if (workProfiles.some(id => !id.trim()) || new Set(workProfiles).size !== workProfiles.length)
+            refuse("Work profiles must be nonempty and unique");
+        execution.workProfiles = [...workProfiles];
+    }
+    if (value("max-parallel") !== undefined) {
+        const raw = value("max-parallel"), n = Number(raw);
+        if (!/^[1-9][0-9]*$/.test(raw) || !Number.isSafeInteger(n) || n > 64)
+            refuse("--max-parallel must be an integer from 1 to 64");
+        execution.delegation = { mode: "external", max_parallel: n };
+    }
+    return { scope: { projectRoot, requestId, flowId }, execution, profileFile: value("profile-file"), intakeFile: value("intake-file"),
+        detach: options.has("detach"), prepareOnly: options.has("prepare-only"), nonInteractive: options.has("non-interactive") };
+}

package/dist/cli/diagnostic.js

@@ -0,0 +1,120 @@
+import { createContext } from "../runtime/context.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { resolveDdFlowHome, resolveProjectRoot } from "../storage/paths.js";
+import { readSetupStatus } from "../services/setup.js";
+import { PreparedInstalledFlowSource } from "../services/installed-flow-source.js";
+import { selectMemoryInitInstalledEngine } from "../services/memory-init-engine-release.js";
+import { readOperatorProfiles, readOperatorProfileInput } from "../services/operator-profiles.js";
+import { FrozenGenericExecution } from "../services/generic-execution.js";
+import { openMemoryInitStores } from "../services/memory-init-stores.js";
+import { registerProject, requireProjectByRoot } from "../services/projects.js";
+import { diagnosticSnapshotRoot } from "../services/diagnostic-snapshot.js";
+import { readDiagnosticRequest, retainDiagnosticRequest, startDiagnosticRun } from "../services/diagnostic-start.js";
+import { readFlowRunExecutionBundle } from "../services/runs.js";
+import { hybridDigest } from "../services/hybrid-contracts.js";
+import { onboardExecutor } from "../services/executor-onboarding.js";
+import { askExecutorChoice } from "./executor-onboarding.js";
+import { prepareDiagnosticInvocation } from "./diagnostic-invocation.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination } from "./response-file.js";
+import { prepareFileBytes } from "./input-preparation.js";
+import { writePreparationError } from "./error-output.js";
+import { launchAndObserveMemoryFlow } from "./memory-init.js";
+import { publishSetup } from "../harness-runtime/lib/setup-progress.mjs";
+export async function runDiagnosticCli(args, env = process.env, io = process) {
+    let context, effects = false;
+    try {
+        const output = parseOutputOptions(args), invocation = prepareDiagnosticInvocation(output.args), home = resolveDdFlowHome(env);
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const scope = invocation.scope;
+        if (resolveProjectRoot(scope.projectRoot) !== scope.projectRoot)
+            throw new AppError("usage", "Project root must be canonical", 2, { effect: "no_effect" });
+        const reader = createContext(env, "read_existing");
+        let retained = null;
+        try {
+            const project = reader.db.get("SELECT status FROM projects WHERE root=?", [scope.projectRoot]);
+            if (project?.status && project.status !== "active")
+                throw new AppError("diagnostic_project_inactive", "Activate the selected project explicitly before diagnosis", 2, { effect: "no_effect" });
+            if (project)
+                retained = readDiagnosticRequest(reader, scope);
+        }
+        finally {
+            reader.db.close?.();
+        }
+        if (invocation.profileFile)
+            invocation.execution.rootProfile = readOperatorProfileInput(invocation.profileFile);
+        const readIntake = () => {
+            if (!invocation.intakeFile)
+                throw new AppError("usage", "Fresh diagnosis requires --intake-file with the requested focus and constraints", 2, { effect: "no_effect" });
+            const bytes = prepareFileBytes(invocation.intakeFile, "diagnostic intake", 64 * 1024).bytes;
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+            }
+            catch {
+                throw new AppError("usage", "Diagnostic intake must be UTF-8", 2, { effect: "no_effect" });
+            }
+            if (!text.trim())
+                throw new AppError("usage", "Diagnostic intake cannot be empty", 2, { effect: "no_effect" });
+            return text;
+        };
+        if (retained) {
+            if (Object.entries(invocation.execution).some(([key, value]) => !Object.hasOwn(retained.selection, key) || hybridDigest(value) !== hybridDigest(retained.selection[key]))
+                || invocation.intakeFile && readIntake() !== retained.objective)
+                throw new AppError("diagnostic_request_conflict", "Supplied selectors differ from the original diagnostic request", 2, { effect: "no_effect" });
+        }
+        const objective = retained?.objective ?? readIntake();
+        let source, engine;
+        let rootProfile = invocation.execution.rootProfile;
+        if (!retained) {
+            const setup = readSetupStatus(home), installation = setup.installation;
+            if (!installation || setup.installation_readiness !== "installed")
+                throw new AppError("diagnostic_setup_required", "Install the desired canon and CLI with setup before diagnosis", 2, { effect: "no_effect" });
+            publishSetup("dependency_check_completed", "diagnostic:installation");
+            source = PreparedInstalledFlowSource.fromInstalledRelease(home, installation.manifest_sha256, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:canon");
+            engine = selectMemoryInitInstalledEngine(home, installation.manifest_sha256);
+            publishSetup("dependency_check_completed", "diagnostic:engine");
+            engine.admitDiagnosticFlow(source, scope.flowId);
+            publishSetup("dependency_check_completed", "diagnostic:handlers");
+            const stdin = io.stdin ?? process.stdin;
+            const selected = await onboardExecutor({ ...(typeof rootProfile === "string" ? { profileId: rootProfile } : {}),
+                ...(invocation.profileFile ? { profileFile: invocation.profileFile } : {}) }, () => readOperatorProfiles(home), { allowSkip: false, nonInteractive: invocation.nonInteractive || output.json || output.progressJsonl
+                    || !stdin.isTTY || !io.stderr.isTTY }, settings => askExecutorChoice(settings, { stdin, stderr: io.stderr }, { allowSave: false, allowSkip: false }));
+            if (!selected.profile)
+                throw new AppError("diagnostic_executor_required", "Select an executor profile before diagnosis", 2, { effect: "no_effect" });
+            rootProfile ??= selected.profile;
+        }
+        effects = true;
+        context = openMemoryInitStores(env, { scope: { projectRoot: scope.projectRoot, workspaceRoot: scope.projectRoot, requestId: scope.requestId },
+            selectionSha256: hybridDigest({ scope, objective, selection: retained?.selection ?? invocation.execution }) }).context;
+        publishSetup("dependency_check_completed", "diagnostic:stores");
+        registerProject(context, { root: scope.projectRoot });
+        if (!retained) {
+            const project = requireProjectByRoot(context, scope.projectRoot);
+            const workspace = diagnosticSnapshotRoot(context, { projectId: project.id, projectRoot: scope.projectRoot, sourceRoot: scope.projectRoot,
+                requestId: scope.requestId, flowId: scope.flowId });
+            const execution = FrozenGenericExecution.prepare(source.resolveRegisteredFlow(), readOperatorProfiles(home), {
+                ...invocation.execution, ...(rootProfile !== undefined ? { rootProfile } : {}), execution: "managed", stageSessionMode: "new_session",
+                delegation: invocation.execution.delegation ?? { mode: "external", max_parallel: 1 }
+            }, { requestId: scope.requestId, projectRoot: scope.projectRoot, workspace });
+            retainDiagnosticRequest(context, { scope, source: source, execution, engine: engine, objective, selection: invocation.execution });
+        }
+        const started = startDiagnosticRun(context, scope), bundle = readFlowRunExecutionBundle(context, { projectRoot: scope.projectRoot, runId: started.runId });
+        if (!bundle)
+            throw new AppError("diagnostic_bundle_missing", "Restore the retained diagnostic bundle", 1, { effect: "committed" });
+        return await launchAndObserveMemoryFlow(context, { ...invocation,
+            scope: { projectRoot: scope.projectRoot, workspaceRoot: bundle.execution.snapshot().scope.workspace, requestId: scope.requestId } }, started, scope.flowId, output, env, io);
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        if (effects)
+            record.details = { ...record.details, effect: ["unknown", "committed", "partial"].includes(String(record.details.effect)) ? record.details.effect : "partial", next_action: "reconcile_exact_request" };
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+    finally {
+        context?.db.close?.();
+    }
+}

package/dist/cli/error-output.js

@@ -0,0 +1,52 @@
+import { hasHelpIntent } from "./help.js";
+import { commandHelpTopic } from "./command-metadata.js";
+import { writeJson } from "../shared/json.js";
+export function writePreparationError(io, args, error) {
+    const literal = args.indexOf("--");
+    const options = literal < 0 ? args : args.slice(0, literal);
+    const payload = { ok: false, error };
+    const help = hasHelpIntent(args);
+    let json = false;
+    for (let index = 0; index < options.length; index++) {
+        if (help && options[index] === "--option") {
+            index++;
+            continue;
+        }
+        if (options[index] === "--json")
+            json = true;
+    }
+    // Retain the hook's machine-only contract even when transport validation fails.
+    if (json || args.slice(0, 3).join(" ") === "codex hook handle")
+        writeJson(io.stderr, payload);
+    else
+        io.stderr.write(renderHumanError(payload, args));
+}
+export function renderHumanError(payload, args) {
+    const lines = [`dd-flow: ${payload.error.message}`];
+    const details = recordObject(payload.error.details);
+    const compatibility = recordObject(details?.compatibility);
+    const remediation = recordObject(details?.remediation);
+    if (compatibility) {
+        lines.push(`Compatibility: ${String(compatibility.verdict ?? "unknown")} (${String(compatibility.engine_resolution ?? "unknown")})`);
+        if (compatibility.blocked_operation)
+            lines.push(`Blocked operation: ${String(compatibility.blocked_operation)}`);
+        if (compatibility.install_hint)
+            lines.push(`Install compatible engine: ${String(compatibility.install_hint)}`);
+    }
+    if (remediation?.mb_upgrade_mode)
+        lines.push(`Upgrade mode: ${String(remediation.mb_upgrade_mode)}`);
+    if (details?.preferred_command)
+        lines.push(`Preferred command: ${String(details.preferred_command)}`);
+    const related = Array.isArray(details?.related_commands) ? details.related_commands.map(String) : [];
+    if (related.length > 0) {
+        lines.push("", "Related commands:");
+        for (const command of related)
+            lines.push(`  ${command}`);
+    }
+    const topic = commandHelpTopic(args, "");
+    lines.push(`See: dd-flow${topic ? ` ${topic}` : ""} --help`);
+    return `${lines.join("\n")}\n`;
+}
+function recordObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}

package/dist/cli/executor-onboarding.js

@@ -0,0 +1,76 @@
+import { createInterface } from "node:readline";
+import { AppError } from "../shared/errors.js";
+import { prepareOperatorProfile, prepareProfileCreation, readOperatorProfileInput } from "../services/operator-profiles.js";
+/** One explicit choice; prompts go to stderr so stdout remains machine-readable. */
+export async function askExecutorChoice(settings, io, policy = {}) {
+    const ids = settings.profiles.map(entry => entry.id);
+    io.stderr.write(`Executor profiles: ${ids.length ? ids.join(", ") : "none configured"}\n`);
+    io.stderr.write(`Choose a profile ID/alias, file:/absolute/profile.json, create${policy.allowSkip === false ? "" : ", or skip"}. No model is selected automatically.\n`);
+    const terminal = createInterface({ input: io.stdin, output: io.stderr });
+    const lines = terminal[Symbol.asyncIterator]();
+    const cancelled = () => new AppError("onboarding_cancelled", "Executor onboarding was cancelled", 1, { effect: "no_effect" });
+    terminal.on("SIGINT", () => terminal.close());
+    const ask = async (prompt) => {
+        io.stderr.write(prompt);
+        const line = await lines.next();
+        if (line.done)
+            throw cancelled();
+        const answer = line.value.trim();
+        if (answer.length > 4096)
+            throw new AppError("usage", "Executor choice exceeds the input limit", 2, { effect: "no_effect" });
+        return answer;
+    };
+    try {
+        const answer = await ask("Executor: ");
+        if (answer === "skip") {
+            if (policy.allowSkip === false)
+                throw new AppError("agent_profile_missing", "This flow requires an executor profile", 1, { effect: "no_effect" });
+            return { skip: true };
+        }
+        if (answer === "create") {
+            io.stderr.write("Enter explicit profile settings; this does not probe providers or verify model access. Nothing is saved by this dialog.\n");
+            const input = { schema_id: "dd-flow/agent-profile@1" };
+            for (const [key, prompt] of [
+                ["id", "Profile ID: "], ["harness", "Harness (codex/zcode/agy/opencode/grok/droid): "],
+                ["provider", "Provider ID: "], ["model", "Model ID: "], ["reasoning", "Reasoning setting: "],
+                ["mode", "Mode setting: "], ["permission", "Permission (allow/deny): "]
+            ])
+                input[key] = await ask(prompt);
+            const profile = prepareOperatorProfile(input);
+            if (settings.profiles.some(entry => entry.id === profile.id) || Object.hasOwn(settings.aliases, profile.id)) {
+                throw new AppError("profile_id_conflict", "New profile ID collides with an existing profile or alias", 2, { effect: "no_effect" });
+            }
+            if (await ask("Use this profile for this operation? Type yes: ") !== "yes")
+                throw cancelled();
+            if (policy.allowSave === false)
+                return { profile };
+            const save = await ask("Save this profile globally during installation? Type yes or no: ");
+            if (save !== "yes" && save !== "no")
+                throw cancelled();
+            if (save === "yes") {
+                const defaultChoice = await ask("Set it as global default? Type yes or no: ");
+                if (defaultChoice !== "yes" && defaultChoice !== "no")
+                    throw cancelled();
+                return { profile, profileCreation: prepareProfileCreation(settings, profile, defaultChoice === "yes") };
+            }
+            return { profile };
+        }
+        if (answer.startsWith("file:")) {
+            const file = answer.slice(5);
+            if (!file.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(file))
+                throw new AppError("usage", "Profile file must be an absolute path", 2, { effect: "no_effect" });
+            return { profile: readOperatorProfileInput(file) };
+        }
+        if (!answer)
+            throw new AppError("agent_profile_missing", "An explicit executor choice is required", 1, { effect: "no_effect" });
+        return { profileId: answer };
+    }
+    catch (error) {
+        if (error instanceof AppError)
+            throw error;
+        throw cancelled();
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/cli/flows.js

@@ -0,0 +1,29 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { parseOutputOptions } from "./output-options.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import { listBundledFlows, showBundledFlow } from "../services/flow-catalog.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { writePreparationError } from "./error-output.js";
+/** Catalog inspection never creates an AppContext or executes a flow. */
+export function runFlowCatalogCli(args, io = process) {
+    try {
+        const output = parseOutputOptions(args);
+        const route = prepareCommandRoute(output.args);
+        let result;
+        if (route.key === "flow list")
+            result = { flows: listBundledFlows() };
+        else if (route.key === "flow show")
+            result = { flow: showBundledFlow(route.parsed.positional[0]) };
+        else
+            throw new AppError("usage", "Use dd-flow flow list or flow show <id>", 2, { effect: "no_effect" });
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        io.stdout.write(`${JSON.stringify(writeResponseFile({ ok: true, action: route.key.replaceAll(" ", "_"), ...result }, output), null, output.json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}

package/dist/cli/harnesses.js

@@ -0,0 +1,84 @@
+import { prepareCommandRoute } from "./command-inputs.js";
+import { writePreparationError } from "./error-output.js";
+import { parseOutputOptions } from "./output-options.js";
+import { optionalOption, optionalPositiveNumber } from "./argument-values.js";
+import { discoverHarnesses, harnessCatalog } from "../services/harness-discovery.js";
+import { AppError, errorRecord } from "../shared/errors.js";
+import { probeHarnessVersion } from "../services/harness-version-probe.js";
+import { probeHarnessDoctor } from "../services/harness-doctor.js";
+import { prepareResponseDestination, writeResponseFile } from "./response-file.js";
+import path from "node:path";
+import { validateModelScope } from "../services/model-discovery.js";
+/** Home-free ingress: process diagnostics require explicit effect admission. */
+export async function runHarnessesCli(args, env, io = { stdout: process.stdout, stderr: process.stderr }) {
+    let json = false;
+    try {
+        const output = parseOutputOptions(args);
+        json = output.json;
+        if (output.responseFile)
+            prepareResponseDestination(output.responseFile);
+        const route = prepareCommandRoute(output.args);
+        const family = route.key === "harnesses show" ? route.parsed.positional[0] : optionalOption(route.parsed, "harness");
+        if (family && !harnessCatalog.entries.some(entry => entry.id === family))
+            throw new AppError("usage", "Unknown harness; see dd-flow harnesses --help", 2, { effect: "no_effect" });
+        const provider = optionalOption(route.parsed, "provider"), account = optionalOption(route.parsed, "account-sha256");
+        const observationFile = optionalOption(route.parsed, "model-observation-file");
+        let modelScope;
+        if (provider !== undefined || account !== undefined || observationFile !== undefined) {
+            if (!provider || !account)
+                throw new AppError("usage", "Doctor model observations require both --provider and --account-sha256", 2, { effect: "no_effect", help: "harnesses doctor" });
+            modelScope = { harness: family, provider, account_sha256: account };
+            validateModelScope(modelScope);
+            if (observationFile) {
+                if (output.responseFile && path.resolve(observationFile) === path.resolve(output.responseFile))
+                    throw new AppError("usage", "Model observation and command response destinations must differ", 2, { effect: "no_effect" });
+                prepareResponseDestination(observationFile);
+            }
+        }
+        const discovery = discoverHarnesses({ env, ...(family ? { harness: family } : {}),
+            ...(optionalOption(route.parsed, "executable") ? { executable: optionalOption(route.parsed, "executable") } : {}) });
+        let probe;
+        let modelObservation;
+        let observationPublication;
+        if (route.key === "harnesses doctor") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Doctor requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            const stateDir = optionalOption(route.parsed, "state-dir"), nativeExecutable = optionalOption(route.parsed, "native-executable");
+            const timeoutMs = optionalPositiveNumber(route.parsed, "timeout-ms", true);
+            probe = await probeHarnessDoctor({ harness: family, executable: selected.path, env,
+                ...(stateDir !== undefined ? { stateDir } : {}), ...(nativeExecutable !== undefined ? { nativeExecutable } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: route.parsed.options.has("allow-services"),
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+            if (modelScope) {
+                modelObservation = { scope: modelScope, observed_at: new Date().toISOString(),
+                    status: probe.reported_models.length ? "listed" : "unavailable", complete: false, models: [...probe.reported_models] };
+                if (observationFile) {
+                    const published = writeResponseFile(modelObservation, { responseFile: observationFile });
+                    observationPublication = { path: observationFile, status: published.response_file_error ? "unknown" : "published",
+                        ...(published.response_file_error ? { error: published.response_file_error } : {}) };
+                }
+            }
+        }
+        else if (route.key === "harnesses probe-version") {
+            const selected = discovery.entries[0]?.candidates.find(candidate => candidate.selected);
+            if (!selected)
+                throw new AppError("harness_selection_required", "Version probe requires one installed executable; use --executable for ambiguous installations", 1, { effect: "no_effect" });
+            probe = await probeHarnessVersion({ harness: family, executable: selected.path, env,
+                ...(optionalPositiveNumber(route.parsed, "timeout-ms", true) === undefined ? {} : { timeoutMs: optionalPositiveNumber(route.parsed, "timeout-ms", true) }),
+                scope: { processes: route.parsed.options.has("allow-processes"), services: false,
+                    credentials: route.parsed.options.has("allow-credentials"), writes: route.parsed.options.has("allow-writes") } });
+        }
+        const result = { ok: true, action: route.key.replaceAll(" ", "_"), catalog: harnessCatalog, discovery, ...(probe ? { probe } : {}),
+            ...(modelObservation ? { model_observation: modelObservation, observation_scope_binding: "operator_declared_unverified" } : {}),
+            ...(observationPublication ? { model_observation_publication: observationPublication } : {}) };
+        io.stdout.write(`${JSON.stringify(writeResponseFile(result, output), null, json ? undefined : 2)}\n`);
+        return 0;
+    }
+    catch (error) {
+        const record = errorRecord(error);
+        writePreparationError(io, args, record);
+        return record.exitCode;
+    }
+}