@ogygie/generate 0.0.0-stage → 0.20.0

package/dist/emit/screen/tests.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @intent Emits `<Ecran>.gen.test.tsx` (D20 for screens, D43): the test file of
+ * a screen follows the front target of the manifest — `emitScreenTests` picks
+ * the flavour, the spec block being the same on both. This file holds the
+ * JSDOM one: one test per behavior line of the spec, named by the line,
+ * rendering the CONTAINER under the front's test bench with a recording
+ * `fetch` stub — the consumed reads served from the fixtures, the state of the
+ * line arranged on the route it speaks of (pending, a server failure, an
+ * access refusal, the empty collection, the rows) — and asserting what the
+ * line says the screen renders: the skeleton, the error banner, the access
+ * explanation, the empty state, the rows and their order, a write sent with
+ * the valid input, the error sentences, nothing written, the save banner of a
+ * refused write. A custom view gets the test of its example: red until its
+ * body is written. A line carried by a hole is a todo. The `static-render`
+ * flavour — states in HTML, no gesture — is tests-static.ts.
+ */
+import type { ScreenPlan } from "../screen-plan.js";
+/** The test file of a screen on the front target the manifest declares (D43): the block is the same, only the tests change. */
+export declare function emitScreenTests(plan: ScreenPlan): string;

package/dist/emit/screen/views.d.ts

@@ -0,0 +1,10 @@
+import type { CustomViewPlan, FormViewPlan, ListViewPlan, ScreenPlan } from "../screen-plan.js";
+export declare function emitListView(plan: ScreenPlan, view: ListViewPlan): string;
+export declare function emitFormView(plan: ScreenPlan, view: FormViewPlan): string;
+/** The props of a custom view: the received fields of the output, and one MutationLike per action. */
+export declare function customViewPropsLines(view: CustomViewPlan): string[];
+/** The signature line of a custom view — what the markers protect and compare. */
+export declare function customViewSignature(view: CustomViewPlan): string;
+/** The imports a custom view's body needs — written between `// @hole-imports` markers, kept verbatim at regeneration: a body composes patterns and hooks the generator cannot foresee (astorg-ai-pdlc, lot 4 M3). */
+export declare function customImportsLines(view: CustomViewPlan, existing: string | null): string[];
+export declare function emitCustomView(plan: ScreenPlan, view: CustomViewPlan, existing: string | null): string;

package/dist/emit/screen/writes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @intent Emits `writes.gen.ts` of a screen (D42): one TanStack mutation hook
+ * per consumed WRITE, calling the route through `fetchContract` with a JSON
+ * body, and making stale — on success — the cache roots the manifest client
+ * derives for it: the route's own root and every root the map declares in
+ * `invalidates`. A keyed write takes its path parameters with its input.
+ */
+import type { ScreenPlan } from "../screen-plan.js";
+export declare function emitScreenWrites(plan: ScreenPlan): string;

package/dist/emit/screen-plan.d.ts

@@ -0,0 +1,187 @@
+import { type ConsumedRoute } from "../consumed-feature.js";
+import type { GuardDenial, GuardRegistry, FrontTarget } from "../manifest-generation.schema.js";
+import { type GenerationBlock, type HttpOperation } from "../generation-block.schema.js";
+import type { HttpOperationKind } from "../motif-catalog.js";
+import { type CustomView, type FormView, type ListView, type ScreenBlock, type ScreenHole } from "../screen-block.schema.js";
+import type { ParsedScreenBehavior } from "../screen-grammar.js";
+import { type FieldModel, type SchemaModels } from "../zod-introspection.js";
+export type { ConsumedRoute };
+export interface ConsumedFeatureInput {
+    featureId: string;
+    /** Null for a feature without a block: the screen reads its GET routes (D41 precision, lot 4 M3). */
+    block: GenerationBlock | null;
+    schemas: SchemaModels;
+    /** The feature's routes as the map declares them — where `invalidates` lives. */
+    routes: readonly ConsumedRoute[];
+}
+export interface BoundScreenBehaviorInput {
+    behavior: ParsedScreenBehavior;
+    status: "derivable" | "hole";
+}
+export interface ScreenPlanInput {
+    featureId: string;
+    /** Folder of the screen feature, relative to the repo root. */
+    folder: string;
+    /** Path of the front app, relative to the repo root. */
+    appPath: string;
+    specPath: string;
+    block: ScreenBlock;
+    consumed: readonly ConsumedFeatureInput[];
+    front: FrontTarget;
+    guards: GuardRegistry;
+    contractViolationCode: string;
+    generatorVersion: string;
+    behaviors: readonly BoundScreenBehaviorInput[];
+}
+/** One consumed operation, with what the screen emits for it: a hook, a key, its invalidations, its fixtures. */
+export interface ScreenOperationPlan {
+    featureId: string;
+    id: string;
+    pascalId: string;
+    kind: HttpOperationKind;
+    method: HttpOperation["method"];
+    path: string;
+    pathParameters: string[];
+    /** The cache root (first path segment) and the operation name the manifest client derives (D13). */
+    root: string;
+    clientOperation: string;
+    /** `useRatesListAll`. */
+    hookName: string;
+    /** The TypeScript literal of the cache key: `["rates", "list"]`, parameters and `input` as identifiers. */
+    keyLiteral: string;
+    /** Cache roots a successful write makes stale, as the manifest client derives them. */
+    invalidationRoots: string[];
+    inputSchema: string;
+    inputType: string;
+    inputModel: FieldModel;
+    outputSchema: string;
+    outputType: string;
+    outputModel: FieldModel;
+    /** A GET whose input carries fields beyond its path parameters sends them as a query string. */
+    hasQueryInput: boolean;
+    /** For a read (and a write that responds with one): the collection field of the output and its element. */
+    collection: {
+        field: string;
+        elementModel: FieldModel;
+    } | null;
+    /** The import specifier of the feature's schemas from the front (D43 `front.contracts`). */
+    contractsImport: string;
+    /** Refusals the guard of the operation declares — the 401 one is the access-denied fixture. */
+    guardDenials: readonly GuardDenial[];
+    /** The code and status of the first refusal the operation itself carries (motif, hole), for the refused-write fixture. */
+    refusal: {
+        code: string;
+        status: number;
+    } | null;
+    /** The valid input a form test sends: the schema's sample under the accept examples of the operation's holes (D23). */
+    validInput: Record<string, unknown>;
+    /** The served output fixtures: two distinct rows, and an empty collection, for a read. */
+    outputFixture: unknown;
+    emptyOutputFixture: unknown | null;
+}
+export interface ViewFieldPlan {
+    name: string;
+    model: FieldModel;
+    /** « Effective date » — the English source text of the header or label `<Trans>`. */
+    label: string;
+    align: "start" | "end";
+}
+export interface ListViewPlan {
+    kind: "list";
+    id: string;
+    componentName: string;
+    operation: ScreenOperationPlan;
+    /** The element type expression, e.g. `ListAllRatesOutput["publications"][number]`. */
+    rowType: string;
+    fields: ViewFieldPlan[];
+    rowKey: string;
+    sort: {
+        field: string;
+        direction: "asc" | "desc";
+    } | null;
+}
+export interface FormViewPlan {
+    kind: "form";
+    id: string;
+    componentName: string;
+    operation: ScreenOperationPlan;
+    /** `createMutation` — the body prop and the view prop carrying the write. */
+    mutationProp: string;
+    fields: ViewFieldPlan[];
+    multiline: string[];
+    /** « Create », « Import », « Save »… the submit label's source text. */
+    submitLabel: string;
+}
+export interface CustomViewPlan {
+    kind: "custom";
+    id: string;
+    componentName: string;
+    operation: ScreenOperationPlan;
+    hole: ScreenHole;
+    /** The output fields the view receives, with their models. */
+    receives: ViewFieldPlan[];
+    /** The writes the view may trigger. */
+    actions: Array<{
+        operation: ScreenOperationPlan;
+        mutationProp: string;
+    }>;
+    /** The output overlaid by the hole's example — what its test renders. */
+    exampleInput: unknown;
+}
+export type ViewPlan = ListViewPlan | FormViewPlan | CustomViewPlan;
+export interface ScreenBehaviorPlan {
+    raw: string;
+    behavior: ParsedScreenBehavior;
+    /** The view the line speaks of; null for « écran », the primary read. */
+    view: ViewPlan | null;
+    hole: string | null;
+}
+export interface ScreenPlan {
+    featureId: string;
+    pascalName: string;
+    camelName: string;
+    folder: string;
+    appPath: string;
+    specPath: string;
+    generatorVersion: string;
+    front: FrontTarget;
+    route: string | null;
+    /** `SaisieDesTauxScreen`, its body `SaisieDesTauxScreenBody`, the body props `SaisieDesTauxScreenBodyProps`, the route factory `saisieDesTauxRoute`. */
+    screenName: string;
+    bodyName: string;
+    propsName: string;
+    routeFactoryName: string;
+    /** The read the container's ScreenState waits for. */
+    primary: ListViewPlan | CustomViewPlan;
+    operations: ScreenOperationPlan[];
+    reads: ScreenOperationPlan[];
+    writes: ScreenOperationPlan[];
+    views: ViewPlan[];
+    behaviors: ScreenBehaviorPlan[];
+    /** Import path of the front test bench from the feature folder, and its export. */
+    testBench: {
+        exportName: string;
+        importPath: string;
+    };
+    /** Vite `?inline` import of the product's stylesheet from the feature folder — null when the front target names none. */
+    stylesheetImport: string | null;
+    /** The access-denied and internal-failure bodies the state tests serve. */
+    failures: {
+        denied: {
+            code: string;
+            status: number;
+            message: string;
+        };
+        internal: {
+            code: string;
+            status: number;
+            message: string;
+        };
+    };
+}
+/** `effectiveDate` → « Effective date » ; `csv` → « CSV » ; `ratePerUnit` → « Rate per unit ». */
+export declare function labelOf(fieldName: string): string;
+/** A distinct sample of a model at `variant`: uuids and dates differ by variant so two rows never share a key. */
+export declare function distinctSampleOf(model: FieldModel, variant: number): unknown;
+export declare function buildScreenPlan(input: ScreenPlanInput): ScreenPlan;
+export type { CustomView, FormView, ListView };

package/dist/emit/service.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @intent Emits `service.gen.ts`: the pipeline of every operation (D22, as
+ * precised on 2026-10-17, extended by D28). A read maps the repository's rows
+ * to the output schema — its element covering the resource, the slot arrays
+ * (one entry per slot key, null when unset), the reference counts, the values
+ * of the view holes — then hands the output to its project holes (D32); a
+ * create runs its validate holes in declared order, the first refusal winning
+ * as the operation's 400, its derive holes, then the motif's insert; an update,
+ * a setOrClear and a delete load the row by key (404 otherwise) and write
+ * through the repository; a write that `respondsWith` a read serves that read
+ * after writing (D30); every write of a signed resource carries who and when
+ * (D31). An import checks the envelope's byte size, runs the transform hole,
+ * then validates every line before the all-or-nothing write. Pure functions:
+ * the context carrying the db and the clock are injected; a hole receives the
+ * effects it declared and nothing else.
+ */
+import type { FeaturePlan } from "./plan.js";
+export declare function emitService(plan: FeaturePlan): string;

package/dist/emit/spec-contracts.d.ts

@@ -0,0 +1,27 @@
+import type { FeaturePlan, OperationPlan } from "./plan.js";
+export declare const CONTRACTS_SECTION_TITLE = "Contrats de donn\u00E9es";
+export declare const SPEC_GENERATED_END = "<!-- @generated:end -->";
+export declare function specGeneratedStart(version: string): string;
+export interface SpecGeneratedBlock {
+    version: string;
+    /** The lines between the markers, without the markers. */
+    content: string;
+    /** Offsets of the whole block in the markdown, markers included. */
+    start: number;
+    end: number;
+}
+/** The generated block of a spec, wherever its markers stand — null without both markers in order. */
+export declare function extractSpecContracts(markdown: string): SpecGeneratedBlock | null;
+/** Every structured refusal a route may answer, code → status, in a stable order. */
+export declare function refusalsOf(operation: OperationPlan, plan: FeaturePlan): Array<[string, number]>;
+/** The lines between the markers — the content `verify` compares. */
+export declare function emitSpecContracts(plan: FeaturePlan): string;
+export interface ApplySpecContractsResult {
+    markdown: string;
+    /** `inserted` at the end of the section, `replaced` between existing markers, or nothing to do. */
+    outcome: "inserted" | "replaced" | "unchanged" | "section-missing";
+}
+/** The spec with its generated block in place — the markers found are replaced, otherwise the block closes the section. */
+export declare function applySpecContracts(markdown: string, plan: FeaturePlan): ApplySpecContractsResult;
+/** Writes a generated block — a feature's or a screen's (D41) — between the markers of `# Contrats de données`: replaced when the markers exist, appended to the section otherwise. */
+export declare function applyGeneratedContracts(markdown: string, content: string, version: string): ApplySpecContractsResult;

package/dist/emit/tests.d.ts

@@ -0,0 +1,3 @@
+import type { FeaturePlan } from "./plan.js";
+export declare function emitContractTests(plan: FeaturePlan): string;
+export declare function emitBehaviorTests(plan: FeaturePlan): string;

package/dist/fill/body.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @intent The text mechanics of filling a hole (D23, D24): put a body between
+ * the markers of `logic.ts` without touching anything else; read a body out of
+ * what a model answered (fences, a repeated signature, a stray closing brace
+ * stripped); refuse a body that carries what the repo bans before any test
+ * runs — the bans of AGENTS.md, plus what a pure hole may not reach (the
+ * clock it did not declare, a network, a process, a module). Pure functions,
+ * proven in memory.
+ */
+/** `logic.ts` with the body of one hole replaced — the signature, the markers and every other line kept byte for byte. */
+export declare function replaceHoleBody(logic: string, holeId: string, body: string): string;
+/** Whether a section's body is still the generator's `todo`. */
+export declare function isTodoBody(body: string, holeId: string): boolean;
+/**
+ * The body in a model's answer: the first fenced block when there is one, a
+ * repeated signature dropped up to its opening brace, a closing brace that
+ * would close the function dropped, two-space indentation restored.
+ */
+export declare function extractCandidateBody(answer: string): string;
+export interface BodyBan {
+    pattern: RegExp;
+    rule: string;
+}
+export declare const BODY_BANS: readonly BodyBan[];
+/** The rules a body breaks — empty when it may be tested. */
+export declare function forbiddenInBody(body: string): string[];

package/dist/fill/fill.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @intent The filling of a hole (DECISIONS.md D24): library, then
+ * draw-and-verify, then escalation, then the human — the FIRST GREEN WINS. A
+ * candidate body is written between the hole's markers, run against the
+ * hole's pure test in a process that holds no secret, checked against the
+ * repo's bans; a red one is thrown away and the body goes back to `todo`. A
+ * retained body enters the library with its provenance. Nothing here reads a
+ * disk or calls a model: every effect is injected, so the whole decision is
+ * proven in memory and the real effects (vitest in a subprocess, the Messages
+ * client of the core) stay in the command.
+ *
+ * The threshold of D24 is counted, not enforced: a feature whose holes reach
+ * escalation more than one in ten is said to have holes too big for a model —
+ * the spec splits them, nobody raises a model.
+ */
+import type { FeaturePlan, HolePlan } from "../emit/plan.js";
+import { type HoleLibraryEntry, type HoleProvenance } from "../hole-shape.js";
+export type FillPath = HoleProvenance["path"];
+export interface Candidate {
+    body: string;
+    /** Where it came from — the library entry, or the model that drew it. */
+    origin: string;
+    model: string | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    } | null;
+}
+export interface FillOptions {
+    /** Candidates per draw round (D24: 5). */
+    candidates: number;
+    /** Draw rounds before escalation (D24: 2). */
+    rounds: number;
+    /** Library and shape neighbours only: no model is ever called. */
+    libraryOnly: boolean;
+}
+export declare const DEFAULT_FILL_OPTIONS: FillOptions;
+export interface FillDeps {
+    /** Writes a body between the hole's markers (or `todo` back). */
+    writeBody(holeId: string, body: string | null): Promise<void>;
+    /** Runs the hole's pure test with the body currently written; green or not, and what the runner said. */
+    runHoleTest(holeId: string): Promise<{
+        green: boolean;
+        lines: string[];
+    }>;
+    /** `n` candidates from the draw model on the hole's context, in parallel. */
+    draw(context: string, n: number, round: number): Promise<Candidate[]>;
+    /** One candidate from the escalation model. */
+    escalate(context: string): Promise<Candidate>;
+    recordLibrary(entry: HoleLibraryEntry): Promise<void>;
+    /** ISO date of today — the provenance carries it. */
+    today(): string;
+    repo: string;
+    log(line: string): void;
+}
+export interface HoleFillInput {
+    hole: HolePlan;
+    plan: FeaturePlan;
+    /** `holes/<id>.gen.md`, the one context a model gets. */
+    context: string;
+    /** What logic.ts holds for this hole now. */
+    currentBody: string;
+    library: readonly HoleLibraryEntry[];
+}
+export interface HoleFillResult {
+    holeId: string;
+    outcome: FillPath | "already-filled";
+    /** Candidates tried, library included. */
+    tried: number;
+    /** Candidates the bans rejected before any test. */
+    banned: number;
+    model: string | null;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        model: string;
+    }[];
+    /** The runner's last lines when nothing was green — what a human reads first. */
+    lastRun: string[];
+}
+/** Fills ONE hole along D24's order; the body ends written (green) or back to `todo`. */
+export declare function fillHole(input: HoleFillInput, deps: FillDeps, options?: FillOptions): Promise<HoleFillResult>;
+export interface FeatureFillSummary {
+    featureId: string;
+    results: HoleFillResult[];
+    filled: number;
+    unfilled: number;
+    /** D24: more than one hole in ten reached escalation — the holes are too big, the spec splits them. */
+    holesTooBig: boolean;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+        model: string;
+    }[];
+}
+/** Fills every `todo` hole of a feature, one after the other (one logic.ts, one test file). */
+export declare function fillFeature(inputs: readonly HoleFillInput[], deps: FillDeps, options?: FillOptions): Promise<FeatureFillSummary>;

package/dist/fill/model-draw.d.ts

@@ -0,0 +1,25 @@
+/**
+ * @intent The model half of the filling (D24): the `draw` and `escalate`
+ * models asked for a body on the SOLE `holes/<id>.gen.md` — the one context
+ * D23 allows — through the core's shared Messages client. The models are the
+ * package's single configuration (`models: { spec, escalate, draw }`), with
+ * D24's defaults, overridable by the command's flags; `draw` may name a local
+ * Ollama model behind an OpenAI-compatible base, which is the operator's
+ * call, not this module's.
+ */
+import type { ModelClient } from "@ogygie/core/model";
+import type { Candidate } from "./fill.js";
+export interface FillModels {
+    spec: string;
+    escalate: string;
+    draw: string;
+}
+/** D24's defaults. */
+export declare const DEFAULT_FILL_MODELS: FillModels;
+/** The stable instructions — cached by the model side; the hole's context is the user turn. */
+export declare const HOLE_SYSTEM_PROMPT: string;
+export interface ModelDrawer {
+    draw(context: string, n: number, round: number): Promise<Candidate[]>;
+    escalate(context: string): Promise<Candidate>;
+}
+export declare function createModelDrawer(client: ModelClient, models?: FillModels): ModelDrawer;

package/dist/generate-feature.d.ts

@@ -0,0 +1,23 @@
+import type { HoleLibraryEntry } from "./hole-shape.js";
+import type { FeaturePlan } from "./emit/plan.js";
+export interface GeneratedFile {
+    /** Repo-relative path. */
+    path: string;
+    content: string;
+}
+export interface GenerateOptions {
+    /** The repo's current logic.ts, whose bodies survive when their signature is unchanged. */
+    existingLogic: string | null;
+    /** The repo's current migration of the feature, whose view bodies (D32) survive between their markers. */
+    existingMigration?: string | null;
+    /** The holes library: neighbours of the same shape in every holes/<id>.gen.md. */
+    library: readonly HoleLibraryEntry[];
+}
+/** File names, relative to the feature folder, every generated feature carries (besides its migration and logic.ts). */
+export declare const GENERATED_FEATURE_FILES: readonly ["db.schema.gen.ts", "holes.runtime.gen.ts", "repository.gen.ts", "service.gen.ts", "routes.gen.ts", "index.ts", "factories.gen.ts", "routes.gen.test.ts", "behaviors.gen.test.ts", "holes.gen.test.ts"];
+export declare function generateFeature(plan: FeaturePlan, options?: GenerateOptions): GeneratedFile[];
+/**
+ * The migration file of a table: the one already there (`<n>_<table>.gen.sql`),
+ * or the next number after the existing migrations — stable across regenerations.
+ */
+export declare function migrationFileNameFor(existingFileNames: readonly string[], table: string): string;

package/dist/generate-screen.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @intent The deterministic half of a SCREEN generation (DECISIONS.md D40,
+ * D41, D43): from a screen plan, the list of files to write — path and
+ * content — in a fixed order, byte-identical for identical inputs. A custom
+ * view is regenerated AROUND its body (kept while its signature is unchanged);
+ * the BODY of the screen is not here: `screenBodyDefault` is written once by
+ * the generate command when the file is absent, and never compared (D40).
+ */
+import type { GeneratedFile } from "./generate-feature.js";
+import type { ScreenPlan } from "./emit/screen-plan.js";
+export interface GenerateScreenOptions {
+    /** The repo's current `views/<Vue>.tsx` of each custom view, by view id — whose body survives when its signature is unchanged. */
+    existingCustomViews: ReadonlyMap<string, string | null>;
+}
+/** The path of the written body of a screen, relative to the repo root. */
+export declare function screenBodyPath(plan: ScreenPlan): string;
+/** The written body, as the generator proposes it the first time (D40). */
+export declare function screenBodyDefault(plan: ScreenPlan): string;
+export declare function generateScreen(plan: ScreenPlan, options?: GenerateScreenOptions): GeneratedFile[];