@ekairos/domain 1.22.15-beta.feature-thread-unify.0 → 1.22.16-beta.development.0

package/README.md

@@ -1,173 +1,168 @@
 # @ekairos/domain
 
-[![npm version](https://img.shields.io/npm/v/@ekairos/domain)](https://www.npmjs.com/package/@ekairos/domain)
-[![npm downloads](https://img.shields.io/npm/dm/@ekairos/domain)](https://www.npmjs.com/package/@ekairos/domain)
+Build one app graph from many bounded contexts.
+Read it through InstantDB.
+Write through step-safe domain actions.
+Operate it through a CLI.
 
-Domain-first TypeScript primitives for InstantDB applications.
+## What you get
 
-`@ekairos/domain` gives you one source of truth for:
+- Composed domain graphs with `domain(...).schema(...)`
+- Explicit runtimes with `EkairosRuntime`
+- Step-safe write boundaries with `defineDomainAction(...)`
+- Workflow-ready action execution with `executeRuntimeAction(...)`
+- A built-in CLI for `create-app`, `inspect`, `action`, and `query`
 
-- Schema composition.
-- Runtime resolution.
-- Typed domain actions.
-- AI-ready domain context.
+## Start Fast
 
-If `@ekairos/thread` is execution, `@ekairos/domain` is system truth.
-
-## Install
+Scaffold a Next app that already exposes the Ekairos domain endpoint:
 
 ```bash
-pnpm add @ekairos/domain @instantdb/core
-pnpm add -D @instantdb/admin
+npx @ekairos/domain create-app my-app --next
 ```
 
-Exports:
-
-- `@ekairos/domain`
-- `@ekairos/domain/runtime`
-- `@ekairos/domain/next`
-
-## Quick start
-
-### 1. Define a domain schema
-
-```ts
-import { domain } from "@ekairos/domain";
-import { i } from "@instantdb/core";
+If you already have an Instant platform token, provision the app and write `.env.local` in one pass:
 
-export const managementDomain = domain("management").schema({
-  entities: {
-    management_tasks: i.entity({
-      title: i.string(),
-      status: i.string().indexed(),
-      createdAt: i.date().indexed(),
-    }),
-  },
-  links: {},
-  rooms: {},
-});
+```bash
+npx @ekairos/domain create-app my-app --next --instantToken=$INSTANT_PERSONAL_ACCESS_TOKEN
 ```
 
-### 2. Add typed actions
-
-```ts
-import { defineDomainAction } from "@ekairos/domain";
-
-const createTask = defineDomainAction<
-  { orgId: string; actorId: string },
-  { title: string },
-  { ok: true; taskId: string },
-  { db: any }
->({
-  name: "management.task.create",
-  description: "Create a management task",
-  async execute({ env, input, runtime }) {
-    const title = String(input.title ?? "").trim();
-    if (!title) throw new Error("title_required");
-
-    // use runtime.db here
-    return { ok: true, taskId: `task_${env.orgId}` };
-  },
-});
+Then run it and inspect it:
 
-export const appDomain = managementDomain.actions([createTask]);
+```bash
+npx @ekairos/domain inspect --baseUrl=http://localhost:3000 --admin --pretty
+npx @ekairos/domain seedDemo --baseUrl=http://localhost:3000 --admin --pretty
+npx @ekairos/domain query "{ app_tasks: { comments: {} } }" --baseUrl=http://localhost:3000 --admin --pretty
 ```
 
-### 3. Configure runtime once
-
-```ts
-import { configureRuntime } from "@ekairos/domain/runtime";
-import { appDomain } from "./domain";
-
-configureRuntime({
-  domain: { domain: appDomain },
-  runtime: async (env) => {
-    // Resolve DB by env (org, actor, tenant, etc.)
-    return { db: { orgId: env.orgId } };
-  },
-});
-```
+## Next.js Route
 
-### 4. Execute actions
+New Next.js apps expose the domain adapter explicitly:
 
 ```ts
-import { executeRuntimeAction } from "@ekairos/domain/runtime";
+// src/app/api/ekairos/domain/route.ts
+import { createRuntimeRouteHandler } from "@ekairos/domain/next";
+import { createRuntime } from "@/runtime";
 
-const output = await executeRuntimeAction({
-  action: "management.task.create",
-  env: { orgId: "org_123", actorId: "user_1" },
-  input: { title: "Ship domain action runtime" },
+export const { GET, POST } = createRuntimeRouteHandler({
+  createRuntime,
 });
 ```
 
-## Action model
-
-Actions are explicit and portable:
-
-- Domain package owns contracts.
-- Adapters own environment (`env`).
-- Runtime is resolved per action domain.
-- Nested action calls are supported with cycle protection.
+This replaces the old `withRuntime(...)` pattern.
+There is no Next config patching and no generated `.well-known` domain route in new apps.
 
-This keeps Web/API/MCP integrations aligned without duplicating mutation logic.
+Your `next.config.ts` should stay focused on Workflow:
 
-## Domain context for AI
+```ts
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
 
-Every domain can produce structured context:
+const nextConfig: NextConfig = {
+  transpilePackages: ["@ekairos/domain"],
+};
 
-- `domain.context()` returns a machine-friendly context object.
-- `domain.contextString()` returns a prompt-friendly string.
+export default withWorkflow(nextConfig) as NextConfig;
+```
 
-Use this to ground coding agents and domain assistants with current entities, links, docs, and subdomains.
+The CLI uses `/api/ekairos/domain` by default and falls back to the legacy
+`/.well-known/ekairos/v1/domain` endpoint for older apps.
 
-## Adapter pattern (recommended)
+## Core Pattern
 
-### Web/API
+```ts
+import { defineDomainAction, domain } from "@ekairos/domain";
+import { EkairosRuntime } from "@ekairos/domain/runtime-handle";
+import { executeRuntimeAction } from "@ekairos/domain/runtime";
+import { init } from "@instantdb/admin";
+import { i } from "@instantdb/core";
 
-- UI calls API route.
-- API route resolves auth and builds `env`.
-- API route executes typed domain action.
+const baseDomain = domain("tasks").schema({
+  entities: {
+    tasks: i.entity({
+      title: i.string().indexed(),
+      status: i.string().indexed(),
+    }),
+  },
+  links: {},
+  rooms: {},
+});
 
-### MCP
+export const createTaskAction = defineDomainAction({
+  name: "tasks.create",
+  async execute({ runtime, input }) {
+    "use step";
+    const scoped = await runtime.use(appDomain);
+    // transact...
+    return { ok: true };
+  },
+});
 
-- Expose one MCP tool per action (or a thin action dispatcher).
-- Resolve transport auth to `env`.
-- Execute the same domain actions used by Web/API.
+export const appDomain = baseDomain.actions({
+  createTask: createTaskAction,
+});
 
-## Design rules
+export class AppRuntime extends EkairosRuntime<{
+  appId?: string;
+  adminToken?: string;
+}, typeof appDomain, any> {
+  protected getDomain() {
+    return appDomain;
+  }
+
+  protected async resolveDb(env: { appId?: string; adminToken?: string }) {
+    return init({
+      appId: env.appId!,
+      adminToken: env.adminToken!,
+      schema: appDomain.toInstantSchema(),
+      useDateObjects: true,
+    } as any);
+  }
+}
+
+export function createRuntime(env = {}) {
+  return new AppRuntime(env);
+}
+
+export async function runWorkflow() {
+  "use workflow";
+  const runtime = createRuntime({
+    appId: process.env.NEXT_PUBLIC_INSTANT_APP_ID,
+    adminToken: process.env.INSTANT_ADMIN_TOKEN,
+  });
+
+  return await executeRuntimeAction({
+    runtime,
+    action: createTaskAction,
+    input: { title: "Ship it" },
+  });
+}
+```
 
-- Domain defines truth.
-- Runtime is explicit.
-- Actions are explicit.
-- `env` is adapter-defined and opaque to the package.
-- Included subdomains do not auto-export actions.
+## Rules Of Thumb
 
-## Purity and immutability guarantees
+- Read directly from the composed schema when no invariant is involved.
+- Put every meaningful write behind an action.
+- Keep action bodies `"use step"`.
+- Keep workflow orchestration above actions.
+- Use `DOMAIN.md` plus `domain.contextString()` when an AI agent needs the model explained.
 
-- `toInstantSchema()` is pure and idempotent for the same domain result.
-- Domain schema results are immutable at runtime.
-- `.actions(...)` is persistent: it returns a new domain result and never mutates the original one.
-- Duplicate link attributes (`entity->label`) are rejected before schema materialization.
+## CLI Input Quality Of Life
 
-## Testing
+The CLI accepts JSON5, `@file`, and stdin:
 
 ```bash
-pnpm run test:unit   # runtime and action behavior
-pnpm run test:e2e    # InstantDB temp app flow (requires INSTANT_CLI_AUTH_TOKEN)
+npx @ekairos/domain query "{ tasks: { $: { limit: 5 } } }" --admin
+npx @ekairos/domain query @query.json5 --admin
+cat query.json5 | npx @ekairos/domain query - --admin
 ```
 
-In the monorepo release flow, required checks run before publishing:
+Add `--meta` when you need to know whether a query used the local client runtime path or the server route.
+
+## Tests
 
 ```bash
-pnpm run release:required-checks
+pnpm --filter @ekairos/domain test
+pnpm --filter @ekairos/domain test:cli
+pnpm --filter @ekairos/domain test:workflow
 ```
-
-## Links
-
-- npm: https://www.npmjs.com/package/@ekairos/domain
-- source: https://github.com/e-kairos/ekairos/tree/main/packages/domain
-- issues: https://github.com/e-kairos/ekairos/issues
-
-## License
-
-MIT

package/dist/cli/bin.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { stdout as output } from "node:process";
+type CliContext = {
+    stdout: Pick<typeof output, "write">;
+    stderr: Pick<typeof output, "write">;
+};
+export declare function runCli(argv: string[], ctx?: CliContext): Promise<1 | 0>;
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/cli/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../../src/cli/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAkB,MAAM,IAAI,MAAM,EAAE,MAAM,cAAc,CAAA;AAgB/D,KAAK,UAAU,GAAG;IAChB,MAAM,EAAE,IAAI,CAAC,OAAO,MAAM,EAAE,OAAO,CAAC,CAAA;IACpC,MAAM,EAAE,IAAI,CAAC,OAAO,MAAM,EAAE,OAAO,CAAC,CAAA;CACrC,CAAA;AAkiBD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,UAA+C,kBAkDrD"}