@dokebi/cli 0.2.5 → 0.4.0

package/dist/recipe-record.d.ts

@@ -0,0 +1,24 @@
+export declare const RECIPE_RECORD = ".dokebi/recipe.json";
+export interface RecordedAnswer {
+    readonly value: string;
+    readonly answeredBy: 'flag' | 'default' | 'recipe';
+    readonly defaultReason?: string;
+}
+export interface AppliedRecipe {
+    readonly recipe: string;
+    readonly appliedAt: string;
+    /** `user`: the user answered; `defaults`: the user left the choices to the agent. */
+    readonly answersFrom: 'user' | 'defaults';
+    readonly answers: Readonly<Record<string, RecordedAnswer>>;
+    /** What the user must know about the result (one line each). */
+    readonly notices: readonly string[];
+}
+/** The recipes recorded in the project; none when there is no record (or it is unreadable). */
+export declare function readAppliedRecipes(root: string): Promise<AppliedRecipe[]>;
+/** Records an applied recipe, replacing an earlier application of the same recipe. */
+export declare function saveAppliedRecipe(root: string, entry: AppliedRecipe): Promise<void>;
+/**
+ * The lines for the user's final message: each answer and who chose it (a default with its
+ * reason), then the notices. Answers fixed by the recipe itself are not choices and are left out.
+ */
+export declare function tellUserLines(recipes: readonly AppliedRecipe[]): string[];

package/dist/recipe-record.js

@@ -0,0 +1,67 @@
+// What a recipe chose, kept for the end of the work (AI-M03): `dokebi recipe` writes
+// `.dokebi/recipe.json` when it applied a recipe, and `dokebi verify` (the last command an agent
+// runs) returns the lines the agent must pass on to the user as `tellUser`: every answer with who
+// gave it (a default with its reason) and the notices, such as no CSRF protection for forms.
+// The file holds choice values and catalog texts only, never secrets.
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { debug, isMissing, reportError } from './diagnostics.js';
+export const RECIPE_RECORD = '.dokebi/recipe.json';
+/** The recipes recorded in the project; none when there is no record (or it is unreadable). */
+export async function readAppliedRecipes(root) {
+    let text;
+    try {
+        text = await readFile(join(root, RECIPE_RECORD), 'utf8');
+    }
+    catch (error) {
+        if (!isMissing(error))
+            reportError('RECIPE_RECORD_READ_FAILED', `Unable to read ${RECIPE_RECORD}`, error);
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed.version === 1 && Array.isArray(parsed.recipes))
+            return parsed.recipes.filter((entry) => typeof entry?.recipe === 'string' &&
+                entry.answers !== null &&
+                typeof entry.answers === 'object' &&
+                Array.isArray(entry.notices));
+        debug('Recipe record ignored: unexpected content', { file: RECIPE_RECORD });
+    }
+    catch (error) {
+        reportError('RECIPE_RECORD_INVALID', `${RECIPE_RECORD} is not valid JSON; ignoring it`, error);
+    }
+    return [];
+}
+/** Records an applied recipe, replacing an earlier application of the same recipe. */
+export async function saveAppliedRecipe(root, entry) {
+    const file = join(root, RECIPE_RECORD);
+    const recipes = [
+        ...(await readAppliedRecipes(root)).filter((item) => item.recipe !== entry.recipe),
+        entry,
+    ];
+    const record = { version: 1, recipes };
+    await mkdir(dirname(file), { recursive: true });
+    await rm(`${file}.tmp`, { force: true });
+    await writeFile(`${file}.tmp`, `${JSON.stringify(record, null, 2)}\n`);
+    await rename(`${file}.tmp`, file);
+    debug('Recipe record written', { recipe: entry.recipe, file: RECIPE_RECORD });
+}
+/**
+ * The lines for the user's final message: each answer and who chose it (a default with its
+ * reason), then the notices. Answers fixed by the recipe itself are not choices and are left out.
+ */
+export function tellUserLines(recipes) {
+    const lines = [];
+    for (const entry of recipes) {
+        const prefix = recipes.length > 1 ? `[${entry.recipe}] ` : '';
+        for (const [id, answer] of Object.entries(entry.answers)) {
+            if (answer.answeredBy === 'default')
+                lines.push(`${prefix}${id} = ${answer.value}: chosen by default (${answer.defaultReason ?? 'the recipe default'})`);
+            else if (answer.answeredBy === 'flag')
+                lines.push(`${prefix}${id} = ${answer.value}: ${entry.answersFrom === 'user' ? 'your answer' : 'chosen by the AI (you left the choice to it)'}`);
+        }
+        for (const notice of entry.notices)
+            lines.push(`${prefix}${notice}`);
+    }
+    return lines;
+}

package/dist/recipe.d.ts

@@ -0,0 +1,120 @@
+import { type CatalogOption } from './catalog.js';
+import { type NextStep, type Project } from './project.js';
+export interface RecipeRequest {
+    readonly name: string;
+    /** Project folder; created with init when it does not exist yet. Default: the current one. */
+    readonly dir?: string;
+    /** Answers by question id (view, db, devInfra, admin). */
+    readonly answers: Readonly<Record<string, string>>;
+    /** Fill unanswered questions with their defaults (only when the user delegated the choice). */
+    readonly defaults: boolean;
+    /**
+     * Where the answers came from (D-0065 §11): `user` — the user answered the questions;
+     * `defaults` — the user said to decide (same as `defaults`). Applying needs one of them.
+     */
+    readonly answersFrom?: 'user' | 'defaults';
+    readonly dryRun: boolean;
+    readonly port?: number;
+    readonly dbPort?: number;
+}
+export interface QuestionOption extends CatalogOption {
+    /** Programs of `needs` that were not found on PATH (devInfra docker, AI-M03); the user decides. */
+    readonly missingNeeds?: readonly string[];
+    /** What was found about this option on this machine, for the user. */
+    readonly note?: string;
+}
+export interface Question {
+    readonly id: string;
+    readonly flag: string;
+    readonly question: string;
+    readonly options: readonly QuestionOption[];
+    readonly default: string;
+    readonly defaultReason: string;
+    /** Asked only when another answer matches (devInfra: when db is not none). */
+    readonly when?: Readonly<Record<string, string>>;
+    readonly answer?: Answer;
+}
+export interface Answer {
+    readonly value: string;
+    readonly answeredBy: 'flag' | 'default' | 'recipe';
+    readonly defaultReason?: string;
+}
+export interface PlanStep {
+    readonly id: string;
+    /** The real command (run it yourself to do the same step). */
+    readonly command: string;
+    readonly why: string;
+}
+export interface Preflight {
+    readonly code: string;
+    readonly severity: 'error' | 'info';
+    readonly message: string;
+    readonly fix?: string;
+    /** PORT_IN_USE: a free port to propose to the user (pass it with the flag in `fix`). */
+    readonly alternative?: number;
+    /**
+     * PORT_IN_USE (AI-M03): the port is the user's call. True unless the user left the choices to
+     * the agent (--defaults / --answers-from defaults); `question` is what to ask, `next` what to do.
+     */
+    readonly waitForUser?: boolean;
+    readonly question?: string;
+    readonly next?: string;
+}
+export interface NeedsAnswers {
+    readonly status: 'needs-answers';
+    readonly recipe: string;
+    readonly summary: string;
+    readonly questions: readonly Question[];
+    readonly missing: readonly string[];
+    /** What to do now (D-0065 §11): ask, end the turn, and only then run the command. */
+    readonly next: string;
+    /** Always true: the agent's turn ends with the questions; nothing runs before the answers. */
+    readonly waitForUser: true;
+}
+/** The first sentence of `next` (and of the guide and AGENTS.md §1), word for word. */
+export declare const ASK_AND_WAIT = "Ask these questions and end your turn; do not run recipe/add/config until the user answers. Only use --defaults if the user said to decide.";
+export interface RecipeOutcome {
+    readonly status: 'planned' | 'applied';
+    readonly recipe: string;
+    readonly root: string;
+    readonly answers: Readonly<Record<string, Answer>>;
+    /** Where the answers came from (`--answers-from`, `--defaults`); null: not stated (dry run). */
+    readonly answersFrom: 'user' | 'defaults' | null;
+    /**
+     * Tell the user (one line each): the answers and who gave them, defaults with their reasons,
+     * and what the app does not protect (no CSRF protection for HTML forms, csrf is absent).
+     */
+    readonly report: string;
+    readonly plan: {
+        readonly steps: readonly PlanStep[];
+    };
+    readonly preflight: readonly Preflight[];
+    readonly completedSteps: readonly string[];
+    readonly skippedSteps: readonly string[];
+    readonly nextSteps: readonly NextStep[];
+    /**
+     * A dry run whose preflight found a taken port (AI-M03): true when the agent must ask the user
+     * before applying (`question`, `next`); false when the user left the choices to the agent.
+     */
+    readonly waitForUser?: boolean;
+    readonly question?: string;
+    readonly next?: string;
+}
+/** `dokebi recipe list`. */
+export declare function listRecipes(): Promise<{
+    recipes: {
+        name: string;
+        summary: string;
+        questions: string[];
+        match: string[];
+    }[];
+}>;
+/** The devInfra docker note when `docker` is not on PATH (the default stays; the user decides). */
+export declare const DOCKER_NOT_FOUND = "docker was not found on PATH: install and start Docker before applying with docker, or choose url (a database server you already have)";
+/**
+ * Runs a command in the project folder; a failure becomes STEP_COMMAND_FAILED with the bounded,
+ * redacted end of its output (`OutputTail` of npm-client).
+ */
+export declare function shell(root: string, command: string, args: string[], timeoutMs: number): Promise<void>;
+/** `dokebi recipe <name> …`. */
+export declare function runRecipe(request: RecipeRequest, project: Project): Promise<NeedsAnswers | RecipeOutcome>;