agileflow 3.4.3 → 4.0.0-alpha.2

package/src/cli/commands/status.js

@@ -0,0 +1,47 @@
+/**
+ * `agileflow status` — print install state, enabled plugins, hook health.
+ *
+ * Phase 1 stub: prints version + config summary if present. Hook health,
+ * plugin state beyond `enabled` flag, and integrity counts land in Phase 5.
+ */
+const path = require('path');
+const pkg = require('../../../package.json');
+const { loadConfig } = require('../../runtime/config/loader.js');
+
+/** @param {{ json?: boolean }} options */
+async function status(options = {}) {
+  const cwd = process.cwd();
+  const result = await loadConfig(cwd);
+
+  const summary = {
+    version: pkg.version,
+    cwd,
+    configPath: result.path || null,
+    configSource: result.source, // 'file' | 'defaults'
+    plugins: Object.entries(result.config.plugins || {})
+      .filter(([, v]) => v && v.enabled)
+      .map(([id]) => id),
+    personalization: result.config.personalization,
+    phase: 'Phase 2a — wizard ready; installer sync engine + hooks + content pending (Phase 2b+)',
+  };
+
+  if (options.json) {
+    // eslint-disable-next-line no-console
+    console.log(JSON.stringify(summary, null, 2));
+    return;
+  }
+
+  const lines = [
+    `agileflow v${summary.version}`,
+    `cwd:      ${summary.cwd}`,
+    `config:   ${summary.configPath ? path.relative(cwd, summary.configPath) : '(defaults — no agileflow.config.json found)'}`,
+    `plugins:  ${summary.plugins.length ? summary.plugins.join(', ') : '(none enabled — core is default)'}`,
+    `tone:     ${summary.personalization.tone}`,
+    `ask:      ${summary.personalization.ask_level}`,
+    `phase:    ${summary.phase}`,
+  ];
+  // eslint-disable-next-line no-console
+  console.log(lines.join('\n'));
+}
+
+module.exports = status;

package/src/cli/commands/update.js

@@ -0,0 +1,83 @@
+/**
+ * `agileflow update` — re-run the installer for the currently-enabled
+ * plugin set, no prompts.
+ *
+ * Use cases:
+ *   - User edited `agileflow.config.json` directly and wants to apply
+ *     it without re-running the wizard.
+ *   - CI step that ensures `.agileflow/` is in sync with the committed
+ *     `agileflow.config.json`.
+ *   - User installed a new bundled plugin via `enable` and wants the
+ *     content materialized.
+ *
+ * Always non-interactive. Exits non-zero on validation / install
+ * failure.
+ */
+const path = require("path");
+const pkg = require("../../../package.json");
+const { loadConfig } = require("../../runtime/config/loader.js");
+const { discoverPlugins } = require("../../runtime/plugins/registry.js");
+const { installPlugins } = require("../../runtime/installer/install.js");
+
+/**
+ * @param {{ force?: boolean }} options
+ */
+async function update(options = {}) {
+  const cwd = process.cwd();
+
+  let existing;
+  try {
+    existing = await loadConfig(cwd);
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(`agileflow update: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (existing.source === "defaults") {
+    // eslint-disable-next-line no-console
+    console.error(
+      "agileflow update: no agileflow.config.json found. Run `agileflow setup` first.",
+    );
+    process.exit(1);
+  }
+
+  const enabled = Object.entries(existing.config.plugins || {})
+    .filter(([, v]) => v && v.enabled)
+    .map(([id]) => id);
+
+  // userSelected excludes core (cannotDisable handles it).
+  const userSelected = enabled.filter((id) => id !== "core");
+
+  let result;
+  try {
+    result = await installPlugins({
+      discovered: discoverPlugins(),
+      userSelected,
+      agileflowDir: path.join(cwd, ".agileflow"),
+      cliVersion: pkg.version,
+      ide: existing.config.ide.primary,
+      behaviors: existing.config.behaviors,
+      force: Boolean(options.force),
+    });
+  } catch (err) {
+    // eslint-disable-next-line no-console
+    console.error(`agileflow update: install failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  // eslint-disable-next-line no-console
+  console.log(`✓ Updated ${enabled.length} plugin(s): ${enabled.join(", ")}`);
+  // eslint-disable-next-line no-console
+  console.log(
+    `  created=${result.ops.created} updated=${result.ops.updated} unchanged=${result.ops.unchanged} preserved=${result.ops.preserved} removed=${result.ops.removed}`,
+  );
+  if (result.ops.preserved > 0 && result.ops.updatesPath) {
+    // eslint-disable-next-line no-console
+    console.log(
+      `  ${result.ops.preserved} file(s) preserved — review ${result.ops.updatesPath}/`,
+    );
+  }
+}
+
+module.exports = update;

package/src/cli/index.js

@@ -0,0 +1,73 @@
+/**
+ * CLI dispatcher — wires commander up with the v4 command surface.
+ *
+ * Phase 1 ships `status`, `setup` (stub), and `doctor` (stub). Phase 2 adds
+ * `enable`, `disable`, and a real `setup`. Phase 5 adds `uninstall`.
+ */
+const { Command } = require('commander');
+const pkg = require('../../package.json');
+
+const status = require('./commands/status.js');
+const setup = require('./commands/setup.js');
+const update = require('./commands/update.js');
+const doctor = require('./commands/doctor.js');
+const hook = require('./commands/hook.js');
+
+/**
+ * Build the commander program. Exported so tests can construct it without
+ * parsing argv.
+ * @returns {Command}
+ */
+function buildProgram() {
+  const program = new Command();
+
+  program
+    .name('agileflow')
+    .description('AgileFlow v4 — skills-first agile toolkit for Claude Code')
+    .version(pkg.version, '-v, --version', 'print version');
+
+  program
+    .command('status')
+    .description('print install state, enabled plugins, and hook health')
+    .option('--json', 'output machine-readable JSON')
+    .action(status);
+
+  program
+    .command('setup')
+    .description('run interactive install wizard')
+    .option('--yes', 'skip prompts, install with defaults')
+    .option('--plugins <ids>', 'comma-separated plugin list to enable')
+    .option('--ide <id>', 'target IDE / CLI: claude-code | cursor | windsurf | codex', 'claude-code')
+    .action(setup);
+
+  program
+    .command('update')
+    .description('re-install plugins from the current agileflow.config.json (no prompts)')
+    .option('--force', 'overwrite local modifications instead of preserving them')
+    .action(update);
+
+  program
+    .command('doctor')
+    .description('validate config, plugins, skills, and hook manifest (Phase 5)')
+    .action(doctor);
+
+  program
+    .command('hook <event>')
+    .description('internal: dispatch a Claude Code hook event (used by settings.json)')
+    .option('--matcher <name>', 'tool name for tool-related events (Bash / Edit / Write / etc.)')
+    .action(hook);
+
+  return program;
+}
+
+/**
+ * Execute the CLI against the given argv.
+ * @param {string[]} argv
+ * @returns {Promise<void>}
+ */
+async function run(argv) {
+  const program = buildProgram();
+  await program.parseAsync(argv);
+}
+
+module.exports = { buildProgram, run };

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

@@ -0,0 +1,108 @@
+/**
+ * Behaviors picker — curated multiselect for the 4 hook-driven presets.
+ *
+ * Behaviors map 1:N to hooks declared in plugin manifests via the
+ * `behavior: <key>` field. Disabling a behavior here excludes its hooks
+ * from the generated `.agileflow/hook-manifest.yaml` at install time.
+ *
+ * Pure logic lives in `buildBehaviorsMap()` so it can be unit-tested
+ * without spawning a TTY.
+ */
+const prompts = require("@clack/prompts");
+
+/**
+ * @typedef {import('../../runtime/config/defaults.js').Behaviors} Behaviors
+ */
+
+/** Stable list of presets surfaced in the wizard, in display order. */
+const BEHAVIOR_OPTIONS = [
+  {
+    key: "loadContext",
+    label: "Load project context at session start",
+    hint: "SessionStart hook prints stories, dirty files, and recent commits so Claude has project context immediately.",
+  },
+  {
+    key: "babysitDefault",
+    label: "Activate Babysit mentor by default",
+    hint: "SessionStart hook injects the mentor pattern so Claude defaults to mentor mode without /agileflow:babysit.",
+  },
+  {
+    key: "damageControl",
+    label: "Damage control on Bash, Edit, Write",
+    hint: "PreToolUse hooks block dangerous commands (rm -rf /, fork bombs) and risky writes (.env, .ssh/) — fail-closed.",
+  },
+  {
+    key: "preCompactState",
+    label: "Save context before compaction",
+    hint: "PreCompact hook dumps active stories, current command, and dirty git state so they survive compaction.",
+  },
+];
+
+/**
+ * Build a complete Behaviors map from a set of selected keys, falling
+ * back to current values for any key not represented in the selection
+ * input. Missing keys default to `false` (the user actively saw the
+ * option and chose not to enable it).
+ *
+ * @param {Iterable<string>} selectedKeys
+ * @returns {Behaviors}
+ */
+function buildBehaviorsMap(selectedKeys) {
+  const set = new Set(selectedKeys);
+  /** @type {Behaviors} */
+  const result = {
+    loadContext: set.has("loadContext"),
+    babysitDefault: set.has("babysitDefault"),
+    damageControl: set.has("damageControl"),
+    preCompactState: set.has("preCompactState"),
+  };
+  return result;
+}
+
+/**
+ * Pre-check options whose keys are currently enabled (or — when no
+ * existing config — fall back to the preset's enabledByDefault). The
+ * default-on shape lives in `defaults.js`; this just reads it.
+ *
+ * @param {Partial<Behaviors>} [current]
+ * @returns {string[]}
+ */
+function initialSelectedKeys(current) {
+  if (!current) return BEHAVIOR_OPTIONS.map((o) => o.key);
+  return BEHAVIOR_OPTIONS.filter((o) => current[o.key] !== false).map(
+    (o) => o.key,
+  );
+}
+
+/**
+ * Interactive picker. Returns a complete Behaviors object.
+ *
+ * @param {Partial<Behaviors>} [currentBehaviors]
+ * @returns {Promise<Behaviors>}
+ */
+async function pickBehaviors(currentBehaviors) {
+  const picked = await prompts.multiselect({
+    message: "Which behaviors should AgileFlow run? (Recommended: all)",
+    options: BEHAVIOR_OPTIONS.map((o) => ({
+      value: o.key,
+      label: o.label,
+      hint: o.hint,
+    })),
+    initialValues: initialSelectedKeys(currentBehaviors),
+    required: false,
+  });
+
+  if (prompts.isCancel(picked)) {
+    prompts.cancel("Setup cancelled. No changes made.");
+    process.exit(1);
+  }
+
+  return buildBehaviorsMap(/** @type {string[]} */ (picked));
+}
+
+module.exports = {
+  pickBehaviors,
+  buildBehaviorsMap,
+  initialSelectedKeys,
+  BEHAVIOR_OPTIONS,
+};

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

@@ -0,0 +1,57 @@
+/**
+ * IDE / CLI picker — Clack select prompt.
+ *
+ * Asks the user which agentic IDE or CLI they're targeting. Defaults to
+ * Claude Code (the full-feature target). The choice is persisted to
+ * `agileflow.config.json` at `ide.primary` and gates which plugin
+ * content the installer writes (hooks, skills, etc. — see
+ * `runtime/ide/capabilities.js`).
+ */
+const prompts = require('@clack/prompts');
+const {
+  IDE_CAPABILITIES,
+  SUPPORTED_IDES,
+  capabilitiesFor,
+} = require('../../runtime/ide/capabilities.js');
+
+/**
+ * @param {string} currentIde - existing config's ide.primary
+ * @returns {Promise<string>} selected ide id
+ */
+async function pickIde(currentIde) {
+  const initialValue = SUPPORTED_IDES.includes(currentIde) ? currentIde : 'claude-code';
+
+  const choice = await prompts.select({
+    message: 'Which IDE / CLI are you using?',
+    options: SUPPORTED_IDES.map((id) => {
+      const caps = IDE_CAPABILITIES[id];
+      const featureList = ['hooks', 'skills', 'commands', 'agents', 'mcp']
+        .filter((f) => caps[f])
+        .join(', ');
+      return {
+        value: id,
+        label: caps.description,
+        hint: featureList ? `enables: ${featureList}` : '(very limited support)',
+      };
+    }),
+    initialValue,
+  });
+
+  if (prompts.isCancel(choice)) {
+    prompts.cancel('Setup cancelled. No changes made.');
+    process.exit(1);
+  }
+
+  const caps = capabilitiesFor(/** @type {string} */ (choice));
+  const disabled = ['hooks', 'skills', 'commands', 'agents']
+    .filter((f) => !caps[f]);
+  if (disabled.length) {
+    prompts.log.warn(
+      `${choice}: ${disabled.join(', ')} won't be installed (not supported by this IDE).`,
+    );
+  }
+
+  return /** @type {string} */ (choice);
+}
+
+module.exports = { pickIde };

package/src/cli/wizard/personalization.js

@@ -0,0 +1,64 @@
+/**
+ * Personalization prompts — three Clack selects for tone, ask-level, verbosity.
+ *
+ * v4.0-alpha scope: three enum flags that render into a short
+ * `{{PERSONALIZATION_BLOCK}}` in each installed SKILL.md (the renderer lands
+ * in Phase 5). ADR-0015 covers the future XML-tag matrix.
+ */
+const prompts = require('@clack/prompts');
+
+/**
+ * @param {import('../../runtime/config/defaults.js').Personalization} current
+ * @returns {Promise<import('../../runtime/config/defaults.js').Personalization>}
+ */
+async function personalizationPrompts(current) {
+  const tone = await prompts.select({
+    message: 'How should AgileFlow respond?',
+    options: [
+      { value: 'concise', label: 'Concise', hint: 'Tight answers, low ceremony' },
+      { value: 'detailed', label: 'Detailed', hint: 'More context and explanation' },
+      { value: 'teaching', label: 'Teaching', hint: 'Walk through the why' },
+    ],
+    initialValue: current.tone,
+  });
+  if (prompts.isCancel(tone)) {
+    prompts.cancel('Setup cancelled. No changes made.');
+    process.exit(1);
+  }
+
+  const askLevel = await prompts.select({
+    message: 'When should AgileFlow ask for confirmation?',
+    options: [
+      { value: 'none', label: 'Never', hint: 'Fully autonomous' },
+      { value: 'decision_points', label: 'At decision points', hint: 'Standard' },
+      { value: 'always', label: 'Always', hint: 'Confirm before each step' },
+    ],
+    initialValue: current.ask_level,
+  });
+  if (prompts.isCancel(askLevel)) {
+    prompts.cancel('Setup cancelled. No changes made.');
+    process.exit(1);
+  }
+
+  const verbosity = await prompts.select({
+    message: 'Output length preference?',
+    options: [
+      { value: 'low', label: 'Low', hint: 'Short responses' },
+      { value: 'medium', label: 'Medium', hint: 'Balanced' },
+      { value: 'high', label: 'High', hint: 'Full context' },
+    ],
+    initialValue: current.verbosity,
+  });
+  if (prompts.isCancel(verbosity)) {
+    prompts.cancel('Setup cancelled. No changes made.');
+    process.exit(1);
+  }
+
+  return {
+    tone: /** @type {any} */ (tone),
+    ask_level: /** @type {any} */ (askLevel),
+    verbosity: /** @type {any} */ (verbosity),
+  };
+}
+
+module.exports = { personalizationPrompts };

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

@@ -0,0 +1,106 @@
+/**
+ * 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');
+
+/**
+ * @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;
+}
+
+/**
+ * @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 picked = await prompts.multiselect({
+    message: 'Select optional plugins to enable:',
+    options: optional.map((p) => ({
+      value: p.id,
+      label: p.name,
+      hint: p.description,
+    })),
+    initialValues,
+    required: false,
+  });
+
+  if (prompts.isCancel(picked)) {
+    prompts.cancel('Setup cancelled. No changes made.');
+    process.exit(1);
+  }
+
+  const selectedOptionalIds = new Set(/** @type {string[]} */ (picked));
+  return buildPluginsMap(all, selectedOptionalIds, currentConfig.plugins || {});
+}
+
+module.exports = { pickPlugins, buildPluginsMap };

package/src/lib/hash.js

@@ -0,0 +1,41 @@
+/**
+ * SHA256 helpers.
+ *
+ * `sha256Hex` accepts either a Buffer or a string. Strings are encoded as
+ * UTF-8 for hashing so the output is deterministic regardless of whether
+ * the caller holds a pre-rendered text string or the raw file bytes.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+
+/**
+ * @param {Buffer|string} content
+ * @returns {string} lowercase hex digest
+ * @throws {TypeError} if content is null or undefined
+ */
+function sha256Hex(content) {
+  if (content == null) {
+    throw new TypeError(
+      `sha256Hex: content must be Buffer or string, got ${content === null ? 'null' : 'undefined'}`,
+    );
+  }
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Hash a file on disk. Returns null if the file does not exist.
+ * @param {string} filePath
+ * @returns {Promise<string|null>}
+ */
+async function sha256File(filePath) {
+  try {
+    const data = await fs.promises.readFile(filePath);
+    return sha256Hex(data);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+module.exports = { sha256Hex, sha256File };

package/src/runtime/config/defaults.js

@@ -0,0 +1,61 @@
+/**
+ * Default user config.
+ *
+ * Returned when `agileflow.config.json` is absent. Also merged into
+ * user-supplied config so missing sections get sensible defaults.
+ *
+ * @typedef {Object} Personalization
+ * @property {'concise'|'detailed'|'teaching'} tone
+ * @property {'none'|'decision_points'|'always'} ask_level
+ * @property {'low'|'medium'|'high'} verbosity
+ *
+ * @typedef {Object} PluginEntry
+ * @property {boolean} enabled
+ * @property {Record<string, unknown>} [settings]
+ *
+ * @typedef {Object} Behaviors
+ * @property {boolean} loadContext       - SessionStart context dump
+ * @property {boolean} babysitDefault    - HARD mentor mode at SessionStart
+ * @property {boolean} damageControl     - PreToolUse guards on Bash/Edit/Write
+ * @property {boolean} preCompactState   - PreCompact state preservation
+ *
+ * @typedef {Object} AgileflowConfig
+ * @property {1} version
+ * @property {Record<string, PluginEntry>} plugins
+ * @property {Record<string, { enabled?: boolean, timeout?: number, skipOnError?: boolean }>} hooks
+ * @property {Behaviors} behaviors
+ * @property {Personalization} personalization
+ * @property {{ primary: 'claude-code'|'cursor'|'windsurf'|'codex' }} ide
+ * @property {string} language
+ */
+
+/** @returns {AgileflowConfig} */
+function defaultConfig() {
+  return {
+    version: 1,
+    plugins: {
+      core: { enabled: true },
+    },
+    hooks: {},
+    behaviors: {
+      // Behaviors are presets that map to one or more hooks. The
+      // wizard surfaces these as a curated multiselect; advanced
+      // users can override individual hooks via the `hooks:` map.
+      loadContext: true,
+      babysitDefault: true,
+      damageControl: true,
+      preCompactState: true,
+    },
+    personalization: {
+      tone: "concise",
+      ask_level: "decision_points",
+      verbosity: "medium",
+    },
+    ide: {
+      primary: "claude-code",
+    },
+    language: "en",
+  };
+}
+
+module.exports = { defaultConfig };