@luizsantiago/spec-guardrails 3.0.1

package/lib/next-steps.js

@@ -0,0 +1,50 @@
+/**
+ * Human-facing messages after install — keep CLI surface minimal.
+ */
+
+/**
+ * @param {{ pythonAvailable?: boolean, preset?: string }} [options]
+ * @returns {string[]}
+ */
+export function formatInstallNextSteps(options = {}) {
+  const lines = [
+    "",
+    "✨ Setup complete.",
+    "",
+    "Next:",
+    "  1. Open Cursor or Claude Code in this project.",
+    "  2. Run **Specify** (`/specify` or “Specify a feature: …”).",
+    "",
+    "  Guide: docs/guide/Quick-start.md (repo) · .specs/GETTING_STARTED.md (this project)",
+  ];
+
+  if (options.preset) {
+    lines.push(`  Config: .specs/config.yaml (preset: ${options.preset})`);
+  }
+
+  if (options.pythonAvailable === false) {
+    lines.push(
+      "  Note: install Python 3.10+ for automatic gates, or the agent checks by hand.",
+    );
+  }
+
+  lines.push(
+    "",
+    "Optional CLI (you rarely need these on day one):",
+    "  project-init   existing repo with code already",
+    "  doctor         if something looks wrong",
+    "  --help         full command list",
+    "",
+  );
+
+  return lines;
+}
+
+/**
+ * @param {{ pythonAvailable?: boolean, preset?: string }} [options]
+ */
+export function printInstallNextSteps(options = {}) {
+  for (const line of formatInstallNextSteps(options)) {
+    console.log(line);
+  }
+}

package/lib/presets.js

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { mergeGuardrailsConfigs, parseGuardrailsConfig, resolveGuardrailsConfig } from "./config.js";
+import { ensureDir, readFileSafe, writeFileIfMissing, writeFileSafe } from "./fs-utils.js";
+
+const PACKAGE_ROOT = path.resolve(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), ".."),
+);
+
+export const PRESETS_DIR = "templates/presets";
+export const CONFIG_PATH = ".specs/config.yaml";
+
+/**
+ * @param {string} name
+ * @returns {string}
+ */
+export function presetAssetPath(name) {
+  return path.join(PACKAGE_ROOT, PRESETS_DIR, `${name}.yaml`);
+}
+
+/**
+ * @returns {Promise<string[]>}
+ */
+export async function listPresets() {
+  const dir = path.join(PACKAGE_ROOT, PRESETS_DIR);
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".yaml"))
+    .map((entry) => entry.name.replace(/\.yaml$/, ""))
+    .sort();
+}
+
+/**
+ * @param {string} name
+ * @returns {Promise<string>}
+ */
+export async function loadPresetText(name) {
+  const presets = await listPresets();
+  if (!presets.includes(name)) {
+    throw new Error(
+      `Unknown preset "${name}". Available: ${presets.join(", ")}`,
+    );
+  }
+
+  return readFileSafe(presetAssetPath(name));
+}
+
+/**
+ * @param {string} name
+ */
+export async function loadPreset(name) {
+  const text = await loadPresetText(name);
+  return parseGuardrailsConfig(text);
+}
+
+/**
+ * @param {ReturnType<typeof parseGuardrailsConfig>} document
+ * @param {Set<string>} [seen]
+ * @returns {Promise<ReturnType<typeof parseGuardrailsConfig>>}
+ */
+export async function resolveConfigDocument(document, seen = new Set()) {
+  return resolveGuardrailsConfig(document, loadPreset, seen);
+}
+
+/**
+ * @param {string} [cwd]
+ * @returns {Promise<ReturnType<typeof parseGuardrailsConfig> | null>}
+ */
+export async function loadResolvedConfig(cwd = process.cwd()) {
+  const configPath = path.join(cwd, CONFIG_PATH);
+
+  try {
+    const text = await readFileSafe(configPath);
+    const document = parseGuardrailsConfig(text);
+    return resolveConfigDocument(document);
+  } catch (err) {
+    if (err.code === "ENOENT" || /cannot read/i.test(err.message)) {
+      return null;
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string} preset
+ * @returns {string}
+ */
+export function configFromPreset(preset) {
+  if (preset === "default") {
+    return `# Project guardrails config (preset: default)
+# Copy/edit freely. See templates/presets/ for other stacks.
+
+schema: spec-driven
+
+context: |
+  Tech stack: (fill in)
+  Test command: npm test
+  Branch prefix: feat
+
+rules:
+  specify:
+    - Prefer EARS acceptance criteria
+    - Mark unknowns with [NEEDS CLARIFICATION: question]
+  tasks:
+    - Every REQ must appear in the Test Coverage Matrix
+  verify:
+    - Evidence must cite test file:line paths
+`;
+  }
+
+  return `# Project guardrails config (extends preset: ${preset})
+extends: ${preset}
+
+# Optional project context (appended to preset):
+# context: |
+#   Team name, repo quirks, etc.
+
+# Optional overrides (appended on top of preset rules):
+# overrides:
+#   rules:
+#     specify:
+#       - Your extra rule on top of the preset
+`;
+}
+
+/**
+ * @param {{ preset?: string, cwd?: string, force?: boolean }} [options]
+ */
+export async function initProjectConfig(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const preset = options.preset ?? "default";
+  const presets = await listPresets();
+
+  if (!presets.includes(preset)) {
+    throw new Error(
+      `Unknown preset "${preset}". Available: ${presets.join(", ")}`,
+    );
+  }
+
+  await ensureDir(path.join(cwd, ".specs"));
+  const configPath = path.join(cwd, CONFIG_PATH);
+  const content = configFromPreset(preset);
+
+  if (options.force) {
+    await writeFileSafe(configPath, content);
+    return { created: false, updated: true, path: CONFIG_PATH, preset };
+  }
+
+  const created = await writeFileIfMissing(configPath, content);
+  return {
+    created,
+    updated: false,
+    path: CONFIG_PATH,
+    preset,
+    skipped: !created,
+  };
+}
+
+/**
+ * Read branch prefix from resolved config (explicit field or context line).
+ *
+ * @param {ReturnType<typeof parseGuardrailsConfig> | null | undefined} config
+ * @returns {string | undefined}
+ */
+export function readBranchPrefix(config) {
+  if (config?.branch_prefix?.trim()) {
+    return config.branch_prefix.trim();
+  }
+
+  const match = config?.context?.match(/^Branch prefix:\s*(\S+)/im);
+  return match?.[1];
+}
+
+export { mergeGuardrailsConfigs };

package/lib/project-rules.js

@@ -0,0 +1,210 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { CURSOR_RULES_DIR, RULE_ASSETS } from "./constants.js";
+import { ensureDir } from "./fs-utils.js";
+
+/** Markers around the catalog skills table — refreshed on every install. */
+export const SKILLS_MAP_START = "<!-- guardrails-managed:skills-map:start -->";
+export const SKILLS_MAP_END = "<!-- guardrails-managed:skills-map:end -->";
+
+/** Markers around the gates table — refreshed on every install. */
+export const GATES_MAP_START = "<!-- guardrails-managed:gates-map:start -->";
+export const GATES_MAP_END = "<!-- guardrails-managed:gates-map:end -->";
+
+/** Prior managed markers — recognized only so `install` can refresh tables. */
+const LEGACY_SKILLS_MAP_PAIRS = [
+  ["<!-- seatbelt-managed:skills-map:start -->", "<!-- seatbelt-managed:skills-map:end -->"],
+  ["<!-- harness-managed:skills-map:start -->", "<!-- harness-managed:skills-map:end -->"],
+];
+const LEGACY_GATES_MAP_PAIRS = [
+  ["<!-- seatbelt-managed:gates-map:start -->", "<!-- seatbelt-managed:gates-map:end -->"],
+  ["<!-- harness-managed:gates-map:start -->", "<!-- harness-managed:gates-map:end -->"],
+];
+
+/**
+ * @param {string} content
+ * @param {string} startMarker
+ * @param {string} endMarker
+ * @returns {string | null}
+ */
+export function extractManagedBlock(content, startMarker, endMarker) {
+  const start = content.indexOf(startMarker);
+  const end = content.indexOf(endMarker);
+  if (start < 0 || end < 0 || end < start) {
+    return null;
+  }
+  return content.slice(start, end + endMarker.length);
+}
+
+/**
+ * @param {string} content
+ * @param {[string, string][]} markerPairs
+ * @returns {string | null}
+ */
+function extractFirstManagedBlock(content, markerPairs) {
+  for (const [startMarker, endMarker] of markerPairs) {
+    const block = extractManagedBlock(content, startMarker, endMarker);
+    if (block) {
+      return block;
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function extractSkillsMapBlock(content) {
+  return extractFirstManagedBlock(content, [
+    [SKILLS_MAP_START, SKILLS_MAP_END],
+    ...LEGACY_SKILLS_MAP_PAIRS,
+  ]);
+}
+
+/**
+ * @param {string} content
+ * @returns {string | null}
+ */
+export function extractGatesMapBlock(content) {
+  return extractFirstManagedBlock(content, [
+    [GATES_MAP_START, GATES_MAP_END],
+    ...LEGACY_GATES_MAP_PAIRS,
+  ]);
+}
+
+/**
+ * Replace a managed block when present in `existing`, otherwise append it.
+ *
+ * @param {string} existing
+ * @param {string} shippedBlock
+ * @param {string} startMarker
+ * @param {string} endMarker
+ * @param {[string, string][]} legacyMarkerPairs
+ * @param {string} [appendHeading]
+ * @returns {string}
+ */
+function mergeManagedBlock(
+  existing,
+  shippedBlock,
+  startMarker,
+  endMarker,
+  legacyMarkerPairs,
+  appendHeading = "",
+) {
+  for (const [legacyStart, legacyEnd] of legacyMarkerPairs) {
+    const legacyBlock = extractManagedBlock(existing, legacyStart, legacyEnd);
+    if (legacyBlock) {
+      return existing.replace(legacyBlock, shippedBlock);
+    }
+  }
+
+  const existingBlock = extractManagedBlock(existing, startMarker, endMarker);
+  if (existingBlock) {
+    return existing.replace(existingBlock, shippedBlock);
+  }
+
+  if (appendHeading) {
+    return `${existing.trimEnd()}\n\n${appendHeading}\n\n${shippedBlock}\n`;
+  }
+
+  return `${existing.trimEnd()}\n\n${shippedBlock}\n`;
+}
+
+/**
+ * Merge shipped baseline into an existing rule file without wiping user prose.
+ *
+ * @param {string} existing
+ * @param {string} shipped
+ * @returns {string}
+ */
+export function mergeBaselineRule(existing, shipped) {
+  const shippedSkills = extractSkillsMapBlock(shipped);
+  const shippedGates = extractGatesMapBlock(shipped);
+  if (!shippedSkills && !shippedGates) {
+    return shipped;
+  }
+
+  let merged = existing;
+
+  if (shippedSkills) {
+    const skillsSection = /^# (?:Harness|Seatbelt|Guardrails) Skills\b[\s\S]*?(?=^# |\Z)/m;
+    if (
+      !extractSkillsMapBlock(merged) &&
+      skillsSection.test(merged) &&
+      shipped.match(/^# (?:Harness|Seatbelt|Guardrails) Skills\b[\s\S]*?(?=^# |\Z)/m)
+    ) {
+      const shippedSection = shipped.match(/^# (?:Harness|Seatbelt|Guardrails) Skills\b[\s\S]*?(?=^# |\Z)/m);
+      if (shippedSection) {
+        merged = merged.replace(skillsSection, shippedSection[0]);
+      }
+    } else {
+      merged = mergeManagedBlock(
+        merged,
+        shippedSkills,
+        SKILLS_MAP_START,
+        SKILLS_MAP_END,
+        LEGACY_SKILLS_MAP_PAIRS,
+        extractSkillsMapBlock(merged) ? "" : "# Guardrails Skills",
+      );
+    }
+  }
+
+  if (shippedGates) {
+    merged = mergeManagedBlock(
+      merged,
+      shippedGates,
+      GATES_MAP_START,
+      GATES_MAP_END,
+      LEGACY_GATES_MAP_PAIRS,
+      extractGatesMapBlock(merged) ? "" : "# Deterministic Gates",
+    );
+  }
+
+  return merged;
+}
+
+/**
+ * Install Cursor project rules (.cursor/rules/*.mdc).
+ *
+ * @param {string} cwd
+ * @param {{ fetchAsset: (remotePath: string, destPath: string) => Promise<void> }} options
+ */
+export async function installProjectRules(cwd, options) {
+  const rulesDir = path.join(cwd, CURSOR_RULES_DIR);
+  await ensureDir(rulesDir);
+
+  for (const rule of RULE_ASSETS) {
+    const destPath = path.join(rulesDir, rule.file);
+    const tmpPath = path.join(rulesDir, `.${rule.file}.incoming`);
+
+    try {
+      await options.fetchAsset(rule.remotePath, tmpPath);
+      const shipped = await fs.readFile(tmpPath, "utf8");
+
+      let exists = false;
+      try {
+        await fs.access(destPath);
+        exists = true;
+      } catch (err) {
+        if (err.code !== "ENOENT") {
+          throw err;
+        }
+      }
+
+      if (!exists) {
+        await fs.rename(tmpPath, destPath);
+        continue;
+      }
+
+      const existing = await fs.readFile(destPath, "utf8");
+      const merged = mergeBaselineRule(existing, shipped);
+      await fs.writeFile(destPath, merged, "utf8");
+      await fs.rm(tmpPath, { force: true });
+    } catch (err) {
+      await fs.rm(tmpPath, { force: true }).catch(() => {});
+      throw err;
+    }
+  }
+}

package/lib/specs-utils.js

@@ -0,0 +1,117 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { readFileSafe } from "./fs-utils.js";
+
+const FEATURES_DIR = ".specs/features";
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string[]>}
+ */
+export async function listFeatureIds(cwd) {
+  const featuresRoot = path.join(cwd, FEATURES_DIR);
+
+  try {
+    const entries = await fs.readdir(featuresRoot, { withFileTypes: true });
+    return entries
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => entry.name)
+      .sort();
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {string | undefined} raw
+ * @param {string} cwd
+ * @returns {Promise<string>}
+ */
+export async function resolveFeatureId(raw, cwd) {
+  if (raw?.trim()) {
+    const trimmed = raw.trim();
+    const asPath = path.resolve(cwd, trimmed);
+
+    if (trimmed.endsWith(".md") || trimmed.includes("/")) {
+      const relative = path.relative(path.join(cwd, FEATURES_DIR), asPath);
+      if (!relative.startsWith("..") && !path.isAbsolute(relative)) {
+        return relative.split(path.sep)[0];
+      }
+    }
+
+    const named = path.join(cwd, FEATURES_DIR, trimmed);
+    try {
+      const stat = await fs.stat(named);
+      if (stat.isDirectory()) {
+        return trimmed;
+      }
+    } catch {
+      // fall through
+    }
+
+    throw new Error(`No such feature or path: ${trimmed}`);
+  }
+
+  const active = await readActiveFeatureFromState(cwd);
+  if (active && active !== "—") {
+    return active;
+  }
+
+  const features = await listFeatureIds(cwd);
+  if (features.length === 1) {
+    return features[0];
+  }
+
+  if (features.length === 0) {
+    throw new Error("No features found — create .specs/features/[feature]/ first.");
+  }
+
+  throw new Error(
+    `${features.length} features found — name the one to use:\n` +
+      features.map((id) => `  ${id}`).join("\n"),
+  );
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<string | null>}
+ */
+export async function readActiveFeatureFromState(cwd) {
+  const statePath = path.join(cwd, ".specs/STATE.md");
+
+  try {
+    const content = await readFileSafe(statePath);
+    const match = content.match(/^-\s*Feature:\s*(.+)$/m);
+    if (!match) {
+      return null;
+    }
+    const value = match[1].trim();
+    return value === "—" ? null : value;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} featureId
+ * @param {string} cwd
+ * @returns {string}
+ */
+export function featureDir(featureId, cwd) {
+  return path.join(cwd, FEATURES_DIR, featureId);
+}
+
+/**
+ * @param {string} featureId
+ * @param {string} cwd
+ * @param {string} filename
+ * @returns {Promise<string>}
+ */
+export async function readFeatureArtifact(featureId, cwd, filename) {
+  const filePath = path.join(featureDir(featureId, cwd), filename);
+  return readFileSafe(filePath);
+}

package/lib/token-cost.js

@@ -0,0 +1,124 @@
+import fs from "node:fs/promises";
+
+import { packagedAssetPath } from "./assets.js";
+import {
+  REFERENCE_ASSETS,
+  RULE_ASSETS,
+  SKILL_ASSETS,
+} from "./constants.js";
+
+/** Rough English/code heuristic (~4 characters per token). Not a billing API. */
+export const CHARS_PER_TOKEN = 4;
+
+/**
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text) {
+    return 0;
+  }
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+/**
+ * @param {string} remotePath
+ * @returns {Promise<string>}
+ */
+async function readPackagedText(remotePath) {
+  return fs.readFile(packagedAssetPath(remotePath), "utf8");
+}
+
+/**
+ * @param {string[]} remotePaths
+ * @returns {Promise<{ chars: number, tokens: number, files: number }>}
+ */
+export async function measureBundle(remotePaths) {
+  let chars = 0;
+  for (const remotePath of remotePaths) {
+    const text = await readPackagedText(remotePath);
+    chars += text.length;
+  }
+  return {
+    chars,
+    tokens: estimateTokens(" ".repeat(chars)),
+    files: remotePaths.length,
+  };
+}
+
+const ALL_SISTER_SKILLS = SKILL_ASSETS.map((asset) => asset.remotePath);
+const ALL_REFERENCES = REFERENCE_ASSETS.map((asset) => asset.remotePath);
+const BASELINE_RULE = RULE_ASSETS[0].remotePath;
+
+/** Documented load profiles — mirror agent-architecture progressive disclosure. */
+export const LOAD_PROFILES = {
+  naiveFullDump: {
+    label: "Naive full dump (everything every turn)",
+    paths: [...ALL_SISTER_SKILLS, ...ALL_REFERENCES, BASELINE_RULE],
+  },
+  specifyTurn: {
+    label: "Specify turn (hub + phase + standards)",
+    paths: [
+      "skills/agent-architecture.md",
+      "skills/references/specify.md",
+      "skills/references/context-limits.md",
+      "skills/engineering-standards.md",
+      BASELINE_RULE,
+    ],
+  },
+  tasksTurn: {
+    label: "Tasks turn (hub + tasks + task graph)",
+    paths: [
+      "skills/agent-architecture.md",
+      "skills/references/tasks.md",
+      "skills/task-graph-engineering.md",
+      "skills/references/context-limits.md",
+      BASELINE_RULE,
+    ],
+  },
+  executeLoop: {
+    label: "Execute /loop (one wave — inline or parallel)",
+    paths: [
+      "skills/references/implement.md",
+      "skills/engineering-standards.md",
+      BASELINE_RULE,
+    ],
+  },
+  verifyTurn: {
+    label: "Verify turn (independent reviewer)",
+    paths: [
+      "skills/references/validate.md",
+      "skills/security-review.md",
+      "skills/references/context-limits.md",
+      BASELINE_RULE,
+    ],
+  },
+};
+
+/**
+ * @returns {Promise<{
+ *   profiles: Record<string, { label: string, chars: number, tokens: number, files: number }>,
+ *   savings: { specifyVsNaivePct: number, executeVsNaivePct: number }
+ * }>}
+ */
+export async function measureLoadProfiles() {
+  /** @type {Record<string, { label: string, chars: number, tokens: number, files: number }>} */
+  const profiles = {};
+
+  for (const [key, profile] of Object.entries(LOAD_PROFILES)) {
+    const measured = await measureBundle(profile.paths);
+    profiles[key] = { label: profile.label, ...measured };
+  }
+
+  const naive = profiles.naiveFullDump.tokens;
+  const specify = profiles.specifyTurn.tokens;
+  const execute = profiles.executeLoop.tokens;
+
+  return {
+    profiles,
+    savings: {
+      specifyVsNaivePct: naive > 0 ? Math.round((1 - specify / naive) * 100) : 0,
+      executeVsNaivePct: naive > 0 ? Math.round((1 - execute / naive) * 100) : 0,
+    },
+  };
+}