@carlos-tzin/tzin 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,6 +1,57 @@
 # Changelog
 
-## 1.0.3 — Quality pass before wider adoption
+## 1.0.5 — 2026-09-21
+
+Deployment polish + release automation. No API changes to the framework core.
+
+### CLI deploy
+
+- `tzin deploy --target node --pack` builds with `tsc` and packs
+  `dist + package.json (+Dockerfile / docker-compose.yml / .dockerignore`
+  when present) into `<name>-<version>.tgz`
+- `tzin deploy --target node --docker <tag> [--push]` runs
+  `docker build -t <tag>` and optionally `docker push`
+- Fix: the trailing `usage()` call and a premature `process.exit(0)` killed
+  async deploy/build before the `tsc` child finished — deploy printed the
+  help text and died silently. Now gated behind a `matched` flag, unknown
+  targets error clearly (`Available: node, workers`)
+
+### Docker + docs
+
+- `Dockerfile` (multi-stage, `node:20-slim`, prod-only deps,
+  `HEALTHCHECK` on `/health`) aligned to the real node template layout
+  (`tsconfig.json` → `dist/index.js`); `.dockerignore`; `docker-compose.yml`
+  (app + Redis with healthchecks)
+- `docs/deployment.md`: Node container, Workers Durable Objects,
+  multi-node Redis recipes, exact `create-tzin → docker build` flow
+- `examples/workers-quickstart/` + `.md`: copy-paste wrangler project
+  (DO + channels + presence); README examples table updated
+
+### Templates
+
+- All `create-tzin` templates bumped to `@carlos-tzin/tzin ^1.0.5`
+- Fix: `createApp([…, usersRoute])` nested an array inside the route list —
+  now `...usersRoute` in node/bun/workers templates
+- New optional `src/bus.ts` in the node template: `redisBus()` returns
+  `undefined` without `REDIS_URL`, ioredis-backed `MessageBus` with it
+  (lazy import, zero new deps to typecheck)
+
+### Release process
+
+- `scripts/release.mjs <patch|minor|major> [--dry-run]`: version bump,
+  template sync, CHANGELOG skeleton, commit + tag
+- `.github/workflows/release.yml`: tag-triggered npm publish via
+  Trusted Publishing (OIDC, `--provenance`), no `NPM_TOKEN` secret
+
+## 1.0.4 — Node 20 compatibility fix
+
+No API changes. CI was failing on the Node 20 floor because the WS test and the
+Workers probe relied on the global `WebSocket`, which only exists on Node ≥22.
+
+### Testing & coverage
+
+- `native websockets` test and the Workers probe use the `ws` package client
+  instead of the global `WebSocket`, keeping the Node 20 floor green
 
 No API changes. Focused on proving the stable claim in CI and on the
 type surface.

package/README.md

@@ -27,6 +27,7 @@ npx create-tzin my-app
 
 - **[API Reference](docs/api-reference.md)** — all exports, types, and options
 - **[Architecture Guide](docs/architecture.md)** — request pipeline, design decisions, internals
+- **[Deployment Guide](docs/deployment.md)** — Docker, Cloudflare Workers, multi-node clustering
 - **[Roadmap](docs/roadmap.md)** — future features
 
 ## Why another framework?
@@ -209,12 +210,12 @@ npx tzin build  # production build
 ## CLI
 
 ```bash
-tzin dev [--port N]              # dev server with hot reload
-tzin build                       # build for production
-tzin deploy --target node|workers # deploy
-tzin generate route <name>       # scaffold a route
-tzin generate middleware <name>  # scaffold middleware
-tzin generate test <name>        # scaffold a test
+tzin dev [--port N]                                # dev server with hot reload
+tzin build                                         # build for production
+tzin deploy --target node|workers [--pack] [--docker <tag> [--push]]  # deploy
+tzin generate route <name>                         # scaffold a route
+tzin generate middleware <name>                    # scaffold middleware
+tzin generate test <name>                          # scaffold a test
 ```
 
 ## Benchmarks
@@ -247,6 +248,8 @@ tzin grows **strictly linearly** (~130 types/endpoint).
 | `examples/todo-api.ts` | Node | Full CRUD: auth middleware, DI, OpenAPI, MCP |
 | `examples/mcp-demo.ts` | Node | MCP server over stdio |
 | `examples/ws-demo.ts` | Bun | WebSocket channels with presence |
+| `examples/workers-quickstart/` | Workers | Copy-paste wrangler project: DO + channels + presence |
+| `examples/workers-quickstart.md` | Workers | Same project, explained file-by-file |
 
 ## Design principles
 

package/dist/cli.js

@@ -1,15 +1,17 @@
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { resolve } from 'node:path';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 const [, , cmd, ...rest] = process.argv;
+let matched = false;
 function usage() {
     console.error(`tzin CLI
 
   Commands:
     tzin dev [entry] [--port N]     start dev server with hot reload
     tzin build                      build for production
-    tzin deploy [--target <target>] deploy (node, workers)
+    tzin deploy [--target <target>] [--pack] [--docker <tag> [--push]]
+                                     deploy (node, workers)
     tzin generate route <name>      generate a route stub
     tzin generate middleware <name>  generate a middleware stub
     tzin generate test <name>       generate a test stub`);
@@ -19,6 +21,7 @@ if (!cmd || cmd === '--help' || cmd === '-h')
     usage();
 // ── dev ──────────────────────────────────────────────────────────────
 if (cmd === 'dev') {
+    matched = true;
     let entry = '';
     let port = '3000';
     const portFlag = rest.indexOf('--port');
@@ -39,6 +42,7 @@ if (cmd === 'dev') {
 }
 // ── build ─────────────────────────────────────────────────────────────
 if (cmd === 'build') {
+    matched = true;
     const cwd = process.cwd();
     // Check for tsconfig
     if (!existsSync(resolve(cwd, 'tsconfig.json'))) {
@@ -65,9 +69,16 @@ if (cmd === 'build') {
 }
 // ── deploy ────────────────────────────────────────────────────────────
 if (cmd === 'deploy') {
+    matched = true;
     const cwd = process.cwd();
     const targetFlag = rest.indexOf('--target');
     const target = targetFlag !== -1 ? rest[targetFlag + 1] : 'node';
+    const pack = rest.includes('--pack');
+    const dockerIdx = rest.indexOf('--docker');
+    const dockerTag = dockerIdx !== -1 && rest[dockerIdx + 1] && !rest[dockerIdx + 1].startsWith('-')
+        ? rest[dockerIdx + 1]
+        : null;
+    const push = rest.includes('--push');
     if (target === 'workers') {
         console.log('Deploying to Cloudflare Workers...');
         // Check for wrangler.toml
@@ -83,6 +94,16 @@ if (cmd === 'deploy') {
         process.exit(0);
     }
     // Default: Node
+    if (target !== 'node') {
+        console.error(`Unknown deploy target: ${target}`);
+        console.error('Available: node, workers');
+        process.exit(1);
+    }
+    // Check for tsconfig
+    if (!existsSync(resolve(cwd, 'tsconfig.json'))) {
+        console.error('No tsconfig.json found');
+        process.exit(1);
+    }
     console.log('Building for production...');
     const build = spawn('npx', ['tsc', '-p', 'tsconfig.json'], {
         cwd,
@@ -92,13 +113,83 @@ if (cmd === 'deploy') {
         if (code !== 0)
             process.exit(code ?? 1);
         console.log('\n✓ Build complete');
+        afterBuild();
+    });
+    // NOTE: no trailing process.exit(0) here — the parent must stay alive
+    // until the build child exits and afterBuild() runs. Calling
+    // process.exit() here would kill the process (and the child listener)
+    // before the build finishes.
+    function afterBuild() {
+        const pkgPath = resolve(cwd, 'package.json');
+        let name = 'app';
+        let version = '0.0.0';
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+            name = String(pkg.name ?? 'app').replace(/^@/, '').replace(/\//g, '-');
+            version = String(pkg.version ?? '0.0.0');
+        }
+        catch {
+            console.error('No package.json found — is this a tzin project?');
+            process.exit(1);
+        }
+        // --pack: runnable tarball (dist + manifest + container files when present).
+        if (pack) {
+            const out = resolve(cwd, `${name}-${version}.tgz`);
+            const files = ['dist', 'package.json'];
+            for (const f of ['Dockerfile', 'docker-compose.yml', '.dockerignore']) {
+                if (existsSync(resolve(cwd, f)))
+                    files.push(f);
+            }
+            console.log(`Packing ${files.join(', ')} → ${out}`);
+            const tar = spawn('tar', ['-czf', out, ...files], { cwd, stdio: 'inherit' });
+            tar.on('exit', (tarCode) => {
+                if (tarCode !== 0)
+                    process.exit(tarCode ?? 1);
+                console.log(`\n✓ Packed ${out}`);
+                console.log(`Unpack + run: tar -xzf ${name}-${version}.tgz && node dist/index.js`);
+                if (dockerTag)
+                    dockerBuild();
+                else
+                    process.exit(0);
+            });
+            return;
+        }
+        if (dockerTag) {
+            dockerBuild();
+            return;
+        }
         console.log('Run: node dist/index.js');
+        console.log('Tip: tzin deploy --target node --pack [--docker <tag> [--push]] for a runnable artifact');
         process.exit(0);
-    });
-    process.exit(0);
+    }
+    function dockerBuild() {
+        if (!dockerTag)
+            return;
+        if (!existsSync(resolve(cwd, 'Dockerfile'))) {
+            console.error('No Dockerfile found. Copy the reference Dockerfile from the tzin repo (see docs/deployment.md).');
+            process.exit(1);
+        }
+        console.log(`Building Docker image ${dockerTag}...`);
+        const args = ['build', '-t', dockerTag, '.'];
+        const child = spawn('docker', args, { cwd, stdio: 'inherit' });
+        child.on('exit', (buildCode) => {
+            if (buildCode !== 0)
+                process.exit(buildCode ?? 1);
+            console.log(`\n✓ Image built: ${dockerTag}`);
+            if (!push) {
+                console.log(`Run: docker run -p 3000:3000 --env PORT=3000 ${dockerTag}`);
+                process.exit(0);
+                return;
+            }
+            console.log(`Pushing ${dockerTag}...`);
+            const pushChild = spawn('docker', ['push', dockerTag], { cwd, stdio: 'inherit' });
+            pushChild.on('exit', (pushCode) => process.exit(pushCode ?? 1));
+        });
+    }
 }
 // ── generate ─────────────────────────────────────────────────────────
 if (cmd === 'generate' || cmd === 'g') {
+    matched = true;
     const [sub, ...args] = rest;
     const name = args[0];
     if (!sub || !name) {
@@ -184,4 +275,5 @@ describe('${name}', () => {
     console.error('Available: route, middleware, test');
     process.exit(1);
 }
-usage();
+if (!matched)
+    usage();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Contract-first TypeScript framework. Types that scale, realtime channels with presence, and an MCP server for every API.",
   "license": "MIT",
   "author": "The tzin authors",