@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/install/tool-lifecycle.ts

@@ -0,0 +1,151 @@
+'use strict';
+
+// External-tool lifecycle coordination deliberately uses execFile-style argument vectors.
+// Commands in the registry are data, never shell snippets, so neither inspection nor mutation
+// needs interpolation or a shell process.
+//
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): authored as `.ts`, run directly by Node
+// native type-stripping — no build step, no runtime dependency. Body stays CommonJS so a `.js`
+// caller's `require('../install/tool-lifecycle.ts')` keeps working while the tree is still `.js`.
+const { execFileSync } = require('node:child_process');
+
+const SUPPORTED_PLATFORMS = new Set(['darwin', 'linux']);
+
+type ExecFileSyncImpl = (file: string, args: string[], opts: any) => any;
+
+function isSupportedPlatform(platform: string = process.platform): boolean {
+  return SUPPORTED_PLATFORMS.has(platform);
+}
+
+function commandText(command: string[]): string {
+  return command.map((part) => JSON.stringify(part)).join(' ');
+}
+
+function failureKind(error: any): 'absent' | 'failed' {
+  return error?.code === 'ENOENT' ? 'absent' : 'failed';
+}
+
+function runInspection(command: string[], execFileSyncImpl: ExecFileSyncImpl): any {
+  try {
+    const output = execFileSyncImpl(command[0], command.slice(1), { encoding: 'utf8', stdio: 'pipe' });
+    return { command: [...command], result: 'succeeded', output: output == null ? '' : String(output) };
+  } catch (error: any) {
+    return {
+      command: [...command], result: failureKind(error),
+      error: error?.message || String(error),
+    };
+  }
+}
+
+/** Reduce every status command result to a safe tool state. */
+function normalizeToolState(inspections: any[]): string {
+  if (inspections.every((inspection) => inspection.result === 'succeeded')) return 'installed';
+  if (inspections.every((inspection) => inspection.result === 'absent')) return 'absent';
+  if (inspections.some((inspection) => inspection.result === 'succeeded')) return 'unknown';
+  return 'inspection-failed';
+}
+
+function inspectTool(tool: any, { execFileSyncImpl = execFileSync }: { execFileSyncImpl?: ExecFileSyncImpl } = {}): any {
+  const inspections = tool.status.commands.map((command: string[]) => runInspection(command, execFileSyncImpl));
+  return { state: normalizeToolState(inspections), inspections };
+}
+
+function inspectPrerequisites(tool: any, { execFileSyncImpl = execFileSync }: { execFileSyncImpl?: ExecFileSyncImpl } = {}): any[] {
+  return (tool.prerequisites || []).map((name: string) => {
+    const inspection = runInspection([name, '--version'], execFileSyncImpl);
+    return { name, available: inspection.result === 'succeeded', inspection };
+  });
+}
+
+function actionEligibility(tool: any, state: string, action: string, prerequisites: any[]): any {
+  if (action === 'status') return { applicable: false, reason: 'status inspection only' };
+  const contract = tool[action];
+  if (!contract) return { applicable: false, reason: `no verified ${action} command is registered` };
+  const missing = prerequisites.filter((prerequisite) => !prerequisite.available);
+  if (missing.length) return { applicable: false, reason: `missing prerequisite: ${missing.map((item) => item.name).join(', ')}` };
+  if (state === 'unknown' || state === 'inspection-failed') {
+    return { applicable: false, reason: `tool state is ${state}` };
+  }
+  if (action === 'install' && state !== 'absent') return { applicable: false, reason: 'tool is already installed' };
+  if ((action === 'update' || action === 'uninstall') && state !== 'installed') {
+    return { applicable: false, reason: 'tool is not installed' };
+  }
+  // The plan records a command before execution begins; callers can show this preview without
+  // implying that it has run. executeToolLifecycle replaces this with a terminal result.
+  return { applicable: true, command: [...contract.command], status: 'not-attempted' };
+}
+
+/**
+ * Inspect all status command vectors, then create a non-mutating action plan.
+ * The registry can be the loaded registry or an { externalTools } fixture.
+ */
+function planToolLifecycle({ registry, action = 'status', platform = process.platform, execFileSyncImpl = execFileSync }: { registry?: any; action?: string; platform?: string; execFileSyncImpl?: ExecFileSyncImpl } = {}): any {
+  if (!['install', 'update', 'uninstall', 'status'].includes(action)) {
+    throw new Error(`Unsupported external-tool action '${action}'`);
+  }
+  const supported = isSupportedPlatform(platform);
+  const tools = (registry?.externalTools || []).map((tool: any) => {
+    if (!supported) {
+      return {
+        tool, state: 'unknown', inspections: [], prerequisites: [],
+        action: { applicable: false, reason: `unsupported platform: ${platform}` },
+      };
+    }
+    const { state, inspections } = inspectTool(tool, { execFileSyncImpl });
+    const prerequisites = inspectPrerequisites(tool, { execFileSyncImpl });
+    return { tool, state, inspections, prerequisites, action: actionEligibility(tool, state, action, prerequisites) };
+  });
+  return { action, platform, supported, tools };
+}
+
+function defaultDisplay(command: string[]): void { console.error(`[INFO]  ${commandText(command)}`); }
+
+/**
+ * Display and separately confirm every planned mutation.  A failed command never prevents later
+ * commands from being independently offered and executed.
+ */
+function executeToolLifecycle({ plan, execFileSyncImpl = execFileSync, displayCommand = defaultDisplay, confirmCommand }: { plan?: any; execFileSyncImpl?: ExecFileSyncImpl; displayCommand?: (command: string[], tool?: any, action?: string) => void; confirmCommand?: (command: string[], tool?: any, action?: string) => boolean } = {}): any {
+  if (!plan) throw new Error('executeToolLifecycle requires a plan');
+  if (typeof confirmCommand !== 'function') throw new Error('executeToolLifecycle requires confirmCommand');
+
+  const notAttempted = plan.tools
+    .filter((item: any) => item.action.applicable)
+    .map((item: any) => ({ tool: item.tool.id, status: 'not-attempted', command: [...item.action.command] }));
+  const results = [];
+  for (const item of plan.tools) {
+    const action = item.action;
+    if (!plan.supported || !action.applicable) {
+      results.push({ tool: item.tool.id, status: 'skipped', reason: action.reason });
+      continue;
+    }
+    const command = action.command;
+    displayCommand([...command], item.tool, plan.action);
+    if (!confirmCommand([...command], item.tool, plan.action)) {
+      results.push({ tool: item.tool.id, status: 'declined', command: [...command] });
+      continue;
+    }
+    try {
+      const output = execFileSyncImpl(command[0], command.slice(1), { encoding: 'utf8', stdio: 'pipe' });
+      results.push({ tool: item.tool.id, status: 'succeeded', command: [...command], output: output == null ? '' : String(output) });
+    } catch (error: any) {
+      results.push({ tool: item.tool.id, status: 'failed', command: [...command], error: error?.message || String(error) });
+    }
+  }
+  return { action: plan.action, notAttempted, results };
+}
+
+// Deliberately no plan-then-execute convenience wrapper. One existed and nothing called it: the
+// only caller, `doflow tools`, plans and executes as two steps precisely so a confirmation lands
+// between them (`src/cli/commands/tools.js` refuses `--force` for that reason). A single call that
+// did both would be the one code path able to run an install command unconfirmed, so the gap is
+// the safety property rather than an omission to fill.
+module.exports = {
+  SUPPORTED_PLATFORMS,
+  isSupportedPlatform,
+  commandText,
+  normalizeToolState,
+  inspectTool,
+  inspectPrerequisites,
+  planToolLifecycle,
+  executeToolLifecycle,
+};

package/src/lifecycle/bash-availability.ts

@@ -0,0 +1,25 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// Preflight for FR-003: hook-bearing installs require an invocable bash interpreter
+// (POSIX bash, Git Bash/MSYS2, or WSL's own bash all satisfy this — from Node's
+// perspective they are indistinguishable, and design.md calls that out explicitly:
+// "is a bash-capable shell invocable" is the same question regardless of harness).
+const { execFileSync } = require('node:child_process');
+
+/** Whether a bash interpreter is invocable from the current process. Actually invokes
+ * `bash --version` rather than checking PATH/`command -v` presence — a same-named
+ * unrelated binary could satisfy a mere PATH check, but only a real bash exits cleanly
+ * on `--version`. ENOENT, a non-zero exit, or any other spawn error are all treated as
+ * "not available"; the caller does not need to distinguish the reason. */
+function hasBashCapableShell(execFileSyncImpl: any = execFileSync): boolean {
+  try {
+    execFileSyncImpl('bash', ['--version'], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { hasBashCapableShell };