@ambitresearch/genie 1.3.1

package/dist/llm/schema.js

@@ -0,0 +1,147 @@
+/**
+ * `COMPONENT_SCHEMA` (M2-02) — the JSON Schema `conjure`/`refine` (M2-03/M2-04)
+ * demand from the model via `response_format: { type: "json_schema",
+ * json_schema: COMPONENT_SCHEMA }`, and that M2-07's Ajv validation pass
+ * (`validateComponent`) compiles against.
+ *
+ * Draft 7 only (AC2): no `anyOf`/`oneOf` discriminator pattern, and the only
+ * `$ref` in the whole schema is a single level deep (`manifestEntry.viewport`
+ * → `#/definitions/Viewport`, mirroring the RFC §9.20 shared-`$defs` shape).
+ * LiteLLM's structured-output passthrough to Anthropic (via tool-use) is the
+ * reason to keep nesting shallow — a deep `$ref` chain is exactly the shape
+ * that passthrough has been observed not to handle reliably.
+ *
+ * `as const satisfies JSONSchema7` (AC1) does two jobs at once: `satisfies`
+ * runs the object through `@types/json-schema`'s `JSONSchema7` shape so a
+ * typo'd keyword (e.g. `additionalProperty` instead of `additionalProperties`)
+ * is a compile error, while `as const` preserves the literal types `FromSchema`
+ * (AC7) needs to actually infer `ValidatedComponent` below rather than widening
+ * every string field to `string`.
+ */
+/**
+ * AC4 — every `files[].path` must land under `components/<group>/<Name>/`,
+ * matching the on-disk layout `write_files` (M1-08) ultimately writes to and
+ * the `@genie`-marker registration convention (D-A/D-B). `<group>` is
+ * `[a-z0-9-]+` (kebab-case, same shape as the top-level `group` field);
+ * `<Name>` is `[A-Z][A-Za-z0-9]+` (PascalCase, same shape as `componentName`);
+ * the file's own basename allows the broader `[A-Za-z0-9._-]+` (AC4's own
+ * pattern) since it must cover `<Name>.tsx`, `<Name>.d.ts`, `<Name>.prompt.md`,
+ * `<Name>.html`, and `meta.json` — five different suffix shapes — rather than
+ * repeating `<Name>` a second time in the basename segment.
+ */
+const PATH_PATTERN = "^components/[a-z0-9-]+/[A-Z][A-Za-z0-9]+/[A-Za-z0-9._-]+$";
+/**
+ * AC5 — at least one `files[]` entry must be a `<Name>.html` file (the
+ * `@genie`-marker carrier M3-01 later validates post-hoc). `contains` is the
+ * Draft-7 keyword for "at least one array item matches this sub-schema" — it
+ * does not require every item to match, unlike `items`. The pattern captures
+ * the directory's `<Name>` segment and backreferences it against the
+ * filename (`([A-Z][A-Za-z0-9]+)/\1\.html$`), so `Button/Button.html`
+ * matches but a mismatched `Button/Wrong.html` does not — enforcing the same
+ * `<Name>/<Name>.html` self-consistency the RFC's file-layout convention
+ * assumes throughout (§7.3/§7.4/§9.10). It deliberately does NOT also check
+ * the file's `content` for the literal `@genie` marker text — that
+ * cross-field, regex-on-a-sibling-field check is exactly what M2-07's
+ * `validateComponent` does as a second pass after schema validation (this
+ * issue's AC5 note: "validated post-hoc by M3-01, not by the schema").
+ */
+const HTML_FILE_CONTAINS = {
+    type: "object",
+    properties: {
+        path: {
+            type: "string",
+            pattern: "^components/[a-z0-9-]+/([A-Z][A-Za-z0-9]{1,63})/\\1\\.html$",
+        },
+    },
+};
+export const COMPONENT_SCHEMA = {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    $id: "https://genie.dev/schema/component.schema.json",
+    title: "GenieComponent",
+    description: "The file set + manifest metadata conjure/refine demand from the configured " +
+        "LLM endpoint via response_format.json_schema (M2-02).",
+    type: "object",
+    additionalProperties: false,
+    // AC3 — top-level shape: { componentName, group, files, manifestEntry }.
+    required: ["componentName", "group", "files", "manifestEntry"],
+    // The only $ref in this schema, one level deep (AC2) — mirrors the shared
+    // `Viewport` $def in RFC §9.20 rather than inlining width/height twice.
+    definitions: {
+        Viewport: {
+            type: "object",
+            additionalProperties: false,
+            required: ["width", "height"],
+            properties: {
+                width: { type: "integer", minimum: 1, maximum: 4096 },
+                height: { type: "integer", minimum: 1, maximum: 4096 },
+            },
+        },
+    },
+    properties: {
+        componentName: {
+            type: "string",
+            description: 'PascalCase component name, e.g. "Button".',
+            // Same shape as the equivalent `name` field in RFC §7.1/§7.5
+            // (manifest.json cards / the RFC's own COMPONENT_SCHEMA draft) — a
+            // 2-64 char PascalCase identifier. Minimum length is 2 (not 1) so a
+            // single-letter name like "B" cannot slip past `componentName` only to
+            // be trapped later by the `files[].path` pattern's `[A-Z][A-Za-z0-9]+`
+            // `<Name>` segment (which itself requires min length 2) — the two
+            // constraints move together.
+            pattern: "^[A-Z][A-Za-z0-9]{1,63}$",
+        },
+        group: {
+            type: "string",
+            description: 'Kebab-case UI-kit group/category, e.g. "actions".',
+            pattern: "^[a-z0-9-]{1,32}$",
+        },
+        files: {
+            type: "array",
+            description: "The component's file set (e.g. <Name>.jsx, <Name>.tsx, <Name>.d.ts, " +
+                "<Name>.prompt.md, <Name>.html, meta.json) — at least one must be a " +
+                "<Name>.html preview file (AC5).",
+            minItems: 1,
+            maxItems: 12,
+            contains: HTML_FILE_CONTAINS,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["path", "content", "mimeType"],
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Kit-relative path under components/<group>/<Name>/.",
+                        pattern: PATH_PATTERN,
+                    },
+                    content: {
+                        type: "string",
+                        description: "Full file contents (AC5: an <Name>.html entry's content " +
+                            "must begin with the @genie marker — checked post-hoc by M3-01/M2-07, " +
+                            "not by this schema).",
+                        minLength: 1,
+                        maxLength: 65536,
+                    },
+                    mimeType: {
+                        type: "string",
+                        description: 'MIME type of `content`, e.g. "text/html".',
+                        pattern: "^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]*$",
+                    },
+                },
+            },
+        },
+        manifestEntry: {
+            type: "object",
+            description: "Metadata the manifest compiler (M3-03) needs to add this card to " +
+                ".genie/manifest.json without re-deriving it from the files themselves.",
+            additionalProperties: false,
+            // AC6 — viewport is required; subtitle/tags are optional.
+            required: ["viewport"],
+            properties: {
+                viewport: { $ref: "#/definitions/Viewport" },
+                subtitle: { type: "string", maxLength: 256 },
+                tags: { type: "array", items: { type: "string" }, maxItems: 16 },
+            },
+        },
+    },
+};
+//# sourceMappingURL=schema.js.map

package/dist/llm/schema.js.map

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

package/dist/llm/validate.d.ts

@@ -0,0 +1,107 @@
+/**
+ * M2-07 — strict Ajv validation for the structured LLM output that conjure
+ * (M2-03) and refine (M2-04) receive from the configured OpenAI-compatible
+ * endpoint via `response_format: { type: "json_schema", ... }`.
+ *
+ * The single public entry point is {@link validateComponent}. It's called
+ * once per LLM completion, on the deserialised JSON payload the client got
+ * back. On success it returns the payload typed as {@link ValidatedComponent}
+ * (a compile-time re-typing — no reshape at runtime). On failure it throws
+ * {@link SchemaValidationError} carrying the full Ajv `errors: ErrorObject[]`
+ * so the retry path in M2-03/M2-04 can append the failure to the next prompt
+ * and give the model exactly one chance to self-correct.
+ *
+ * Two-pass design (AC3 + AC4):
+ *   1. Ajv strict-mode structural validation against `COMPONENT_SCHEMA`
+ *      (M2-02). Catches missing fields, wrong types, bad path patterns, the
+ *      "no <Name>.html preview" case, and the `manifestEntry.viewport`
+ *      requirement.
+ *   2. `@genie` first-line marker cross-check on every `<Name>/<Name>.html`
+ *      preview file the (now shape-valid) payload contains. This is
+ *      intentionally *not* modelled in the JSON Schema itself — a regex-on-a-
+ *      sibling-field is exactly the kind of cross-field constraint Draft 7
+ *      can't express, and pushing it into JSON Schema would force the same
+ *      shallow-`$ref` shape M2-02 was carefully written to avoid (see
+ *      `schema.ts` AC2 note).
+ *
+ * The schema is compiled exactly once, at module load (AC5) — Ajv compilation
+ * is measurable per call and every LLM completion goes through this function,
+ * so caching pays for itself immediately.
+ */
+import { type ErrorObject } from "ajv";
+import { type ValidatedComponent } from "./schema.js";
+export type { ValidatedComponent } from "./schema.js";
+export type { ErrorObject } from "ajv";
+/**
+ * AC4 — the canonical `@genie` first-line marker regex from
+ * Every generated `<Name>.html` preview
+ * must open with a comment matching this pattern so the manifest compiler
+ * (M3-03) and the validate tool (M3-04) can register / verify the card
+ * without re-parsing the component's JSX.
+ *
+ * M3-01 (DRO-257) landed the single source of truth for this pattern at
+ * `packages/server/src/validate/marker.ts`'s `MARKER_REGEX`, imported here
+ * via the `validate/index.ts` public barrel (Copilot review, PR #142) rather
+ * than reaching into `marker.js` directly, so this call site tracks the
+ * barrel's stable surface instead of the module's internal file layout.
+ * This is now a re-export alias, kept under its original M2-07 name for
+ * backwards compatibility with existing consumers (this module's own
+ * cross-check below, plus `packages/e2e/test/m2-generation.test.ts`) rather
+ * than forcing every call site to rename in the same change that removes
+ * the duplicate literal.
+ */
+export declare const MARKER_REGEX_M2_07: RegExp;
+/**
+ * Same selector as `COMPONENT_SCHEMA.properties.files.items.contains.pattern`
+ * — the `<group>/<Name>/<Name>.html` self-consistency shape ("preview file
+ * whose basename matches its containing directory"). Kept here as a compiled
+ * `RegExp` so the cross-check pass in {@link validateComponent} doesn't
+ * re-compile the pattern on every file iteration.
+ *
+ * The backreference `\1` locks the basename to the same PascalCase segment
+ * as the enclosing directory — this is what makes `Button/Wrong.html` fail
+ * schema-level AC5 but still lets `Button/Button.html` through. We reuse the
+ * exact shape here so the schema's `contains` guarantee (at least one file
+ * matches) and this cross-check (every matching file also has the `@genie`
+ * marker) can never disagree about which files are "preview files".
+ *
+ * Exported (Copilot review, PR #136) so consumers outside this module that
+ * need to identify "which files are actually preview files" — e.g.
+ * `m2-generation.test.ts`'s AC5 assertions — share this exact definition
+ * instead of re-deriving a looser one (`files[].path` also legally permits
+ * non-preview `.html` basenames like `dark-mode.html` per `schema.ts`'s
+ * `PATH_PATTERN`, which a naive `.endsWith(".html")` filter would wrongly
+ * subject to the marker rule).
+ */
+export declare const NAMED_HTML_PATH: RegExp;
+/**
+ * `Error` subclass thrown by {@link validateComponent} on structural or
+ * marker-cross-check failure. Callers in M2-03/M2-04 catch this narrowly and
+ * append `error.errors` to the next prompt — the retry loop is exactly one
+ * round-trip, per DRO-254's "Out of Scope: auto-repair" note.
+ *
+ * `name` is set explicitly so `error.name === "SchemaValidationError"` works
+ * even after ESM module boundaries strip the class identity (defensive
+ * against `instanceof` foot-guns in vitest / workers).
+ */
+export declare class SchemaValidationError extends Error {
+    /** Ajv-style structured errors; always non-empty when this is thrown. */
+    readonly errors: ErrorObject[];
+    constructor(message: string, errors: ErrorObject[]);
+}
+/**
+ * AC1 — the module's sole export contract. Validates `output` against
+ * `COMPONENT_SCHEMA` (M2-02) and the `@genie` marker convention (AC4). On
+ * success returns `output` cast to {@link ValidatedComponent} — an assertion
+ * of type, not a copy: callers get the exact same object identity back so
+ * downstream `write_files` (M1-08) can pass it through without an extra
+ * allocation per completion.
+ *
+ * @throws {SchemaValidationError} on any structural or marker failure. The
+ *   thrown error's `errors` array holds Ajv `ErrorObject`s (schema-level
+ *   failures) and/or synthetic `ErrorObject`s with `keyword: "@genie-marker"`
+ *   (marker-level failures). Both live in the same array so M2-03/M2-04's
+ *   retry prompt can serialise them uniformly.
+ */
+export declare function validateComponent(output: unknown): ValidatedComponent;
+//# sourceMappingURL=validate.d.ts.map

package/dist/llm/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/llm/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAO,KAAK,WAAW,EAAyB,MAAM,KAAK,CAAC;AAEnE,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGxE,YAAY,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACtD,YAAY,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,kBAAkB,QAAe,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,QAAiE,CAAC;AAE9F;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,WAAW,EAAE,CAAC;gBAEnB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE;CAKnD;AAgBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,OAAO,GAAG,kBAAkB,CAkErE"}

package/dist/llm/validate.js

@@ -0,0 +1,174 @@
+/**
+ * M2-07 — strict Ajv validation for the structured LLM output that conjure
+ * (M2-03) and refine (M2-04) receive from the configured OpenAI-compatible
+ * endpoint via `response_format: { type: "json_schema", ... }`.
+ *
+ * The single public entry point is {@link validateComponent}. It's called
+ * once per LLM completion, on the deserialised JSON payload the client got
+ * back. On success it returns the payload typed as {@link ValidatedComponent}
+ * (a compile-time re-typing — no reshape at runtime). On failure it throws
+ * {@link SchemaValidationError} carrying the full Ajv `errors: ErrorObject[]`
+ * so the retry path in M2-03/M2-04 can append the failure to the next prompt
+ * and give the model exactly one chance to self-correct.
+ *
+ * Two-pass design (AC3 + AC4):
+ *   1. Ajv strict-mode structural validation against `COMPONENT_SCHEMA`
+ *      (M2-02). Catches missing fields, wrong types, bad path patterns, the
+ *      "no <Name>.html preview" case, and the `manifestEntry.viewport`
+ *      requirement.
+ *   2. `@genie` first-line marker cross-check on every `<Name>/<Name>.html`
+ *      preview file the (now shape-valid) payload contains. This is
+ *      intentionally *not* modelled in the JSON Schema itself — a regex-on-a-
+ *      sibling-field is exactly the kind of cross-field constraint Draft 7
+ *      can't express, and pushing it into JSON Schema would force the same
+ *      shallow-`$ref` shape M2-02 was carefully written to avoid (see
+ *      `schema.ts` AC2 note).
+ *
+ * The schema is compiled exactly once, at module load (AC5) — Ajv compilation
+ * is measurable per call and every LLM completion goes through this function,
+ * so caching pays for itself immediately.
+ */
+import { Ajv } from "ajv";
+import { COMPONENT_SCHEMA } from "./schema.js";
+import { MARKER_REGEX } from "../validate/index.js";
+/**
+ * AC4 — the canonical `@genie` first-line marker regex from
+ * Every generated `<Name>.html` preview
+ * must open with a comment matching this pattern so the manifest compiler
+ * (M3-03) and the validate tool (M3-04) can register / verify the card
+ * without re-parsing the component's JSX.
+ *
+ * M3-01 (DRO-257) landed the single source of truth for this pattern at
+ * `packages/server/src/validate/marker.ts`'s `MARKER_REGEX`, imported here
+ * via the `validate/index.ts` public barrel (Copilot review, PR #142) rather
+ * than reaching into `marker.js` directly, so this call site tracks the
+ * barrel's stable surface instead of the module's internal file layout.
+ * This is now a re-export alias, kept under its original M2-07 name for
+ * backwards compatibility with existing consumers (this module's own
+ * cross-check below, plus `packages/e2e/test/m2-generation.test.ts`) rather
+ * than forcing every call site to rename in the same change that removes
+ * the duplicate literal.
+ */
+export const MARKER_REGEX_M2_07 = MARKER_REGEX;
+/**
+ * Same selector as `COMPONENT_SCHEMA.properties.files.items.contains.pattern`
+ * — the `<group>/<Name>/<Name>.html` self-consistency shape ("preview file
+ * whose basename matches its containing directory"). Kept here as a compiled
+ * `RegExp` so the cross-check pass in {@link validateComponent} doesn't
+ * re-compile the pattern on every file iteration.
+ *
+ * The backreference `\1` locks the basename to the same PascalCase segment
+ * as the enclosing directory — this is what makes `Button/Wrong.html` fail
+ * schema-level AC5 but still lets `Button/Button.html` through. We reuse the
+ * exact shape here so the schema's `contains` guarantee (at least one file
+ * matches) and this cross-check (every matching file also has the `@genie`
+ * marker) can never disagree about which files are "preview files".
+ *
+ * Exported (Copilot review, PR #136) so consumers outside this module that
+ * need to identify "which files are actually preview files" — e.g.
+ * `m2-generation.test.ts`'s AC5 assertions — share this exact definition
+ * instead of re-deriving a looser one (`files[].path` also legally permits
+ * non-preview `.html` basenames like `dark-mode.html` per `schema.ts`'s
+ * `PATH_PATTERN`, which a naive `.endsWith(".html")` filter would wrongly
+ * subject to the marker rule).
+ */
+export const NAMED_HTML_PATH = /^components\/[a-z0-9-]+\/([A-Z][A-Za-z0-9]{1,63})\/\1\.html$/;
+/**
+ * `Error` subclass thrown by {@link validateComponent} on structural or
+ * marker-cross-check failure. Callers in M2-03/M2-04 catch this narrowly and
+ * append `error.errors` to the next prompt — the retry loop is exactly one
+ * round-trip, per DRO-254's "Out of Scope: auto-repair" note.
+ *
+ * `name` is set explicitly so `error.name === "SchemaValidationError"` works
+ * even after ESM module boundaries strip the class identity (defensive
+ * against `instanceof` foot-guns in vitest / workers).
+ */
+export class SchemaValidationError extends Error {
+    /** Ajv-style structured errors; always non-empty when this is thrown. */
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.name = "SchemaValidationError";
+        this.errors = errors;
+    }
+}
+/**
+ * AC2 + AC5 — one Ajv instance, compiled once, at module load. The `strict:
+ * true` flag turns every unknown/ambiguous keyword into a *compile-time*
+ * throw, so if `schema.ts` ever grows a typo (e.g. `additionalProperty`
+ * instead of `additionalProperties`) the server refuses to boot rather than
+ * silently letting malformed output through at runtime. `allErrors: true`
+ * asks Ajv to keep validating past the first failure and return every
+ * problem — critical for the "append failures to the prompt" retry loop,
+ * which can only fix errors the model actually sees.
+ */
+const ajv = new Ajv({ strict: true, allErrors: true });
+const validate = ajv.compile(COMPONENT_SCHEMA);
+/**
+ * AC1 — the module's sole export contract. Validates `output` against
+ * `COMPONENT_SCHEMA` (M2-02) and the `@genie` marker convention (AC4). On
+ * success returns `output` cast to {@link ValidatedComponent} — an assertion
+ * of type, not a copy: callers get the exact same object identity back so
+ * downstream `write_files` (M1-08) can pass it through without an extra
+ * allocation per completion.
+ *
+ * @throws {SchemaValidationError} on any structural or marker failure. The
+ *   thrown error's `errors` array holds Ajv `ErrorObject`s (schema-level
+ *   failures) and/or synthetic `ErrorObject`s with `keyword: "@genie-marker"`
+ *   (marker-level failures). Both live in the same array so M2-03/M2-04's
+ *   retry prompt can serialise them uniformly.
+ */
+export function validateComponent(output) {
+    // Pass 1 — Ajv structural validation. `validate` mutates `.errors` on the
+    // ValidateFunction itself (Ajv's API quirk); snapshot into a local so a
+    // concurrent second call from another async caller can't clobber it before
+    // we've thrown.
+    if (!validate(output)) {
+        const errors = validate.errors ?? [];
+        throw new SchemaValidationError(`LLM output failed COMPONENT_SCHEMA validation (${errors.length} error${errors.length === 1 ? "" : "s"}).`, 
+        // Defensive copy — a caller inspecting `.errors` shouldn't be able to
+        // mutate the ValidateFunction's internal buffer through this handle.
+        errors.map((e) => ({ ...e })));
+    }
+    // At this point Ajv has narrowed `output` to `ValidatedComponent` via the
+    // typed ValidateFunction type-guard return; `output` is the same object
+    // identity the caller passed in.
+    const component = output;
+    // Pass 2 — @genie marker cross-check (AC4). Ajv can't express "field A
+    // matches regex X on field B's first line", so this runs in plain code
+    // against the (now shape-valid) file set. Collect every failure so the
+    // retry prompt can name all of them at once, mirroring `allErrors: true`.
+    const markerErrors = [];
+    for (let i = 0; i < component.files.length; i++) {
+        const file = component.files[i];
+        if (!NAMED_HTML_PATH.test(file.path)) {
+            // Not a `<Name>/<Name>.html` preview — the schema's `contains`
+            // guarantees at least one file *does* match, but non-preview files
+            // (e.g. `Button.tsx`, `meta.json`) are exempt from the marker rule.
+            continue;
+        }
+        // First line only (`\n` split limit=1 style, but done via indexOf to
+        // avoid allocating the whole `split()` array on files that pass — the
+        // vast majority in the steady state).
+        const newlineAt = file.content.indexOf("\n");
+        const firstLine = newlineAt === -1 ? file.content : file.content.slice(0, newlineAt);
+        if (!MARKER_REGEX_M2_07.test(firstLine)) {
+            markerErrors.push({
+                keyword: "@genie-marker",
+                instancePath: `/files/${i}/content`,
+                schemaPath: "#/properties/files/items/content",
+                params: {
+                    expected: MARKER_REGEX_M2_07.source,
+                    path: file.path,
+                },
+                message: `first line of ${file.path} does not match the @genie marker ` +
+                    `regex ${MARKER_REGEX_M2_07} (required for card registration)`,
+            });
+        }
+    }
+    if (markerErrors.length > 0) {
+        throw new SchemaValidationError(`LLM output has ${markerErrors.length} @genie marker error${markerErrors.length === 1 ? "" : "s"} (structural schema OK, marker cross-check failed).`, markerErrors);
+    }
+    return component;
+}
+//# sourceMappingURL=validate.js.map

package/dist/llm/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/llm/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,GAAG,EAA2C,MAAM,KAAK,CAAC;AAEnE,OAAO,EAAE,gBAAgB,EAA2B,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAKpD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAY,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,8DAA8D,CAAC;AAE9F;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,yEAAyE;IAChE,MAAM,CAAgB;IAE/B,YAAY,OAAe,EAAE,MAAqB;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACvD,MAAM,QAAQ,GACZ,GAAG,CAAC,OAAO,CAAqB,gBAAgB,CAAC,CAAC;AAEpD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAe;IAC/C,0EAA0E;IAC1E,wEAAwE;IACxE,2EAA2E;IAC3E,gBAAgB;IAChB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC;QACrC,MAAM,IAAI,qBAAqB,CAC7B,kDAAkD,MAAM,CAAC,MAAM,SAC7D,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAC7B,IAAI;QACJ,sEAAsE;QACtE,qEAAqE;QACrE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAC9B,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,wEAAwE;IACxE,iCAAiC;IACjC,MAAM,SAAS,GAAG,MAAM,CAAC;IAEzB,uEAAuE;IACvE,uEAAuE;IACvE,uEAAuE;IACvE,0EAA0E;IAC1E,MAAM,YAAY,GAAkB,EAAE,CAAC;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QACjC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACrC,+DAA+D;YAC/D,mEAAmE;YACnE,oEAAoE;YACpE,SAAS;QACX,CAAC;QACD,qEAAqE;QACrE,sEAAsE;QACtE,sCAAsC;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,SAAS,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACrF,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC;YACxC,YAAY,CAAC,IAAI,CAAC;gBAChB,OAAO,EAAE,eAAe;gBACxB,YAAY,EAAE,UAAU,CAAC,UAAU;gBACnC,UAAU,EAAE,kCAAkC;gBAC9C,MAAM,EAAE;oBACN,QAAQ,EAAE,kBAAkB,CAAC,MAAM;oBACnC,IAAI,EAAE,IAAI,CAAC,IAAI;iBAChB;gBACD,OAAO,EACL,iBAAiB,IAAI,CAAC,IAAI,oCAAoC;oBAC9D,SAAS,kBAAkB,mCAAmC;aACjE,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,qBAAqB,CAC7B,kBAAkB,YAAY,CAAC,MAAM,uBACnC,YAAY,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GACnC,qDAAqD,EACrD,YAAY,CACb,CAAC;IACJ,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/manifest/compiler.d.ts

@@ -0,0 +1,112 @@
+/**
+ * M3-03 (DRO-259) — the `.genie/manifest.json` writer (client-side compiler).
+ *
+ * This is genie's substitute for Anthropic's server-side manifest
+ * compilation (research report §6): a small, dependency-light walker that
+ * recompiles `<projectRoot>/.genie/manifest.json` from the `@genie` markers
+ * on disk whenever the M3-02 watcher fires (or on any direct call — this
+ * module has no opinion on WHEN it runs, only on producing a correct
+ * manifest for a given `projectRoot` snapshot).
+ *
+ * ── Schema reconciliation (recorded on DRO-259 before this file was written) ──
+ * This issue's own AC4 (and the RFC §6.8/§7.1 sketch, and the M4-03 viewer's
+ * `fetch` code) describe a root key `cards` with `viewport: {width,height}`
+ * as an object. But `../store/manifest.ts` — already merged, backing the
+ * shipped/tested M1-15 `list_components` tool, read by BOTH `LocalFsKitStore`
+ * and `GitHostKitStore` — has a zod schema that requires the root key
+ * `components`, with `viewport` as the raw marker STRING (e.g. `"400x200"`
+ * or `"desktop"`), plus `{name, group, path, hash, lastModified}`.
+ *
+ * Emitting `cards` would silently break `list_components` (a live, shipped
+ * P0 tool): its zod parse requires `components` and would throw
+ * `ManifestParseError` on a `cards`-shaped file. So this compiler emits
+ * `components` with a STRING `viewport`, matching the already-shipped reader
+ * contract. `../store/manifest.ts`'s schemas are `.passthrough()`, so the
+ * RFC's additional fields are layered on top without conflict: top-level
+ * `version: 1`, `generatedAt`, `name` (the kit/project's directory basename),
+ * `groups: string[]`; per-card `subtitle`/`tags` when a sibling `meta.json`
+ * supplies them. This is additive/forward-compatible per RFC §16.2 ("add a
+ * new output field — allowed in minor/patch").
+ *
+ * Pure-ish orchestration: the only side effects are reading the component
+ * tree + sibling `meta.json`/`_groups.json` files and the final atomic write.
+ * Marker PRESENCE validation and card sort order are delegated to
+ * already-shipped, independently-tested modules (M3-01's `validateMarker`,
+ * `store/manifest.ts`'s `compareComponents`); group/viewport extraction is
+ * a narrow regex read of the same already-validated marker line (see
+ * `extractGroup`/`extractViewportToken` below for why M3-01's own
+ * `extractViewport` isn't reused verbatim here).
+ */
+/**
+ * One compiled card (AC2–AC5). Matches `../store/manifest.ts`'s
+ * `ComponentEntry` six required fields exactly, plus the two optional
+ * `meta.json`-sourced fields already defined by `llm/schema.ts`'s
+ * `manifestEntry` (`subtitle`, `tags`).
+ */
+export interface ManifestCard {
+    name: string;
+    group: string;
+    path: string;
+    /** The raw marker token (e.g. "400x200" or "desktop") — AC5 note; not decomposed. */
+    viewport: string;
+    /** `sha256-<base64>` SRI hash of the HTML file's bytes (AC5). */
+    hash: string;
+    /** ISO-8601 mtime of the HTML file. */
+    lastModified: string;
+    subtitle?: string;
+    tags?: string[];
+}
+/** The full compiled manifest (AC4, reconciled — see module doc). */
+export interface Manifest {
+    version: 1;
+    name: string;
+    generatedAt: string;
+    groups: string[];
+    components: ManifestCard[];
+}
+/**
+ * One skipped file the compiler declined to card — surfaced so a caller (the
+ * M3-02 watcher's `onChange`, or a future `validate` full-scan) can report
+ * `markerMissing` rather than the omission vanishing silently. Mirrors the
+ * RFC §6.8 failure mode: "the watcher silently skips it; `validate` surfaces
+ * the omission."
+ */
+export interface ManifestSkip {
+    path: string;
+    reason: "MARKER_MISSING";
+}
+/** {@link compileManifest}'s full result: the manifest plus any skips. */
+export interface CompileResult {
+    manifest: Manifest;
+    skipped: ManifestSkip[];
+}
+/**
+ * Recompile the manifest for `projectRoot` (AC1) purely from what's on disk
+ * right now — no incremental state, no cache. Safe to call as often as the
+ * watcher likes; a debounce (M3-02's own 100 ms window) is the caller's
+ * concern, not this function's.
+ *
+ * Steps (AC2/AC3):
+ *  1. Walk `${projectRoot}/components/**\/*.html`.
+ *  2. For each, validate the `@genie` first line (M3-01). A file that fails
+ *     is SKIPPED (not carded) and reported in `skipped` — mirrors the RFC
+ *     §6.8 failure mode ("the watcher silently skips it; validate surfaces
+ *     the omission").
+ *  3. Extract `viewport` from the marker line; join a sibling `meta.json`
+ *     for `subtitle`/`tags` when present (AC3).
+ *  4. Hash the HTML file's bytes as `sha256-<base64>` SRI (AC5, same format
+ *     `list_files`/`.genie/sync.json` use — `store/kit-files.ts`'s
+ *     `sriSha256`).
+ *  5. Sort groups alphabetically unless a root `_groups.json` sibling pins an
+ *     explicit order (Impl Notes); sort cards alphabetically by `name`
+ *     within a group, ties broken by `path` (the shared `compareComponents`
+ *     from `store/manifest.ts` — AC6-equivalent ordering used everywhere
+ *     else a component list is sorted in this codebase).
+ *  6. Atomically write `.genie/manifest.json` (AC6): stage under
+ *     `${projectRoot}/.genie-tmp/`, then rename over the destination — same
+ *     same-filesystem-rename pattern `sync/anchor.ts` and `store/local.ts`
+ *     already use, so a crash mid-write leaves the PRIOR manifest (or none)
+ *     intact, never a half-written one.
+ */
+export declare function compileManifest(projectRoot: string): Promise<CompileResult>;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/manifest/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../src/manifest/compiler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAWH;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,qFAAqF;IACrF,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,CAAC,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,YAAY,EAAE,CAAC;CAC5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,QAAQ,CAAC;IACnB,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAqKD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CA2DjF"}