@arki/dot 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,456 @@
+#!/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 { parseArgs as nodeParseArgs } from 'node:util';
+import { createDebugLogger } from '@arki/log/debug';
+import { DotLifecycleError } from '../lifecycle.js';
+import { discoverApp, guards } from './discover.js';
+import { DotCliError, DotCliErrorCode, dotCliDocsUrl } from './error-codes.js';
+import { runNew } from './new.js';
+import { probeObservability } from './observability-probe.js';
+import { renderDoctor } from './render-doctor.js';
+import { renderExplain } from './render-explain.js';
+const debugCli = createDebugLogger('arki:dot:cli');
+const VERSION = '0.1.0';
+const HELP_TEXT = `dot — CLI for inspecting and scaffolding DOT apps
+
+Usage:
+  dot <command> [options]
+
+Commands:
+  explain                Print the static app graph (manifest)
+  doctor                 Boot the app and print runtime diagnostics
+  new <app-name>         Scaffold a minimal DOT app
+
+Common options:
+  --json                 Emit a JSON envelope to stdout (default: text)
+  --help                 Show this help and exit
+  --version              Print version and exit
+
+\`explain\` / \`doctor\` options:
+  --app <path>           Path to the app entry file (default: discovers
+                         ./dot.config.ts, ./src/app.ts, or ./app.ts)
+  --cwd <dir>            Working directory (default: current)
+
+\`doctor\` options:
+  --observability        Also probe whether an OpenTelemetry SDK is
+                         registered. Surfaces a warning issue when not,
+                         pointing at the docs to wire one in.
+
+\`new\` options:
+  --target <dir>         Directory to create the app in (default: <app-name>)
+  --pm <npm|pnpm|bun>    Package manager hint for the README (default: bun)
+  --dry-run              Print planned file operations without writing
+  --force                Overwrite existing files in the target directory
+`;
+/**
+ * Parse argv into a typed shape. Exported so tests can exercise it without
+ * spawning the binary.
+ */
+export function parseArgs(argv) {
+    // Extract the (optional) leading positional command; node:util parseArgs
+    // wants every positional to come *after* flags by default, but we want
+    // `dot explain --json` to parse correctly.
+    const rest = [...argv];
+    let command = null;
+    // Pull off the first positional that doesn't look like a flag.
+    for (let i = 0; i < rest.length; i++) {
+        const tok = rest[i];
+        if (!tok.startsWith('-')) {
+            const cmd = tok;
+            if (cmd === 'explain' || cmd === 'doctor' || cmd === 'new' || cmd === 'help' || cmd === 'version') {
+                command = cmd;
+                rest.splice(i, 1);
+                break;
+            }
+            throw new DotCliError({
+                code: DotCliErrorCode.UnknownCommand,
+                message: `Unknown command: ${cmd}`,
+                remediation: 'Use one of: explain, doctor, new. Run `dot --help` for usage.',
+                metadata: { received: cmd },
+            });
+        }
+    }
+    // `new` takes a positional <app-name> after the command. Pull the next
+    // non-flag token out so node:util parseArgs doesn't see it.
+    let positional;
+    if (command === 'new') {
+        for (let i = 0; i < rest.length; i++) {
+            const tok = rest[i];
+            if (!tok.startsWith('-')) {
+                positional = tok;
+                rest.splice(i, 1);
+                break;
+            }
+        }
+    }
+    let parsed;
+    try {
+        parsed = nodeParseArgs({
+            args: rest,
+            strict: true,
+            allowPositionals: false,
+            options: {
+                json: { type: 'boolean', default: false },
+                app: { type: 'string' },
+                cwd: { type: 'string' },
+                help: { type: 'boolean', default: false },
+                version: { type: 'boolean', default: false },
+                target: { type: 'string' },
+                pm: { type: 'string' },
+                'dry-run': { type: 'boolean', default: false },
+                force: { type: 'boolean', default: false },
+                observability: { type: 'boolean', default: false },
+            },
+        });
+    }
+    catch (err) {
+        throw new DotCliError({
+            code: DotCliErrorCode.InvalidArgs,
+            message: `Invalid CLI arguments: ${err instanceof Error ? err.message : String(err)}`,
+            remediation: 'Run `dot --help` to see supported options.',
+            cause: err,
+        });
+    }
+    const values = parsed.values;
+    if (values.help)
+        command = 'help';
+    if (values.version)
+        command = 'version';
+    if (!command)
+        command = 'help';
+    let pm;
+    if (values.pm !== undefined) {
+        if (values.pm !== 'npm' && values.pm !== 'pnpm' && values.pm !== 'bun') {
+            throw new DotCliError({
+                code: DotCliErrorCode.InvalidArgs,
+                message: `Invalid --pm value: ${values.pm}`,
+                remediation: 'Use one of: npm, pnpm, bun.',
+                metadata: { received: values.pm },
+            });
+        }
+        pm = values.pm;
+    }
+    return {
+        command,
+        json: values.json ?? false,
+        appPath: values.app,
+        cwd: values.cwd,
+        positional,
+        target: values.target,
+        pm,
+        dryRun: values['dry-run'] ?? false,
+        force: values.force ?? false,
+        observability: values.observability ?? false,
+    };
+}
+/** Discovery wrapper — returns `null` for help/version commands. */
+async function loadApp(args) {
+    const { app } = await discoverApp({ appPath: args.appPath, cwd: args.cwd });
+    return app;
+}
+/**
+ * Run `explain` on a discovered app.
+ * Pure dependency on a `DiscoveredApp` so tests can pass synthetic values.
+ */
+export async function runExplain(discovered, opts) {
+    let configured;
+    try {
+        if (guards.isDotAppBuilder(discovered)) {
+            // explain never boots — just configure.
+            configured = discovered.configure();
+        }
+        else {
+            configured = discovered;
+        }
+    }
+    catch (err) {
+        throw wrapLifecycleError(err, 'configure');
+    }
+    return renderExplain({ manifest: configured.manifest }, { json: opts.json, out: opts.out, now: opts.now });
+}
+/**
+ * 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 async function runDoctor(discovered, opts) {
+    // Already-booted app: just read diagnostics, don't touch lifecycle.
+    if (!guards.isDotAppBuilder(discovered) && !guards.isDotAppConfigured(discovered)) {
+        const app = discovered;
+        const diagnostics = applyObservabilityProbe(app.diagnostics, opts.observability ?? false);
+        return renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
+    }
+    // Builder or configured seam: drive lifecycle ourselves. Boot failures fall
+    // back to the configured seam's diagnostics so per-pip issues stay
+    // visible.
+    let configured;
+    try {
+        configured = guards.isDotAppBuilder(discovered)
+            ? discovered.configure()
+            : discovered;
+    }
+    catch (err) {
+        throw wrapLifecycleError(err, 'configure');
+    }
+    let bootedApp = null;
+    let bootThrew = false;
+    try {
+        bootedApp = await configured.boot();
+    }
+    catch (err) {
+        // Boot failed — surface diagnostics from the configured seam below.
+        // We deliberately swallow the throw so the user sees the per-pip
+        // issues instead of an opaque wrapper error.
+        bootThrew = true;
+        debugCli('boot threw, falling back to configured diagnostics: %O', err);
+    }
+    try {
+        const rawDiagnostics = bootedApp ? bootedApp.diagnostics : configured.diagnostics;
+        const diagnostics = applyObservabilityProbe(rawDiagnostics, opts.observability ?? false);
+        const envelope = renderDoctor({ diagnostics }, { json: opts.json, out: opts.out, now: opts.now });
+        // Sanity: if boot threw, the envelope SHOULD be failure already (kernel
+        // populates issues on boot failure). If somehow it isn't, downgrade
+        // status to surface the failure.
+        if (bootThrew && envelope.status === 'success') {
+            return { ...envelope, status: 'failure' };
+        }
+        return envelope;
+    }
+    finally {
+        if (bootedApp) {
+            try {
+                await bootedApp.dispose();
+            }
+            catch (err) {
+                debugCli('dispose threw: %O', err);
+            }
+        }
+    }
+}
+/**
+ * Run the observability probe and fold its issue (if any) into the
+ * top-level `issues` array. Returns a new snapshot — never mutates the
+ * input.
+ */
+function applyObservabilityProbe(diagnostics, enabled) {
+    if (!enabled)
+        return diagnostics;
+    const probeIssue = probeObservability();
+    if (!probeIssue)
+        return diagnostics;
+    return { ...diagnostics, issues: [...diagnostics.issues, probeIssue] };
+}
+function wrapLifecycleError(err, phase) {
+    if (err instanceof DotCliError)
+        return err;
+    const isLifecycleError = err instanceof DotLifecycleError;
+    const message = err instanceof Error ? err.message : String(err);
+    const code = isLifecycleError ? err.code : 'UNKNOWN';
+    return new DotCliError({
+        code: DotCliErrorCode.AppLifecycleFailed,
+        message: `App ${phase} failed: ${message}`,
+        remediation: phase === 'configure'
+            ? 'Check the pips registered in your app for a synchronous `configure` hook that throws or returns a Promise. Run `dot doctor` for per-pip diagnostics.'
+            : 'Run `dot doctor` to see per-pip diagnostics. The boot hook for one of your pips failed.',
+        metadata: { phase, underlyingCode: code },
+        cause: err,
+    });
+}
+/**
+ * Convert a `DotCliError` into a synthetic envelope so JSON consumers see a
+ * uniform shape regardless of failure mode.
+ */
+function errorEnvelope(err, command, now) {
+    const issue = {
+        code: err.code,
+        severity: 'error',
+        message: err.message,
+        remediation: err.remediation,
+        docsUrl: err.docsUrl,
+        metadata: err.metadata,
+    };
+    return {
+        status: 'failure',
+        command,
+        generatedAt: now().toISOString(),
+        data: null,
+        errors: [issue],
+    };
+}
+/**
+ * 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 async function main(options) {
+    const stdout = options.stdout ?? ((line) => process.stdout.write(line));
+    const stderr = options.stderr ?? ((line) => process.stderr.write(line));
+    const nowFactory = options.now ?? (() => new Date());
+    let args;
+    try {
+        args = parseArgs(options.argv);
+    }
+    catch (err) {
+        if (err instanceof DotCliError) {
+            const envelope = errorEnvelope(err, 'unknown', nowFactory);
+            stderr(`${JSON.stringify(envelope, null, 2)}\n`);
+            return 1;
+        }
+        throw err;
+    }
+    if (args.command === 'help') {
+        stdout(HELP_TEXT);
+        return 0;
+    }
+    if (args.command === 'version') {
+        stdout(`${VERSION}\n`);
+        return 0;
+    }
+    if (args.command === 'new') {
+        if (!args.positional) {
+            const err = new DotCliError({
+                code: DotCliErrorCode.InvalidArgs,
+                message: 'Missing required <app-name> positional for `dot new`.',
+                remediation: 'Run `dot new <app-name>`. Example: `dot new my-app`.',
+            });
+            const envelope = errorEnvelope(err, 'new', nowFactory);
+            if (args.json)
+                stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+            else
+                stderr(formatErrorText(err));
+            return 1;
+        }
+        try {
+            const envelope = await runNew({
+                name: args.positional,
+                cwd: args.cwd,
+                target: args.target,
+                pm: args.pm,
+                dryRun: args.dryRun,
+                json: args.json,
+                force: args.force,
+                out: stdout,
+                err: stderr,
+                now: nowFactory,
+            });
+            return envelope.status === 'failure' ? 1 : 0;
+        }
+        catch (err) {
+            if (err instanceof DotCliError) {
+                const envelope = errorEnvelope(err, 'new', nowFactory);
+                if (args.json)
+                    stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+                else
+                    stderr(formatErrorText(err));
+                return 1;
+            }
+            throw err;
+        }
+    }
+    try {
+        const discovered = await loadApp(args);
+        const opts = { json: args.json, out: stdout, now: nowFactory };
+        let envelope;
+        if (args.command === 'explain') {
+            envelope = await runExplain(discovered, opts);
+        }
+        else {
+            envelope = await runDoctor(discovered, { ...opts, observability: args.observability });
+        }
+        return envelopeExitCode(envelope.status);
+    }
+    catch (err) {
+        if (err instanceof DotCliError) {
+            const envelope = errorEnvelope(err, args.command, nowFactory);
+            if (args.json) {
+                stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+            }
+            else {
+                stderr(formatErrorText(err));
+            }
+            return 1;
+        }
+        // Last-resort path: an exception escaped without being wrapped. Surface
+        // it as a structured envelope rather than dumping a stack trace.
+        const fallback = new DotCliError({
+            code: DotCliErrorCode.AppLifecycleFailed,
+            message: err instanceof Error ? err.message : String(err),
+            remediation: 'See debug logs (DEBUG=arki:dot:cli) for context. Re-run with --json for machine-readable output.',
+            cause: err,
+        });
+        const envelope = errorEnvelope(fallback, args.command, nowFactory);
+        if (args.json) {
+            stdout(`${JSON.stringify(envelope, null, 2)}\n`);
+        }
+        else {
+            stderr(formatErrorText(fallback));
+        }
+        return 1;
+    }
+}
+function envelopeExitCode(status) {
+    return status === 'failure' ? 1 : 0;
+}
+function formatErrorText(err) {
+    return [
+        `dot: ${err.code} ${err.message}`,
+        `  remediation: ${err.remediation}`,
+        `  docs: ${err.docsUrl}`,
+        '',
+    ].join('\n');
+}
+/**
+ * Re-exports for test consumers and adapter packages.
+ */
+export { DotCliError, DotCliErrorCode, dotCliDocsUrl };
+export { runNew } from './new.js';
+// Direct-execution guard: only spin up the CLI when this module is the entry
+// point, not when it's imported (e.g. by tests).
+const isMainModule = await (async () => {
+    try {
+        // Bun sets `import.meta.main` when running as the entry script.
+        if (typeof import.meta.main === 'boolean') {
+            return import.meta.main;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    // Node fallback: compare argv[1]'s resolved file URL with import.meta.url.
+    try {
+        const entry = process.argv[1];
+        if (typeof entry !== 'string')
+            return false;
+        const { pathToFileURL } = await import('node:url');
+        return pathToFileURL(entry).href === import.meta.url;
+    }
+    catch {
+        return false;
+    }
+})();
+if (isMainModule) {
+    void main({ argv: process.argv.slice(2) }).then(code => {
+        process.exit(code);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

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

package/dist/cli/json.d.ts

@@ -0,0 +1,38 @@
+/**
+ * JSON envelope shapes for the `dot new` command.
+ *
+ * The envelope mirrors `DotCliEnvelope` in spirit but exposes the
+ * scaffold-specific `app` + `operations` payload directly at the top level
+ * so consumers don't have to dig under a generic `data` field.
+ */
+import type { DiagnosticIssue } from '../diagnostics.js';
+import type { FileOperation } from './files.js';
+/** Subset of {@link FileOperation} emitted in the JSON envelope. */
+export type DotNewOperation = {
+    readonly path: string;
+    readonly action: FileOperation['action'];
+    readonly contentHash: string;
+    readonly contentBytes: number;
+    readonly reason: string;
+};
+/**
+ * Envelope returned by `dot new`. Both dry-run and real runs share the
+ * same shape, distinguished only by `errors` and per-operation `action`.
+ *
+ * `errors` carries the same {@link DiagnosticIssue} shape used everywhere
+ * else in the CLI — agents already parse it.
+ */
+export type DotNewEnvelope = {
+    readonly status: 'success' | 'failure';
+    readonly command: 'new';
+    readonly generatedAt: string;
+    readonly app: {
+        readonly name: string;
+        readonly target: string;
+    };
+    readonly operations: readonly DotNewOperation[];
+    readonly errors: readonly DiagnosticIssue[];
+};
+/** Strip the in-memory `content` field before serialising. */
+export declare function toPublicOperation(op: FileOperation): DotNewOperation;
+//# sourceMappingURL=json.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/cli/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,oEAAoE;AACpE,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE;QACZ,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IAChD,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C,CAAC;AAEF,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,aAAa,GAAG,eAAe,CAQpE"}

package/dist/cli/json.js

@@ -0,0 +1,18 @@
+/**
+ * JSON envelope shapes for the `dot new` command.
+ *
+ * The envelope mirrors `DotCliEnvelope` in spirit but exposes the
+ * scaffold-specific `app` + `operations` payload directly at the top level
+ * so consumers don't have to dig under a generic `data` field.
+ */
+/** Strip the in-memory `content` field before serialising. */
+export function toPublicOperation(op) {
+    return {
+        path: op.path,
+        action: op.action,
+        contentHash: op.contentHash,
+        contentBytes: op.contentBytes,
+        reason: op.reason,
+    };
+}
+//# sourceMappingURL=json.js.map

package/dist/cli/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/cli/json.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiCH,8DAA8D;AAC9D,MAAM,UAAU,iBAAiB,CAAC,EAAiB;IACjD,OAAO;QACL,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,MAAM,EAAE,EAAE,CAAC,MAAM;QACjB,WAAW,EAAE,EAAE,CAAC,WAAW;QAC3B,YAAY,EAAE,EAAE,CAAC,YAAY;QAC7B,MAAM,EAAE,EAAE,CAAC,MAAM;KAClB,CAAC;AACJ,CAAC"}

package/dist/cli/new.d.ts

@@ -0,0 +1,105 @@
+/**
+ * `dot new <app>` — scaffold a minimal DOT app.
+ *
+ * Two-phase: we first build an in-memory list of {@link FileOperation}
+ * entries describing every file the scaffold WOULD write (template
+ * substitution included), then either:
+ *
+ *   - `--dry-run` -> print the JSON envelope, write nothing.
+ *   - real run    -> commit the planned operations to disk.
+ *
+ * The dry-run envelope is the contract: agents read it to know exactly
+ * which files will land, with sha256 hashes so they can verify the
+ * post-run filesystem matches the plan.
+ *
+ * Templates live at `packages/dot/templates/app-minimal/` and use
+ * `.tmpl` suffixes + `{{name}}`-style placeholders. The suffix is
+ * stripped during scaffolding so `package.json.tmpl` becomes
+ * `package.json` on disk.
+ *
+ * Commands deferred to v1.1 (`dot add <pip>`, `dot dev`,
+ * `dot migrate`) are deliberately NOT surfaced here.
+ */
+import type { FileOperation } from './files.js';
+import type { DotNewEnvelope } from './json.js';
+/**
+ * Package manager the generated README + AGENTS.md will reference.
+ * `bun` is the default because the kernel + adapter packages are tested
+ * with Bun first.
+ */
+export type PackageManager = 'npm' | 'pnpm' | 'bun';
+/** Options accepted by {@link runNew}. */
+export type RunNewOptions = {
+    /** Application name (becomes `package.json#name`). */
+    readonly name: string;
+    /**
+     * Working directory for resolving `--target`. Defaults to
+     * `process.cwd()` when omitted.
+     */
+    readonly cwd?: string;
+    /**
+     * Target directory; resolved against `cwd`. Defaults to `<name>`
+     * under `cwd`. The directory is created if missing.
+     */
+    readonly target?: string;
+    /** Package manager hint surfaced in README/AGENTS.md. Defaults to `bun`. */
+    readonly pm?: PackageManager;
+    /** When true, only plan operations — write nothing. */
+    readonly dryRun?: boolean;
+    /** When true, emit JSON to `out`. Otherwise emit progress lines. */
+    readonly json?: boolean;
+    /** When true, overwrite existing files in the target dir. */
+    readonly force?: boolean;
+    /** Stdout sink. Defaults to `process.stdout.write`. */
+    readonly out?: (line: string) => void;
+    /** Stderr sink. Defaults to `process.stderr.write`. */
+    readonly err?: (line: string) => void;
+    /** Override clock for deterministic envelopes. */
+    readonly now?: () => Date;
+    /**
+     * Override template root. Used by tests; production callers should
+     * leave this undefined so the bundled `templates/app-minimal/`
+     * directory is used.
+     */
+    readonly templateRoot?: string;
+    /**
+     * Version values inlined into the generated `package.json`. The
+     * defaults track the current `@arki/dot` + `@arki/env` releases.
+     */
+    readonly versions?: {
+        readonly dot?: string;
+        readonly env?: string;
+        readonly zod?: string;
+    };
+};
+/**
+ * Resolve the absolute target path for a given app + options bundle.
+ * Exported so tests can assert resolution behaviour without running the
+ * full scaffold.
+ */
+export declare function resolveTargetDir(opts: {
+    name: string;
+    cwd?: string;
+    target?: string;
+}): string;
+/**
+ * Validate an app name. Rules match `package.json#name` constraints
+ * (lower-case, leading alphanumeric, no spaces) with one extra: we
+ * disallow scoped names so the scaffold produces a single-segment dir.
+ */
+export declare function validateAppName(name: string): void;
+/**
+ * Plan the file operations for a scaffold run. Pure — does not touch
+ * disk other than reading templates and `stat`-ing target paths.
+ */
+export declare function planOperations(opts: RunNewOptions): Promise<{
+    operations: FileOperation[];
+    target: string;
+}>;
+/**
+ * Run the `new` command. Returns the envelope so callers (CLI + tests)
+ * can act on it. Side effects: writes files when not in dry-run mode,
+ * emits progress to `out`/`err`.
+ */
+export declare function runNew(opts: RunNewOptions): Promise<DotNewEnvelope>;
+//# sourceMappingURL=new.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"new.d.ts","sourceRoot":"","sources":["../../src/cli/new.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAehD;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAEpD,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GAAG;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,kDAAkD;IAClD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE;QAClB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH,CAAC;AAsCF;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAI9F;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAiBlD;AAeD;;;GAGG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IACjE,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC,CAiED;AA0BD;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,cAAc,CAAC,CA4HzE"}