@arki/dot 0.1.1 → 0.1.3

package/src/cli/render-explain.ts

@@ -0,0 +1,161 @@
+/**
+ * Renderers for `dot explain`.
+ *
+ * Reads a configured (or booted) app's `manifest` and emits one of:
+ *   - JSON envelope to stdout (when --json)
+ *   - human-readable plain text to stdout (default)
+ *
+ * The JSON envelope shape matches the broader release-tooling envelope so
+ * agents can parse the output identically across CLI surfaces.
+ */
+
+import type { DiagnosticIssue } from '../diagnostics.js';
+import type { DotAppManifest } from '../manifest.js';
+
+export type DotCliEnvelopeStatus = 'success' | 'failure' | 'warning';
+
+export type DotCliEnvelope<T = unknown> = {
+  status: DotCliEnvelopeStatus;
+  command: string;
+  generatedAt: string;
+  data: T;
+  errors: DiagnosticIssue[];
+};
+
+export type ExplainSource = {
+  /** The static manifest produced by configure (or read off a booted app). */
+  manifest: DotAppManifest;
+};
+
+export type RenderOptions = {
+  /** Set to true to emit JSON to stdout; otherwise pretty text. */
+  json: boolean;
+  /** Override clock for deterministic test output. */
+  now?: () => Date;
+  /** Override stdout sink. Defaults to `process.stdout.write`. */
+  out?: (line: string) => void;
+};
+
+const defaultOut = (line: string) => {
+  process.stdout.write(line);
+};
+
+function nowIso(opts: RenderOptions): string {
+  const factory = opts.now ?? (() => new Date());
+  return factory().toISOString();
+}
+
+/**
+ * Build the envelope without writing anything. Useful for tests that need
+ * to assert shape and for embedding the CLI logic from other tools.
+ */
+export function buildExplainEnvelope(source: ExplainSource, opts: RenderOptions): DotCliEnvelope<DotAppManifest> {
+  return {
+    status: 'success',
+    command: 'explain',
+    generatedAt: nowIso(opts),
+    data: source.manifest,
+    errors: [],
+  };
+}
+
+function pad(s: string, width: number): string {
+  return s.length >= width ? s : s + ' '.repeat(width - s.length);
+}
+
+function renderTextManifest(manifest: DotAppManifest): string {
+  const lines: string[] = [];
+  const title = `App: ${manifest.app.name}${manifest.app.version ? `@${manifest.app.version}` : ''}`;
+  lines.push(title);
+  lines.push('='.repeat(title.length));
+  lines.push('');
+
+  // Pips
+  lines.push(`Pips (${manifest.pips.length})`);
+  if (manifest.pips.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const widthName = Math.max(6, ...manifest.pips.map(p => p.name.length));
+    lines.push(`  ${pad('NAME', widthName)}  VERSION  DEPENDENCIES`);
+    for (const p of manifest.pips) {
+      const version = p.version ?? '-';
+      const deps = p.dependencies.length > 0 ? p.dependencies.join(', ') : '-';
+      lines.push(`  ${pad(p.name, widthName)}  ${pad(version, 7)}  ${deps}`);
+    }
+  }
+  lines.push('');
+
+  // Services
+  lines.push(`Services (${manifest.services.length})`);
+  if (manifest.services.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const widthName = Math.max(4, ...manifest.services.map(s => s.name.length));
+    const widthKind = Math.max(4, ...manifest.services.map(s => s.kind.length));
+    lines.push(`  ${pad('NAME', widthName)}  ${pad('KIND', widthKind)}  PLUGIN`);
+    for (const s of manifest.services) {
+      lines.push(`  ${pad(s.name, widthName)}  ${pad(s.kind, widthKind)}  ${s.pip}`);
+    }
+  }
+  lines.push('');
+
+  // Routes
+  lines.push(`Routes (${manifest.routes.length})`);
+  if (manifest.routes.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const widthId = Math.max(2, ...manifest.routes.map(r => r.id.length));
+    const widthMethod = Math.max(6, ...manifest.routes.map(r => (r.method ?? '-').length));
+    lines.push(`  ${pad('ID', widthId)}  ${pad('METHOD', widthMethod)}  PATH/TRANSPORT  PLUGIN`);
+    for (const r of manifest.routes) {
+      const method = r.method ?? '-';
+      const target = r.path ?? `(${r.transport})`;
+      lines.push(`  ${pad(r.id, widthId)}  ${pad(method, widthMethod)}  ${pad(target, 14)}  ${r.pip}`);
+    }
+  }
+  lines.push('');
+
+  // Dependencies
+  lines.push(`Dependencies (${manifest.dependencies.length})`);
+  if (manifest.dependencies.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const d of manifest.dependencies) {
+      lines.push(`  ${d.from} --[${d.kind}]--> ${d.to}`);
+    }
+  }
+  lines.push('');
+
+  // Lifecycle
+  lines.push(`Lifecycle hooks (${manifest.lifecycle.length})`);
+  if (manifest.lifecycle.length === 0) {
+    lines.push('  (none)');
+  } else {
+    const widthPip = Math.max(6, ...manifest.lifecycle.map(l => l.pip.length));
+    lines.push(`  ${pad('PLUGIN', widthPip)}  HOOKS`);
+    for (const l of manifest.lifecycle) {
+      const hooks = l.hooks.length > 0 ? l.hooks.join(', ') : '-';
+      lines.push(`  ${pad(l.pip, widthPip)}  ${hooks}`);
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Render the explain output. Returns the envelope so callers can act on it
+ * (e.g. set the process exit code based on `status`).
+ */
+export function renderExplain(source: ExplainSource, opts: RenderOptions): DotCliEnvelope<DotAppManifest> {
+  const envelope = buildExplainEnvelope(source, opts);
+  const out = opts.out ?? defaultOut;
+
+  if (opts.json) {
+    out(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    out(`${renderTextManifest(source.manifest)}\n`);
+  }
+
+  return envelope;
+}

package/src/define-app.ts

@@ -0,0 +1,310 @@
+/**
+ * Public entry point for the DOT kernel (v2).
+ *
+ * `defineApp(name)` returns a `DotAppBuilder` that accumulates pips via
+ * `.use(pip)`, then transitions through the 5-hook lifecycle:
+ *
+ *   defineApp -> use* -> configure() -> boot() -> start() -> stop() -> dispose()
+ *
+ * `.use()` is compile-time guarded: a pip whose `needs` are not satisfied
+ * by services provided so far — or whose provides collide with existing
+ * wire keys — fails to typecheck at the call site ("Expected 2 arguments,
+ * but got 1", with the diagnostic embedded in the expected second
+ * argument's type). Declaration order IS boot order.
+ *
+ * Most callers don't need to call `configure()` explicitly — `boot()` runs it
+ * implicitly. `boot()` is also implicit when starting from `defined` via
+ * `start()`.
+ *
+ * See `./lifecycle.ts` for hook semantics, failure ordering, idempotency rules.
+ */
+
+import type { DotDiagnosticsSnapshot } from './diagnostics.js';
+import type { DotLifecycleObserver } from './lifecycle-observer.js';
+import type { DotLifecycleState } from './lifecycle.js';
+import type { DotAppManifest } from './manifest.js';
+import type { AnyPip, EmptyShape, Pip, ServiceRecord } from './pip-contract.js';
+import { DotAppImpl } from './kernel/app-instance.js';
+import { renderTimeline } from './timeline.js';
+
+/* ------------------------------------------------------------------ */
+/* Compile-time wiring guard                                           */
+/* ------------------------------------------------------------------ */
+
+type MissingKeys<TAvail, TNeeds> = {
+  readonly [K in Exclude<keyof TNeeds, keyof TAvail>]: TNeeds[K];
+};
+
+type MismatchedKeys<TAvail, TNeeds> = {
+  readonly [K in keyof TAvail & keyof TNeeds as TAvail[K] extends TNeeds[K] ? never : K]: {
+    readonly provided: TAvail[K];
+    readonly needed: TNeeds[K];
+  };
+};
+
+type NeedsError<TAvail extends ServiceRecord, TNeeds extends ServiceRecord> = {
+  readonly 'DOT: pip needs services no earlier .use() provides': {
+    readonly missing: MissingKeys<TAvail, TNeeds>;
+    readonly mismatched: MismatchedKeys<TAvail, TNeeds>;
+  };
+};
+
+type CollisionError<TAvail, TProvides> = {
+  readonly 'DOT: pip provides wire keys already provided (use rename())': keyof TAvail & keyof TProvides;
+};
+
+/**
+ * A pip whose `boot` always throws infers `TProvides = never`, which would
+ * poison both the collision check (`keyof never` matches everything) and
+ * the accumulated record (`TAvail & never` = `never`). Such a pip provides
+ * nothing — normalize to the empty shape.
+ */
+type NormalizeProvides<TP extends ServiceRecord> = [TP] extends [never] ? EmptyShape : TP;
+
+/**
+ * Rest-tuple guard. Satisfied → `[]` (call `.use(pip)` with one argument).
+ * Violated → a required second argument of an unconstructible error type,
+ * so the call site fails with the diagnostic embedded in the expected type.
+ */
+export type UseGuard<
+  TAvail extends ServiceRecord,
+  TNeeds extends ServiceRecord,
+  TProvides extends ServiceRecord,
+> = [TAvail] extends [TNeeds]
+  ? [keyof TAvail & keyof TProvides] extends [never]
+    ? []
+    : [error: CollisionError<TAvail, TProvides>]
+  : [error: NeedsError<TAvail, TNeeds>];
+
+/* ------------------------------------------------------------------ */
+/* Public app surface                                                  */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Public DotApp surface. The internal `DotAppImpl` implements this; consumers
+ * see only these members.
+ */
+export type DotApp<TServices extends ServiceRecord> = {
+  /** App name (passed to `defineApp`). */
+  readonly name: string;
+  /** Current lifecycle state. */
+  readonly state: DotLifecycleState;
+  /**
+   * Services published by booted pips, keyed by wire key.
+   * Empty before `boot()` succeeds.
+   */
+  readonly services: TServices;
+  /** Declarative manifest — describes the static shape of the app. */
+  readonly manifest: DotAppManifest;
+  /** Point-in-time diagnostics snapshot. Re-computed on every access. */
+  readonly diagnostics: DotDiagnosticsSnapshot;
+  /**
+   * Start active work. Boots first if app is `defined` or `configured`.
+   * Idempotent while `started`. Throws if app is `failed` or `disposed`.
+   */
+  start(): Promise<void>;
+  /**
+   * Stop active work. Keeps booted resources for later cleanup.
+   * Idempotent while not `started`.
+   */
+  stop(): Promise<void>;
+  /**
+   * Release booted resources. Runs stop() first if `started`.
+   * Idempotent while `disposed`.
+   */
+  dispose(): Promise<void>;
+  /**
+   * Register an in-process lifecycle observer. Returns an unsubscribe
+   * function. Observers added here see events from this point onward —
+   * pass observers through `defineApp(name, { observers })` to catch
+   * `configure`-phase events too.
+   */
+  subscribe(observer: DotLifecycleObserver): () => void;
+  /**
+   * Render the recorded lifecycle as an ASCII waterfall. Reads from
+   * the current `diagnostics` snapshot — call after `boot()` /
+   * `dispose()` / a failure to see the full picture.
+   */
+  timeline(): string;
+};
+
+/**
+ * Intermediate type after `configure()` but before `boot()`.
+ * Exposes the manifest and diagnostics already, but no `services` yet.
+ */
+export type DotAppConfigured<TServices extends ServiceRecord> = {
+  readonly name: string;
+  readonly state: DotLifecycleState;
+  readonly manifest: DotAppManifest;
+  readonly diagnostics: DotDiagnosticsSnapshot;
+  /** Continue the lifecycle. */
+  boot(): Promise<DotApp<TServices>>;
+  start(): Promise<DotApp<TServices>>;
+  /** See {@link DotApp.subscribe}. */
+  subscribe(observer: DotLifecycleObserver): () => void;
+  /** See {@link DotApp.timeline}. */
+  timeline(): string;
+};
+
+/**
+ * Builder produced by `defineApp(name)`.
+ *
+ * `.use(pip)` is type-tracking in both directions: the pip's `needs` must
+ * be satisfied by the services accumulated so far, and its `provides`
+ * merge into the accumulated record for the next `.use()`.
+ */
+export type DotAppBuilder<TAvail extends ServiceRecord> = {
+  /**
+   * Register a pip. Compile error when the pip's needs are unsatisfied
+   * or its provides collide with existing wire keys.
+   */
+  use<TNeeds extends ServiceRecord, TProvides extends ServiceRecord>(
+    pip: Pip<TNeeds, TProvides>,
+    ...guard: UseGuard<TAvail, TNeeds, NormalizeProvides<TProvides>>
+  ): DotAppBuilder<TAvail & NormalizeProvides<TProvides>>;
+  /** Run the configure phase synchronously. Throws on configure failure. */
+  configure(): DotAppConfigured<TAvail>;
+  /** Run configure + boot. Throws on configure or boot failure. */
+  boot(): Promise<DotApp<TAvail>>;
+  /** Convenience: configure + boot + start. */
+  start(): Promise<DotApp<TAvail>>;
+};
+
+type BuilderState = {
+  appName: string;
+  appVersion?: string;
+  pips: AnyPip[];
+  config?: Readonly<Record<string, unknown>>;
+  observers?: readonly DotLifecycleObserver[];
+};
+
+/**
+ * Create a new DOT app builder.
+ *
+ * @example
+ * const app = await defineApp('my-app')
+ *   .use(dbPip)
+ *   .use(billingPip)   // billing's needs must be satisfied by now
+ *   .boot();
+ *
+ * await app.start();
+ * console.log(app.manifest);
+ * // ...
+ * await app.dispose();
+ */
+export function defineApp(
+  name: string,
+  options: {
+    version?: string;
+    config?: Readonly<Record<string, unknown>>;
+    /**
+     * In-process lifecycle observers, registered before the first phase
+     * fires. Required if you want to see `configure`-phase events — after
+     * configure runs, observers can be added post-hoc via
+     * `configured.subscribe(...)` or `app.subscribe(...)`.
+     */
+    observers?: readonly DotLifecycleObserver[];
+  } = {},
+): DotAppBuilder<EmptyShape> {
+  const state: BuilderState = {
+    appName: name,
+    appVersion: options.version,
+    pips: [],
+    config: options.config,
+    observers: options.observers,
+  };
+  return makeBuilder<EmptyShape>(state);
+}
+
+function buildImpl(state: BuilderState): DotAppImpl {
+  return new DotAppImpl({
+    appName: state.appName,
+    appVersion: state.appVersion,
+    pips: state.pips,
+    config: state.config,
+    observers: state.observers,
+  });
+}
+
+function makeBuilder<TAvail extends ServiceRecord>(state: BuilderState): DotAppBuilder<TAvail> {
+  // The `use` implementation is signature-erased (the guard exists purely
+  // at the type level); the single cast below is the same kernel boundary
+  // v1 crossed in its wrapApp helper.
+  const impl = {
+    use(pip: AnyPip, ..._guard: readonly unknown[]): DotAppBuilder<ServiceRecord> {
+      const nextState: BuilderState = {
+        ...state,
+        pips: [...state.pips, pip],
+      };
+      return makeBuilder<ServiceRecord>(nextState);
+    },
+    configure(): DotAppConfigured<ServiceRecord> {
+      const appImpl = buildImpl(state);
+      appImpl.runConfigure();
+      return wrapConfigured<ServiceRecord>(appImpl);
+    },
+    async boot(): Promise<DotApp<ServiceRecord>> {
+      const appImpl = buildImpl(state);
+      await appImpl.boot();
+      return wrapApp<ServiceRecord>(appImpl);
+    },
+    async start(): Promise<DotApp<ServiceRecord>> {
+      const appImpl = buildImpl(state);
+      await appImpl.start();
+      return wrapApp<ServiceRecord>(appImpl);
+    },
+  };
+  return impl as DotAppBuilder<TAvail>;
+}
+
+function wrapApp<TServices extends ServiceRecord>(impl: DotAppImpl): DotApp<TServices> {
+  return {
+    get name() {
+      return impl.name;
+    },
+    get state() {
+      return impl.state;
+    },
+    get services() {
+      return impl.services as TServices;
+    },
+    get manifest() {
+      return impl.manifest;
+    },
+    get diagnostics() {
+      return impl.diagnostics;
+    },
+    start: () => impl.start(),
+    stop: () => impl.stop(),
+    dispose: () => impl.dispose(),
+    subscribe: observer => impl.subscribe(observer),
+    timeline: () => renderTimeline(impl.diagnostics),
+  };
+}
+
+function wrapConfigured<TServices extends ServiceRecord>(impl: DotAppImpl): DotAppConfigured<TServices> {
+  return {
+    get name() {
+      return impl.name;
+    },
+    get state() {
+      return impl.state;
+    },
+    get manifest() {
+      return impl.manifest;
+    },
+    get diagnostics() {
+      return impl.diagnostics;
+    },
+    async boot() {
+      await impl.boot();
+      return wrapApp<TServices>(impl);
+    },
+    async start() {
+      await impl.start();
+      return wrapApp<TServices>(impl);
+    },
+    subscribe: observer => impl.subscribe(observer),
+    timeline: () => renderTimeline(impl.diagnostics),
+  };
+}

package/src/diagnostics.ts

@@ -0,0 +1,91 @@
+/**
+ * Diagnostics types for the DOT kernel.
+ *
+ * Where the manifest describes the static shape of an app, a
+ * `DotDiagnosticsSnapshot` is a point-in-time observability record: the
+ * lifecycle state of the app and every pip, plus structured issues with
+ * remediation guidance.
+ *
+ * CONTRACT: `DotDiagnosticsSnapshot` always exposes the same five arrays
+ * (`pips`, `routes`, `services`, `lifecycle`, `issues`). Consumers must
+ * never see an omitted array — empty is empty, but never missing.
+ * This is the "5 arrays" contract referenced by the kernel spec.
+ */
+
+import type { DotLifecycleHook, DotLifecycleState } from './lifecycle.js';
+
+/** Severity of a single diagnostic issue. */
+export type DiagnosticSeverity = 'info' | 'warning' | 'error';
+
+/** Status of a pip/route/service/lifecycle entry. */
+export type DiagnosticStatus = 'ok' | 'degraded' | 'failed' | 'skipped' | 'missing';
+
+/**
+ * Single point-in-time diagnostic snapshot of a DotApp.
+ *
+ * Five top-level arrays — pips, routes, services, lifecycle, issues —
+ * are guaranteed to be present even when empty.
+ */
+export type DotDiagnosticsSnapshot = {
+  /** ISO-8601 timestamp at which the snapshot was generated. */
+  generatedAt: string;
+  app: {
+    name: string;
+    state: DotLifecycleState;
+  };
+  pips: PipDiagnostic[];
+  routes: RouteDiagnostic[];
+  services: ServiceDiagnostic[];
+  lifecycle: LifecycleDiagnostic[];
+  issues: DiagnosticIssue[];
+};
+
+export type PipDiagnostic = {
+  pip: string;
+  status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'skipped'>;
+  issues: DiagnosticIssue[];
+};
+
+export type RouteDiagnostic = {
+  id: string;
+  pip: string;
+  status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed'>;
+  issues: DiagnosticIssue[];
+};
+
+export type ServiceDiagnostic = {
+  service: string;
+  pip: string;
+  status: Extract<DiagnosticStatus, 'ok' | 'degraded' | 'failed' | 'missing'>;
+  issues: DiagnosticIssue[];
+};
+
+export type LifecycleDiagnostic = {
+  pip: string;
+  hook: DotLifecycleHook;
+  state: DotLifecycleState;
+  /** 0-based topological order of this pip within the hook pass. */
+  order: number;
+  /** Wall-clock duration of the hook call, in milliseconds. */
+  durationMs?: number;
+  issues: DiagnosticIssue[];
+};
+
+/**
+ * Single structured issue surfaced by the kernel or by a pip.
+ *
+ * `code`, `message`, `remediation` and `docsUrl` are required so that issues
+ * are always actionable — never just "something went wrong".
+ */
+export type DiagnosticIssue = {
+  /** Stable machine-readable code, e.g. `DOT_LIFECYCLE_E003`. */
+  code: string;
+  severity: DiagnosticSeverity;
+  pip?: string;
+  message: string;
+  /** Human-readable remediation: what the developer should do. */
+  remediation: string;
+  /** Link to the relevant docs page for this issue. */
+  docsUrl: string;
+  metadata?: Record<string, unknown>;
+};

package/src/index.ts

@@ -0,0 +1,89 @@
+/**
+ * @arki/dot — TypeScript-first application composition framework
+ *
+ * Public surface:
+ *   - `defineApp(name)` — the entry point for composing applications.
+ *   - `pip(config)` — author lifecycle-aware pips with typed needs/provides.
+ *   - `service<T>()` / `token<T>()(key)` — service witnesses for DI wiring.
+ *   - `rename(pip, map)` — mount-time multi-instance primitive.
+ *   - Lifecycle / manifest / diagnostics types.
+ *   - `testApp` / `bootTestApp` — test harnesses for pip authors.
+ */
+
+// #region Kernel — public surface
+export { defineApp } from './define-app.js';
+export type { DotApp, DotAppBuilder, DotAppConfigured, UseGuard } from './define-app.js';
+
+export { isLazy, lazy, lazyOf, pip, provide, rename, service, token, DotPipError } from './pip-contract.js';
+export type {
+  AnyPip,
+  CtxOf,
+  DotConfigureContext,
+  EmptyShape,
+  KernelCtx,
+  Lazy,
+  LazyService,
+  NeedsShape,
+  Pip,
+  PipNeeds,
+  PipProvides,
+  RenamedProvides,
+  Service,
+  ServiceRecord,
+  Token,
+  WireNeeds,
+} from './pip-contract.js';
+
+export {
+  DotLifecycleError,
+  DotLifecycleErrorCode,
+  DOT_LIFECYCLE_HOOKS,
+} from './lifecycle.js';
+export type {
+  DotLifecycleHook,
+  DotLifecycleState,
+  DotLifecyclePipFailure,
+  DotLifecycleErrorCodeValue,
+} from './lifecycle.js';
+
+export type {
+  DotAppManifest,
+  PipManifest,
+  RouteManifest,
+  ServiceManifest,
+  LifecycleManifest,
+  DependencyEdge,
+  DependencyEdgeKind,
+  ServiceKind,
+  RouteTransport,
+} from './manifest.js';
+
+export type {
+  DotDiagnosticsSnapshot,
+  PipDiagnostic,
+  RouteDiagnostic,
+  ServiceDiagnostic,
+  LifecycleDiagnostic,
+  DiagnosticIssue,
+  DiagnosticSeverity,
+  DiagnosticStatus,
+} from './diagnostics.js';
+
+export type {
+  DotLifecycleEvent,
+  DotLifecycleEventStatus,
+  DotLifecycleObserver,
+  DotPhaseLifecycleEvent,
+  DotPipHookLifecycleEvent,
+} from './lifecycle-observer.js';
+
+export { renderTimeline } from './timeline.js';
+export type { RenderTimelineOptions } from './timeline.js';
+
+export { testApp, bootTestApp } from './test-harness.js';
+export type { TestAppOptions } from './test-harness.js';
+
+// Task 9b: CLI envelope type is exported so adapter packages can produce the
+// same shape from related tooling (release-tooling, pip scaffolds, etc.).
+export type { DotCliEnvelope, DotCliEnvelopeStatus } from './cli/render-explain.js';
+// #endregion