@ogygie/core 0.19.0 → 0.20.0

package/src/proposal.ts

@@ -0,0 +1,525 @@
+/**
+ * @intent Write by PROPOSAL (DECISIONS.md D17, hoisted into the core by D51):
+ * a spec or a decisions file becomes one commit on a branch and a pull
+ * request, never a file on the host. Two consumers share it — the MCP server
+ * (spec ogygie-mcp B10) and the hosted studio (spec ogygie-hosted-mode) —
+ * and a validation fixed on one side and not the other would be a lockstep
+ * bug waiting to happen (the motive of D10, applied to writing).
+ *
+ * Three things live here, in this order:
+ * 1. the CONTRACTS — the closed perimeter of proposable paths IS a schema;
+ * 2. the GitHub client — six calls, exactly what a proposal needs, over an
+ *    injected `fetch`;
+ * 3. `proposeChange` — the validation `verify-specs` will run on the PR, done
+ *    first so the caller learns the refusal before anyone reviews it, then
+ *    the remote steps. The order is fixed: path, rate limit, content, remote
+ *    state — a forbidden path never costs a remote read.
+ *
+ * Effects are injected (AGENTS.md principle 5): the client, the clock, the
+ * ledger of recent proposals, the sentence that names the proposer. What the
+ * caller READ is given as a `RepoAdapter` (D10) to detect a stale page;
+ * nothing here touches a disk or a process, and a purity gate can prove it.
+ */
+import { z } from "zod";
+import {
+  extractDecisionSection,
+  findUnknownDecisionReferences,
+  parseKnownDecisionIds,
+} from "./decision-refs.js";
+import { OgygieFailure, throwOgygieError } from "./error.schema.js";
+import type { RepoAdapter } from "./repo-adapter.js";
+import { SECTIONS_SPEC_OBLIGATOIRES, parseSpecDocument } from "./spec.schema.js";
+
+// ------------------------------------------------------------- contracts
+
+/** The two decision files, one GLOBAL D<n> numbering across both. */
+export const DECISION_FILES = ["DECISIONS.md", "DECISIONS.product.md"] as const;
+
+/** Where a repo lives on GitHub — what makes it writable by proposal. */
+export const GithubCoordinatesSchema = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+  defaultBranch: z.string().min(1).default("main"),
+});
+export type GithubCoordinates = z.infer<typeof GithubCoordinatesSchema>;
+
+/**
+ * The closed perimeter IS the schema: a spec (never the template), or one of
+ * the two decision files. Anything else is refused before any remote read.
+ */
+export const ProposablePathSchema = z.union([
+  z.string().regex(/^specs\/(?!_)[a-z][a-z0-9]*(-[a-z0-9]+)*\.spec\.md$/),
+  z.literal("DECISIONS.md"),
+  z.literal("DECISIONS.product.md"),
+]);
+export type ProposablePath = z.infer<typeof ProposablePathSchema>;
+
+export const ProposalSchema = z.object({
+  repo: z.string(),
+  path: ProposablePathSchema,
+  branch: z.string(),
+  baseSha: z.string(),
+  commitSha: z.string(),
+  pullRequestNumber: z.number().int().positive(),
+  pullRequestUrl: z.url(),
+  /** false when an open pull request was updated instead of created. */
+  created: z.boolean(),
+});
+export type Proposal = z.infer<typeof ProposalSchema>;
+
+/** Refuses anything outside the perimeter — the first check of every proposal. */
+export function assertProposablePath(path: string): ProposablePath {
+  const parsed = ProposablePathSchema.safeParse(path);
+  if (!parsed.success) {
+    return throwOgygieError({
+      code: "WRITE_PATH_FORBIDDEN",
+      message: `"${path}" is outside what a proposal may touch.`,
+      file: path,
+      cause: "the perimeter is specs/<id>.spec.md (not the template), DECISIONS.md, DECISIONS.product.md",
+      suggestedFix:
+        "Propose a spec or a decisions file; code, manifest, governed files and FAILURES.md are out of reach (D17).",
+    });
+  }
+  return parsed.data;
+}
+
+// --------------------------------------------------------- GitHub client
+
+export interface GithubWriteClient {
+  getBranchHead(branch: string): Promise<string | null>;
+  readFileAtRef(path: string, ref: string): Promise<{ content: string; sha: string } | null>;
+  createBranch(branch: string, fromSha: string): Promise<void>;
+  commitFile(input: {
+    branch: string;
+    path: string;
+    content: string;
+    message: string;
+    /** Blob sha of the file on that branch — null when the file is new. */
+    expectedSha: string | null;
+    /** Git author of the commit; the committer stays the token's identity. */
+    author?: { name: string; email: string };
+  }): Promise<{ commitSha: string }>;
+  findOpenPullRequest(branch: string): Promise<{ number: number; url: string } | null>;
+  openPullRequest(input: {
+    branch: string;
+    base: string;
+    title: string;
+    body: string;
+  }): Promise<{ number: number; url: string }>;
+}
+
+export interface GithubWriteClientDeps {
+  token: string;
+  fetchImpl: typeof fetch;
+  apiBase?: string;
+  /** Sent as `user-agent`, which the GitHub API requires on every call. */
+  userAgent?: string;
+  /**
+   * How the caller names its credential in a refusal — `OGYGIE_MCP_GITHUB_TOKEN`
+   * for the MCP server. A 401 that names the variable to check is a fix; one
+   * that says "the token" is a riddle.
+   */
+  credentialHint?: string;
+}
+
+export function createGithubWriteClient(
+  deps: GithubWriteClientDeps,
+  github: GithubCoordinates,
+): GithubWriteClient {
+  const apiBase = deps.apiBase ?? "https://api.github.com";
+  const repoUrl = `${apiBase}/repos/${github.owner}/${github.repo}`;
+  const credential = deps.credentialHint ?? "the GitHub token";
+
+  /** One request; 404 is an answer (null) when `allowNotFound`, never a failure. */
+  async function request<T>(
+    method: string,
+    url: string,
+    body: unknown,
+    allowNotFound: boolean,
+  ): Promise<T | null> {
+    let response: Response;
+    try {
+      response = await deps.fetchImpl(url, {
+        method,
+        headers: {
+          authorization: `Bearer ${deps.token}`,
+          accept: "application/vnd.github+json",
+          "x-github-api-version": "2022-11-28",
+          "user-agent": deps.userAgent ?? "ogygie-core",
+          ...(body === undefined ? {} : { "content-type": "application/json" }),
+        },
+        ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      });
+    } catch (thrown) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub could not be reached for ${github.owner}/${github.repo}.`,
+        file: null,
+        cause: thrown instanceof Error ? thrown.message : String(thrown),
+        suggestedFix: "Retry once the network is back — nothing was written, nothing is queued.",
+      });
+    }
+    if (response.status === 404 && allowNotFound) return null;
+    if (!response.ok) {
+      return throwOgygieError({
+        code: "GITHUB_UNAVAILABLE",
+        message: `GitHub answered ${response.status} for ${method} ${url.replace(apiBase, "")}.`,
+        file: null,
+        cause: `status=${response.status}`,
+        suggestedFix:
+          response.status === 401 || response.status === 403
+            ? `Check ${credential}: it must grant contents and pull requests on this repo.`
+            : "Retry later — nothing was written, nothing is queued.",
+      });
+    }
+    return (await response.json()) as T;
+  }
+
+  return {
+    async getBranchHead(branch) {
+      const ref = await request<{ object: { sha: string } }>(
+        "GET",
+        `${repoUrl}/git/ref/heads/${encodeURIComponent(branch)}`,
+        undefined,
+        true,
+      );
+      return ref?.object.sha ?? null;
+    },
+    async readFileAtRef(path, ref) {
+      const file = await request<{ content: string; sha: string }>(
+        "GET",
+        `${repoUrl}/contents/${path}?ref=${encodeURIComponent(ref)}`,
+        undefined,
+        true,
+      );
+      if (file === null) return null;
+      return { content: Buffer.from(file.content, "base64").toString("utf8"), sha: file.sha };
+    },
+    async createBranch(branch, fromSha) {
+      await request("POST", `${repoUrl}/git/refs`, { ref: `refs/heads/${branch}`, sha: fromSha }, false);
+    },
+    async commitFile(input) {
+      const result = await request<{ commit: { sha: string } }>(
+        "PUT",
+        `${repoUrl}/contents/${input.path}`,
+        {
+          message: input.message,
+          content: Buffer.from(input.content, "utf8").toString("base64"),
+          branch: input.branch,
+          ...(input.expectedSha === null ? {} : { sha: input.expectedSha }),
+          ...(input.author === undefined ? {} : { author: input.author }),
+        },
+        false,
+      );
+      return { commitSha: result?.commit.sha ?? "" };
+    },
+    async findOpenPullRequest(branch) {
+      const pulls = await request<{ number: number; html_url: string }[]>(
+        "GET",
+        `${repoUrl}/pulls?state=open&head=${encodeURIComponent(`${github.owner}:${branch}`)}`,
+        undefined,
+        false,
+      );
+      const first = pulls?.[0];
+      return first === undefined ? null : { number: first.number, url: first.html_url };
+    },
+    async openPullRequest(input) {
+      const pull = await request<{ number: number; html_url: string }>(
+        "POST",
+        `${repoUrl}/pulls`,
+        { title: input.title, body: input.body, head: input.branch, base: input.base },
+        false,
+      );
+      return { number: pull?.number ?? 0, url: pull?.html_url ?? "" };
+    },
+  };
+}
+
+// --------------------------------------------------------------- proposal
+
+/** The repo a proposal targets: its id, its GitHub coordinates, what the caller read. */
+export interface ProposalTarget {
+  id: string;
+  github: GithubCoordinates;
+  /** The repo AS THE CALLER SAW IT — compared to the remote head (REMOTE_CONFLICT). */
+  adapter: RepoAdapter;
+}
+
+export interface ProposalDeps {
+  clientFor: (github: GithubCoordinates) => GithubWriteClient;
+  /** The sentence closing the PR body: who proposed, through what. */
+  originOf: (path: string) => string;
+  now: () => number;
+  rateLimitPerHour: number;
+  /** Accepted proposals per target id, kept by the caller across calls. */
+  recentProposals: Map<string, number[]>;
+  /** The branch a path lands on. Default: `mcp/<id>/<path-slug>` (D17). */
+  branchFor?: (target: ProposalTarget, path: string) => string;
+  /**
+   * The git author of the commit — the human who wanted it (D45). Absent, the
+   * commit is signed by the token's identity alone, as the MCP server does.
+   */
+  authorOf?: () => { name: string; email: string } | undefined;
+  /**
+   * Which head the caller READ, hence which head a stale page is detected
+   * against: `defaultBranch` (an MCP client reads a clone of it) or `branch`
+   * — the proposal branch itself, when it exists, for a caller that works on
+   * it (the hosted studio, D46). Default: `defaultBranch`.
+   */
+  readFrom?: "defaultBranch" | "branch";
+}
+
+export interface ProposalInput {
+  path: string;
+  content: string;
+  message: string;
+}
+
+const HOUR_MS = 3_600_000;
+const DECISION_HEADING = /^## D(\d+) — \d{4}-\d{2}-\d{2} — \S/;
+const DECISION_BULLETS = ["**Décision**", "**Motivation**", "**Exclut**"];
+
+function specIdOfPath(path: string): string {
+  return path.replace(/^specs\//, "").replace(/\.spec\.md$/, "");
+}
+
+/** What verify-specs checks on a spec, replayed before proposing. */
+export function assertSpecProposable(path: string, content: string): void {
+  const parsed = parseSpecDocument(content);
+  const problems = [...parsed.problems];
+  if (parsed.frontmatter !== null && parsed.frontmatter.id !== specIdOfPath(path)) {
+    problems.push(`id "${parsed.frontmatter.id}" differs from the file name "${specIdOfPath(path)}"`);
+  }
+  let cursor = 0;
+  for (const section of SECTIONS_SPEC_OBLIGATOIRES) {
+    const position = parsed.body.indexOf(`\n${section}\n`, cursor);
+    if (position === -1) problems.push(`section "${section}" missing or out of order`);
+    else cursor = position + section.length;
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "SPEC_INVALID",
+      message: `The proposed spec would fail verify-specs (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix:
+        "Fix the frontmatter (id, status, depends_on, priority, refs) and keep the six canonical sections in order.",
+    });
+  }
+  if (parsed.frontmatter?.status === "implemented") {
+    throwOgygieError({
+      code: "SPEC_STATUS_FORBIDDEN",
+      message: "A proposal may not declare a spec implemented.",
+      file: path,
+      cause: "status=implemented",
+      suggestedFix:
+        "Propose the spec as draft or validated — the repo's manifest and CI say when it is implemented.",
+    });
+  }
+}
+
+/**
+ * A decisions file keeps every id it had, numbers stay contiguous across the
+ * two files, and a new decision carries its three bullets.
+ */
+export function assertDecisionsProposable(
+  path: string,
+  content: string,
+  baseSame: string | null,
+  baseOther: string | null,
+): void {
+  const problems: string[] = [];
+  for (const line of content.split("\n")) {
+    if (line.startsWith("## ") && !DECISION_HEADING.test(line)) {
+      problems.push(`heading "${line}" is not "## D<n> — AAAA-MM-JJ — <titre>"`);
+    }
+  }
+  const proposedIds = parseKnownDecisionIds(content);
+  const otherIds = parseKnownDecisionIds(baseOther ?? "");
+  const previousIds = parseKnownDecisionIds(baseSame ?? "");
+  for (const id of previousIds) {
+    if (!proposedIds.includes(id)) problems.push(`${id} was declared and is removed or renumbered`);
+  }
+  const all = [...proposedIds, ...otherIds];
+  const seen = new Set<string>();
+  for (const id of all) {
+    if (seen.has(id)) problems.push(`${id} is declared twice across the decision files`);
+    seen.add(id);
+  }
+  const numbers = [...seen].map((id) => Number.parseInt(id.slice(1), 10)).sort((a, b) => a - b);
+  numbers.forEach((value, index) => {
+    if (value !== index + 1) problems.push(`numbering has a gap: expected D${index + 1}, found D${value}`);
+  });
+  for (const id of proposedIds.filter((candidate) => !previousIds.includes(candidate))) {
+    const section = extractDecisionSection(content, id) ?? "";
+    for (const bullet of DECISION_BULLETS) {
+      if (!section.includes(bullet)) problems.push(`${id} lacks its ${bullet} bullet`);
+    }
+  }
+  if (problems.length > 0) {
+    throwOgygieError({
+      code: "DECISION_INVALID",
+      message: `The proposed decisions file breaks the D<n> contract (${problems.length} problem(s)).`,
+      file: path,
+      cause: problems.join(" ; "),
+      suggestedFix:
+        "Keep every existing decision, number the new one right after the last across both files, and give it its Décision / Motivation / Exclut bullets.",
+    });
+  }
+}
+
+function assertDecisionReferencesKnown(path: string, content: string, known: readonly string[]): void {
+  const unknown = findUnknownDecisionReferences(content, known);
+  if (unknown.length > 0) {
+    throwOgygieError({
+      code: "UNKNOWN_DECISION_REFERENCE",
+      message: `The proposal cites ${unknown.length} decision(s) the repo does not declare.`,
+      file: path,
+      cause: unknown.map((reference) => `${reference.decision} (line ${reference.line})`).join(", "),
+      suggestedFix: `Cite only declared decisions (${known.join(", ") || "<none>"}), or propose the decision first.`,
+    });
+  }
+}
+
+function branchSlug(path: string): string {
+  return path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+
+function defaultBranchFor(target: ProposalTarget, path: string): string {
+  return `mcp/${target.id}/${branchSlug(path)}`;
+}
+
+/** Anything the GitHub client throws outside its contract is still GITHUB_UNAVAILABLE. */
+async function withGithub<T>(action: () => Promise<T>): Promise<T> {
+  try {
+    return await action();
+  } catch (thrown) {
+    if (thrown instanceof OgygieFailure) throw thrown;
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: "The GitHub client failed outside its contract.",
+      file: null,
+      cause: thrown instanceof Error ? thrown.message : String(thrown),
+      suggestedFix: "Retry — nothing was written, nothing is queued.",
+    });
+  }
+}
+
+export async function proposeChange(
+  target: ProposalTarget,
+  deps: ProposalDeps,
+  input: ProposalInput,
+): Promise<Proposal> {
+  const path = assertProposablePath(input.path);
+  const github = target.github;
+  const now = deps.now();
+  const recent = (deps.recentProposals.get(target.id) ?? []).filter((at) => now - at < HOUR_MS);
+  if (recent.length >= deps.rateLimitPerHour) {
+    const retryAfterSeconds = Math.ceil(((recent[0] ?? now) + HOUR_MS - now) / 1000);
+    throwOgygieError({
+      code: "WRITE_RATE_LIMITED",
+      message: `Repo "${target.id}" already received ${recent.length} proposals this hour.`,
+      file: null,
+      cause: `limit=${deps.rateLimitPerHour}/hour`,
+      suggestedFix: `Retry in ${retryAfterSeconds} s, or merge or close the open proposals first.`,
+    });
+  }
+
+  const client = deps.clientFor(github);
+  const baseSha = await withGithub(() => client.getBranchHead(github.defaultBranch));
+  if (baseSha === null) {
+    return throwOgygieError({
+      code: "GITHUB_UNAVAILABLE",
+      message: `Branch "${github.defaultBranch}" does not exist on ${github.owner}/${github.repo}.`,
+      file: null,
+      cause: "default branch head not found",
+      suggestedFix: "Fix `defaultBranch` in the GitHub coordinates of that repo.",
+    });
+  }
+  const baseFiles = new Map<string, string | null>();
+  for (const decisionsPath of DECISION_FILES) {
+    const file = await withGithub(() => client.readFileAtRef(decisionsPath, baseSha));
+    baseFiles.set(decisionsPath, file?.content ?? null);
+  }
+  if (path.startsWith("specs/")) {
+    assertSpecProposable(path, input.content);
+    const known = DECISION_FILES.flatMap((file) => parseKnownDecisionIds(baseFiles.get(file) ?? ""));
+    assertDecisionReferencesKnown(path, input.content, known);
+  } else {
+    const other = DECISION_FILES.find((file) => file !== path) ?? DECISION_FILES[1];
+    assertDecisionsProposable(path, input.content, baseFiles.get(path) ?? null, baseFiles.get(other) ?? null);
+    const known = [...parseKnownDecisionIds(input.content), ...parseKnownDecisionIds(baseFiles.get(other) ?? "")];
+    assertDecisionReferencesKnown(path, input.content, known);
+  }
+
+  let branch = (deps.branchFor ?? defaultBranchFor)(target, path);
+  let branchHead = await withGithub(() => client.getBranchHead(branch));
+  let openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  if (branchHead !== null && openPull === null) {
+    // A branch with no open PR was merged or abandoned: a fresh one, never a
+    // commit on top of history the default branch already has.
+    branch = `${branch}-${baseSha.slice(0, 7)}`;
+    branchHead = await withGithub(() => client.getBranchHead(branch));
+    openPull = branchHead === null ? null : await withGithub(() => client.findOpenPullRequest(branch));
+  }
+  const headOfBranch = branchHead;
+  const baseFile = await withGithub(() => client.readFileAtRef(path, baseSha));
+  const branchFile =
+    headOfBranch === null ? null : await withGithub(() => client.readFileAtRef(path, headOfBranch));
+
+  // What the caller READ is its adapter; what it must not overwrite is the
+  // head it read from — the default branch, or the proposal branch when the
+  // caller works on it. When they differ, the caller decided on a stale page.
+  const readsBranch = deps.readFrom === "branch" && headOfBranch !== null;
+  const compared = readsBranch ? branchFile : baseFile;
+  const comparedName = readsBranch ? branch : github.defaultBranch;
+  const local = (await target.adapter.exists(path)) ? await target.adapter.readFile(path) : null;
+  if ((compared?.content ?? null) !== local) {
+    throwOgygieError({
+      code: "REMOTE_CONFLICT",
+      message: `"${path}" changed on ${comparedName} since it was read.`,
+      file: path,
+      cause: `head sha=${compared?.sha ?? "<absent>"}, the read copy ${local === null ? "has no such file" : "differs"}`,
+      suggestedFix: "Re-read the file (details.headContent is the current head), reapply your change and propose again.",
+      details: { headSha: compared?.sha ?? null, headContent: compared?.content ?? null },
+    });
+  }
+
+  recent.push(now);
+  deps.recentProposals.set(target.id, recent);
+  const expectedSha = headOfBranch === null ? (baseFile?.sha ?? null) : (branchFile?.sha ?? null);
+  if (headOfBranch === null) {
+    await withGithub(() => client.createBranch(branch, baseSha));
+  }
+  const author = deps.authorOf?.();
+  const commit = await withGithub(() =>
+    client.commitFile({
+      branch,
+      path,
+      content: input.content,
+      message: input.message,
+      expectedSha,
+      ...(author === undefined ? {} : { author }),
+    }),
+  );
+  const pull =
+    openPull ??
+    (await withGithub(() =>
+      client.openPullRequest({
+        branch,
+        base: github.defaultBranch,
+        title: (input.message.split("\n")[0] ?? input.message).slice(0, 72),
+        body: `${input.message}\n\n---\n${deps.originOf(path)}`,
+      }),
+    ));
+  return {
+    repo: target.id,
+    path,
+    branch,
+    baseSha,
+    commitSha: commit.commitSha,
+    pullRequestNumber: pull.number,
+    pullRequestUrl: pull.url,
+    created: openPull === null,
+  };
+}