@massu/core 1.0.0 → 1.2.0

package/src/commands/config-upgrade.ts

@@ -0,0 +1,126 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu config upgrade` — migrate a v1 `massu.config.yaml` to schema_version=2.
+ *
+ * Flags:
+ *   --rollback    Restore massu.config.yaml from massu.config.yaml.bak.
+ *   --ci / --yes  Non-interactive; no prompts; detector wins on conflicts.
+ *
+ * Safety:
+ *   - Writes .bak of the original before overwriting.
+ *   - Atomic write via writeConfigAtomic (tmp + rename).
+ *   - Idempotent: running on a schema_version=2 config is a no-op.
+ *
+ * Exit codes:
+ *   0  success (migrated, rolled back, or already current)
+ *   1  config missing / rollback source missing
+ *   2  parse or write failure
+ */
+
+import { existsSync, readFileSync, writeFileSync, copyFileSync, unlinkSync } 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 { migrateV1ToV2, type AnyConfig } from '../detect/migrate.ts';
+import { renderConfigYaml, writeConfigAtomic } from './init.ts';
+
+export interface ConfigUpgradeOptions {
+  rollback?: boolean;
+  ci?: boolean;
+  cwd?: string;
+  silent?: boolean;
+}
+
+export interface ConfigUpgradeResult {
+  exitCode: 0 | 1 | 2;
+  action: 'migrated' | 'already-current' | 'rolled-back' | 'none';
+  message?: string;
+}
+
+export async function runConfigUpgrade(opts: ConfigUpgradeOptions = {}): Promise<ConfigUpgradeResult> {
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = resolve(cwd, 'massu.config.yaml');
+  const bakPath = `${configPath}.bak`;
+  const log = opts.silent ? () => {} : (s: string) => process.stdout.write(s);
+  const err = opts.silent ? () => {} : (s: string) => process.stderr.write(s);
+
+  if (opts.rollback) {
+    if (!existsSync(bakPath)) {
+      const message = `No backup found at ${bakPath}`;
+      err(message + '\n');
+      return { exitCode: 1, action: 'none', message };
+    }
+    try {
+      copyFileSync(bakPath, configPath);
+      unlinkSync(bakPath);
+      log('Config restored from backup.\n');
+      return { exitCode: 0, action: 'rolled-back' };
+    } catch (e) {
+      const message = `Rollback failed: ${e instanceof Error ? e.message : String(e)}`;
+      err(message + '\n');
+      return { exitCode: 2, action: 'none', message };
+    }
+  }
+
+  if (!existsSync(configPath)) {
+    const message = 'massu.config.yaml not found. Run: npx massu init';
+    err(message + '\n');
+    return { exitCode: 1, action: 'none', 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 (e) {
+    const message = `Failed to parse massu.config.yaml: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  const schemaVersion = existing.schema_version;
+  if (schemaVersion === 2) {
+    log('Config is already at schema_version=2; nothing to do.\n');
+    return { exitCode: 0, action: 'already-current' };
+  }
+
+  const detection = await runDetection(cwd);
+  const v2 = migrateV1ToV2(existing, detection);
+  v2.detection = {
+    ...(v2.detection as Record<string, unknown> | undefined ?? {}),
+    fingerprint: computeFingerprint(detection),
+  };
+
+  // Back up original before any write.
+  try {
+    const original = readFileSync(configPath, 'utf-8');
+    writeFileSync(bakPath, original, 'utf-8');
+  } catch (e) {
+    const message = `Failed to write backup: ${e instanceof Error ? e.message : String(e)}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  const yamlContent = renderConfigYaml(v2);
+  const writeRes = writeConfigAtomic(configPath, yamlContent);
+  if (!writeRes.validated) {
+    const message = `Failed to write upgraded config: ${writeRes.error}`;
+    err(message + '\n');
+    return { exitCode: 2, action: 'none', message };
+  }
+
+  // Non-interactive mode just proceeds; interactive mode currently has no
+  // prompt on migrate (the migrator is deterministic and always user-preserving).
+  // --ci / --yes remain accepted for script-pipeline safety.
+  void opts.ci;
+
+  log(`Config upgraded to schema_version=2. Backup saved at ${bakPath}\n`);
+  return { exitCode: 0, action: 'migrated' };
+}

package/src/commands/init.ts

@@ -40,6 +40,7 @@ import {
   type SupportedLanguage,
   type VRCommandSet,
 } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -430,6 +431,9 @@ export function buildConfigFromDetection(
     config.verification = verification;
   }
 
+  // P5-002: stamp a stack fingerprint so session-start can detect drift later.
+  config.detection = { fingerprint: computeFingerprint(detection) };
+
   // Preserve legacy `python` block for v1 consumers (domain-enforcer, etc.).
   // Per Phase 0 P1-009 (b): python legacy config coexists with languages.python.
   if (languages.includes('python')) {

package/src/detect/migrate.ts

@@ -22,6 +22,7 @@
  */
 
 import type { DetectionResult, SupportedLanguage, VRCommandSet } from './index.ts';
+import { copyUnknownKeys, preserveNestedSubkeys } from './passthrough.ts';
 
 /**
  * Shape accepted for input. We intentionally use `Record<string, unknown>`
@@ -190,6 +191,9 @@ export function migrateV1ToV2(
   if (Object.keys(languageEntries).length > 0) {
     framework.languages = languageEntries;
   }
+  // P1-004: preserve any v1Framework subkey the explicit rebuild didn't emit
+  // (e.g., hedge's `framework.{python, rust, swift, typescript}` language sub-blocks).
+  preserveNestedSubkeys(v1Framework, framework);
 
   // Paths: preserve user-set fields; fill `source` from detection if user had 'src' default.
   let pathsSource: string = typeof v1Paths.source === 'string' ? v1Paths.source : 'src';
@@ -207,16 +211,24 @@ export function migrateV1ToV2(
   for (const k of ['routers', 'routerRoot', 'pages', 'middleware', 'schema', 'components', 'hooks']) {
     if (typeof v1Paths[k] === 'string') paths[k] = v1Paths[k];
   }
+  // P1-005: preserve any v1Paths subkey the explicit rebuild didn't emit
+  // (e.g., hedge's 19 custom `paths.*` entries like adr, plans, monorepo_root).
+  preserveNestedSubkeys(v1Paths, paths);
 
   const verification = buildVerificationBlock(detection, v1Verification);
 
+  // P1-006: build project block with nested passthrough so custom subkeys
+  // (e.g., hedge's `project.description`) survive the migration.
+  const project: Record<string, unknown> = {
+    name: typeof v1Project.name === 'string' ? v1Project.name : 'my-project',
+    root: typeof v1Project.root === 'string' ? v1Project.root : 'auto',
+  };
+  preserveNestedSubkeys(v1Project, project);
+
   // Construct v2 output.
   const v2: AnyConfig = {
     schema_version: 2,
-    project: {
-      name: typeof v1Project.name === 'string' ? v1Project.name : 'my-project',
-      root: typeof v1Project.root === 'string' ? v1Project.root : 'auto',
-    },
+    project,
     framework,
     paths,
     toolPrefix: typeof v1.toolPrefix === 'string' ? v1.toolPrefix : 'massu',
@@ -229,6 +241,24 @@ export function migrateV1ToV2(
     }
   }
 
+  // P1-001: preserve any v1 top-level key not already handled by the explicit
+  // migrator. This is the generalization of PRESERVED_FIELDS — custom sections
+  // like `services`, `workflow`, `north_stars` (hedge) now pass through.
+  //
+  // `detection` is intentionally NOT in handledTopLevel: when a v2 config is
+  // fed back in (idempotence check at migrate.ts:16), the existing `detection`
+  // block round-trips via this passthrough path. It gets re-stamped with a
+  // fresh fingerprint by the caller at config-upgrade.ts:96-99 right after
+  // migrateV1ToV2 returns. Any future v2-only top-level key added here must
+  // either appear in this list (with explicit handling above) or round-trip
+  // through this passthrough — never add a v2-only key that does neither.
+  // (A-006 architecture-review follow-up.)
+  const handledTopLevel = new Set<string>([
+    'schema_version', 'project', 'framework', 'paths', 'toolPrefix',
+    'verification', 'python', ...PRESERVED_FIELDS,
+  ]);
+  copyUnknownKeys(v1, v2, handledTopLevel);
+
   // Ensure domains / rules exist as arrays (v2 requires them).
   if (!Array.isArray(v2.domains)) {
     v2.domains = [];
@@ -268,6 +298,9 @@ export function migrateV1ToV2(
     } else if (existing.orm !== undefined) {
       pythonBlock.orm = existing.orm;
     }
+    // P1-007: preserve any v1 python subkey not already handled above
+    // (e.g., `python.test_framework`, `python.database`).
+    preserveNestedSubkeys(v1.python, pythonBlock);
     v2.python = pythonBlock;
   } else if (v1.python !== undefined) {
     // Preserve even if detection didn't find python (e.g. non-monorepo-with-python).

package/src/detect/passthrough.ts

@@ -0,0 +1,108 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Shared passthrough helpers for config migration + refresh.
+ *
+ * These helpers exist to prevent the class of bug fixed in @massu/core@1.2.0
+ * (incident 2026-04-19-config-upgrade-data-loss): a hand-maintained allow-list
+ * in `migrate.ts` silently dropped any v1 top-level key not on the list, and
+ * the parallel rebuild blocks inside `framework` / `paths` / `project` /
+ * `python` did the same thing at the nested level.
+ *
+ * Both helpers are TARGET-WINS: the migrator writes the keys it actively owns,
+ * then the helper fills in everything else the user had. A user-authored value
+ * in `target` is NEVER overwritten by the source.
+ *
+ * Why two exports instead of one:
+ *   - `copyUnknownKeys` takes an explicit `handledKeys` set — used for TOP-LEVEL
+ *     passthrough where the caller enumerates the keys it migrated explicitly
+ *     (e.g., schema_version, project, framework, paths, toolPrefix, …).
+ *   - `preserveNestedSubkeys` takes no handled-set — used for NESTED passthrough
+ *     where the target block was just rebuilt, so `k in target` already skips
+ *     any key the rebuild populated. Splitting the two makes callsites
+ *     self-documenting without a verbose `new Set()` argument at every nested
+ *     call (A-002 architecture-review follow-up).
+ */
+
+/** Keys that would mutate Object.prototype if copied as own properties. Explicit
+ *  denylist defense-in-depth on top of the existing `k in target` guard and the
+ *  `yaml@2.8` parser's non-polluting behavior (S-001 security-review follow-up). */
+const UNSAFE_KEYS: ReadonlySet<string> = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Copy any key from `source` into `target` that target doesn't already have set,
+ * skipping keys listed in `handledKeys`. Target values ALWAYS win — this function
+ * never overwrites an existing target key.
+ *
+ * - If source[k] is undefined → skip (undefined is not a preservable value).
+ * - If k is an UNSAFE_KEYS entry → skip (prototype-pollution defense).
+ * - If handledKeys.has(k) → skip (caller has its own handling).
+ * - If target already owns k → skip (target wins).
+ * - Otherwise → target[k] = deepClone(source[k]).
+ *
+ * Values are DEEP-CLONED via structuredClone so that mutating the output v2
+ * object never reaches back into the v1 input (S-002 security-review follow-up).
+ * Preserves the migrator's "pure data in, pure data out" contract.
+ */
+export function copyUnknownKeys(
+  source: Record<string, unknown>,
+  target: Record<string, unknown>,
+  handledKeys: ReadonlySet<string>
+): void {
+  if (source === null || typeof source !== 'object' || Array.isArray(source)) {
+    return;
+  }
+  for (const k of Object.keys(source)) {
+    if (UNSAFE_KEYS.has(k)) continue;
+    if (source[k] === undefined) continue;
+    if (handledKeys.has(k)) continue;
+    if (Object.prototype.hasOwnProperty.call(target, k)) continue;
+    target[k] = safeClone(source[k]);
+  }
+}
+
+/**
+ * Preserve every subkey from sourceBlock into targetBlock that targetBlock
+ * doesn't already have. Target values ALWAYS win.
+ *
+ * If sourceBlock is not a plain object (string, array, null, undefined),
+ * return early — there are no subkeys to preserve. This matches the coercion
+ * semantics of `getRecord` in migrate.ts and prevents throws on loose v1 inputs
+ * like `framework: "typescript"`.
+ *
+ * Values are deep-cloned (see copyUnknownKeys); UNSAFE_KEYS are skipped.
+ */
+export function preserveNestedSubkeys(
+  sourceBlock: unknown,
+  targetBlock: Record<string, unknown>
+): void {
+  if (
+    sourceBlock === null ||
+    sourceBlock === undefined ||
+    typeof sourceBlock !== 'object' ||
+    Array.isArray(sourceBlock)
+  ) {
+    return;
+  }
+  const src = sourceBlock as Record<string, unknown>;
+  for (const k of Object.keys(src)) {
+    if (UNSAFE_KEYS.has(k)) continue;
+    if (src[k] === undefined) continue;
+    if (Object.prototype.hasOwnProperty.call(targetBlock, k)) continue;
+    targetBlock[k] = safeClone(src[k]);
+  }
+}
+
+/** structuredClone with a fallback for environments without it (Node <17). */
+function safeClone<T>(v: T): T {
+  if (typeof structuredClone === 'function') {
+    try {
+      return structuredClone(v);
+    } catch {
+      // structuredClone throws on functions, DOM nodes, etc. — YAML never produces
+      // those, but if a caller passes something exotic, fall through to shallow.
+    }
+  }
+  return v;
+}

package/src/hooks/session-start.ts

@@ -11,8 +11,11 @@
 import { getMemoryDb, getSessionSummaries, getRecentObservations, getFailedAttempts, getCrossTaskProgress, autoDetectTaskId, linkSessionToTask, createSession } from '../memory-db.ts';
 import { getConfig, getResolvedPaths } from '../config.ts';
 import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
+import { join, resolve } from 'path';
+import { parse as parseYaml } from 'yaml';
 import type Database from 'better-sqlite3';
+import { runDetection } from '../detect/index.ts';
+import { computeFingerprint } from '../detect/drift.ts';
 
 interface HookInput {
   session_id: string;
@@ -63,6 +66,12 @@ async function main(): Promise<void> {
       if (context.trim()) {
         process.stdout.write(context);
       }
+
+      // P5-001: drift banner (runs after memory context, independent of it).
+      const driftBanner = await buildDriftBanner();
+      if (driftBanner) {
+        process.stdout.write(driftBanner);
+      }
     } finally {
       db.close();
     }
@@ -244,6 +253,38 @@ function readStdin(): Promise<string> {
   });
 }
 
+/**
+ * P5-001: compare the fingerprint stored in massu.config.yaml (detection.fingerprint,
+ * stamped by init/refresh/upgrade) against a freshly-computed fingerprint. If they
+ * disagree, return a plain-text banner. Returns '' on any error or when the
+ * config has no fingerprint (back-compat with v1 configs).
+ */
+async function buildDriftBanner(): Promise<string> {
+  try {
+    const configPath = resolve(process.cwd(), 'massu.config.yaml');
+    if (!existsSync(configPath)) return '';
+    const content = readFileSync(configPath, 'utf-8');
+    const parsed = parseYaml(content) as Record<string, unknown> | null;
+    if (!parsed || typeof parsed !== 'object') return '';
+    const det = parsed.detection as Record<string, unknown> | undefined;
+    const storedFp = typeof det?.fingerprint === 'string' ? (det.fingerprint as string) : null;
+    if (!storedFp) return '';
+    const detection = await runDetection(process.cwd());
+    const currentFp = computeFingerprint(detection);
+    if (currentFp === storedFp) return '';
+    return (
+      '=== Massu Config Drift ===\n' +
+      'Detected stack has changed since last config refresh.\n' +
+      `Fingerprint:  ${storedFp.slice(0, 16)}  ->  ${currentFp.slice(0, 16)}\n` +
+      'Run: npx massu config refresh\n' +
+      '=== END ===\n'
+    );
+  } catch (_e) {
+    // Never block session start on drift-check failure.
+    return '';
+  }
+}
+
 function safeParseJson(json: string): Record<string, string> | null {
   try {
     return JSON.parse(json);