okengine 0.1.4 → 0.1.6

package/README.md

@@ -2,12 +2,37 @@
 
 *"Encore's batteries and dashboard, Elysia's speed and DX, Hono's portability — without the Rust lock-in, the cloud gravity, or the source-available license."*
 
+[![npm](https://img.shields.io/npm/v/okengine.svg)](https://www.npmjs.com/package/okengine)
+[![JSR](https://jsr.io/badges/@omqkhafi/okengine)](https://jsr.io/@omqkhafi/okengine)
+[![npm](https://img.shields.io/npm/v/create-oke.svg)](https://www.npmjs.com/package/create-oke)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![Bun >=1.3](https://img.shields.io/badge/Bun-%3E%3D1.3-black.svg)](https://bun.sh)
 
-**Package:** `okengine` · **CLI:** `oke` · **License:** MIT
+**Framework:** [`okengine`](https://www.npmjs.com/package/okengine) · **CLI:** `oke` · **Scaffold:** [`create-oke`](https://www.npmjs.com/package/create-oke) · **License:** MIT
 
-JSR (`@omqkhafi/okengine`) does not support npm-style `exports` wildcards — import deep drivers (`okengine/drivers/…`) from the npm package, not JSR. The `okengine/drivers` index is available on both.
+### Install
+
+```bash
+bun add okengine                 # npm (recommended — ships the `oke` CLI)
+bunx jsr add @omqkhafi/okengine  # JSR — library API only
+bunx create-oke@latest my-app    # scaffold from npm
+```
+
+| Package | npm | JSR |
+|---|---|---|
+| Framework | [`okengine`](https://www.npmjs.com/package/okengine) | [`@omqkhafi/okengine`](https://jsr.io/@omqkhafi/okengine) |
+| Scaffold | [`create-oke`](https://www.npmjs.com/package/create-oke) | [`@omqkhafi/create-oke`](https://jsr.io/@omqkhafi/create-oke) |
+
+### npm vs JSR
+
+| Surface | npm | JSR |
+|---|---|---|
+| Library imports (`okengine`, `/client`, `/drivers`, …) | yes | yes |
+| Deep drivers (`okengine/drivers/postgres`, …) | yes | no — use `okengine/drivers`, or install from npm |
+| `oke` CLI | yes | no |
+| `create-oke` binary | yes | no — prefer `bunx create-oke@latest` from npm |
+
+JSR cannot rewrite the CLI’s dynamic imports of your app entry (`oke dev` / `oke start` / config load). Install `okengine` from npm when you need the binary. Deep driver subpaths use npm `exports` wildcards, which JSR does not support.
 
 ---
 
@@ -27,7 +52,7 @@ Eight elements cover what a backend needs. Ten exports are the whole public voca
 import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";
 ```
 
-Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Detail and comparisons live in [`docs/spec/unified-theory.md`](docs/spec/unified-theory.md).
+Batteries included for the Bun era: contract-first APIs, typed client, infrastructure primitives, Console, auth — pure TypeScript, MIT, self-hostable, no cloud lock-in. Detail and comparisons live in [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md).
 
 ---
 
@@ -45,7 +70,7 @@ oke dev
 | `:6533` | Console |
 | `:6535` | MCP |
 
-That scaffolds the **Notes** app (same tree as [`examples/notes`](examples/notes)). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
+That scaffolds the **Notes** app (same tree as [`examples/notes`](https://github.com/omqkhafi/okengine/tree/main/examples/notes)). Open the Console — flows, contracts, effects, and an architecture diagram are already there. Derived, not configured.
 
 ### The idea, in one file
 
@@ -318,10 +343,11 @@ The Console is treated as internet-facing even on localhost. Host header validat
 
 ## Status
 
-Pre-1.0. MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
+Pre-1.0. Published on [npm](https://www.npmjs.com/package/okengine) and [JSR](https://jsr.io/@omqkhafi/okengine) (`okengine` + `create-oke`, lockstep). MIT. No `CONTRIBUTING` yet — issues and PRs welcome.
 
 | Spec | Path |
 |---|---|
-| Unified theory | [`docs/spec/unified-theory.md`](docs/spec/unified-theory.md) |
-| Four applications | [`docs/spec/four-applications.md`](docs/spec/four-applications.md) |
-| Console | [`docs/spec/console.md`](docs/spec/console.md) |
+| Unified theory | [`docs/spec/unified-theory.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/unified-theory.md) |
+| Four applications | [`docs/spec/four-applications.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/four-applications.md) |
+| Console | [`docs/spec/console.md`](https://github.com/omqkhafi/okengine/blob/main/docs/spec/console.md) |
+| Scaffold | [`packages/create-oke`](https://github.com/omqkhafi/okengine/tree/main/packages/create-oke) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okengine",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "One law. Eight elements. Ten exports. One package. One manifest. Every backend need is derived, never added.",
   "license": "MIT",
   "type": "module",
@@ -122,7 +122,7 @@
     "bun": ">=1.3"
   },
   "bin": {
-    "oke": "./src/cli/index.ts"
+    "oke": "src/cli/index.ts"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -149,4 +149,4 @@
     "AGENTS.md",
     "docs/spec"
   ]
-}
+}

package/src/auth/index.ts

@@ -3,6 +3,7 @@
  * plus a provider seam. Subpath: `okengine/auth`.
  *
  * Two planes — `fx.operator` vs `fx.auth` — permanently separated.
+ * @module
  */
 
 export { auth, type AuthPluginOptions } from "./plugin.ts";

package/src/client/index.ts

@@ -2,6 +2,7 @@
  * Typed client (+ live). Subpath: `okengine/client`.
  *
  * First Manifest derivation: `type App` → fully typed client, zero codegen.
+ * @module
  */
 
 export { createClient, flattenRoutes } from "./create.ts";

package/src/config/index.ts

@@ -2,6 +2,7 @@
  * `oke.config.ts` surface. Subpath: `okengine/config`.
  *
  * Driver maps are protocol-named; vendor/image choice lives in `images`.
+ * @module
  */
 
 /** Environment role keys used in driver maps. */

package/src/console/index.ts

@@ -3,6 +3,7 @@
  *
  * Built on `createClient<ConsoleApp>`. Every action is a real flow through `fx`;
  * the audit log is the trace (docs/spec/console.md).
+ * @module
  */
 
 export {

package/src/drivers/index.ts

@@ -2,6 +2,7 @@
  * Protocol-named drivers, tree-shaken by the Manifest.
  *
  * Subpath: `okengine/drivers/*`
+ * @module
  */
 
 export type {

package/src/elements/ai.ts

@@ -9,6 +9,7 @@
  * (`oke eval` gates CI). Agents' tools are the app's own flows (gates apply).
  * PII fields cannot reach a third-party model without explicit `allowPii`.
  * Nondeterministic ⇒ journaling forced, auto-cache disabled.
+ * @module
  */
 
 export { ai } from "./ai/declare.ts";

package/src/elements/channel.ts

@@ -8,6 +8,7 @@
  * MIME, attachments, retry, and the unified error hierarchy come from sently.
  * OKE adds: declared templates with i18n, consent/opt-out, fallback chains
  * recorded as chains, and delivery receipts.
+ * @module
  */
 
 export { channel } from "./channel/declare.ts";

package/src/elements/clock.ts

@@ -7,6 +7,7 @@
  * Durability lives on the Flow (`durable: true`); the journal records every
  * `fx` call. Crons leader-elect; schedules are reconciled into the Store at
  * boot (console §5).
+ * @module
  */
 
 export { clock } from "./clock/declare.ts";

package/src/elements/gate.ts

@@ -5,6 +5,7 @@
  * Rate strategies are atomic Lua on the kv driver.
  *
  * Drivers: inherits `store.kv` (`memory` · `redis`).
+ * @module
  */
 
 export { gate } from "./gate/declare.ts";

package/src/elements/signal.ts

@@ -3,6 +3,7 @@
  *
  * Delivery physics: `once` · `broadcast` · `live` (mandatory, no default).
  * Drivers: `memory` · `postgres` (default / transactional) · `redis` · `nats`.
+ * @module
  */
 
 export { signal } from "./signal/declare.ts";

package/src/elements/store.ts

@@ -5,6 +5,7 @@
  * Drivers are protocol-named and live under `src/drivers/*`.
  * All world access still goes through `fx`; this module only declares
  * resources and provides runtime helpers (cache, replica routing, PII).
+ * @module
  */
 
 export { store, sql, kv, files, index } from "./store/declare.ts";

package/src/elements/vault.ts

@@ -7,6 +7,7 @@
  * A declaration is a contract, never a value. Boot validates every contract
  * and lists all gaps at once. Logs/traces receive fingerprints and redaction
  * registered at boot — cleartext never appears even when passed to `fx.log`.
+ * @module
  */
 
 export {

package/src/index.ts

@@ -3,6 +3,15 @@
  *
  * Full ten-export surface lands as elements ship; this entry exposes the
  * executable core (oke · on · flow · http · fx · contracts).
+ *
+ * @example
+ * ```ts
+ * import { oke, on, flow, http } from "okengine";
+ *
+ * export const app = oke({ name: "notes" });
+ * ```
+ *
+ * @module
  */
 
 export {

package/src/mcp/index.ts

@@ -6,6 +6,7 @@
  * human confirmation, every return wrapped as inert data.
  *
  * Subpath: `okengine/mcp`
+ * @module
  */
 
 export {

package/src/runs/index.ts

@@ -3,6 +3,7 @@
  *
  * Not a ninth element: observability derived from the effect system.
  * Subpath: planned as part of the Console / runtime surface.
+ * @module
  */
 
 export type {

package/src/test/index.ts

@@ -1,5 +1,6 @@
 /**
  * Test harness (`createTestApp`). Subpath: `okengine/test`.
+ * @module
  */
 
 export {