quick

Author: rbbydotdev

README.md

@@ -3,7 +3,7 @@
 TypeScript DSL for authoring OpenAPI 3.1+ specs. Uses [TypeBox](https://github.com/sinclairzx81/typebox) for JSON Schema with full type inference — you write TypeScript, not YAML.
 
 [![CI](https://github.com/rbbydotdev/spac/actions/workflows/ci.yml/badge.svg)](https://github.com/rbbydotdev/spac/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/spac.svg)](https://www.npmjs.com/package/spac)
+[![npm](https://img.shields.io/npm/v/@spec-spac/spac.svg)](https://www.npmjs.com/package/@spec-spac/spac)
 [![TypeScript 5.7+](https://img.shields.io/badge/TypeScript-5.7+-3178c6.svg)](https://www.typescriptlang.org/)
 
 **[Docs](https://rbbydotdev.github.io/spac/)** · **[Playground](https://rbbydotdev.github.io/spac/playground)** · **[Getting Started](https://rbbydotdev.github.io/spac/docs/tutorials/getting-started)** · **[API Reference](https://rbbydotdev.github.io/spac/docs/reference/api)**
@@ -28,32 +28,114 @@ const spec = api.emit() // valid OpenAPI 3.1 JSON
 
 Named schemas automatically hoist to `components.schemas` as `$ref`s. Groups inherit tags and security. Macros let you compose reusable route/group patterns.
 
-## Install
+## Quick start
+
+### 1. Install
 
 ```sh
 npm install @spec-spac/spac @sinclair/typebox
 ```
 
+### 2. Define your API
+
+Create `api.ts`:
+
+```ts
+import { Api, named } from '@spec-spac/spac'
+import { Type } from '@sinclair/typebox'
+
+const User = named('User', Type.Object({
+  id: Type.String(),
+  name: Type.String(),
+  email: Type.String({ format: 'email' }),
+}))
+
+const api = new Api('3.1', 'My API', { version: '1.0.0' })
+
+api.group('/users', g => {
+  g.tag('users')
+  g.get('/').response(Type.Array(User)).summary('List users')
+  g.get('/:id').params(Type.Object({ id: Type.String() })).response(User)
+  g.post('/').body(User).response(User).summary('Create user')
+})
+
+console.log(JSON.stringify(api.emit(), null, 2))
+```
+
+### 3. Run it
+
+```sh
+npx tsx api.ts > openapi.json
+```
+
+That's it — `openapi.json` is a valid OpenAPI 3.1 document with `User` hoisted to `components.schemas`.
+
 ## Packages
 
-| Package | Path | Description |
+| Package | Install | What it does |
 |---|---|---|
-| [`@spec-spac/spac`](packages/spac) | Core library | Define routes, groups, schemas, and emit OpenAPI 3.1 JSON/YAML with source maps |
-| [`@spec-spac/from-openapi`](packages/from-openapi) | Code generator | Parse an existing OpenAPI spec and emit idiomatic spac TypeScript |
-| [`@spec-spac/from-openapi-biome`](packages/from-openapi/plugins/biome) | Formatter | Biome formatter adapter for from-openapi |
-| [`@spec-spac/from-openapi-prettier`](packages/from-openapi/plugins/prettier) | Formatter | Prettier formatter adapter for from-openapi |
-| [`spac-playground`](packages/playground) | App | Split-pane CodeMirror viewer — SPAC source on the left, OpenAPI YAML on the right |
-| [`spac-vscode`](packages/spac-vscode) | Extension | VS Code extension for live OpenAPI preview |
+| [`@spec-spac/spac`](packages/spac) | `npm i @spec-spac/spac` | Core library — define routes, groups, schemas, emit OpenAPI 3.1 JSON/YAML with source maps |
+| [`@spec-spac/from-openapi`](packages/from-openapi) | `npm i -g @spec-spac/from-openapi` | CLI + library — reverse-generate spac TypeScript from an existing OpenAPI spec |
+| [`@spec-spac/from-openapi-biome`](packages/from-openapi/plugins/biome) | `npm i @spec-spac/from-openapi-biome` | Biome formatter plugin for the code generator |
+| [`@spec-spac/from-openapi-prettier`](packages/from-openapi/plugins/prettier) | `npm i @spec-spac/from-openapi-prettier` | Prettier formatter plugin for the code generator |
 
-## Quick start
+## `spac-from-openapi` CLI
+
+Already have an OpenAPI spec? Generate spac TypeScript from it:
+
+```sh
+# Preview what will be generated (dry run)
+npx @spec-spac/from-openapi petstore.json
 
-### Define routes and groups
+# Generate to a directory
+npx spac-from-openapi petstore.json --out ./generated
+
+# Strip path prefixes for cleaner grouping
+npx spac-from-openapi cloudflare.json --out ./generated \
+  --strip '/accounts/{account_id}' \
+  --strip '/zones/{zone_id}'
+```
+
+| Flag | Description |
+|------|-------------|
+| `--out <dir>` | Output directory (omit for dry-run) |
+| `--strip <prefix>` | Path prefix to strip before grouping (repeatable) |
+| `--name <name>` | Override API title |
+| `--spec-version <ver>` | Override OpenAPI version |
+| `--debug` | Enable source map support in generated code |
+
+Output structure:
+
+```
+generated/
+  index.ts              — Api setup, imports all groups
+  shared/schemas.ts     — Schemas used by 2+ groups
+  <group>/index.ts      — Routes for that group
+  <group>/schemas.ts    — Schemas local to that group
+```
+
+## Core concepts
+
+### Routes and chaining
+
+Every HTTP method returns a builder — all configuration is chained:
 
 ```ts
-const api = new Api('3.1', 'My API')
+api.get('/users/:id')
+  .params(Type.Object({ id: Type.String() }))
+  .query(Type.Object({ fields: Type.Optional(Type.String()) }))
+  .response(User)
+  .error(404, ErrorSchema)
+  .summary('Get a user by ID')
+  .operationId('getUser')
+  .tag('users')
+```
 
-api.get('/health').response(Type.Object({ ok: Type.Boolean() }))
+### Groups
 
+Groups collect routes under a shared prefix with inherited metadata:
+
+```ts
 api.group('/users', g => {
   g.tag('users')
   g.security('bearer')
@@ -65,11 +147,10 @@ api.group('/users', g => {
 
 ### Named schemas
 
+Wrap any TypeBox schema with `named()` to hoist it to `components.schemas`:
+
 ```ts
-const Pet = named('Pet', Type.Object({
-  id: Type.String(),
-  name: Type.String(),
-}))
+const Pet = named('Pet', Type.Object({ id: Type.String(), name: Type.String() }))
 // Any route referencing Pet emits { "$ref": "#/components/schemas/Pet" }
 ```
 
@@ -87,6 +168,8 @@ api.post('/items')
 
 ### Macros
 
+Reusable transforms applied via `.use()`:
+
 ```ts
 import { macro } from '@spec-spac/spac'
 
@@ -99,16 +182,9 @@ api.group('/admin', g => {
 })
 ```
 
-### Generate spac code from an existing OpenAPI spec
-
-```sh
-npx spac-from-openapi spec.json --out ./generated
-npx spac-from-openapi spec.json --out ./generated --strip '/accounts/{account_id}'
-```
-
-See [`@spec-spac/from-openapi` README](packages/from-openapi) for full CLI options.
+### Source maps
 
-### Source mapping
+Map every line of emitted YAML back to the TypeScript that produced it:
 
 ```ts
 const api = new Api('3.1', 'Petstore', { version: '1.0.0', debug: true })
@@ -120,7 +196,7 @@ result.sourceMap   // standard Source Map V3
 result.sourceTable // Map<jsonPath, SourceEntry>
 ```
 
-## Api reference
+## API reference
 
 | Method | Description |
 |---|---|
@@ -140,14 +216,6 @@ result.sourceTable // Map<jsonPath, SourceEntry>
 
 `.params()` `.query()` `.headers()` `.body()` `.response()` `.respond()` `.error()` `.summary()` `.description()` `.tag()` `.operationId()` `.deprecated()` `.security()` `.server()` `.extension()` `.use()`
 
-## Architecture
-
-```
-User code -> Api / GroupBuilder / RouteBuilder (AST) -> emitOpenApi() -> OpenAPI 3.1 JSON / YAML + Source Map V3
-```
-
-The DSL builds an AST of `RouteNode` and `GroupNode` objects. `emitOpenApi()` walks the tree, flattens routes with inherited group metadata, resolves TypeBox schemas (hoisting named schemas to `components.schemas` as `$ref`s), and produces a spec-compliant OpenAPI 3.1 document.
-
 ## Contributing
 
 See [INDEX.md](INDEX.md) for the full repo layout, build instructions, and the examples branch workflow.

package.json

@@ -4,7 +4,8 @@
   "scripts": {
     "format": "biome format --write packages/spac packages/from-openapi packages/examples packages/playground/scripts",
     "format:check": "biome format packages/spac packages/from-openapi packages/examples packages/playground/scripts",
-    "sync-examples": "bash scripts/sync-examples.sh"
+    "sync-examples": "bash scripts/sync-examples.sh",
+    "publish-pkg": "bash scripts/publish.sh"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.7"

packages/from-openapi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-spac/from-openapi",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "description": "Generate idiomatic spac TypeScript from existing OpenAPI specs",
   "license": "MIT",

packages/spac/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec-spac/spac",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "description": "TypeScript DSL for authoring OpenAPI 3.1+ specs with TypeBox schemas",
   "license": "MIT",

packages/spac/tsconfig.json

@@ -4,5 +4,6 @@
     "rootDir": "src",
     "outDir": "dist"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/__tests__", "src/**/*.test.ts"]
 }

packages/website/content/docs/index.mdx

@@ -8,36 +8,97 @@ description: TypeScript DSL for authoring OpenAPI 3.1+ specs
 ```spac
 import { Api, named } from '@spec-spac/spac'
 import { Type } from '@sinclair/typebox'
-
 const Pet = named('Pet', Type.Object({
   id: Type.String(),
   name: Type.String(),
 }))
-
 const api = new Api('3.1', 'Petstore')
 api.group('/pets', g => {
   g.get('/').response(Type.Array(Pet)).tag('pets')
   g.post('/').body(Pet).response(Pet).tag('pets')
 })
-
 export default api
 ```
 
+## Install
+
+```bash
+npm install @spec-spac/spac @sinclair/typebox
+```
+
+## Packages
+
+| Package | What it does |
+|---|---|
+| `@spec-spac/spac` | Core library — define routes, groups, schemas, emit OpenAPI 3.1 JSON/YAML with source maps |
+| `@spec-spac/from-openapi` | CLI + library — reverse-generate spac TypeScript from an existing OpenAPI spec |
+| `@spec-spac/from-openapi-biome` | Biome formatter plugin for the code generator |
+| `@spec-spac/from-openapi-prettier` | Prettier formatter plugin for the code generator |
+
 ## Why spac?
 
 - **TypeBox schemas directly** — no wrapper DSL, full JSON Schema type inference
 - **Named schemas auto-hoist** to `components.schemas` as `$ref`
 - **Group inheritance** — tags and security cascade from groups to routes
 - **Macro system** — reusable route/group/api transforms
 - **Source maps** — trace emitted YAML back to TypeScript source lines
+- **Reverse generator** — already have an OpenAPI spec? Generate spac code from it with [`spac-from-openapi`](/docs/guides/from-openapi-cli)
 
-## Documentation
+## Quick start
+
+Create `api.ts`:
+
+```ts
+import { Api, named } from '@spec-spac/spac'
+import { Type } from '@sinclair/typebox'
+
+const User = named('User', Type.Object({
+  id: Type.String(),
+  name: Type.String(),
+  email: Type.String({ format: 'email' }),
+}))
+
+const api = new Api('3.1', 'My API', { version: '1.0.0' })
 
-This documentation follows the [Diataxis](https://diataxis.fr/) framework:
+api.group('/users', g => {
+  g.tag('users')
+  g.get('/').response(Type.Array(User)).summary('List users')
+  g.post('/').body(User).response(User).summary('Create user')
+})
+
+console.log(JSON.stringify(api.emit(), null, 2))
+```
+
+Run it:
+
+```bash
+npx tsx api.ts > openapi.json
+```
+
+That's it — `openapi.json` is a valid OpenAPI 3.1 document.
+
+## `spac-from-openapi` CLI
+
+Already have an OpenAPI spec? Generate spac TypeScript from it:
+
+```bash
+npx spac-from-openapi petstore.json --out ./generated
+```
+
+Use `--strip` to clean up deeply nested paths:
+
+```bash
+npx spac-from-openapi cloudflare.json --out ./generated \
+  --strip '/accounts/{account_id}'
+```
+
+See the full [CLI reference](/docs/guides/from-openapi-cli) for all options.
+
+## Documentation
 
 <Cards>
-  <Card title="Tutorials" href="/docs/tutorials/getting-started" description="Learning-oriented walkthroughs to get you started" />
-  <Card title="Guides" href="/docs/guides/defining-routes" description="Task-oriented how-to guides for specific goals" />
-  <Card title="Explanation" href="/docs/explanation/philosophy" description="Understanding-oriented discussion of concepts and design" />
-  <Card title="Reference" href="/docs/reference/api" description="Technical API reference extracted from source" />
+  <Card title="Getting Started" href="/docs/tutorials/getting-started" description="Build your first OpenAPI spec with spac in 5 minutes" />
+  <Card title="Defining Routes" href="/docs/guides/defining-routes" description="Routes, groups, macros, and response helpers" />
+  <Card title="from-openapi CLI" href="/docs/guides/from-openapi-cli" description="Generate spac code from existing OpenAPI specs" />
+  <Card title="API Reference" href="/docs/reference/api" description="Full type reference for the Api class" />
 </Cards>

scripts/PUBLISHING.md

@@ -0,0 +1,54 @@
+# Publishing to npm
+
+## Quick start
+
+```bash
+pnpm publish-pkg <package> <patch|minor|major>
+```
+
+## Packages
+
+| Shorthand | npm package |
+|-----------|-------------|
+| `spac` | `@spec-spac/spac` |
+| `from-openapi` | `@spec-spac/from-openapi` |
+| `biome` | `@spec-spac/from-openapi-biome` |
+| `prettier` | `@spec-spac/from-openapi-prettier` |
+| `all` | All four, in dependency order |
+
+## Examples
+
+```bash
+pnpm publish-pkg spac patch           # 0.0.2 → 0.0.3
+pnpm publish-pkg spac minor           # 0.1.0
+pnpm publish-pkg from-openapi patch
+pnpm publish-pkg all patch            # bump + publish everything
+```
+
+The script builds before publishing, so you don't need to run `build` separately.
+
+## Auth
+
+**Option 1 — npm login (interactive):**
+
+```bash
+npm login
+```
+
+**Option 2 — API token (non-interactive):**
+
+Generate a token at https://www.npmjs.com/settings/~/tokens and set it:
+
+```bash
+export NPM_TOKEN=npm_xxxxxxxxxxxx
+```
+
+Add to your shell profile (`~/.zshrc`) to persist across sessions. The publish script picks it up automatically.
+
+## After publishing
+
+The script bumps `package.json` versions but doesn't commit. After publishing:
+
+```bash
+git add -A && git commit -m "release: v0.1.0" && git push
+```