Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,76 @@

Instructions for AI coding agents working with this codebase.

## Development Workflow

### Build & Lint

- **Package Manager:** Use `bun` for all operations. Do not use `npm`, `yarn`, or `pnpm`.
- **Install Dependencies:** `bun install`
- **Build:** `bun run build` (uses TurboRepo)
- **Lint & Format:** `bun check` (runs `oxfmt` and `oxlint`). Fix issues with `oxfmt .` if needed.
- **Dev Server:** `bun run dev`

### Testing

- **Runner:** Use `bun test`.
- **Run All Tests:** `bun test` (in a specific package/app directory).
- **Run Single Test File:** `bun test <path/to/file>`
- Example: `bun test apps/cli/test/cli.test.ts`
- **Run Specific Test Case:** `bun test -t "test name pattern"`
- **Note:** Always run `bun run build` before testing if testing build artifacts, or ensure the test command handles it (e.g., `apps/cli` runs build in its test script).

## Code Style & Conventions

### General

- **Runtime:** This is a **Bun** project.
- Use `Bun.file` over `node:fs`.
- Use `Bun.serve` over `express`.
- Use `Bun.env` or just `process.env` (auto-loaded).
- **Paradigm:** Prefer **Functional Programming**. Avoid Object-Oriented patterns (classes) unless strictly required by a framework.
- Use standard `function name() {}` declarations for top-level functions (better stack traces/hoisting) instead of arrow functions `const name = () => {}`, unless inside components/callbacks.
- **Types:** Use **Type Aliases** (`type X = ...`) instead of interfaces (`interface X ...`).
- **Formatting:** Adhere to `oxfmt` defaults.
- **Comments:** No emojis in code or comments.
- **Exports:** Prefer named exports over default exports.

### Apps & Packages

- **Monorepo:** Uses TurboRepo.
- **CLI:** Located in `apps/cli`.
- **Web:** Located in `apps/web`.
- **Backend:** Located in `packages/backend` (Convex).

## Framework Specifics

### Convex (Backend)

- **Syntax:** Always use the new object-style syntax for functions.
```ts
export const myFunc = query({
args: { name: v.string() },
returns: v.string(), // Always specify returns
handler: async (ctx, args) => { ... }
});
```
- **Validators:** Strict validation required.
- Use `v.null()` for void/null returns.
- Use `v.id("tableName")` for IDs.
- **Internal vs Public:**
- Public: `query`, `mutation`, `action` (in `convex/` root or subfolders).
- Internal: `internalQuery`, `internalMutation`, `internalAction`.
- **Calling Functions:**
- Use `ctx.runQuery(api.path.to.func, args)`.
- Use `internal.path.to.func` for internal functions.
- **Schema:** Defined in `convex/schema.ts` using `defineSchema` and `defineTable`.
- **Actions:** Use `"use node";` at the top if using Node.js built-ins. Actions do not have DB access (`ctx.db`); use queries/mutations for data.

### Handlebars (Templates)

- Avoid generic `if/else`. Use explicit helpers: `{{#if (eq orm "prisma")}}`.
- Escape double braces if needed: `\{{`.

<!-- opensrc:start -->

## Source Code Reference
Expand Down
1 change: 1 addition & 0 deletions apps/cli/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,7 @@
"@orpc/server": "^1.13.4",
"better-result": "^2.3.0",
"consola": "^3.4.2",
"env-paths": "^4.0.0",
"execa": "^9.6.1",
"fs-extra": "^11.3.3",
"gradient-string": "^3.0.0",
Expand Down
1 change: 1 addition & 0 deletions apps/cli/src/constants.ts
Original file line number Diff line number Diff line change
Expand Up @@ -60,5 +60,6 @@ export const ADDON_COMPATIBILITY = {
fumadocs: [],
opentui: [],
wxt: [],
skills: [],
none: [],
} as const;
5 changes: 5 additions & 0 deletions apps/cli/src/helpers/addons/addons-setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import { UserCancelledError } from "../../utils/errors";
import { setupFumadocs } from "./fumadocs-setup";
import { setupOxlint } from "./oxlint-setup";
import { setupRuler } from "./ruler-setup";
import { setupSkills } from "./skills-setup";
import { setupStarlight } from "./starlight-setup";
import { setupTauri } from "./tauri-setup";
import { setupTui } from "./tui-setup";
Expand Down Expand Up @@ -109,6 +110,10 @@ export async function setupAddons(config: ProjectConfig) {
if (addons.includes("ruler")) {
await runSetup(() => setupRuler(config));
}

if (addons.includes("skills")) {
await runSetup(() => setupSkills(config));
}
}

export async function setupBiome(projectDir: string) {
Expand Down
30 changes: 28 additions & 2 deletions apps/cli/src/helpers/addons/fumadocs-setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,17 +11,24 @@ import { getPackageExecutionArgs } from "../../utils/package-runner";

type FumadocsTemplate =
| "next-mdx"
| "next-mdx-static"
| "waku"
| "react-router"
| "react-router-spa"
| "tanstack-start";
| "tanstack-start"
| "tanstack-start-spa";

const TEMPLATES = {
"next-mdx": {
label: "Next.js: Fumadocs MDX",
hint: "Recommended template with MDX support",
value: "+next+fuma-docs-mdx",
},
"next-mdx-static": {
label: "Next.js: Fumadocs MDX (Static)",
hint: "Static export template with MDX support",
value: "+next+fuma-docs-mdx+static",
},
waku: {
label: "Waku: Content Collections",
hint: "Template using Waku with content collections",
Expand All @@ -42,6 +49,11 @@ const TEMPLATES = {
hint: "Template for Tanstack Start with MDX remote",
value: "tanstack-start",
},
"tanstack-start-spa": {
label: "Tanstack Start: SPA",
hint: "Template for Tanstack Start SPA",
value: "tanstack-start-spa",
},
} as const;

export async function setupFumadocs(
Expand All @@ -66,8 +78,22 @@ export async function setupFumadocs(
}

const templateArg = TEMPLATES[template].value;
const isNextTemplate = template.startsWith("next-");

// Build command with options
const options: string[] = [`--template ${templateArg}`, `--pm ${packageManager}`, "--no-git"];

// Add --src only for Next.js templates
if (isNextTemplate) {
options.push("--src");
}

// Use biome if the addon is enabled
if (config.addons.includes("biome")) {
options.push("--linter biome");
}

const commandWithArgs = `create-fumadocs-app@latest fumadocs --template ${templateArg} --src --pm ${packageManager} --no-git`;
const commandWithArgs = `create-fumadocs-app@latest fumadocs ${options.join(" ")}`;
const args = getPackageExecutionArgs(packageManager, commandWithArgs);

const appsDir = path.join(projectDir, "apps");
Expand Down
2 changes: 2 additions & 0 deletions apps/cli/src/helpers/addons/ruler-setup.ts
Original file line number Diff line number Diff line change
Expand Up @@ -41,6 +41,7 @@ export async function setupRuler(
copilot: { label: "GitHub Copilot" },
crush: { label: "Crush" },
cursor: { label: "Cursor" },
factory: { label: "Factory" },
firebase: { label: "Firebase Studio" },
firebender: { label: "Firebender" },
"gemini-cli": { label: "Gemini CLI" },
Expand All @@ -52,6 +53,7 @@ export async function setupRuler(
mistral: { label: "Mistral" },
opencode: { label: "OpenCode" },
openhands: { label: "Open Hands" },
pi: { label: "Pi" },
qwen: { label: "Qwen" },
roo: { label: "RooCode" },
trae: { label: "Trae AI" },
Expand Down
Loading