@pragma-sh/scratchpad-contract 0.1.0

package/README.md

@@ -0,0 +1,26 @@
+# @pragma-sh/scratchpad-contract
+
+The Pragma scratchpad file contract. Part of [Pragma](https://github.com/pragma-sh/pragma) — a desktop workspace for
+running persistent, worktree-scoped coding agents.
+
+Pure data: the managed frontmatter of a `.mdx` scratchpad and the sibling
+`<file>.mdx.comments.json` thread. No React, no renderer, no transport.
+
+Everything that reads or writes those two files should go through here — a
+second implementation of frontmatter parsing or comment serialization is how
+clients drift apart and a comment written on one device stops showing up on
+another.
+
+```sh
+bun add @pragma-sh/scratchpad-contract
+```
+
+```ts
+import { parseScratchpadDocument } from "@pragma-sh/scratchpad-contract";
+```
+
+Docs: <https://pragma-app.sh/docs/sdk/scratchpads>
+
+## License
+
+AGPL-3.0-only. See [LICENSE](https://github.com/pragma-sh/pragma/blob/main/LICENSE).

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@pragma-sh/scratchpad-contract",
+  "version": "0.1.0",
+  "description": "The scratchpad file contract: managed frontmatter, agent attachment, and the sibling comment-thread file. Source of truth shared by the desktop, the SDK, and the read-only viewer.",
+  "homepage": "https://github.com/pragma-sh/pragma#readme",
+  "bugs": "https://github.com/pragma-sh/pragma/issues",
+  "license": "AGPL-3.0-only",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pragma-sh/pragma.git",
+    "directory": "packages/scratchpad-contract"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun --bun vitest run",
+    "lint": "oxlint ."
+  },
+  "dependencies": {
+    "@pragma-sh/constants": "^0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.8"
+  }
+}

package/src/comments.ts

@@ -0,0 +1,91 @@
+import { isNumber, isString, matchesShape, nullable } from "./guards";
+import type { ScratchpadBlock, ScratchpadComment } from "./types";
+
+export type { ScratchpadComment };
+
+/** Sibling JSON path storing one scratchpad's comment threads. */
+export function scratchpadCommentsPath(filePath: string): string {
+  return `${filePath}.comments.json`;
+}
+
+/**
+ * Parses a persisted comment file, dropping malformed entries instead of
+ * failing the whole document — one bad entry must not cost the user the rest of
+ * their comments.
+ */
+export function parseScratchpadComments(source: string): ScratchpadComment[] {
+  const value: unknown = JSON.parse(source);
+  if (!Array.isArray(value)) throw new Error("Scratchpad comments must be an array.");
+  return value.filter(isScratchpadComment);
+}
+
+/** Serializes comments in the exact on-disk shape the desktop writes. */
+export function serializeScratchpadComments(comments: readonly ScratchpadComment[]): string {
+  return `${JSON.stringify(comments, null, 2)}\n`;
+}
+
+/**
+ * Builds one comment anchored to a rendered block.
+ *
+ * `from`/`to` stay `0`: they are ProseMirror positions in the desktop editor's
+ * document, which a rendered web view has no way to compute. The desktop skips
+ * decorating a zero-width range, so a phone-authored comment shows up in its
+ * list and in the agent handoff without highlighting an arbitrary paragraph.
+ */
+export function createScratchpadComment(
+  block: ScratchpadBlock,
+  text: string,
+  now: number,
+  id: string,
+): ScratchpadComment {
+  return {
+    id,
+    from: 0,
+    to: 0,
+    quote: block.quote,
+    text: text.trim(),
+    createdAt: now,
+    resolvedAt: null,
+    blockIndex: block.index,
+  };
+}
+
+/** Comments still awaiting the agent. */
+export function unresolvedComments(
+  comments: readonly ScratchpadComment[],
+): readonly ScratchpadComment[] {
+  return comments.filter((comment) => comment.resolvedAt === null);
+}
+
+/** Stamps every open comment as resolved at the given time. */
+export function markAllResolved(
+  comments: readonly ScratchpadComment[],
+  now: number,
+): ScratchpadComment[] {
+  return comments.map((comment) =>
+    comment.resolvedAt === null ? { ...comment, resolvedAt: now } : comment,
+  );
+}
+
+/**
+ * The handoff message an agent receives when the user submits open comments.
+ * Shared with the desktop so an agent sees the same prompt either way.
+ */
+export function unresolvedCommentsPrompt(unresolved: readonly ScratchpadComment[]): string {
+  return [
+    "The user left the following scratchpad comments for you to address:",
+    ...unresolved.map((comment, index) => `${index + 1}. On "${comment.quote}": ${comment.text}`),
+  ].join("\n");
+}
+
+function isScratchpadComment(value: unknown): value is ScratchpadComment {
+  return matchesShape(value, {
+    id: isString,
+    from: isNumber,
+    to: isNumber,
+    quote: isString,
+    text: isString,
+    createdAt: isNumber,
+    resolvedAt: nullable(isNumber),
+  });
+}

package/src/document.ts

@@ -0,0 +1,92 @@
+import { constants } from "@pragma-sh/constants";
+
+import { isNumber, isString, matchesShape, nullable } from "./guards";
+
+/** Managed metadata stored as one JSON line in scratchpad YAML frontmatter. */
+export interface ScratchpadMetadata {
+  version: number;
+  id: string;
+  title: string;
+  agentTabId: string | null;
+  agentId: string | null;
+  createdAt: number;
+}
+
+/** Parsed managed scratchpad with its editable MDX body split from frontmatter. */
+export interface ScratchpadDocument {
+  metadata: ScratchpadMetadata;
+  body: string;
+  frontmatter: string;
+}
+
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n)?/;
+
+/**
+ * Parses required managed frontmatter. MDX dropped into the scratchpad
+ * directory by hand is rejected: without the managed line there is no id, no
+ * title, and no agent attachment to edit.
+ */
+export function parseScratchpadDocument(source: string): ScratchpadDocument {
+  const frontmatter = FRONTMATTER_PATTERN.exec(source);
+  if (!frontmatter) {
+    throw new Error("This MDX file is not a managed Pragma scratchpad.");
+  }
+  return {
+    metadata: parseMetadata(metadataLine(frontmatter[1] ?? "")),
+    body: source.slice(frontmatter[0].length),
+    frontmatter: frontmatter[0],
+  };
+}
+
+/** The one managed line inside a frontmatter block. */
+function metadataLine(frontmatter: string): string {
+  const key = constants.scratchpads.frontmatterKey;
+  const line = frontmatter.split(/\r?\n/).find((entry) => entry.startsWith(`${key}: `));
+  if (!line) throw new Error("Scratchpad frontmatter is missing managed metadata.");
+  return line.slice(key.length + 2);
+}
+
+/** Parses that line, rejecting a contract version this build does not know. */
+function parseMetadata(json: string): ScratchpadMetadata {
+  const parsed: unknown = JSON.parse(json);
+  if (!isScratchpadMetadata(parsed) || parsed.version !== constants.scratchpads.version) {
+    throw new Error("Scratchpad metadata is invalid or uses an unsupported version.");
+  }
+  return parsed;
+}
+
+/** Replaces the MDX body while preserving every frontmatter byte. */
+export function replaceScratchpadBody(document: ScratchpadDocument, body: string): string {
+  return `${document.frontmatter}${body}`;
+}
+
+/** Updates the attached agent identity in managed frontmatter. */
+export function attachScratchpadAgent(
+  source: string,
+  agent: { tabId: string; agentId: string },
+): string {
+  const document = parseScratchpadDocument(source);
+  const metadata: ScratchpadMetadata = {
+    ...document.metadata,
+    agentTabId: agent.tabId,
+    agentId: agent.agentId,
+  };
+  const key = constants.scratchpads.frontmatterKey;
+  const nextLine = `${key}: ${JSON.stringify(metadata)}`;
+  const lines = document.frontmatter.split(/\r?\n/);
+  const index = lines.findIndex((line) => line.startsWith(`${key}: `));
+  if (index < 0) throw new Error("Scratchpad frontmatter is missing managed metadata.");
+  lines[index] = nextLine;
+  return `${lines.join("\n")}${document.body}`;
+}
+
+function isScratchpadMetadata(value: unknown): value is ScratchpadMetadata {
+  return matchesShape(value, {
+    version: isNumber,
+    id: isString,
+    title: isString,
+    agentTabId: nullable(isString),
+    agentId: nullable(isString),
+    createdAt: isNumber,
+  });
+}

package/src/guards.ts

@@ -0,0 +1,27 @@
+/** A predicate narrowing one field of a parsed JSON value. */
+export type FieldGuard = (value: unknown) => boolean;
+
+/**
+ * Checks a parsed JSON value field by field.
+ *
+ * Both files this package parses — the comment thread and the managed
+ * frontmatter — are written by another process (an agent, or an older Pragma),
+ * so every field is validated before it is trusted. Sharing one checker keeps
+ * those two validations from drifting into subtly different strictness.
+ */
+export function matchesShape(value: unknown, fields: Record<string, FieldGuard>): boolean {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value as Record<string, unknown>;
+  return Object.entries(fields).every(([field, guard]) => guard(record[field]));
+}
+
+/** Field is a string. */
+export const isString: FieldGuard = (value) => typeof value === "string";
+
+/** Field is a number. */
+export const isNumber: FieldGuard = (value) => typeof value === "number";
+
+/** Field is `null` or passes `guard`. */
+export function nullable(guard: FieldGuard): FieldGuard {
+  return (value) => value === null || guard(value);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  createScratchpadComment,
+  markAllResolved,
+  parseScratchpadComments,
+  scratchpadCommentsPath,
+  serializeScratchpadComments,
+  unresolvedComments,
+  unresolvedCommentsPrompt,
+} from "./comments";
+export {
+  attachScratchpadAgent,
+  parseScratchpadDocument,
+  replaceScratchpadBody,
+  type ScratchpadDocument,
+  type ScratchpadMetadata,
+} from "./document";
+export type { ScratchpadBlock, ScratchpadComment } from "./types";

package/src/types.ts

@@ -0,0 +1,37 @@
+/**
+ * The on-disk shapes every scratchpad client shares.
+ *
+ * They live in their own module (and their own package) because the desktop
+ * editor, the SDK, the read-only viewer, and the native clients all read and
+ * write the same two files — the MDX with its managed frontmatter, and the
+ * sibling comment thread — and a second definition of either shape is how they
+ * drift apart.
+ */
+
+/** One block of the rendered document a comment can be attached to. */
+export interface ScratchpadBlock {
+  /** Index of the block among the document's top-level rendered blocks. */
+  index: number;
+  /** Plain-text excerpt of the block, used as the comment's quote. */
+  quote: string;
+}
+
+/** One persisted scratchpad comment, in the desktop's on-disk shape. */
+export interface ScratchpadComment {
+  id: string;
+  /**
+   * ProseMirror document positions the desktop editor decorates. A native
+   * client has no ProseMirror document, so it writes `0`/`0` and anchors by
+   * {@link ScratchpadComment.quote} and {@link ScratchpadComment.blockIndex}
+   * instead; the desktop then renders the comment without a highlight rather
+   * than highlighting the wrong range.
+   */
+  from: number;
+  to: number;
+  quote: string;
+  text: string;
+  createdAt: number;
+  resolvedAt: number | null;
+  /** Rendered block this comment was attached to, when written on mobile. */
+  blockIndex?: number;
+}