@almadar/workspace 0.2.6 → 0.4.0

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

@@ -21,4 +21,5 @@ export declare class LocalBackend implements WorkspaceBackend {
     }>;
     rename(srcAbs: string, dstAbs: string): Promise<void>;
     chmod(absPath: string, mode: number): Promise<void>;
+    watch(absPath: string, onChange: (kind: 'change' | 'rename') => void): () => void;
 }

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

@@ -22,6 +22,7 @@ export declare class MemoryBackend implements WorkspaceBackend {
     }>;
     rename(srcAbs: string, dstAbs: string): Promise<void>;
     chmod(): Promise<void>;
+    watch(): () => void;
     getAll(): Map<string, string>;
     clear(): void;
 }

package/dist/internal/types.d.ts

@@ -37,6 +37,15 @@ export interface WorkspaceBackend {
     rename(srcAbs: string, dstAbs: string): Promise<void>;
     /** Set file mode bits (e.g. `0o600` for a secrets file). No-op on backends without a real fs. */
     chmod(absPath: string, mode: number): Promise<void>;
+    /**
+     * Watch an absolute path (file or directory) for EXTERNAL changes — edits
+     * made outside this service (a user editing a `.orb` in another editor, a
+     * remote sync landing). Returns a closer that stops watching. The `'local'`
+     * backend implements this with `fs.watch`; backends without a real fs
+     * (memory) may no-op. A future remote/github backend implements it its own
+     * way (poll/webhook) — consumers never see the difference.
+     */
+    watch(absPath: string, onChange: (kind: 'change' | 'rename') => void): () => void;
 }
 /**
  * The persisted marker that pins an `appId` to a workspace dir on disk.

package/dist/list-workspaces.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `listWorkspaces` — enumerate the app-workspaces a user has under a root.
+ *
+ * The single source for "which projects exist locally": scans
+ * `<root>/<userId>/*` for dirs carrying an `app-marker.json` (minted or
+ * adopted-as-app workspaces) and reports `{ appId, workDir, name?, updatedAt? }`.
+ * Bare-adopted loose files (no marker) are intentionally excluded — they aren't
+ * projects. Consumers (apps/builder's offline AppStore, orbital-agent-cli) use
+ * this instead of fs-scanning the layout themselves.
+ *
+ * @packageDocumentation
+ */
+import type { ListWorkspacesOptions, WorkspaceSummary } from './types.js';
+export declare function listWorkspaces(opts: ListWorkspacesOptions): Promise<WorkspaceSummary[]>;

package/dist/service.d.ts

@@ -7,7 +7,7 @@
  * @packageDocumentation
  */
 import type { JsonObject, JsonValue } from '@almadar/core';
-import type { FileTreeNode, GitHubConfig, GitStatusInfo, WorkspaceObserver, WorkspaceService } from './types.js';
+import type { FileTreeNode, GitHubConfig, GitStatusInfo, 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';
@@ -85,6 +85,7 @@ export declare class WorkspaceServiceImpl implements WorkspaceService {
     pullIfLinked(): Promise<boolean>;
     gitStatus(): Promise<GitStatusInfo>;
     subscribe(observer: WorkspaceObserver): () => void;
+    watch(relPath: string, onChange: (event: WorkspaceWatchEvent) => void): () => void;
     dispose(): Promise<void>;
 }
 export {};

package/dist/types.d.ts

@@ -98,6 +98,18 @@ export type WorkspaceWriteEvent = {
     kind: 'workspace-index-manifest';
     content: JsonObject;
 };
+/**
+ * Emitted by {@link WorkspaceService.watch} when storage changes underneath the
+ * service — an edit made OUTSIDE this service (another editor, a remote sync).
+ * Distinct from {@link WorkspaceObserver}, which fires on writes the service
+ * itself performs.
+ */
+export interface WorkspaceWatchEvent {
+    /** Workspace-relative POSIX path that changed. */
+    relPath: string;
+    /** `'change'` = content edited; `'rename'` = created / deleted / moved. */
+    kind: 'change' | 'rename';
+}
 /**
  * Caller-supplied backend used when the local cache misses but the
  * workspace state lives somewhere addressable (Firestore, S3, etc.).
@@ -153,6 +165,15 @@ export interface OpenWorkspaceOptions {
     appId?: string;
     /** Adopt an existing absolute workDir as-is. */
     adopt?: string;
+    /**
+     * Bare adopt — use the adopted dir WITHOUT scaffolding it: no `.almadar/`
+     * skeleton, no mint templates, no app-marker, no index warm. For opening a
+     * loose external file in place (desktop file-centric editing): read / write /
+     * watch the file via the sandboxed relPath (its basename), leaving zero litter
+     * in the user's directory. Only meaningful together with `adopt`; ignored
+     * otherwise.
+     */
+    bare?: boolean;
     /** Clone-on-resume / push-on-dispose configuration. */
     github?: GitHubConfig;
     /** Fallback fetcher used when the local cache misses. */
@@ -169,6 +190,26 @@ export interface OpenWorkspaceOptions {
      */
     embedder?: EmbedderPort;
 }
+/** Input for {@link listWorkspaces}. */
+export interface ListWorkspacesOptions {
+    /** Workspaces root, e.g. `/workspaces` — user dirs nest under it. */
+    root: string;
+    /** Owning user id. */
+    userId: string;
+    /** Storage selector. `'memory'` is for tests; `'local'` is default. */
+    backend?: 'local' | 'memory';
+}
+/** One project workspace returned by {@link listWorkspaces}. */
+export interface WorkspaceSummary {
+    /** Pinned app id from `.almadar/app-marker.json`. */
+    appId: string;
+    /** Absolute workspace directory. */
+    workDir: string;
+    /** Schema display name (`schema.orb` `name`), when present. */
+    name?: string;
+    /** `schema.orb` mtime if present, else the marker's `createdAt`. */
+    updatedAt?: number;
+}
 /**
  * The single workspace I/O surface. Every consumer (rabit, apps/builder,
  * cli, future tools) operates through this. Methods are grouped per
@@ -234,6 +275,14 @@ export interface WorkspaceService {
     pullIfLinked(): Promise<boolean>;
     gitStatus(): Promise<GitStatusInfo>;
     subscribe(observer: WorkspaceObserver): () => void;
+    /**
+     * Watch a workspace-relative path (file or directory) for EXTERNAL changes —
+     * edits made outside this service, e.g. a user editing a `.orb` in another
+     * editor (desktop hot-reload). Unlike `subscribe`, which is write-side only.
+     * Backend-agnostic: `'local'` uses `fs.watch`; a remote/github backend its own
+     * mechanism. Returns an unsubscribe function. Rejects `..` / absolute paths.
+     */
+    watch(relPath: string, onChange: (event: WorkspaceWatchEvent) => void): () => void;
     readonly index: WorkspaceIndex;
     dispose(): Promise<void>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@almadar/workspace",
-  "version": "0.2.6",
+  "version": "0.4.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",