@ekairos/domain 1.22.34-beta.development.0 → 1.22.35

package/README.md

@@ -1,173 +1,327 @@
 # @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(...).withSchema(...)`
+- Explicit runtimes with `EkairosRuntime`
+- Step-safe write boundaries with `defineAction(...)`
+- Workflow-ready action execution with `executeRuntimeAction(...)`
+- A companion CLI through `@ekairos/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.
+Scaffold a Next app that already exposes the Ekairos domain endpoint:
 
-## Install
+```bash
+ekairos create-app my-app --next
+```
+
+Run the full supply-chain demo cycle:
+
+```bash
+ekairos create-app --demo
+```
+
+If you already have an Instant platform token, provision the app and write `.env.local` in one pass:
+
+```bash
+ekairos create-app my-app --next --instantToken=$INSTANT_PERSONAL_ACCESS_TOKEN
+```
+
+Then run it and inspect it:
 
 ```bash
-pnpm add @ekairos/domain @instantdb/core
-pnpm add -D @instantdb/admin
+ekairos domain inspect --baseUrl=http://localhost:3000 --admin --pretty
+ekairos domain "supplyChain.order.launch" "{ reference: 'PO-7842', supplierName: 'Marula Components', sku: 'DRV-2048' }" --baseUrl=http://localhost:3000 --admin --pretty
+ekairos domain query "{ procurement_order: { supplier: {}, stockItems: {}, shipments: { inspections: {} } } }" --baseUrl=http://localhost:3000 --admin --pretty
+```
+
+## Next.js Route
+
+New Next.js apps expose the domain adapter explicitly:
+
+```ts
+// src/app/api/ekairos/domain/route.ts
+import { createRuntimeRouteHandler } from "@ekairos/domain/next";
+import { createRuntime } from "@/runtime";
+
+export const { GET, POST } = createRuntimeRouteHandler({
+  createRuntime,
+});
 ```
 
-Exports:
+This replaces the old `withRuntime(...)` pattern.
+There is no Next config patching and no generated `.well-known` domain route in new apps.
+
+Your `next.config.ts` should stay focused on Workflow:
+
+```ts
+import type { NextConfig } from "next";
+import { withWorkflow } from "workflow/next";
+
+const nextConfig: NextConfig = {
+  transpilePackages: ["@ekairos/domain"],
+};
 
-- `@ekairos/domain`
-- `@ekairos/domain/runtime`
-- `@ekairos/domain/next`
+export default withWorkflow(nextConfig) as NextConfig;
+```
 
-## Quick start
+The CLI uses `/api/ekairos/domain`.
 
-### 1. Define a domain schema
+## Core Pattern
 
 ```ts
-import { domain } from "@ekairos/domain";
+import { defineAction, 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";
 
-export const managementDomain = domain("management").schema({
+const baseDomain = domain("tasks").withSchema({
   entities: {
-    management_tasks: i.entity({
-      title: i.string(),
+    tasks: i.entity({
+      title: i.string().indexed(),
       status: i.string().indexed(),
-      createdAt: i.date().indexed(),
     }),
   },
   links: {},
   rooms: {},
 });
-```
-
-### 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}` };
+export const createTaskAction = defineAction({
+  name: "tasks.create",
+  async execute({ runtime, input }) {
+    "use step";
+    const scoped = await runtime.use(appDomain);
+    // transact...
+    return { ok: true };
   },
 });
 
-export const appDomain = managementDomain.actions([createTask]);
+export const appDomain = baseDomain.withActions({
+  createTask: createTaskAction,
+});
+
+// Raw definitions stay available for reflection and adapters:
+appDomain.actions.createTask;
+
+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.instantSchema(),
+      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" },
+  });
+}
 ```
 
-### 3. Configure runtime once
+## Rules Of Thumb
+
+- 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.
+
+## Public And Full Domains
+
+Use normal domain composition to split browser-visible schema from server/runtime
+capabilities. The public domain is a smaller domain. The full domain imports and
+extends it.
 
 ```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 } };
+// @acme/sandbox/public
+export const sandboxDomain = domain("sandbox").withSchema({
+  entities: {
+    sandbox_sandboxes: i.entity({
+      provider: i.string().indexed(),
+      status: i.string().indexed(),
+      createdAt: i.number().indexed(),
+    }),
   },
+  links: {},
+  rooms: {},
 });
 ```
 
-### 4. Execute actions
+```ts
+// @acme/sandbox
+import { sandboxDomain as publicSandboxDomain } from "@acme/sandbox/public";
+
+export const sandboxDomain = domain("sandbox")
+  .includes(publicSandboxDomain)
+  .withSchema({
+    entities: {
+      sandbox_processes: i.entity({
+        kind: i.string().indexed(),
+        status: i.string().indexed(),
+        command: i.string(),
+        startedAt: i.number().indexed(),
+      }),
+    },
+    links: {
+      sandboxProcessSandbox: {
+        forward: { on: "sandbox_processes", has: "one", label: "sandbox" },
+        reverse: { on: "sandbox_sandboxes", has: "many", label: "processes" },
+      },
+    },
+    rooms: {},
+  })
+  .withActions({
+    runCommand: defineAction({
+      name: "sandbox.runCommand",
+      async execute({ runtime, input }) {
+        "use step";
+        // server/provider work
+      },
+    }),
+  });
+```
+
+Client schema composition imports public domains:
 
 ```ts
-import { executeRuntimeAction } from "@ekairos/domain/runtime";
+import { sandboxDomain } from "@acme/sandbox/public";
 
-const output = await executeRuntimeAction({
-  action: "management.task.create",
-  env: { orgId: "org_123", actorId: "user_1" },
-  input: { title: "Ship domain action runtime" },
-});
-```
+export const appDomain = domain("app")
+  .includes(sandboxDomain)
+  .withSchema({ entities: {}, links: {}, rooms: {} });
 
-## Action model
+export default appDomain.instantSchema();
+```
 
-Actions are explicit and portable:
+Server runtime imports full domains:
 
-- Domain package owns contracts.
-- Adapters own environment (`env`).
-- Runtime is resolved per action domain.
-- Nested action calls are supported with cycle protection.
+```ts
+import { sandboxDomain } from "@acme/sandbox";
 
-This keeps Web/API/MCP integrations aligned without duplicating mutation logic.
+const sandbox = await runtime.use(sandboxDomain);
+await sandbox.actions.runCommand({ sandboxId, command: "pnpm", args: ["test"] });
+```
 
-## Domain context for AI
+This pattern controls schema visibility only. It is not an authorization model:
+configure Instant permissions for actual data access.
 
-Every domain can produce structured context:
+## CLI Input Quality Of Life
 
-- `domain.context()` returns a machine-friendly context object.
-- `domain.contextString()` returns a prompt-friendly string.
+The CLI accepts JSON5, `@file`, and stdin:
 
-Use this to ground coding agents and domain assistants with current entities, links, docs, and subdomains.
+```bash
+ekairos domain query "{ tasks: { $: { limit: 5 } } }" --admin
+ekairos domain query @query.json5 --admin
+cat query.json5 | ekairos domain query - --admin
+```
 
-## Adapter pattern (recommended)
+Add `--meta` when you need to know whether a query used the local client runtime path or the server route.
 
-### Web/API
+## Tests
 
-- UI calls API route.
-- API route resolves auth and builds `env`.
-- API route executes typed domain action.
+```bash
+pnpm --filter @ekairos/domain test
+pnpm --filter @ekairos/domain test:cli
+pnpm --filter @ekairos/domain test:workflow
+```
 
-### MCP
+## Type And DX Notes
 
-- 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.
+`@ekairos/domain` intentionally encapsulates InstantDB at the domain boundary, but
+the schema returned by a domain must remain usable anywhere an InstantDB schema is
+expected.
 
-## Design rules
+Use `instantSchema()` when provisioning or passing a runtime schema to InstantDB:
 
-- 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.
+```ts
+const db = init({
+  appId,
+  adminToken,
+  schema: appDomain.instantSchema(),
+});
+```
 
-## Purity and immutability guarantees
+Use `DomainInstantSchema<typeof domain>` when you need the schema type for
+`db.query`, `InstaQLParams`, `InstaQLResult`, or service constructors:
 
-- `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.
+```ts
+import type { DomainInstantSchema } from "@ekairos/domain";
+import type { InstantAdminDatabase } from "@instantdb/admin";
+
+type AppSchema = DomainInstantSchema<typeof appDomain>;
+
+function createService(db: InstantAdminDatabase<AppSchema, true>) {
+  return db.query({
+    tasks: {
+      owner: {},
+    },
+  });
+}
+```
 
-## Testing
+Prefer exported domain values without widening their type:
 
-```bash
-pnpm run test:unit   # runtime and action behavior
-pnpm run test:e2e    # InstantDB temp app flow (requires INSTANT_CLI_AUTH_TOKEN)
+```ts
+export const tasksDomain = domain("tasks").withSchema({
+  entities: { tasks: i.entity({ title: i.string() }) },
+  links: {},
+  rooms: {},
+});
 ```
 
-In the monorepo release flow, required checks run before publishing:
+Avoid annotating exported domains as plain `DomainSchemaResult` unless you need to
+hide their concrete shape. That annotation widens the domain name and schema, so
+TypeScript loses some compile-time checks for `runtime.use(...)`, `RuntimeForDomain`,
+and composed queries.
 
-```bash
-pnpm run release:required-checks
+```ts
+// Avoid for runtime/domain composition:
+export const tasksDomain: DomainSchemaResult = domain("tasks").withSchema(...);
 ```
 
-## Links
+Type tests under `src/__type_tests__` are intentionally split by use case:
 
-- 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
+- `domain.schema-*.typecheck.ts`: schema extraction, entity/link visibility, and query shape.
+- `domain.includes-*.typecheck.ts`: composed entities, transitive links, and traversal direction.
+- `domain.instaql-fetch.typecheck.ts`: namespaces, associations, deferred query shapes, and `queryOnce`.
+- `domain.instaql-filters.typecheck.ts`: dotted relation filters and advanced where operators.
+- `domain.instaql-options.typecheck.ts`: pagination, ordering, selected fields, and page info.
+- `domain.instantdb-*.typecheck.ts`: InstantDB query, entity, and result helpers.
+- `domain.query-negative-*.typecheck.ts`: invalid entities and relation labels stay rejected.
+- `domain.dx-*.typecheck.ts`: public helper aliases, literal names, and schema helpers.
+- `runtime.domain-names-*.typecheck.ts`: `RuntimeForDomain` validates name plus schema.
+- `workflow-output-*.typecheck.ts`: workflow serde output contracts.
 
-## License
+When a type regression appears, add one small file or one focused case to the
+matching file. Avoid broad "kitchen sink" type tests; they make IntelliSense and
+compiler failures hard to read.
 
-MIT

package/SKILL.md

@@ -0,0 +1,56 @@
+# Skill: ekairos-domain
+
+Use this skill when creating, editing, reviewing, or operating Ekairos domain code.
+
+## Core Contract
+
+- Model knowledge boundaries as domains first. A domain owns one coherent concept.
+- Domain names are camelCase, for example `supplierNetwork`, `procurement`, `qualityControl`.
+- Entity names must follow `<domainName>_<entityName>`, for example `supplierNetwork_supplier`.
+- Put writes behind `defineDomainAction(...)`.
+- Keep action bodies step-safe:
+  `async execute({ runtime, input }) { "use step"; const scoped = await runtime.use(appDomain); ... }`
+- Prefer typed action calls in app-owned code:
+  `const scoped = await runtime.use(appDomain); await scoped.actions.launchOrder(input);`
+- Use string action names only for dynamic runtime/HTTP/CLI execution.
+- Use explicit runtime classes that extend `EkairosRuntime`.
+- New Next.js apps expose `/api/ekairos/domain` through `createRuntimeRouteHandler({ createRuntime })`.
+- Do not use or reintroduce `withRuntime(...)`.
+
+## Domain Design Workflow
+
+1. Identify the knowledge domains before writing schema.
+2. Name every entity with its owning domain prefix.
+3. Use `domain(...).includes(...)` only when one domain needs another domain's entities or links.
+4. Keep root app domains thin. The root should usually include domains and register actions.
+5. Write actions around business use cases, not CRUD verbs.
+6. Verify the graph with a nested query that crosses at least two domains.
+
+## Schema Rules
+
+- Prefer operational names over abstract names.
+- Avoid generic `app_*` entities in new examples unless the domain itself is `app`.
+- Do not duplicate entity names across domains.
+- Links should describe the business relationship, not implementation plumbing.
+- Use optional attributes when migrating an existing app with data.
+
+## Runtime And Actions
+
+- Dynamic endpoints may call `executeRuntimeAction({ action: "domain.action", input })`.
+- Workflows and app code should use typed scoped actions.
+- Action outputs should return durable ids needed by callers.
+- Keep actions idempotent where possible when they will be used by smoke tests or agents.
+
+## Verification
+
+For a generated or edited app:
+
+1. Run `pnpm typecheck`.
+2. Start the app locally.
+3. Verify `GET /api/ekairos/domain`.
+4. Execute at least one domain action.
+5. Query the linked graph produced by that action.
+
+## Related Skills
+
+- CLI/application workflow skill: `../cli/SKILL.md`

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<0 | 1>;
+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":";AAGA,OAAO,EAAkB,MAAM,IAAI,MAAM,EAAE,MAAM,cAAc,CAAA;AAkB/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;AAgqBD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,GAAE,UAA+C,kBAuDrD"}