@massu/core 1.6.3 → 1.8.0

package/dist/hooks/session-start.js

@@ -8360,14 +8360,33 @@ function domainFromWorkspace(pkg) {
     allowedImportsFrom: []
   };
 }
-function topLevelSrcSubdirs(root) {
-  const srcDir = join3(root, "src");
-  if (!existsSync5(srcDir)) return [];
-  try {
-    return readdirSync3(srcDir, { withFileTypes: true }).filter((e) => e.isDirectory() && !IGNORED_SUBDIRS.has(e.name)).map((e) => e.name).sort();
-  } catch {
-    return [];
+function topLevelSrcSubdirs(root, sourceDirs) {
+  const effective = sourceDirs.length > 0 ? sourceDirs : ["src"];
+  const seen = /* @__PURE__ */ new Set();
+  for (const rel of effective) {
+    const abs = join3(root, rel);
+    if (!existsSync5(abs)) continue;
+    try {
+      for (const e of readdirSync3(abs, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        if (IGNORED_SUBDIRS.has(e.name)) continue;
+        seen.add(e.name);
+      }
+    } catch {
+    }
+  }
+  return Array.from(seen).sort();
+}
+function flattenSourceDirs(sourceDirs) {
+  const flat = /* @__PURE__ */ new Set();
+  for (const entry of Object.values(sourceDirs)) {
+    if (!entry) continue;
+    for (const dir of entry.source_dirs) {
+      if (dir === "." || dir === "") continue;
+      flat.add(dir);
+    }
   }
+  return Array.from(flat);
 }
 function inferDomains(projectRoot, monorepo, sourceDirs) {
   const domains = [];
@@ -8376,7 +8395,8 @@ function inferDomains(projectRoot, monorepo, sourceDirs) {
       domains.push(domainFromWorkspace(pkg));
     }
   } else {
-    const subdirs = topLevelSrcSubdirs(projectRoot);
+    const flat = flattenSourceDirs(sourceDirs);
+    const subdirs = topLevelSrcSubdirs(projectRoot, flat);
     for (const s of subdirs) {
       domains.push({
         name: titleCase(s),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.6.3",
+  "version": "1.8.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

@@ -47,6 +47,12 @@ async function main(): Promise<void> {
       await runInstallCommands();
       break;
     }
+    case 'permissions': {
+      const { handlePermissionsSubcommand } = await import('./commands/permissions.ts');
+      const result = await handlePermissionsSubcommand(args.slice(1));
+      process.exit(result.exitCode);
+      return;
+    }
     case 'show-template': {
       const { runShowTemplate } = await import('./commands/show-template.ts');
       await runShowTemplate(args.slice(1));
@@ -162,12 +168,13 @@ Commands:
   init              Set up Massu AI in your project (one command, full setup)
   doctor            Check installation health
   install-hooks     Install/update Claude Code hooks
-  install-commands  Install/update slash commands
+  install-commands  Install/update slash commands (use --skip-permissions to opt out of MCP allowlist seeding)
   show-template     Print the resolved variant of a bundled template (e.g. for diffs)
   watch             Run the file-watcher daemon (auto-refresh on stack changes)
   refresh-log [N]   Show the last N watcher auto-refresh events
   validate-config   Validate massu.config.yaml (alias: config validate)
   config <sub>      Config lifecycle: refresh | validate | upgrade | doctor | check-drift
+  permissions <sub> MCP permission lifecycle: install | verify | check-drift
   adapters <sub>    Third-party adapter registry: list | refresh | search | add-local | remove-local | install | resign
 
 Options:

package/src/commands/doctor.ts

@@ -23,6 +23,7 @@ import { fileURLToPath } from 'url';
 import { parse as parseYaml } from 'yaml';
 import { getConfig, getResolvedPaths } from '../config.ts';
 import { getCurrentTier, getLicenseInfo, daysUntilExpiry } from '../license.ts';
+import { readSettingsAtPath } from '../lib/settings-local.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -103,7 +104,7 @@ function checkHooksConfig(projectRoot: string): CheckResult {
   }
 
   try {
-    const content = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const content = readSettingsAtPath(settingsPath);
     if (!content.hooks) {
       return { name: 'Hooks Config', status: 'fail', detail: 'No hooks configured. Run: npx massu install-hooks' };
     }
@@ -238,8 +239,8 @@ function checkShellHooksWired(_projectRoot: string): CheckResult {
   }
 
   try {
-    const content = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-    const hooks = content.hooks ?? {};
+    const content = readSettingsAtPath(settingsPath);
+    const hooks = (content.hooks ?? {}) as Record<string, unknown>;
     const hasSessionStart = Array.isArray(hooks.SessionStart) && hooks.SessionStart.length > 0;
     const hasPreToolUse = Array.isArray(hooks.PreToolUse) && hooks.PreToolUse.length > 0;
     if (!hasSessionStart && !hasPreToolUse) {

package/src/commands/init.ts

@@ -34,6 +34,7 @@ import { stringify as yamlStringify, parse as yamlParse } from 'yaml';
 import { backfillMemoryFiles } from '../memory-file-ingest.ts';
 import { getConfig, resetConfig } from '../config.ts';
 import { installAll } from './install-commands.ts';
+import { readSettingsLocal, writeSettingsLocalAtomic } from '../lib/settings-local.ts';
 import {
   runDetection,
   type DetectionResult,
@@ -1107,20 +1108,12 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
     claudeDirName = '.claude';
   }
   const claudeDir = resolve(projectRoot, claudeDirName);
-  const settingsPath = resolve(claudeDir, 'settings.local.json');
 
   if (!existsSync(claudeDir)) {
     mkdirSync(claudeDir, { recursive: true });
   }
 
-  let settings: Record<string, unknown> = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
-  }
+  const settings = readSettingsLocal(claudeDir);
 
   const hooksDir = resolveHooksDir();
   const hooksConfig = buildHooksConfig(hooksDir);
@@ -1134,7 +1127,7 @@ export function installHooks(projectRoot: string): { installed: boolean; count:
 
   settings.hooks = hooksConfig;
 
-  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  writeSettingsLocalAtomic(claudeDir, settings);
 
   return { installed: true, count: hookCount };
 }

package/src/commands/install-commands.ts

@@ -20,17 +20,11 @@
  */
 
 import {
-  closeSync,
   existsSync,
-  fsyncSync,
-  openSync,
   readFileSync,
-  rmSync,
-  writeSync,
   mkdirSync,
   readdirSync,
   statSync,
-  renameSync,
 } from 'fs';
 import { resolve, dirname, relative, join } from 'path';
 import { fileURLToPath } from 'url';
@@ -38,6 +32,8 @@ import { createHash } from 'crypto';
 import { getConfig } from '../config.ts';
 import type { Config } from '../config.ts';
 import { renderTemplate, MissingVariableError, TemplateParseError } from './template-engine.ts';
+import { atomicWriteFile } from '../lib/settings-local.ts';
+import { installPermissions } from '../permissions.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -131,47 +127,7 @@ export function loadManifest(claudeDir: string): Manifest {
   }
 }
 
-/**
- * Iter-7 fix: atomic file write — tmp + fsync + rename.
- *
- * Plan 3a §3 Risk #4 ("Watcher writes to .claude/ while editor has it open:
- * editors can lose changes. Mitigation: write to .massu-tmp then atomic rename")
- * AND the watcher spec doc §3 Shutdown Semantics claim ("every file op the
- * refresh issues is already atomic-rename-safe... installAll writes <path>.tmp
- * then renameSync") both demand this. Previously installAll's per-file writes
- * (lines 463/467) and saveManifest were direct `writeFileSync` calls — a
- * SIGINT/power-loss between truncate and complete-write left a partial file.
- * Now both go through this helper so the watcher's iter-6 "we don't await
- * fireRefresh because atomic-rename covers everything" decision is sound.
- *
- * Writes via openSync + writeSync + fsyncSync + closeSync + renameSync so the
- * data hits the platter before the rename. On any error, removes the tmp file.
- * Tmp filename includes process.pid to avoid clashes with concurrent installs
- * from sibling processes (e.g. a manual `npx massu config refresh` racing the
- * watcher daemon — the install-lock should prevent this, but the file-level
- * tmp name disambiguates if it ever happens).
- */
-function atomicWriteFile(targetPath: string, content: string, mode = 0o644): void {
-  const tmpPath = `${targetPath}.${process.pid}.tmp`;
-  try {
-    const fd = openSync(tmpPath, 'w', mode);
-    try {
-      const buf = Buffer.from(content, 'utf-8');
-      writeSync(fd, buf, 0, buf.length, 0);
-      fsyncSync(fd);
-    } finally {
-      closeSync(fd);
-    }
-    renameSync(tmpPath, targetPath);
-  } catch (err) {
-    if (existsSync(tmpPath)) {
-      try { rmSync(tmpPath, { force: true }); } catch { /* ignore */ }
-    }
-    throw err;
-  }
-}
-
-/** Write the manifest atomically: tempfile + fsync + renameSync. */
+/** Write the manifest atomically: tempfile + fsync + renameSync (uses shared lib/settings-local.ts:atomicWriteFile). */
 export function saveManifest(claudeDir: string, manifest: Manifest): void {
   const dir = resolve(claudeDir, '.massu');
   if (!existsSync(dir)) {
@@ -541,7 +497,15 @@ export function buildTemplateVars(): Record<string, unknown> {
   };
 }
 
-export function installCommands(projectRoot: string): InstallCommandsResult {
+export interface InstallCommandsOptions {
+  /** When true, skip seeding `mcp__massu__*` into permissions.allow. */
+  skipPermissions?: boolean;
+}
+
+export function installCommands(
+  projectRoot: string,
+  opts: InstallCommandsOptions = {},
+): InstallCommandsResult {
   const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
   const claudeDir = resolve(projectRoot, claudeDirName);
   const targetDir = resolve(claudeDir, 'commands');
@@ -559,9 +523,21 @@ export function installCommands(projectRoot: string): InstallCommandsResult {
 
   const framework = getConfig().framework;
   const templateVars = buildTemplateVars();
-  const stats = runWithManifest(claudeDir, (manifest) =>
-    syncDirectory(sourceDir, targetDir, framework, manifest, 'commands', true, templateVars),
-  );
+  const stats = runWithManifest(claudeDir, (manifest) => {
+    const syncStats = syncDirectory(
+      sourceDir,
+      targetDir,
+      framework,
+      manifest,
+      'commands',
+      true,
+      templateVars,
+    );
+    if (!opts.skipPermissions) {
+      installPermissions(claudeDir, manifest, { silent: true });
+    }
+    return syncStats;
+  });
   return { ...stats, commandsDir: targetDir };
 }
 
@@ -576,9 +552,19 @@ export interface InstallAllResult {
   totalSkipped: number;
   totalKept: number;
   claudeDir: string;
+  /** Permission-seeding outcome (undefined when --skip-permissions). */
+  permissions?: { installed: number; kept: number; skipped: number };
 }
 
-export function installAll(projectRoot: string): InstallAllResult {
+export interface InstallAllOptions {
+  /** When true, skip seeding `mcp__massu__*` into permissions.allow. */
+  skipPermissions?: boolean;
+}
+
+export function installAll(
+  projectRoot: string,
+  opts: InstallAllOptions = {},
+): InstallAllResult {
   const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
   const claudeDir = resolve(projectRoot, claudeDirName);
 
@@ -587,6 +573,7 @@ export function installAll(projectRoot: string): InstallAllResult {
   let totalUpdated = 0;
   let totalSkipped = 0;
   let totalKept = 0;
+  let permissionsResult: { installed: number; kept: number; skipped: number } | undefined;
 
   const framework = getConfig().framework;
   const templateVars = buildTemplateVars();
@@ -613,6 +600,9 @@ export function installAll(projectRoot: string): InstallAllResult {
       totalSkipped += stats.skipped;
       totalKept += stats.kept;
     }
+    if (!opts.skipPermissions) {
+      permissionsResult = installPermissions(claudeDir, manifest, { silent: true });
+    }
   });
 
   return {
@@ -622,6 +612,7 @@ export function installAll(projectRoot: string): InstallAllResult {
     totalSkipped,
     totalKept,
     claudeDir,
+    permissions: permissionsResult,
   };
 }
 
@@ -631,13 +622,14 @@ export function installAll(projectRoot: string): InstallAllResult {
 
 export async function runInstallCommands(): Promise<void> {
   const projectRoot = process.cwd();
+  const skipPermissions = process.argv.slice(2).includes('--skip-permissions');
 
   console.log('');
   console.log('Massu AI - Install Project Assets');
   console.log('==================================');
   console.log('');
 
-  const result = installAll(projectRoot);
+  const result = installAll(projectRoot, { skipPermissions });
 
   // Report per-asset-type
   for (const assetType of ASSET_TYPES) {
@@ -667,6 +659,23 @@ export async function runInstallCommands(): Promise<void> {
       `  ${result.totalKept} file(s) had local edits and were preserved (see stderr above).`,
     );
   }
+
+  // Permission seeding outcome line
+  if (skipPermissions) {
+    console.log('  Permission seeding skipped (--skip-permissions).');
+  } else if (result.permissions) {
+    if (result.permissions.installed > 0) {
+      console.log(
+        `  Wrote merged permissions block to .claude/settings.local.json (use --skip-permissions to opt out).`,
+      );
+    } else if (result.permissions.kept > 0) {
+      console.log(
+        `  MCP allowlist entry was edited by operator; preserved. Use \`npx massu permissions check-drift\` to inspect.`,
+      );
+    }
+    // skipped:1 → silent (already in sync, no operator-visible change)
+  }
+
   console.log('');
   console.log('  Restart your Claude Code session to use them.');
   console.log('');

package/src/commands/permissions.ts

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * `massu permissions <subcommand>` — MCP permission lifecycle CLI.
+ *
+ * Subcommands (each is documented at https://massu.ai/docs/reference/cli-reference):
+ *   install      Seed `mcp__massu__*` into permissions.allow + propagate global
+ *                defaultMode (idempotent, kept-because-edited preservation).
+ *   verify       Read-only check; exit 0 if all canonical entries present, else 1.
+ *   check-drift  Extended diagnostic (4 drift kinds, severity-mapped exit codes).
+ *
+ * Exit code matrix for `check-drift` (highest severity wins when multiple kinds present):
+ *   0 = clean
+ *   1 = missing-allow
+ *   2 = invalid-default-mode
+ *   3 = unknown-key
+ *   4 = strips-global-defaultmode
+ *
+ * Mirrors the existing `handleConfigSubcommand` dispatch pattern at cli.ts.
+ */
+
+import { resolve } from 'path';
+import { getConfig } from '../config.ts';
+import {
+  installPermissions,
+  verifyPermissions,
+  checkPermissionsDrift,
+  type DriftKind,
+} from '../permissions.ts';
+import { runWithManifest } from './install-commands.ts';
+
+function resolveClaudeDir(): string {
+  let claudeDirName = '.claude';
+  try {
+    claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
+  } catch {
+    claudeDirName = '.claude';
+  }
+  return resolve(process.cwd(), claudeDirName);
+}
+
+const DRIFT_KIND_EXIT_CODE: Record<DriftKind, number> = {
+  'missing-allow': 1,
+  'invalid-default-mode': 2,
+  'unknown-key': 3,
+  'strips-global-defaultmode': 4,
+};
+
+export async function handlePermissionsSubcommand(
+  args: string[],
+): Promise<{ exitCode: number }> {
+  const sub = args[0];
+
+  switch (sub) {
+    case 'install': {
+      const claudeDir = resolveClaudeDir();
+      const result = runWithManifest(claudeDir, (manifest) =>
+        installPermissions(claudeDir, manifest, { silent: false }),
+      );
+      // Final user-facing summary line on stdout
+      if (result.installed > 0) {
+        process.stdout.write(
+          'Wrote merged permissions block to .claude/settings.local.json.\n',
+        );
+      } else if (result.skipped > 0) {
+        process.stdout.write('Permissions already in sync — no changes.\n');
+      } else if (result.kept > 0) {
+        process.stdout.write(
+          'Operator-edited permissions block preserved. Run `npx massu permissions check-drift` to inspect.\n',
+        );
+      }
+      return { exitCode: 0 };
+    }
+
+    case 'verify': {
+      const claudeDir = resolveClaudeDir();
+      const { missing } = verifyPermissions(claudeDir);
+      if (missing.length === 0) {
+        process.stdout.write('All MCP allowlist entries present.\n');
+        return { exitCode: 0 };
+      }
+      for (const entry of missing) {
+        process.stderr.write(`missing: ${entry}\n`);
+      }
+      return { exitCode: 1 };
+    }
+
+    case 'check-drift': {
+      const claudeDir = resolveClaudeDir();
+      const { driftItems } = checkPermissionsDrift(claudeDir);
+      if (driftItems.length === 0) {
+        process.stdout.write('No permission drift detected.\n');
+        return { exitCode: 0 };
+      }
+      // Highest-severity kind wins for exit code
+      let highest = 0;
+      for (const item of driftItems) {
+        const code = DRIFT_KIND_EXIT_CODE[item.kind];
+        if (code > highest) highest = code;
+        process.stderr.write(
+          `drift[${item.kind}]: ${item.detail} — remediation: ${item.remediation}\n`,
+        );
+      }
+      return { exitCode: highest };
+    }
+
+    case '--help':
+    case '-h':
+    case undefined: {
+      printPermissionsHelp();
+      return { exitCode: 0 };
+    }
+
+    default: {
+      process.stderr.write(`massu: unknown permissions subcommand: ${sub}\n`);
+      printPermissionsHelp();
+      return { exitCode: 1 };
+    }
+  }
+}
+
+export function printPermissionsHelp(): void {
+  process.stdout.write(`
+massu permissions <subcommand>
+
+Subcommands:
+  install       Seed mcp__massu__* into .claude/settings.local.json's permissions.allow.
+                  Also propagates global defaultMode (from ~/.claude/settings.json) into
+                  the project-local file to prevent the merge-replacement trap (see
+                  https://massu.ai/docs/reference/cli-reference#permissions-trap).
+                  Idempotent. Preserves operator-edited values.
+
+  verify        Read-only check that all canonical MCP allowlist entries are present.
+                  Exit 0 if clean, exit 1 with one diagnostic line per missing entry.
+
+  check-drift   Extended diagnostic surfacing 4 drift kinds:
+                  - missing-allow             (exit 1) — canonical entries missing
+                  - invalid-default-mode      (exit 2) — defaultMode requires launch flag
+                  - unknown-key               (exit 3) — undocumented top-level setting
+                  - strips-global-defaultmode (exit 4) — project-local would strip global value
+
+Examples:
+  npx massu permissions install
+  npx massu permissions verify
+  npx massu permissions check-drift
+
+Documentation: https://massu.ai/docs/reference/cli-reference#massu-permissions
+`);
+}

package/src/detect/domain-inferrer.ts

@@ -67,17 +67,69 @@ function domainFromWorkspace(pkg: WorkspacePackage): DomainConfig {
   };
 }
 
-function topLevelSrcSubdirs(root: string): string[] {
-  const srcDir = join(root, 'src');
-  if (!existsSync(srcDir)) return [];
-  try {
-    return readdirSync(srcDir, { withFileTypes: true })
-      .filter((e) => e.isDirectory() && !IGNORED_SUBDIRS.has(e.name))
-      .map((e) => e.name)
-      .sort();
-  } catch {
-    return [];
+/**
+ * Enumerate domain candidates under each detected source directory.
+ *
+ * The `sourceDirs` argument is the flattened, unique list of relative
+ * source paths produced upstream by the source-dir detector
+ * (`detectSourceDirs` in `source-dir-detector.ts`). For each path that
+ * exists under `root`, this function lists immediate subdirectories as
+ * candidate domain names. Hardcoded `src/` lookup was removed (plan
+ * `plan-1.7.0-cohesive-cleanup` P-B-002) — the function now consumes
+ * the detection pipeline's output verbatim, so projects whose source
+ * lives at non-`src/` paths (e.g. `lib/`, `apps/<x>/src/`) are no
+ * longer silently dropped.
+ *
+ * Empty `sourceDirs` is treated as a legacy single-repo `src/` lookup
+ * to preserve behavior for callers that pre-date the source-dir
+ * pipeline (CLI / test harnesses that hand-wire `inferDomains`).
+ *
+ * Returns deduplicated subdir names sorted alphabetically.
+ */
+function topLevelSrcSubdirs(root: string, sourceDirs: readonly string[]): string[] {
+  const effective = sourceDirs.length > 0 ? sourceDirs : ['src'];
+  const seen = new Set<string>();
+  for (const rel of effective) {
+    const abs = join(root, rel);
+    if (!existsSync(abs)) continue;
+    try {
+      for (const e of readdirSync(abs, { withFileTypes: true })) {
+        if (!e.isDirectory()) continue;
+        if (IGNORED_SUBDIRS.has(e.name)) continue;
+        seen.add(e.name);
+      }
+    } catch {
+      // skip directories that cannot be read; do not throw.
+    }
+  }
+  return Array.from(seen).sort();
+}
+
+/**
+ * Flatten a `SourceDirMap` into a unique, deduplicated list of relative
+ * source paths across all detected languages.
+ *
+ * Drops the root sentinels `.` and `''` — those are emitted by the
+ * source-dir-detector when source files live directly at the project
+ * root (e.g. Django's `manage.py` or Swift's `Package.swift`). Treating
+ * them as enumerable source dirs causes spurious top-level directory
+ * inclusion (Tests/, Sources/, etc.), which collides with the
+ * language-fallback path in `inferDomains`. Root-source repos rely on
+ * the language-fallback path to emit `{Python}` / `{Swift}` domains,
+ * NOT a fan-out of every root subdirectory.
+ *
+ * Order is not guaranteed — callers that need determinism must sort.
+ */
+function flattenSourceDirs(sourceDirs: SourceDirMap): string[] {
+  const flat = new Set<string>();
+  for (const entry of Object.values(sourceDirs)) {
+    if (!entry) continue;
+    for (const dir of entry.source_dirs) {
+      if (dir === '.' || dir === '') continue;
+      flat.add(dir);
+    }
   }
+  return Array.from(flat);
 }
 
 /**
@@ -100,8 +152,11 @@ export function inferDomains(
       domains.push(domainFromWorkspace(pkg));
     }
   } else {
-    // Single repo: suggest one domain per top-level src/<subdir>/ if src/ exists.
-    const subdirs = topLevelSrcSubdirs(projectRoot);
+    // Single repo: suggest one domain per top-level <sourceDir>/<subdir>/ for
+    // every detected source dir (formerly hardcoded to `src/` only — see
+    // P-B-002 in plan-1.7.0-cohesive-cleanup).
+    const flat = flattenSourceDirs(sourceDirs);
+    const subdirs = topLevelSrcSubdirs(projectRoot, flat);
     for (const s of subdirs) {
       domains.push({
         name: titleCase(s),