@cogito.ai/cli 0.3.1 → 0.3.2

package/README.md

@@ -0,0 +1,181 @@
+# AgentDock CLI
+
+**`@cogito.ai/cli`** — Scaffold production-ready AI coding agent projects for humans, CI pipelines, and AI agents.
+
+[![npm version](https://img.shields.io/npm/v/@cogito.ai/cli)](https://www.npmjs.com/package/@cogito.ai/cli)
+
+---
+
+## Quick Start
+
+```bash
+# Interactive mode (for humans)
+npx @cogito.ai/cli init
+
+# Headless mode (for CI / AI agents)
+npx @cogito.ai/cli init --name my-app --template web-nextjs --pm pnpm --json
+
+# Start MCP Stdio server (for AI agents via Model Context Protocol)
+npx @cogito.ai/cli mcp
+```
+
+## Installation
+
+```bash
+# Run without installing (recommended)
+npx @cogito.ai/cli <command>
+
+# Global install
+npm install -g @cogito.ai/cli
+pnpm add -g @cogito.ai/cli
+```
+
+---
+
+## Commands
+
+### `agentdock init`
+
+Scaffold a new project from a template. Auto-detects the environment:
+
+- **TTY** → interactive prompts (human mode)
+- **Non-TTY / `--silent` / `--json`** → headless execution (agent/CI mode)
+
+| Flag | Type | Default | Description |
+| ---- | ---- | ------- | ----------- |
+| `--name` | string | required | Project name and target directory name |
+| `--template` | string | required | Template ID (e.g. `web-nextjs`) |
+| `--pm` | string | `pnpm` | Package manager: `pnpm` / `npm` / `yarn` / `bun` |
+| `--dir` | string | `./<name>` | Target directory (absolute or relative to cwd) |
+| `--json` | boolean | `false` | Output NDJSON result to stdout |
+| `--silent` | boolean | `false` | Suppress all output |
+
+**JSON output (success):**
+```json
+{"ok":true,"targetDir":"/path/to/my-app","name":"my-app","template":"web-nextjs"}
+```
+
+**JSON output (failure):**
+```json
+{"ok":false,"error":"TARGET_DIR_EXISTS","message":"Directory already exists: /path/to/my-app"}
+```
+
+**Error codes:** `MISSING_ARG` · `TEMPLATE_NOT_FOUND` · `TARGET_DIR_EXISTS` · `CLI_VERSION_OUTDATED` · `SCAFFOLD_FAILED`
+
+---
+
+### `agentdock mcp`
+
+Start an MCP (Model Context Protocol) Stdio server. Exposes CLI capabilities as tools directly callable by AI agents.
+
+```bash
+agentdock mcp
+```
+
+**Available tools:**
+
+| Tool | Description |
+| ---- | ----------- |
+| `list_templates` | List all available project templates |
+| `scaffold_project` | Scaffold a project into a target directory |
+
+**VS Code Copilot MCP config (`.vscode/mcp.json`):**
+```json
+{
+  "servers": {
+    "agentdock": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@cogito.ai/cli", "mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Available Templates
+
+| Template ID | Description |
+| ----------- | ----------- |
+| `web-nextjs` | Next.js 16 + Supabase + next-intl + Tailwind CSS v4 + Vitest + Fumadocs — full-stack monorepo starter |
+
+---
+
+## Architecture
+
+The CLI uses an **Adapter pattern** — a single executor core serves three consumer surfaces:
+
+```
+agentdock init
+      │
+      ├── TTY detected ──→ Human Adapter  (Clack interactive UI)
+      └── Non-TTY / flags ──→ Agent Adapter (structured JSON output)
+
+agentdock mcp ──→ MCP Adapter (MCP Stdio Server)
+
+All adapters share the same Core Executor (scaffold + registry)
+```
+
+**Design principles:**
+
+1. **Headless-first** — the executor core has no TTY dependency; the human UI is a thin shell on top.
+2. **Structured output as protocol** — `--json` mode produces stable machine-parseable NDJSON, not natural language.
+3. **One capability, three surfaces** — `scaffold_project` is implemented once and projected to CLI flags, JSON mode, and MCP tool automatically.
+
+**Tech stack:**
+
+| Component | Role |
+| --------- | ---- |
+| [Bun](https://github.com/oven-sh/bun) | Build: single-file Node.js executable |
+| [Citty](https://github.com/unjs/citty) | Command modeling: sub-commands, flag schema, lazy loading |
+| [Clack](https://github.com/bombshell-dev/clack) | Human interaction: TTY prompts |
+| [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) | Agent protocol: MCP Stdio server |
+| [Changesets](https://github.com/changesets/changesets) | Release governance: semantic versioning + changelog |
+
+---
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Regenerate template registry
+pnpm --filter @cogito.ai/cli generate-registry
+
+# Run from source (no build needed)
+npx tsx packages/cli/bin/agentdock.ts init
+
+# Run tests
+pnpm --filter @cogito.ai/cli test
+
+# Build
+pnpm --filter @cogito.ai/cli build
+```
+
+### Adding a template
+
+1. Create `templates/<id>/` with a complete project structure.
+2. Add `package.json` with `"agentdock": { "minCliVersion": "x.y.z" }`.
+3. Run `pnpm --filter @cogito.ai/cli generate-registry`.
+4. Publish a new CLI version — templates are bundled inside the npm package.
+
+### Publishing a new version
+
+```bash
+pnpm changeset          # describe the change
+pnpm changeset version  # bump version + update CHANGELOG
+pnpm --filter @cogito.ai/cli build
+pnpm --filter @cogito.ai/cli publish
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+[中文文档 →](./README-zh.md)

package/dist/templates/web-nextjs/.env.example

@@ -20,3 +20,7 @@ SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>
 
 # Public URL of this app (used for OG image URLs, absolute redirects, etc.)
 NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# Default locale used for root redirects and i18n fallback
+# Allowed values: en, zh
+APP_DEFAULT_LOCALE=zh

package/dist/templates/web-nextjs/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "css.lint.unknownAtRules": "ignore"
+}

package/dist/templates/web-nextjs/README.md

@@ -71,7 +71,31 @@ Open `.env.local` and fill in your values:
 | `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard → Project Settings → API → service_role (server only) |
 | `NEXT_PUBLIC_APP_URL` | `http://localhost:3000` for local dev |
 
-### 4. Start development server
+### 4. Set up Supabase Auth (required for login / signup)
+
+**4a. Enable GitHub OAuth provider**
+
+1. Go to **Supabase Dashboard → Authentication → Providers → GitHub**.
+2. Toggle **Enable Sign in with GitHub** on.
+3. Create a GitHub OAuth App at [github.com/settings/developers](https://github.com/settings/developers):
+   - **Homepage URL**: `http://localhost:3000`
+   - **Authorization callback URL**: copy the **Callback URL (for OAuth)** shown in the Supabase GitHub provider dialog (e.g. `https://<project-ref>.supabase.co/auth/v1/callback`)
+4. Paste the GitHub **Client ID** and **Client Secret** back into the Supabase provider settings and click **Save**.
+
+**4b. Add redirect URL**
+
+1. Go to **Supabase Dashboard → Authentication → URL Configuration**.
+2. Under **Redirect URLs**, click **Add URL** and add:
+   - `http://localhost:3000/auth/callback` ← for local development
+   - `https://<your-production-domain>/auth/callback` ← for production
+3. Under **Site URL** set `http://localhost:3000` (or your production URL).
+
+**4c. (Optional) Email confirmation**
+
+By default Supabase requires email confirmation before a user can sign in.  
+To disable during development: **Authentication → Email → Enable email confirmations** → toggle off.
+
+### 5. Start development server
 
 ```bash
 pnpm dev

package/dist/templates/web-nextjs/apps/docs/.source/browser.ts

@@ -7,6 +7,6 @@ const create = browser<typeof Config, import("fumadocs-mdx/runtime/types").Inter
   }
 }>();
 const browserCollections = {
-  docs: create.doc("docs", {"index.mdx": () => import("../content/docs/index.mdx?collection=docs"), "changelog/index.mdx": () => import("../content/docs/changelog/index.mdx?collection=docs"), "features/hello.mdx": () => import("../content/docs/features/hello.mdx?collection=docs"), "roadmap/index.mdx": () => import("../content/docs/roadmap/index.mdx?collection=docs"), }),
+  docs: create.doc("docs", {"index.mdx": () => import("../content/docs/index.mdx?collection=docs"), "changelog/index.mdx": () => import("../content/docs/changelog/index.mdx?collection=docs"), "roadmap/index.mdx": () => import("../content/docs/roadmap/index.mdx?collection=docs"), "features/auth.mdx": () => import("../content/docs/features/auth.mdx?collection=docs"), "features/hello.mdx": () => import("../content/docs/features/hello.mdx?collection=docs"), }),
 };
 export default browserCollections;

package/dist/templates/web-nextjs/apps/docs/.source/server.ts

@@ -1,6 +1,7 @@
 // @ts-nocheck
-import * as __fd_glob_8 from "../content/docs/roadmap/index.mdx?collection=docs"
-import * as __fd_glob_7 from "../content/docs/features/hello.mdx?collection=docs"
+import * as __fd_glob_9 from "../content/docs/features/hello.mdx?collection=docs"
+import * as __fd_glob_8 from "../content/docs/features/auth.mdx?collection=docs"
+import * as __fd_glob_7 from "../content/docs/roadmap/index.mdx?collection=docs"
 import * as __fd_glob_6 from "../content/docs/changelog/index.mdx?collection=docs"
 import * as __fd_glob_5 from "../content/docs/index.mdx?collection=docs"
 import { default as __fd_glob_4 } from "../content/docs/roadmap/meta.json?collection=docs"
@@ -16,4 +17,4 @@ const create = server<typeof Config, import("fumadocs-mdx/runtime/types").Intern
   }
 }>({"doc":{"passthroughs":["extractedReferences"]}});
 
-export const docs = await create.docs("docs", "content/docs", {"meta.json": __fd_glob_0, "changelog/meta.json": __fd_glob_1, "decisions/meta.json": __fd_glob_2, "features/meta.json": __fd_glob_3, "roadmap/meta.json": __fd_glob_4, }, {"index.mdx": __fd_glob_5, "changelog/index.mdx": __fd_glob_6, "features/hello.mdx": __fd_glob_7, "roadmap/index.mdx": __fd_glob_8, });
+export const docs = await create.docs("docs", "content/docs", {"meta.json": __fd_glob_0, "changelog/meta.json": __fd_glob_1, "decisions/meta.json": __fd_glob_2, "features/meta.json": __fd_glob_3, "roadmap/meta.json": __fd_glob_4, }, {"index.mdx": __fd_glob_5, "changelog/index.mdx": __fd_glob_6, "roadmap/index.mdx": __fd_glob_7, "features/auth.mdx": __fd_glob_8, "features/hello.mdx": __fd_glob_9, });

package/dist/templates/web-nextjs/apps/docs/content/docs/features/auth.mdx

@@ -0,0 +1,139 @@
+---
+title: Authentication (auth)
+description: Email/password and GitHub OAuth authentication using Supabase Auth, implemented following the four-layer contract.
+---
+
+## Overview
+
+The `auth` feature provides full authentication using **Supabase Auth**:
+
+- Email + password sign-in and sign-up (with email verification)
+- GitHub OAuth sign-in
+- Session management via `@supabase/ssr` (httpOnly cookies, auto-refresh)
+- Route protection via `(protected)` route group + server-side session check
+
+UI components: **shadcn/ui** blocks (`login-03`, `signup-03`, `dashboard-01`)  
+Forms: **react-hook-form + zod** (all multi-field forms use this pattern)
+
+---
+
+## Architecture: Four-Layer Contract
+
+```
+core/types/auth.ts              ← Domain types (AuthUser, AuthResult, ActionResult)
+core/repositories/IAuthRepository.ts  ← Interface (no Supabase types)
+infra/db/SupabaseAuthRepository.ts    ← Implementation (Supabase SDK)
+infra/providers.ts              ← DI factory: getAuthRepository()
+features/auth/__contract__.ts   ← Public API types
+features/auth/actions.ts        ← Server Actions ('use server')
+features/auth/index.ts          ← Barrel export
+```
+
+### Why the interface layer?
+
+`IAuthRepository` decouples features from the Supabase SDK. To swap to Auth.js:
+1. Implement `IAuthRepository` with Auth.js
+2. Update `infra/providers.ts` to return the new implementation
+3. `features/auth/actions.ts` is unchanged — zero feature churn
+
+---
+
+## Server Actions
+
+Import from the feature barrel:
+
+```ts
+import { signIn, signUp, signOut, signInWithGithub } from '@/features/auth'
+```
+
+| Action | Returns | Side effect |
+|--------|---------|------------|
+| `signIn(prevState, formData)` | `ActionResult` | Redirects to `/${locale}/dashboard` on success |
+| `signUp(prevState, formData)` | `ActionResult<{ success: true; email: string }>` | No redirect — waits for email verification |
+| `signOut()` | `void` | Clears session, redirects to `/${locale}/login` |
+| `signInWithGithub()` | `ActionResult<{ url: string }>` | Returns OAuth URL — caller does `router.push(url)` |
+
+All actions use `useActionState` on the client side:
+
+```tsx
+const [state, formAction, isPending] = useActionState(signIn, null)
+```
+
+---
+
+## Route Structure
+
+```
+src/app/
+  [locale]/
+    (auth)/                  ← Unauthenticated pages (no layout)
+      login/page.tsx
+      signup/page.tsx
+    (protected)/             ← Authenticated pages
+      layout.tsx             ← Server: checks session, redirects to /login if missing
+      dashboard/page.tsx
+  auth/
+    callback/route.ts        ← OAuth + email verification callback (no locale prefix)
+```
+
+### Why no locale prefix on `/auth/callback`?
+
+Supabase callbacks must be registered with a fixed URL. Using `/auth/callback` (without `[locale]`)
+avoids registering multiple locale variants in the Supabase dashboard.
+After a successful callback, the app redirects to `/en/dashboard` (default locale).
+
+---
+
+## Route Protection
+
+Protection happens at the **layout level** (server-side), not middleware-only:
+
+```ts
+// (protected)/layout.tsx
+const { data: { user } } = await supabase.auth.getUser()
+if (!user) redirect(`/${locale}/login`)
+```
+
+`getUser()` is used (not `getSession()`) because it validates the JWT server-side,
+preventing forged tokens.
+
+Middleware additionally:
+1. Refreshes the Supabase session token on every request
+2. Redirects authenticated users away from `/(auth)` pages to `/dashboard`
+
+---
+
+## Zod Schemas
+
+Defined in `src/lib/validations/auth.ts` — shared between Server Actions and UI:
+
+```ts
+import { signInSchema, signUpSchema } from '@/lib/validations/auth'
+```
+
+| Schema | Fields | Rules |
+|--------|--------|-------|
+| `signInSchema` | `email`, `password` | email format, min 8 chars |
+| `signUpSchema` | `email`, `password`, `confirmPassword` | above + passwords match |
+
+---
+
+## Setup Requirements
+
+Before auth works, configure Supabase:
+
+1. **GitHub OAuth** — Supabase Dashboard → Authentication → Providers → GitHub
+2. **Redirect URL** — Supabase Dashboard → Authentication → URL Configuration → add `http://localhost:3000/auth/callback`
+
+See the template `README.md` for the full step-by-step guide.
+
+---
+
+## Non-Goals
+
+This feature intentionally excludes:
+- Password reset / forgot password
+- User profile / avatar / account settings
+- Role-based access control (RBAC)
+- Magic link / OTP / phone login
+- Custom email templates

package/dist/templates/web-nextjs/apps/web/components.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "base-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.ts",
+    "css": "src/app/[locale]/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": false,
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "registries": {}
+}

package/dist/templates/web-nextjs/apps/web/messages/en.json

@@ -6,5 +6,33 @@
   "hello": {
     "title": "Hello Feature",
     "greeting": "Hello, {name}!"
+  },
+  "auth": {
+    "loginTitle": "Welcome back",
+    "loginSubtitle": "Sign in to your account",
+    "signupTitle": "Create an account",
+    "signupSubtitle": "Enter your details to get started",
+    "emailLabel": "Email",
+    "emailPlaceholder": "you@example.com",
+    "emailHelperText": "Use a real email address — you'll need to verify it after sign up.",
+    "passwordLabel": "Password",
+    "passwordPlaceholder": "••••••••",
+    "confirmPasswordLabel": "Confirm password",
+    "confirmPasswordPlaceholder": "••••••••",
+    "signInButton": "Sign in",
+    "signUpButton": "Create account",
+    "signOutButton": "Sign out",
+    "githubButton": "Sign in with GitHub",
+    "noAccountText": "Don't have an account?",
+    "signUpLink": "Sign up",
+    "hasAccountText": "Already have an account?",
+    "signInLink": "Sign in",
+    "orContinueWith": "Or continue with",
+    "verifyEmailTitle": "Check your email",
+    "verifyEmailMessage": "We sent a verification link to {email}. Click the link to complete your sign up.",
+    "dashboardTitle": "Dashboard",
+    "dashboardWelcome": "Welcome, {email}",
+    "errorInvalidCredentials": "Invalid email or password.",
+    "errorGeneric": "Something went wrong. Please try again."
   }
 }

package/dist/templates/web-nextjs/apps/web/messages/zh.json

@@ -6,5 +6,33 @@
   "hello": {
     "title": "hello.title",
     "greeting": "hello.greeting"
+  },
+  "auth": {
+    "loginTitle": "auth.loginTitle",
+    "loginSubtitle": "auth.loginSubtitle",
+    "signupTitle": "auth.signupTitle",
+    "signupSubtitle": "auth.signupSubtitle",
+    "emailLabel": "auth.emailLabel",
+    "emailPlaceholder": "auth.emailPlaceholder",
+    "emailHelperText": "auth.emailHelperText",
+    "passwordLabel": "auth.passwordLabel",
+    "passwordPlaceholder": "auth.passwordPlaceholder",
+    "confirmPasswordLabel": "auth.confirmPasswordLabel",
+    "confirmPasswordPlaceholder": "auth.confirmPasswordPlaceholder",
+    "signInButton": "auth.signInButton",
+    "signUpButton": "auth.signUpButton",
+    "signOutButton": "auth.signOutButton",
+    "githubButton": "auth.githubButton",
+    "noAccountText": "auth.noAccountText",
+    "signUpLink": "auth.signUpLink",
+    "hasAccountText": "auth.hasAccountText",
+    "signInLink": "auth.signInLink",
+    "orContinueWith": "auth.orContinueWith",
+    "verifyEmailTitle": "auth.verifyEmailTitle",
+    "verifyEmailMessage": "auth.verifyEmailMessage",
+    "dashboardTitle": "auth.dashboardTitle",
+    "dashboardWelcome": "auth.dashboardWelcome",
+    "errorInvalidCredentials": "auth.errorInvalidCredentials",
+    "errorGeneric": "auth.errorGeneric"
   }
 }

package/dist/templates/web-nextjs/apps/web/middleware.ts

@@ -1,23 +1,67 @@
 import createMiddleware from 'next-intl/middleware'
 import { defineRouting } from 'next-intl/routing'
 import { NextResponse, type NextRequest } from 'next/server'
+import { createMiddlewareClient } from '@/infra/db/client'
+import { defaultLocale, isLocale, locales } from '@/i18n/config'
 
 export const routing = defineRouting({
-  locales: ['en', 'zh'],
-  defaultLocale: 'en',
+  locales,
+  defaultLocale,
 })
 
 const handleI18nRouting = createMiddleware(routing)
 
-export default function middleware(request: NextRequest) {
-  const segments = request.nextUrl.pathname.split('/').filter(Boolean)
+function copyCookies(from: NextResponse, to: NextResponse) {
+  for (const cookie of from.cookies.getAll()) {
+    to.cookies.set(cookie)
+  }
+}
+
+export default async function middleware(request: NextRequest) {
+  const pathname = request.nextUrl.pathname
+
+  if (pathname === '/') {
+    const url = request.nextUrl.clone()
+    url.pathname = `/${defaultLocale}`
+    return NextResponse.redirect(url)
+  }
+
+  // Skip Supabase session refresh for the auth callback route
+  // (it's handled by the route handler itself)
+  if (pathname.startsWith('/auth/')) {
+    return NextResponse.next()
+  }
+
+  // 1. Let next-intl build the final response first.
+  // Supabase cookie refresh should write into this response to avoid cookie loss.
+  const response = handleI18nRouting(request)
+
+  // 2. Refresh the Supabase session (keeps token alive, writes updated cookie)
+  const { supabase } = createMiddlewareClient(request, response)
+  const {
+    data: { user },
+  } = await supabase.auth.getUser()
+
+  // 3. Redirect authenticated users away from auth pages (/(auth)/ routes)
+  const authPagePattern = /^\/[a-z]{2}\/(login|signup)(\/|$)/
+  if (user && authPagePattern.test(pathname)) {
+    const localeSegment = pathname.split('/')[1] ?? defaultLocale
+    const locale = isLocale(localeSegment) ? localeSegment : defaultLocale
+    const url = request.nextUrl.clone()
+    url.pathname = `/${locale}/dashboard`
+    const redirectResponse = NextResponse.redirect(url)
+    copyCookies(response, redirectResponse)
+    return redirectResponse
+  }
+
+  // 4. Normalize unknown locale-like prefixes: /fr/hello -> /en/hello
+  const segments = pathname.split('/').filter(Boolean)
   const firstSegment = segments[0]
 
   if (firstSegment !== undefined) {
     const isLocaleLike = /^[a-z]{2}(?:-[A-Z]{2})?$/.test(firstSegment)
-    const isSupportedLocale = routing.locales.includes(firstSegment as 'en' | 'zh')
+    const isSupportedLocale = isLocale(firstSegment)
 
-    // Normalize unknown locale-like prefixes: /fr/hello -> /en/hello.
     if (isLocaleLike && !isSupportedLocale) {
       const url = request.nextUrl.clone()
       url.pathname = `/${routing.defaultLocale}/${segments.slice(1).join('/')}`.replace(/\/$/, '')
@@ -25,10 +69,10 @@ export default function middleware(request: NextRequest) {
     }
   }
 
-  return handleI18nRouting(request)
+  return response
 }
 
 export const config = {
-  // Match all pathnames except Next.js internals and static files.
-  matcher: ['/((?!_next|_vercel|.*\\..*).*)'],
+  // Match all pathnames except Next.js internals, static files, and auth callback.
+  matcher: ['/((?!_next|_vercel|auth/callback|.*\\..*).*)'],
 }

package/dist/templates/web-nextjs/apps/web/package.json

@@ -11,11 +11,23 @@
     "check-types": "tsc --noEmit"
   },
   "dependencies": {
+    "@base-ui/react": "^1.5.0",
+    "@hookform/resolvers": "^5.4.0",
     "@supabase/ssr": "^0.10.3",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.17.0",
     "next": "16",
     "next-intl": "^4.13.0",
+    "next-themes": "^0.4.6",
     "react": "19",
-    "react-dom": "19"
+    "react-dom": "19",
+    "react-hook-form": "^7.77.0",
+    "shadcn": "^4.10.0",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.6.0",
+    "tw-animate-css": "^1.4.0",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@cogito.ai/eslint-config": "workspace:*",