`prompts`

Purpose

Runs the plugin's optional prompts stage and validates the answers against the schema the plugin returns. This is where --answers <file> flows in (via answersFromFile) and where --no-interactive is enforced. Validation failures surface as INSTALLER.PROMPT_VALIDATION_FAILED with the underlying Zod (or other compatible) error attached as cause and field-level issues attached as context.issues.

Features

Accepts both explicit answers (programmatic harness) and answersFromFile (loaded from a JSON file by the bin).
Fails fast under noInteractive when a plugin demands answers that weren't pre-supplied — prevents silent prompts in CI.
No-op when the plugin omits prompts — explicit answers pass through, otherwise an empty {} is supplied to plan. Plugins that need answers must declare a schema.
Wrapped in OTel span installer.prompts so prompt validation timing is observable.

Basic Example

import { runPrompts } from "@suaveplan/installer";
import z from "zod";

const schema = z.object({ name: z.string().min(1) });
const plugin = {
    id: "demo",
    version: "0.1.0",
    prompts: () => schema,
    plan: async () => [],
    apply: async () => undefined,
};
const answers = await runPrompts({
    plugin,
    ctx,
    explicitAnswers: { name: "alice" },
});

Advanced Example

import { runPrompts, InstallerError } from "@suaveplan/installer";

try {
    const answers = await runPrompts({
        plugin,
        ctx,
        answersFromFile: JSON.parse(await fileContent),
    });
    // ... pass to plan
} catch (err) {
    if (
        err instanceof InstallerError &&
        err.code === "INSTALLER.PROMPT_VALIDATION_FAILED"
    ) {
        const issues = err.context?.["issues"];
        console.error("Invalid answers:", issues);
        process.exit(2);
    }
    throw err;
}

API Reference

runPrompts<TAnswers>(options): Promise<TAnswers>
interface RunPromptsOptions<TAnswers> — { plugin, ctx, explicitAnswers?, answersFromFile? }.
Errors: INSTALLER.PROMPT_VALIDATION_FAILED for missing answers, validation failures, or non-interactive without answers.

Implementation Notes

explicitAnswers is preferred over answersFromFile when both are supplied — the testing harness uses explicitAnswers and we want it to take precedence when callers also pass a file. safeParse is used instead of parse so the host can attach the Zod issues as structured context rather than letting them bubble as raw ZodError. The schema returned by plugin.prompts is treated structurally (PromptSchema<T>), not nominally — any object with parse and safeParse is acceptable, which lets plugins swap validators without breaking the host contract.

2.7 KiB Raw Blame History

prompts