@luizsantiago/spec-guardrails 3.0.1

package/lib/delta-merge.js

@@ -0,0 +1,248 @@
+const REQUIREMENT_HEADING =
+  /^(?<level>#{2,6})\s*(?<id>[A-Z][A-Z0-9]{1,9}-\d{2,4})\s*[:\-–]?\s*(?<title>.*)$/gm;
+const ANY_HEADING = /^(?<level>#{1,6})\s+\S/m;
+
+const DELTA_SECTIONS = [
+  "ADDED Requirements",
+  "MODIFIED Requirements",
+  "REMOVED Requirements",
+];
+
+const REMOVED_ID = /^\s*(?:-\s*)?(?<id>[A-Z][A-Z0-9]{1,9}-\d{2,4})\b/gm;
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isDeltaSpec(text) {
+  return DELTA_SECTIONS.some((heading) => hasSection(text, heading));
+}
+
+/**
+ * @param {string} text
+ * @param {string} heading
+ * @returns {boolean}
+ */
+function hasSection(text, heading) {
+  const pattern = new RegExp(`^#{1,6}\\s+${escapeRegExp(heading)}\\s*$`, "im");
+  return pattern.test(text);
+}
+
+/**
+ * @param {string} value
+ * @returns {string}
+ */
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * @param {string} text
+ * @param {string} sectionHeading
+ * @returns {string | null}
+ */
+function sectionBody(text, sectionHeading) {
+  const headingPattern = new RegExp(
+    `^(?<level>#{2,6})\\s*${escapeRegExp(sectionHeading)}\\b`,
+    "im",
+  );
+  const match = headingPattern.exec(text);
+  if (!match) {
+    return null;
+  }
+
+  const level = match[0].match(/^#+/)?.[0].length ?? 2;
+  const start = match.index + match[0].length;
+  let end = text.length;
+
+  const rest = text.slice(start);
+  for (const heading of rest.matchAll(/^(#{1,6})\s+\S/gm)) {
+    if (heading.index === undefined) {
+      continue;
+    }
+    if (heading[1].length <= level) {
+      end = start + heading.index;
+      break;
+    }
+  }
+
+  return text.slice(start, end);
+}
+
+/**
+ * @param {string} scoped
+ * @returns {Map<string, string>}
+ */
+function extractRequirementBlocks(scoped) {
+  /** @type {Map<string, string>} */
+  const blocks = new Map();
+
+  const headingRe = new RegExp(REQUIREMENT_HEADING.source, REQUIREMENT_HEADING.flags);
+  let match = headingRe.exec(scoped);
+
+  while (match) {
+    const level = match.groups.level.length;
+    const id = match.groups.id;
+    const blockStart = match.index;
+    let blockEnd = scoped.length;
+
+    const scanRe = new RegExp(REQUIREMENT_HEADING.source, REQUIREMENT_HEADING.flags);
+    scanRe.lastIndex = match.index + match[0].length;
+    let next = scanRe.exec(scoped);
+    while (next) {
+      if (next.groups.level.length <= level) {
+        blockEnd = next.index;
+        break;
+      }
+      next = scanRe.exec(scoped);
+    }
+
+    const headingLine = scoped.slice(blockStart, match.index + match[0].length).split("\n")[0];
+    const body = scoped.slice(match.index + match[0].length, blockEnd).trimEnd();
+    blocks.set(id, `${headingLine}\n${body}`.trimEnd());
+
+    headingRe.lastIndex = blockEnd;
+    match = headingRe.exec(scoped);
+  }
+
+  return blocks;
+}
+
+/**
+ * @param {string} text
+ * @returns {Map<string, string>}
+ */
+export function extractDomainRequirements(text) {
+  const requirementsSection = sectionBody(text, "Requirements");
+  if (!requirementsSection) {
+    return new Map();
+  }
+  return extractRequirementBlocks(requirementsSection);
+}
+
+/**
+ * @param {string} domainSpec
+ * @param {Map<string, string>} requirements
+ * @returns {string}
+ */
+function writeDomainRequirements(domainSpec, requirements) {
+  const blocks = [...requirements.values()];
+  const requirementsBody = blocks.length ? `\n${blocks.join("\n\n")}\n` : "\n- none\n";
+
+  if (hasSection(domainSpec, "Requirements")) {
+    const headingPattern = /^#{2,6}\s*Requirements\b/im;
+    const match = headingPattern.exec(domainSpec);
+    if (!match) {
+      return domainSpec;
+    }
+
+    const level = match[0].match(/^#+/)?.[0] ?? "##";
+    const start = match.index;
+    const levelLen = level.length;
+    let end = domainSpec.length;
+
+    for (const heading of domainSpec.slice(start + match[0].length).matchAll(/^(#{1,6})\s+\S/gm)) {
+      if (heading.index === undefined) {
+        continue;
+      }
+      if (heading[1].length <= levelLen) {
+        end = start + match[0].length + heading.index;
+        break;
+      }
+    }
+
+    return (
+      domainSpec.slice(0, start) +
+      `${level} Requirements${requirementsBody}` +
+      domainSpec.slice(end).replace(/^\n+/, "")
+    );
+  }
+
+  const trimmed = domainSpec.trimEnd();
+  return `${trimmed}\n\n## Requirements${requirementsBody}`;
+}
+
+/**
+ * @param {string} scoped
+ * @returns {string[]}
+ */
+function extractRemovedIds(scoped) {
+  if (!scoped) {
+    return [];
+  }
+  if (/\bnone\b/i.test(scoped.trim())) {
+    return [];
+  }
+
+  /** @type {string[]} */
+  const ids = [];
+  for (const match of scoped.matchAll(REMOVED_ID)) {
+    ids.push(match.groups.id);
+  }
+  return ids;
+}
+
+/**
+ * Merge a feature spec (full or delta) into a domain spec.
+ *
+ * @param {string} domainSpec
+ * @param {string} featureSpec
+ * @returns {{ spec: string, summary: string[] }}
+ */
+export function mergeFeatureIntoDomain(domainSpec, featureSpec) {
+  const summary = [];
+  let requirements = extractDomainRequirements(domainSpec);
+
+  if (isDeltaSpec(featureSpec)) {
+    const added = sectionBody(featureSpec, "ADDED Requirements");
+    const modified = sectionBody(featureSpec, "MODIFIED Requirements");
+    const removed = sectionBody(featureSpec, "REMOVED Requirements");
+
+    for (const [id, block] of extractRequirementBlocks(added ?? "")) {
+      requirements.set(id, block);
+      summary.push(`ADDED ${id}`);
+    }
+
+    for (const [id, block] of extractRequirementBlocks(modified ?? "")) {
+      requirements.set(id, block);
+      summary.push(`MODIFIED ${id}`);
+    }
+
+    for (const id of extractRemovedIds(removed ?? "")) {
+      if (requirements.delete(id)) {
+        summary.push(`REMOVED ${id}`);
+      } else {
+        summary.push(`REMOVED ${id} (not in domain spec)`);
+      }
+    }
+  } else {
+    const fullRequirements = sectionBody(featureSpec, "Requirements");
+    if (fullRequirements) {
+      requirements = extractRequirementBlocks(fullRequirements);
+      summary.push(`copied ${requirements.size} requirement(s) from full spec`);
+    } else {
+      summary.push("full spec has no Requirements section — domain spec unchanged");
+    }
+  }
+
+  return {
+    spec: writeDomainRequirements(domainSpec, requirements),
+    summary,
+  };
+}
+
+/**
+ * @param {string} domain
+ * @param {string} featureId
+ * @returns {string}
+ */
+export function domainSpecStub(domain, featureId) {
+  return `# Domain: ${domain}
+
+> Seeded by archive-feature from \`${featureId}\`.
+
+## Requirements
+
+- none
+`;
+}

package/lib/doctor.js

@@ -0,0 +1,343 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import { NPX, SKILL_DIRS } from "./constants.js";
+import { resolveScriptsDir } from "./gates.js";
+import { readFileSafe } from "./fs-utils.js";
+import { listFeatureIds } from "./specs-utils.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   label: string,
+ *   weight: number,
+ *   pass: boolean,
+ *   suggest?: string,
+ *   optional?: boolean,
+ * }} DoctorCheck
+ */
+
+/**
+ * @param {string} cwd
+ * @param {string} relativePath
+ * @returns {Promise<boolean>}
+ */
+async function pathExists(cwd, relativePath) {
+  try {
+    await fs.access(path.join(cwd, relativePath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function pythonAvailable() {
+  for (const bin of ["python3", "python"]) {
+    try {
+      const { stdout } = await execFileAsync(bin, ["--version"]);
+      const match = stdout.match(/(\d+)\.(\d+)/);
+      if (!match) {
+        continue;
+      }
+      const major = Number(match[1]);
+      const minor = Number(match[2]);
+      if (major > 3 || (major === 3 && minor >= 10)) {
+        return true;
+      }
+    } catch {
+      // try next binary
+    }
+  }
+  return false;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
+async function readActiveFeature(cwd) {
+  try {
+    const state = await readFileSafe(path.join(cwd, ".specs/STATE.md"));
+    const match = state.match(/^\s*[-*]\s*\*\*Active feature\*\*:\s*(.+)$/im);
+    if (!match) {
+      return null;
+    }
+    const value = match[1].trim();
+    if (!value || /^none|idle|—|-$/i.test(value)) {
+      return null;
+    }
+    return value.replace(/^`|`$/g, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<DoctorCheck[]>}
+ */
+export async function runDoctorChecks(cwd) {
+  /** @type {DoctorCheck[]} */
+  const checks = [];
+
+  const hubInstalled = (
+    await Promise.all(
+      SKILL_DIRS.map((dir) => pathExists(cwd, path.join(dir, "agent-architecture.md"))),
+    )
+  ).some(Boolean);
+
+  checks.push({
+    id: "skills-hub",
+    label: "Agent hub skill (agent-architecture.md)",
+    weight: 12,
+    pass: hubInstalled,
+    suggest: NPX("install"),
+  });
+
+  const scriptsDir = await resolveScriptsDir(cwd);
+  const gatesDir = path.join(cwd, scriptsDir);
+  let gatesPresent = false;
+  try {
+    const entries = await fs.readdir(gatesDir);
+    gatesPresent = entries.some((name) => name.endsWith(".py"));
+  } catch {
+    gatesPresent = false;
+  }
+
+  checks.push({
+    id: "gate-scripts",
+    label: `Python gate scripts under ${scriptsDir}/`,
+    weight: 15,
+    pass: gatesPresent,
+    suggest: NPX("install"),
+  });
+
+  const pythonOk = await pythonAvailable();
+  checks.push({
+    id: "python",
+    label: "Python 3.10+ available for gates",
+    weight: 8,
+    pass: pythonOk,
+    suggest: "Install Python 3.10+ or run gate checklists manually from skills/references/",
+  });
+
+  const specsScaffold =
+    (await pathExists(cwd, ".specs/STATE.md")) &&
+    (await pathExists(cwd, ".specs/features")) &&
+    (await pathExists(cwd, ".specs/project"));
+
+  checks.push({
+    id: "specs-scaffold",
+    label: ".specs/ memory scaffold (STATE, features/, project/)",
+    weight: 10,
+    pass: specsScaffold,
+    suggest: NPX("install"),
+  });
+
+  checks.push({
+    id: "config",
+    label: ".specs/config.yaml project config",
+    weight: 10,
+    pass: await pathExists(cwd, ".specs/config.yaml"),
+    suggest: NPX("init-config --preset default"),
+  });
+
+  checks.push({
+    id: "baseline-rule",
+    label: "engineering-baseline.mdc always-on rule",
+    weight: 8,
+    pass: await pathExists(cwd, ".cursor/rules/engineering-baseline.mdc"),
+    suggest: NPX("install"),
+  });
+
+  const hasProjectMd = await pathExists(cwd, ".specs/project/PROJECT.md");
+  checks.push({
+    id: "project-context",
+    label: "PROJECT.md brownfield context",
+    weight: 10,
+    pass: hasProjectMd,
+    optional: true,
+    suggest: NPX("project-init"),
+  });
+
+  const activeFeature = await readActiveFeature(cwd);
+  let activeFeatureOk = true;
+  let activeFeatureSuggest;
+
+  if (activeFeature) {
+    const features = await listFeatureIds(cwd);
+    activeFeatureOk = features.includes(activeFeature);
+    if (!activeFeatureOk) {
+      activeFeatureSuggest = `Update .specs/STATE.md or run feature-init — "${activeFeature}" not found under .specs/features/`;
+    }
+  }
+
+  checks.push({
+    id: "state-feature",
+    label: "STATE.md active feature matches .specs/features/",
+    weight: 5,
+    pass: activeFeatureOk,
+    suggest: activeFeatureSuggest,
+  });
+
+  let gateSmoke = false;
+  if (gatesPresent && pythonOk) {
+    try {
+      const script = path.join(cwd, scriptsDir, "check_commit.py");
+      await execFileAsync("python3", [
+        script,
+        "--message",
+        "chore(guardrails): doctor smoke test",
+      ], { cwd });
+      gateSmoke = true;
+    } catch {
+      gateSmoke = false;
+    }
+  }
+
+  checks.push({
+    id: "gate-smoke",
+    label: "check-commit gate runs",
+    weight: 12,
+    pass: gateSmoke,
+    suggest: gatesPresent
+      ? "Fix Python gate install or run: python3 .specs/guardrails/scripts/check_commit.py --message \"test: smoke\""
+      : NPX("install"),
+  });
+
+  if (activeFeature) {
+    const featureDir = path.join(cwd, ".specs/features", activeFeature);
+    const tasksPath = path.join(featureDir, "tasks.md");
+    let taskCount = 0;
+    let needsGraph = false;
+    let hasGraph = false;
+
+    try {
+      const tasks = await readFileSafe(tasksPath);
+      taskCount = (tasks.match(/^#{2,6}\s*T\d+/gim) ?? []).length;
+      needsGraph = taskCount >= 3;
+      hasGraph = await pathExists(cwd, path.join(".specs/features", activeFeature, "task-graph.md"));
+    } catch {
+      needsGraph = false;
+    }
+
+    if (needsGraph) {
+      checks.push({
+        id: "task-graph",
+        label: `task-graph.md for active feature (${taskCount} tasks)`,
+        weight: 10,
+        pass: hasGraph,
+        suggest: `Draw the DAG in .specs/features/${activeFeature}/task-graph.md (see task-graph-engineering.md)`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+/**
+ * Contextual Execute hint when the active feature has tasks.md.
+ *
+ * @param {string} cwd
+ * @param {string | null} activeFeature
+ * @returns {Promise<string | null>}
+ */
+export async function resolveExecuteHint(cwd, activeFeature) {
+  if (!activeFeature) {
+    return null;
+  }
+
+  const tasksPath = path.join(cwd, ".specs/features", activeFeature, "tasks.md");
+
+  try {
+    const tasks = await readFileSafe(tasksPath);
+    const taskIds = tasks.match(/^#{2,6}\s*T\d+/gim) ?? [];
+    if (taskIds.length === 0) {
+      return null;
+    }
+
+    const completeCount = (tasks.match(/-\s*\[x\]\s*complete\b/gi) ?? []).length;
+    if (completeCount >= taskIds.length) {
+      return `${NPX(`validate-state ${activeFeature}`)} — tasks look complete; run Validate before /verify`;
+    }
+
+    return `${NPX(`loop-plan ${activeFeature}`)} — next Execute wave (then /loop in chat)`;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {DoctorCheck[]} checks
+ * @returns {number}
+ */
+export function scoreDoctorChecks(checks) {
+  const scored = checks.filter((check) => !check.optional);
+  const earned = scored.filter((check) => check.pass).reduce((sum, check) => sum + check.weight, 0);
+  const total = scored.reduce((sum, check) => sum + check.weight, 0);
+  if (total === 0) {
+    return 0;
+  }
+  return Math.round((earned / total) * 100);
+}
+
+/**
+ * @param {DoctorCheck[]} checks
+ * @param {number} limit
+ * @returns {DoctorCheck[]}
+ */
+export function topDoctorSuggestions(checks, limit = 3) {
+  return checks.filter((check) => !check.pass && check.suggest).slice(0, limit);
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ suggest?: boolean, json?: boolean }} [options]
+ * @returns {Promise<{ score: number, checks: DoctorCheck[], suggestions: DoctorCheck[], executeHint: string | null }>}
+ */
+export async function doctor(cwd, options = {}) {
+  const checks = await runDoctorChecks(cwd);
+  const score = scoreDoctorChecks(checks);
+  const suggestions = topDoctorSuggestions(checks);
+  const activeFeature = await readActiveFeature(cwd);
+  const executeHint = await resolveExecuteHint(cwd, activeFeature);
+
+  if (options.json) {
+    console.log(
+      JSON.stringify({ score, checks, suggestions, executeHint }, null, 2),
+    );
+    return { score, checks, suggestions, executeHint };
+  }
+
+  console.log(`Guardrails Ready: ${score}/100\n`);
+
+  for (const check of checks) {
+    const mark = check.pass ? "✓" : "✗";
+    const optional = check.optional ? " (optional)" : "";
+    console.log(`${mark} ${check.label}${optional}`);
+    if (!check.pass && check.suggest && options.suggest !== false) {
+      console.log(`  → ${check.suggest}`);
+    }
+  }
+
+  if (suggestions.length > 0) {
+    console.log("\nTop next actions:");
+    suggestions.forEach((check, index) => {
+      console.log(`${index + 1}. ${check.suggest}`);
+    });
+  }
+
+  if (executeHint) {
+    console.log(`\nExecute hint:\n  → ${executeHint}`);
+  }
+
+  return { score, checks, suggestions, executeHint };
+}

package/lib/download.js

@@ -0,0 +1,133 @@
+import { createWriteStream } from "node:fs";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+import { assertSafeDownloadUrl } from "./constants.js";
+import { assertSafeWriteTarget, removeFileSafe } from "./fs-utils.js";
+
+/** A stalled mirror should fail the install instead of hanging it. */
+const REQUEST_TIMEOUT_MS = 30_000;
+
+/** Harness assets are markdown and small scripts; anything larger is suspect. */
+const MAX_ASSET_BYTES = 2 * 1024 * 1024;
+
+/** Cap redirect chains so a malicious mirror cannot loop forever. */
+const MAX_REDIRECTS = 10;
+
+function limitSize(url, limit) {
+  let received = 0;
+
+  return new Transform({
+    transform(chunk, _encoding, callback) {
+      received += chunk.length;
+
+      if (received > limit) {
+        callback(
+          new Error(
+            `Download failed: ${url} exceeds the ${limit}-byte asset limit`,
+          ),
+        );
+        return;
+      }
+
+      callback(null, chunk);
+    },
+  });
+}
+
+/**
+ * Follow redirects manually so every hop re-validates the HTTPS/localhost policy.
+ *
+ * @param {string} startUrl
+ * @returns {Promise<Response>}
+ */
+async function fetchWithSafeRedirects(startUrl) {
+  let current = assertSafeDownloadUrl(startUrl);
+
+  for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+    let response;
+
+    try {
+      response = await fetch(current, {
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        redirect: "manual",
+      });
+    } catch (err) {
+      if (err.name === "TimeoutError" || err.name === "AbortError") {
+        throw new Error(
+          `Download failed: ${current} timed out after ${REQUEST_TIMEOUT_MS}ms`,
+        );
+      }
+      throw new Error(
+        `Download failed: unable to reach ${current} (${err.message})`,
+      );
+    }
+
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (!location) {
+        throw new Error(
+          `Download failed: redirect ${response.status} from ${current} with no Location`,
+        );
+      }
+
+      let next;
+      try {
+        next = new URL(location, current).href;
+      } catch {
+        throw new Error(
+          `Download failed: invalid redirect Location from ${current}`,
+        );
+      }
+
+      try {
+        current = assertSafeDownloadUrl(next, current);
+      } catch (err) {
+        throw new Error(
+          `Download failed: redirect from ${startUrl} to disallowed URL (${err.message})`,
+        );
+      }
+      continue;
+    }
+
+    return response;
+  }
+
+  throw new Error(
+    `Download failed: too many redirects while fetching ${startUrl}`,
+  );
+}
+
+export async function downloadToFile(url, destPath) {
+  await assertSafeWriteTarget(destPath);
+
+  const response = await fetchWithSafeRedirects(url);
+
+  if (!response.ok) {
+    throw new Error(`Download failed: ${response.status} ${url}`);
+  }
+
+  if (!response.body) {
+    throw new Error(`Download failed: empty response body from ${url}`);
+  }
+
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > MAX_ASSET_BYTES) {
+    throw new Error(
+      `Download failed: ${url} exceeds the ${MAX_ASSET_BYTES}-byte asset limit`,
+    );
+  }
+
+  const body = Readable.fromWeb(response.body);
+  const fileStream = createWriteStream(destPath);
+
+  try {
+    await pipeline(body, limitSize(url, MAX_ASSET_BYTES), fileStream);
+  } catch (err) {
+    await removeFileSafe(destPath);
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new Error(`Permission denied: cannot write ${destPath}`);
+    }
+    throw err;
+  }
+}