@procedures/snapshot 0.0.0-stage → 0.1.0

package/src/procedures/snapshot/restore.ts

@@ -0,0 +1,166 @@
+/**
+ * snapshot.restore procedure
+ *
+ * Restore an environment snapshot from S3.
+ */
+
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { tmpdir } from "node:os";
+import * as tar from "tar";
+import type { ProcedureContext } from "@procedures/client";
+import type {
+  SnapshotRestoreInput,
+  SnapshotRestoreOutput,
+  SnapshotMetadata,
+} from "../../types.js";
+import { listAllObjects, findSnapshotKey } from "./s3-lookup.js";
+import { assertSnapshotName } from "./names.js";
+import { sha256File } from "./archive-io.js";
+
+/**
+ * Restore a snapshot from S3
+ */
+export async function snapshotRestore(
+  input: SnapshotRestoreInput,
+  ctx: ProcedureContext
+): Promise<SnapshotRestoreOutput> {
+  // Scratch directory used solely to hold the downloaded archive; it is always
+  // safe to delete. The extraction target is `input.targetPath` (required) and
+  // is never removed — that is the fix for the self-deleting-restore bug where
+  // targetPath defaulted to workDir and the `finally` then wiped it.
+  //
+  // The id must be a plain name, and the scratch folder is a new unique folder: before, the id
+  // went into the path, so `x/../../<dir>` made the `finally` delete <dir>, even when the S3
+  // lookup failed (deep dive DATA-1).
+  assertSnapshotName("id", input.id);
+  const workDir = mkdtempSync(join(tmpdir(), "restore-"));
+
+  try {
+
+    // First, download metadata to get archive location
+    const downloadStart = Date.now();
+
+    // Find the snapshot by ID (paginated listing, exact basename match).
+    const objects = await listAllObjects(ctx, input.bucket, "snapshots/");
+    const metadataKey = findSnapshotKey(objects, input.id, ".metadata.json");
+
+    if (!metadataKey) {
+      throw new Error(`Snapshot not found: ${input.id}`);
+    }
+
+    // Download metadata
+    const metadataResult = await ctx.client.call<
+      { bucket: string; key: string; encoding?: string },
+      { body: string }
+    >(["s3", "download"], {
+      bucket: input.bucket,
+      key: metadataKey,
+      encoding: "utf8",
+    });
+
+    const metadata: SnapshotMetadata = JSON.parse(metadataResult.body);
+
+    // Download archive
+    const archiveKey = metadataKey.replace(".metadata.json", ".tar.gz");
+    const archivePath = join(workDir, `${input.id}.tar.gz`);
+
+    // Stream the archive to disk: an archive can be large, and loading it into memory as
+    // base64 was a third larger again (BUGS-2026-07 M22)
+    await ctx.client.call<
+      { bucket: string; key: string; destPath: string },
+      { path?: string }
+    >(["s3", "download"], {
+      bucket: input.bucket,
+      key: archiveKey,
+      destPath: archivePath,
+    });
+
+    // Verify the downloaded archive against the checksum recorded at snapshot
+    // creation time. Do this before extracting so a corrupted or tampered
+    // archive never reaches the target directory.
+    if (metadata.checksum) {
+      const actualChecksum = await sha256File(archivePath);
+      if (actualChecksum !== metadata.checksum) {
+        throw new Error(
+          `Checksum mismatch for snapshot ${input.id}: expected ${metadata.checksum}, got ${actualChecksum}`
+        );
+      }
+    }
+
+    const downloadDuration = Date.now() - downloadStart;
+
+    // Extract archive into the caller-provided target directory.
+    const extractStart = Date.now();
+    const targetPath = input.targetPath;
+
+    if (!existsSync(targetPath)) {
+      mkdirSync(targetPath, { recursive: true });
+    }
+
+    // Check for existing files if not overwriting
+    if (!input.overwrite) {
+      // The archive stores each repository under the base name of its path (createArchive), not
+      // under its package name: before, the guard checked the package name, so an existing working
+      // copy was overwritten with overwrite: false (deep dive DATA-2)
+      for (const repo of metadata.repositories) {
+        const repoPath = join(targetPath, basename(repo.path));
+        if (existsSync(repoPath)) {
+          throw new Error(
+            `Target path already exists: ${repoPath}. Use overwrite: true to replace.`
+          );
+        }
+      }
+    }
+
+    // Extract into a staging folder in the target, then move each top-level folder into place.
+    // With overwrite: true, a restored folder replaces the existing one: before, the archive
+    // was extracted over it, and files that the snapshot does not hold stayed. A failed
+    // extraction leaves the target as it was.
+    const staging = mkdtempSync(join(targetPath, ".snapshot-restore-"));
+    try {
+      await tar.extract({
+        file: archivePath,
+        cwd: staging,
+      });
+      for (const entry of readdirSync(staging)) {
+        const destination = join(targetPath, entry);
+        if (existsSync(destination)) {
+          if (!input.overwrite) {
+            throw new Error(`Target path already exists: ${destination}. Use overwrite: true to replace.`);
+          }
+          rmSync(destination, { recursive: true, force: true });
+        }
+        renameSync(join(staging, entry), destination);
+      }
+    } finally {
+      rmSync(staging, { recursive: true, force: true });
+    }
+
+    const extractDuration = Date.now() - extractStart;
+
+    // Restore stashes if available
+    const restoredPaths: string[] = [];
+    for (const repo of metadata.repositories) {
+      const repoPath = join(targetPath, basename(repo.path));
+      if (existsSync(repoPath)) {
+        restoredPaths.push(repoPath);
+      }
+    }
+
+    return {
+      success: true,
+      metadata,
+      restoredPaths,
+      downloadDuration,
+      extractDuration,
+    };
+  } finally {
+    // Only ever remove the scratch download directory — never the extraction
+    // target. The `workDir !== input.targetPath` guard is belt-and-suspenders:
+    // targetPath is required and distinct from the temp scratch dir.
+    if (existsSync(workDir) && workDir !== input.targetPath) {
+      rmSync(workDir, { recursive: true, force: true });
+    }
+  }
+}

package/src/procedures/snapshot/s3-lookup.ts

@@ -0,0 +1,88 @@
+/**
+ * Shared S3 lookup helpers for snapshot procedures.
+ *
+ * Snapshot objects are stored under keys of the form
+ *   snapshots/<name>/<id>.tar.gz
+ *   snapshots/<name>/<id>.metadata.json
+ * where <id> already embeds <name>, a timestamp and a random suffix, so the
+ * final path segment (basename) of a key uniquely identifies a snapshot file.
+ *
+ * These helpers replace the previous "single s3.list + key.includes(id)"
+ * approach, which (a) missed snapshots once a bucket held more than 1000
+ * objects (S3 truncates and requires continuation), and (b) matched by
+ * substring, so an id that is a substring of a different snapshot's id could
+ * resolve to — and, for delete, remove — the wrong files.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+
+export interface S3ListedObject {
+  key: string;
+  /** The time of the last write (ISO 8601), as s3.list gives it */
+  lastModified?: string;
+}
+
+interface S3ListResult {
+  contents: S3ListedObject[];
+  isTruncated: boolean;
+  nextContinuationToken?: string;
+}
+
+/**
+ * List every object under `prefix`, following S3 pagination via
+ * continuationToken until the listing is no longer truncated.
+ */
+export async function listAllObjects(
+  ctx: ProcedureContext,
+  bucket: string,
+  prefix: string
+): Promise<S3ListedObject[]> {
+  const all: S3ListedObject[] = [];
+  let continuationToken: string | undefined;
+
+  do {
+    const result = await ctx.client.call<
+      { bucket: string; prefix?: string; continuationToken?: string },
+      S3ListResult
+    >(["s3", "list"], {
+      bucket,
+      prefix,
+      ...(continuationToken ? { continuationToken } : {}),
+    });
+
+    all.push(...result.contents);
+    continuationToken = result.isTruncated ? result.nextContinuationToken : undefined;
+  } while (continuationToken);
+
+  return all;
+}
+
+/** Final path segment of an S3 key. */
+function basenameOf(key: string): string {
+  const idx = key.lastIndexOf("/");
+  return idx === -1 ? key : key.slice(idx + 1);
+}
+
+/**
+ * Find the single object whose basename is exactly `${id}${suffix}`.
+ *
+ * Matching is by exact basename equality, never substring, so an id that is a
+ * substring of a different snapshot's id can never resolve to the wrong file.
+ */
+export function findSnapshotKey(
+  objects: S3ListedObject[],
+  id: string,
+  suffix: string
+): string | undefined {
+  const target = `${id}${suffix}`;
+  return objects.find((obj) => basenameOf(obj.key) === target)?.key;
+}
+
+/**
+ * All object keys belonging to snapshot `id` (archive + metadata), matched by
+ * exact basename so delete can never remove a different snapshot's files.
+ */
+export function findSnapshotKeys(objects: S3ListedObject[], id: string): string[] {
+  const targets = new Set([`${id}.tar.gz`, `${id}.metadata.json`]);
+  return objects.filter((obj) => targets.has(basenameOf(obj.key))).map((obj) => obj.key);
+}

package/src/register.ts

@@ -0,0 +1,17 @@
+/**
+ * Importing this file registers the procedures of @procedures/snapshot in the global registry
+ * (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as data
+ * are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+
+import { registerProcedures } from "@procedures/client";
+import { snapshotModule } from "./module.js";
+
+export * from "./module.js";
+
+export function registerSnapshotProcedures(): void {
+  registerProcedures(snapshotModule.procedures);
+}
+
+// Auto-register when this module is loaded
+registerSnapshotProcedures();

package/src/types.ts

@@ -0,0 +1,381 @@
+/**
+ * Type definitions for client-snapshot procedures
+ *
+ * Environment snapshot/restore for testing and recovery.
+ * Supports light/medium/heavy presets for different capture levels.
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// Snapshot Presets
+// =============================================================================
+
+export type SnapshotPreset = "light" | "medium" | "heavy";
+
+export const SnapshotPresetSchema: z.ZodEnum<{ light: "light"; medium: "medium"; heavy: "heavy" }> = z.enum(["light", "medium", "heavy"]);
+
+/**
+ * Preset descriptions:
+ * - light: Git repos only (.git, working tree, branches, stashes) ~500MB
+ * - medium: + node_modules + pnpm lockfiles ~2GB
+ * - heavy: + pnpm store + global installs + configs ~10GB+
+ */
+
+// =============================================================================
+// Repository Info
+// =============================================================================
+
+export interface RepositoryInfo {
+  /** Repository path relative to snapshot root */
+  path: string;
+  /** Package name from package.json */
+  name: string;
+  /** Current branch */
+  branch: string;
+  /** HEAD commit hash */
+  commit: string;
+  /** Whether working tree is dirty */
+  dirty: boolean;
+  /** Number of stashes */
+  stashCount: number;
+  /** Remote URL */
+  remoteUrl?: string | undefined;
+  /** Commits ahead of remote */
+  ahead: number;
+  /** Commits behind remote */
+  behind: number;
+}
+
+// =============================================================================
+// Snapshot Metadata
+// =============================================================================
+
+export interface SnapshotMetadata {
+  /** Unique snapshot ID */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Snapshot preset used */
+  preset: SnapshotPreset;
+  /** Creation timestamp (ISO string) */
+  createdAt: string;
+  /** Environment info */
+  environment: {
+    /** Operating system (win32, darwin, linux) */
+    os: string;
+    /** Node.js version */
+    nodeVersion: string;
+    /** pnpm version */
+    pnpmVersion: string;
+    /** Username who created snapshot */
+    username: string;
+    /** Hostname */
+    hostname: string;
+  };
+  /** List of repositories in snapshot */
+  repositories: RepositoryInfo[];
+  /** Archive checksum (SHA-256) */
+  checksum: string;
+  /** Compressed archive size in bytes */
+  archiveSize: number;
+  /** Optional description */
+  description?: string | undefined;
+}
+
+// =============================================================================
+// snapshot.create Types
+// =============================================================================
+
+export const SnapshotCreateInputSchema: z.ZodObject<{
+  name: z.ZodString;
+  preset: z.ZodDefault<z.ZodEnum<{ light: "light"; medium: "medium"; heavy: "heavy" }>>;
+  bucket: z.ZodString;
+  paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  description: z.ZodOptional<z.ZodString>;
+}> = z.object({
+  /** Snapshot name (used in S3 key and metadata) */
+  name: z.string().describe("Snapshot name (used in S3 key and metadata)"),
+  /** Capture preset (default: medium) */
+  preset: SnapshotPresetSchema.default("medium").describe("Capture preset (default: medium)"),
+  /** S3 bucket for storage */
+  bucket: z.string().describe("S3 bucket for storage"),
+  /** Specific paths to include (default: all repos in ecosystem) */
+  paths: z.array(z.string()).optional().describe("Specific paths to include (default: all repos in ecosystem)"),
+  /** Optional description */
+  description: z.string().optional().describe("Optional description"),
+});
+
+export type SnapshotCreateInput = z.infer<typeof SnapshotCreateInputSchema>;
+
+export interface SnapshotCreateOutput {
+  /** Snapshot ID */
+  id: string;
+  /** S3 location */
+  location: string;
+  /** Metadata */
+  metadata: SnapshotMetadata;
+  /** Upload duration in ms */
+  uploadDuration: number;
+}
+
+// =============================================================================
+// snapshot.restore Types
+// =============================================================================
+
+export const SnapshotRestoreInputSchema: z.ZodObject<{
+  id: z.ZodString;
+  bucket: z.ZodString;
+  targetPath: z.ZodString;
+  overwrite: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}> = z.object({
+  /** Snapshot ID to restore */
+  id: z.string().describe("Snapshot ID to restore"),
+  /** S3 bucket containing snapshot */
+  bucket: z.string().describe("S3 bucket containing snapshot"),
+  /**
+   * Destination directory the snapshot is extracted into. Required: restore
+   * must never fall back to a temporary scratch directory, because that
+   * scratch directory is deleted on cleanup and would wipe the restored files.
+   */
+  targetPath: z.string().describe("Destination directory the snapshot is extracted into. Required: restore must never fall back to a temporary scratch directory, because that scratch directory is deleted on cleanup and would wipe the restored files."),
+  /** Overwrite existing files (default: false) */
+  overwrite: z.boolean().optional().default(false).describe("Overwrite existing files (default: false)"),
+});
+
+export type SnapshotRestoreInput = z.infer<typeof SnapshotRestoreInputSchema>;
+
+export interface SnapshotRestoreOutput {
+  /** Whether restore succeeded */
+  success: boolean;
+  /** Restored snapshot metadata */
+  metadata: SnapshotMetadata;
+  /** Paths that were restored */
+  restoredPaths: string[];
+  /** Download duration in ms */
+  downloadDuration: number;
+  /** Extract duration in ms */
+  extractDuration: number;
+}
+
+// =============================================================================
+// snapshot.list Types
+// =============================================================================
+
+export const SnapshotListInputSchema: z.ZodObject<{
+  bucket: z.ZodString;
+  prefix: z.ZodOptional<z.ZodString>;
+  maxResults: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}> = z.object({
+  /** S3 bucket to list */
+  bucket: z.string().describe("S3 bucket to list"),
+  /** Filter by name prefix */
+  prefix: z.string().optional().describe("Filter by name prefix"),
+  /** Maximum results (default: 100) */
+  maxResults: z.number().optional().default(100).describe("Maximum results (default: 100)"),
+});
+
+export type SnapshotListInput = z.infer<typeof SnapshotListInputSchema>;
+
+export interface SnapshotListEntry {
+  /** Snapshot ID */
+  id: string;
+  /** Snapshot name */
+  name: string;
+  /** Preset used */
+  preset: SnapshotPreset;
+  /** Creation date */
+  createdAt: string;
+  /** Archive size in bytes */
+  size: number;
+  /** OS it was created on */
+  os: string;
+}
+
+export interface SnapshotListOutput {
+  /** List of snapshots */
+  snapshots: SnapshotListEntry[];
+  /** Total count */
+  count: number;
+}
+
+// =============================================================================
+// snapshot.diff Types
+// =============================================================================
+
+export const SnapshotDiffInputSchema: z.ZodObject<{
+  id: z.ZodString;
+  bucket: z.ZodString;
+  paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}> = z.object({
+  /** Snapshot ID to compare against */
+  id: z.string().describe("Snapshot ID to compare against"),
+  /** S3 bucket containing snapshot */
+  bucket: z.string().describe("S3 bucket containing snapshot"),
+  /** Specific paths to compare (default: all) */
+  paths: z.array(z.string()).optional().describe("Specific paths to compare (default: all)"),
+});
+
+export type SnapshotDiffInput = z.infer<typeof SnapshotDiffInputSchema>;
+
+export interface SnapshotDiffRepository {
+  /** Repository path */
+  path: string;
+  /** Branch difference (current vs snapshot) */
+  branchDiff?: { current: string; snapshot: string } | undefined;
+  /** Commit difference */
+  commitDiff?: { current: string; snapshot: string } | undefined;
+  /** Files changed since snapshot */
+  filesChanged: number;
+  /** New stashes since snapshot */
+  newStashes: number;
+}
+
+export interface SnapshotDiffOutput {
+  /** Snapshot metadata for comparison */
+  snapshotMetadata: SnapshotMetadata;
+  /** Per-repository differences */
+  repositories: SnapshotDiffRepository[];
+  /** Overall summary */
+  summary: {
+    /** Total repos with differences */
+    reposChanged: number;
+    /** Total files changed */
+    totalFilesChanged: number;
+    /** Whether current state matches snapshot */
+    isMatch: boolean;
+  };
+}
+
+// =============================================================================
+// snapshot.delete Types
+// =============================================================================
+
+export const SnapshotDeleteInputSchema: z.ZodObject<{
+  id: z.ZodString;
+  bucket: z.ZodString;
+}> = z.object({
+  /** Snapshot ID to delete */
+  id: z.string().describe("Snapshot ID to delete"),
+  /** S3 bucket containing snapshot */
+  bucket: z.string().describe("S3 bucket containing snapshot"),
+});
+
+export type SnapshotDeleteInput = z.infer<typeof SnapshotDeleteInputSchema>;
+
+export interface SnapshotDeleteOutput {
+  /** Whether deletion succeeded */
+  deleted: boolean;
+  /** Deleted snapshot ID */
+  id: string;
+}
+
+// =============================================================================
+// Output schemas (roadmap 2.1)
+// =============================================================================
+
+// Loose objects: a field that a schema does not name stays in the result (a strict schema would
+// remove it when the output is validated).
+//
+// The metadata of a snapshot comes back from S3, where an older version of this package can have
+// written it with fewer fields. A schema that required each field of today's type would turn a
+// restore that worked into a validation error, so the metadata parts require only the id. The
+// casts say that these schemas are more lenient than the types on purpose.
+
+const repositoryInfo = z.looseObject({
+  path: z.string().optional().describe("The repository folder, relative to the snapshot root"),
+  name: z.string().optional().describe("The package name"),
+  branch: z.string().optional().describe("The branch at the time of the snapshot"),
+  commit: z.string().optional().describe("The HEAD commit at the time of the snapshot"),
+  dirty: z.boolean().optional().describe("True when the working tree had changes"),
+  stashCount: z.number().optional().describe("The number of stashes"),
+  remoteUrl: z.string().optional().describe("The remote URL"),
+  ahead: z.number().optional().describe("The commits that the remote did not have"),
+  behind: z.number().optional().describe("The commits of the remote that the branch did not have"),
+});
+
+const snapshotMetadata = z
+  .looseObject({
+    id: z.string().describe("The snapshot id"),
+    name: z.string().optional().describe("The name of the snapshot"),
+    preset: z.string().optional().describe("The preset: light, medium or heavy"),
+    createdAt: z.string().optional().describe("The time of the snapshot (ISO 8601)"),
+    environment: z
+      .looseObject({
+        os: z.string().optional().describe("The operating system"),
+        nodeVersion: z.string().optional().describe("The Node.js version"),
+        pnpmVersion: z.string().optional().describe("The pnpm version"),
+        username: z.string().optional().describe("The user who made the snapshot"),
+        hostname: z.string().optional().describe("The host name"),
+      })
+      .optional()
+      .describe("The environment of the snapshot"),
+    repositories: z.array(repositoryInfo).optional().describe("The repositories in the snapshot"),
+    checksum: z.string().optional().describe("The SHA-256 checksum of the archive"),
+    archiveSize: z.number().optional().describe("The size of the compressed archive, in bytes"),
+    description: z.string().optional().describe("The description"),
+  })
+  .describe("The metadata of the snapshot");
+
+export const SnapshotCreateOutputSchema: z.ZodType<SnapshotCreateOutput> = z.looseObject({
+  id: z.string().describe("The snapshot id"),
+  location: z.string().describe("The S3 location of the archive"),
+  metadata: snapshotMetadata,
+  uploadDuration: z.number().describe("The time of the upload, in milliseconds"),
+}) as unknown as z.ZodType<SnapshotCreateOutput>;
+
+export const SnapshotRestoreOutputSchema: z.ZodType<SnapshotRestoreOutput> = z.looseObject({
+  success: z.boolean().describe("True when the restore succeeded"),
+  metadata: snapshotMetadata,
+  restoredPaths: z.array(z.string()).describe("The folders that the restore wrote"),
+  downloadDuration: z.number().describe("The time of the download, in milliseconds"),
+  extractDuration: z.number().describe("The time of the extraction, in milliseconds"),
+}) as unknown as z.ZodType<SnapshotRestoreOutput>;
+
+export const SnapshotListOutputSchema: z.ZodType<SnapshotListOutput> = z.looseObject({
+  snapshots: z
+    .array(
+      z.looseObject({
+        id: z.string().describe("The snapshot id"),
+        name: z.string().optional().describe("The name of the snapshot"),
+        preset: z.string().optional().describe("The preset"),
+        createdAt: z.string().optional().describe("The time of the snapshot (ISO 8601)"),
+        size: z.number().optional().describe("The size of the archive, in bytes"),
+        os: z.string().optional().describe("The operating system of the snapshot"),
+      })
+    )
+    .describe("The snapshots, newest first"),
+  count: z.number().describe("The number of snapshots"),
+}) as unknown as z.ZodType<SnapshotListOutput>;
+
+const pair = z.looseObject({
+  current: z.string().describe("The value now"),
+  snapshot: z.string().describe("The value in the snapshot"),
+});
+
+export const SnapshotDiffOutputSchema: z.ZodType<SnapshotDiffOutput> = z.looseObject({
+  snapshotMetadata,
+  repositories: z
+    .array(
+      z.looseObject({
+        path: z.string().describe("The repository folder"),
+        branchDiff: pair.optional().describe("The branch now and in the snapshot, when they differ"),
+        commitDiff: pair.optional().describe("The commit now and in the snapshot, when they differ"),
+        filesChanged: z.number().describe("The files changed since the snapshot"),
+        newStashes: z.number().describe("The stashes made since the snapshot"),
+      })
+    )
+    .describe("The differences of each repository"),
+  summary: z
+    .looseObject({
+      reposChanged: z.number().describe("The repositories with differences"),
+      totalFilesChanged: z.number().describe("The files changed in all repositories"),
+      isMatch: z.boolean().describe("True when the current state matches the snapshot"),
+    })
+    .describe("The summary"),
+}) as unknown as z.ZodType<SnapshotDiffOutput>;
+
+export const SnapshotDeleteOutputSchema: z.ZodType<SnapshotDeleteOutput> = z.looseObject({
+  deleted: z.boolean().describe("True when the snapshot was deleted"),
+  id: z.string().describe("The snapshot id"),
+});