@ogygie/core 0.1.0

package/src/manifest-client.test.ts

@@ -0,0 +1,287 @@
+/**
+ * @intent Proves the manifest-client derivation (spec front-derivation §1):
+ * the client exposes exactly the declared routes (mutation test: a removed
+ * route disappears), derives namespaces, operations, cache keys and
+ * invalidation roots, and refuses loudly what it cannot derive. Fixtures are
+ * deliberately vocabulary-neutral — the vocabulary test next door scans this
+ * file too.
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { OgygieFailure } from "./error.schema.js";
+import {
+  createManifestClient,
+  type ManifestClientRequest,
+} from "./manifest-client.js";
+
+const SCHEMA_NAMES = [
+  "ListWidgetsInputSchema",
+  "ListWidgetsOutputSchema",
+  "CreateWidgetInputSchema",
+  "CreateWidgetOutputSchema",
+  "UpdateWidgetInputSchema",
+  "UpdateWidgetOutputSchema",
+  "WidgetParamsSchema",
+  "GetWidgetOutputSchema",
+  "ArchiveWidgetOutputSchema",
+  "ListWorkOrdersInputSchema",
+  "ListWorkOrdersOutputSchema",
+  "DecideWorkOrderInputSchema",
+  "DecideWorkOrderOutputSchema",
+  "SearchReportsInputSchema",
+  "SearchReportsOutputSchema",
+] as const;
+
+/** One distinct schema instance per name, so identity can be asserted. */
+function schemaRegistry(): Record<string, z.ZodType> {
+  return Object.fromEntries(
+    SCHEMA_NAMES.map((name) => [name, z.record(z.string(), z.unknown())]),
+  );
+}
+
+interface RouteOverride {
+  invalidates?: string[];
+}
+
+function fixtureManifest(options?: {
+  dropArchiveRoute?: boolean;
+  extraWidgetRoutes?: Record<string, unknown>[];
+  acceptRoute?: RouteOverride;
+}) {
+  const widgetRoutes: Record<string, unknown>[] = [
+    {
+      method: "GET",
+      path: "/api/widgets",
+      description: "Lists the widgets of the account.",
+      schemaInput: "ListWidgetsInputSchema",
+      schemaOutput: "ListWidgetsOutputSchema",
+    },
+    {
+      method: "POST",
+      path: "/api/widgets",
+      description: "Creates a widget for the account.",
+      schemaInput: "CreateWidgetInputSchema",
+      schemaOutput: "CreateWidgetOutputSchema",
+    },
+    {
+      method: "PATCH",
+      path: "/api/widgets/:widgetId",
+      description: "Updates a widget of the account.",
+      schemaInput: "UpdateWidgetInputSchema",
+      schemaOutput: "UpdateWidgetOutputSchema",
+    },
+    {
+      method: "GET",
+      path: "/api/widgets/:widgetId",
+      description: "Reads one widget of the account.",
+      schemaInput: "WidgetParamsSchema",
+      schemaOutput: "GetWidgetOutputSchema",
+    },
+    ...(options?.dropArchiveRoute === true
+      ? []
+      : [
+          {
+            method: "POST",
+            path: "/api/widgets/:widgetId/archive",
+            description: "Archives a widget (one-way removal).",
+            schemaInput: "WidgetParamsSchema",
+            schemaOutput: "ArchiveWidgetOutputSchema",
+          },
+        ]),
+    ...(options?.extraWidgetRoutes ?? []),
+  ];
+  return {
+    version: 1,
+    product: { name: "acme", description: "Vocabulary-neutral fixture product for derivation tests." },
+    apps: [{ name: "api", path: "apps/api", type: "api", entryPoint: "apps/api/src/server.ts" }],
+    features: [
+      {
+        name: "widgets",
+        intent: "Fixture feature with the full nominal route surface of a referential.",
+        folder: "src/features/widgets",
+        spec: null,
+        routes: widgetRoutes,
+        dbTables: [],
+        dependsOn: [],
+        status: "delivered",
+      },
+      {
+        name: "work-orders",
+        intent: "Fixture feature with a kebab-case root and a cross invalidation.",
+        folder: "src/features/work-orders",
+        spec: null,
+        routes: [
+          {
+            method: "GET",
+            path: "/api/work-orders",
+            description: "Lists the pending work orders.",
+            schemaInput: "ListWorkOrdersInputSchema",
+            schemaOutput: "ListWorkOrdersOutputSchema",
+          },
+          {
+            method: "POST",
+            path: "/api/work-orders/:orderId/accept",
+            description: "Accepts a pending work order.",
+            schemaInput: "DecideWorkOrderInputSchema",
+            schemaOutput: "DecideWorkOrderOutputSchema",
+            ...(options?.acceptRoute ?? { invalidates: ["widgets"] }),
+          },
+          {
+            method: "GET",
+            path: "/api/reports",
+            description: "Searches the reports of the account.",
+            schemaInput: "SearchReportsInputSchema",
+            schemaOutput: "SearchReportsOutputSchema",
+          },
+        ],
+        dbTables: [],
+        dependsOn: [],
+        status: "delivered",
+      },
+    ],
+    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
+  };
+}
+
+function buildClient(manifest: unknown = fixtureManifest()) {
+  const requests: ManifestClientRequest[] = [];
+  const schemas = schemaRegistry();
+  const client = createManifestClient(manifest, schemas, {
+    performRequest: async (request) => {
+      requests.push(request);
+      return { ok: true };
+    },
+  });
+  return { client, requests, schemas };
+}
+
+function failureCodeOf(run: () => unknown): string | null {
+  try {
+    run();
+    return null;
+  } catch (thrown) {
+    return thrown instanceof OgygieFailure ? thrown.error.code : "NOT_AN_OGYGIE_FAILURE";
+  }
+}
+
+describe("manifest-client — dérivation (spec front-derivation §1)", () => {
+  it("ÉTANT DONNÉ le manifeste QUAND le client est construit ALORS il expose exactement les routes déclarées", () => {
+    const { client } = buildClient();
+    expect(Object.keys(client).sort()).toEqual(["reports", "widgets", "workOrders"]);
+    expect(Object.keys(client["widgets"] ?? {}).sort()).toEqual([
+      "archive",
+      "create",
+      "get",
+      "list",
+      "update",
+    ]);
+    expect(Object.keys(client["workOrders"] ?? {}).sort()).toEqual(["accept", "list"]);
+    expect(Object.keys(client["reports"] ?? {}).sort()).toEqual(["search"]);
+  });
+
+  it("MUTATION : une route retirée du manifeste disparaît du client", () => {
+    const { client } = buildClient(fixtureManifest({ dropArchiveRoute: true }));
+    expect(client["widgets"]?.["archive"]).toBeUndefined();
+    expect(client["widgets"]?.["create"]).toBeDefined();
+  });
+
+  it("les clés de cache sont dérivées du chemin : racine, opération, valeurs de params, puis reste de l'entrée", () => {
+    const { client } = buildClient();
+    expect(client["widgets"]?.["list"]?.queryKey()).toEqual(["widgets", "list"]);
+    expect(client["widgets"]?.["get"]?.queryKey({ widgetId: "w-1" })).toEqual([
+      "widgets",
+      "get",
+      "w-1",
+    ]);
+    expect(client["reports"]?.["search"]?.queryKey({ q: "ab", limit: 20 })).toEqual([
+      "reports",
+      "search",
+      { q: "ab", limit: 20 },
+    ]);
+    // Kebab-case root stays RAW in the key (it is the invalidation currency),
+    // while the namespace is camelCased for the call site.
+    expect(client["workOrders"]?.["list"]?.queryKey()).toEqual(["work-orders", "list"]);
+  });
+
+  it("RÉGRESSION (ecrans-plan) : deux GET voisins sur la même entité ne partagent JAMAIS une clé de cache", () => {
+    // Without the operation in the key, widgets.get and a sibling
+    // GET /api/widgets/:widgetId/child would collide — TanStack would dedupe
+    // them and the second query would silently never fire.
+    const { client } = buildClient();
+    const getKey = client["widgets"]?.["get"]?.queryKey({ widgetId: "w-1" });
+    const archiveKey = client["widgets"]?.["archive"]?.queryKey({ widgetId: "w-1" });
+    expect(getKey).not.toEqual(archiveKey);
+  });
+
+  it("les racines d'invalidation = racine propre + invalidates déclarés au manifeste", () => {
+    const { client } = buildClient();
+    expect(client["workOrders"]?.["accept"]?.invalidationRoots).toEqual([
+      "work-orders",
+      "widgets",
+    ]);
+    expect(client["widgets"]?.["create"]?.invalidationRoots).toEqual(["widgets"]);
+    expect(client["widgets"]?.["create"]?.isMutation).toBe(true);
+    expect(client["widgets"]?.["list"]?.isMutation).toBe(false);
+  });
+
+  it("un appel GET envoie le reste de l'entrée en query string, sans body", async () => {
+    const { client, requests, schemas } = buildClient();
+    await client["reports"]?.["search"]?.({ q: "ab", limit: 20 });
+    expect(requests).toEqual([
+      {
+        method: "GET",
+        path: "/api/reports?q=ab&limit=20",
+        outputSchema: schemas["SearchReportsOutputSchema"],
+      },
+    ]);
+  });
+
+  it("un appel de mutation consomme les params du chemin et envoie le reste en body", async () => {
+    const { client, requests } = buildClient();
+    await client["widgets"]?.["update"]?.({ widgetId: "w-1", title: "renamed" });
+    await client["workOrders"]?.["accept"]?.({ orderId: "o-9" });
+    expect(requests[0]?.path).toBe("/api/widgets/w-1");
+    expect(requests[0]?.body).toEqual({ title: "renamed" });
+    expect(requests[1]?.path).toBe("/api/work-orders/o-9/accept");
+    expect(requests[1]?.body).toEqual({});
+  });
+
+  it("un param de chemin manquant à l'appel est refusé bruyamment", async () => {
+    const { client } = buildClient();
+    await expect(client["widgets"]?.["update"]?.({ title: "renamed" })).rejects.toSatisfy(
+      (thrown) =>
+        thrown instanceof OgygieFailure && thrown.error.code === "CLIENT_MISSING_PATH_PARAM",
+    );
+  });
+
+  it("MUTATION : un schéma absent du registre refuse la construction (CLIENT_MANIFEST_INVALID)", () => {
+    const schemas = schemaRegistry();
+    delete schemas["CreateWidgetInputSchema"];
+    expect(
+      failureCodeOf(() =>
+        createManifestClient(fixtureManifest(), schemas, {
+          performRequest: async () => ({}),
+        }),
+      ),
+    ).toBe("CLIENT_MANIFEST_INVALID");
+  });
+
+  it("MUTATION : deux routes qui dérivent la même opération refusent la construction", () => {
+    const manifest = fixtureManifest({
+      extraWidgetRoutes: [
+        {
+          method: "PUT",
+          path: "/api/widgets/:widgetId",
+          description: "Collides with PATCH: same derived operation name.",
+          schemaInput: "UpdateWidgetInputSchema",
+          schemaOutput: "UpdateWidgetOutputSchema",
+        },
+      ],
+    });
+    expect(failureCodeOf(() => buildClient(manifest))).toBe("CLIENT_MANIFEST_INVALID");
+  });
+
+  it("MUTATION : un manifeste invalide refuse la construction au lieu de dériver un client menteur", () => {
+    expect(failureCodeOf(() => buildClient({ version: 1 }))).toBe("CLIENT_MANIFEST_INVALID");
+  });
+});

package/src/manifest-client.ts

@@ -0,0 +1,313 @@
+/**
+ * @intent GENERIC manifest-derived API client factory, framework side — the
+ * browser pendant of the manifest-derived gateway: this module knows ZERO
+ * product vocabulary (D10 amended — generic tooling lives in the core), and
+ * the vocabulary test next to it proves it. It derives callable operations
+ * from an Ogygie manifest: every declared route becomes a method under its
+ * path-root namespace, nothing else exists — a route removed from the
+ * manifest disappears from the client, the manifest is the only map (D27).
+ *
+ * Derivations (all from the manifest, nothing hand-written per feature):
+ * - namespace: first path segment after /api, camelCased
+ *   ("/api/work-orders/..." → client.workOrders);
+ * - operation: the static segments after the namespace, camelCased
+ *   (".../:orderId/accept" → accept); when there are none, the VERB of the
+ *   declared input schema name ("SearchThingsInputSchema" → search); when the
+ *   schema name carries no verb, a method fallback (GET → list, GET on
+ *   ":param" → get, POST → create, PATCH/PUT → update, DELETE → delete);
+ * - cache key: [root, ...path param values, remaining input if any] — the
+ *   number-one source of cache bugs, so it is never written by hand;
+ * - invalidation roots: the route's own root, plus the roots the manifest
+ *   declares in `invalidates` (cross-feature staleness is READ, never
+ *   guessed in a screen).
+ *
+ * Transport stays OUTSIDE: the consumer injects `performRequest` (its typed
+ * fetch over the shared contracts, dev-time response validation included) —
+ * this module only resolves paths, splits inputs and derives keys. Building
+ * an incoherent client REFUSES loudly (CLIENT_MANIFEST_INVALID): a refusal
+ * at construction beats a method that lies at call time.
+ */
+import { z } from "zod";
+import { throwOgygieError } from "./error.schema.js";
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+/**
+ * The SUBSET of an Ogygie manifest the client consumes: the route surface,
+ * nothing else. Validating this VIEW (zod strips the unknown rest, so a full
+ * manifest passes as-is) keeps the guardianship of the whole manifest where
+ * it lives — verify-manifest in CI, the gateway at boot — and lets a browser
+ * bundle carry only these fields: the consumer may prune the manifest at
+ * build time by parsing it with this very schema.
+ */
+export const ClientManifestViewSchema = z.object({
+  features: z.array(
+    z.object({
+      name: z.string().min(1),
+      routes: z.array(
+        z.object({
+          method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
+          path: z.string().startsWith("/api/"),
+          schemaInput: z.string().min(1),
+          schemaOutput: z.string().min(1),
+          invalidates: z.array(z.string()).optional(),
+        }),
+      ),
+    }),
+  ),
+});
+export type ClientManifestView = z.infer<typeof ClientManifestViewSchema>;
+
+/** What the injected transport receives: a fully resolved request. */
+export interface ManifestClientRequest {
+  method: HttpMethod;
+  /** Path with params substituted and the query string already appended. */
+  path: string;
+  /** Present on POST/PUT/PATCH only: the input minus the path params. */
+  body?: unknown;
+  outputSchema: z.ZodType;
+}
+
+export interface ManifestClientOptions {
+  performRequest: (request: ManifestClientRequest) => Promise<unknown>;
+}
+
+/** One derived operation: callable, and self-describing for the query layer. */
+export interface ApiOperation {
+  (input?: Record<string, unknown>): Promise<unknown>;
+  method: HttpMethod;
+  path: string;
+  namespace: string;
+  operation: string;
+  inputSchema: z.ZodType;
+  outputSchema: z.ZodType;
+  /** True for POST/PUT/PATCH/DELETE — the caller picks query vs mutation. */
+  isMutation: boolean;
+  /** Derived cache key: [root, ...param values, remaining input if any]. */
+  queryKey: (input?: Record<string, unknown>) => ReadonlyArray<unknown>;
+  /** Cache roots stale after a successful mutation: own root + declared `invalidates`. */
+  invalidationRoots: ReadonlyArray<string>;
+}
+
+export type ManifestClient = Record<string, Record<string, ApiOperation>>;
+
+const METHODS_WITH_BODY = new Set<HttpMethod>(["POST", "PUT", "PATCH"]);
+
+/** Same well-formedness bar as the gateway: /api segments and :params only. */
+const WELL_FORMED_ROUTE_PATH = /^\/api(\/(:?[a-zA-Z0-9_-]+))+$/;
+
+/** "work-orders" → "workOrders" (path segments are kebab-case by convention). */
+function camelCaseOf(segment: string): string {
+  return segment.replace(/-([a-z0-9])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+/** "SearchThingsInputSchema" → "search"; null when the name carries no verb. */
+function verbOfInputSchemaName(schemaName: string): string | null {
+  const match = /^([A-Z][a-z0-9]*)[A-Z].*InputSchema$/.exec(schemaName);
+  return match?.[1] === undefined ? null : match[1].toLowerCase();
+}
+
+function refuseClient(cause: string): never {
+  throwOgygieError(
+    {
+      code: "CLIENT_MANIFEST_INVALID",
+      message: "Manifest client construction refused: the manifest cannot be derived into operations.",
+      file: "ogygie.manifest.json",
+      cause,
+      suggestedFix:
+        "Fix the manifest (or register the missing schema in the client's schema registry) — a construction refusal beats a method that lies.",
+    },
+    500,
+  );
+}
+
+interface DerivedRoute {
+  method: HttpMethod;
+  path: string;
+  root: string;
+  namespace: string;
+  operation: string;
+  paramNames: ReadonlyArray<string>;
+  schemaInput: string;
+  schemaOutput: string;
+  invalidates: ReadonlyArray<string>;
+}
+
+function deriveOperationName(route: DerivedRoute): string {
+  const staticTail = route.path
+    .split("/")
+    .slice(3)
+    .filter((segment) => !segment.startsWith(":"));
+  if (staticTail.length > 0) return camelCaseOf(staticTail.join("-"));
+  const verb = verbOfInputSchemaName(route.schemaInput);
+  if (verb !== null) return verb;
+  const endsOnParam = route.path.split("/").at(-1)?.startsWith(":") === true;
+  switch (route.method) {
+    case "GET":
+      return endsOnParam ? "get" : "list";
+    case "POST":
+      return "create";
+    case "PUT":
+    case "PATCH":
+      return "update";
+    case "DELETE":
+      return "delete";
+  }
+}
+
+export function createManifestClient(
+  manifest: unknown,
+  schemas: Record<string, z.ZodType>,
+  options: ManifestClientOptions,
+): ManifestClient {
+  const parsedManifest = ClientManifestViewSchema.safeParse(manifest);
+  if (!parsedManifest.success) {
+    refuseClient(
+      parsedManifest.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join(" ; "),
+    );
+  }
+
+  const derived: DerivedRoute[] = [];
+  const mounted = new Set<string>();
+  for (const feature of parsedManifest.data.features) {
+    for (const route of feature.routes) {
+      if (!WELL_FORMED_ROUTE_PATH.test(route.path)) {
+        refuseClient(`feature "${feature.name}": route path "${route.path}" is malformed`);
+      }
+      for (const schemaName of [route.schemaInput, route.schemaOutput]) {
+        if (schemas[schemaName] === undefined) {
+          refuseClient(
+            `feature "${feature.name}": route ${route.method} ${route.path} declares schema "${schemaName}" which is not in the schema registry`,
+          );
+        }
+      }
+      const key = `${route.method} ${route.path}`;
+      if (mounted.has(key)) refuseClient(`route ${key} is declared twice`);
+      mounted.add(key);
+
+      const segments = route.path.split("/").slice(2);
+      const root = segments[0];
+      if (root === undefined || root.startsWith(":")) {
+        refuseClient(`route ${key}: the first segment after /api must be static`);
+      }
+      const entry: DerivedRoute = {
+        method: route.method,
+        path: route.path,
+        root,
+        namespace: camelCaseOf(root),
+        operation: "",
+        paramNames: segments
+          .filter((segment) => segment.startsWith(":"))
+          .map((segment) => segment.slice(1)),
+        schemaInput: route.schemaInput,
+        schemaOutput: route.schemaOutput,
+        invalidates: route.invalidates ?? [],
+      };
+      entry.operation = deriveOperationName(entry);
+      derived.push(entry);
+    }
+  }
+
+  const client: ManifestClient = {};
+  for (const route of derived) {
+    const namespaceOperations = (client[route.namespace] ??= {});
+    if (namespaceOperations[route.operation] !== undefined) {
+      refuseClient(
+        `operation "${route.namespace}.${route.operation}" is derived twice (${route.method} ${route.path} collides) — the derivation must stay unambiguous`,
+      );
+    }
+    namespaceOperations[route.operation] = buildOperation(route, schemas, options);
+  }
+  return client;
+}
+
+function buildOperation(
+  route: DerivedRoute,
+  schemas: Record<string, z.ZodType>,
+  options: ManifestClientOptions,
+): ApiOperation {
+  const inputSchema = schemas[route.schemaInput];
+  const outputSchema = schemas[route.schemaOutput];
+  if (inputSchema === undefined || outputSchema === undefined) {
+    refuseClient(`route ${route.method} ${route.path}: schema lookup failed`); // unreachable — checked above
+  }
+
+  /** Path params consumed by name; everything else is body or query string. */
+  function splitInput(input: Record<string, unknown>): {
+    paramValues: string[];
+    rest: Record<string, unknown>;
+  } {
+    const paramValues: string[] = [];
+    const rest: Record<string, unknown> = { ...input };
+    for (const paramName of route.paramNames) {
+      const value = input[paramName];
+      if (typeof value !== "string" || value === "") {
+        throwOgygieError(
+          {
+            code: "CLIENT_MISSING_PATH_PARAM",
+            message: `Operation ${route.namespace}.${route.operation} was called without its ":${paramName}" path param.`,
+            file: null,
+            cause: `${route.method} ${route.path} needs "${paramName}", received ${JSON.stringify(value)}`,
+            suggestedFix: `Pass a non-empty string "${paramName}" in the operation input.`,
+          },
+          500,
+        );
+      }
+      paramValues.push(value);
+      delete rest[paramName];
+    }
+    return { paramValues, rest };
+  }
+
+  const call = async (input: Record<string, unknown> = {}): Promise<unknown> => {
+    const { rest } = splitInput(input);
+    let resolvedPath = route.path;
+    for (const paramName of route.paramNames) {
+      resolvedPath = resolvedPath.replace(
+        `:${paramName}`,
+        encodeURIComponent(String(input[paramName])),
+      );
+    }
+    if (METHODS_WITH_BODY.has(route.method)) {
+      return options.performRequest({
+        method: route.method,
+        path: resolvedPath,
+        body: rest,
+        outputSchema,
+      });
+    }
+    const searchParameters = new URLSearchParams();
+    for (const [name, value] of Object.entries(rest)) {
+      if (value !== undefined && value !== null) searchParameters.set(name, String(value));
+    }
+    const queryString = searchParameters.toString();
+    return options.performRequest({
+      method: route.method,
+      path: queryString === "" ? resolvedPath : `${resolvedPath}?${queryString}`,
+      outputSchema,
+    });
+  };
+
+  return Object.assign(call, {
+    method: route.method,
+    path: route.path,
+    namespace: route.namespace,
+    operation: route.operation,
+    inputSchema,
+    outputSchema,
+    isMutation: route.method !== "GET",
+    queryKey: (input: Record<string, unknown> = {}): ReadonlyArray<unknown> => {
+      const { paramValues, rest } = splitInput(input);
+      // The OPERATION is part of the key: two GET routes on the same entity
+      // (…/:id, …/:id/quantities, …/:id/costs) must never share a cache entry
+      // — without it TanStack dedupes them and the later queries never fire
+      // (found by ecrans-plan, the first consumer of sibling GET routes).
+      const key: unknown[] = [route.root, route.operation, ...paramValues];
+      if (Object.keys(rest).length > 0) key.push(rest);
+      return key;
+    },
+    invalidationRoots: [route.root, ...route.invalidates],
+  });
+}