@ambitresearch/genie 1.3.1

package/dist/tools/validate.js

@@ -0,0 +1,224 @@
+/**
+ * MCP tool: validate (D-A — one verb, two facets).
+ *
+ * genie's `validate` verb has two facets that share this single MCP tool
+ * (`00-decisions.md` D-A folds `report_validate` + `validate_design_system`
+ * into one verb):
+ *
+ *   1. **Counter-persistence facet (M1-12).** The caller already ran validation
+ *      client-side and passes aggregate `counts`; this facet persists them to a
+ *      timestamped report + emits Prometheus metrics. Read-side telemetry, no
+ *      planId semantics.
+ *        Input:  { kitId, counts: { total, bad, thin, variantsIdentical, iterations } }
+ *        Output: {}
+ *
+ *   2. **Full-scan facet (M3-04 · DRO-260).** The caller passes NO `counts`;
+ *      this facet does the heavyweight walk itself — the `@genie` marker check,
+ *      the "thin render" check, and the "variants identical" perceptual-hash
+ *      check across every `.html` file in the kit — and returns structured
+ *      findings the model can act on, THEN persists the derived counters via the
+ *      exact same `persistReport`/`emitMetrics` path as facet 1 (AC8: one verb,
+ *      one persistence path).
+ *        Input:  { kitId, planId? }
+ *        Output: { markerMissing, thin, variantsIdentical, total, bad }
+ *
+ * The presence of `counts` in the input discriminates the two facets — the MCP
+ * verb has one input schema, so `counts` is optional and its presence selects
+ * the persist-only path; its absence selects the full scan.
+ */
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { Counter, Registry } from "prom-client";
+import { fullScan, createDefaultRenderer, } from "../validate/index.js";
+/** Input schema for validate (counter-persistence facet). */
+const countsSchema = z.object({
+    total: z.number().int().nonnegative().describe("Total component count"),
+    bad: z.number().int().nonnegative().describe("Failed validation count"),
+    thin: z.number().int().nonnegative().describe("Thin component count"),
+    variantsIdentical: z.number().int().nonnegative().describe("Variants identical count"),
+    iterations: z.number().int().nonnegative().describe("Iteration count"),
+});
+const inputSchema = {
+    kitId: z.string().min(1).describe("UI kit identifier"),
+    // Facet 1 (counter-persistence, M1-12): when present, the caller supplies
+    // pre-computed counts and this verb only persists them. When ABSENT, facet 2
+    // (full-scan, M3-04) runs the checks itself. Optional so one MCP input schema
+    // serves both facets (D-A: one verb).
+    counts: countsSchema
+        .optional()
+        .describe("Pre-computed validation counts (counter-persistence facet). Omit to run " +
+        "the full-scan facet, which computes findings by scanning the kit."),
+    // Facet 2 (full-scan, M3-04 · AC2): optional planId, accepted per the verb's
+    // declared `validate({ kitId, planId? })` signature. Ignored by facet 1.
+    planId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Optional plan id (full-scan facet); accepted per the verb signature."),
+};
+/**
+ * Prometheus metrics registry and counters.
+ * Exposed as a module singleton so M6-01 can register it with the HTTP endpoint.
+ */
+export const metricsRegistry = new Registry();
+const totalCounter = new Counter({
+    name: "genie_validate_total",
+    help: "Total components validated",
+    labelNames: ["kitId"],
+    registers: [metricsRegistry],
+});
+const badCounter = new Counter({
+    name: "genie_validate_bad",
+    help: "Components that failed validation",
+    labelNames: ["kitId"],
+    registers: [metricsRegistry],
+});
+const thinCounter = new Counter({
+    name: "genie_validate_thin",
+    help: "Thin components (minimal content)",
+    labelNames: ["kitId"],
+    registers: [metricsRegistry],
+});
+const variantsIdenticalCounter = new Counter({
+    name: "genie_validate_variantsIdentical",
+    help: "Components with identical variants",
+    labelNames: ["kitId"],
+    registers: [metricsRegistry],
+});
+const iterationsCounter = new Counter({
+    name: "genie_validate_iterations",
+    help: "Validation iterations performed",
+    labelNames: ["kitId"],
+    registers: [metricsRegistry],
+});
+/**
+ * Persist validation counts to a timestamped JSON report file.
+ *
+ * @param reportsDir - Directory where reports are stored (.genie/reports)
+ * @param kitId - Kit identifier
+ * @param counts - Validation counts to persist
+ * @returns The path to the created report file
+ */
+export async function persistReport(reportsDir, kitId, counts) {
+    await mkdir(reportsDir, { recursive: true });
+    const timestamp = new Date().toISOString();
+    // Sanitize for Windows-safe filenames (`:` is forbidden) and append a
+    // random hex suffix so concurrent calls within the same millisecond never
+    // collide or overwrite each other.
+    const safeTimestamp = timestamp.replace(/:/g, "-");
+    const suffix = Math.random().toString(16).slice(2, 8);
+    const reportPath = join(reportsDir, `${safeTimestamp}-${suffix}.json`);
+    const report = {
+        timestamp,
+        kitId,
+        counts,
+    };
+    await writeFile(reportPath, JSON.stringify(report, null, 2), "utf-8");
+    return reportPath;
+}
+/**
+ * Emit Prometheus metrics for the given validation counts.
+ *
+ * @param kitId - Kit identifier (used as metric label)
+ * @param counts - Validation counts to emit
+ */
+export function emitMetrics(kitId, counts) {
+    totalCounter.inc({ kitId }, counts.total);
+    badCounter.inc({ kitId }, counts.bad);
+    thinCounter.inc({ kitId }, counts.thin);
+    variantsIdenticalCounter.inc({ kitId }, counts.variantsIdentical);
+    iterationsCounter.inc({ kitId }, counts.iterations);
+}
+/**
+ * Derive the M1-12 counter shape from a full-scan result (AC8: the full-scan
+ * facet persists its run via the SAME `persistReport`/`emitMetrics` path as the
+ * counter facet). `iterations` is 1 — a single scan pass — and the four
+ * validation dimensions come straight off the scan. `bad` is the scan's own
+ * literal sum (`markerMissing + thin + variantsIdentical`).
+ */
+export function countsFromScan(result) {
+    return {
+        total: result.total,
+        bad: result.bad,
+        thin: result.thin.length,
+        variantsIdentical: result.variantsIdentical.length,
+        iterations: 1,
+    };
+}
+/**
+ * Register the `mcp__genie__validate` tool on the given MCP server (both
+ * facets — see the module header).
+ *
+ * Backward-compatible call shape: `registerValidate(server, reportsDir?)` still
+ * works (the M1-12 wiring), and `registerValidate(server, options)` opts into
+ * the full-scan facet by supplying a `kitStore`.
+ */
+export function registerValidate(server, reportsDirOrOptions) {
+    const options = typeof reportsDirOrOptions === "string"
+        ? { reportsDir: reportsDirOrOptions }
+        : (reportsDirOrOptions ?? {});
+    const resolvedReportsDir = options.reportsDir ?? process.env.GENIE_REPORTS_DIR ?? join(process.cwd(), ".genie", "reports");
+    const createRenderer = options.createRenderer ?? createDefaultRenderer;
+    server.registerTool("mcp__genie__validate", {
+        title: "Validate",
+        description: "genie's validate verb (two facets, one tool). WITH `counts`: persists " +
+            "pre-computed validation counts for telemetry (no planId needed — read-" +
+            "side). WITHOUT `counts`: runs the full-scan facet — @genie marker check " +
+            "+ thin-render check + variants-identical perceptual-hash check across " +
+            "the kit — and returns { markerMissing, thin, variantsIdentical, total, " +
+            "bad }, persisting the derived counters via the same path. Reach for this as an " +
+            "advisory quality audit after conjure/refine + write_files — its findings are " +
+            "counts, not blocking errors.",
+        inputSchema,
+    }, async ({ kitId, counts, planId, }) => {
+        // ── Facet 1: counter-persistence (M1-12) ────────────────────────────────
+        // Explicit `counts` → persist-only, exactly as before.
+        if (counts) {
+            await persistReport(resolvedReportsDir, kitId, counts);
+            emitMetrics(kitId, counts);
+            return { content: [{ type: "text", text: JSON.stringify({}) }] };
+        }
+        // ── Facet 2: full-scan (M3-04 · DRO-260) ────────────────────────────────
+        // No `counts` → run the checks ourselves. Needs a kit store to read the
+        // tree; without one, the facet is not available in this deployment.
+        if (!options.kitStore) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "ERR_FULLSCAN_UNAVAILABLE",
+                            message: "The full-scan facet requires a kit store; this validate tool was " +
+                                "registered without one. Pass pre-computed `counts` to use the " +
+                                "counter-persistence facet instead.",
+                        }),
+                    },
+                ],
+            };
+        }
+        // One renderer per scan (AC7), created here and closed after — the
+        // orchestrator never closes a renderer it did not create. A `null`
+        // renderer (Playwright/Chromium unavailable) makes the scan degrade to
+        // marker-only rather than fail (same posture as `refine`'s region crop).
+        const renderer = await createRenderer();
+        let result;
+        try {
+            result = await fullScan({ kitStore: options.kitStore, renderer }, { kitId, planId });
+        }
+        finally {
+            if (renderer)
+                await renderer.close();
+        }
+        // AC8 — persist the derived counters through the SAME path as facet 1.
+        const derived = countsFromScan(result);
+        await persistReport(resolvedReportsDir, kitId, derived);
+        emitMetrics(kitId, derived);
+        // Return the structured findings (the heavyweight facet's whole point).
+        return {
+            content: [{ type: "text", text: JSON.stringify(result) }],
+        };
+    });
+}
+//# sourceMappingURL=validate.js.map

package/dist/tools/validate.js.map

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

package/dist/tools/write_files.d.ts

@@ -0,0 +1,158 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { KitStore } from "../store/interface.js";
+export declare const WRITE_FILES_TOOL_NAME = "mcp__genie__write_files";
+/** M1-08 AC3 — hard ceiling on files per call. */
+export declare const MAX_FILES_PER_CALL = 256;
+/**
+ * Byte-cap for a single `write_files` call's total decoded payload.
+ *
+ * RFC §17.5 flags Anthropic's exact server-side cap as unconfirmed for their
+ * hosted endpoint; PRD §EC-029 sets genie's own default at 16 MiB with a
+ * configurable ceiling. `GENIE_WRITE_BYTE_CAP` overrides the default; values
+ * that are non-numeric or ≤ 0 fall back to it.
+ */
+export declare const DEFAULT_WRITE_BYTE_CAP: number;
+/** M1-08 AC3 — more than 256 files were supplied to `write_files` in one call. */
+export declare class TooManyFilesError extends Error {
+    readonly count: number;
+    readonly max: number;
+    readonly code = "TooManyFilesError";
+    constructor(count: number, max: number);
+}
+/**
+ * Two or more files in the same call target the same `path` (Copilot review
+ * finding on PR #106). Without this check, `resolvedLocalPaths` — keyed by
+ * `file.path` — would silently drop all but the last entry's `localPath`
+ * (so an earlier duplicate would stage the WRONG file's bytes), and
+ * `writtenPaths` would list the same path twice as if two distinct files had
+ * been written, when in fact whichever entry committed last (an unspecified,
+ * input-order-dependent race between the two renames) is the only one that
+ * survives. Rejected up front, before any per-file validation, so partial
+ * ambiguity is never staged.
+ */
+export declare class DuplicatePathError extends Error {
+    readonly path: string;
+    readonly code = "DuplicatePathError";
+    constructor(path: string);
+}
+/**
+ * M1-08 AC4 — a file's `path` is rejected by the plan boundary: either it
+ * doesn't match any glob in the plan's `writes` (`reason: "glob"`), or it
+ * resolves outside the plan's `localDir` even though a glob DID match
+ * (`reason: "escapesLocalDir"` — e.g. an absolute path under a permissive
+ * `**`; see the containment check in `writeFiles`). Both failure modes share
+ * one error class/code (`PathOutsidePlanError`) so callers can branch on a
+ * single `code`, but the message and `reason` field distinguish them —
+ * a Copilot review finding on PR #106 flagged the message as misleadingly
+ * glob-specific even when the actual cause was the containment check.
+ */
+export declare class PathOutsidePlanError extends Error {
+    readonly path: string;
+    readonly reason: "glob" | "escapesLocalDir";
+    readonly code = "PathOutsidePlanError";
+    constructor(path: string, reason?: "glob" | "escapesLocalDir");
+}
+/** M1-08 AC6 — a file's `localPath` resolves outside the plan's `localDir`. */
+export declare class LocalPathEscapeError extends Error {
+    readonly localPath: string;
+    readonly localDir: string;
+    readonly code = "LocalPathEscapeError";
+    constructor(localPath: string, localDir: string);
+}
+/** M1-08 AC7 — a file set neither `localPath` nor `data`, or set both. */
+export declare class InvalidFileInputError extends Error {
+    readonly path: string;
+    readonly code = "InvalidFileInputError";
+    constructor(path: string, reason: "missing" | "both");
+}
+/** M1-08 AC7 — `data` was not valid base64 when `encoding: "base64"` was declared. */
+export declare class InvalidEncodingError extends Error {
+    readonly path: string;
+    readonly code = "InvalidEncodingError";
+    constructor(path: string);
+}
+/** M1-08 AC9 — the call's total decoded byte size exceeds the configured cap. */
+export declare class PayloadTooLargeError extends Error {
+    readonly totalBytes: number;
+    readonly maxBytes: number;
+    readonly retryMaxFiles: number;
+    readonly code = "PayloadTooLargeError";
+    constructor(totalBytes: number, maxBytes: number, retryMaxFiles: number);
+}
+/**
+ * AC10 write-failure taxonomy now lives in the store layer (`store/interface.ts`),
+ * because the store owns the atomic write transaction after the DRO-565 re-plumb.
+ * Re-exported here so existing importers of these names from `write_files.js`
+ * (tests, in-process callers) keep resolving them.
+ */
+export { RollbackIncompleteError, WriteFailedError } from "../store/interface.js";
+interface FileInput {
+    path: string;
+    localPath?: string;
+    data?: string;
+    encoding?: "utf-8" | "base64";
+    mimeType?: string;
+}
+interface WriteFilesArgs {
+    planId: string;
+    files: FileInput[];
+}
+/**
+ * Register the `mcp__genie__write_files` tool.
+ *
+ * @param server   The MCP server to register against. `planId`/`writes` are
+ *                 validated against the shared M1-07 plan registry
+ *                 (`../plans/index.ts`) via the M1-13 plan-guard middleware
+ *                 (`../middleware/plan-guard.ts`) — the guard owns AC5's planId
+ *                 presence/existence/expiry checks and AC4's path-vs-`writes`-
+ *                 glob check; this file's own remaining validation covers
+ *                 per-file structural rules (duplicates, localPath containment,
+ *                 encoding, byte cap) that the guard is intentionally
+ *                 tool-agnostic about.
+ * @param kitStore The injected kit backend (M1-14a-1b / DRO-565). The physical
+ *                 write is `kitStore.writeFiles(plan.kitId, ops)` — the kit is
+ *                 the destination (same surface read_file/list_files see), and
+ *                 the atomic rename-transaction (LocalFs) / contents-API commit
+ *                 (GitHost) lives behind that primitive. Mirrors how
+ *                 `registerDeleteFilesTool(server, kitStore)` routes deletes.
+ */
+export declare function registerWriteFilesTool(server: McpServer, kitStore: KitStore): void;
+export interface WriteFilesResult extends Record<string, unknown> {
+    writtenPaths: string[];
+}
+/**
+ * Validate + execute a `write_files` call against a resolved plan, committing
+ * the batch into the plan's KIT via the injected store.
+ *
+ * Order of validation (fails fast, before any write) — keep this list in
+ * lockstep with the code below; downstream steps assume every prior step has
+ * passed (e.g. the `resolvedLocalPaths` map keyed by `file.path` assumes step 3
+ * rejected duplicates):
+ *   1. AC5           — planId exists + not expired (`getPlan`, from the M1-07
+ *                      plan registry — throws `PlanNotFoundError` for either
+ *                      failure mode).
+ *   2. AC3           — `files.length <= 256`.
+ *   3. Structural    — no two `files[]` entries share the same destination
+ *                      `path` (`DuplicatePathError`; Copilot review finding
+ *                      on PR #106).
+ *   4. AC4           — every `path` matches a plan `writes` glob.
+ *   5. Security      — every destination `path` is kit-relative and contained
+ *                      (no absolute path, no `..`/`.` segment). Destinations
+ *                      resolve against the KIT now (not `localDir`), so this is
+ *                      a lexical containment check (`PathOutsidePlanError` with
+ *                      `reason: "escapesLocalDir"`; RFC §10 T-13). The store
+ *                      re-checks via `safePath` as defense-in-depth.
+ *   6. AC7           — every file sets exactly one of `localPath` / `data`.
+ *   7. AC6           — every `localPath` resolves inside the plan's `localDir`
+ *                      (the SOURCE base — where uploads are read from).
+ *   8. AC9           — total decoded payload size <= the configured byte cap.
+ * Only once every file in the batch passes is the batch handed to
+ * `store.writeFiles(plan.kitId, ops)` for the atomic commit (AC10).
+ *
+ * @param store The injected kit backend. The destination is `plan.kitId`; the
+ *   physical atomic write (rename transaction on LocalFs / contents-API commit
+ *   on GitHost) lives behind `store.writeFiles`, so this function is now purely
+ *   validation + WriteOp assembly.
+ */
+export declare function writeFiles(store: KitStore, args: WriteFilesArgs, env?: Record<string, string | undefined>): Promise<WriteFilesResult>;
+//# sourceMappingURL=write_files.d.ts.map

package/dist/tools/write_files.d.ts.map

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