singular-skill 0.0.0-stage → 0.2.0

package/lib/commands/status.js

@@ -0,0 +1,128 @@
+// lib/commands/status.js — `singular status`: config, cache stats, loaded pins, persistent installs, recent log lines.
+//
+//   node bin/singular.js status [--json] [--cwd <dir>]      (bin/singular.js dispatches here)
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { cacheGet, cacheStats } from '../cache.js';
+import { configPath, defaultHomeDir, hardenEnv, homeDir, loadConfig, SEAM_VARS } from '../config.js';
+import { TAG } from '../context.js';
+import { logPath } from '../log.js';
+import { COOLDOWN_KEY } from '../registry.js';
+import { buildIndex } from '../skill-index.js';
+import { detectStack } from '../stack.js';
+
+const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+function readJson(file) {
+  try {
+    const v = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return v && typeof v === 'object' ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+function tailLines(file, n) {
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    return text.split('\n').filter(Boolean).slice(-n);
+  } catch {
+    return [];
+  }
+}
+
+export async function collectStatus({ env: rawEnv = process.env, cwd } = {}) {
+  const dir = path.resolve(cwd || process.cwd());
+  const hardened = hardenEnv(rawEnv, { cwd: dir });
+  const env = hardened.env;
+  const config = loadConfig(env);
+  const home = homeDir(env);
+  let cooldownUntil = null;
+  try {
+    const v = cacheGet(COOLDOWN_KEY, 1, env);
+    if (v && Number(v.until) > Date.now()) cooldownUntil = Number(v.until);
+  } catch {
+    cooldownUntil = null;
+  }
+  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 byScope = {};
+  for (const s of index) byScope[s.scope] = (byScope[s.scope] ?? 0) + 1;
+  const pkg = readJson(path.join(PLUGIN_ROOT, 'package.json')) ?? {};
+  return {
+    version: pkg.version ?? null,
+    pluginRoot: PLUGIN_ROOT,
+    home,
+    configPath: configPath(env),
+    defaultConfigPath: path.join(defaultHomeDir(env), 'config.json'),
+    config: { ...config },
+    fileMode: config.fileMode ?? config.mode,
+    configWarnings: [...hardened.warnings, ...(config.warnings ?? [])],
+    envOverrides: {
+      SINGULAR_HOME: rawEnv.SINGULAR_HOME ?? null,
+      SINGULAR_MODE: rawEnv.SINGULAR_MODE ?? null,
+      CLAUDE_CONFIG_DIR: rawEnv.CLAUDE_CONFIG_DIR ?? null,
+      ...Object.fromEntries(SEAM_VARS.map((k) => [k, rawEnv[k] ?? null])),
+    },
+    testSeams: hardened.seams?.active ?? [],
+    cache: cacheStats(env),
+    cooldownUntil,
+    loaded: readJson(path.join(home, 'loaded.json')) ?? {},
+    installed: readJson(path.join(home, 'installed.json')) ?? {},
+    index: { total: index.length, byScope },
+    stack,
+    cwd: dir,
+    log: { path: logPath(env), tail: tailLines(logPath(env), 5) },
+    autoWarned: fs.existsSync(path.join(home, '.auto-mode-warned')),
+  };
+}
+
+export function formatStatus(s) {
+  const lines = [];
+  lines.push(`${TAG} singular ${s.version ?? '?'}  plugin root: ${s.pluginRoot}`);
+  lines.push(`state dir: ${s.home}`);
+  lines.push(`config:    ${s.configPath}`);
+  for (const [k, v] of Object.entries(s.config)) lines.push(`  ${k}: ${JSON.stringify(v)}`);
+  for (const w of s.configWarnings) lines.push(`  ! ${w}`);
+  const ov = Object.entries(s.envOverrides).filter(([, v]) => v);
+  if (ov.length) lines.push(`env overrides: ${ov.map(([k, v]) => `${k}=${v}`).join(' ')}`);
+  if (Array.isArray(s.testSeams) && s.testSeams.length) lines.push(`  TEST SEAMS ACTIVE (not for real use, see docs/testing.md): ${s.testSeams.join(', ')}`);
+  if (s.fileMode && s.fileMode !== s.config.mode) lines.push(`  effective mode "${s.config.mode}" (file says "${s.fileMode}"; the environment can only lower the mode, and "auto" counts only in ${s.defaultConfigPath})`);
+  if (s.config.mode === 'auto') lines.push('  WARNING: mode "auto" injects allowlisted third-party skill text without confirmation (see README "What auto actually costs"). /singular mode suggest reverts it.');
+  if (Array.isArray(s.config.pinnedSkills) && s.config.pinnedSkills.length) lines.push(`  pinnedSkills (injected once per session): ${s.config.pinnedSkills.join(', ')}`);
+  lines.push(`installed skills indexed: ${s.index.total} (${Object.entries(s.index.byScope).map(([k, v]) => `${k} ${v}`).join(', ') || 'none'})`);
+  lines.push(`stack (${s.cwd}): ${s.stack.summary || '(unknown)'}`);
+  const c = s.cache;
+  const age = (ts) => (ts ? `${Math.round((Date.now() - ts) / 60000)} min ago` : '-');
+  lines.push(`cache: ${c.entries} entries, ${(c.bytes / 1024).toFixed(1)} KB, newest ${age(c.newestTs)}, oldest ${age(c.oldestTs)} (${c.dir})`);
+  if (s.cooldownUntil) {
+    const d = new Date(s.cooldownUntil);
+    lines.push(`skills.sh: rate-limited (HTTP 429) — no requests until ${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}; cached catalogs still rank`);
+  }
+  const loaded = Object.entries(s.loaded);
+  lines.push(`loaded pins (/singular load, ephemeral): ${loaded.length}`);
+  for (const [key, v] of loaded) lines.push(`  ${key} -> ${v.sha ?? '?'}  loads ${v.loads ?? '?'}  last ${v.lastTs ? new Date(v.lastTs).toISOString() : '?'}${Array.isArray(v.stripped) && v.stripped.length ? `  stripped: ${v.stripped.length}` : ''}`);
+  const installed = Object.entries(s.installed);
+  lines.push(`persistent installs (/singular add): ${installed.length}`);
+  for (const [key, v] of installed) lines.push(`  ${key} -> ${v.sha ?? '?'}  ${v.path ?? ''}  audit ${v.audit ?? '?'}`);
+  lines.push(`log: ${s.log.path}`);
+  for (const l of s.log.tail) lines.push(`  ${l.slice(0, 200)}`);
+  return lines.join('\n');
+}
+
+/**
+ * `singular status [--json] [--cwd <dir>]`. Text mode prints the status followed by `trailer` (the one-screen
+ * help, passed in by the dispatcher); --json prints the structured status only. Returns the exit code.
+ */
+export async function main(argv = process.argv.slice(2), { trailer = '' } = {}) {
+  const json = argv.includes('--json');
+  const i = argv.indexOf('--cwd');
+  const cwd = i >= 0 ? argv[i + 1] : null;
+  const s = await collectStatus({ env: process.env, cwd });
+  process.stdout.write(json ? `${JSON.stringify(s, null, 2)}\n` : `${formatStatus(s)}\n${trailer ? `\n${trailer}\n` : ''}`);
+  return 0;
+}

package/lib/config.js

@@ -0,0 +1,407 @@
+// lib/config.js — singular configuration.
+//
+//   loadConfig(env)            -> Config (DEFAULTS merged with $SINGULAR_HOME/config.json; created on first run)
+//   DEFAULTS                   -> the built-in defaults (frozen)
+//   configPath(env)            -> absolute path of config.json
+//   homeDir(env)               -> $SINGULAR_HOME (absolute only) or ~/.claude/singular (mkdir -p)
+//   defaultHomeDir(env)        -> ~/.claude/singular regardless of SINGULAR_HOME
+//   isAllowlisted(source, list)-> owner or owner/repo match, case-insensitive
+//   validateConfig(raw)        -> {config, warnings}   (pure; used by loadConfig and /singular status)
+//   hardenEnv(env, {cwd})      -> copy of env with untrusted SINGULAR_HOME / HOME / TMPDIR overrides removed
+//   testSeams(env, {cwd})      -> the test-only seams (docs/testing.md), validated; never a user feature
+//   tmpdirOf(env)              -> the temp base for clones and npx runs, from the (hardened) env, never process.env alone
+//
+// Environment variables reach the hook process from the user's shell AND from a repository's committed
+// `.claude/settings.json` `env` block, so the environment is treated as untrusted and can only LOWER
+// privilege (docs/security.md §1):
+//   SINGULAR_HOME  state directory: honoured only when absolute and (in hook mode) neither inside nor an
+//                     ancestor of the project cwd (an ancestor would let a checkout named `cache` be the cache dir)
+//   TMPDIR/TMP/TEMP   a value inside the project cwd is replaced by the platform default (the temp cwd of a clone or
+//                     `npx skills` run must never sit inside the repository: npm would read its .npmrc)
+//   SINGULAR_MODE  can only downgrade the file's mode (off < local < suggest < auto); never raises it
+//   mode "auto"       is honoured only when it comes from the default ~/.claude/singular/config.json
+//
+// Test seams (docs/testing.md; NOT user features; every honoured seam is logged as a warning and listed by
+// /singular status, and production behaviour is byte-identical when they are unset):
+//   SINGULAR_REGISTRY_BASE  http(s)://localhost|127.0.0.1|[::1][:port][/path] replaces https://skills.sh
+//   SINGULAR_GIT_BASE       absolute local path or file:// URL (neither inside nor above the project) replaces
+//                              https://github.com, and skill text is then fetched with git instead of `npx skills use`
+//   SINGULAR_SKILLS_DIR     absolute path (neither inside nor above the project) replaces ~/.claude/skills for /singular add
+//   SINGULAR_TEST_ALLOW_AUTO=1  honours mode "auto" in a redirected SINGULAR_HOME (still never from the env)
+// Remote http(s) git bases and non-loopback registry hosts are refused: a repository's env block must not be
+// able to redirect a trusted ref to another host.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const MODES = Object.freeze(['off', 'local', 'suggest', 'auto']);
+export const SEAM_VARS = Object.freeze(['SINGULAR_REGISTRY_BASE', 'SINGULAR_GIT_BASE', 'SINGULAR_SKILLS_DIR', 'SINGULAR_TEST_ALLOW_AUTO']);
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+
+export const DEFAULTS = Object.freeze({
+  mode: 'suggest',
+  allowlist: Object.freeze(['anthropics', 'vercel-labs', 'microsoft', 'multica-ai']),
+  installFloor: 1000,
+  maxLocalSkills: 3,
+  maxCandidates: 2,
+  minPromptChars: 40,
+  remoteTimeoutMs: 2500,
+  totalBudgetMs: 6000,
+  contextBudgetChars: 2000,
+  cacheTtlHours: 24,
+  skillsCliVersion: '1.5.26',
+  requireAuditPass: true,
+  stackDetection: true,
+  blockedRefs: Object.freeze([]),
+  pinnedSkills: Object.freeze([]),
+  prefetch: true,
+});
+
+const CLI_VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+
+function realHome() {
+  try {
+    const h = os.userInfo().homedir;
+    if (h && path.isAbsolute(h)) return h;
+  } catch {
+    /* no passwd entry */
+  }
+  return os.homedir();
+}
+
+/**
+ * Resolve symlinks in `p` as far as the path exists (the longest existing ancestor is realpath'd, the
+ * rest re-joined), so `/tmp/x` and `/private/tmp/x`, or `<repo>/alias -> <repo>`, compare equal.
+ */
+function realResolve(p) {
+  let cur = path.resolve(p);
+  const rest = [];
+  for (;;) {
+    try {
+      return path.join(fs.realpathSync.native(cur), ...rest.reverse());
+    } catch {
+      const parent = path.dirname(cur);
+      if (parent === cur) return path.join(cur, ...rest.reverse());
+      rest.push(path.basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+function isInside(child, parent) {
+  const c = realResolve(child);
+  const p = realResolve(parent);
+  return c === p || c.startsWith(p.endsWith(path.sep) ? p : p + path.sep);
+}
+
+/** `p` is the project, inside it, or an ancestor of it: a path a repository could reach or be checked out under. */
+function touchesProject(p, cwd) {
+  return isInside(p, cwd) || isInside(cwd, p);
+}
+
+/** The platform's default temp directory, independent of TMPDIR/TMP/TEMP. */
+function platformTmpdir(env = process.env) {
+  if (process.platform === 'win32') return path.join(env.SystemRoot || env.SYSTEMROOT || env.windir || 'C:\\Windows', 'Temp');
+  return '/tmp';
+}
+
+/**
+ * Temp base for pinned clones and `npx skills use` runs: TMPDIR (TEMP/TMP on Windows) from the given env when it is
+ * an absolute path, else os.tmpdir(). Callers pass the hardened env, in which an in-project value has already been
+ * replaced, so a repository's env block can never place the work dir (and npm's config walk-up) inside itself.
+ */
+export function tmpdirOf(env = process.env) {
+  const keys = process.platform === 'win32' ? ['TEMP', 'TMP'] : ['TMPDIR', 'TMP', 'TEMP'];
+  for (const k of keys) {
+    const v = env && env[k] != null ? String(env[k]).trim() : '';
+    if (v && path.isAbsolute(v)) return path.resolve(v);
+  }
+  return os.tmpdir();
+}
+
+/** ~/.claude/singular for the given env (HOME override honoured; SINGULAR_HOME ignored). */
+export function defaultHomeDir(env = process.env) {
+  return path.join(env.HOME || os.homedir(), '.claude', 'singular');
+}
+
+/** Is SINGULAR_HOME usable? Only absolute paths count; relative values are ignored (they would resolve against the project cwd). */
+export function redirectedHome(env = process.env) {
+  const raw = env.SINGULAR_HOME && String(env.SINGULAR_HOME).trim();
+  if (!raw) return null;
+  if (!path.isAbsolute(raw)) return null;
+  return path.resolve(raw);
+}
+
+export function homeDir(env = process.env) {
+  const dir = redirectedHome(env) ?? defaultHomeDir(env);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+  } catch {
+    /* read-only FS: callers still get a path */
+  }
+  return dir;
+}
+
+export function configPath(env = process.env) {
+  return path.join(homeDir(env), 'config.json');
+}
+
+/**
+ * Copy of `env` with environment overrides that could hand a repository control of singular removed:
+ * a relative SINGULAR_HOME, a SINGULAR_HOME inside `cwd` (the project) or an ancestor of it (the cache
+ * or state dir would then be a sibling checkout), a HOME that differs from the account's real home AND lies
+ * inside `cwd`, and a TMPDIR/TMP/TEMP inside `cwd` (replaced by the platform default: a clone or npx work dir
+ * inside the repository would hand npm the repository's .npmrc). Invalid test seams are removed too; honoured
+ * ones are reported as warnings so every entrypoint logs them. Returns {env, warnings, seams}. Pure; never throws.
+ */
+export function hardenEnv(env = process.env, { cwd } = {}) {
+  const out = { ...env };
+  const warnings = [];
+  const raw = out.SINGULAR_HOME && String(out.SINGULAR_HOME).trim();
+  if (raw) {
+    if (!path.isAbsolute(raw)) {
+      warnings.push(`SINGULAR_HOME=${raw} ignored (must be an absolute path)`);
+      delete out.SINGULAR_HOME;
+    } else if (cwd && isInside(raw, cwd)) {
+      warnings.push(`SINGULAR_HOME=${raw} ignored (inside the project directory ${cwd})`);
+      delete out.SINGULAR_HOME;
+    } else if (cwd && isInside(cwd, raw)) {
+      warnings.push(`SINGULAR_HOME=${raw} ignored (an ancestor of the project directory ${cwd})`);
+      delete out.SINGULAR_HOME;
+    }
+  }
+  if (cwd) {
+    for (const k of ['TMPDIR', 'TMP', 'TEMP']) {
+      const v = out[k] && String(out[k]).trim();
+      if (!v) continue;
+      if (!path.isAbsolute(v) || isInside(v, cwd)) {
+        const fallback = platformTmpdir(out);
+        warnings.push(`${k}=${v} ignored (${path.isAbsolute(v) ? 'inside the project directory' : 'relative; would resolve inside the project directory'} ${cwd}); using ${fallback}`);
+        out[k] = fallback;
+      }
+    }
+  }
+  const home = out.HOME && String(out.HOME).trim();
+  if (home && cwd) {
+    const real = realHome();
+    if (path.resolve(home) !== path.resolve(real) && isInside(home, cwd)) {
+      warnings.push(`HOME=${home} ignored (inside the project directory ${cwd}); using ${real}`);
+      out.HOME = real;
+    }
+  }
+  const seams = testSeams(out, { cwd });
+  for (const v of seams.invalid) delete out[v];
+  warnings.push(...seams.warnings);
+  return { env: out, warnings, seams };
+}
+
+/**
+ * Parse and validate the test-only seams (see the header). Each is honoured only in its narrow form:
+ *   registryBase  http(s) URL whose host is loopback (a fixture server); trailing slash dropped
+ *   gitBase       absolute local path or file:// URL, neither inside nor an ancestor of `cwd` when given; never http(s)
+ *                 (an ancestor base would resolve <base>/<owner>/<repo> to a sibling or the project checkout itself)
+ *   skillsDir     absolute path, neither inside nor an ancestor of `cwd` when given
+ *   allowAuto     the literal value "1"
+ * Returns {registryBase, gitBase, skillsDir, allowAuto, active, invalid, warnings}; `invalid` names the
+ * variables that must be dropped, `warnings` explains every drop and announces every active seam. Pure.
+ */
+export function testSeams(env = process.env, { cwd } = {}) {
+  const out = { registryBase: null, gitBase: null, skillsDir: null, allowAuto: false, active: [], invalid: [], warnings: [] };
+  const note = 'test seam, see docs/testing.md';
+  const get = (k) => (env && env[k] != null ? String(env[k]).trim() : '');
+  const outsideProject = (p) => !cwd || !touchesProject(p, cwd);
+
+  const reg = get('SINGULAR_REGISTRY_BASE');
+  if (reg) {
+    let ok = false;
+    try {
+      const u = new URL(reg);
+      ok = (u.protocol === 'http:' || u.protocol === 'https:') && LOOPBACK_HOSTS.has(u.hostname) && !u.search && !u.hash;
+      if (ok) out.registryBase = `${u.origin}${u.pathname.replace(/\/+$/, '')}`;
+    } catch {
+      ok = false;
+    }
+    if (ok) out.active.push('SINGULAR_REGISTRY_BASE');
+    else {
+      out.invalid.push('SINGULAR_REGISTRY_BASE');
+      out.warnings.push(`SINGULAR_REGISTRY_BASE=${reg} ignored (${note}: only http(s)://localhost, 127.0.0.1 or [::1] is honoured)`);
+    }
+  }
+
+  const git = get('SINGULAR_GIT_BASE');
+  if (git) {
+    let local = null;
+    if (/^file:\/\//i.test(git)) {
+      try {
+        const u = new URL(git);
+        if (u.protocol === 'file:' && (!u.hostname || u.hostname === 'localhost')) local = decodeURIComponent(u.pathname);
+      } catch {
+        local = null;
+      }
+    } else if (path.isAbsolute(git)) local = git;
+    if (local && path.isAbsolute(local) && outsideProject(local)) {
+      out.gitBase = /^file:\/\//i.test(git) ? `file://${path.resolve(local).replace(/\/+$/, '')}` : path.resolve(local).replace(/\/+$/, '');
+      out.active.push('SINGULAR_GIT_BASE');
+    } else {
+      out.invalid.push('SINGULAR_GIT_BASE');
+      out.warnings.push(`SINGULAR_GIT_BASE=${git} ignored (${note}: must be an absolute local path or file:// URL neither inside nor above the project directory; remote hosts are never honoured)`);
+    }
+  }
+
+  const skills = get('SINGULAR_SKILLS_DIR');
+  if (skills) {
+    if (path.isAbsolute(skills) && outsideProject(skills)) {
+      out.skillsDir = path.resolve(skills);
+      out.active.push('SINGULAR_SKILLS_DIR');
+    } else {
+      out.invalid.push('SINGULAR_SKILLS_DIR');
+      out.warnings.push(`SINGULAR_SKILLS_DIR=${skills} ignored (${note}: must be an absolute path neither inside nor above the project directory)`);
+    }
+  }
+
+  const auto = get('SINGULAR_TEST_ALLOW_AUTO');
+  if (auto) {
+    if (auto === '1') {
+      out.allowAuto = true;
+      out.active.push('SINGULAR_TEST_ALLOW_AUTO');
+    } else {
+      out.invalid.push('SINGULAR_TEST_ALLOW_AUTO');
+      out.warnings.push(`SINGULAR_TEST_ALLOW_AUTO=${auto} ignored (${note}: only "1" is honoured)`);
+    }
+  }
+  for (const v of out.active) out.warnings.push(`TEST SEAM ACTIVE: ${v}=${get(v)} (${note}; never set this in a real shell)`);
+  return out;
+}
+
+/** The honoured registry base URL (no trailing slash) or null when the seam is unset / invalid. */
+export function seamRegistryBase(env = process.env) {
+  return testSeams(env).registryBase;
+}
+
+/** The honoured git base (absolute path or file:// URL, no trailing slash) or null. */
+export function seamGitBase(env = process.env) {
+  return testSeams(env).gitBase;
+}
+
+/** The honoured /singular add target directory or null. */
+export function seamSkillsDir(env = process.env) {
+  return testSeams(env).skillsDir;
+}
+
+/** `source` is owner/repo (or a bare owner); entries are `owner` or `owner/repo`, exact, case-insensitive. */
+export function isAllowlisted(source, allowlist) {
+  const src = String(source ?? '').trim().toLowerCase().replace(/^\/+|\/+$/g, '');
+  if (!src) return false;
+  const owner = src.split('/')[0];
+  for (const raw of Array.isArray(allowlist) ? allowlist : []) {
+    const entry = String(raw ?? '').trim().toLowerCase().replace(/^\/+|\/+$/g, '');
+    if (!entry) continue;
+    if (entry.includes('/')) {
+      if (entry === src) return true;
+    } else if (entry === owner) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isStringArray(v) {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+/**
+ * Merge a raw object over DEFAULTS, type-checking every known key (a wrong type
+ * falls back to the default and yields a warning). Unknown keys are kept as-is.
+ */
+export function validateConfig(raw) {
+  const warnings = [];
+  const src = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  if (src !== raw) warnings.push('config is not a JSON object; using defaults');
+  const cfg = { ...src };
+  const fallback = (key, why) => {
+    warnings.push(`${key}: ${why}; using default ${JSON.stringify(DEFAULTS[key])}`);
+    cfg[key] = Array.isArray(DEFAULTS[key]) ? [...DEFAULTS[key]] : DEFAULTS[key];
+  };
+  for (const [key, def] of Object.entries(DEFAULTS)) {
+    if (!(key in src)) {
+      cfg[key] = Array.isArray(def) ? [...def] : def;
+      continue;
+    }
+    const v = src[key];
+    if (key === 'mode') {
+      if (typeof v !== 'string' || !MODES.includes(v.toLowerCase())) fallback(key, `must be one of ${MODES.join('|')}`);
+      else cfg.mode = v.toLowerCase();
+    } else if (key === 'skillsCliVersion') {
+      if (typeof v !== 'string' || !CLI_VERSION_RE.test(v)) fallback(key, 'must be a semver string like "1.5.26"');
+    } else if (Array.isArray(def)) {
+      if (!isStringArray(v)) fallback(key, 'must be an array of strings');
+      else cfg[key] = v.map((s) => s.trim()).filter(Boolean);
+    } else if (typeof def === 'number') {
+      if (typeof v !== 'number' || !Number.isFinite(v) || v < 0) fallback(key, 'must be a non-negative number');
+    } else if (typeof def === 'boolean') {
+      if (typeof v !== 'boolean') fallback(key, 'must be true or false');
+    } else if (typeof v !== typeof def) {
+      fallback(key, `must be a ${typeof def}`);
+    }
+  }
+  return { config: cfg, warnings };
+}
+
+/**
+ * Load the config. Creates config.json from DEFAULTS on first run. Never throws:
+ * an unreadable or corrupt file yields DEFAULTS plus `warnings`.
+ * The result carries non-enumerable `warnings`, `path`, `fileMode` and `redirected` for diagnostics.
+ */
+export function loadConfig(env = process.env) {
+  const file = configPath(env);
+  const redirected = redirectedHome(env) !== null;
+  let raw = null;
+  const warnings = [];
+  let missing = false;
+  try {
+    const text = fs.readFileSync(file, 'utf8');
+    try {
+      raw = JSON.parse(text);
+    } catch (err) {
+      warnings.push(`config.json is not valid JSON (${err.message}); using defaults`);
+    }
+  } catch (err) {
+    // Only a genuinely missing file is created from the defaults; anything else (EISDIR, EACCES, ...) is
+    // reported so /singular status shows a "!" line instead of silently pretending the file is absent.
+    if (err && err.code === 'ENOENT') missing = true;
+    else warnings.push(`config.json unreadable (${err?.code ?? err?.message ?? 'unknown error'}); using defaults`);
+  }
+  if (missing) {
+    try {
+      fs.writeFileSync(file, `${JSON.stringify(DEFAULTS, null, 2)}\n`, { flag: 'wx' });
+    } catch {
+      /* raced or read-only: fine */
+    }
+  }
+  const { config, warnings: w2 } = validateConfig(raw ?? {});
+  warnings.push(...w2);
+  const fileMode = config.mode;
+  if (config.mode === 'auto' && redirected) {
+    if (testSeams(env).allowAuto) {
+      warnings.push(`TEST SEAM: SINGULAR_TEST_ALLOW_AUTO=1 honours mode "auto" in the redirected ${homeDir(env)} (test-only; never set this in a real shell)`);
+    } else {
+      warnings.push(`mode "auto" ignored: it is honoured only in the default ${defaultHomeDir(env)}/config.json, not in a SINGULAR_HOME redirect; using "suggest"`);
+      config.mode = 'suggest';
+    }
+  }
+  if (env.SINGULAR_HOME && !redirected && String(env.SINGULAR_HOME).trim()) {
+    warnings.push(`SINGULAR_HOME=${env.SINGULAR_HOME} ignored (must be an absolute path)`);
+  }
+  if (env.SINGULAR_MODE) {
+    const m = String(env.SINGULAR_MODE).trim().toLowerCase();
+    if (!MODES.includes(m)) warnings.push(`SINGULAR_MODE=${env.SINGULAR_MODE} ignored (not one of ${MODES.join('|')})`);
+    else if (MODES.indexOf(m) > MODES.indexOf(config.mode)) warnings.push(`SINGULAR_MODE=${m} ignored (the environment can only lower the mode below "${config.mode}")`);
+    else config.mode = m;
+  }
+  Object.defineProperty(config, 'warnings', { value: warnings, enumerable: false });
+  Object.defineProperty(config, 'path', { value: file, enumerable: false });
+  Object.defineProperty(config, 'fileMode', { value: fileMode, enumerable: false });
+  Object.defineProperty(config, 'redirected', { value: redirected, enumerable: false });
+  return config;
+}