ai-forge-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pablo García
+
+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,148 @@
+# Forge CLI
+
+TypeScript stack scaffolding & enforcement CLI for **TanStack Start + Convex + Tailwind**.
+
+The key insight: Claude Code reads `CLAUDE.md` automatically. Forge uses this as a **hook** — imperative instructions that tell Claude it MUST use the forge CLI commands. No more AI drift.
+
+## Installation
+
+```bash
+npm install -g forge-cli
+```
+
+Or use with npx:
+
+```bash
+npx forge-cli init my-app
+```
+
+## Commands
+
+### `forge init <project-name>`
+
+Creates a complete project with:
+- TanStack Start (file-based routing, SSR-ready)
+- Convex (real-time database)
+- Tailwind CSS + shadcn/ui ready
+- Biome (linting/formatting)
+- TypeScript strict mode
+- **CLAUDE.md** — the AI hook
+
+```bash
+forge init my-app
+cd my-app
+pnpm install
+npx convex init
+pnpm dlx shadcn@latest init
+pnpm dev
+```
+
+### `forge add:feature <name>`
+
+Creates a full vertical slice:
+
+```
+convex/features/<name>/
+├── schema.ts      # Table definition (exports <name>Tables)
+├── queries.ts     # All queries
+├── mutations.ts   # All mutations
+└── index.ts       # Barrel export
+
+src/features/<name>/
+├── components/
+│   └── index.ts   # Component exports
+├── hooks.ts       # Feature hooks
+└── index.ts       # Barrel export
+
+app/routes/<name>/
+├── index.tsx      # List view
+└── $id.tsx        # Detail view
+```
+
+Also auto-registers the schema in `convex/schema.ts`.
+
+```bash
+forge add:feature projects
+
+# Output:
+✓ Created convex/features/projects/schema.ts
+✓ Created convex/features/projects/queries.ts
+✓ Created convex/features/projects/mutations.ts
+✓ Created convex/features/projects/index.ts
+✓ Created src/features/projects/components/index.ts
+✓ Created src/features/projects/hooks.ts
+✓ Created src/features/projects/index.ts
+✓ Created app/routes/projects/index.tsx
+✓ Created app/routes/projects/$id.tsx
+✓ Updated convex/schema.ts
+```
+
+### `forge check`
+
+Validates project structure. Fails if rules are broken. Use in CI/pre-commit.
+
+```bash
+forge check
+
+# Output:
+✓ Feature structure valid
+✓ Component locations valid
+✓ Hook locations valid
+✓ Thin routes valid
+✓ Cross-feature imports valid
+✓ Feature parity valid
+
+All checks passed!
+```
+
+## Validation Rules
+
+1. **Feature structure** — Every feature has required files
+2. **Component location** — Components only in `src/features/*/components/` or `src/components/`
+3. **Hook location** — Hooks only in `src/features/*/hooks.ts` or `src/hooks/`
+4. **Thin routes** — Route files can only import from features/components, no business logic
+5. **No cross-feature imports** — `src/features/X/` cannot import from `src/features/Y/`
+6. **Feature parity** — Every `src/features/X` has matching `convex/features/X`
+
+## The CLAUDE.md Hook
+
+When you run `forge init`, it generates a `CLAUDE.md` file that instructs Claude Code to:
+
+1. **Always** run `forge add:feature <name>` before building any feature
+2. **Never** create feature files manually
+3. **Always** run `forge check` before completing any task
+
+This eliminates AI drift and enforces consistent architecture.
+
+```markdown
+# From generated CLAUDE.md
+
+## YOU MUST USE FORGE CLI
+
+When the user asks you to build ANY feature, you MUST:
+1. FIRST run `forge add:feature <name>`
+2. THEN fill in the generated files
+3. NEVER create feature files manually
+```
+
+## Project Structure
+
+```
+app/routes/         → Thin route files (import from features, no logic)
+src/features/       → All feature code (components, hooks, types)
+src/components/     → Shared UI only (used across features)
+src/lib/            → Pure utilities
+convex/features/    → Backend mirrors frontend features
+```
+
+## Stack
+
+- **Frontend**: TanStack Start
+- **Backend**: Convex
+- **Styling**: Tailwind CSS + shadcn/ui
+- **Linting**: Biome
+- **Language**: TypeScript (strict)
+
+## License
+
+MIT

package/dist/add-feature-YXWSRIVE.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+import {
+  camelCase,
+  kebabCase,
+  renderTemplate
+} from "./chunk-PIFX2L5H.js";
+import {
+  fileExists,
+  logger,
+  readFile,
+  writeFile
+} from "./chunk-J4V5PGVT.js";
+
+// src/commands/add-feature.ts
+import { defineCommand } from "citty";
+import { join } from "path";
+var add_feature_default = defineCommand({
+  meta: {
+    name: "add:feature",
+    description: "Create a new feature with vertical slice architecture"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Name of the feature (will be converted to kebab-case)",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const rawName = args.name;
+    const name = kebabCase(rawName);
+    const cwd = process.cwd();
+    const srcFeaturePath = join(cwd, "src/features", name);
+    const convexFeaturePath = join(cwd, "convex/features", name);
+    if (await fileExists(srcFeaturePath)) {
+      logger.error(`Feature "${name}" already exists at src/features/${name}`);
+      process.exit(1);
+    }
+    if (await fileExists(convexFeaturePath)) {
+      logger.error(`Feature "${name}" already exists at convex/features/${name}`);
+      process.exit(1);
+    }
+    logger.blank();
+    const templateData = { name };
+    const files = [
+      // Convex files
+      {
+        templatePath: "feature/convex/schema.ts.hbs",
+        destPath: join(cwd, "convex/features", name, "schema.ts")
+      },
+      {
+        templatePath: "feature/convex/queries.ts.hbs",
+        destPath: join(cwd, "convex/features", name, "queries.ts")
+      },
+      {
+        templatePath: "feature/convex/mutations.ts.hbs",
+        destPath: join(cwd, "convex/features", name, "mutations.ts")
+      },
+      {
+        templatePath: "feature/convex/index.ts.hbs",
+        destPath: join(cwd, "convex/features", name, "index.ts")
+      },
+      // Src files
+      {
+        templatePath: "feature/src/components/index.ts.hbs",
+        destPath: join(cwd, "src/features", name, "components/index.ts")
+      },
+      {
+        templatePath: "feature/src/hooks.ts.hbs",
+        destPath: join(cwd, "src/features", name, "hooks.ts")
+      },
+      {
+        templatePath: "feature/src/index.ts.hbs",
+        destPath: join(cwd, "src/features", name, "index.ts")
+      },
+      // Route files
+      {
+        templatePath: "feature/routes/index.tsx.hbs",
+        destPath: join(cwd, "app/routes", name, "index.tsx")
+      },
+      {
+        templatePath: "feature/routes/$id.tsx.hbs",
+        destPath: join(cwd, "app/routes", name, "$id.tsx")
+      }
+    ];
+    for (const file of files) {
+      const content = renderTemplate(file.templatePath, templateData);
+      await writeFile(file.destPath, content);
+      const relativePath = file.destPath.replace(cwd + "/", "");
+      logger.success(`Created ${relativePath}`);
+    }
+    await updateConvexSchema(cwd, name);
+    logger.blank();
+    logger.log(`  Feature "${name}" created successfully.`);
+    logger.blank();
+    logger.log("  Next steps:");
+    logger.log(`    1. Define your schema in convex/features/${name}/schema.ts`);
+    logger.log("    2. Run `npx convex dev` to sync");
+    logger.log(`    3. Build components in src/features/${name}/components/`);
+    logger.blank();
+  }
+});
+async function updateConvexSchema(cwd, featureName) {
+  const schemaPath = join(cwd, "convex/schema.ts");
+  const camelName = camelCase(featureName);
+  if (!await fileExists(schemaPath)) {
+    logger.warn("convex/schema.ts not found - skipping schema registration");
+    return;
+  }
+  let content = await readFile(schemaPath);
+  const importLine = `import { ${camelName}Tables } from "./features/${featureName}/schema";`;
+  const exportDefault = "export default defineSchema({";
+  if (content.includes(importLine)) {
+    logger.warn("Schema import already exists - skipping");
+    return;
+  }
+  const exportPos = content.indexOf(exportDefault);
+  if (exportPos === -1) {
+    logger.warn("Could not find 'export default defineSchema({' in schema.ts - skipping");
+    return;
+  }
+  content = content.slice(0, exportPos) + importLine + "\n\n" + content.slice(exportPos);
+  const spreadLine = `  ...${camelName}Tables,`;
+  const defineSchemaStart = content.indexOf(exportDefault);
+  const afterDefineSchema = content.slice(defineSchemaStart + exportDefault.length);
+  const closingIndex = content.lastIndexOf("});");
+  if (closingIndex === -1) {
+    logger.warn("Could not find closing '});' in schema.ts - skipping spread");
+    return;
+  }
+  if (content.includes(spreadLine)) {
+    logger.warn("Schema spread already exists - skipping");
+  } else {
+    content = content.slice(0, closingIndex) + spreadLine + "\n" + content.slice(closingIndex);
+  }
+  await writeFile(schemaPath, content);
+  logger.success("Updated convex/schema.ts");
+}
+export {
+  add_feature_default as default
+};

package/dist/check-RCJRXIU5.js

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+import {
+  fileExists,
+  logger,
+  readFile
+} from "./chunk-J4V5PGVT.js";
+
+// src/commands/check.ts
+import { defineCommand } from "citty";
+
+// src/validators/feature-structure.ts
+import { join } from "path";
+import fg from "fast-glob";
+var REQUIRED_SRC_FILES = ["components/index.ts", "hooks.ts", "index.ts"];
+var REQUIRED_CONVEX_FILES = ["schema.ts", "queries.ts", "mutations.ts", "index.ts"];
+var featureStructureValidator = {
+  name: "Feature structure",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const srcFeatures = await fg("src/features/*", {
+      cwd,
+      onlyDirectories: true
+    });
+    for (const featurePath of srcFeatures) {
+      const featureName = featurePath.split("/").pop();
+      for (const requiredFile of REQUIRED_SRC_FILES) {
+        const filePath = join(cwd, featurePath, requiredFile);
+        if (!await fileExists(filePath)) {
+          errors.push({
+            file: join(featurePath, requiredFile),
+            message: `Missing required file in feature "${featureName}"`
+          });
+        }
+      }
+    }
+    const convexFeatures = await fg("convex/features/*", {
+      cwd,
+      onlyDirectories: true
+    });
+    for (const featurePath of convexFeatures) {
+      const featureName = featurePath.split("/").pop();
+      for (const requiredFile of REQUIRED_CONVEX_FILES) {
+        const filePath = join(cwd, featurePath, requiredFile);
+        if (!await fileExists(filePath)) {
+          errors.push({
+            file: join(featurePath, requiredFile),
+            message: `Missing required file in feature "${featureName}"`
+          });
+        }
+      }
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+
+// src/validators/locations.ts
+import fg2 from "fast-glob";
+var componentLocationValidator = {
+  name: "Component locations",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const tsxFiles = await fg2("**/*.tsx", {
+      cwd,
+      ignore: [
+        "node_modules/**",
+        "dist/**",
+        ".vinxi/**",
+        "app/**",
+        // TanStack Start entry files and routes
+        "src/features/*/components/**",
+        // Valid location
+        "src/components/**",
+        // Valid location
+        "src/providers/**"
+        // Provider wrappers
+      ]
+    });
+    for (const file of tsxFiles) {
+      errors.push({
+        file,
+        message: "Component outside valid location (should be in src/features/*/components/ or src/components/)"
+      });
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+var hookLocationValidator = {
+  name: "Hook locations",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const potentialHookFiles = await fg2(["**/use*.ts", "**/use*.tsx", "**/*hook*.ts", "**/*hook*.tsx"], {
+      cwd,
+      ignore: [
+        "node_modules/**",
+        "dist/**",
+        "src/features/*/hooks.ts",
+        // Valid location
+        "src/hooks/**",
+        // Valid location
+        "src/hooks.ts"
+        // Valid location (root hooks file)
+      ]
+    });
+    for (const file of potentialHookFiles) {
+      if (file.startsWith("app/routes/")) continue;
+      errors.push({
+        file,
+        message: "Hook file outside valid location (should be in src/features/*/hooks.ts or src/hooks/)"
+      });
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+
+// src/validators/thin-routes.ts
+import { join as join2 } from "path";
+import fg3 from "fast-glob";
+var ALLOWED_IMPORT_PATTERNS = [
+  /^~/,
+  // ~/features/, ~/components/, ~/lib/
+  /^@tanstack\//,
+  // @tanstack/react-router, etc.
+  /^convex\//,
+  // convex/react, etc.
+  /^@convex\//,
+  // @convex/_generated/
+  /^react$/,
+  // react
+  /^react-dom$/
+  // react-dom
+];
+var LINE_THRESHOLD = 50;
+var thinRoutesValidator = {
+  name: "Thin routes",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const routeFiles = await fg3("app/routes/**/*.{ts,tsx}", {
+      cwd,
+      ignore: ["node_modules/**"]
+    });
+    for (const file of routeFiles) {
+      const fullPath = join2(cwd, file);
+      const content = await readFile(fullPath);
+      const lines = content.split("\n");
+      if (lines.length > LINE_THRESHOLD) {
+        warnings.push({
+          file,
+          message: `Route file exceeds ${LINE_THRESHOLD} lines (${lines.length} lines) - consider moving logic to feature`
+        });
+      }
+      const importMatches = content.matchAll(/import\s+.*?\s+from\s+["']([^"']+)["']/g);
+      for (const match of importMatches) {
+        const importPath = match[1];
+        if (importPath.startsWith(".")) continue;
+        const isAllowed = ALLOWED_IMPORT_PATTERNS.some((pattern) => pattern.test(importPath));
+        if (!isAllowed) {
+          errors.push({
+            file,
+            message: `Invalid import "${importPath}" - routes should only import from ~/features/, ~/components/, ~/lib/, or framework packages`
+          });
+        }
+      }
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+
+// src/validators/cross-feature.ts
+import { join as join3, dirname } from "path";
+import fg4 from "fast-glob";
+var crossFeatureValidator = {
+  name: "Cross-feature imports",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const featureFiles = await fg4("src/features/**/*.{ts,tsx}", {
+      cwd,
+      ignore: ["node_modules/**"]
+    });
+    for (const file of featureFiles) {
+      const parts = file.split("/");
+      const featureIndex = parts.indexOf("features");
+      if (featureIndex === -1 || featureIndex + 1 >= parts.length) continue;
+      const currentFeature = parts[featureIndex + 1];
+      const fullPath = join3(cwd, file);
+      const content = await readFile(fullPath);
+      const importMatches = content.matchAll(/import\s+.*?\s+from\s+["']([^"']+)["']/g);
+      for (const match of importMatches) {
+        const importPath = match[1];
+        const tildeMatch = importPath.match(/^~\/features\/([^/]+)/);
+        if (tildeMatch) {
+          const importedFeature = tildeMatch[1];
+          if (importedFeature !== currentFeature) {
+            errors.push({
+              file,
+              message: `Cross-feature import from "${currentFeature}" to "${importedFeature}"`
+            });
+          }
+          continue;
+        }
+        if (importPath.startsWith("..")) {
+          const fileDir = dirname(file);
+          const resolvedParts = resolveRelativePath(fileDir, importPath);
+          if (resolvedParts.length >= 3 && resolvedParts[0] === "src" && resolvedParts[1] === "features") {
+            const importedFeature = resolvedParts[2];
+            if (importedFeature !== currentFeature) {
+              errors.push({
+                file,
+                message: `Cross-feature import from "${currentFeature}" to "${importedFeature}" via relative path`
+              });
+            }
+          }
+        }
+      }
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+function resolveRelativePath(fromDir, relativePath) {
+  const fromParts = fromDir.split("/").filter(Boolean);
+  const relativeParts = relativePath.split("/").filter(Boolean);
+  const result = [...fromParts];
+  for (const part of relativeParts) {
+    if (part === "..") {
+      result.pop();
+    } else if (part !== ".") {
+      result.push(part);
+    }
+  }
+  return result;
+}
+
+// src/validators/feature-parity.ts
+import fg5 from "fast-glob";
+var featureParityValidator = {
+  name: "Feature parity",
+  async validate(cwd) {
+    const errors = [];
+    const warnings = [];
+    const srcFeatures = await fg5("src/features/*", {
+      cwd,
+      onlyDirectories: true
+    });
+    const srcFeatureNames = new Set(srcFeatures.map((f) => f.split("/").pop()));
+    const convexFeatures = await fg5("convex/features/*", {
+      cwd,
+      onlyDirectories: true
+    });
+    const convexFeatureNames = new Set(convexFeatures.map((f) => f.split("/").pop()));
+    for (const name of srcFeatureNames) {
+      if (!convexFeatureNames.has(name)) {
+        errors.push({
+          file: `src/features/${name}`,
+          message: `Feature "${name}" exists in src/features but not in convex/features`
+        });
+      }
+    }
+    for (const name of convexFeatureNames) {
+      if (!srcFeatureNames.has(name)) {
+        errors.push({
+          file: `convex/features/${name}`,
+          message: `Feature "${name}" exists in convex/features but not in src/features`
+        });
+      }
+    }
+    return {
+      rule: this.name,
+      passed: errors.length === 0,
+      errors,
+      warnings
+    };
+  }
+};
+
+// src/validators/index.ts
+var validators = [
+  featureStructureValidator,
+  componentLocationValidator,
+  hookLocationValidator,
+  thinRoutesValidator,
+  crossFeatureValidator,
+  featureParityValidator
+];
+async function runAllValidators(cwd) {
+  const results = [];
+  for (const validator of validators) {
+    const result = await validator.validate(cwd);
+    results.push(result);
+  }
+  return results;
+}
+
+// src/commands/check.ts
+import pc from "picocolors";
+var check_default = defineCommand({
+  meta: {
+    name: "check",
+    description: "Validate project structure and conventions"
+  },
+  async run() {
+    const cwd = process.cwd();
+    logger.blank();
+    logger.log("  Checking project structure...");
+    logger.blank();
+    const results = await runAllValidators(cwd);
+    let totalErrors = 0;
+    let totalWarnings = 0;
+    for (const result of results) {
+      if (result.passed && result.warnings.length === 0) {
+        logger.success(`${result.rule} valid`);
+      } else if (result.passed && result.warnings.length > 0) {
+        logger.warn(`${result.rule} (${result.warnings.length} warning${result.warnings.length > 1 ? "s" : ""})`);
+        for (const warning of result.warnings) {
+          logger.log(`    ${pc.yellow("\u2192")} ${warning.file}: ${warning.message}`);
+        }
+        totalWarnings += result.warnings.length;
+      } else {
+        logger.error(`${result.rule} violated`);
+        for (const error of result.errors) {
+          logger.log(`    ${pc.red("\u2192")} ${error.file}: ${error.message}`);
+        }
+        for (const warning of result.warnings) {
+          logger.log(`    ${pc.yellow("\u2192")} ${warning.file}: ${warning.message}`);
+        }
+        totalErrors += result.errors.length;
+        totalWarnings += result.warnings.length;
+      }
+    }
+    logger.blank();
+    if (totalErrors > 0) {
+      logger.log(`  ${pc.red(`${totalErrors} error${totalErrors > 1 ? "s" : ""} found.`)}`);
+      if (totalWarnings > 0) {
+        logger.log(`  ${pc.yellow(`${totalWarnings} warning${totalWarnings > 1 ? "s" : ""}.`)}`);
+      }
+      logger.blank();
+      process.exit(1);
+    } else if (totalWarnings > 0) {
+      logger.log(`  ${pc.yellow(`${totalWarnings} warning${totalWarnings > 1 ? "s" : ""} found.`)}`);
+      logger.blank();
+    } else {
+      logger.log(`  ${pc.green("All checks passed!")}`);
+      logger.blank();
+    }
+  }
+});
+export {
+  check_default as default
+};