@carlos-tzin/tzin 1.0.5 → 1.0.7

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## 1.0.7 — 2026-09-27
+
+The `tzin` CLI was announced as a headline feature but was **not reachable** in
+a published install. `npm run dev` in a freshly scaffolded app failed with
+`sh: 1: tzin: not found`, and `npx tzin dev` in the docs 404'd because no
+unscoped `tzin` package exists on npm. Fixed here.
+
+### Fixed
+
+- **`bin` field added to `package.json`** — `@carlos-tzin/tzin` now installs a
+  `tzin` executable into `node_modules/.bin`, so the `create-tzin` node
+  template (`"dev": "tzin dev"`, `"build": "tzin build"`) works after
+  `npm install`.
+- **Shebang in `src/cli.ts`** — `dist/cli.js` is now a runnable binary. `tsc`
+  preserves it on emit.
+- **`dev` no longer resolves a `.ts` file from `dist/`** — the CLI pointed
+  `tsx watch` at `./dev-server.ts` relative to itself, which only exists in
+  `src/`. In the published package the watcher died with
+  `ERR_MODULE_NOT_FOUND: .../dist/dev-server.ts`. It now resolves the sibling
+  module for both layouts (`.js` when built, `.ts` when run from source).
+- **`tzin build` / `tzin dev` no longer return before their child exits** —
+  both spawned `tsc` / `tsx watch` and then called `process.exit(0)`, so
+  `tzin build` reported success (exit 0) even with type errors and the dev
+  server was orphaned. The CLI now waits and forwards the child's exit code,
+  breaking a CI build on a type error instead of shipping stale output.
+- **Tool resolution** — `tsx` / `tsc` / `wrangler` are now taken from the
+  project's own `node_modules/.bin` (walking up from cwd). The npx fallback
+  pins the right package (`--package typescript tsc`); previously `npx tsc`
+  without a local install ran an unrelated third-party `tsc` package.
+
+### Also fixed (found while verifying the above — both shipped broken in 1.0.6)
+
+- **`signJwt` / `verifyJwt` threw in every consumer install.**
+  `src/auth.ts` used a bare `require('node:crypto')` inside an ESM package,
+  so `dist/auth.js` shipped as `require` + top-level `await` and blew up with
+  `ReferenceError: Cannot determine intended module format` /
+  `ERR_AMBIGUOUS_MODULE_SYNTAX` on the first call. The unit tests passed
+  because Vitest's module runner injects a `require` shim, so nothing
+  exercised the published artifact. Now a static `import`.
+- **`loadConfig()` silently ignored every config file.** Same bare `require`
+  in `src/config.ts`, swallowed by the surrounding `try/catch` and turned into
+  a `null` return, so `port` / `openapi` / `routes` from `tzin.config.*` never
+  applied. Now uses `createRequire(import.meta.url)`, which also lets Node load
+  ESM `.js` and `.mjs` configs.
+
+### Docs
+
+- Replaced every `npx tzin dev` / `npx tzin build` (which 404) with
+  `npm run dev` / `npm run build`, plus `npx --package @carlos-tzin/tzin tzin dev`
+  for one-off runs without a local install.
+
+### Tests
+
+- `test/cli.test.ts`: asserts the `bin` mapping, the shebang in source and
+  build output, that `build` waits for `tsc` and propagates a non-zero exit
+  code, and that `dev` from the built layout finds `dev-server` instead of
+  crashing.
+- `test/cli.test.ts`: runs the built `dist/` in a plain node process to assert
+  JWT signing, `loadConfig`, and a served app work outside Vitest's transform
+  (the gap that let the `require` bugs reach npm).
+
+## 1.0.6 — 2026-09-22
+
+Deployment fixes after the 1.0.5 release. No API changes.
+
+### Templates
+
+- `create-tzin/templates/node/src/bus.ts`: `import('ioredis' as string)`
+  — the dynamic import was being resolved by `tsc` at compile time, so a
+  freshly scaffolded app (without `ioredis` installed) failed to build with
+  `Cannot find module 'ioredis'`. Now it typechecks and runs with zero new
+  dependencies; `ioredis` is only fetched at runtime when `REDIS_URL` is set.
+
+### Docker
+
+- `Dockerfile` HEALTHCHECK now hits `/openapi.json` instead of `/health`.
+  The node template mounts `bearerAuth` on every route, so `/health` returns
+  401 and the healthcheck would always fail. `/openapi.json` is public.
+
+### Compose / docs
+
+- `docker-compose.yml`: removed the `TZIN_BUS=redis` env var (the framework
+  never read it — clustering is enabled by `REDIS_URL` via `src/bus.ts`).
+  Added a comment that `build: .` points at the app root, not the framework
+  repo.
+- `docs/deployment.md` env-var table: `TZIN_BUS` → `REDIS_URL`.
+
 ## 1.0.5 — 2026-09-21
 
 Deployment polish + release automation. No API changes to the framework core.
@@ -40,8 +127,8 @@ Deployment polish + release automation. No API changes to the framework core.
 
 - `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
+- `.github/workflows/release.yml`: tag-triggered CI (build + tests only);
+  publishing is manual with the npm token in `~/.npmrc` (no repo secret)
 
 ## 1.0.4 — Node 20 compatibility fix
 

package/README.md

@@ -8,6 +8,7 @@
 [![CI](https://github.com/Tzinny-dev/tzin/actions/workflows/ci.yml/badge.svg)](https://github.com/Tzinny-dev/tzin/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@carlos-tzin/tzin)](https://www.npmjs.com/package/@carlos-tzin/tzin)
 [![Donate](https://img.shields.io/badge/Donate-PayPal-00457C?logo=paypal&logoColor=white)](https://paypal.me/carlostzin)
+[![Buy Me A Coffee](https://img.shields.io/badge/Buy_Me_A_Coffee-FFDD00?logo=buy-me-a-coffee&logoColor=black)](https://buymeacoffee.com/tzinny)
 
 **Status: stable (1.0.x).** The core works end-to-end (see [Benchmarks](#benchmarks));
 1.0.0 shipped the stable API, and 1.0.2 adds test coverage gates, a wider CI
@@ -25,6 +26,8 @@ npx create-tzin my-app
 
 ## Documentation
 
+Hosted site: **[tzin.tzinny.com](https://tzin.tzinny.com)**
+
 - **[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
@@ -203,8 +206,15 @@ export const app = createApp([getUserRoute], {
 ### 4. Run
 
 ```bash
-npx tzin dev    # dev server at http://localhost:3000
-npx tzin build  # production build
+npm run dev    # tzin dev  -> dev server at http://localhost:3000
+npm run build  # tzin build -> production build
+```
+
+The `tzin` binary ships with the package, so these scripts work after `npm install`. Without
+a local install, run it through npm exec:
+
+```bash
+npx --package @carlos-tzin/tzin tzin dev
 ```
 
 ## CLI

package/dist/auth.js

@@ -1,3 +1,4 @@
+import { createHmac } from 'node:crypto';
 import { defineContext } from './context.js';
 // ── Context Key ──────────────────────────────────────────────────────
 /** Typed key for the authenticated user */
@@ -10,7 +11,6 @@ function base64UrlDecode(data) {
     return Buffer.from(data, 'base64url').toString();
 }
 function hmacSign(data, secret) {
-    const { createHmac } = require('node:crypto');
     return createHmac('sha256', secret).update(data).digest('base64url');
 }
 /**

package/dist/cli.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/cli.js

@@ -1,8 +1,51 @@
+#!/usr/bin/env node
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { resolve } from 'node:path';
+import { resolve, dirname } from 'node:path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
 const [, , cmd, ...rest] = process.argv;
+// Published package ships dist/*.js, repo runs from src/*.ts — pick the one that exists.
+function siblingModule(name) {
+    const js = fileURLToPath(new URL(`./${name}.js`, import.meta.url));
+    if (existsSync(js))
+        return js;
+    const ts = fileURLToPath(new URL(`./${name}.ts`, import.meta.url));
+    if (existsSync(ts))
+        return ts;
+    console.error(`tzin: cannot locate ${name} (looked for ${js} and ${ts})`);
+    process.exit(1);
+}
+// npm package that provides each binary (never assume bin name == package name:
+// `npx tsc` without typescript installed runs an unrelated third-party `tsc`).
+const TOOL_PACKAGE = { tsc: 'typescript' };
+const isWin = process.platform === 'win32';
+function localBin(name, cwd) {
+    const exe = isWin ? `${name}.cmd` : name;
+    let dir = cwd;
+    for (;;) {
+        const candidate = resolve(dir, 'node_modules', '.bin', exe);
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+// Prefer the project's own binary; only fall back to npx (pinned to the right
+// package) when the tool is not installed locally.
+function runTool(name, args, cwd) {
+    const local = localBin(name, cwd);
+    if (local)
+        return spawn(local, args, { cwd, stdio: 'inherit' });
+    const pkg = TOOL_PACKAGE[name] ?? name;
+    console.error(`tzin: ${name} not found in ${cwd} (install it to pin the version)`);
+    return spawn('npx', ['--yes', '--package', pkg, name, ...args], {
+        cwd,
+        stdio: 'inherit',
+        shell: isWin,
+    });
+}
 let matched = false;
 function usage() {
     console.error(`tzin CLI
@@ -22,6 +65,7 @@ if (!cmd || cmd === '--help' || cmd === '-h')
 // ── dev ──────────────────────────────────────────────────────────────
 if (cmd === 'dev') {
     matched = true;
+    const cwd = process.cwd();
     let entry = '';
     let port = '3000';
     const portFlag = rest.indexOf('--port');
@@ -30,15 +74,17 @@ if (cmd === 'dev') {
     const entryArg = rest.find((a) => !a.startsWith('-'));
     if (entryArg)
         entry = entryArg;
-    const devServer = fileURLToPath(new URL('./dev-server.ts', import.meta.url));
-    const args = ['tsx', 'watch', '--clear-screen=false', devServer];
+    const devServer = siblingModule('dev-server');
+    const args = ['watch', '--clear-screen=false', devServer];
     if (entry)
         args.push(entry);
     args.push('--port', port);
-    const child = spawn('npx', args, { stdio: 'inherit' });
+    const child = runTool('tsx', args, cwd);
     process.on('SIGINT', () => child.kill('SIGINT'));
-    child.on('exit', (code) => process.exit(code ?? 0));
-    process.exit(0);
+    process.on('SIGTERM', () => child.kill('SIGTERM'));
+    // Stay alive until the watcher exits — the parent must not return the
+    // prompt (or npm's exit code) while the dev server is still running.
+    child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)));
 }
 // ── build ─────────────────────────────────────────────────────────────
 if (cmd === 'build') {
@@ -55,17 +101,15 @@ if (cmd === 'build') {
         process.exit(1);
     }
     console.log('Building...');
-    const child = spawn('npx', ['tsc', '-p', 'tsconfig.json'], {
-        cwd,
-        stdio: 'inherit',
-    });
+    const child = runTool('tsc', ['-p', 'tsconfig.json'], cwd);
     child.on('exit', (code) => {
         if (code === 0) {
             console.log('\n✓ Build complete → dist/');
         }
         process.exit(code ?? 1);
     });
-    process.exit(0);
+    // NOTE: no trailing process.exit(0) — it would return success to the
+    // caller before tsc finishes (and mask type errors).
 }
 // ── deploy ────────────────────────────────────────────────────────────
 if (cmd === 'deploy') {
@@ -86,105 +130,102 @@ if (cmd === 'deploy') {
             console.error('No wrangler.toml found. Run: npx wrangler init');
             process.exit(1);
         }
-        const child = spawn('npx', ['wrangler', 'deploy'], {
-            cwd,
-            stdio: 'inherit',
-        });
+        const child = runTool('wrangler', ['deploy'], cwd);
         child.on('exit', (code) => process.exit(code ?? 1));
-        process.exit(0);
     }
-    // Default: Node
-    if (target !== 'node') {
+    else if (target === 'node') {
+        nodeDeploy();
+    }
+    else {
         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,
-        stdio: 'inherit',
-    });
-    build.on('exit', (code) => {
-        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?');
+    function nodeDeploy() {
+        // Check for tsconfig
+        if (!existsSync(resolve(cwd, 'tsconfig.json'))) {
+            console.error('No tsconfig.json found');
             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('Building for production...');
+        const build = runTool('tsc', ['-p', 'tsconfig.json'], cwd);
+        build.on('exit', (code) => {
+            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');
             }
-            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);
-    }
-    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);
+            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);
         }
-        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);
+        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(`Pushing ${dockerTag}...`);
-            const pushChild = spawn('docker', ['push', dockerTag], { cwd, stdio: 'inherit' });
-            pushChild.on('exit', (pushCode) => process.exit(pushCode ?? 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 ─────────────────────────────────────────────────────────

package/dist/config.js

@@ -1,5 +1,6 @@
 import { resolve } from 'node:path';
 import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 const CONFIG_FILES = [
     'tzin.config.ts',
     'tzin.config.js',
@@ -16,8 +17,9 @@ export function loadConfig(cwd = process.cwd()) {
                     // Return null for now - will be handled by tsx loader
                     return null;
                 }
-                // For .js/.mjs, import dynamically
-                const config = require(path);
+                // createRequire, not a bare require(): the package is ESM, where a
+                // bare require() is undefined and would silently drop the config.
+                const config = createRequire(import.meta.url)(path);
                 return config.default || config;
             }
             catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carlos-tzin/tzin",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "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",
@@ -26,6 +26,9 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "tzin": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",