@dev.fast/whiteboard 0.3.4 → 0.3.5-preview.20261020.130

package/src/sharing/host.ts

@@ -5,7 +5,7 @@ import { parseShareLink, shareIdSchema } from "@dev.fast/review-share-protocol";
 import {
   DEFAULT_STORE_ORIGIN,
   clearStoreAuth,
-  openUrlInBrowser,
+  type openUrlInBrowser,
   readStoreAuth,
   runStoreLogin,
 } from "@dev.fast/trace-core";
@@ -18,13 +18,18 @@ import { z } from "zod";
 
 import { readSharingAuth } from "./auth.js";
 import { ShareAuthError, ShareClient, SharePreflightError } from "./client.js";
-import { exportShare, validateShareSources } from "./export.js";
+import {
+  exportShare,
+  referenceCommits,
+  validateShareSources,
+} from "./export.js";
 import { SharedReviewStore, sharedReviewId } from "./import.js";
 import { readShareRepository, verifyShareRepository } from "./repository.js";
 
 interface LoginState {
   pending: boolean;
   url?: string;
+  userCode?: string;
   error?: string;
 }
 
@@ -61,7 +66,6 @@ export function mountSharingHost(
   options: SharingHostOptions = {},
 ) {
   const startLogin = options.login ?? runStoreLogin;
-  const openUrl = options.openUrl ?? openUrlInBrowser;
 
   let login: LoginState = {
     pending: false,
@@ -92,9 +96,9 @@ export function mountSharingHost(
         traces: false,
         stdout: discard,
         stderr: discard,
-        openUrl: async (url) => {
-          login.url = url;
-          await openUrl(url);
+        openUrl: options.openUrl,
+        onDeviceCode: (device) => {
+          Object.assign(login, device);
         },
       })
         .then((code) => {
@@ -223,13 +227,26 @@ export function mountSharingPublisher(
         409,
       );
 
-    const root = snapshot.pins
-      ? store.repositoryPath(snapshot.pins.repositoryId)
-      : undefined;
+    const repositoryId =
+      snapshot.pins?.repositoryId ?? snapshot.target?.repositoryId;
+
+    const root = repositoryId ? store.repositoryPath(repositoryId) : undefined;
 
-    const repository = root
-      ? await (options.readRepository ?? readShareRepository)(root)
-      : undefined;
+    const readRepository = options.readRepository ?? readShareRepository;
+
+    // Unpinned boards name their repository when they can, so receivers can
+    // group them.
+    const repository = !root
+      ? undefined
+      : snapshot.pins
+        ? await readRepository(root)
+        : await (async () => {
+            try {
+              return await readRepository(root);
+            } catch {
+              return undefined;
+            }
+          })();
 
     const bundle = await exportShare({
       store,
@@ -239,9 +256,12 @@ export function mountSharingPublisher(
       repository,
     });
 
+    const commits = referenceCommits(snapshot);
+
+    // The commits must be on GitHub for a recipient to fetch them.
     const verification =
-      root && snapshot.pins && repository
-        ? verifyRepository(root, snapshot.pins, repository).then(
+      root && (snapshot.pins || commits.length) && repository
+        ? verifyRepository(root, snapshot.pins, repository, commits).then(
             () => ({ ok: true as const }),
             (error: Error) => ({ ok: false as const, error }),
           )

package/src/sharing/import.ts

@@ -28,6 +28,9 @@ import { textIncludesQuote } from "@review/evidence.js";
 import { lensSchema } from "@review/review-api/diff-lenses.js";
 import { ReviewInputError } from "@review/review-api/document.js";
 import {
+  type FileLineRange,
+  type Pins,
+  anchorPins,
   checkReferences,
   documentSchema,
   pinsSchema,
@@ -52,10 +55,16 @@ import { z } from "zod";
 import {
   type ShareBundle,
   digestBytes,
+  referenceCommits,
   validateShareSources,
 } from "./export.js";
 import {
+  COMMIT_ID,
+  assertCommitIds,
+  cloneSharedRepository,
   fetchPinnedRepository,
+  fetchSharedCommits,
+  forgetSharedCommits,
   repositoryReady,
   sharedGit,
 } from "./repository.js";
@@ -63,11 +72,12 @@ import {
 export const sharedSnapshotSchema = z.strictObject({
   reviewId: z.string().min(1),
   version: z.number().int().nonnegative(),
-  title: z.string().min(1),
+  /** Empty for a board never named; it reads "Untitled". */
+  title: z.string(),
   pins: pinsSchema
     .extend({
-      base: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/),
-      head: z.string().regex(/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/),
+      base: z.string().regex(COMMIT_ID),
+      head: z.string().regex(COMMIT_ID),
     })
     .optional(),
   document: documentSchema,
@@ -90,7 +100,7 @@ const count = z.number().int().nonnegative();
 const counts = z.strictObject({ additions: count, deletions: count });
 
 const mapSchema = z.strictObject({
-  commit: z.string(),
+  commit: z.string().regex(COMMIT_ID),
   side: z.enum(["base", "head"]),
   elements: z.array(normalizedSoftwareElementSchema),
   relationships: z.array(normalizedSoftwareRelationshipSchema),
@@ -166,8 +176,10 @@ export function validateShareBundle(bundle: ShareBundle) {
     throw new Error("Shared snapshot does not match its manifest.");
   checkReferences(snapshot.document);
   validateShareSources(snapshot);
+  // Every commit it quotes reaches git as an argument.
+  assertCommitIds(referenceCommits(snapshot));
 
-  if (Boolean(snapshot.pins) !== Boolean(manifest.repository))
+  if (snapshot.pins && !manifest.repository)
     throw new Error("Shared source pins require a repository.");
 
   const presentation = sharePresentationSchema.parse(
@@ -285,6 +297,7 @@ export class SharedReviewStore {
   constructor(
     readonly root: string,
     private readonly fetchRepository = fetchPinnedRepository,
+    private readonly cloneRepository = cloneSharedRepository,
   ) {
     this.purgeTimer = setInterval(() => {
       void this.purgeExpired().catch((error) =>
@@ -372,7 +385,7 @@ export class SharedReviewStore {
       throw new ReviewInputError("Shared review is not available.", 404);
 
     if (!saved.snapshot.pins) {
-      this.setStatus(id, "ready");
+      await this.prepareUnpinned(id, saved.manifest.repository?.cloneUrl);
 
       return;
     }
@@ -381,10 +394,12 @@ export class SharedReviewStore {
       throw new ReviewInputError("Repository service is unavailable.", 409);
     const root = this.repositoryRoot(id);
 
+    const commits = referenceCommits(saved.snapshot);
+
     try {
       this.setStatus(id, "fetching");
 
-      if (!(await repositoryReady(root, saved.snapshot.pins))) {
+      if (!(await repositoryReady(root, saved.snapshot.pins, commits))) {
         const prior = this.repositories.get(id);
         await local.data.workspaces.remove(id);
 
@@ -394,11 +409,13 @@ export class SharedReviewStore {
           root,
           saved.manifest.repository!.cloneUrl,
           saved.snapshot.pins,
+          false,
+          commits,
         );
         await sharedGit(root, [
           "checkout",
           "--detach",
-          saved.snapshot.pins.head,
+          { commit: saved.snapshot.pins.head },
         ]);
       }
 
@@ -413,16 +430,7 @@ export class SharedReviewStore {
       this.setStatus(id, "validating");
       await local.data.validatePins(pins);
 
-      const references = sourceReferences(saved.snapshot.document).map(
-        (item) => item.source,
-      );
-
-      for (const map of Object.values(saved.presentation.maps))
-        for (const element of map.elements)
-          for (const range of element.sourceRanges ?? [])
-            references.push({ ...range, side: map.side });
-
-      await local.data.validateSources(pins, references);
+      await this.validateReferences(saved, repository.id, pins);
       await local.data.workspaces.open(id, pins);
 
       if (
@@ -449,13 +457,114 @@ export class SharedReviewStore {
     }
   }
 
+  /** Reads each of a shared board's references at its own commits, in the
+   * checkout of its repository. */
+  private async validateReferences(
+    saved: ReturnType<typeof validateShareBundle>,
+    repositoryId: string,
+    pins?: Pins,
+  ) {
+    const references = new Map<
+      string,
+      { pins: Pins; ranges: FileLineRange[] }
+    >();
+
+    const add = (at: Pins, range: FileLineRange) => {
+      const key = JSON.stringify([at.base, at.head]);
+      const group = references.get(key) ?? { pins: at, ranges: [] };
+
+      group.ranges.push(range);
+      references.set(key, group);
+    };
+
+    for (const { source } of sourceReferences(saved.snapshot.document, {
+      repositoryId,
+    }))
+      add({ ...anchorPins(source, pins), repositoryId }, source);
+
+    if (pins)
+      for (const map of Object.values(saved.presentation.maps))
+        for (const element of map.elements)
+          for (const range of element.sourceRanges ?? [])
+            add(pins, { ...range, side: map.side });
+
+    for (const group of references.values())
+      await this.local!.data.validateSources(group.pins, group.ranges);
+  }
+
+  /** Files an unpinned board under a local checkout of its repository,
+   * else a managed clone. */
+  private async prepareUnpinned(id: string, cloneUrl: string | undefined) {
+    const local = this.local;
+    const saved = this.validated.get(id)!;
+
+    if (!cloneUrl || !local) {
+      this.setStatus(id, "ready");
+
+      return;
+    }
+
+    const root = this.repositoryRoot(id);
+
+    try {
+      this.setStatus(id, "fetching");
+      const managed = path.join(await realpath(this.root), ".repositories");
+
+      let repositoryId = local.store
+        .checkoutsOf(cloneUrl)
+        .find(
+          (checkout) =>
+            !local.store.repositoryPath(checkout).startsWith(managed),
+        );
+
+      if (!repositoryId) {
+        if (!existsSync(path.join(root, ".git"))) {
+          await rm(root, { recursive: true, force: true });
+          await this.cloneRepository(root, cloneUrl);
+        }
+
+        repositoryId = (await local.data.register(root)).id;
+      }
+
+      // A plan's commit links read at commits the checkout may not have.
+      const checkout = local.store.repositoryPath(repositoryId);
+
+      await fetchSharedCommits(
+        checkout,
+        referenceCommits(saved.snapshot, repositoryId),
+        id,
+      );
+      this.setStatus(id, "validating");
+      await this.validateReferences(saved, repositoryId);
+      this.repositories.set(id, repositoryId);
+      await writeFile(
+        path.join(this.root, id, "repository.json"),
+        JSON.stringify({ repositoryId, ready: true }),
+        { mode: 0o600 },
+      );
+      this.setStatus(id, "ready");
+    } catch (error) {
+      const message =
+        error instanceof ReviewInputError
+          ? error.message
+          : "Could not prepare the shared repository. Check Git credentials and retry.";
+
+      this.setStatus(id, "error", message);
+      throw new ReviewInputError(message, 409);
+    }
+  }
+
   async assertReady(id: string) {
     const saved = this.validated.get(id);
 
     if (
       !saved ||
       (saved.snapshot.pins &&
-        !(await repositoryReady(this.repositoryRoot(id), saved.snapshot.pins)))
+        !(await repositoryReady(
+          this.repositoryRoot(id),
+          saved.snapshot.pins,
+          referenceCommits(saved.snapshot),
+        )))
     ) {
       this.setStatus(
         id,
@@ -517,9 +626,14 @@ export class SharedReviewStore {
             ),
           );
 
+        // A board with no pins may use the receiver's own checkout.
         if (
           this.local?.store.repositoryPath(metadata.repositoryId) ===
-          path.join(await realpath(this.root), ".repositories", id)
+            path.join(await realpath(this.root), ".repositories", id) ||
+          (!validated.snapshot.pins &&
+            this.local?.store
+              .repositories()
+              .some((repository) => repository.id === metadata.repositoryId))
         ) {
           this.repositories.set(id, metadata.repositoryId);
           prepared = metadata.ready;
@@ -528,13 +642,17 @@ export class SharedReviewStore {
         /* A first or interrupted import has no local registration yet. */
       }
 
-      if (!validated.snapshot.pins) this.setStatus(id, "ready");
-      else if (
+      if (!validated.snapshot.pins) {
+        if (this.repositories.has(id) || !validated.manifest.repository)
+          this.setStatus(id, "ready");
+        else void this.prepare(id).catch(() => {});
+      } else if (
         prepared &&
         this.local &&
         (await repositoryReady(
           this.repositoryRoot(id),
           validated.snapshot.pins,
+          referenceCommits(validated.snapshot),
         ))
       ) {
         const repository = await this.local.data.register(
@@ -637,7 +755,9 @@ export class SharedReviewStore {
               ...validated.snapshot.pins,
               repositoryId: repositoryId!,
             }
-          : undefined,
+          : repositoryId
+            ? { kind: "project" as const, repositoryId }
+            : undefined,
         shared: {
           ...bundle.attribution,
           cloneUrl: bundle.manifest.repository?.cloneUrl,
@@ -658,11 +778,16 @@ export class SharedReviewStore {
       .map((id) => {
         const { document: _document, ...snapshot } = this.get(id).snapshot;
 
+        const project = snapshot.target
+          ? this.local?.store.checkoutProject(snapshot.target.repositoryId)
+          : undefined;
+
         return {
           ...snapshot,
           firstCreatedAt:
             snapshot.version === 0 ? snapshot.createdAt : undefined,
           repositoryName: "Shared review",
+          ...(project && { project }),
           viewedAt: this.attention.get(id)?.viewedAt ?? null,
           trashedAt: this.attention.get(id)?.trashedAt ?? null,
         };
@@ -700,8 +825,15 @@ export class SharedReviewStore {
     const repositoryId = this.repositories.get(id);
 
     if (repositoryId) {
+      const checkout = this.local?.store.repositoryPath(repositoryId);
+
+      // The commits kept for its links go with it.
+      if (checkout)
+        await forgetSharedCommits(checkout, id).catch((error) =>
+          console.error(`Could not drop the refs kept for share ${id}:`, error),
+        );
       await this.local?.data.forgetRepository(repositoryId);
-      this.local?.store.unregisterRepository(repositoryId);
+      await this.local?.store.unregisterRepository(repositoryId);
     }
 
     await rm(this.repositoryRoot(id), { recursive: true, force: true });

package/src/sharing/repository.ts

@@ -2,12 +2,25 @@ 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 { type VcsArg, gitAt } from "@dev.fast/local-vcs";
 import { normalizeGitHubRemote } from "@dev.fast/review-share-protocol";
 import { type Pins, ReviewInputError } from "@review/review-api/document.js";
 
+/** A full commit id, SHA-1 or SHA-256. */
+export const COMMIT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+
+/** Refuses anything but full commit ids, before any of them reaches git:
+ * a shared board's commits come from someone else, and one spelled as an
+ * option or a refspec would make git do something else. */
+export function assertCommitIds(commits: readonly string[]) {
+  if (!commits.every((commit) => COMMIT_ID.test(commit)))
+    throw new ReviewInputError(
+      "The shared whiteboard names a commit that isn't a full commit id.",
+    );
+}
+
 /** Keep credential helpers but prevent the calling shell from redirecting Git's object store. */
-export function sharedGit(cwd: string, args: string[]) {
+export function sharedGit(cwd: string, args: VcsArg[]) {
   const env = Object.fromEntries(
     Object.entries(process.env).filter(
       ([key]) =>
@@ -25,7 +38,7 @@ export function sharedGit(cwd: string, args: string[]) {
     cwd,
     ["-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", ...args],
     {
-      env: { ...env, GIT_TERMINAL_PROMPT: "0" },
+      env,
       timeout: 300_000,
     },
   );
@@ -46,18 +59,28 @@ function fetchError(stderr: string, publishing: boolean): ReviewInputError {
   );
 }
 
-/** Recipients need complete history; publication only checks that the commits exist. */
+/** Recipients need complete history; publication only checks that the commits exist.
+ * `commits` are other commits the board's references read at; a plan has
+ * only those. */
 export async function fetchPinnedRepository(
   root: string,
   url: string,
-  pins: Pick<Pins, "base" | "head">,
+  pins: Pick<Pins, "base" | "head"> | undefined,
   publishing = false,
+  commits: readonly string[] = [],
 ) {
-  if (
-    ![pins.base, pins.head].every((commit) =>
-      /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(commit),
-    )
-  )
+  // Each commit and the ref it is fetched to.
+  const named = [
+    ...(pins
+      ? [
+          { commit: pins.base, ref: "base" },
+          { commit: pins.head, ref: "head" },
+        ]
+      : []),
+    ...commits.map((commit) => ({ commit, ref: `commits/${commit}` })),
+  ];
+
+  if (!named.every(({ commit }) => COMMIT_ID.test(commit)))
     throw new ReviewInputError(
       "Sharing requires immutable base and head commits.",
     );
@@ -67,7 +90,7 @@ export async function fetchPinnedRepository(
   if (!publishing) {
     await sharedGit(root, ["config", "core.hooksPath", "/dev/null"]);
     await sharedGit(root, ["config", "core.fsmonitor", "false"]);
-    await sharedGit(root, ["remote", "add", "origin", url]);
+    await sharedGit(root, ["remote", "add", "origin", { remote: url }]);
   }
 
   // Branch refs make Git reject non-commit objects during the fetch itself.
@@ -79,9 +102,10 @@ export async function fetchPinnedRepository(
       "--no-tags",
       "--force",
       ...(publishing ? ["--depth=1", "--filter=tree:0"] : []),
-      publishing ? url : "origin",
-      `${pins.base}:${refs}/base`,
-      `${pins.head}:${refs}/head`,
+      { remote: publishing ? url : "origin" },
+      ...named.map(({ commit, ref }) => ({
+        refspec: { from: commit, to: `${refs}/${ref}` },
+      })),
     ]);
   } catch (error) {
     throw fetchError(
@@ -91,21 +115,104 @@ export async function fetchPinnedRepository(
   }
 
   if (!publishing)
-    for (const commit of [pins.base, pins.head])
-      await sharedGit(root, ["cat-file", "-e", `${commit}^{commit}`]);
+    for (const { commit } of named)
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
+}
+
+/** Fetches the commits a shared board's links read at into a checkout of
+ * its repository, from its origin unless it has them, and keeps each under
+ * `refs/review/shared/<share>/<commit>`, so `git gc` can't prune one the
+ * board still quotes. */
+export async function fetchSharedCommits(
+  root: string,
+  commits: readonly string[],
+  share: string,
+) {
+  assertCommitIds(commits);
+
+  const ref = (commit: string) => `refs/review/shared/${share}/${commit}`;
+  const missing: string[] = [];
+
+  for (const commit of commits)
+    try {
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
+      await sharedGit(root, ["update-ref", { ref: ref(commit) }, { commit }]);
+    } catch {
+      missing.push(commit);
+    }
+
+  if (!missing.length) return;
+
+  try {
+    await sharedGit(root, [
+      "fetch",
+      "--no-tags",
+      "origin",
+      ...missing.map((commit) => ({
+        refspec: { from: commit, to: ref(commit), force: true },
+      })),
+    ]);
+  } catch (error) {
+    throw fetchError(
+      error instanceof Error && "stderr" in error ? String(error.stderr) : "",
+      false,
+    );
+  }
+}
+
+/** Drops the refs `fetchSharedCommits` kept for a share, once the share is
+ * gone, so `git gc` can prune what only it quoted. */
+export async function forgetSharedCommits(root: string, share: string) {
+  const { stdout } = await sharedGit(root, [
+    "for-each-ref",
+    "--format=%(refname)",
+    { ref: `refs/review/shared/${share}/` },
+  ]);
+
+  for (const ref of stdout.split("\n").filter(Boolean))
+    await sharedGit(root, ["update-ref", "-d", { ref }]);
+}
+
+/** A managed clone of a repository's default branch, for a shared board
+ * with no pins whose repository the receiver has no checkout of. */
+export async function cloneSharedRepository(root: string, url: string) {
+  await mkdir(root, { recursive: true, mode: 0o700 });
+  await sharedGit(root, ["init", "--quiet"]);
+  await sharedGit(root, ["config", "core.hooksPath", "/dev/null"]);
+  await sharedGit(root, ["config", "core.fsmonitor", "false"]);
+  await sharedGit(root, ["remote", "add", "origin", { remote: url }]);
+
+  try {
+    await sharedGit(root, ["fetch", "--no-tags", "origin", "HEAD"]);
+  } catch (error) {
+    throw fetchError(
+      error instanceof Error && "stderr" in error ? String(error.stderr) : "",
+      false,
+    );
+  }
+
+  await sharedGit(root, ["checkout", "--detach", "FETCH_HEAD"]);
 }
 
 export async function repositoryReady(
   root: string,
   pins: Pick<Pins, "base" | "head">,
+  commits: readonly string[] = [],
 ): Promise<boolean> {
+  if (
+    ![pins.base, pins.head, ...commits].every((commit) =>
+      COMMIT_ID.test(commit),
+    )
+  )
+    return false;
+
   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}`]);
+    for (const commit of [pins.base, pins.head, ...commits])
+      await sharedGit(root, ["cat-file", "-e", { rev: `${commit}^{commit}` }]);
 
     return true;
   } catch {
@@ -129,14 +236,15 @@ export async function readShareRepository(root: string) {
 
 export async function verifyShareRepository(
   root: string,
-  pins: Pins,
+  pins: Pins | undefined,
   repository?: { cloneUrl: string },
+  commits: readonly string[] = [],
 ) {
   const { cloneUrl } = repository ?? (await readShareRepository(root));
   const temporary = await mkdtemp(path.join(tmpdir(), "review-share-check-"));
 
   try {
-    await fetchPinnedRepository(temporary, cloneUrl, pins, true);
+    await fetchPinnedRepository(temporary, cloneUrl, pins, true, commits);
   } finally {
     await rm(temporary, { recursive: true, force: true });
   }

package/src/startup-trace.ts

@@ -221,9 +221,9 @@ if (traceEnabled) {
   // Every git/jj spawn inside @dev.fast/local-vcs becomes a `$ …` span under
   // whatever span is active in the caller's async context.
   setLocalVcsCommandObserver({
-    start({ file, args, cwd }) {
-      const handle = startSpan(commandSpanName(file, args), {
-        detail: commandDetail(file, args, cwd),
+    start({ tool, args, cwd }) {
+      const handle = startSpan(commandSpanName(tool, args), {
+        detail: commandDetail(tool, args, cwd),
       });
 
       return ({ ok }) => (ok ? handle.end() : handle.fail());