@almadar/workspace 0.8.0 → 0.10.0

package/dist/internal/backends/local.d.ts

@@ -4,6 +4,8 @@ export declare class LocalBackend implements WorkspaceBackend {
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    readFileBytes(absPath: string): Promise<Uint8Array>;
+    writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;
     exists(absPath: string): boolean;
     readdir(absPath: string): Promise<string[]>;
     readdirSync(absPath: string): string[];

package/dist/internal/backends/memory.d.ts

@@ -4,11 +4,14 @@
 import type { WorkspaceBackend } from '../types.js';
 export declare class MemoryBackend implements WorkspaceBackend {
     private files;
+    private bytes;
     private dirs;
     readFile(absPath: string): Promise<string>;
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    readFileBytes(absPath: string): Promise<Uint8Array>;
+    writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;
     exists(absPath: string): boolean;
     readdir(absPath: string): Promise<string[]>;
     readdirSync(absPath: string): string[];

package/dist/internal/git-client.d.ts

@@ -12,6 +12,12 @@ export interface GitStatus {
     modified: string[];
     untracked: string[];
 }
+/** One commit in the history of a path — the snapshot view. */
+export interface GitLogEntry {
+    oid: string;
+    timestamp: number;
+    subject: string;
+}
 export declare class GitClient {
     private readonly cwd;
     private readonly backend;
@@ -28,5 +34,16 @@ export declare class GitClient {
     addRemote(remote: string, url: string): Promise<void>;
     status(): Promise<GitStatus>;
     headSha(): Promise<string | null>;
+    /**
+     * Commit history of `filepath` (newest first) — the snapshot list. NUL-delimited
+     * fields so commit subjects with tabs/spaces parse cleanly.
+     */
+    log(filepath?: string, limit?: number): Promise<GitLogEntry[]>;
+    /** Content of `filepath` at commit `oid` — the restore read. Null if absent. */
+    show(oid: string, filepath: string): Promise<string | null>;
+    /** Bundle the whole repo into a single delta-compressed file (the durable archive). */
+    bundleAll(outAbsPath: string): Promise<void>;
+    /** Clone a bundle file into `targetDir` (hydrate a fresh workspace from the archive). */
+    cloneBundle(bundleAbsPath: string, targetDir: string): Promise<void>;
     private exec;
 }

package/dist/internal/types.d.ts

@@ -13,6 +13,9 @@ export interface WorkspaceBackend {
     readFileSync(absPath: string): string;
     writeFile(absPath: string, content: string): Promise<void>;
     writeFileSync(absPath: string, content: string): void;
+    /** Binary read/write — for git bundle artifacts (durable archive bytes). */
+    readFileBytes(absPath: string): Promise<Uint8Array>;
+    writeFileBytes(absPath: string, bytes: Uint8Array): Promise<void>;
     exists(absPath: string): boolean;
     readdir(absPath: string): Promise<string[]>;
     readdirSync(absPath: string): string[];

package/dist/internal/workspace-manager.d.ts

@@ -17,5 +17,5 @@ export declare function ensureSkeleton(backend: WorkspaceBackend, workDir: strin
 export declare function ensureOrbitalSessionDir(backend: WorkspaceBackend, workDir: string, orbital: string): Promise<void>;
 /** Write mint-time templates only when they don't exist. */
 export declare function writeMintTemplatesIfMissing(backend: WorkspaceBackend, workDir: string, userId: string, projectName: string, appId?: string): Promise<void>;
-/** Initialise git for the workspace if it isn't already a repo. */
+/** Initialise git for the workspace if it isn't already a repo (+ write `.gitignore`). */
 export declare function ensureGitInit(backend: WorkspaceBackend, workDir: string): Promise<GitClient>;

package/dist/service.d.ts

@@ -7,7 +7,7 @@
  * @packageDocumentation
  */
 import type { JsonObject, JsonValue } from '@almadar/core';
-import type { FileTreeNode, GitHubConfig, GitStatusInfo, WorkspaceObserver, WorkspaceService, WorkspaceWatchEvent } from './types.js';
+import type { FileTreeNode, GitHubConfig, GitStatusInfo, SnapshotMeta, WorkspaceArchiveBackend, WorkspaceObserver, WorkspaceService, WorkspaceWatchEvent } from './types.js';
 import type { WorkspaceBackend } from './internal/types.js';
 import { SinkManager } from './internal/sink-manager.js';
 import { GitClient } from './internal/git-client.js';
@@ -20,6 +20,7 @@ interface ServiceCtorArgs {
     appId?: string;
     git?: GitClient;
     github?: GitHubConfig;
+    archiveBackend?: WorkspaceArchiveBackend;
 }
 export declare class WorkspaceServiceImpl implements WorkspaceService {
     readonly workDir: string;
@@ -27,13 +28,20 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     private readonly backend;
     private readonly sinks;
     private readonly git;
-    private readonly github;
+    private github;
+    private readonly archiveBackend;
     /** Per-absolute-path serial queue. */
     private readonly writeQueue;
     readonly index: WorkspaceIndex;
     constructor(args: ServiceCtorArgs);
     get appId(): string | undefined;
     setAppId(id: string): void;
+    /**
+     * Set (or clear) the GitHub config after open. Lets a consumer resolve the
+     * link/token lazily — e.g. from a workspace file read post-open — and wire
+     * `commitAndPush`/`pullIfLinked` without knowing it at construction time.
+     */
+    setGitHub(config: GitHubConfig | undefined): void;
     /** Run `op` under a per-path serial lock. */
     private withLock;
     /** Make sure the parent directory of `absPath` exists. */
@@ -85,6 +93,15 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     } | null>;
     pullIfLinked(): Promise<boolean>;
     gitStatus(): Promise<GitStatusInfo>;
+    snapshot(reason: string): Promise<{
+        oid: string;
+    } | null>;
+    listSnapshots(opts?: {
+        limit?: number;
+    }): Promise<SnapshotMeta[]>;
+    restore(oid: string): Promise<string | null>;
+    archive(): Promise<void>;
+    hydrateFromArchive(): Promise<boolean>;
     subscribe(observer: WorkspaceObserver): () => void;
     watch(relPath: string, onChange: (event: WorkspaceWatchEvent) => void): () => void;
     dispose(): Promise<void>;

package/dist/types.d.ts

@@ -146,6 +146,24 @@ export interface GitStatusInfo {
     /** Resolved when an upstream remote+branch is configured. */
     linked: boolean;
 }
+/** One snapshot = one commit in the history of `schema.orb`. */
+export interface SnapshotMeta {
+    /** Commit oid. */
+    id: string;
+    /** Commit time, epoch ms. */
+    timestamp: number;
+    /** Human reason (the `snapshot: <reason>` subject, prefix stripped). */
+    reason: string;
+}
+/**
+ * Durable store for the workspace's git history when there's no remote — the
+ * consumer supplies it (e.g. a Firestore-backed bundle store on cloud). The
+ * workspace produces/consumes a single `git bundle`; it stays account-agnostic.
+ */
+export interface WorkspaceArchiveBackend {
+    saveBundle(bytes: Uint8Array): Promise<void>;
+    loadBundle(): Promise<Uint8Array | null>;
+}
 /** Single node returned by `listTree(relPath?)`. */
 export interface FileTreeNode {
     /** Workspace-relative POSIX path (forward slashes). */
@@ -181,6 +199,8 @@ export interface OpenWorkspaceOptions {
     github?: GitHubConfig;
     /** Fallback fetcher used when the local cache misses. */
     restore?: RestoreBackend;
+    /** Durable git-history store (bundle) for workspaces without a remote (e.g. cloud Firestore). */
+    archiveBackend?: WorkspaceArchiveBackend;
     /**
      * When `false`, open is a pure read: resolve an EXISTING workspace (local
      * resume, or restore that actually yields files) but NEVER mint a fresh one.
@@ -236,6 +256,8 @@ export interface WorkspaceService {
     readonly appId: string | undefined;
     readonly workDir: string;
     setAppId(id: string): void;
+    /** Set/clear the GitHub config post-open (resolve link/token lazily, then wire push/pull). */
+    setGitHub(config: GitHubConfig | undefined): void;
     readOrbital(name: string): string | null;
     writeOrbital(name: string, content: string): Promise<void>;
     listOrbitals(): string[];
@@ -289,6 +311,20 @@ export interface WorkspaceService {
     } | null>;
     pullIfLinked(): Promise<boolean>;
     gitStatus(): Promise<GitStatusInfo>;
+    /** Commit the current app files as a snapshot. Returns the oid, or null if nothing changed / no git. */
+    snapshot(reason: string): Promise<{
+        oid: string;
+    } | null>;
+    /** List snapshots (commits touching schema.orb), newest first. */
+    listSnapshots(opts?: {
+        limit?: number;
+    }): Promise<SnapshotMeta[]>;
+    /** Read `schema.orb` at a snapshot oid (the caller writes it back through the canonical save). */
+    restore(oid: string): Promise<string | null>;
+    /** Bundle the whole repo to the injected archive backend (durable history without a remote). No-op if unset. */
+    archive(): Promise<void>;
+    /** Reconstruct the repo from the archive backend into an empty workspace. Returns false if no archive. */
+    hydrateFromArchive(): Promise<boolean>;
     subscribe(observer: WorkspaceObserver): () => void;
     /**
      * Watch a workspace-relative path (file or directory) for EXTERNAL changes —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Storage-agnostic workspace primitives shared by Almadar consumers. One service, six exports, hidden paths, single observer. See docs/Almadar_Workspace.md.",
   "type": "module",
   "main": "./dist/index.js",