@luizsantiago/spec-guardrails 3.0.1

package/lib/feature.js

@@ -0,0 +1,272 @@
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { STATE_HEADER } from "./constants.js";
+import { ensureDir, readFileSafe, writeFileSafe } from "./fs-utils.js";
+import { loadResolvedConfig, readBranchPrefix } from "./presets.js";
+
+const FEATURES_DIR = ".specs/features";
+const FEATURE_ID_PATTERN = /^(\d{3})-([a-z0-9][a-z0-9-]*)$/;
+const DEFAULT_BRANCH_PREFIX = "feat";
+
+/**
+ * @param {string} description
+ * @returns {string}
+ */
+export function slugifyDescription(description) {
+  const slug = description
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+
+  if (!slug) {
+    throw new Error("Description must contain at least one letter or digit.");
+  }
+
+  return slug;
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<number>}
+ */
+export async function nextFeatureNumber(cwd) {
+  const featuresRoot = path.join(cwd, FEATURES_DIR);
+
+  try {
+    const entries = await fs.readdir(featuresRoot, { withFileTypes: true });
+    let max = 0;
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const match = FEATURE_ID_PATTERN.exec(entry.name);
+      if (match) {
+        max = Math.max(max, Number.parseInt(match[1], 10));
+      }
+    }
+
+    return max + 1;
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return 1;
+    }
+    throw err;
+  }
+}
+
+/**
+ * @param {number} number
+ * @param {string} slug
+ * @returns {string}
+ */
+export function formatFeatureId(number, slug) {
+  return `${String(number).padStart(3, "0")}-${slug}`;
+}
+
+/**
+ * @param {string} featureId
+ * @param {string} [prefix]
+ * @returns {string}
+ */
+export function featureBranchName(featureId, prefix = DEFAULT_BRANCH_PREFIX) {
+  return `${prefix}/${featureId}`;
+}
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {string} cwd
+ * @returns {Promise<{ code: number, stdout: string, stderr: string }>}
+ */
+function runCapture(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+
+    child.stdout?.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
+/**
+ * @param {string} cwd
+ * @returns {Promise<boolean>}
+ */
+async function isGitRepo(cwd) {
+  const result = await runCapture("git", ["rev-parse", "--is-inside-work-tree"], cwd);
+  return result.code === 0 && result.stdout.trim() === "true";
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} branchName
+ * @returns {Promise<{ created: boolean, message: string }>}
+ */
+async function ensureFeatureBranch(cwd, branchName) {
+  if (!(await isGitRepo(cwd))) {
+    return {
+      created: false,
+      message: "Not a git repository — feature folder and STATE updated; branch skipped.",
+    };
+  }
+
+  const current = await runCapture("git", ["branch", "--show-current"], cwd);
+  if (current.code !== 0) {
+    return {
+      created: false,
+      message: "Could not read current git branch — branch creation skipped.",
+    };
+  }
+
+  const active = current.stdout.trim();
+  if (active === branchName) {
+    return { created: false, message: `Already on ${branchName}.` };
+  }
+
+  const exists = await runCapture("git", ["show-ref", "--verify", `refs/heads/${branchName}`], cwd);
+  if (exists.code === 0) {
+    const checkout = await runCapture("git", ["checkout", branchName], cwd);
+    if (checkout.code !== 0) {
+      throw new Error(
+        `Branch ${branchName} exists but checkout failed: ${checkout.stderr.trim() || checkout.stdout.trim()}`,
+      );
+    }
+    return { created: false, message: `Checked out existing branch ${branchName}.` };
+  }
+
+  const create = await runCapture("git", ["checkout", "-b", branchName], cwd);
+  if (create.code !== 0) {
+    throw new Error(
+      `Failed to create branch ${branchName}: ${create.stderr.trim() || create.stdout.trim()}`,
+    );
+  }
+
+  return { created: true, message: `Created and checked out ${branchName} (Tier 0).` };
+}
+
+/**
+ * @param {string} cwd
+ * @param {{ featureId: string, branchName: string, phase?: string }} info
+ */
+async function updateStateForFeature(cwd, info) {
+  const statePath = path.join(cwd, ".specs/STATE.md");
+  const phase = info.phase ?? "Specify";
+  const nextStep = `- [ ] Draft spec.md in .specs/features/${info.featureId}/`;
+
+  let content;
+  try {
+    content = await readFileSafe(statePath);
+  } catch {
+    content = STATE_HEADER;
+  }
+
+  const setField = (label, value) => {
+    const pattern = new RegExp(`(^-\\s*${label}:\\s*).*$`, "m");
+    if (pattern.test(content)) {
+      content = content.replace(pattern, `$1${value}`);
+    }
+  };
+
+  setField("Feature", info.featureId);
+  setField("Phase", phase);
+  setField("Branch", info.branchName);
+
+  const nextStepPattern = /^## Next Step \(single item\)\n- \[ \].*$/m;
+  if (nextStepPattern.test(content)) {
+    content = content.replace(nextStepPattern, `## Next Step (single item)\n${nextStep}`);
+  }
+
+  await writeFileSafe(statePath, content);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {string} description
+ */
+async function writeSpecStub(cwd, featureId, description) {
+  const specPath = path.join(cwd, FEATURES_DIR, featureId, "spec.md");
+  const stub = `# Spec: ${featureId}
+
+## Goal
+${description.trim()}
+
+## Requirements
+
+### REQ-001: [Short title]
+- **Acceptance Criteria**: WHEN [trigger] THEN the system SHALL [outcome]
+
+## Assumptions
+- none
+
+## Out of Scope
+- [Explicitly excluded work]
+`;
+
+  await writeFileSafe(specPath, stub);
+}
+
+/**
+ * Initialize a numbered feature workspace (Tier 0).
+ *
+ * @param {string} description
+ * @param {{ cwd?: string, branchPrefix?: string, skipBranch?: boolean, skipSpec?: boolean }} [options]
+ */
+export async function featureInit(description, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const trimmed = description?.trim();
+
+  if (!trimmed) {
+    throw new Error("Description is required. Example: feature-init \"chat with presence\"");
+  }
+
+  const slug = slugifyDescription(trimmed);
+  const number = await nextFeatureNumber(cwd);
+  const featureId = formatFeatureId(number, slug);
+
+  const resolvedConfig = await loadResolvedConfig(cwd);
+  const branchPrefix =
+    options.branchPrefix ?? readBranchPrefix(resolvedConfig) ?? DEFAULT_BRANCH_PREFIX;
+  const branchName = featureBranchName(featureId, branchPrefix);
+  const featureDir = path.join(cwd, FEATURES_DIR, featureId);
+
+  await ensureDir(featureDir);
+
+  if (!options.skipSpec) {
+    const specPath = path.join(featureDir, "spec.md");
+    try {
+      await fs.access(specPath);
+    } catch {
+      await writeSpecStub(cwd, featureId, trimmed);
+    }
+  }
+
+  await updateStateForFeature(cwd, { featureId, branchName });
+
+  let branchResult = { created: false, message: "Branch creation skipped (--no-branch)." };
+  if (!options.skipBranch) {
+    branchResult = await ensureFeatureBranch(cwd, branchName);
+  }
+
+  return {
+    featureId,
+    featureDir: path.join(FEATURES_DIR, featureId),
+    branchName,
+    branchCreated: branchResult.created,
+    branchMessage: branchResult.message,
+  };
+}

package/lib/fs-utils.js

@@ -0,0 +1,114 @@
+import fs from "node:fs/promises";
+
+function isPermissionError(err) {
+  return err && (err.code === "EACCES" || err.code === "EPERM");
+}
+
+/**
+ * Refuse to overwrite through a symlink (install must not clobber .env etc.).
+ * Used for packaged copies, remote downloads, memory files, and `.cursorrules`.
+ *
+ * @param {string} destPath
+ */
+export async function assertSafeWriteTarget(destPath) {
+  let st;
+  try {
+    st = await fs.lstat(destPath);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return;
+    }
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot access ${destPath}`);
+    }
+    throw err;
+  }
+
+  if (st.isSymbolicLink()) {
+    throw new Error(
+      `Refusing to write through symlink: ${destPath} — ` +
+        "remove the link or choose another destination before installing.",
+    );
+  }
+}
+
+export async function ensureDir(dirPath) {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+  } catch (err) {
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot create ${dirPath}`);
+    }
+    throw err;
+  }
+}
+
+export async function writeFileIfMissing(filePath, content) {
+  await assertSafeWriteTarget(filePath);
+
+  try {
+    await fs.writeFile(filePath, content, { encoding: "utf8", flag: "wx" });
+    return true;
+  } catch (err) {
+    if (err.code === "EEXIST") {
+      return false;
+    }
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot write ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+export async function appendFileSafe(filePath, content) {
+  await assertSafeWriteTarget(filePath);
+
+  try {
+    await fs.appendFile(filePath, content, "utf8");
+  } catch (err) {
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot write ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+export async function writeFileSafe(filePath, content) {
+  await assertSafeWriteTarget(filePath);
+
+  try {
+    await fs.writeFile(filePath, content, "utf8");
+  } catch (err) {
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot write ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+export async function readFileSafe(filePath) {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch (err) {
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot read ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+export async function removeFileSafe(filePath) {
+  try {
+    await fs.unlink(filePath);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return;
+    }
+    if (isPermissionError(err)) {
+      throw new Error(`Permission denied: cannot remove ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+export { isPermissionError };

package/lib/gates.js

@@ -0,0 +1,138 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+import { NPX, GUARDRAILS_SCRIPTS_DIR } from "./constants.js";
+
+const PYTHON_CANDIDATES = ["python3", "python"];
+
+const GATE_SCRIPTS = {
+  "validate-spec": "validate_spec.py",
+  "validate-tasks": "validate_tasks.py",
+  "validate-state": "validate_state.py",
+  "analyze-artifacts": "analyze_artifacts.py",
+  "check-commit": "check_commit.py",
+  lessons: "lessons.py",
+};
+
+const AUX_SCRIPTS = {
+  "loop-plan": "loop_plan.py",
+};
+
+const GUARDRAILS_SCRIPTS = { ...GATE_SCRIPTS, ...AUX_SCRIPTS };
+
+export const GATE_COMMANDS = Object.keys(GATE_SCRIPTS);
+
+export const AUX_COMMANDS = Object.keys(AUX_SCRIPTS);
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @returns {Promise<number>}
+ */
+function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: options.stdio ?? "inherit",
+      ...(options.cwd ? { cwd: options.cwd } : {}),
+    });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+/**
+ * Resolve gate scripts directory (`.specs/guardrails/scripts` only — no legacy dual-path).
+ *
+ * @param {string} _cwd
+ * @returns {Promise<string>}
+ */
+export async function resolveScriptsDir(_cwd) {
+  return GUARDRAILS_SCRIPTS_DIR;
+}
+
+/**
+ * Resolve the available Python interpreter, or null when none is installed.
+ * @returns {Promise<string | null>}
+ */
+export async function resolvePython() {
+  for (const candidate of PYTHON_CANDIDATES) {
+    try {
+      const code = await run(candidate, ["--version"], { stdio: "ignore" });
+      if (code === 0) {
+        return candidate;
+      }
+    } catch {
+      // Interpreter not on PATH; try the next candidate.
+    }
+  }
+
+  return null;
+}
+
+/** @returns {Promise<boolean>} */
+export async function hasPython() {
+  return (await resolvePython()) !== null;
+}
+
+/**
+ * Run a guardrails Python script installed under `.specs/guardrails/scripts/`.
+ *
+ * @param {string} command gate or aux command name
+ * @param {string[]} args forwarded to the Python script
+ * @param {{ cwd?: string, stdio?: import("node:child_process").StdioOptions }} [options]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runGuardrailsScript(command, args, options = {}) {
+  const scriptName = GUARDRAILS_SCRIPTS[command];
+
+  if (!scriptName) {
+    throw new Error(`Unknown guardrails command: ${command}`);
+  }
+
+  const cwd = options.cwd ?? process.cwd();
+  const scriptsDir = await resolveScriptsDir(cwd);
+  const scriptPath = path.join(cwd, scriptsDir, scriptName);
+
+  for (const required of [scriptName, "_common.py"]) {
+    try {
+      await access(path.join(cwd, scriptsDir, required), constants.R_OK);
+    } catch {
+      throw new Error(
+        `Guardrails script not found at ${path.join(scriptsDir, required)}. ` +
+          `Run \`${NPX("install")}\` in this project first.`,
+      );
+    }
+  }
+
+  const python = await resolvePython();
+
+  if (!python) {
+    throw new Error(
+      "Python 3 not found. Install Python 3.10+ to run guardrails scripts, " +
+        "or perform the equivalent checks manually (degraded mode).",
+    );
+  }
+
+  return run(python, [scriptPath, ...args], {
+    cwd,
+    stdio: options.stdio,
+  });
+}
+
+/**
+ * Run a structural gate script installed under `.specs/guardrails/scripts/`.
+ *
+ * @param {string} gate one of GATE_COMMANDS
+ * @param {string[]} args forwarded to the Python script
+ * @param {{ cwd?: string, stdio?: import("node:child_process").StdioOptions }} [options]
+ * @returns {Promise<number>} process exit code
+ */
+export async function runGate(gate, args, options = {}) {
+  if (!GATE_SCRIPTS[gate]) {
+    throw new Error(`Unknown gate: ${gate}`);
+  }
+
+  return runGuardrailsScript(gate, args, options);
+}

package/lib/install.js

@@ -0,0 +1,140 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { installAsset, resolveInstallSource, packagedAssetPath } from "./assets.js";
+import {
+  GUARDRAILS_SCRIPTS_DIR,
+  REFERENCE_ASSETS,
+  REFERENCES_SUBDIR,
+  SCRIPT_ASSETS,
+  SKILL_ASSETS,
+  SKILL_DIRS,
+  DISPLAY_NAME,
+  resolveAssetOverride,
+} from "./constants.js";
+import { injectCursorRules } from "./cursorrules.js";
+import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
+import { hasPython } from "./gates.js";
+import { initGuardrailsMemory } from "./memory.js";
+import { printInstallNextSteps } from "./next-steps.js";
+import { initProjectConfig } from "./presets.js";
+import { installProjectRules } from "./project-rules.js";
+
+/**
+ * @param {{ cwd?: string, repoUrl?: string, silent?: boolean }} [options]
+ */
+export async function install(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const log = options.silent ? () => {} : console.log;
+  const override = options.repoUrl ?? resolveAssetOverride();
+  const source = resolveInstallSource(options.repoUrl);
+  const state = { warned: false };
+
+  if (!options.repoUrl && override) {
+    log(
+      `⚠️  SPEC_GUARDRAILS_REPO_URL is set — installing skills and executable gate ` +
+        `scripts from ${override} instead of the packaged assets.`,
+    );
+  }
+
+  const fetchAsset = (remotePath, destPath) =>
+    installAsset({ remotePath, destPath, source, state, log });
+
+  log(`🚀 Installing ${DISPLAY_NAME}...`);
+
+  if (source.mode === "package") {
+    log("📦 Copying skills, references and gates from the npm package...");
+  }
+
+  for (const skill of SKILL_ASSETS) {
+    for (const dir of SKILL_DIRS) {
+      const targetDir = path.join(cwd, dir);
+      await ensureDir(targetDir);
+      await fetchAsset(skill.remotePath, path.join(targetDir, skill.file));
+    }
+  }
+  log(`✅ ${SKILL_ASSETS.length} sister skills → ${SKILL_DIRS.join(", ")}`);
+
+  log("📚 Installing phase references...");
+  for (const reference of REFERENCE_ASSETS) {
+    for (const dir of SKILL_DIRS) {
+      const targetDir = path.join(cwd, dir, REFERENCES_SUBDIR);
+      await ensureDir(targetDir);
+      await fetchAsset(
+        reference.remotePath,
+        path.join(targetDir, reference.file),
+      );
+    }
+  }
+  log(`✅ ${REFERENCE_ASSETS.length} references → ${REFERENCES_SUBDIR}/`);
+
+  log("🔒 Installing deterministic gates (Python)...");
+  const scriptsDir = path.join(cwd, GUARDRAILS_SCRIPTS_DIR);
+  await ensureDir(scriptsDir);
+
+  for (const script of SCRIPT_ASSETS) {
+    const destPath = path.join(scriptsDir, script.file);
+    await fetchAsset(script.remotePath, destPath);
+
+    try {
+      await fs.chmod(destPath, 0o755);
+    } catch (err) {
+      log(
+        `⚠️  Could not mark ${script.file} as executable (${err.code ?? err.message}). ` +
+          "Run it with `python3 <script>` instead.",
+      );
+    }
+  }
+  log(`✅ ${SCRIPT_ASSETS.length} scripts → ${GUARDRAILS_SCRIPTS_DIR}`);
+
+  log("📋 Installing project rules (.cursor/rules/)...");
+  await installProjectRules(cwd, { fetchAsset });
+
+  log("🧠 Setting up persistent memory in .specs/...");
+  const { stateCreated, lessonsCreated } = await initGuardrailsMemory(cwd);
+
+  if (options.preset) {
+    const configResult = await initProjectConfig({
+      cwd,
+      preset: options.preset,
+      force: options.forceConfig,
+    });
+    if (configResult.created) {
+      log(`✅ config.yaml initialized from preset: ${options.preset}`);
+    } else if (configResult.skipped) {
+      log("ℹ️  config.yaml already exists — kept your file (use --force-config to replace)");
+    }
+  }
+
+  if (stateCreated) {
+    log("✅ STATE.md initialized [feed forward]");
+  }
+
+  if (lessonsCreated) {
+    log("✅ LESSONS.md initialized [feedback loop]");
+  }
+
+  await injectCursorRules(cwd);
+
+  const gettingStartedCreated = await writeFileIfMissing(
+    path.join(cwd, ".specs/GETTING_STARTED.md"),
+    await readFileSafe(packagedAssetPath("templates/GETTING_STARTED.md")),
+  );
+  if (gettingStartedCreated) {
+    log("✅ GETTING_STARTED.md → .specs/");
+  }
+
+  const pythonAvailable = await hasPython();
+  if (!pythonAvailable) {
+    log(
+      "⚠️  Python 3 not found. Skills still work in degraded mode " +
+        "(manual checks). Install Python 3.10+ to enable the gates.",
+    );
+  }
+
+  if (!options.silent) {
+    printInstallNextSteps({ pythonAvailable, preset: options.preset });
+  }
+
+  return { pythonAvailable };
+}

package/lib/memory.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+
+import { packagedAssetPath } from "./assets.js";
+import {
+  LESSONS_HEADER,
+  STATE_HEADER,
+} from "./constants.js";
+import { ensureDir, readFileSafe, writeFileIfMissing } from "./fs-utils.js";
+
+export async function initGuardrailsMemory(cwd) {
+  const specsDir = path.join(cwd, ".specs");
+  const featuresDir = path.join(specsDir, "features");
+  const projectDir = path.join(specsDir, "project");
+  const domainsDir = path.join(specsDir, "domains");
+
+  await ensureDir(featuresDir);
+  await ensureDir(projectDir);
+  await ensureDir(domainsDir);
+
+  const stateCreated = await writeFileIfMissing(
+    path.join(specsDir, "STATE.md"),
+    STATE_HEADER,
+  );
+  const lessonsCreated = await writeFileIfMissing(
+    path.join(specsDir, "LESSONS.md"),
+    LESSONS_HEADER,
+  );
+  await writeFileIfMissing(
+    path.join(specsDir, "config.yaml.example"),
+    await readFileSafe(packagedAssetPath("templates/config.yaml.example")),
+  );
+
+  return { stateCreated, lessonsCreated };
+}