ai-forge-cli 0.1.0

package/dist/templates/init/package.json.hbs

@@ -0,0 +1,34 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vinxi dev",
+    "build": "vinxi build",
+    "start": "vinxi start",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "format": "biome format . --write"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.95.1",
+    "@tanstack/start": "^1.95.1",
+    "convex": "^1.17.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vinxi": "^0.5.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

package/dist/templates/init/postcss.config.js.hbs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/dist/templates/init/src/lib/cn.ts.hbs

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/dist/templates/init/src/providers/index.tsx.hbs

@@ -0,0 +1,10 @@
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { useState } from "react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const [convex] = useState(
+    () => new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)
+  );
+
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}

package/dist/templates/init/tailwind.config.ts.hbs

@@ -0,0 +1,12 @@
+import type { Config } from "tailwindcss";
+
+export default {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx}",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+} satisfies Config;

package/dist/templates/init/tsconfig.json.hbs

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "paths": {
+      "~/*": ["./src/*"],
+      "@convex/*": ["./convex/*"]
+    }
+  },
+  "include": ["src", "app", "convex"]
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ai-forge-cli",
+  "version": "0.1.0",
+  "description": "TypeScript stack scaffolding & enforcement CLI for TanStack Start + Convex",
+  "type": "module",
+  "license": "MIT",
+  "author": "Pablo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Thaloz/forge-cli.git"
+  },
+  "homepage": "https://github.com/Thaloz/forge-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Thaloz/forge-cli/issues"
+  },
+  "keywords": [
+    "cli",
+    "scaffold",
+    "typescript",
+    "tanstack",
+    "convex",
+    "tailwind",
+    "ai",
+    "claude"
+  ],
+  "bin": {
+    "forge": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dependencies": {
+    "citty": "^0.1.6",
+    "consola": "^3.2.3",
+    "fast-glob": "^3.3.2",
+    "handlebars": "^4.7.8",
+    "oxc-parser": "^0.56.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "tsx": "^4.19.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/templates/feature/convex/index.ts.hbs

@@ -0,0 +1,3 @@
+export * as queries from "./queries";
+export * as mutations from "./mutations";
+export { {{camelCase name}}Tables } from "./schema";

package/templates/feature/convex/mutations.ts.hbs

@@ -0,0 +1,37 @@
+import { mutation } from "convex/_generated/server";
+import { v } from "convex/values";
+
+export const create = mutation({
+  args: {
+    // Define your args here
+  },
+  handler: async (ctx, args) => {
+    const now = Date.now();
+    return await ctx.db.insert("{{camelCase name}}", {
+      ...args,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+export const update = mutation({
+  args: {
+    id: v.id("{{camelCase name}}"),
+    // Define your update args here
+  },
+  handler: async (ctx, args) => {
+    const { id, ...fields } = args;
+    await ctx.db.patch(id, {
+      ...fields,
+      updatedAt: Date.now(),
+    });
+  },
+});
+
+export const remove = mutation({
+  args: { id: v.id("{{camelCase name}}") },
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+  },
+});

package/templates/feature/convex/queries.ts.hbs

@@ -0,0 +1,16 @@
+import { query } from "convex/_generated/server";
+import { v } from "convex/values";
+
+export const list = query({
+  args: {},
+  handler: async (ctx) => {
+    return await ctx.db.query("{{camelCase name}}").collect();
+  },
+});
+
+export const getById = query({
+  args: { id: v.id("{{camelCase name}}") },
+  handler: async (ctx, args) => {
+    return await ctx.db.get(args.id);
+  },
+});

package/templates/feature/convex/schema.ts.hbs

@@ -0,0 +1,10 @@
+import { defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export const {{camelCase name}}Tables = {
+  {{camelCase name}}: defineTable({
+    // Define your fields here
+    createdAt: v.number(),
+    updatedAt: v.number(),
+  }).index("by_created", ["createdAt"]),
+};

package/templates/feature/routes/$id.tsx.hbs

@@ -0,0 +1,27 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { use{{pascalCase name}} } from "~/features/{{camelCase name}}";
+import type { Id } from "@convex/_generated/dataModel";
+
+export const Route = createFileRoute("/{{kebabCase name}}/$id")({
+  component: {{pascalCase name}}DetailRoute,
+});
+
+function {{pascalCase name}}DetailRoute() {
+  const { id } = Route.useParams();
+  const { item, isLoading } = use{{pascalCase name}}(id as Id<"{{camelCase name}}">);
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!item) {
+    return <div>Not found</div>;
+  }
+
+  return (
+    <div>
+      <h1>{{pascalCase name}} Detail</h1>
+      {/* Build your UI here */}
+    </div>
+  );
+}

package/templates/feature/routes/index.tsx.hbs

@@ -0,0 +1,21 @@
+import { createFileRoute } from "@tanstack/react-router";
+import { use{{pascalCase name}}List } from "~/features/{{camelCase name}}";
+
+export const Route = createFileRoute("/{{kebabCase name}}/")({
+  component: {{pascalCase name}}IndexRoute,
+});
+
+function {{pascalCase name}}IndexRoute() {
+  const { items, isLoading } = use{{pascalCase name}}List();
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      <h1>{{pascalCase name}}</h1>
+      {/* Build your UI here */}
+    </div>
+  );
+}

package/templates/feature/src/components/index.ts.hbs

@@ -0,0 +1,4 @@
+// Export components as you create them
+// export { {{pascalCase name}}Card } from "./{{pascalCase name}}Card";
+// export { {{pascalCase name}}List } from "./{{pascalCase name}}List";
+// export { {{pascalCase name}}Form } from "./{{pascalCase name}}Form";

package/templates/feature/src/hooks.ts.hbs

@@ -0,0 +1,29 @@
+import { useQuery, useMutation } from "convex/react";
+import { api } from "@convex/_generated/api";
+import type { Id } from "@convex/_generated/dataModel";
+
+export function use{{pascalCase name}}List() {
+  const items = useQuery(api.features.{{camelCase name}}.queries.list);
+
+  return {
+    items: items ?? [],
+    isLoading: items === undefined,
+  };
+}
+
+export function use{{pascalCase name}}(id: Id<"{{camelCase name}}">) {
+  const item = useQuery(api.features.{{camelCase name}}.queries.getById, { id });
+
+  return {
+    item,
+    isLoading: item === undefined,
+  };
+}
+
+export function use{{pascalCase name}}Mutations() {
+  const create = useMutation(api.features.{{camelCase name}}.mutations.create);
+  const update = useMutation(api.features.{{camelCase name}}.mutations.update);
+  const remove = useMutation(api.features.{{camelCase name}}.mutations.remove);
+
+  return { create, update, remove };
+}

package/templates/feature/src/index.ts.hbs

@@ -0,0 +1,2 @@
+export * from "./hooks";
+export * from "./components";

package/templates/init/app/client.tsx.hbs

@@ -0,0 +1,7 @@
+import { hydrateRoot } from "react-dom/client";
+import { StartClient } from "@tanstack/start";
+import { createRouter } from "./router";
+
+const router = createRouter();
+
+hydrateRoot(document, <StartClient router={router} />);

package/templates/init/app/router.tsx.hbs

@@ -0,0 +1,17 @@
+import { createRouter as createTanStackRouter } from "@tanstack/react-router";
+import { routeTree } from "./routeTree.gen";
+
+export function createRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    defaultPreload: "intent",
+  });
+
+  return router;
+}
+
+declare module "@tanstack/react-router" {
+  interface Register {
+    router: ReturnType<typeof createRouter>;
+  }
+}

package/templates/init/app/routes/__root.tsx.hbs

@@ -0,0 +1,38 @@
+import { Outlet, ScrollRestoration, createRootRoute } from "@tanstack/react-router";
+import { Meta, Scripts } from "@tanstack/start";
+import { Providers } from "~/providers";
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "{{pascalCase name}}" },
+    ],
+    links: [{ rel: "stylesheet", href: "/styles.css" }],
+  }),
+  component: RootComponent,
+});
+
+function RootComponent() {
+  return (
+    <RootDocument>
+      <Outlet />
+    </RootDocument>
+  );
+}
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <Meta />
+      </head>
+      <body>
+        <Providers>{children}</Providers>
+        <ScrollRestoration />
+        <Scripts />
+      </body>
+    </html>
+  );
+}

package/templates/init/app/routes/index.tsx.hbs

@@ -0,0 +1,18 @@
+import { createFileRoute } from "@tanstack/react-router";
+
+export const Route = createFileRoute("/")({
+  component: Home,
+});
+
+function Home() {
+  return (
+    <div className="min-h-screen flex items-center justify-center">
+      <div className="text-center">
+        <h1 className="text-4xl font-bold mb-4">{{pascalCase name}}</h1>
+        <p className="text-gray-600">
+          Your TanStack Start + Convex app is ready.
+        </p>
+      </div>
+    </div>
+  );
+}

package/templates/init/app/ssr.tsx.hbs

@@ -0,0 +1,11 @@
+import {
+  createStartHandler,
+  defaultStreamHandler,
+} from "@tanstack/start/server";
+import { getRouterManifest } from "@tanstack/start/router-manifest";
+import { createRouter } from "./router";
+
+export default createStartHandler({
+  createRouter,
+  getRouterManifest,
+})(defaultStreamHandler);

package/templates/init/app.config.ts.hbs

@@ -0,0 +1,8 @@
+import { defineConfig } from "@tanstack/start/config";
+import viteTsConfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  vite: {
+    plugins: [viteTsConfigPaths()],
+  },
+});

package/templates/init/biome.json.hbs

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false,
+    "ignore": ["node_modules", "dist", ".vinxi", "convex/_generated"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2
+  },
+  "organizeImports": {
+    "enabled": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always"
+    }
+  }
+}

package/templates/init/claude.md.hbs

@@ -0,0 +1,93 @@
+# 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
+
+## Trigger Words → Action
+
+| User says | You run |
+|-----------|---------|
+| "add feature", "create feature", "build feature" | `forge add:feature <name>` |
+| "add X with Y" (any domain entity) | `forge add:feature <name>` |
+| "new page for X" | `forge add:feature <name>` |
+| "build X functionality" | `forge add:feature <name>` |
+
+## File Creation Rules
+
+DO NOT create these files manually:
+- `src/features/**/*` (forge creates the structure)
+- `convex/features/**/*` (forge creates the structure)
+- `app/routes/<feature>/**/*` (forge creates the structure)
+
+ONLY the forge CLI creates these. You fill them in after.
+
+## What You CAN Create Manually
+
+- Files inside existing feature component folders (after forge created them)
+- `src/components/*` (shared UI)
+- `src/lib/*` (utilities)
+- `src/hooks/*` (global hooks)
+
+## Workflow Example
+
+User: "Add a comments feature with replies"
+
+You MUST:
+```
+Run: forge add:feature comments
+Edit: convex/features/comments/schema.ts (add fields for comments + replies)
+Edit: convex/features/comments/queries.ts (add queries)
+Edit: convex/features/comments/mutations.ts (add mutations)
+Edit: src/features/comments/hooks.ts (add/modify hooks)
+Create: src/features/comments/components/CommentCard.tsx
+Create: src/features/comments/components/CommentList.tsx
+Create: src/features/comments/components/ReplyForm.tsx
+Update: src/features/comments/components/index.ts (add exports)
+Edit: app/routes/comments/index.tsx (wire up components)
+```
+
+## Validation
+
+Before finishing ANY task, run:
+```bash
+forge check
+```
+If it fails, fix ALL issues before responding to the user.
+
+## Project Structure
+
+```
+app/routes/         → Thin route files only (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
+```
+
+## Rules
+
+1. **Routes are thin**: Only import and render. No business logic. No hooks defined here.
+2. **No cross-feature imports**: `src/features/X` cannot import from `src/features/Y`
+3. **Hooks in hooks.ts**: All feature hooks in `src/features/<name>/hooks.ts`
+4. **Components in components/**: All feature components in `src/features/<name>/components/`
+5. **Mirror structure**: Every `src/features/X` has `convex/features/X`
+
+## Stack Quick Reference
+
+- **Data fetching**: Use hooks from `src/features/<name>/hooks.ts` (they wrap Convex)
+- **Mutations**: Use mutation hooks from `src/features/<name>/hooks.ts`
+- **UI primitives**: Import from `~/components/ui/*` (shadcn)
+- **Styling**: Tailwind classes only, no CSS files
+- **Forms**: react-hook-form + zod for validation
+
+## Commands Reference
+
+| Command | When to use |
+|---------|-------------|
+| `forge add:feature <name>` | BEFORE building any new feature |
+| `forge check` | BEFORE completing any task |

package/templates/init/convex/schema.ts.hbs

@@ -0,0 +1,7 @@
+import { defineSchema } from "convex/server";
+
+// Feature table imports will be added here by forge add:feature
+
+export default defineSchema({
+  // Feature tables will be spread here by forge add:feature
+});

package/templates/init/package.json.hbs

@@ -0,0 +1,34 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vinxi dev",
+    "build": "vinxi build",
+    "start": "vinxi start",
+    "lint": "biome check .",
+    "lint:fix": "biome check . --write",
+    "format": "biome format . --write"
+  },
+  "dependencies": {
+    "@tanstack/react-router": "^1.95.1",
+    "@tanstack/start": "^1.95.1",
+    "convex": "^1.17.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "vinxi": "^0.5.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^2.6.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.7.2",
+    "vite-tsconfig-paths": "^5.1.4"
+  }
+}

package/templates/init/postcss.config.js.hbs

@@ -0,0 +1,6 @@
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};

package/templates/init/src/lib/cn.ts.hbs

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/templates/init/src/providers/index.tsx.hbs

@@ -0,0 +1,10 @@
+import { ConvexProvider, ConvexReactClient } from "convex/react";
+import { useState } from "react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  const [convex] = useState(
+    () => new ConvexReactClient(import.meta.env.VITE_CONVEX_URL as string)
+  );
+
+  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
+}

package/templates/init/tailwind.config.ts.hbs

@@ -0,0 +1,12 @@
+import type { Config } from "tailwindcss";
+
+export default {
+  content: [
+    "./app/**/*.{js,ts,jsx,tsx}",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+} satisfies Config;

package/templates/init/tsconfig.json.hbs

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "paths": {
+      "~/*": ["./src/*"],
+      "@convex/*": ["./convex/*"]
+    }
+  },
+  "include": ["src", "app", "convex"]
+}