gorsee 0.2.3 → 0.2.5

package/dist-pkg/cli/cmd-upgrade.d.ts

@@ -0,0 +1,38 @@
+import { type RuntimeOptions } from "../runtime/project.js";
+interface UpgradeFlags {
+    check: boolean;
+    force: boolean;
+    report: string | null;
+    rewriteImports: boolean;
+}
+export interface UpgradeIssue {
+    code: string;
+    file: string;
+    severity: "info" | "warn";
+    message: string;
+    fix: string;
+}
+export interface UpgradeReport {
+    schemaVersion: 1;
+    generatedAt: string;
+    currentVersion: string | null;
+    latestVersion: string | null;
+    upgradeAvailable: boolean;
+    issues: UpgradeIssue[];
+}
+export declare function parseUpgradeFlags(args: string[]): UpgradeFlags;
+/** Compare semver strings: -1 (a < b), 0 (equal), 1 (a > b) */
+export declare function compareVersions(a: string, b: string): number;
+export declare const NPM_REGISTRY_URL = "https://registry.npmjs.org/gorsee/latest";
+export declare function collectUpgradeIssues(cwd: string): Promise<UpgradeIssue[]>;
+export declare function collectUpgradeReport(cwd: string, versions: {
+    currentVersion: string | null;
+    latestVersion: string | null;
+}): Promise<UpgradeReport>;
+export declare function writeUpgradeReport(cwd: string, reportPath: string, report: UpgradeReport): Promise<void>;
+export interface UpgradeCommandOptions extends RuntimeOptions {
+}
+export declare function upgradeFramework(args: string[], options?: UpgradeCommandOptions): Promise<void>;
+/** @deprecated Use upgradeFramework() for programmatic access. */
+export declare function runUpgrade(args: string[], options?: UpgradeCommandOptions): Promise<void>;
+export {};

package/dist-pkg/cli/cmd-upgrade.js

@@ -0,0 +1,232 @@
+import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { createProjectContext } from "../runtime/project.js";
+import { analyzeModuleSource } from "../compiler/module-analysis.js";
+import { collectCanonicalImportDrift } from "./canonical-imports.js";
+import { rewriteCanonicalImportsInProject, rewriteLegacyLoadersInProject } from "./canonical-import-rewrite.js";
+export function parseUpgradeFlags(args) {
+  const flags = { check: !1, force: !1, report: null, rewriteImports: !1 };
+  for (let index = 0;index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--check")
+      flags.check = !0;
+    else if (arg === "--force")
+      flags.force = !0;
+    else if (arg === "--rewrite-imports")
+      flags.rewriteImports = !0;
+    else if (arg === "--report" && args[index + 1])
+      flags.report = args[++index];
+  }
+  return flags;
+}
+export function compareVersions(a, b) {
+  const pa = a.replace(/^v/, "").split(".").map(Number), pb = b.replace(/^v/, "").split(".").map(Number);
+  for (let i = 0;i < 3; i++) {
+    const va = pa[i] ?? 0, vb = pb[i] ?? 0;
+    if (va < vb)
+      return -1;
+    if (va > vb)
+      return 1;
+  }
+  return 0;
+}
+async function getCurrentVersion(cwd) {
+  try {
+    const pkg = await readFile(join(cwd, "node_modules/gorsee/package.json"), "utf-8");
+    return JSON.parse(pkg).version ?? null;
+  } catch {
+    return null;
+  }
+}
+export const NPM_REGISTRY_URL = "https://registry.npmjs.org/gorsee/latest";
+async function fetchLatestVersion() {
+  try {
+    const res = await fetch(NPM_REGISTRY_URL);
+    if (!res.ok)
+      return null;
+    return (await res.json()).version ?? null;
+  } catch {
+    return null;
+  }
+}
+async function tryReadFile(path) {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+async function getAllSourceFiles(cwd, dir) {
+  const path = join(cwd, dir);
+  try {
+    const entries = await readdir(path), files = [];
+    for (const entry of entries) {
+      if (entry === "node_modules" || entry === "dist" || entry === ".git")
+        continue;
+      const fullPath = join(path, entry);
+      if ((await stat(fullPath)).isDirectory())
+        files.push(...await getAllSourceFiles(cwd, relative(cwd, fullPath)));
+      else if (entry.endsWith(".ts") || entry.endsWith(".tsx"))
+        files.push(fullPath);
+    }
+    return files;
+  } catch {
+    return [];
+  }
+}
+function issue(code, file, message, fix, severity = "warn") {
+  return { code, file, severity, message, fix };
+}
+export async function collectUpgradeIssues(cwd) {
+  const issues = [], tsconfigSource = await tryReadFile(join(cwd, "tsconfig.json"));
+  if (tsconfigSource)
+    try {
+      const tsconfig = JSON.parse(tsconfigSource);
+      if (tsconfig.compilerOptions?.jsx !== "preserve")
+        issues.push(issue("UG001", "tsconfig.json", "Canonical Gorsee JSX mode is no longer configured", 'Set compilerOptions.jsx to "preserve"'));
+      if (tsconfig.compilerOptions?.jsxImportSource !== "gorsee")
+        issues.push(issue("UG002", "tsconfig.json", "Canonical jsxImportSource is missing", 'Set compilerOptions.jsxImportSource to "gorsee"'));
+    } catch {
+      issues.push(issue("UG003", "tsconfig.json", "Could not parse tsconfig.json for migration checks", "Fix tsconfig.json so upgrade checks can validate the canonical compiler contract"));
+    }
+  if ((await tryReadFile(join(cwd, "app.config.ts")))?.includes("ssr:"))
+    issues.push(issue("UG004", "app.config.ts", "Deprecated app.config.ts key 'ssr' is still present", "Replace 'ssr' with the canonical 'rendering' configuration surface"));
+  const packageJsonSource = await tryReadFile(join(cwd, "package.json"));
+  if (packageJsonSource)
+    try {
+      const pkg = JSON.parse(packageJsonSource);
+      if (!pkg.packageManager || !/^bun@\d+\.\d+\.\d+$/.test(pkg.packageManager))
+        issues.push(issue("UG005", "package.json", "packageManager should pin the exact Bun version used by the project", 'Set packageManager to an exact version such as "bun@1.3.9"'));
+    } catch {
+      issues.push(issue("UG006", "package.json", "Could not parse package.json for upgrade checks", "Fix package.json so upgrade checks can validate package-manager and dependency contracts"));
+    }
+  for (const deployFile of ["app.config.ts", "wrangler.toml", "netlify.toml", "fly.toml", "vercel.json"]) {
+    const source = await tryReadFile(join(cwd, deployFile));
+    if (!source)
+      continue;
+    if (/REPLACE_WITH_APP_ORIGIN|https:\/\/example\.com/.test(source))
+      issues.push(issue("UG007", deployFile, "Placeholder origin values are still present", "Replace placeholder origins with the canonical application origin before shipping the upgrade"));
+  }
+  const sourceFiles = [
+    ...await getAllSourceFiles(cwd, "routes"),
+    ...await getAllSourceFiles(cwd, "shared"),
+    ...await getAllSourceFiles(cwd, "middleware")
+  ];
+  for (const file of sourceFiles) {
+    const source = await tryReadFile(file);
+    if (!source)
+      continue;
+    const facts = analyzeModuleSource(file, source);
+    if (facts.imports.some((entry) => entry.specifier === "gorsee"))
+      issues.push(issue("UG008", relative(cwd, file), 'Compatibility-only root "gorsee" import is still used in application code', 'Move browser-safe imports to "gorsee/client", server code to "gorsee/server", or explicit compatibility bridges to "gorsee/compat"'));
+    for (const drift of collectCanonicalImportDrift(facts.imports)) {
+      const entries = [...drift.replacements.entries()].map(([name, target]) => `${name} -> ${target}`).join(", "), targets = [...new Set(drift.replacements.values())].join(", ");
+      issues.push(issue(drift.source === "gorsee/server" ? "UG009" : "UG010", relative(cwd, file), `Domain APIs still come from "${drift.source}" instead of scoped stable subpaths: ${entries}`, drift.source === "gorsee/server" ? `Keep runtime primitives on "gorsee/server" and move domain imports to ${targets}` : `Keep browser runtime primitives on "gorsee/client" and move domain imports to ${targets}`, "info"));
+    }
+    if (facts.exportedNames.has("loader"))
+      issues.push(issue("UG011", relative(cwd, file), 'Route module still exports "loader" instead of canonical "load"', 'Rename exported "loader" to "load", or run `gorsee upgrade --rewrite-imports` to rewrite obvious cases automatically', "info"));
+  }
+  return issues;
+}
+export async function collectUpgradeReport(cwd, versions) {
+  const issues = await collectUpgradeIssues(cwd), { currentVersion, latestVersion } = versions, upgradeAvailable = currentVersion !== null && latestVersion !== null && compareVersions(currentVersion, latestVersion) < 0;
+  return {
+    schemaVersion: 1,
+    generatedAt: new Date().toISOString(),
+    currentVersion,
+    latestVersion,
+    upgradeAvailable,
+    issues
+  };
+}
+export async function writeUpgradeReport(cwd, reportPath, report) {
+  const outputPath = join(cwd, reportPath);
+  await mkdir(dirname(outputPath), { recursive: !0 });
+  await writeFile(outputPath, JSON.stringify(report, null, 2) + `
+`, "utf-8");
+}
+export async function upgradeFramework(args, options = {}) {
+  const { cwd } = createProjectContext(options), flags = parseUpgradeFlags(args);
+  if (flags.rewriteImports) {
+    const importRewrite = await rewriteCanonicalImportsInProject(cwd), loaderRewrite = await rewriteLegacyLoadersInProject(cwd), changedFiles = [...new Set([...importRewrite.changedFiles, ...loaderRewrite.changedFiles])].sort();
+    if (changedFiles.length > 0) {
+      console.log(`
+  Rewrote canonical imports and loader aliases:`);
+      for (const file of changedFiles)
+        console.log(`    - ${file}`);
+    } else
+      console.log(`
+  Canonical import and loader rewrite found no changes.`);
+  }
+  const current = await getCurrentVersion(cwd);
+  if (!current) {
+    console.log(`
+  Gorsee.js not found in node_modules. Run: bun add gorsee
+`);
+    return;
+  }
+  console.log(`
+  Current version: v${current}`);
+  const latest = await fetchLatestVersion();
+  if (!latest) {
+    console.log(`  Could not fetch latest version from npm registry.
+`);
+    return;
+  }
+  const report = await collectUpgradeReport(cwd, {
+    currentVersion: current,
+    latestVersion: latest
+  });
+  if (flags.report) {
+    await writeUpgradeReport(cwd, flags.report, report);
+    console.log(`  Upgrade report:  ${flags.report}`);
+  }
+  if (compareVersions(current, latest) >= 0) {
+    console.log(`  Already up to date (v${current})`);
+    if (report.issues.length > 0) {
+      console.log(`
+  Migration audit:`);
+      for (const entry of report.issues)
+        console.log(`    - [${entry.code}] ${entry.file}: ${entry.message}`);
+    }
+    console.log();
+    return;
+  }
+  console.log(`  Latest version:  v${latest}`);
+  console.log(`  Upgrade: v${current} -> v${latest}`);
+  if (report.issues.length > 0) {
+    console.log(`
+  Migration audit:`);
+    for (const entry of report.issues)
+      console.log(`    - [${entry.code}] ${entry.file}: ${entry.message}`);
+  }
+  if (flags.check) {
+    console.log();
+    return;
+  }
+  if (!flags.force) {
+    console.log(`
+  Run with --force to install after reviewing the migration audit.
+`);
+    return;
+  }
+  console.log(`
+  Installing gorsee@latest...`);
+  const exitCode = await Bun.spawn(["bun", "add", "gorsee@latest"], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit"
+  }).exited;
+  if (exitCode !== 0) {
+    console.log(`
+  Install failed (exit code ${exitCode})
+`);
+    process.exit(exitCode);
+  }
+  console.log(`
+  Upgraded successfully to v${latest}
+`);
+}
+export async function runUpgrade(args, options = {}) {
+  return upgradeFramework(args, options);
+}

package/dist-pkg/cli/context.d.ts

@@ -0,0 +1,4 @@
+/** @deprecated Import shared project context from "../runtime/project" in new code. */
+export { createProjectContext as createCommandContext, resolveProjectPaths, } from "../runtime/project.js";
+/** @deprecated Import shared runtime types from "../runtime/project" in new code. */
+export type { RuntimeOptions as CommandRuntimeOptions, ProjectContext as CommandContext, ProjectPaths, } from "../runtime/project.js";

package/dist-pkg/cli/context.js

@@ -0,0 +1,4 @@
+export {
+  createProjectContext as createCommandContext,
+  resolveProjectPaths
+} from "../runtime/project.js";

package/dist-pkg/cli/framework-md.d.ts

@@ -0,0 +1 @@
+export declare function generateFrameworkMD(projectName: string): string;

package/dist-pkg/cli/framework-md.js

@@ -0,0 +1,391 @@
+export function generateFrameworkMD(projectName) {
+  return `# ${projectName} -- Gorsee.js Framework Reference
+
+> This file is auto-generated. It provides complete context for AI assistants.
+> Include this file in your AI context window for best results.
+
+## Product Identity
+
+Gorsee is an AI-first reactive full-stack framework designed for deterministic collaboration between humans and coding agents.
+
+Treat it as a mature product framework:
+
+- not a pet project
+- not a toy runtime
+- not a loose collection of optional recipes
+
+The framework prefers one clear path, strict contracts, and product-grade discipline over flexibility for its own sake.
+
+## Quick Reference
+
+\`\`\`
+Runtime: Bun | Language: TypeScript + JSX | Reactivity: Signals (no VDOM)
+\`\`\`
+
+## Project Structure
+
+\`\`\`
+routes/          Page and API routes (file-based routing)
+  index.ts       / (home page)
+  about.tsx      /about
+  users/
+    index.tsx    /users
+    [id].tsx     /users/:id (dynamic)
+  api/
+    health.ts    API endpoint (no UI)
+  _layout.tsx    Layout wrapper for folder
+  _middleware.ts Middleware for folder
+shared/          Shared types and utilities
+middleware/      Global middleware
+migrations/      Database migrations (SQL)
+public/          Static files
+app.config.ts    Configuration
+\`\`\`
+
+## Imports
+
+\`\`\`typescript
+// Browser-safe route code
+import { createSignal, createComputed, createEffect, createResource, createStore } from "gorsee/client"
+
+// Server runtime contracts
+import { server, middleware, type Context } from "gorsee/server"
+
+// Domain-focused server surfaces
+import { createDB } from "gorsee/db"
+import { createAuth } from "gorsee/auth"
+import { cors } from "gorsee/security"
+import { log } from "gorsee/log"
+\`\`\`
+
+## Import Boundaries
+
+- \`gorsee/client\` for route components, islands, navigation, forms, and reactive primitives
+- \`gorsee/server\` for middleware, \`load\`, \`action\`, RPC, cache, and route execution
+- prefer scoped subpaths such as \`gorsee/auth\`, \`gorsee/db\`, \`gorsee/security\`, \`gorsee/env\`, and \`gorsee/log\` when the concern is already domain-specific
+- Root \`gorsee\` is compatibility-only and should not be used in new code
+- \`gorsee/compat\` is available as an explicit legacy migration entrypoint
+
+## Engineering Doctrine
+
+- Prefer deterministic architecture over multiple equivalent patterns.
+- Prefer built-in framework guarantees over handwritten recipes.
+- Preserve fine-grained reactivity and avoid VDOM-style architectural drift.
+- Treat security, deploy assumptions, and AI diagnostics as part of the framework contract.
+- If a pattern must exist, it should be easy for both humans and agents to infer from structure and docs.
+
+## Adapter Recipes
+
+\`\`\`typescript
+import { createClient } from "redis"
+import {
+  createRedisSessionStore,
+  createRedisCacheStore,
+  createNodeRedisLikeClient,
+  routeCache,
+} from "gorsee/server"
+import { createAuth } from "gorsee/auth"
+import { createCSRFMiddleware } from "gorsee/security"
+
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+const redisClient = createNodeRedisLikeClient(redis)
+
+const auth = createAuth({
+  secret: process.env.SESSION_SECRET!,
+  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
+})
+
+export const cache = routeCache({
+  maxAge: 60,
+  staleWhileRevalidate: 300,
+  mode: "public", // default mode is private/auth-aware
+  store: createRedisCacheStore(redisClient, {
+    prefix: "app:cache",
+    maxEntryAgeMs: 360_000,
+  }),
+})
+\`\`\`
+
+- SQLite adapters are the default persistent single-node path
+- Redis adapters are the default multi-instance path
+- \`createNodeRedisLikeClient()\` and \`createIORedisLikeClient()\` normalize real Redis SDK clients to the framework adapter contract
+- \`routeCache()\` defaults to \`mode: "private"\` and varies by \`Cookie\`, \`Authorization\`, \`Accept\`, and \`X-Gorsee-Navigate\`
+- Use \`mode: "public"\` or \`mode: "shared"\` only for intentionally non-personalized cache entries
+- RPC handlers remain process-local by design; do not try to distribute closures through Redis
+
+## RPC Security
+
+\`\`\`typescript
+import { handleRPCRequestWithPolicy } from "gorsee/server"
+import { createAuth } from "gorsee/auth"
+import { createCSRFMiddleware } from "gorsee/security"
+
+const auth = createAuth({ secret: process.env.SESSION_SECRET! })
+
+const rpcResponse = await handleRPCRequestWithPolicy(request, {
+  middlewares: [
+    auth.protect(),
+    createCSRFMiddleware(process.env.SESSION_SECRET!),
+  ],
+})
+\`\`\`
+
+- RPC is \`POST\`-only
+- RPC uses a versioned envelope over \`application/vnd.gorsee-rpc+json\`
+- Route \`_middleware.ts\` does not automatically protect \`/api/_rpc/*\`
+- Apply auth/CSRF policy explicitly at the RPC boundary
+
+## AI Observability
+
+\`\`\`typescript
+export default {
+  ai: {
+    enabled: true,
+    jsonlPath: ".gorsee/ai-events.jsonl",
+    diagnosticsPath: ".gorsee/ai-diagnostics.json",
+    sessionPack: {
+      enabled: true,
+      outDir: ".gorsee/agent",
+      triggerKinds: ["diagnostic.issue", "request.error", "build.summary", "check.summary"],
+    },
+    bridge: {
+      url: "http://127.0.0.1:4318/gorsee/ai-events",
+      timeoutMs: 250,
+      events: ["diagnostic.issue", "check.summary", "build.summary", "request.error"],
+    },
+  },
+}
+\`\`\`
+
+- AI observability is opt-in and must not change app behavior when disabled
+- \`.gorsee/ai-events.jsonl\` is the canonical machine-readable event stream for agents and IDE tooling
+- \`.gorsee/ai-diagnostics.json\` keeps the latest error/warning snapshot for fast IDE polling
+- \`.gorsee/ide/diagnostics.json\`, \`.gorsee/ide/events.json\`, and \`.gorsee/ide/context.md\` are editor-facing projections produced by \`gorsee ai ide-sync\`
+- \`.gorsee/ide/events.json\` now includes \`artifactRegressions\` plus event-level \`artifact\` / \`version\` metadata for release/deploy/build drift
+- \`.gorsee/agent/latest.json\` and \`.gorsee/agent/latest.md\` are session packs for agents; they can be generated manually with \`gorsee ai pack\` or automatically after error/build/check triggers
+- \`gorsee ai doctor\` clusters repeated failures by trace/request/file/route so agents can spot systemic regressions quickly
+- \`gorsee ai doctor\` and \`gorsee ai export\` also surface artifact regressions, so agents can reason about broken tarballs, VSIX files, build outputs, and deploy configs without separate tooling
+- Bridge delivery is best-effort only; a dead IDE bridge must never fail the request/build/check path
+- Event schema carries \`requestId\`, \`traceId\`, \`spanId\`, \`route\`, \`code\`, \`file\`, \`line\`, and \`durationMs\`
+- Prefer AI events over scraped console logs when automating analysis
+- Use \`gorsee ai export --bundle\` when an agent needs a compact context packet plus root-cause-ranked code snippets
+- Use \`gorsee ai pack\` when you want the latest context bundle written to disk for another tool to pick up
+- Use \`bun run ai:package:vscode\` to stage and package the VS Code/Cursor extension consumer from \`integrations/vscode-gorsee-ai\`
+- Use \`bun run release:extension\` to build a version-locked VSIX release artifact
+- In the VS Code/Cursor extension, use \`Gorsee AI: Show Context\` for the full context packet and \`Gorsee AI: Show Artifact Regressions\` for release/deploy/build drift
+
+## Failure References
+
+- Use \`docs/RUNTIME_FAILURES.md\` for common production/runtime failures
+- Use \`docs/RUNTIME_TRIAGE.md\` for operator triage flow
+- Use \`docs/CACHE_INVALIDATION.md\` before widening cache scope
+- Use \`docs/STREAMING_HYDRATION_FAILURES.md\` when streaming or hydration behavior drifts
+- Use \`docs/STARTER_FAILURES.md\` for common scaffold/setup mistakes
+
+## AI Workflow References
+
+- Use \`docs/AI_WORKFLOWS.md\` for the overall human + agent operating model
+- Use \`docs/AI_IDE_SYNC_WORKFLOW.md\` for editor projections
+- Use \`docs/AI_MCP_WORKFLOW.md\` for MCP consumers
+- Use \`docs/AI_BRIDGE_WORKFLOW.md\` for local bridge ingestion
+- Use \`docs/AI_TOOL_BUILDERS.md\` when building external consumers
+- Use \`docs/AI_SURFACE_STABILITY.md\` before changing AI-facing contracts
+- Use \`docs/AI_SESSION_PACKS.md\` for cross-session handoff
+- Use \`docs/AI_DEBUGGING_WORKFLOWS.md\` for diagnostics-first debugging
+
+## Product DX References
+
+- Use \`docs/STARTER_ONBOARDING.md\` to choose the right app class
+- Use \`docs/MIGRATION_GUIDE.md\` when cleaning up compatibility imports
+- Use \`docs/UPGRADE_PLAYBOOK.md\` before release-channel or contract upgrades
+- Use \`docs/DEPLOY_TARGET_GUIDE.md\` before committing to a deploy target
+- Use \`docs/FIRST_PRODUCTION_ROLLOUT.md\` for the first real launch
+- Use \`docs/AUTH_CACHE_DATA_PATHS.md\` to choose auth/cache/data defaults by app class
+- Use \`docs/RECIPE_BOUNDARIES.md\` when a recipe looks stretched beyond its intended shape
+- Use \`docs/WORKSPACE_ADOPTION.md\` for monorepo/workspace layouts
+- Use \`docs/TEAM_FAILURES.md\` for common team-level adoption mistakes
+
+## Patterns
+
+### Page Route
+
+\`\`\`typescript
+// routes/users/index.tsx
+import { ssrJsx as h } from "gorsee/runtime"
+import { SafeSQL } from "gorsee/types"
+import { createDB } from "gorsee/db"
+
+const db = createDB()
+
+export default function UsersPage() {
+  const users = db.all<User>(SafeSQL\`SELECT * FROM users\`)
+  return h("ul", {
+    children: users.map(u => h("li", { children: u.name }))
+  })
+}
+\`\`\`
+
+### Dynamic Route
+
+\`\`\`typescript
+// routes/users/[id].tsx
+export default function UserPage(props: { params: { id: string } }) {
+  const user = db.get<User>(SafeSQL\`SELECT * FROM users WHERE id = \${Number(props.params.id)}\`)
+  if (!user) return h("div", { children: "Not found" })
+  return h("h1", { children: user.name })
+}
+\`\`\`
+
+### API Route
+
+\`\`\`typescript
+// routes/api/users.ts
+import type { Context } from "gorsee/server"
+
+export function GET(ctx: Context): Response {
+  return Response.json({ users: [] })
+}
+
+export function POST(ctx: Context): Response {
+  return Response.json({ created: true }, { status: 201 })
+}
+\`\`\`
+
+### Route Action
+
+\`\`\`typescript
+// routes/users/new.tsx
+import { defineForm, defineFormAction } from "gorsee/forms"
+
+const userForm = defineForm<{ name: string }>([
+  { name: "name", rules: { required: true }, label: "Name" },
+])
+
+export const action = defineFormAction(userForm, async ({ data }) => {
+  await db.run(SafeSQL\`INSERT INTO users (name) VALUES (\${data.name})\`)
+  return { ok: true, data: { created: true } }
+})
+\`\`\`
+
+### Middleware
+
+\`\`\`typescript
+// routes/_middleware.ts
+import { middleware } from "gorsee/server"
+
+export default middleware(async (ctx, next) => {
+  const session = ctx.cookies.get("session")
+  if (!session) return ctx.redirect("/login")
+  ctx.locals.user = await getUser(session)
+  return next()
+})
+\`\`\`
+
+### Signals
+
+\`\`\`typescript
+const [count, setCount] = createSignal(0)        // reactive value
+const doubled = createComputed(() => count() * 2) // derived
+createEffect(() => console.log(count()))          // side effect
+const [data] = createResource(fetchData)          // async resource
+const [store, setStore] = createStore({ a: 1 })   // reactive object
+\`\`\`
+
+### SafeSQL (prevents SQL injection at compile time)
+
+\`\`\`typescript
+// OK:
+db.get(SafeSQL\`SELECT * FROM users WHERE id = \${id}\`)
+
+// COMPILE ERROR -- string not assignable to SafeSQL:
+db.get(\`SELECT * FROM users WHERE id = \${id}\`)
+db.get("SELECT * FROM users WHERE id = " + id)
+\`\`\`
+
+## Configuration (app.config.ts)
+
+\`\`\`typescript
+export default {
+  port: 3000,
+  db: { driver: "sqlite", url: "./data.sqlite" },
+  log: "info",  // off | error | info | verbose | debug
+  security: {
+    origin: process.env.APP_ORIGIN ?? "https://app.example.com",
+    proxy: {
+      preset: "none",
+      trustForwardedHeaders: false,
+      trustedForwardedHops: 1,
+    },
+    csp: true,
+    hsts: true,
+    csrf: true,
+    rateLimit: { requests: 100, window: "1m" },
+  },
+  // RPC is a separate boundary from route _middleware.ts
+  // security: { rpc: { middlewares: [auth.protect(), createCSRFMiddleware(process.env.SESSION_SECRET!)] } },
+  deploy: { target: "bun" },  // bun | cloudflare | deno | node
+}
+\`\`\`
+
+- Replace placeholder origins in deploy configs and \`security.origin\` before production rollout.
+- \`gorsee check --strict\` escalates floating runtime dependency versions and placeholder origin values to errors.
+
+## Security Docs
+
+- \`SECURITY.md\` defines disclosure policy, reporting path, and the rule that security bugs are treated as broken framework invariants.
+- \`docs/PRODUCT_VISION.md\` defines the product position and market thesis.
+- \`docs/FRAMEWORK_DOCTRINE.md\` defines non-negotiable engineering principles.
+- \`docs/TOP_TIER_ROADMAP.md\` defines the maturity roadmap to top-tier framework quality.
+- \`docs/CANONICAL_RECIPES.md\` defines the recommended production paths for secure SaaS apps, content sites, internal tools, and workspace-based apps.
+- \`docs/API_STABILITY.md\` defines stable, compatibility, experimental, and internal API tiers.
+- \`docs/AI_ARTIFACT_CONTRACT.md\` defines versioned AI packet, IDE projection, and session-pack artifact expectations.
+- \`docs/SUPPORT_MATRIX.md\` defines what the product currently supports and validates.
+- \`docs/DEPRECATION_POLICY.md\` defines how public behavior is deprecated and migrated.
+- \`docs/SECURITY_MODEL.md\` defines framework guarantees around request ordering, canonical origin, internal/public boundaries, cache expectations, RPC, and adapter assumptions.
+- \`docs/SECURE_PATTERNS.md\` lists preferred and unsafe usage patterns for auth, redirects, cache, RPC, origins, proxy headers, provider presets, dev server exposure, and file serving.
+- \`docs/ADAPTER_SECURITY.md\` documents provider-specific deploy assumptions for Vercel, Cloudflare, Netlify, Fly.io, and Docker.
+- \`docs/RELEASE_POLICY.md\` defines stable/canary/rc channel rules and the intended release train for security-sensitive changes.
+- \`docs/RELEASE_CHECKLIST.md\` defines the operator-facing stable/canary/rc checklist and the invariants that must hold before publishing.
+- \`docs/CI_POLICY.md\` defines the required CI gates, change-sensitive rules, release-train validation, and the exact Bun contract used in automation.
+
+## CLI
+
+\`\`\`
+gorsee dev          Start dev server
+gorsee build        Production build
+gorsee check        Type + safety + structure check
+gorsee check --rewrite-imports --rewrite-loaders
+                    Normalize canonical imports and loader aliases before auditing
+gorsee ai doctor    Summarize AI diagnostics and incidents
+gorsee ai replay    Reconstruct recent correlated AI event timeline
+gorsee ai export    Export a compact agent-ready context packet
+gorsee ai ide-sync  Write IDE-friendly diagnostics/events/context files
+gorsee ai mcp       Expose local AI state as a stdio MCP server
+gorsee routes       List all routes
+gorsee migrate      Run database migrations
+gorsee generate X   Generate CRUD for entity X
+\`\`\`
+
+- For migration cleanup, prefer \`gorsee upgrade --rewrite-imports --check --report docs/upgrade-report.json\`.
+
+## Error Codes
+
+| Code | Category | Description |
+|------|----------|-------------|
+| E001 | SafeSQL | Raw string in SQL query |
+| E002 | SafeHTML | Unsanitized HTML |
+| E003 | Server | Closure captures client variable |
+| E004 | URL | Invalid URL |
+| E005 | URL | Disallowed protocol |
+
+## Security (enabled by default)
+
+- CSP with nonce (no inline scripts except framework)
+- HSTS (production)
+- CSRF tokens (auto for POST)
+- Rate limiting (100 req/min default)
+- X-Frame-Options: DENY
+- X-Content-Type-Options: nosniff
+`;
+}

package/dist-pkg/cli/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+declare const args: string[];
+declare const command: string | undefined;
+declare const COMMANDS: Record<string, string>;
+declare function main(): Promise<void>;
+declare function printHelp(): void;