@savestate/cli 0.1.0

package/dist/snapshot.js

@@ -0,0 +1,95 @@
+/**
+ * SaveState Snapshot Creation
+ *
+ * Collects state from an adapter, builds the SAF structure,
+ * encrypts it, and stores it in the configured backend.
+ *
+ * Flow:
+ * 1. Adapter extracts current state → Snapshot object
+ * 2. packSnapshot() → file map
+ * 3. packToArchive() → tar.gz buffer
+ * 4. Compute checksum, update manifest with size
+ * 5. Re-pack with updated manifest
+ * 6. encrypt() → encrypted buffer
+ * 7. storage.put() with snapshot filename
+ * 8. Update local index
+ */
+import { generateSnapshotId, SAF_VERSION, packSnapshot, packToArchive, computeChecksum, snapshotFilename, } from './format.js';
+import { encrypt } from './encryption.js';
+import { addToIndex } from './index-file.js';
+/**
+ * Create a new snapshot by extracting state from an adapter.
+ *
+ * @param adapter - Platform adapter to extract state from
+ * @param storage - Storage backend to write to
+ * @param passphrase - Encryption passphrase
+ * @param options - Snapshot options (label, tags, etc.)
+ * @returns Details about the created snapshot
+ */
+export async function createSnapshot(adapter, storage, passphrase, options) {
+    // Step 1: Extract state from the platform
+    const snapshot = await adapter.extract();
+    // Step 2: Enrich manifest
+    const snapshotId = generateSnapshotId();
+    const now = new Date().toISOString();
+    snapshot.manifest = {
+        ...snapshot.manifest,
+        id: snapshotId,
+        version: SAF_VERSION,
+        timestamp: now,
+        adapter: adapter.id,
+        platform: adapter.platform,
+        label: options?.label ?? snapshot.manifest.label,
+        tags: options?.tags ?? snapshot.manifest.tags,
+        parent: options?.parentId,
+    };
+    // Step 3: Update snapshot chain
+    snapshot.chain = {
+        current: snapshotId,
+        parent: options?.parentId,
+        ancestors: options?.parentId
+            ? [...(snapshot.chain?.ancestors ?? []), options.parentId]
+            : [],
+    };
+    // Step 4: First pass — pack to get file map and compute checksum
+    const fileMap = packSnapshot(snapshot);
+    const firstArchive = packToArchive(fileMap);
+    const checksum = computeChecksum(firstArchive);
+    // Step 5: Update manifest with checksum and size, then re-pack
+    snapshot.manifest.checksum = checksum;
+    snapshot.manifest.size = firstArchive.length;
+    const finalFileMap = packSnapshot(snapshot);
+    const finalArchive = packToArchive(finalFileMap);
+    // Step 6: Encrypt the archive
+    const encrypted = await encrypt(finalArchive, passphrase);
+    // Step 7: Store the encrypted archive
+    const filename = snapshotFilename(snapshotId);
+    await storage.put(filename, encrypted);
+    // Step 8: Update local index
+    await addToIndex({
+        id: snapshotId,
+        timestamp: now,
+        platform: adapter.platform,
+        adapter: adapter.id,
+        label: options?.label,
+        tags: options?.tags,
+        filename,
+        size: encrypted.length,
+    });
+    return {
+        snapshot,
+        filename,
+        archiveSize: finalArchive.length,
+        encryptedSize: encrypted.length,
+        fileCount: finalFileMap.size,
+    };
+}
+/**
+ * Get the latest snapshot ID from the index.
+ */
+export async function getLatestSnapshotId() {
+    const { getLatestEntry } = await import('./index-file.js');
+    const entry = await getLatestEntry();
+    return entry?.id ?? null;
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/snapshot.js.map

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

package/dist/storage/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Storage module re-exports
+ */
+export { LocalStorageBackend } from './local.js';
+export { resolveStorage } from './resolve.js';
+export type { StorageBackend } from './interface.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/storage/index.js

@@ -0,0 +1,6 @@
+/**
+ * Storage module re-exports
+ */
+export { LocalStorageBackend } from './local.js';
+export { resolveStorage } from './resolve.js';
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/storage/interface.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Storage Backend Interface
+ *
+ * All storage backends receive only encrypted data.
+ * Zero-knowledge by design — the backend never sees plaintext.
+ */
+export type { StorageBackend } from '../types.js';
+//# sourceMappingURL=interface.d.ts.map

package/dist/storage/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/storage/interface.js

@@ -0,0 +1,8 @@
+/**
+ * Storage Backend Interface
+ *
+ * All storage backends receive only encrypted data.
+ * Zero-knowledge by design — the backend never sees plaintext.
+ */
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/storage/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/storage/interface.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/storage/local.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Local Filesystem Storage Backend
+ *
+ * Default backend. Stores encrypted archives at ~/.savestate/snapshots/
+ * or a user-configured directory.
+ */
+import type { StorageBackend } from '../types.js';
+export declare class LocalStorageBackend implements StorageBackend {
+    readonly id = "local";
+    private readonly baseDir;
+    constructor(options?: {
+        path?: string;
+    });
+    private resolvePath;
+    private ensureDir;
+    put(key: string, data: Buffer): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    list(prefix?: string): Promise<string[]>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/storage/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/storage/local.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAIlD,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,EAAE,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAIvC,OAAO,CAAC,WAAW;YAML,SAAS;IAMjB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAKjC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAUxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAS5C"}

package/dist/storage/local.js

@@ -0,0 +1,63 @@
+/**
+ * Local Filesystem Storage Backend
+ *
+ * Default backend. Stores encrypted archives at ~/.savestate/snapshots/
+ * or a user-configured directory.
+ */
+import { readFile, writeFile, readdir, unlink, mkdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+const DEFAULT_BASE_DIR = join(homedir(), '.savestate', 'snapshots');
+export class LocalStorageBackend {
+    id = 'local';
+    baseDir;
+    constructor(options) {
+        this.baseDir = options?.path ?? DEFAULT_BASE_DIR;
+    }
+    resolvePath(key) {
+        // Prevent path traversal
+        const sanitized = key.replace(/\.\./g, '').replace(/^\//, '');
+        return join(this.baseDir, sanitized);
+    }
+    async ensureDir() {
+        if (!existsSync(this.baseDir)) {
+            await mkdir(this.baseDir, { recursive: true });
+        }
+    }
+    async put(key, data) {
+        await this.ensureDir();
+        const filePath = this.resolvePath(key);
+        const dir = filePath.substring(0, filePath.lastIndexOf('/'));
+        await mkdir(dir, { recursive: true });
+        await writeFile(filePath, data);
+    }
+    async get(key) {
+        const filePath = this.resolvePath(key);
+        return readFile(filePath);
+    }
+    async list(prefix) {
+        await this.ensureDir();
+        const entries = await readdir(this.baseDir, { recursive: true });
+        const keys = entries.map((e) => String(e));
+        if (prefix) {
+            return keys.filter((k) => k.startsWith(prefix));
+        }
+        return keys;
+    }
+    async delete(key) {
+        const filePath = this.resolvePath(key);
+        await unlink(filePath);
+    }
+    async exists(key) {
+        try {
+            const filePath = this.resolvePath(key);
+            await stat(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=local.js.map

package/dist/storage/local.js.map

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

package/dist/storage/resolve.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Storage Backend Resolver
+ *
+ * Creates a storage backend instance from config.
+ */
+import type { SaveStateConfig, StorageBackend } from '../types.js';
+/**
+ * Create a storage backend from the config's storage section.
+ */
+export declare function resolveStorage(config: SaveStateConfig): StorageBackend;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/storage/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/storage/resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGnE;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,cAAc,CAatE"}

package/dist/storage/resolve.js

@@ -0,0 +1,21 @@
+/**
+ * Storage Backend Resolver
+ *
+ * Creates a storage backend instance from config.
+ */
+import { LocalStorageBackend } from './local.js';
+/**
+ * Create a storage backend from the config's storage section.
+ */
+export function resolveStorage(config) {
+    switch (config.storage.type) {
+        case 'local':
+            return new LocalStorageBackend({
+                path: config.storage.options.path,
+            });
+        default:
+            throw new Error(`Unknown storage backend: ${config.storage.type}. ` +
+                `Supported: local. S3/R2/B2 coming soon.`);
+    }
+}
+//# sourceMappingURL=resolve.js.map

package/dist/storage/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../../src/storage/resolve.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEjD;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAuB;IACpD,QAAQ,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC5B,KAAK,OAAO;YACV,OAAO,IAAI,mBAAmB,CAAC;gBAC7B,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,IAA0B;aACxD,CAAC,CAAC;QAEL;YACE,MAAM,IAAI,KAAK,CACb,4BAA4B,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI;gBACnD,yCAAyC,CAC1C,CAAC;IACN,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,273 @@
+/**
+ * SaveState Archive Format (SAF) Types
+ *
+ * The SAF is an open format for capturing AI agent state.
+ * Structure: tar.gz → AES-256-GCM encrypted → .saf.enc
+ */
+export interface Manifest {
+    /** SAF format version */
+    version: string;
+    /** ISO 8601 timestamp of snapshot creation */
+    timestamp: string;
+    /** Unique snapshot identifier */
+    id: string;
+    /** Source platform identifier */
+    platform: string;
+    /** Adapter used to create this snapshot */
+    adapter: string;
+    /** SHA-256 checksum of the unencrypted archive */
+    checksum: string;
+    /** Parent snapshot ID (for incremental snapshots) */
+    parent?: string;
+    /** Human-readable label */
+    label?: string;
+    /** Tags for organization */
+    tags?: string[];
+    /** Size in bytes of the unencrypted archive */
+    size: number;
+}
+export interface Identity {
+    /** System prompt / personality / SOUL document */
+    personality?: string;
+    /** Configuration and settings */
+    config?: Record<string, unknown>;
+    /** Tool/plugin/skill configurations */
+    tools?: ToolConfig[];
+    /** Skills with their configs and scripts */
+    skills?: SkillEntry[];
+    /** Custom user scripts */
+    scripts?: ScriptEntry[];
+    /** Extension configurations (not code/node_modules) */
+    extensions?: ExtensionEntry[];
+    /** Project file manifest (paths + sizes, no content) */
+    fileManifest?: FileManifestEntry[];
+    /** Project metadata files (package.json, pyproject.toml, etc.) */
+    projectMeta?: Record<string, string>;
+}
+export interface ToolConfig {
+    name: string;
+    type: string;
+    config: Record<string, unknown>;
+    enabled: boolean;
+}
+export interface SkillEntry {
+    /** Skill directory name */
+    name: string;
+    /** SKILL.md content */
+    skillMd?: string;
+    /** Files in the skill (relative path → content) */
+    files: Record<string, string>;
+}
+export interface ScriptEntry {
+    /** Relative path from workspace root */
+    path: string;
+    /** Script content */
+    content: string;
+    /** Whether this is a cron wrapper */
+    isCronWrapper: boolean;
+}
+export interface ExtensionEntry {
+    /** Extension directory name */
+    name: string;
+    /** Config files in the extension (relative path → content) */
+    configs: Record<string, string>;
+}
+export interface FileManifestEntry {
+    /** Relative file path */
+    path: string;
+    /** File size in bytes */
+    size: number;
+    /** Last modified ISO timestamp */
+    modified: string;
+}
+export interface Memory {
+    /** Platform memory entries (ChatGPT memories, Claude memory, etc.) */
+    core: MemoryEntry[];
+    /** Knowledge base documents */
+    knowledge: KnowledgeDocument[];
+    /** Optional vector embeddings for search */
+    embeddings?: EmbeddingData;
+}
+export interface MemoryEntry {
+    id: string;
+    content: string;
+    source: string;
+    createdAt: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface KnowledgeDocument {
+    id: string;
+    filename: string;
+    mimeType: string;
+    /** Relative path within the archive */
+    path: string;
+    size: number;
+    checksum: string;
+}
+export interface EmbeddingData {
+    model: string;
+    dimensions: number;
+    /** Path to binary embeddings file */
+    path: string;
+}
+export interface ConversationIndex {
+    total: number;
+    conversations: ConversationMeta[];
+}
+export interface ConversationMeta {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    messageCount: number;
+    /** Relative path to the conversation JSON */
+    path: string;
+}
+export interface Conversation {
+    id: string;
+    title?: string;
+    createdAt: string;
+    updatedAt: string;
+    messages: Message[];
+    metadata?: Record<string, unknown>;
+}
+export interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system' | 'tool';
+    content: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PlatformMeta {
+    name: string;
+    version?: string;
+    apiVersion?: string;
+    accountId?: string;
+    exportMethod: string;
+}
+export interface SnapshotChain {
+    current: string;
+    parent?: string;
+    /** Full chain of ancestor snapshot IDs (oldest first) */
+    ancestors: string[];
+}
+export interface RestoreHints {
+    platform: string;
+    /** Steps needed for restore on this platform */
+    steps: RestoreStep[];
+    /** Capabilities that can't be auto-restored */
+    manualSteps?: string[];
+}
+export interface RestoreStep {
+    type: 'api' | 'file' | 'manual';
+    description: string;
+    target: string;
+    data?: string;
+}
+export interface Snapshot {
+    manifest: Manifest;
+    identity: Identity;
+    memory: Memory;
+    conversations: ConversationIndex;
+    platform: PlatformMeta;
+    chain: SnapshotChain;
+    restoreHints: RestoreHints;
+}
+export interface Adapter {
+    /** Unique adapter identifier */
+    readonly id: string;
+    /** Human-readable name */
+    readonly name: string;
+    /** Platform this adapter targets */
+    readonly platform: string;
+    /** Adapter version */
+    readonly version: string;
+    /** Check if this adapter can operate in the current environment */
+    detect(): Promise<boolean>;
+    /** Extract current state from the platform */
+    extract(): Promise<Snapshot>;
+    /** Restore state to the platform */
+    restore(snapshot: Snapshot): Promise<void>;
+    /** Get platform-specific identity information */
+    identify(): Promise<PlatformMeta>;
+}
+export interface StorageBackend {
+    /** Backend identifier (e.g., 'local', 's3', 'r2') */
+    readonly id: string;
+    /** Store encrypted data */
+    put(key: string, data: Buffer): Promise<void>;
+    /** Retrieve encrypted data */
+    get(key: string): Promise<Buffer>;
+    /** List all stored keys, optionally filtered by prefix */
+    list(prefix?: string): Promise<string[]>;
+    /** Delete stored data */
+    delete(key: string): Promise<void>;
+    /** Check if a key exists */
+    exists(key: string): Promise<boolean>;
+}
+export interface SaveStateConfig {
+    /** Config format version */
+    version: string;
+    /** Storage backend configuration */
+    storage: StorageConfig;
+    /** Default adapter to use */
+    defaultAdapter?: string;
+    /** Auto-snapshot schedule (cron expression or interval) */
+    schedule?: string;
+    /** Snapshot retention policy */
+    retention?: RetentionPolicy;
+    /** Registered adapters */
+    adapters: AdapterConfig[];
+}
+export interface StorageConfig {
+    /** Backend type: 'local' | 's3' | 'r2' | 'b2' | 'filesystem' */
+    type: string;
+    /** Backend-specific options */
+    options: Record<string, unknown>;
+}
+export interface RetentionPolicy {
+    /** Maximum number of snapshots to keep */
+    maxSnapshots?: number;
+    /** Maximum age of snapshots (e.g., '90d', '1y') */
+    maxAge?: string;
+    /** Keep at least one snapshot per period */
+    keepPer?: 'day' | 'week' | 'month';
+}
+export interface AdapterConfig {
+    id: string;
+    enabled: boolean;
+    options?: Record<string, unknown>;
+}
+export interface SearchResult {
+    snapshotId: string;
+    snapshotTimestamp: string;
+    type: 'memory' | 'conversation' | 'identity' | 'knowledge';
+    /** The matching content */
+    content: string;
+    /** Context around the match */
+    context?: string;
+    /** Relevance score (0-1) */
+    score: number;
+    /** Source path within the archive */
+    path: string;
+}
+export interface DiffResult {
+    snapshotA: string;
+    snapshotB: string;
+    changes: DiffChange[];
+    summary: {
+        added: number;
+        removed: number;
+        modified: number;
+    };
+}
+export interface DiffChange {
+    type: 'added' | 'removed' | 'modified';
+    category: 'identity' | 'memory' | 'conversation' | 'tool';
+    path: string;
+    description: string;
+    before?: string;
+    after?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * SaveState Archive Format (SAF) Types
+ *
+ * The SAF is an open format for capturing AI agent state.
+ * Structure: tar.gz → AES-256-GCM encrypted → .saf.enc
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@savestate/cli",
+  "version": "0.1.0",
+  "description": "Time Machine for AI. Backup, restore, and migrate your AI identity.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "savestate": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ai",
+    "backup",
+    "restore",
+    "encryption",
+    "agent",
+    "state",
+    "migration",
+    "chatgpt",
+    "claude",
+    "time-machine"
+  ],
+  "author": "DBH Ventures <hello@savestate.dev>",
+  "license": "MIT",
+  "homepage": "https://savestate.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/savestatedev/savestate.git"
+  },
+  "bugs": {
+    "url": "https://github.com/savestatedev/savestate/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "ora": "^8.2.0",
+    "tar": "^7.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.8.3"
+  }
+}