npm - gorsee - Versions diffs - 0.2.0 → 0.2.1 - Mend

gorsee 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "gorsee",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Full-stack TypeScript framework — islands, reactive WebSocket, optimistic mutations, built-in auth, type-safe routes",
   "type": "module",
   "license": "MIT",

package/src/cli/cmd-docs.ts ADDED Viewed

@@ -0,0 +1,145 @@
+// gorsee docs -- generate API documentation from route files
+import { join } from "node:path"
+import { readFile, mkdir, writeFile } from "node:fs/promises"
+import { createRouter, type Route } from "../router/scanner.ts"
+const HTTP_METHODS = ["GET", "POST", "PUT", "DELETE", "PATCH"] as const
+interface DocFlags {
+  output: string
+  format: "md" | "json" | "html"
+  routesOnly: boolean
+}
+interface RouteDoc {
+  path: string
+  methods: string[]
+  hasLoader: boolean
+  isApi: boolean
+  hasMiddleware: boolean
+  title: string
+  meta: Record<string, unknown> | null
+}
+export function parseDocsFlags(args: string[]): DocFlags {
+  const flags: DocFlags = { output: "docs/api.md", format: "md", routesOnly: false }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (arg === "--output" && args[i + 1]) flags.output = args[++i]!
+    else if (arg === "--format" && args[i + 1]) {
+      const fmt = args[++i]!
+      if (fmt === "md" || fmt === "json" || fmt === "html") flags.format = fmt
+    } else if (arg === "--routes-only") flags.routesOnly = true
+  }
+  return flags
+}
+async function extractRouteInfo(route: Route): Promise<RouteDoc> {
+  const content = await readFile(route.filePath, "utf-8")
+  const methods: string[] = []
+  for (const method of HTTP_METHODS) {
+    if (new RegExp(`export\\s+(async\\s+)?function\\s+${method}\\b`, "i").test(content)) {
+      methods.push(method)
+    }
+  }
+  const hasDefault = /export\s+default\s+/.test(content)
+  const hasLoader = /export\s+(async\s+)?function\s+loader\b/.test(content)
+  const isApi = !hasDefault || methods.length > 0
+  if (methods.length === 0 && hasDefault) methods.push("GET")
+  if (methods.length === 0 && hasLoader) methods.push("GET")
+  // Extract title from JSDoc or component name
+  let title = ""
+  const jsdocMatch = content.match(/\/\*\*\s*\n?\s*\*\s*(.+?)(?:\n|\*\/)/s)
+  if (jsdocMatch) title = jsdocMatch[1]!.trim()
+  // Extract meta export
+  let meta: Record<string, unknown> | null = null
+  const metaMatch = content.match(/export\s+const\s+meta\s*=\s*(\{[^}]+\})/)
+  if (metaMatch) {
+    try { meta = JSON.parse(metaMatch[1]!.replace(/'/g, '"')) } catch { /* skip */ }
+  }
+  return {
+    path: route.path,
+    methods,
+    hasLoader,
+    isApi,
+    hasMiddleware: route.middlewarePaths.length > 0,
+    title,
+    meta,
+  }
+}
+function generateMarkdown(docs: RouteDoc[]): string {
+  const lines = ["# API Documentation", "", "| Path | Methods | Type | Loader | Middleware |", "| --- | --- | --- | --- | --- |"]
+  for (const doc of docs) {
+    const type = doc.isApi ? "API" : "Page"
+    const mw = doc.hasMiddleware ? "Yes" : "-"
+    lines.push(`| ${doc.path} | ${doc.methods.join(", ")} | ${type} | ${doc.hasLoader ? "Yes" : "-"} | ${mw} |`)
+  }
+  return lines.join("\n") + "\n"
+}
+function generateJson(docs: RouteDoc[]): string {
+  return JSON.stringify(docs, null, 2) + "\n"
+}
+function generateHtml(docs: RouteDoc[]): string {
+  const rows = docs.map((d) => {
+    const type = d.isApi ? "API" : "Page"
+    const mw = d.hasMiddleware ? "Yes" : "-"
+    return `<tr><td>${d.path}</td><td>${d.methods.join(", ")}</td><td>${type}</td><td>${d.hasLoader ? "Yes" : "-"}</td><td>${mw}</td></tr>`
+  }).join("\n      ")
+  return `<!DOCTYPE html>
+<html><head><meta charset="utf-8"><title>API Docs</title>
+<style>body{font-family:sans-serif;margin:2rem}table{border-collapse:collapse;width:100%}
+th,td{border:1px solid #ddd;padding:8px;text-align:left}th{background:#f5f5f5}</style>
+</head><body><h1>API Documentation</h1>
+<table><thead><tr><th>Path</th><th>Methods</th><th>Type</th><th>Loader</th><th>Middleware</th></tr></thead>
+  <tbody>${rows}</tbody></table></body></html>\n`
+}
+const GENERATORS: Record<string, (docs: RouteDoc[]) => string> = {
+  md: generateMarkdown,
+  json: generateJson,
+  html: generateHtml,
+}
+export async function runDocs(args: string[]) {
+  const cwd = process.cwd()
+  const flags = parseDocsFlags(args)
+  const routesDir = join(cwd, "routes")
+  const routes = await createRouter(routesDir)
+  if (routes.length === 0) {
+    console.log("\n  No routes found in routes/\n")
+    return
+  }
+  const docs: RouteDoc[] = []
+  for (const route of routes) {
+    const info = await extractRouteInfo(route)
+    if (flags.routesOnly && info.isApi) continue
+    docs.push(info)
+  }
+  const generate = GENERATORS[flags.format]!
+  const content = generate(docs)
+  const outputPath = join(cwd, flags.output)
+  await mkdir(join(outputPath, ".."), { recursive: true })
+  await writeFile(outputPath, content, "utf-8")
+  console.log(`\n  Generated docs for ${docs.length} routes -> ${flags.output}\n`)
+}
+export { extractRouteInfo, generateMarkdown, generateJson, generateHtml }
+export type { RouteDoc, DocFlags }

package/src/cli/cmd-test.ts ADDED Viewed

@@ -0,0 +1,121 @@
+// gorsee test -- smart test runner wrapping bun test
+import { readdir, stat } from "node:fs/promises"
+import { join } from "node:path"
+interface TestFlags {
+  watch: boolean
+  coverage: boolean
+  filter: string | null
+  e2e: boolean
+  unit: boolean
+  integration: boolean
+}
+function parseFlags(args: string[]): TestFlags {
+  const flags: TestFlags = {
+    watch: false,
+    coverage: false,
+    filter: null,
+    e2e: false,
+    unit: false,
+    integration: false,
+  }
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (arg === "--watch") flags.watch = true
+    else if (arg === "--coverage") flags.coverage = true
+    else if (arg === "--filter" && args[i + 1]) flags.filter = args[++i]!
+    else if (arg === "--e2e") flags.e2e = true
+    else if (arg === "--unit") flags.unit = true
+    else if (arg === "--integration") flags.integration = true
+  }
+  return flags
+}
+async function findTestFiles(dir: string, pattern: RegExp): Promise<string[]> {
+  const results: string[] = []
+  let entries: string[]
+  try {
+    entries = await readdir(dir)
+  } catch {
+    return results
+  }
+  for (const entry of entries) {
+    if (entry === "node_modules" || entry === "dist") continue
+    const fullPath = join(dir, entry)
+    const s = await stat(fullPath)
+    if (s.isDirectory()) {
+      results.push(...(await findTestFiles(fullPath, pattern)))
+    } else if (pattern.test(fullPath)) {
+      results.push(fullPath)
+    }
+  }
+  return results
+}
+function getTestPattern(flags: TestFlags): RegExp {
+  if (flags.e2e) return /(?:\.e2e\.test\.ts$|e2e\/.*\.test\.ts$)/
+  if (flags.integration) return /(?:\.integration\.test\.ts$|tests\/integration\/.*\.test\.ts$)/
+  if (flags.unit) return /(?:\.unit\.test\.ts$|tests\/unit\/.*\.test\.ts$)/
+  return /\.test\.ts$/
+}
+/** Build bun test args from parsed flags */
+export function buildTestArgs(flags: TestFlags, files: string[]): string[] {
+  const bunArgs = ["test"]
+  if (flags.watch) bunArgs.push("--watch")
+  if (flags.coverage) bunArgs.push("--coverage")
+  if (flags.filter) {
+    bunArgs.push("--bail", "--filter", flags.filter)
+  }
+  bunArgs.push(...files)
+  return bunArgs
+}
+export async function runTest(args: string[]) {
+  const cwd = process.cwd()
+  const flags = parseFlags(args)
+  const pattern = getTestPattern(flags)
+  const files = await findTestFiles(cwd, pattern)
+  if (files.length === 0) {
+    const kind = flags.e2e ? "e2e" : flags.integration ? "integration" : flags.unit ? "unit" : "any"
+    console.log(`\n  No ${kind} test files found.\n`)
+    return
+  }
+  console.log(`\n  Running ${files.length} test file(s)...\n`)
+  const bunArgs = buildTestArgs(flags, files)
+  const proc = Bun.spawn(["bun", ...bunArgs], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+    env: {
+      ...process.env,
+      NODE_ENV: "test",
+      GORSEE_TEST: "1",
+    },
+  })
+  const exitCode = await proc.exited
+  console.log()
+  if (exitCode === 0) {
+    console.log(`  Tests passed (${files.length} file(s))`)
+  } else {
+    console.log(`  Tests failed (exit code ${exitCode})`)
+    process.exit(exitCode)
+  }
+}
+// Re-export for testing
+export { parseFlags, findTestFiles, getTestPattern }

package/src/cli/cmd-upgrade.ts ADDED Viewed

@@ -0,0 +1,135 @@
+// gorsee upgrade -- upgrade framework version with migration guidance
+import { readFile } from "node:fs/promises"
+import { join } from "node:path"
+interface UpgradeFlags {
+  check: boolean
+  force: boolean
+}
+export function parseUpgradeFlags(args: string[]): UpgradeFlags {
+  const flags: UpgradeFlags = { check: false, force: false }
+  for (const arg of args) {
+    if (arg === "--check") flags.check = true
+    else if (arg === "--force") flags.force = true
+  }
+  return flags
+}
+/** Compare semver strings: -1 (a < b), 0 (equal), 1 (a > b) */
+export function compareVersions(a: string, b: string): number {
+  const pa = a.replace(/^v/, "").split(".").map(Number)
+  const pb = b.replace(/^v/, "").split(".").map(Number)
+  for (let i = 0; i < 3; i++) {
+    const va = pa[i] ?? 0
+    const vb = pb[i] ?? 0
+    if (va < vb) return -1
+    if (va > vb) return 1
+  }
+  return 0
+}
+async function getCurrentVersion(cwd: string): Promise<string | null> {
+  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(): Promise<string | null> {
+  try {
+    const res = await fetch(NPM_REGISTRY_URL)
+    if (!res.ok) return null
+    const data = (await res.json()) as { version?: string }
+    return data.version ?? null
+  } catch {
+    return null
+  }
+}
+async function checkMigrationHints(cwd: string): Promise<string[]> {
+  const hints: string[] = []
+  // Check tsconfig.json jsx setting
+  try {
+    const tsconfig = await readFile(join(cwd, "tsconfig.json"), "utf-8")
+    const parsed = JSON.parse(tsconfig)
+    if (parsed.compilerOptions?.jsx !== "react-jsx") {
+      hints.push("tsconfig.json: set compilerOptions.jsx to \"react-jsx\"")
+    }
+  } catch { /* no tsconfig */ }
+  // Check for deprecated app.config.ts keys
+  try {
+    const config = await readFile(join(cwd, "app.config.ts"), "utf-8")
+    if (config.includes("ssr:")) {
+      hints.push("app.config.ts: 'ssr' key is deprecated, use 'rendering' instead")
+    }
+  } catch { /* no config */ }
+  return hints
+}
+export async function runUpgrade(args: string[]) {
+  const cwd = process.cwd()
+  const flags = parseUpgradeFlags(args)
+  const current = await getCurrentVersion(cwd)
+  if (!current) {
+    console.log("\n  Gorsee.js not found in node_modules. Run: bun add gorsee\n")
+    return
+  }
+  console.log(`\n  Current version: v${current}`)
+  const latest = await fetchLatestVersion()
+  if (!latest) {
+    console.log("  Could not fetch latest version from npm registry.\n")
+    return
+  }
+  if (compareVersions(current, latest) >= 0) {
+    console.log(`  Already up to date (v${current})\n`)
+    return
+  }
+  console.log(`  Latest version:  v${latest}`)
+  console.log(`  Upgrade: v${current} -> v${latest}`)
+  if (flags.check) {
+    console.log()
+    return
+  }
+  if (!flags.force) {
+    console.log("\n  Run with --force to install, or confirm interactively.")
+  }
+  console.log("\n  Installing gorsee@latest...")
+  const proc = Bun.spawn(["bun", "add", "gorsee@latest"], {
+    cwd,
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const exitCode = await proc.exited
+  if (exitCode !== 0) {
+    console.log(`\n  Install failed (exit code ${exitCode})\n`)
+    process.exit(exitCode)
+  }
+  const hints = await checkMigrationHints(cwd)
+  if (hints.length > 0) {
+    console.log("\n  Migration hints:")
+    for (const hint of hints) {
+      console.log(`    - ${hint}`)
+    }
+  }
+  console.log(`\n  Upgraded successfully to v${latest}\n`)
+}

package/src/cli/index.ts CHANGED Viewed

@@ -15,6 +15,9 @@ const COMMANDS: Record<string, string> = {
   generate: "Generate CRUD scaffold for entity",
   typegen: "Generate typed route definitions",
   deploy: "Generate deploy config (vercel/fly/cloudflare/netlify/docker)",
+  test: "Run tests (unit/integration/e2e)",
+  docs: "Generate API documentation from routes",
+  upgrade: "Upgrade Gorsee.js to latest version",
   help: "Show this help message",
 }
@@ -60,6 +63,21 @@ async function main() {
       const { runDeploy } = await import("./cmd-deploy.ts")
       await runDeploy(args.slice(1))
       break
+    case "test": {
+      const { runTest } = await import("./cmd-test.ts")
+      await runTest(args.slice(1))
+      break
+    }
+    case "docs": {
+      const { runDocs } = await import("./cmd-docs.ts")
+      await runDocs(args.slice(1))
+      break
+    }
+    case "upgrade": {
+      const { runUpgrade } = await import("./cmd-upgrade.ts")
+      await runUpgrade(args.slice(1))
+      break
+    }
     case "help":
     case undefined:
     case "--help":