@almadar/workspace

Storage-agnostic workspace primitives shared by Almadar consumers (@almadar-io/rabit, apps/builder, tools/orbital-agent-cli).

One service. Typed methods. Hidden paths. Single observer.

Design

Full contract lives in docs/Almadar_Workspace.md in the main repo. This package implements that contract.

Surface (exhaustive — six names)

import {
  openWorkspace,            // factory
  type WorkspaceService,    // typed methods + subscribe + dispose
  type WorkspaceObserver,   // single onWrite(event) callback
  type WorkspaceWriteEvent, // discriminated union per write reason
  type OpenWorkspaceOptions,
  type RestoreBackend,
} from '@almadar/workspace';

Everything else is internal. The package's src/internal/ directory contains the ports of WorkspaceManager, WorkspaceResolver, restoreWorkspace, sinks, backends, templates, path constants, and GitClient — none exported.

Install

npm install @almadar/workspace

Published to GitHub Packages (https://npm.pkg.github.com). Add a .npmrc line for the @almadar scope to resolve from the registry.

Quick start

import { openWorkspace } from '@almadar/workspace';

const ws = await openWorkspace({
  root: '/workspaces',
  userId: 'alice',
});

await ws.writeOrbital('CartOrbital', orbContent);
await ws.emitTrace({ type: 'orbital_started', orbital: 'CartOrbital' });

ws.subscribe({
  onWrite(event) {
    switch (event.kind) {
      case 'orbital': /* push to your storage */ break;
      case 'trace':   /* push to SSE */ break;
      // ... exhaustive over WorkspaceWriteEvent variants
    }
  },
});

await ws.dispose();

License

BUSL-1.1 — see LICENSE.