bazis 0.96.1 → 0.96.2

package/README.md

@@ -7,18 +7,58 @@ per-environment defaults, JWT, WebSocket, gRPC, background services, AI agents
 and a CLI that scaffolds, runs, tests and compiles your app into a single
 executable.
 
-The package ships TypeScript sources and runs on Bun only (≥ 1.4.0). There is
-no build step and no separate type package.
+## Requirements
 
-## Quick start
+- **Bun 1.4.0 or newer. Node.js and Deno are not supported.** The package
+  ships TypeScript sources with standard decorators and no build step; Bun
+  runs them directly. Node.js refuses to load TypeScript from `node_modules`
+  (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`), and the runtime uses Bun
+  APIs throughout: `Bun.serve`, `Bun.SQL`, the built-in Redis client,
+  `bun:test`, `bun build --compile`.
+- TypeScript 5.9 or newer as a peer dependency: the code generator reads
+  your sources through the TypeScript compiler API. Nothing is compiled to
+  JavaScript.
+- PostgreSQL for the ORM.
+- Qualified platforms: macOS arm64, Linux x64 and arm64.
+
+## Install
+
+The package is `bazis` on npm. Install
+it with Bun; `npm install` would download it too, but the code only runs on Bun.
+
+**A new project** (recommended): the CLI creates the app and adds the
+dependency `"bazis": "^<current version>"`:
 
 ```sh
-bunx bazis new MyApp
+bunx bazis new MyApp      # creates ./my-app; nothing is copied, the package comes from npm
 cd my-app
-bun install
+bun install               # downloads bazis and its peer dependency typescript
 bunx bazis dev            # GET http://127.0.0.1:3000/health
 ```
 
+**An existing Bun project:**
+
+```sh
+bun add bazis             # or a fixed version: bun add bazis@0.96.2
+bun add -d typescript @types/bun
+```
+
+Then take `tsconfig.json`, `bazis.config.json` and `src/index.ts` from a
+project made by `bazis new` as the starting point, and run `bunx bazis codegen`.
+
+| Task | Command |
+| --- | --- |
+| Show the installed version | `bun pm ls \| grep bazis` |
+| Update within the version range | `bun update bazis` |
+| Move to the latest release | `bun add bazis@latest` |
+| A project that must build without npm access | `bunx bazis new MyApp --vendor` (copies the package into `vendor/bazis`) |
+
+Every release is published from GitHub Actions with
+[npm provenance](https://docs.npmjs.com/generating-provenance-statements): the
+npm page shows the source commit and the workflow that built it. The release
+tarball is also attached to each
+[GitHub Release](https://github.com/asus97178/bazis/releases).
+
 `bazis new` creates a project with `src/index.ts`, a root `AppModule`,
 `bazis.config.json`, scripts, a `/health` test and an `.env.example`.
 
@@ -26,7 +66,7 @@ bunx bazis dev            # GET http://127.0.0.1:3000/health
 
 | Command | What it does |
 | --- | --- |
-| `bazis new <Name>` | Create a project in `./<name>` |
+| `bazis new <Name> [--vendor]` | Create a project in `./<name>` that depends on `bazis` from npm; `--vendor` copies the package into `vendor/bazis` instead |
 | `bazis g module <Name> --empty\|--minimal\|--full` | Add a module: empty; CRUD with ORM, validation and paging; or the same with auth guards |
 | `bazis g pack <Name> --parts a,b` | Add a composite module made of several atomic ones |
 | `bazis codegen` | Regenerate dependency wiring into `src/generated/bazis` |

package/cli/generateProject.ts

@@ -8,8 +8,10 @@ export interface GenerateProjectOptions {
   readonly outputPath?: string;
   /** Local Bazis package source; defaults to this checkout's src/bazis. */
   readonly frameworkPath?: string;
-  /** Opt into a live link to the source checkout instead of a portable snapshot. */
+  /** Opt into a live link to the source checkout instead of the npm dependency. */
   readonly linkFramework?: boolean;
+  /** Copy the package into vendor/bazis instead of depending on npm (offline projects). */
+  readonly vendor?: boolean;
   readonly dryRun?: boolean;
 }
 
@@ -18,8 +20,11 @@ export interface GenerateProjectResult {
   /** Application scaffold files; framework sources are summarized separately. */
   readonly files: readonly string[];
   readonly dryRun: boolean;
-  readonly frameworkMode: "snapshot" | "link";
+  /** registry: `"bazis": "^<version>"` from npm; snapshot: vendor/bazis copy; link: `file:` to a checkout. */
+  readonly frameworkMode: FrameworkMode;
   readonly frameworkFileCount: number;
+  /** The dependency written to package.json. */
+  readonly dependency: string;
 }
 
 /** Create a separate application without mutating the framework checkout. */
@@ -35,16 +40,17 @@ export async function generateProject(options: GenerateProjectOptions): Promise<
   const projectDir = path.join(parent, path.basename(requested));
   if (await exists(projectDir)) throw new Error(`Project path already exists: ${projectDir}`);
 
+  if (options.linkFramework && options.vendor) throw new Error("--link-framework and --vendor cannot be combined.");
   const frameworkDir = await resolveFramework(options.frameworkPath);
   if (projectDir.startsWith(`${frameworkDir}${path.sep}`)) {
     throw new Error("Project directory must be outside the Bazis package.");
   }
   const dependencyPath = path.relative(projectDir, frameworkDir).replaceAll("\\", "/");
-  const frameworkMode = options.linkFramework ? "link" : "snapshot";
-  const frameworkFiles = options.linkFramework ? [] : await collectFrameworkFiles(frameworkDir);
-  const dependency = options.linkFramework
+  const frameworkMode: FrameworkMode = options.linkFramework ? "link" : options.vendor ? "snapshot" : "registry";
+  const frameworkFiles = frameworkMode === "snapshot" ? await collectFrameworkFiles(frameworkDir) : [];
+  const dependency = frameworkMode === "link"
     ? `file:${dependencyPath.startsWith(".") ? dependencyPath : `./${dependencyPath}`}`
-    : "file:./vendor/bazis";
+    : frameworkMode === "snapshot" ? "file:./vendor/bazis" : `^${await frameworkVersion(frameworkDir)}`;
   const files = buildProjectFiles(name, dependency, frameworkMode);
   if (!options.dryRun) {
     const staged = await mkdtemp(path.join(parent, `.${name}.bazis-`));
@@ -67,7 +73,16 @@ export async function generateProject(options: GenerateProjectOptions): Promise<
     }
   }
   return { projectDir, files: files.map(([relative]) => path.join(projectDir, relative)), dryRun: options.dryRun === true,
-    frameworkMode, frameworkFileCount: frameworkFiles.length };
+    frameworkMode, frameworkFileCount: frameworkFiles.length, dependency };
+}
+
+export type FrameworkMode = "registry" | "snapshot" | "link";
+
+/** The version the CLI belongs to; a new project depends on the same release line. */
+async function frameworkVersion(directory: string): Promise<string> {
+  const version = JSON.parse(await readFile(path.join(directory, "package.json"), "utf8")).version;
+  if (typeof version !== "string" || !/^\d+\.\d+\.\d+$/.test(version)) throw new Error(`Bazis package has no release version: ${String(version)}`);
+  return version;
 }
 
 /** Package sources only: do not carry checkout state, dependencies or test fixtures. */
@@ -122,7 +137,7 @@ async function exists(file: string): Promise<boolean> {
   }
 }
 
-function buildProjectFiles(name: string, dependency: string, frameworkMode: "snapshot" | "link"): readonly (readonly [string, string])[] {
+function buildProjectFiles(name: string, dependency: string, frameworkMode: FrameworkMode): readonly (readonly [string, string])[] {
   const manifest = {
     name, version: "0.1.0", private: true, type: "module",
     scripts: {
@@ -156,7 +171,9 @@ function buildProjectFiles(name: string, dependency: string, frameworkMode: "sna
     ["docs/architecture/MODULE_ARCHITECTURE.md", "# Application module architecture\n\n`src/index.ts` calls `runApp`; `src/app/modules/App.module.ts` composes feature modules through `imports`. The application root owns no domain logic.\n\nOne self-contained function is an atomic module. It owns its data, services, HTTP and background handlers. A composite module is only for several independent functions; its root does composition. Layers and file counts alone do not create submodules.\n\nCreate new modules only with `bunx bazis g module <Name> --empty|--minimal|--full` or `bunx bazis g pack <Name> --parts <a,b>`. Before implementing, define the responsibility and public entries, then fill in the generated `MODULE.md`: fields, errors, dependencies, exports and checks. Use the public APIs of the `bazis` package and its DI and ORM. Do not edit `src/generated/` by hand; run `bunx bazis codegen`.\n\n`--minimal` creates a sample CRUD with the ORM. To run it the application needs a database provider and a ready schema. For a first function without a database use `--empty`. Check types and the binary build after changes that affect startup.\n"],
     ["src/app/modules/App.module.ts", 'import { Module } from "bazis/core/di";\n\n@Module({ imports: [], exports: [] })\nexport class AppModule {}\n'],
     ["src/index.ts", 'import { runApp } from "bazis/core/app";\nimport { AppModule } from "./app/modules/App.module";\nimport { registerBazisGeneratedRuntime } from "./generated/bazis/runtime";\n\nawait registerBazisGeneratedRuntime();\nawait runApp(AppModule, { http: { hostname: process.env.HOST ?? "127.0.0.1", port: Number(process.env.PORT ?? 3000), health: true } });\n'],
-    ["README.md", `# ${name}\n\nAn [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "snapshot"
+    ["README.md", `# ${name}\n\nA [bazis](https://www.npmjs.com/package/bazis) application. ${frameworkMode === "registry"
+      ? "The framework comes from npm as the `bazis` dependency; update it with `bun update bazis`."
+      : frameworkMode === "snapshot"
       ? "The framework package is copied to `vendor/bazis`; keep it in Git and move it with the project. The framework checkout is no longer needed. Framework updates do not reach this copy automatically."
       : "The `bazis` dependency links an external local checkout (`--link-framework`). Moving the project needs the same package and an updated path in `package.json`."}\nRead the [local architecture](docs/architecture/MODULE_ARCHITECTURE.md) before changing modules.\n\nNeeds Bun ≥ 1.4.0. Settings go to \`.env\` (example: \`.env.example\`).\n\n\`\`\`sh\nbun install\nbunx bazis dev\n# GET http://127.0.0.1:3000/health\n# If the port is busy: PORT=3100 bunx bazis dev\n\`\`\`\n\nAdd an atomic module from the project root: \`bunx bazis g module Task --empty\`.\nAfter filling in its passport and implementation, run \`bunx bazis codegen\`.\nTests: \`bunx bazis test\`. Typecheck: \`bunx bazis build\`. Binary: \`bunx bazis build --bin\`, run it with \`bun run start\`.\n\n\`--minimal\` creates a sample CRUD with paging (20 records by default, at most 100 over HTTP); it needs a database provider and a schema to run. The service returns \`PageResult\`; the HTTP controller builds JSON:API. \`DbContext.saveChanges()\` saves every change of its context. In ORM predicates combine conditions with \`.and()\` and \`.or()\`; codegen rejects \`&&\` and \`||\` between predicates.\n`],
   ];

package/cli/main.ts

@@ -22,7 +22,8 @@ export const USAGE = `Usage:
 Generation options:
   --path <directory>    Exact project directory (new only; default: ./<name>)
   --framework <path>    Local bazis package directory (new only)
-  --link-framework      Link that checkout instead of copying vendor/bazis (new only)
+  --vendor              Copy the package into vendor/bazis instead of the npm dependency (new only)
+  --link-framework      Depend on that local checkout through a file: link (new only)
   --modules-root <path>  Modules root (default: src/app/modules)
   --app-module <path>    Host module (default: {modules-root}/App.module.ts)
   --empty               Module entry and MODULE.md only
@@ -83,10 +84,12 @@ export async function runCli(argv: readonly string[], runtime: CliRuntime = defa
     if (parsed.kind === "test") return await runTest(process.cwd(), parsed.args, runtime.codegen);
     if (parsed.kind === "build") return await runBuild(process.cwd(), { bin: parsed.bin, outfile: parsed.outfile }, runtime.codegen, runtime.log);
     if (parsed.kind === "new") {
-      const result = await generateProject({ name: parsed.name, outputPath: parsed.outputPath, frameworkPath: parsed.frameworkPath, linkFramework: parsed.linkFramework, dryRun: parsed.dryRun });
+      const result = await generateProject({ name: parsed.name, outputPath: parsed.outputPath, frameworkPath: parsed.frameworkPath, linkFramework: parsed.linkFramework, vendor: parsed.vendor, dryRun: parsed.dryRun });
       runtime.log(`[bazis] ${result.dryRun ? "planned" : "created"} project: ${result.projectDir}`);
       for (const file of result.files) runtime.log(`  + ${file}`);
-      runtime.log(result.frameworkMode === "snapshot"
+      runtime.log(result.frameworkMode === "registry"
+        ? `[bazis] Framework dependency: "bazis": "${result.dependency}" from npm.`
+        : result.frameworkMode === "snapshot"
         ? `[bazis] vendor/bazis: ${result.frameworkFileCount} package files${result.dryRun ? " planned" : " copied"}. Keep this directory in version control.`
         : "[bazis] Framework is linked to an external checkout (--link-framework).");
       if (!result.dryRun) runtime.log(`[bazis] Next: cd ${result.projectDir} && bun install && bunx bazis dev`);

package/cli/parseCli.ts

@@ -18,7 +18,7 @@ export interface ParsedGenerateArgs {
 
 export type ParseCliResult =
   | { readonly kind: "help"; readonly help: boolean }
-  | { readonly kind: "new"; readonly name: string; readonly outputPath?: string; readonly frameworkPath?: string; readonly linkFramework: boolean; readonly dryRun: boolean }
+  | { readonly kind: "new"; readonly name: string; readonly outputPath?: string; readonly frameworkPath?: string; readonly linkFramework: boolean; readonly vendor: boolean; readonly dryRun: boolean }
   | { readonly kind: "generate"; readonly args: ParsedGenerateArgs }
   | { readonly kind: "codegen"; readonly target?: string }
   | { readonly kind: "dev"; readonly watch: boolean }
@@ -31,7 +31,7 @@ const GENERATOR_ALIASES = new Map<string, "module" | "pack">([
   ["pack", "pack"], ["p", "pack"], ["module-pack", "pack"],
 ]);
 const VALUE_OPTIONS = new Set(["--modules-root", "--app-module", "--parts", "--target", "--path", "--framework", "--outfile"]);
-const FLAG_OPTIONS = new Set(["--no-register", "--force", "--full", "--enterprise", "--minimal", "--empty", "--dry-run", "--no-codegen", "--link-framework", "--bin", "--watch"]);
+const FLAG_OPTIONS = new Set(["--no-register", "--force", "--full", "--enterprise", "--minimal", "--empty", "--dry-run", "--no-codegen", "--link-framework", "--vendor", "--bin", "--watch"]);
 
 /** Parsing is pure: help and invalid input can never start generation. */
 export function parseCliArgs(argv: readonly string[]): ParseCliResult {
@@ -64,18 +64,19 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
   const [command, generatorToken, name] = positional;
   const target = options.get("--target");
   if (command === "new") {
-    if (positional.length !== 2) return error("Use: bazis new <Name> [--path <directory>] [--framework <directory>] [--link-framework] [--dry-run]");
+    if (positional.length !== 2) return error("Use: bazis new <Name> [--path <directory>] [--framework <directory>] [--vendor | --link-framework] [--dry-run]");
     for (const option of options.keys()) {
-      if (option !== "--path" && option !== "--framework" && option !== "--link-framework" && option !== "--dry-run") {
+      if (option !== "--path" && option !== "--framework" && option !== "--link-framework" && option !== "--vendor" && option !== "--dry-run") {
         return error(`Option ${option} is not supported by new.`);
       }
     }
+    if (options.has("--vendor") && options.has("--link-framework")) return error("--vendor and --link-framework cannot be combined.");
     try {
       parseModuleName(generatorToken!);
     } catch (cause) {
       return error(cause instanceof Error ? cause.message : String(cause));
     }
-    return { kind: "new", name: generatorToken!, outputPath: options.get("--path"), frameworkPath: options.get("--framework"), linkFramework: options.has("--link-framework"), dryRun: options.has("--dry-run") };
+    return { kind: "new", name: generatorToken!, outputPath: options.get("--path"), frameworkPath: options.get("--framework"), linkFramework: options.has("--link-framework"), vendor: options.has("--vendor"), dryRun: options.has("--dry-run") };
   }
   if (target !== undefined && !/^[a-z][a-z0-9-]*$/.test(target)) {
     return error("Target must be a codegen target name or all.");
@@ -105,7 +106,7 @@ export function parseCliArgs(argv: readonly string[]): ParseCliResult {
     return error(`Unknown command: ${command ?? "(missing)"}. Use: bazis --help`);
   }
   if (generatorToken === undefined) return error("Generator is required: module (m) or pack (p).");
-  if (options.has("--path") || options.has("--framework") || options.has("--link-framework")) return error("--path, --framework and --link-framework are only supported by new.");
+  if (options.has("--path") || options.has("--framework") || options.has("--link-framework") || options.has("--vendor")) return error("--path, --framework, --link-framework and --vendor are only supported by new.");
   const generator = GENERATOR_ALIASES.get(generatorToken);
   if (generator === undefined) return error(`Unknown generator: ${generatorToken}. Supported: module (m), pack (p)`);
   if (name === undefined) return error("Module name is required.");

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.96.1" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.96.2" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.96.1",
+  "version": "0.96.2",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",