@bradygaster/squad-sdk 0.9.1 → 0.9.2-insider.1

package/dist/storage/sqlite-storage-provider.js

@@ -0,0 +1,383 @@
+import { posix } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync as fsMkdirSync, renameSync } from 'fs';
+import { dirname } from 'path';
+const DEFAULT_DB_PATH = '.squad/squad.db';
+/**
+ * SQLiteStorageProvider -- cross-platform SQLite-backed StorageProvider using sql.js (WASM).
+ *
+ * Use this provider when you need a single-file, portable storage backend that
+ * works identically across Windows, Linux, and macOS without native compilation.
+ * It is ideal for desktop tools and CLI applications that need durable storage
+ * without external database dependencies.
+ *
+ * **Initialization:** You MUST call {@link init} before performing any read or
+ * write operations. Calling `init()` is safe to call multiple times; subsequent
+ * calls are no-ops that return the same initialization promise.
+ *
+ * **Concurrency:** This provider is designed for single-process access. Running
+ * multiple processes against the same database file simultaneously may cause
+ * data corruption because sql.js loads the entire DB into memory and persists
+ * it atomically on every write. Use file-level locking or a dedicated process
+ * if concurrent access is required.
+ *
+ * **Database location:** The database file defaults to `.squad/squad.db`
+ * relative to the working directory. The file and parent directories are
+ * created automatically on first write. Callers are responsible for deleting
+ * the file when it is no longer needed (e.g. in test cleanup).
+ *
+ * Schema: `files(path TEXT PRIMARY KEY, content TEXT, updated_at TEXT)`
+ *
+ * sql.js runs SQLite entirely in WASM -- no native compilation required.
+ * The WASM bundle is loaded lazily via dynamic `import('sql.js')` so it
+ * only impacts startup when this provider is actually instantiated.
+ *
+ * Sync methods work because sql.js operations are synchronous under the
+ * hood (WASM, not network). The DB must be initialized before sync calls.
+ */
+export class SQLiteStorageProvider {
+    dbPath;
+    db = null;
+    initPromise = null;
+    constructor(dbPath = DEFAULT_DB_PATH) {
+        this.dbPath = dbPath;
+    }
+    // ── Initialization ──────────────────────────────────────────────────────
+    /**
+     * Initialize the SQLite database, loading the WASM bundle and creating the
+     * schema if needed. **Must be called before any read/write operation.**
+     *
+     * Safe to call multiple times -- the first call performs initialization and
+     * subsequent calls return the same resolved promise (no extra work).
+     *
+     * If the database file already exists on disk it is loaded into memory;
+     * otherwise a fresh in-memory database is created and will be persisted on
+     * the first write.
+     *
+     * @throws If the sql.js WASM bundle cannot be loaded (e.g. missing dependency).
+     */
+    async init() {
+        if (this.db)
+            return;
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = this.doInit();
+        return this.initPromise;
+    }
+    async doInit() {
+        const initSqlJs = (await import('sql.js')).default;
+        const SQL = await initSqlJs();
+        if (existsSync(this.dbPath)) {
+            const fileBuffer = readFileSync(this.dbPath);
+            this.db = new SQL.Database(fileBuffer);
+        }
+        else {
+            this.db = new SQL.Database();
+        }
+        this.db.run(`
+      CREATE TABLE IF NOT EXISTS files (
+        path       TEXT PRIMARY KEY,
+        content    TEXT,
+        updated_at TEXT
+      )
+    `);
+    }
+    /** Throws if the DB has not been initialized (for sync methods). */
+    ensureDb() {
+        if (!this.db) {
+            throw new Error('SQLiteStorageProvider is not initialized. Call init() before using sync methods.');
+        }
+        return this.db;
+    }
+    /** Ensure the DB is ready (for async methods). */
+    async ready() {
+        await this.init();
+        return this.ensureDb();
+    }
+    // ── Helpers ─────────────────────────────────────────────────────────────
+    /** Normalize a path to forward-slash POSIX form with no trailing slash. */
+    norm(p) {
+        return posix.normalize(p.replace(/\\/g, '/')).replace(/\/+$/, '');
+    }
+    /** Escape SQL LIKE wildcards so user-supplied paths are matched literally. */
+    escapeLike(value) {
+        return value.replace(/[%_]/g, char => `\\${char}`);
+    }
+    /** Persist the in-memory DB to disk (atomic write-then-rename). */
+    persist() {
+        const db = this.ensureDb();
+        const data = db.export();
+        const buffer = Buffer.from(data);
+        fsMkdirSync(dirname(this.dbPath), { recursive: true });
+        const tmpPath = this.dbPath + '.tmp';
+        writeFileSync(tmpPath, buffer);
+        renameSync(tmpPath, this.dbPath);
+    }
+    now() {
+        return new Date().toISOString();
+    }
+    // ── Async interface ─────────────────────────────────────────────────────
+    async read(filePath) {
+        await this.ready();
+        return this.readSync(filePath);
+    }
+    async write(filePath, data) {
+        await this.ready();
+        this.writeSync(filePath, data);
+    }
+    async append(filePath, data) {
+        await this.ready();
+        const key = this.norm(filePath);
+        const existing = this.readSync(filePath) ?? '';
+        this.internalWrite(key, existing + data);
+    }
+    async exists(filePath) {
+        await this.ready();
+        return this.existsSync(filePath);
+    }
+    async list(dirPath) {
+        await this.ready();
+        return this.listSync(dirPath);
+    }
+    async delete(filePath) {
+        await this.ready();
+        const db = this.ensureDb();
+        const key = this.norm(filePath);
+        db.run('DELETE FROM files WHERE path = ?', [key]);
+        this.persist();
+    }
+    async deleteDir(dirPath) {
+        await this.ready();
+        const db = this.ensureDb();
+        const dir = this.norm(dirPath);
+        db.run('DELETE FROM files WHERE path = ? OR path LIKE ? ESCAPE \'\\\'', [dir, `${this.escapeLike(dir)}/%`]);
+        this.persist();
+    }
+    // ── Sync interface ──────────────────────────────────────────────────────
+    readSync(filePath) {
+        const db = this.ensureDb();
+        const key = this.norm(filePath);
+        const stmt = db.prepare('SELECT content FROM files WHERE path = ?');
+        stmt.bind([key]);
+        if (stmt.step()) {
+            const row = stmt.getAsObject();
+            stmt.free();
+            return row.content;
+        }
+        stmt.free();
+        return undefined;
+    }
+    writeSync(filePath, data) {
+        const key = this.norm(filePath);
+        this.internalWrite(key, data);
+    }
+    existsSync(filePath) {
+        const db = this.ensureDb();
+        const key = this.norm(filePath);
+        // Exact file match OR directory prefix match
+        const stmt = db.prepare('SELECT 1 FROM files WHERE path = ? OR path LIKE ? ESCAPE \'\\\' LIMIT 1');
+        stmt.bind([key, `${this.escapeLike(key)}/%`]);
+        const found = stmt.step();
+        stmt.free();
+        return found;
+    }
+    listSync(dirPath) {
+        const db = this.ensureDb();
+        const dir = this.norm(dirPath);
+        const prefix = dir + '/';
+        const stmt = db.prepare('SELECT path FROM files WHERE path LIKE ? ESCAPE \'\\\'');
+        stmt.bind([`${this.escapeLike(dir)}/%`]);
+        const entries = new Set();
+        while (stmt.step()) {
+            const row = stmt.getAsObject();
+            const rest = row.path.slice(prefix.length);
+            const name = rest.split('/')[0];
+            entries.add(name);
+        }
+        stmt.free();
+        return [...entries];
+    }
+    // ── Phase 3 Wave 1 additions ────────────────────────────────────────────
+    async isDirectory(targetPath) {
+        await this.ready();
+        return this.isDirectorySync(targetPath);
+    }
+    async mkdir(_dirPath, _options) {
+        // SQLite provider stores files in a virtual tree — directories are implicit.
+        await this.ready();
+    }
+    async rename(oldPath, newPath) {
+        await this.ready();
+        const db = this.ensureDb();
+        const oldKey = this.norm(oldPath);
+        const newKey = this.norm(newPath);
+        const prefix = oldKey + '/';
+        // Collect rows to move
+        const stmt = db.prepare('SELECT path, content, updated_at FROM files WHERE path = ? OR path LIKE ? ESCAPE \'\\\'');
+        stmt.bind([oldKey, `${this.escapeLike(oldKey)}/%`]);
+        const rows = [];
+        while (stmt.step()) {
+            rows.push(stmt.getAsObject());
+        }
+        stmt.free();
+        if (rows.length === 0) {
+            const err = new Error(`ENOENT: no such file or directory, rename '${oldPath}'`);
+            err.code = 'ENOENT';
+            throw err;
+        }
+        // Delete old, insert new
+        for (const row of rows) {
+            const renamedPath = row.path === oldKey
+                ? newKey
+                : newKey + row.path.slice(oldKey.length);
+            db.run('DELETE FROM files WHERE path = ?', [row.path]);
+            db.run('INSERT INTO files (path, content, updated_at) VALUES (?, ?, ?) ON CONFLICT(path) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at', [renamedPath, row.content, this.now()]);
+        }
+        this.persist();
+    }
+    async copy(srcPath, destPath) {
+        await this.ready();
+        const srcKey = this.norm(srcPath);
+        const content = this.readSync(srcPath);
+        if (content === undefined) {
+            const err = new Error(`ENOENT: no such file or directory, copy '${srcPath}'`);
+            err.code = 'ENOENT';
+            throw err;
+        }
+        this.internalWrite(this.norm(destPath), content);
+    }
+    async stat(targetPath) {
+        await this.ready();
+        const db = this.ensureDb();
+        const key = this.norm(targetPath);
+        // Check for exact file match
+        const stmt = db.prepare('SELECT content, updated_at FROM files WHERE path = ?');
+        stmt.bind([key]);
+        if (stmt.step()) {
+            const row = stmt.getAsObject();
+            stmt.free();
+            return {
+                size: Buffer.byteLength(row.content, 'utf-8'),
+                mtimeMs: new Date(row.updated_at).getTime(),
+                isDirectory: false,
+            };
+        }
+        stmt.free();
+        // Check if it's a directory (has children)
+        const dirStmt = db.prepare('SELECT 1 FROM files WHERE path LIKE ? ESCAPE \'\\\' LIMIT 1');
+        dirStmt.bind([`${this.escapeLike(key)}/%`]);
+        const isDir = dirStmt.step();
+        dirStmt.free();
+        if (isDir) {
+            return { size: 0, mtimeMs: 0, isDirectory: true };
+        }
+        return undefined;
+    }
+    isDirectorySync(targetPath) {
+        const db = this.ensureDb();
+        const key = this.norm(targetPath);
+        // A path is a directory if it's not a file but has children
+        const fileStmt = db.prepare('SELECT 1 FROM files WHERE path = ?');
+        fileStmt.bind([key]);
+        const isFile = fileStmt.step();
+        fileStmt.free();
+        if (isFile)
+            return false;
+        const dirStmt = db.prepare('SELECT 1 FROM files WHERE path LIKE ? ESCAPE \'\\\' LIMIT 1');
+        dirStmt.bind([`${this.escapeLike(key)}/%`]);
+        const isDir = dirStmt.step();
+        dirStmt.free();
+        return isDir;
+    }
+    mkdirSync(_dirPath, _options) {
+        // SQLite provider stores files in a virtual tree — directories are implicit.
+        this.ensureDb();
+    }
+    statSync(targetPath) {
+        const db = this.ensureDb();
+        const key = this.norm(targetPath);
+        // Check for exact file match
+        const stmt = db.prepare('SELECT content, updated_at FROM files WHERE path = ?');
+        stmt.bind([key]);
+        if (stmt.step()) {
+            const row = stmt.getAsObject();
+            stmt.free();
+            return {
+                size: Buffer.byteLength(row.content, 'utf-8'),
+                mtimeMs: new Date(row.updated_at).getTime(),
+                isDirectory: false,
+            };
+        }
+        stmt.free();
+        // Check if it's a directory (has children)
+        const dirStmt = db.prepare('SELECT 1 FROM files WHERE path LIKE ? ESCAPE \'\\\' LIMIT 1');
+        dirStmt.bind([`${this.escapeLike(key)}/%`]);
+        const isDir = dirStmt.step();
+        dirStmt.free();
+        if (isDir) {
+            return { size: 0, mtimeMs: 0, isDirectory: true };
+        }
+        return undefined;
+    }
+    appendSync(filePath, data) {
+        const key = this.norm(filePath);
+        const existing = this.readSync(filePath) ?? '';
+        this.internalWrite(key, existing + data);
+    }
+    deleteSync(filePath) {
+        const db = this.ensureDb();
+        const key = this.norm(filePath);
+        db.run('DELETE FROM files WHERE path = ?', [key]);
+        this.persist();
+    }
+    renameSync(oldPath, newPath) {
+        const db = this.ensureDb();
+        const oldKey = this.norm(oldPath);
+        const newKey = this.norm(newPath);
+        const prefix = oldKey + '/';
+        // Collect rows to move
+        const stmt = db.prepare('SELECT path, content, updated_at FROM files WHERE path = ? OR path LIKE ? ESCAPE \'\\\'');
+        stmt.bind([oldKey, `${this.escapeLike(oldKey)}/%`]);
+        const rows = [];
+        while (stmt.step()) {
+            rows.push(stmt.getAsObject());
+        }
+        stmt.free();
+        if (rows.length === 0) {
+            const err = new Error(`ENOENT: no such file or directory, rename '${oldPath}'`);
+            err.code = 'ENOENT';
+            throw err;
+        }
+        // Delete old, insert new
+        for (const row of rows) {
+            const renamedPath = row.path === oldKey
+                ? newKey
+                : newKey + row.path.slice(oldKey.length);
+            db.run('DELETE FROM files WHERE path = ?', [row.path]);
+            db.run('INSERT INTO files (path, content, updated_at) VALUES (?, ?, ?) ON CONFLICT(path) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at', [renamedPath, row.content, this.now()]);
+        }
+        this.persist();
+    }
+    copySync(srcPath, destPath) {
+        const content = this.readSync(srcPath);
+        if (content === undefined) {
+            const err = new Error(`ENOENT: no such file or directory, copy '${srcPath}'`);
+            err.code = 'ENOENT';
+            throw err;
+        }
+        this.internalWrite(this.norm(destPath), content);
+    }
+    deleteDirSync(dirPath) {
+        const db = this.ensureDb();
+        const dir = this.norm(dirPath);
+        db.run('DELETE FROM files WHERE path = ? OR path LIKE ? ESCAPE \'\\\'', [dir, `${this.escapeLike(dir)}/%`]);
+        this.persist();
+    }
+    // ── Internal────────────────────────────────────────────────────────────
+    internalWrite(normalizedPath, data) {
+        const db = this.ensureDb();
+        db.run(`INSERT INTO files (path, content, updated_at) VALUES (?, ?, ?)
+       ON CONFLICT(path) DO UPDATE SET content = excluded.content, updated_at = excluded.updated_at`, [normalizedPath, data, this.now()]);
+        this.persist();
+    }
+}
+//# sourceMappingURL=sqlite-storage-provider.js.map

package/dist/storage/sqlite-storage-provider.js.map

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

package/dist/storage/storage-error.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Sanitized storage error that strips internal filesystem paths from error messages.
+ *
+ * When a StorageProvider operation fails, the underlying OS error often contains
+ * absolute filesystem paths (e.g. `/home/user/.squad/data/file.txt`). Exposing
+ * these in logs or user-facing output leaks server internals. StorageError
+ * replaces the full path with just the basename so callers see *what* failed
+ * and *why* (the errno code) without revealing *where* on disk.
+ *
+ * @example
+ * ```ts
+ * // Thrown automatically by FSStorageProvider on failure:
+ * // StorageError: Storage read failed for "file.txt": ENOENT
+ * ```
+ */
+export declare class StorageError extends Error {
+    /** The errno code from the underlying OS/system error (e.g. `ENOENT`, `EACCES`, `UNKNOWN`). */
+    readonly code: string;
+    /** The storage operation that failed (e.g. `read`, `write`, `delete`, `rename`). */
+    readonly operation: string;
+    /**
+     * @param operation - The storage operation that failed (e.g. `read`, `write`).
+     * @param filePath  - The original file path; only its basename is included in the message.
+     * @param cause     - The underlying Node.js filesystem error.
+     */
+    constructor(operation: string, filePath: string, cause: NodeJS.ErrnoException);
+}
+//# sourceMappingURL=storage-error.d.ts.map

package/dist/storage/storage-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-error.d.ts","sourceRoot":"","sources":["../../src/storage/storage-error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,+FAA+F;IAC/F,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oFAAoF;IACpF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;OAIG;gBACS,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,cAAc;CAO9E"}

package/dist/storage/storage-error.js

@@ -0,0 +1,35 @@
+import { basename } from 'path';
+/**
+ * Sanitized storage error that strips internal filesystem paths from error messages.
+ *
+ * When a StorageProvider operation fails, the underlying OS error often contains
+ * absolute filesystem paths (e.g. `/home/user/.squad/data/file.txt`). Exposing
+ * these in logs or user-facing output leaks server internals. StorageError
+ * replaces the full path with just the basename so callers see *what* failed
+ * and *why* (the errno code) without revealing *where* on disk.
+ *
+ * @example
+ * ```ts
+ * // Thrown automatically by FSStorageProvider on failure:
+ * // StorageError: Storage read failed for "file.txt": ENOENT
+ * ```
+ */
+export class StorageError extends Error {
+    /** The errno code from the underlying OS/system error (e.g. `ENOENT`, `EACCES`, `UNKNOWN`). */
+    code;
+    /** The storage operation that failed (e.g. `read`, `write`, `delete`, `rename`). */
+    operation;
+    /**
+     * @param operation - The storage operation that failed (e.g. `read`, `write`).
+     * @param filePath  - The original file path; only its basename is included in the message.
+     * @param cause     - The underlying Node.js filesystem error.
+     */
+    constructor(operation, filePath, cause) {
+        super(`Storage ${operation} failed for "${basename(filePath)}": ${cause.code ?? 'UNKNOWN'}`);
+        this.name = 'StorageError';
+        this.code = cause.code ?? 'UNKNOWN';
+        this.operation = operation;
+        this.cause = cause;
+    }
+}
+//# sourceMappingURL=storage-error.js.map

package/dist/storage/storage-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-error.js","sourceRoot":"","sources":["../../src/storage/storage-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,MAAM,CAAC;AAEhC;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,+FAA+F;IACtF,IAAI,CAAS;IACtB,oFAAoF;IAC3E,SAAS,CAAS;IAE3B;;;;OAIG;IACH,YAAY,SAAiB,EAAE,QAAgB,EAAE,KAA4B;QAC3E,KAAK,CAAC,WAAW,SAAS,gBAAgB,QAAQ,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,IAAI,IAAI,SAAS,EAAE,CAAC,CAAC;QAC7F,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,SAAS,CAAC;QACpC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}

package/dist/storage/storage-provider.d.ts

@@ -0,0 +1,161 @@
+/**
+ * StorageProvider — abstract I/O contract for squad-sdk.
+ *
+ * All persistent storage operations flow through this interface so that
+ * runtimes (Node fs, in-memory, cloud) can be swapped without touching
+ * business logic.
+ *
+ * Wave 1 ships FSStorageProvider (Node.js fs wrapper).
+ * Wave 2 will remove the synchronous methods; callers should migrate now.
+ *
+ * **Error handling note:** FSStorageProvider wraps OS errors in `StorageError`
+ * (with typed `.code` and `.operation`). InMemoryStorageProvider and
+ * SQLiteStorageProvider throw plain `Error` for invalid operations. Callers
+ * that need provider-agnostic error handling should catch `Error` and inspect
+ * `.code` only when the value is a `StorageError`.
+ */
+/** Metadata returned by stat(). */
+export interface StorageStats {
+    /** File size in bytes. 0 for directories in virtual providers. */
+    size: number;
+    /** Last modification time as ms since epoch. */
+    mtimeMs: number;
+    /** True if the path is a directory. */
+    isDirectory: boolean;
+}
+export interface StorageProvider {
+    /**
+     * Read the full contents of a file as a UTF-8 string.
+     * Returns `undefined` if the file does not exist (ENOENT).
+     */
+    read(filePath: string): Promise<string | undefined>;
+    /**
+     * Write data to a file, creating parent directories as needed.
+     * Overwrites any existing content.
+     */
+    write(filePath: string, data: string): Promise<void>;
+    /**
+     * Append data to a file, creating it (and parent dirs) if it does not exist.
+     */
+    append(filePath: string, data: string): Promise<void>;
+    /**
+     * Return `true` if the path exists (file or directory).
+     *
+     * ⚠️ TOCTOU WARNING: Do not use exists() as a guard before read/write.
+     * Between the exists() check and the subsequent operation, the file can
+     * be deleted, replaced, or swapped by another process. Instead, call
+     * read() directly and handle `undefined` (ENOENT) in the result.
+     */
+    exists(filePath: string): Promise<boolean>;
+    /**
+     * Return the names (not full paths) of entries directly inside `dirPath`.
+     * Returns an empty array if the directory is empty or does not exist.
+     */
+    list(dirPath: string): Promise<string[]>;
+    /**
+     * Delete a file. No-op if the file does not exist (ENOENT).
+     */
+    delete(filePath: string): Promise<void>;
+    /**
+     * Recursively delete a directory and all its contents.
+     * No-op if the directory does not exist (ENOENT).
+     */
+    deleteDir(dirPath: string): Promise<void>;
+    /**
+     * Return `true` if the path exists and is a directory.
+     * Returns `false` for files or non-existent paths.
+     */
+    isDirectory(targetPath: string): Promise<boolean>;
+    /**
+     * Create a directory. When `options.recursive` is true, creates parent
+     * directories as needed (like `mkdir -p`). No-op if the directory
+     * already exists.
+     */
+    mkdir(dirPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    /**
+     * Atomically rename/move a file or directory.
+     * Throws StorageError if the source does not exist.
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+    /**
+     * Copy a file from `srcPath` to `destPath`.
+     * Creates parent directories for `destPath` as needed.
+     * Overwrites `destPath` if it already exists.
+     * Throws StorageError if `srcPath` does not exist.
+     */
+    copy(srcPath: string, destPath: string): Promise<void>;
+    /**
+     * Return file/directory metadata, or `undefined` if the path does not exist.
+     */
+    stat(targetPath: string): Promise<StorageStats | undefined>;
+    /**
+     * Synchronous read. Returns `undefined` on ENOENT.
+     * @deprecated Use read() instead. Migration: replace `const data = provider.readSync(path)` with `const data = await provider.read(path)`. Will be removed in Wave 2.
+     */
+    readSync(filePath: string): string | undefined;
+    /**
+     * Synchronous write with recursive mkdir.
+     * @deprecated Use write() instead. Migration: replace `provider.writeSync(path, data)` with `await provider.write(path, data)`. Will be removed in Wave 2.
+     */
+    writeSync(filePath: string, data: string): void;
+    /**
+     * Synchronous exists check.
+     * @deprecated Use exists() instead. Migration: replace `if (provider.existsSync(path))` with `if (await provider.exists(path))`. Will be removed in Wave 2.
+     *
+     * TOCTOU: Same race condition warning as exists(). Prefer read()
+     * with undefined check over exists() then read() patterns.
+     */
+    existsSync(filePath: string): boolean;
+    /**
+     * Synchronous directory listing.
+     * Returns entry names directly inside dirPath.
+     * Returns empty array if directory does not exist.
+     * @deprecated Use list() instead. Migration: replace `const entries = provider.listSync(dir)` with `const entries = await provider.list(dir)`. Will be removed in Wave 2.
+     */
+    listSync(dirPath: string): string[];
+    /**
+     * Synchronous directory check.
+     * @deprecated Use isDirectory() instead. Migration: replace `if (provider.isDirectorySync(path))` with `if (await provider.isDirectory(path))`. Will be removed in Wave 2.
+     */
+    isDirectorySync(targetPath: string): boolean;
+    /**
+     * Synchronous directory creation.
+     * @deprecated Use mkdir() instead. Migration: replace `provider.mkdirSync(dir, { recursive: true })` with `await provider.mkdir(dir, { recursive: true })`. Will be removed in Wave 2.
+     */
+    mkdirSync(dirPath: string, options?: {
+        recursive?: boolean;
+    }): void;
+    /**
+     * Synchronous stat. Returns undefined on ENOENT.
+     * @deprecated Use stat() instead. Migration: replace `const s = provider.statSync(path)` with `const s = await provider.stat(path)`. Will be removed in Wave 2.
+     */
+    statSync(targetPath: string): StorageStats | undefined;
+    /**
+     * Synchronous append with recursive mkdir.
+     * @deprecated Use append() instead. Migration: replace `provider.appendSync(path, data)` with `await provider.append(path, data)`. Will be removed in Wave 2.
+     */
+    appendSync(filePath: string, data: string): void;
+    /**
+     * Synchronous delete. No-op if file does not exist (ENOENT).
+     * @deprecated Use delete() instead. Migration: replace `provider.deleteSync(path)` with `await provider.delete(path)`. Will be removed in Wave 2.
+     */
+    deleteSync(filePath: string): void;
+    /**
+     * Synchronous rename/move.
+     * @deprecated Use rename() instead. Migration: replace `provider.renameSync(old, new)` with `await provider.rename(old, new)`. Will be removed in Wave 2.
+     */
+    renameSync(oldPath: string, newPath: string): void;
+    /**
+     * Synchronous file copy with recursive mkdir for dest.
+     * @deprecated Use copy() instead. Migration: replace `provider.copySync(src, dest)` with `await provider.copy(src, dest)`. Will be removed in Wave 2.
+     */
+    copySync(srcPath: string, destPath: string): void;
+    /**
+     * Synchronous recursive directory delete. No-op if dir does not exist (ENOENT).
+     * @deprecated Use deleteDir() instead. Migration: replace `provider.deleteDirSync(dir)` with `await provider.deleteDir(dir)`. Will be removed in Wave 2.
+     */
+    deleteDirSync(dirPath: string): void;
+}
+//# sourceMappingURL=storage-provider.d.ts.map

package/dist/storage/storage-provider.d.ts.map

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

package/dist/storage/storage-provider.js

@@ -0,0 +1,18 @@
+/**
+ * StorageProvider — abstract I/O contract for squad-sdk.
+ *
+ * All persistent storage operations flow through this interface so that
+ * runtimes (Node fs, in-memory, cloud) can be swapped without touching
+ * business logic.
+ *
+ * Wave 1 ships FSStorageProvider (Node.js fs wrapper).
+ * Wave 2 will remove the synchronous methods; callers should migrate now.
+ *
+ * **Error handling note:** FSStorageProvider wraps OS errors in `StorageError`
+ * (with typed `.code` and `.operation`). InMemoryStorageProvider and
+ * SQLiteStorageProvider throw plain `Error` for invalid operations. Callers
+ * that need provider-agnostic error handling should catch `Error` and inspect
+ * `.code` only when the value is a `StorageError`.
+ */
+export {};
+//# sourceMappingURL=storage-provider.js.map