@arki/dot 0.1.3 → 0.2.0

package/README.md

@@ -3,26 +3,31 @@
 > TypeScript-first application composition framework for the ARKI package family.
 
 `@arki/dot` is the kernel that wires **pips**, lifecycle hooks, dependency
-graphs, and diagnostics into a deterministic application boot. It gives library
-authors a stable contract for declaring how their package participates in an
-app, and gives app developers a single place to wire those packages together.
+injection, and diagnostics into a deterministic application boot. It gives
+library authors a stable contract for declaring how their package
+participates in an app, and gives app developers a single place to wire
+those packages together — with the type checker verifying the wiring before
+anything runs.
 
 ## What is a pip?
 
 A **pip** is the unit a DOT app is built from — one self-describing,
 lifecycle-aware piece of an application. Each pip:
 
-- declares a **name**, **version**, and the kinds of **services it provides**;
+- declares a **name**, **version**, and the services it **needs** as a shape
+  of type witnesses;
+- **provides** services by returning them from its `boot` hook — provides
+  are *inferred from the return type*, never declared separately;
 - runs a **5-hook lifecycle** — `configure` → `boot` → `start` → `stop` → `dispose`;
-- **publishes typed services** to a shared, type-safe registry that later pips
-  can read from;
-- **composes deterministically** — pips boot in declaration order and dispose
-  in reverse.
+- **publishes typed services** to a shared, type-safe registry that later
+  pips can read from;
+- **composes deterministically** — pips boot in declaration order and
+  dispose in reverse.
 
 The name comes from the small dots on dice, dominoes, and music notation:
-each pip is one small mark, and the *combination* of pips is what gives the app
-its value. Two pips on a die make a value of two; six pips make six. The pips
-**are** the app — not optional add-ons to a hidden core.
+each pip is one small mark, and the *combination* of pips is what gives the
+app its value. Two pips on a die make a value of two; six pips make six. The
+pips **are** the app — not optional add-ons to a hidden core.
 
 ```ts
 import { defineApp } from '@arki/dot';
@@ -61,6 +66,19 @@ bun add @arki/dot
 ```ts
 import { defineApp, pip, service } from '@arki/dot';
 
+type Db = { query(sql: string): Promise<unknown[]> };
+
+const dbPip = pip({
+  name: 'database',
+  async boot() {
+    const db = await openDb(process.env.DATABASE_URL);
+    return { db };                    // ← this IS the provides declaration
+  },
+  async dispose({ db }) {
+    await db.close();
+  },
+});
+
 const billingPip = pip({
   name: 'billing',
   version: '1.0.0',
@@ -94,6 +112,371 @@ await app.stop();
 await app.dispose();
 ```
 
+There is no registry to configure, no decorators, no reflection. The `needs`
+shape is the injection contract; the `boot` return type is the provision
+contract; the builder's type-level guard connects the two.
+
+## Dependency injection
+
+### Needs are witnesses, provides are inferred
+
+`service<T>()` creates a phantom **type witness** — a runtime no-op that
+carries `T` at the type level. The property name you give it is your local
+alias *and* (for anonymous witnesses) the wire key:
+
+```ts
+const search = pip({
+  name: 'search',
+  needs: {
+    db: service<Db>(),                 // wire key 'db', local alias 'db'
+    log: service<Logger>(),            // wire key 'log'
+  },
+  async boot({ db, log, $app }) {      // $app/$pip/$config: kernel context
+    log.info(`indexing for ${$app}`);
+    return { search: await buildIndex(db) };
+  },
+});
+```
+
+`start`, `stop`, and `dispose` additionally receive the pip's **own
+provides** — and because teardown runs in reverse declaration order, a pip's
+needs are still alive in its `dispose`:
+
+```ts
+async dispose({ search, db }) {        // own provide + still-live need
+  await search.flush(db);
+},
+```
+
+### Wrong wiring does not compile
+
+Declaration order IS boot order. The `.use()` guard makes unsatisfied needs,
+type mismatches, and key collisions **compile errors at the call site**:
+
+```ts
+defineApp('shop')
+  .use(billing)      // ❌ "Expected 2 arguments, but got 1."
+  .use(database);    //    billing's `db` need has no earlier provider
+
+defineApp('shop')
+  .use(database)
+  .use(database2);   // ❌ collision: two providers of wire key 'db'
+```
+
+Reordering the first example — or `rename`-ing one provider in the second —
+makes both compile. The kernel re-validates at runtime with coded errors
+(`E012` unsatisfied need, `E013` collision, `E014` reserved key) for
+erased/dynamic composition, with full rollback of already-booted pips.
+
+There is no dependency graph to debug and **cycles are unrepresentable**:
+services flow strictly forward through the `.use()` chain. If two pips need
+each other's services, that's a design smell the type system surfaces
+immediately — merge them, or extract the shared piece into a third pip both
+consume.
+
+### Tokens — cross-package service contracts
+
+An anonymous `service<T>()` couples consumer and provider by property name.
+When a contract spans packages, a **token** owns the wire key and the local
+alias becomes free choice:
+
+```ts
+// The package that owns the contract exports the token:
+export const Db = token<NodePgDatabase<Schema>>()('arki.db');
+
+// A provider publishes under the token's key:
+const database = pip({
+  name: 'database',
+  async boot() {
+    return provide(Db, await connect());   // → { 'arki.db': NodePgDatabase }
+  },
+});
+
+// Any consumer, any package, any local alias:
+const reports = pip({
+  name: 'reports',
+  needs: { warehouse: Db },                // wire key 'arki.db', alias yours
+  async boot({ warehouse }) { /* ... */ },
+});
+```
+
+### Multi-instance with `rename`
+
+Mounting an adapter twice would collide on its wire keys — loudly, at
+compile time. `rename` is the multi-instance primitive, and
+`Token.instance()` derives the matching contract:
+
+```ts
+const ReportsDb = Db.instance('reports');  // token for key 'arki.db#reports'
+
+const app = await defineApp('shop')
+  .use(database({ url: PRIMARY_URL }))
+  .use(rename(
+    database({ url: REPLICA_URL }),
+    { 'arki.db': ReportsDb.key },          // republish under the derived key
+    'reports-db',                          // distinct pip name
+  ))
+  .use(pip({
+    name: 'analytics',
+    needs: { primary: Db, replica: ReportsDb },
+    async boot({ primary, replica }) { /* two live instances, both typed */ },
+  }))
+  .boot();
+```
+
+Renames compose left-to-right and are applied at publish time — collision
+checks see the final keys.
+
+### Lazy services
+
+`lazy(init, { dispose })` publishes a **handle** instead of an open
+resource. Initialization runs on first `get()` (memoized, single-flight;
+failed attempts retry). Never-touched handles never initialize — and the
+kernel auto-disposes initialized ones during teardown, *after* the
+publishing pip's own `dispose` hook, even if that pip has none:
+
+```ts
+const search = pip({
+  name: 'search',
+  async boot() {
+    return {
+      search: lazy(() => connectToElastic(), {
+        dispose: client => client.close(),
+      }),
+    };
+  },
+});
+```
+
+Consumers that shouldn't care whether a provider is eager or lazy declare a
+**lifting witness** — `service.lazy<T>()` always delivers a `Lazy<T>`
+handle, wrapping eager provides and passing lazy ones through by identity:
+
+```ts
+const suggestions = pip({
+  name: 'suggestions',
+  needs: { search: service.lazy<SearchClient>() },
+  async start({ search }) {
+    const client = await search.get();     // first access initializes
+    /* ... */
+  },
+});
+```
+
+Swapping the search provider between eager and lazy is invisible to every
+consumer — the wiring guard accepts both shapes against the same witness.
+
+### Kernel context — the reserved `$` namespace
+
+Every service-carrying hook context includes `$app` (app name), `$pip` (pip
+name), and `$config` (the `defineApp(name, { config })` bag). The `$` prefix
+is enforced as reserved: `pip()` rejects `$`-prefixed needs aliases and
+publish keys at compile time, and the kernel re-validates at runtime
+(`DOT_LIFECYCLE_E014`) — kernel keys can never be shadowed.
+
+## A complex setup
+
+A distilled commerce platform showing everything above working together.
+(The package's stress-test suite boots a 28-pip version of this and asserts
+exact boot/teardown ordering.)
+
+```ts
+import { defineApp, lazy, pip, provide, rename, service, token } from '@arki/dot';
+
+// ── contracts.ts — tokens owned by their respective packages ─────────
+export const Env = token<AppEnv>()('shop.env');
+export const Db = token<DbHandle>()('shop.db');
+export const ReportsDb = Db.instance('reports');
+export const Cache = token<CacheHandle>()('shop.cache');
+export const Bus = token<MessageBus>()('shop.bus');
+
+// ── infrastructure pips ───────────────────────────────────────────────
+const env = pip({
+  name: 'env',
+  boot: ({ $config }) => provide(Env, parseEnv($config)),
+});
+
+const telemetry = pip({
+  name: 'telemetry',
+  needs: { env: Env },
+  boot: ({ env }) => ({ metrics: makeMetrics(env.OTEL_ENDPOINT) }),
+  dispose: ({ metrics }) => metrics.flush(),
+});
+
+const database = (url: string) =>
+  pip({
+    name: 'database',
+    needs: { metrics: service<Metrics>() },
+    async boot({ metrics }) {
+      return provide(Db, await connectPg(url, { metrics }));
+    },
+    async dispose(ctx) {
+      await ctx[Db.key].end();       // own provide, published under the token key
+    },
+  });
+
+const cache = pip({
+  name: 'cache',
+  needs: { env: Env },
+  boot: ({ env }) => provide(Cache, connectRedis(env.REDIS_URL)),
+  dispose: async ctx => ctx[Cache.key].quit(),
+});
+
+const searchCluster = pip({
+  name: 'search-cluster',
+  needs: { env: Env },
+  boot: ({ env }) => ({
+    // Expensive external cluster — only opens if something get()s it.
+    search: lazy(() => connectElastic(env.ELASTIC_URL), {
+      dispose: client => client.close(),
+    }),
+  }),
+});
+
+const bus = pip({
+  name: 'bus',
+  boot: () => provide(Bus, makeInMemoryBus()),
+});
+
+// ── domain pips ───────────────────────────────────────────────────────
+const catalog = pip({
+  name: 'catalog',
+  needs: {
+    db: Db,
+    cache: Cache,
+    search: service.lazy<SearchClient>(),   // eager or lazy provider — same code
+  },
+  boot: ({ db, cache, search }) => ({
+    catalog: makeCatalog({ db, cache, search }),
+  }),
+});
+
+const checkout = pip({
+  name: 'checkout',
+  needs: { db: Db, bus: Bus, catalog: service<Catalog>() },
+  boot: ({ db, bus, catalog }) => ({
+    checkout: makeCheckout({ db, bus, catalog }),
+  }),
+});
+
+const reporting = pip({
+  name: 'reporting',
+  needs: { replica: ReportsDb, catalog: service<Catalog>() },
+  boot: ({ replica, catalog }) => ({ reporting: makeReporting(replica, catalog) }),
+});
+
+// ── process pips — real work happens in start/stop ───────────────────
+const outboxWorker = pip({
+  name: 'outbox-worker',
+  needs: { db: Db, bus: Bus },
+  boot: ({ db, bus }) => ({ outbox: makeOutbox(db, bus) }),
+  start: ({ outbox }) => outbox.startPolling(),
+  stop: ({ outbox }) => outbox.drain(),      // stop processing, keep resources
+});
+
+const http = pip({
+  name: 'http',
+  needs: {
+    env: Env,
+    catalog: service<Catalog>(),
+    checkout: service<Checkout>(),
+    reporting: service<Reporting>(),
+  },
+  async boot({ env, catalog, checkout, reporting }) {
+    return { server: buildServer({ port: env.PORT, catalog, checkout, reporting }) };
+  },
+  start: ({ server }) => server.listen(),
+  stop: ({ server }) => server.close(),
+});
+
+// ── composition — the order IS the architecture ──────────────────────
+const app = await defineApp('shop', { config: process.env })
+  .use(env)
+  .use(telemetry)
+  .use(database(PRIMARY_URL))
+  .use(rename(database(REPLICA_URL), { 'shop.db': ReportsDb.key }, 'reports-db'))
+  .use(cache)
+  .use(searchCluster)
+  .use(bus)
+  .use(catalog)
+  .use(checkout)
+  .use(reporting)
+  .use(outboxWorker)
+  .use(http)
+  .start();
+
+// SIGTERM → dispose() cascades stop() first, tears down in exact reverse:
+// http, outbox (drained), reporting, checkout, catalog, bus,
+// search cluster (only if it ever initialized), cache, reports-db,
+// primary db, telemetry, env.
+process.on('SIGTERM', () => void app.dispose());
+```
+
+What the type checker is holding for you in that chain:
+
+- move `.use(catalog)` above `.use(cache)` → compile error at that line;
+- delete `.use(bus)` → compile errors at `checkout` and `outboxWorker`;
+- mount the second `database(...)` without `rename` → collision error;
+- change `makeCatalog` to return something that isn't a `Catalog` →
+  every consumer's `.use()` flags the mismatch.
+
+Concurrent lifecycle calls are safe: transitions are serialized on one
+queue, same-phase calls coalesce onto one in-flight promise, and a
+`dispose()` racing a slow `start()` always runs after it — the app ends
+`disposed`, never resurrected.
+
+## Testing pips
+
+`testPip` is the typed unit-test builder: satisfy a pip's needs directly
+with fakes — no real providers, no dependency chain — and the compiler
+holds the same line it holds in production. A missing fake means `boot()`
+does not compile; a fake of the wrong shape fails at the `.provide()`
+call site:
+
+```ts
+import { testPip } from '@arki/dot/test-harness';
+
+const app = await testPip(catalog)
+  .provide(Db, fakeDb)             // token need
+  .provide('cache', fakeKv)        // anonymous need — wire key is the alias
+  .boot();
+
+expect(app.services.catalog.list()).toEqual([]);
+await app.dispose();
+```
+
+The fakes are published by a synthetic first pip, so lifecycle semantics
+are the real kernel's — reverse-order teardown, lazy auto-dispose, and
+`$config` all behave exactly as in production. `service.lazy<T>()` needs
+accept a plain `T` fake (lifted automatically) or `lazyOf(value)`.
+
+For integration tests across several real pips, `testApp([...pips])`
+builds an app from an erased pip array (runtime validation only), and
+`bootTestApp` is the one-line boot-and-return variant.
+
+## Operations
+
+Two kernel helpers close the gap between "boots on my machine" and "runs
+under a process manager":
+
+```ts
+const app = await defineApp('shop', { hookTimeoutMs: 30_000 })
+  .use(/* ... */)
+  .start();
+
+hookSignals(app); // SIGTERM/SIGINT → stop() + dispose() → re-raise
+```
+
+- **`hookSignals(app, { timeoutMs? })`** — graceful shutdown wiring. The
+  first signal drains the app (bounded by `timeoutMs`, default 10 s) and
+  re-raises itself so the exit status keeps standard signal semantics; a
+  second signal falls through to the runtime default (immediate kill).
+  Returns an unhook function.
+- **`hookTimeoutMs`** — a per-hook watchdog. Any `boot`/`start`/`stop`/
+  `dispose` hook exceeding the budget fails with `DOT_LIFECYCLE_E015`
+  naming the pip and hook, and the kernel applies its normal rollback or
+  aggregation rules. Your app cannot hang silently at boot.
+
 ## Pip authoring
 
 `pip(config)` accepts a `needs` shape plus five lifecycle hooks. Hook
@@ -106,7 +489,7 @@ contexts carry the needed services (typed, under your local aliases) and
 | `boot`      | Open connections; the returned record is what the pip provides.     |
 | `start`     | Begin processing (workers, subscribers, schedulers).                |
 | `stop`      | Stop processing in reverse declaration order.                       |
-| `dispose`   | Free resources after `stop`.                                        |
+| `dispose`   | Free resources after `stop`; lazy handles auto-clean afterwards.    |
 
 Wiring is compile-time checked: `.use(pip)` fails to typecheck when the
 pip's needs aren't satisfied by earlier `.use()` calls, or when its
@@ -122,7 +505,7 @@ order is boot order — same input, same order, every time.
 `defineApp(name)` returns a builder. Calling `.use(pip)` accumulates
 pips. The lifecycle then flows:
 
-```
+```text
 defined ──configure()──▶ configured ──boot()──▶ booted ──start()──▶ started
                                                                        │
                        disposed ◀──dispose()── stopped ◀──stop()───────┘
@@ -131,7 +514,20 @@ defined ──configure()──▶ configured ──boot()──▶ booted ─
 `boot()` runs `configure()` implicitly if you skipped it. `start()` runs
 `boot()` implicitly. `stop()` and `dispose()` always run in reverse
 declaration order, even when an earlier hook failed — failure isolation is
-part of the contract.
+part of the contract. A boot failure rolls back every already-booted pip
+before throwing.
+
+Runtime failures carry stable codes (`DotLifecycleError.code`):
+
+| Code                 | Meaning                                              |
+| -------------------- | ---------------------------------------------------- |
+| `DOT_LIFECYCLE_E011` | Pip registered twice.                                |
+| `DOT_LIFECYCLE_E012` | A need has no provider among earlier pips.           |
+| `DOT_LIFECYCLE_E013` | A published wire key collides with an earlier one.   |
+| `DOT_LIFECYCLE_E014` | A service key uses the reserved `$` (kernel) prefix. |
+| `DOT_LIFECYCLE_E015` | A hook exceeded the `hookTimeoutMs` watchdog.        |
+
+(Full table including hook-failure codes: [docs/lifecycle.md](./docs/lifecycle.md).)
 
 ## CLI
 
@@ -151,12 +547,18 @@ dot explain --app ./my-app.ts
 # Run boot-time diagnostics; non-zero exit if any check fails.
 dot doctor --app ./my-app.ts
 
+# Render the pip graph as Mermaid flowchart source. explain shows
+# declaration (= boot) order; doctor boots and shows the OBSERVED wiring.
+dot doctor --app ./my-app.ts --graph
+
 # Every command supports --json for agent-friendly output.
 dot explain --app ./my-app.ts --json | jq '.data.pips'
 ```
 
 The CLI emits the same envelope shape as the in-process diagnostics snapshot
-(`app.diagnostics`), so the same downstream tools can consume either.
+(`app.diagnostics`), so the same downstream tools can consume either. The
+manifest's dependency edges are **observed, not declared** — the kernel
+records which pip's published service satisfied which need during boot.
 
 ### `dot new <app-name>`
 
@@ -177,7 +579,14 @@ ship with the published tarball.
 `@arki/dot` is intentionally small: it defines the contracts (pip shape,
 lifecycle hooks, manifest schema, diagnostics envelope) and runs them. Adapters
 that bridge databases, queues, auth providers, and HTTP routers live in their
-own packages and consume `@arki/dot` as a peer dependency.
+own packages and consume `@arki/dot` as a peer dependency:
+
+```ts
+import { env } from '@arki/env/dot';
+import { db } from '@arki/db/dot';
+import { kv } from '@arki/kv/dot';
+import { eventSourcing } from '@arki/event-sourcing/dot';
+```
 
 This keeps the kernel free of optional dependencies and lets each adapter
 ship at its own cadence.
@@ -189,8 +598,8 @@ The full docs live in [`docs/`](./docs):
 - [Principles](./docs/principles.md) — **read first.** The five rules every
   API, error, and PR is measured against. Slightly playful, very precise.
 - [Quickstart](./docs/quickstart.md) — boot your first app in five minutes.
-- [Pip authoring](./docs/pip-authoring.md) — write your own `DotPip`.
-- [Lifecycle](./docs/lifecycle.md) — the 5-hook contract.
+- [Pip authoring](./docs/pip-authoring.md) — write your own pip.
+- [Lifecycle](./docs/lifecycle.md) — the 5-hook contract, idempotency, error codes.
 - [Diagnostics](./docs/diagnostics.md) — `app.manifest`, `app.diagnostics`,
   `dot explain`, `dot doctor`.
 - [Adapter authoring](./docs/adapter-authoring.md) — expose your package as

package/dist/cli/index.d.ts

@@ -37,6 +37,8 @@ export type CliArgs = {
     force?: boolean;
     /** `--observability` (only honored by `doctor`). */
     observability?: boolean;
+    /** `--graph` (honored by `explain` and `doctor`). */
+    graph?: boolean;
 };
 /**
  * Parse argv into a typed shape. Exported so tests can exercise it without
@@ -49,6 +51,7 @@ export declare function parseArgs(argv: readonly string[]): CliArgs;
  */
 export declare function runExplain(discovered: DiscoveredApp, opts: {
     json: boolean;
+    graph?: boolean;
     out?: (line: string) => void;
     now?: () => Date;
 }): Promise<DotCliEnvelope<unknown>>;
@@ -62,6 +65,8 @@ type DoctorRunOptions = {
      * present. Default `false`.
      */
     observability?: boolean;
+    /** When `true`, emit the pip graph (Mermaid) instead of diagnostics. */
+    graph?: boolean;
 };
 /**
  * Run `doctor` on a discovered app. The CLI owns boot+dispose only when it

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA0C/E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA+G1D;AAQD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACtE,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAgBlC;AAED,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAoDlC;AA0DD,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGhE;AAeD;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA+C/E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,qDAAqD;IACrD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAkH1D;AAQD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACvF,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAsBlC;AAED,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAoElC;AA0DD,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGhE;AAeD;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}

package/dist/cli/index.js

@@ -25,6 +25,7 @@ import { runNew } from './new.js';
 import { probeObservability } from './observability-probe.js';
 import { renderDoctor } from './render-doctor.js';
 import { renderExplain } from './render-explain.js';
+import { renderGraph } from './render-graph.js';
 const debugCli = createDebugLogger('arki:dot:cli');
 const VERSION = '0.1.0';
 const HELP_TEXT = `dot — CLI for inspecting and scaffolding DOT apps
@@ -46,6 +47,10 @@ Common options:
   --app <path>           Path to the app entry file (default: discovers
                          ./dot.config.ts, ./src/app.ts, or ./app.ts)
   --cwd <dir>            Working directory (default: current)
+  --graph                Emit the pip graph as Mermaid flowchart source
+                         instead of the standard output. explain shows
+                         declaration (= boot) order; doctor shows the
+                         wiring observed during boot. Composes with --json.
 
 \`doctor\` options:
   --observability        Also probe whether an OpenTelemetry SDK is
@@ -116,6 +121,7 @@ export function parseArgs(argv) {
                 'dry-run': { type: 'boolean', default: false },
                 force: { type: 'boolean', default: false },
                 observability: { type: 'boolean', default: false },
+                graph: { type: 'boolean', default: false },
             },
         });
     }
@@ -157,6 +163,7 @@ export function parseArgs(argv) {
         dryRun: values['dry-run'] ?? false,
         force: values.force ?? false,
         observability: values.observability ?? false,
+        graph: values.graph ?? false,
     };
 }
 /** Discovery wrapper — returns `null` for help/version commands. */
@@ -182,6 +189,9 @@ export async function runExplain(discovered, opts) {
     catch (err) {
         throw wrapLifecycleError(err, 'configure');
     }
+    if (opts.graph === true) {
+        return renderGraph({ manifest: configured.manifest, command: 'explain' }, { json: opts.json, out: opts.out, now: opts.now });
+    }
     return renderExplain({ manifest: configured.manifest }, { json: opts.json, out: opts.out, now: opts.now });
 }
 /**
@@ -198,6 +208,9 @@ export async function runDoctor(discovered, opts) {
     // Already-booted app: just read diagnostics, don't touch lifecycle.
     if (!guards.isDotAppBuilder(discovered) && !guards.isDotAppConfigured(discovered)) {
         const app = discovered;
+        if (opts.graph === true) {
+            return renderGraph({ manifest: app.manifest, command: 'doctor' }, { json: opts.json, out: opts.out, now: opts.now });
+        }
         const diagnostics = applyObservabilityProbe(app.diagnostics, opts.observability ?? false);
         return renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
     }
@@ -226,6 +239,13 @@ export async function runDoctor(discovered, opts) {
         debugCli('boot threw, falling back to configured diagnostics: %O', err);
     }
     try {
+        if (opts.graph === true) {
+            // Post-boot manifest carries the observed wiring edges; after a boot
+            // failure it carries the edges recorded up to the failing pip.
+            const manifest = bootedApp ? bootedApp.manifest : configured.manifest;
+            const graphEnvelope = renderGraph({ manifest, command: 'doctor' }, { json: opts.json, out: opts.out, now: opts.now });
+            return bootThrew ? { ...graphEnvelope, status: 'failure' } : graphEnvelope;
+        }
         const rawDiagnostics = bootedApp ? bootedApp.diagnostics : configured.diagnostics;
         const diagnostics = applyObservabilityProbe(rawDiagnostics, opts.observability ?? false);
         const envelope = renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
@@ -369,7 +389,7 @@ export async function main(options) {
     }
     try {
         const discovered = await loadApp(args);
-        const opts = { json: args.json, out: stdout, now: nowFactory };
+        const opts = { json: args.json, graph: args.graph, out: stdout, now: nowFactory };
         let envelope;
         if (args.command === 'explain') {
             envelope = await runExplain(discovered, opts);