@ogygie/studio 0.4.0 → 0.5.1

package/src/server/storage/spec-storage.ts

@@ -1,22 +0,0 @@
-/**
- * @intent The SpecStorage contract (injected dependency — declared-effects
- * principle): everything the studio reads or writes goes through this
- * interface, with paths RELATIVE to the repo root. v1 ships the local
- * filesystem adapter; a v2 github-adapter becomes an addition, not a rework.
- * `message` is the future commit message — the local adapter ignores it
- * (the dev commits by hand in v1).
- */
-
-export interface FileEntry {
-  /** File name inside the listed directory (no path separator). */
-  name: string;
-}
-
-export interface SpecStorage {
-  /** Lists the FILES of a directory (relative path); [] when it is absent. */
-  list(dir: string): Promise<FileEntry[]>;
-  /** Reads a file (relative path) as UTF-8. Rejects when it does not exist. */
-  read(path: string): Promise<string>;
-  /** Writes a file (relative path); `message` documents the intent (v2: commit). */
-  write(path: string, content: string, message: string): Promise<void>;
-}

package/src/ui/app.css

@@ -1,3 +0,0 @@
-/* @intent Tailwind v4 entry point of the studio UI — no custom theme: the
-   studio is a framework dev tool, it carries no product design tokens. */
-@import "tailwindcss";

package/src/ui/features/manifest-view/ManifestView.test.tsx

@@ -1,67 +0,0 @@
-// @vitest-environment jsdom
-/**
- * @intent Proves the manifest view behavior from specs/ogygie-studio.spec.md:
- * features, routes and dependencies displayed READ-ONLY — no write control of
- * any kind exists on this screen.
- */
-import { afterEach, describe, expect, it } from "vitest";
-import { cleanup, screen, within } from "@testing-library/react";
-import { renderStudio, stubFetch } from "../../test-utils";
-
-const MANIFEST_PAYLOAD = {
-  manifest: {
-    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: [
-      {
-        name: "notes",
-        intent: "Feature d'exemple prouvant chaque rail du framework.",
-        folder: "src/features/notes",
-        spec: "specs/notes.spec.md",
-        routes: [
-          {
-            method: "POST",
-            path: "/api/notes",
-            description: "Crée une note dans l'espace actif.",
-            schemaInput: "CreateNoteInputSchema",
-            schemaOutput: "CreateNoteOutputSchema",
-          },
-        ],
-        dbTables: ["notes"],
-        dependsOn: ["espaces-et-comptes"],
-        status: "delivered",
-      },
-      {
-        name: "espaces-et-comptes",
-        intent: "Socle SaaS multi-tenant fournissant le WorkspaceContext.",
-        folder: "src/features/espaces-et-comptes",
-        spec: "specs/espaces-et-comptes.spec.md",
-        routes: [],
-        dbTables: [],
-        dependsOn: [],
-        status: "delivered",
-      },
-    ],
-    conventions: { agentsMd: "AGENTS.md", failuresMd: "FAILURES.md", specsFolder: "specs/" },
-  },
-};
-
-describe("ogygie-studio — vue manifeste (état UI)", () => {
-  afterEach(cleanup);
-
-  it("ÉTANT DONNÉ le manifeste QUAND on ouvre la vue ALORS features, routes et dépendances s'affichent et AUCUNE action d'écriture n'existe", async () => {
-    stubFetch([{ path: "/api/manifest", payload: MANIFEST_PAYLOAD }]);
-    renderStudio("/manifest");
-
-    expect(await screen.findByText("notes")).toBeDefined();
-    expect(screen.getByText("/api/notes")).toBeDefined();
-    // The dependency appears twice: as its own feature card AND as "Dépend de".
-    expect(screen.getAllByText("espaces-et-comptes", { exact: false }).length).toBeGreaterThanOrEqual(2);
-
-    // Read-only: not a single button/input/form on the whole screen.
-    const main = screen.getByRole("main");
-    expect(within(main).queryAllByRole("button")).toHaveLength(0);
-    expect(within(main).queryAllByRole("textbox")).toHaveLength(0);
-  });
-});

package/src/ui/features/manifest-view/ManifestView.tsx

@@ -1,80 +0,0 @@
-/**
- * @intent Read-only projection of ogygie.manifest.json: product, apps,
- * features with routes and dependencies. NO write action exists on this
- * screen — the manifest belongs to feature commits, the studio only reads it.
- */
-import { useManifest } from "../../lib/queries";
-import { ErrorBanner } from "../../patterns/ErrorBanner";
-
-const STATUS_BADGES: Record<string, string> = {
-  skeleton: "bg-gray-100 text-gray-600",
-  "in-progress": "bg-amber-100 text-amber-800",
-  delivered: "bg-emerald-100 text-emerald-800",
-};
-
-export function ManifestView() {
-  const { data, isPending, error } = useManifest();
-  if (error) return <ErrorBanner error={error} />;
-  if (isPending) {
-    return <div aria-label="Chargement du manifeste" className="h-96 animate-pulse rounded-lg bg-gray-100" />;
-  }
-  const { manifest } = data;
-  return (
-    <div className="space-y-4">
-      <header>
-        <h1 className="text-lg font-semibold text-gray-900">
-          {manifest.product.name}
-          <span className="ml-2 align-middle text-xs font-normal text-gray-400">
-            manifeste en lecture seule
-          </span>
-        </h1>
-        <p className="mt-1 text-sm text-gray-600">{manifest.product.description}</p>
-      </header>
-
-      <section aria-label="Apps" className="rounded-lg border border-gray-200 bg-white p-4">
-        <h2 className="mb-2 text-sm font-semibold text-gray-700">Apps</h2>
-        <ul className="space-y-1 text-sm text-gray-700">
-          {manifest.apps.map((app) => (
-            <li key={app.name} className="flex gap-2">
-              <span className="font-mono font-medium">{app.name}</span>
-              <span className="text-gray-400">({app.type})</span>
-              <span className="font-mono text-xs text-gray-500">{app.path}</span>
-            </li>
-          ))}
-        </ul>
-      </section>
-
-      <section aria-label="Features" className="space-y-3">
-        {manifest.features.map((feature) => (
-          <article key={feature.name} className="rounded-lg border border-gray-200 bg-white p-4">
-            <div className="flex items-center justify-between gap-3">
-              <h3 className="font-mono text-sm font-semibold text-gray-900">{feature.name}</h3>
-              <span
-                className={`rounded-full px-2 py-0.5 text-xs font-medium ${STATUS_BADGES[feature.status] ?? ""}`}
-              >
-                {feature.status}
-              </span>
-            </div>
-            <p className="mt-1 text-sm text-gray-600">{feature.intent}</p>
-            {feature.dependsOn.length > 0 && (
-              <p className="mt-2 text-xs text-gray-500">
-                Dépend de :{" "}
-                <span className="font-mono">{feature.dependsOn.join(", ")}</span>
-              </p>
-            )}
-            {feature.routes.length > 0 && (
-              <ul className="mt-2 space-y-1 text-xs text-gray-600">
-                {feature.routes.map((route) => (
-                  <li key={`${route.method} ${route.path}`} className="flex gap-2">
-                    <span className="w-14 shrink-0 font-mono font-semibold">{route.method}</span>
-                    <span className="font-mono">{route.path}</span>
-                  </li>
-                ))}
-              </ul>
-            )}
-          </article>
-        ))}
-      </section>
-    </div>
-  );
-}

package/src/ui/features/spec-board/SpecBoard.test.tsx

@@ -1,92 +0,0 @@
-// @vitest-environment jsdom
-/**
- * @intent Proves the board's UI states from specs/ogygie-studio.spec.md: empty
- * (EmptyState + creation), loading (skeleton), nominal (3 status columns),
- * error (full OgygieError card per unreadable spec).
- */
-import { afterEach, describe, expect, it } from "vitest";
-import { cleanup, screen, within } from "@testing-library/react";
-import { renderStudio, stubFetch, stubFetchPending } from "../../test-utils";
-
-const READABLE = (id: string, status: string) => ({
-  id,
-  status,
-  priority: "P1",
-  depends_on: [],
-  filePath: `specs/${id}.spec.md`,
-  presentSections: ["# @intent"],
-});
-
-describe("ogygie-studio — board (états UI)", () => {
-  afterEach(cleanup);
-
-  it("ÉTANT DONNÉ aucune spec QUAND le board s'affiche ALORS EmptyState propose la création depuis le template", async () => {
-    stubFetch([{ path: "/api/specs", payload: { specs: [] } }]);
-    renderStudio("/");
-    expect(await screen.findByText("Aucune spec dans ce repo")).toBeDefined();
-    expect(screen.getByRole("button", { name: "Nouvelle spec" })).toBeDefined();
-  });
-
-  it("ÉTANT DONNÉ un chargement en cours QUAND le board s'affiche ALORS le squelette est visible", async () => {
-    stubFetchPending();
-    renderStudio("/");
-    expect(await screen.findByLabelText("Chargement du board")).toBeDefined();
-  });
-
-  it("ÉTANT DONNÉ des specs dans les trois statuts QUAND le board s'affiche ALORS chaque spec est dans sa colonne de statut", async () => {
-    stubFetch([
-      {
-        path: "/api/specs",
-        payload: {
-          specs: [
-            READABLE("alpha", "draft"),
-            READABLE("beta", "validated"),
-            READABLE("gamma", "implemented"),
-          ],
-        },
-      },
-    ]);
-    renderStudio("/");
-
-    const draftColumn = await screen.findByLabelText("Colonne Draft");
-    expect(within(draftColumn).getByText("alpha")).toBeDefined();
-    const validatedColumn = screen.getByLabelText("Colonne Validated");
-    expect(within(validatedColumn).getByText("beta")).toBeDefined();
-    const implementedColumn = screen.getByLabelText("Colonne Implemented");
-    expect(within(implementedColumn).getByText("gamma")).toBeDefined();
-  });
-
-  it("ÉTANT DONNÉ une spec au frontmatter invalide QUAND le board s'affiche ALORS sa carte d'erreur porte l'OgygieError en entier", async () => {
-    stubFetch([
-      {
-        path: "/api/specs",
-        payload: {
-          specs: [
-            READABLE("alpha", "draft"),
-            {
-              id: "broken",
-              filePath: "specs/broken.spec.md",
-              error: {
-                ogygie: true,
-                code: "SPEC_FRONTMATTER_INVALID",
-                message: "Spec specs/broken.spec.md has an invalid frontmatter.",
-                file: "specs/broken.spec.md",
-                cause: "status: nonsense is not a valid status",
-                suggestedFix: "Fix the frontmatter in your editor.",
-                details: {},
-                timestamp: "2026-08-23T00:00:00.000Z",
-              },
-            },
-          ],
-        },
-      },
-    ]);
-    renderStudio("/");
-
-    expect(await screen.findByText("SPEC_FRONTMATTER_INVALID")).toBeDefined();
-    expect(screen.getByText("status: nonsense is not a valid status")).toBeDefined();
-    expect(screen.getByText("Fix the frontmatter in your editor.")).toBeDefined();
-    // The readable spec still sits in its column next to the error card.
-    expect(screen.getByText("alpha")).toBeDefined();
-  });
-});

package/src/ui/features/spec-board/SpecBoard.tsx

@@ -1,198 +0,0 @@
-/**
- * @intent The spec board: one kanban column per status (draft / validated /
- * implemented), unreadable specs surfaced as FULL error cards above the board
- * (never repaired, never hidden), and spec creation from the template. Pure
- * composition of patterns over useSpecs — zero business logic.
- */
-import { useState } from "react";
-import { Link, useNavigate } from "@tanstack/react-router";
-import { StudioApiError } from "../../lib/fetchContract";
-import { useCreateSpec, useSpecs } from "../../lib/queries";
-import { EmptyState } from "../../patterns/EmptyState";
-import { ErrorBanner, OgygieErrorCard } from "../../patterns/ErrorBanner";
-import { Modal } from "../../patterns/Modal";
-import type {
-  ReadableSpecSummary,
-  SpecStatus,
-  SpecSummary,
-  UnreadableSpecSummary,
-} from "../../../server/schemas";
-
-const COLUMNS: { status: SpecStatus; title: string; accent: string }[] = [
-  { status: "draft", title: "Draft", accent: "border-t-amber-400" },
-  { status: "validated", title: "Validated", accent: "border-t-emerald-500" },
-  { status: "implemented", title: "Implemented", accent: "border-t-sky-500" },
-];
-
-function isReadable(summary: SpecSummary): summary is ReadableSpecSummary {
-  return !("error" in summary);
-}
-
-export function SpecBoard() {
-  const { data, isPending, error } = useSpecs();
-  if (error) return <ErrorBanner error={error} />;
-  if (isPending) return <BoardSkeleton />;
-
-  const readable = data.specs.filter(isReadable);
-  const unreadable = data.specs.filter(
-    (summary): summary is UnreadableSpecSummary => !isReadable(summary),
-  );
-
-  if (data.specs.length === 0) {
-    return (
-      <EmptyState
-        title="Aucune spec dans ce repo"
-        hint="Créez la première depuis le template canonique — elle naîtra en draft."
-        action={<NewSpecButton />}
-      />
-    );
-  }
-
-  return (
-    <div className="space-y-4">
-      <div className="flex items-center justify-between">
-        <h1 className="text-lg font-semibold text-gray-900">Specs</h1>
-        <NewSpecButton />
-      </div>
-      {unreadable.length > 0 && (
-        <section aria-label="Specs illisibles" className="space-y-2">
-          {unreadable.map((summary) => (
-            <OgygieErrorCard key={summary.filePath} error={summary.error} />
-          ))}
-        </section>
-      )}
-      <div className="grid grid-cols-1 gap-4 md:grid-cols-3">
-        {COLUMNS.map((column) => (
-          <BoardColumn
-            key={column.status}
-            title={column.title}
-            accent={column.accent}
-            specs={readable.filter((summary) => summary.status === column.status)}
-          />
-        ))}
-      </div>
-    </div>
-  );
-}
-
-function BoardColumn({
-  title,
-  accent,
-  specs,
-}: {
-  title: string;
-  accent: string;
-  specs: ReadableSpecSummary[];
-}) {
-  return (
-    <section
-      aria-label={`Colonne ${title}`}
-      className={`rounded-lg border border-gray-200 border-t-4 bg-gray-50 p-3 ${accent}`}
-    >
-      <h2 className="mb-3 flex items-baseline justify-between text-sm font-semibold text-gray-700">
-        {title}
-        <span className="text-xs font-normal text-gray-400">{specs.length}</span>
-      </h2>
-      <ul className="space-y-2">
-        {specs.map((summary) => (
-          <li key={summary.id}>
-            <Link
-              to="/specs/$specId"
-              params={{ specId: summary.id }}
-              className="block rounded-md border border-gray-200 bg-white p-3 shadow-sm hover:border-gray-400"
-            >
-              <p className="font-mono text-sm font-medium text-gray-900">{summary.id}</p>
-              <p className="mt-1 text-xs text-gray-500">
-                {summary.priority} · {summary.presentSections.length}/6 sections
-                {summary.depends_on.length > 0 && ` · dépend de ${summary.depends_on.join(", ")}`}
-              </p>
-            </Link>
-          </li>
-        ))}
-      </ul>
-    </section>
-  );
-}
-
-function BoardSkeleton() {
-  return (
-    <div aria-label="Chargement du board" className="grid grid-cols-1 gap-4 md:grid-cols-3">
-      {[0, 1, 2].map((column) => (
-        <div key={column} className="h-64 animate-pulse rounded-lg border border-gray-200 bg-gray-100" />
-      ))}
-    </div>
-  );
-}
-
-function NewSpecButton() {
-  const [open, setOpen] = useState(false);
-  const [specId, setSpecId] = useState("");
-  const navigate = useNavigate();
-  const creation = useCreateSpec();
-
-  const submit = () => {
-    creation.mutate(
-      { id: specId },
-      {
-        onSuccess: async (created) => {
-          setOpen(false);
-          await navigate({ to: "/specs/$specId", params: { specId: created.spec.id } });
-        },
-      },
-    );
-  };
-
-  return (
-    <>
-      <button
-        type="button"
-        onClick={() => {
-          creation.reset();
-          setSpecId("");
-          setOpen(true);
-        }}
-        className="rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white hover:bg-gray-700"
-      >
-        Nouvelle spec
-      </button>
-      <Modal open={open} title="Nouvelle spec depuis le template" onClose={() => setOpen(false)}>
-        <form
-          onSubmit={(event) => {
-            event.preventDefault();
-            submit();
-          }}
-          className="space-y-3"
-        >
-          <label className="block text-sm text-gray-700">
-            Identifiant (kebab-case, il nomme le fichier specs/&lt;id&gt;.spec.md)
-            <input
-              value={specId}
-              onChange={(event) => setSpecId(event.target.value)}
-              placeholder="ma-nouvelle-feature"
-              className="mt-1 w-full rounded-md border border-gray-300 px-2 py-1.5 font-mono text-sm"
-            />
-          </label>
-          {creation.error instanceof StudioApiError && (
-            <ErrorBanner error={creation.error} />
-          )}
-          <div className="flex justify-end gap-2">
-            <button
-              type="button"
-              onClick={() => setOpen(false)}
-              className="rounded-md border border-gray-300 px-3 py-1.5 text-sm text-gray-700"
-            >
-              Annuler
-            </button>
-            <button
-              type="submit"
-              disabled={creation.isPending || specId === ""}
-              className="rounded-md bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
-            >
-              Créer en draft
-            </button>
-          </div>
-        </form>
-      </Modal>
-    </>
-  );
-}

package/src/ui/features/spec-editor/MarkdownPreview.tsx

@@ -1,49 +0,0 @@
-/**
- * @intent Renders the parsed markdown blocks as React elements — never an HTML
- * string (dangerouslySetInnerHTML is banned repo-wide). Minimal on purpose:
- * the preview reassures the writer, the file stays the source of truth.
- */
-import { parseMarkdownBlocks } from "./markdown-blocks";
-
-const HEADING_CLASSES: Record<number, string> = {
-  1: "text-base font-bold text-gray-900 mt-4 first:mt-0",
-  2: "text-sm font-bold text-gray-900 mt-3",
-};
-
-export function MarkdownPreview({ markdown }: { markdown: string }) {
-  const blocks = parseMarkdownBlocks(markdown);
-  return (
-    <div className="space-y-2">
-      {blocks.map((block, index) => {
-        if (block.kind === "heading") {
-          return (
-            <p key={index} className={HEADING_CLASSES[Math.min(block.level, 2)]}>
-              {block.text}
-            </p>
-          );
-        }
-        if (block.kind === "bullet") {
-          return (
-            <ul key={index} className="list-disc space-y-1 pl-5 text-sm text-gray-700">
-              {block.items.map((item, itemIndex) => (
-                <li key={itemIndex}>{item}</li>
-              ))}
-            </ul>
-          );
-        }
-        if (block.kind === "code") {
-          return (
-            <pre key={index} className="overflow-x-auto rounded bg-gray-100 p-2 font-mono text-xs text-gray-800">
-              {block.text}
-            </pre>
-          );
-        }
-        return (
-          <p key={index} className="text-sm text-gray-700">
-            {block.text}
-          </p>
-        );
-      })}
-    </div>
-  );
-}

package/src/ui/features/spec-editor/SpecEditor.test.tsx

@@ -1,79 +0,0 @@
-// @vitest-environment jsdom
-/**
- * @intent Proves the editor's UI state from specs/ogygie-studio.spec.md:
- * schema-derived frontmatter form + side-by-side markdown preview, and the
- * validation refusal (SPEC_SECTION_MISSING) displayed as the full OgygieError
- * without any status change.
- */
-import { afterEach, describe, expect, it } from "vitest";
-import { cleanup, fireEvent, screen } from "@testing-library/react";
-import { renderStudio, stubFetch } from "../../test-utils";
-
-const SPEC_PAYLOAD = {
-  frontmatter: {
-    id: "alpha",
-    status: "draft",
-    depends_on: [],
-    priority: "P1",
-    refs: [],
-    deferred: [],
-  },
-  body: "\n# @intent\nLe pourquoi.\n\n# Comportements\n- ÉTANT DONNÉ x\n",
-  presentSections: ["# @intent", "# Comportements"],
-};
-
-describe("ogygie-studio — éditeur (état UI)", () => {
-  afterEach(cleanup);
-
-  it("ÉTANT DONNÉ une spec en draft QUAND l'éditeur s'ouvre ALORS le formulaire est dérivé du schéma et la preview rend le markdown à côté", async () => {
-    stubFetch([{ path: "/api/specs/alpha", payload: SPEC_PAYLOAD }]);
-    renderStudio("/specs/alpha");
-
-    // Schema-derived form: the status enum options come from the schema.
-    const statusSelect = await screen.findByRole("combobox", { name: /status/ });
-    const options = Array.from(statusSelect.querySelectorAll("option")).map(
-      (option) => option.value,
-    );
-    expect(options).toEqual(["draft", "validated", "implemented"]);
-
-    // Side-by-side: the textarea holds the raw markdown, the preview renders it.
-    const bodyArea = screen.getByRole("textbox", { name: /sections \(markdown\)/ });
-    expect(bodyArea).toHaveProperty("value", SPEC_PAYLOAD.body);
-    expect(screen.getByText("@intent")).toBeDefined(); // preview heading
-    expect(screen.getByText("Le pourquoi.")).toBeDefined();
-    expect(screen.getByRole("button", { name: "Valider" })).toBeDefined();
-  });
-
-  it("ÉTANT DONNÉ une section obligatoire manquante QUAND on confirme « Valider » ALORS l'OgygieError SPEC_SECTION_MISSING s'affiche en entier", async () => {
-    stubFetch([
-      { path: "/api/specs/alpha", payload: SPEC_PAYLOAD },
-      {
-        method: "PUT",
-        path: "/api/specs/alpha",
-        status: 409,
-        payload: {
-          ogygie: true,
-          code: "SPEC_SECTION_MISSING",
-          message: "Spec alpha cannot be validated: 4 mandatory section(s) missing.",
-          file: "specs/alpha.spec.md",
-          cause: "missing or out-of-order: # Contrats de données ; # États UI ; # Non-objectifs ; # Budget",
-          suggestedFix: "Write the missing sections (in canonical order) before validating.",
-          details: { missingSections: ["# Contrats de données", "# États UI", "# Non-objectifs", "# Budget"] },
-          timestamp: "2026-08-23T00:00:00.000Z",
-        },
-      },
-    ]);
-    renderStudio("/specs/alpha");
-
-    fireEvent.click(await screen.findByRole("button", { name: "Valider" }));
-    fireEvent.click(await screen.findByRole("button", { name: "Confirmer la validation" }));
-
-    expect(await screen.findByText("SPEC_SECTION_MISSING")).toBeDefined();
-    expect(
-      screen.getByText(/# Contrats de données ; # États UI ; # Non-objectifs ; # Budget/),
-    ).toBeDefined();
-    expect(
-      screen.getByText("Write the missing sections (in canonical order) before validating."),
-    ).toBeDefined();
-  });
-});