lilflow 0.1.0

package/src/config.js

@@ -0,0 +1,776 @@
+import { access, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import yaml from "js-yaml";
+
+export const DEFAULT_CONFIG = Object.freeze({
+  log: {
+    level: "info"
+  },
+  parallelism: 4,
+  timeout: {
+    default: "5m"
+  },
+  agent: Object.freeze({
+    opencode: Object.freeze({ bin: null }),
+    claude: Object.freeze({ bin: null })
+  })
+});
+
+const LOG_LEVELS = ["debug", "info", "warn", "error"];
+const CONFIG_KEYS = [
+  "log.level",
+  "parallelism",
+  "timeout.default",
+  "agent.opencode.bin",
+  "agent.claude.bin"
+];
+const CONFIG_TEMPLATE = `# Flow configuration
+# log.level controls console verbosity.
+log:
+  level: info
+
+# parallelism limits concurrent work.
+parallelism: 4
+
+timeout:
+  # timeout.default is the fallback timeout for steps.
+  default: 5m
+`;
+
+export class ConfigError extends Error {
+  /**
+   * @param {string} message - Human-readable validation or parsing error.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+/**
+ * Return the filesystem path for the global config file.
+ *
+ * @param {string} [homeDir=os.homedir()] - Home directory override.
+ * @returns {string} Absolute global config path.
+ */
+export function getGlobalConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, ".flow", "config.yaml");
+}
+
+/**
+ * Return the filesystem path for the project config file.
+ *
+ * @param {string} [cwd=process.cwd()] - Project directory override.
+ * @returns {string} Absolute project config path.
+ */
+export function getProjectConfigPath(cwd = process.cwd()) {
+  return path.join(cwd, ".flow", "config.yaml");
+}
+
+/**
+ * Return the adjacent local override path for a workflow file.
+ *
+ * @param {string} workflowPath - Absolute or relative workflow path.
+ * @returns {string} Workflow-local override path.
+ */
+export function getLocalWorkflowConfigPath(workflowPath) {
+  const extension = path.extname(workflowPath);
+
+  if (extension === "") {
+    return `${workflowPath}.local`;
+  }
+
+  return path.join(
+    path.dirname(workflowPath),
+    `${path.basename(workflowPath, extension)}.local${extension}`
+  );
+}
+
+/**
+ * Return the config template used for new files.
+ *
+ * @returns {string} Documented YAML template.
+ */
+export function getConfigTemplate() {
+  return CONFIG_TEMPLATE;
+}
+
+/**
+ * Return the config-specific help text.
+ *
+ * @returns {string} Help text shown for `flow config --help`.
+ */
+export function getConfigHelpText() {
+  return `flow config
+
+Usage:
+  flow config
+  flow config --show
+  flow config --defaults
+  flow config --global
+  flow config --project
+  flow config [--log-level=<level>] [--parallelism=<count>] [--timeout-default=<duration>]
+  flow config --help
+
+Flags:
+  --global                Create or show ~/.flow/config.yaml
+  --project               Create or show .flow/config.yaml in the current directory
+  --show                  Show the merged config with a source annotation per value
+  --defaults              Show built-in default values
+  --log-level=<level>     Override log.level for this command
+  --parallelism=<count>   Override parallelism for this command
+  --timeout-default=<dur> Override timeout.default for this command
+  --help                  Show this help text
+
+Supported keys:
+  log.level        debug | info | warn | error
+  parallelism      integer from 1 to 16
+  timeout.default  duration like 30s, 5m, 1h
+
+Examples:
+  flow config --global
+  FLOW_LOG_LEVEL=debug flow config
+  flow config --show --log-level=error`;
+}
+
+/**
+ * Parse config overrides and command flags from CLI args.
+ *
+ * @param {string[]} args - CLI args after `config`.
+ * @returns {{commandFlags: object, overrideFlags: object}} Parsed flags.
+ */
+export function parseConfigCommandArgs(args) {
+  const commandFlags = {
+    defaults: false,
+    global: false,
+    help: false,
+    project: false,
+    show: false
+  };
+  const overrideFlags = {};
+
+  for (const arg of args) {
+    if (arg === "--help" || arg === "-h") {
+      commandFlags.help = true;
+      continue;
+    }
+
+    if (arg === "--show") {
+      commandFlags.show = true;
+      continue;
+    }
+
+    if (arg === "--defaults") {
+      commandFlags.defaults = true;
+      continue;
+    }
+
+    if (arg === "--global") {
+      commandFlags.global = true;
+      continue;
+    }
+
+    if (arg === "--project") {
+      commandFlags.project = true;
+      continue;
+    }
+
+    if (arg.startsWith("--log-level=")) {
+      overrideFlags["log.level"] = arg.slice("--log-level=".length);
+      continue;
+    }
+
+    if (arg.startsWith("--parallelism=")) {
+      const value = Number.parseInt(arg.slice("--parallelism=".length), 10);
+      overrideFlags.parallelism = value;
+      continue;
+    }
+
+    if (arg.startsWith("--timeout-default=")) {
+      overrideFlags["timeout.default"] = arg.slice("--timeout-default=".length);
+      continue;
+    }
+
+    throw new ConfigError(`Unknown config flag: ${arg}`);
+  }
+
+  return { commandFlags, overrideFlags };
+}
+
+/**
+ * Parse YAML configuration content into a plain object.
+ *
+ * @param {string} content - YAML file content.
+ * @param {string} sourceLabel - Source name used in error messages.
+ * @returns {object} Parsed config object.
+ */
+export function parseConfigContent(content, sourceLabel) {
+  try {
+    const parsed = yaml.load(content);
+
+    if (parsed == null) {
+      return {};
+    }
+
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new ConfigError(`${sourceLabel} must contain a YAML object.`);
+    }
+
+    return parsed;
+  } catch (error) {
+    if (error instanceof ConfigError) {
+      throw error;
+    }
+
+    throw new ConfigError(`Failed to parse ${sourceLabel}: ${error.message}`);
+  }
+}
+
+/**
+ * Ensure a config file exists, preserving any current content.
+ *
+ * @param {string} filePath - Target config path.
+ * @returns {Promise<boolean>} True when the file was created.
+ */
+export async function ensureConfigFile(filePath) {
+  const directoryPath = path.dirname(filePath);
+  await mkdir(directoryPath, { recursive: true });
+
+  try {
+    await access(filePath, constants.F_OK);
+    return false;
+  } catch {
+    const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+    await writeFile(temporaryPath, CONFIG_TEMPLATE, "utf8");
+    await rename(temporaryPath, filePath);
+    return true;
+  }
+}
+
+/**
+ * Load, merge, and validate flow configuration.
+ *
+ * @param {object} [options={}] - Load options.
+ * @param {string} [options.cwd=process.cwd()] - Working directory override.
+ * @param {object} [options.env=process.env] - Environment override.
+ * @param {object} [options.flags={}] - CLI flag overrides.
+ * @param {string} [options.homeDir=os.homedir()] - Home directory override.
+ * @param {string} [options.workflowPath] - Workflow file whose local config should participate in merging.
+ * @returns {Promise<{config: object, sources: object}>} Merged config and sources.
+ */
+export async function loadConfig(options = {}) {
+  const {
+    cwd = process.cwd(),
+    env = process.env,
+    flags = {},
+    homeDir = os.homedir(),
+    workflowPath = path.join(cwd, "workflow.yaml")
+  } = options;
+
+  const config = cloneConfig(DEFAULT_CONFIG);
+  const sources = createDefaultSources();
+
+  const globalFilePath = getGlobalConfigPath(homeDir);
+  const projectFilePath = getProjectConfigPath(cwd);
+
+  const globalConfig = await readConfigFile(globalFilePath, "global config");
+  validateConfigFragment(globalConfig);
+  applyConfigLayer(config, sources, globalConfig, "global");
+
+  const projectConfig = await readConfigFile(projectFilePath, "project config");
+  validateConfigFragment(projectConfig);
+  applyConfigLayer(config, sources, projectConfig, "project");
+
+  const workflowConfig = await readWorkflowConfigFile(workflowPath, "workflow config");
+  validateConfigFragment(workflowConfig);
+  applyConfigLayer(config, sources, workflowConfig, "workflow");
+
+  const workflowLocalConfig = await readWorkflowConfigFile(
+    getLocalWorkflowConfigPath(workflowPath),
+    "workflow local config",
+    true
+  );
+  validateConfigFragment(workflowLocalConfig);
+  applyConfigLayer(config, sources, workflowLocalConfig, "workflow-local");
+
+  const envConfig = readEnvConfig(env);
+  validateConfigFragment(envConfig);
+  applyConfigLayer(config, sources, envConfig, "env");
+
+  const flagConfig = readFlagConfig(flags);
+  validateConfigFragment(flagConfig);
+  applyConfigLayer(config, sources, flagConfig, "flag");
+
+  validateResolvedConfig(config);
+
+  return { config, sources };
+}
+
+/**
+ * Render config as YAML.
+ *
+ * @param {object} config - Config to serialize.
+ * @returns {string} YAML output.
+ */
+export function renderConfig(config) {
+  return yaml.dump(config, {
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false
+  }).trimEnd();
+}
+
+/**
+ * Render config with per-key source annotations.
+ *
+ * @param {object} config - Merged config values.
+ * @param {object} sources - Per-key source labels.
+ * @returns {string} YAML-like output with comments.
+ */
+export function renderConfigWithSources(config, sources) {
+  return [
+    "log:",
+    `  level: ${config.log.level} # source: ${sources["log.level"]}`,
+    `parallelism: ${config.parallelism} # source: ${sources.parallelism}`,
+    "timeout:",
+    `  default: ${config.timeout.default} # source: ${sources["timeout.default"]}`,
+    "agent:",
+    "  opencode:",
+    `    bin: ${formatConfigValue(config.agent.opencode.bin)} # source: ${sources["agent.opencode.bin"]}`,
+    "  claude:",
+    `    bin: ${formatConfigValue(config.agent.claude.bin)} # source: ${sources["agent.claude.bin"]}`
+  ].join("\n");
+}
+
+/**
+ * @param {unknown} value - Config value to format for `--show` output.
+ * @returns {string} Display form ("null" for null/undefined).
+ */
+function formatConfigValue(value) {
+  if (value === null || value === undefined) {
+    return "null";
+  }
+
+  return String(value);
+}
+
+/**
+ * Validate a config fragment or resolved config object.
+ *
+ * @param {object} config - Config value to validate.
+ */
+export function validateConfig(config) {
+  validateConfigFragment(config);
+}
+
+/**
+ * @returns {object} Fresh copy of the default config.
+ */
+function cloneConfig() {
+  return {
+    log: {
+      level: DEFAULT_CONFIG.log.level
+    },
+    parallelism: DEFAULT_CONFIG.parallelism,
+    timeout: {
+      default: DEFAULT_CONFIG.timeout.default
+    },
+    agent: {
+      opencode: { bin: DEFAULT_CONFIG.agent.opencode.bin },
+      claude: { bin: DEFAULT_CONFIG.agent.claude.bin }
+    }
+  };
+}
+
+/**
+ * @returns {object} Default source map.
+ */
+function createDefaultSources() {
+  return {
+    "log.level": "default",
+    parallelism: "default",
+    "timeout.default": "default",
+    "agent.opencode.bin": "default",
+    "agent.claude.bin": "default"
+  };
+}
+
+/**
+ * @param {string} filePath - Path to inspect.
+ * @param {string} sourceLabel - Error label.
+ * @returns {Promise<object>} Parsed config or empty object if missing.
+ */
+async function readConfigFile(filePath, sourceLabel) {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return parseConfigContent(content, sourceLabel);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {string} filePath - Workflow or workflow-local config path.
+ * @param {string} sourceLabel - Error label.
+ * @param {boolean} [allowBareConfigFragment=false] - Whether the full file can be treated as a config fragment.
+ * @returns {Promise<object>} Extracted workflow-scoped config fragment.
+ */
+async function readWorkflowConfigFile(filePath, sourceLabel, allowBareConfigFragment = false) {
+  try {
+    const content = await readFile(filePath, "utf8");
+    return parseWorkflowConfigContent(content, sourceLabel, allowBareConfigFragment);
+  } catch (error) {
+    if (error && error.code === "ENOENT") {
+      return {};
+    }
+
+    throw error;
+  }
+}
+
+/**
+ * @param {string} content - Workflow YAML content.
+ * @param {string} sourceLabel - Error label.
+ * @param {boolean} [allowBareConfigFragment=false] - Whether the file can be parsed directly as a config fragment.
+ * @returns {object} Extracted workflow-scoped config.
+ */
+function parseWorkflowConfigContent(content, sourceLabel, allowBareConfigFragment = false) {
+  const parsed = parseConfigContent(content, sourceLabel);
+  return extractWorkflowConfigFragment(parsed, sourceLabel, allowBareConfigFragment);
+}
+
+/**
+ * @param {object} parsed - Parsed workflow document.
+ * @param {string} sourceLabel - Error label.
+ * @param {boolean} allowBareConfigFragment - Whether the full document is a config fragment.
+ * @returns {object} Extracted workflow config fragment.
+ */
+function extractWorkflowConfigFragment(parsed, sourceLabel, allowBareConfigFragment) {
+  if (Object.hasOwn(parsed, "config")) {
+    if (parsed.config == null || typeof parsed.config !== "object" || Array.isArray(parsed.config)) {
+      throw new ConfigError(`${sourceLabel} config must be a YAML object.`);
+    }
+
+    return parsed.config;
+  }
+
+  if (allowBareConfigFragment) {
+    return parsed;
+  }
+
+  return pickKnownConfigKeys(parsed);
+}
+
+/**
+ * @param {object} value - Parsed workflow document.
+ * @returns {object} Top-level supported config keys copied from the workflow document.
+ */
+function pickKnownConfigKeys(value) {
+  const config = {};
+
+  if (value.log !== undefined) {
+    config.log = value.log;
+  }
+
+  if (value.parallelism !== undefined) {
+    config.parallelism = value.parallelism;
+  }
+
+  if (value.timeout !== undefined) {
+    config.timeout = value.timeout;
+  }
+
+  if (value.agent !== undefined) {
+    config.agent = value.agent;
+  }
+
+  return config;
+}
+
+/**
+ * @param {object} env - Process environment.
+ * @returns {object} Partial config from env vars.
+ */
+function readEnvConfig(env) {
+  const config = {};
+
+  if (env.FLOW_LOG_LEVEL !== undefined) {
+    config.log = {
+      level: env.FLOW_LOG_LEVEL
+    };
+  }
+
+  if (env.FLOW_PARALLELISM !== undefined) {
+    config.parallelism = Number.parseInt(env.FLOW_PARALLELISM, 10);
+  }
+
+  if (env.FLOW_TIMEOUT_DEFAULT !== undefined) {
+    config.timeout = {
+      default: env.FLOW_TIMEOUT_DEFAULT
+    };
+  }
+
+  if (env.FLOW_AGENT_OPENCODE_BIN !== undefined || env.FLOW_AGENT_CLAUDE_BIN !== undefined) {
+    config.agent = {};
+
+    if (env.FLOW_AGENT_OPENCODE_BIN !== undefined) {
+      config.agent.opencode = { bin: env.FLOW_AGENT_OPENCODE_BIN };
+    }
+
+    if (env.FLOW_AGENT_CLAUDE_BIN !== undefined) {
+      config.agent.claude = { bin: env.FLOW_AGENT_CLAUDE_BIN };
+    }
+  }
+
+  return config;
+}
+
+/**
+ * @param {object} flags - Dot-path and flat flag overrides.
+ * @returns {object} Partial config from CLI flags.
+ */
+function readFlagConfig(flags) {
+  const config = {};
+
+  if (Object.hasOwn(flags, "log.level")) {
+    config.log = {
+      level: flags["log.level"]
+    };
+  }
+
+  if (Object.hasOwn(flags, "parallelism")) {
+    config.parallelism = flags.parallelism;
+  }
+
+  if (Object.hasOwn(flags, "timeout.default")) {
+    config.timeout = {
+      default: flags["timeout.default"]
+    };
+  }
+
+  if (Object.hasOwn(flags, "agent.opencode.bin") || Object.hasOwn(flags, "agent.claude.bin")) {
+    config.agent = {};
+
+    if (Object.hasOwn(flags, "agent.opencode.bin")) {
+      config.agent.opencode = { bin: flags["agent.opencode.bin"] };
+    }
+
+    if (Object.hasOwn(flags, "agent.claude.bin")) {
+      config.agent.claude = { bin: flags["agent.claude.bin"] };
+    }
+  }
+
+  return config;
+}
+
+/**
+ * @param {object} target - Current merged config.
+ * @param {object} sources - Current source map.
+ * @param {object} layer - Partial config to merge.
+ * @param {string} sourceName - Label for changed keys.
+ */
+function applyConfigLayer(target, sources, layer, sourceName) {
+  if (layer.log && Object.hasOwn(layer.log, "level")) {
+    target.log.level = layer.log.level;
+    sources["log.level"] = sourceName;
+  }
+
+  if (Object.hasOwn(layer, "parallelism")) {
+    target.parallelism = layer.parallelism;
+    sources.parallelism = sourceName;
+  }
+
+  if (layer.timeout && Object.hasOwn(layer.timeout, "default")) {
+    target.timeout.default = layer.timeout.default;
+    sources["timeout.default"] = sourceName;
+  }
+
+  if (layer.agent) {
+    if (layer.agent.opencode && Object.hasOwn(layer.agent.opencode, "bin")) {
+      target.agent.opencode.bin = layer.agent.opencode.bin;
+      sources["agent.opencode.bin"] = sourceName;
+    }
+
+    if (layer.agent.claude && Object.hasOwn(layer.agent.claude, "bin")) {
+      target.agent.claude.bin = layer.agent.claude.bin;
+      sources["agent.claude.bin"] = sourceName;
+    }
+  }
+}
+
+/**
+ * @param {object} config - Partial config to validate.
+ */
+function validateConfigFragment(config) {
+  validateKnownKeys(config);
+
+  if (config.log && Object.hasOwn(config.log, "level")) {
+    validateLogLevel(config.log.level, "log.level");
+  }
+
+  if (Object.hasOwn(config, "parallelism")) {
+    validateParallelism(config.parallelism, "parallelism");
+  }
+
+  if (config.timeout && Object.hasOwn(config.timeout, "default")) {
+    validateDuration(config.timeout.default, "timeout.default");
+  }
+
+  if (config.agent) {
+    if (config.agent.opencode && Object.hasOwn(config.agent.opencode, "bin")) {
+      validateAgentBin(config.agent.opencode.bin, "agent.opencode.bin");
+    }
+
+    if (config.agent.claude && Object.hasOwn(config.agent.claude, "bin")) {
+      validateAgentBin(config.agent.claude.bin, "agent.claude.bin");
+    }
+  }
+}
+
+/**
+ * @param {object} config - Resolved config.
+ */
+function validateResolvedConfig(config) {
+  validateConfigFragment(config);
+}
+
+/**
+ * @param {object} value - Partial config value.
+ */
+function validateKnownKeys(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    throw new ConfigError("Config must be a YAML object.");
+  }
+
+  for (const key of Object.keys(value)) {
+    if (key === "log") {
+      validateKnownNestedKeys(value.log, "log", ["level"]);
+      continue;
+    }
+
+    if (key === "timeout") {
+      validateKnownNestedKeys(value.timeout, "timeout", ["default"]);
+      continue;
+    }
+
+    if (key === "parallelism") {
+      continue;
+    }
+
+    if (key === "agent") {
+      validateAgentSection(value.agent);
+      continue;
+    }
+
+    throw createUnknownKeyError(key);
+  }
+}
+
+/**
+ * @param {object} agent - Candidate agent section.
+ */
+function validateAgentSection(agent) {
+  if (agent == null || typeof agent !== "object" || Array.isArray(agent)) {
+    throw new ConfigError("agent must be a YAML object.");
+  }
+
+  for (const key of Object.keys(agent)) {
+    if (key === "opencode") {
+      validateKnownNestedKeys(agent.opencode, "agent.opencode", ["bin"]);
+      continue;
+    }
+
+    if (key === "claude") {
+      validateKnownNestedKeys(agent.claude, "agent.claude", ["bin"]);
+      continue;
+    }
+
+    throw createUnknownKeyError(`agent.${key}`);
+  }
+}
+
+/**
+ * @param {object} value - Nested config object.
+ * @param {string} parentKey - Prefix for errors.
+ * @param {string[]} validKeys - Allowed nested keys.
+ */
+function validateKnownNestedKeys(value, parentKey, validKeys) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    throw new ConfigError(`${parentKey} must be a YAML object.`);
+  }
+
+  for (const key of Object.keys(value)) {
+    if (!validKeys.includes(key)) {
+      throw createUnknownKeyError(`${parentKey}.${key}`);
+    }
+  }
+}
+
+/**
+ * @param {string} level - Candidate log level.
+ * @param {string} key - Config key name.
+ */
+function validateLogLevel(level, key) {
+  if (typeof level !== "string" || !LOG_LEVELS.includes(level)) {
+    throw new ConfigError(
+      `Invalid value for ${key}: ${String(level)}. Valid options: ${LOG_LEVELS.join(", ")}. Run 'flow config --help' for guidance.`
+    );
+  }
+}
+
+/**
+ * @param {number} parallelism - Candidate parallelism.
+ * @param {string} key - Config key name.
+ */
+function validateParallelism(parallelism, key) {
+  if (!Number.isInteger(parallelism) || parallelism < 1 || parallelism > 16) {
+    throw new ConfigError(
+      `Invalid value for ${key}: ${String(parallelism)}. Valid range: 1-16. Run 'flow config --help' for guidance.`
+    );
+  }
+}
+
+/**
+ * @param {string} duration - Candidate duration string.
+ * @param {string} key - Config key name.
+ */
+function validateDuration(duration, key) {
+  if (typeof duration !== "string" || !/^\d+(ms|s|m|h)$/.test(duration)) {
+    throw new ConfigError(
+      `Invalid value for ${key}: ${String(duration)}. Valid format: <number><ms|s|m|h>. Run 'flow config --help' for guidance.`
+    );
+  }
+}
+
+/**
+ * @param {unknown} value - Candidate binary path override.
+ * @param {string} key - Config key name.
+ */
+function validateAgentBin(value, key) {
+  if (value === null) {
+    return;
+  }
+
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ConfigError(
+      `Invalid value for ${key}: ${String(value)}. Must be a non-empty string or null. Run 'flow config --help' for guidance.`
+    );
+  }
+}
+
+/**
+ * @param {string} key - Unknown key path.
+ * @returns {ConfigError} Error describing allowed keys.
+ */
+function createUnknownKeyError(key) {
+  return new ConfigError(
+    `Invalid configuration key: ${key}. Supported keys: ${CONFIG_KEYS.join(", ")}. Run 'flow config --help' for guidance.`
+  );
+}