ai-forge-cli 0.1.0

package/dist/chunk-J4V5PGVT.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+// src/utils/logger.ts
+import { consola } from "consola";
+import pc from "picocolors";
+var logger = {
+  success(msg) {
+    consola.log(`  ${pc.green("\u2713")} ${msg}`);
+  },
+  error(msg) {
+    consola.log(`  ${pc.red("\u2717")} ${msg}`);
+  },
+  warn(msg) {
+    consola.log(`  ${pc.yellow("!")} ${msg}`);
+  },
+  info(msg) {
+    consola.log(`  ${pc.blue("\u2192")} ${msg}`);
+  },
+  log(msg) {
+    consola.log(msg);
+  },
+  blank() {
+    consola.log("");
+  }
+};
+
+// src/utils/fs.ts
+import { mkdir, readFile as fsReadFile, writeFile as fsWriteFile, access } from "fs/promises";
+import { dirname } from "path";
+async function ensureDir(path) {
+  await mkdir(path, { recursive: true });
+}
+async function fileExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function writeFile(path, content) {
+  await ensureDir(dirname(path));
+  await fsWriteFile(path, content, "utf-8");
+}
+async function readFile(path) {
+  return fsReadFile(path, "utf-8");
+}
+
+export {
+  logger,
+  ensureDir,
+  fileExists,
+  writeFile,
+  readFile
+};

package/dist/chunk-PIFX2L5H.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+// src/utils/case.ts
+function camelCase(str) {
+  return str.replace(/[-_\s]+(.)?/g, (_, c) => c ? c.toUpperCase() : "").replace(/^[A-Z]/, (c) => c.toLowerCase());
+}
+function pascalCase(str) {
+  const camel = camelCase(str);
+  return camel.charAt(0).toUpperCase() + camel.slice(1);
+}
+function kebabCase(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
+}
+
+// src/utils/template.ts
+import Handlebars from "handlebars";
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+Handlebars.registerHelper("camelCase", (str) => camelCase(str));
+Handlebars.registerHelper("pascalCase", (str) => pascalCase(str));
+Handlebars.registerHelper("kebabCase", (str) => kebabCase(str));
+function getTemplatesDir() {
+  const devPath = join(__dirname2, "../../templates");
+  if (existsSync(devPath)) return devPath;
+  const prodPath = join(__dirname2, "../templates");
+  if (existsSync(prodPath)) return prodPath;
+  throw new Error("Templates directory not found");
+}
+function renderTemplate(templatePath, data) {
+  const templatesDir = getTemplatesDir();
+  const fullPath = join(templatesDir, templatePath);
+  if (!existsSync(fullPath)) {
+    throw new Error(`Template not found: ${fullPath}`);
+  }
+  const templateContent = readFileSync(fullPath, "utf-8");
+  const template = Handlebars.compile(templateContent);
+  return template(data);
+}
+
+export {
+  camelCase,
+  kebabCase,
+  renderTemplate
+};

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { defineCommand, runMain } from "citty";
+var main = defineCommand({
+  meta: {
+    name: "forge",
+    version: "0.1.0",
+    description: "TypeScript stack scaffolding & enforcement CLI"
+  },
+  subCommands: {
+    init: () => import("./init-GQA3WDXQ.js").then((m) => m.default),
+    "add:feature": () => import("./add-feature-YXWSRIVE.js").then((m) => m.default),
+    check: () => import("./check-RCJRXIU5.js").then((m) => m.default)
+  }
+});
+runMain(main);

package/dist/init-GQA3WDXQ.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+import {
+  kebabCase,
+  renderTemplate
+} from "./chunk-PIFX2L5H.js";
+import {
+  ensureDir,
+  fileExists,
+  logger,
+  writeFile
+} from "./chunk-J4V5PGVT.js";
+
+// src/commands/init.ts
+import { defineCommand } from "citty";
+import { join } from "path";
+import pc from "picocolors";
+var init_default = defineCommand({
+  meta: {
+    name: "init",
+    description: "Create a new project with TanStack Start + Convex + Tailwind"
+  },
+  args: {
+    name: {
+      type: "positional",
+      description: "Name of the project",
+      required: true
+    }
+  },
+  async run({ args }) {
+    const rawName = args.name;
+    const name = kebabCase(rawName);
+    const cwd = process.cwd();
+    const projectDir = join(cwd, name);
+    if (await fileExists(projectDir)) {
+      logger.error(`Directory "${name}" already exists`);
+      process.exit(1);
+    }
+    logger.blank();
+    logger.log(`  Creating project "${name}"...`);
+    logger.blank();
+    const templateData = { name };
+    const files = [
+      // Root config files
+      { templatePath: "init/package.json.hbs", destPath: join(projectDir, "package.json") },
+      { templatePath: "init/tsconfig.json.hbs", destPath: join(projectDir, "tsconfig.json") },
+      { templatePath: "init/biome.json.hbs", destPath: join(projectDir, "biome.json") },
+      { templatePath: "init/tailwind.config.ts.hbs", destPath: join(projectDir, "tailwind.config.ts") },
+      { templatePath: "init/postcss.config.js.hbs", destPath: join(projectDir, "postcss.config.js") },
+      { templatePath: "init/app.config.ts.hbs", destPath: join(projectDir, "app.config.ts") },
+      // App files
+      { templatePath: "init/app/client.tsx.hbs", destPath: join(projectDir, "app/client.tsx") },
+      { templatePath: "init/app/ssr.tsx.hbs", destPath: join(projectDir, "app/ssr.tsx") },
+      { templatePath: "init/app/router.tsx.hbs", destPath: join(projectDir, "app/router.tsx") },
+      { templatePath: "init/app/routes/__root.tsx.hbs", destPath: join(projectDir, "app/routes/__root.tsx") },
+      { templatePath: "init/app/routes/index.tsx.hbs", destPath: join(projectDir, "app/routes/index.tsx") },
+      // Src files
+      { templatePath: "init/src/lib/cn.ts.hbs", destPath: join(projectDir, "src/lib/cn.ts") },
+      { templatePath: "init/src/providers/index.tsx.hbs", destPath: join(projectDir, "src/providers/index.tsx") },
+      // Convex files
+      { templatePath: "init/convex/schema.ts.hbs", destPath: join(projectDir, "convex/schema.ts") },
+      // CLAUDE.md - THE HOOK
+      { templatePath: "init/claude.md.hbs", destPath: join(projectDir, "CLAUDE.md") }
+    ];
+    for (const file of files) {
+      const content = renderTemplate(file.templatePath, templateData);
+      await writeFile(file.destPath, content);
+      const relativePath = file.destPath.replace(projectDir + "/", "");
+      logger.success(`Created ${relativePath}`);
+    }
+    const emptyDirs = [
+      join(projectDir, "src/components/ui"),
+      join(projectDir, "src/features"),
+      join(projectDir, "src/hooks"),
+      join(projectDir, "convex/features")
+    ];
+    for (const dir of emptyDirs) {
+      await ensureDir(dir);
+      await writeFile(join(dir, ".gitkeep"), "");
+    }
+    const globalCss = `@tailwind base;
+@tailwind components;
+@tailwind utilities;
+`;
+    await writeFile(join(projectDir, "src/styles.css"), globalCss);
+    logger.success("Created src/styles.css");
+    const gitignore = `node_modules
+dist
+.vinxi
+.env
+.env.local
+`;
+    await writeFile(join(projectDir, ".gitignore"), gitignore);
+    logger.success("Created .gitignore");
+    const envExample = `VITE_CONVEX_URL=
+`;
+    await writeFile(join(projectDir, ".env.example"), envExample);
+    logger.success("Created .env.example");
+    logger.blank();
+    logger.log(`  ${pc.green("Project created successfully!")}`);
+    logger.blank();
+    logger.log("  Next steps:");
+    logger.log(`    1. ${pc.cyan(`cd ${name}`)}`);
+    logger.log(`    2. ${pc.cyan("pnpm install")}`);
+    logger.log(`    3. ${pc.cyan("npx convex init")}`);
+    logger.log(`    4. ${pc.cyan("pnpm dlx shadcn@latest init")}`);
+    logger.log(`    5. ${pc.cyan("pnpm dev")}`);
+    logger.blank();
+    logger.log(`  ${pc.dim("CLAUDE.md is configured. Claude Code will use forge CLI automatically.")}`);
+    logger.blank();
+  }
+});
+export {
+  init_default as default
+};

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/templates/feature/src/index.ts.hbs

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

package/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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/dist/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
+});