Diagnostics

import type { DotAppManifest as ExportedManifest } from '@arki/dot';
 
type DotAppManifest = {
  manifestVersion: 2;
  app: { name: string; version?: string };
  plugins: PluginManifest[];
  actions: ActionManifest[];
  services: ServiceManifest[];
  lifecycle: LifecycleManifest[];
  dependencies: DependencyEdge[];
  projections: ProjectionManifest[];
};
 
// Shapes are written out to read. This line stops compiling if one drifts from the exported type.
type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
export const manifestMatches: Same<DotAppManifest, ExportedManifest> = true;
 
// The sub-shapes are in the next block.
type PluginManifest = ExportedManifest['plugins'][number];
type ActionManifest = ExportedManifest['actions'][number];
type ServiceManifest = ExportedManifest['services'][number];
type LifecycleManifest = ExportedManifest['lifecycle'][number];
type DependencyEdge = ExportedManifest['dependencies'][number];
type ProjectionManifest = ExportedManifest['projections'][number];

import type { DotAppManifest, DotLifecycleHook, JsonObject } from '@arki/dot';
 
type PluginManifest = {
  name: string;
  role?: 'feature' | 'driving'; // the hexagon role the app builder gave the plugin
  dependencies: readonly string[];
  provides: readonly string[];
};
 
type ActionManifest = {
  id: string;
  plugin: string;
  binding: string;
  direction: 'in' | 'out';
  address?: string;
  summary?: string;
  meta?: JsonObject;
  metaSchema?: string;
};
 
type ServiceManifest = {
  name: string;
  plugin: string;
  kind: 'env' | 'db' | 'kv' | 'queue' | 'auth' | 'email' | 'logger' | 'event-store' | 'message-bus' | 'custom';
};
 
type LifecycleManifest = {
  plugin: string;
  hooks: readonly DotLifecycleHook[];
};
 
type DependencyEdge = {
  from: string;
  to: string;
  kind: 'requires' | 'provides' | 'uses';
  key?: string; // the capability, on edges derived at configure() from static provides
};
 
type ProjectionManifest = {
  format: string;
  binding: string;
  module: string;
  plugin: string;
};
 
// Each shape must equal the entry type of the exported manifest.
type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
export const pluginMatches: Same<PluginManifest, DotAppManifest['plugins'][number]> = true;
export const actionMatches: Same<ActionManifest, DotAppManifest['actions'][number]> = true;
export const serviceMatches: Same<ServiceManifest, DotAppManifest['services'][number]> = true;
export const lifecycleMatches: Same<LifecycleManifest, DotAppManifest['lifecycle'][number]> = true;
export const edgeMatches: Same<DependencyEdge, DotAppManifest['dependencies'][number]> = true;
export const projectionMatches: Same<ProjectionManifest, DotAppManifest['projections'][number]> = true;

import type { DotLifecycleState, DotDiagnosticsSnapshot as ExportedSnapshot } from '@arki/dot';
 
type DotDiagnosticsSnapshot = {
  snapshotVersion: 2;
  generatedAt: string; // ISO-8601
  app: { name: string; state: DotLifecycleState };
  plugins: ExportedSnapshot['plugins'];
  actions: ExportedSnapshot['actions'];
  services: ExportedSnapshot['services'];
  lifecycle: ExportedSnapshot['lifecycle'];
  issues: ExportedSnapshot['issues'];
};
 
type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
export const snapshotMatches: Same<DotDiagnosticsSnapshot, ExportedSnapshot> = true;

import type { DiagnosticIssue as ExportedIssue } from '@arki/dot';
 
type DiagnosticIssue = {
  code: string; // stable machine-readable code, e.g. ARKI_DOT_E003
  severity: 'info' | 'warning' | 'error';
  plugin?: string; // owning plugin, when applicable
  message: string; // human-readable summary
  remediation: string; // what the developer (or agent) should do
  docsUrl: string; // link to the relevant doc
  metadata?: Record<string, unknown>;
};
 
type Same<A, B> = [A] extends [B] ? ([B] extends [A] ? true : never) : never;
export const issueMatches: Same<DiagnosticIssue, ExportedIssue> = true;

import { defineApp, plugin } from '@arki/dot';
import { isFailure } from '@arki/failure';
 
const database = plugin({ name: 'database', provides: { db: () => ({ ready: true }) } });
const billing = plugin({ name: 'billing', needs: { db: database.provides.db } });
 
const app = await defineApp('my-app').use(database).use(billing).boot();
if (isFailure(app)) throw new Error(app.code);
 
// Static graph
console.log(app.manifest.plugins.map(p => p.name).join());
console.log(JSON.stringify(app.manifest.dependencies));
 
// Runtime snapshot
const snapshot = app.diagnostics;
console.log(snapshot.app.state, snapshot.issues.length);
for (const issue of snapshot.issues) {
  console.error(`[${issue.severity}] ${issue.code}: ${issue.message}`);
  console.error(`  remediation: ${issue.remediation}`);
  console.error(`  docs: ${issue.docsUrl}`);
}
await app.dispose();

database,billing
[{"from":"billing","to":"database","kind":"requires","key":"db"}]
booted 0

# Human-readable
npx dot explain
 
# JSON (for agents and CI)
npx dot explain --json | jq '.data.manifest.plugins'

import type { Envelope } from '@arki/cli';
import type { DotAppManifest } from '@arki/dot';
 
// What `dot explain --json` prints, read the way an agent reads it.
export function pluginNames(envelope: Envelope<DotAppManifest>): readonly string[] {
  if (!envelope.ok) throw new Error(`${envelope.error.code}: ${envelope.error.remediation ?? envelope.error.message}`);
  return envelope.data?.plugins.map(p => p.name) ?? [];
}

# Human-readable
npx dot doctor
 
# JSON (for agents and CI)
npx dot doctor --json | jq '.data.issues'