@webjskit/cli 0.1.0 → 0.1.2

package/README.md

@@ -7,20 +7,25 @@ Installing this package gives you the `webjs` command.
 
 ## Install
 
-Most users won't install globally. Scaffold a new app instead:
+Install once, globally:
 
 ```sh
-npx @webjskit/cli create my-app
-cd my-app
-npm install
-npm run dev
+npm i -g @webjskit/cli
 ```
 
-Or globally:
+Then scaffold a new app anywhere:
 
 ```sh
-npm install -g @webjskit/cli
 webjs create my-app
+cd my-app && npm install && npm run dev
+# → http://localhost:3000
+```
+
+One-shot without global install:
+
+```sh
+npx @webjskit/cli create my-app
+cd my-app && npm install && npm run dev
 ```
 
 ## Commands

package/lib/create.js

@@ -42,6 +42,7 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     'modules',
     'lib',
     'public',
+    'prisma',
     'test/unit',
     'test/e2e',
   ];
@@ -55,6 +56,8 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     type: 'module',
     private: true,
     scripts: {
+      predev: 'prisma generate',
+      prestart: 'prisma migrate deploy',
       dev: 'webjs dev',
       build: 'webjs build',
       start: 'webjs start',
@@ -62,19 +65,22 @@ export async function scaffoldApp(name, cwd, opts = {}) {
       'test:server': 'webjs test --server',
       'test:browser': 'webjs test --browser',
       check: 'webjs check',
+      'db:migrate': 'prisma migrate dev',
+      'db:generate': 'prisma generate',
+      'db:studio': 'prisma studio',
     },
     dependencies: {
+      '@prisma/client': '^6.0.0',
       '@webjskit/cli': 'latest',
       '@webjskit/core': 'latest',
       '@webjskit/server': 'latest',
-      ...(isSaas ? { '@prisma/client': '^6.0.0' } : {}),
     },
     devDependencies: {
       esbuild: '^0.28.0',
+      prisma: '^6.0.0',
       '@web/test-runner': '^0.20.0',
       '@web/test-runner-playwright': '^0.11.0',
       'playwright': '^1.59.0',
-      ...(isSaas ? { prisma: '^6.0.0' } : {}),
     },
   }, null, 2) + '\n');
 
@@ -95,9 +101,10 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     },
   }, null, 2) + '\n');
 
-  // --- Templates (CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
+  // --- Templates (AGENTS.md, CONVENTIONS.md, CLAUDE.md, test files, Claude hooks) ---
 
   const templateFiles = [
+    'AGENTS.md',
     'CONVENTIONS.md',
     'CLAUDE.md',
     'test/unit/example.test.ts',
@@ -139,6 +146,64 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   const preCommitPath = join(appDir, '.hooks', 'pre-commit');
   if (existsSync(preCommitPath)) await chmod(preCommitPath, 0o755);
 
+  // --- Prisma schema + client singleton (all templates) ---
+
+  await writeFile(join(appDir, 'prisma', 'schema.prisma'), `generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  // Defaults to SQLite at ./prisma/dev.db. Switch to postgresql / mysql
+  // by changing the provider + DATABASE_URL in .env.
+  provider = "sqlite"
+  url      = env("DATABASE_URL")
+}
+
+// Example model — feel free to delete or extend.
+model User {
+  id        Int      @id @default(autoincrement())
+  email     String   @unique
+  name      String?
+  createdAt DateTime @default(now())
+}
+`);
+
+  await writeFile(join(appDir, 'lib', 'prisma.ts'), `/**
+ * Prisma client singleton. The \`globalThis\` trick keeps a single
+ * instance across dev-server module reloads, so we don't open a new
+ * DB connection on every file change.
+ */
+import { PrismaClient } from '@prisma/client';
+
+const g = globalThis as unknown as { __prisma?: PrismaClient };
+
+export const prisma = g.__prisma ?? new PrismaClient();
+if (process.env.NODE_ENV !== 'production') g.__prisma = prisma;
+`);
+
+  // Env vars: append DATABASE_URL to the .env.example the template
+  // already copied (if present). The scaffold's root .env.example
+  // lists auth secrets etc.; we just add the DB line idempotently.
+  const envExample = join(appDir, '.env.example');
+  if (existsSync(envExample)) {
+    const cur = await readFile(envExample, 'utf8');
+    if (!cur.includes('DATABASE_URL')) {
+      await writeFile(envExample, cur.replace(/\n?$/, '\n') + '\nDATABASE_URL=file:./prisma/dev.db\n');
+    }
+  } else {
+    await writeFile(envExample, 'DATABASE_URL=file:./prisma/dev.db\n');
+  }
+
+  // .gitignore the generated SQLite file.
+  const gitignore = join(appDir, '.gitignore');
+  const gitignoreExtra = '\n# SQLite dev database\nprisma/dev.db\nprisma/dev.db-journal\n';
+  if (existsSync(gitignore)) {
+    const cur = await readFile(gitignore, 'utf8');
+    if (!cur.includes('prisma/dev.db')) await writeFile(gitignore, cur + gitignoreExtra);
+  } else {
+    await writeFile(gitignore, 'node_modules\n.webjs\n' + gitignoreExtra);
+  }
+
   // --- App files (template-specific) ---
 
   if (isApi) {
@@ -386,12 +451,8 @@ export default function Home() {
 }
 `);
 
-  // --- AGENTS.md (copy from framework root) ---
-
-  const agentsSrc = resolve(__dirname, '..', '..', '..', 'AGENTS.md');
-  if (existsSync(agentsSrc)) {
-    await cp(agentsSrc, join(appDir, 'AGENTS.md'));
-  }
+  // AGENTS.md is copied via the `templateFiles` loop above, from
+  // `packages/cli/templates/AGENTS.md` with `{{APP_NAME}}` substitution.
 
   // --- Theme toggle component ---
 
@@ -437,18 +498,26 @@ export class ThemeToggle extends WebComponent {
   }
 
   render() {
+    const t = this.state.theme;
+    const label = t === 'system' ? 'AUTO' : t === 'light' ? 'LIGHT' : 'DARK';
+    const icon = t === 'light' ? ICONS.sun : t === 'dark' ? ICONS.moon : ICONS.system;
     return html\`
       <button
-        class="inline-flex items-center px-3 py-1.5 rounded-full border border-border bg-bg-elev text-fg-muted font-mono text-[11px] leading-none tracking-wider uppercase duration-fast hover:text-fg hover:border-border-strong"
+        class="inline-flex items-center justify-center w-9 h-9 p-0 border border-border rounded-full bg-bg-elev text-fg-muted cursor-pointer transition-all duration-150 hover:text-fg hover:border-border-strong active:scale-[0.94] focus-visible:outline-none focus-visible:border-accent focus-visible:ring-[3px] focus-visible:ring-accent-tint"
         @click=\${() => this.cycle()}
-      >
-        \${this.state.theme === 'system' ? 'Auto'
-          : this.state.theme === 'light' ? 'Light' : 'Dark'}
-      </button>
+        aria-label="Cycle theme (currently \${label})"
+        title="Theme: \${label.toLowerCase()}"
+      >\${icon}</button>
     \`;
   }
 }
 
+const ICONS = {
+  sun: html\`<svg class="w-4 h-4 stroke-current fill-none" style="stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round" viewBox="0 0 24 24"><circle cx="12" cy="12" r="4"/><path d="M12 3v2M12 19v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M3 12h2M19 12h2M4.93 19.07l1.41-1.41M17.66 6.34l1.41-1.41"/></svg>\`,
+  moon: html\`<svg class="w-4 h-4 stroke-current fill-none" style="stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round" viewBox="0 0 24 24"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8Z"/></svg>\`,
+  system: html\`<svg class="w-4 h-4 stroke-current fill-none" style="stroke-width:1.8;stroke-linecap:round;stroke-linejoin:round" viewBox="0 0 24 24"><path d="M3 5h18v11H3zM8 20h8M12 16v4"/></svg>\`,
+};
+
 ThemeToggle.register('theme-toggle');
 `);
   } // end if (!isApi)
@@ -459,11 +528,8 @@ ThemeToggle.register('theme-toggle');
     await writeSaasFiles(appDir);
   }
 
-  // --- AGENTS.md (always copy) ---
-  const agentsSrc2 = resolve(__dirname, '..', '..', '..', 'AGENTS.md');
-  if (!existsSync(join(appDir, 'AGENTS.md')) && existsSync(agentsSrc2)) {
-    await cp(agentsSrc2, join(appDir, 'AGENTS.md'));
-  }
+  // AGENTS.md is already in place via the shared `templateFiles` loop
+  // earlier in this function — no framework-root fallback needed.
 
   // --- Git init + configure hooks directory ---
   const { execSync } = await import('node:child_process');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjskit/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "type": "module",
   "description": "webjs CLI — dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -0,0 +1,195 @@
+# AGENTS.md — {{APP_NAME}}
+
+Read this before editing any file. This is a webjs app: AI-first, web-
+components-first, no build step. The framework's own full API reference
+lives at https://github.com/vivek7405/webjs/blob/main/AGENTS.md — treat
+this file as the app-scoped companion.
+
+## Framework source is in `node_modules/`
+
+No build step, no bundler, no minification — what you read is what
+runs. When in doubt, grep the framework:
+
+```
+node_modules/@webjskit/
+  core/            renderer, WebComponent, directives, client router,
+                    Task, context, testing helpers
+    src/component.js          ← lifecycle, properties, light vs shadow DOM
+    src/render-client.js      ← client-side DOM patching + hydration
+    src/render-server.js      ← renderToString / renderToStream
+    src/router-client.js      ← Turbo-Drive-style client navigation
+    src/directives.js         ← unsafeHTML, live
+    src/context.js            ← Context Protocol
+    src/task.js               ← async data with states
+  server/          dev + prod server, SSR, file router, actions,
+                    auth, sessions, cache, rate-limit, WebSocket
+    src/ssr.js                ← how metadata becomes <head> tags
+    src/router.js             ← file convention → route table
+    src/actions.js            ← .server.ts scanner, RPC, expose()
+    src/auth.js, session.js, cache.js, rate-limit.js, csrf.js
+  cli/             webjs CLI (dev / start / build / test / check / create / db)
+  ts-plugin/       tsserver go-to-definition for custom-element tag names
+```
+
+Reaching straight for the source is the fastest way to resolve "why
+doesn't X work?" — no documentation guesswork, no stale blog posts.
+
+## File conventions
+
+```
+app/                     thin route adapters — import from modules/
+  page.ts                → /
+  layout.ts              root layout, wraps every page
+  error.ts               error boundary (render failures → user-friendly)
+  loading.ts             Suspense fallback for sibling page
+  not-found.ts           custom 404 page
+  middleware.ts          global request middleware
+  [slug]/page.ts         dynamic route segment
+  [...rest]/page.ts      catch-all
+  (group)/               route group (parens not in URL)
+  _private/              underscore = not routable
+  api/
+    <path>/route.ts      GET / POST / PUT / DELETE / WS handlers
+  sitemap.ts             metadata route → /sitemap.xml
+  robots.ts              metadata route → /robots.txt
+  opengraph-image.ts     metadata route → /opengraph-image
+components/              web components — extend WebComponent, call .register()
+modules/<feature>/
+  actions/*.server.ts    server actions (one function per file)
+  queries/*.server.ts    data reads (one function per file)
+  components/*.ts        feature-scoped components
+  utils/*.ts             feature-scoped helpers
+  types.ts               feature types
+lib/
+  prisma.ts              PrismaClient singleton (import from here, never `new PrismaClient()`)
+  ...                    other cross-cutting infra (session, auth config, etc.)
+prisma/
+  schema.prisma          Prisma schema — SQLite by default, switch provider for Postgres/MySQL
+  dev.db                 SQLite file (gitignored); run `npm run db:migrate` to create
+  migrations/            generated migration SQL
+public/                  static assets, served at /public/*
+test/unit/*.test.ts      unit tests (node --test)
+test/browser/*.test.ts   browser tests (web-test-runner)
+middleware.ts            root middleware (optional, outermost)
+```
+
+## Database (Prisma + SQLite by default)
+
+Every scaffold includes a Prisma setup pointed at a local SQLite file.
+First-run workflow:
+
+```sh
+cp .env.example .env          # DATABASE_URL is pre-filled for SQLite
+npm run db:migrate            # creates prisma/dev.db + migration
+npm run dev                   # webjs dev + prisma generate via predev
+```
+
+Scripts:
+
+- `npm run db:migrate` — `prisma migrate dev` (dev-time schema changes + migration + generate)
+- `npm run db:generate` — `prisma generate` (regenerate client only)
+- `npm run db:studio` — `prisma studio` (GUI)
+- `predev` hook auto-runs `prisma generate` before `npm run dev`
+- `prestart` hook runs `prisma migrate deploy` before `npm start` (idempotent in prod)
+
+Always import the client from `lib/prisma.ts` (never `new PrismaClient()` directly —
+the singleton avoids opening a new connection on every dev-server reload):
+
+```ts
+import { prisma } from '../../../lib/prisma.ts';
+const users = await prisma.user.findMany();
+```
+
+To switch to Postgres or MySQL: change `provider` in `prisma/schema.prisma`
+and the `DATABASE_URL` in `.env`.
+
+## Imports
+
+```ts
+import { html, css, WebComponent } from '@webjskit/core';
+import '@webjskit/core/client-router';              // enable SPA nav
+import { unsafeHTML, live } from '@webjskit/core/directives';
+import { createContext } from '@webjskit/core/context';
+import { Task } from '@webjskit/core/task';
+import { fixture, waitForUpdate } from '@webjskit/core/testing';
+
+import { rateLimit, cache, createAuth, Credentials, Session } from '@webjskit/server';
+```
+
+## Component pattern
+
+```ts
+import { WebComponent, html, css } from '@webjskit/core';
+
+export class Counter extends WebComponent {
+  static tag = 'my-counter';       // required, must contain a hyphen
+  static properties = { count: { type: Number } };
+  static styles = css`button { padding: 8px 12px; }`;
+  // static shadow = true;          // opt into shadow DOM (default: light DOM)
+  // static lazy = true;             // download JS only when scrolled into view
+
+  render() {
+    return html`
+      <button @click=${() => this.setState({ count: this.count + 1 })}>
+        ${this.count}
+      </button>
+    `;
+  }
+}
+Counter.register('my-counter');
+```
+
+## Server action pattern
+
+```ts
+// modules/posts/actions/create-post.server.ts
+'use server';
+import { prisma } from '../../../lib/prisma.ts';
+
+export async function createPost(input: { title: string; body: string }) {
+  if (!input.title) return { success: false, error: 'title required', status: 400 };
+  const post = await prisma.post.create({ data: input });
+  return { success: true, data: post };
+}
+```
+
+Import it from a client component — the framework rewrites it into a
+type-safe RPC stub automatically.
+
+## Metadata (per-page)
+
+```ts
+export const metadata = {
+  title: 'My page',
+  description: 'A page in {{APP_NAME}}',
+  openGraph: { type: 'website', image: 'https://...' },
+  twitter: { card: 'summary_large_image' },
+  cacheControl: 'public, max-age=60',  // opt into caching (default: no-store)
+};
+```
+
+Use `generateMetadata(ctx)` when you need request-scoped values (e.g.
+absolute URLs from `ctx.url`).
+
+## Invariants (do not violate)
+
+1. Custom element tags must contain a hyphen. Set `static tag`, call `.register()`.
+2. Never import `@prisma/client` or `node:*` from client-reachable files —
+   only from `.server.ts` modules or `lib/*.ts`.
+3. Event / property / boolean holes in `` html`` `` are unquoted:
+   `@click=${fn}`, not `@click="${fn}"`.
+4. Use `setState()` — never mutate `this.state` directly.
+5. Pages / layouts / metadata routes default-export a server-only function.
+6. One exported function per action / query file. Name the file after it.
+
+## Workflow expectations for AI agents
+
+1. Branch before editing — never push to `main` directly.
+2. Every code change comes with: unit test(s), AGENTS.md / docs updates if
+   the feature surface changed, `npx webjs check` passing.
+3. Commit and push after each logical unit. No AI attribution trailers.
+4. When unsure how a framework feature works, `grep` or `cat` the
+   relevant `node_modules/@webjskit/*/src/` file before asking the user.
+
+Project-specific conventions and overrides live in
+[CONVENTIONS.md](./CONVENTIONS.md).

package/templates/CONVENTIONS.md

@@ -82,14 +82,19 @@ variables control infrastructure — no config files needed:
 
 | Environment variable | Effect |
 |---|---|
-| `REDIS_URL` | Cache, sessions, rate limiting, and pub/sub all use Redis |
+| `REDIS_URL` | Connection string consumed by `redisStore({ url: process.env.REDIS_URL })`. Not auto-wired — call `setStore(redisStore())` once at app startup to put cache / sessions / rate-limit on Redis. |
 | `AUTH_SECRET` | Required for auth JWT signing (32+ random chars) |
 | `AUTH_GOOGLE_ID` | Google OAuth client ID (optional) |
 | `AUTH_GITHUB_ID` | GitHub OAuth client ID (optional) |
 | `PORT` | Server port (default: 3000) |
 
 **Development:** zero env vars needed. Everything works with memory/cookie/disk.
-**Production:** set `REDIS_URL` + `SESSION_SECRET`. That's it.
+**Production:** set `AUTH_SECRET` + `SESSION_SECRET`. For horizontal scaling, also set `REDIS_URL` and add one line at app startup:
+
+```js
+import { setStore, redisStore } from '@webjskit/server';
+setStore(redisStore({ url: process.env.REDIS_URL }));
+```
 
 ---