agileflow 3.4.3 → 4.0.0-alpha.10

package/src/cli/wizard/launch-cli-picker.js

@@ -0,0 +1,129 @@
+/**
+ * AI CLI picker for `agileflow launch setup`.
+ *
+ * Two-step flow:
+ *   1. multiselect — which detected CLIs to include in the fallback order
+ *   2. select       — which of those is the preferred / default
+ *
+ * Only CLIs actually present on PATH are offered. If zero are detected
+ * the picker still surfaces the known set so the user can configure
+ * AgileFlow before they install the underlying CLI (with a warning).
+ */
+const prompts = require("@clack/prompts");
+const { questionMessage } = require("../../lib/brand.js");
+const {
+  KNOWN_CLIS,
+  availableClis,
+} = require("../../runtime/launch/detect-clis.js");
+
+/**
+ * Pure helper extracted for unit testing: decide what to offer in the
+ * multiselect given a list of detected descriptors and the user's current
+ * fallbackOrder.
+ *
+ * @param {import('../../runtime/launch/detect-clis.js').CliDescriptor[]} detected
+ * @param {string[]} currentFallback
+ * @returns {{
+ *   choices: import('../../runtime/launch/detect-clis.js').CliDescriptor[],
+ *   initial: string[],
+ *   noneDetected: boolean,
+ * }}
+ */
+function buildCliChoices(detected, currentFallback) {
+  const noneDetected = detected.length === 0;
+  const choices = noneDetected ? KNOWN_CLIS : detected;
+  const choiceIds = new Set(choices.map((c) => c.id));
+  const initial = (currentFallback || []).filter((id) => choiceIds.has(id));
+  return { choices, initial, noneDetected };
+}
+
+/**
+ * Pure helper: pick the default for the "preferred CLI" select. Prefers
+ * the user's existing preference if it's still in the selected set,
+ * otherwise the first selected id.
+ *
+ * @param {string[]} selected
+ * @param {string} currentPreferred
+ * @returns {string}
+ */
+function pickInitialPreferred(selected, currentPreferred) {
+  if (selected.includes(currentPreferred)) return currentPreferred;
+  return selected[0];
+}
+
+/**
+ * Run the picker.
+ *
+ * @param {{
+ *   cli: { preferred: string, fallbackOrder: string[] },
+ * }} currentPrefs
+ * @param {(name: string) => boolean} [exists] - injectable for tests; defaults to PATH probe
+ * @returns {Promise<{ preferred: string, fallbackOrder: string[] }>}
+ */
+async function pickCli(currentPrefs, exists) {
+  const detected = availableClis(exists);
+  const { choices, initial, noneDetected } = buildCliChoices(
+    detected,
+    currentPrefs.cli.fallbackOrder,
+  );
+
+  if (noneDetected) {
+    prompts.log.warn(
+      "No supported AI CLIs detected on PATH (claude, codex, cursor-agent, aider). " +
+        "You can still pick which CLIs `agileflow launch` should target — install them later.",
+    );
+  }
+
+  const selectedRaw = await prompts.multiselect({
+    message: questionMessage(
+      "Which AI CLIs should `agileflow launch` know about?",
+      "Order is preserved as fallback order if your preferred CLI is missing.",
+    ),
+    options: choices.map((c) => ({
+      value: c.id,
+      label: c.label,
+      hint: c.hint,
+    })),
+    initialValues: initial.length ? initial : choices.map((c) => c.id),
+    required: true,
+  });
+
+  if (prompts.isCancel(selectedRaw)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const selected = /** @type {string[]} */ (selectedRaw);
+
+  const preferredRaw = await prompts.select({
+    message: questionMessage(
+      "Which CLI should `agileflow launch` use by default?",
+    ),
+    options: selected.map((id) => {
+      const desc = choices.find((c) => c.id === id);
+      return {
+        value: id,
+        label: desc ? desc.label : id,
+        hint: desc && desc.hint,
+      };
+    }),
+    initialValue: pickInitialPreferred(selected, currentPrefs.cli.preferred),
+  });
+
+  if (prompts.isCancel(preferredRaw)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const preferred = /** @type {string} */ (preferredRaw);
+
+  // Fallback order = preferred first, then the rest in user's multiselect order.
+  const fallbackOrder = [
+    preferred,
+    ...selected.filter((id) => id !== preferred),
+  ];
+
+  return { preferred, fallbackOrder };
+}
+
+module.exports = { pickCli, buildCliChoices, pickInitialPreferred };

package/src/cli/wizard/launch-tmux-picker.js

@@ -0,0 +1,133 @@
+/**
+ * tmux preferences picker for `agileflow launch setup`.
+ *
+ * Asks:
+ *   1. tmux on/off (confirm)
+ *   2. if on: status bar position (top/bottom)
+ *   3. if on: keybind preset (default/minimal/none)
+ *
+ * Left/right status positions are NOT offered in slice 1 — tmux doesn't
+ * have a native left/right status; faking it requires pane layout
+ * hackery, which is a slice 2+ concern.
+ *
+ * Returned shape is exactly the `tmux` + `keybinds` blocks of LaunchPrefs.
+ */
+const prompts = require("@clack/prompts");
+const { questionMessage } = require("../../lib/brand.js");
+const {
+  STATUS_POSITIONS,
+  KEYBIND_PRESETS,
+} = require("../../runtime/launch/defaults.js");
+
+/**
+ * Pure helper: build the status-position select options. Extracted for
+ * unit testing — the labels need to stay aligned with STATUS_POSITIONS.
+ *
+ * @param {string} current
+ * @returns {{ options: { value: string, label: string }[], initialValue: string }}
+ */
+function buildStatusOptions(current) {
+  const options = STATUS_POSITIONS.map((id) => ({
+    value: id,
+    label: id === "top" ? "Top of terminal" : "Bottom of terminal",
+  }));
+  const initialValue = STATUS_POSITIONS.includes(current) ? current : "bottom";
+  return { options, initialValue };
+}
+
+/**
+ * Pure helper: keybind preset options.
+ *
+ * @param {string} current
+ * @returns {{ options: { value: string, label: string, hint?: string }[], initialValue: string }}
+ */
+function buildKeybindOptions(current) {
+  const options = [
+    {
+      value: "default",
+      label: "Default",
+      hint: "Worktree (Alt+N), same-dir (Alt+S), freeze recovery (Alt+k/K/R), detach (Alt+q)",
+    },
+    {
+      value: "minimal",
+      label: "Minimal",
+      hint: "Only detach (Alt+q). Lets your existing tmux config shine.",
+    },
+    {
+      value: "none",
+      label: "None",
+      hint: "No keybinds installed. You wire your own.",
+    },
+  ];
+  const initialValue = KEYBIND_PRESETS.includes(current) ? current : "default";
+  return { options, initialValue };
+}
+
+/**
+ * @param {{ tmux: { enabled: boolean, statusPosition: string }, keybinds: { preset: string } }} currentPrefs
+ * @returns {Promise<{ tmux: { enabled: boolean, statusPosition: 'top' | 'bottom' }, keybinds: { preset: string } }>}
+ */
+async function pickTmux(currentPrefs) {
+  const enabledRaw = await prompts.confirm({
+    message: questionMessage(
+      "Run sessions inside tmux?",
+      "tmux gives you persistent sessions, parallel panes, and freeze recovery. " +
+        "Disable if you're on Windows or prefer plain shell.",
+    ),
+    initialValue:
+      typeof currentPrefs.tmux.enabled === "boolean"
+        ? currentPrefs.tmux.enabled
+        : true,
+  });
+
+  if (prompts.isCancel(enabledRaw)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const enabled = /** @type {boolean} */ (enabledRaw);
+
+  if (!enabled) {
+    return {
+      tmux: {
+        enabled: false,
+        statusPosition: /** @type {'bottom'} */ ("bottom"),
+      },
+      keybinds: { preset: "none" },
+    };
+  }
+
+  const statusOpts = buildStatusOptions(currentPrefs.tmux.statusPosition);
+  const statusRaw = await prompts.select({
+    message: questionMessage("Where should the tmux status bar live?"),
+    options: statusOpts.options,
+    initialValue: statusOpts.initialValue,
+  });
+
+  if (prompts.isCancel(statusRaw)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const keybindOpts = buildKeybindOptions(currentPrefs.keybinds.preset);
+  const presetRaw = await prompts.select({
+    message: questionMessage("Which keybind preset?"),
+    options: keybindOpts.options,
+    initialValue: keybindOpts.initialValue,
+  });
+
+  if (prompts.isCancel(presetRaw)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  return {
+    tmux: {
+      enabled: true,
+      statusPosition: /** @type {'top' | 'bottom'} */ (statusRaw),
+    },
+    keybinds: { preset: /** @type {string} */ (presetRaw) },
+  };
+}
+
+module.exports = { pickTmux, buildStatusOptions, buildKeybindOptions };

package/src/cli/wizard/learnings-picker.js

@@ -0,0 +1,40 @@
+/**
+ * Learnings picker — single confirm prompt for the global on/off toggle.
+ *
+ * When enabled:
+ *   - install-time scaffolds `_learnings/<file>.yaml` for every skill
+ *     that opts in via `learns.enabled: true` in its frontmatter
+ *   - the SessionStart context-loader injects a one-line hint telling
+ *     Claude to call `agileflow learn append …` on user corrections
+ *
+ * When disabled, neither happens. The `agileflow learn` CLI still works
+ * for users who want to manage signals manually.
+ */
+const prompts = require("@clack/prompts");
+const { questionMessage } = require("../../lib/brand.js");
+
+/**
+ * @param {{ enabled?: boolean }} [current]
+ * @returns {Promise<{ enabled: boolean }>}
+ */
+async function pickLearnings(current) {
+  const initialValue =
+    current && typeof current.enabled === "boolean" ? current.enabled : true;
+
+  const choice = await prompts.confirm({
+    message: questionMessage(
+      "Enable skill learnings?",
+      "Skills can remember your corrections for next time.",
+    ),
+    initialValue,
+  });
+
+  if (prompts.isCancel(choice)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  return { enabled: Boolean(choice) };
+}
+
+module.exports = { pickLearnings };

package/src/cli/wizard/plugin-picker.js

@@ -0,0 +1,137 @@
+/**
+ * Plugin picker — Clack multiselect driven by the plugin registry.
+ *
+ * Exports a pure `buildPluginsMap()` helper used by both the interactive
+ * wizard and the non-interactive `--yes` path. The helper:
+ *   - forces cannotDisable plugins (core) to enabled
+ *   - marks the user-picked opt-ins as enabled
+ *   - marks the rest of discovered opt-ins as disabled
+ *   - PRESERVES any custom (non-discovered) plugin entries from the
+ *     existing config, so wizard reruns don't silently drop user edits
+ *
+ * Cancellation (Ctrl+C / Esc) exits with code 1 (not 0) so CI can tell
+ * the difference between success and user abort.
+ */
+const prompts = require("@clack/prompts");
+const { discoverPlugins } = require("../../runtime/plugins/registry.js");
+const { questionMessage } = require("../../lib/brand.js");
+
+/**
+ * @param {Array<{id:string, cannotDisable?:boolean}>} discovered
+ * @param {Set<string>} selectedOptionalIds
+ * @param {Record<string, {enabled:boolean, settings?:any}>} [existingPluginsMap]
+ * @returns {Record<string, { enabled: boolean, settings?: any }>}
+ */
+function buildPluginsMap(
+  discovered,
+  selectedOptionalIds,
+  existingPluginsMap = {},
+) {
+  /** @type {Record<string, { enabled: boolean, settings?: any }>} */
+  const result = {};
+  for (const p of discovered) {
+    /** @type {{ enabled: boolean, settings?: any }} */
+    const entry = {
+      enabled: Boolean(p.cannotDisable) || selectedOptionalIds.has(p.id),
+    };
+    // Preserve `settings` sub-object across wizard reruns: enable/disable
+    // is recomputed each time from the user's picker choices, but any
+    // per-plugin settings (e.g. seo.settings.crawlDepth) are keyed by
+    // plugin id and should survive untouched.
+    const existing = (existingPluginsMap || {})[p.id];
+    if (
+      existing &&
+      typeof existing === "object" &&
+      !Array.isArray(existing) &&
+      existing.settings
+    ) {
+      entry.settings = existing.settings;
+    }
+    result[p.id] = entry;
+  }
+  // Preserve unknown (custom / user-added) plugin entries from existing config.
+  // Arrays are rejected — they pass `typeof === 'object'` but would break any
+  // downstream code that reads `entry.enabled` as a property.
+  for (const [id, entry] of Object.entries(existingPluginsMap || {})) {
+    if (
+      !(id in result) &&
+      entry &&
+      typeof entry === "object" &&
+      !Array.isArray(entry)
+    ) {
+      result[id] = entry;
+    }
+  }
+  return result;
+}
+
+/**
+ * Keep plugin rows compact. AgileFlow exposes these as skill packs in
+ * the wizard, even when the plugin carries legacy command/agent source
+ * files internally for IDE compatibility.
+ *
+ * @param {import('../../runtime/plugins/registry.js').PluginManifest} p
+ * @returns {string}
+ */
+function pluginHint(p) {
+  return p.description || "Skill pack";
+}
+
+/**
+ * @param {import('../../runtime/config/defaults.js').AgileflowConfig} currentConfig
+ * @returns {Promise<Record<string, { enabled: boolean }>>}
+ */
+async function pickPlugins(currentConfig) {
+  const all = discoverPlugins();
+  const required = all.filter((p) => p.cannotDisable);
+  const optional = all.filter((p) => !p.cannotDisable);
+
+  if (required.length) {
+    prompts.log.info(
+      `Always on: ${required.map((p) => `${p.name} (${p.id})`).join(", ")}`,
+    );
+  }
+
+  const initialValues = optional
+    .filter((p) => {
+      const existing = (currentConfig.plugins || {})[p.id];
+      if (existing && typeof existing.enabled === "boolean")
+        return existing.enabled;
+      return Boolean(p.enabledByDefault);
+    })
+    .map((p) => p.id);
+
+  const SELECT_ALL = "__select_all__";
+
+  const picked = await prompts.multiselect({
+    message: questionMessage("Choose optional skill packs:"),
+    options: [
+      {
+        value: SELECT_ALL,
+        label: "Enable all",
+        hint: "Turn on every skill pack at once.",
+      },
+      ...optional.map((p) => ({
+        value: p.id,
+        label: p.name,
+        hint: pluginHint(p),
+      })),
+    ],
+    initialValues,
+    required: false,
+  });
+
+  if (prompts.isCancel(picked)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  const pickedSet = new Set(/** @type {string[]} */ (picked));
+  const selectedOptionalIds = pickedSet.has(SELECT_ALL)
+    ? new Set(optional.map((p) => p.id))
+    : new Set([...pickedSet].filter((id) => id !== SELECT_ALL));
+
+  return buildPluginsMap(all, selectedOptionalIds, currentConfig.plugins || {});
+}
+
+module.exports = { pickPlugins, buildPluginsMap, pluginHint };

package/src/lib/brand.js

@@ -0,0 +1,116 @@
+/**
+ * Brand styling helpers for the CLI wizard.
+ *
+ * BRAND_COLOR (#e8683a, burnt orange) is AgileFlow's identity color —
+ * used for the logo banner and option labels in setup prompts so users
+ * can visually parse "label vs. description" without squinting.
+ */
+const chalk = require("chalk");
+
+const BRAND_COLOR = "#e8683a";
+const brand = chalk.hex(BRAND_COLOR);
+
+// Recolor Clack's frame symbols to the brand color. Clack reads
+// `picocolors.cyan` (left-side bar │, corners └, active diamond ◆) and
+// `picocolors.green` (submit diamond ◇, success bullet) at render time,
+// so replacing those two functions on the picocolors module is enough
+// to retheme the entire wizard without forking @clack/prompts.
+//
+// We leave red (error), yellow (warn), gray (dim), and blue (info)
+// alone — those convey state and shouldn't all collapse into brand
+// orange. Text content stays default white; only the structural symbols
+// change.
+let themed = false;
+function applyClackTheme() {
+  if (themed) return;
+  themed = true;
+  try {
+    const pc = require("picocolors");
+    const wrap = (s) => `\x1b[38;2;232;104;58m${s}\x1b[39m`;
+    pc.cyan = wrap;
+    pc.green = wrap;
+
+    // Make `dim` ALSO strip bold escapes from its input, so a label that
+    // contains `\x1b[1m...\x1b[22m` (chalk.bold) renders bold only when
+    // it's the active row (Clack doesn't wrap active labels), and renders
+    // plain when Clack wraps the inactive label in `dim()`. This is the
+    // only way to get "bold on active, normal on inactive" without
+    // forking @clack/prompts.
+    const BOLD_RE = /\x1b\[(?:1|22)m/g;
+    const origDim = pc.dim;
+    pc.dim = (s) => origDim(String(s).replace(BOLD_RE, ""));
+  } catch {
+    // picocolors not installed (shouldn't happen — clack depends on it).
+    // Silently skip; the wizard still works, just with default colors.
+  }
+}
+applyClackTheme();
+
+// Canonical AgileFlow wordmark — kept in sync with apps/website/lib/logo.ts.
+const LOGO = [
+  " █████╗  ██████╗ ██╗██╗     ███████╗███████╗██╗      ██████╗ ██╗    ██╗",
+  "██╔══██╗██╔════╝ ██║██║     ██╔════╝██╔════╝██║     ██╔═══██╗██║    ██║",
+  "███████║██║  ███╗██║██║     █████╗  █████╗  ██║     ██║   ██║██║ █╗ ██║",
+  "██╔══██║██║   ██║██║██║     ██╔══╝  ██╔══╝  ██║     ██║   ██║██║███╗██║",
+  "██║  ██║╚██████╔╝██║███████╗███████╗██║     ███████╗╚██████╔╝╚███╔███╔╝",
+  "╚═╝  ╚═╝ ╚═════╝ ╚═╝╚══════╝╚══════╝╚═╝     ╚══════╝ ╚═════╝  ╚══╝╚══╝",
+];
+
+/**
+ * Render the brand logo as a single string, brand-colored. Caller is
+ * responsible for printing it (typically before `prompts.intro`).
+ *
+ * @param {string} [version]
+ * @returns {string}
+ */
+function logoBanner(version) {
+  const lines = LOGO.map((l) => brand(l));
+  if (version) {
+    lines.push("");
+    lines.push(brand.bold(`v${version}`));
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Build a Clack option label that visually separates name and description:
+ *   bold brand-color label
+ *   dim description on a second line
+ *
+ * Clack renders `label` verbatim, so embedded newlines work and produce
+ * a clean two-line option that's much easier to read than label+hint
+ * sharing one line in the same color.
+ *
+ * @param {string} title
+ * @param {string} [description]
+ * @returns {string}
+ */
+function optionLabel(title, description) {
+  // Bold the title; the picocolors.dim() patch above strips bold from
+  // dimmed rows, so this only renders bold on the active row.
+  const head = chalk.bold(title);
+  if (!description) return head;
+  return `${head}\n   ${chalk.ansi256(245)(description)}`;
+}
+
+/**
+ * Build a Clack prompt message with a bold question and optional muted
+ * supporting sentence on the next line.
+ *
+ * @param {string} title
+ * @param {string} [description]
+ * @returns {string}
+ */
+function questionMessage(title, description) {
+  const head = chalk.bold(title);
+  if (!description) return head;
+  return `${head}\n${chalk.ansi256(245)(description)}`;
+}
+
+module.exports = {
+  BRAND_COLOR,
+  brand,
+  logoBanner,
+  optionLabel,
+  questionMessage,
+};

package/src/lib/errors.js

@@ -0,0 +1,120 @@
+/**
+ * Typed user-facing errors for the AgileFlow CLI.
+ *
+ * Every error a user is likely to hit (bad argument, missing config,
+ * failed install) should be one of these classes so the formatter can
+ * print a consistent two-line message:
+ *
+ *   ✗ agileflow <cmd>: <message>
+ *     Try: <suggestion>
+ *
+ * Internal/programmer errors should stay as plain `Error` — `fail()`
+ * wraps them with a generic "Try: re-run with --debug" suggestion so
+ * the CLI never prints a bare stack trace at users.
+ */
+const chalk = require("chalk");
+
+/**
+ * @typedef {object} AgileflowErrorOptions
+ * @property {string} [suggestion] Actionable fix the user should try next.
+ * @property {string} [code]       Stable machine-readable code (defaults per subclass).
+ * @property {Error}  [cause]      Underlying error, if wrapping.
+ */
+
+class AgileflowError extends Error {
+  /**
+   * @param {string} message
+   * @param {AgileflowErrorOptions} [options]
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "AgileflowError";
+    this.suggestion = options.suggestion;
+    this.code = options.code || "ERR_AGILEFLOW";
+    if (options.cause) this.cause = options.cause;
+  }
+}
+
+class MissingFileError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_MISSING_FILE", ...options });
+    this.name = "MissingFileError";
+  }
+}
+
+class InvalidArgumentError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_INVALID_ARGUMENT", ...options });
+    this.name = "InvalidArgumentError";
+  }
+}
+
+class OperationFailedError extends AgileflowError {
+  constructor(message, options = {}) {
+    super(message, { code: "ERR_OPERATION_FAILED", ...options });
+    this.name = "OperationFailedError";
+  }
+}
+
+/**
+ * Format an error as a two-line stderr string. Does not write — caller decides.
+ *
+ * @param {Error} err
+ * @param {{ command?: string }} [opts]
+ * @returns {string}
+ */
+function formatError(err, opts = {}) {
+  const cmd = opts.command ? `agileflow ${opts.command}` : "agileflow";
+  const head = `${chalk.red("✗")} ${cmd}: ${err.message}`;
+  const isAgileflowError = err instanceof AgileflowError;
+  const hasStringSuggestion =
+    isAgileflowError && typeof err.suggestion === "string" && err.suggestion;
+  const suggestion = hasStringSuggestion
+    ? err.suggestion
+    : isAgileflowError
+      ? null
+      : "Re-run with DEBUG=1 for a stack trace, or report at https://github.com/anthropics/agileflow/issues";
+  if (!suggestion) return head;
+  return `${head}\n  ${chalk.dim(`Try: ${suggestion}`)}`;
+}
+
+/**
+ * Print an error to stderr and exit with code 1. Use this at the leaf of
+ * a command handler instead of `console.error(...); process.exit(1)`.
+ *
+ * Internal errors (non-AgileflowError) are still printed clearly; their
+ * stack trace is emitted only when `DEBUG=1` is set, so users don't see
+ * Node internals by default.
+ *
+ * @param {Error} err
+ * @param {{ command?: string }} [opts]
+ * @returns {never}
+ */
+function fail(err, opts = {}) {
+  console.error(formatError(err, opts));
+  if (isDebugEnabled() && err.stack) {
+    console.error(chalk.dim(err.stack));
+  }
+  process.exit(1);
+}
+
+/**
+ * Treat DEBUG as set unless it's an explicit falsy string. Mirrors the
+ * convention used by most Node libraries (`debug`, `npm`), where
+ * DEBUG=0 / DEBUG=false / DEBUG="" all mean off.
+ */
+function isDebugEnabled() {
+  const v = process.env.DEBUG;
+  if (!v) return false;
+  const lowered = String(v).toLowerCase();
+  return lowered !== "0" && lowered !== "false" && lowered !== "no";
+}
+
+module.exports = {
+  AgileflowError,
+  MissingFileError,
+  InvalidArgumentError,
+  OperationFailedError,
+  formatError,
+  fail,
+};