@strav/spring 0.4.31 → 1.0.0-alpha.28

package/README.md

@@ -1,61 +1,20 @@
 # @strav/spring
 
-Flagship framework scaffolding tool for the Strav ecosystem - the rite of the Bun ecosystem.
-
-## Usage
+Project scaffolder for Strav 1.0. Writes a working app skeleton you can boot in a single command.
 
 ```bash
-bunx @strav/spring my-app --web   # full-stack with Vue islands
-bunx @strav/spring my-app --api   # headless REST API
-bunx @strav/spring my-app         # interactive prompt
-```
-
-## Templates
-
-- **api** — Headless REST API with CORS enabled
-- **web** — Full-stack with .strav views, Vue islands, and sessions
-
-## Options
-
-```
-bunx @strav/spring <project-name> [options]
-
---api                     Headless REST API template
---web                     Full-stack template with Vue islands
---template, -t api|web    Alias for --api / --web
---db <name>               Database name (default: project name)
--h, --help                Show help
+bunx @strav/spring my-app --api
+cd my-app
+bun install
+bun strav serve
+# → listening on http://localhost:3000
 ```
 
-## What's scaffolded
+See [`docs/spring/`](../../docs/spring/) for the full documentation and the [template-strategy ADR](../../docs/decisions/spring-template-strategy.md) for design notes.
 
-```
-my-app/
-├── app/
-│   ├── controllers/      # HTTP controllers
-│   ├── models/           # Database models (generated from schemas)
-│   ├── middleware/       # Custom middleware
-│   ├── providers/        # Service providers
-│   ├── policies/         # Authorization policies
-│   ├── jobs/             # Queue jobs
-│   └── services/         # Business logic services
-├── config/               # Configuration files
-├── database/
-│   ├── schemas/         # Schema definitions
-│   ├── migrations/      # Generated migrations
-│   ├── seeders/          # Database seeders
-│   └── factories/        # Model factories
-├── resources/
-│   ├── views/            # .strav templates
-│   ├── css/              # Stylesheets
-│   └── ts/islands/       # Vue.js islands
-├── routes/               # Route definitions
-├── tests/                # Test files
-├── index.ts              # Application entry point
-├── strav.ts              # CLI tool
-└── .env                  # Environment variables
-```
+## Status
 
-## License
+- Slice A — `--api` template + CLI shell. **Shipped.**
+- Slice B — `--web` template (`@strav/view` + Vue islands + plain CSS). **Shipped.**
 
-MIT
+The scaffolder is feature-complete for 1.0. Slice 5.17 (`port` codemod) is cancelled — no 0.x backward-compat commitment.

package/package.json

@@ -1,30 +1,29 @@
 {
   "name": "@strav/spring",
-  "version": "0.4.31",
+  "version": "1.0.0-alpha.28",
+  "description": "Strav project scaffolder — `bunx @strav/spring my-app` writes a working app skeleton (bin/, bootstrap/, config/, routes/, …) per spec/directory-structure.md. Two templates: --api (headless REST) and --web (Vue islands + .strav views). Runtime-independent of the framework — no @strav/* runtime deps.",
   "type": "module",
-  "description": "Flagship framework scaffolding tool for the Strav ecosystem.",
-  "license": "MIT",
-  "keywords": [
-    "strav",
-    "bun",
-    "framework",
-    "scaffold",
-    "create",
-    "typescript",
-    "vue"
-  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
   "bin": {
-    "@strav/spring": "./src/index.ts"
+    "@strav/spring": "./src/cli.ts"
   },
   "files": [
-    "src/",
-    "package.json",
+    "src",
     "README.md"
   ],
-  "dependencies": {
-    "@strav/kernel": "0.4.31"
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@types/bun": ">=1.3.14"
   },
-  "devDependencies": {
-    "@types/bun": "latest"
-  }
+  "dependencies": null,
+  "devDependencies": null
 }

package/src/args.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure CLI argument parser for `bunx @strav/spring`. Side-effect free so
+ * `tests/unit/args.test.ts` can hit every branch without spawning a process.
+ *
+ * Surface:
+ *   bunx @strav/spring <project-name> [--api|--web|-t api|web] [--db <name>]
+ *                                     [--no-install] [-h|--help] [-v|--version]
+ *
+ * Validation rules:
+ *   - Project name is required for a real run. Help / version short-circuit it.
+ *   - Project name matches `/^[a-z0-9][a-z0-9_-]*$/` (no uppercase, no leading
+ *     dot, no spaces). This is what npm packageName allows minus the scope.
+ *   - `--template` / `-t` only accepts `api` or `web`. Conflicts between
+ *     `--api` / `--web` / `--template` → error.
+ */
+
+import { SpringError } from './spring_error.ts'
+
+export type Template = 'api' | 'web'
+
+export interface ParsedArgs {
+  /** Empty when the user just asked for help or version. */
+  projectName?: string
+  template?: Template
+  dbName?: string
+  noInstall: boolean
+  help: boolean
+  version: boolean
+}
+
+const NAME_RE = /^[a-z0-9][a-z0-9_-]*$/
+
+export function parseArgs(argv: readonly string[]): ParsedArgs {
+  const out: ParsedArgs = { noInstall: false, help: false, version: false }
+  let templateSeenAs: string | undefined
+
+  const setTemplate = (value: string, flag: string): void => {
+    if (value !== 'api' && value !== 'web') {
+      throw new SpringError(`${flag}: expected "api" or "web", got "${value}"`)
+    }
+    if (out.template !== undefined && out.template !== value) {
+      throw new SpringError(
+        `${flag} conflicts with earlier ${templateSeenAs} (resolved to "${out.template}")`,
+      )
+    }
+    out.template = value as Template
+    templateSeenAs = flag
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i] as string
+    switch (arg) {
+      case '-h':
+      case '--help':
+        out.help = true
+        break
+      case '-v':
+      case '--version':
+        out.version = true
+        break
+      case '--api':
+        setTemplate('api', '--api')
+        break
+      case '--web':
+        setTemplate('web', '--web')
+        break
+      case '--no-install':
+        out.noInstall = true
+        break
+      case '-t':
+      case '--template': {
+        const next = argv[++i]
+        if (next === undefined) {
+          throw new SpringError(`${arg}: missing value (expected "api" or "web")`)
+        }
+        setTemplate(next, arg)
+        break
+      }
+      case '--db': {
+        const next = argv[++i]
+        if (next === undefined) {
+          throw new SpringError(`--db: missing value (expected a database name)`)
+        }
+        out.dbName = next
+        break
+      }
+      default: {
+        if (arg.startsWith('-')) {
+          throw new SpringError(`unknown option: ${arg}`)
+        }
+        if (out.projectName !== undefined) {
+          throw new SpringError(
+            `unexpected positional argument "${arg}" (project name "${out.projectName}" already set)`,
+          )
+        }
+        if (!NAME_RE.test(arg)) {
+          throw new SpringError(
+            `invalid project name "${arg}" — must match /^[a-z0-9][a-z0-9_-]*$/ (lowercase letters, digits, hyphen, underscore)`,
+          )
+        }
+        out.projectName = arg
+        break
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Convert a project name to a snake_case database default. Splits on `-`
+ * and runs of non-alphanumerics. Mirrors what 0.x spring did so the
+ * default `DB_DATABASE` value reads naturally for `my-blog` → `my_blog`.
+ */
+export function toSnakeCase(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+}

package/src/cli.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+/**
+ * `bunx @strav/spring <project>` entry. Wires argv parsing → optional
+ * interactive prompts → scaffold → `bun install`. Errors print to stderr
+ * and exit non-zero; expected (`SpringError`) errors print without the
+ * stack trace, unexpected ones include it.
+ */
+
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { parseArgs, type Template, toSnakeCase } from './args.ts'
+import { input, select } from './prompts.ts'
+import { scaffold } from './scaffold.ts'
+import { SpringError } from './spring_error.ts'
+import { STRAV_VERSION } from './version.ts'
+
+const bold = (s: string): string => `\x1b[1m${s}\x1b[0m`
+const dim = (s: string): string => `\x1b[2m${s}\x1b[0m`
+const green = (s: string): string => `\x1b[32m${s}\x1b[0m`
+const red = (s: string): string => `\x1b[31m${s}\x1b[0m`
+const cyan = (s: string): string => `\x1b[36m${s}\x1b[0m`
+
+const SPRING_VERSION = '1.0.0-alpha.28'
+
+function printUsage(): void {
+  process.stdout.write(`
+  ${bold('@strav/spring')} ${dim(`v${SPRING_VERSION}`)}
+  ${dim('Strav project scaffolder')}
+
+  ${bold('Usage:')}
+    bunx @strav/spring ${cyan('<project-name>')} [options]
+
+  ${bold('Options:')}
+    --api                       Headless REST template
+    --web                       Full-stack template ${dim('(pages auto-router + Vue islands)')}
+    --template, -t ${dim('api|web')}      Alias for --api / --web
+    --db ${dim('<name>')}                 Database name ${dim('(default: snake_case(project-name))')}
+    --no-install                Skip ${dim('bun install')} after scaffolding
+    -v, --version               Print spring version and exit
+    -h, --help                  Show this help and exit
+
+  ${bold('Examples:')}
+    bunx @strav/spring my-api --api
+    bunx @strav/spring my-app                 ${dim('# interactive prompt')}
+    bunx @strav/spring my-app --api --no-install
+`)
+}
+
+async function main(): Promise<number> {
+  const args = parseArgs(process.argv.slice(2))
+
+  if (args.help) {
+    printUsage()
+    return 0
+  }
+  if (args.version) {
+    process.stdout.write(`${SPRING_VERSION}\n`)
+    return 0
+  }
+  if (args.projectName === undefined) {
+    printUsage()
+    return 1
+  }
+
+  const dest = resolve(args.projectName)
+  if (existsSync(dest)) {
+    throw new SpringError(`directory already exists: ${dest}`)
+  }
+
+  process.stdout.write(`\n  ${bold('@strav/spring')} ${dim(`v${SPRING_VERSION}`)}\n`)
+  process.stdout.write(`  ${dim('Scaffolding a Strav app')}\n`)
+
+  let template: Template
+  if (args.template !== undefined) {
+    template = args.template
+  } else {
+    template = await select<Template>('Which template?', [
+      { value: 'api', label: 'api', description: 'Headless REST template' },
+      {
+        value: 'web',
+        label: 'web',
+        description: 'Full-stack — pages auto-router + Vue islands + plain CSS',
+      },
+    ])
+  }
+
+  const dbName = args.dbName ?? (await input('Database name', toSnakeCase(args.projectName)))
+
+  process.stdout.write('\n')
+  const result = await scaffold({
+    projectName: args.projectName,
+    template,
+    dbName,
+    dest,
+    stravVersion: STRAV_VERSION,
+  })
+  process.stdout.write(`  ${green('+')} wrote ${result.files.length} files into ${dest}\n`)
+
+  if (!args.noInstall) {
+    process.stdout.write(`  ${dim('…')} installing dependencies\n`)
+    const proc = Bun.spawn(['bun', 'install'], {
+      cwd: dest,
+      stdout: 'ignore',
+      stderr: 'pipe',
+    })
+    const code = await proc.exited
+    if (code !== 0) {
+      const stderr = await new Response(proc.stderr).text()
+      throw new SpringError(`bun install failed (exit ${code}):\n${stderr}`)
+    }
+    process.stdout.write(`  ${green('+')} installed dependencies\n`)
+  } else {
+    process.stdout.write(`  ${dim('-')} skipped install (--no-install)\n`)
+  }
+
+  process.stdout.write(`\n  ${green('Done!')} Next steps:\n\n`)
+  process.stdout.write(`    ${dim('$')} cd ${args.projectName}\n`)
+  if (args.noInstall) process.stdout.write(`    ${dim('$')} bun install\n`)
+  process.stdout.write(`    ${dim('$')} bun strav serve\n\n`)
+  process.stdout.write(`  ${dim('Then open http://localhost:3000')}\n\n`)
+  return 0
+}
+
+try {
+  process.exit(await main())
+} catch (err) {
+  if (err instanceof SpringError) {
+    process.stderr.write(`\n  ${red('✗')} ${err.message}\n\n`)
+    process.exit(1)
+  }
+  process.stderr.write(`\n  ${red('✗ internal error')}\n`)
+  process.stderr.write(`  ${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n\n`)
+  process.exit(1)
+}

package/src/index.ts

@@ -1,176 +1,10 @@
-#!/usr/bin/env bun
-import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
-import { select, input } from './prompts.ts'
-import { scaffold, type ScaffoldOptions } from './scaffold.ts'
-import pkg from '../package.json'
-
-const VERSION = pkg.version
-
-// ── Colors ──────────────────────────────────────────────────────────
-
-const bold = (s: string) => `\x1b[1m${s}\x1b[0m`
-const dim = (s: string) => `\x1b[2m${s}\x1b[0m`
-const green = (s: string) => `\x1b[32m${s}\x1b[0m`
-const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`
-const red = (s: string) => `\x1b[31m${s}\x1b[0m`
-
-// ── Arg parsing ─────────────────────────────────────────────────────
-
-interface ParsedArgs {
-  projectName?: string
-  template?: 'api' | 'web'
-  db?: string
-  help?: boolean
-}
-
-function parseArgs(): ParsedArgs {
-  const args = process.argv.slice(2)
-  const result: ParsedArgs = {}
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i]
-
-    if (arg === '--help' || arg === '-h') {
-      result.help = true
-    } else if (arg === '--api') {
-      result.template = 'api'
-    } else if (arg === '--web') {
-      result.template = 'web'
-    } else if (arg === '--template' || arg === '-t') {
-      const val = args[++i]
-      if (val === 'api' || val === 'web') {
-        result.template = val
-      } else {
-        console.error(red(`  Invalid template: ${val}. Use "api" or "web".`))
-        process.exit(1)
-      }
-    } else if (arg === '--db') {
-      result.db = args[++i]
-    } else if (arg && !arg.startsWith('-') && !result.projectName) {
-      result.projectName = arg
-    }
-  }
-
-  return result
-}
-
-function printUsage(): void {
-  console.log(`
-  ${bold('@strav/spring')} ${dim(`v${VERSION}`)}
-  ${dim('The Rite of the Bun ecosystem')}
-
-  ${bold('Usage:')}
-    bunx @strav/spring ${cyan('<project-name>')} [options]
-
-  ${bold('Options:')}
-    --api                     Headless REST API template
-    --web                     Full-stack template with Vue islands and views
-    --template, -t ${dim('api|web')}    Alias for --api / --web
-    --db ${dim('<name>')}               Database name (default: project name)
-    -h, --help                Show this help message
-
-  ${bold('Examples:')}
-    bunx @strav/spring my-blog --web
-    bunx @strav/spring my-api --api
-    bunx @strav/spring my-app              ${dim('# interactive prompt')}
-  `)
-}
-
-function toSnakeCase(name: string): string {
-  return name
-    .replace(/([A-Z])/g, '_$1')
-    .toLowerCase()
-    .replace(/[-\s]+/g, '_')
-    .replace(/^_+|_+$/g, '')
-    .replace(/_+/g, '_')
-}
-
-// ── Main ────────────────────────────────────────────────────────────
-
-async function main(): Promise<void> {
-  const args = parseArgs()
-
-  if (args.help) {
-    printUsage()
-    process.exit(0)
-  }
-
-  console.log()
-  console.log(`  ${bold('@strav/spring')} ${dim(`v${VERSION}`)}`)
-  console.log(`  ${dim('The rite of the Bun ecosystem')}`)
-  console.log()
-
-  // Project name
-  if (!args.projectName) {
-    printUsage()
-    process.exit(1)
-  }
-
-  const projectName = args.projectName
-  const root = resolve(projectName)
-
-  // Validate
-  if (existsSync(root)) {
-    console.error(red(`  Directory "${projectName}" already exists.`))
-    process.exit(1)
-  }
-
-  if (!/^[a-zA-Z0-9_-]+$/.test(projectName)) {
-    console.error(
-      red(`  Invalid project name. Use only letters, numbers, hyphens, and underscores.`)
-    )
-    process.exit(1)
-  }
-
-  // Template
-  let template = args.template
-  if (!template) {
-    template = (await select('Which template?', [
-      { label: 'web', value: 'web', description: 'Full-stack with Vue islands, views, and sessions' },
-      { label: 'api', value: 'api', description: 'Headless REST API with CORS enabled' },
-    ])) as 'api' | 'web'
-  }
-
-  // Database name
-  const defaultDb = toSnakeCase(projectName)
-  const dbName = args.db ?? defaultDb
-
-  console.log()
-
-  // Scaffold
-  const opts: ScaffoldOptions = { projectName, template, dbName }
-  await scaffold(root, opts)
-  console.log(`  ${green('+')} Scaffolded project files`)
-
-  // Install dependencies
-  console.log(`  ${dim('...')} Installing dependencies`)
-  const install = Bun.spawn(['bun', 'install'], { cwd: root, stdout: 'ignore', stderr: 'pipe' })
-  const exitCode = await install.exited
-
-  if (exitCode !== 0) {
-    const stderr = await new Response(install.stderr).text()
-    console.error(red(`  Failed to install dependencies:`))
-    console.error(dim(`  ${stderr}`))
-    process.exit(1)
-  }
-
-  console.log(`  ${green('+')} Installed dependencies`)
-
-  // Done
-  console.log()
-  console.log(`  ${green('Project created successfully!')}`)
-  console.log()
-  console.log(`  Next steps:`)
-  console.log()
-  console.log(`    ${dim('$')} cd ${projectName}`)
-  console.log(`    ${dim('$')} bun --hot index.ts`)
-  console.log()
-  console.log(`  ${dim('Then open http://localhost:3000')}`)
-  console.log()
-}
-
-main().catch(err => {
-  console.error(red(`  Error: ${err instanceof Error ? err.message : err}`))
-  process.exit(1)
-})
+/**
+ * Public barrel for `@strav/spring`. The package's primary surface is the
+ * CLI (`bin: @strav/spring`); the exports here are the programmatic API
+ * used by tests and any tool that wants to embed scaffolding.
+ */
+
+export { type ParsedArgs, parseArgs, type Template, toSnakeCase } from './args.ts'
+export { type ScaffoldOptions, type ScaffoldResult, scaffold } from './scaffold.ts'
+export { SpringError } from './spring_error.ts'
+export { STRAV_VERSION } from './version.ts'