@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/telemetry-debug-sink.ts

@@ -0,0 +1,38 @@
+// Developer-only telemetry sink. When DEV_FAST_REVIEW_TELEMETRY_DEBUG is `1`
+// or `true`, Review prints each event to stderr and sends nothing to PostHog.
+// The switch is an environment variable, not a CLI flag, because the CLI, the
+// local server, and the Desktop server host each build their own telemetry
+// instance, and most events reach the server process, not the CLI.
+import type { PostHogCaptureInput } from "./posthog-capture-client";
+import type { ReviewTelemetryCaptureClient } from "./review-telemetry";
+
+/**
+ * The debug sink, or `undefined` when the switch is off. The sink replaces the
+ * PostHog client: a developer run never reaches the production project.
+ */
+export function createTelemetryDebugSink(
+  env: NodeJS.ProcessEnv,
+  output: NodeJS.WritableStream = process.stderr,
+): ReviewTelemetryCaptureClient | undefined {
+  if (!isEnabledEnvValue(env.DEV_FAST_REVIEW_TELEMETRY_DEBUG)) return undefined;
+
+  return {
+    enabled: true,
+    // Printing is not sending, so the sink prints events that the opt-out
+    // would otherwise drop.
+    ignoresOptOut: true,
+    capture(input: PostHogCaptureInput): Promise<void> {
+      try {
+        output.write(`[review-telemetry] ${JSON.stringify(input)}\n`);
+      } catch {
+        // The sink is a developer aid and must never affect Review behavior.
+      }
+
+      return Promise.resolve();
+    },
+  };
+}
+
+function isEnabledEnvValue(value: string | undefined): boolean {
+  return value === "1" || value?.toLowerCase() === "true";
+}

package/src/telemetry.ts

@@ -0,0 +1,13 @@
+// Keep this compatibility module because the review server and app import it.
+// The implementation lives in one place so CLI and UI telemetry share the
+// same install state, privacy checks, queue, and transport.
+export {
+  ReviewTelemetry,
+  createLogger,
+  isTelemetryOptedOut,
+  type Logger,
+  type ReviewTabTelemetryEvent,
+  type ReviewTabTelemetryReason,
+  type ReviewTelemetryTab,
+  type ReviewTelemetryContext,
+} from "./review-telemetry";

package/src/trace-cli.ts

@@ -0,0 +1,156 @@
+import type { Writable } from "node:stream";
+
+import type { ReviewApiSummary } from "@dev.fast/review-protocol";
+import {
+  type TraceListScope,
+  type TracePullScope,
+  type TraceReviewScope,
+  errorMessage,
+  runTraceList as listWithScope,
+  runTracePull as pullWithScope,
+  resolveTraceReadStorage,
+} from "@dev.fast/trace-core";
+import type { TraceStorageKind } from "@dev.fast/trace-core";
+
+import { runReviewInfo } from "./review-info";
+
+/**
+ * The Review app's trace commands. It resolves `--review <uuid>` (or the
+ * Review that owns the current checkout) against the Review store and hands
+ * the change range to the store-free read commands as a value.
+ */
+
+export {
+  runTraceDisable,
+  runTraceEnable,
+  runTraceGitHook,
+  runTraceHook,
+  runTraceRepair,
+  runTraceStatus,
+  runTraceSync,
+  type TraceListScope,
+  type TracePullScope,
+  type TraceReviewScope,
+  runTraceBlame,
+  runTraceLookupCommit,
+  runTraceLookupSession,
+  runTraceShow,
+} from "@dev.fast/trace-core";
+
+export async function resolveTraceReviewScope(
+  cwd: string,
+  reviewUuid: string | undefined,
+): Promise<TraceReviewScope> {
+  const review = await resolveTraceReview(cwd, reviewUuid);
+
+  if (!review.repositoryPath || !review.pins)
+    throw new Error("Review repository is unavailable.");
+
+  return {
+    uuid: review.reviewId,
+    repoRoot: review.repositoryPath,
+    baseCommit: review.pins.base,
+    headCommit: review.pins.head,
+  };
+}
+
+export async function runTraceList(input: {
+  cwd: string;
+  reviewUuid?: string;
+  commitSha?: string;
+  storage?: TraceStorageKind;
+  json?: boolean;
+  stdout: Writable;
+}): Promise<number> {
+  const resolvedStorage = await resolveTraceReadStorage(
+    input.storage,
+    input.cwd,
+  );
+  // Without --commit the command lists the Review's range, so a missing
+  // --review still resolves the Review that owns this checkout.
+
+  const scope: TraceListScope = input.commitSha
+    ? { commit: input.commitSha }
+    : { review: await resolveTraceReviewScope(input.cwd, input.reviewUuid) };
+
+  return listWithScope({
+    cwd: input.cwd,
+    scope,
+    resolvedStorage,
+    json: input.json,
+    stdout: input.stdout,
+  });
+}
+
+export async function runTracePull(input: {
+  cwd: string;
+  repo?: string;
+  reviewUuid?: string;
+  commitSha?: string;
+  session?: string;
+  mainOnly?: boolean;
+  storage?: TraceStorageKind;
+  json?: boolean;
+  stdout: Writable;
+  stderr: Writable;
+}): Promise<number> {
+  try {
+    const resolvedStorage = await resolveTraceReadStorage(
+      input.storage,
+      input.cwd,
+    );
+
+    const scope = await resolveTracePullScope(input);
+
+    return pullWithScope({
+      cwd: input.cwd,
+      scope,
+      repo: input.repo,
+      mainOnly: input.mainOnly,
+      resolvedStorage,
+      json: input.json,
+      stdout: input.stdout,
+      stderr: input.stderr,
+    });
+  } catch (error) {
+    input.stderr.write(`trace pull error: ${errorMessage(error)}\n`);
+
+    return 1;
+  }
+}
+
+async function resolveTracePullScope(input: {
+  cwd: string;
+  reviewUuid?: string;
+  commitSha?: string;
+  session?: string;
+}): Promise<TracePullScope> {
+  if (input.reviewUuid) {
+    return {
+      review: await resolveTraceReviewScope(input.cwd, input.reviewUuid),
+    };
+  }
+
+  if (input.commitSha) return { commit: input.commitSha };
+
+  if (input.session) return { session: input.session };
+
+  return { repository: true };
+}
+
+async function resolveTraceReview(
+  cwd: string,
+  reviewUuid: string | undefined,
+): Promise<ReviewApiSummary> {
+  const candidates = (await runReviewInfo({ cwd, reviewUuid })).reviews;
+
+  if (candidates.length === 0) {
+    throw new Error("No review found for this worktree.");
+  }
+
+  if (candidates.length > 1) {
+    throw new Error("Multiple Whiteboards require --session <uuid>.");
+  }
+
+  return candidates[0];
+}

package/src/trace-storage-cli.ts

@@ -0,0 +1,509 @@
+import { existsSync, renameSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import {
+  type CliJsonOutput,
+  DEFAULT_HOSTED_ORIGIN,
+  HOSTED_CAPTURE_SCOPE_DESCRIPTION,
+  type S3CaptureSettings,
+  type S3Credentials,
+  type S3Profile,
+  S3_DEFAULT_REGION,
+  StoreApiError,
+  StoreClient,
+  type TraceConfig,
+  TraceConfigurationError,
+  type TraceRepositoryTarget,
+  clearTraceEnvCache,
+  currentStore,
+  describeSelection,
+  emitJsonEvent,
+  emptyTraceConfig,
+  errorMessage,
+  failWithJsonError,
+  humanStream,
+  isS3MockMode,
+  loadS3TraceStorage,
+  normalizeStoreOrigin,
+  readLegacyCaptureSettings,
+  readStoreAuth,
+  readTraceConfigFile,
+  readTraceEnvFile,
+  readTraceUserConfig,
+  requireTraceConsent,
+  resolveS3Setup,
+  resolveTraceRepositoryTarget,
+  s3ProfileSchema,
+  s3Store,
+  sameS3Profile,
+  selectTraceStorage,
+  traceMachineStatus,
+  traceRepositoryStatus,
+  traceSettingsPath,
+  writeTraceConfigFile,
+} from "@dev.fast/trace-core";
+
+import { devReviewHome } from "./review-home-paths";
+
+/**
+ * `whiteboard trace storage use` and `whiteboard trace config migrate`: the explicit
+ * selection and configuration commands. Both write only
+ * `$DEV_REVIEW_HOME/trace/config.json`; the legacy files, environment, and
+ * every remote object stay as they are.
+ */
+
+interface TraceStorageCommandScope {
+  homeDir?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface RunReviewTraceStorageUseInput
+  extends CliJsonOutput, TraceStorageCommandScope {
+  cwd: string;
+  mode: string;
+  origin?: string;
+  /** The hosted API client; tests inject one that answers locally. */
+  client?: StoreClient;
+  endpoint?: string;
+  bucket?: string;
+  key?: string;
+  secret?: string;
+  region?: string;
+}
+
+export async function runTraceStorageUse(
+  input: RunReviewTraceStorageUseInput,
+): Promise<number> {
+  const stage = "trace.storage.use";
+  const scope = commandScope(input);
+
+  if (input.mode === "hosted") return useHosted(input, scope, stage);
+
+  if (input.mode !== "s3") {
+    return failWithJsonError(
+      input,
+      stage,
+      `Unknown storage mode "${input.mode}". Use "s3" or "hosted".`,
+    );
+  }
+
+  try {
+    const configFile = readTraceConfigFile(scope);
+
+    if (configFile.error) throw new TraceConfigurationError(configFile.error);
+    const current = configFile.config ?? emptyTraceConfig();
+    const flags = [input.endpoint, input.bucket, input.key, input.secret];
+    let next: TraceConfig;
+
+    if (flags.some(Boolean)) {
+      if (!flags.every(Boolean)) {
+        throw new TraceConfigurationError(
+          "The s3 store needs --endpoint, --bucket, --key, and --secret together.",
+        );
+      }
+
+      const profile = s3ProfileSchema.parse({
+        endpoint: input.endpoint,
+        bucket: input.bucket,
+        accessKeyId: input.key,
+        secretAccessKey: input.secret,
+        region:
+          input.region?.trim() ||
+          current.stores?.s3?.region ||
+          S3_DEFAULT_REGION,
+        capture: current.stores?.s3?.capture ??
+          (await readLegacyCaptureSettings(
+            traceSettingsPath(scope.homeDir, scope.env),
+          )) ?? { enabled: true, autoActivateRepositories: true },
+      });
+
+      await requireReachable(profile, scope);
+      next = {
+        ...current,
+        "current-store": "s3",
+        stores: { ...current.stores, s3: profile },
+      };
+    } else {
+      const setup = resolveS3Setup(scope);
+
+      if (!setup.credentials && !isS3MockMode(scope.env)) {
+        throw new TraceConfigurationError(
+          "No S3/R2 credentials are configured. Pass --endpoint, --bucket, --key, and --secret, or use Whiteboard Agent Setup.",
+        );
+      }
+
+      next = { ...current, "current-store": "s3" };
+    }
+
+    await writeTraceConfigFile(configFile, next);
+    clearTraceEnvCache();
+
+    const selection = selectTraceStorage(scope);
+    const machine = await traceMachineStatus(scope);
+    const repository = await traceRepositoryStatus(input.cwd);
+    const human = humanStream(input);
+    human.write(`Storage: ${describeSelection(selection)}\n`);
+    human.write(`Capture: ${machine.enabled ? "enabled" : "disabled"}\n`);
+    human.write(`Repository: ${repository.message}\n`);
+    emitJsonEvent(input, {
+      event: stage,
+      mode: "s3",
+      configPath: configFile.path,
+      endpoint: machine.endpoint ?? null,
+      bucket: machine.bucket ?? null,
+      region: machine.region ?? null,
+      captureEnabled: machine.enabled,
+      repository: repository.message,
+    });
+
+    return 0;
+  } catch (error) {
+    return failWithJsonError(input, stage, errorMessage(error));
+  }
+}
+
+/**
+ * Selecting hosted storage validates everything a publication needs: a
+ * login for the origin, a store that answers the revised contract, and
+ * consent for this checkout's repository at that origin. Only then is the
+ * selection persisted. Bucket credentials stay where they are, inert.
+ */
+async function useHosted(
+  input: RunReviewTraceStorageUseInput,
+  scope: { homeDir: string; env: NodeJS.ProcessEnv },
+  stage: string,
+): Promise<number> {
+  try {
+    const auth = await readStoreAuth(scope.env);
+
+    const origin = normalizeStoreOrigin(
+      input.origin ?? auth?.origin ?? DEFAULT_HOSTED_ORIGIN,
+    );
+
+    if (!auth || auth.origin !== origin) {
+      throw new TraceConfigurationError(
+        `Log in to ${origin} first: \`whiteboard login --origin ${origin}\`.`,
+      );
+    }
+
+    const devHome = devReviewHome(scope.env, scope.homeDir);
+
+    const client =
+      input.client ?? new StoreClient({ origin, token: auth.token });
+
+    let target: TraceRepositoryTarget;
+
+    try {
+      ({ target } = await resolveTraceRepositoryTarget({
+        cwd: input.cwd,
+        origin,
+        client,
+        write: true,
+        devHome,
+      }));
+    } catch (error) {
+      if (error instanceof StoreApiError && error.code === "upgrade_required") {
+        throw new TraceConfigurationError(
+          `${origin} does not serve the trace store contract this version of Whiteboard needs. Hosted storage was not selected.`,
+        );
+      }
+
+      throw error;
+    }
+
+    const consent = await requireTraceConsent(target, devHome);
+
+    const configFile = readTraceConfigFile(scope);
+
+    if (configFile.error) throw new TraceConfigurationError(configFile.error);
+    const current = configFile.config ?? emptyTraceConfig();
+    // The default origin needs no entry; any other origin is written down.
+    const stores = { ...current.stores };
+
+    if (origin === DEFAULT_HOSTED_ORIGIN) delete stores.hosted;
+    else stores.hosted = { origin };
+    await writeTraceConfigFile(configFile, {
+      ...current,
+      "current-store": "hosted",
+      stores,
+    });
+    clearTraceEnvCache();
+
+    const config = await readTraceUserConfig(devHome);
+    const human = humanStream(input);
+    human.write(`Storage: hosted (${origin})\n`);
+    human.write(
+      `Destination: ${target.name} (repository ${target.repositoryId}, store ${target.storeId})\n`,
+    );
+    human.write(
+      `Publication scope: ${config.repositories
+        .filter((entry) => entry.enabledOrigins.includes(origin))
+        .map((entry) => entry.name)
+        .join(", ")}\n`,
+    );
+
+    if (selectTraceStorage(scope).s3?.credentials) {
+      human.write(
+        "Bucket credentials stay saved and inactive; `whiteboard trace storage use s3` switches back.\n",
+      );
+    }
+
+    human.write(HOSTED_CAPTURE_SCOPE_DESCRIPTION);
+
+    emitJsonEvent(input, {
+      event: stage,
+      mode: "hosted",
+      configPath: configFile.path,
+      origin,
+      repositoryId: target.repositoryId,
+      storeId: target.storeId,
+      name: target.name,
+      allowedAt: consent.allowedAt,
+      allowedRepositories: config.repositories
+        .filter((entry) => entry.enabledOrigins.includes(origin))
+        .map((entry) => entry.name),
+    });
+
+    return 0;
+  } catch (error) {
+    return failWithJsonError(input, stage, errorMessage(error));
+  }
+}
+
+export interface RunReviewTraceConfigMigrateInput
+  extends CliJsonOutput, TraceStorageCommandScope {
+  dryRun?: boolean;
+  /** Leave the legacy env and settings files in place after migrating. */
+  keepLegacy?: boolean;
+}
+
+/**
+ * Where a migrated legacy file goes: `legacy_<name>` beside the original,
+ * with a timestamp when that name is already taken by an earlier backup.
+ */
+export function legacyRetiredPath(filePath: string): string {
+  const base = path.join(
+    path.dirname(filePath),
+    `legacy_${path.basename(filePath)}`,
+  );
+
+  if (!existsSync(base)) return base;
+
+  return `${base}.${new Date().toISOString().replace(/[:.]/g, "-")}`;
+}
+
+/**
+ * Copies the effective legacy bucket setup into the version-2 config.
+ * Configuration moves; bucket objects, paths, and formats do not.
+ */
+export async function runTraceConfigMigrate(
+  input: RunReviewTraceConfigMigrateInput,
+): Promise<number> {
+  const stage = "trace.config.migrate";
+  const scope = commandScope(input);
+  const human = humanStream(input);
+
+  try {
+    // 1. The effective legacy inputs, overrides and custom paths included.
+    const legacy = resolveS3Setup({ ...scope, ignoreProfile: true });
+
+    if (!legacy.credentials) {
+      throw new TraceConfigurationError(
+        `No legacy S3/R2 configuration to migrate (checked ${legacy.envPath} and the environment).`,
+      );
+    }
+
+    const settingsPath = traceSettingsPath(scope.homeDir, scope.env);
+    const settings = await readLegacyCaptureSettings(settingsPath);
+
+    // 2. The candidate profile and explicit selection. Disabled or absent
+    // capture settings stay disabled; migration never enables capture.
+    const capture: S3CaptureSettings = {
+      enabled: settings?.enabled === true,
+      autoActivateRepositories:
+        settings?.enabled === true &&
+        settings.autoActivateRepositories === true,
+    };
+
+    if (settings?.verifiedAt) capture.verifiedAt = settings.verifiedAt;
+
+    const candidate = s3ProfileSchema.parse({
+      ...legacy.credentials,
+      capture,
+    });
+
+    const configFile = readTraceConfigFile(scope);
+
+    if (configFile.error) throw new TraceConfigurationError(configFile.error);
+    const current = configFile.config ?? emptyTraceConfig();
+
+    if (currentStore(current) === "hosted") {
+      throw new TraceConfigurationError(
+        `Hosted storage is selected in ${configFile.path}. Run \`whiteboard trace storage use s3\` first; migration never switches destinations.`,
+      );
+    }
+
+    const existingProfile = s3Store(current);
+
+    const unchanged =
+      existingProfile !== null && sameS3Profile(existingProfile, candidate);
+
+    if (existingProfile && !unchanged) {
+      throw new TraceConfigurationError(
+        `${configFile.path} already holds a different s3 store. Remove it or update it with \`whiteboard trace storage use s3 --endpoint ...\`; migration does not overwrite it.`,
+      );
+    }
+
+    human.write(
+      `${input.dryRun ? "Previewing" : "Migrating"} S3 trace configuration into ${configFile.path}\n`,
+    );
+    human.write(
+      `  Credentials: ${legacy.source === "process-env" ? "process environment" : legacy.envPath}${
+        legacy.overrides.length > 0 && legacy.source !== "process-env"
+          ? ` (environment overrides: ${legacy.overrides.join(", ")})`
+          : ""
+      }\n`,
+    );
+    human.write(
+      `  Capture: ${candidate.capture?.enabled ? "enabled" : "disabled"} (from ${settingsPath})\n`,
+    );
+    human.write(
+      `  Destination: ${candidate.endpoint} bucket "${candidate.bucket}" region ${candidate.region ?? S3_DEFAULT_REGION}, key ${candidate.accessKeyId.slice(0, 6)}…\n`,
+    );
+
+    // 3. Validate independently of overrides and check reachability.
+    await requireReachable(candidate, scope);
+    human.write("  Reachability: ok\n");
+
+    let status: "unchanged" | "written" | "preview";
+
+    if (input.dryRun) {
+      // A dry run touches nothing, whatever the config already holds.
+      status = "preview";
+      human.write(
+        unchanged && currentStore(current) === "s3"
+          ? "Dry run: the config already holds this profile; nothing would be written.\n"
+          : "Dry run: nothing was written.\n",
+      );
+    } else if (unchanged && currentStore(current) === "s3") {
+      status = "unchanged";
+      human.write("Nothing to do: the config already holds this profile.\n");
+    } else {
+      // 4. Atomic private write; concurrent edits are refused.
+      await writeTraceConfigFile(configFile, {
+        ...current,
+        "current-store": "s3",
+        stores: { ...current.stores, s3: candidate },
+      });
+      clearTraceEnvCache();
+      status = "written";
+      human.write(`Wrote ${configFile.path} (mode 0600).\n`);
+    }
+
+    // 5. The legacy files are retired beside their originals so the new
+    //    file is the only active source. Renaming, not deleting, keeps the
+    //    rollback a rename away. Exported variables are the user's own.
+    const retired: Array<{ from: string; to: string }> = [];
+    const kept: string[] = [];
+
+    if (!input.dryRun && !input.keepLegacy) {
+      for (const filePath of [legacy.envPath, settingsPath]) {
+        if (!existsSync(filePath)) continue;
+
+        // The env file may also hold session-root settings that only it
+        // supplies; those keys are not migrated, so such a file stays.
+        const others =
+          filePath === legacy.envPath
+            ? [...readTraceEnvFile(filePath).keys()].filter(
+                (key) => !key.startsWith("TRACE_R2_"),
+              )
+            : [];
+
+        if (others.length > 0) {
+          kept.push(`${filePath} (still supplies ${others.join(", ")})`);
+          continue;
+        }
+
+        const to = legacyRetiredPath(filePath);
+        renameSync(filePath, to);
+        retired.push({ from: filePath, to });
+      }
+
+      clearTraceEnvCache();
+    }
+
+    for (const line of kept) human.write(`Kept ${line}\n`);
+
+    if (retired.length > 0) {
+      for (const move of retired) {
+        human.write(`Retired ${move.from} -> ${move.to}\n`);
+      }
+
+      human.write(
+        `To roll back, rename the retired files back and delete ${configFile.path}. Exported TRACE_R2_* variables still take precedence.\n`,
+      );
+    } else {
+      human.write(
+        "Legacy env and settings files were left unchanged; exported TRACE_R2_* variables still take precedence.\n",
+      );
+    }
+
+    emitJsonEvent(input, {
+      event: stage,
+      status,
+      dryRun: Boolean(input.dryRun),
+      retired,
+      configPath: configFile.path,
+      credentialsSource: legacy.source,
+      overrides: legacy.overrides,
+      settingsPath,
+      endpoint: candidate.endpoint,
+      bucket: candidate.bucket,
+      region: candidate.region ?? S3_DEFAULT_REGION,
+      accessKeyIdPrefix: candidate.accessKeyId.slice(0, 6),
+      capture: candidate.capture ?? null,
+    });
+
+    return 0;
+  } catch (error) {
+    return failWithJsonError(input, stage, errorMessage(error));
+  }
+}
+
+async function requireReachable(
+  profile: S3Profile,
+  scope: TraceStorageCommandScope,
+): Promise<void> {
+  const env = scope.env ?? process.env;
+
+  if (isS3MockMode(env)) return;
+
+  const credentials: S3Credentials = {
+    endpoint: profile.endpoint,
+    bucket: profile.bucket,
+    accessKeyId: profile.accessKeyId,
+    secretAccessKey: profile.secretAccessKey,
+    region: profile.region ?? S3_DEFAULT_REGION,
+  };
+
+  const S3TraceStorage = await loadS3TraceStorage();
+
+  const readiness = await S3TraceStorage.fromCredentials(
+    credentials,
+    env,
+  ).readiness();
+
+  if (!readiness.ready) {
+    throw new TraceConfigurationError(
+      `Cannot reach S3/R2 bucket "${profile.bucket}": ${readiness.reason ?? "unknown error"}. Nothing was written; retry when the bucket is reachable.`,
+    );
+  }
+}
+
+function commandScope(scope: TraceStorageCommandScope) {
+  return {
+    homeDir: scope.homeDir ?? os.homedir(),
+    env: scope.env ?? process.env,
+  };
+}