@arki/dot 0.1.0

package/dist/cli/files.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Filesystem helpers for the `dot new` scaffold.
+ *
+ * Kept deliberately small and dependency-free so the scaffolding code path
+ * stays auditable. The scaffold first builds an in-memory list of
+ * {@link FileOperation} entries describing every file it WOULD write, then
+ * either prints them (`--dry-run`) or commits them to disk.
+ */
+/**
+ * Action the generator will take for a particular file.
+ *
+ * - `create` — file does not yet exist at the target path.
+ * - `overwrite` — file exists; the generator will replace it (only when
+ *   `--force` was passed).
+ * - `skip` — file exists and the generator refuses to overwrite without
+ *   `--force`. Surfaced in dry-run output and converted to a failure on
+ *   real runs.
+ */
+export type FileOperationAction = 'create' | 'overwrite' | 'skip';
+/**
+ * Description of a single file the scaffold plans to emit.
+ *
+ * `path` is always relative to the target directory so the envelope is
+ * portable across machines. `contentHash` is sha256 of the rendered bytes
+ * — agents can use it to confirm the file we wrote matches the file we
+ * planned.
+ */
+export type FileOperation = {
+    readonly path: string;
+    readonly action: FileOperationAction;
+    readonly contentHash: string;
+    readonly contentBytes: number;
+    readonly reason: string;
+    /**
+     * Rendered file contents. Internal to the generator — NOT emitted in the
+     * JSON envelope. Kept on the in-memory plan so a non-dry-run can write
+     * the same bytes that produced `contentHash`.
+     */
+    readonly content: string;
+};
+/**
+ * Walk a template directory and return the relative paths of every file.
+ *
+ * Subdirectories are descended into; symlinks and non-regular files are
+ * ignored. Paths are returned without a leading separator and are sorted
+ * lexicographically for deterministic output.
+ */
+export declare function collectTemplateFiles(root: string): Promise<string[]>;
+/** Compute the sha256 hex digest of a string payload (utf-8 encoded). */
+export declare function sha256(content: string): string;
+/** Byte length of a utf-8 string. Wrapper exists so the call site is obvious. */
+export declare function utf8ByteLength(content: string): number;
+/** Return `true` when a regular file exists at the given path. */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/** Return `true` when a directory exists and contains at least one entry. */
+export declare function directoryIsNonEmpty(dirPath: string): Promise<boolean>;
+/**
+ * Write a single file, creating parent directories as needed.
+ */
+export declare function writeFileEnsuringDir(filePath: string, content: string): Promise<void>;
+/**
+ * Read a template file from disk. Trivially thin wrapper around
+ * `fs.readFile`, but exists so the scaffold imports stay symmetric with
+ * its helpers.
+ */
+export declare function readTemplate(filePath: string): Promise<string>;
+//# sourceMappingURL=files.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"files.d.ts","sourceRoot":"","sources":["../../src/cli/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH;;;;;;;;;GASG;AACH,MAAM,MAAM,mBAAmB,GAAG,QAAQ,GAAG,WAAW,GAAG,MAAM,CAAC;AAElE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkB1E;AAED,yEAAyE;AACzE,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,kEAAkE;AAClE,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED,6EAA6E;AAC7E,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO3E;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3F;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE"}

package/dist/cli/files.js

@@ -0,0 +1,80 @@
+/**
+ * Filesystem helpers for the `dot new` scaffold.
+ *
+ * Kept deliberately small and dependency-free so the scaffolding code path
+ * stays auditable. The scaffold first builds an in-memory list of
+ * {@link FileOperation} entries describing every file it WOULD write, then
+ * either prints them (`--dry-run`) or commits them to disk.
+ */
+import { createHash } from 'node:crypto';
+import { mkdir, readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Walk a template directory and return the relative paths of every file.
+ *
+ * Subdirectories are descended into; symlinks and non-regular files are
+ * ignored. Paths are returned without a leading separator and are sorted
+ * lexicographically for deterministic output.
+ */
+export async function collectTemplateFiles(root) {
+    const out = [];
+    async function walk(dir) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                out.push(path.relative(root, full));
+            }
+        }
+    }
+    await walk(root);
+    out.sort();
+    return out;
+}
+/** Compute the sha256 hex digest of a string payload (utf-8 encoded). */
+export function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Byte length of a utf-8 string. Wrapper exists so the call site is obvious. */
+export function utf8ByteLength(content) {
+    return Buffer.byteLength(content, 'utf8');
+}
+/** Return `true` when a regular file exists at the given path. */
+export async function fileExists(filePath) {
+    try {
+        const result = await stat(filePath);
+        return result.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Return `true` when a directory exists and contains at least one entry. */
+export async function directoryIsNonEmpty(dirPath) {
+    try {
+        const entries = await readdir(dirPath);
+        return entries.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Write a single file, creating parent directories as needed.
+ */
+export async function writeFileEnsuringDir(filePath, content) {
+    await mkdir(path.dirname(filePath), { recursive: true });
+    await writeFile(filePath, content, 'utf8');
+}
+/**
+ * Read a template file from disk. Trivially thin wrapper around
+ * `fs.readFile`, but exists so the scaffold imports stay symmetric with
+ * its helpers.
+ */
+export async function readTemplate(filePath) {
+    return readFile(filePath, 'utf8');
+}
+//# sourceMappingURL=files.js.map

package/dist/cli/files.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"files.js","sourceRoot":"","sources":["../../src/cli/files.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7E,OAAO,IAAI,MAAM,WAAW,CAAC;AAoC7B;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAAY;IACrD,MAAM,GAAG,GAAa,EAAE,CAAC;IAEzB,KAAK,UAAU,IAAI,CAAC,GAAW;QAC7B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;YACxC,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;YACnB,CAAC;iBAAM,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBAC1B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACtC,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,MAAM,CAAC,OAAe;IACpC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACpE,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,OAAO,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,CAAC;QACpC,OAAO,MAAM,CAAC,MAAM,EAAE,CAAC;IACzB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;QACvC,OAAO,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,QAAgB,EAAE,OAAe;IAC1E,MAAM,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,MAAM,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,OAAO,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AACpC,CAAC"}

package/dist/cli/index.d.ts

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * `dot` CLI entry point.
+ *
+ * Two commands are wired today (more land in v1.1):
+ *   - `dot explain` — print the static app graph (manifest)
+ *   - `dot doctor`  — boot the app and print runtime diagnostics
+ *
+ * Common options:
+ *   --json       Emit JSON envelope instead of human-readable text
+ *   --app <p>    Path to the app file (overrides auto-discovery)
+ *   --cwd <p>    Working directory (default: process.cwd())
+ *   --help       Show help
+ *   --version    Print version
+ *
+ * Exit codes: `0` on success/warning envelopes (doctor warnings still mean the
+ * app booted), `1` on `failure` envelopes and on every structured CLI error.
+ */
+import type { DiscoveredApp } from './discover.js';
+import type { DotCliEnvelope } from './render-explain.js';
+import { DotCliError, DotCliErrorCode, dotCliDocsUrl } from './error-codes.js';
+export type CliCommand = 'explain' | 'doctor' | 'new' | 'help' | 'version';
+export type CliArgs = {
+    command: CliCommand;
+    json: boolean;
+    appPath?: string;
+    cwd?: string;
+    /** Positional after the command (used by `new` for the app name). */
+    positional?: string;
+    /** `--target` (only honored by `new`). */
+    target?: string;
+    /** `--pm` (only honored by `new`). */
+    pm?: 'npm' | 'pnpm' | 'bun';
+    /** `--dry-run` (only honored by `new`). */
+    dryRun?: boolean;
+    /** `--force` (only honored by `new`). */
+    force?: boolean;
+    /** `--observability` (only honored by `doctor`). */
+    observability?: boolean;
+};
+/**
+ * Parse argv into a typed shape. Exported so tests can exercise it without
+ * spawning the binary.
+ */
+export declare function parseArgs(argv: readonly string[]): CliArgs;
+/**
+ * Run `explain` on a discovered app.
+ * Pure dependency on a `DiscoveredApp` so tests can pass synthetic values.
+ */
+export declare function runExplain(discovered: DiscoveredApp, opts: {
+    json: boolean;
+    out?: (line: string) => void;
+    now?: () => Date;
+}): Promise<DotCliEnvelope<unknown>>;
+type DoctorRunOptions = {
+    json: boolean;
+    out?: (line: string) => void;
+    now?: () => Date;
+    /**
+     * When `true`, probes for a registered OpenTelemetry SDK and injects
+     * a warning-severity issue into the diagnostics envelope when none is
+     * present. Default `false`.
+     */
+    observability?: boolean;
+};
+/**
+ * Run `doctor` on a discovered app. The CLI owns boot+dispose only when it
+ * receives a builder. If the caller passed an already-booted app, we leave
+ * lifecycle to them.
+ *
+ * If `boot()` throws, doctor's job is still to surface diagnostics — so we
+ * pre-configure the builder, then re-read the configured seam's diagnostics
+ * even after a boot throw. This is the whole point of `doctor`: failure
+ * should be observable, not opaque.
+ */
+export declare function runDoctor(discovered: DiscoveredApp, opts: DoctorRunOptions): Promise<DotCliEnvelope<unknown>>;
+type MainOptions = {
+    argv: readonly string[];
+    stdout?: (line: string) => void;
+    stderr?: (line: string) => void;
+    now?: () => Date;
+};
+/**
+ * Run the CLI. Returns the exit code so tests can assert without calling
+ * `process.exit`. Real entry point at the bottom of the file calls `exit()`.
+ */
+export declare function main(options: MainOptions): Promise<number>;
+/**
+ * Re-exports for test consumers and adapter packages.
+ */
+export { DotCliError, DotCliErrorCode, dotCliDocsUrl };
+export type { DotCliEnvelope, DotCliEnvelopeStatus } from './render-explain.js';
+export { runNew } from './new.js';
+export type { DotNewEnvelope, DotNewOperation } from './json.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;GAgBG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EAAE,cAAc,EAAwB,MAAM,qBAAqB,CAAC;AAGhF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA0C/E,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAE3E,MAAM,MAAM,OAAO,GAAG;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,EAAE,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC5B,2CAA2C;IAC3C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,oDAAoD;IACpD,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CA+G1D;AAQD;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CAAE,GACtE,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAgBlC;AAED,KAAK,gBAAgB,GAAG;IACtB,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,aAAa,EACzB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAoDlC;AA0DD,KAAK,WAAW,GAAG;IACjB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsGhE;AAeD;;GAEG;AACH,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}