@mhd-ghaith-abtah/flow 0.7.2-beta.0

package/lib/commands/plan.js

@@ -0,0 +1,108 @@
+// lib/commands/plan.js — `flow plan` dry-run resolver.
+//
+// Prints the resolved install plan for a given profile: which Flow components,
+// adapters, MCPs, and upstream subsets would be installed. Does NOT execute
+// anything — purely a preview / scriptable plan emitter.
+//
+// Usage:
+//   flow plan --profile standard
+//   flow plan --profile team --json
+//   flow plan --profile mini --without adapter:e2e-playwright-mcp
+
+import chalk from 'chalk';
+import { loadCatalog, resolveProfile, listProfiles } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+/**
+ * @param {Object} args - parsed yargs args
+ * @param {Object} ctx
+ */
+export default async function plan(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  const catalog = loadCatalog(repoRoot);
+
+  const profileName = args.profile ?? 'standard';
+  if (!catalog.profiles[profileName]) {
+    console.error(chalk.red(`✗ Unknown profile: ${profileName}`));
+    console.error(`  Available: ${listProfiles(catalog).join(', ')}`);
+    return 1;
+  }
+
+  const profile = resolveProfile(catalog, profileName);
+
+  // Apply --with / --without overrides (no-op if empty).
+  const withList = toArray(args.with);
+  const withoutList = toArray(args.without);
+  const adapters = applyOverrides(profile.adapters, withList, withoutList, catalog);
+
+  const planSpec = {
+    profile: profileName,
+    description: profile.description,
+    flow_components: profile.flow_components,
+    adapters,
+    mcps: profile.mcps,
+    upstreams: {
+      bmad: profile.bmad_subset,
+      ecc: profile.ecc_subset,
+      caveman: profile.caveman_subset
+    },
+    features: profile.features ?? {}
+  };
+
+  if (args.json) {
+    console.log(JSON.stringify(planSpec, null, 2));
+    return 0;
+  }
+
+  renderHuman(planSpec, ctx);
+  return 0;
+}
+
+function toArray(v) {
+  if (v == null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+function applyOverrides(adapters, withList, withoutList, catalog) {
+  let result = [...adapters];
+  for (const id of withList) result.push(id);
+  result = result.filter(id => !withoutList.includes(id));
+
+  // De-dupe by family (later wins).
+  const byFamily = new Map();
+  for (const id of result) {
+    const a = catalog.adapters.find(x => x.id === id);
+    const family = a?.family ?? id;
+    byFamily.set(family, id);
+  }
+  return [...byFamily.values()];
+}
+
+function renderHuman(p, ctx) {
+  const lines = [];
+  lines.push(chalk.bold(`━━━ flow plan ━━━`));
+  lines.push(`Profile:      ${chalk.cyan(p.profile)} — ${p.description}`);
+  lines.push('');
+  lines.push(chalk.bold('Flow components:'));
+  for (const c of p.flow_components) lines.push(`  ${chalk.green('+')} ${c}`);
+  lines.push('');
+  lines.push(chalk.bold('Adapters:'));
+  for (const a of p.adapters) lines.push(`  ${chalk.green('+')} ${a}`);
+  lines.push('');
+  lines.push(chalk.bold('MCPs:'));
+  if (p.mcps.length === 0) lines.push(`  ${chalk.dim('(none)')}`);
+  for (const m of p.mcps) lines.push(`  ${chalk.green('+')} ${m}`);
+  lines.push('');
+  lines.push(chalk.bold('Upstreams:'));
+  lines.push(`  BMad:     ${p.upstreams.bmad}`);
+  lines.push(`  ECC:      ${p.upstreams.ecc}`);
+  lines.push(`  Caveman:  ${p.upstreams.caveman}`);
+  if (Object.keys(p.features).length > 0) {
+    lines.push('');
+    lines.push(chalk.bold('Features:'));
+    for (const [k, v] of Object.entries(p.features)) lines.push(`  ${k}: ${v}`);
+  }
+  lines.push('');
+  lines.push(chalk.dim('This is a preview. Run `/flow-init` inside Claude Code to execute.'));
+  console.log(lines.join('\n'));
+}

package/lib/commands/remove.js

@@ -0,0 +1,87 @@
+// lib/commands/remove.js — `flow remove <component-id>` removes an adapter.
+//
+// Counterpart to `flow add`. For adapters, sets the family back to the `none`
+// variant (which keeps Flow's flow-story phase decision happy — it expects
+// SOME adapter per family). Does NOT remove the adapter file from disk (other
+// projects might still use it via the home-scope install).
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { loadCatalog } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+export default async function remove(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  const catalog = loadCatalog(repoRoot);
+  const yes = Boolean(args.yes);
+  const dryRun = Boolean(args['dry-run']);
+
+  const componentId = args._?.[0];
+  if (!componentId) {
+    console.error(chalk.red('✗ Missing component id. Example: flow remove adapter:e2e-playwright-mcp'));
+    return 1;
+  }
+
+  const adapter = catalog.adapters?.find((a) => a.id === componentId);
+  if (!adapter) {
+    console.error(chalk.red(`✗ Unknown adapter (or not an adapter — only adapters are removable via this command): ${componentId}`));
+    return 1;
+  }
+
+  // Find the "none" sibling for the same family.
+  const noneId = `adapter:${adapter.family}-none`;
+  const noneExists = catalog.adapters?.some((a) => a.id === noneId);
+  if (!noneExists) {
+    console.error(chalk.red(`✗ No '${noneId}' fallback in catalog. Refusing to remove without a fallback.`));
+    return 1;
+  }
+
+  console.log(chalk.bold(`━━━ flow remove ${componentId} ━━━`));
+  console.log();
+  console.log(`Family:    ${adapter.family}`);
+  console.log(`Fallback:  ${noneId}  (flow-story expects SOME adapter per family)`);
+  console.log();
+
+  const configPath = join(ctx.cwd, 'flow.config.yaml');
+  if (!existsSync(configPath)) {
+    console.error(chalk.yellow('⚠'), `No flow.config.yaml in ${ctx.cwd}. Nothing to update.`);
+    return 0;
+  }
+
+  const config = parseYaml(readFileSync(configPath, 'utf-8')) || {};
+  config.adapters = config.adapters || {};
+  const configKey = adapter.family.replace(/-/g, '_');
+  const currentShort = config.adapters[configKey];
+  const shortIdOfThis = adapter.id.replace(`adapter:${adapter.family}-`, '');
+
+  if (currentShort !== shortIdOfThis) {
+    console.log(chalk.yellow('ℹ'), `flow.config.yaml.adapters.${configKey} is '${currentShort}', not '${shortIdOfThis}'.`);
+    console.log(chalk.dim('  Nothing to remove.'));
+    return 0;
+  }
+
+  console.log(`Would set flow.config.yaml.adapters.${configKey}: ${shortIdOfThis} → none`);
+
+  if (dryRun) {
+    console.log();
+    console.log(chalk.dim('--dry-run: stopping before write.'));
+    return 0;
+  }
+
+  if (!yes) {
+    console.log();
+    console.log(chalk.yellow('?'), 'Re-run with --yes to confirm.');
+    return 0;
+  }
+
+  config.adapters[configKey] = 'none';
+  writeFileSync(configPath, stringifyYaml(config));
+  console.log();
+  console.log(`  ${chalk.cyan('↻')} flow.config.yaml: adapters.${configKey} ${shortIdOfThis} → none`);
+  console.log();
+  console.log(chalk.dim(`Note: ${adapter.id}'s files at ~/.claude/skills/flow-story/adapters/${adapter.family}/`));
+  console.log(chalk.dim(`were NOT removed — other projects may still use them. Re-add with: flow add ${adapter.id}`));
+  return 0;
+}

package/lib/commands/uninstall.js

@@ -0,0 +1,157 @@
+// lib/commands/uninstall.js — `flow uninstall` removal path.
+//
+// Removes Flow's own skills, adapters, and per-scope state. Does NOT touch
+// BMad, ECC, or Caveman — those are owned by their own installers and Flow
+// only records that they were used.
+//
+// Default: --scope project (only this project's .claude/flow/). Pass
+// --scope home to remove the user-level install. Pass --scope both to do both.
+//
+// Default: dry-run. Prints what WOULD be removed. Pass --execute to actually
+// remove. Refuses to run without --execute unless --yes is also passed.
+
+import { existsSync, rmSync, readFileSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { loadCatalog } from '../catalog.js';
+import { resolveRepoRoot } from '../repo-root.js';
+
+const HOME_PATHS = [
+  '$HOME/.claude/skills/flow-init',
+  '$HOME/.claude/skills/flow-sprint',
+  '$HOME/.claude/skills/flow-story',
+  '$HOME/.claude/skills/flow-doctor',
+  '$HOME/.claude/flow'
+];
+
+const PROJECT_PATHS = [
+  '.claude/flow',
+  'flow.config.yaml',
+  'flow.config.local.yaml'
+];
+
+const PROJECT_PATHS_KEEP_BY_DEFAULT = [
+  // These are user content — keep unless --remove-stories is passed.
+  'docs/flow'
+];
+
+/**
+ * @param {Object} args
+ * @param {Object} ctx
+ */
+export default async function uninstall(args, ctx) {
+  const repoRoot = ctx.repoRoot ?? resolveRepoRoot(import.meta.url);
+  loadCatalog(repoRoot);  // validate parseable
+
+  const scope = args.scope ?? 'project';
+  const execute = Boolean(args.execute);
+  const yes = Boolean(args.yes);
+  const removeStories = Boolean(args['remove-stories']);
+  const removeBackups = Boolean(args['remove-backups']);
+
+  if (!['project', 'home', 'both'].includes(scope)) {
+    console.error(chalk.red(`✗ Unknown scope: ${scope}. Use project | home | both.`));
+    return 1;
+  }
+
+  const plan = buildPlan({ scope, removeStories, removeBackups, cwd: ctx.cwd, home: ctx.home });
+
+  renderPlan(plan, { execute });
+
+  if (!execute) {
+    console.log();
+    console.log(chalk.dim('Dry run. Re-run with --execute to actually remove. Add --yes to skip the confirm.'));
+    return 0;
+  }
+
+  if (!yes) {
+    console.log();
+    console.log(chalk.yellow('⚠'), 'About to remove the above. Re-run with --execute --yes to confirm.');
+    return 0;
+  }
+
+  // Execute.
+  console.log();
+  console.log(chalk.bold('Removing:'));
+  let removed = 0;
+  let kept = 0;
+  for (const item of plan.toRemove) {
+    if (!existsSync(item.resolved)) {
+      console.log(`  ${chalk.dim('skip (not present)')} ${item.path}`);
+      kept++;
+      continue;
+    }
+    try {
+      rmSync(item.resolved, { recursive: true, force: true });
+      console.log(`  ${chalk.green('removed')} ${item.path}`);
+      removed++;
+    } catch (err) {
+      console.log(`  ${chalk.red('failed')} ${item.path}: ${err.message}`);
+    }
+  }
+
+  console.log();
+  console.log(chalk.bold(`Done: ${removed} removed, ${kept} not present.`));
+  console.log();
+  console.log(chalk.dim('Flow does NOT remove BMad, ECC, or Caveman — they were installed by their own'));
+  console.log(chalk.dim('installers and Flow only recorded that they were used. Remove them via:'));
+  console.log(chalk.dim('  BMad:    rm -rf _bmad/ docs/_bmad-output/ (or `npx bmad-method uninstall`)'));
+  console.log(chalk.dim('  ECC:     ~/.claude/rules/uninstall.sh (or rm -rf ~/.claude/rules/)'));
+  console.log(chalk.dim('  Caveman: rm -rf ~/.claude/plugins/cache/caveman/ and `claude mcp remove caveman-shrink`'));
+
+  return 0;
+}
+
+function buildPlan({ scope, removeStories, removeBackups, cwd, home }) {
+  const toRemove = [];
+
+  if (scope === 'home' || scope === 'both') {
+    for (const p of HOME_PATHS) {
+      toRemove.push({ path: p, resolved: resolveHomePath(p, home), kind: 'home' });
+    }
+  }
+
+  if (scope === 'project' || scope === 'both') {
+    for (const p of PROJECT_PATHS) {
+      toRemove.push({ path: p, resolved: resolve(cwd, p), kind: 'project' });
+    }
+    if (removeStories) {
+      for (const p of PROJECT_PATHS_KEEP_BY_DEFAULT) {
+        toRemove.push({ path: p, resolved: resolve(cwd, p), kind: 'project-user-content' });
+      }
+    }
+  }
+
+  const toKeep = [];
+  if (scope !== 'home' && !removeStories) {
+    for (const p of PROJECT_PATHS_KEEP_BY_DEFAULT) {
+      toKeep.push({ path: p, resolved: resolve(cwd, p), reason: 'user content — pass --remove-stories to drop' });
+    }
+  }
+  toKeep.push({ path: 'BMad', reason: 'owned by BMad installer; not removed' });
+  toKeep.push({ path: 'ECC', reason: 'owned by ECC installer; not removed' });
+  toKeep.push({ path: 'Caveman', reason: 'owned by Caveman installer; not removed' });
+
+  return { scope, toRemove, toKeep, removeBackups };
+}
+
+function resolveHomePath(p, home) {
+  return p.replace(/\$HOME/g, home);
+}
+
+function renderPlan(plan, { execute }) {
+  console.log(chalk.bold(`━━━ flow uninstall plan (scope: ${plan.scope}) ━━━`));
+  console.log();
+  console.log(chalk.bold(execute ? 'Will remove:' : 'Would remove:'));
+  for (const item of plan.toRemove) {
+    const present = existsSync(item.resolved);
+    const tag = present ? chalk.red('-') : chalk.dim('-');
+    const suffix = present ? '' : chalk.dim('  (not present)');
+    console.log(`  ${tag} ${item.path}${suffix}`);
+  }
+  console.log();
+  console.log(chalk.bold('Keeping:'));
+  for (const item of plan.toKeep) {
+    console.log(`  ${chalk.green('+')} ${item.path}  ${chalk.dim('— ' + item.reason)}`);
+  }
+}

package/lib/repo-root.js

@@ -0,0 +1,53 @@
+// lib/repo-root.js — resolve Flow's repo root the same way the skills do.
+//
+// Resolution order (matches skills/flow-init/workflow.md step 1):
+//   1. $FLOW_REPO_ROOT env (explicit override).
+//   2. Walk up from import.meta.url's directory looking for catalog.yaml
+//      (works whether installed via npm at ~/.npm-global/lib/node_modules/...
+//      or via dev-link symlinks to a checked-out clone).
+//   3. CWD if it contains catalog.yaml (dev mode).
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+/**
+ * @param {string} startDir
+ * @returns {string|null}
+ */
+function walkUpForCatalog(startDir) {
+  let dir = startDir;
+  while (dir && dir !== dirname(dir)) {
+    if (existsSync(resolve(dir, 'catalog.yaml'))) return dir;
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * @param {string} importMetaUrl - typically `import.meta.url` from the caller
+ * @returns {string}
+ */
+export function resolveRepoRoot(importMetaUrl) {
+  if (process.env.FLOW_REPO_ROOT) {
+    if (!existsSync(resolve(process.env.FLOW_REPO_ROOT, 'catalog.yaml'))) {
+      throw new Error(`FLOW_REPO_ROOT=${process.env.FLOW_REPO_ROOT} but no catalog.yaml found there`);
+    }
+    return process.env.FLOW_REPO_ROOT;
+  }
+
+  // Walk up from the caller's file location (works for npm install + symlinks).
+  const callerPath = new URL(importMetaUrl).pathname;
+  const fromCaller = walkUpForCatalog(dirname(callerPath));
+  if (fromCaller) return fromCaller;
+
+  // Fall back to CWD (dev mode).
+  const fromCwd = walkUpForCatalog(process.cwd());
+  if (fromCwd) return fromCwd;
+
+  throw new Error(
+    "Couldn't locate catalog.yaml. Either:\n" +
+    "  • Set FLOW_REPO_ROOT to the directory containing catalog.yaml, or\n" +
+    "  • Run `flow` from inside a Flow clone, or\n" +
+    "  • Re-install Flow (clone https://github.com/mhd-ghaith-abtah/flow; tools/dev-link.sh)."
+  );
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mhd-ghaith-abtah/flow",
+  "version": "0.7.2-beta.0",
+  "description": "Token-light per-story workflow for Claude Code. Delegates to BMad + ECC.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "flow": "bin/flow.js"
+  },
+  "files": [
+    "bin",
+    "lib/**/*.js",
+    "!lib/**/*.test.js",
+    "skills",
+    "adapters",
+    "templates",
+    "schemas",
+    "tools/lint-changelog.js",
+    "tools/fix-caveman-shrink.sh",
+    "catalog.yaml",
+    "docs/quickstart.md",
+    "docs/adapters.md",
+    "docs/profiles.md",
+    "docs/migrate-from-bmad.md",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "smoke": "node bin/flow.js plan --profile standard --dry-run"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^7.0.0",
+    "ajv": "^8.17.1",
+    "chalk": "^5.3.0",
+    "execa": "^9.5.1",
+    "ora": "^8.1.1",
+    "yaml": "^2.6.1",
+    "yargs-parser": "^21.1.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhd-ghaith-abtah/flow.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mhd-ghaith-abtah/flow/issues"
+  },
+  "homepage": "https://github.com/mhd-ghaith-abtah/flow#readme",
+  "keywords": [
+    "claude-code",
+    "workflow",
+    "sprint",
+    "story",
+    "bmad",
+    "ecc",
+    "spec-driven"
+  ]
+}

package/schemas/catalog.schema.json

@@ -0,0 +1,155 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/mhd-ghaith-abtah/flow/schemas/catalog.schema.json",
+  "title": "Flow catalog",
+  "description": "The single source of truth for what Flow can install. Validated on every install.",
+  "type": "object",
+  "required": ["version", "flow_components", "adapters", "profiles"],
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "flow_version_compat": { "type": "string" },
+
+    "flow_components": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/flow_component" }
+    },
+
+    "adapters": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/adapter" }
+    },
+
+    "mcps": {
+      "type": "array",
+      "items": { "$ref": "#/definitions/mcp" }
+    },
+
+    "upstreams": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/definitions/upstream" }
+    },
+
+    "profiles": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/definitions/profile" }
+    }
+  },
+  "additionalProperties": false,
+
+  "definitions": {
+    "flow_component": {
+      "type": "object",
+      "required": ["id", "family"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9-]+:[a-z0-9-]+$" },
+        "family": { "type": "string", "enum": ["core", "adapter", "mcp"] },
+        "description": { "type": "string" },
+        "required": { "type": "boolean" },
+        "operations": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/operation" }
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "adapter": {
+      "type": "object",
+      "required": ["id", "family"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^adapter:[a-z0-9-]+$" },
+        "family": {
+          "type": "string",
+          "enum": ["issue-tracker", "pr", "e2e", "verify", "notification"]
+        },
+        "description": { "type": "string" },
+        "needs_mcp": { "type": "array", "items": { "type": "string" } },
+        "needs_cli": { "type": "array", "items": { "type": "string" } },
+        "detect": { "type": "string" },
+        "config_keys": { "type": "array" },
+        "runtime_deps": { "type": "array" },
+        "operations": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/operation" }
+        }
+      },
+      "additionalProperties": true
+    },
+
+    "mcp": {
+      "type": "object",
+      "required": ["id"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9-]+$" },
+        "name": { "type": "string" },
+        "description": { "type": "string" },
+        "package": { "type": "string" },
+        "install_cmd": { "type": "string" },
+        "detect_cmd": { "type": "string" },
+        "scope_default": { "type": "string", "enum": ["home", "project"] },
+        "auth": {
+          "type": "string",
+          "enum": ["none", "api_token", "oauth_browser", "oauth_device"]
+        },
+        "auth_instructions": { "type": "string" },
+        "env": { "type": "array" },
+        "optional": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+
+    "upstream": {
+      "type": "object",
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string" },
+        "repo": { "type": "string" },
+        "homepage": { "type": "string" },
+        "description": { "type": "string" },
+        "detect": { "type": "object" },
+        "installer": { "type": "object" },
+        "available_modules": { "type": "array" },
+        "available_profiles": { "type": "array" },
+        "available_modes": { "type": "array" },
+        "curated_subsets": { "type": "object" }
+      },
+      "additionalProperties": true
+    },
+
+    "profile": {
+      "type": "object",
+      "required": ["description"],
+      "properties": {
+        "description": { "type": "string" },
+        "extends": { "type": "string" },
+        "flow_components": { "type": "array", "items": { "type": "string" } },
+        "adapters": { "type": "array", "items": { "type": "string" } },
+        "mcps": { "type": "array", "items": { "type": "string" } },
+        "bmad_subset": { "type": "string" },
+        "ecc_subset": { "type": "string" },
+        "caveman_subset": { "type": "string" },
+        "features": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+
+    "operation": {
+      "type": "object",
+      "properties": {
+        "copy": {
+          "type": "object",
+          "required": ["from", "to"],
+          "properties": {
+            "from": { "type": "string" },
+            "to": { "type": "string" }
+          }
+        },
+        "ensure_dir": { "type": "string" },
+        "touch": { "type": "string" },
+        "run": { "type": "string" }
+      },
+      "additionalProperties": false
+    }
+  }
+}