@notis_ai/cli 0.2.17 → 0.2.19

package/src/runtime/agent-setup.js

@@ -4,14 +4,17 @@ import {
   mkdirSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   renameSync,
   writeFileSync,
 } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
+import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { BASE_SKILL_NAMES, RETIRED_BASE_SKILL_NAMES, isBaseSkillLink } from './base-skills.js';
+
 const HERE = dirname(fileURLToPath(import.meta.url));
 const INSTRUCTIONS_PATH = join(HERE, '..', '..', 'skills', 'notis-cli', 'AGENT_INSTRUCTIONS.md');
 const HOOK_BUNDLE_PATH = join(HERE, '..', '..', 'dist', 'agent-hooks', 'notis-agent-hook.mjs');
@@ -20,6 +23,16 @@ const END_MARKER = '<!-- notis-cli:instructions:end -->';
 const LEGACY_SENTINEL = 'Use the Notis CLI (`npx --package @notis_ai/cli@latest -- notis ...`)';
 const MANAGED_HOOK_MARKER = '--notis-managed-agent-hook';
 const LEGACY_MANAGED_HOOK_MARKER = 'NOTIS_MANAGED_AGENT_HOOK=1';
+const CODEX_TRUST_START = '# notis-cli:hook-trust:start';
+const CODEX_TRUST_END = '# notis-cli:hook-trust:end';
+const CODEX_EVENT_LABELS = Object.freeze({
+  SessionStart: 'session_start',
+  UserPromptSubmit: 'user_prompt_submit',
+  Stop: 'stop',
+});
+// Recall-only hooks inject memory and never capture turns, so they run only
+// on these events.
+export const RECALL_ONLY_HOOK_EVENTS = Object.freeze(['SessionStart', 'UserPromptSubmit']);
 
 export const AGENT_IDS = Object.freeze(['codex', 'claude-code']);
 
@@ -148,7 +161,11 @@ export function installManagedHookRuntime({
   bundlePath = HOOK_BUNDLE_PATH,
   nodePath = process.execPath,
   platform = process.platform,
+  envFile = null,
 } = {}) {
+  if (envFile && (platform === 'win32' || !isAbsolute(envFile))) {
+    throw new Error('A session environment file must be an absolute POSIX path');
+  }
   const bundle = readFileSync(bundlePath);
   const digest = createHash('sha256').update(bundle).digest('hex');
   const runtimePath = join(
@@ -184,6 +201,9 @@ export function installManagedHookRuntime({
       ].join('\r\n')
     : [
         '#!/bin/sh',
+        // A hosted session's sign-in is rotated into this file while the
+        // coding agent keeps running, so each hook reads the current one.
+        ...(envFile ? [`if [ -r ${shellQuote(envFile)} ]; then . ${shellQuote(envFile)}; fi`] : []),
         `if [ -x ${shellQuote(nodePath)} ]; then`,
         `  exec ${shellQuote(nodePath)} ${shellQuote(runtimePath)} "$@"`,
         'fi',
@@ -213,10 +233,17 @@ function shellHookCommand(launcherPath, profileName, command, agentId = null, pl
   return `${quotedLauncher} ${MANAGED_HOOK_MARKER} --profile ${profileName} --timeout-ms 30000 ${command}${agentFlag}`;
 }
 
-function contextHandler(agentId, profileName, launcherPath, platform) {
+function recallOnlyHookCommand(launcherPath, stateDir) {
+  // No --profile: the hook signs in with the session's injected credential.
+  return `${shellQuote(launcherPath)} ${MANAGED_HOOK_MARKER} --timeout-ms 30000 agent-context --recall-only --state-dir ${shellQuote(stateDir)}`;
+}
+
+function contextHandler(agentId, profileName, launcherPath, platform, recallOnly = null) {
   return {
     type: 'command',
-    command: shellHookCommand(launcherPath, profileName, 'agent-context', null, platform),
+    command: recallOnly
+      ? recallOnlyHookCommand(launcherPath, recallOnly.stateDir)
+      : shellHookCommand(launcherPath, profileName, 'agent-context', null, platform),
     timeout: 30,
     statusMessage: 'Loading relevant Notis memory',
     ...(agentId === 'codex' ? { additionalContextLimit: 2500 } : {}),
@@ -239,20 +266,24 @@ function upsertPromptHooks(
   enabled,
   launcherPath = '',
   platform = process.platform,
+  recallOnly = null,
 ) {
   const settings = readJsonObject(filePath);
   const hooks = settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks)
     ? { ...settings.hooks }
     : {};
   let removedManagedHook = false;
+  const managed = [];
   for (const event of ['SessionStart', 'UserPromptSubmit', 'Stop']) {
     const previousGroups = Array.isArray(hooks[event]) ? hooks[event] : [];
     const groups = removePriorNotisPromptHooks(previousGroups);
     if (JSON.stringify(groups) !== JSON.stringify(previousGroups)) removedManagedHook = true;
-    if (enabled) {
-      groups.push({ hooks: [event === 'Stop'
+    if (enabled && (!recallOnly || RECALL_ONLY_HOOK_EVENTS.includes(event))) {
+      const handler = event === 'Stop'
         ? captureHandler(agentId, profileName, launcherPath, platform)
-        : contextHandler(agentId, profileName, launcherPath, platform)] });
+        : contextHandler(agentId, profileName, launcherPath, platform, recallOnly);
+      groups.push({ hooks: [handler] });
+      managed.push({ event, groupIndex: groups.length - 1, handlerIndex: 0, handler });
     }
     if (groups.length) hooks[event] = groups;
     else delete hooks[event];
@@ -260,15 +291,90 @@ function upsertPromptHooks(
   const next = { ...settings, hooks };
   const serialized = `${JSON.stringify(next, null, 2)}\n`;
   const existing = readText(filePath);
-  if (!enabled && !removedManagedHook) return { path: filePath, status: 'unchanged' };
-  if (existing === serialized) return { path: filePath, status: 'unchanged' };
+  if (!enabled && !removedManagedHook) return { path: filePath, status: 'unchanged', managed };
+  if (existing === serialized) return { path: filePath, status: 'unchanged', managed };
   atomicWrite(filePath, serialized);
   return {
     path: filePath,
     status: enabled
       ? existsSync(filePath) && existing ? 'updated' : 'installed'
       : 'removed',
+    managed,
+  };
+}
+
+function canonicalJson(value) {
+  if (Array.isArray(value)) return value.map(canonicalJson);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalJson(value[key])]));
+  }
+  return value;
+}
+
+/**
+ * The hash Codex records when a user trusts one hook in `/hooks`: SHA-256 of
+ * the event's normalized handler group, serialized with sorted keys. Matches
+ * the pinned Codex 0.160 app-server `hooks/list` currentHash for the handler
+ * shape this installer writes (no matcher; additionalContextLimit not hashed).
+ */
+export function codexHookTrustHash(event, handler) {
+  const label = CODEX_EVENT_LABELS[event];
+  if (!label) throw new Error(`Unsupported Codex hook event: ${event}`);
+  const normalized = {
+    type: 'command',
+    command: handler.command,
+    timeout: handler.timeout,
+    async: false,
+    ...(handler.statusMessage ? { statusMessage: handler.statusMessage } : {}),
   };
+  const digest = createHash('sha256')
+    .update(JSON.stringify(canonicalJson({ event_name: label, hooks: [normalized] })))
+    .digest('hex');
+  return `sha256:${digest}`;
+}
+
+/** The `hooks.state` key Codex uses for one handler in a hooks.json file. */
+export function codexHookTrustKey(hooksPath, event, groupIndex, handlerIndex = 0) {
+  return `${hooksPath}:${CODEX_EVENT_LABELS[event]}:${groupIndex}:${handlerIndex}`;
+}
+
+function tomlBasicString(value) {
+  return `"${String(value).replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * Record trust for the managed Codex hooks in config.toml, so a headless Codex
+ * runs them without the interactive `/hooks` review. Only the block between
+ * the managed markers is rewritten; a key the user already trusts elsewhere is
+ * left alone, because a second TOML table with the same name breaks parsing.
+ */
+export function upsertCodexHookTrust(configPath, hooksPath, managed) {
+  const existing = readText(configPath);
+  const blockPattern = new RegExp(
+    `\\n?${CODEX_TRUST_START}[\\s\\S]*?${CODEX_TRUST_END}\\n?`,
+    'g',
+  );
+  const outside = existing.replace(blockPattern, '\n');
+  const resolvedHooksPath = realpathSync(hooksPath);
+  const entries = [];
+  const skipped = [];
+  for (const item of managed) {
+    const key = codexHookTrustKey(resolvedHooksPath, item.event, item.groupIndex, item.handlerIndex);
+    const header = `[hooks.state.${tomlBasicString(key)}]`;
+    if (outside.includes(header)) {
+      skipped.push(key);
+      continue;
+    }
+    entries.push(`${header}\ntrusted_hash = ${tomlBasicString(codexHookTrustHash(item.event, item.handler))}`);
+  }
+  const prefix = outside.replace(/\n+$/, '');
+  const block = entries.length
+    ? `${CODEX_TRUST_START}\n${entries.join('\n\n')}\n${CODEX_TRUST_END}\n`
+    : '';
+  const next = prefix && block ? `${prefix}\n\n${block}` : prefix ? `${prefix}\n` : block;
+  if (next === existing) return { path: configPath, status: 'unchanged', skipped };
+  atomicWrite(configPath, next);
+  return { path: configPath, status: existing ? 'updated' : 'installed', skipped };
 }
 
 function agentPaths(agentId, home) {
@@ -336,7 +442,7 @@ export function installAgentSetup({
       result.memory_hook = { path: paths.hooks, status: 'preserved' };
     } else {
       try {
-        result.memory_hook = upsertPromptHooks(
+        const { managed: _managed, ...memoryHook } = upsertPromptHooks(
           paths.hooks,
           agentId,
           profileName,
@@ -344,6 +450,7 @@ export function installAgentSetup({
           hookRuntime?.launcherPath,
           platform,
         );
+        result.memory_hook = memoryHook;
       } catch (error) {
         result.memory_hook = {
           path: paths.hooks,
@@ -357,6 +464,56 @@ export function installAgentSetup({
   return results;
 }
 
+/**
+ * Recall-only memory hooks for a hosted coding agent (the Cloud Computer's
+ * native Codex and Claude Code). They go into the agent's own config folder
+ * (CODEX_HOME or CLAUDE_CONFIG_DIR), sign in with the session's injected
+ * credential, run only on SessionStart and UserPromptSubmit, and never capture
+ * a turn. No instruction file is written: the hosted contract already carries
+ * the Notis guidance. Codex trust is recorded so no `/hooks` review is needed.
+ */
+export function installRecallOnlyAgentHooks({
+  agentId,
+  configDir,
+  envFile = null,
+  bundlePath = HOOK_BUNDLE_PATH,
+  nodePath = process.execPath,
+  platform = process.platform,
+} = {}) {
+  if (!AGENT_IDS.includes(agentId)) throw new Error(`Unsupported agent: ${agentId}`);
+  if (platform === 'win32') throw new Error('Recall-only hooks are only supported on POSIX hosts');
+  if (typeof configDir !== 'string' || !isAbsolute(configDir)) {
+    throw new Error('Recall-only hooks need the agent config folder as an absolute path');
+  }
+  const runtime = installManagedHookRuntime({
+    home: configDir, bundlePath, nodePath, platform, envFile,
+  });
+  const hooksPath = join(configDir, agentId === 'codex' ? 'hooks.json' : 'settings.json');
+  const result = { agent: agentId, mode: 'recall_only', instructions: null, memory_hook: null };
+  try {
+    const { managed, ...memoryHook } = upsertPromptHooks(
+      hooksPath,
+      agentId,
+      null,
+      true,
+      runtime.launcherPath,
+      platform,
+      { stateDir: configDir },
+    );
+    result.memory_hook = memoryHook;
+    if (agentId === 'codex') {
+      result.hook_trust = upsertCodexHookTrust(join(configDir, 'config.toml'), hooksPath, managed);
+    }
+  } catch (error) {
+    result.memory_hook = {
+      path: hooksPath,
+      status: 'error',
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+  return result;
+}
+
 export function detectedAgentIds(home = homedir()) {
   return AGENT_IDS.filter((agentId) => {
     const root = agentPaths(agentId, home).root;
@@ -367,10 +524,12 @@ export function detectedAgentIds(home = homedir()) {
       const skillsRoot = join(root, 'skills');
       if (!existsSync(skillsRoot)) return false;
       // Base reconciliation intentionally creates every supported vendor root.
-      // A root containing only our three links is not evidence that the vendor
-      // itself is installed; any other skill entry is a genuine user signal.
-      return readdirSync(skillsRoot).some((name) => (
-        !['notis-apps', 'notis-query', 'notis-cli'].includes(name)
+      // A root containing only our base links, or the links an earlier CLI
+      // made under retired names, is not evidence that the vendor itself is
+      // installed; any other skill entry is a genuine user signal.
+      return readdirSync(skillsRoot).some((name) => !(
+        BASE_SKILL_NAMES.includes(name)
+        || (RETIRED_BASE_SKILL_NAMES.includes(name) && isBaseSkillLink(join(skillsRoot, name), name, { home }))
       ));
     } catch {
       return false;

package/src/runtime/app-boundary-validator.js

@@ -3,6 +3,7 @@ import { dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { usageError } from './errors.js';
+import { maskSerializedJsonData } from './app-data-literals.js';
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
@@ -133,10 +134,12 @@ function validateTextFile(relPath, content) {
   const extension = extname(relPath);
   const rules = getCompiledRules();
   if (extension === '.css' || extension === '.scss' || extension === '.sass' || extension === '.pcss') {
-    return applyRules(content, rules.css, relPath);
+    // A comment that mentions html, body or :root is not a selector. Blanking
+    // comments keeps offsets and line numbers; every rule still runs unchanged.
+    return applyRules(maskComments(content, '.css'), rules.css, relPath);
   }
   if (extension === '.js' || extension === '.jsx' || extension === '.ts' || extension === '.tsx') {
-    return applyRules(content, rules.javascript, relPath);
+    return applyRules(maskSerializedJsonData(content, extension), rules.javascript, relPath);
   }
   return [];
 }
@@ -181,3 +184,336 @@ export function validateArtifactBoundary(files) {
     );
   }
 }
+
+// ---------------------------------------------------------------------------
+// Design rules
+//
+// The portal boundary rules above keep an app inside its surface. The design
+// rules below keep it looking like a native, flat Notis page: no bordered
+// boxes around items, no dividers, no palette colors, no eyebrows, no loading
+// text. They are path-scoped, report line numbers, and only ever run on the
+// app's own source files (never on the bundled artifact, where every
+// dependency legitimately contains the word "border").
+//
+// The only override is an inline directive on the same line or the line
+// before the match:
+//   // notis-design-allow: <rule-id> <reason of at least N characters>
+// Allowed matches are reported with `allowed: true` so they stay visible.
+// ---------------------------------------------------------------------------
+
+export const DESIGN_RULES_PATH_CANDIDATES = [
+  resolve(moduleDir, '../../../../server/config/notis_app_design_rules.json'),
+  resolve(moduleDir, '../../config/notis_app_design_rules.json'),
+];
+
+export function resolveDesignRulesPath() {
+  for (const candidate of DESIGN_RULES_PATH_CANDIDATES) {
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return DESIGN_RULES_PATH_CANDIDATES[DESIGN_RULES_PATH_CANDIDATES.length - 1];
+}
+
+const DEFAULT_DESIGN_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.css'];
+
+function globToRegExp(glob) {
+  let source = '';
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    if (char === '*') {
+      if (glob[index + 1] === '*') {
+        index += 1;
+        if (glob[index + 1] === '/') {
+          index += 1;
+          source += '(?:.*/)?';
+        } else {
+          source += '.*';
+        }
+      } else {
+        source += '[^/]*';
+      }
+    } else if (char === '?') {
+      source += '[^/]';
+    } else {
+      source += char.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function matchesAny(relPath, globs) {
+  return (globs || []).some((glob) => globToRegExp(glob).test(relPath));
+}
+
+const REGEX_PRECEDERS = new Set(['', '(', ',', '=', ':', '[', '!', '&', '|', '?', '{', '}', ';', '+', '-', '*', '%', '>', '~', '^']);
+
+function blankRange(chars, start, end) {
+  for (let index = start; index < end; index += 1) {
+    if (chars[index] !== '\n') chars[index] = ' ';
+  }
+}
+
+/**
+ * Blank out comments so the design rules never match words inside them. Every
+ * character keeps its offset and newlines stay, so line numbers do not move.
+ * CSS has only block comments; JS and TS also have line comments. Quoted
+ * strings end at a newline so an apostrophe in JSX text cannot swallow a file,
+ * and "scheme://" is never a comment. Mirrored by mask_comments in
+ * server/lib/app_boundary_validator.py.
+ */
+export function maskComments(content, extension) {
+  const isCss = extension === '.css';
+  const chars = content.split('');
+  const length = chars.length;
+  let index = 0;
+  let previous = '';
+  while (index < length) {
+    const char = chars[index];
+    const next = chars[index + 1];
+    if (char === '/' && next === '*') {
+      const close = content.indexOf('*/', index + 2);
+      const end = close === -1 ? length : close + 2;
+      blankRange(chars, index, end);
+      index = end;
+      continue;
+    }
+    if (!isCss && char === '/' && next === '/' && !(chars[index - 1] === ':' && /[A-Za-z0-9]/.test(chars[index - 2] || ''))) {
+      let end = content.indexOf('\n', index);
+      if (end === -1) end = length;
+      blankRange(chars, index, end);
+      index = end;
+      continue;
+    }
+    if (char === '"' || char === "'" || (!isCss && char === '`')) {
+      let cursor = index + 1;
+      while (cursor < length) {
+        const inner = chars[cursor];
+        if (inner === '\\') { cursor += 2; continue; }
+        if (inner === char) { cursor += 1; break; }
+        if (inner === '\n' && char !== '`') break;
+        cursor += 1;
+      }
+      previous = char;
+      index = cursor;
+      continue;
+    }
+    if (!isCss && char === '/' && REGEX_PRECEDERS.has(previous)) {
+      let cursor = index + 1;
+      let inClass = false;
+      while (cursor < length && chars[cursor] !== '\n') {
+        const inner = chars[cursor];
+        if (inner === '\\') { cursor += 2; continue; }
+        if (inner === '[') inClass = true;
+        else if (inner === ']') inClass = false;
+        else if (inner === '/' && !inClass) { cursor += 1; break; }
+        cursor += 1;
+      }
+      previous = '/';
+      index = cursor;
+      continue;
+    }
+    if (!/\s/.test(char)) previous = char;
+    index += 1;
+  }
+  return chars.join('');
+}
+
+const compiledDesignRules = new Map();
+
+/**
+ * Load the design rules for one profile. The default profile ("app") keeps the
+ * file's top-level include/exclude. A named profile (for example "space")
+ * replaces the include with its own, adds its excludes, and turns on the rules
+ * that list it in `profiles`. Rules naming a `toolkit_piece` stay warnings until
+ * that piece appears in `toolkit_live_pieces`, then they refuse like errors.
+ */
+export function loadDesignRules({ rulesPath = resolveDesignRulesPath(), profile = 'app' } = {}) {
+  let payload = null;
+  try {
+    const parsed = JSON.parse(readFileSync(rulesPath, 'utf-8'));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      payload = parsed;
+    }
+  } catch (error) {
+    process.stderr.write(
+      `Warning: could not load Notis app design rules (${error.message}); skipping design checks.\n`,
+    );
+  }
+  if (!payload) {
+    return { profile, include: [], exclude: [], extensions: DEFAULT_DESIGN_EXTENSIONS, rules: [], allowDirective: 'notis-design-allow', allowReasonMinLength: 12 };
+  }
+  const profiles = payload.profiles && typeof payload.profiles === 'object' && !Array.isArray(payload.profiles) ? payload.profiles : {};
+  const selected = profile !== 'app' && profiles[profile] && typeof profiles[profile] === 'object' ? profiles[profile] : null;
+  const baseInclude = Array.isArray(payload.include) ? payload.include : ['app/**', 'components/**'];
+  const baseExclude = Array.isArray(payload.exclude) ? payload.exclude : [];
+  const livePieces = new Set(Array.isArray(payload.toolkit_live_pieces) ? payload.toolkit_live_pieces : []);
+  return {
+    profile,
+    include: Array.isArray(selected?.include) ? selected.include : baseInclude,
+    exclude: [...baseExclude, ...(Array.isArray(selected?.exclude) ? selected.exclude : [])],
+    extensions: Array.isArray(payload.extensions) ? payload.extensions : DEFAULT_DESIGN_EXTENSIONS,
+    allowDirective: typeof payload.allow_directive === 'string' ? payload.allow_directive : 'notis-design-allow',
+    allowReasonMinLength: Number.isInteger(payload.allow_reason_min_length) ? payload.allow_reason_min_length : 12,
+    rules: (Array.isArray(payload.rules) ? payload.rules : [])
+      .filter((rule) => !Array.isArray(rule.profiles) || rule.profiles.includes(profile))
+      .map((rule) => ({
+        id: rule.id,
+        severity: typeof rule.toolkit_piece === 'string'
+          ? (livePieces.has(rule.toolkit_piece) ? 'error' : 'warn')
+          : rule.severity === 'warn' ? 'warn' : 'error',
+        toolkitPiece: typeof rule.toolkit_piece === 'string' ? rule.toolkit_piece : null,
+        scope: rule.scope === 'file' ? 'file' : 'line',
+        regex: new RegExp(rule.pattern, rule.scope === 'file' ? '' : 'gm'),
+        message: typeof rule.profile_messages?.[profile] === 'string' ? rule.profile_messages[profile] : rule.message,
+        include: Array.isArray(rule.include) ? rule.include : null,
+        exclude: Array.isArray(rule.exclude) ? rule.exclude : [],
+      })),
+  };
+}
+
+function getCompiledDesignRules(profile = 'app') {
+  if (!compiledDesignRules.has(profile)) {
+    compiledDesignRules.set(profile, loadDesignRules({ profile }));
+  }
+  return compiledDesignRules.get(profile);
+}
+
+function lineNumberAt(content, index) {
+  let line = 1;
+  for (let cursor = 0; cursor < index; cursor += 1) {
+    if (content.charCodeAt(cursor) === 10) line += 1;
+  }
+  return line;
+}
+
+function findAllowDirective(lines, lineNumber, ruleId, directive) {
+  const pattern = new RegExp(`${directive}:\\s*${ruleId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b\\s*(.*)$`);
+  for (const candidate of [lines[lineNumber - 1], lines[lineNumber - 2]]) {
+    if (typeof candidate !== 'string') continue;
+    const match = candidate.match(pattern);
+    if (match) {
+      return match[1].replace(/\*\/\s*}?\s*$/, '').replace(/-->\s*$/, '').trim();
+    }
+  }
+  return null;
+}
+
+export function collectDesignViolationsForFile(relPath, content, config = getCompiledDesignRules()) {
+  const normalized = relPath.split('\\').join('/');
+  if (!config.extensions.includes(extname(normalized))) return [];
+  if (!matchesAny(normalized, config.include)) return [];
+  if (matchesAny(normalized, config.exclude)) return [];
+
+  const extension = extname(normalized);
+  // Data is masked first so it can neither break a rule nor supply an allow
+  // directive; comments are masked after, for matching only, so a real
+  // directive comment is still read from `lines`.
+  const unserialized = ['.js', '.jsx', '.ts', '.tsx'].includes(extension)
+    ? maskSerializedJsonData(content, extension) : content;
+  const checked = maskComments(unserialized, extension);
+  const lines = unserialized.split('\n');
+  const violations = [];
+  for (const rule of config.rules) {
+    if (rule.include && !matchesAny(normalized, rule.include)) continue;
+    if (matchesAny(normalized, rule.exclude)) continue;
+
+    const matches = [];
+    if (rule.scope === 'file') {
+      const match = rule.regex.exec(checked);
+      if (match) matches.push(match.index);
+    } else {
+      rule.regex.lastIndex = 0;
+      let match;
+      while ((match = rule.regex.exec(checked)) !== null) {
+        matches.push(match.index);
+        if (match[0].length === 0) rule.regex.lastIndex += 1;
+      }
+    }
+
+    const seenLines = new Set();
+    for (const index of matches) {
+      const line = lineNumberAt(content, index);
+      if (seenLines.has(line)) continue;
+      seenLines.add(line);
+      const reason = findAllowDirective(lines, line, rule.id, config.allowDirective);
+      const allowed = reason !== null && reason.length >= config.allowReasonMinLength;
+      violations.push({
+        file: normalized,
+        line,
+        ruleId: rule.id,
+        severity: allowed ? 'warn' : rule.severity,
+        message: reason !== null && !allowed
+          ? `${rule.message} (a notis-design-allow directive needs a reason of at least ${config.allowReasonMinLength} characters)`
+          : rule.message,
+        allowed,
+        reason: allowed ? reason : null,
+      });
+    }
+  }
+  return violations;
+}
+
+export function collectProjectDesignViolations(projectDir, config = getCompiledDesignRules()) {
+  const files = [];
+  collectProjectFiles(projectDir, projectDir, files);
+  return files.flatMap((file) => collectDesignViolationsForFile(file.relPath, file.content, config));
+}
+
+export function collectSourceDesignViolations(files, config = getCompiledDesignRules(), { encoding = 'utf-8' } = {}) {
+  return Object.entries(files).flatMap(([relPath, rawContent]) => {
+    const content = Buffer.isBuffer(rawContent)
+      ? rawContent.toString('utf-8')
+      : typeof rawContent === 'string'
+        ? (encoding === 'base64' ? Buffer.from(rawContent, 'base64').toString('utf-8') : rawContent)
+        : String(rawContent ?? '');
+    return collectDesignViolationsForFile(relPath, content, config);
+  });
+}
+
+export function formatDesignViolation(violation) {
+  const prefix = violation.allowed ? 'allowed' : violation.severity;
+  const suffix = violation.allowed ? ` (${violation.reason})` : '';
+  return `${violation.file}:${violation.line} [${violation.ruleId}] ${prefix}: ${violation.message}${suffix}`;
+}
+
+function enforceDesign(violations, { enforce, log, subject }) {
+  const blocking = violations.filter((violation) => !violation.allowed && violation.severity === 'error');
+  const nonBlocking = violations.filter((violation) => !blocking.includes(violation));
+  if (typeof log === 'function') {
+    for (const violation of nonBlocking) log(`[design] ${formatDesignViolation(violation)}`);
+    if (!enforce) for (const violation of blocking) log(`[design] ${formatDesignViolation(violation)}`);
+  }
+  if (enforce && blocking.length > 0) {
+    throw usageError(
+      `${subject} violates the Notis ${subject === 'Space' ? 'Spaces' : 'app'} design bar (${blocking.length} issue${blocking.length === 1 ? '' : 's'}). `
+      + 'Fix each line below; the only override is an inline "// notis-design-allow: <rule-id> <reason>" comment on the line before.\n'
+      + blocking.map((violation) => `  - ${formatDesignViolation(violation)}`).join('\n'),
+    );
+  }
+  return violations;
+}
+
+/**
+ * Enforce the design rules on an app's or a Space's source tree.
+ *
+ * Returns every violation (allowed ones included) so callers can print
+ * warnings. When `enforce` is true (build, verify, screenshot, deploy) any
+ * unallowed error-severity violation aborts with a usage error that lists the
+ * exact file and line to fix. Dev servers pass `enforce: false` so a
+ * half-edited page still reloads. Spaces pass `profile: 'space'`.
+ */
+export function validateProjectDesign(projectDir, { enforce = true, log = null, profile = 'app' } = {}) {
+  const violations = collectProjectDesignViolations(projectDir, getCompiledDesignRules(profile));
+  return enforceDesign(violations, { enforce, log, subject: profile === 'space' ? 'Space' : 'Project' });
+}
+
+/**
+ * The same check on an in-memory source snapshot (the exact bytes a Space
+ * release uploads). The server re-runs it with the same rules file on
+ * source-verify, source-stage and source-publish.
+ */
+export function validateSourceDesign(files, { enforce = true, log = null, profile = 'space', encoding = 'utf-8' } = {}) {
+  const violations = collectSourceDesignViolations(files, getCompiledDesignRules(profile), { encoding });
+  return enforceDesign(violations, { enforce, log, subject: profile === 'space' ? 'Space' : 'Project' });
+}