lilflow 0.1.0

package/src/agents/session-store.js

@@ -0,0 +1,91 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/**
+ * Absolute path to the session store file for a given run.
+ *
+ * @param {string} cwd - Workflow working directory.
+ * @param {string} runId - Workflow run identifier.
+ * @returns {string} Session store path.
+ */
+export function getSessionStorePath(cwd, runId) {
+  return path.join(cwd, ".flow", "sessions", `${runId}.json`);
+}
+
+/**
+ * Load the session store for a run. Returns an empty store if the file is absent.
+ *
+ * @param {string} cwd - Workflow working directory.
+ * @param {string} runId - Workflow run identifier.
+ * @returns {Promise<{sessions: Record<string, {provider: string, sessionId: string, updatedAt: string}>}>} Parsed store.
+ */
+export async function loadSessionStore(cwd, runId) {
+  const storePath = getSessionStorePath(cwd, runId);
+
+  try {
+    const raw = await readFile(storePath, "utf8");
+    const parsed = JSON.parse(raw);
+
+    if (parsed && typeof parsed === "object" && parsed.sessions && typeof parsed.sessions === "object") {
+      return { sessions: parsed.sessions };
+    }
+
+    return { sessions: {} };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { sessions: {} };
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * Look up the prior session ID for a step within a run.
+ *
+ * @param {{sessions: Record<string, {provider: string, sessionId: string, updatedAt: string}>}} store - Loaded store.
+ * @param {string} stepName - Step name used as the session key.
+ * @returns {string | null} Session ID or null when absent.
+ */
+export function getSessionId(store, stepName) {
+  const entry = store.sessions[stepName];
+
+  if (!entry || typeof entry.sessionId !== "string" || entry.sessionId === "") {
+    return null;
+  }
+
+  return entry.sessionId;
+}
+
+/**
+ * Persist a session ID captured from an agent result event.
+ *
+ * Writes atomically via a uuid-suffixed temp file + rename to avoid torn writes
+ * when the workflow crashes mid-save.
+ *
+ * @param {string} cwd - Workflow working directory.
+ * @param {string} runId - Workflow run identifier.
+ * @param {string} stepName - Step name used as the session key.
+ * @param {string} provider - Provider name (e.g. `opencode`, `claude-code`).
+ * @param {string} sessionId - Session identifier returned by the agent.
+ * @returns {Promise<void>} Resolves when the store is durable on disk.
+ */
+export async function saveSessionId(cwd, runId, stepName, provider, sessionId) {
+  const store = await loadSessionStore(cwd, runId);
+
+  store.sessions[stepName] = {
+    provider,
+    sessionId,
+    updatedAt: new Date().toISOString()
+  };
+
+  const storePath = getSessionStorePath(cwd, runId);
+  const storeDir = path.dirname(storePath);
+
+  await mkdir(storeDir, { recursive: true });
+
+  const tempPath = `${storePath}.${randomUUID()}.tmp`;
+  await writeFile(tempPath, `${JSON.stringify(store, null, 2)}\n`, "utf8");
+  await rename(tempPath, storePath);
+}

package/src/cli.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { getInitHelpText, runInitCommand } from "./init-project.js";
+import {
+  ConfigError,
+  DEFAULT_CONFIG,
+  ensureConfigFile,
+  getConfigHelpText,
+  getGlobalConfigPath,
+  getProjectConfigPath,
+  loadConfig,
+  parseConfigCommandArgs,
+  renderConfig,
+  renderConfigWithSources
+} from "./config.js";
+import {
+  getListHelpText,
+  getLogsHelpText,
+  getResumeHelpText,
+  getRunHelpText,
+  getSetStepHelpText,
+  getSignalHelpText,
+  runWorkflowListCommand,
+  runWorkflowLogsCommand,
+  getStatusHelpText,
+  runWorkflowCommand,
+  runWorkflowResumeCommand,
+  runWorkflowSetStepCommand,
+  runWorkflowSignalCommand,
+  runWorkflowStatusCommand
+} from "./run-workflow.js";
+
+/**
+ * Return the CLI help text for `flow`.
+ *
+ * @returns {string} Help text shown to users.
+ */
+export function getHelpText() {
+  return `flow
+
+Usage:
+  flow init [--template <name>]
+  flow config
+  flow run
+  flow resume
+  flow set-step
+  flow signal <run-id> <step-name> [--data '{}']
+  flow status
+  flow list
+  flow logs
+  flow --help
+
+Commands:
+  init     Initialize flow in the current repository or from a reusable template
+  config   Show or initialize flow configuration
+  run      Execute a workflow from YAML
+  resume   Resume a failed persisted workflow run
+  set-step Manually set which persisted workflow step to resume from
+  signal   Deliver a signal to a waiting workflow step
+  status   Show the status of a persisted workflow run
+  list     List persisted workflow runs
+  logs     Show persisted logs for a workflow run`;
+}
+
+/**
+ * Execute the `flow` command line interface.
+ *
+ * @param {string[]} argv - Process arguments excluding the Node executable.
+ * @param {(message: string) => void} [stdout=console.log] - Standard output writer.
+ * @param {(message: string) => void} [stderr=console.error] - Standard error writer.
+ * @param {object} [options={}] - Runtime overrides used by tests.
+ * @param {string} [options.cwd=process.cwd()] - Working directory override.
+ * @param {object} [options.env=process.env] - Environment override.
+ * @param {string} [options.homeDir] - Home directory override.
+ * @returns {Promise<number>} Process exit code.
+ */
+export async function runCli(argv, stdout = console.log, stderr = console.error, options = {}) {
+  const [command, ...commandArgs] = argv;
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    homeDir
+  } = options;
+
+  if (!command || command === "--help" || command === "-h") {
+    stdout(getHelpText());
+    return 0;
+  }
+
+  if (command === "config") {
+    return runConfigCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "init") {
+    return runInitCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "run") {
+    return runWorkflowCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "resume") {
+    return runWorkflowResumeCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "set-step") {
+    return runWorkflowSetStepCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "status") {
+    return runWorkflowStatusCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "list") {
+    return runWorkflowListCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "logs") {
+    return runWorkflowLogsCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  if (command === "signal") {
+    return runWorkflowSignalCommand(commandArgs, stdout, stderr, { cwd, env, homeDir });
+  }
+
+  stderr(`Unknown command: ${command}`);
+  stderr("Run 'flow --help' to see available commands.");
+  return 1;
+}
+
+/**
+ * Execute `flow config`.
+ *
+ * @param {string[]} args - CLI args after `config`.
+ * @param {(message: string) => void} stdout - Standard output writer.
+ * @param {(message: string) => void} stderr - Standard error writer.
+ * @param {object} options - Runtime overrides used by tests.
+ * @param {string} options.cwd - Working directory override.
+ * @param {object} options.env - Environment override.
+ * @param {string} [options.homeDir] - Home directory override.
+ * @returns {Promise<number>} Process exit code.
+ */
+async function runConfigCommand(args, stdout, stderr, options) {
+  try {
+    const { commandFlags, overrideFlags } = parseConfigCommandArgs(args);
+
+    if (commandFlags.help) {
+      stdout(getConfigHelpText());
+      return 0;
+    }
+
+    if (commandFlags.defaults) {
+      stdout(renderConfig(DEFAULT_CONFIG));
+      return 0;
+    }
+
+    if (commandFlags.global) {
+      const globalConfigPath = getGlobalConfigPath(options.homeDir);
+      const created = await ensureConfigFile(globalConfigPath);
+      stdout(`${created ? "Created" : "Global config already exists at"} ${globalConfigPath}`);
+      return 0;
+    }
+
+    if (commandFlags.project) {
+      const projectConfigPath = getProjectConfigPath(options.cwd);
+      const created = await ensureConfigFile(projectConfigPath);
+      stdout(`${created ? "Created" : "Project config already exists at"} ${projectConfigPath}`);
+      return 0;
+    }
+
+    const { config, sources } = await loadConfig({
+      cwd: options.cwd,
+      env: options.env,
+      flags: overrideFlags,
+      homeDir: options.homeDir
+    });
+
+    stdout(commandFlags.show ? renderConfigWithSources(config, sources) : renderConfig(config));
+    return 0;
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      stderr(`Error: ${error.message}`);
+      return 1;
+    }
+
+    throw error;
+  }
+}
+
+export {
+  getInitHelpText,
+  getListHelpText,
+  getLogsHelpText,
+  getResumeHelpText,
+  getRunHelpText,
+  getSetStepHelpText,
+  getSignalHelpText,
+  getStatusHelpText
+};
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const exitCode = await runCli(process.argv.slice(2));
+  process.exit(exitCode);
+}

package/src/config/AGENTS.md

@@ -0,0 +1,23 @@
+# src/config
+
+## Purpose
+
+Contains flow configuration loading, validation, rendering, and file initialization.
+
+## Modules
+
+- `../config.js`: config defaults, parsing, merge precedence, and `flow config` helpers
+
+## Conventions
+
+- Keep the precedence order exact: defaults, global, project, workflow, workflow-local, env, flag
+- Validate both keys and values before merging user-provided config
+- Keep YAML output stable for tests and proof artifacts
+- Prefer explicit supported-key handling over generic deep merges
+
+## Verification
+
+- Run `npm test`
+- Run `npm run coverage`
+- Run `npx eslint src/ --fix`
+- Run `npx eslint src/`