@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/sharing/index.ts

@@ -0,0 +1,16 @@
+export { ShareClient } from "./client.js";
+
+export {
+  exportShare,
+  type ShareBundle,
+  type ShareExportData,
+  type ShareExportStore,
+} from "./export.js";
+
+export {
+  SharedReviewStore,
+  sharedReviewId,
+  validateShareBundle,
+} from "./import.js";
+
+export { verifyShareRepository } from "./repository.js";

package/src/sharing/repository.ts

@@ -0,0 +1,145 @@
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { gitAt } from "@dev.fast/local-vcs";
+import { normalizeGitHubRemote } from "@dev.fast/review-share-protocol";
+import { type Pins, ReviewInputError } from "@review/review-api/document.js";
+
+/** Keep credential helpers but prevent the calling shell from redirecting Git's object store. */
+export function sharedGit(cwd: string, args: string[]) {
+  const env = Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([key]) =>
+        !key.startsWith("GIT_") ||
+        [
+          "GIT_SSH",
+          "GIT_SSH_COMMAND",
+          "GIT_ASKPASS",
+          "GIT_SSH_VARIANT",
+        ].includes(key),
+    ),
+  );
+
+  return gitAt(
+    cwd,
+    ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args],
+    {
+      env: { ...env, GIT_TERMINAL_PROMPT: "0" },
+      timeout: 300_000,
+    },
+  );
+}
+
+function fetchError(stderr: string, publishing: boolean): ReviewInputError {
+  if (/not our ref|couldn't find remote ref|unadvertised object/i.test(stderr))
+    return new ReviewInputError(
+      publishing
+        ? "Push the reviewed commits to GitHub before sharing."
+        : "The shared commits are no longer available on GitHub. Ask the sender to restore them, then retry.",
+      409,
+    );
+
+  return new ReviewInputError(
+    "Could not fetch the GitHub repository. Check your connection and Git credentials for this repository, then retry.",
+    409,
+  );
+}
+
+/** Recipients need complete history; publication only checks that the commits exist. */
+export async function fetchPinnedRepository(
+  root: string,
+  url: string,
+  pins: Pick<Pins, "base" | "head">,
+  publishing = false,
+) {
+  if (
+    ![pins.base, pins.head].every((commit) =>
+      /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit),
+    )
+  )
+    throw new ReviewInputError(
+      "Sharing requires immutable base and head commits.",
+    );
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await sharedGit(root, ["init", "--quiet"]);
+
+  if (!publishing) {
+    await sharedGit(root, ["config", "core.hooksPath", "/dev/null"]);
+    await sharedGit(root, ["config", "core.fsmonitor", "false"]);
+    await sharedGit(root, ["remote", "add", "origin", url]);
+  }
+
+  // Branch refs make Git reject non-commit objects during the fetch itself.
+  const refs = publishing ? "refs/heads/review" : "refs/review";
+
+  try {
+    await sharedGit(root, [
+      "fetch",
+      "--no-tags",
+      "--force",
+      ...(publishing ? ["--depth=1", "--filter=tree:0"] : []),
+      publishing ? url : "origin",
+      `${pins.base}:${refs}/base`,
+      `${pins.head}:${refs}/head`,
+    ]);
+  } catch (error) {
+    throw fetchError(
+      error instanceof Error && "stderr" in error ? String(error.stderr) : "",
+      publishing,
+    );
+  }
+
+  if (!publishing)
+    for (const commit of [pins.base, pins.head])
+      await sharedGit(root, ["cat-file", "-e", `${commit}^{commit}`]);
+}
+
+export async function repositoryReady(
+  root: string,
+  pins: Pick<Pins, "base" | "head">,
+): Promise<boolean> {
+  try {
+    const head = await sharedGit(root, ["rev-parse", "HEAD"]);
+
+    if (head.stdout.trim() !== pins.head) return false;
+
+    for (const commit of [pins.base, pins.head])
+      await sharedGit(root, ["cat-file", "-e", `${commit}^{commit}`]);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readShareRepository(root: string) {
+  let cloneUrl: string;
+
+  try {
+    cloneUrl = normalizeGitHubRemote(
+      (await sharedGit(root, ["remote", "get-url", "origin"])).stdout,
+    );
+  } catch {
+    throw new ReviewInputError("Sharing requires a GitHub origin remote.");
+  }
+
+  return { cloneUrl };
+}
+
+export async function verifyShareRepository(
+  root: string,
+  pins: Pins,
+  repository?: { cloneUrl: string },
+) {
+  const { cloneUrl } = repository ?? (await readShareRepository(root));
+  const temporary = await mkdtemp(path.join(tmpdir(), "review-share-check-"));
+
+  try {
+    await fetchPinnedRepository(temporary, cloneUrl, pins, true);
+  } finally {
+    await rm(temporary, { recursive: true, force: true });
+  }
+
+  return { cloneUrl };
+}

package/src/sharing/routes.ts

@@ -0,0 +1,34 @@
+import { ReviewInputError } from "@review/review-api/document.js";
+
+import type { SharedReviewStore } from "./import.js";
+
+/** Snapshot-backed reads used by the same HTTP routes as local reviews. */
+export class SharedReviewData {
+  constructor(private readonly store: SharedReviewStore) {}
+
+  map(id: string, resourceId: string) {
+    const map = this.store.get(id).presentation.maps[resourceId];
+
+    if (!map)
+      throw new ReviewInputError("Map is not included in this share.", 404);
+
+    return map;
+  }
+
+  async resource(id: string, resourceId: string) {
+    const resource = this.store
+      .get(id)
+      .manifest.resources.find((item) => item.id === resourceId);
+
+    if (!resource)
+      throw new ReviewInputError(
+        "Resource is not included in this share.",
+        404,
+      );
+
+    return {
+      data: await this.store.readObject(id, resource.object),
+      mimeType: resource.mimeType,
+    };
+  }
+}

package/src/slug.ts

@@ -0,0 +1,23 @@
+/** Lowercase ASCII slug: runs of anything but `a-z0-9` become one `-`, outer
+ * dashes go. Empty input, or input with no letters or digits, yields `""`;
+ * callers choose their own fallback (`"section"`, `"diagram"`, `"database"`).
+ * This is the rule sequence and lens ids were already published with, so it
+ * must not change. */
+export function slugify(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+/** First of `base`, `base-2`, `base-3`, … not present in `used`. */
+export function uniqueId(base: string, used: ReadonlySet<string>): string {
+  let candidate = base;
+
+  for (let suffix = 2; used.has(candidate); suffix += 1) {
+    candidate = `${base}-${suffix}`;
+  }
+
+  return candidate;
+}