@massu/core 1.3.0 → 1.4.0

package/src/commands/install-commands.ts

@@ -20,9 +20,13 @@
  */
 
 import {
+  closeSync,
   existsSync,
+  fsyncSync,
+  openSync,
   readFileSync,
-  writeFileSync,
+  rmSync,
+  writeSync,
   mkdirSync,
   readdirSync,
   statSync,
@@ -33,6 +37,7 @@ import { fileURLToPath } from 'url';
 import { createHash } from 'crypto';
 import { getConfig } from '../config.ts';
 import type { Config } from '../config.ts';
+import { renderTemplate, MissingVariableError, TemplateParseError } from './template-engine.ts';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -126,17 +131,55 @@ export function loadManifest(claudeDir: string): Manifest {
   }
 }
 
-/** Write the manifest atomically: tempfile + renameSync. */
+/**
+ * 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. */
 export function saveManifest(claudeDir: string, manifest: Manifest): void {
   const dir = resolve(claudeDir, '.massu');
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
   const finalPath = resolve(dir, 'install-manifest.json');
-  const tempPath = finalPath + '.tmp';
   manifest.generatedAt = new Date().toISOString();
-  writeFileSync(tempPath, JSON.stringify(manifest, null, 2), 'utf-8');
-  renameSync(tempPath, finalPath);
+  atomicWriteFile(finalPath, JSON.stringify(manifest, null, 2));
 }
 
 function emptyManifest(): Manifest {
@@ -183,12 +226,22 @@ const PASSTHROUGH_LANG_KEYS = [
 /**
  * Choose the variant suffix for a base template name.
  *
- * Priority order (per plan §"Variant resolution algorithm"):
- *   1. `framework.primary` (or `framework.type` if primary undefined)
+ * Two-axis priority (Plan #2 P2-001 extends Plan #1's lang-only axis):
+ *   For each language `L` in priority order (primary, languages.*, passthrough.*):
+ *     a. If a sub-framework `F` is declared for L, probe `<base>.<L>-<F>.md`.
+ *     b. Probe `<base>.<L>.md` (lang-only fallback).
+ *   Then probe the unsuffixed `<base>.md`.
+ *
+ * Priority order for the language list (Plan #1):
+ *   1. `framework.primary` (or `framework.type` if primary undefined). With the
+ *      sub-framework axis, the candidate framework is the matching
+ *      `framework.languages[primary].framework` if present, else `framework.router`
+ *      / `framework.orm` / `framework.ui` heuristics, else just lang-only.
  *   2. Each declared `framework.languages.<lang>` entry with a non-empty `framework`,
- *      in YAML declaration order.
+ *      in YAML declaration order. Sub-framework = `entry.framework`.
  *   3. Passthrough fallback: well-known top-level `framework.<lang>` blocks with a
  *      non-empty `framework` field, in fixed order, excluding entries already covered.
+ *      Sub-framework = top-level block's `framework` field.
  *   4. The unsuffixed default ("").
  *
  * The function NEVER throws. It returns a discriminated union so the caller can
@@ -199,12 +252,37 @@ export function pickVariant(
   sourceDir: string,
   framework: Config['framework'],
 ): PickVariantResult {
-  const candidates: string[] = [];
+  // Build (lang, subFramework) candidate pairs in priority order. Sub-framework
+  // can be undefined — in that case only the lang-only axis is probed for that
+  // language.
+  type Candidate = { lang: string; subFramework?: string };
+  const candidates: Candidate[] = [];
+  const seenLangs = new Set<string>();
+
+  function pushCandidate(lang: string, sub: string | undefined): void {
+    if (seenLangs.has(lang)) return;
+    seenLangs.add(lang);
+    candidates.push({ lang, subFramework: sub && sub.length > 0 ? sub : undefined });
+  }
 
   // 1. framework.primary (or fall back to framework.type)
   const primary = framework.primary ?? framework.type;
   if (primary && primary !== 'multi') {
-    candidates.push(primary);
+    // Best-effort sub-framework detection for the primary lang:
+    //   - If `framework.languages[primary]` has a `framework`, use that.
+    //   - Else, fall back to top-level passthrough `framework[primary].framework`.
+    let primarySub: string | undefined;
+    if (framework.languages && framework.languages[primary]?.framework) {
+      primarySub = framework.languages[primary].framework;
+    } else {
+      const passthrough = framework as unknown as Record<string, unknown>;
+      const block = passthrough[primary];
+      if (block && typeof block === 'object') {
+        const fw = (block as { framework?: unknown }).framework;
+        if (typeof fw === 'string' && fw.length > 0) primarySub = fw;
+      }
+    }
+    pushCandidate(primary, primarySub);
   }
 
   // 2. framework.languages declaration order
@@ -212,34 +290,35 @@ export function pickVariant(
     for (const lang of Object.keys(framework.languages)) {
       const entry = framework.languages[lang];
       if (entry && typeof entry.framework === 'string' && entry.framework.length > 0) {
-        if (!candidates.includes(lang)) {
-          candidates.push(lang);
-        }
+        pushCandidate(lang, entry.framework);
       }
     }
   }
 
   // 3. Passthrough fallback — `framework.<lang>` (top-level passthrough block).
-  //    Zod's `.passthrough()` preserves these at runtime even though they are not
-  //    typed members of `Config['framework']`. Reading via a Record-shaped widening
-  //    avoids `any`/`@ts-ignore`.
   const passthrough = framework as unknown as Record<string, unknown>;
   for (const lang of PASSTHROUGH_LANG_KEYS) {
-    if (candidates.includes(lang)) continue;
+    if (seenLangs.has(lang)) continue;
     const block = passthrough[lang];
     if (block && typeof block === 'object') {
       const fw = (block as { framework?: unknown }).framework;
       if (typeof fw === 'string' && fw.length > 0) {
-        candidates.push(lang);
+        pushCandidate(lang, fw);
       }
     }
   }
 
-  // 4. Probe disk
+  // 4. Probe disk — for each (lang, sub) pair, try lang-sub first, then lang-only.
   for (const cand of candidates) {
-    const path = resolve(sourceDir, `${baseName}.${cand}.md`);
-    if (existsSync(path)) {
-      return { kind: 'hit', suffix: `.${cand}` };
+    if (cand.subFramework) {
+      const subPath = resolve(sourceDir, `${baseName}.${cand.lang}-${cand.subFramework}.md`);
+      if (existsSync(subPath)) {
+        return { kind: 'hit', suffix: `.${cand.lang}-${cand.subFramework}` };
+      }
+    }
+    const langPath = resolve(sourceDir, `${baseName}.${cand.lang}.md`);
+    if (existsSync(langPath)) {
+      return { kind: 'hit', suffix: `.${cand.lang}` };
     }
   }
   // Unsuffixed default
@@ -296,6 +375,7 @@ export function syncDirectory(
   manifest: Manifest,
   manifestKeyPrefix: string,
   topLevel: boolean = true,
+  templateVars: Record<string, unknown> = {},
 ): SyncStats {
   const stats: SyncStats = { installed: 0, updated: 0, skipped: 0, kept: 0 };
 
@@ -322,6 +402,7 @@ export function syncDirectory(
         manifest,
         subPrefix,
         false,
+        templateVars,
       );
       stats.installed += subStats.installed;
       stats.updated += subStats.updated;
@@ -360,7 +441,25 @@ export function syncDirectory(
     // Target filename is always the BASE name (variant suffix is internal to the package).
     const targetFilename = topLevel ? `${baseName}.md` : entry;
     const targetPath = resolve(targetDir, targetFilename);
-    const sourceContent = readFileSync(resolvedSourcePath, 'utf-8');
+    const rawContent = readFileSync(resolvedSourcePath, 'utf-8');
+
+    // Plan #2 P1-003: render any `{{var}}` substitutions BEFORE hashing so
+    // the manifest entry hash matches the byte-stream that lands on disk.
+    // Engine errors (missing var, malformed token) fail this single file but
+    // never abort the whole install — see spec §"Error semantics".
+    let sourceContent: string;
+    try {
+      sourceContent = renderTemplate(rawContent, templateVars);
+    } catch (err) {
+      if (err instanceof MissingVariableError || err instanceof TemplateParseError) {
+        process.stderr.write(
+          `massu: skipping ${resolvedSourcePath}: ${err.message}\n`,
+        );
+        stats.skipped++;
+        continue;
+      }
+      throw err;
+    }
     const sourceHash = hashContent(sourceContent);
 
     const manifestKey = manifestKeyPrefix === ''
@@ -403,11 +502,11 @@ export function syncDirectory(
       }
 
       // existingHash === lastInstalledHash and sourceHash differs → safe upgrade.
-      writeFileSync(targetPath, sourceContent, 'utf-8');
+      atomicWriteFile(targetPath, sourceContent);
       manifest.entries[manifestKey] = sourceHash;
       stats.updated++;
     } else {
-      writeFileSync(targetPath, sourceContent, 'utf-8');
+      atomicWriteFile(targetPath, sourceContent);
       manifest.entries[manifestKey] = sourceHash;
       stats.installed++;
     }
@@ -428,6 +527,20 @@ export interface InstallCommandsResult {
   commandsDir: string;
 }
 
+/**
+ * Build the variable scope passed to the templating engine.
+ * See spec §"Variable scope passed to the engine" for the contract.
+ */
+export function buildTemplateVars(): Record<string, unknown> {
+  const config = getConfig();
+  return {
+    framework: config.framework,
+    paths: config.paths,
+    detected: config.detected ?? {},
+    config,
+  };
+}
+
 export function installCommands(projectRoot: string): InstallCommandsResult {
   const claudeDirName = getConfig().conventions?.claudeDirName ?? '.claude';
   const claudeDir = resolve(projectRoot, claudeDirName);
@@ -445,8 +558,9 @@ 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),
+    syncDirectory(sourceDir, targetDir, framework, manifest, 'commands', true, templateVars),
   );
   return { ...stats, commandsDir: targetDir };
 }
@@ -475,6 +589,7 @@ export function installAll(projectRoot: string): InstallAllResult {
   let totalKept = 0;
 
   const framework = getConfig().framework;
+  const templateVars = buildTemplateVars();
 
   runWithManifest(claudeDir, (manifest) => {
     for (const assetType of ASSET_TYPES) {
@@ -489,6 +604,7 @@ export function installAll(projectRoot: string): InstallAllResult {
         manifest,
         assetType.targetSubdir,
         true,
+        templateVars,
       );
 
       assets[assetType.name] = stats;

package/src/commands/refresh-log.ts

@@ -0,0 +1,37 @@
+// 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/template-engine.ts

@@ -0,0 +1,260 @@
+// 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);
+      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;
+}
+
+/**
+ * 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);
+}