blogwright 0.3.3 → 0.4.0-beta.0

package/dist/context.d.ts

@@ -7,13 +7,26 @@ export interface OpsContext {
     /** True for the shared preview stack (host-routed, per-PR prefixes). */
     preview: boolean;
     config: OpsConfig;
+    /**
+     * The environment's config file exactly as parsed, before `OpsConfig`'s
+     * merge and validation - every top-level key the document carries, a
+     * plugin's own block included. `OpsConfig` has no index signature, so this
+     * is the only typed route to `config[plugin.configKey]` (see
+     * `blogwright-core`'s `parseConfigDocument`).
+     *
+     * CLI-side ONLY, and deliberately absent from `PluginContext`: dispatch
+     * reads the DISPATCHED plugin's block off this and hands that one block to
+     * that one plugin (`resolvePluginConfig`, `plugins.ts`), so no plugin ever
+     * sees another plugin's config.
+     */
+    configDocument: Readonly<Record<string, unknown>>;
     names: Names;
     accountId: string;
     clients: AwsClients;
     ports: Ports;
     /**
-     * Directory holding the build-agent artifacts — Dockerfile, bundled server.js,
-     * and agent-manifest.json — copied into this package by its build
+     * Directory holding the build-agent artifacts - Dockerfile, bundled server.js,
+     * and agent-manifest.json - copied into this package by its build
      * (scripts/copy-agent.mjs). Resolved at the composition root; tests inject one.
      */
     agentDir: string;
@@ -30,7 +43,7 @@ export interface OpsContext {
 }
 /**
  * The `app` tag value, by precedence: the explicit `config.app`, else the
- * site's domain, else the repo directory name — always something a human can
+ * site's domain, else the repo directory name - always something a human can
  * trace back to the project from a billing or resource listing.
  */
 export declare function deriveAppTag(config: Pick<OpsConfig, 'app'>, domain: string | undefined, repoRoot: string): string;
@@ -43,6 +56,42 @@ export interface ContextOptions {
     /** Adapter overrides; anything omitted defaults to the real (node) adapter. */
     ports?: Partial<Ports> | undefined;
 }
+/**
+ * The directory holding the CLI's own `package.json` - `blogwright`'s package
+ * root. Located from `import.meta.url` the same way {@link OpsContext.agentDir}
+ * is (below): `packages/cli/package.json` declares an `exports` map with a
+ * `./rkey` entry and no `.` entry (the CLI is consumed through its `bin`, not
+ * imported), so neither `blogwright` nor `blogwright/package.json` can be
+ * resolved through the `ModuleLoader` port - see that port's doc comment.
+ * Self-location is therefore a composition-root concern, not something
+ * `discover` (`plugins.ts`) can derive itself.
+ *
+ * A standalone function, not folded into {@link createContext}: `blogwright
+ * plugin list` dispatches before a context exists and still needs this
+ * value, and it is the one supplier every discovery-running path (plugin
+ * dispatch, `blogwright --help`, the init wizard, `plugin list`) passes as
+ * `discover`'s second argument.
+ */
+export declare function cliPackageDir(): string;
+/**
+ * The running CLI's own declared version - the value `blogwright plugin add`
+ * (`plugin-commands.ts`) pins into the install spec, so a plugin and the CLI
+ * that dispatches it can never silently drift apart across two developers'
+ * checkouts.
+ *
+ * Read HERE, at the composition root, for exactly the reason
+ * {@link cliPackageDir} is resolved here: `blogwright`'s own `exports` map has
+ * no `.` entry, so neither the package nor its `package.json` can be reached
+ * through the `ModuleLoader` port, and this module is one of the few the
+ * `no-restricted-imports` rule lets touch `node:fs` at all. `plugin-commands.ts`
+ * receives the resolved string as DATA and never walks the filesystem for it -
+ * the same division `agentDir` already makes.
+ *
+ * Read on demand rather than at module load: `blogwright plugin list` and every
+ * built-in command share this module and none of them needs the value, so only
+ * the one command that pins a version pays for the read.
+ */
+export declare function cliVersion(): Promise<string>;
 export interface ConfigSource {
     env: string;
     /** Repo root the default config candidates resolve against. */
@@ -50,12 +99,33 @@ export interface ConfigSource {
     /** Explicit config file; when set it is the only candidate. */
     configPath?: string | undefined;
 }
-/** Load and parse the first config candidate that exists. Exported for tests. */
-export declare function loadConfig(fs: FileSystem, source: ConfigSource): Promise<OpsConfig>;
+/**
+ * Resolve the first config candidate that exists, in `configCandidates`'
+ * precedence. Throws, naming every candidate it looked for, when none does -
+ * the same message `loadConfig` has always raised on this path.
+ *
+ * Exported so `blogwright <plugin> init` (`plugin-commands.ts`) writes its
+ * spliced block into exactly the file `loadConfig` would read, rather than
+ * re-deriving the candidate list a second time.
+ */
+export declare function resolveConfigPath(fs: FileSystem, source: ConfigSource): Promise<string>;
+/**
+ * Load and parse the first config candidate that exists, returning BOTH
+ * halves `parseConfigDocument` produces: the validated `config` every
+ * built-in command reads, and the `raw` document the dispatch path reads a
+ * plugin's own block out of. The candidate list and its precedence are
+ * unchanged - only the return type widens, so `createContext` can keep the
+ * raw half on {@link OpsContext.configDocument} instead of the file having to
+ * be read and parsed a second time at dispatch. Exported for tests.
+ */
+export declare function loadConfig(fs: FileSystem, source: ConfigSource): Promise<{
+    config: OpsConfig;
+    raw: Readonly<Record<string, unknown>>;
+}>;
 /**
  * Build the runtime context: load config, resolve the account id, derive names, create
  * clients, and load topology state from S3. The state bucket name is deterministic, which
- * resolves the bootstrap chicken-and-egg. This is the composition root — the only place
+ * resolves the bootstrap chicken-and-egg. This is the composition root - the only place
  * real adapters are constructed and wired.
  */
 export declare function createContext(opts: ContextOptions): Promise<OpsContext>;

package/dist/context.js

@@ -1,53 +1,132 @@
-import { basename, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { basename, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { createClients, createNodeFileSystem, createNodeTerminal, deriveNames, FileNotFoundError, findRepoRoot, parseConfig, StateStore, } from 'blogwright-core';
+import { createClients, createNodeFileSystem, createNodeTerminal, deriveNames, findRepoRoot, parseConfigDocument, StateStore, } from 'blogwright-core';
 import { createFetchPing } from './adapters/fetch-ping.js';
+import { createNodeModuleLoader } from './adapters/node-module-loader.js';
 import { createProcessVcs } from './adapters/process-vcs.js';
 import { createLogger } from './logger.js';
 /**
  * The `app` tag value, by precedence: the explicit `config.app`, else the
- * site's domain, else the repo directory name — always something a human can
+ * site's domain, else the repo directory name - always something a human can
  * trace back to the project from a billing or resource listing.
  */
 export function deriveAppTag(config, domain, repoRoot) {
     return config.app ?? domain ?? basename(repoRoot);
 }
-/** Load and parse the first config candidate that exists. Exported for tests. */
-export async function loadConfig(fs, source) {
-    const candidates = source.configPath
+/**
+ * The directory holding the CLI's own `package.json` - `blogwright`'s package
+ * root. Located from `import.meta.url` the same way {@link OpsContext.agentDir}
+ * is (below): `packages/cli/package.json` declares an `exports` map with a
+ * `./rkey` entry and no `.` entry (the CLI is consumed through its `bin`, not
+ * imported), so neither `blogwright` nor `blogwright/package.json` can be
+ * resolved through the `ModuleLoader` port - see that port's doc comment.
+ * Self-location is therefore a composition-root concern, not something
+ * `discover` (`plugins.ts`) can derive itself.
+ *
+ * A standalone function, not folded into {@link createContext}: `blogwright
+ * plugin list` dispatches before a context exists and still needs this
+ * value, and it is the one supplier every discovery-running path (plugin
+ * dispatch, `blogwright --help`, the init wizard, `plugin list`) passes as
+ * `discover`'s second argument.
+ */
+export function cliPackageDir() {
+    // `new URL('..', …)` yields a trailing separator, unlike every other directory
+    // value in the CLI. join() and createRequire() tolerate it, but a caller
+    // writing `${cliPackageDir()}/x` would get a doubled separator - in the path
+    // and in any error message built from it. Normalise here so no caller has to
+    // remember. Four discovery-running paths (tasks 10, 11, 14, 17) consume this.
+    return resolve(fileURLToPath(new URL('..', import.meta.url)));
+}
+/** Narrow parsed JSON to an object before reading a field off it - no cast, no `any`. */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * The running CLI's own declared version - the value `blogwright plugin add`
+ * (`plugin-commands.ts`) pins into the install spec, so a plugin and the CLI
+ * that dispatches it can never silently drift apart across two developers'
+ * checkouts.
+ *
+ * Read HERE, at the composition root, for exactly the reason
+ * {@link cliPackageDir} is resolved here: `blogwright`'s own `exports` map has
+ * no `.` entry, so neither the package nor its `package.json` can be reached
+ * through the `ModuleLoader` port, and this module is one of the few the
+ * `no-restricted-imports` rule lets touch `node:fs` at all. `plugin-commands.ts`
+ * receives the resolved string as DATA and never walks the filesystem for it -
+ * the same division `agentDir` already makes.
+ *
+ * Read on demand rather than at module load: `blogwright plugin list` and every
+ * built-in command share this module and none of them needs the value, so only
+ * the one command that pins a version pays for the read.
+ */
+export async function cliVersion() {
+    const path = join(cliPackageDir(), 'package.json');
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    const version = isRecord(parsed) ? parsed.version : undefined;
+    if (typeof version !== 'string' || version.length === 0) {
+        throw new Error(`${path} declares no "version" - \`blogwright plugin add\` pins the installed plugin to ` +
+            "the running CLI's own version and has nothing to pin to");
+    }
+    return version;
+}
+/** Candidate config paths, in the precedence `loadConfig`/`resolveConfigPath` read them: an explicit `--config`, or `config/<env>.jsonc` then `ops.config.jsonc`. */
+function configCandidates(source) {
+    return source.configPath
         ? [source.configPath]
         : [
             resolve(source.root, `config/${source.env}.jsonc`),
             resolve(source.root, 'ops.config.jsonc'),
         ];
+}
+/**
+ * Resolve the first config candidate that exists, in `configCandidates`'
+ * precedence. Throws, naming every candidate it looked for, when none does -
+ * the same message `loadConfig` has always raised on this path.
+ *
+ * Exported so `blogwright <plugin> init` (`plugin-commands.ts`) writes its
+ * spliced block into exactly the file `loadConfig` would read, rather than
+ * re-deriving the candidate list a second time.
+ */
+export async function resolveConfigPath(fs, source) {
+    const candidates = configCandidates(source);
     for (const path of candidates) {
-        try {
-            return parseConfig(await fs.readText(path));
-        }
-        catch (err) {
-            if (!(err instanceof FileNotFoundError))
-                throw err;
-        }
+        if (await fs.exists(path))
+            return path;
     }
-    throw new Error(`no config found for environment "${source.env}" — looked for ${candidates.join(', ')}`);
+    throw new Error(`no config found for environment "${source.env}" - looked for ${candidates.join(', ')}`);
+}
+/**
+ * Load and parse the first config candidate that exists, returning BOTH
+ * halves `parseConfigDocument` produces: the validated `config` every
+ * built-in command reads, and the `raw` document the dispatch path reads a
+ * plugin's own block out of. The candidate list and its precedence are
+ * unchanged - only the return type widens, so `createContext` can keep the
+ * raw half on {@link OpsContext.configDocument} instead of the file having to
+ * be read and parsed a second time at dispatch. Exported for tests.
+ */
+export async function loadConfig(fs, source) {
+    return parseConfigDocument(await fs.readText(await resolveConfigPath(fs, source)));
 }
 /**
  * Build the runtime context: load config, resolve the account id, derive names, create
  * clients, and load topology state from S3. The state bucket name is deterministic, which
- * resolves the bootstrap chicken-and-egg. This is the composition root — the only place
+ * resolves the bootstrap chicken-and-egg. This is the composition root - the only place
  * real adapters are constructed and wired.
  */
 export async function createContext(opts) {
+    const fs = opts.ports?.fs ?? createNodeFileSystem();
     const ports = {
-        fs: opts.ports?.fs ?? createNodeFileSystem(),
+        fs,
         vcs: opts.ports?.vcs ?? createProcessVcs(),
         terminal: opts.ports?.terminal ?? createNodeTerminal(),
         ping: opts.ports?.ping ?? createFetchPing(),
+        loader: opts.ports?.loader ?? createNodeModuleLoader(),
     };
     const logger = createLogger(ports.terminal);
-    const agentDir = fileURLToPath(new URL('../agent', import.meta.url));
+    const agentDir = join(cliPackageDir(), 'agent');
     const root = await findRepoRoot(ports.fs);
-    const config = await loadConfig(ports.fs, {
+    const { config, raw: configDocument } = await loadConfig(ports.fs, {
         env: opts.env,
         root,
         configPath: opts.configPath,
@@ -68,6 +147,7 @@ export async function createContext(opts) {
         domain,
         preview: opts.preview ?? false,
         config,
+        configDocument,
         names,
         accountId,
         clients,

package/dist/deploy.d.ts

@@ -19,7 +19,7 @@ declare function manifestKey(hash: string): string;
 /**
  * Launch the builder MicroVM, retrying gateway errors (502/503/504) with a
  * bounded backoff. The control plane can answer 502 for a short window right
- * after the builder image was updated (fresh agent hash) — an
+ * after the builder image was updated (fresh agent hash) - an
  * eventual-consistency gap that would otherwise fail every consumer's first
  * deploy after a blogwright upgrade. Retrying is safe: the input's client
  * token makes the launch idempotent. Exported for tests.
@@ -29,7 +29,7 @@ export declare function runMicrovmWithRetry(ctx: OpsContext, input: RunMicrovmIn
  * Resolve the MicroVM build log group from bootstrapped state rather than re-deriving it.
  * The image and the build-role IAM policy bake this name in at bootstrap, so if the derived
  * name (`ctx.names.microvmLogGroup`) is renamed in code later, a deploy must still target
- * the group the running stack actually logs to — otherwise the VM's logs land in (or are
+ * the group the running stack actually logs to - otherwise the VM's logs land in (or are
  * denied to) a different group and `pollBuild` waits on an empty one.
  */
 export declare function microvmLogGroup(ctx: OpsContext): string;

package/dist/deploy.js

@@ -7,8 +7,8 @@ function manifestKey(hash) {
 }
 /**
  * Nudge the MicroVM's endpoint to wake its event loop. A Firecracker-resumed process
- * can sit idle with its poll timer pending until some I/O arrives; a connection here —
- * even one the agent's HTTP/1 server can't fully parse — wakes the loop so the timer
+ * can sit idle with its poll timer pending until some I/O arrives; a connection here -
+ * even one the agent's HTTP/1 server can't fully parse - wakes the loop so the timer
  * fires and the build starts. The wake-up, not the response, is the point: a missing
  * endpoint or token means nothing to nudge, and a rejecting ping never fails the poll.
  */
@@ -26,7 +26,7 @@ function isGatewayError(err) {
 /**
  * Launch the builder MicroVM, retrying gateway errors (502/503/504) with a
  * bounded backoff. The control plane can answer 502 for a short window right
- * after the builder image was updated (fresh agent hash) — an
+ * after the builder image was updated (fresh agent hash) - an
  * eventual-consistency gap that would otherwise fail every consumer's first
  * deploy after a blogwright upgrade. Retrying is safe: the input's client
  * token makes the launch idempotent. Exported for tests.
@@ -40,7 +40,7 @@ export async function runMicrovmWithRetry(ctx, input, delaysMs = RUN_RETRY_DELAY
             const delay = delaysMs[attempt];
             if (!isGatewayError(err) || delay === undefined)
                 throw err;
-            ctx.logger.warn(`MicroVM launch returned HTTP ${err.statusCode} — ` +
+            ctx.logger.warn(`MicroVM launch returned HTTP ${err.statusCode} - ` +
                 `retrying in ${Math.round(delay / 1000)}s (a just-updated builder image can lag)`);
             await sleep(delay);
         }
@@ -50,7 +50,7 @@ export async function runMicrovmWithRetry(ctx, input, delaysMs = RUN_RETRY_DELAY
  * Resolve the MicroVM build log group from bootstrapped state rather than re-deriving it.
  * The image and the build-role IAM policy bake this name in at bootstrap, so if the derived
  * name (`ctx.names.microvmLogGroup`) is renamed in code later, a deploy must still target
- * the group the running stack actually logs to — otherwise the VM's logs land in (or are
+ * the group the running stack actually logs to - otherwise the VM's logs land in (or are
  * denied to) a different group and `pollBuild` waits on an empty one.
  */
 export function microvmLogGroup(ctx) {
@@ -74,7 +74,7 @@ export function microvmLogGroup(ctx) {
  */
 export async function pollBuild(ctx, hash, startTime, endpoint, token) {
     const seen = new Set();
-    // Anchored at VM launch (startTime), like the VM's own maximumDuration —
+    // Anchored at VM launch (startTime), like the VM's own maximumDuration -
     // anchoring at poll start would keep polling a VM that is already dead for
     // however long the RUNNING-wait consumed. One grace minute for log delivery.
     const deadline = startTime + ctx.config.microvm.maxDurationSeconds * 1000 + 60_000;
@@ -109,7 +109,7 @@ export async function pollBuild(ctx, hash, startTime, endpoint, token) {
                 return result;
             // Log delivery can lag or drop (e.g. the VM logging to a group the deploy isn't tailing).
             // The agent writes build/changed/<hash>.json as its final step, so treat that artifact as
-            // an authoritative completion signal too — a successful build then can't hang until the
+            // an authoritative completion signal too - a successful build then can't hang until the
             // deadline just because its logs never reached CloudWatch. runBuild clears any stale copy
             // before launch, so its presence means *this* build finished.
             if (await ctx.clients.s3.objectExists(ctx.names.bucket, `build/changed/${hash}.json`)) {
@@ -147,7 +147,7 @@ export async function runBuild(ctx, opts) {
     ctx.logger.step(`running builder MicroVM for ${opts.hash}`);
     // Launch first: if runMicrovm throws, no pending.json is left behind (a leaked job
     // could otherwise be picked up during a later image bake and poison the snapshot).
-    // A MicroVM is ephemeral compute, so the client token is unique per launch — keying it
+    // A MicroVM is ephemeral compute, so the client token is unique per launch - keying it
     // on the hash would make a re-deploy (or workflow re-run) of the same source idempotently
     // return the ALREADY-TERMINATED original VM instead of launching a fresh one. Generated
     // once here so a network retry of this single call still dedupes.
@@ -195,7 +195,7 @@ export async function runBuild(ctx, opts) {
     finally {
         // The pending-job cleanup must survive a terminate failure: a leaked
         // pending.json is the poison-the-next-image-bake hazard the launch
-        // ordering above exists to avoid. A failed terminate is only logged —
+        // ordering above exists to avoid. A failed terminate is only logged -
         // the VM self-terminates at maxDuration, and the build outcome (already
         // determined) must not be masked by a cleanup error.
         await ctx.clients.microvms.terminateMicrovm(run.microvmId).catch((err) => {
@@ -251,17 +251,17 @@ export async function invalidateChanged(ctx, hash) {
         }
     }
     if (!paths) {
-        ctx.logger.warn('no changed-paths manifest — invalidating everything (/*)');
+        ctx.logger.warn('no changed-paths manifest - invalidating everything (/*)');
         await invalidateCloudFront(ctx, ['/*']);
         return { mode: 'all', count: 0 };
     }
     let summary;
     if (paths.length === 0) {
-        ctx.logger.ok('no content changed — skipping CloudFront invalidation');
+        ctx.logger.ok('no content changed - skipping CloudFront invalidation');
         summary = { mode: 'none', count: 0 };
     }
     else if (paths.length > ctx.config.invalidationMaxPaths) {
-        ctx.logger.step(`${paths.length} paths changed (> cap) — invalidating everything (/*)`);
+        ctx.logger.step(`${paths.length} paths changed (> cap) - invalidating everything (/*)`);
         await invalidateCloudFront(ctx, ['/*']);
         summary = { mode: 'all', count: paths.length };
     }

package/dist/graph.d.ts

@@ -1,20 +1,31 @@
-import type { OpsContext } from './context.js';
-/** A node in the infrastructure dependency graph. */
-export interface ResourceNode {
-    id: string;
-    dependsOn: string[];
-    /** Human label for logging. */
-    title: string;
-    /** Does the resource already exist? (Also hydrates outputs into ctx.state.) */
-    read(ctx: OpsContext): Promise<boolean>;
-    create(ctx: OpsContext): Promise<void>;
-    /** Reconcile an existing resource (optional). */
-    update?(ctx: OpsContext): Promise<void>;
-    delete(ctx: OpsContext): Promise<void>;
+import type { ResourceNode, ResourceOutputs } from 'blogwright-core';
+/**
+ * The structural minimum the engine below (`topoSort`, `applyGraph`,
+ * `destroyGraph`) actually reads off a node's context: a logger it calls
+ * `step`/`ok`/`warn` on, a way to persist state, and the state's resources
+ * map (`destroyGraph` deletes an entry from it). Exported so a caller
+ * running this engine over a different context - `OpsContext` (`context.ts`)
+ * and core's `PluginContext` (`blogwright-core`) both do already - knows
+ * exactly what that context must supply, without this module depending on
+ * either one. Neither `OpsContext` nor `PluginContext` is named here on
+ * purpose: this is the structural minimum both happen to satisfy, not a
+ * fixed supertype of them (see the doc comment on core's `ResourceNode` for
+ * why no such supertype is worth naming).
+ */
+export interface GraphContext {
+    logger: {
+        step(msg: string): void;
+        ok(msg: string): void;
+        warn(msg: string): void;
+    };
+    state: {
+        resources: Record<string, ResourceOutputs>;
+    };
+    save(): Promise<void>;
 }
 /** Topologically order nodes so dependencies come before dependents (Kahn's algorithm). */
-export declare function topoSort(nodes: ResourceNode[]): ResourceNode[];
+export declare function topoSort<Ctx>(nodes: ResourceNode<Ctx>[]): ResourceNode<Ctx>[];
 /** Reconcile the graph in dependency order (create missing, update existing). */
-export declare function applyGraph(nodes: ResourceNode[], ctx: OpsContext): Promise<void>;
+export declare function applyGraph<Ctx extends GraphContext>(nodes: ResourceNode<Ctx>[], ctx: Ctx): Promise<void>;
 /** Tear down the graph in reverse dependency order. */
-export declare function destroyGraph(nodes: ResourceNode[], ctx: OpsContext): Promise<void>;
+export declare function destroyGraph<Ctx extends GraphContext>(nodes: ResourceNode<Ctx>[], ctx: Ctx): Promise<void>;

package/dist/graph.js

@@ -77,7 +77,7 @@ export async function destroyGraph(nodes, ctx) {
         await node.delete(ctx);
         delete ctx.state.resources[node.id];
         // The state lives in the bucket that is itself being deleted, so persisting it may
-        // fail (NoSuchBucket) once the bucket node is gone — never let that abort teardown.
+        // fail (NoSuchBucket) once the bucket node is gone - never let that abort teardown.
         await ctx.save().catch(() => undefined);
         ctx.logger.ok(`deleted ${node.title}`);
     }

package/dist/init.d.ts

@@ -1,4 +1,38 @@
-import { type FileSystem, type Terminal } from 'blogwright-core';
+import { type FileSystem, type Plugin, type Terminal } from 'blogwright-core';
 import type { Logger } from './logger.js';
-/** Run the wizard. Returns a process exit code; never throws for expected refusals. */
-export declare function initSite(fs: FileSystem, terminal: Terminal, logger: Logger, root?: string): Promise<number>;
+/**
+ * One question, and how to ask it: shown text, a prefilled default, whether
+ * an empty answer must re-prompt, and an optional validator. Exported - and
+ * `ask` below along with it - because `plugin-commands.ts`'s `io.ask` (the
+ * surface an `init?(io)` contributor asks its own questions through) reuses
+ * this exact prompt/validate/retry loop rather than writing a second one; no
+ * plugin path may reach `node:readline` itself. Structurally the same shape
+ * as core's `PluginQuestion` (`blogwright-core`'s `plugin.ts`), so a
+ * contributor's question passes straight through with no conversion.
+ */
+export interface Question {
+    prompt: string;
+    defaultValue?: string | undefined;
+    required?: boolean | undefined;
+    validate?: ((answer: string) => string | undefined) | undefined;
+}
+/**
+ * Ask `q.prompt` over `terminal`, retrying up to `MAX_ATTEMPTS` times on a
+ * required-but-empty answer or a `validate` failure, and resolving with
+ * `undefined` for an unanswered optional question. Throws once every attempt
+ * is spent. The one prompt/validate/retry loop every wizard-shaped question -
+ * `blogwright init`'s own four and any plugin's `init?(io)` contributor -
+ * asks through.
+ */
+export declare function ask(terminal: Terminal, logger: Logger, q: Question): Promise<string | undefined>;
+/**
+ * Run the wizard. Returns a process exit code; never throws for expected
+ * refusals (non-interactive, an existing config file). `plugins` is every
+ * plugin the caller has ALREADY discovered (`cli.ts`, over
+ * `DiscoveryPortsFactory`) - this function asks their questions and writes
+ * their blocks but never runs discovery itself. A plugin's `init(io)`
+ * contributor throwing propagates unchanged, rejecting this call before the
+ * single `fs.writeText` below ever runs, so the config file stays exactly
+ * what it was - absent, on this path - rather than a partial write.
+ */
+export declare function initSite(fs: FileSystem, terminal: Terminal, logger: Logger, plugins: readonly Plugin[], root?: string): Promise<number>;