@deksden-com/dd-flow-cli 0.9.0-beta.16 → 0.9.0-beta.161

package/dist/harness-runtime/lib/lifecycle-command.mjs

@@ -0,0 +1,273 @@
+import path from "node:path";
+import { createRequire } from "node:module";
+import { parse, quote } from "shell-quote";
+import { lifecycleOperationForArgv } from "./lifecycle-contract.mjs";
+
+// One grammar owns structure. shell-quote decodes identified command words;
+// neither parser grants authority or executes expansions.
+const require = createRequire(import.meta.url);
+let parser;
+function shellParser() {
+  if (!parser) {
+    const Parser = require("tree-sitter"), Bash = require("tree-sitter-bash");
+    const initialized = new Parser();
+    initialized.setLanguage(Bash);
+    parser = initialized;
+  }
+  return parser;
+}
+const shells = new Set(["bash", "sh", "zsh"]);
+const repeatedContexts = new Set(["for_statement", "while_statement", "function_definition", "c_style_for_statement"]);
+const dynamicTypes = ["command_substitution", "process_substitution", "arithmetic_expansion", "brace_expression", "extglob_pattern"];
+function words(text) {
+  try { const entries = parse(text, name => `$${name}`); return entries.every(entry => typeof entry === "string") ? entries : null; }
+  catch { return null; }
+}
+function ancestors(node) {
+  const result = [];
+  for (let parent = node.parent; parent; parent = parent.parent) result.push(parent.type);
+  return result;
+}
+function backgroundContext(node) {
+  for (let unit = node; unit.parent; unit = unit.parent) {
+    const siblings = unit.parent.children;
+    if (siblings[siblings.findIndex(child => child.id === unit.id) + 1]?.type === "&") return true;
+  }
+  return false;
+}
+function dynamicWord(node) {
+  return node.descendantsOfType(dynamicTypes).length > 0
+    || node.descendantsOfType(["simple_expansion", "expansion"]).some(expansion => !["$DD_FLOW_BIN", "${DD_FLOW_BIN}"].includes(expansion.text))
+    || node.type === "word" && /[*?[]/.test(node.text);
+}
+function launcherIndex(values, env) {
+  let index = 0;
+  while (values[index] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(values[index])) {
+    const value = values[index++], equals = value.indexOf("="); env[value.slice(0, equals)] = value.slice(equals + 1);
+  }
+  if (path.basename(values[index] ?? "") === "env") {
+    index++; if (values[index] === "--") index++;
+    if (values[index]?.startsWith("-")) return null;
+    while (values[index] && /^[A-Za-z_][A-Za-z0-9_]*=/.test(values[index])) {
+      const value = values[index++], equals = value.indexOf("="); env[value.slice(0, equals)] = value.slice(equals + 1);
+    }
+  }
+  if (["command", "exec"].includes(values[index] ?? "")) { index++; if (values[index] === "--") index++; }
+  return index;
+}
+function executionCwd(node, nodes) {
+  const lineage = unit => { const result = []; for (; unit; unit = unit.parent) result.push(unit); return result; };
+  const target = lineage(node), targetIds = new Set(target.map(unit => unit.id));
+  let cwd;
+  for (const previous of nodes) {
+    if (previous.endIndex >= node.startIndex) continue;
+    const values = words(previous.text);
+    if (!values) continue;
+    let index = launcherIndex(values, {});
+    if (values[index - 1] === "command" && values[index] === "-p") { index++; if (values[index] === "--") index++; }
+    if (values[index] === "builtin") { index++; if (values[index] === "--") index++; }
+    if (!["cd", "pushd", "popd"].includes(values[index])) continue;
+    const directoryIndex = index + (values[index + 1] === "--" ? 2 : 1);
+    const source = lineage(previous);
+    // A different subshell/substitution cannot change this leaf's directory.
+    // Pipelines are not treated as isolated: bash lastpipe is configurable.
+    if (source.some(unit => ["subshell", "command_substitution", "process_substitution"].includes(unit.type) && !targetIds.has(unit.id))) continue;
+    const common = source.find(unit => targetIds.has(unit.id));
+    const andList = unit => unit.type === "list" && unit.children.some(child => child.type === "&&");
+    const sourcePath = source.slice(1, source.indexOf(common));
+    const targetPath = target.slice(1, target.findIndex(unit => unit.id === common?.id));
+    // Only a successful, foreground absolute cd dominating the leaf is a
+    // route. This walks the grammar's nested left-associative && lists;
+    // it does not evaluate conditionals, directory stacks or shell programs.
+    // `command cd` is a builtin in bash but an external child in zsh;
+    // without native dialect proof none of these prefixes proves parent cwd.
+    if (values.slice(0, index).some(value => ["env", "exec", "command"].includes(path.basename(value)))
+      || values[index] !== "cd" || values.length !== directoryIndex + 1 || !path.isAbsolute(values[directoryIndex]) || dynamicWord(previous)
+      || backgroundContext(previous) || !common || !andList(common)
+      || sourcePath.some(unit => unit.type !== "redirected_statement" && !andList(unit))
+      || targetPath.some(unit => !["redirected_statement", "subshell", "compound_statement"].includes(unit.type) && !andList(unit))) return { unresolved: true };
+    cwd = path.resolve(values[directoryIndex]);
+  }
+  return { cwd };
+}
+function invocationFromWords(values, node, wrapped, env) {
+  let index = launcherIndex(values, env);
+  if (index === null) return null;
+  let executable = values[index], launcher;
+  if (path.basename(executable ?? "") === "node" && (path.basename(values[index + 1] ?? "") === "cli.js" || values[index + 1] === "$DD_FLOW_BIN")) {
+    launcher = executable; executable = values[++index];
+  }
+  if (!executable || !(path.basename(executable) === "dd-flow" || executable === "$DD_FLOW_BIN" || launcher && path.basename(executable) === "cli.js")) return null;
+  const argv = values.slice(index + 1), operation = lifecycleOperationForArgv(argv);
+  if (!operation) return null;
+  const contexts = ancestors(node);
+  const heredoc = node.parent?.type === "redirected_statement" && node.parent.descendantsOfType("heredoc_redirect").length > 0;
+  return { operation, executable, ...(launcher ? { launcher } : {}), argv, env, args: parseCommandArgs(argv.slice(operation === "recovery_accept" ? 3 : 2)),
+    command: quote(values), rewriteSafe: !wrapped, wrapped, heredoc, contexts, ...(!wrapped ? { sourceRange: { start: node.startIndex, end: node.endIndex } } : {}) };
+}
+export function parseLifecycleCommand(command) {
+  const result = analyze(command, false, 0);
+  return { ...result, participation: result.kind !== "none" ? "lifecycle" : result.participation ?? (result.auxiliary ? "auxiliary" : result.unresolved ? "unproven" : "none") };
+}
+function auxiliaryFromWords(values) {
+  const env = {}, index = launcherIndex(values, env);
+  let start = index;
+  if (path.basename(values[start] ?? "") === "node" && (path.basename(values[start + 1] ?? "") === "cli.js" || values[start + 1] === "$DD_FLOW_BIN")) start++;
+  if (!(path.basename(values[start] ?? "") === "dd-flow" || values[start] === "$DD_FLOW_BIN" || start !== index && path.basename(values[start] ?? "") === "cli.js")) return null;
+  const args = parseCommandArgs(values.slice(start + 1)), route = args.positional.slice(0, 3).join(" ");
+  const operation = route === "work repair add" ? "work_repair_add" : args.positional[0] === "stage" && args.positional[1] === "block" ? "stage_block" : null;
+  return operation ? { operation, args } : null;
+}
+// Recognition is not admission: recovered commands never provide argv authority.
+function recognizedParticipation(root, depth) {
+  for (const node of root.descendantsOfType("command")) {
+    const name = node.childForFieldName("name");
+    if (!name || name.type === "ERROR" || dynamicWord(name)) continue;
+    const values = words(node.text);
+    if (!values) continue;
+    if (invocationFromWords(values, node, true, {})) return "lifecycle";
+    if (auxiliaryFromWords(values)) return "auxiliary";
+    const index = launcherIndex(values, {});
+    if (values[index] === "eval" && depth < 8) {
+      const payload = node.namedChildren[index + 1];
+      if (payload && !dynamicWord(payload)) {
+        const nested = analyze(values.slice(index + 1).join(" "), true, depth + 1);
+        if (nested.kind !== "none" || nested.participation === "lifecycle") return "lifecycle";
+        if (nested.auxiliary || nested.participation === "auxiliary") return "auxiliary";
+      }
+    }
+  }
+  return "unproven";
+}
+function analyze(command, wrapped, depth) {
+  if (depth > 8 || command.length > 1_000_000) return { kind: "none", unresolved: true, reason: "shell_input_limit" };
+  const tree = shellParser().parse(command);
+  if (!tree) return { kind: "none", unresolved: true, reason: "shell_parse_error" };
+  try {
+    const root = tree.rootNode;
+    if (root.hasError) return { kind: "none", unresolved: true, participation: recognizedParticipation(root, depth), reason: "shell_parse_error" };
+    const nodes = root.descendantsOfType("command"), found = [], auxiliaries = [];
+    let unsupported;
+    for (const node of nodes) {
+      const name = node.childForFieldName("name"), values = words(node.text);
+      if (!name || !values) { if (name && dynamicWord(name)) unsupported ??= "dynamic_executable"; continue; }
+      const inherited = {};
+      // Conditional exports cannot become unconditional facts in a sibling.
+      for (const previous of root.namedChildren) {
+        if (previous.endIndex > node.startIndex) break;
+        if (previous.type !== "declaration_command" || !previous.text.startsWith("export ")) continue;
+        for (const assignment of previous.descendantsOfType("variable_assignment")) {
+          if (dynamicWord(assignment)) continue;
+          const decoded = words(assignment.text)?.[0], equals = decoded?.indexOf("=") ?? -1;
+          if (decoded && equals > 0) inherited[decoded.slice(0, equals)] = decoded.slice(equals + 1);
+        }
+      }
+      const direct = invocationFromWords(values, node, wrapped, inherited);
+      const auxiliary = auxiliaryFromWords(values);
+      if (auxiliary) {
+        const route = executionCwd(node, nodes);
+        if (dynamicWord(node) || backgroundContext(node) || ancestors(node).some(type => repeatedContexts.has(type) || ["command_substitution", "process_substitution"].includes(type)) || route.unresolved) unsupported ??= "unsupported_auxiliary_execution";
+        auxiliaries.push({ ...auxiliary, ...(route.cwd ? { expectedCwd: route.cwd } : {}) });
+        continue;
+      }
+      if (direct) {
+        if (backgroundContext(node)) unsupported ??= "background_lifecycle_execution";
+        if (node.namedChildren.some(dynamicWord)) unsupported ??= "unresolved_lifecycle_word";
+        if (direct.contexts.some(type => repeatedContexts.has(type))) unsupported ??= "repeated_lifecycle_context";
+        if (direct.contexts.some(type => ["command_substitution", "process_substitution"].includes(type))) unsupported ??= "executable_substitution";
+        const route = executionCwd(node, nodes);
+        if (route.unresolved) unsupported ??= "unresolved_execution_cwd";
+        else if (route.cwd) direct.expectedCwd = route.cwd;
+        found.push(direct); continue;
+      }
+      const outerEnv = { ...inherited }, shellIndex = launcherIndex(values, outerEnv);
+      const wrapper = path.basename(values[shellIndex] ?? "");
+      if (["time", "nohup", "timeout"].includes(wrapper)) {
+        let nestedIndex = shellIndex + 1;
+        if (wrapper === "time" && values[nestedIndex] === "-p") nestedIndex++;
+        if (values[nestedIndex] === "--") nestedIndex++;
+        if (wrapper === "timeout" && /^\d+(?:\.\d+)?[smhd]?$/.test(values[nestedIndex] ?? "")) nestedIndex++;
+        const nested = analyze(quote(values.slice(nestedIndex)), true, depth + 1);
+        if (nested.auxiliary || ["lifecycle", "auxiliary"].includes(nested.participation)) return { kind: "none", participation: nested.auxiliary ? "auxiliary" : nested.participation, unresolved: true, reason: "opaque_execution_wrapper" };
+        if (nested.kind !== "none") { found.push(...(nested.invocations ?? [nested.invocation])); unsupported ??= "opaque_execution_wrapper"; continue; }
+        if (nested.unresolved) unsupported ??= nested.reason;
+      }
+      if (shellIndex !== null && shells.has(path.basename(values[shellIndex] ?? "")) && /^-(?:l?c|cl)$/.test(values[shellIndex + 1] ?? "") && values[shellIndex + 2] !== undefined) {
+        const payloadNode = node.namedChildren[shellIndex + 2];
+        if (!payloadNode || dynamicWord(payloadNode)) { unsupported ??= "dynamic_shell_payload"; continue; }
+        if (node.namedChildren.some(child => child !== payloadNode && dynamicWord(child))) unsupported ??= "unresolved_shell_environment";
+        const nested = analyze(values[shellIndex + 2], true, depth + 1);
+        if (nested.auxiliary) {
+          const route = executionCwd(node, nodes);
+          if (route.unresolved || backgroundContext(node) || ancestors(node).some(type => repeatedContexts.has(type) || ["command_substitution", "process_substitution"].includes(type))) unsupported ??= "unsupported_auxiliary_execution";
+          auxiliaries.push({ ...nested.auxiliary, ...(route.cwd && !nested.auxiliary.expectedCwd ? { expectedCwd: route.cwd } : {}) });
+        }
+        if (nested.participation && ["lifecycle", "auxiliary"].includes(nested.participation) && nested.unresolved) return { kind: "none", unresolved: true, participation: nested.participation, reason: nested.reason };
+        if (nested.kind !== "none") {
+          const route = executionCwd(node, nodes);
+          if (route.unresolved) unsupported ??= "unresolved_execution_cwd";
+          for (const invocation of nested.invocations ?? [nested.invocation]) {
+            invocation.env = { ...outerEnv, ...invocation.env };
+            if (!invocation.expectedCwd && route.cwd) invocation.expectedCwd = route.cwd;
+          }
+          found.push(...(nested.invocations ?? [nested.invocation]));
+          if (backgroundContext(node)) unsupported ??= "background_lifecycle_execution";
+          if (ancestors(node).some(type => repeatedContexts.has(type))) unsupported ??= "repeated_lifecycle_context";
+          if (ancestors(node).some(type => ["command_substitution", "process_substitution"].includes(type))) unsupported ??= "executable_substitution";
+          if (nested.supported === false) unsupported ??= nested.reason ?? "unsupported_wrapper";
+        }
+        else if (nested.unresolved) unsupported ??= nested.reason;
+      } else if (values[shellIndex] === "eval") {
+        const participation = recognizedParticipation(root, depth);
+        if (participation !== "unproven") return { kind: "none", unresolved: true, participation, reason: "dynamic_eval" };
+        unsupported ??= "dynamic_eval";
+      }
+      else if (values[shellIndex] === "coproc") unsupported ??= "background_lifecycle_execution";
+      else if (dynamicWord(name)) unsupported ??= "dynamic_executable";
+    }
+    if (auxiliaries.length) {
+      if (found.length || auxiliaries.length !== 1) unsupported ??= "multiple_lifecycle_invocations";
+      if (!found.length) return { kind: "none", participation: "auxiliary", ...(unsupported ? { unresolved: true, reason: unsupported } : { auxiliary: auxiliaries[0] }) };
+    }
+    if (!found.length) return unsupported ? { kind: "none", unresolved: true, reason: unsupported } : { kind: "none" };
+    if (found.length > 1) unsupported ??= "multiple_lifecycle_invocations";
+    const invocation = found[0];
+    const composed = nodes.length > 1 || root.namedChildren.length !== 1 || invocation.contexts.some(type => !["program", "redirected_statement", "command"].includes(type));
+    return composed || unsupported ? { kind: "compound", invocation, invocations: found, supported: !unsupported, reason: unsupported ?? "shell_composition" }
+      : { kind: "standalone", invocation, invocations: found, supported: true };
+  } finally { /* Native Tree lifetime is managed by the Node binding. */ }
+}
+export function lifecycleCommandFromPayload(payload) {
+  const input = payload.tool_input && typeof payload.tool_input === "object" ? payload.tool_input : {};
+  const command = [payload.command, input.command, input.cmd].find(value => typeof value === "string" && value.length > 0);
+  return typeof command === "string" ? unwrapShellCommand(command) : undefined;
+}
+export function continuationCommand(command) {
+  return parseLifecycleCommand(command).auxiliary ?? null;
+}
+export function unwrapShellCommand(command) {
+  const values = words(command); if (!values || values.length !== 3 || !shells.has(path.basename(values[0])) || !/^-(?:l?c|cl)$/.test(values[1])) return command;
+  const tree = shellParser().parse(command);
+  try { const node = tree?.rootNode.namedChildren[0]?.namedChildren[2]; return node && !dynamicWord(node) ? values[2] : command; }
+  finally { /* Native Tree lifetime is managed by the Node binding. */ }
+}
+export function parseCommandArgs(argv) {
+  const positional = [], options = new Map();
+  for (let index = 0; index < argv.length; index++) {
+    const value = argv[index];
+    if (value === "--") { positional.push(...argv.slice(index + 1)); break; }
+    if (value?.startsWith("--")) {
+      const equals = value.indexOf("=");
+      if (equals > 2) { const key = value.slice(2, equals); options.set(key, [...(options.get(key) ?? []), value.slice(equals + 1)]); continue; }
+      const key = value.slice(2), next = argv[index + 1], optionValue = !next || next.startsWith("--") ? "__dd_flow_flag__" : next;
+      options.set(key, [...(options.get(key) ?? []), optionValue]); if (optionValue !== "__dd_flow_flag__") index++;
+    } else if (value) positional.push(value);
+  }
+  return { positional, options };
+}
+export function commandOption(invocation, name) { const value = invocation.args.options.get(name)?.at(-1); return value === "__dd_flow_flag__" ? undefined : value; }
+export function commandHasOption(invocation, name) { return invocation.args.options.has(name); }
+export function commandPosition(invocation, index) { return invocation.args.positional[index]; }
+export function shellSuffixOffset(command) {
+  const analysis = parseLifecycleCommand(command); return analysis.kind === "none" ? command.length : analysis.invocation.sourceRange?.end ?? command.length;
+}

package/dist/harness-runtime/lib/lifecycle-contract.d.mts

@@ -0,0 +1,11 @@
+export const lifecycleRoutes: {
+  readonly "session register": "session_register"; readonly "stage start": "stage_start"; readonly "stage finish": "stage_finish";
+  readonly "stage pause": "stage_pause"; readonly "stage resume": "stage_resume"; readonly "work start": "work_start";
+  readonly "work finish": "work_finish"; readonly "work fail": "work_fail"; readonly "merge apply": "merge_apply";
+  readonly "merge repair": "merge_repair"; readonly "run recovery accept": "recovery_accept";
+  readonly "delivery checks": "delivery_checks"; readonly "delivery execute": "delivery_execute"; readonly "delivery reconcile": "delivery_reconcile";
+};
+export type LifecycleOperation = typeof lifecycleRoutes[keyof typeof lifecycleRoutes];
+export const lifecycleInternalOptions: readonly ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv: readonly string[]): LifecycleOperation | null;
+export function lifecycleRouteForOperation(operation: LifecycleOperation): keyof typeof lifecycleRoutes;

package/dist/harness-runtime/lib/lifecycle-contract.mjs

@@ -0,0 +1,20 @@
+export const lifecycleRoutes = {
+  "session register": "session_register", "stage start": "stage_start", "stage finish": "stage_finish",
+  "stage pause": "stage_pause", "stage resume": "stage_resume", "work start": "work_start",
+  "work finish": "work_finish", "work fail": "work_fail", "merge apply": "merge_apply",
+  "merge repair": "merge_repair", "run recovery accept": "recovery_accept",
+  "delivery checks": "delivery_checks", "delivery execute": "delivery_execute", "delivery reconcile": "delivery_reconcile"
+};
+export const lifecycleInternalOptions = ["invocation-id", "hook-event-id"];
+export function lifecycleOperationForArgv(argv) {
+  if (argv.some(arg => arg === "--help" || arg === "-h")) return null;
+  for (const [route, operation] of Object.entries(lifecycleRoutes)) {
+    if (route.split(" ").every((part, index) => argv[index] === part)) return operation;
+  }
+  return null;
+}
+export function lifecycleRouteForOperation(operation) {
+  const entry = Object.entries(lifecycleRoutes).find(([, value]) => value === operation);
+  if (!entry) throw new Error(`Unknown lifecycle operation: ${operation}`);
+  return entry[0];
+}

package/dist/harness-runtime/lib/managed-daemon.d.mts

@@ -0,0 +1,16 @@
+import type { ChildProcess } from "node:child_process";
+type RuntimeConfig = Record<string, unknown>;
+type ProcessBinding = { id: string; lease_token: string; kind?: string; lease_expires_at?: string; registration_sha256?: string };
+export function runtimeProcess(config: RuntimeConfig, action: string, options?: Record<string, unknown>, transport?: { timeoutMs?: number; signal?: AbortSignal }): Promise<Record<string, unknown> | null>;
+export function readbackDaemonProcess(config: RuntimeConfig, record: ProcessBinding, transport?: { signal?: AbortSignal }): Promise<Record<string, unknown>>;
+export function registerDaemonProcess(config: RuntimeConfig, input: { kind: string; [key: string]: unknown }): Promise<ProcessBinding | null>;
+export function confirmDaemonProcess(config: RuntimeConfig, record: ProcessBinding | null | undefined, child: Pick<ChildProcess, "pid"> | null | undefined): Promise<void>;
+export function assertDaemonOwnership(stateDir: string, dispatch?: Record<string, unknown>, assertCurrent?: () => void): Promise<void>;
+export function heartbeatDaemonProcess(config: RuntimeConfig, record: ProcessBinding | null | undefined): Promise<void>;
+export function finishDaemonProcess(config: RuntimeConfig, record: ProcessBinding | null | undefined, state?: string, reason?: string): Promise<void>;
+export function cleanupFailedDaemonStart(config: RuntimeConfig, record: ProcessBinding | null, child: ChildProcess | null, original: Error & { details?: Record<string, unknown> }, readState: () => Promise<Record<string, unknown>>, daemonId: string): Promise<void>;
+export function completeBudgetOperation(stateDir: string, request: { id: string; operation: string; params?: { sessionId?: string } }, result: unknown, observe?: () => Promise<Record<string, unknown>>): Promise<Record<string, unknown>>;
+export function stopProcessGroup(child: ChildProcess | { pid: number; started: string } | null | undefined, graceMs?: number, options?: { detached?: boolean; settlementMs?: number; started?: string }): Promise<void>;
+export function assertStartupChild(child: Pick<ChildProcess, "pid" | "exitCode" | "signalCode">, expected: Record<string, unknown>, observed: Record<string, unknown> | null, log: string): void;
+export function retainStartupFailure(input: { state: Record<string, unknown>; publish: (state: Record<string, unknown>) => Promise<unknown>; log: string; error: Error & { code?: string; details?: Record<string, unknown> } }): Promise<void>;
+export function startManagedBridge(input: { config: RuntimeConfig; state: Record<string, unknown>; bridge: { child: ChildProcess | null; options: { onSpawn?: (child: ChildProcess) => Promise<void> }; start: () => Promise<unknown> }; kind: string; publish: (state: Record<string, unknown>) => Promise<unknown>; log?: string }): Promise<unknown>;