@luizsantiago/spec-guardrails 3.0.1

package/lib/config.js

@@ -0,0 +1,293 @@
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+
+const CONFIG_PATH = ".specs/config.yaml";
+
+/** Map CLI phase names to config.yaml rules keys. */
+export const PHASE_ALIASES = {
+  explore: "explore",
+  constitution: "constitution",
+  specify: "specify",
+  discuss: "discuss",
+  design: "design",
+  tasks: "tasks",
+  analyze: "analyze",
+  implement: "implement",
+  execute: "implement",
+  loop: "implement",
+  verify: "verify",
+  validate: "verify",
+  archive: "archive",
+  converge: "converge",
+  quick: "quick",
+  handoff: "handoff",
+  memory: "handoff",
+};
+
+/**
+ * @typedef {Object} GuardrailsConfigDocument
+ * @property {string} [schema]
+ * @property {string} [extends]
+ * @property {string} [branch_prefix]
+ * @property {string} [context]
+ * @property {Record<string, string[]>} [rules]
+ * @property {{ rules?: Record<string, string[]> }} [overrides]
+ */
+
+/**
+ * Minimal YAML parser for the guardrails config schema (no external deps).
+ *
+ * @param {string} text
+ * @returns {GuardrailsConfigDocument}
+ */
+export function parseGuardrailsConfig(text) {
+  /** @type {GuardrailsConfigDocument} */
+  const config = {};
+  /** @type {Record<string, string[]> | undefined} */
+  let rules;
+  /** @type {Record<string, string[]> | undefined} */
+  let overrideRules;
+  /** @type {string | undefined} */
+  let currentRulesPhase;
+  /** @type {"rules" | "overrides" | undefined} */
+  let rulesSection;
+  let contextLines = null;
+  const lines = text.split("\n");
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+
+    if (contextLines !== null) {
+      if (line.startsWith("  ") || line.startsWith("\t")) {
+        contextLines.push(line.replace(/^\s{2}/, ""));
+        continue;
+      }
+
+      config.context = contextLines.join("\n").replace(/\n+$/, "");
+      contextLines = null;
+
+      if (trimmed === "") {
+        continue;
+      }
+    }
+
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    const scalar = trimmed.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (scalar) {
+      const [, key, value] = scalar;
+      if (key === "schema") {
+        config.schema = value.replace(/^['"]|['"]$/g, "");
+        continue;
+      }
+      if (key === "extends") {
+        config.extends = value.replace(/^['"]|['"]$/g, "");
+        continue;
+      }
+      if (key === "branch_prefix") {
+        config.branch_prefix = value.replace(/^['"]|['"]$/g, "");
+        continue;
+      }
+      if (key === "context" && value === "|") {
+        contextLines = [];
+        continue;
+      }
+      if (key === "rules" && value === "") {
+        rules = {};
+        config.rules = rules;
+        rulesSection = "rules";
+        currentRulesPhase = undefined;
+        continue;
+      }
+      if (key === "overrides" && value === "") {
+        config.overrides = {};
+        rulesSection = "overrides";
+        currentRulesPhase = undefined;
+        continue;
+      }
+    }
+
+    if (rulesSection === "overrides") {
+      const nestedRules = trimmed.match(/^rules:\s*$/);
+      if (nestedRules) {
+        overrideRules = {};
+        config.overrides ??= {};
+        config.overrides.rules = overrideRules;
+        currentRulesPhase = undefined;
+        continue;
+      }
+    }
+
+    const activeRules = rulesSection === "overrides" ? overrideRules : rules;
+    const rulesPhase = trimmed.match(/^([a-zA-Z0-9_-]+):\s*$/);
+    if (rulesPhase && activeRules) {
+      currentRulesPhase = rulesPhase[1];
+      activeRules[currentRulesPhase] = [];
+      continue;
+    }
+
+    const listItem = trimmed.match(/^-\s+(.+)$/);
+    if (listItem && currentRulesPhase && activeRules) {
+      activeRules[currentRulesPhase].push(listItem[1]);
+    }
+  }
+
+  if (contextLines !== null) {
+    config.context = contextLines.join("\n").replace(/\n+$/, "");
+  }
+
+  return config;
+}
+
+/**
+ * @param {GuardrailsConfigDocument | null | undefined} base
+ * @param {GuardrailsConfigDocument | null | undefined} overlay
+ * @returns {GuardrailsConfigDocument}
+ */
+export function mergeGuardrailsConfigs(base, overlay) {
+  /** @type {GuardrailsConfigDocument} */
+  const merged = {
+    schema: overlay?.schema ?? base?.schema,
+    branch_prefix: overlay?.branch_prefix ?? base?.branch_prefix,
+    rules: mergeRules(base?.rules, overlay?.rules),
+  };
+
+  const contexts = [base?.context, overlay?.context]
+    .map((value) => value?.trim())
+    .filter(Boolean);
+  if (contexts.length) {
+    merged.context = contexts.join("\n\n");
+  }
+
+  if (overlay?.overrides?.rules) {
+    merged.rules = mergeRules(merged.rules, overlay.overrides.rules);
+  }
+
+  return merged;
+}
+
+/**
+ * @param {Record<string, string[]> | undefined} base
+ * @param {Record<string, string[]> | undefined} overlay
+ * @returns {Record<string, string[]> | undefined}
+ */
+function mergeRules(base, overlay) {
+  if (!base && !overlay) {
+    return undefined;
+  }
+
+  /** @type {Record<string, string[]>} */
+  const merged = { ...(base ?? {}) };
+
+  for (const [phase, items] of Object.entries(overlay ?? {})) {
+    merged[phase] = [...(merged[phase] ?? []), ...items];
+  }
+
+  return merged;
+}
+
+/**
+ * Resolve extends chain and apply overrides.
+ *
+ * @param {GuardrailsConfigDocument} document
+ * @param {(name: string) => Promise<GuardrailsConfigDocument>} loadPreset
+ * @param {Set<string>} [seen]
+ * @returns {Promise<GuardrailsConfigDocument>}
+ */
+export async function resolveGuardrailsConfig(document, loadPreset, seen = new Set()) {
+  const { extends: presetName, overrides, ...local } = document;
+
+  if (!presetName) {
+    return mergeGuardrailsConfigs(null, { ...local, overrides });
+  }
+
+  if (seen.has(presetName)) {
+    throw new Error(`Config preset cycle detected: ${[...seen, presetName].join(" → ")}`);
+  }
+
+  seen.add(presetName);
+  const preset = await loadPreset(presetName);
+  const resolvedPreset = await resolveGuardrailsConfig(preset, loadPreset, seen);
+  const merged = mergeGuardrailsConfigs(resolvedPreset, local);
+  return mergeGuardrailsConfigs(merged, { overrides });
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<GuardrailsConfigDocument | null>}
+ */
+export async function loadGuardrailsConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, CONFIG_PATH);
+
+  try {
+    const text = await readFileSafe(configPath);
+    return parseGuardrailsConfig(text);
+  } catch (err) {
+    if (err.code === "ENOENT" || /cannot read/i.test(err.message)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string} phase
+ * @returns {string}
+ */
+export function normalizePhase(phase) {
+  const key = phase.trim().toLowerCase();
+  const mapped = PHASE_ALIASES[key];
+  if (!mapped) {
+    throw new Error(
+      `Unknown phase "${phase}". Known phases: ${[...new Set(Object.keys(PHASE_ALIASES))].sort().join(", ")}`,
+    );
+  }
+  return mapped;
+}
+
+/**
+ * Build markdown injected before a phase procedure.
+ *
+ * @param {string} phase
+ * @param {GuardrailsConfigDocument | null} config
+ * @returns {string}
+ */
+export function formatPhaseContext(phase, config) {
+  const normalized = normalizePhase(phase);
+  const parts = [];
+
+  if (config?.context?.trim()) {
+    parts.push("## Project context (.specs/config.yaml)\n");
+    parts.push(config.context.trim());
+    parts.push("");
+  }
+
+  const rules = config?.rules?.[normalized] ?? [];
+  if (rules.length) {
+    parts.push(`## Phase rules (${normalized})\n`);
+    for (const rule of rules) {
+      parts.push(`- ${rule}`);
+    }
+    parts.push("");
+  }
+
+  if (!parts.length) {
+    return `# Phase context: ${normalized}\n\n(no .specs/config.yaml or no entries for this phase)\n`;
+  }
+
+  return `# Phase context: ${normalized}\n\n${parts.join("\n").trimEnd()}\n`;
+}
+
+/**
+ * @param {string} phase
+ * @param {{ cwd?: string }} [options]
+ */
+export async function phaseContext(phase, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const { loadResolvedConfig } = await import("./presets.js");
+  const config = await loadResolvedConfig(cwd);
+  return formatPhaseContext(phase, config);
+}

package/lib/constants.js

@@ -0,0 +1,262 @@
+import { createRequire } from "node:module";
+
+export const { name: PACKAGE_NAME, version: PACKAGE_VERSION } =
+  createRequire(import.meta.url)("../package.json");
+
+export const CLI_NAME = "spec-guardrails";
+export const DISPLAY_NAME = "Spec Guardrails";
+export const NPX = (command) => `npx ${PACKAGE_NAME}${command ? ` ${command}` : ""}`;
+
+const REPO_RAW_BASE =
+  "https://raw.githubusercontent.com/luizssantiago92/spec-guardrails";
+
+/** Assets are fetched from the tag matching the installed CLI version. */
+export const PINNED_REF = `v${PACKAGE_VERSION}`;
+
+/** Used only when the pinned tag is not published yet. */
+export const FALLBACK_REF = "main";
+
+export const REPO_RAW_URL = `${REPO_RAW_BASE}/${PINNED_REF}`;
+
+export const FALLBACK_REPO_URL = `${REPO_RAW_BASE}/${FALLBACK_REF}`;
+
+export const SKILL_DIRS = [".cursor/skills", ".claude/skills"];
+
+export const CURSOR_RULES_DIR = ".cursor/rules";
+
+export const REFERENCES_SUBDIR = "references";
+
+export const GUARDRAILS_SCRIPTS_DIR = ".specs/guardrails/scripts";
+
+/** @type {{ file: string, remotePath: string }[]} */
+export const SKILL_ASSETS = [
+  {
+    file: "agent-architecture.md",
+    remotePath: "skills/agent-architecture.md",
+  },
+  {
+    file: "engineering-standards.md",
+    remotePath: "skills/engineering-standards.md",
+  },
+  {
+    file: "security-review.md",
+    remotePath: "skills/security-review.md",
+  },
+  {
+    file: "appsec.md",
+    remotePath: "skills/appsec.md",
+  },
+  {
+    file: "qa-strategy.md",
+    remotePath: "skills/qa-strategy.md",
+  },
+  {
+    file: "code-simplify.md",
+    remotePath: "skills/code-simplify.md",
+  },
+  {
+    file: "ship-ready.md",
+    remotePath: "skills/ship-ready.md",
+  },
+  {
+    file: "git-handoff.md",
+    remotePath: "skills/git-handoff.md",
+  },
+  {
+    file: "task-graph-engineering.md",
+    remotePath: "skills/task-graph-engineering.md",
+  },
+];
+
+/** Phase procedures loaded on demand by the hub skill. */
+/** @type {{ file: string, remotePath: string }[]} */
+export const REFERENCE_ASSETS = [
+  { file: "explore.md", remotePath: "skills/references/explore.md" },
+  { file: "project-init.md", remotePath: "skills/references/project-init.md" },
+  { file: "constitution.md", remotePath: "skills/references/constitution.md" },
+  { file: "specify.md", remotePath: "skills/references/specify.md" },
+  { file: "discuss.md", remotePath: "skills/references/discuss.md" },
+  { file: "design.md", remotePath: "skills/references/design.md" },
+  { file: "tasks.md", remotePath: "skills/references/tasks.md" },
+  { file: "analyze.md", remotePath: "skills/references/analyze.md" },
+  { file: "implement.md", remotePath: "skills/references/implement.md" },
+  { file: "validate.md", remotePath: "skills/references/validate.md" },
+  { file: "converge.md", remotePath: "skills/references/converge.md" },
+  { file: "archive.md", remotePath: "skills/references/archive.md" },
+  { file: "memory.md", remotePath: "skills/references/memory.md" },
+  { file: "quick-mode.md", remotePath: "skills/references/quick-mode.md" },
+  { file: "context-limits.md", remotePath: "skills/references/context-limits.md" },
+  { file: "lessons.md", remotePath: "skills/references/lessons.md" },
+  { file: "sub-agents.md", remotePath: "skills/references/sub-agents.md" },
+];
+
+/** Deterministic gates executed with python3. */
+/** @type {{ file: string, remotePath: string }[]} */
+export const SCRIPT_ASSETS = [
+  { file: "_common.py", remotePath: "scripts/_common.py" },
+  { file: "validate_spec.py", remotePath: "scripts/validate_spec.py" },
+  { file: "validate_tasks.py", remotePath: "scripts/validate_tasks.py" },
+  { file: "validate_state.py", remotePath: "scripts/validate_state.py" },
+  { file: "analyze_artifacts.py", remotePath: "scripts/analyze_artifacts.py" },
+  { file: "check_commit.py", remotePath: "scripts/check_commit.py" },
+  { file: "lessons.py", remotePath: "scripts/lessons.py" },
+  { file: "loop_plan.py", remotePath: "scripts/loop_plan.py" },
+];
+
+/** @type {{ file: string, remotePath: string }[]} */
+export const RULE_ASSETS = [
+  {
+    file: "engineering-baseline.mdc",
+    remotePath: "rules/engineering-baseline.mdc",
+  },
+];
+
+export const STATE_HEADER = `# 📝 Project State & Decisions
+
+## Active Feature
+- Feature: —
+- Phase: —
+- Branch: —
+
+## Next Step (single item)
+- [ ] —
+
+## Blockers
+- none
+
+## Deferred Ideas
+- none
+
+## Decisions
+`;
+
+export const LESSONS_HEADER = `# Lessons Learned
+
+Generated by \`lessons.py\` from \`.specs/lessons.json\`. Do not edit this file.
+A clean PASS records nothing. Only **confirmed** lessons below are guidance.
+Inspect candidates with \`python3 .specs/guardrails/scripts/lessons.py list --status all\`.
+
+- none yet
+`;
+
+export const CURSORRULES_MARKER_BEGIN = "<!-- SPEC-GUARDRAILS:BEGIN -->";
+
+export const CURSORRULES_MARKER_END = "<!-- SPEC-GUARDRAILS:END -->";
+
+/**
+ * Prior product markers — recognized only so `install` can upgrade `.cursorrules`.
+ * Runtime does not dual-path scripts under these names.
+ */
+export const LEGACY_CURSORRULES_MARKER_PAIRS = [
+  ["<!-- SPEC-SEATBELT:BEGIN -->", "<!-- SPEC-SEATBELT:END -->"],
+  ["<!-- AGENTIC-HARNESS:BEGIN -->", "<!-- AGENTIC-HARNESS:END -->"],
+];
+
+/** @deprecated Use LEGACY_CURSORRULES_MARKER_PAIRS */
+export const LEGACY_CURSORRULES_MARKER_BEGIN = "<!-- AGENTIC-HARNESS:BEGIN -->";
+
+/** @deprecated Use LEGACY_CURSORRULES_MARKER_PAIRS */
+export const LEGACY_CURSORRULES_MARKER_END = "<!-- AGENTIC-HARNESS:END -->";
+
+export const CURSORRULES_BLOCK = `${CURSORRULES_MARKER_BEGIN}
+# Execution Contract (Spec Guardrails)
+When planning architecture, specs, or multi-step features, read the hub first:
+- \`.cursor/skills/agent-architecture.md\` — SDD hub: contract, phases, gates, complexity router
+- \`.cursor/skills/references/\` — phase procedures (explore, project-init, constitution, specify, discuss, design, tasks, analyze, implement, validate, converge, archive, memory, quick-mode, context-limits, lessons, sub-agents)
+- \`.cursor/skills/task-graph-engineering.md\` — task DAG, parallelism, verify topology
+- \`.cursor/skills/engineering-standards.md\` — secure coding, code quality, artifact language
+- \`.cursor/skills/security-review.md\` — security checklist for /verify
+- \`.cursor/skills/appsec.md\` — conditional AppSec (Complex / attack surface); never with other conditionals at once
+- \`.cursor/skills/qa-strategy.md\` — conditional QA strategy; load after AppSec if both apply
+- \`.cursor/skills/code-simplify.md\` — conditional simplify (Medium+ after A–D or owner ask)
+- \`.cursor/skills/ship-ready.md\` — conditional ship checklist (owner ask; does not authorize push)
+- \`.cursor/skills/git-handoff.md\` — git sync and session handoff for .specs/
+
+Deterministic gates (python3, non-zero exit means STOP):
+- Scripts in \`.specs/guardrails/scripts/\` — the **agent** runs them at phase boundaries (see hub).
+- Humans: \`install\` once; optional \`feature-init\`, \`project-init\`, \`doctor\`. Full CLI: \`npx @luizsantiago/spec-guardrails --help\`.
+- Onboarding: \`.specs/GETTING_STARTED.md\`
+
+All project artifacts are written in English.
+Persistent state: \`.specs/STATE.md\` (decisions/handoff), \`.specs/lessons.json\` (canonical lessons), and \`.specs/LESSONS.md\` (generated playbook).
+Project rules: \`.cursor/rules/engineering-baseline.mdc\`
+${CURSORRULES_MARKER_END}
+`;
+
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]", "::1"]);
+
+/**
+ * Assets become executable gate scripts on disk, so the source has to be
+ * trustworthy. Plain HTTP is rejected except against a local host, which the
+ * test suite uses.
+ *
+ * @param {string} base
+ * @returns {string} the validated base, without a trailing slash
+ */
+function assertAllowedAssetUrl(raw) {
+  let url;
+
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`Invalid guardrails asset URL: ${raw}`);
+  }
+
+  const isLocal = LOCAL_HOSTS.has(url.hostname);
+
+  if (url.protocol === "https:" || (url.protocol === "http:" && isLocal)) {
+    return url;
+  }
+
+  throw new Error(
+    `Refusing to download guardrails assets over ${url.protocol}//${url.hostname} ` +
+      "— only HTTPS sources are allowed. Guardrails assets include executable gate scripts.",
+  );
+}
+
+export function assertSafeAssetBase(base) {
+  assertAllowedAssetUrl(base);
+  return base.replace(/\/+$/, "");
+}
+
+/**
+ * Validate a full download URL (including path), including each redirect hop.
+ * Returns the URL string unchanged when the scheme/host policy passes.
+ * When `sourceUrl` is set (a redirect hop), the next URL must share that origin.
+ *
+ * @param {string} raw
+ * @param {string} [sourceUrl] previous hop; cross-origin redirects are refused
+ * @returns {string}
+ */
+export function assertSafeDownloadUrl(raw, sourceUrl) {
+  assertAllowedAssetUrl(raw);
+
+  if (sourceUrl) {
+    const next = new URL(raw);
+    const from = new URL(sourceUrl);
+    if (next.origin !== from.origin) {
+      throw new Error(
+        `Refusing to follow a cross-origin redirect from ${from.origin} to ${next.origin}`,
+      );
+    }
+  }
+
+  return raw;
+}
+
+/** @returns {string | undefined} the override base, when one is configured */
+export function resolveAssetOverride() {
+  const override = process.env.SPEC_GUARDRAILS_REPO_URL;
+  return override ? assertSafeAssetBase(override) : undefined;
+}
+
+/**
+ * @param {string} remotePath
+ * @param {string} [repoUrl]
+ */
+export function resolveAssetUrl(remotePath, repoUrl) {
+  const base = assertSafeAssetBase(
+    repoUrl ?? resolveAssetOverride() ?? REPO_RAW_URL,
+  );
+  return `${base}/${remotePath}`;
+}

package/lib/cursorrules.js

@@ -0,0 +1,92 @@
+import path from "node:path";
+
+import {
+  CURSORRULES_BLOCK,
+  CURSORRULES_MARKER_BEGIN,
+  CURSORRULES_MARKER_END,
+  LEGACY_CURSORRULES_MARKER_PAIRS,
+} from "./constants.js";
+import {
+  appendFileSafe,
+  readFileSafe,
+  writeFileSafe,
+} from "./fs-utils.js";
+
+const MARKER_PAIRS = [
+  [CURSORRULES_MARKER_BEGIN, CURSORRULES_MARKER_END],
+  ...LEGACY_CURSORRULES_MARKER_PAIRS,
+];
+
+/**
+ * @param {string} content
+ * @returns {{ start: number, end: number, begin: string, endMarker: string } | null}
+ */
+function locateGuardrailsBlock(content) {
+  for (const [begin, endMarker] of MARKER_PAIRS) {
+    const start = content.indexOf(begin);
+    const end = content.indexOf(endMarker);
+
+    if (start !== -1 && end !== -1 && end >= start) {
+      return { start, end, begin, endMarker };
+    }
+  }
+
+  return null;
+}
+
+function extractGuardrailsBlock(content) {
+  const located = locateGuardrailsBlock(content);
+  if (!located) {
+    return null;
+  }
+
+  return content.slice(located.start, located.end + located.endMarker.length);
+}
+
+function replaceGuardrailsBlock(content) {
+  const located = locateGuardrailsBlock(content);
+  if (!located) {
+    return null;
+  }
+
+  const before = content.slice(0, located.start);
+  const after = content.slice(located.end + located.endMarker.length);
+  const trimmedBlock = `${CURSORRULES_BLOCK.trim()}\n`;
+
+  return `${before}${trimmedBlock}${after.replace(/^\n+/, "")}`;
+}
+
+export async function injectCursorRules(cwd) {
+  const rulesPath = path.join(cwd, ".cursorrules");
+  const expectedBlock = CURSORRULES_BLOCK.trim();
+
+  try {
+    const existing = await readFileSafe(rulesPath);
+    const currentBlock = extractGuardrailsBlock(existing);
+
+    if (currentBlock) {
+      if (currentBlock.trim() === expectedBlock) {
+        return { created: false, updated: false };
+      }
+
+      const replaced = replaceGuardrailsBlock(existing);
+      if (replaced === null) {
+        throw new Error(`Failed to upgrade guardrails block in ${rulesPath}`);
+      }
+
+      await writeFileSafe(rulesPath, replaced.endsWith("\n") ? replaced : `${replaced}\n`);
+      return { created: false, updated: true };
+    }
+
+    const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+    await appendFileSafe(rulesPath, `${separator}${CURSORRULES_BLOCK}\n`);
+    return { created: false, updated: true };
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      throw err;
+    }
+  }
+
+  await writeFileSafe(rulesPath, `${CURSORRULES_BLOCK}\n`);
+  return { created: true, updated: false };
+}