@ogygie/studio 0.4.0 → 0.5.1

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

@@ -1,237 +0,0 @@
-/**
- * @intent The spec editor: frontmatter form DERIVED from SpecFrontmatterSchema
- * (never hand-described), markdown body as textarea with a side-by-side
- * preview (v1 decision recorded in the spec's non-objectifs), explicit
- * validation with confirmation. Every server refusal (missing section,
- * forbidden transition) is displayed as the full OgygieError.
- */
-import { useState } from "react";
-import { Link } from "@tanstack/react-router";
-import { SpecFrontmatterSchema, type SpecFrontmatter } from "@ogygie/core/spec";
-import { useSaveSpec, useSpec } from "../../lib/queries";
-import { ErrorBanner } from "../../patterns/ErrorBanner";
-import { Modal } from "../../patterns/Modal";
-import {
-  deriveFrontmatterFields,
-  fromFormState,
-  toFormState,
-  type FrontmatterFormState,
-} from "./frontmatter-fields";
-import { MarkdownPreview } from "./MarkdownPreview";
-
-export function SpecEditor({ specId }: { specId: string }) {
-  const { data, isPending, error } = useSpec(specId);
-  if (error) {
-    return (
-      <div className="space-y-3">
-        <BackLink />
-        <ErrorBanner error={error} />
-      </div>
-    );
-  }
-  if (isPending) {
-    return <div aria-label="Chargement de la spec" className="h-96 animate-pulse rounded-lg bg-gray-100" />;
-  }
-  return (
-    <EditorForm
-      key={specId}
-      specId={specId}
-      initialFrontmatter={data.frontmatter}
-      initialBody={data.body}
-    />
-  );
-}
-
-function BackLink() {
-  return (
-    <Link to="/" className="text-sm text-gray-500 hover:text-gray-900">
-      ← Retour au board
-    </Link>
-  );
-}
-
-function EditorForm({
-  specId,
-  initialFrontmatter,
-  initialBody,
-}: {
-  specId: string;
-  initialFrontmatter: SpecFrontmatter;
-  initialBody: string;
-}) {
-  const fields = deriveFrontmatterFields();
-  const [formState, setFormState] = useState<FrontmatterFormState>(() =>
-    toFormState(initialFrontmatter),
-  );
-  const [body, setBody] = useState(initialBody);
-  const [localError, setLocalError] = useState<string | null>(null);
-  const [confirming, setConfirming] = useState(false);
-  const save = useSaveSpec(specId);
-
-  const setField = (name: keyof FrontmatterFormState, value: string) => {
-    setFormState((state) => ({ ...state, [name]: value }));
-  };
-
-  /** Rebuilds and validates the frontmatter with the SHARED schema. */
-  const candidateFrontmatter = (): SpecFrontmatter | null => {
-    const parsed = SpecFrontmatterSchema.safeParse(fromFormState(formState));
-    if (!parsed.success) {
-      setLocalError(
-        parsed.error.issues
-          .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
-          .join(" ; "),
-      );
-      return null;
-    }
-    setLocalError(null);
-    return parsed.data;
-  };
-
-  const saveDraft = () => {
-    const frontmatter = candidateFrontmatter();
-    if (frontmatter === null) return;
-    save.mutate({ frontmatter, body });
-  };
-
-  const confirmValidation = () => {
-    const frontmatter = candidateFrontmatter();
-    if (frontmatter === null) {
-      setConfirming(false);
-      return;
-    }
-    save.mutate(
-      { frontmatter: { ...frontmatter, status: "validated" }, body },
-      { onSettled: () => setConfirming(false) },
-    );
-  };
-
-  return (
-    <div className="space-y-4">
-      <div className="flex items-center justify-between">
-        <div>
-          <BackLink />
-          <h1 className="font-mono text-lg font-semibold text-gray-900">{specId}</h1>
-        </div>
-        <div className="flex gap-2">
-          <button
-            type="button"
-            onClick={saveDraft}
-            disabled={save.isPending}
-            className="rounded-md border border-gray-300 px-3 py-1.5 text-sm font-medium text-gray-700 hover:bg-gray-50 disabled:opacity-50"
-          >
-            Enregistrer
-          </button>
-          {formState.status === "draft" && (
-            <button
-              type="button"
-              onClick={() => setConfirming(true)}
-              disabled={save.isPending}
-              className="rounded-md bg-emerald-600 px-3 py-1.5 text-sm font-medium text-white hover:bg-emerald-500 disabled:opacity-50"
-            >
-              Valider
-            </button>
-          )}
-        </div>
-      </div>
-
-      {localError !== null && (
-        <div role="alert" className="rounded-md border border-amber-300 bg-amber-50 p-3 text-sm text-amber-900">
-          Frontmatter invalide : {localError}
-        </div>
-      )}
-      {save.error != null && <ErrorBanner error={save.error} />}
-      {save.isSuccess && save.error == null && (
-        <p role="status" className="rounded-md border border-emerald-200 bg-emerald-50 p-2 text-sm text-emerald-800">
-          Spec enregistrée — statut : {save.data.spec.status}.
-        </p>
-      )}
-
-      <section aria-label="Frontmatter" className="rounded-lg border border-gray-200 bg-white p-4">
-        <h2 className="mb-3 text-sm font-semibold text-gray-700">
-          Frontmatter (formulaire dérivé de SpecFrontmatterSchema)
-        </h2>
-        <div className="grid grid-cols-1 gap-3 md:grid-cols-2">
-          {fields.map((field) => (
-            <label key={field.name} className="block text-sm text-gray-700">
-              <span className="font-mono text-xs text-gray-500">{field.name}</span>
-              {field.kind === "enum" ? (
-                <select
-                  value={formState[field.name]}
-                  onChange={(event) => setField(field.name, event.target.value)}
-                  className="mt-1 w-full rounded-md border border-gray-300 px-2 py-1.5 text-sm"
-                >
-                  {(field.options ?? []).map((option) => (
-                    <option key={option} value={option}>
-                      {option}
-                    </option>
-                  ))}
-                </select>
-              ) : field.kind === "string-array" ? (
-                <textarea
-                  value={formState[field.name]}
-                  onChange={(event) => setField(field.name, event.target.value)}
-                  rows={2}
-                  placeholder="un élément par ligne"
-                  className="mt-1 w-full rounded-md border border-gray-300 px-2 py-1.5 font-mono text-xs"
-                />
-              ) : (
-                <input
-                  value={formState[field.name]}
-                  readOnly={field.readOnly}
-                  onChange={(event) => setField(field.name, event.target.value)}
-                  className={`mt-1 w-full rounded-md border border-gray-300 px-2 py-1.5 font-mono text-sm ${field.readOnly ? "bg-gray-50 text-gray-500" : ""}`}
-                />
-              )}
-            </label>
-          ))}
-        </div>
-      </section>
-
-      <section aria-label="Sections markdown" className="grid grid-cols-1 gap-4 lg:grid-cols-2">
-        <label className="block text-sm text-gray-700">
-          <span className="font-mono text-xs text-gray-500">sections (markdown)</span>
-          <textarea
-            value={body}
-            onChange={(event) => setBody(event.target.value)}
-            rows={24}
-            className="mt-1 w-full rounded-md border border-gray-300 p-3 font-mono text-xs leading-relaxed"
-          />
-        </label>
-        <div className="text-sm">
-          <span className="font-mono text-xs text-gray-500">preview</span>
-          <div className="mt-1 h-full rounded-md border border-gray-200 bg-white p-4">
-            <MarkdownPreview markdown={body} />
-          </div>
-        </div>
-      </section>
-
-      <Modal
-        open={confirming}
-        title={`Valider ${specId} ?`}
-        onClose={() => setConfirming(false)}
-      >
-        <p className="text-sm text-gray-600">
-          Une spec validée est un contrat d'implémentation : status passera à
-          « validated » et le fichier sera réécrit (message « spec: validate {specId} »).
-        </p>
-        <div className="mt-4 flex justify-end gap-2">
-          <button
-            type="button"
-            onClick={() => setConfirming(false)}
-            className="rounded-md border border-gray-300 px-3 py-1.5 text-sm text-gray-700"
-          >
-            Annuler
-          </button>
-          <button
-            type="button"
-            onClick={confirmValidation}
-            disabled={save.isPending}
-            className="rounded-md bg-emerald-600 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
-          >
-            Confirmer la validation
-          </button>
-        </div>
-      </Modal>
-    </div>
-  );
-}

package/src/ui/features/spec-editor/frontmatter-fields.test.ts

@@ -1,54 +0,0 @@
-/**
- * @intent Proves that the frontmatter form is really DERIVED from
- * SpecFrontmatterSchema (never hand-described): field kinds and enum options
- * come from the schema, and the form-state round-trip re-validates against the
- * SAME schema — no duplicated rule can drift.
- */
-import { describe, expect, it } from "vitest";
-import { SpecFrontmatterSchema } from "@ogygie/core/spec";
-import {
-  deriveFrontmatterFields,
-  fromFormState,
-  toFormState,
-} from "./frontmatter-fields";
-
-describe("ogygie-studio — dérivation du formulaire de frontmatter", () => {
-  it("ÉTANT DONNÉ SpecFrontmatterSchema QUAND on dérive les champs ALORS chaque clé du schéma a son champ, avec les options d'enum lues du schéma", () => {
-    const fields = deriveFrontmatterFields();
-    expect(fields.map((field) => field.name)).toEqual([
-      "id",
-      "status",
-      "depends_on",
-      "priority",
-      "refs",
-      "deferred",
-    ]);
-    const status = fields.find((field) => field.name === "status");
-    expect(status).toMatchObject({
-      kind: "enum",
-      options: ["draft", "validated", "implemented"],
-    });
-    const priority = fields.find((field) => field.name === "priority");
-    expect(priority).toMatchObject({ kind: "enum", options: ["P0", "P1", "P2"] });
-    const id = fields.find((field) => field.name === "id");
-    expect(id).toMatchObject({ kind: "text", readOnly: true });
-    for (const arrayField of ["depends_on", "refs", "deferred"]) {
-      expect(fields.find((field) => field.name === arrayField)).toMatchObject({
-        kind: "string-array",
-      });
-    }
-  });
-
-  it("ÉTANT DONNÉ un frontmatter valide QUAND on passe par l'état de formulaire puis on revalide ALORS le round-trip est identique", () => {
-    const frontmatter = SpecFrontmatterSchema.parse({
-      id: "alpha",
-      status: "draft",
-      depends_on: ["beta"],
-      priority: "P2",
-      refs: ["specs/OGYGIE-STUDIO-ARCHI.md"],
-      deferred: [],
-    });
-    const roundTrip = SpecFrontmatterSchema.parse(fromFormState(toFormState(frontmatter)));
-    expect(roundTrip).toEqual(frontmatter);
-  });
-});

package/src/ui/features/spec-editor/frontmatter-fields.ts

@@ -1,85 +0,0 @@
-/**
- * @intent DERIVES the frontmatter form from SpecFrontmatterSchema — never
- * described by hand (same rule as the ContractForm pattern): a field added to
- * the schema appears in the studio without touching the UI. Only the flat
- * shapes the spec format allows are supported (scalar string, enum, array of
- * strings); anything else fails loudly instead of rendering a wrong field.
- */
-import { z } from "zod";
-import { SpecFrontmatterSchema, type SpecFrontmatter } from "@ogygie/core/spec";
-
-export type FrontmatterFieldKind = "text" | "enum" | "string-array";
-
-export interface FrontmatterField {
-  name: keyof SpecFrontmatter;
-  kind: FrontmatterFieldKind;
-  /** Enum options, present only when kind === "enum". */
-  options?: readonly string[] | undefined;
-  /** The id names the file: shown, never editable from the studio. */
-  readOnly: boolean;
-}
-
-function unwrap(schema: z.ZodType): z.ZodType {
-  if (schema instanceof z.ZodDefault) {
-    return unwrap(schema.def.innerType as z.ZodType);
-  }
-  return schema;
-}
-
-export function deriveFrontmatterFields(): FrontmatterField[] {
-  const shape = SpecFrontmatterSchema.shape;
-  return (Object.keys(shape) as (keyof SpecFrontmatter)[]).map((name) => {
-    const fieldSchema = unwrap(shape[name]);
-    if (fieldSchema instanceof z.ZodEnum) {
-      return {
-        name,
-        kind: "enum",
-        options: fieldSchema.options.map((option) => String(option)),
-        readOnly: false,
-      };
-    }
-    if (fieldSchema instanceof z.ZodArray) {
-      return { name, kind: "string-array", readOnly: false };
-    }
-    if (fieldSchema instanceof z.ZodString) {
-      return { name, kind: "text", readOnly: name === "id" };
-    }
-    throw new Error(
-      `deriveFrontmatterFields: unsupported schema for "${String(name)}" — extend the derivation, never hand-describe the form`,
-    );
-  });
-}
-
-/** Form state: every field edited as text (arrays = one element per line). */
-export type FrontmatterFormState = Record<keyof SpecFrontmatter, string>;
-
-export function toFormState(frontmatter: SpecFrontmatter): FrontmatterFormState {
-  return {
-    id: frontmatter.id,
-    status: frontmatter.status,
-    depends_on: frontmatter.depends_on.join("\n"),
-    priority: frontmatter.priority,
-    refs: frontmatter.refs.join("\n"),
-    deferred: frontmatter.deferred.join("\n"),
-  };
-}
-
-function linesOf(text: string): string[] {
-  return text
-    .split("\n")
-    .map((line) => line.trim())
-    .filter((line) => line !== "");
-}
-
-/** Rebuilds a candidate frontmatter from the form; the caller validates it
- * with SpecFrontmatterSchema (single source of truth — no duplicated rules). */
-export function fromFormState(state: FrontmatterFormState): Record<string, unknown> {
-  return {
-    id: state.id,
-    status: state.status,
-    depends_on: linesOf(state.depends_on),
-    priority: state.priority,
-    refs: linesOf(state.refs),
-    deferred: linesOf(state.deferred),
-  };
-}

package/src/ui/features/spec-editor/markdown-blocks.test.ts

@@ -1,37 +0,0 @@
-/**
- * @intent Proves the preview parser: headings, bullets, fenced code and
- * paragraphs become typed blocks (the preview never renders an HTML string).
- */
-import { describe, expect, it } from "vitest";
-import { parseMarkdownBlocks } from "./markdown-blocks";
-
-describe("ogygie-studio — parseur de preview markdown", () => {
-  it("ÉTANT DONNÉ un corps de spec canonique QUAND on le parse ALORS titres, listes, code et paragraphes deviennent des blocs typés", () => {
-    const markdown = [
-      "# @intent",
-      "Le pourquoi de la feature.",
-      "",
-      "# Comportements",
-      "- ÉTANT DONNÉ x",
-      "  QUAND y",
-      "- ALORS z",
-      "",
-      "```",
-      "const a = 1;",
-      "```",
-    ].join("\n");
-
-    expect(parseMarkdownBlocks(markdown)).toEqual([
-      { kind: "heading", level: 1, text: "@intent" },
-      { kind: "paragraph", text: "Le pourquoi de la feature." },
-      { kind: "heading", level: 1, text: "Comportements" },
-      { kind: "bullet", items: ["ÉTANT DONNÉ x QUAND y", "ALORS z"] },
-      { kind: "code", text: "const a = 1;" },
-    ]);
-  });
-
-  it("ÉTANT DONNÉ un texte vide QUAND on le parse ALORS aucun bloc", () => {
-    expect(parseMarkdownBlocks("")).toEqual([]);
-    expect(parseMarkdownBlocks("\n\n")).toEqual([]);
-  });
-});

package/src/ui/features/spec-editor/markdown-blocks.ts

@@ -1,82 +0,0 @@
-/**
- * @intent Tiny markdown block parser for the side-by-side preview (v1 spec:
- * textarea + preview). Pure function returning typed blocks that the preview
- * renders as React elements — never an HTML string (dangerouslySetInnerHTML is
- * banned repo-wide). Deliberately minimal: headings, bullets, fenced code,
- * paragraphs — a spec is prose, not a rendering benchmark.
- */
-
-export type MarkdownBlock =
-  | { kind: "heading"; level: number; text: string }
-  | { kind: "bullet"; items: string[] }
-  | { kind: "code"; text: string }
-  | { kind: "paragraph"; text: string };
-
-export function parseMarkdownBlocks(markdown: string): MarkdownBlock[] {
-  const blocks: MarkdownBlock[] = [];
-  const lines = markdown.split("\n");
-  let index = 0;
-  while (index < lines.length) {
-    const line = lines[index] ?? "";
-    const trimmed = line.trim();
-    if (trimmed === "") {
-      index += 1;
-      continue;
-    }
-    const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed);
-    if (heading !== null) {
-      blocks.push({
-        kind: "heading",
-        level: (heading[1] ?? "#").length,
-        text: heading[2] ?? "",
-      });
-      index += 1;
-      continue;
-    }
-    if (trimmed.startsWith("```")) {
-      const codeLines: string[] = [];
-      index += 1;
-      while (index < lines.length && !(lines[index] ?? "").trim().startsWith("```")) {
-        codeLines.push(lines[index] ?? "");
-        index += 1;
-      }
-      index += 1; // closing fence (or end of text)
-      blocks.push({ kind: "code", text: codeLines.join("\n") });
-      continue;
-    }
-    if (trimmed.startsWith("- ")) {
-      const items: string[] = [];
-      while (index < lines.length) {
-        const itemLine = (lines[index] ?? "").trim();
-        if (itemLine.startsWith("- ")) {
-          items.push(itemLine.slice(2));
-          index += 1;
-        } else if (itemLine !== "" && !itemLine.startsWith("#")) {
-          // continuation of the previous item (indented prose)
-          items[items.length - 1] = `${items[items.length - 1] ?? ""} ${itemLine}`;
-          index += 1;
-        } else {
-          break;
-        }
-      }
-      blocks.push({ kind: "bullet", items });
-      continue;
-    }
-    const paragraphLines: string[] = [];
-    while (index < lines.length) {
-      const paragraphLine = (lines[index] ?? "").trim();
-      if (
-        paragraphLine === "" ||
-        paragraphLine.startsWith("#") ||
-        paragraphLine.startsWith("- ") ||
-        paragraphLine.startsWith("```")
-      ) {
-        break;
-      }
-      paragraphLines.push(paragraphLine);
-      index += 1;
-    }
-    blocks.push({ kind: "paragraph", text: paragraphLines.join(" ") });
-  }
-  return blocks;
-}

package/src/ui/index.html

@@ -1,12 +0,0 @@
-<!doctype html>
-<html lang="fr">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Ogygie Studio</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="./main.tsx"></script>
-  </body>
-</html>

package/src/ui/lib/fetchContract.ts

@@ -1,40 +0,0 @@
-/**
- * @intent Single fetch path of the studio UI: relative /api/... calls, output
- * parsed against the shared Zod contract (zero drift with the server), and any
- * non-2xx response surfaced as the full OgygieError payload — the UI displays
- * errors entirely, it never summarizes them away.
- */
-import type { z } from "zod";
-import { OgygieErrorSchema, type OgygieError } from "@ogygie/core/errors";
-
-export class StudioApiError extends Error {
-  public readonly payload: OgygieError;
-
-  constructor(payload: OgygieError) {
-    super(payload.message);
-    this.name = "StudioApiError";
-    this.payload = payload;
-  }
-}
-
-export async function fetchContract<Output>(
-  path: string,
-  schema: z.ZodType<Output>,
-  init?: RequestInit,
-): Promise<Output> {
-  const response = await fetch(path, init);
-  const json: unknown = await response.json();
-  if (!response.ok) {
-    const parsed = OgygieErrorSchema.safeParse(json);
-    if (parsed.success) throw new StudioApiError(parsed.data);
-    throw new Error(`HTTP ${response.status} on ${path} (non-OgygieError payload)`);
-  }
-  return schema.parse(json);
-}
-
-export function jsonBody(body: unknown): RequestInit {
-  return {
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify(body),
-  };
-}

package/src/ui/lib/queries.ts

@@ -1,69 +0,0 @@
-/**
- * @intent Data access of the studio UI: TanStack Query hooks over the shared
- * contracts. Every mutation invalidates the specs root — the board and the
- * editor always re-read the repo, which is the only state.
- */
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import type { SpecFrontmatter } from "@ogygie/core/spec";
-import {
-  CreateSpecOutputSchema,
-  GetManifestOutputSchema,
-  GetSpecOutputSchema,
-  ListSpecsOutputSchema,
-  UpdateSpecOutputSchema,
-} from "../../server/schemas";
-import { fetchContract, jsonBody } from "./fetchContract";
-
-export function useSpecs() {
-  return useQuery({
-    queryKey: ["specs"],
-    queryFn: () => fetchContract("/api/specs", ListSpecsOutputSchema),
-  });
-}
-
-export function useSpec(specId: string) {
-  return useQuery({
-    queryKey: ["specs", specId],
-    queryFn: () => fetchContract(`/api/specs/${specId}`, GetSpecOutputSchema),
-  });
-}
-
-export function useManifest() {
-  return useQuery({
-    queryKey: ["manifest"],
-    queryFn: () => fetchContract("/api/manifest", GetManifestOutputSchema),
-  });
-}
-
-export interface SaveSpecVariables {
-  frontmatter: SpecFrontmatter;
-  body: string;
-}
-
-export function useSaveSpec(specId: string) {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (variables: SaveSpecVariables) =>
-      fetchContract(`/api/specs/${specId}`, UpdateSpecOutputSchema, {
-        method: "PUT",
-        ...jsonBody(variables),
-      }),
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({ queryKey: ["specs"] });
-    },
-  });
-}
-
-export function useCreateSpec() {
-  const queryClient = useQueryClient();
-  return useMutation({
-    mutationFn: (variables: { id: string }) =>
-      fetchContract("/api/specs", CreateSpecOutputSchema, {
-        method: "POST",
-        ...jsonBody(variables),
-      }),
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({ queryKey: ["specs"] });
-    },
-  });
-}

package/src/ui/main.tsx

@@ -1,27 +0,0 @@
-/**
- * @intent Browser entry point of the studio UI: TanStack Query client +
- * router mounted on #root. The repo stays the only state — the client cache
- * is a projection, invalidated after every write.
- */
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { RouterProvider } from "@tanstack/react-router";
-import { createStudioRouter } from "./router";
-import "./app.css";
-
-const queryClient = new QueryClient();
-const router = createStudioRouter();
-
-const rootElement = document.getElementById("root");
-if (rootElement === null) {
-  throw new Error("Studio UI: #root element missing from index.html");
-}
-
-createRoot(rootElement).render(
-  <StrictMode>
-    <QueryClientProvider client={queryClient}>
-      <RouterProvider router={router} />
-    </QueryClientProvider>
-  </StrictMode>,
-);

package/src/ui/patterns/EmptyState.tsx

@@ -1,24 +0,0 @@
-/**
- * @intent Canonical empty state of the studio: a title, an optional hint, and
- * the action that fills the void (spec: the empty board offers creation from
- * the template).
- */
-import type { ReactNode } from "react";
-
-export function EmptyState({
-  title,
-  hint,
-  action,
-}: {
-  title: string;
-  hint?: string;
-  action?: ReactNode;
-}) {
-  return (
-    <div className="flex flex-col items-center gap-3 rounded-lg border border-dashed border-gray-300 bg-white p-10 text-center">
-      <p className="text-base font-medium text-gray-900">{title}</p>
-      {hint !== undefined && <p className="text-sm text-gray-500">{hint}</p>}
-      {action}
-    </div>
-  );
-}