agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

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

@@ -0,0 +1,50 @@
+/**
+ * `af` alias picker for `agileflow launch setup`.
+ *
+ * Asks whether to install the short `af` alias as a symlink at
+ * `~/.local/bin/af` → `agileflow`. The picker only captures the user's
+ * preference; the actual symlink is created by `installAfAlias()` after
+ * prefs are written, so failure modes (permission errors, PATH warnings)
+ * are surfaced cleanly through the existing outro path.
+ *
+ * Windows users see the option but the side-effect step reports
+ * "unsupported" and prints a PowerShell function snippet instead.
+ */
+const prompts = require("@clack/prompts");
+const { questionMessage } = require("../../lib/brand.js");
+
+/**
+ * @param {{ aliases: { af: { enabled: boolean } } }} currentPrefs
+ * @returns {Promise<{ af: { enabled: boolean } }>}
+ */
+async function pickAliases(currentPrefs) {
+  const initial =
+    currentPrefs &&
+    currentPrefs.aliases &&
+    currentPrefs.aliases.af &&
+    typeof currentPrefs.aliases.af.enabled === "boolean"
+      ? currentPrefs.aliases.af.enabled
+      : false;
+
+  const detail =
+    process.platform === "win32"
+      ? "On Windows the symlink can't be auto-created; we'll print a PowerShell snippet instead."
+      : "Creates ~/.local/bin/af → agileflow. No sudo needed.";
+
+  const choice = await prompts.confirm({
+    message: questionMessage(
+      "Install `af` as a short alias for `agileflow launch`?",
+      detail,
+    ),
+    initialValue: initial,
+  });
+
+  if (prompts.isCancel(choice)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  return { af: { enabled: /** @type {boolean} */ (choice) } };
+}
+
+module.exports = { pickAliases };

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

@@ -12,8 +12,9 @@
  * 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 prompts = require("@clack/prompts");
+const { discoverPlugins } = require("../../runtime/plugins/registry.js");
+const { questionMessage } = require("../../lib/brand.js");
 
 /**
  * @param {Array<{id:string, cannotDisable?:boolean}>} discovered
@@ -21,7 +22,11 @@ const { discoverPlugins } = require('../../runtime/plugins/registry.js');
  * @param {Record<string, {enabled:boolean, settings?:any}>} [existingPluginsMap]
  * @returns {Record<string, { enabled: boolean, settings?: any }>}
  */
-function buildPluginsMap(discovered, selectedOptionalIds, existingPluginsMap = {}) {
+function buildPluginsMap(
+  discovered,
+  selectedOptionalIds,
+  existingPluginsMap = {},
+) {
   /** @type {Record<string, { enabled: boolean, settings?: any }>} */
   const result = {};
   for (const p of discovered) {
@@ -36,7 +41,7 @@ function buildPluginsMap(discovered, selectedOptionalIds, existingPluginsMap = {
     const existing = (existingPluginsMap || {})[p.id];
     if (
       existing &&
-      typeof existing === 'object' &&
+      typeof existing === "object" &&
       !Array.isArray(existing) &&
       existing.settings
     ) {
@@ -51,7 +56,7 @@ function buildPluginsMap(discovered, selectedOptionalIds, existingPluginsMap = {
     if (
       !(id in result) &&
       entry &&
-      typeof entry === 'object' &&
+      typeof entry === "object" &&
       !Array.isArray(entry)
     ) {
       result[id] = entry;
@@ -60,6 +65,18 @@ function buildPluginsMap(discovered, selectedOptionalIds, existingPluginsMap = {
   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 }>>}
@@ -71,36 +88,50 @@ async function pickPlugins(currentConfig) {
 
   if (required.length) {
     prompts.log.info(
-      `Always on: ${required.map((p) => `${p.name} (${p.id})`).join(', ')}`,
+      `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;
+      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: 'Select optional plugins to enable:',
-    options: optional.map((p) => ({
-      value: p.id,
-      label: p.name,
-      hint: p.description,
-    })),
+    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.');
+    prompts.cancel("Setup cancelled. No changes made.");
     process.exit(1);
   }
 
-  const selectedOptionalIds = new Set(/** @type {string[]} */ (picked));
+  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 };
+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,
+};