@arki/dot 0.1.0 → 0.1.2

package/src/cli/discover.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 type { DotApp, DotAppBuilder, DotAppConfigured } from '../define-app.js';
+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: readonly string[] = ['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: readonly string[] = ['.ts', '.mts', '.mjs', '.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;
+};
+
+async function fileExists(filePath: string): Promise<boolean> {
+  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: DiscoveryOptions = {}): Promise<string | null> {
+  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: unknown): value is DotAppBuilder<Record<string, unknown>> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return typeof v.use === 'function' && typeof v.configure === 'function' && typeof v.boot === 'function';
+}
+
+function isDotAppConfigured(value: unknown): value is DotAppConfigured<Record<string, unknown>> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.name === 'string' &&
+    typeof v.boot === 'function' &&
+    'manifest' in v &&
+    'diagnostics' in v &&
+    typeof v.use !== 'function'
+  );
+}
+
+function isDotApp(value: unknown): value is DotApp<Record<string, unknown>> {
+  if (typeof value !== 'object' || value === null) return false;
+  const v = value as Record<string, unknown>;
+  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: unknown): unknown {
+  if (typeof mod !== 'object' || mod === null) return mod;
+  const record = mod as Record<string, unknown>;
+  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: string): Promise<DiscoveredApp> {
+  let mod: unknown;
+  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 as () => unknown;
+      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: DiscoveryOptions = {}): Promise<DiscoveryResult> {
+  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,
+};

package/src/cli/error-codes.ts

@@ -0,0 +1,74 @@
+/**
+ * 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',
+} as const;
+
+export type DotCliErrorCodeValue = (typeof DotCliErrorCode)[keyof typeof DotCliErrorCode];
+
+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: Record<DotCliErrorCodeValue, string> = {
+  [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: DotCliErrorCodeValue): string {
+  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 {
+  readonly code: DotCliErrorCodeValue;
+  readonly remediation: string;
+  readonly docsUrl: string;
+  readonly metadata?: Record<string, unknown>;
+  override readonly cause?: unknown;
+
+  constructor(args: {
+    code: DotCliErrorCodeValue;
+    message: string;
+    remediation: string;
+    metadata?: Record<string, unknown>;
+    cause?: unknown;
+  }) {
+    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;
+  }
+}

package/src/cli/files.ts

@@ -0,0 +1,120 @@
+/**
+ * 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';
+
+/**
+ * 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 async function collectTemplateFiles(root: string): Promise<string[]> {
+  const out: string[] = [];
+
+  async function walk(dir: string): Promise<void> {
+    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: string): string {
+  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: string): number {
+  return Buffer.byteLength(content, 'utf8');
+}
+
+/** Return `true` when a regular file exists at the given path. */
+export async function fileExists(filePath: string): Promise<boolean> {
+  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: string): Promise<boolean> {
+  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: string, content: string): Promise<void> {
+  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: string): Promise<string> {
+  return readFile(filePath, 'utf8');
+}