@procedures/snapshot 0.0.0-stage → 0.2.0

package/dist/types.js

@@ -0,0 +1,168 @@
+/**
+ * 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";
+export const SnapshotPresetSchema = z.enum(["light", "medium", "heavy"]);
+// =============================================================================
+// snapshot.create Types
+// =============================================================================
+export const SnapshotCreateInputSchema = 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"),
+});
+// =============================================================================
+// snapshot.restore Types
+// =============================================================================
+export const SnapshotRestoreInputSchema = 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)"),
+});
+// =============================================================================
+// snapshot.list Types
+// =============================================================================
+export const SnapshotListInputSchema = 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)"),
+});
+// =============================================================================
+// snapshot.diff Types
+// =============================================================================
+export const SnapshotDiffInputSchema = 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)"),
+});
+// =============================================================================
+// snapshot.delete Types
+// =============================================================================
+export const SnapshotDeleteInputSchema = 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"),
+});
+// =============================================================================
+// 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.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"),
+});
+export const SnapshotRestoreOutputSchema = 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"),
+});
+export const SnapshotListOutputSchema = 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"),
+});
+const pair = z.looseObject({
+    current: z.string().describe("The value now"),
+    snapshot: z.string().describe("The value in the snapshot"),
+});
+export const SnapshotDiffOutputSchema = 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"),
+});
+export const SnapshotDeleteOutputSchema = z.looseObject({
+    deleted: z.boolean().describe("True when the snapshot was deleted"),
+    id: z.string().describe("The snapshot id"),
+});
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,90 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/snapshot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Snapshot and restore development environments with S3: git state, packages and files, with streamed archives and a safe restore.",
+  "keywords": [
+    "snapshot",
+    "backup",
+    "restore",
+    "s3",
+    "environment",
+    "procedures"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-snapshot"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./module": {
+      "types": "./dist/module.d.ts",
+      "import": "./dist/module.js"
+    },
+    "./register": {
+      "types": "./dist/register.d.ts",
+      "import": "./dist/register.js"
+    },
+    "./register.js": {
+      "import": "./dist/register.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": [
+    "./dist/register.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0",
+    "@procedures/fs": "0.2.0",
+    "@procedures/git": "0.2.0",
+    "@procedures/pnpm": "0.2.0",
+    "@procedures/s3": "0.2.0",
+    "@procedures/shell": "0.2.0",
+    "tar": "^7.5.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3",
+    "@types/tar": "^6.1.11"
+  },
+  "client": {
+    "procedures": "./dist/register.js"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
 }

package/src/index.ts

@@ -0,0 +1,51 @@
+/**
+ * client-snapshot - Environment snapshot/restore procedures
+ *
+ * Provides procedures for capturing and restoring environment snapshots
+ * including git repositories, node_modules, and pnpm stores.
+ *
+ * Presets:
+ * - light: Git repos only (~500MB)
+ * - medium: + node_modules (~2GB)
+ * - heavy: + pnpm store (~10GB+)
+ */
+
+export * from "./module.js";
+
+// Re-export types
+export type {
+  SnapshotPreset,
+  RepositoryInfo,
+  SnapshotMetadata,
+  SnapshotCreateInput,
+  SnapshotCreateOutput,
+  SnapshotRestoreInput,
+  SnapshotRestoreOutput,
+  SnapshotListInput,
+  SnapshotListOutput,
+  SnapshotListEntry,
+  SnapshotDiffInput,
+  SnapshotDiffOutput,
+  SnapshotDiffRepository,
+  SnapshotDeleteInput,
+  SnapshotDeleteOutput,
+} from "./types.js";
+
+// Re-export schemas
+export {
+  SnapshotPresetSchema,
+  SnapshotCreateInputSchema,
+  SnapshotRestoreInputSchema,
+  SnapshotListInputSchema,
+  SnapshotDiffInputSchema,
+  SnapshotDeleteInputSchema,
+} from "./types.js";
+
+// Re-export procedure implementations
+export {
+  snapshotCreate,
+  snapshotList,
+  snapshotRestore,
+  snapshotDiff,
+  snapshotDelete,
+} from "./procedures/snapshot/index.js";

package/src/module.ts

@@ -0,0 +1,155 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for snapshot operations
+ *
+ * Provides snapshot.create, snapshot.list, snapshot.restore, snapshot.diff, snapshot.delete procedures.
+ */
+
+import { createProcedure, zodAdapter, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import type { ProcedureContext } from "@procedures/client";
+import {
+  snapshotCreate,
+  snapshotList,
+  snapshotRestore,
+  snapshotDiff,
+  snapshotDelete,
+} from "./procedures/snapshot/index.js";
+import {
+  SnapshotCreateInputSchema,
+  SnapshotListInputSchema,
+  SnapshotRestoreInputSchema,
+  SnapshotDiffInputSchema,
+  SnapshotDeleteInputSchema,
+  type SnapshotCreateInput,
+  type SnapshotCreateOutput,
+  type SnapshotListInput,
+  type SnapshotListOutput,
+  type SnapshotRestoreInput,
+  type SnapshotRestoreOutput,
+  type SnapshotDiffInput,
+  type SnapshotDiffOutput,
+  type SnapshotDeleteInput,
+  type SnapshotDeleteOutput,
+  SnapshotCreateOutputSchema,
+  SnapshotRestoreOutputSchema,
+  SnapshotListOutputSchema,
+  SnapshotDiffOutputSchema,
+  SnapshotDeleteOutputSchema,
+} from "./types.js";
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+const snapshotCreateProcedure = createProcedure()
+  .path(["snapshot", "create"])
+  .input(zodAdapter<SnapshotCreateInput>(SnapshotCreateInputSchema))
+  .output(zodAdapter<SnapshotCreateOutput>(SnapshotCreateOutputSchema))
+  .meta({
+    description: "Create environment snapshot and upload to S3",
+    // It writes the archive to a new folder of the temporary directory and to new S3 keys with a
+    // unique id, so it replaces no data
+    effects: { reads: ["fs", "s3", "network"], writes: ["fs", "s3", "network"], destructive: false },
+    args: ["name"],
+    shorts: { bucket: "b", preset: "p", description: "d" },
+    output: "json",
+  })
+  .handler(async (input: SnapshotCreateInput, ctx: ProcedureContext): Promise<SnapshotCreateOutput> => {
+    return snapshotCreate(input, ctx);
+  })
+  .build();
+
+const snapshotListProcedure = createProcedure()
+  .path(["snapshot", "list"])
+  .input(zodAdapter<SnapshotListInput>(SnapshotListInputSchema))
+  .output(zodAdapter<SnapshotListOutput>(SnapshotListOutputSchema))
+  .meta({
+    description: "List available snapshots in S3 bucket",
+    // It downloads the metadata files into memory, not to a file
+    effects: { reads: ["s3", "network"], writes: [] },
+    args: [],
+    shorts: { bucket: "b", prefix: "p", maxResults: "n" },
+    output: "json",
+  })
+  .handler(async (input: SnapshotListInput, ctx: ProcedureContext): Promise<SnapshotListOutput> => {
+    return snapshotList(input, ctx);
+  })
+  .build();
+
+const snapshotRestoreProcedure = createProcedure()
+  .path(["snapshot", "restore"])
+  .input(zodAdapter<SnapshotRestoreInput>(SnapshotRestoreInputSchema))
+  .output(zodAdapter<SnapshotRestoreOutput>(SnapshotRestoreOutputSchema))
+  .meta({
+    description: "Restore environment from S3 snapshot",
+    // With overwrite: true, a restored folder replaces the existing folder
+    effects: { reads: ["fs", "s3", "network"], writes: ["fs"] },
+    args: ["id"],
+    shorts: { bucket: "b", targetPath: "t", overwrite: "f" },
+    output: "json",
+  })
+  .handler(async (input: SnapshotRestoreInput, ctx: ProcedureContext): Promise<SnapshotRestoreOutput> => {
+    return snapshotRestore(input, ctx);
+  })
+  .build();
+
+const snapshotDiffProcedure = createProcedure()
+  .path(["snapshot", "diff"])
+  .input(zodAdapter<SnapshotDiffInput>(SnapshotDiffInputSchema))
+  .output(zodAdapter<SnapshotDiffOutput>(SnapshotDiffOutputSchema))
+  .meta({
+    description: "Compare current state against a snapshot",
+    // It reads the repositories with git queries that change nothing
+    effects: { reads: ["fs", "s3", "network"], writes: [] },
+    args: ["id"],
+    shorts: { bucket: "b" },
+    output: "json",
+  })
+  .handler(async (input: SnapshotDiffInput, ctx: ProcedureContext): Promise<SnapshotDiffOutput> => {
+    return snapshotDiff(input, ctx);
+  })
+  .build();
+
+const snapshotDeleteProcedure = createProcedure()
+  .path(["snapshot", "delete"])
+  .input(zodAdapter<SnapshotDeleteInput>(SnapshotDeleteInputSchema))
+  .output(zodAdapter<SnapshotDeleteOutput>(SnapshotDeleteOutputSchema))
+  .meta({
+    description: "Delete a snapshot from S3",
+    effects: { reads: ["s3", "network"], writes: ["s3", "network"] },
+    args: ["id"],
+    shorts: { bucket: "b" },
+    output: "json",
+  })
+  .handler(async (input: SnapshotDeleteInput, ctx: ProcedureContext): Promise<SnapshotDeleteOutput> => {
+    return snapshotDelete(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const snapshotModule: ProcedureModule = defineModule("@procedures/snapshot", [
+    snapshotCreateProcedure,
+    snapshotListProcedure,
+    snapshotRestoreProcedure,
+    snapshotDiffProcedure,
+    snapshotDeleteProcedure,
+  ]);
+
+export default snapshotModule;
+
+/**
+ * This function registers the procedures of @procedures/snapshot, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerSnapshotProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [snapshotModule]);
+}

package/src/procedures/snapshot/archive-io.ts

@@ -0,0 +1,31 @@
+/**
+ * File access for snapshot archives without the whole archive in memory.
+ *
+ * Before, create and restore read each archive into memory (for the checksum and the upload).
+ * An archive over 2 GiB failed, and the peak was about 2.3 times the archive (deep dive DATA-19).
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+
+/** The SHA-256 of a file, read as a stream. */
+export async function sha256File(path: string): Promise<string> {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk as Buffer);
+  }
+  return hash.digest("hex");
+}
+
+/** The bytes of a file from `offset`, at most `size`. */
+export async function readPart(file: FileHandle, offset: number, size: number): Promise<Buffer> {
+  const buffer = Buffer.alloc(size);
+  let filled = 0;
+  while (filled < size) {
+    const { bytesRead } = await file.read(buffer, filled, size - filled, offset + filled);
+    if (bytesRead === 0) break;
+    filled += bytesRead;
+  }
+  return buffer.subarray(0, filled);
+}

package/src/procedures/snapshot/commands.ts

@@ -0,0 +1,34 @@
+/**
+ * The programs that the snapshot procedures run: git and pnpm, through `runCommand`.
+ *
+ * `runCommand` is async, kills the process tree when the signal aborts, and runs no shell.
+ * Before, the procedures used `execSync`: it blocked the event loop of the host for each call,
+ * ignored the signal, and passed the command line to a shell.
+ */
+
+import { runCommand } from "@procedures/shell/command";
+import { resolvePnpm } from "@procedures/pnpm";
+
+/** The longest time of one git or pnpm query, in milliseconds. */
+const QUERY_TIMEOUT_MS = 30_000;
+
+/**
+ * This function runs `git <args>` in `cwd` and gives its trimmed output. It gives `undefined`
+ * when git fails, when it cannot start, or when the signal aborts.
+ */
+export async function gitText(args: readonly string[], cwd: string, signal?: AbortSignal): Promise<string | undefined> {
+  const result = await runCommand("git", { args, cwd, signal, timeout: QUERY_TIMEOUT_MS });
+  return result.success ? result.stdout.trim() : undefined;
+}
+
+/** This function gives the version of pnpm, or "unknown" when pnpm cannot run. */
+export async function pnpmVersion(signal?: AbortSignal): Promise<string> {
+  let pnpm: { command: string; prefix: string[] };
+  try {
+    pnpm = resolvePnpm();
+  } catch {
+    return "unknown";
+  }
+  const result = await runCommand(pnpm.command, { args: [...pnpm.prefix, "--version"], signal, timeout: QUERY_TIMEOUT_MS });
+  return result.success ? result.stdout.trim() : "unknown";
+}