@arki/dot 0.1.0

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

@@ -0,0 +1,66 @@
+# Agent Guidance — {{name}}
+
+## What this app is
+
+A DOT app composed via `defineApp(...).use(pip).boot()`. The runtime
+graph is statically inspectable via `app.manifest` and runtime-inspectable
+via `app.diagnostics`.
+
+## Verification commands
+
+After any change, run these in order:
+
+1. `{{pkgManager}} run typecheck` — TypeScript compilation must pass.
+2. `{{pkgManager}} run test` — vitest must pass (booting the app and
+   asserting manifest shape).
+3. `bunx dot explain --json` — inspect the static graph.
+4. `bunx dot doctor --json` — verify runtime health (5-array diagnostics
+   plus issues).
+
+Stop and surface any failure. Don't claim "done" until every verification
+command exits zero.
+
+## Local conventions
+
+- App entrypoint lives at `src/app.ts` and exports the booted `app`.
+- 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
+  `defineApp('{{name}}')` and `.boot()` in `src/app.ts`.
+
+## Public / private boundaries
+
+- `src/app.ts` exports the booted `app` — consumers call `app.services.X`.
+- `src/env.ts` exports the env schema — keep narrow; only env keys this
+  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` / `defineDotPip` API from `@arki/dot` and the
+  `defineDotPip` symbol from `@arki/dot/pip`.
+
+## DOT artifact locations
+
+- Static graph: `app.manifest` (or `bunx dot explain --json`).
+- Runtime health: `app.diagnostics` (or `bunx dot doctor --json`).
+- Lifecycle state: `app.state` (`defined` -> `configured` -> `booted` ->
+  `started` -> `stopped` -> `disposed`).
+- Errors carry stable `code`, `severity`, `remediation`, `docsUrl`.
+
+## Adding a pip
+
+1. Install the adapter package: `{{pkgManager}} add @arki/<pkg>`.
+2. Import its DOT adapter: `import { <pip> } 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`.
+
+## Diagnostics triage
+
+When `dot doctor` reports issues:
+
+- Each `DiagnosticIssue` has a stable `code`, `severity`, `remediation`,
+  and `docsUrl`. Follow the `docsUrl`, then apply the `remediation`.
+- Re-run `bunx dot doctor --json` after each change; status flips to
+  `success` once every `error`-severity issue is resolved.

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

@@ -0,0 +1,24 @@
+# {{name}}
+
+A DOT-composed application.
+
+## Quickstart
+
+```bash
+{{pkgManager}} install
+{{pkgManager}} run test
+{{pkgManager}} run boot
+```
+
+## Inspect
+
+```bash
+bunx dot explain --json
+bunx dot doctor --json
+```
+
+`dot explain` prints the static graph (pips, services, routes, dependencies,
+lifecycle hooks). `dot doctor` boots the app and prints the runtime
+diagnostics envelope (the same five arrays, plus issues).
+
+See [AGENTS.md](./AGENTS.md) for agent-readable conventions.

package/templates/app-minimal/package.json.tmpl

@@ -0,0 +1,21 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "boot": "node --experimental-strip-types src/app.ts"
+  },
+  "dependencies": {
+    "@arki/dot": "^{{dotVersion}}",
+    "@arki/env": "^{{envVersion}}",
+    "zod": "^{{zodVersion}}"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  }
+}

package/templates/app-minimal/src/app.ts.tmpl

@@ -0,0 +1,20 @@
+import { defineApp } from '@arki/dot';
+import { env } from '@arki/env/dot';
+
+import { envSchema } from './env.js';
+
+/**
+ * App builder. Exported as both `app` (for tests that want to boot
+ * synchronously inside a `test(...)` block) and as the module default
+ * (so `dot explain` / `dot doctor` can discover it via the CLI).
+ */
+export const app = defineApp('{{name}}').use(env({ schema: envSchema }));
+
+export default app;
+
+if ((import.meta as { main?: boolean }).main) {
+  const booted = await app.boot();
+  // Intentional console use — this branch only runs as a script.
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(booted.manifest, null, 2));
+}

package/templates/app-minimal/src/env.ts.tmpl

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+
+export const envSchema = {
+  NODE_ENV: z
+    .enum(['development', 'test', 'production'])
+    .default('development'),
+  // Add your env keys here.
+};
+
+export type Env = {
+  readonly [K in keyof typeof envSchema]: z.infer<(typeof envSchema)[K]>;
+};

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

@@ -0,0 +1,25 @@
+import { beforeAll, expect, test } from 'vitest';
+
+import { app as appBuilder } from '../src/app.js';
+
+type BootedApp = Awaited<ReturnType<typeof appBuilder.boot>>;
+let booted: BootedApp;
+
+beforeAll(async () => {
+  booted = await appBuilder.boot();
+});
+
+test('app boots and exposes env service', () => {
+  expect(booted.state).toBe('booted');
+  expect(booted.services.env).toBeDefined();
+  expect(booted.manifest.services.map(s => s.name)).toContain('env');
+});
+
+test('diagnostics has all 5 arrays', () => {
+  const { diagnostics } = booted;
+  expect(diagnostics.pips).toBeDefined();
+  expect(diagnostics.routes).toBeDefined();
+  expect(diagnostics.services).toBeDefined();
+  expect(diagnostics.lifecycle).toBeDefined();
+  expect(diagnostics.issues).toBeDefined();
+});

package/templates/app-minimal/tsconfig.json.tmpl

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "outDir": "dist",
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*", "tests/**/*"],
+  "exclude": ["node_modules", "dist"]
+}