@luizsantiago/spec-guardrails 3.0.1

package/lib/archive.js

@@ -0,0 +1,208 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import { STATE_HEADER } from "./constants.js";
+import {
+  domainSpecStub,
+  mergeFeatureIntoDomain,
+} from "./delta-merge.js";
+import { ensureDir, readFileSafe, writeFileSafe } from "./fs-utils.js";
+import { runGate } from "./gates.js";
+import {
+  featureDir,
+  readFeatureArtifact,
+  resolveFeatureId,
+} from "./specs-utils.js";
+
+const ROADMAP_HEADER = `# Roadmap
+
+Track milestones and archived features.
+
+## Completed
+
+`;
+
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+function validationPassed(text) {
+  const visible = text.replace(/<!--[\s\S]*?-->/g, "");
+  return /\b(?:PASS|PASSED)\b/.test(visible);
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} featureId
+ * @param {string} domainRelPath
+ * @param {string[]} mergeSummary
+ */
+async function updateRoadmap(cwd, featureId, domainRelPath, mergeSummary) {
+  const roadmapPath = path.join(cwd, ".specs/project/ROADMAP.md");
+  await ensureDir(path.dirname(roadmapPath));
+
+  let content;
+  try {
+    content = await readFileSafe(roadmapPath);
+  } catch {
+    content = ROADMAP_HEADER;
+  }
+
+  if (!content.includes("## Completed")) {
+    content = `${content.trimEnd()}\n\n## Completed\n\n`;
+  }
+
+  const date = new Date().toISOString().slice(0, 10);
+  const validationLink = `.specs/features/${featureId}/validation.md`;
+  let entry = `- **${date}** \`${featureId}\` — archived. Validation: \`${validationLink}\``;
+
+  if (domainRelPath) {
+    entry += `\n  - Merged → \`${domainRelPath}\``;
+    if (mergeSummary.length) {
+      entry += ` (${mergeSummary.join(", ")})`;
+    }
+  }
+
+  entry += "\n";
+
+  if (content.includes(entry.trim())) {
+    return { updated: false, path: roadmapPath };
+  }
+
+  const completedHeading = "## Completed";
+  const idx = content.indexOf(completedHeading);
+  const insertAt = idx + completedHeading.length;
+  const before = content.slice(0, insertAt);
+  const after = content.slice(insertAt).replace(/^\n*/, "\n\n");
+  content = `${before}\n${entry}${after}`;
+
+  await writeFileSafe(roadmapPath, content);
+  return { updated: true, path: roadmapPath };
+}
+
+/**
+ * @param {string} cwd
+ */
+async function resetState(cwd) {
+  const statePath = path.join(cwd, ".specs/STATE.md");
+  let content;
+
+  try {
+    content = await readFileSafe(statePath);
+  } catch {
+    content = STATE_HEADER;
+  }
+
+  content = content.replace(/^-\s*Feature:\s*.*$/m, "- Feature: —");
+  content = content.replace(/^-\s*Phase:\s*.*$/m, "- Phase: —");
+  content = content.replace(/^-\s*Branch:\s*.*$/m, "- Branch: —");
+  content = content.replace(
+    /^## Next Step \(single item\)\n- \[ \].*$/m,
+    "## Next Step (single item)\n- [ ] —",
+  );
+
+  await writeFileSafe(statePath, content);
+}
+
+/**
+ * Infer domain slug from feature id (003-chat-system → chat-system).
+ *
+ * @param {string} featureId
+ * @returns {string}
+ */
+export function inferDomainFromFeature(featureId) {
+  const match = /^(\d{3})-(.+)$/.exec(featureId);
+  return match ? match[2] : featureId;
+}
+
+/**
+ * Archive a verified feature: ROADMAP update, optional domain merge, STATE reset.
+ *
+ * @param {string | undefined} featureArg
+ * @param {{
+ *   cwd?: string,
+ *   domain?: string,
+ *   skipVerify?: boolean,
+ *   skipRoadmap?: boolean,
+ *   skipState?: boolean,
+ *   skipDomainMerge?: boolean,
+ * }} [options]
+ */
+export async function archiveFeature(featureArg, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const featureId = await resolveFeatureId(featureArg, cwd);
+  const featurePath = featureDir(featureId, cwd);
+
+  try {
+    await fs.access(featurePath);
+  } catch {
+    throw new Error(`Feature directory not found: ${featurePath}`);
+  }
+
+  if (!options.skipVerify) {
+    const validationText = await readFeatureArtifact(featureId, cwd, "validation.md").catch(
+      () => {
+        throw new Error(
+          `Missing validation.md for ${featureId}. Run validate-state before archive.`,
+        );
+      },
+    );
+
+    if (!validationPassed(validationText)) {
+      throw new Error(
+        `validation.md for ${featureId} does not contain PASS/PASSED. Run validate-state first.`,
+      );
+    }
+
+    const gateCode = await runGate("validate-state", [featureId], {
+      cwd,
+      stdio: "pipe",
+    });
+    if (gateCode !== 0) {
+      throw new Error(`validate-state failed for ${featureId}. Fix gaps before archive.`);
+    }
+  }
+
+  const specText = await readFeatureArtifact(featureId, cwd, "spec.md");
+  let domainRelPath = "";
+  let mergeSummary = [];
+
+  if (!options.skipDomainMerge) {
+    const domain = options.domain ?? inferDomainFromFeature(featureId);
+    const domainDir = path.join(cwd, ".specs/domains", domain);
+    const domainSpecPath = path.join(domainDir, "spec.md");
+    domainRelPath = `.specs/domains/${domain}/spec.md`;
+
+    await ensureDir(domainDir);
+
+    let domainSpec;
+    try {
+      domainSpec = await readFileSafe(domainSpecPath);
+    } catch {
+      domainSpec = domainSpecStub(domain, featureId);
+    }
+
+    const merged = mergeFeatureIntoDomain(domainSpec, specText);
+    mergeSummary = merged.summary;
+    await writeFileSafe(domainSpecPath, merged.spec);
+  }
+
+  let roadmap = { updated: false, path: "" };
+  if (!options.skipRoadmap) {
+    roadmap = await updateRoadmap(cwd, featureId, domainRelPath, mergeSummary);
+  }
+
+  if (!options.skipState) {
+    await resetState(cwd);
+  }
+
+  return {
+    featureId,
+    featureDir: path.join(".specs/features", featureId),
+    domainPath: domainRelPath || null,
+    mergeSummary,
+    roadmapUpdated: roadmap.updated,
+    roadmapPath: roadmap.path ? path.relative(cwd, roadmap.path) : null,
+    stateReset: !options.skipState,
+  };
+}

package/lib/assets.js

@@ -0,0 +1,145 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  FALLBACK_REPO_URL,
+  PACKAGE_NAME,
+  PINNED_REF,
+  assertSafeAssetBase,
+  resolveAssetOverride,
+  resolveAssetUrl,
+} from "./constants.js";
+import { downloadToFile } from "./download.js";
+import { assertSafeWriteTarget } from "./fs-utils.js";
+
+const PACKAGE_ROOT = path.resolve(
+  path.join(path.dirname(fileURLToPath(import.meta.url)), ".."),
+);
+
+/**
+ * Absolute path of a guardrails asset shipped inside the npm package.
+ *
+ * @param {string} remotePath path relative to the repo root (e.g. skills/agent-architecture.md)
+ */
+export function packagedAssetPath(remotePath) {
+  const resolved = path.resolve(PACKAGE_ROOT, remotePath);
+  const rootWithSep = PACKAGE_ROOT.endsWith(path.sep)
+    ? PACKAGE_ROOT
+    : PACKAGE_ROOT + path.sep;
+
+  if (resolved !== PACKAGE_ROOT && !resolved.startsWith(rootWithSep)) {
+    throw new Error(
+      `Refusing packaged asset path outside package root: ${remotePath}`,
+    );
+  }
+
+  return resolved;
+}
+
+/**
+ * Default install copies from the package. A remote fetch happens only when
+ * `SPEC_GUARDRAILS_REPO_URL` or `options.repoUrl` is set (forks and the test suite).
+ *
+ * @param {string} [repoUrl]
+ * @returns {{ mode: "package" } | { mode: "remote", repoUrl: string }}
+ */
+export function resolveInstallSource(repoUrl) {
+  const override = repoUrl ?? resolveAssetOverride();
+  if (override) {
+    return { mode: "remote", repoUrl: assertSafeAssetBase(override) };
+  }
+  return { mode: "package" };
+}
+
+/**
+ * @param {string} remotePath
+ * @param {string} destPath
+ */
+export async function copyPackagedAsset(remotePath, destPath) {
+  const source = packagedAssetPath(remotePath);
+
+  try {
+    await fs.access(source);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(
+        `Packaged guardrails asset missing: ${remotePath}. ` +
+          `Reinstall ${PACKAGE_NAME}.`,
+      );
+    }
+    throw err;
+  }
+
+  await assertSafeWriteTarget(destPath);
+
+  try {
+    await fs.copyFile(source, destPath);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      throw new Error(`cannot write ${destPath} - destination directory missing`);
+    }
+    if (err.code === "EACCES" || err.code === "EPERM") {
+      throw new Error(`Permission denied: cannot write ${destPath}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Download one asset. Pin-tag fallback applies only when fetching the official
+ * repo with no override (kept for the remote path; the default install no
+ * longer uses it).
+ *
+ * @param {{ remotePath: string, destPath: string, repoUrl?: string, state: { warned: boolean }, log: (msg: string) => void }} params
+ */
+export async function downloadRemoteAsset({
+  remotePath,
+  destPath,
+  repoUrl,
+  state,
+  log,
+}) {
+  try {
+    await downloadToFile(resolveAssetUrl(remotePath, repoUrl), destPath);
+    return;
+  } catch (err) {
+    const missingPinnedAsset =
+      !repoUrl && /Download failed: 404/.test(err.message);
+
+    if (!missingPinnedAsset) {
+      throw err;
+    }
+
+    if (!state.warned) {
+      state.warned = true;
+      log(
+        `⚠️  Tag ${PINNED_REF} has no published assets yet — ` +
+          "falling back to the default branch.",
+      );
+    }
+  }
+
+  await downloadToFile(
+    resolveAssetUrl(remotePath, FALLBACK_REPO_URL),
+    destPath,
+  );
+}
+
+/**
+ * @param {{ remotePath: string, destPath: string, source: ReturnType<typeof resolveInstallSource>, state: { warned: boolean }, log: (msg: string) => void }} params
+ */
+export async function installAsset({ remotePath, destPath, source, state, log }) {
+  if (source.mode === "package") {
+    await copyPackagedAsset(remotePath, destPath);
+    return;
+  }
+
+  await downloadRemoteAsset({
+    remotePath,
+    destPath,
+    repoUrl: source.repoUrl,
+    state,
+    log,
+  });
+}