@arki/dot 0.3.0 → 0.4.0

package/src/test-harness.ts

@@ -1,32 +1,32 @@
 /**
- * Test harness for unit-testing DOT pips.
+ * Test harness for unit-testing DOT plugins.
  *
- * Provides `testApp` — a convenience wrapper that lets pip authors verify
+ * Provides `testApp` — a convenience wrapper that lets plugin authors verify
  * lifecycle behaviour, registration, and service publishing without dragging
  * in concrete framework dependencies.
  *
- * NOTE: `testApp` takes an erased pip array, so the compile-time wiring
+ * NOTE: `testApp` takes an erased plugin array, so the compile-time wiring
  * guard does not apply here — the kernel's runtime validation (unsatisfied
  * needs, collisions) still does. Use `defineApp(...).use(...)` chains in
  * tests that should exercise the type-level guard.
  *
  * @example
- *   import { testApp, pip } from '@arki/dot';
+ *   import { testApp, plugin } from '@arki/dot';
  *
- *   const myPip = pip({
+ *   const myPlugin = plugin({
  *     name: 'counter',
  *     boot: () => ({ counter: { value: 0 } }),
  *   });
  *
  *   it('publishes a counter service', async () => {
- *     const app = await bootTestApp<{ counter: { value: number } }>([myPip]);
+ *     const app = await bootTestApp<{ counter: { value: number } }>([myPlugin]);
  *     expect(app.services.counter.value).toBe(0);
  *     await app.dispose();
  *   });
  */
 
 import type { DotApp, DotAppBuilder } from './define-app.js';
-import type { AnyPip, EmptyShape, Pip, ServiceRecord, Token } from './pip-contract.js';
+import type { AnyPlugin, EmptyShape, Plugin, ServiceRecord, Token } from './plugin-contract.js';
 import { defineApp } from './define-app.js';
 
 export type TestAppOptions = {
@@ -37,24 +37,24 @@ export type TestAppOptions = {
 };
 
 /**
- * Guard-free view of the builder for erased pip arrays. The runtime `use`
+ * Guard-free view of the builder for erased plugin arrays. The runtime `use`
  * implementation accepts the missing guard argument (it is type-level
  * only), so this seam is safe — the kernel still validates wiring at boot.
  */
 type LooseBuilder = {
-  use(pip: AnyPip): LooseBuilder;
+  use(plugin: AnyPlugin): LooseBuilder;
 };
 
 /**
- * Build a DOT app builder pre-populated with the given pips, ready to
+ * Build a DOT app builder pre-populated with the given plugins, ready to
  * `.configure()`, `.boot()` or `.start()` from a test.
  */
 export function testApp<TServices extends ServiceRecord = EmptyShape>(
-  pips: readonly AnyPip[] = [],
+  plugins: readonly AnyPlugin[] = [],
   options: TestAppOptions = {},
 ): DotAppBuilder<TServices> {
   let builder: unknown = defineApp(options.name ?? 'test-app', { config: options.config });
-  for (const p of pips) {
+  for (const p of plugins) {
     builder = (builder as LooseBuilder).use(p);
   }
   return builder as DotAppBuilder<TServices>;
@@ -65,87 +65,87 @@ export function testApp<TServices extends ServiceRecord = EmptyShape>(
  * calling `app.dispose()` when finished.
  */
 export async function bootTestApp<TServices extends ServiceRecord = EmptyShape>(
-  pips: readonly AnyPip[] = [],
+  plugins: readonly AnyPlugin[] = [],
   options: TestAppOptions = {},
 ): Promise<DotApp<TServices>> {
-  return testApp<TServices>(pips, options).boot();
+  return testApp<TServices>(plugins, options).boot();
 }
 
 /**
- * Rest-tuple guard for {@link TestPipBuilder.boot} — the same trick the app
+ * Rest-tuple guard for {@link TestPluginBuilder.boot} — the same trick the app
  * builder's `UseGuard` uses. While any need is still unprovided, `boot()`
  * demands an impossible second argument, so the call site fails with
  * "Expected 2 arguments, but got 1" and the error payload names the
  * missing wire keys and their types.
  */
-type TestPipBootGuard<TRemaining extends ServiceRecord> = keyof TRemaining extends never
+type TestPluginBootGuard<TRemaining extends ServiceRecord> = keyof TRemaining extends never
   ? readonly []
   : readonly [
       needs: {
-        readonly 'DOT-TEST: pip needs still unprovided — call .provide() for each': {
+        readonly 'DOT-TEST: plugin needs still unprovided — call .provide() for each': {
           readonly [K in keyof TRemaining]: TRemaining[K];
         };
       },
     ];
 
 /**
- * Typed unit-test builder for a single pip — see {@link testPip}.
+ * Typed unit-test builder for a single plugin — see {@link testPlugin}.
  *
  * `TRemaining` tracks the wire keys not yet covered by `.provide()`;
  * `TServices` accumulates what the booted app will expose (the fakes plus
- * the pip's own provides).
+ * the plugin's own provides).
  */
-export type TestPipBuilder<TRemaining extends ServiceRecord, TServices extends ServiceRecord> = {
+export type TestPluginBuilder<TRemaining extends ServiceRecord, TServices extends ServiceRecord> = {
   /**
    * Satisfy one need directly with a fake. Token form — the token names
    * the wire key and carries the type:
    *
    * ```ts
-   * testPip(reports).provide(Db, fakeDb)
+   * testPlugin(reports).provide(Db, fakeDb)
    * ```
    */
   provide<K extends keyof TRemaining & string, T extends TRemaining[K]>(
     token: Token<T, K>,
     value: T,
-  ): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, T>>>;
+  ): TestPluginBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, T>>>;
   /**
    * Satisfy one need directly with a fake. Key form — for anonymous
    * `service<T>()` needs, where the wire key is the property name:
    *
    * ```ts
-   * testPip(billing).provide('db', fakeDb)
+   * testPlugin(billing).provide('db', fakeDb)
    * ```
    */
   provide<K extends keyof TRemaining & string>(
     key: K,
     value: TRemaining[K],
-  ): TestPipBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, TRemaining[K]>>>;
-  /** Boot the pip against the provided fakes. Compile error until every need is provided. */
-  boot(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
-  /** Boot + start. Same guard as {@link TestPipBuilder.boot}. */
-  start(...guard: TestPipBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+  ): TestPluginBuilder<Omit<TRemaining, K>, TServices & Readonly<Record<K, TRemaining[K]>>>;
+  /** Boot the plugin against the provided fakes. Compile error until every need is provided. */
+  boot(...guard: TestPluginBootGuard<TRemaining>): Promise<DotApp<TServices>>;
+  /** Boot + start. Same guard as {@link TestPluginBuilder.boot}. */
+  start(...guard: TestPluginBootGuard<TRemaining>): Promise<DotApp<TServices>>;
 };
 
-/** Internal accumulating state for {@link testPip}. */
-type TestPipState = {
-  readonly pip: AnyPip;
+/** Internal accumulating state for {@link testPlugin}. */
+type TestPluginState = {
+  readonly plugin: AnyPlugin;
   readonly fakes: Readonly<Record<string, unknown>>;
   readonly options: TestAppOptions;
 };
 
 /**
- * Unit-test a single pip with **typed overrides** — the compile-checked
+ * Unit-test a single plugin with **typed overrides** — the compile-checked
  * counterpart to {@link testApp}'s erased arrays.
  *
- * Each `.provide()` satisfies one of the pip's needs directly (no real
- * provider pip, no dependency chain) and removes it from the builder's
+ * Each `.provide()` satisfies one of the plugin's needs directly (no real
+ * provider plugin, no dependency chain) and removes it from the builder's
  * remaining-needs type. `boot()` only compiles once every need is covered,
  * and a fake of the wrong shape fails at the `.provide()` call site:
  *
  * ```ts
- * import { testPip } from '@arki/dot/test-harness';
+ * import { testPlugin } from '@arki/dot/test-harness';
  *
- * const app = await testPip(catalog)
+ * const app = await testPlugin(catalog)
  *   .provide(Db, fakeDb)          // token need
  *   .provide('cache', fakeKv)     // anonymous need — wire key is the alias
  *   .boot();
@@ -157,38 +157,39 @@ type TestPipState = {
  * `service.lazy<T>()` needs accept either a plain `T` fake (the kernel
  * lifts it) or a `Lazy<T>` handle (`lazyOf(value)` is handy here).
  * Lifecycle semantics are the real kernel's — the fakes are published by a
- * synthetic first pip, so reverse-order teardown and lazy auto-dispose
+ * synthetic first plugin, so reverse-order teardown and lazy auto-dispose
  * behave exactly as in production.
  */
-export function testPip<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(
-  pip: Pip<TNeeds, TProvides>,
+export function testPlugin<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(
+  plugin: Plugin<TNeeds, TProvides>,
   options: TestAppOptions = {},
-): TestPipBuilder<TNeeds, TProvides> {
+): TestPluginBuilder<TNeeds, TProvides> {
   // Erasure seam — same boundary as `makeBuilder` in define-app.ts: the
   // runtime impl is untyped, the type parameters do all the guarding.
-  return makeTestPipBuilder({ pip: pip as AnyPip, fakes: {}, options }) as TestPipBuilder<TNeeds, TProvides>;
+  return makeTestPluginBuilder({ plugin: plugin as AnyPlugin, fakes: {}, options }) as TestPluginBuilder<TNeeds, TProvides>;
 }
 
 /**
- * Erased implementation behind {@link testPip}. Mirrors `makeBuilder` in
+ * Erased implementation behind {@link testPlugin}. Mirrors `makeBuilder` in
  * `define-app.ts`: the runtime is untyped, the single cast at the return
  * is the seam, and the type parameters do all the guarding.
  */
-function makeTestPipBuilder(state: TestPipState): TestPipBuilder<ServiceRecord, ServiceRecord> {
+function makeTestPluginBuilder(state: TestPluginState): TestPluginBuilder<ServiceRecord, ServiceRecord> {
   const bootApp = async (): Promise<DotApp<ServiceRecord>> => {
-    const pips: AnyPip[] = [];
+    const plugins: AnyPlugin[] = [];
     if (Object.keys(state.fakes).length > 0) {
       const fakes = { ...state.fakes };
-      pips.push({
-        name: `test:fakes(${state.pip.name})`,
+      plugins.push({
+        name: `test:fakes(${state.plugin.name})`,
         needs: {},
+        actions: [],
         renames: {},
         hooks: { boot: () => fakes },
       });
     }
-    pips.push(state.pip);
-    return testApp<ServiceRecord>(pips, {
-      name: state.options.name ?? `test:${state.pip.name}`,
+    plugins.push(state.plugin);
+    return testApp<ServiceRecord>(plugins, {
+      name: state.options.name ?? `test:${state.plugin.name}`,
       ...(state.options.config === undefined ? {} : { config: state.options.config }),
     }).boot();
   };
@@ -196,7 +197,7 @@ function makeTestPipBuilder(state: TestPipState): TestPipBuilder<ServiceRecord,
   const impl = {
     provide(tokenOrKey: Token<unknown, string> | string, value: unknown) {
       const key = typeof tokenOrKey === 'string' ? tokenOrKey : tokenOrKey.key;
-      return makeTestPipBuilder({ ...state, fakes: { ...state.fakes, [key]: value } });
+      return makeTestPluginBuilder({ ...state, fakes: { ...state.fakes, [key]: value } });
     },
     async boot(..._guard: readonly unknown[]) {
       return bootApp();
@@ -207,5 +208,5 @@ function makeTestPipBuilder(state: TestPipState): TestPipBuilder<ServiceRecord,
       return app;
     },
   };
-  return impl as TestPipBuilder<ServiceRecord, ServiceRecord>;
+  return impl as TestPluginBuilder<ServiceRecord, ServiceRecord>;
 }

package/src/timeline.ts

@@ -1,7 +1,7 @@
 /**
  * ASCII waterfall renderer for DOT lifecycle diagnostics.
  *
- * Given a `DotDiagnosticsSnapshot`, builds a compact per-phase, per-pip
+ * Given a `DotDiagnosticsSnapshot`, builds a compact per-phase, per-plugin
  * duration chart suitable for printing in a terminal or embedding in a
  * `dot doctor` text report. No colour, no Unicode beyond `█` so the
  * output stays clean in log aggregators and CI.
@@ -38,7 +38,7 @@ export type RenderTimelineOptions = {
   /** Maximum bar width in characters (default `50`). */
   readonly barWidth?: number;
   /**
-   * When `true`, also emit any pip's diagnostic `issues[]` underneath
+   * When `true`, also emit any plugin's diagnostic `issues[]` underneath
    * the bar so failure reasons are visible in the timeline view.
    * Default `true`.
    */
@@ -78,8 +78,8 @@ export function renderTimeline(snapshot: DotDiagnosticsSnapshot, opts: RenderTim
   lines.push(title);
   lines.push('─'.repeat(title.length));
 
-  // Layout: 2-space indent, 10-char pip column, 8-char duration column, then bar.
-  const PIP_COL = 12;
+  // Layout: 2-space indent, 10-char plugin column, 8-char duration column, then bar.
+  const PLUGIN_COL = 12;
   const DUR_COL = 8;
   const indent = '  ';
 
@@ -94,9 +94,9 @@ export function renderTimeline(snapshot: DotDiagnosticsSnapshot, opts: RenderTim
       const durationMs = entry.durationMs ?? 0;
       const bar = makeBar(durationMs, maxDuration, barWidth);
       const failedMark = entry.state === 'failed' ? ' ✗' : '';
-      const pipCol = entry.pip.padEnd(PIP_COL);
+      const pluginCol = entry.plugin.padEnd(PLUGIN_COL);
       const durCol = formatDuration(durationMs).padStart(DUR_COL);
-      lines.push(`${indent}${pipCol}${durCol}  ${bar}${failedMark}`);
+      lines.push(`${indent}${pluginCol}${durCol}  ${bar}${failedMark}`);
       if (showIssues && entry.issues.length > 0) {
         for (const issue of entry.issues) {
           lines.push(`${indent}  └─ ${issue.code}: ${issue.message}`);

package/templates/app-minimal/AGENTS.md.tmpl

@@ -2,7 +2,7 @@
 
 ## What this app is
 
-A DOT app composed via `defineApp(...).use(pip).boot()`. The runtime
+A DOT app composed via `defineApp(...).use(plugin).boot()`. The runtime
 graph is statically inspectable via `app.manifest` and runtime-inspectable
 via `app.diagnostics`.
 
@@ -26,7 +26,7 @@ command exits zero.
 - Env schema lives at `src/env.ts` — keep it narrow; one entry per env
   key the app actually reads.
 - Tests live under `tests/` and import the app via the `src/` barrel.
-- Add new pips by wiring `.use(pip(options))` between
+- Add new plugins by wiring `.use(plugin(options))` between
   `defineApp('{{name}}')` and `.boot()` in `src/app.ts`.
 
 ## Public / private boundaries
@@ -36,8 +36,8 @@ command exits zero.
   app reads belong here.
 - Don't reach into `@arki/dot` internals (anything under
   `@arki/dot/kernel`, `@arki/dot/legacy`, or `dist/` subpaths). Use the
-  public `defineApp` / `pip` API from `@arki/dot` and the
-  `pip` / `service` / `rename` symbols from `@arki/dot/pip`.
+  public `defineApp` / `plugin` API from `@arki/dot` and the
+  `plugin` / `service` / `rename` symbols from `@arki/dot/plugin`.
 
 ## DOT artifact locations
 
@@ -47,14 +47,14 @@ command exits zero.
   `started` -> `stopped` -> `disposed`).
 - Errors carry stable `code`, `severity`, `remediation`, `docsUrl`.
 
-## Adding a pip
+## Adding a plugin
 
 1. Install the adapter package: `{{pkgManager}} add @arki/<pkg>`.
-2. Import its DOT adapter: `import { <pip> } from '@arki/<pkg>/dot';`.
+2. Import its DOT adapter: `import { <plugin> } from '@arki/<pkg>/dot';`.
 3. Chain it into the builder before `.boot()`:
-   `.use(<pip>(options))`.
-4. Verify with `bunx dot explain --json` — the new pip should appear
-   under `.data.pips`.
+   `.use(<plugin>(options))`.
+4. Verify with `bunx dot explain --json` — the new plugin should appear
+   under `.data.plugins`.
 
 ## Diagnostics triage
 

package/templates/app-minimal/README.md.tmpl

@@ -17,7 +17,7 @@ bunx dot explain --json
 bunx dot doctor --json
 ```
 
-`dot explain` prints the static graph (pips, services, routes, dependencies,
+`dot explain` prints the static graph (plugins, services, routes, dependencies,
 lifecycle hooks). `dot doctor` boots the app and prints the runtime
 diagnostics envelope (the same five arrays, plus issues).
 

package/templates/app-minimal/tests/boot.test.ts.tmpl

@@ -17,7 +17,7 @@ test('app boots and exposes env service', () => {
 
 test('diagnostics has all 5 arrays', () => {
   const { diagnostics } = booted;
-  expect(diagnostics.pips).toBeDefined();
+  expect(diagnostics.plugins).toBeDefined();
   expect(diagnostics.routes).toBeDefined();
   expect(diagnostics.services).toBeDefined();
   expect(diagnostics.lifecycle).toBeDefined();

package/src/cli/render-openapi.ts

@@ -1,147 +0,0 @@
-/**
- * Renderer for `dot explain --openapi`.
- *
- * Emits an OpenAPI 3.1 document straight from `manifest.routes` — no boot
- * required. Adapters (e.g. `@arki/http`'s `registerRoutes`) convert their
- * validation schemas to JSON Schema at `configure` time and register them
- * via `ctx.registerRoute`, so the manifest already carries everything the
- * document needs: methods, paths, per-location input schemas, output
- * schemas, and the `streaming` flag for `text/event-stream` responses.
- *
- * Deterministic: paths and operations follow manifest registration order
- * (which follows pip declaration order). Only `transport: 'http'` routes
- * are rendered — rpc mounts have their own schema story.
- */
-
-import type { DotAppManifest, RouteManifest } from '../manifest.js';
-import type { DotCliEnvelope, RenderOptions } from './render-explain.js';
-
-/** Envelope payload for OpenAPI output. */
-export type OpenApiData = {
-  format: 'openapi';
-  /** OpenAPI 3.1 document. */
-  document: Record<string, unknown>;
-};
-
-function openApiPath(path: string): string {
-  return path.replaceAll(/:(\w+)/g, '{$1}');
-}
-
-function pathParamNames(path: string): readonly string[] {
-  return [...path.matchAll(/:(\w+)/g)]
-    .map(match => match[1])
-    .filter((name): name is string => name !== undefined);
-}
-
-function buildOperation(route: RouteManifest): Record<string, unknown> {
-  const parameters: Record<string, unknown>[] = pathParamNames(route.path ?? '').map(name => ({
-    name,
-    in: 'path',
-    required: true,
-    schema: { type: 'string' },
-  }));
-
-  const querySchema = route.input?.query;
-  if (querySchema !== undefined) {
-    const properties = (querySchema['properties'] ?? {}) as Readonly<Record<string, unknown>>;
-    const required = new Set(querySchema['required'] as readonly string[] | undefined);
-    for (const [name, propertySchema] of Object.entries(properties)) {
-      parameters.push({ name, in: 'query', required: required.has(name), schema: propertySchema });
-    }
-  }
-
-  const operation: Record<string, unknown> = {
-    operationId: route.id,
-    tags: [route.pip],
-  };
-  if (route.description !== undefined) operation['summary'] = route.description;
-  if (parameters.length > 0) operation['parameters'] = parameters;
-
-  const bodySchema = route.input?.body;
-  if (bodySchema !== undefined) {
-    operation['requestBody'] = {
-      required: true,
-      content: { 'application/json': { schema: bodySchema } },
-    };
-  }
-
-  if (route.streaming === true) {
-    operation['responses'] = {
-      '200': {
-        description: 'event stream',
-        content: {
-          'text/event-stream': route.output === undefined ? {} : { schema: route.output },
-        },
-      },
-    };
-  } else if (route.output === undefined) {
-    operation['responses'] = { '200': { description: 'success' } };
-  } else {
-    operation['responses'] = {
-      '200': {
-        description: 'success',
-        content: { 'application/json': { schema: route.output } },
-      },
-    };
-  }
-
-  return operation;
-}
-
-/**
- * Build an OpenAPI 3.1 document from a manifest. First registration wins
- * on a method+path collision — collisions are an app bug the serving
- * adapter rejects at boot; the document renderer stays total.
- */
-export function buildOpenApiDocument(manifest: DotAppManifest): Record<string, unknown> {
-  const paths: Record<string, Record<string, unknown>> = {};
-  for (const route of manifest.routes) {
-    if (route.transport !== 'http') continue;
-    if (route.path === undefined) continue;
-    const path = openApiPath(route.path);
-    const method = (route.method ?? 'GET').toLowerCase();
-    const entry = (paths[path] ??= {});
-    if (entry[method] !== undefined) continue;
-    entry[method] = buildOperation(route);
-  }
-  return {
-    openapi: '3.1.0',
-    info: {
-      title: manifest.app.name,
-      version: manifest.app.version ?? '0.0.0',
-    },
-    paths,
-  };
-}
-
-/**
- * Render the OpenAPI output. Plain mode prints the document as JSON
- * (pipe it into a file or a swagger viewer); `--json` wraps it in the
- * standard CLI envelope under `data.document`.
- */
-export function renderOpenApi(
-  source: { manifest: DotAppManifest; command: 'explain' },
-  opts: RenderOptions,
-): DotCliEnvelope<OpenApiData> {
-  const document = buildOpenApiDocument(source.manifest);
-  const nowFactory = opts.now ?? (() => new Date());
-  const envelope: DotCliEnvelope<OpenApiData> = {
-    status: 'success',
-    command: source.command,
-    generatedAt: nowFactory().toISOString(),
-    data: { format: 'openapi', document },
-    errors: [],
-  };
-
-  const out =
-    opts.out ??
-    ((line: string) => {
-      process.stdout.write(line);
-    });
-  if (opts.json) {
-    out(`${JSON.stringify(envelope, null, 2)}\n`);
-  } else {
-    out(`${JSON.stringify(document, null, 2)}\n`);
-  }
-  return envelope;
-}