@massu/core 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massu/core",
-  "version": "1.7.0",
+  "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/lib/settings-local.ts

@@ -0,0 +1,110 @@
+// Copyright (c) 2026 Massu. All rights reserved.
+// Licensed under BSL 1.1 - see LICENSE file for details.
+
+/**
+ * Shared IO helper for `.claude/settings.local.json` and the user-global
+ * `~/.claude/settings.json`. SSOT for read+atomic-write semantics; closes
+ * the pre-existing non-atomic-write bug at init.ts installHooks (previously
+ * used writeFileSync which was vulnerable to SIGINT-between-truncate-and-write).
+ *
+ * Three exports:
+ *   - readSettingsLocal(claudeDir): safe-parse of <claudeDir>/settings.local.json
+ *   - writeSettingsLocalAtomic(claudeDir, settings): atomic write of same
+ *   - readSettingsAtPath(absolutePath): generic safe-parse used by readSettingsLocal
+ *     AND by permissions.ts:readGlobalSettings() reading ~/.claude/settings.json
+ *
+ * Plus the atomicWriteFile primitive (moved here from install-commands.ts to
+ * centralize). All consumers — install-commands manifest save, install-commands
+ * per-file syncs, init.ts installHooks, doctor.ts hooks-config check — share
+ * this single source of truth for filesystem IO.
+ */
+
+import {
+  closeSync,
+  existsSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeSync,
+} from 'fs';
+import { dirname, resolve } from 'path';
+
+/**
+ * Atomic file write — tmp + fsync + rename. Moved from install-commands.ts so
+ * it can be reused by settings-local IO without circular import.
+ *
+ * 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.
+ */
+export 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;
+  }
+}
+
+/**
+ * Generic safe-parse of a JSON settings file. Used by readSettingsLocal
+ * (project-local) AND permissions.ts:readGlobalSettings (user-global).
+ *
+ * Returns `{}` on any failure path: missing file, unreadable, malformed JSON,
+ * non-object root. This contract lets callers do `(settings.permissions as any)`
+ * shape-checks defensively without a separate "does the file exist" pre-check.
+ */
+export function readSettingsAtPath(absolutePath: string): Record<string, unknown> {
+  if (!existsSync(absolutePath)) {
+    return {};
+  }
+  try {
+    const raw = readFileSync(absolutePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Read `<claudeDir>/settings.local.json`. Returns `{}` on missing/corrupt.
+ */
+export function readSettingsLocal(claudeDir: string): Record<string, unknown> {
+  return readSettingsAtPath(resolve(claudeDir, 'settings.local.json'));
+}
+
+/**
+ * Atomically write `<claudeDir>/settings.local.json`. Creates the parent
+ * directory if missing. JSON.stringify with 2-space indent + trailing newline
+ * (matches the existing convention in init.ts installHooks).
+ */
+export function writeSettingsLocalAtomic(
+  claudeDir: string,
+  settings: Record<string, unknown>,
+): void {
+  const targetPath = resolve(claudeDir, 'settings.local.json');
+  const dir = dirname(targetPath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const content = JSON.stringify(settings, null, 2) + '\n';
+  atomicWriteFile(targetPath, content);
+}