@theagilemonkeys/facility 0.11.4 → 0.12.0

package/modules/database/guards/migrations-immutable.mjs

@@ -1,57 +0,0 @@
-// facility module: database
-//
-// Applied migrations are immutable. This guard fails when a commit range
-// modifies or deletes an existing migration file instead of adding a new one.
-// In CI it diffs against the PR base; locally it diffs against the merge-base
-// with the default branch.
-import { execFileSync } from "node:child_process";
-
-// Directories that hold ordered migration files. Adjust to your stack.
-const MIGRATION_DIRS = [
-  "migrations/",
-  "supabase/migrations/",
-  "db/migrations/",
-  "prisma/migrations/",
-];
-
-// key: "<path>", value: written reason (e.g. "squashed baseline, 2026-01").
-const ALLOWLIST = {};
-
-function git(args) {
-  try {
-    return execFileSync("git", args, {
-      encoding: "utf8",
-      stdio: ["ignore", "pipe", "ignore"],
-    }).trim();
-  } catch {
-    return "";
-  }
-}
-
-export default {
-  name: "migrations-immutable",
-  description: "existing migration files are never edited or deleted, only added",
-  run() {
-    const base =
-      process.env.GITHUB_BASE_SHA ||
-      git(["merge-base", "HEAD", `origin/${process.env.DEFAULT_BRANCH || "main"}`]) ||
-      git(["merge-base", "HEAD", "main"]);
-    if (!base) return []; // shallow clone or fresh repo — nothing to compare against
-
-    const out = git(["diff", "--name-status", base, "HEAD"]);
-    const violations = [];
-    for (const row of out.split("\n").filter(Boolean)) {
-      const [status, ...paths] = row.split("\t");
-      const path = paths[paths.length - 1];
-      if (!MIGRATION_DIRS.some((dir) => path.startsWith(dir))) continue;
-      if (status.startsWith("M") || status.startsWith("D") || status.startsWith("R")) {
-        if (ALLOWLIST[path]) continue;
-        violations.push({
-          file: path,
-          message: `migration ${status.startsWith("D") ? "deleted" : "modified"} — migrations are append-only; write a new one`,
-        });
-      }
-    }
-    return violations;
-  },
-};

package/modules/database/hooks/protect-migrations.fragment.mjs

@@ -1,10 +0,0 @@
-// facility module: database — migration immutability (PreToolUse)
-if (/(^|\/)(supabase\/|db\/|prisma\/)?migrations\/[^/]+\.(sql|js|ts|rb|py)$/.test(filePath)) {
-  const tool = payload?.tool_name ?? "";
-  const isEdit = tool === "Edit" || tool === "MultiEdit";
-  if (isEdit) {
-    block(
-      "Migration files are immutable once written. Create a NEW timestamped migration instead.",
-    );
-  }
-}

package/modules/database/module.json

@@ -1,25 +0,0 @@
-{
-  "name": "database",
-  "title": "Database",
-  "description": "Migrations are immutable and append-only; access control by default; privileged credentials stay out of user-facing paths.",
-  "standardSection": "standard-section.md",
-  "files": [
-    {
-      "from": "agents/data-security-reviewer.md",
-      "to": ".claude/agents/data-security-reviewer.md"
-    },
-    {
-      "from": "guards/migrations-immutable.mjs",
-      "to": "guards/migrations-immutable.mjs"
-    },
-    {
-      "from": "guards/migration-versions.mjs",
-      "to": "guards/migration-versions.mjs"
-    },
-    {
-      "from": "commands/new-migration.md",
-      "to": ".claude/commands/new-migration.md"
-    }
-  ],
-  "hookRules": "hooks/protect-migrations.fragment.mjs"
-}

package/modules/database/standard-section.md

@@ -1,20 +0,0 @@
-### Database (facility module)
-
-Migrations are the durable state of the database. They are **append-only**:
-a change is a NEW migration, never an edit to one that may have been applied
-anywhere. The `migrations-immutable` guard and the `.claude/hooks` rules
-enforce this mechanically.
-
-- New tables and collections start closed: enable row/document-level access
-  control where the platform supports it, deny by default, grant only the
-  minimum required operations.
-- Authorization checks route through one shared helper layer — never inline
-  token/claim parsing inside individual policies or queries.
-- Privileged credentials (service role, admin connections) stay out of
-  user-facing and agent-facing read paths. Any privileged action lives in a
-  reviewed application service with explicit permission checks and tests.
-- Update seed data whenever a feature needs realistic data to test locally.
-  Seeds follow the domain: realistic names, states, relationships, and edge
-  cases — not toy rows that only satisfy a test selector.
-- Empty results must be permission-safe: do not imply hidden data exists when
-  access control returns nothing.

package/modules/design-system/agents/design-reviewer.md

@@ -1,37 +0,0 @@
----
-name: design-reviewer
-description: Reviews UI changes against the repo's design system and checks that critical UI flows carry browser evidence. Use when a change adds or modifies UI, layout, components, or styling.
-tools: Read, Grep, Glob, Bash
----
-
-You review product UI against this repository's design system and confirm
-critical flows are verified in a browser. A UI that conflicts with the design
-system is a product-quality issue.
-
-## Authoritative references
-- The design system source of truth declared in `STANDARD.md` (Design system
-  section) — read it before judging.
-- The repo's design tokens / shared component layer — existing values come
-  first.
-
-## What to check
-1. Existing design tokens and helpers are reused before any new value; no
-   ad-hoc colors, spacing, or radii that bypass the token layer.
-2. Components match the system's catalog: shapes, sizes, states, and
-   hierarchy expressed the way the system prescribes.
-3. **Evidence**: UI flow changes include a browser verification note
-   (Playwright run, screenshots), or an explicit reason UI verification did
-   not apply.
-4. Responsive behavior holds at the product's breakpoints when layout, text
-   fit, navigation, modals, or tables can be affected.
-5. Empty, error, and loading states are designed, not accidental.
-
-## How to verify
-- `grep` the diff for raw color/spacing literals that should be tokens.
-- Recommend the smallest browser run that covers the affected flows.
-
-## Output contract
-List design-system violations and missing evidence by severity with file:line
-and the token/helper to use instead. Confirm which critical flows are covered
-by browser evidence. Flag only design-system/UX-correctness gaps, not
-subjective taste.

package/modules/design-system/module.json

@@ -1,9 +0,0 @@
-{
-  "name": "design-system",
-  "title": "Design system",
-  "description": "UI changes conform to your design system and critical flows carry browser evidence.",
-  "standardSection": "standard-section.md",
-  "files": [
-    { "from": "agents/design-reviewer.md", "to": ".claude/agents/design-reviewer.md" }
-  ]
-}

package/modules/design-system/standard-section.md

@@ -1,15 +0,0 @@
-### Design system (facility module)
-
-A UI that conflicts with the design system is a product-quality issue, not a
-matter of taste. Declare your source of truth here (a spec doc, a tokens
-file, a published package) — the design reviewer reads it before judging.
-
-- Use existing design tokens and shared components before inventing values.
-  Ad-hoc colors, spacing, and radii that bypass the token layer are defects.
-- UI flow changes include browser evidence — a Playwright run, screenshots,
-  or a recorded check — or an explicit reason why UI verification did not
-  apply. "It compiles" is not evidence for layout.
-- Verify responsive behavior at the breakpoints your product supports when a
-  change can affect layout, text fit, navigation, modals, or tables.
-- Empty states, error states, and loading states are part of the surface —
-  design them, don't let them fall out of the happy path.

package/src/add.mjs

@@ -1,77 +0,0 @@
-// `facility add <module>` — install a quality module: its STANDARD.md section,
-// its reviewer subagent, its guards, and its hook rules.
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
-import { insertHookRules, insertModuleSection } from "./render.mjs";
-import { fail, heading, ok, skip, warn } from "./ui.mjs";
-
-export async function addModule(name, { dir, pkgRoot, banner = true }) {
-  const moduleDir =
-    name.startsWith(".") || isAbsolute(name) ? resolve(dir, name) : join(pkgRoot, "modules", name);
-
-  const manifestPath = join(moduleDir, "module.json");
-  if (!existsSync(manifestPath)) {
-    const available = readdirSync(join(pkgRoot, "modules"), { withFileTypes: true })
-      .filter((entry) => entry.isDirectory())
-      .map((entry) => entry.name)
-      .join(", ");
-    fail(`Unknown module "${name}". Available: ${available} (or a local path).`);
-    return 1;
-  }
-  const module = JSON.parse(readFileSync(manifestPath, "utf8"));
-  if (banner) heading(`Adding module: ${module.title}`);
-
-  // 1. Files (reviewer subagents, guards) — never overwrite.
-  for (const file of module.files ?? []) {
-    const target = join(dir, file.to);
-    if (existsSync(target)) {
-      skip(`${file.to} exists — left untouched`);
-      continue;
-    }
-    mkdirSync(dirname(target), { recursive: true });
-    writeFileSync(target, readFileSync(join(moduleDir, file.from), "utf8"));
-    ok(file.to);
-  }
-
-  // 2. STANDARD.md section between the facility:modules markers.
-  const standardPath = join(dir, "STANDARD.md");
-  if (module.standardSection && existsSync(standardPath)) {
-    const section = readFileSync(join(moduleDir, module.standardSection), "utf8");
-    const { content, inserted } = insertModuleSection(readFileSync(standardPath, "utf8"), section, module.title);
-    if (inserted) {
-      writeFileSync(standardPath, content);
-      ok(`STANDARD.md — "${module.title}" section`);
-    } else {
-      skip(`STANDARD.md already has the "${module.title}" section`);
-    }
-  } else if (module.standardSection) {
-    warn("STANDARD.md not found — run `facility init` first.");
-  }
-
-  // 3. Hook rules spliced into protect-files.mjs at the module marker.
-  if (module.hookRules) {
-    const hookPath = join(dir, ".claude/hooks/protect-files.mjs");
-    if (existsSync(hookPath)) {
-      const fragment = readFileSync(join(moduleDir, module.hookRules), "utf8");
-      const { content, inserted } = insertHookRules(readFileSync(hookPath, "utf8"), fragment, module.name);
-      if (inserted) {
-        writeFileSync(hookPath, content);
-        ok(".claude/hooks/protect-files.mjs — rules spliced");
-      } else {
-        skip(".claude/hooks/protect-files.mjs already has this module's rules");
-      }
-    }
-  }
-
-  // 4. Record it in the manifest.
-  const facilityManifestPath = join(dir, ".facility.json");
-  if (existsSync(facilityManifestPath)) {
-    const manifest = JSON.parse(readFileSync(facilityManifestPath, "utf8"));
-    if (!manifest.modules?.includes(module.name)) {
-      manifest.modules = [...(manifest.modules ?? []), module.name];
-      writeFileSync(facilityManifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
-    }
-  }
-
-  return 0;
-}