agileflow 3.4.2 → 4.0.0-alpha.1

package/src/cli/commands/update.js

@@ -0,0 +1,82 @@
+/**
+ * `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,
+      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/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,45 @@
+/**
+ * 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} AgileflowConfig
+ * @property {1} version
+ * @property {Record<string, PluginEntry>} plugins
+ * @property {Record<string, { enabled?: boolean, timeout?: number, skipOnError?: boolean }>} hooks
+ * @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: {},
+    personalization: {
+      tone: 'concise',
+      ask_level: 'decision_points',
+      verbosity: 'medium',
+    },
+    ide: {
+      primary: 'claude-code',
+    },
+    language: 'en',
+  };
+}
+
+module.exports = { defaultConfig };

package/src/runtime/config/loader.js

@@ -0,0 +1,118 @@
+/**
+ * Unified config loader for AgileFlow v4.
+ *
+ * Reads `agileflow.config.json` from a project root, validates against the
+ * JSON Schema, merges with defaults, and returns a frozen config object.
+ *
+ * Missing file → returns defaults (not an error — first-run case).
+ * Invalid JSON → throws with the file path.
+ * Schema violation → throws with a JSON Pointer to the offending field.
+ */
+const fs = require('fs');
+const path = require('path');
+const Ajv = require('ajv');
+
+const schema = require('./schema.json');
+const { defaultConfig } = require('./defaults.js');
+
+const CONFIG_FILENAME = 'agileflow.config.json';
+
+const ajv = new Ajv({ allErrors: true, useDefaults: false, strict: false });
+const validate = ajv.compile(schema);
+
+/**
+ * Shallow-merge user config on top of defaults. `plugins`, `hooks`, and
+ * `personalization` sub-objects are deep-merged at one level so that
+ * partial user configs don't wipe defaults.
+ *
+ * @param {import('./defaults.js').AgileflowConfig} defaults
+ * @param {Partial<import('./defaults.js').AgileflowConfig>} user
+ * @returns {import('./defaults.js').AgileflowConfig}
+ */
+function mergeConfig(defaults, user) {
+  return {
+    version: user.version ?? defaults.version,
+    plugins: { ...defaults.plugins, ...(user.plugins || {}) },
+    hooks: { ...defaults.hooks, ...(user.hooks || {}) },
+    personalization: {
+      ...defaults.personalization,
+      ...(user.personalization || {}),
+    },
+    ide: { ...defaults.ide, ...(user.ide || {}) },
+    language: user.language ?? defaults.language,
+  };
+}
+
+/**
+ * Format Ajv errors as a single human-readable message with JSON Pointers.
+ * @param {import('ajv').ErrorObject[]} errors
+ * @returns {string}
+ */
+function formatSchemaErrors(errors) {
+  return errors
+    .map((e) => `  • ${e.instancePath || '/'} ${e.message}`)
+    .join('\n');
+}
+
+/**
+ * Load config from the given project root.
+ *
+ * @param {string} cwd - project root directory
+ * @returns {Promise<{
+ *   config: import('./defaults.js').AgileflowConfig,
+ *   path: string | null,
+ *   source: 'file' | 'defaults'
+ * }>}
+ */
+async function loadConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILENAME);
+
+  // Read directly and treat ENOENT as "no config → use defaults". This
+  // eliminates the existsSync-then-readFileSync TOCTOU window; between
+  // the two calls another process could delete the file and the user
+  // would get a misleading "Failed to read" error instead of defaults.
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return Object.freeze({
+        config: Object.freeze(defaultConfig()),
+        path: null,
+        source: 'defaults',
+      });
+    }
+    throw new Error(`Failed to read ${configPath}: ${err.message}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
+  }
+
+  if (!validate(parsed)) {
+    const details = formatSchemaErrors(validate.errors || []);
+    throw new Error(
+      `Config validation failed for ${configPath}:\n${details}`,
+    );
+  }
+
+  const merged = mergeConfig(defaultConfig(), parsed);
+  // Core plugin cannot be disabled — enforce at load time.
+  merged.plugins.core = { ...merged.plugins.core, enabled: true };
+
+  return Object.freeze({
+    config: Object.freeze(merged),
+    path: configPath,
+    source: 'file',
+  });
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  loadConfig,
+  mergeConfig,
+  formatSchemaErrors,
+};

package/src/runtime/config/schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/projectquestorg/AgileFlow/apps/cli/config.schema.json",
+  "title": "AgileFlow v4 user config",
+  "description": "User-facing configuration for AgileFlow v4. Lives at agileflow.config.json in project root.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Config schema version. Bumped on breaking changes."
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Map of plugin-id -> { enabled: bool, settings?: object }. core is always enabled.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "settings": { "type": "object", "additionalProperties": true }
+        },
+        "required": ["enabled"]
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Per-hook-id user overrides applied on top of plugin-supplied defaults.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "timeout": { "type": "integer", "minimum": 0, "maximum": 60000 },
+          "skipOnError": { "type": "boolean" }
+        }
+      }
+    },
+    "personalization": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tone": {
+          "type": "string",
+          "enum": ["concise", "detailed", "teaching"]
+        },
+        "ask_level": {
+          "type": "string",
+          "enum": ["none", "decision_points", "always"]
+        },
+        "verbosity": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        }
+      }
+    },
+    "ide": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "string",
+          "enum": ["claude-code", "cursor", "windsurf", "codex"]
+        }
+      }
+    },
+    "language": {
+      "type": "string",
+      "description": "IETF BCP 47 language tag (e.g. 'en', 'es', 'pt-BR').",
+      "pattern": "^[a-z]{2}(-[A-Z][a-zA-Z0-9]+)?$"
+    }
+  }
+}