@massu/core 1.10.8 → 1.12.1

package/src/commands/install-hooks.ts

@@ -1,27 +0,0 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * `massu install-hooks` — Standalone hook installation.
- *
- * Installs or updates the canonical Massu hook set in .claude/settings.local.json.
- * Count is sourced from lib/hook-registry.ts SoT; see REGISTERED_HOOKS there.
- * Uses the same logic as `massu init` but only handles hooks.
- */
-
-import { installHooks } from './init.ts';
-
-export async function runInstallHooks(): Promise<void> {
-  const projectRoot = process.cwd();
-
-  console.log('');
-  console.log('Massu AI - Hook Installation');
-  console.log('============================');
-  console.log('');
-
-  const { count } = installHooks(projectRoot);
-  console.log(`  Installed ${count} hooks in .claude/settings.local.json`);
-  console.log('');
-  console.log('Hooks will activate on your next Claude Code session.');
-  console.log('');
-}

package/src/commands/permissions.ts

@@ -1,150 +0,0 @@
-// 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/commands/refresh-log.ts

@@ -1,37 +0,0 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * `massu refresh-log [N]` — show the last N watcher auto-refresh events.
- *
- * Library discipline: returns a result object; cli.ts owns process.exit.
- */
-
-import { gitToplevel } from '../lib/gitToplevel.ts';
-import { readRefreshLog } from './watch.ts';
-
-export interface RefreshLogResult {
-  exitCode: 0 | 1;
-  message?: string;
-}
-
-export async function runRefreshLog(args: string[]): Promise<RefreshLogResult> {
-  const limitArg = args.find((a) => /^\d+$/.test(a));
-  const limit = limitArg ? Math.max(1, Math.min(1000, Number(limitArg))) : 10;
-  const root = gitToplevel(process.cwd());
-
-  const events = readRefreshLog(root, limit);
-  if (events.length === 0) {
-    process.stdout.write('massu refresh-log: no auto-refresh events recorded yet.\n');
-    return { exitCode: 0 };
-  }
-
-  for (const e of events) {
-    const from = e.fromFingerprint ? e.fromFingerprint.slice(0, 12) : 'init';
-    const to = e.toFingerprint.slice(0, 12);
-    process.stdout.write(
-      `${e.at}  ${from} -> ${to}  installed=${e.filesInstalled} updated=${e.filesUpdated} kept=${e.filesKept}\n`,
-    );
-  }
-  return { exitCode: 0 };
-}

package/src/commands/show-template.ts

@@ -1,65 +0,0 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * `massu show-template <name>` — print the resolved variant of a template.
- *
- * Used by the local-edit-protection messaging to support a workflow like:
- *
- *   diff .claude/commands/massu-scaffold-router.md \
- *        <(npx massu show-template massu-scaffold-router)
- *
- * The resolved variant honors `pickVariant` against the consumer's current
- * `massu.config.yaml`. Exits 0 on success, 1 on unknown template.
- */
-
-import { existsSync, readFileSync } from 'fs';
-import { resolve } from 'path';
-import { getConfig } from '../config.ts';
-import { pickVariant, resolveAssetDir } from './install-commands.ts';
-
-/** Strip an optional trailing `.md` extension. */
-function normalizeBaseName(input: string): string {
-  return input.endsWith('.md') ? input.slice(0, -'.md'.length) : input;
-}
-
-export async function runShowTemplate(args: string[]): Promise<void> {
-  const rawName = args[0];
-  if (!rawName) {
-    process.stderr.write('massu: show-template requires a template name\n');
-    process.stderr.write('  usage: massu show-template <name>\n');
-    process.exit(1);
-    return;
-  }
-
-  const baseName = normalizeBaseName(rawName);
-  const sourceDir = resolveAssetDir('commands');
-  if (!sourceDir) {
-    process.stderr.write('massu: could not locate the bundled commands directory\n');
-    process.exit(1);
-    return;
-  }
-
-  const framework = getConfig().framework;
-  const choice = pickVariant(baseName, sourceDir, framework);
-
-  if (choice.kind === 'miss') {
-    process.stderr.write(`massu: no template named "${baseName}" found\n`);
-    process.exit(1);
-    return;
-  }
-
-  const suffix = choice.kind === 'hit' ? choice.suffix : '';
-  const file = suffix === ''
-    ? resolve(sourceDir, `${baseName}.md`)
-    : resolve(sourceDir, `${baseName}${suffix}.md`);
-
-  if (!existsSync(file)) {
-    // Defensive: pickVariant said hit but the file isn't there.
-    process.stderr.write(`massu: resolved template "${file}" no longer exists\n`);
-    process.exit(1);
-    return;
-  }
-
-  process.stdout.write(readFileSync(file, 'utf-8'));
-}

package/src/commands/template-engine.ts

@@ -1,301 +0,0 @@
-// Copyright (c) 2026 Massu. All rights reserved.
-// Licensed under BSL 1.1 - see LICENSE file for details.
-
-/**
- * Massu codebase-aware templating engine — string substitution only.
- *
- * Grammar (the entire surface):
- *   {{path.to.var}}                       Look up + render
- *   {{path.to.var | default("fallback")}} Look up; use literal on miss
- *   \{{                                   Literal `{{` (escape)
- *
- * Hard rules (do not weaken in maintenance):
- *   - NO `eval`, `Function`, `new Function`, `vm`, `child_process`, `exec`, `spawn`.
- *   - Variable lookup uses `Object.hasOwn` ONLY — no prototype walk.
- *   - Output is NEVER re-rendered (a value containing `{{x}}` stays literal).
- *   - No HTML escaping; output is markdown.
- *   - Single linear pass; no recursion, no fixed-point loop.
- */
-
-/** Thrown when a variable is missing and no `| default("...")` was given. */
-export class MissingVariableError extends Error {
-  readonly path: string;
-  constructor(path: string) {
-    super(`Template variable not found: "${path}"`);
-    this.name = 'MissingVariableError';
-    this.path = path;
-  }
-}
-
-/** Thrown on an unbalanced or malformed template token. */
-export class TemplateParseError extends Error {
-  readonly position: number;
-  constructor(message: string, position: number) {
-    super(`Template parse error at position ${position}: ${message}`);
-    this.name = 'TemplateParseError';
-    this.position = position;
-  }
-}
-
-/**
- * Render `template` against the given variables object.
- *
- * Throws:
- *   - `MissingVariableError` if a token references a path that doesn't exist
- *     and no `default("...")` is provided.
- *   - `TemplateParseError` on unbalanced `{{` (no closing `}}`) or malformed
- *     `default(...)` syntax.
- */
-export function renderTemplate(template: string, vars: Record<string, unknown>): string {
-  const out: string[] = [];
-  const len = template.length;
-  let i = 0;
-
-  while (i < len) {
-    const ch = template[i];
-
-    // Escape sequence: \{{ → literal {{
-    if (ch === '\\' && i + 2 < len && template[i + 1] === '{' && template[i + 2] === '{') {
-      out.push('{{');
-      i += 3;
-      continue;
-    }
-
-    // Token open: {{...}}
-    if (ch === '{' && i + 1 < len && template[i + 1] === '{') {
-      const tokenStart = i;
-      const closeIdx = findTokenClose(template, i + 2);
-      if (closeIdx === -1) {
-        throw new TemplateParseError('unclosed `{{` (no matching `}}`)', tokenStart);
-      }
-      const inner = template.slice(i + 2, closeIdx);
-
-      // P-H007 (plan-stage-c-high-batch): JSX pass-through. Pattern docs
-      // contain content like `action={{ label: "X" }}` (JSX object literal)
-      // that LOOKS like a template token but isn't. Pre-fix the engine
-      // threw TemplateParseError and the WHOLE file silently failed to
-      // install. Now: detect ONLY clearly-JSX patterns (multi-line OR
-      // leading whitespace inside the braces) and emit verbatim. Everything
-      // else (including security probes, empty `{{}}`, malformed filters,
-      // invalid path characters) still goes through strict renderToken and
-      // throws — security tests still pass.
-      if (isJsxPassThrough(inner)) {
-        out.push('{{');
-        out.push(inner);
-        out.push('}}');
-        i = closeIdx + 2;
-        continue;
-      }
-
-      const rendered = renderToken(inner, vars, tokenStart);
-      out.push(rendered);
-      i = closeIdx + 2;
-      continue;
-    }
-
-    out.push(ch);
-    i++;
-  }
-
-  return out.join('');
-}
-
-/**
- * Find the closing `}}` for a token that starts at index `start` (which points
- * to the first character INSIDE the `{{`). Skips `}}` that occur inside a
- * double-quoted string literal (so `default("a }} b")` works).
- *
- * Returns the index of the first `}` of the closing `}}`, or -1 if not found.
- */
-function findTokenClose(template: string, start: number): number {
-  const len = template.length;
-  let i = start;
-  let inString = false;
-
-  while (i < len) {
-    const ch = template[i];
-
-    if (inString) {
-      if (ch === '\\' && i + 1 < len) {
-        // Skip the next char (escape sequence inside default string literal).
-        i += 2;
-        continue;
-      }
-      if (ch === '"') {
-        inString = false;
-        i++;
-        continue;
-      }
-      i++;
-      continue;
-    }
-
-    if (ch === '"') {
-      inString = true;
-      i++;
-      continue;
-    }
-
-    if (ch === '}' && i + 1 < len && template[i + 1] === '}') {
-      return i;
-    }
-
-    i++;
-  }
-
-  return -1;
-}
-
-/**
- * P-H007: Decide whether the inner text of a `{{...}}` block is a multi-line
- * JSX expression that should be emitted verbatim (NOT parsed as a Massu
- * template token).
- *
- * Detection is intentionally MINIMAL: only multi-line content passes through.
- * The original P-H007 evidence (`patterns/component-patterns.md` JSX
- * `action={{ label: "X", onClick: () => ... }}` formatted across lines)
- * IS multi-line; that is the bug class to close.
- *
- * Single-line content of EVERY shape (valid Massu vars, malformed paths,
- * empty `{{}}`, security probes like `constructor.constructor("...")()`,
- * default filters with escaped quotes) goes through the strict renderToken
- * path so all pre-existing template-engine.test.ts behavior is preserved.
- *
- * Tradeoff: single-line JSX `action={{ x: 1 }}` (rare in practice) would
- * still throw under this rule. The vast majority of JSX in shipped pattern
- * docs is multi-line, so this is the correct conservative fix.
- */
-function isJsxPassThrough(inner: string): boolean {
-  return inner.includes('\n');
-}
-
-/**
- * Render a single token (text BETWEEN `{{` and `}}`).
- * Format: `path.to.var` OR `path.to.var | default("fallback")`.
- */
-function renderToken(
-  inner: string,
-  vars: Record<string, unknown>,
-  tokenStart: number,
-): string {
-  const trimmed = inner.trim();
-  if (trimmed === '') {
-    throw new TemplateParseError('empty token `{{}}`', tokenStart);
-  }
-
-  // Split on the first unquoted `|`. Anything inside a string literal is preserved.
-  const pipeIdx = findUnquotedPipe(trimmed);
-
-  let path: string;
-  let defaultValue: string | null = null;
-
-  if (pipeIdx === -1) {
-    path = trimmed;
-  } else {
-    path = trimmed.slice(0, pipeIdx).trim();
-    const filterPart = trimmed.slice(pipeIdx + 1).trim();
-    defaultValue = parseDefaultFilter(filterPart, tokenStart);
-  }
-
-  if (!isValidPath(path)) {
-    throw new TemplateParseError(
-      `invalid variable path: "${path}" (allowed: dot-separated identifiers)`,
-      tokenStart,
-    );
-  }
-
-  const looked = lookup(vars, path);
-  if (looked === undefined) {
-    if (defaultValue !== null) return defaultValue;
-    throw new MissingVariableError(path);
-  }
-
-  return stringify(looked);
-}
-
-/**
- * Find the first `|` outside a double-quoted string literal. Returns -1 if none.
- * Backslash escapes are honored inside the string.
- */
-function findUnquotedPipe(s: string): number {
-  let inString = false;
-  for (let i = 0; i < s.length; i++) {
-    const c = s[i];
-    if (inString) {
-      if (c === '\\' && i + 1 < s.length) {
-        i++;
-        continue;
-      }
-      if (c === '"') inString = false;
-      continue;
-    }
-    if (c === '"') {
-      inString = true;
-      continue;
-    }
-    if (c === '|') return i;
-  }
-  return -1;
-}
-
-/**
- * Parse a `default("...")` filter, returning the literal string.
- * Throws `TemplateParseError` on any deviation from the grammar.
- */
-function parseDefaultFilter(filter: string, tokenStart: number): string {
-  // Must be exactly: `default(<string-literal>)`
-  const m = /^default\s*\(\s*"((?:\\.|[^"\\])*)"\s*\)\s*$/.exec(filter);
-  if (!m) {
-    throw new TemplateParseError(
-      `malformed filter: expected default("...")`,
-      tokenStart,
-    );
-  }
-  // Decode \" → ", \\ → \. Other backslashes are preserved verbatim per spec.
-  const raw = m[1];
-  return raw.replace(/\\(["\\])/g, '$1');
-}
-
-/**
- * Validate a dot-walk path: must be one or more segments, each a valid identifier.
- * Identifiers: ASCII letters, digits, underscore, hyphen; must not start with a digit.
- * Hyphens are allowed because some YAML keys (e.g., `web-source`) use them.
- */
-function isValidPath(path: string): boolean {
-  if (path.length === 0) return false;
-  const segments = path.split('.');
-  for (const seg of segments) {
-    if (seg.length === 0) return false;
-    if (!/^[A-Za-z_][A-Za-z0-9_-]*$/.test(seg)) return false;
-  }
-  return true;
-}
-
-/**
- * Walk a dot-path through `obj` using own-property lookups only. NEVER traverses
- * the prototype chain. Returns `undefined` if any segment is missing or if the
- * value at any non-leaf segment is not an object.
- */
-function lookup(obj: Record<string, unknown>, path: string): unknown {
-  const segments = path.split('.');
-  let current: unknown = obj;
-  for (const seg of segments) {
-    if (current === null || current === undefined) return undefined;
-    if (typeof current !== 'object') return undefined;
-    if (Array.isArray(current)) return undefined;
-    if (!Object.hasOwn(current as object, seg)) return undefined;
-    current = (current as Record<string, unknown>)[seg];
-  }
-  return current;
-}
-
-/**
- * Stringify a looked-up value. `undefined` is impossible at this point (caller
- * already checked). `null` becomes the literal `"null"`. Everything else uses
- * `String(value)`.
- */
-function stringify(value: unknown): string {
-  if (value === null) return 'null';
-  if (typeof value === 'string') return value;
-  return String(value);
-}