TypeScript workspace API

Prepare directories, capture checkpoints, transfer archives and serve a workspace through S3. Import from @chester-hill-solutions/stow-s3/workspace.

Defaults and limits

Behavior

• Keep registryDir and team consistent across operations.
• Pause writers before checkpoint capture.
• resume opens the original workspace; adopt creates a new one.
• Delta application verifies its named base.
• handoff can write a document to a file; the helper reads that file as its result.
• serveWorkspace owns the process until close, without deleting the workspace.

Errors

• A nonzero native exit rejects the promise with command diagnostics.
• Invalid JSON or a non-object result is rejected.
• Archives can fail path, digest, size or file-count checks.
• Unknown save outcomes require resolution before retry.
• Destroy refuses live, adopted or protected directories.

Example

import { prepareWorkspace, checkpointWorkspace } from "@chester-hill-solutions/stow-s3/workspace";

const task = await prepareWorkspace("task.json");
// Run your task in task.working_directory, then pause writers.
const saved = await checkpointWorkspace({ id: String(task.workspace_id) });

Symbols

adoptWorkspaceHandoff · applyWorkspaceDelta · checkpointWorkspace · collectWorkspaces · createWorkspaceDelta · decodeWorkspaceJSON · destroyWorkspace · diffWorkspaces · exportWorkspaceCheckpoint · handoffWorkspace · importWorkspaceCheckpoint · listWorkspaces · prepareWorkspace · pruneWorkspaces · restoreWorkspaceCheckpoint · resumeWorkspace · ResumeWorkspaceOptions · runWorkspaceCommand · ServedWorkspace · serveWorkspace · ServeWorkspaceOptions · WorkspaceAdoptOptions · WorkspaceApplyOptions · WorkspaceArchiveOptions · WorkspaceCheckpointOptions · WorkspaceDeltaOptions · WorkspaceJSON

adoptWorkspaceHandoff

Verify a portable handoff and restore it under a new workspace identity.

adoptWorkspaceHandoff(options: WorkspaceAdoptOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

applyWorkspaceDelta

Verify the named base and optional document digest before publishing a new checkpoint.

applyWorkspaceDelta(options: WorkspaceApplyOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

checkpointWorkspace

Capture an immutable checkpoint of paused writers.

checkpointWorkspace(options: WorkspaceCheckpointOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

collectWorkspaces

Collect expired workspaces that are unused and eligible for deletion.

collectWorkspaces(registryDir?: string | undefined): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

createWorkspaceDelta

Write a verified change document between two checkpoints from the same workspace.

createWorkspaceDelta(options: WorkspaceDeltaOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

decodeWorkspaceJSON

Run the native workspace command contract without invoking a shell.

decodeWorkspaceJSON(raw: string): Readonly<Record<string, unknown>>

Returns: Readonly<Record<string, unknown>>.

destroyWorkspace

Explicitly destroy a registered, eligible workspace.

destroyWorkspace(id: string, registryDir?: string | undefined): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

diffWorkspaces

Compare two checkpoints and return changed paths.

diffWorkspaces(from: string, to: string, registryDir?: string | undefined, team?: string | undefined): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

exportWorkspaceCheckpoint

Write a portable checkpoint archive to the selected file.

exportWorkspaceCheckpoint(checkpointId: string, output: string, options?: WorkspaceArchiveOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

handoffWorkspace

Create a handoff reference, optionally with a portable archive.

handoffWorkspace(id: string, options?: { readonly registryDir?: string | undefined; readonly team?: string | undefined; readonly checkpointId?: string | undefined; readonly archive?: string | undefined; readonly output?: string | undefined; }): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

importWorkspaceCheckpoint

Validate and import a portable checkpoint archive.

importWorkspaceCheckpoint(archive: string, options?: WorkspaceArchiveOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

listWorkspaces

List registered workspaces, including records whose directories are missing.

listWorkspaces(options?: { readonly registryDir?: string | undefined; readonly team?: string | undefined; }): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

prepareWorkspace

Create a workspace from a task manifest and return its launch descriptor.

prepareWorkspace(manifestPath: string): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

pruneWorkspaces

Remove registry records for missing directories; preserve existing directories.

pruneWorkspaces(options?: { readonly registryDir?: string | undefined; readonly team?: string | undefined; readonly includeAdopted?: boolean | undefined; }): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

restoreWorkspaceCheckpoint

Restore a checkpoint into a new workspace directory.

restoreWorkspaceCheckpoint(checkpointId: string, root: string, registryDir?: string | undefined): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

resumeWorkspace

Open the workspace selected by ID or a same-machine handoff.

resumeWorkspace(options: ResumeWorkspaceOptions): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

ResumeWorkspaceOptions

interface ResumeWorkspaceOptions {
  readonly id?: string | undefined;
  readonly handoffPath?: string | undefined;
  readonly registryDir?: string | undefined;
}

runWorkspaceCommand

Run the native workspace command without a shell and decode its JSON object.

runWorkspaceCommand(args: readonly string[]): Promise<Readonly<Record<string, unknown>>>

Returns: Promise<Readonly<Record<string, unknown>>>.

ServedWorkspace

interface ServedWorkspace {
  readonly ready: Readonly<Record<string, unknown>>;
  close(): Promise<void>;
}

ServedWorkspace.close

Release this handle. Do not submit new operations after closing it.

close(): Promise<void>

Returns: Promise<void>.

serveWorkspace

Own a workspace S3 server until the returned handle closes; preserve workspace data.

serveWorkspace(options: ServeWorkspaceOptions): Promise<ServedWorkspace>

Returns: Promise<ServedWorkspace>.

ServeWorkspaceOptions

interface ServeWorkspaceOptions {
  readonly maxRequestBytes?: number | undefined;
  maxConcurrentRequests?: number | undefined;
  readonly id: string;
  readonly registryDir?: string | undefined;
  readonly team?: string | undefined;
  readonly maxBytes?: number | undefined;
  readonly maxObjects?: number | undefined;
  readonly timeoutMs?: number | undefined;
  readonly signal?: AbortSignal | undefined;
}

WorkspaceAdoptOptions

interface WorkspaceAdoptOptions  extends WorkspaceArchiveOptions {
  readonly handoffPath: string;
  readonly root: string;
}

WorkspaceApplyOptions

The base a delta applies to, and the document that says what changes.

interface WorkspaceApplyOptions  extends WorkspaceArchiveOptions {
  readonly delta: string;
  readonly base: string;
  readonly expectSHA256?: string | undefined;
}

WorkspaceArchiveOptions

interface WorkspaceArchiveOptions {
  readonly registryDir?: string | undefined;
  readonly team?: string | undefined;
  readonly maxBytes?: number | undefined;
  readonly maxFiles?: number | undefined;
  readonly includeSensitive?: boolean | undefined;
}

WorkspaceCheckpointOptions

interface WorkspaceCheckpointOptions {
  readonly id: string;
  readonly registryDir?: string | undefined;
  readonly team?: string | undefined;
  readonly parent?: string | undefined;
  readonly maxBytes?: number | undefined;
  readonly maxFiles?: number | undefined;
  readonly includeSensitive?: boolean | undefined;
}

WorkspaceDeltaOptions

interface WorkspaceDeltaOptions  extends WorkspaceArchiveOptions {
  readonly from: string;
  readonly to: string;
  readonly output: string;
}

WorkspaceJSON

type WorkspaceJSON = Readonly<Record<string, unknown>>;