@ogygie/studio 0.5.0 → 0.5.2

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ogygie/studio",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Ogygie framework dev studio: projects a repo's specs and manifest into a local UI. Ships its built UI; launched by `ogygie studio`.",
   "license": "MIT",
   "type": "module",
   "files": [
-    "src",
+    "dist",
     "dist-ui",
     "README.md",
     "LICENSE"
@@ -14,15 +14,14 @@
     "access": "public"
   },
   "exports": {
-    ".": "./src/index.ts",
-    "./server": "./src/server/start.ts"
+    "./server": "./dist/server.js"
   },
   "dependencies": {
     "@fastify/static": "^10.1.3",
     "fastify": "^5.0.0",
     "fastify-type-provider-zod": "^6.0.0",
     "zod": "^4.0.0",
-    "@ogygie/core": "0.5.0"
+    "@ogygie/core": "0.5.2"
   },
   "devDependencies": {
     "@tailwindcss/vite": "^4.3.3",
@@ -34,18 +33,19 @@
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.4",
     "@vitejs/plugin-react": "^5.2.0",
+    "esbuild": "^0.28.0",
     "jsdom": "^30.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.3",
     "tsx": "^4.20.0",
     "typescript": "^5.8.0",
-    "vitest": "^3.2.0",
-    "vite": "^7.3.6"
+    "vite": "^7.3.6",
+    "vitest": "^3.2.0"
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build",
+    "build": "vite build && tsx scripts/build-server.ts",
     "typecheck": "tsc -p tsconfig.json"
   }
 }

package/src/index.ts

@@ -1,41 +0,0 @@
-/**
- * @intent SOLE public export point of the ogygie-studio feature: the launcher,
- * the Fastify app factory (embedded/test use), the SpecStorage contract with
- * its two adapters, and the API contracts shared with the UI.
- */
-export { startStudio, type StartStudioOptions } from "./server/start.js";
-export { createStudioApp, type StudioAppOptions } from "./server/app.js";
-export type { FileEntry, SpecStorage } from "./server/storage/spec-storage.js";
-export { createLocalSpecStorage } from "./server/storage/local-adapter.js";
-export {
-  createMemorySpecStorage,
-  type MemorySpecStorage,
-} from "./server/storage/memory-adapter.js";
-export {
-  CreateSpecInputSchema,
-  CreateSpecOutputSchema,
-  GetManifestOutputSchema,
-  GetSpecOutputSchema,
-  ListSpecsOutputSchema,
-  ReadableSpecSummarySchema,
-  SpecParamsSchema,
-  SpecStatusSchema,
-  SpecSummarySchema,
-  UnreadableSpecSummarySchema,
-  UpdateSpecInputSchema,
-  UpdateSpecOutputSchema,
-} from "./server/schemas.js";
-export type {
-  CreateSpecInput,
-  CreateSpecOutput,
-  GetManifestOutput,
-  GetSpecOutput,
-  ListSpecsOutput,
-  ReadableSpecSummary,
-  SpecParams,
-  SpecStatus,
-  SpecSummary,
-  UnreadableSpecSummary,
-  UpdateSpecInput,
-  UpdateSpecOutput,
-} from "./server/schemas.js";

package/src/server/app.ts

@@ -1,84 +0,0 @@
-/**
- * @intent Fastify bootstrap of the studio server: Zod compilers, the OgygieError
- * handler (only contract fields ever reach the client — never a stack trace),
- * the studio API routes, and the built UI served statically with an SPA
- * fallback. No helmet/rate-limit/session on purpose: the studio binds
- * 127.0.0.1 only (see start.ts), is single-user by spec (non-objectifs), and
- * relays no product data — the product bootstrap rules target apps/api.
- */
-import Fastify, { type FastifyInstance } from "fastify";
-import {
-  hasZodFastifySchemaValidationErrors,
-  serializerCompiler,
-  validatorCompiler,
-} from "fastify-type-provider-zod";
-import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
-import type { StudioDeps } from "./service.js";
-import { registerStudioRoutes } from "./routes.js";
-
-export interface StudioAppOptions extends StudioDeps {
-  /** Absolute path of the built UI (dist-ui); omitted in API-only tests. */
-  uiDistDir?: string | undefined;
-}
-
-export async function createStudioApp(options: StudioAppOptions): Promise<FastifyInstance> {
-  const app = Fastify({ logger: false });
-  app.setValidatorCompiler(validatorCompiler);
-  app.setSerializerCompiler(serializerCompiler);
-
-  app.setErrorHandler((error, _request, reply) => {
-    if (error instanceof OgygieFailure) {
-      return reply.status(error.httpStatus).send(error.error);
-    }
-    if (hasZodFastifySchemaValidationErrors(error)) {
-      return reply.status(400).send(
-        ogygieError({
-          code: "CONTRACT_VALIDATION_FAILED",
-          message: "The request does not satisfy the route's input contract.",
-          file: null,
-          cause: error.validation
-            .map((issue) => `${issue.instancePath || "(root)"}: ${issue.message ?? "invalid"}`)
-            .join(" ; "),
-          suggestedFix: "Fix the listed fields to match the route's Zod input schema.",
-        }),
-      );
-    }
-    // Unknown error: log server-side, leak nothing.
-    app.log.error(error);
-    return reply.status(500).send(
-      ogygieError({
-        code: "INTERNAL_ERROR",
-        message: "Unexpected studio error — details are in the server logs only.",
-        file: null,
-        cause: "unhandled exception",
-        suggestedFix: "Relaunch `pnpm ogygie studio`; record a FAILURES.md entry if it recurs.",
-      }),
-    );
-  });
-
-  await registerStudioRoutes(app, options);
-
-  if (options.uiDistDir !== undefined) {
-    const fastifyStatic = (await import("@fastify/static")).default;
-    await app.register(fastifyStatic, { root: options.uiDistDir });
-    // SPA fallback: every non-API GET renders the UI shell, whose router owns
-    // the path (/specs/<id>, /manifest…).
-    app.setNotFoundHandler((request, reply) => {
-      if (request.method === "GET" && !request.url.startsWith("/api/")) {
-        return reply.sendFile("index.html");
-      }
-      return reply.status(404).send(
-        ogygieError({
-          code: "ROUTE_NOT_FOUND",
-          message: "No studio route matches this request.",
-          file: null,
-          cause: `${request.method} ${request.url}`,
-          suggestedFix: "Use the routes documented in specs/ogygie-studio.spec.md.",
-        }),
-      );
-    });
-  }
-
-  await app.ready();
-  return app;
-}

package/src/server/routes.test.ts

@@ -1,164 +0,0 @@
-/**
- * @intent Proves the HTTP surface described in specs/ogygie-studio.spec.md:
- * every internal route with its contracts and error statuses, via
- * fastify.inject over the in-memory SpecStorage (no port, no fs).
- */
-import { afterAll, beforeAll, describe, expect, it } from "vitest";
-import type { FastifyInstance } from "fastify";
-import { createStudioApp } from "./app.js";
-import { createMemorySpecStorage, type MemorySpecStorage } from "./storage/memory-adapter.js";
-
-const TEMPLATE = [
-  "---",
-  "id: nom-de-la-feature",
-  "status: draft",
-  "depends_on: []",
-  "priority: P1",
-  "refs: []",
-  "---",
-  "",
-  "# @intent",
-  "x",
-  "",
-  "# Comportements",
-  "x",
-  "",
-  "# Contrats de données",
-  "x",
-  "",
-  "# États UI",
-  "x",
-  "",
-  "# Non-objectifs",
-  "x",
-  "",
-  "# Budget",
-  "x",
-  "",
-].join("\n");
-
-const DRAFT_SPEC = TEMPLATE.replace("id: nom-de-la-feature", "id: alpha");
-
-const MANIFEST = JSON.stringify({
-  version: 1,
-  product: { name: "starter", description: "Squelette de produit Ogygie pour les tests." },
-  apps: [{ name: "api", path: "apps/api", type: "api", entryPoint: "apps/api/src/server.ts" }],
-  features: [],
-  conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
-});
-
-describe("ogygie-studio — routes", () => {
-  let app: FastifyInstance;
-  let storage: MemorySpecStorage;
-
-  beforeAll(async () => {
-    storage = createMemorySpecStorage({
-      "specs/_TEMPLATE.spec.md": TEMPLATE,
-      "specs/alpha.spec.md": DRAFT_SPEC,
-      "ogygie.manifest.json": MANIFEST,
-    });
-    app = await createStudioApp({ storage });
-  });
-
-  afterAll(async () => {
-    await app.close();
-  });
-
-  it("ÉTANT DONNÉ un repo valide QUAND GET /api/specs ALORS 200 et le résumé de chaque spec", async () => {
-    const response = await app.inject({ method: "GET", url: "/api/specs" });
-    expect(response.statusCode).toBe(200);
-    const payload = response.json();
-    expect(payload.specs).toEqual([
-      expect.objectContaining({ id: "alpha", status: "draft" }),
-    ]);
-  });
-
-  it("ÉTANT DONNÉ une spec lisible QUAND GET /api/specs/:id ALORS 200 avec frontmatter, body et sections présentes", async () => {
-    const response = await app.inject({ method: "GET", url: "/api/specs/alpha" });
-    expect(response.statusCode).toBe(200);
-    const payload = response.json();
-    expect(payload.frontmatter).toMatchObject({ id: "alpha", status: "draft" });
-    expect(payload.presentSections).toHaveLength(6);
-    expect(payload.body).toContain("# Budget");
-  });
-
-  it("ÉTANT DONNÉ un id inconnu QUAND GET /api/specs/:id ALORS 404 SPEC_NOT_FOUND", async () => {
-    const response = await app.inject({ method: "GET", url: "/api/specs/fantome" });
-    expect(response.statusCode).toBe(404);
-    expect(response.json().code).toBe("SPEC_NOT_FOUND");
-  });
-
-  it("ÉTANT DONNÉ un body hors contrat QUAND PUT /api/specs/:id ALORS 400 CONTRACT_VALIDATION_FAILED", async () => {
-    const response = await app.inject({
-      method: "PUT",
-      url: "/api/specs/alpha",
-      payload: { frontmatter: { id: "alpha" } },
-    });
-    expect(response.statusCode).toBe(400);
-    expect(response.json().code).toBe("CONTRACT_VALIDATION_FAILED");
-  });
-
-  it("ÉTANT DONNÉ une spec draft complète QUAND PUT la valide ALORS 200, statut validated, message d'écriture \"spec: validate alpha\"", async () => {
-    const current = (await app.inject({ method: "GET", url: "/api/specs/alpha" })).json();
-    const response = await app.inject({
-      method: "PUT",
-      url: "/api/specs/alpha",
-      payload: { frontmatter: { ...current.frontmatter, status: "validated" } },
-    });
-    expect(response.statusCode).toBe(200);
-    expect(response.json().spec.status).toBe("validated");
-    expect(storage.messages).toContain("spec: validate alpha");
-  });
-
-  it("ÉTANT DONNÉ une spec validated QUAND PUT force status implemented ALORS 409 STUDIO_TRANSITION_FORBIDDEN", async () => {
-    const current = (await app.inject({ method: "GET", url: "/api/specs/alpha" })).json();
-    const response = await app.inject({
-      method: "PUT",
-      url: "/api/specs/alpha",
-      payload: { frontmatter: { ...current.frontmatter, status: "implemented" } },
-    });
-    expect(response.statusCode).toBe(409);
-    expect(response.json().code).toBe("STUDIO_TRANSITION_FORBIDDEN");
-  });
-
-  it("ÉTANT DONNÉ le board QUAND POST /api/specs avec un id kebab-case ALORS 201 et la spec naît en draft ; un doublon répond 409 SPEC_ALREADY_EXISTS", async () => {
-    const created = await app.inject({
-      method: "POST",
-      url: "/api/specs",
-      payload: { id: "ma-feature" },
-    });
-    expect(created.statusCode).toBe(201);
-    expect(created.json().spec).toMatchObject({ id: "ma-feature", status: "draft" });
-
-    const duplicate = await app.inject({
-      method: "POST",
-      url: "/api/specs",
-      payload: { id: "ma-feature" },
-    });
-    expect(duplicate.statusCode).toBe(409);
-    expect(duplicate.json().code).toBe("SPEC_ALREADY_EXISTS");
-  });
-
-  it("ÉTANT DONNÉ un id non kebab-case QUAND POST /api/specs ALORS 400 CONTRACT_VALIDATION_FAILED", async () => {
-    const response = await app.inject({
-      method: "POST",
-      url: "/api/specs",
-      payload: { id: "Pas Kebab" },
-    });
-    expect(response.statusCode).toBe(400);
-    expect(response.json().code).toBe("CONTRACT_VALIDATION_FAILED");
-  });
-
-  it("ÉTANT DONNÉ le manifeste QUAND GET /api/manifest ALORS 200 en lecture seule (aucune route d'écriture du manifeste n'existe)", async () => {
-    const response = await app.inject({ method: "GET", url: "/api/manifest" });
-    expect(response.statusCode).toBe(200);
-    expect(response.json().manifest.product.name).toBe("starter");
-
-    const write = await app.inject({
-      method: "PUT",
-      url: "/api/manifest",
-      payload: {},
-    });
-    expect(write.statusCode).toBe(404);
-  });
-});

package/src/server/routes.ts

@@ -1,87 +0,0 @@
-/**
- * @intent HTTP endpoints of the studio's internal localhost API.
- * No business logic here: schema validation + delegation to the service.
- * These routes are NEVER declared in ogygie.manifest.json nor mounted by a
- * product gateway — the studio is a dev tool, not a product surface.
- */
-import type { FastifyInstance } from "fastify";
-import type { ZodTypeProvider } from "fastify-type-provider-zod";
-import type { StudioDeps } from "./service.js";
-import {
-  createSpec,
-  getManifest,
-  getSpec,
-  listSpecSummaries,
-  saveSpec,
-} from "./service.js";
-import {
-  CreateSpecInputSchema,
-  CreateSpecOutputSchema,
-  GetManifestOutputSchema,
-  GetSpecOutputSchema,
-  ListSpecsOutputSchema,
-  SpecParamsSchema,
-  UpdateSpecInputSchema,
-  UpdateSpecOutputSchema,
-} from "./schemas.js";
-
-export async function registerStudioRoutes(
-  app: FastifyInstance,
-  deps: StudioDeps,
-): Promise<void> {
-  const route = app.withTypeProvider<ZodTypeProvider>();
-
-  route.route({
-    method: "GET",
-    url: "/api/specs",
-    schema: { response: { 200: ListSpecsOutputSchema } },
-    handler: async (_request, reply) => {
-      return reply.code(200).send({ specs: await listSpecSummaries(deps) });
-    },
-  });
-
-  route.route({
-    method: "GET",
-    url: "/api/specs/:specId",
-    schema: { params: SpecParamsSchema, response: { 200: GetSpecOutputSchema } },
-    handler: async (request, reply) => {
-      return reply.code(200).send(await getSpec(deps, request.params.specId));
-    },
-  });
-
-  route.route({
-    method: "PUT",
-    url: "/api/specs/:specId",
-    schema: {
-      params: SpecParamsSchema,
-      body: UpdateSpecInputSchema,
-      response: { 200: UpdateSpecOutputSchema },
-    },
-    handler: async (request, reply) => {
-      const spec = await saveSpec(deps, request.params.specId, request.body);
-      return reply.code(200).send({ spec });
-    },
-  });
-
-  route.route({
-    method: "POST",
-    url: "/api/specs",
-    schema: {
-      body: CreateSpecInputSchema,
-      response: { 201: CreateSpecOutputSchema },
-    },
-    handler: async (request, reply) => {
-      const spec = await createSpec(deps, request.body.id);
-      return reply.code(201).send({ spec });
-    },
-  });
-
-  route.route({
-    method: "GET",
-    url: "/api/manifest",
-    schema: { response: { 200: GetManifestOutputSchema } },
-    handler: async (_request, reply) => {
-      return reply.code(200).send({ manifest: await getManifest(deps) });
-    },
-  });
-}

package/src/server/schemas.ts

@@ -1,92 +0,0 @@
-/**
- * @intent Data contracts of the ogygie-studio feature: the studio's internal
- * localhost API (never mounted by a product gateway). Single source of truth
- * shared by the Fastify server and the studio UI: runtime validation + TS
- * types + documentation. The frontmatter contract itself is NOT redefined
- * here — the studio projects @ogygie/core/spec, it never forks it.
- */
-import { z } from "zod";
-import { FeatureNameSchema, OgygieManifestSchema } from "@ogygie/core/manifest";
-import { OgygieErrorSchema } from "@ogygie/core/errors";
-import { SpecFrontmatterSchema } from "@ogygie/core/spec";
-
-export const SpecStatusSchema = SpecFrontmatterSchema.shape.status;
-export type SpecStatus = z.infer<typeof SpecStatusSchema>;
-
-/**
- * Summary of one spec file for the board. A spec whose frontmatter cannot be
- * read has NO trustworthy status/priority: it becomes an error card carrying
- * the full OgygieError instead — never silently repaired nor hidden.
- */
-export const ReadableSpecSummarySchema = z.object({
-  id: FeatureNameSchema,
-  status: SpecStatusSchema,
-  priority: SpecFrontmatterSchema.shape.priority,
-  depends_on: z.array(FeatureNameSchema),
-  filePath: z.string(),
-  presentSections: z.array(z.string()),
-});
-export type ReadableSpecSummary = z.infer<typeof ReadableSpecSummarySchema>;
-
-export const UnreadableSpecSummarySchema = z.object({
-  id: z.string(),
-  filePath: z.string(),
-  error: OgygieErrorSchema,
-});
-export type UnreadableSpecSummary = z.infer<typeof UnreadableSpecSummarySchema>;
-
-export const SpecSummarySchema = z.union([
-  ReadableSpecSummarySchema,
-  UnreadableSpecSummarySchema,
-]);
-export type SpecSummary = z.infer<typeof SpecSummarySchema>;
-
-// ---------------------------------------------------------------- GET /api/specs
-export const ListSpecsOutputSchema = z.object({
-  specs: z.array(SpecSummarySchema),
-});
-export type ListSpecsOutput = z.infer<typeof ListSpecsOutputSchema>;
-
-// ---------------------------------------------------------- GET /api/specs/:specId
-export const SpecParamsSchema = z.object({
-  specId: FeatureNameSchema,
-});
-export type SpecParams = z.infer<typeof SpecParamsSchema>;
-
-export const GetSpecOutputSchema = z.object({
-  frontmatter: SpecFrontmatterSchema,
-  /** Markdown body after the frontmatter block, byte-exact. */
-  body: z.string(),
-  presentSections: z.array(z.string()),
-});
-export type GetSpecOutput = z.infer<typeof GetSpecOutputSchema>;
-
-// ---------------------------------------------------------- PUT /api/specs/:specId
-export const UpdateSpecInputSchema = z.object({
-  frontmatter: SpecFrontmatterSchema,
-  /** Omitted ⇒ the existing markdown body is preserved byte-exact. */
-  body: z.string().max(200_000).optional(),
-});
-export type UpdateSpecInput = z.infer<typeof UpdateSpecInputSchema>;
-
-export const UpdateSpecOutputSchema = z.object({
-  spec: ReadableSpecSummarySchema,
-});
-export type UpdateSpecOutput = z.infer<typeof UpdateSpecOutputSchema>;
-
-// ---------------------------------------------------------------- POST /api/specs
-export const CreateSpecInputSchema = z.object({
-  id: FeatureNameSchema.max(80),
-});
-export type CreateSpecInput = z.infer<typeof CreateSpecInputSchema>;
-
-export const CreateSpecOutputSchema = z.object({
-  spec: ReadableSpecSummarySchema,
-});
-export type CreateSpecOutput = z.infer<typeof CreateSpecOutputSchema>;
-
-// -------------------------------------------------------------- GET /api/manifest
-export const GetManifestOutputSchema = z.object({
-  manifest: OgygieManifestSchema,
-});
-export type GetManifestOutput = z.infer<typeof GetManifestOutputSchema>;