@almadar/workspace 0.2.5 → 0.3.0

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

@@ -20,4 +20,6 @@ export declare class LocalBackend implements WorkspaceBackend {
         isDirectory: boolean;
     }>;
     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

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

package/dist/internal/types.d.ts

@@ -35,6 +35,17 @@ export interface WorkspaceBackend {
      * exists; backend ensures `dstAbs`'s parent dir exists before move.
      */
     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/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

@@ -7,6 +7,7 @@
  * @packageDocumentation
  */
 import type { JsonObject, JsonValue } from '@almadar/core';
+import type { ProviderConfig } from '@almadar/llm';
 import type { EmbedderPort, WorkspaceIndex } from './workspace-index/types.js';
 /**
  * The only extension point. Consumers register one observer via
@@ -97,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.).
@@ -152,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. */
@@ -233,6 +255,83 @@ 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>;
 }
+/**
+ * Non-secret account config, persisted to `~/.almadar/config.json`. Safe to
+ * inspect/sync. Secrets live in `credentials.json` (see {@link ProviderCredential}).
+ */
+export interface AccountConfig {
+    schemaVersion: 1;
+    /** ISO timestamp; absence signals the first-run setup hasn't completed. */
+    setupCompletedAt?: string;
+    defaultProvider: string;
+    defaultModel: string;
+    autonomy: 'full' | 'balanced' | 'cautious';
+    budget?: number;
+    /** Per-provider non-secret overrides, keyed by provider name. */
+    providers?: Record<string, {
+        baseUrl?: string;
+        model?: string;
+    }>;
+    /** Service endpoints (override the built-in defaults). */
+    services?: {
+        authUrl?: string;
+        builderUrl?: string;
+        masarUrl?: string;
+    };
+    /** Where the active config came from. */
+    source: 'local' | 'studio';
+}
+/** A single provider's secret, persisted to `~/.almadar/credentials.json` (chmod 600). */
+export interface ProviderCredential {
+    apiKey: string;
+}
+/** Studio-synced identity overlay, persisted to `~/.almadar/account.json`. Empty until login. */
+export interface AccountIdentity {
+    uid: string;
+    email?: string;
+    tier?: string;
+    teamId?: string | null;
+    syncedAt: string;
+}
+export interface OpenAccountOptions {
+    /** Home directory root. Defaults to `os.homedir()`. */
+    home?: string;
+    /** Storage backend. Defaults to `'local'` (real filesystem). */
+    backend?: 'local' | 'memory';
+}
+/**
+ * Account-level store rooted at `~/.almadar/`. Home-rooted and NOT sandboxed
+ * (unlike {@link WorkspaceService}); owns config + credentials + the Studio
+ * identity overlay. Construct via `openAccount`.
+ */
+export interface AccountService {
+    /** Absolute `~/.almadar` path. */
+    readonly root: string;
+    getConfig(): Promise<AccountConfig>;
+    setConfig(patch: Partial<AccountConfig>): Promise<void>;
+    getCredential(provider: string): Promise<ProviderCredential | null>;
+    setCredential(provider: string, cred: ProviderCredential): Promise<void>;
+    listCredentialedProviders(): Promise<string[]>;
+    readAccount(): Promise<AccountIdentity | null>;
+    writeAccount(identity: AccountIdentity): Promise<void>;
+    /**
+     * Resolve the explicit {@link ProviderConfig} for `provider` (stored apiKey +
+     * config baseUrl/model overrides), ready to pass into `@almadar/llm` / rabit.
+     * Returns null when no credential is stored for `provider`.
+     */
+    resolveProviderConfig(provider: string): Promise<ProviderConfig | null>;
+    /** True once setup completed AND at least one provider has a stored credential. */
+    isConfigured(): Promise<boolean>;
+    dispose(): Promise<void>;
+}

package/package.json

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