@massu/core 1.0.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "AI Engineering Governance MCP Server - Session memory, knowledge system, feature registry, code intelligence, rule enforcement, tiered tooling (12 free / 72 total), 55+ workflow commands, 11 agents, 20+ patterns",
   "main": "src/server.ts",

package/src/cli.ts

@@ -52,6 +52,10 @@ async function main(): Promise<void> {
       await runValidateConfig();
       break;
     }
+    case 'config': {
+      await handleConfigSubcommand(args.slice(1));
+      break;
+    }
     case '--help':
     case '-h': {
       printHelp();
@@ -70,6 +74,56 @@ async function main(): Promise<void> {
   }
 }
 
+async function handleConfigSubcommand(configArgs: string[]): Promise<void> {
+  const sub = configArgs[0];
+  const flags = new Set(configArgs.slice(1));
+  switch (sub) {
+    case 'refresh': {
+      const { runConfigRefresh } = await import('./commands/config-refresh.ts');
+      const result = await runConfigRefresh({ dryRun: flags.has('--dry-run') });
+      process.exit(result.exitCode);
+      return;
+    }
+    case 'validate': {
+      const { runValidateConfig } = await import('./commands/doctor.ts');
+      await runValidateConfig();
+      return;
+    }
+    case 'upgrade': {
+      const { runConfigUpgrade } = await import('./commands/config-upgrade.ts');
+      const result = await runConfigUpgrade({
+        rollback: flags.has('--rollback'),
+        ci: flags.has('--ci') || flags.has('--yes'),
+      });
+      process.exit(result.exitCode);
+      return;
+    }
+    case 'doctor': {
+      const { runDoctor } = await import('./commands/doctor.ts');
+      await runDoctor();
+      return;
+    }
+    case 'check-drift': {
+      const { runConfigCheckDrift } = await import('./commands/config-check-drift.ts');
+      const result = await runConfigCheckDrift({ verbose: flags.has('--verbose') });
+      process.exit(result.exitCode);
+      return;
+    }
+    case '--help':
+    case '-h':
+    case undefined: {
+      printConfigHelp();
+      return;
+    }
+    default: {
+      process.stderr.write(`massu: unknown config subcommand: ${sub}\n`);
+      printConfigHelp();
+      process.exit(1);
+      return;
+    }
+  }
+}
+
 function printHelp(): void {
   console.log(`
 Massu AI - Engineering Governance Platform
@@ -82,7 +136,8 @@ Commands:
   doctor            Check installation health
   install-hooks     Install/update Claude Code hooks
   install-commands  Install/update slash commands
-  validate-config   Validate massu.config.yaml
+  validate-config   Validate massu.config.yaml (alias: config validate)
+  config <sub>      Config lifecycle: refresh | validate | upgrade | doctor | check-drift
 
 Options:
   --help, -h        Show this help message
@@ -91,11 +146,34 @@ Options:
 Getting started:
   npx massu init              # Full setup in one command
   npx massu init --help       # Show all init options (--ci, --force, --template)
+  npx massu config --help     # Show config subcommands
 
 Documentation: https://massu.ai/docs
 `);
 }
 
+function printConfigHelp(): void {
+  console.log(`
+massu config <subcommand>
+
+Subcommands:
+  refresh       Re-run detection and apply changes to massu.config.yaml.
+                  --dry-run    Print diff and exit without writing.
+  validate      Validate massu.config.yaml (alias of \`massu validate-config\`).
+  upgrade       Migrate a v1 config to schema_version=2.
+                  --rollback   Restore from .bak file.
+                  --ci, --yes  Non-interactive mode (no prompts).
+  doctor        Run the full health check (alias of \`massu doctor\`).
+  check-drift   CI-safe drift gate; exits 1 on drift.
+                  --verbose    Print detailed changes to stdout.
+
+Examples:
+  npx massu config refresh --dry-run
+  npx massu config upgrade --ci
+  npx massu config check-drift --verbose
+`);
+}
+
 function printVersion(): void {
   try {
     const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));

package/src/commands/config-check-drift.ts

@@ -0,0 +1,132 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config check-drift` — CI-safe drift gate.
+ *
+ * Reads massu.config.yaml, runs detection, and compares the result with both
+ * the stored fingerprint (if present) and the structural detectDrift() check.
+ *
+ * Flags:
+ *   --verbose   Emit the full changes[] to stdout (field: before -> after).
+ *
+ * Exit codes:
+ *   0  no drift
+ *   1  drift detected
+ *   2  config missing or unparseable
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint, detectDrift, type DriftChange } from '../detect/drift.ts';
+import type { AnyConfig } from '../detect/migrate.ts';
+
+export interface ConfigCheckDriftOptions {
+  verbose?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigCheckDriftResult {
+  exitCode: 0 | 1 | 2;
+  drifted: boolean;
+  changes: DriftChange[];
+  storedFingerprint: string | null;
+  currentFingerprint: string | null;
+  message?: string;
+}
+
+function renderChanges(changes: DriftChange[]): string {
+  if (changes.length === 0) return '(none)\n';
+  return changes
+    .map((c) => `  ${c.field}: ${JSON.stringify(c.before)} -> ${JSON.stringify(c.after)}`)
+    .join('\n') + '\n';
+}
+
+export async function runConfigCheckDrift(
+  opts: ConfigCheckDriftOptions = {}
+): Promise<ConfigCheckDriftResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+  const err = opts.silent ? () => {} : (s: string) => process.stderr.write(s);
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    err(message + '\n');
+    return {
+      exitCode: 2,
+      drifted: false,
+      changes: [],
+      storedFingerprint: null,
+      currentFingerprint: null,
+      message,
+    };
+  }
+
+  let config: AnyConfig;
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('config is not a YAML object');
+    }
+    config = parsed as AnyConfig;
+  } catch (e) {
+    const message = `Failed to parse massu.config.yaml: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return {
+      exitCode: 2,
+      drifted: false,
+      changes: [],
+      storedFingerprint: null,
+      currentFingerprint: null,
+      message,
+    };
+  }
+
+  const detection = await runDetection(cwd);
+  const currentFp = computeFingerprint(detection);
+  const storedFp =
+    typeof (config.detection as Record<string, unknown> | undefined)?.fingerprint === 'string'
+      ? ((config.detection as Record<string, unknown>).fingerprint as string)
+      : null;
+
+  const report = detectDrift(config, detection);
+  const fingerprintDrift = storedFp !== null && storedFp !== currentFp;
+  const drifted = report.drifted || fingerprintDrift;
+
+  if (!drifted) {
+    log('No drift detected.\n');
+    if (opts.verbose) {
+      log(`Fingerprint: ${currentFp}\n`);
+    }
+    return {
+      exitCode: 0,
+      drifted: false,
+      changes: report.changes,
+      storedFingerprint: storedFp,
+      currentFingerprint: currentFp,
+    };
+  }
+
+  err('Config drift detected; run `npx massu config refresh` to update.\n');
+  if (opts.verbose) {
+    if (storedFp !== null) {
+      log(`Fingerprint: ${storedFp.slice(0, 16)} -> ${currentFp.slice(0, 16)}\n`);
+    } else {
+      log(`Fingerprint (new): ${currentFp.slice(0, 16)}\n`);
+    }
+    log('Changes:\n');
+    log(renderChanges(report.changes));
+  }
+  return {
+    exitCode: 1,
+    drifted: true,
+    changes: report.changes,
+    storedFingerprint: storedFp,
+    currentFingerprint: currentFp,
+  };
+}

package/src/commands/config-refresh.ts

@@ -0,0 +1,327 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config refresh` — re-run detection, diff against current config, apply
+ * or print-only (--dry-run).
+ *
+ * Merge semantics:
+ *   - Detector-owned keys (framework, paths.source, verification, detection) are REFRESHED.
+ *   - User-authored keys (rules, domains, canonical_paths, accessScopes,
+ *     knownMismatches, dbAccessPattern, analytics, governance, security, team,
+ *     regression, cloud, conventions, autoLearning, verification_types,
+ *     python) are PRESERVED verbatim from the existing config.
+ *
+ * Flags:
+ *   --dry-run    Emit the diff to stdout, exit 0, never write.
+ *   (none)       Interactive: show diff, prompt for confirmation via @clack/prompts.
+ *                When stdin is not a TTY, behaves as --dry-run with a note.
+ *
+ * Exit codes:
+ *   0  success (applied, or dry-run completed)
+ *   1  missing massu.config.yaml (run `massu init`)
+ *   2  unparseable massu.config.yaml
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
+import type { AnyConfig } from '../detect/migrate.ts';
+import { copyUnknownKeys, preserveNestedSubkeys } from '../detect/passthrough.ts';
+import { buildConfigFromDetection, renderConfigYaml, writeConfigAtomic } from './init.ts';
+
+const PRESERVED_FIELDS = [
+  'rules',
+  'domains',
+  'canonical_paths',
+  'verification_types',
+  'accessScopes',
+  'knownMismatches',
+  'dbAccessPattern',
+  'analytics',
+  'governance',
+  'security',
+  'team',
+  'regression',
+  'cloud',
+  'conventions',
+  'autoLearning',
+  'python',
+  'toolPrefix',
+] as const;
+
+export interface ConfigRefreshOptions {
+  dryRun?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigRefreshResult {
+  exitCode: 0 | 1 | 2;
+  applied: boolean;
+  dryRun: boolean;
+  diff: DiffLine[];
+  message?: string;
+}
+
+export interface DiffLine {
+  kind: 'add' | 'remove' | 'change' | 'same';
+  path: string;
+  before?: unknown;
+  after?: unknown;
+}
+
+function flatten(obj: unknown, prefix = ''): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (obj === null || obj === undefined) {
+    out[prefix || '<root>'] = obj;
+    return out;
+  }
+  if (typeof obj !== 'object' || Array.isArray(obj)) {
+    out[prefix || '<root>'] = obj;
+    return out;
+  }
+  const rec = obj as Record<string, unknown>;
+  for (const [k, v] of Object.entries(rec)) {
+    const p = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      Object.assign(out, flatten(v, p));
+    } else {
+      out[p] = v;
+    }
+  }
+  return out;
+}
+
+export function computeDiff(before: AnyConfig, after: AnyConfig): DiffLine[] {
+  const b = flatten(before);
+  const a = flatten(after);
+  const keys = new Set<string>([...Object.keys(b), ...Object.keys(a)]);
+  const sorted = [...keys].sort();
+  const lines: DiffLine[] = [];
+  for (const k of sorted) {
+    const bVal = b[k];
+    const aVal = a[k];
+    const bHas = k in b;
+    const aHas = k in a;
+    if (bHas && !aHas) {
+      lines.push({ kind: 'remove', path: k, before: bVal });
+    } else if (!bHas && aHas) {
+      lines.push({ kind: 'add', path: k, after: aVal });
+    } else if (JSON.stringify(bVal) !== JSON.stringify(aVal)) {
+      lines.push({ kind: 'change', path: k, before: bVal, after: aVal });
+    }
+  }
+  return lines;
+}
+
+export function mergeRefresh(existing: AnyConfig, refreshed: AnyConfig): AnyConfig {
+  // P1-008: Start from detector output (fresh framework, paths.source, verification, detection).
+  const out: AnyConfig = { ...refreshed };
+
+  // Restore user-authored top-level sections verbatim.
+  for (const field of PRESERVED_FIELDS) {
+    if (existing[field] !== undefined) {
+      out[field] = existing[field];
+    }
+  }
+
+  // Restore toolPrefix from existing (never let detector-defaulted 'massu' overwrite a custom prefix).
+  if (typeof existing.toolPrefix === 'string' && existing.toolPrefix !== '') {
+    out.toolPrefix = existing.toolPrefix;
+  }
+
+  // For detector-owned blocks (framework, paths, project), preserve any user subkey the detector didn't emit.
+  for (const block of ['framework', 'paths', 'project'] as const) {
+    const existingBlock = existing[block];
+    const outBlock = out[block];
+    if (
+      existingBlock && typeof existingBlock === 'object' && !Array.isArray(existingBlock) &&
+      outBlock && typeof outBlock === 'object' && !Array.isArray(outBlock)
+    ) {
+      preserveNestedSubkeys(existingBlock, outBlock as Record<string, unknown>);
+    }
+  }
+
+  // Restore user-set project.root (detector at init.ts:418 always writes 'auto'; user value wins).
+  // Separated from the block loop above for readability (A-004 architecture-review follow-up).
+  const existingProject = existing.project;
+  const outProject = out.project;
+  if (
+    existingProject && typeof existingProject === 'object' && !Array.isArray(existingProject) &&
+    outProject && typeof outProject === 'object' && !Array.isArray(outProject)
+  ) {
+    const userRoot = (existingProject as Record<string, unknown>).root;
+    if (typeof userRoot === 'string' && userRoot !== '') {
+      (outProject as Record<string, unknown>).root = userRoot;
+    }
+  }
+
+  // paths.aliases is a 2-level-nested user block. Detector always writes
+  // { '@': <source-dir> }; user-authored alias map must survive. Spread user
+  // over detector so user keys win for any overlap AND user-only keys survive.
+  // (P5-002 discovery — hedge's paths.aliases['@'] was being overwritten.)
+  const existingPaths = existing.paths;
+  const outPaths = out.paths;
+  if (
+    existingPaths && typeof existingPaths === 'object' && !Array.isArray(existingPaths) &&
+    outPaths && typeof outPaths === 'object' && !Array.isArray(outPaths)
+  ) {
+    const existingAliases = (existingPaths as Record<string, unknown>).aliases;
+    const outAliases = (outPaths as Record<string, unknown>).aliases;
+    if (
+      existingAliases && typeof existingAliases === 'object' && !Array.isArray(existingAliases) &&
+      outAliases && typeof outAliases === 'object' && !Array.isArray(outAliases)
+    ) {
+      (outPaths as Record<string, unknown>).aliases = {
+        ...(outAliases as Record<string, unknown>),
+        ...(existingAliases as Record<string, unknown>),
+      };
+    } else if (existingAliases && typeof existingAliases === 'object' && !Array.isArray(existingAliases)) {
+      (outPaths as Record<string, unknown>).aliases = existingAliases;
+    }
+  }
+
+  // verification is the other 2-level-nested detector-owned block. Semantics
+  // mirror migrate.ts:132-138 buildVerificationBlock: user's custom language
+  // sections (e.g., hedge's `gateway`, `ios`, `runtime`, `web`) survive
+  // wholesale; user's command overrides on shared languages (e.g., `python`)
+  // win over detector defaults. (P5-002 discovery — hedge was losing 15
+  // verification command entries across 4 custom language sections plus
+  // having 4 python commands overwritten with detector defaults.)
+  const existingVer = existing.verification;
+  const outVer = out.verification;
+  if (
+    existingVer && typeof existingVer === 'object' && !Array.isArray(existingVer) &&
+    outVer && typeof outVer === 'object' && !Array.isArray(outVer)
+  ) {
+    const eVer = existingVer as Record<string, unknown>;
+    const oVer = outVer as Record<string, unknown>;
+    for (const lang of Object.keys(eVer)) {
+      const userLang = eVer[lang];
+      if (userLang === undefined) continue;
+      if (!(lang in oVer)) {
+        // User-custom language (no detector counterpart) → preserve wholesale.
+        oVer[lang] = userLang;
+      } else if (
+        userLang && typeof userLang === 'object' && !Array.isArray(userLang) &&
+        oVer[lang] && typeof oVer[lang] === 'object' && !Array.isArray(oVer[lang])
+      ) {
+        // Shared language → user commands win over detector defaults (spread).
+        oVer[lang] = {
+          ...(oVer[lang] as Record<string, unknown>),
+          ...(userLang as Record<string, unknown>),
+        };
+      }
+    }
+  }
+
+  // Preserve top-level user keys not handled above (mirrors P1-001 passthrough for upgrade).
+  const handledTopLevel = new Set<string>([
+    'schema_version', 'project', 'framework', 'paths', 'toolPrefix', 'verification', 'detection',
+    ...PRESERVED_FIELDS,
+  ]);
+  copyUnknownKeys(existing, out, handledTopLevel);
+
+  return out;
+}
+
+function renderDiff(diff: DiffLine[]): string {
+  if (diff.length === 0) return '(no changes)\n';
+  const lines: string[] = [];
+  for (const d of diff) {
+    if (d.kind === 'add') lines.push(`+ ${d.path}: ${JSON.stringify(d.after)}`);
+    else if (d.kind === 'remove') lines.push(`- ${d.path}: ${JSON.stringify(d.before)}`);
+    else if (d.kind === 'change') {
+      lines.push(`~ ${d.path}: ${JSON.stringify(d.before)} -> ${JSON.stringify(d.after)}`);
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
+export async function runConfigRefresh(opts: ConfigRefreshOptions = {}): Promise<ConfigRefreshResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 1, applied: false, dryRun: !!opts.dryRun, diff: [], message };
+  }
+
+  let existing: AnyConfig;
+  try {
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content);
+    if (!parsed || typeof parsed !== 'object') {
+      throw new Error('config is not a YAML object');
+    }
+    existing = parsed as AnyConfig;
+  } catch (err) {
+    const message = `Failed to parse massu.config.yaml: ${err instanceof Error ? err.message : String(err)}`;
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 2, applied: false, dryRun: !!opts.dryRun, diff: [], message };
+  }
+
+  const detection = await runDetection(cwd);
+  const refreshed = buildConfigFromDetection({
+    projectRoot: cwd,
+    detection,
+    projectName: typeof (existing.project as Record<string, unknown> | undefined)?.name === 'string'
+      ? (existing.project as Record<string, unknown>).name as string
+      : undefined,
+  });
+  // buildConfigFromDetection already stamps detection.fingerprint. Double-check.
+  if (!(refreshed.detection as Record<string, unknown> | undefined)?.fingerprint) {
+    refreshed.detection = { fingerprint: computeFingerprint(detection) };
+  }
+
+  const merged = mergeRefresh(existing, refreshed);
+  const diff = computeDiff(existing, merged);
+
+  if (opts.dryRun) {
+    log('Config diff (dry-run; no changes written):\n');
+    log(renderDiff(diff));
+    return { exitCode: 0, applied: false, dryRun: true, diff };
+  }
+
+  if (diff.length === 0) {
+    log('No changes needed — config is already up to date.\n');
+    return { exitCode: 0, applied: false, dryRun: false, diff };
+  }
+
+  // Interactive prompt; fall back to dry-run semantics when not a TTY.
+  if (!process.stdin.isTTY) {
+    log('Config diff (non-interactive; pass --dry-run to suppress this note or run interactively to apply):\n');
+    log(renderDiff(diff));
+    return {
+      exitCode: 0,
+      applied: false,
+      dryRun: false,
+      diff,
+      message: 'non-interactive shell; no changes written',
+    };
+  }
+
+  log('Config diff:\n');
+  log(renderDiff(diff));
+  const { confirm } = await import('@clack/prompts');
+  const apply = await confirm({ message: 'Apply these changes to massu.config.yaml?' });
+  if (apply !== true) {
+    log('Aborted; no changes written.\n');
+    return { exitCode: 0, applied: false, dryRun: false, diff, message: 'aborted by user' };
+  }
+
+  const yamlContent = renderConfigYaml(merged);
+  const writeRes = writeConfigAtomic(configPath, yamlContent);
+  if (!writeRes.validated) {
+    const message = `Failed to write config: ${writeRes.error}`;
+    if (!opts.silent) process.stderr.write(message + '\n');
+    return { exitCode: 2, applied: false, dryRun: false, diff, message };
+  }
+  log('Config refreshed.\n');
+  return { exitCode: 0, applied: true, dryRun: false, diff };
+}