singular-skill 0.0.0-stage → 0.2.0

package/lib/context.js

@@ -0,0 +1,184 @@
+// lib/context.js — compose the additionalContext text and the hook JSON envelope.
+//
+//   composeContext({stack, localMatches, candidates, mode, budgetChars, loaded?, pinned?}) -> string
+//   fitLoadedText(text, reservedChars) -> {text, truncated}   (budget a skill body against the spill threshold)
+//   spillIfNeeded(text, home) -> text | short note with the spill file path (when > 9,500 chars)
+//   hookOutput(eventName, additionalContext, {systemMessage?}) -> JSON string for stdout
+//
+// The context is factual and short. It names things; it never says "you must use".
+// Format (sections omitted when empty; the first line carries the [singular] tag):
+//   [singular] Stack: <summary>
+//   Installed skills likely relevant: <name> (<why>), <name> (<why>)
+//   If one of the third-party candidates below fits the request, end your reply with exactly one line ...
+//   Third-party candidates (not loaded): <owner/repo#sha7@skill> (<installs> installs, audit <status>) — load with /singular load owner/repo@skill
+//   <notes: extra factual one-liners such as the singular command list>
+//
+// The relay instruction sits BEFORE the candidate list and names the exact line to add (measured
+// 2026-10-07: the old trailing "tell the user ... how to load it" line was relayed in 0 of 6 runs with
+// candidates); the hook additionally announces fresh candidates to the user through `systemMessage`
+// (bin/on-prompt.js), so the user learns about /singular load even when the model stays silent.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const TAG = '[singular]';
+export const SPILL_THRESHOLD = 9500;
+export const HOOK_HARD_CAP = 10000;
+export const TRUNCATION_MARKER = '\n[singular: truncated]';
+export const RELAY_LINE = 'If one of the third-party candidates below fits the request, end your reply with exactly one line `Load with /singular load <ref>` naming the single best fit; omit that line if none fits.';
+
+function fmtInstalls(n) {
+  const v = Number(n) || 0;
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(v >= 10_000_000 ? 0 : 1)}M`;
+  if (v >= 1000) return `${(v / 1000).toFixed(v >= 100_000 ? 0 : 1)}K`;
+  return String(v);
+}
+
+function skillLabel(m) {
+  const s = m && m.skill ? m.skill : m;
+  if (!s || typeof s !== 'object') return String(s ?? '');
+  return s.invocableName || (s.pluginName ? `${s.pluginName}:${s.name}` : s.name) || '';
+}
+
+function whyOf(m) {
+  if (!m || typeof m !== 'object') return '';
+  const matched = Array.isArray(m.matched) ? m.matched.filter(Boolean).slice(0, 4) : [];
+  if (matched.length) return `matches ${matched.join(', ')}`;
+  return typeof m.why === 'string' ? m.why : '';
+}
+
+/**
+ * Candidate line: owner/repo#sha7@skill (N installs, audit S) — load with /singular load owner/repo@skill
+ * The command is the short unpinned form (the first /singular load pins HEAD and records it); the
+ * `#sha7` suffix is display only, shown when a sha is already known from the cache.
+ */
+function candidateLine(c) {
+  const source = c.source ?? (c.owner && c.repo ? `${c.owner}/${c.repo}` : '');
+  const skill = c.skill ?? '';
+  if (!source || !skill) return '';
+  const sha = typeof c.sha === 'string' && /^[0-9a-f]{40}$/.test(c.sha) ? c.sha : null;
+  const display = `${source}${sha ? `#${sha.slice(0, 7)}` : ''}@${skill}`;
+  const audit = c.audit && typeof c.audit === 'object' ? c.audit.status : c.audit;
+  const auditText = audit ? `, audit ${audit}` : '';
+  return `${display} (${fmtInstalls(c.installs)} installs${auditText}) — load with /singular load ${source}@${skill}`;
+}
+
+/**
+ * Fit a loaded skill body into what remains under SPILL_THRESHOLD once `reservedChars` (the rest of
+ * the context, header and wrapper) are accounted for. Never returns more than `room` chars.
+ */
+export function fitLoadedText(text, reservedChars = 0) {
+  const s = String(text ?? '');
+  const room = SPILL_THRESHOLD - Math.max(0, Math.floor(Number(reservedChars) || 0));
+  if (s.length <= room) return { text: s, truncated: 0 };
+  const keep = Math.max(0, room - TRUNCATION_MARKER.length);
+  return { text: `${s.slice(0, keep)}${TRUNCATION_MARKER}`, truncated: s.length - keep };
+}
+
+/**
+ * @param {object} p
+ * @param {{summary?: string, tags?: string[]}|string} [p.stack]
+ * @param {{skill: object, score: number, matched: string[]}[]} [p.localMatches]
+ * @param {object[]} [p.candidates]  gated candidates: {source|owner+repo, skill, installs, sha?, audit?}
+ * @param {string} [p.mode]
+ * @param {number} [p.budgetChars]   default 2000
+ * @param {{ref: string, text: string, stripped?: string[], reason?: string}} [p.loaded]  auto-mode / pinned payload, appended last
+ * @param {string[]} [p.pinned]      installed skills the user pinned in config (one hint line)
+ * @param {string[]} [p.notes]       extra factual one-liners appended after the candidates (never dropped by the budget)
+ */
+export function composeContext({ stack, localMatches, candidates, mode = 'suggest', budgetChars = 2000, loaded, pinned, notes } = {}) {
+  const budget = Math.max(200, Math.floor(Number(budgetChars) || 2000));
+  const extra = (Array.isArray(notes) ? notes : []).map((n) => String(n ?? '').trim()).filter(Boolean);
+  const summary = typeof stack === 'string' ? stack : stack && typeof stack === 'object' ? String(stack.summary ?? '') : '';
+  const stackLine = summary.trim() ? `Stack: ${summary.trim()}` : '';
+
+  const locals = (Array.isArray(localMatches) ? localMatches : [])
+    .map((m) => {
+      const label = skillLabel(m);
+      if (!label) return '';
+      const why = whyOf(m);
+      return why ? `${label} (${why})` : label;
+    })
+    .filter(Boolean);
+
+  const pins = (Array.isArray(pinned) ? pinned : []).map((p) => String(p ?? '').trim()).filter(Boolean);
+
+  const cands = mode === 'off' || mode === 'local'
+    ? []
+    : (Array.isArray(candidates) ? candidates : []).map(candidateLine).filter(Boolean);
+
+  const build = (nLocal, nCand) => {
+    const lines = [];
+    if (stackLine) lines.push(stackLine);
+    if (pins.length) lines.push(`Pinned installed skills (user-configured, consider invoking): ${pins.join(', ')}`);
+    if (nLocal > 0) lines.push(`Installed skills likely relevant: ${locals.slice(0, nLocal).join(', ')}`);
+    if (nCand > 0) lines.push(RELAY_LINE, `Third-party candidates (not loaded): ${cands.slice(0, nCand).join('; ')}`);
+    lines.push(...extra);
+    if (lines.length === 0) return '';
+    lines[0] = `${TAG} ${lines[0]}`;
+    return lines.join('\n');
+  };
+
+  let nLocal = locals.length;
+  let nCand = cands.length;
+  let text = build(nLocal, nCand);
+  // Shrink to budget: drop candidates from the end first, then local matches, then hard-cut.
+  while (text.length > budget && (nCand > 0 || nLocal > 0)) {
+    if (nCand > 0) nCand--;
+    else nLocal--;
+    text = build(nLocal, nCand);
+  }
+  if (text.length > budget) text = `${text.slice(0, budget - 1)}…`;
+
+  if (loaded && typeof loaded === 'object' && typeof loaded.text === 'string' && loaded.text.trim()) {
+    const strippedList = Array.isArray(loaded.stripped) ? [...loaded.stripped] : [];
+    const reason = typeof loaded.reason === 'string' && loaded.reason.trim() ? loaded.reason.trim() : 'auto mode, user-configured';
+    const wrap = (body, strippedText) => {
+      const header = `Loaded third-party skill ${loaded.ref} (${reason}; text only, nothing installed).${strippedText}`;
+      return `${text ? `${text}\n` : `${TAG} `}${header}\n<singular-loaded ref="${loaded.ref}">\n${body}\n</singular-loaded>`;
+    };
+    const strippedText = () => (strippedList.length ? ` Stripped: ${strippedList.join('; ')}.` : '');
+    let block = wrap(loaded.text, strippedText());
+    if (block.length > SPILL_THRESHOLD) {
+      // Budget the skill body against the threshold; the stack / routing lines are more valuable than its tail.
+      const probe = wrap('', ` Stripped: ${[...strippedList, `truncated 99999 chars to fit the 9,500-char hook budget`].join('; ')}.`);
+      const fitted = fitLoadedText(loaded.text, probe.length);
+      if (fitted.truncated > 0) strippedList.push(`truncated ${fitted.truncated} chars to fit the 9,500-char hook budget`);
+      block = wrap(fitted.text, strippedText());
+    }
+    return block;
+  }
+  return text;
+}
+
+/**
+ * Last-resort guard: Claude Code only shows the model a 2 KB preview of hook output past 10,000
+ * chars, so anything still over SPILL_THRESHOLD (9,500) is written to $SINGULAR_HOME/spill-<ts>.md
+ * and replaced by a short note with the path. composeContext() budgets the loaded body first, so this
+ * fires only for oversized stack / routing text.
+ */
+export function spillIfNeeded(text, home) {
+  const s = String(text ?? '');
+  if (s.length <= SPILL_THRESHOLD) return s;
+  const dir = String(home || '').trim() || process.cwd();
+  const file = path.join(dir, `spill-${Date.now()}.md`);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, s);
+    return `${TAG} Context was ${s.length} chars (over singular's ${SPILL_THRESHOLD}-char threshold; Claude Code previews only 2 KB past ${HOOK_HARD_CAP}) and was written to ${file}. Read that file if the loaded skill text is needed.`;
+  } catch (err) {
+    return `${s.slice(0, SPILL_THRESHOLD - 120)}\n${TAG} [truncated: ${s.length} chars; spill to ${file} failed: ${String(err?.message ?? err).slice(0, 60)}]`;
+  }
+}
+
+/** JSON envelope Claude Code expects on a hook's stdout. `systemMessage` (optional) is shown to the user. */
+export function hookOutput(eventName, additionalContext, extra = {}) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: String(eventName),
+      additionalContext: String(additionalContext ?? ''),
+    },
+  };
+  if (extra && typeof extra.systemMessage === 'string' && extra.systemMessage.trim()) out.systemMessage = extra.systemMessage;
+  return JSON.stringify(out);
+}

package/lib/git.js

@@ -0,0 +1,173 @@
+// lib/git.js — the few git operations singular performs, shared by lib/refs.js, lib/registry.js and
+// lib/commands/add.js (/singular add). Zero dependencies; every call is execFile with an argument array (no shell),
+// GIT_TERMINAL_PROMPT=0, LC_ALL=C, an allowlisted child environment (childEnv), hard timeouts with SIGKILL.
+//
+//   GITHUB_BASE                         'https://github.com'
+//   gitBase(env)                        -> GITHUB_BASE, or the SINGULAR_GIT_BASE test seam (local path / file:// only)
+//   repoUrl(owner, repo, env)           -> `${gitBase}/${owner}/${repo}`
+//   childEnv(env, extra)                -> the minimal, fixed environment every git / npx child gets (allowlist, never the
+//                                          inherited env: a repository's .claude/settings.json env block reaches hook
+//                                          processes, and GIT_CONFIG_* / npm_config_* there would redirect clones and npx)
+//   describeGitFailure(what, r, ms)     -> one-line error text; credential prompts become "repository not found or private"
+//   runExecFile(impl, file, args, opts) -> Promise<{error, code, signal, killed, stdout, stderr}> (never rejects)
+//   cloneAtSha({...})                   -> fetch exactly one commit into an empty dir (init / remote add / fetch --depth 1 / checkout)
+//   findSkillDirs(root)                 -> every SKILL.md folder under root as {dir, rel, name}
+//
+// The owner/repo segments are validated by the callers (lib/refs.js grammar) before they reach an argv.
+
+import { execFile as nodeExecFile } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { seamGitBase } from './config.js';
+import { parseFrontmatter } from './skill-index.js';
+
+export const GITHUB_BASE = 'https://github.com';
+
+// The only variables a git or npx child inherits from singular's own environment. That environment is
+// untrusted (docs/security.md section 4: a repository's committed `.claude/settings.json` `env` block is
+// applied to every hook process), and git honours GIT_CONFIG_COUNT / GIT_CONFIG_KEY_n / GIT_CONFIG_VALUE_n
+// (`url.<elsewhere>.insteadOf=https://github.com/` would make a trusted ref fetch attacker-chosen text under an
+// allowlisted owner), GIT_SSL_NO_VERIFY, GIT_SSH_COMMAND, GIT_PROXY_COMMAND, GIT_EXEC_PATH, GIT_DIR, XDG_CONFIG_HOME
+// (a config file inside the repository), while npm honours npm_config_registry (`npx skills` would download and run
+// a package from an attacker registry), npm_config_cache / npm_config_userconfig, NODE_OPTIONS, NODE_PATH,
+// NODE_TLS_REJECT_UNAUTHORIZED and NODE_EXTRA_CA_CERTS / SSL_CERT_FILE (an attacker CA inside the repository).
+// None of those are copied. PATH, HOME and the proxy variables are: a proxy cannot forge a verified TLS peer, and
+// a corporate CA or registry mirror belongs in ~/.gitconfig (http.sslCAInfo) / ~/.npmrc (cafile, registry), which
+// git and npm still read from HOME.
+export const CHILD_ENV_ALLOWLIST = Object.freeze([
+  'PATH', 'HOME', 'USER', 'LOGNAME', 'LANG',
+  'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY', 'ALL_PROXY', 'http_proxy', 'https_proxy', 'no_proxy', 'all_proxy',
+  // Windows: git and node need these to start at all
+  'SYSTEMROOT', 'SystemRoot', 'SYSTEMDRIVE', 'SystemDrive', 'USERPROFILE', 'HOMEDRIVE', 'HOMEPATH', 'APPDATA', 'LOCALAPPDATA', 'PATHEXT', 'COMSPEC', 'ComSpec', 'TEMP', 'TMP',
+]);
+// What every child gets regardless of the caller: no credential prompts, stable English messages, no colour.
+export const CHILD_ENV_FIXED = Object.freeze({ GIT_TERMINAL_PROMPT: '0', LC_ALL: 'C', NO_COLOR: '1' });
+
+/**
+ * The environment for a git / npx child: the allowlisted keys of `env` (strings only), the fixed values, then
+ * `extra` (TMPDIR=<work dir>, DISABLE_TELEMETRY=1, ...). Everything else in `env` is dropped. Pure.
+ */
+export function childEnv(env = process.env, extra = {}) {
+  const out = {};
+  const src = env && typeof env === 'object' ? env : {};
+  for (const k of CHILD_ENV_ALLOWLIST) {
+    if (src[k] != null && String(src[k]) !== '') out[k] = String(src[k]);
+  }
+  return { ...out, ...CHILD_ENV_FIXED, ...extra };
+}
+// What git prints when GitHub answers a request for a missing or private repository with a credential
+// prompt (which GIT_TERMINAL_PROMPT=0 turns into an error), or when it names the condition itself.
+export const CREDENTIAL_PROMPT_RE = /could not read Username|Repository not found|Authentication failed|terminal prompts disabled|Permission denied \(publickey\)/i;
+const MAX_SKILL_MD_SCAN = 2000;
+const SKIP_DIRS = new Set(['.git', 'node_modules']);
+
+export function gitBase(env = process.env) {
+  return seamGitBase(env) ?? GITHUB_BASE;
+}
+
+export function repoUrl(owner, repo, env = process.env) {
+  return `${gitBase(env)}/${owner}/${repo}`;
+}
+
+/** Promise wrapper over an execFile-shaped function; closes the child's stdin; never rejects. */
+export function runExecFile(execFileImpl, file, args, options) {
+  return new Promise((resolve) => {
+    let done = false;
+    const finish = (error, stdout, stderr) => {
+      if (done) return;
+      done = true;
+      resolve({
+        error: error ?? null,
+        code: error ? (typeof error.code === 'number' ? error.code : null) : 0,
+        signal: error?.signal ?? null,
+        killed: Boolean(error?.killed || error?.signal),
+        stdout: String(stdout ?? ''),
+        stderr: String(stderr ?? ''),
+      });
+    };
+    let child;
+    try {
+      child = execFileImpl(file, args, options, finish);
+    } catch (err) {
+      finish(err, '', '');
+      return;
+    }
+    try {
+      child?.stdin?.end?.();
+    } catch {
+      /* ignore */
+    }
+  });
+}
+
+/**
+ * One-line description of a failed git run. A credential prompt (what GitHub does for a missing or
+ * private repository) is named as such, with the raw detail kept after it.
+ */
+export function describeGitFailure(what, r, timeoutMs) {
+  if (r.killed || r.signal) return `${what} timed out after ${timeoutMs}ms`;
+  const err = String(r.stderr ?? '').trim() || r.error?.message || '';
+  const detail = err.split('\n').filter(Boolean).slice(-2).join(' | ').slice(0, 300);
+  const code = r.code ?? r.error?.code ?? 'unknown';
+  const hint = CREDENTIAL_PROMPT_RE.test(err) ? 'repository not found or private (GitHub asked for credentials)' : '';
+  const tail = [hint, detail].filter(Boolean).join(': ');
+  return `${what} failed (exit ${code})${tail ? `: ${tail}` : ''}`;
+}
+
+/**
+ * Fetch exactly one commit of <base>/<owner>/<repo> into `dest` (an existing, empty directory), the way
+ * the skills CLI's cloneAtSha does: git init, remote add, fetch --depth 1 <sha>, checkout FETCH_HEAD.
+ * Returns {ok: true, steps} or {ok: false, step, message}. Never throws.
+ */
+export async function cloneAtSha({ owner, repo, sha, dest, timeoutMs = 90000, execFileImpl = nodeExecFile, env = process.env, tmpdir } = {}) {
+  const url = repoUrl(owner, repo, env);
+  const gitEnv = childEnv(env, tmpdir ? { TMPDIR: tmpdir } : {});
+  const steps = [
+    ['init', ['init', '-q']],
+    ['remote add', ['remote', 'add', 'origin', url]],
+    ['fetch', ['fetch', '--depth', '1', 'origin', sha]],
+    ['checkout', ['-c', 'core.symlinks=true', 'checkout', '-q', 'FETCH_HEAD']],
+  ];
+  for (const [label, args] of steps) {
+    const r = await runExecFile(execFileImpl, 'git', args, { cwd: dest, env: gitEnv, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 32 * 1024 * 1024, windowsHide: true });
+    if (r.killed) return { ok: false, step: label, message: `git ${label} timed out after ${timeoutMs}ms` };
+    if (r.error || r.code !== 0) return { ok: false, step: label, message: `${describeGitFailure(`git ${label}`, r, timeoutMs)} — could not fetch ${owner}/${repo} at ${sha}` };
+  }
+  return { ok: true, url, env: gitEnv };
+}
+
+/** Every SKILL.md under `root` (depth-limited, skipping .git/node_modules), as {dir, rel, name} sorted by rel. */
+export function findSkillDirs(root, maxDepth = 6) {
+  const out = [];
+  const stack = [{ dir: root, depth: 0 }];
+  let scanned = 0;
+  while (stack.length && scanned < MAX_SKILL_MD_SCAN) {
+    const { dir, depth } = stack.pop();
+    let ents;
+    try {
+      ents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const ent of ents) {
+      scanned++;
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (!SKIP_DIRS.has(ent.name) && depth < maxDepth) stack.push({ dir: full, depth: depth + 1 });
+        continue;
+      }
+      if (ent.isFile() && ent.name === 'SKILL.md') {
+        let name = null;
+        try {
+          name = parseFrontmatter(fs.readFileSync(full, 'utf8')).name;
+        } catch {
+          name = null;
+        }
+        out.push({ dir, rel: path.relative(root, dir) || '.', name: name ? String(name).trim() : null });
+      }
+    }
+  }
+  out.sort((a, b) => a.rel.localeCompare(b.rel));
+  return out;
+}

package/lib/inspect.js

@@ -0,0 +1,183 @@
+// lib/inspect.js — decide whether a downloaded skill folder is prose or a plugin in disguise.
+//
+//   inspectSkillFolder(dir) -> {ok: boolean, problems: string[], files: number}
+//
+// A folder copied under ~/.claude/skills becomes a `<name>@skills-dir` plugin (hooks, MCP, LSP,
+// bin/ on PATH, agents) with no trust dialog when it carries plugin components, and SKILL.md
+// frontmatter itself can grant capability (allowed-tools, hooks, context/agent, shell, paths).
+// This module only reads; it never modifies anything.
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { parseFrontmatter } from './skill-index.js';
+
+export const FORBIDDEN_DIRS = ['.claude-plugin', 'hooks', 'bin', 'monitors', 'agents', 'commands', 'scripts', '.claude'];
+export const FORBIDDEN_FILES = ['plugin.json', '.mcp.json', '.lsp.json', 'settings.json', 'hooks.json', 'marketplace.json'];
+export const FORBIDDEN_FRONTMATTER = ['hooks', 'allowed-tools', 'disallowed-tools', 'context', 'agent', 'shell', 'paths', 'model'];
+const MAX_DEPTH = 8;
+const MAX_ENTRIES = 5000;
+
+const FENCE_BANG_RE = /^\s*(`{3,}|~{3,})\s*!/;
+const AT_REF_RE = /^\s*(?:[-*+]\s+)?@[^\s@]/;
+// Raw frontmatter scan (fail closed): Claude Code 2.1.282 honours quoted (`"allowed-tools":`) and
+// uniformly indented (`  hooks:`) keys that the minimal parser above does not see as top-level.
+const RAW_CAPABILITY_KEY_RE = /^\s*["']?(hooks|allowed-tools|disallowed-tools|context|agent|shell|paths|model|user-invocable)["']?\s*:/i;
+const RAW_QUOTED_KEY_RE = /^\s*["'][^"']*["']\s*:/;
+const RAW_FLOW_RE = /^\s*[{[]/;
+const RAW_KEY_RE = /^(\s*)[A-Za-z0-9_"'][^:]*:/;
+const PLAIN_TOP_KEY_RE = /^[A-Za-z0-9_][A-Za-z0-9_.-]*\s*:(?:\s|$)/;
+
+function rel(root, p) {
+  const r = path.relative(root, p);
+  return r || '.';
+}
+
+function walk(root, problems, counters) {
+  const stack = [{ dir: root, depth: 0 }];
+  while (stack.length) {
+    const { dir, depth } = stack.pop();
+    let ents;
+    try {
+      ents = fs.readdirSync(dir, { withFileTypes: true });
+    } catch (err) {
+      problems.push(`unreadable directory ${rel(root, dir)}: ${err.code ?? err.message}`);
+      continue;
+    }
+    for (const ent of ents) {
+      if (++counters.entries > MAX_ENTRIES) {
+        problems.push(`more than ${MAX_ENTRIES} entries; inspection aborted`);
+        return;
+      }
+      const full = path.join(dir, ent.name);
+      const r = rel(root, full);
+      let lst;
+      try {
+        lst = fs.lstatSync(full);
+      } catch {
+        problems.push(`unreadable entry ${r}`);
+        continue;
+      }
+      if (lst.isSymbolicLink()) {
+        let target = '?';
+        try {
+          target = fs.readlinkSync(full);
+        } catch {
+          /* ignore */
+        }
+        problems.push(`symlink ${r} -> ${target}`);
+        continue; // never follow
+      }
+      if (lst.isDirectory()) {
+        if (ent.name === '.git') continue; // not copied by the CLI; ignore
+        if (FORBIDDEN_DIRS.includes(ent.name)) problems.push(`plugin component directory ${r}/`);
+        if (depth + 1 <= MAX_DEPTH) stack.push({ dir: full, depth: depth + 1 });
+        else problems.push(`directory nesting deeper than ${MAX_DEPTH}: ${r}`);
+        continue;
+      }
+      if (!lst.isFile()) {
+        problems.push(`special file ${r}`);
+        continue;
+      }
+      counters.files++;
+      if (FORBIDDEN_FILES.includes(ent.name)) problems.push(`plugin component file ${r}`);
+      if (lst.mode & 0o111) problems.push(`executable bit on ${r}`);
+    }
+  }
+}
+
+function inspectSkillMd(file, problems) {
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    problems.push(`SKILL.md unreadable: ${err.code ?? err.message}`);
+    return;
+  }
+  const fm = parseFrontmatter(text);
+  for (const key of Object.keys(fm.fields)) {
+    const k = key.toLowerCase();
+    if (FORBIDDEN_FRONTMATTER.includes(k)) problems.push(`frontmatter key "${key}"`);
+    if (k === 'user-invocable' && /^(false|no|off)$/i.test(String(fm.fields[key]).trim())) problems.push('frontmatter user-invocable: false');
+  }
+  const lines = fm.body.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.includes('!`')) problems.push(`inline shell (!\`) in SKILL.md line ${i + 1}`);
+    if (FENCE_BANG_RE.test(line)) problems.push(`fenced shell block (\`\`\`!) in SKILL.md line ${i + 1}`);
+    if (AT_REF_RE.test(line)) problems.push(`@-file reference in SKILL.md line ${i + 1}: ${line.trim().slice(0, 60)}`);
+  }
+  // Frontmatter lines can carry shell forms too (e.g. description: !`cmd`).
+  const fmText = text.slice(0, Math.max(0, text.length - fm.body.length));
+  if (fm.hasFrontmatter && fmText.includes('!`')) problems.push('inline shell (!`) in SKILL.md frontmatter');
+  if (fm.hasFrontmatter) scanRawFrontmatter(fmText, problems);
+}
+
+/**
+ * Line-by-line scan of the raw frontmatter block. Rejects any capability key in any spelling
+ * (quoted, indented, mixed case), any quoted key at all, any flow mapping line (`{` / `[`), and a
+ * first key that is indented: whatever the minimal parser cannot fully interpret is refused.
+ */
+export function scanRawFrontmatter(fmText, problems) {
+  const lines = String(fmText ?? '').replace(/\r\n?/g, '\n').split('\n');
+  const inner = lines.slice(1); // drop the opening ---
+  let firstKeySeen = false;
+  for (let i = 0; i < inner.length; i++) {
+    const line = inner[i];
+    const t = line.trim();
+    if (t === '---' || t === '...') break;
+    if (!t || t.startsWith('#')) continue;
+    const cap = RAW_CAPABILITY_KEY_RE.exec(line);
+    // Plain top-level keys (`hooks:` at column 0, unquoted) are already reported from the parsed fields;
+    // the raw scan adds the spellings the parser does not see (quoted, indented, mixed case).
+    if (cap && !PLAIN_TOP_KEY_RE.test(line)) {
+      const key = cap[1].toLowerCase();
+      const value = line.slice(line.indexOf(':') + 1).trim();
+      if (key === 'user-invocable') {
+        if (/^(false|no|off)$/i.test(value)) problems.push(`frontmatter user-invocable: false (raw line ${i + 1})`);
+      } else {
+        problems.push(`frontmatter key "${key}" (raw line ${i + 1})`);
+      }
+    }
+    if (RAW_QUOTED_KEY_RE.test(line)) problems.push(`frontmatter quoted key (raw line ${i + 1}): ${t.slice(0, 40)}`);
+    if (RAW_FLOW_RE.test(line)) problems.push(`frontmatter flow mapping (raw line ${i + 1}): ${t.slice(0, 40)}`);
+    const km = RAW_KEY_RE.exec(line);
+    if (km && !firstKeySeen) {
+      firstKeySeen = true;
+      if (km[1].length > 0) problems.push(`frontmatter first key is indented (raw line ${i + 1}): ${t.slice(0, 40)}`);
+    }
+  }
+}
+
+/**
+ * @param {string} dir  the skill folder (must contain SKILL.md)
+ * @returns {Promise<{ok: boolean, problems: string[], files: number}>}
+ */
+export async function inspectSkillFolder(dir) {
+  const problems = [];
+  const counters = { entries: 0, files: 0 };
+  const root = path.resolve(String(dir ?? ''));
+  let st;
+  try {
+    st = fs.lstatSync(root);
+  } catch {
+    return { ok: false, problems: [`not found: ${root}`], files: 0 };
+  }
+  if (st.isSymbolicLink()) return { ok: false, problems: [`skill folder itself is a symlink: ${root}`], files: 0 };
+  if (!st.isDirectory()) return { ok: false, problems: [`not a directory: ${root}`], files: 0 };
+
+  walk(root, problems, counters);
+
+  const skillMd = path.join(root, 'SKILL.md');
+  let skillSt = null;
+  try {
+    skillSt = fs.lstatSync(skillMd);
+  } catch {
+    skillSt = null;
+  }
+  if (!skillSt || !skillSt.isFile()) problems.push('SKILL.md missing');
+  else inspectSkillMd(skillMd, problems);
+
+  const unique = [...new Set(problems)];
+  return { ok: unique.length === 0, problems: unique, files: counters.files };
+}

package/lib/log.js

@@ -0,0 +1,67 @@
+// lib/log.js — JSON-lines logging for singular. Never writes to stdout
+// (stdout of a hook is the hook's output) and never throws.
+//
+//   log(level, msg, extra?)  -> appends {ts, level, msg, ...extra} to $SINGULAR_HOME/singular.log
+//   timer()                  -> { elapsed(): ms }
+//   logPath(env?)            -> absolute path of the log file
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { defaultHomeDir, redirectedHome } from './config.js';
+
+export const LOG_FILE = 'singular.log';
+const MAX_LOG_BYTES = 2 * 1024 * 1024; // rotate to singular.log.1 past this
+
+/** Same directory rule as lib/config.js homeDir(): SINGULAR_HOME only when absolute, else ~/.claude/singular. */
+export function logPath(env = process.env) {
+  return path.join(redirectedHome(env) ?? defaultHomeDir(env), LOG_FILE);
+}
+
+function safeExtra(extra) {
+  if (!extra || typeof extra !== 'object') return {};
+  const out = {};
+  for (const [k, v] of Object.entries(extra)) {
+    if (k === 'ts' || k === 'level' || k === 'msg') continue;
+    if (v instanceof Error) out[k] = { message: v.message, name: v.name };
+    else out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Append one JSON line to the log. `level` is free-form ("debug" | "info" | "warn" | "error").
+ * Failures (unwritable dir, disk full, cyclic extra) are swallowed.
+ */
+export function log(level, msg, extra) {
+  try {
+    const file = logPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    try {
+      const st = fs.statSync(file);
+      if (st.size > MAX_LOG_BYTES) fs.renameSync(file, `${file}.1`);
+    } catch {
+      /* no file yet */
+    }
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      pid: process.pid,
+      level: String(level ?? 'info'),
+      msg: String(msg ?? ''),
+      ...safeExtra(extra),
+    });
+    fs.appendFileSync(file, `${line}\n`);
+  } catch {
+    /* never throw from logging */
+  }
+}
+
+/** Monotonic stopwatch. */
+export function timer() {
+  const start = process.hrtime.bigint();
+  return {
+    elapsed() {
+      return Number(process.hrtime.bigint() - start) / 1e6;
+    },
+  };
+}