@dev-loops/core 0.1.0

package/src/bash-exit-one.mjs

@@ -0,0 +1,130 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+
+export const DEFAULT_OUTPUT_LIMIT = 4000;
+
+function requireNonEmptyString(value, fieldName) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${fieldName} must be a non-empty string`);
+  }
+
+  return value.trim();
+}
+
+export function truncateText(value, limit = DEFAULT_OUTPUT_LIMIT) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  const text = String(value);
+  if (text.length <= limit) {
+    return text;
+  }
+
+  const truncatedCount = text.length - limit;
+  return `${text.slice(0, limit)}…[truncated ${truncatedCount} chars]`;
+}
+
+export function normalizeBashExitOneRecord(record) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) {
+    throw new Error("record must be an object");
+  }
+
+  const exitCode = Number(record.exitCode);
+  if (exitCode !== 1) {
+    throw new Error(`exitCode must be 1, received ${record.exitCode}`);
+  }
+
+  const normalized = {
+    timestamp:
+      typeof record.timestamp === "string" && record.timestamp.trim().length > 0
+        ? record.timestamp.trim()
+        : new Date().toISOString(),
+    phase: requireNonEmptyString(record.phase, "phase"),
+    cwd: requireNonEmptyString(record.cwd, "cwd"),
+    command: requireNonEmptyString(record.command, "command"),
+    exitCode: 1,
+    purpose: requireNonEmptyString(record.purpose, "purpose"),
+    summary: requireNonEmptyString(record.summary, "summary"),
+  };
+
+  const stdout = truncateText(record.stdout);
+  const stderr = truncateText(record.stderr);
+  const artifactPath = truncateText(record.artifactPath, 2000);
+
+  if (stdout !== undefined && stdout.length > 0) {
+    normalized.stdout = stdout;
+  }
+
+  if (stderr !== undefined && stderr.length > 0) {
+    normalized.stderr = stderr;
+  }
+
+  if (artifactPath !== undefined && artifactPath.length > 0) {
+    normalized.artifactPath = artifactPath;
+  }
+
+  return normalized;
+}
+
+export function formatBashExitOneRecord(record) {
+  return `${JSON.stringify(normalizeBashExitOneRecord(record))}\n`;
+}
+
+export async function appendBashExitOneRecord(logPath, record) {
+  const normalized = normalizeBashExitOneRecord(record);
+  await mkdir(path.dirname(logPath), { recursive: true });
+  await appendFile(logPath, `${JSON.stringify(normalized)}\n`, "utf8");
+  return normalized;
+}
+
+export function parseCliArgs(argv) {
+  const args = [...argv];
+  let logPath;
+  let recordJson;
+
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--log") {
+      logPath = args.shift();
+      continue;
+    }
+
+    if (token === "--record") {
+      recordJson = args.shift();
+      continue;
+    }
+
+    throw new Error(`Unknown argument: ${token}`);
+  }
+
+  if (!logPath) {
+    throw new Error("Missing required --log <path> argument");
+  }
+
+  return { logPath, recordJson };
+}
+
+export async function readRecordFromStdin(stream = process.stdin) {
+  let input = "";
+
+  for await (const chunk of stream) {
+    input += chunk;
+  }
+
+  if (input.trim().length === 0) {
+    throw new Error("Expected a JSON record via --record or stdin");
+  }
+
+  return JSON.parse(input);
+}
+
+export async function runCli(argv = process.argv.slice(2), stream = process.stdin) {
+  const { logPath, recordJson } = parseCliArgs(argv);
+  const record = recordJson ? JSON.parse(recordJson) : await readRecordFromStdin(stream);
+  const normalized = await appendBashExitOneRecord(logPath, record);
+
+  process.stdout.write(
+    `${JSON.stringify({ ok: true, logPath, record: normalized })}\n`,
+  );
+}

package/src/cli/helpers.mjs

@@ -0,0 +1,22 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Shared CLI helpers for script boilerplate reduction.
+ * Extracted from scripts/_core-helpers.mjs per issue #548 Phase 2.
+ */
+
+export function buildParseError(usage) {
+  return function parseError(message) {
+    return Object.assign(new Error(message), { usage });
+  };
+}
+
+export function isDirectCliRun(importMetaUrl, argv1 = process.argv[1]) {
+  if (typeof argv1 !== "string" || argv1.length === 0) { return false; }
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(importMetaUrl));
+  } catch {
+    return false;
+  }
+}

package/src/cli/primitives.mjs

@@ -0,0 +1,70 @@
+import { spawn } from "node:child_process";
+
+/**
+ * Shared CLI primitives for arg parsing, validation, and child process execution.
+ * Extracted from scripts/_cli-primitives.mjs per issue #548 Phase 2.
+ */
+
+function toCliError(message, parseError) {
+  if (typeof parseError === "function") {
+    return parseError(message);
+  }
+  return new Error(message);
+}
+
+export function requireOptionValue(args, flag, parseError = null, { flagPattern = /^--/u } = {}) {
+  const value = args.shift();
+  if (typeof value !== "string" || value.length === 0 || flagPattern.test(value)) {
+    throw toCliError(`Missing value for ${flag}`, parseError);
+  }
+  return value;
+}
+
+export function parsePositiveInteger(value, flag, parseError = null) {
+  if (!/^\d+$/.test(value) || Number(value) === 0) {
+    throw toCliError(`${flag} must be a positive integer`, parseError);
+  }
+  return Number(value);
+}
+
+export function parseNonNegativeInteger(value, flag, parseError = null) {
+  if (!/^\d+$/.test(value)) {
+    throw toCliError(`${flag} must be a non-negative integer`, parseError);
+  }
+  return Number(value);
+}
+
+export function parsePrNumber(value, parseError = null) {
+  return parsePositiveInteger(value, "--pr", parseError);
+}
+
+export function parseIssueNumber(value, parseError = null) {
+  return parsePositiveInteger(value, "--issue", parseError);
+}
+
+export function runChild(command, args, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+    child.on("error", reject);
+    child.on("close", (code) => { resolve({ code, stdout, stderr }); });
+  });
+}
+
+export function runCommand(command, args, { cwd = process.cwd(), env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += String(chunk); });
+    child.stderr.on("data", (chunk) => { stderr += String(chunk); });
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code === 0) { resolve({ stdout, stderr }); return; }
+      reject(new Error(stderr.trim().length > 0 ? stderr.trim() : `${command} exited with code ${code}`));
+    });
+  });
+}

package/src/cli/retry-wrapper.mjs

@@ -0,0 +1,169 @@
+/**
+ * Deterministic retry wrapper for CLI usage/flag errors.
+ *
+ * When a script receives unknown flags, it emits a usage/flag error to stderr.
+ * This wrapper detects such errors, parses the usage output for valid flags,
+ * and retries once with corrected args.
+ *
+ * Only retries on usage/flag errors — NOT on network/auth/data errors.
+ *
+ * Detection contract:
+ *   A usage/flag error is stderr JSON with { ok: false, usage: "..." }
+ *   OR stderr text matching known argument-error patterns.
+ *
+ * Non-retryable: runtime errors ({ ok: false } without usage field),
+ *   network errors, auth errors, data errors, signal exits.
+ *
+ * Issue: #483
+ */
+
+const USAGE_PATTERNS = [
+  /\bUnknown argument:/i,
+  /\bMissing required option:/i,
+  /\bMissing value for\b/i,
+  /\bhas been removed/i,
+  /\bUnrecognized\b/i,
+  /\bMissing command\b/i,
+];
+
+/**
+ * Check if stderr represents a CLI usage/flag error that is retryable.
+ * @param {string|null|undefined} stderr
+ * @returns {boolean}
+ */
+export function isUsageError(stderr) {
+  if (!stderr || stderr.trim().length === 0) return false;
+
+  const trimmed = stderr.trim();
+
+  // Try JSON parse first: { ok: false, usage: "..." }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (parsed && parsed.ok === false && typeof parsed.usage === 'string' && parsed.usage.length > 0) {
+      return true;
+    }
+  } catch {
+    // Not JSON — fall through to pattern matching
+  }
+
+  return USAGE_PATTERNS.some((p) => p.test(trimmed));
+}
+
+/**
+ * Extract valid flag names from usage text.
+ * Finds all --flag-name patterns and returns them as a Set.
+ *
+ * Only matches flags that look like valid CLI option names:
+ * letters and hyphens after --, minimum 2 chars (--x is not a valid flag).
+ *
+ * @param {string} usageText
+ * @returns {Set<string>}
+ */
+export function extractValidFlags(usageText) {
+  const flags = new Set();
+  if (!usageText || usageText.length === 0) return flags;
+
+  // Match --flag-name (letters and hyphens after --)
+  const flagPattern = /--([a-z][a-z0-9-]*)/gi;
+  let match;
+  while ((match = flagPattern.exec(usageText)) !== null) {
+    flags.add(`--${match[1]}`);
+  }
+  return flags;
+}
+
+/**
+ * Extract the canonical usage text from stderr.
+ *
+ * For JSON stderr: returns the `usage` field value.
+ * For non-JSON stderr: tries to find a "Usage:" section and returns that;
+ *   if no Usage: section is found, returns null to avoid false positives.
+ *
+ * @param {string} stderr
+ * @returns {string|null}
+ */
+export function extractUsageText(stderr) {
+  if (!stderr || stderr.trim().length === 0) return null;
+
+  try {
+    const parsed = JSON.parse(stderr.trim());
+    if (parsed && typeof parsed.usage === 'string' && parsed.usage.length > 0) {
+      return parsed.usage;
+    }
+    // JSON but no usage field — not a usage error, don't return raw text
+    return null;
+  } catch {
+    // Not JSON — try to find a "Usage:" section
+  }
+
+  const trimmed = stderr.trim();
+
+  // Find "Usage:" line and take from there to end
+  const usageIdx = trimmed.search(/^Usage:/im);
+  if (usageIdx >= 0) {
+    return trimmed.slice(usageIdx);
+  }
+
+  // No usage marker — can't reliably extract
+  return null;
+}
+
+/**
+ * Filter original args to keep only recognized flags and their value args.
+ * A value arg is the token immediately following a recognized flag
+ * that does not start with '-'.
+ *
+ * @param {string[]} originalArgs
+ * @param {Set<string>} validFlags
+ * @returns {string[]}
+ */
+export function filterArgs(originalArgs, validFlags) {
+  const filtered = [];
+  for (let i = 0; i < originalArgs.length; i++) {
+    const arg = originalArgs[i];
+    if (validFlags.has(arg)) {
+      filtered.push(arg);
+      // If next arg exists and doesn't look like a flag, it's a value
+      if (i + 1 < originalArgs.length && !originalArgs[i + 1].startsWith('-')) {
+        filtered.push(originalArgs[i + 1]);
+        i++; // consume the value
+      }
+    }
+  }
+  return filtered;
+}
+
+/**
+ * Build a corrected args array from the original args and the stderr usage error.
+ * Returns null if no correction is possible or needed.
+ *
+ * Steps:
+ * 1. Extract canonical usage text from stderr.
+ * 2. Extract valid flags from usage text.
+ * 3. Filter original args to keep only recognized flags + values.
+ * 4. If filtered args differ from original, return them; otherwise return null.
+ *
+ * @param {string[]} originalArgs
+ * @param {string} stderr
+ * @returns {string[]|null} Corrected args, or null if no correction needed.
+ */
+export function buildCorrectedArgs(originalArgs, stderr) {
+  if (!originalArgs || originalArgs.length === 0) return null;
+
+  const usageText = extractUsageText(stderr);
+  if (!usageText) return null;
+
+  const validFlags = extractValidFlags(usageText);
+  if (validFlags.size === 0) return null;
+
+  const corrected = filterArgs(originalArgs, validFlags);
+  if (corrected.length === 0) return null;
+
+  // Only retry if args actually changed
+  if (corrected.length === originalArgs.length &&
+      corrected.every((v, i) => v === originalArgs[i])) {
+    return null;
+  }
+
+  return corrected;
+}

package/src/cli/subcommand-runner.mjs

@@ -0,0 +1,246 @@
+/**
+ * Shared subcommand runner for standardizing CLI script boilerplate.
+ * Extracted per issue #548 Phase 3.
+ *
+ * Replaces per-script: USAGE string, parseError, arg-parsing loop,
+ * removed-flags handling, and direct-invocation boilerplate.
+ */
+
+import { buildParseError, isDirectCliRun } from "./helpers.mjs";
+import { requireOptionValue, parsePrNumber, parseIssueNumber,
+         parsePositiveInteger, parseNonNegativeInteger } from "./primitives.mjs";
+
+/**
+ * Option descriptor for defineSubcommand.
+ *
+ * @typedef {Object} CliOption
+ * @property {string} flag       - e.g. "--repo"
+ * @property {string} [key]      - override output key name; defaults to dashed→camelCase (e.g. "--head-sha" → "headSha")
+ * @property {string} [valueName] - human-readable value name for usage (ignored for boolean flags)
+ * @property {string} [description] - help text
+ * @property {"string"|"number"|"boolean"|"pr"|"issue"|"positiveInt"|"nonNegativeInt"} [type] - default "string"
+ * @property {boolean} [required] - default false
+ * @property {*} [default]        - default value
+ * @property {string[]} [choices] - allowed values
+ * @property {string[]} [removedAliases] - flags that should be rejected with a message
+ */
+
+/** Convert a dashed flag name (e.g. "--head-sha") to camelCase (e.g. "headSha"). */
+function dashedToCamel(flag) {
+  const stem = flag.replace(/^--/, "");
+  return stem.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Return the parsed output key for an option. Respects opt.key override. */
+function optionKey(opt) {
+  if (opt.key) return opt.key;
+  return dashedToCamel(opt.flag);
+}
+
+/** Render a single option's usage fragment for the generated help text. */
+function optionUsageFragment(opt) {
+  if (opt.type === "boolean") return opt.flag;
+  const vn = opt.valueName || opt.flag.replace(/^--/, "").replace(/-/g, "_").toUpperCase();
+  return `${opt.flag} <${vn}>`;
+}
+
+/**
+ * Define a subcommand with auto-generated usage, arg parsing, and help.
+ *
+ * @param {Object} def
+ * @param {string} def.name        - subcommand name for usage
+ * @param {string} def.description - one-line description
+ * @param {string} [def.longDescription] - extended help text
+ * @param {CliOption[]} def.options - option descriptors
+ * @param {Function} def.run       - async (parsed, { args, stdout, stderr }) => exitCode
+ * @param {Object} [def.extraUsage] - extra usage lines
+ * @param {Object} [def.outputSchema] - stdout JSON schema description
+ * @returns {{ parseArgs, runAsScript, usage, parseError }}
+ */
+export function defineSubcommand(def) {
+  const {
+    name,
+    description,
+    longDescription = "",
+    options = [],
+    run,
+    extraUsage = {},
+    outputSchema = null,
+  } = def;
+
+  // Auto-build usage string
+  const requiredOpts = options.filter((o) => o.required);
+  const optionalOpts = options.filter((o) => !o.required);
+
+  const usageLines = [`Usage: dev-loops ${name}`];
+  for (const opt of requiredOpts) {
+    usageLines.push(`  ${optionUsageFragment(opt)}`);
+  }
+  if (optionalOpts.length > 0) {
+    const optStrs = optionalOpts.map((o) => optionUsageFragment(o));
+    usageLines.push(`  [${optStrs.join("] [")}]`);
+  }
+
+  if (description) usageLines.push("", description);
+  if (longDescription) usageLines.push("", longDescription);
+
+  if (requiredOpts.length > 0) {
+    usageLines.push("", "Required:");
+    for (const opt of requiredOpts) {
+      usageLines.push(`  ${optionUsageFragment(opt)}${opt.description ? `    ${opt.description}` : ""}`);
+    }
+  }
+
+  if (optionalOpts.length > 0) {
+    usageLines.push("", "Optional:");
+    for (const opt of optionalOpts) {
+      usageLines.push(`  ${optionUsageFragment(opt)}${opt.description ? `    ${opt.description}` : ""}`);
+    }
+  }
+
+  if (extraUsage.before) usageLines.splice(1, 0, ...extraUsage.before);
+  if (extraUsage.after) usageLines.push(...extraUsage.after);
+
+  if (outputSchema) {
+    usageLines.push("", "Output (stdout, JSON):", JSON.stringify(outputSchema, null, 2));
+  }
+
+  const usage = usageLines.join("\n");
+  const parseError = buildParseError(usage);
+
+  // Build removed-flags set
+  const removedFlags = new Set();
+  for (const opt of options) {
+    if (opt.removedAliases) {
+      for (const alias of opt.removedAliases) removedFlags.add(alias);
+    }
+  }
+
+  function parseValue(raw, opt) {
+    if (raw === undefined) return opt.default;
+    switch (opt.type) {
+      case "number": case "positiveInt": case "nonNegativeInt": {
+        if (opt.type === "positiveInt") return parsePositiveInteger(raw, opt.flag, parseError);
+        if (opt.type === "nonNegativeInt") return parseNonNegativeInteger(raw, opt.flag, parseError);
+        const n = Number(raw);
+        if (isNaN(n)) throw parseError(`${opt.flag} must be a number`);
+        return n;
+      }
+      case "pr": return parsePrNumber(raw, parseError);
+      case "issue": return parseIssueNumber(raw, parseError);
+      case "string":
+      default: {
+        const v = raw.trim();
+        if (opt.choices && !opt.choices.includes(v)) {
+          throw parseError(`${opt.flag} must be one of: ${opt.choices.join(", ")}`);
+        }
+        return v;
+      }
+    }
+  }
+
+  function parseArgs(argv) {
+    const args = [...argv];
+    const parsed = {};
+    // Initialize defaults for all options
+    for (const opt of options) {
+      if (opt.default !== undefined) {
+        parsed[optionKey(opt)] = opt.default;
+      }
+    }
+
+    while (args.length > 0) {
+      const token = args.shift();
+
+      if (token === "--help" || token === "-h") {
+        return { help: true };
+      }
+
+      if (removedFlags.has(token)) {
+        throw parseError(
+          `${token} has been removed. Omit the flag.`,
+        );
+      }
+
+      const opt = options.find((o) => o.flag === token);
+      if (opt) {
+        if (opt.type === "boolean") {
+          // Boolean flags are presence-only: --flag sets true, no value required.
+          parsed[optionKey(opt)] = true;
+        } else {
+          const raw = requireOptionValue(args, opt.flag, parseError);
+          parsed[optionKey(opt)] = parseValue(raw, opt);
+        }
+        continue;
+      }
+
+      throw parseError(`Unknown argument: ${token}`);
+    }
+
+    // Validate option definitions
+    for (const opt of options) {
+      if (opt.required && opt.default !== undefined) {
+        throw new Error(`Option ${opt.flag}: 'required' and 'default' conflict`);
+      }
+    }
+
+    // Check required
+    for (const opt of requiredOpts) {
+      const key = optionKey(opt);
+      if (parsed[key] === undefined) {
+        throw parseError(`Missing required option: ${opt.flag}`);
+      }
+    }
+
+    return { parsed };
+  }
+
+  async function runAsScript(scriptArgv = process.argv.slice(2)) {
+    try {
+      const result = parseArgs(scriptArgv);
+      if (result.help) {
+        process.stdout.write(`${usage}\n`);
+        process.exitCode = 0;
+        return;
+      }
+      const code = await run(result.parsed, { args: scriptArgv, usage });
+      process.exitCode = typeof code === "number" ? code : 0;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      if (error instanceof Error && typeof error.usage === "string") {
+        process.stderr.write(JSON.stringify({ ok: false, error: msg, usage: error.usage }) + "\n");
+      } else {
+        process.stderr.write(JSON.stringify({ ok: false, error: msg }) + "\n");
+      }
+      process.exitCode = 1;
+    }
+  }
+
+  return { parseArgs, runAsScript, usage, parseError };
+}
+
+/**
+ * Run a CLI function as the main entrypoint when the module is invoked directly.
+ * Handles process.exitCode and error formatting.
+ *
+ * Usage: replace `if (isDirectCliRun(import.meta.url)) { ... }` with:
+ *   if (isDirectCliRun(import.meta.url)) { runAsMain(runCli); }
+ *
+ * @param {Function} fn - async function returning exit code or void
+ * @param {Object} [opts]
+ * @param {Function} [opts.formatError] - error formatter (default: JSON.stringify)
+ */
+export function runAsMain(fn, { formatError } = {}) {
+  Promise.resolve(fn()).then(
+    (code) => { process.exitCode = typeof code === "number" ? code : 0; },
+    (error) => {
+      const msg = formatError
+        ? formatError(error)
+        : JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) });
+      process.stderr.write(`${msg}\n`);
+      process.exitCode = 1;
+    },
+  );
+}
+
+export { isDirectCliRun };