singular-skill 0.0.0-stage → 0.2.0

package/lib/commands/add.js

@@ -0,0 +1,339 @@
+// lib/commands/add.js — `singular add`: persistent, pinned install of one allowlisted skill with inspection BEFORE
+// anything lands in ~/.claude/skills.
+//
+//   node bin/singular.js add <owner/repo[#sha]@skill> [--yes] [--json]      (bin/singular.js dispatches here)
+//
+// 1. ref must match REF_RE, owner must be allowlisted, ref must not be blocked
+// 2. sha: from the ref, else `git ls-remote ... HEAD` (pin)
+// 3. refuses if ~/.claude/skills/<skill> already exists (never overwrites)
+// 4. pinned fetch into a fresh temp dir, exactly what the skills CLI's cloneAtSha does:
+//      git init && git remote add origin https://github.com/<owner>/<repo> && git fetch --depth 1 origin <sha> && git checkout FETCH_HEAD
+//    (execFile, args array, GIT_TERMINAL_PROMPT=0, no shell)
+// 5. locate the skill folder: a SKILL.md whose directory name OR frontmatter `name` equals <skill> exactly
+//    (the skills CLI matches case-insensitively; we do not, so `@DOCX` cannot install `docx`)
+// 6. `git ls-tree -r <sha> -- <skill path>`: any 120000 (symlink), 100755 (exec bit) or 160000 (submodule)
+//    entry rejects the skill before it is copied — the CLI's `fs.cp({dereference: true})` would otherwise
+//    turn a symlink to a host file into a regular file that no later inspection could see
+// 7. inspectSkillFolder(<checkout>/<skill path>) (plugin components, capability frontmatter, shell forms)
+// 8. only then: fs.cpSync(checkout -> ~/.claude/skills/<skill>) with dereference: false, errorOnExist,
+//    a snapshot diff of ~/.claude/skills (exactly one new entry: the target) and a post-copy re-inspection;
+//    any failure removes exactly the folder we created (guarded three ways; other entries that appeared
+//    meanwhile belong to someone else and are only reported) and prints REJECTED
+// 9. otherwise INSTALLED <ref> sha <sha> + audit JSON + "Run /reload-skills or start a new session"
+
+import { execFile as nodeExecFile } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+
+import { hardenEnv, homeDir, isAllowlisted, loadConfig, seamSkillsDir, tmpdirOf } from '../config.js';
+import { TAG } from '../context.js';
+import { childEnv, cloneAtSha, findSkillDirs, repoUrl, runExecFile } from '../git.js';
+import { inspectSkillFolder } from '../inspect.js';
+import { auditSkill } from '../registry.js';
+import { log, timer } from '../log.js';
+import { formatRef, parseRef, REF_RE, resolveHeadSha, unpinnedRef } from '../refs.js';
+
+export const ADD_TIMEOUT_MS = 90000;
+export const USAGE = 'usage: singular add <owner/repo[#sha]@skill> [--yes] [--json]';
+export { findSkillDirs };
+
+/** ~/.claude/skills, or the SINGULAR_SKILLS_DIR test seam (absolute, outside the project; docs/testing.md). */
+export function skillsDir(env = process.env) {
+  return seamSkillsDir(env) ?? path.join(env.HOME || os.homedir(), '.claude', 'skills');
+}
+
+const run = runExecFile;
+
+/** The CLI prints an ANSI box before the JSON; find the last parseable JSON value in stdout. (Kept for tooling.) */
+export function parseCliJson(stdout) {
+  const s = String(stdout ?? '').replace(/\x1b\[[0-9;?]*[ -/]*[@-~]/g, '');
+  const lines = s.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const t = lines[i].trim();
+    if (t !== '[' && t !== '{' && !t.startsWith('[{') && !t.startsWith('{"')) continue;
+    const chunk = lines.slice(i).join('\n').trim();
+    for (let end = chunk.length; end > 0; end--) {
+      const c = chunk[end - 1];
+      if (c !== ']' && c !== '}') continue;
+      try {
+        return JSON.parse(chunk.slice(0, end));
+      } catch {
+        /* keep shrinking */
+      }
+    }
+  }
+  return null;
+}
+
+function isBlockedRef(parsed, blockedRefs) {
+  const src = `${parsed.owner}/${parsed.repo}`.toLowerCase();
+  const full = `${src}@${parsed.skill.toLowerCase()}`;
+  for (const raw of Array.isArray(blockedRefs) ? blockedRefs : []) {
+    const e = String(raw).trim().toLowerCase().replace(/#[0-9a-f]{40}(?=@)/, '');
+    if (e && (e === full || e === src || e === parsed.owner.toLowerCase())) return true;
+  }
+  return false;
+}
+
+function recordInstall(env, entry) {
+  const file = path.join(homeDir(env), 'installed.json');
+  let map = {};
+  try {
+    map = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!map || typeof map !== 'object') map = {};
+  } catch {
+    map = {};
+  }
+  map[entry.key] = entry;
+  try {
+    fs.writeFileSync(file, `${JSON.stringify(map, null, 2)}\n`);
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Parse `git ls-tree -r` output; return entries whose mode is not a plain file (100644). */
+export function unsafeTreeEntries(lsTreeOut) {
+  const bad = [];
+  for (const line of String(lsTreeOut ?? '').split('\n')) {
+    if (!line.trim()) continue;
+    const m = /^(\d{6})\s+(\S+)\s+([0-9a-f]{40})\t(.*)$/.exec(line);
+    if (!m) {
+      bad.push({ mode: '?', path: line.slice(0, 120), why: 'unparseable ls-tree line' });
+      continue;
+    }
+    const [, mode, type, , p] = m;
+    if (mode === '120000') bad.push({ mode, path: p, why: 'symlink' });
+    else if (mode === '100755') bad.push({ mode, path: p, why: 'executable bit' });
+    else if (mode === '160000' || type === 'commit') bad.push({ mode, path: p, why: 'git submodule' });
+    else if (mode !== '100644' || type !== 'blob') bad.push({ mode, path: p, why: `unexpected mode/type ${mode} ${type}` });
+  }
+  return bad;
+}
+
+/**
+ * @returns {Promise<{status:'installed'|'rejected'|'error', ref?, sha?, path?, problems?, audit?, message, files?}>}
+ */
+export async function runAdd({ ref, env: rawEnv = process.env, deps = {}, config: cfgOverride, timeoutMs = ADD_TIMEOUT_MS } = {}) {
+  const t = timer();
+  const hardened = hardenEnv(rawEnv, { cwd: rawEnv.PWD || process.cwd() });
+  const env = hardened.env;
+  for (const w of hardened.warnings) log('warn', /TEST SEAM/.test(w) ? 'add: test seam active' : 'add: environment override ignored', { warning: w });
+  const config = cfgOverride ?? loadConfig(env);
+  const execFileImpl = deps.execFileImpl ?? nodeExecFile;
+  const gitDeps = { ...deps, env };
+  const raw = String(ref ?? '').trim();
+  if (!REF_RE.test(raw)) return { status: 'error', message: `invalid ref "${raw.slice(0, 80)}": expected owner/repo@skill or owner/repo#<40-hex-sha>@skill` };
+  const parsed = parseRef(raw);
+  if (!parsed) return { status: 'error', message: `invalid ref "${raw.slice(0, 80)}": segments must start with a letter or digit` };
+  const source = `${parsed.owner}/${parsed.repo}`;
+  if (!isAllowlisted(source, config.allowlist)) {
+    return { status: 'error', message: `REJECTED: owner "${parsed.owner}" is not allowlisted [${config.allowlist.join(', ')}]. Add it to "allowlist" in ${config.path ?? 'config.json'} if you trust it.` };
+  }
+  if (isBlockedRef(parsed, config.blockedRefs)) return { status: 'error', message: `REJECTED: ${unpinnedRef(parsed)} matches blockedRefs` };
+
+  // --- the target must not exist: checked BEFORE any network round trip (a rerun used to pay a ls-remote first)
+  const root = skillsDir(env);
+  const target = path.join(root, parsed.skill);
+  if (path.dirname(target) !== root || path.basename(target) !== parsed.skill) {
+    return { status: 'error', message: `refusing unexpected target path ${target}` };
+  }
+  let pre = null;
+  try {
+    pre = fs.lstatSync(target);
+  } catch {
+    pre = null;
+  }
+  if (pre) return { status: 'error', message: `REFUSED: ${target} already exists (${pre.isSymbolicLink() ? 'symlink' : pre.isDirectory() ? 'directory' : 'file'}). Remove it yourself first; singular never overwrites.` };
+
+  let sha = parsed.sha;
+  if (!sha) {
+    try {
+      sha = await resolveHeadSha(parsed.owner, parsed.repo, { timeoutMs: 8000 }, gitDeps);
+    } catch (err) {
+      return { status: 'error', message: `could not resolve HEAD of ${repoUrl(parsed.owner, parsed.repo, env)}: ${String(err?.message ?? err)}` };
+    }
+  }
+  const pinned = formatRef({ ...parsed, sha });
+  try {
+    fs.mkdirSync(root, { recursive: true });
+  } catch (err) {
+    return { status: 'error', message: `cannot create ${root}: ${err.message}` };
+  }
+
+  // --- pinned fetch into a temp dir (same steps as the skills CLI's cloneAtSha; lib/git.js)
+  const base = path.resolve(deps.tmpdir ?? tmpdirOf(env));
+  fs.mkdirSync(base, { recursive: true });
+  const work = fs.mkdtempSync(path.join(base, 'singular-add-'));
+  const checkout = path.join(work, 'repo');
+  fs.mkdirSync(checkout);
+  const gitEnv = childEnv(env, { TMPDIR: work });
+  const git = (args, extra = {}) => run(execFileImpl, 'git', args, { cwd: checkout, env: gitEnv, timeout: timeoutMs, killSignal: 'SIGKILL', maxBuffer: 32 * 1024 * 1024, windowsHide: true, ...extra });
+  const cleanup = () => {
+    if (work.startsWith(base + path.sep)) fs.rmSync(work, { recursive: true, force: true });
+  };
+  const fail = (message) => {
+    cleanup();
+    return { status: 'error', message };
+  };
+  try {
+    const cloned = await cloneAtSha({ owner: parsed.owner, repo: parsed.repo, sha, dest: checkout, timeoutMs, execFileImpl, env, tmpdir: work });
+    if (!cloned.ok) return fail(cloned.message);
+
+    // --- locate the skill folder (exact match on directory name or frontmatter name)
+    const all = findSkillDirs(checkout);
+    const matches = all.filter((s) => path.basename(s.dir) === parsed.skill || s.name === parsed.skill);
+    if (matches.length === 0) {
+      const label = (s) => {
+        const dir = path.basename(s.dir);
+        return s.name && s.name !== dir ? `${dir} (name: ${s.name})` : dir;
+      };
+      const names = [...new Set(all.map(label))].slice(0, 30);
+      return fail(`no skill named "${parsed.skill}" in ${source} at ${sha.slice(0, 7)} (exact, case-sensitive). Found: ${names.join(', ') || 'none'}`);
+    }
+    if (matches.length > 1) return fail(`ambiguous: ${matches.length} folders match "${parsed.skill}" in ${source}: ${matches.map((m) => m.rel).join(', ')}`);
+    const found = matches[0];
+    const relPath = found.rel === '.' ? '' : found.rel.split(path.sep).join('/');
+
+    // --- tree modes from git itself: symlinks / exec bits / submodules never reach the copy step
+    const problems = [];
+    const ls = await git(['ls-tree', '-r', 'FETCH_HEAD', '--', relPath || '.']);
+    if (ls.error || ls.code !== 0) return fail(`git ls-tree failed (exit ${ls.code ?? 'unknown'}): ${ls.stderr.trim().slice(0, 300)}`);
+    for (const e of unsafeTreeEntries(ls.stdout)) problems.push(`${e.why} in repository tree: ${e.path} (mode ${e.mode})`);
+
+    // --- folder / frontmatter / shell-form inspection on the checkout (before anything is copied)
+    const inspection = await inspectSkillFolder(found.dir);
+    problems.push(...inspection.problems);
+    if (problems.length > 0) {
+      const unique = [...new Set(problems)];
+      log('warn', 'add rejected before copy', { ref: pinned, problems: unique });
+      cleanup();
+      return {
+        status: 'rejected',
+        ref: pinned,
+        sha,
+        path: target,
+        problems: unique,
+        removed: false,
+        copied: false,
+        message: `REJECTED: ${pinned}\n  ${unique.join('\n  ')}\nNothing was written to ${root}.`,
+      };
+    }
+
+    // --- copy (no dereference; refuse to overwrite), verify exactly one new entry appeared, re-inspect
+    let before;
+    try {
+      before = new Set(fs.readdirSync(root));
+    } catch (err) {
+      return fail(`cannot read ${root}: ${err.message}`);
+    }
+    let preCopy = null;
+    try {
+      preCopy = fs.lstatSync(target);
+    } catch {
+      preCopy = null;
+    }
+    if (preCopy) return fail(`REFUSED: ${target} appeared while fetching; not touching it.`);
+    try {
+      fs.cpSync(found.dir, target, { recursive: true, dereference: false, errorOnExist: true, force: false, verbatimSymlinks: true, filter: (src) => path.basename(src) !== '.git' });
+    } catch (err) {
+      const removed = removeCreated(target, root, parsed.skill, before);
+      return fail(`copy into ${target} failed: ${err.message}${removed ? ' (partial copy removed)' : ''}`);
+    }
+    const after = new Set(fs.readdirSync(root));
+    const created = [...after].filter((n) => !before.has(n));
+    const post = await inspectSkillFolder(target);
+    let postSt = null;
+    try {
+      postSt = fs.lstatSync(target);
+    } catch {
+      postSt = null;
+    }
+    const postProblems = [...post.problems];
+    if (!postSt || postSt.isSymbolicLink() || !postSt.isDirectory()) postProblems.unshift(`${target} is not a plain directory after the copy`);
+    if (created.length !== 1 || created[0] !== parsed.skill) postProblems.unshift(`expected exactly one new entry (${parsed.skill}) in ${root}, got: ${created.join(', ') || 'none'}`);
+    if (postProblems.length > 0) {
+      // Only the folder this run wrote is removed. fs.cpSync writes into `target` and nowhere else, so any other
+      // entry that appeared meanwhile belongs to a concurrent writer (another install tool, a sync) and is left
+      // alone; it is named in the problems so the user can look at it.
+      const removed = removeCreated(target, root, parsed.skill, before);
+      const others = created.filter((n) => n !== parsed.skill);
+      if (others.length) postProblems.push(`other entries appeared in ${root} during the copy and were left untouched (not created by singular): ${others.join(', ')}`);
+      log('warn', 'add rejected after copy', { ref: pinned, problems: postProblems, removed });
+      cleanup();
+      return {
+        status: 'rejected',
+        ref: pinned,
+        sha,
+        path: target,
+        problems: postProblems,
+        removed,
+        copied: true,
+        message: `REJECTED: ${pinned}\n  ${postProblems.join('\n  ')}\n${removed ? `Removed ${target}.` : `WARNING: ${target} was NOT removed; inspect it manually.`}`,
+      };
+    }
+
+    cleanup();
+    const audit = await auditSkill(source, parsed.skill, { timeoutMs: 5000 }, gitDeps);
+    recordInstall(env, { key: unpinnedRef(parsed), ref: pinned, sha, path: target, ts: Date.now(), audit: audit.status, files: post.files, sourcePath: relPath || '.' });
+    log('info', 'add installed', { ref: pinned, path: target, audit: audit.status, ms: Math.round(t.elapsed()) });
+    const auditJson = JSON.stringify({ status: audit.status, providers: audit.providers }, null, 2);
+    return {
+      status: 'installed',
+      ref: pinned,
+      sha,
+      path: target,
+      files: post.files,
+      audit,
+      message: `INSTALLED ${pinned} sha ${sha}\n  path: ${target} (${post.files} files, inspected before and after the copy: clean)\n  source: ${source} ${relPath || '.'}\n  audit: ${auditJson.replace(/\n/g, '\n  ')}\nRun /reload-skills or start a new session to use it.`,
+    };
+  } catch (err) {
+    cleanup();
+    return { status: 'error', message: `add failed: ${String(err?.message ?? err)}` };
+  }
+}
+
+/** Remove exactly the folder this run created: it must sit directly under root, be named after the skill, and not have existed before. */
+function removeCreated(target, root, skill, before) {
+  if (path.dirname(target) !== root || path.basename(target) !== skill || !target.startsWith(root + path.sep) || before.has(skill)) return false;
+  try {
+    fs.rmSync(target, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function confirm(question) {
+  if (!process.stdin.isTTY) return false;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise((resolve) => rl.question(question, resolve));
+  rl.close();
+  return /^y(es)?$/i.test(String(answer).trim());
+}
+
+/** `singular add <ref> [--yes] [--json]`: returns the exit code (0 only when INSTALLED). */
+export async function main(argv = process.argv.slice(2)) {
+  const json = argv.includes('--json');
+  const yes = argv.includes('--yes') || argv.includes('-y');
+  const positional = argv.filter((a) => !a.startsWith('-'));
+  if (argv.includes('--help') || argv.includes('-h') || positional.length !== 1) {
+    process.stderr.write(`${USAGE}\n`);
+    return positional.length === 1 ? 0 : 1;
+  }
+  const ref = positional[0];
+  if (!yes) {
+    const parsed = REF_RE.test(ref) ? parseRef(ref) : null;
+    const ok = await confirm(`${TAG} install ${ref} into ${skillsDir()}${parsed ? `/${parsed.skill}` : ''} (pinned, inspected before it is copied)? [y/N] `);
+    if (!ok) {
+      process.stderr.write(`${TAG} not installed (pass --yes to skip this prompt; non-interactive runs require it)\n`);
+      return 1;
+    }
+  }
+  const result = await runAdd({ ref, env: process.env });
+  if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  else process.stdout.write(`${result.message}\n`);
+  return result.status === 'installed' ? 0 : 1;
+}

package/lib/commands/find.js

@@ -0,0 +1,195 @@
+// lib/commands/find.js — `singular find`: search skills.sh for a query, apply the same gates as the hook, print a table.
+//
+//   node bin/singular.js find "<query>" [--limit N] [--all] [--json] [--cwd <dir>]      (bin/singular.js dispatches here)
+//
+// Prints installed skills that already match (local index), then gated third-party candidates
+//   ref  installs  audit  allowlisted?
+// and the rejected count grouped by reason (--all lists every rejected entry). Never installs.
+//
+// This is the ONE path that sends prompt-derived text to skills.sh: the user typed the query on purpose,
+// so the joined keywords go out as `q=` (one request) in addition to the cached owner catalogs.
+
+import path from 'node:path';
+
+import { hardenEnv, loadConfig } from '../config.js';
+import { TAG } from '../context.js';
+import { log } from '../log.js';
+import { discover, rankCandidates } from '../registry.js';
+import { isWeakMatch, scoreSkills } from '../score.js';
+import { buildIndex } from '../skill-index.js';
+import { detectStack } from '../stack.js';
+
+export const FIND_TIMEOUT_MS = 15000;
+export const USAGE = 'usage: singular find "<query>" [--limit N] [--all] [--json] [--cwd <dir>]';
+const OWNER_REJECTION_RE = /^owner (\S+) not allowlisted$/;
+
+function fmtInstalls(n) {
+  const v = Number(n) || 0;
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1000) return `${(v / 1000).toFixed(v >= 100_000 ? 0 : 1)}K`;
+  return String(v);
+}
+
+function pad(s, n) {
+  const t = String(s ?? '');
+  return t.length >= n ? t : t + ' '.repeat(n - t.length);
+}
+
+export function parseArgs(argv) {
+  const out = { query: [], limit: 10, all: false, json: false, cwd: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--limit') out.limit = Math.max(1, Math.min(50, Number(argv[++i]) || 10));
+    else if (a === '--all') out.all = true;
+    else if (a === '--json') out.json = true;
+    else if (a === '--cwd') out.cwd = argv[++i] ?? null;
+    else if (a === '--help' || a === '-h') out.help = true;
+    else out.query.push(a);
+  }
+  out.query = out.query.join(' ').trim();
+  return out;
+}
+
+/**
+ * Rank the rejected entries by the same relevance score the accepted ones get (installs alone put
+ * `frontend-design (already installed)` on top of every query) and name the best allowlist-only
+ * rejection explicitly, so the model can quote it instead of inferring an owner from an unrelated row.
+ */
+export function rankRejected(rejected, keywords, { prompt, stackTags } = {}) {
+  const list = Array.isArray(rejected) ? rejected : [];
+  const ranked = rankCandidates(list.map((r) => r.cand), keywords, { prompt, stackTags });
+  const byRef = new Map(ranked.map((c) => [`${c.source}@${c.skill}`.toLowerCase(), c]));
+  const out = list.map((r) => {
+    const ref = `${r.cand.source}@${r.cand.skill}`;
+    const c = byRef.get(ref.toLowerCase());
+    return { ref, installs: r.cand.installs, reason: r.reason, matches: c?.matches ?? 0, matched: c?.matched ?? [], rank: c?.rank ?? 0 };
+  });
+  out.sort((a, b) => Number(b.matches > 0) - Number(a.matches > 0) || b.rank - a.rank || b.installs - a.installs || a.ref.localeCompare(b.ref));
+  const best = out.find((x) => x.matches > 0 && OWNER_REJECTION_RE.test(x.reason));
+  const bestRejected = best ? { ref: best.ref, installs: best.installs, owner: OWNER_REJECTION_RE.exec(best.reason)[1], matched: best.matched } : null;
+  return { rejected: out, bestRejected };
+}
+
+/** @returns {Promise<{query, keywords, local, accepted, rejected, bestRejected, errors, cached, elapsedMs}>} */
+export async function runFind({ query, limit = 10, cwd, env: rawEnv = process.env, deps = {}, config: cfgOverride, timeoutMs = FIND_TIMEOUT_MS } = {}) {
+  const dir = path.resolve(cwd || process.cwd());
+  const hardened = hardenEnv(rawEnv, { cwd: dir });
+  const env = hardened.env;
+  for (const w of hardened.warnings) log('warn', /TEST SEAM/.test(w) ? 'find: test seam active' : 'find: environment override ignored', { warning: w });
+  const config = cfgOverride ?? loadConfig(env);
+  const indexOpts = { cwd: dir, home: env.HOME };
+  if (env.CLAUDE_CONFIG_DIR) indexOpts.configDir = env.CLAUDE_CONFIG_DIR;
+  const [index, stack] = await Promise.all([buildIndex(indexOpts).catch(() => []), detectStack(dir).catch(() => ({ summary: '', tags: [] }))]);
+  const local = scoreSkills(query, index, { max: 8, minScore: 1.5 }).filter((m) => !isWeakMatch(m.matched)).slice(0, 5).map((m) => ({
+    name: m.skill.invocableName || m.skill.name,
+    scope: m.skill.scope,
+    score: m.score,
+    matched: m.matched,
+    description: String(m.skill.description ?? '').slice(0, 100),
+  }));
+  const installedNames = [...new Set(index.flatMap((s) => [s.name, s.frontmatterName].filter(Boolean).map((n) => String(n).toLowerCase())))];
+  const d = await discover(query, {
+    config: { ...config, maxCandidates: limit, remoteTimeoutMs: Math.max(Number(config.remoteTimeoutMs) || 2500, 6000) },
+    stackTags: stack.tags,
+    timeoutMs,
+    deps: { ...deps, env },
+    installedNames,
+    search: true,
+  });
+  const { rejected, bestRejected } = rankRejected(d.rejected, d.keywords, { prompt: query, stackTags: stack.tags });
+  return {
+    query,
+    keywords: d.keywords,
+    intent: d.intent,
+    stack: stack.summary,
+    configPath: config.path ?? null,
+    local,
+    accepted: d.candidates.map((c) => ({
+      ref: c.ref,
+      source: c.source,
+      skill: c.skill,
+      installs: c.installs,
+      audit: c.audit?.status ?? 'unknown',
+      allowlisted: true,
+      url: c.url,
+      matches: c.matches,
+      matched: c.matched,
+      rank: c.rank,
+    })),
+    rejected,
+    bestRejected,
+    queries: d.queries,
+    errors: d.errors,
+    cached: d.cached,
+    auditSkipped: d.auditSkipped,
+    cooldownUntil: d.cooldownUntil ?? null,
+    elapsedMs: d.elapsedMs,
+  };
+}
+
+function hhmm(ts) {
+  const d = new Date(ts);
+  return `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`;
+}
+
+export function formatReport(r, { all = false } = {}) {
+  const lines = [];
+  lines.push(`${TAG} query: "${r.query}"  keywords: ${r.keywords.join(', ') || '(none)'}${r.stack ? `  stack: ${r.stack}` : ''}`);
+  if (r.local.length) {
+    lines.push('', 'Installed locally (already available, use the Skill tool / slash command):');
+    for (const l of r.local) lines.push(`  ${pad(l.name, 44)} ${pad(l.scope, 8)} score ${l.score}  ${l.description}`);
+  } else {
+    lines.push('', 'Installed locally: no match.');
+  }
+  lines.push('', 'Third-party candidates (gated: allowlist, install floor, audit; NOT installed):');
+  const requests = Array.isArray(r.queries) ? r.queries : [];
+  const allFailed = requests.length > 0 && requests.every((q) => q.skipped && !q.cached);
+  const rateLimited = r.cooldownUntil && Number(r.cooldownUntil) > Date.now();
+  if (r.accepted.length === 0 && (allFailed || rateLimited)) {
+    lines.push(`  Third-party search failed (${rateLimited ? `skills.sh rate-limited until ${hhmm(r.cooldownUntil)}` : 'timeout / network error'}); nothing could be evaluated.`);
+  } else if (r.accepted.length === 0) lines.push('  (none passed the gates)');
+  else {
+    lines.push(`  ${pad('ref', 64)} ${pad('installs', 9)} ${pad('audit', 8)} allowlisted?`);
+    for (const c of r.accepted) lines.push(`  ${pad(c.ref, 64)} ${pad(fmtInstalls(c.installs), 9)} ${pad(c.audit, 8)} yes`);
+    lines.push('', '  Load ephemerally (text only):  /singular load <ref>', '  Install persistently (pinned): /singular add <ref>');
+  }
+  const groups = new Map();
+  for (const x of r.rejected) {
+    const key = x.reason
+      .replace(/\d[\d,]*/g, 'N')
+      .replace(/kept .*$/, 'kept ...')
+      .replace(/fork of .*$/, 'fork of ...')
+      .replace(/owner \S+ not allowlisted/, 'owner not allowlisted')
+      .replace(/\(.*\)$/, '(...)');
+    groups.set(key, (groups.get(key) ?? 0) + 1);
+  }
+  if ((allFailed || rateLimited) && r.rejected.length === 0) lines.push('', `Rejected: n/a (${rateLimited ? `rate-limited until ${hhmm(r.cooldownUntil)}` : 'search failed'})`);
+  else {
+    lines.push('', `Rejected: ${r.rejected.length}${allFailed || rateLimited ? ' (from cached catalogs only)' : ''}`);
+    for (const [reason, n] of [...groups.entries()].sort((a, b) => b[1] - a[1])) lines.push(`  ${n} x ${reason}`);
+  }
+  if (r.bestRejected) {
+    lines.push(`  Best allowlist-only rejection: ${r.bestRejected.ref} (${fmtInstalls(r.bestRejected.installs)} installs, matched ${r.bestRejected.matched.join(', ') || '-'}) - add "${r.bestRejected.owner}" to "allowlist" in ${r.configPath ?? '~/.claude/singular/config.json'} to consider it`);
+  }
+  const show = all ? r.rejected : r.rejected.slice(0, 8);
+  if (show.length) {
+    lines.push(all ? '  all rejected entries (by relevance, then installs):' : '  top rejected by relevance (use --all for the full list):');
+    for (const x of show) lines.push(`    ${pad(x.ref, 64)} ${pad(fmtInstalls(x.installs), 9)} ${x.reason}${x.matches > 0 ? `  [matched ${x.matched.join(', ')}]` : ''}`);
+  }
+  if (r.errors.length) lines.push('', `Errors: ${r.errors.join(' | ')}`);
+  lines.push('', `(${r.queries.length} requests, cached: ${r.cached}${r.auditSkipped ? ', audits skipped (deadline)' : ''}${rateLimited ? `, skills.sh rate-limited until ${hhmm(r.cooldownUntil)}` : ''}, ${Math.round(r.elapsedMs)} ms)`);
+  return lines.join('\n');
+}
+
+/** `singular find ...`: returns the exit code (1 without a query, 0 otherwise). */
+export async function main(argv = process.argv.slice(2)) {
+  const args = parseArgs(argv);
+  if (args.help || !args.query) {
+    process.stderr.write(`${USAGE}\n`);
+    return args.help ? 0 : 1;
+  }
+  const r = await runFind({ query: args.query, limit: args.limit, cwd: args.cwd, env: process.env });
+  log('info', 'find', { query: args.query, accepted: r.accepted.length, rejected: r.rejected.length, ms: Math.round(r.elapsedMs) });
+  process.stdout.write(args.json ? `${JSON.stringify(r, null, 2)}\n` : `${formatReport(r, { all: args.all })}\n`);
+  return 0;
+}

package/lib/commands/mode.js

@@ -0,0 +1,93 @@
+// lib/commands/mode.js — `singular mode`: show or switch singular's mode by rewriting ONLY the `mode` key of config.json.
+//
+//   node bin/singular.js mode                            prints the current mode and where it comes from
+//   node bin/singular.js mode <off|local|suggest|auto> [--json]        (bin/singular.js dispatches here)
+//
+// Writes to the default ~/.claude/singular/config.json (or $SINGULAR_HOME/config.json when that is
+// an absolute path). `auto` is only honoured by the hooks when it lives in the default file, so this
+// command refuses to write `auto` into a redirected home. Every other key in the file is left untouched
+// (unknown keys, comments are not supported by JSON anyway).
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { configPath, DEFAULTS, defaultHomeDir, hardenEnv, loadConfig, MODES, redirectedHome } from '../config.js';
+import { TAG } from '../context.js';
+import { log } from '../log.js';
+
+export const USAGE = `usage: singular mode [${MODES.join('|')}] [--json]`;
+export const AUTO_WARNING = `${TAG} mode "auto": third-party skill text from allowlisted skills.sh sources will be injected into your prompts WITHOUT confirmation (text only, pinned, sanitized, still untrusted prose). Cold prompts add up to ~5 s and up to 9,000 chars of third-party text per prompt; see README "What auto actually costs". Run /singular mode suggest to go back.`;
+
+/**
+ * @returns {{status:'ok'|'error', mode, previous?, path, message}}
+ */
+export function setMode(mode, env = process.env) {
+  const m = String(mode ?? '').trim().toLowerCase();
+  const file = configPath(env);
+  if (!MODES.includes(m)) return { status: 'error', mode: null, path: file, message: `${TAG} unknown mode "${mode}"; expected one of ${MODES.join(' | ')}` };
+  if (m === 'auto' && redirectedHome(env)) {
+    return { status: 'error', mode: null, path: file, message: `${TAG} refusing to write mode "auto" into ${file}: auto is honoured only in the default ${defaultHomeDir(env)}/config.json (unset SINGULAR_HOME first)` };
+  }
+  let raw = {};
+  let previous = DEFAULTS.mode;
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    try {
+      const parsed = JSON.parse(text);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) raw = parsed;
+      else return { status: 'error', mode: null, path: file, message: `${TAG} ${file} is not a JSON object; fix it by hand first` };
+    } catch (err) {
+      return { status: 'error', mode: null, path: file, message: `${TAG} ${file} is not valid JSON (${err.message}); fix it by hand first` };
+    }
+  } catch (err) {
+    if (err && err.code !== 'ENOENT') return { status: 'error', mode: null, path: file, message: `${TAG} ${file} is unreadable (${err.code ?? err.message}); fix it by hand first` };
+    raw = { ...DEFAULTS };
+  }
+  if (typeof raw.mode === 'string') previous = raw.mode;
+  raw.mode = m;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(raw, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    return { status: 'error', mode: null, path: file, message: `${TAG} could not write ${file}: ${err.message}` };
+  }
+  log('info', 'mode', { mode: m, previous, path: file });
+  const note = m === 'auto' ? `\n${AUTO_WARNING}` : '';
+  return { status: 'ok', mode: m, previous, path: file, message: `${TAG} mode: ${previous} -> ${m} (${file}). Takes effect on the next prompt; no restart needed.${note}` };
+}
+
+/** @param {string[]} [envWarnings] hardenEnv warnings (ignored overrides, active test seams), printed as "! ..." lines like `singular status` does */
+export function describeMode(env = process.env, envWarnings = []) {
+  const config = loadConfig(env);
+  const lines = [`${TAG} mode: ${config.mode}  (config file: ${config.path})`];
+  if (config.fileMode && config.fileMode !== config.mode) lines.push(`  file says "${config.fileMode}"; effective "${config.mode}" (${config.warnings.filter((w) => /mode/i.test(w)).join('; ') || 'environment override'})`);
+  for (const w of [...envWarnings, ...config.warnings]) lines.push(`  ! ${w}`);
+  lines.push(`  usage: /singular mode <${MODES.join('|')}>`);
+  return lines.join('\n');
+}
+
+/** `singular mode [...]`: returns the exit code. */
+export async function main(argv = process.argv.slice(2)) {
+  const json = argv.includes('--json');
+  const positional = argv.filter((a) => !a.startsWith('-'));
+  if (argv.includes('--help') || argv.includes('-h') || positional.length > 1) {
+    process.stderr.write(`${USAGE}\n`);
+    return positional.length > 1 ? 1 : 0;
+  }
+  // A relative SINGULAR_HOME (or one inside the project) is ignored: say so instead of silently
+  // reading or writing the real ~/.claude/singular/config.json.
+  const hardened = hardenEnv(process.env, { cwd: process.cwd() });
+  const env = hardened.env;
+  for (const w of hardened.warnings) log('warn', 'mode: environment note', { warning: w });
+  if (positional.length === 0) {
+    process.stdout.write(`${describeMode(env, hardened.warnings)}\n`);
+    return 0;
+  }
+  const r = setMode(positional[0], env);
+  r.warnings = hardened.warnings;
+  if (json) process.stdout.write(`${JSON.stringify(r, null, 2)}\n`);
+  else process.stdout.write(`${r.message}\n${hardened.warnings.map((w) => `  ! ${w}\n`).join('')}`);
+  return r.status === 'ok' ? 0 : 1;
+}