wize-dev-kit 0.5.0 → 0.6.0

package/src/security-overlay/_shared/install-script.js

@@ -0,0 +1,205 @@
+'use strict';
+
+// install-script.js — generates a self-contained install script for the
+// security-overlay pentest tools, using the CORRECT install source per
+// tool. Most security tools are NOT in apt/brew: they are Go binaries
+// shipped as GitHub releases. Treating everything as a PM package
+// produces a script that fails (apt has no `gitleaks`/`nuclei`/`ffuf`/
+// `osv-scanner`/`grype`). So each tool declares its real method:
+//
+//   - 'pm'       : available in the OS package manager (nmap, nikto, sqlmap, curl)
+//   - 'github'   : a GitHub release asset (gitleaks, nuclei, ffuf, osv-scanner)
+//   - 'script'   : an official installer script (grype)
+//
+// The generated bash script is idempotent and installs only what's missing.
+
+const HEADER = `#!/usr/bin/env bash
+# security-overlay — install pentest tools
+# Generated by wize-sec-preflight. Safe to re-run (idempotent).
+#
+# Most of these tools are NOT in apt/brew — they are GitHub release
+# binaries. This script installs each from its correct source.
+# GitHub binaries go to ~/.local/bin (no sudo needed for those).
+set -euo pipefail
+
+LOCAL_BIN="\${HOME}/.local/bin"
+mkdir -p "\${LOCAL_BIN}"
+case ":\${PATH}:" in
+  *":\${LOCAL_BIN}:"*) : ;;
+  *) echo "NOTE: add \${LOCAL_BIN} to your PATH (e.g. in ~/.bashrc):"
+     echo '      export PATH="$HOME/.local/bin:$PATH"' ;;
+esac
+
+# Detect arch for GitHub release downloads.
+ARCH="$(uname -m)"
+case "\${ARCH}" in
+  x86_64|amd64) GH_ARCH="amd64"; GH_ARCH_ALT="x64" ;;
+  aarch64|arm64) GH_ARCH="arm64"; GH_ARCH_ALT="arm64" ;;
+  *) GH_ARCH="amd64"; GH_ARCH_ALT="x64" ;;
+esac
+OS_LC="$(uname -s | tr '[:upper:]' '[:lower:]')"
+
+# Helper: download a tar.gz GitHub release and install one binary from it.
+gh_targz() { # $1=url $2=binary-name-inside-archive
+  local url="$1" bin="$2" tmp
+  tmp="$(mktemp -d)"
+  echo "  ↓ \${bin} <- \${url}"
+  curl -fsSL "\${url}" -o "\${tmp}/a.tgz"
+  tar -xzf "\${tmp}/a.tgz" -C "\${tmp}"
+  install -m 0755 "\${tmp}/\${bin}" "\${LOCAL_BIN}/\${bin}"
+  rm -rf "\${tmp}"
+}
+
+gh_zip() { # $1=url $2=binary-name-inside-archive
+  local url="$1" bin="$2" tmp
+  tmp="$(mktemp -d)"
+  echo "  ↓ \${bin} <- \${url}"
+  curl -fsSL "\${url}" -o "\${tmp}/a.zip"
+  unzip -q -o "\${tmp}/a.zip" -d "\${tmp}"
+  install -m 0755 "\${tmp}/\${bin}" "\${LOCAL_BIN}/\${bin}"
+  rm -rf "\${tmp}"
+}
+`;
+
+// Per-tool install recipe. Versions are pinned to known-good releases; the
+// user can bump them. {GH_ARCH}/{GH_ARCH_ALT}/{OS} are substituted by the
+// bash script's own variables at run time (we emit them as shell vars).
+const TOOL_RECIPES = {
+  // --- package-manager tools ---
+  nmap:   { via: 'pm' },
+  nikto:  { via: 'pm' },
+  sqlmap: { via: 'pm' },
+  curl:   { via: 'pm' },
+
+  // --- GitHub release binaries ---
+  gitleaks: {
+    via: 'github',
+    // gitleaks_8.18.4_linux_x64.tar.gz  (note: x64/arm64, not amd64)
+    cmd: 'gh_targz "https://github.com/gitleaks/gitleaks/releases/download/v8.18.4/gitleaks_8.18.4_${OS_LC}_${GH_ARCH_ALT}.tar.gz" gitleaks'
+  },
+  nuclei: {
+    via: 'github',
+    // nuclei_3.3.7_linux_amd64.zip
+    cmd: 'gh_zip "https://github.com/projectdiscovery/nuclei/releases/download/v3.3.7/nuclei_3.3.7_${OS_LC}_${GH_ARCH}.zip" nuclei'
+  },
+  ffuf: {
+    via: 'github',
+    // ffuf_2.1.0_linux_amd64.tar.gz
+    cmd: 'gh_targz "https://github.com/ffuf/ffuf/releases/download/v2.1.0/ffuf_2.1.0_${OS_LC}_${GH_ARCH}.tar.gz" ffuf'
+  },
+  'osv-scanner': {
+    via: 'github',
+    // osv-scanner_linux_amd64 (raw binary, not archived)
+    cmd: 'echo "  ↓ osv-scanner"; curl -fsSL "https://github.com/google/osv-scanner/releases/download/v2.0.2/osv-scanner_${OS_LC}_${GH_ARCH}" -o "${LOCAL_BIN}/osv-scanner"; chmod 0755 "${LOCAL_BIN}/osv-scanner"'
+  },
+
+  // --- official installer script ---
+  grype: {
+    via: 'script',
+    cmd: 'curl -fsSL https://raw.githubusercontent.com/anchore/grype/main/install.sh | sh -s -- -b "${LOCAL_BIN}"'
+  }
+};
+
+const TOOL_URLS = {
+  nmap: 'https://nmap.org/download.html',
+  nuclei: 'https://github.com/projectdiscovery/nuclei',
+  gitleaks: 'https://github.com/gitleaks/gitleaks',
+  'osv-scanner': 'https://github.com/google/osv-scanner',
+  grype: 'https://github.com/anchore/grype',
+  nikto: 'https://github.com/sullo/nikto',
+  sqlmap: 'https://github.com/sqlmapproject/sqlmap',
+  ffuf: 'https://github.com/ffuf/ffuf'
+};
+
+const PM_INSTALL = {
+  apt:        (pkgs) => `sudo apt-get update && sudo apt-get install -y ${pkgs.join(' ')}`,
+  dnf:        (pkgs) => `sudo dnf install -y ${pkgs.join(' ')}`,
+  pacman:     (pkgs) => `sudo pacman -Syu --noconfirm ${pkgs.join(' ')}`,
+  zypper:     (pkgs) => `sudo zypper install -y ${pkgs.join(' ')}`,
+  apk:        (pkgs) => `sudo apk add ${pkgs.join(' ')}`,
+  brew:       (pkgs) => `brew install ${pkgs.join(' ')}`,
+  scoop:      (pkgs) => `scoop install ${pkgs.join(' ')}`,
+  chocolatey: (pkgs) => `choco install -y ${pkgs.join(' ')}`
+};
+
+function generateInstallScript(preflight) {
+  const { os, arch, packageManager, missing = [] } = preflight;
+  const lines = [HEADER];
+
+  lines.push(`# OS: ${os} (${arch})`);
+  lines.push(`# Package manager: ${packageManager || 'none'}`);
+  lines.push(`# Missing tools: ${missing.length === 0 ? '(none)' : missing.join(', ')}`);
+  lines.push('');
+
+  if (missing.length === 0) {
+    lines.push('echo "All tools are already installed. Nothing to do."');
+    return lines.join('\n');
+  }
+
+  // Bucket the missing tools by install method.
+  const pmTools = [];
+  const ghTools = [];
+  const scriptTools = [];
+  const unknownTools = [];
+  for (const tool of missing) {
+    const r = TOOL_RECIPES[tool];
+    if (!r) { unknownTools.push(tool); continue; }
+    if (r.via === 'pm') pmTools.push(tool);
+    else if (r.via === 'github') ghTools.push(tool);
+    else if (r.via === 'script') scriptTools.push(tool);
+  }
+
+  // 1. Package-manager tools (need a known PM).
+  if (pmTools.length) {
+    const pmFn = PM_INSTALL[packageManager];
+    if (pmFn) {
+      lines.push(`echo "==> Installing via ${packageManager}: ${pmTools.join(', ')}"`);
+      lines.push(pmFn(pmTools));
+    } else {
+      lines.push(`echo "==> These need a package manager (none detected): ${pmTools.join(', ')}"`);
+      for (const t of pmTools) lines.push(`echo "    ${t}: ${TOOL_URLS[t] || ''}"`);
+    }
+    lines.push('');
+  }
+
+  // 2. GitHub release binaries.
+  if (ghTools.length) {
+    lines.push(`echo "==> Installing GitHub-release binaries to \${LOCAL_BIN}: ${ghTools.join(', ')}"`);
+    for (const t of ghTools) {
+      lines.push(TOOL_RECIPES[t].cmd);
+    }
+    lines.push('');
+  }
+
+  // 3. Official installer scripts.
+  if (scriptTools.length) {
+    lines.push(`echo "==> Installing via official scripts: ${scriptTools.join(', ')}"`);
+    for (const t of scriptTools) {
+      lines.push(TOOL_RECIPES[t].cmd);
+    }
+    lines.push('');
+  }
+
+  // 4. Anything we don't have a recipe for.
+  if (unknownTools.length) {
+    lines.push(`echo "==> Manual install required for: ${unknownTools.join(', ')}"`);
+    for (const t of unknownTools) {
+      lines.push(`echo "    ${t}: ${TOOL_URLS[t] || 'https://www.google.com/search?q=' + encodeURIComponent(t + ' install')}"`);
+    }
+    lines.push('');
+  }
+
+  // Verification.
+  lines.push('echo ""');
+  lines.push('echo "==> Verifying..."');
+  for (const tool of missing) {
+    lines.push(`command -v ${tool} >/dev/null 2>&1 && echo "  ✓ ${tool}" || echo "  ✗ ${tool} (not on PATH yet)"`);
+  }
+  lines.push('');
+  lines.push('echo "Done. If any tool shows ✗, ensure ~/.local/bin is on your PATH and re-open the shell."');
+  lines.push('echo "Then run /wize-sec-pentest."');
+
+  return lines.join('\n');
+}
+
+module.exports = { generateInstallScript, TOOL_RECIPES, TOOL_URLS, PM_INSTALL };

package/src/security-overlay/_shared/invoke-phase.js

@@ -0,0 +1,86 @@
+'use strict';
+
+// invoke-phase.js — single point that spawns a phase skill as a Node
+// subprocess. The orchestrator (wize-sec-pentest) calls invokePhase to
+// run each phase in sequence. Failures return {ok:false, code} — the
+// orchestrator decides whether to continue or abort.
+//
+// Security invariants (enforced by the canary test in
+// test/security-overlay/invoke-phase.test.js):
+//   - NEVER uses shell:true (no command-injection escape).
+//   - Skill names cannot escape the kit root via path traversal.
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+const fs = require('node:fs');
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes per phase
+
+// resolvePhaseScript(skill, { kitRoot }) -> absolute path.
+// Convention: src/security-overlay/skills/<skill>/scripts/<last-segment>.js
+// E.g. wize-sec-recon -> .../skills/wize-sec-recon/scripts/recon.js.
+// The path is computed even if the file does not exist (callers that want
+// to verify existence should call fs.existsSync on the result).
+function resolvePhaseScript(skill, opts = {}) {
+  if (typeof skill !== 'string' || !skill) return null;
+  // Reject anything that tries to escape via ../
+  if (skill.includes('..') || skill.includes('/') || skill.includes('\\') || path.isAbsolute(skill)) {
+    throw new Error(`phase-skill-name-traversal: refused ${JSON.stringify(skill)}`);
+  }
+  const kitRoot = opts.kitRoot || path.resolve(__dirname, '..', '..', '..');
+  // Convention: src/security-overlay/skills/<skill>/scripts/<scriptName>
+  // where scriptName is the explicit opts.scriptName (must include .js)
+  // if given, otherwise 'run-<lastSegment>.js'.
+  const scriptName = opts.scriptName || `run-${skill.split('-').pop()}.js`;
+  return path.join(kitRoot, 'src', 'security-overlay', 'skills', skill, 'scripts', scriptName);
+}
+
+// invokePhase(skill, opts) -> Promise<{ok, code, stdout, stderr, error?}>.
+// opts: { kitRoot?, active?, extraArgs?: string[], timeout?: ms }
+// Does NOT throw on subprocess failure — returns {ok:false, code, error}.
+function invokePhase(skill, opts = {}) {
+  return new Promise(resolve => {
+    let script;
+    try {
+      script = resolvePhaseScript(skill, opts);
+    } catch (e) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: '', error: String(e.message || e) });
+    }
+    if (!script || !fs.existsSync(script)) {
+      return resolve({ ok: false, code: -1, stdout: '', stderr: '', error: `phase script not found for ${skill}` });
+    }
+
+    const argv = [];
+    if (opts.active) argv.push('--active');
+    if (opts.securityDir) argv.push(`--securityDir=${opts.securityDir}`);
+    if (opts.scopePath) argv.push(`--scope=${opts.scopePath}`);
+    if (Array.isArray(opts.extraArgs)) argv.push(...opts.extraArgs);
+
+    const child = spawn(process.execPath, [script, ...argv], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      // shell: false is the default in spawn(); we do not set it.
+      timeout: opts.timeout || DEFAULT_TIMEOUT_MS
+    });
+
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', d => { stdout += d.toString(); });
+    child.stderr.on('data', d => { stderr += d.toString(); });
+
+    child.on('error', err => {
+      resolve({ ok: false, code: -1, stdout, stderr, error: String(err.message || err) });
+    });
+    child.on('close', code => {
+      resolve({ ok: code === 0, code: code == null ? -1 : code, stdout, stderr });
+    });
+  });
+}
+
+// Exposed for tests that need to introspect the spawn call.
+function _spawnForTest(...args) { return spawn(...args); }
+
+module.exports = {
+  invokePhase,
+  resolvePhaseScript,
+  _spawnForTest
+};

package/src/security-overlay/_shared/owasp.js

@@ -0,0 +1,56 @@
+'use strict';
+
+// owasp.js — maps a finding (rule id / cve / poc) to an OWASP Top 10 (2021)
+// category. Zero-dep: the category table is loaded from
+// src/security-overlay/data/owasp-top10.json.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DATA_PATH = path.join(__dirname, '..', 'data', 'owasp-top10.json');
+
+let _cache = null;
+function _load() {
+  if (_cache) return _cache;
+  const raw = fs.readFileSync(DATA_PATH, 'utf8');
+  const parsed = JSON.parse(raw);
+  _cache = parsed.categories || [];
+  return _cache;
+}
+
+function listOwaspCategories() {
+  return _load().slice();
+}
+
+function listOwaspCategoryIds() {
+  return _load().map(c => c.id);
+}
+
+// Ordered rules: the FIRST match wins. We check cve before generic rule
+// because a finding with a CVE is unambiguously A06 (vulnerable components).
+const RULES = [
+  { match: f => !!f.cve,                                 to: 'A06:2021' },
+  { match: f => /sqli|sql[-_ ]?injection|injection/i.test(f.rule || ''), to: 'A03:2021' },
+  { match: f => /\bxss\b/i.test(f.rule || ''),           to: 'A03:2021' },
+  { match: f => /\bauth[-_ ]?bypass|auth[-_ ]?bypass|session/i.test(f.rule || ''), to: 'A07:2021' },
+  { match: f => /\btls|cert|cipher|\bssl\b/i.test(f.rule || ''), to: 'A02:2021' },
+  { match: f => /\bcors|\bcsp|headers?|\bhttponly/i.test(f.rule || ''), to: 'A05:2021' },
+  { match: f => /\bexposed|\bdisclosed|server-status|admin\b/i.test(f.rule || ''), to: 'A05:2021' },
+  { match: f => /\bssrf|redirect/i.test(f.rule || ''),   to: 'A10:2021' }
+];
+
+function tagOwasp(finding) {
+  if (!finding || typeof finding !== 'object') return 'UNKNOWN';
+  for (const r of RULES) {
+    try {
+      if (r.match(finding)) return r.to;
+    } catch (_) { /* defensive: never throw from a tagger */ }
+  }
+  return 'UNKNOWN';
+}
+
+module.exports = {
+  tagOwasp,
+  listOwaspCategories,
+  listOwaspCategoryIds
+};

package/src/security-overlay/_shared/partial.js

@@ -0,0 +1,225 @@
+'use strict';
+
+// partial.js — the contract between phase skills and the report render.
+//
+// All phase skills write their findings to <securityDir>/<phase>.md using
+// this helper. The format is a YAML frontmatter (zero-dep serialization)
+// followed by `## <heading>` sections in a stable order. The report
+// (wize-sec-report) consumes these parciais and produces the final MD/HTML.
+//
+// Reruns are idempotent: writePartial overwrites the file in place; sections
+// are rendered in the order provided by the caller.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PARTIALS_SUBDIR = '.wize/security';
+
+// --- serialization helpers (zero-dep) ------------------------------------
+
+// YAML-quote a string value (only when needed). Strings that look like
+// numbers or booleans are still rendered as plain scalars — but the parse
+// side uses a STRICT type-coercion only when the string came in as a
+// non-string. That keeps version="2.9" round-tripping as a string.
+function yamlScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number') return String(value);
+  if (typeof value === 'string') {
+    // Quote when the string contains characters that YAML would mis-parse
+    // OR when the string is empty / has leading/trailing whitespace.
+    if (/[:#&*?|<>=!%@`\n]/.test(value) || value === '' || /^\s|\s$/.test(value)) {
+      return JSON.stringify(value);
+    }
+    return value;
+  }
+  throw new Error(`yamlScalar: unsupported type ${typeof value}`);
+}
+
+// Build a nested YAML mapping under a fixed indent. Used for `tools:` and
+// any other { name: { ... } } structure. Depth is unbounded; objects are
+// rendered as nested mappings, scalars as flat `key: value` lines.
+function renderNestedMap(obj, indent) {
+  const pad = ' '.repeat(indent);
+  const inner = ' '.repeat(indent + 2);
+  const out = [];
+  for (const [k, v] of Object.entries(obj)) {
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+      out.push(`${pad}${k}:`);
+      for (const [k2, v2] of Object.entries(v)) {
+        if (v2 && typeof v2 === 'object' && !Array.isArray(v2)) {
+          out.push(`${inner}${k2}:`);
+          const inner2 = ' '.repeat(indent + 4);
+          for (const [k3, v3] of Object.entries(v2)) {
+            out.push(`${inner2}${k3}: ${yamlScalar(v3)}`);
+          }
+        } else {
+          out.push(`${inner}${k2}: ${yamlScalar(v2)}`);
+        }
+      }
+    } else {
+      out.push(`${pad}${k}: ${yamlScalar(v)}`);
+    }
+  }
+  return out.join('\n');
+}
+
+// Parse a flat YAML frontmatter into an object. We only accept the limited
+// shape the helper writes: flat `key: value` lines plus a `tools:` block
+// that may nest 2 levels deep (tool -> { key: value }). This is
+// intentionally not a general YAML parser.
+function parseFrontmatter(text) {
+  const lines = text.split('\n');
+  const out = {};
+  let inTools = false;
+  let tools = null;
+  let toolKey = null;
+  for (const raw of lines) {
+    if (inTools) {
+      if (raw.trim() === '') continue;
+      // 2-space-indented top-level key under `tools:`.
+      const toolKeyMatch = raw.match(/^  ([a-zA-Z_][a-zA-Z0-9_-]*):\s*$/);
+      if (toolKeyMatch) {
+        toolKey = toolKeyMatch[1];
+        tools[toolKey] = {};
+        continue;
+      }
+      // 4-space-indented mapping under the current tool.
+      const valMatch = raw.match(/^    ([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+      if (valMatch && toolKey) {
+        tools[toolKey][valMatch[1]] = coerceScalar(valMatch[2]);
+        continue;
+      }
+      // Anything else ends the tools block.
+      if (/^\S/.test(raw)) {
+        inTools = false;
+        toolKey = null;
+        // fall through to the top-level branch on the same line
+      } else {
+        continue;
+      }
+    }
+    if (/^[a-zA-Z_][a-zA-Z0-9_-]*:(\s|$)/.test(raw)) {
+      const m = raw.match(/^([a-zA-Z_][a-zA-Z0-9_-]*):\s*(.*?)\s*$/);
+      if (!m) continue;
+      const [, k, vRaw] = m;
+      const v = vRaw.replace(/^['"]|['"]$/g, '');
+      if (k === 'tools') {
+        inTools = true;
+        tools = {};
+        out.tools = tools;
+        toolKey = null;
+        continue;
+      }
+      out[k] = coerceScalar(v);
+    }
+  }
+  return out;
+}
+
+function coerceScalar(v) {
+  // Strings are kept as strings (so version="2.9" round-trips as a string,
+  // not a number). Booleans and null are explicit.
+  if (v === 'true') return true;
+  if (v === 'false') return false;
+  if (v === 'null') return null;
+  // Inline JSON array: [a, b, c]
+  if (/^\[.*\]$/.test(v)) {
+    try { return JSON.parse(v); } catch (_) { /* fall through */ }
+  }
+  return v;
+}
+
+// --- public API ----------------------------------------------------------
+
+function defaultSecurityDir() {
+  return path.join(process.cwd(), PARTIALS_SUBDIR);
+}
+
+// Refuse phase names that try to escape the securityDir.
+function assertSafePhase(phase) {
+  if (typeof phase !== 'string' || !phase) {
+    throw new Error('invalid phase: empty');
+  }
+  if (phase.includes('..') || phase.includes('/') || phase.includes('\\') || path.isAbsolute(phase)) {
+    throw new Error(`partial phase-name-traversal: refused ${JSON.stringify(phase)}`);
+  }
+}
+
+// writePartial({ securityDir?, phase, mode, scope, status, tools?, sections })
+//   - sections: object of { heading: content } (preserves order via Object.keys).
+//   - Returns the absolute path of the written file.
+function writePartial(opts) {
+  if (!opts || typeof opts !== 'object') throw new Error('writePartial: opts required');
+  const phase = opts.phase;
+  assertSafePhase(phase);
+  const sec = opts.securityDir || defaultSecurityDir();
+  fs.mkdirSync(sec, { recursive: true });
+
+  const scope = opts.scope || {};
+  const scopeSha = (scope.frontmatter && scope.frontmatter.scope_sha256) || (opts.scopeSha256 || '');
+
+  const fm = [];
+  fm.push('---');
+  fm.push(`phase: ${yamlScalar(phase)}`);
+  fm.push(`generated_at: ${new Date().toISOString()}`);
+  fm.push(`scope_sha256: ${yamlScalar(scopeSha)}`);
+  fm.push(`mode: ${yamlScalar(opts.mode || 'passive')}`);
+  fm.push(`partial_status: ${yamlScalar(opts.status || 'complete')}`);
+  if (Array.isArray(opts.dependsOn) && opts.dependsOn.length) {
+    const arr = '[' + opts.dependsOn.map(v => JSON.stringify(String(v))).join(', ') + ']';
+    fm.push(`depends_on: ${arr}`);
+  }
+  if (opts.tools && Object.keys(opts.tools).length) {
+    fm.push(renderNestedMap({ tools: opts.tools }, 0));
+  }
+  fm.push('---');
+  fm.push('');
+
+  const body = [];
+  for (const [heading, content] of Object.entries(opts.sections || {})) {
+    body.push(`## ${heading}`);
+    body.push('');
+    body.push(String(content == null ? '' : content).trimEnd());
+    body.push('');
+  }
+
+  const file = path.join(sec, `${phase}.md`);
+  fs.writeFileSync(file, fm.join('\n') + '\n' + body.join('\n'), 'utf8');
+  return file;
+}
+
+// loadPartial({ securityDir?, phase }) -> { frontmatter, body } or null.
+function loadPartial(opts) {
+  const phase = opts.phase;
+  assertSafePhase(phase);
+  const sec = opts.securityDir || defaultSecurityDir();
+  const file = path.join(sec, `${phase}.md`);
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, 'utf8');
+  const fmMatch = text.match(/^---\n([\s\S]*?)\n---\n/);
+  if (!fmMatch) return null;
+  const frontmatter = parseFrontmatter(fmMatch[1]);
+  const body = text.slice(fmMatch[0].length);
+  return { frontmatter, body };
+}
+
+// listPartials({ securityDir? }) -> array of phase names (sorted).
+function listPartials(opts = {}) {
+  const sec = opts.securityDir || defaultSecurityDir();
+  if (!fs.existsSync(sec)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(sec)) {
+    if (name.endsWith('.md') && !name.startsWith('.')) {
+      out.push(name.replace(/\.md$/, ''));
+    }
+  }
+  return out.sort();
+}
+
+module.exports = {
+  writePartial,
+  loadPartial,
+  listPartials,
+  PARTIALS_SUBDIR
+};