@webjsdev/cli 0.8.1

package/lib/saas-template.js

@@ -0,0 +1,397 @@
+/**
+ * SaaS template files for `webjs create --template saas`.
+ * Extracted to avoid nested template literal escaping issues.
+ */
+
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const UI_REGISTRY_ROOT = resolve(
+  __dirname, '..', '..', 'ui', 'packages', 'registry',
+);
+
+/**
+ * Read a registry component and rewrite its `'../lib/utils.ts'` import for
+ * the scaffolded app's `components/ui/<name>.ts` layout (two-up to lib/).
+ * Mirrors the helper in `create.js`, kept private here to avoid coupling.
+ */
+async function readUiComponent(name) {
+  const src = join(UI_REGISTRY_ROOT, 'components', `${name}.ts`);
+  if (!existsSync(src)) return null;
+  const raw = await readFile(src, 'utf8');
+  return raw
+    .replaceAll("'../lib/utils.ts'", "'../../lib/utils.ts'")
+    .replaceAll('"../lib/utils.ts"', '"../../lib/utils.ts"');
+}
+
+/** Copy named registry components into `<appDir>/components/ui/`. */
+async function copyUiComponents(appDir, names) {
+  const uiDir = join(appDir, 'components', 'ui');
+  await mkdir(uiDir, { recursive: true });
+  for (const n of names) {
+    const content = await readUiComponent(n);
+    if (content == null) continue;
+    await writeFile(join(uiDir, `${n}.ts`), content);
+  }
+}
+
+/**
+ * @param {string} appDir
+ */
+export async function writeSaasFiles(appDir) {
+  // SaaS pages use auth forms, so copy the extra ui-* components on top of
+  // the standard set the full-stack scaffold already wrote. Pre-importing
+  // them in login/signup/dashboard pages below means the dev server will
+  // SSR these elements with full styling on first paint.
+  // `form` and `field` are deferred to v2 (see packages/ui/AGENTS.md) -
+  // the saas auth pages use raw <form> + label/input class helpers instead.
+  await copyUiComponents(appDir, ['dialog', 'switch', 'checkbox']);
+
+  // lib/prisma.server.ts
+  await mkdir(join(appDir, 'lib'), { recursive: true });
+  await writeFile(join(appDir, 'lib', 'prisma.server.ts'), [
+    "import { PrismaClient } from '@prisma/client';",
+    "",
+    "const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };",
+    "export const prisma = globalForPrisma.prisma || new PrismaClient();",
+    "if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;",
+    "",
+  ].join('\n'));
+
+  // lib/password.server.ts
+  await writeFile(join(appDir, 'lib', 'password.server.ts'), [
+    "import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';",
+    "import { promisify } from 'node:util';",
+    "",
+    "const scryptAsync = promisify(scrypt);",
+    "",
+    "export async function hash(password: string): Promise<string> {",
+    "  const salt = randomBytes(16).toString('hex');",
+    "  const buf = (await scryptAsync(password, salt, 64)) as Buffer;",
+    "  return salt + ':' + buf.toString('hex');",
+    "}",
+    "",
+    "export async function compare(password: string, stored: string): Promise<boolean> {",
+    "  const [salt, key] = stored.split(':');",
+    "  const buf = (await scryptAsync(password, salt, 64)) as Buffer;",
+    "  return timingSafeEqual(buf, Buffer.from(key, 'hex'));",
+    "}",
+    "",
+  ].join('\n'));
+
+  // lib/auth.server.ts
+  await writeFile(join(appDir, 'lib', 'auth.server.ts'), [
+    "import { createAuth, Credentials } from '@webjsdev/server';",
+    "import { prisma } from './prisma.server.ts';",
+    "import { compare } from './password.server.ts';",
+    "",
+    "export const { auth, signIn, signOut, handlers } = createAuth({",
+    "  providers: [",
+    "    Credentials({",
+    "      async authorize(credentials: { email: string; password: string }) {",
+    "        const user = await prisma.user.findUnique({ where: { email: credentials.email } });",
+    "        if (!user || !await compare(credentials.password, user.passwordHash)) return null;",
+    "        return { id: String(user.id), name: user.name, email: user.email };",
+    "      },",
+    "    }),",
+    "  ],",
+    "  secret: process.env.AUTH_SECRET,",
+    "});",
+    "",
+  ].join('\n'));
+
+  // prisma/schema.prisma
+  await mkdir(join(appDir, 'prisma'), { recursive: true });
+  await writeFile(join(appDir, 'prisma', 'schema.prisma'), [
+    'datasource db {',
+    '  provider = "sqlite"',
+    '  url      = env("DATABASE_URL")',
+    '}',
+    '',
+    'generator client {',
+    '  provider = "prisma-client-js"',
+    '}',
+    '',
+    'model User {',
+    '  id           Int      @id @default(autoincrement())',
+    '  email        String   @unique',
+    '  name         String?',
+    '  passwordHash String',
+    '  createdAt    DateTime @default(now())',
+    '}',
+    '',
+  ].join('\n'));
+
+  // modules/auth/actions/signup.server.ts
+  await mkdir(join(appDir, 'modules', 'auth', 'actions'), { recursive: true });
+  await mkdir(join(appDir, 'modules', 'auth', 'queries'), { recursive: true });
+
+  await writeFile(join(appDir, 'modules', 'auth', 'actions', 'signup.server.ts'), [
+    "'use server';",
+    "",
+    "import { prisma } from '../../../lib/prisma.server.ts';",
+    "import { hash } from '../../../lib/password.server.ts';",
+    "",
+    "export async function signup(input: { name: string; email: string; password: string }) {",
+    "  const exists = await prisma.user.findUnique({ where: { email: input.email } });",
+    "  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };",
+    "  const user = await prisma.user.create({",
+    "    data: { name: input.name, email: input.email, passwordHash: await hash(input.password) },",
+    "  });",
+    "  return { success: true as const, data: { id: user.id, name: user.name, email: user.email } };",
+    "}",
+    "",
+  ].join('\n'));
+
+  // modules/auth/queries/current-user.server.ts
+  await writeFile(join(appDir, 'modules', 'auth', 'queries', 'current-user.server.ts'), [
+    "'use server';",
+    "",
+    "import { auth } from '../../../lib/auth.server.ts';",
+    "",
+    "export async function currentUser() {",
+    "  const session = await auth();",
+    "  return session?.user ?? null;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // modules/auth/types.ts
+  await writeFile(join(appDir, 'modules', 'auth', 'types.ts'), [
+    "export interface User {",
+    "  id: number;",
+    "  name: string | null;",
+    "  email: string;",
+    "}",
+    "",
+    "export type ActionResult<T> =",
+    "  | { success: true; data: T }",
+    "  | { success: false; error: string; status: number };",
+    "",
+  ].join('\n'));
+
+  // test/unit/auth.test.ts: minimal stub so the scaffold passes
+  // `webjs check` (tests-exist) and `webjs test` runs cleanly out of the
+  // box. The signup/current-user functions import from lib/prisma.server.ts
+  // and lib/auth.server.ts, both of which need `prisma generate` to have run before
+  // they can be imported, so we deliberately test only the runtime-
+  // dependency-free types.ts here. Replace with real tests once Prisma
+  // is set up (run `npm install && npx prisma migrate dev --name init`).
+  await writeFile(join(appDir, 'test', 'unit', 'auth.test.ts'), [
+    "import { test } from 'node:test';",
+    "import assert from 'node:assert/strict';",
+    "",
+    "import type { User, ActionResult } from '../../modules/auth/types.ts';",
+    "",
+    "test('User shape: id is numeric, email is required', () => {",
+    "  const u: User = { id: 1, name: 'Test', email: 'test@example.com' };",
+    "  assert.equal(typeof u.id, 'number');",
+    "  assert.equal(typeof u.email, 'string');",
+    "});",
+    "",
+    "test('ActionResult: success envelope carries data', () => {",
+    "  const r: ActionResult<User> = {",
+    "    success: true,",
+    "    data: { id: 1, name: 'Test', email: 'test@example.com' },",
+    "  };",
+    "  assert.equal(r.success, true);",
+    "  if (r.success) assert.equal(r.data.email, 'test@example.com');",
+    "});",
+    "",
+    "test('ActionResult: failure envelope carries error + status', () => {",
+    "  const r: ActionResult<User> = {",
+    "    success: false,",
+    "    error: 'Email already registered',",
+    "    status: 409,",
+    "  };",
+    "  assert.equal(r.success, false);",
+    "  if (!r.success) {",
+    "    assert.equal(r.status, 409);",
+    "    assert.ok(r.error.length > 0);",
+    "  }",
+    "});",
+    "",
+    "// TODO: once you've run `npm install && npx prisma migrate dev` you can",
+    "// import { signup } from '../../modules/auth/actions/signup.server.ts'",
+    "// and { currentUser } from '../../modules/auth/queries/current-user.server.ts'",
+    "// and write real integration tests against a test SQLite DB.",
+    "",
+  ].join('\n'));
+
+  // app/api/auth/[...path]/route.ts
+  await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'api', 'auth', '[...path]', 'route.ts'), [
+    "import { handlers } from '../../../../../lib/auth.server.ts';",
+    "export const GET = handlers.GET;",
+    "export const POST = handlers.POST;",
+    "",
+  ].join('\n'));
+
+  // app/login/page.ts
+  await mkdir(join(appDir, 'app', 'login'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'login', 'page.ts'), [
+    "import { html } from '@webjsdev/core';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { inputClass } from '../../components/ui/input.ts';",
+    "import { labelClass } from '../../components/ui/label.ts';",
+    "",
+    "export const metadata = { title: 'Login' };",
+    "",
+    "export default function LoginPage() {",
+    "  return html`",
+    "    <div class=\"max-w-sm mx-auto mt-12\">",
+    "      <div class=${cardClass()}>",
+    "        <div class=${cardHeaderClass()}>",
+    "          <h3 class=${cardTitleClass()}>Sign in</h3>",
+    "          <p class=${cardDescriptionClass()}>Welcome back: log in to continue.</p>",
+    "        </div>",
+    "        <div class=${cardContentClass()}>",
+    "          <form method=\"POST\" action=\"/api/auth/callback/credentials\" class=\"flex flex-col gap-4\">",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"email\">Email</label>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"password\">Password</label>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "            </div>",
+    "            <button class=${buttonClass()} type=\"submit\">Sign in</button>",
+    "          </form>",
+    "        </div>",
+    "        <div class=${cardFooterClass()}>",
+    "          <p class=\"text-sm text-muted-foreground\">Don't have an account? <a href=\"/signup\" class=\"underline\">Sign up</a></p>",
+    "        </div>",
+    "      </div>",
+    "    </div>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/signup/page.ts
+  await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
+    "import { html } from '@webjsdev/core';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass, cardFooterClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { inputClass } from '../../components/ui/input.ts';",
+    "import { labelClass } from '../../components/ui/label.ts';",
+    "",
+    "export const metadata = { title: 'Sign up' };",
+    "",
+    "export default function SignupPage() {",
+    "  return html`",
+    "    <div class=\"max-w-sm mx-auto mt-12\">",
+    "      <div class=${cardClass()}>",
+    "        <div class=${cardHeaderClass()}>",
+    "          <h3 class=${cardTitleClass()}>Create an account</h3>",
+    "          <p class=${cardDescriptionClass()}>Get started with your new workspace.</p>",
+    "        </div>",
+    "        <div class=${cardContentClass()}>",
+    "          <form id=\"signup-form\" class=\"flex flex-col gap-4\">",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"name\">Name</label>",
+    "              <input class=${inputClass()} id=\"name\" name=\"name\" type=\"text\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"email\">Email</label>",
+    "              <input class=${inputClass()} id=\"email\" name=\"email\" type=\"email\" required>",
+    "            </div>",
+    "            <div class=\"flex flex-col gap-1.5\">",
+    "              <label class=${labelClass()} for=\"password\">Password</label>",
+    "              <input class=${inputClass()} id=\"password\" name=\"password\" type=\"password\" required>",
+    "            </div>",
+    "            <button class=${buttonClass()} type=\"submit\">Create account</button>",
+    "          </form>",
+    "        </div>",
+    "        <div class=${cardFooterClass()}>",
+    "          <p class=\"text-sm text-muted-foreground\">Already have an account? <a href=\"/login\" class=\"underline\">Log in</a></p>",
+    "        </div>",
+    "      </div>",
+    "    </div>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/middleware.ts
+  await mkdir(join(appDir, 'app', 'dashboard', 'settings'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'dashboard', 'middleware.ts'), [
+    "import { auth } from '../../lib/auth.server.ts';",
+    "",
+    "export default async function requireAuth(req: Request, next: () => Promise<Response>) {",
+    "  const session = await auth();",
+    "  if (!session?.user) {",
+    "    return new Response(null, { status: 302, headers: { location: '/login' } });",
+    "  }",
+    "  return next();",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/page.ts
+  await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
+    "import { html } from '@webjsdev/core';",
+    "import { currentUser } from '../../modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../components/ui/card.ts';",
+    "import { buttonClass } from '../../components/ui/button.ts';",
+    "import { badgeClass } from '../../components/ui/badge.ts';",
+    "",
+    "export const metadata = { title: 'Dashboard' };",
+    "",
+    "export default async function Dashboard() {",
+    "  const user = await currentUser();",
+    "  return html`",
+    "    <div class=\"flex items-center justify-between mb-6\">",
+    "      <h1 class=\"text-2xl font-semibold\">Dashboard</h1>",
+    "      <span class=${badgeClass({ variant: 'secondary' })}>Signed in</span>",
+    "    </div>",
+    "    <div class=${cardClass()}>",
+    "      <div class=${cardHeaderClass()}>",
+    "        <h3 class=${cardTitleClass()}>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</h3>",
+    "        <p class=${cardDescriptionClass()}>You're authenticated. Replace this scaffold with your real app.</p>",
+    "      </div>",
+    "      <div class=${cardContentClass()}>",
+    "        <a class=${buttonClass({ variant: 'outline' })} href=\"/dashboard/settings\">Settings</a>",
+    "      </div>",
+    "    </div>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/settings/page.ts
+  await writeFile(join(appDir, 'app', 'dashboard', 'settings', 'page.ts'), [
+    "import { html } from '@webjsdev/core';",
+    "import { currentUser } from '../../../modules/auth/queries/current-user.server.ts';",
+    "import { cardClass, cardHeaderClass, cardTitleClass, cardDescriptionClass, cardContentClass } from '../../../components/ui/card.ts';",
+    "",
+    "export const metadata = { title: 'Settings' };",
+    "",
+    "export default async function Settings() {",
+    "  const user = await currentUser();",
+    "  return html`",
+    "    <h1 class=\"text-2xl font-semibold mb-6\">Settings</h1>",
+    "    <div class=${cardClass()}>",
+    "      <div class=${cardHeaderClass()}>",
+    "        <h3 class=${cardTitleClass()}>Account</h3>",
+    "        <p class=${cardDescriptionClass()}>Your basic profile information.</p>",
+    "      </div>",
+    "      <div class=${cardContentClass()}>",
+    "        <dl class=\"grid grid-cols-[max-content_1fr] gap-x-6 gap-y-2 text-sm\">",
+    "          <dt class=\"text-muted-foreground\">Email</dt>",
+    "          <dd>${`\\$\\{user?.email\\}`}</dd>",
+    "          <dt class=\"text-muted-foreground\">Name</dt>",
+    "          <dd>${`\\$\\{user?.name || 'Not set'\\}`}</dd>",
+    "        </dl>",
+    "      </div>",
+    "    </div>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@webjsdev/cli",
+  "version": "0.8.1",
+  "type": "module",
+  "description": "webjs CLI - dev, start, create, db",
+  "bin": {
+    "webjs": "bin/webjs.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md"
+  ],
+  "dependencies": {
+    "@webjsdev/server": "^0.7.2",
+    "@webjsdev/ui": "^0.3.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivek7405/webjs.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/vivek7405/webjs#readme",
+  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "license": "MIT",
+  "keywords": [
+    "webjs",
+    "cli",
+    "dev",
+    "scaffold"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  }
+}

package/templates/.claude/hooks/block-prose-punctuation.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+#
+# PreToolUse hook: block prose-punctuation patterns the webjs convention bans.
+#
+# Catches four classes of new content in tool calls:
+#
+#   1. U+2014 em-dash, anywhere.
+#   2. Space-hyphen-space " - " in PROSE contexts (comment lines, markdown
+#      lines, headings, blockquotes). Math expressions in code like
+#      `Math.abs(a - b)` or `arr.length - 1` are NOT flagged.
+#   3. Space-semicolon-space " ; " in PROSE contexts. JS / CSS statement
+#      terminators (`;\n`) are NOT flagged.
+#   4. Code-shaped left-hand side immediately followed by a colon and prose:
+#        - `<code>foo()</code>:` (markdown code-LHS in docs)
+#        - `<my-tag>:` (custom-element tag with hyphen)
+#        - Inline comment `// foo(): description`
+#
+# Why this exists: see AGENTS.md "Invariants", item 10. These patterns
+# confuse AI agents that try to parse the prose as TypeScript / shorthand-
+# method / object-literal syntax, and trip humans reading API docs.
+#
+# Covers two tool-call paths:
+#   * Write / Edit / MultiEdit / NotebookEdit. The hook inspects the NEW
+#     content fields of the tool payload. Existing glyphs in old_string
+#     are not flagged: you can still Edit a line that contains one to
+#     remove it.
+#   * Bash. The hook inspects the command string, which catches commit
+#     messages (`git commit -m "..."`), heredocs, echo / printf, and any
+#     other prose typed at the shell.
+
+set -euo pipefail
+
+payload=$(cat)
+
+# Pull every field where prose might land. `// empty` keeps missing
+# fields silent; `[]?` keeps array iteration safe when absent.
+new_content=$(printf '%s' "$payload" | jq -r '
+  (.tool_input.content // empty),
+  (.tool_input.new_string // empty),
+  (.tool_input.new_source // empty),
+  (.tool_input.command // empty),
+  (.tool_input.edits[]?.new_string // empty)
+' 2>/dev/null || true)
+
+if [ -z "$new_content" ]; then
+  exit 0
+fi
+
+# --- 1. U+2014 em-dash --------------------------------------------------
+if printf '%s' "$new_content" | grep -q $'\xe2\x80\x94'; then
+  cat >&2 <<'EOF'
+BLOCKED: em-dash (U+2014) detected in this tool call.
+
+webjs bans em-dashes repo-wide. Replace every U+2014 character with
+a period, comma, colon (on a plain-noun LHS), parentheses, or
+restructured sentence. Do NOT replace it with " - " or " ; " or a
+trailing colon on code: those are also banned. See rule 2 / 3 / 4
+below for the alternatives.
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+# --- 2. Pause-hyphen " - " in PROSE contexts ----------------------------
+# Only flag lines whose context is clearly prose:
+#   - Markdown lines starting with `#`, `>`, `*`, plain text outside code
+#     fences (heuristic: line has no `=`, `{`, or `(...)` math)
+#   - JSDoc / block comment lines starting with `*`
+#   - Single-line comments starting with `//`
+#
+# Math expressions like `Math.abs(a - b)` or `arr.length - 1` are NOT
+# flagged because they appear in code lines (not comments) with code
+# context. The hook trades some false negatives in prose for zero false
+# positives in code-heavy diffs.
+
+block_pause_hyphen=0
+
+# Comment-line " - " pause: line starts with `//` or ` *` (JSDoc/block) or
+# `*` (markdown bold-start would have a letter after, distinguishable),
+# followed by prose with `\w+ - \w+` pattern. Specifically: catch lines
+# like `// foo - bar`, ` * foo - bar`, `* foo - bar`.
+if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+  block_pause_hyphen=1
+fi
+
+# Markdown heading " - " pause: line starts with `#` followed by prose
+# and ` - ` pattern.
+if printf '%s\n' "$new_content" | grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+  block_pause_hyphen=1
+fi
+
+# Markdown blockquote " - " pause: line starts with `>` followed by prose
+# and ` - ` pattern. (Single `>` blockquote, not table.)
+if printf '%s\n' "$new_content" | grep -qE '^>[[:space:]].*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+  block_pause_hyphen=1
+fi
+
+# HTML / markdown <p>, <li>, <td> body " - " pause: line contains a
+# closing HTML tag from a prose context, then prose-style ` - `.
+if printf '%s\n' "$new_content" | grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)>][[:space:]]-[[:space:]][A-Za-z`(<]'; then
+  block_pause_hyphen=1
+fi
+
+if [ "$block_pause_hyphen" = "1" ]; then
+  cat >&2 <<'EOF'
+BLOCKED: pause-hyphen " - " detected in a prose context.
+
+webjs bans plain hyphens used as pause-punctuation in prose. Rewrite
+the sentence with a period, comma, colon (on a plain-noun LHS), or
+restructured phrasing.
+
+  Bad:  // Foo - bar
+  Good: // Foo, with bar
+  Good: // Foo. Bar.
+
+  Bad:  <li>Foo - bar.</li>
+  Good: <li>Foo, with bar.</li>
+
+Plain hyphens are still fine in compound words (`AI-first`), CLI
+flags (`--http2`), filenames, ranges, and math expressions in code
+(`arr.length - 1`, `Math.abs(a - b)`). The hook only flags the
+` < word > - < word > ` pause-pattern in prose contexts (comments,
+markdown headings, blockquotes, HTML prose tags).
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+# --- 3. Pause-semicolon " ; " in PROSE contexts -------------------------
+# Same prose-context guard as #2.
+block_pause_semicolon=0
+
+if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+  block_pause_semicolon=1
+fi
+
+if printf '%s\n' "$new_content" | grep -qE '^#{1,6}[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+  block_pause_semicolon=1
+fi
+
+if printf '%s\n' "$new_content" | grep -qE '^>[[:space:]].*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+  block_pause_semicolon=1
+fi
+
+if printf '%s\n' "$new_content" | grep -qE '<(p|li|td|h[1-6]|strong|em|blockquote)[^>]*>[^<]*[A-Za-z`)][[:space:]];[[:space:]][A-Za-z`(]'; then
+  block_pause_semicolon=1
+fi
+
+if [ "$block_pause_semicolon" = "1" ]; then
+  cat >&2 <<'EOF'
+BLOCKED: pause-semicolon " ; " detected in a prose context.
+
+webjs bans semicolons used as pause-punctuation in prose. Rewrite as
+two sentences (period) or with a conjunction (", and", ", but", ", so").
+
+  Bad:  // Forms work ; links work too.
+  Good: // Forms work. Links work too.
+  Good: // Forms work, and links work too.
+
+Semicolons stay fine inside code (JS statement terminators, CSS
+declarations) since those are not flagged.
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+# --- 4a. <code>foo()</code>: prose ---------------------------------------
+# Markdown / HTML definition list with code-call followed by colon and
+# lowercase prose. The `)</code>:` shape is unambiguous: this is markdown,
+# not code, AND the inner code ends in `()` so the colon visually parses
+# as a return-type annotation.
+if printf '%s' "$new_content" | grep -qE '\)</code>:[[:space:]][a-z]'; then
+  cat >&2 <<'EOF'
+BLOCKED: code-LHS colon-then-prose detected ("<code>foo()</code>: ...").
+
+webjs bans `<code>foo()</code>: <prose>` because the colon visually
+parses as a TypeScript return-type annotation. Rewrite verb-led.
+
+  Bad:  <code>repeat()</code>: keyed list directive
+  Good: <code>repeat()</code> is the keyed list directive
+  Good: <code>startServer()</code> creates an HTTP(S) server
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+# --- 4b. Custom-element-tag <my-tag>: prose ------------------------------
+# HTML reserves hyphenated tag names for custom elements (W3C spec), so
+# `<x-y>:` is unambiguous prose, never JSX / TS / CSS.
+if printf '%s' "$new_content" | grep -qE '<[a-z][a-z0-9]*(-[a-z0-9]+)+([[:space:]][^>]*)?>:[[:space:]][a-z]'; then
+  cat >&2 <<'EOF'
+BLOCKED: custom-element-tag colon-then-prose detected ("<my-tag>: ...").
+
+webjs bans `<my-tag>: <prose>` in comments and docs. Rewrite verb-led.
+
+  Bad:  // <ui-dialog>: owns open state, focus trap, escape, scroll lock.
+  Good: // <ui-dialog> owns open state, focus trap, escape, scroll lock.
+  Bad:  // <ui-dialog-content>: the centered panel.
+  Good: // <ui-dialog-content> is the centered panel.
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+# --- 4c. Inline / JSDoc comment "foo(): prose" --------------------------
+# Match comment-line prefix (`//` or leading `*`) before `\w+(...): ` and
+# lowercase prose. Avoids TS return-type annotations because those never
+# appear inside comment lines.
+if printf '%s\n' "$new_content" | grep -qE '^[[:space:]]*(//|\*)[[:space:]][^(]*[A-Za-z_][A-Za-z0-9_]*\([^)]*\):[[:space:]][a-z]'; then
+  cat >&2 <<'EOF'
+BLOCKED: comment-line code-LHS colon-then-prose detected ("// foo(): ...").
+
+webjs bans `xyz(): <prose>` inside comments and JSDoc. Rewrite verb-led.
+
+  Bad:  // firstUpdated(): once, on the first render only
+  Good: // firstUpdated() runs once, on the first render only
+  Bad:  // closest(): null if the click wasn't inside a frame
+  Good: // closest() returns null when the click wasn't inside a frame
+
+Rule: AGENTS.md, Invariants section, item 10.
+Hook: .claude/hooks/block-prose-punctuation.sh.
+EOF
+  exit 2
+fi
+
+exit 0