@arki/dot 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ARKI Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @arki/dot
+
+> 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.
+
+## 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**;
+- 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.
+
+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.
+
+```ts
+import { defineApp } from '@arki/dot';
+import { env } from '@arki/env/dot';      // env pip
+import { db } from '@arki/db/dot';        // db pip
+import { kv } from '@arki/kv/dot';        // kv pip
+
+const app = await defineApp('orders')
+  .use(env({ schema: { /* ... */ } }))     // 1st pip — provides services.env
+  .use(db({ relations }))                  // 2nd pip — provides services.db
+  .use(kv({ url: process.env.KV_URL! }))   // 3rd pip — provides services.kv
+  .boot();                                  // pips boot in declaration order
+
+await app.services.db.query(/* ... */);
+await app.dispose();                       // pips dispose in REVERSE order
+```
+
+Each `/dot` subpath exports a **pip** for that package. The subpath names
+the framework the adapter targets (DOT), not the unit (which is a pip).
+
+> **Why not "plugin"?** Plugins suggest *optional add-ons* to a core. DOT's
+> reality is the opposite: there is no hidden core — the pips *are* the app.
+> "Pip" names that truth, and ties the framework to the DOT name etymologically
+> (a dot, a pip, a small mark that gains meaning by combining with others).
+
+## Installation
+
+```bash
+npm install @arki/dot
+# or
+bun add @arki/dot
+```
+
+## Quick start
+
+```ts
+import { defineApp, defineDotPip } from '@arki/dot';
+
+const billingPip = defineDotPip({
+  name: 'billing',
+  version: '1.0.0',
+  configure(ctx) {
+    // Validate config, register schemas, no I/O.
+  },
+  async boot(ctx) {
+    // Open connections, register providers.
+    return { stripe: makeStripeClient() };
+  },
+  async start(ctx) {
+    // Begin processing — workers, subscriptions, schedulers.
+  },
+  async stop() {
+    // Stop processing — drain workers, unsubscribe.
+  },
+  async dispose() {
+    // Close connections, free resources.
+  },
+});
+
+const app = defineApp('acme')
+  .use(billingPip);
+
+await app.configure();
+await app.boot();
+await app.start();
+
+// app.manifest, app.diagnostics — agent-friendly envelopes.
+
+await app.stop();
+await app.dispose();
+```
+
+## Pip authoring
+
+`defineDotPip(config)` accepts five lifecycle hooks. Each receives a
+phase-specific context with services contributed by earlier pips:
+
+| Hook        | Purpose                                                          |
+| ----------- | ---------------------------------------------------------------- |
+| `configure` | Validate static config; declare schemas, routes, services. No I/O. |
+| `boot`      | Open connections; register providers; return a typed kit.       |
+| `start`     | Begin processing (workers, subscribers, schedulers).             |
+| `stop`      | Stop processing in reverse dependency order.                     |
+| `dispose`   | Free resources after `stop`.                                     |
+
+Pips can declare dependencies on others by name. The kernel computes a
+topological order and runs hooks deterministically — same input, same order,
+every time.
+
+## Lifecycle
+
+`defineApp(name)` returns a builder. Calling `.use(pip)` accumulates
+pips. The lifecycle then flows:
+
+```
+defined ──configure()──▶ configured ──boot()──▶ booted ──start()──▶ started
+                                                                       │
+                       disposed ◀──dispose()── stopped ◀──stop()───────┘
+```
+
+`boot()` runs `configure()` implicitly if you skipped it. `start()` runs
+`boot()` implicitly. `stop()` and `dispose()` always run in reverse dependency
+order, even when an earlier hook failed — failure isolation is part of the
+contract.
+
+## CLI
+
+`@arki/dot` ships a small CLI for scaffolding and inspecting apps:
+
+```bash
+# Scaffold a minimal DOT app (package.json, tsconfig, app entrypoint,
+# env schema, AGENTS.md, README, gitignore, vitest boot test).
+dot new my-app
+
+# Preview the file operations without writing anything.
+dot new my-app --dry-run --json | jq '.operations'
+
+# Print the app manifest as a structured envelope.
+dot explain --app ./my-app.ts
+
+# Run boot-time diagnostics; non-zero exit if any check fails.
+dot doctor --app ./my-app.ts
+
+# 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.
+
+### `dot new <app-name>`
+
+Scaffolds a minimal DOT app under `<app-name>/` (override with `--target`).
+The scaffold ships a `defineApp(...)` entrypoint wired to `@arki/env/dot`,
+a vitest that boots the app and asserts the manifest shape, and an
+`AGENTS.md` documenting verification commands and the public/private
+boundary for agents working in the generated tree. Pass `--dry-run --json`
+to inspect the exact file operations (path, action, contentHash,
+contentBytes, reason) before committing them to disk; `--force`
+overwrites pre-existing files in the target directory.
+
+Templates live at [`templates/app-minimal/`](./templates/app-minimal) and
+ship with the published tarball.
+
+## Architecture
+
+`@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.
+
+This keeps the kernel free of optional dependencies and lets each adapter
+ship at its own cadence.
+
+## Documentation
+
+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.
+- [Diagnostics](./docs/diagnostics.md) — `app.manifest`, `app.diagnostics`,
+  `dot explain`, `dot doctor`.
+- [Adapter authoring](./docs/adapter-authoring.md) — expose your package as
+  a DOT pip.
+- [Agent guide](./docs/agent-guide.md) — how coding agents inspect, modify,
+  and verify DOT apps.
+- [Release policy](./docs/release-policy.md) — SemVer and deprecation.
+
+Agent-discoverable index: [`llms.txt`](./llms.txt).
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/cli/discover.d.ts

@@ -0,0 +1,65 @@
+/**
+ * App-file discovery + dynamic import for the DOT CLI.
+ *
+ * The CLI inspects a user's DOT app at the command line. Apps live in source
+ * files like `dot.config.ts` or `src/app.ts`; this module resolves the right
+ * file, imports it, unwraps the default export, and returns either a
+ * `DotApp` or `DotAppBuilder`.
+ *
+ * The CLI commands (`explain`, `doctor`) then decide whether to call
+ * `.configure()` / `.boot()` on the result.
+ */
+import type { DotApp, DotAppBuilder, DotAppConfigured } from '../define-app.js';
+export type DiscoveredApp = DotApp<Record<string, unknown>> | DotAppBuilder<Record<string, unknown>> | DotAppConfigured<Record<string, unknown>>;
+export type DiscoveryOptions = {
+    /** Explicit app file path. When set, takes precedence over the search list. */
+    appPath?: string;
+    /** Working directory for discovery. Defaults to `process.cwd()`. */
+    cwd?: string;
+};
+export type DiscoveryResult = {
+    /** Absolute path of the resolved app file. */
+    filePath: string;
+    /** Discovered app (builder, configured, or booted). */
+    app: DiscoveredApp;
+};
+/**
+ * Resolve which app file to load.
+ *
+ * If `appPath` is set, return its absolute path (without checking existence —
+ * the caller's `import` will throw with a clearer error if missing).
+ * Otherwise, walk the default file list and return the first that exists.
+ *
+ * Returns `null` when nothing was found.
+ */
+export declare function resolveAppFile(options?: DiscoveryOptions): Promise<string | null>;
+/**
+ * Heuristic guard: detect whether the default export looks like a `DotApp` or
+ * `DotAppBuilder` / `DotAppConfigured`. We avoid `instanceof` because the
+ * surface types are structural; instead we duck-type the key methods.
+ */
+declare function isDotAppBuilder(value: unknown): value is DotAppBuilder<Record<string, unknown>>;
+declare function isDotAppConfigured(value: unknown): value is DotAppConfigured<Record<string, unknown>>;
+declare function isDotApp(value: unknown): value is DotApp<Record<string, unknown>>;
+/**
+ * Dynamic-import the app file and unwrap its default export into a
+ * `DotApp` / `DotAppBuilder`. Functions returning either are awaited.
+ *
+ * Throws `DotCliError` on any failure path.
+ */
+export declare function loadAppFromFile(filePath: string): Promise<DiscoveredApp>;
+/**
+ * Combined: resolve the file and load the app. Throws `DotCliError` when no
+ * file was found or the import/export shape is invalid.
+ */
+export declare function discoverApp(options?: DiscoveryOptions): Promise<DiscoveryResult>;
+/**
+ * Type guards re-exported for test and renderer consumers.
+ */
+export declare const guards: {
+    isDotApp: typeof isDotApp;
+    isDotAppBuilder: typeof isDotAppBuilder;
+    isDotAppConfigured: typeof isDotAppConfigured;
+};
+export {};
+//# sourceMappingURL=discover.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discover.d.ts","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAkBhF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEjJ,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,GAAG,EAAE,aAAa,CAAC;CACpB,CAAC;AAWF;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAqB3F;AAED;;;;GAIG;AACH,iBAAS,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAIxF;AAED,iBAAS,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAU9F;AAED,iBAAS,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAY1E;AASD;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAgD9E;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC,CAgB1F;AAED;;GAEG;AACH,eAAO,MAAM,MAAM;;;;CAIlB,CAAC"}

package/dist/cli/discover.js

@@ -0,0 +1,184 @@
+/**
+ * App-file discovery + dynamic import for the DOT CLI.
+ *
+ * The CLI inspects a user's DOT app at the command line. Apps live in source
+ * files like `dot.config.ts` or `src/app.ts`; this module resolves the right
+ * file, imports it, unwraps the default export, and returns either a
+ * `DotApp` or `DotAppBuilder`.
+ *
+ * The CLI commands (`explain`, `doctor`) then decide whether to call
+ * `.configure()` / `.boot()` on the result.
+ */
+import { stat } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createDebugLogger } from '@arki/log/debug';
+import { DotCliError, DotCliErrorCode } from './error-codes.js';
+const debugDiscover = createDebugLogger('arki:dot:cli:discover');
+/**
+ * Default file names probed at cwd, in priority order.
+ * Each entry is tried with each of the supported file extensions below.
+ */
+const DEFAULT_APP_PATHS = ['dot.config', 'src/app', 'app'];
+/**
+ * Supported file extensions. `.ts` is preferred because the CLI runs under
+ * Bun, which executes TypeScript natively. `.js` and `.mjs` are accepted for
+ * apps that prefer JS sources or pre-compiled output.
+ */
+const SUPPORTED_EXTENSIONS = ['.ts', '.mts', '.mjs', '.js'];
+async function fileExists(filePath) {
+    try {
+        const result = await stat(filePath);
+        return result.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve which app file to load.
+ *
+ * If `appPath` is set, return its absolute path (without checking existence —
+ * the caller's `import` will throw with a clearer error if missing).
+ * Otherwise, walk the default file list and return the first that exists.
+ *
+ * Returns `null` when nothing was found.
+ */
+export async function resolveAppFile(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    if (options.appPath) {
+        const absolute = isAbsolute(options.appPath) ? options.appPath : resolve(cwd, options.appPath);
+        debugDiscover('explicit app path: %s', absolute);
+        return absolute;
+    }
+    for (const base of DEFAULT_APP_PATHS) {
+        for (const ext of SUPPORTED_EXTENSIONS) {
+            const candidate = resolve(cwd, `${base}${ext}`);
+            if (await fileExists(candidate)) {
+                debugDiscover('discovered app file: %s', candidate);
+                return candidate;
+            }
+        }
+    }
+    debugDiscover('no app file found at %s', cwd);
+    return null;
+}
+/**
+ * Heuristic guard: detect whether the default export looks like a `DotApp` or
+ * `DotAppBuilder` / `DotAppConfigured`. We avoid `instanceof` because the
+ * surface types are structural; instead we duck-type the key methods.
+ */
+function isDotAppBuilder(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return typeof v.use === 'function' && typeof v.configure === 'function' && typeof v.boot === 'function';
+}
+function isDotAppConfigured(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === 'string' &&
+        typeof v.boot === 'function' &&
+        'manifest' in v &&
+        'diagnostics' in v &&
+        typeof v.use !== 'function');
+}
+function isDotApp(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    return (typeof v.name === 'string' &&
+        typeof v.dispose === 'function' &&
+        typeof v.start === 'function' &&
+        typeof v.stop === 'function' &&
+        'manifest' in v &&
+        'diagnostics' in v &&
+        'services' in v);
+}
+function unwrapDefaultExport(mod) {
+    if (typeof mod !== 'object' || mod === null)
+        return mod;
+    const record = mod;
+    if ('default' in record)
+        return record.default;
+    return mod;
+}
+/**
+ * Dynamic-import the app file and unwrap its default export into a
+ * `DotApp` / `DotAppBuilder`. Functions returning either are awaited.
+ *
+ * Throws `DotCliError` on any failure path.
+ */
+export async function loadAppFromFile(filePath) {
+    let mod;
+    try {
+        // Use `pathToFileURL` so dynamic import accepts absolute paths on Windows.
+        mod = await import(pathToFileURL(filePath).href);
+    }
+    catch (err) {
+        throw new DotCliError({
+            code: DotCliErrorCode.AppImportFailed,
+            message: `Failed to import app file at ${filePath}: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: 'Verify the file path is correct and that the module loads without errors. Run the file directly with `bun <path>` to reproduce.',
+            metadata: { filePath },
+            cause: err,
+        });
+    }
+    let candidate = unwrapDefaultExport(mod);
+    // If the default export is a function, call it (it may return the
+    // builder/app, or a Promise of one). This supports lazy/async setup.
+    if (typeof candidate === 'function') {
+        try {
+            const fn = candidate;
+            const result = fn();
+            candidate = result instanceof Promise ? await result : result;
+        }
+        catch (err) {
+            throw new DotCliError({
+                code: DotCliErrorCode.AppImportFailed,
+                message: `Default export function in ${filePath} threw: ${err instanceof Error ? err.message : String(err)}`,
+                remediation: 'Make the default-exported factory return a DotApp or DotAppBuilder. Check for setup errors.',
+                metadata: { filePath },
+                cause: err,
+            });
+        }
+    }
+    if (isDotApp(candidate) || isDotAppBuilder(candidate) || isDotAppConfigured(candidate)) {
+        debugDiscover('loaded app from %s', filePath);
+        return candidate;
+    }
+    throw new DotCliError({
+        code: DotCliErrorCode.AppInvalidExport,
+        message: `Default export from ${filePath} is not a DotApp or DotAppBuilder.`,
+        remediation: 'Export a DotApp or DotAppBuilder as the default. Example: `export default defineApp("my-app").use(pip);`',
+        metadata: { filePath },
+    });
+}
+/**
+ * Combined: resolve the file and load the app. Throws `DotCliError` when no
+ * file was found or the import/export shape is invalid.
+ */
+export async function discoverApp(options = {}) {
+    const filePath = await resolveAppFile(options);
+    if (!filePath) {
+        const cwd = options.cwd ?? process.cwd();
+        throw new DotCliError({
+            code: DotCliErrorCode.AppNotFound,
+            message: `No DOT app file found in ${cwd}.`,
+            remediation: 'Create `dot.config.ts` exporting your app (e.g. `export default defineApp("my-app").use(pip)`), or pass `--app <path>` to point at an existing file.',
+            metadata: { cwd, searched: DEFAULT_APP_PATHS },
+        });
+    }
+    const app = await loadAppFromFile(filePath);
+    return { filePath, app };
+}
+/**
+ * Type guards re-exported for test and renderer consumers.
+ */
+export const guards = {
+    isDotApp,
+    isDotAppBuilder,
+    isDotAppConfigured,
+};
+//# sourceMappingURL=discover.js.map

package/dist/cli/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/cli/discover.ts"],"names":[],"mappings":"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"}

package/dist/cli/error-codes.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Stable error codes used by the DOT CLI.
+ *
+ * Every code starts with `DOT_CLI_E` so it can be visually distinguished from
+ * lifecycle errors (`DOT_LIFECYCLE_E*`). Codes are part of the public contract
+ * — agents grep on them to branch behaviour. Do not renumber.
+ */
+export declare const DotCliErrorCode: {
+    /** No app file could be discovered at the cwd and `--app` was not provided. */
+    readonly AppNotFound: "DOT_CLI_E001";
+    /** App file was located but its default export is not a DotApp/DotAppBuilder. */
+    readonly AppInvalidExport: "DOT_CLI_E002";
+    /** Importing the app file threw an exception. */
+    readonly AppImportFailed: "DOT_CLI_E003";
+    /** Unknown CLI command. */
+    readonly UnknownCommand: "DOT_CLI_E004";
+    /** CLI args were malformed. */
+    readonly InvalidArgs: "DOT_CLI_E005";
+    /** Configure or boot threw while preparing the app for inspection. */
+    readonly AppLifecycleFailed: "DOT_CLI_E006";
+    /** `dot doctor --observability` ran but no OTel SDK is registered. */
+    readonly ObservabilityNoSdk: "DOT_CLI_E007";
+};
+export type DotCliErrorCodeValue = (typeof DotCliErrorCode)[keyof typeof DotCliErrorCode];
+/**
+ * Anchors on the CLI docs page. Kept here so both the renderers and tests can
+ * reference the same URL without drift.
+ */
+export declare const DotCliDocsAnchor: Record<DotCliErrorCodeValue, string>;
+export declare function dotCliDocsUrl(code: DotCliErrorCodeValue): string;
+/**
+ * Structured CLI error. Carries enough metadata to be rendered as a JSON
+ * envelope or a human-readable diagnostic line.
+ */
+export declare class DotCliError extends Error {
+    readonly code: DotCliErrorCodeValue;
+    readonly remediation: string;
+    readonly docsUrl: string;
+    readonly metadata?: Record<string, unknown>;
+    readonly cause?: unknown;
+    constructor(args: {
+        code: DotCliErrorCodeValue;
+        message: string;
+        remediation: string;
+        metadata?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=error-codes.d.ts.map

package/dist/cli/error-codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.d.ts","sourceRoot":"","sources":["../../src/cli/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,eAAO,MAAM,eAAe;IAC1B,+EAA+E;;IAE/E,iFAAiF;;IAEjF,iDAAiD;;IAEjD,2BAA2B;;IAE3B,+BAA+B;;IAE/B,sEAAsE;;IAEtE,sEAAsE;;CAE9D,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,CAAC;AAI1F;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,oBAAoB,EAAE,MAAM,CAQjE,CAAC;AAEF,wBAAgB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAEhE;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE;QAChB,IAAI,EAAE,oBAAoB,CAAC;QAC3B,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACnC,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;CASF"}

package/dist/cli/error-codes.js

@@ -0,0 +1,61 @@
+/**
+ * Stable error codes used by the DOT CLI.
+ *
+ * Every code starts with `DOT_CLI_E` so it can be visually distinguished from
+ * lifecycle errors (`DOT_LIFECYCLE_E*`). Codes are part of the public contract
+ * — agents grep on them to branch behaviour. Do not renumber.
+ */
+export const DotCliErrorCode = {
+    /** No app file could be discovered at the cwd and `--app` was not provided. */
+    AppNotFound: 'DOT_CLI_E001',
+    /** App file was located but its default export is not a DotApp/DotAppBuilder. */
+    AppInvalidExport: 'DOT_CLI_E002',
+    /** Importing the app file threw an exception. */
+    AppImportFailed: 'DOT_CLI_E003',
+    /** Unknown CLI command. */
+    UnknownCommand: 'DOT_CLI_E004',
+    /** CLI args were malformed. */
+    InvalidArgs: 'DOT_CLI_E005',
+    /** Configure or boot threw while preparing the app for inspection. */
+    AppLifecycleFailed: 'DOT_CLI_E006',
+    /** `dot doctor --observability` ran but no OTel SDK is registered. */
+    ObservabilityNoSdk: 'DOT_CLI_E007',
+};
+const DOCS_BASE = 'https://docs.arki.dev/dot/cli';
+/**
+ * Anchors on the CLI docs page. Kept here so both the renderers and tests can
+ * reference the same URL without drift.
+ */
+export const DotCliDocsAnchor = {
+    [DotCliErrorCode.AppNotFound]: 'app-not-found',
+    [DotCliErrorCode.AppInvalidExport]: 'app-invalid-export',
+    [DotCliErrorCode.AppImportFailed]: 'app-import-failed',
+    [DotCliErrorCode.UnknownCommand]: 'unknown-command',
+    [DotCliErrorCode.InvalidArgs]: 'invalid-args',
+    [DotCliErrorCode.AppLifecycleFailed]: 'app-lifecycle-failed',
+    [DotCliErrorCode.ObservabilityNoSdk]: 'observability-no-sdk',
+};
+export function dotCliDocsUrl(code) {
+    return `${DOCS_BASE}#${DotCliDocsAnchor[code]}`;
+}
+/**
+ * Structured CLI error. Carries enough metadata to be rendered as a JSON
+ * envelope or a human-readable diagnostic line.
+ */
+export class DotCliError extends Error {
+    code;
+    remediation;
+    docsUrl;
+    metadata;
+    cause;
+    constructor(args) {
+        super(args.message);
+        this.name = 'DotCliError';
+        this.code = args.code;
+        this.remediation = args.remediation;
+        this.docsUrl = dotCliDocsUrl(args.code);
+        this.metadata = args.metadata;
+        this.cause = args.cause;
+    }
+}
+//# sourceMappingURL=error-codes.js.map

package/dist/cli/error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes.js","sourceRoot":"","sources":["../../src/cli/error-codes.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,+EAA+E;IAC/E,WAAW,EAAE,cAAc;IAC3B,iFAAiF;IACjF,gBAAgB,EAAE,cAAc;IAChC,iDAAiD;IACjD,eAAe,EAAE,cAAc;IAC/B,2BAA2B;IAC3B,cAAc,EAAE,cAAc;IAC9B,+BAA+B;IAC/B,WAAW,EAAE,cAAc;IAC3B,sEAAsE;IACtE,kBAAkB,EAAE,cAAc;IAClC,sEAAsE;IACtE,kBAAkB,EAAE,cAAc;CAC1B,CAAC;AAIX,MAAM,SAAS,GAAG,+BAA+B,CAAC;AAElD;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAyC;IACpE,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,eAAe;IAC9C,CAAC,eAAe,CAAC,gBAAgB,CAAC,EAAE,oBAAoB;IACxD,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,mBAAmB;IACtD,CAAC,eAAe,CAAC,cAAc,CAAC,EAAE,iBAAiB;IACnD,CAAC,eAAe,CAAC,WAAW,CAAC,EAAE,cAAc;IAC7C,CAAC,eAAe,CAAC,kBAAkB,CAAC,EAAE,sBAAsB;IAC5D,CAAC,eAAe,CAAC,kBAAkB,CAAC,EAAE,sBAAsB;CAC7D,CAAC;AAEF,MAAM,UAAU,aAAa,CAAC,IAA0B;IACtD,OAAO,GAAG,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,EAAE,CAAC;AAClD,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAuB;IAC3B,WAAW,CAAS;IACpB,OAAO,CAAS;IAChB,QAAQ,CAA2B;IAC1B,KAAK,CAAW;IAElC,YAAY,IAMX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;QACtB,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAC;QACpC,IAAI,CAAC,OAAO,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;CACF"}