@almadar/workspace 0.1.0-alpha.0 → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Public surface types for `@almadar/workspace`.
+ *
+ * Six names total are exported from the package barrel; everything else
+ * is internal. See docs/Almadar_Workspace.md for the contract.
+ *
+ * @packageDocumentation
+ */
+import type { JsonObject, JsonValue } from '@almadar/core';
+/**
+ * The only extension point. Consumers register one observer via
+ * `service.subscribe(observer)`; every workspace write fans out
+ * through `onWrite`. Adding a new `WorkspaceWriteEvent.kind` is a
+ * compile-time forcing function for every consumer's switch.
+ */
+export interface WorkspaceObserver {
+    onWrite(event: WorkspaceWriteEvent): Promise<void> | void;
+}
+/**
+ * Discriminated union covering every reason the workspace touches storage.
+ * Strict typed payload per variant — no `unknown`, no `any`.
+ *
+ * Consumers exhaust the union with
+ * `switch (event.kind) { …; default: const _: never = event; }`.
+ */
+export type WorkspaceWriteEvent = {
+    kind: 'orbital';
+    name: string;
+    content: string;
+} | {
+    kind: 'schema';
+    content: string;
+} | {
+    kind: 'analysis';
+    content: JsonObject;
+} | {
+    kind: 'plan';
+    content: JsonObject;
+} | {
+    kind: 'clarifications';
+    content: Record<string, string>;
+} | {
+    kind: 'coordinator-messages';
+    content: JsonValue[];
+} | {
+    kind: 'spec';
+    orbital: string;
+    content: JsonObject;
+} | {
+    kind: 'memory';
+    orbital: string;
+    content: JsonObject;
+} | {
+    kind: 'history';
+    orbital: string;
+    entry: JsonObject;
+} | {
+    kind: 'params-history';
+    orbital: string;
+    row: JsonObject;
+} | {
+    kind: 'errors';
+    orbital: string;
+    content: JsonObject[];
+} | {
+    kind: 'subagent-messages';
+    orbital: string;
+    content: JsonValue[];
+} | {
+    kind: 'trace';
+    event: JsonObject;
+} | {
+    kind: 'compiled';
+    relPath: string;
+    content: string;
+} | {
+    kind: 'orbital-archived';
+    name: string;
+} | {
+    kind: 'orbital-renamed';
+    from: string;
+    to: string;
+} | {
+    kind: 'file';
+    relPath: string;
+    content: string;
+};
+/**
+ * Caller-supplied backend used when the local cache misses but the
+ * workspace state lives somewhere addressable (Firestore, S3, etc.).
+ * Zero vendor dependencies inside this package; the consumer supplies
+ * the network/SDK plumbing.
+ */
+export interface RestoreBackend {
+    listFiles(): Promise<string[]>;
+    readFile(path: string): Promise<string | null>;
+}
+/**
+ * Opt-in git lifecycle config. When set on `openWorkspace`, the service
+ * exposes `commitAndPush` / `pullIfLinked` / `gitStatus`, and `dispose()`
+ * commits + pushes any pending changes.
+ */
+export interface GitHubConfig {
+    token: string;
+    owner?: string;
+    repo?: string;
+    /** Optional remote URL when cloning on resume (https with token-auth). */
+    repoUrl?: string;
+    /** Default branch — `main` if unset. */
+    branch?: string;
+}
+/** Git working-tree snapshot returned by `gitStatus()`. */
+export interface GitStatusInfo {
+    clean: boolean;
+    staged: string[];
+    modified: string[];
+    untracked: string[];
+    /** Resolved when an upstream remote+branch is configured. */
+    linked: boolean;
+}
+/** Single node returned by `listTree(relPath?)`. */
+export interface FileTreeNode {
+    /** Workspace-relative POSIX path (forward slashes). */
+    path: string;
+    /** Directory or regular file. Symlinks are not followed. */
+    type: 'file' | 'directory';
+    /** Byte size for files; `0` for directories. */
+    size: number;
+}
+/**
+ * Factory input. Lifecycle resolution order: `adopt` → resume-from-disk →
+ * `restore` backend → `github` clone → mint fresh.
+ */
+export interface OpenWorkspaceOptions {
+    /** Workspaces root, e.g. `/workspaces` — user dirs nest under it. */
+    root: string;
+    /** Owning user id. */
+    userId: string;
+    /** Resume an identified workspace, or promote later via `setAppId()`. */
+    appId?: string;
+    /** Adopt an existing absolute workDir as-is. */
+    adopt?: string;
+    /** Clone-on-resume / push-on-dispose configuration. */
+    github?: GitHubConfig;
+    /** Fallback fetcher used when the local cache misses. */
+    restore?: RestoreBackend;
+    /** Storage selector. `'memory'` is for tests; `'local'` is default. */
+    backend?: 'local' | 'memory';
+    /** Optional project name baked into the mint-time schema template. */
+    projectName?: string;
+}
+/**
+ * The single workspace I/O surface. Every consumer (rabit, apps/builder,
+ * cli, future tools) operates through this. Methods are grouped per
+ * docs/Almadar_Workspace.md §3.
+ *
+ * Generic parameters carry the caller's payload types through serialize +
+ * observer. The service stays neutral — it serializes JSON and emits typed
+ * `WorkspaceWriteEvent`s.
+ */
+export interface WorkspaceService {
+    readonly appId: string | undefined;
+    readonly workDir: string;
+    setAppId(id: string): void;
+    readOrbital(name: string): string | null;
+    writeOrbital(name: string, content: string): Promise<void>;
+    listOrbitals(): string[];
+    archiveOrbital(name: string): Promise<void>;
+    renameOrbital(from: string, to: string): Promise<void>;
+    readSchema(): string | null;
+    writeSchema(content: string): Promise<void>;
+    readAnalysis<T extends JsonObject>(): T | null;
+    writeAnalysis<T extends JsonObject>(analysis: T): Promise<void>;
+    readPlan<T extends JsonObject>(): T | null;
+    writePlan<T extends JsonObject>(plan: T): Promise<void>;
+    readClarificationAnswers(): Record<string, string>;
+    writeClarificationAnswers(answers: Record<string, string>): Promise<void>;
+    readCoordinatorMessages<T extends JsonValue>(): T[] | null;
+    writeCoordinatorMessages<T extends JsonValue>(messages: T[]): Promise<void>;
+    readSpec<T extends JsonObject>(orbital: string): T | null;
+    writeSpec<T extends JsonObject>(orbital: string, spec: T): Promise<void>;
+    readMemory<T extends JsonObject>(orbital: string): T | null;
+    writeMemory<T extends JsonObject>(orbital: string, memory: T): Promise<void>;
+    appendHistory<T extends JsonObject>(orbital: string, entry: T): Promise<void>;
+    readHistory<T extends JsonObject>(orbital: string): T[];
+    appendParamsHistory<T extends JsonObject>(orbital: string, row: T): Promise<void>;
+    readErrors<T extends JsonObject>(orbital: string): T[];
+    writeErrors<T extends JsonObject>(orbital: string, errors: T[]): Promise<void>;
+    readSubagentMessages<T extends JsonValue>(orbital: string): T[] | null;
+    writeSubagentMessages<T extends JsonValue>(orbital: string, messages: T[]): Promise<void>;
+    emitTrace<T extends JsonObject>(event: T): Promise<void>;
+    readTrace<T extends JsonObject>(): T[];
+    writeCompiled(relPath: string, content: string): Promise<void>;
+    readCompiled(relPath: string): string | null;
+    clearCompiled(): Promise<void>;
+    readFile(relPath: string): Promise<string | null>;
+    writeFile(relPath: string, content: string): Promise<void>;
+    listTree(relPath?: string): Promise<FileTreeNode[]>;
+    exists(relPath: string): Promise<boolean>;
+    commitAndPush(opts: {
+        message: string;
+        tags?: string[];
+    }): Promise<{
+        sha: string;
+    } | null>;
+    pullIfLinked(): Promise<boolean>;
+    gitStatus(): Promise<GitStatusInfo>;
+    subscribe(observer: WorkspaceObserver): () => void;
+    dispose(): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.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",