@bantay/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Zachary Cancio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# Bantay
+
+Write down the rules your system must never break. We enforce them on every PR.
+
+## Quickstart
+
+```bash
+bunx @bantay/cli init        # Detect stack, generate invariants.md
+bantay check                  # Verify all invariants
+bantay export claude          # Export to CLAUDE.md for agent context
+bantay ci --github-actions    # Generate CI workflow
+```
+
+## What invariants.md looks like
+
+```markdown
+## Auth
+- [inv_auth_on_routes] auth | All API routes check authentication before processing
+
+## Schema
+- [inv_timestamps] schema | All tables have createdAt and updatedAt columns
+
+## Logging
+- [inv_no_pii_logs] logging | No PII (email, phone, SSN) appears in log output
+```
+
+Each invariant has a stable ID, category, and statement. `bantay check` evaluates them against your codebase using static analysis.
+
+## Three-tier checkers
+
+| Tier | Location | Example |
+|------|----------|---------|
+| **Built-in** | Ships with `@bantay/cli` | `auth-on-routes`, `timestamps-on-tables` |
+| **Community** | npm packages | `@bantay/checker-stripe`, `@bantay/checker-posthog` |
+| **Project** | `.bantay/checkers/*.ts` | Custom rules for your codebase |
+
+All tiers implement the same interface. Resolution order: project > community > built-in.
+
+## The .aide spec
+
+Bantay uses a `.aide` file as its source of truth. `invariants.md`, `CLAUDE.md`, and `.cursorrules` are generated exports.
+
+See [bantay.aide](./bantay.aide) for the living spec.
+
+## Commands
+
+```
+bantay init                   Initialize in current project
+bantay check                  Check all invariants
+bantay check --diff HEAD~1    Check only affected invariants
+bantay check --id inv_auth    Check single invariant
+bantay export invariants      Generate invariants.md from .aide
+bantay export claude          Export to CLAUDE.md
+bantay export cursor          Export to .cursorrules
+bantay export all             Export all targets
+bantay ci --github-actions    Generate GitHub Actions workflow
+bantay aide show              View the .aide entity tree
+bantay aide validate          Validate .aide syntax
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bantay/cli",
+  "version": "0.1.0",
+  "description": "Write down the rules your system must never break. We enforce them on every PR.",
+  "type": "module",
+  "bin": {
+    "bantay": "./src/cli.ts"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./src/cli.ts --outdir ./dist --target bun",
+    "dev": "bun run ./src/cli.ts"
+  },
+  "keywords": [
+    "invariants",
+    "cli",
+    "testing",
+    "ci",
+    "static-analysis",
+    "code-quality"
+  ],
+  "author": "Zachary Cancio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zcancio/bantay.git"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.0"
+  }
+}

package/src/aide/index.ts

@@ -0,0 +1,301 @@
+import { readFile, writeFile } from "fs/promises";
+import * as yaml from "js-yaml";
+import {
+  type AideTree,
+  type Entity,
+  type Relationship,
+  type AddEntityOptions,
+  type RemoveEntityOptions,
+  type AddRelationshipOptions,
+  type RelationshipType,
+  VALID_RELATIONSHIP_TYPES,
+  ID_PREFIX_CONVENTIONS,
+  SCENARIO_PREFIX,
+} from "./types";
+
+// Re-export types
+export type { AideTree, Entity, Relationship } from "./types";
+
+/**
+ * Read and parse a .aide YAML file
+ */
+export async function read(path: string): Promise<AideTree> {
+  const content = await readFile(path, "utf-8");
+  const parsed = yaml.load(content) as {
+    entities?: Record<string, unknown>;
+    relationships?: unknown[];
+  };
+
+  const entities: Record<string, Entity> = {};
+  const relationships: Relationship[] = [];
+
+  // Parse entities
+  if (parsed.entities) {
+    for (const [id, value] of Object.entries(parsed.entities)) {
+      const entity = value as Record<string, unknown>;
+      entities[id] = {
+        display: entity.display as string | undefined,
+        parent: entity.parent as string | undefined,
+        props: entity.props as Record<string, unknown> | undefined,
+      };
+    }
+  }
+
+  // Parse relationships
+  if (parsed.relationships && Array.isArray(parsed.relationships)) {
+    for (const rel of parsed.relationships) {
+      const r = rel as Record<string, unknown>;
+      relationships.push({
+        from: r.from as string,
+        to: r.to as string,
+        type: r.type as RelationshipType,
+        cardinality: r.cardinality as string,
+      } as Relationship);
+    }
+  }
+
+  return { entities, relationships };
+}
+
+/**
+ * Write an aide tree to a .aide YAML file
+ */
+export async function write(path: string, tree: AideTree): Promise<void> {
+  const content = yaml.dump(
+    {
+      entities: tree.entities,
+      relationships: tree.relationships,
+    },
+    {
+      indent: 2,
+      lineWidth: -1, // Don't wrap lines
+      noRefs: true,
+      sortKeys: false,
+      quotingType: '"',
+      forceQuotes: false,
+    }
+  );
+  await writeFile(path, content, "utf-8");
+}
+
+/**
+ * Add an entity to the tree
+ */
+export function addEntity(tree: AideTree, options: AddEntityOptions): AideTree {
+  const { parent, display, props } = options;
+  let { id } = options;
+
+  // Validate parent exists if specified
+  if (parent && !tree.entities[parent]) {
+    throw new Error(`Parent entity "${parent}" not found`);
+  }
+
+  // Auto-generate ID if not provided
+  if (!id) {
+    id = generateEntityId(tree, parent);
+  }
+
+  // Check for duplicate ID
+  if (tree.entities[id]) {
+    throw new Error(`Entity "${id}" already exists`);
+  }
+
+  // Create new entity
+  const entity: Entity = {};
+  if (display) entity.display = display;
+  if (parent) entity.parent = parent;
+  if (props) entity.props = props;
+
+  // Return new tree with entity added
+  return {
+    entities: {
+      ...tree.entities,
+      [id]: entity,
+    },
+    relationships: [...tree.relationships],
+  };
+}
+
+/**
+ * Remove an entity from the tree
+ */
+export function removeEntity(
+  tree: AideTree,
+  id: string,
+  options: RemoveEntityOptions = {}
+): AideTree {
+  const { force = false } = options;
+
+  // Check entity exists
+  if (!tree.entities[id]) {
+    throw new Error(`Entity "${id}" not found`);
+  }
+
+  // Find relationships involving this entity
+  const involvedRelationships = tree.relationships.filter(
+    (r) => r.from === id || r.to === id
+  );
+
+  if (involvedRelationships.length > 0 && !force) {
+    throw new Error(
+      `Cannot remove "${id}": relationships exist. Use force=true to remove anyway.`
+    );
+  }
+
+  // Find all child entities (cascade)
+  const idsToRemove = new Set<string>([id]);
+  findChildEntities(tree, id, idsToRemove);
+
+  // Remove entities
+  const newEntities: Record<string, Entity> = {};
+  for (const [entityId, entity] of Object.entries(tree.entities)) {
+    if (!idsToRemove.has(entityId)) {
+      newEntities[entityId] = entity;
+    }
+  }
+
+  // Remove relationships involving removed entities
+  const newRelationships = tree.relationships.filter(
+    (r) => !idsToRemove.has(r.from) && !idsToRemove.has(r.to)
+  );
+
+  return {
+    entities: newEntities,
+    relationships: newRelationships,
+  };
+}
+
+/**
+ * Add a relationship to the tree
+ */
+export function addRelationship(
+  tree: AideTree,
+  options: AddRelationshipOptions
+): AideTree {
+  const { from, to, type, cardinality } = options;
+
+  // Validate 'from' entity exists
+  if (!tree.entities[from]) {
+    throw new Error(`"from" entity "${from}" not found`);
+  }
+
+  // Validate 'to' entity exists
+  if (!tree.entities[to]) {
+    throw new Error(`"to" entity "${to}" not found`);
+  }
+
+  // Validate relationship type
+  if (!VALID_RELATIONSHIP_TYPES.includes(type)) {
+    throw new Error(
+      `Invalid relationship type "${type}". Valid types: ${VALID_RELATIONSHIP_TYPES.join(", ")}`
+    );
+  }
+
+  const relationship: Relationship = { from, to, type, cardinality };
+
+  return {
+    entities: { ...tree.entities },
+    relationships: [...tree.relationships, relationship],
+  };
+}
+
+/**
+ * Validate the aide tree and return an array of error messages
+ */
+export function validate(tree: AideTree): string[] {
+  const errors: string[] = [];
+
+  // Check for orphaned relationships (from entity missing)
+  for (const rel of tree.relationships) {
+    if (!tree.entities[rel.from]) {
+      errors.push(
+        `Orphaned relationship: "from" entity "${rel.from}" not found`
+      );
+    }
+    if (!tree.entities[rel.to]) {
+      errors.push(`Orphaned relationship: "to" entity "${rel.to}" not found`);
+    }
+
+    // Validate relationship type
+    if (!VALID_RELATIONSHIP_TYPES.includes(rel.type)) {
+      errors.push(
+        `Invalid relationship type "${rel.type}" in relationship from "${rel.from}" to "${rel.to}"`
+      );
+    }
+  }
+
+  // Check for missing parent references
+  for (const [id, entity] of Object.entries(tree.entities)) {
+    if (entity.parent && !tree.entities[entity.parent]) {
+      errors.push(`Entity "${id}" has missing parent "${entity.parent}"`);
+    }
+  }
+
+  return errors;
+}
+
+// --- Helper Functions ---
+
+/**
+ * Find all child entities recursively
+ */
+function findChildEntities(
+  tree: AideTree,
+  parentId: string,
+  collected: Set<string>
+): void {
+  for (const [id, entity] of Object.entries(tree.entities)) {
+    if (entity.parent === parentId && !collected.has(id)) {
+      collected.add(id);
+      findChildEntities(tree, id, collected);
+    }
+  }
+}
+
+/**
+ * Generate an entity ID based on parent conventions
+ */
+function generateEntityId(tree: AideTree, parent?: string): string {
+  if (!parent) {
+    // Generate a generic ID
+    let counter = 1;
+    while (tree.entities[`entity_${counter}`]) {
+      counter++;
+    }
+    return `entity_${counter}`;
+  }
+
+  // Check if parent has a known prefix convention
+  let prefix = ID_PREFIX_CONVENTIONS[parent];
+
+  // If parent is a CUJ (starts with cuj_), generate scenario prefix
+  if (!prefix && parent.startsWith("cuj_")) {
+    prefix = SCENARIO_PREFIX;
+  }
+
+  // If parent itself has a prefix, use the same prefix
+  if (!prefix) {
+    for (const [container, containerPrefix] of Object.entries(
+      ID_PREFIX_CONVENTIONS
+    )) {
+      if (tree.entities[parent]?.parent === container) {
+        prefix = containerPrefix;
+        break;
+      }
+    }
+  }
+
+  // Default to a generic prefix based on parent
+  if (!prefix) {
+    prefix = `${parent}_`;
+  }
+
+  // Find next available number for this prefix
+  let counter = 1;
+  while (tree.entities[`${prefix}${counter}`]) {
+    counter++;
+  }
+
+  return `${prefix}${counter}`;
+}
+

package/src/aide/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Valid relationship types in an aide file
+ */
+export const VALID_RELATIONSHIP_TYPES = [
+  "protected_by",
+  "depends_on",
+  "implements",
+  "delegates_to",
+  "weakens",
+] as const;
+
+export type RelationshipType = (typeof VALID_RELATIONSHIP_TYPES)[number];
+
+/**
+ * Valid cardinality values
+ */
+export const VALID_CARDINALITIES = [
+  "one_to_one",
+  "one_to_many",
+  "many_to_one",
+  "many_to_many",
+] as const;
+
+export type Cardinality = (typeof VALID_CARDINALITIES)[number];
+
+/**
+ * A relationship between two entities in the aide tree
+ */
+export interface Relationship {
+  from: string;
+  to: string;
+  type: RelationshipType;
+  cardinality: Cardinality;
+}
+
+/**
+ * An entity in the aide tree
+ */
+export interface Entity {
+  display?: string;
+  parent?: string;
+  props?: Record<string, unknown>;
+}
+
+/**
+ * The complete aide tree structure
+ */
+export interface AideTree {
+  entities: Record<string, Entity>;
+  relationships: Relationship[];
+}
+
+/**
+ * Options for adding an entity
+ */
+export interface AddEntityOptions {
+  id?: string;
+  parent?: string;
+  display?: string;
+  props?: Record<string, unknown>;
+}
+
+/**
+ * Options for removing an entity
+ */
+export interface RemoveEntityOptions {
+  force?: boolean;
+}
+
+/**
+ * Options for adding a relationship
+ */
+export interface AddRelationshipOptions {
+  from: string;
+  to: string;
+  type: RelationshipType;
+  cardinality: Cardinality;
+}
+
+/**
+ * Prefix conventions for auto-generating entity IDs based on parent
+ */
+export const ID_PREFIX_CONVENTIONS: Record<string, string> = {
+  cujs: "cuj_",
+  invariants: "inv_",
+  constraints: "con_",
+  foundations: "found_",
+  wisdom: "wis_",
+};
+
+/**
+ * Prefix for entities under a CUJ (scenarios)
+ */
+export const SCENARIO_PREFIX = "sc_";

package/src/checkers/auth.ts

@@ -0,0 +1,111 @@
+import type { Checker, CheckResult, CheckerContext, CheckViolation } from "./types";
+import type { Invariant } from "../generators/invariants";
+import { Glob } from "bun";
+import { readFile } from "fs/promises";
+import { join, relative } from "path";
+
+// Auth patterns to look for in route files
+const AUTH_PATTERNS = [
+  // Next.js auth patterns
+  /auth\(\)/,
+  /getServerSession/,
+  /useSession/,
+  /withAuth/,
+  /requireAuth/,
+  /checkAuth/,
+  /isAuthenticated/,
+  /currentUser/,
+  /getUser/,
+  // Clerk patterns
+  /auth\(\)\.protect/,
+  /clerkMiddleware/,
+  /SignedIn/,
+  /SignedOut/,
+  // Auth.js / NextAuth patterns
+  /getSession/,
+  /unstable_getServerSession/,
+  // Supabase patterns
+  /supabase\.auth/,
+  /createServerClient/,
+  // Generic patterns
+  /middleware.*auth/i,
+  /protected/i,
+];
+
+// Route handler exports that need auth
+const ROUTE_EXPORTS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+
+async function findRouteFiles(
+  projectPath: string,
+  routeDirectories: string[]
+): Promise<string[]> {
+  const routeFiles: string[] = [];
+
+  for (const routeDir of routeDirectories) {
+    const pattern = "**/{route,page}.{ts,tsx,js,jsx}";
+    const glob = new Glob(pattern);
+
+    const dirPath = join(projectPath, routeDir);
+
+    try {
+      for await (const file of glob.scan({ cwd: dirPath, absolute: true })) {
+        routeFiles.push(file);
+      }
+    } catch {
+      // Directory doesn't exist, skip
+    }
+  }
+
+  return routeFiles;
+}
+
+function hasAuthCheck(content: string): boolean {
+  return AUTH_PATTERNS.some((pattern) => pattern.test(content));
+}
+
+function isApiRoute(content: string): boolean {
+  // Check if file exports HTTP method handlers
+  return ROUTE_EXPORTS.some((method) => {
+    const pattern = new RegExp(`export\\s+(async\\s+)?function\\s+${method}\\b`);
+    return pattern.test(content);
+  });
+}
+
+export const authChecker: Checker = {
+  category: "auth",
+
+  async check(invariant: Invariant, context: CheckerContext): Promise<CheckResult> {
+    const violations: CheckViolation[] = [];
+    const routeDirs = context.config.routeDirectories ?? ["app/api", "pages/api"];
+
+    const routeFiles = await findRouteFiles(context.projectPath, routeDirs);
+
+    for (const filePath of routeFiles) {
+      try {
+        const content = await readFile(filePath, "utf-8");
+
+        // Only check API routes (files with HTTP method exports)
+        if (!isApiRoute(content)) {
+          continue;
+        }
+
+        // Check if any auth pattern is present
+        if (!hasAuthCheck(content)) {
+          violations.push({
+            filePath: relative(context.projectPath, filePath),
+            line: 1,
+            message: "API route missing authentication check",
+          });
+        }
+      } catch {
+        // File read error, skip
+      }
+    }
+
+    return {
+      invariant,
+      status: violations.length > 0 ? "fail" : "pass",
+      violations,
+    };
+  },
+};