@deepseek-ai/dsh-api-workspace-files 0.1.5-alpha.1

package/lib/types/client/change-feed.js

@@ -0,0 +1,296 @@
+/**
+ * The follower key of one absolute path.
+ * @param path - an absolute path from a Host stat or change frame.
+ * @returns the path with `\\` normalized to `/`.
+ */
+function keyOf(path) {
+    return path.replace(/\\/g, '/');
+}
+/** Notices of one follower, delivered in order and pulled by its consumer. */
+class Follower {
+    address;
+    leave;
+    pending = [];
+    started = Promise.withResolvers();
+    wake;
+    ended = false;
+    hostKey;
+    /**
+     * Resolves true after the Host acknowledges its subscription, or false if
+     * this follower ends before acknowledgement.
+     */
+    ready = this.started.promise;
+    /**
+     * @param address - resource address used for reload lookup.
+     * @param leave - unregisters this follower and its abort listener.
+     */
+    constructor(address, leave) {
+        this.address = address;
+        this.leave = leave;
+    }
+    /** The normalized Host path, absent until a successful stat. */
+    get key() {
+        return this.hostKey;
+    }
+    /**
+     * Select the Host path for queued and future changes.
+     * @param absolutePath - the successful stat's absolute path.
+     */
+    bind(absolutePath) {
+        this.hostKey = keyOf(absolutePath);
+    }
+    /** The Host acknowledged an active subscription and resolved workspace root. */
+    start() {
+        this.started.resolve(true);
+    }
+    /**
+     * Queue one notice.
+     * @param notice - what the consumer receives next.
+     * @param key - normalized Host path for a change; absent for a reload.
+     */
+    push(notice, key) {
+        this.pending.push({ key, notice });
+        this.wake?.();
+    }
+    /** Deliver what is queued, then finish. */
+    end() {
+        this.ended = true;
+        this.started.resolve(false);
+        this.wake?.();
+    }
+    /** Unregister even when the consumer has not started pulling notices. */
+    dispose() {
+        this.leave();
+    }
+    /** @inheritdoc */
+    async *[Symbol.asyncIterator]() {
+        try {
+            while (true) {
+                const next = this.pending.shift();
+                if (next !== undefined) {
+                    if (next.key === undefined || this.hostKey === undefined || next.key === this.hostKey)
+                        yield next.notice;
+                    continue;
+                }
+                if (this.ended)
+                    return;
+                await new Promise((resolve) => { this.wake = resolve; });
+                this.wake = undefined;
+            }
+        }
+        finally {
+            this.dispose();
+        }
+    }
+}
+/** The stream and followers of one session. */
+class SessionFeed {
+    onClose;
+    followers = new Set();
+    stream;
+    closed = false;
+    started = false;
+    /**
+     * @param remote - the Remote face carrying `workspaceFiles.changes`.
+     * @param sessionId - the session whose writes this feed follows.
+     * @param after - the previous feed of this session still closing, if any; the stream opens once it has settled.
+     * @param onClose - called once when the stream is gone, whatever the cause, with the dispose that is closing it.
+     */
+    constructor(remote, sessionId, after, onClose) {
+        this.onClose = onClose;
+        this.stream = remote.$stream({
+            name: `workspace file changes of ${sessionId}`,
+            // A predecessor still closing finishes first, so one session never has
+            // two Host streams open at once.
+            open: (signal) => {
+                this.started = false;
+                return openAfter(after, () => remote.workspaceFiles.changes(sessionId, signal));
+            },
+            // A normal end means the Host closed the session's feed: the session is
+            // gone or the Host is shutting down, so there is nothing to reopen.
+            ended: () => new Error(`workspace file changes of ${sessionId} ended`),
+        });
+        void this.pump();
+    }
+    /**
+     * Register one resource address before its Host path is known.
+     * @param follower - receives changes and binds its path after stat.
+     */
+    add(follower) {
+        this.followers.add(follower);
+        if (this.started)
+            follower.start();
+    }
+    /**
+     * Unregister one follower; the last one leaving disposes the stream.
+     * @param follower - the follower to drop.
+     */
+    remove(follower) {
+        this.followers.delete(follower);
+        if (this.followers.size === 0)
+            this.close();
+    }
+    /**
+     * Reload an address and every follower bound to the same Host path.
+     * @param address - the resource address requesting a reload.
+     */
+    requestRestat(address) {
+        const keys = new Set();
+        for (const follower of this.followers) {
+            if (follower.address === address && follower.key !== undefined)
+                keys.add(follower.key);
+        }
+        for (const follower of this.followers) {
+            if (follower.address === address || (follower.key !== undefined && keys.has(follower.key))) {
+                follower.push({ kind: 'restat' });
+            }
+        }
+    }
+    async pump() {
+        try {
+            for await (const item of this.stream) {
+                const frame = item.value;
+                switch (frame.kind) {
+                    case 'ready':
+                        item.accept();
+                        this.started = true;
+                        for (const follower of this.followers)
+                            follower.start();
+                        break;
+                    case 'change': {
+                        const key = keyOf(frame.change.absolutePath);
+                        const notice = editOf(frame.change);
+                        for (const follower of this.followers)
+                            follower.push(notice, key);
+                        break;
+                    }
+                    default:
+                        assertNever(frame);
+                }
+            }
+        }
+        catch {
+            // A terminal stream failure or the Host's end: followers end quietly
+            // below, and the metadata they hold stays the last known.
+        }
+        finally {
+            this.close();
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const closed = this.stream.dispose();
+        for (const follower of this.followers)
+            follower.end();
+        this.followers.clear();
+        this.onClose(closed);
+    }
+}
+/**
+ * Open a Host stream once a predecessor has finished closing.
+ * @param after - the predecessor's dispose, or nothing to wait for.
+ * @param open - opens the stream.
+ * @returns the stream's items.
+ */
+async function* openAfter(after, open) {
+    await after;
+    yield* open();
+}
+/**
+ * The write one Host frame reports.
+ * @param frame - the Host frame.
+ * @returns the edit notice followers receive.
+ */
+function editOf(frame) {
+    return 'absent' in frame ? { kind: 'absent' } : { kind: 'changed', version: frame.version };
+}
+function assertNever(frame) {
+    throw new Error(`Unexpected workspace file watch frame: ${JSON.stringify(frame)}`);
+}
+/**
+ * Per-session fan-out of the Host's workspace file change stream.
+ *
+ * Owned by the provider; one instance serves every session of the Client.
+ */
+export class ChangeFeed {
+    remote;
+    /** Live feeds only: a feed removes itself when its stream closes. */
+    sessions = new Map();
+    /** Streams still closing, by session: the session's next feed opens after its predecessor has settled. */
+    closing = new Map();
+    /**
+     * @param remote - the Remote face carrying `$stream` and `workspaceFiles.changes`.
+     */
+    constructor(remote) {
+        this.remote = remote;
+    }
+    /**
+     * Follow one resource address in one session before its Host path is known.
+     *
+     * The follower is registered on call, not on first pull. Changes delivered
+     * to this Client are queued while stat is pending. The first follower starts
+     * the session's local `changes` call. The iterable ends
+     * when `signal` aborts or when the session stream is gone; ending it early
+     * (`break`, `return`) unregisters the follower as well, and the last follower
+     * of a session disposes its stream. Await a true `ready` result before stat
+     * so the Host subscription is active, then bind each stat's absolute path. Until binding,
+     * any session write can trigger a retry; after binding, only matching queued
+     * and live changes pass.
+     * @param sessionId - the session whose workspace holds the file.
+     * @param address - the resource address, used only for reload lookup.
+     * @param signal - ends the follow.
+     * @returns a single-consumer subscription with Host-path binding and explicit disposal.
+     */
+    follow(sessionId, address, signal) {
+        const feed = signal.aborted ? undefined : this.feedOf(sessionId);
+        const leave = () => {
+            signal.removeEventListener('abort', leave);
+            follower.end();
+            feed?.remove(follower);
+        };
+        const follower = new Follower(address, leave);
+        if (feed === undefined) {
+            follower.end();
+        }
+        else {
+            feed.add(follower);
+            signal.addEventListener('abort', leave, { once: true });
+        }
+        return follower;
+    }
+    /**
+     * Ask an address and its same-session Host-path peers to `stat` again.
+     * @param sessionId - the session whose workspace holds the file.
+     * @param address - the resource address requesting a reload.
+     */
+    requestRestat(sessionId, address) {
+        this.sessions.get(sessionId)?.requestRestat(address);
+    }
+    /**
+     * Wait for every stream that is still closing, so an owner tearing down
+     * leaves no Host stream behind.
+     * @returns resolves once no stream of this feed is closing.
+     */
+    async settle() {
+        await Promise.all(this.closing.values());
+    }
+    feedOf(sessionId) {
+        const existing = this.sessions.get(sessionId);
+        if (existing !== undefined)
+            return existing;
+        const feed = new SessionFeed(this.remote, sessionId, this.closing.get(sessionId), (closed) => {
+            this.sessions.delete(sessionId);
+            // A dispose that rejects is still a settled close: nothing remains to wait for.
+            const tracked = closed.then(() => undefined, () => undefined).then(() => {
+                if (this.closing.get(sessionId) === tracked)
+                    this.closing.delete(sessionId);
+            });
+            this.closing.set(sessionId, tracked);
+        });
+        this.sessions.set(sessionId, feed);
+        return feed;
+    }
+}
+//# sourceMappingURL=change-feed.js.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser half: the `file` resource provider over `remote.workspaceFiles`.
+ *
+ * `types.ts` is what the protocol publishes, `change-feed.ts` shares one Host
+ * `changes` stream per session, `provider.ts` turns it and `stat` into a value
+ * stream, and this module only wires them into `ctx.resources`.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+export type { SessionLookup } from './provider.ts';
+export type { WorkspaceFileParams, WorkspaceFileResource } from './types.ts';
+/** Required browser services: the resource model, the Remote carrier and its namespace, and the Session list. */
+export declare const inject: string[];
+/**
+ * Client plugin body: register the `file` provider for this plugin's lifetime.
+ * @param ctx - client root context carrying `resources`, the Remote face, and `sessions`.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.js

@@ -0,0 +1,26 @@
+import { ChangeFeed } from "./change-feed.js";
+import { createFileResourceProvider } from "./provider.js";
+/** Required browser services: the resource model, the Remote carrier and its namespace, and the Session list. */
+export const inject = ['resources', 'remote', 'remote.workspaceFiles', 'sessions'];
+/**
+ * Client plugin body: register the `file` provider for this plugin's lifetime.
+ * @param ctx - client root context carrying `resources`, the Remote face, and `sessions`.
+ */
+export function apply(ctx) {
+    // The current Session changes with navigation; absolute addresses read it on demand.
+    const sessions = {
+        current: () => ctx.sessions.list.getSnapshot().current,
+    };
+    const changes = new ChangeFeed(ctx.remote);
+    const provider = createFileResourceProvider(ctx.remote, changes, sessions);
+    ctx.effect(() => {
+        const release = ctx.resources.register(provider);
+        // Teardown waits for every session stream still closing, so the plugin
+        // leaves no Host stream behind.
+        return async () => {
+            release();
+            await changes.settle();
+        };
+    }, 'workspace-files: file resource provider');
+}
+//# sourceMappingURL=index.js.map

package/lib/types/client/provider.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The `file` protocol's provider: a workspace file's metadata as a stream of
+ * `RemoteResult` frames.
+ *
+ * An address names the file in one of two scopes. A `session` address,
+ * `dsh-resource://file/session/<sessionId>/<path>`, carries a path relative to
+ * that Session's workspace root: the Host receives the relative path as-is and
+ * resolves it against the root it holds. Only the Host's `stat.absolutePath`
+ * selects the change-feed key; no Client Session summary is needed.
+ * An `absolute` address, `dsh-resource://file/absolute/<path>`, carries no
+ * Session and is read through the Session on screen. An address neither scope
+ * resolves yields one failure frame — `workspace-file/unsupported-address` for
+ * a string outside the grammar, `workspace-file/unknown-workspace` when the
+ * absolute address has no current Session — and ends.
+ *
+ * The first frame is the file's `stat`; every Host-reported write yields the
+ * metadata flagged `changed`; a reported disappearance, or a write while the
+ * last stat had failed, runs `stat` again and flags what it finds; a reload
+ * runs `stat` again and clears the flag. Failures travel as `ok: false` frames, never as thrown errors: the
+ * Remote face does not reject, and anything thrown inside the stream is a
+ * programming error the resource model lets surface. A failed stat does not end
+ * the stream: the next write or reload stats again. One {@link ChangeFeed}
+ * serves every open file of the Client.
+ */
+import type { ResourceProvider } from '@deepseek-ai/dsh-client-resources/client';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { ChangeFeed } from './change-feed.ts';
+import type { WorkspaceFilesRemote } from './remote.ts';
+/** The current Session used to authorize an absolute address. */
+export interface SessionLookup {
+    /**
+     * The Session on screen, which an `absolute` address is read through.
+     * @returns its id, or `undefined` while no Session is current.
+     */
+    current(): SessionId | undefined;
+}
+/**
+ * Build the `file` provider over one Remote face, one change feed, and the Client's Session list.
+ * @param remote - the Remote face carrying `workspaceFiles.stat`.
+ * @param changes - the per-session change fan-out.
+ * @param sessions - the current Session, read for absolute addresses on every open and reload.
+ * @returns the provider to register into `ctx.resources`.
+ */
+export declare function createFileResourceProvider(remote: WorkspaceFilesRemote, changes: ChangeFeed, sessions: SessionLookup): ResourceProvider<'file'>;
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/client/provider.js

@@ -0,0 +1,129 @@
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path';
+/**
+ * Build the `file` provider over one Remote face, one change feed, and the Client's Session list.
+ * @param remote - the Remote face carrying `workspaceFiles.stat`.
+ * @param changes - the per-session change fan-out.
+ * @param sessions - the current Session, read for absolute addresses on every open and reload.
+ * @returns the provider to register into `ctx.resources`.
+ */
+export function createFileResourceProvider(remote, changes, sessions) {
+    return {
+        protocol: 'file',
+        async *open(address, { signal }) {
+            const resolved = resolve(address, sessions);
+            if (!resolved.ok) {
+                yield resolved;
+                return;
+            }
+            const { sessionId, path } = resolved.value;
+            // Queue changes delivered to this Client while stat is pending.
+            const notices = changes.follow(sessionId, address, signal);
+            const stat = () => remote.workspaceFiles.stat(sessionId, path, signal);
+            // Read through a call: a plain `signal.aborted` is narrowed to `false` by
+            // the first check and would read as always-false after the later awaits.
+            const aborted = () => signal.aborted;
+            // Undefined while the last stat failed: the follow is on the address, not
+            // on the file, so a write or a reload can still bring the file live.
+            let current;
+            try {
+                if (!await notices.ready || aborted())
+                    return;
+                const first = await stat();
+                if (aborted())
+                    return;
+                if (first.ok) {
+                    notices.bind(first.value.absolutePath);
+                    current = metadataOf(first.value, false);
+                    yield { ok: true, value: current };
+                }
+                else {
+                    yield first;
+                }
+                for await (const notice of notices) {
+                    if (current === undefined) {
+                        // Still gone: nothing new to report.
+                        if (notice.kind === 'absent')
+                            continue;
+                    }
+                    else if (notice.kind === 'changed') {
+                        // Frames report observations: holding this version already means the
+                        // consumer learns nothing new.
+                        if (notice.version === current.version)
+                            continue;
+                        current = { ...current, version: notice.version, changed: true };
+                        yield { ok: true, value: current };
+                        continue;
+                    }
+                    // A Host notice may mean stale content; only a reload clears the flag.
+                    const again = await stat();
+                    if (aborted())
+                        return;
+                    if (!again.ok) {
+                        current = undefined;
+                        yield again;
+                        continue;
+                    }
+                    notices.bind(again.value.absolutePath);
+                    current = metadataOf(again.value, notice.kind !== 'restat');
+                    yield { ok: true, value: current };
+                }
+            }
+            finally {
+                notices.dispose();
+            }
+        },
+        reload(address) {
+            const resolved = resolve(address, sessions);
+            if (resolved.ok)
+                changes.requestRestat(resolved.value.sessionId, address);
+        },
+    };
+}
+/**
+ * Resolve one address to the Host call it stands for, or to the failure frame it earns.
+ * @param address - the full address, scheme included.
+ * @param sessions - the Client's Session list.
+ * @returns the Host file, or the `unsupported-address` / `unknown-workspace` failure.
+ */
+function resolve(address, sessions) {
+    const parsed = parseFileAddress(address);
+    if (parsed === undefined)
+        return { ok: false, error: unsupportedAddress(address) };
+    if (parsed.scope === 'session') {
+        // The address is a string boundary: its id segment is the Session id it names.
+        const sessionId = parsed.sessionId;
+        return { ok: true, value: { sessionId, path: parsed.path } };
+    }
+    const sessionId = sessions.current();
+    if (sessionId === undefined)
+        return { ok: false, error: unknownWorkspace(address) };
+    return { ok: true, value: { sessionId, path: parsed.path } };
+}
+/**
+ * The failure frame's error for an address this provider does not serve.
+ * @param address - the offending address.
+ * @returns the typed error.
+ */
+function unsupportedAddress(address) {
+    return new RemoteError('workspace-file/unsupported-address', `${address} is not a dsh-resource://file/session/<sessionId>/<path> or dsh-resource://file/absolute/<path> address`, { address });
+}
+/**
+ * The failure frame's error for an absolute address with no current Session.
+ * @param address - the offending address.
+ * @returns the typed error.
+ */
+function unknownWorkspace(address) {
+    return new RemoteError('workspace-file/unknown-workspace', `${address} requires a current Session`, { address });
+}
+/**
+ * The resource value one `stat` result amounts to.
+ * @param stat - what the Host reported.
+ * @param changed - whether the consumer's content may be stale: `true` after a
+ *   Host notice prompted the stat, `false` for the opening stat and a reload's.
+ * @returns the metadata frame value.
+ */
+function metadataOf(stat, changed) {
+    return { absolutePath: stat.absolutePath, version: stat.version, changed, ...(stat.bytes === undefined ? {} : { bytes: stat.bytes }) };
+}
+//# sourceMappingURL=provider.js.map

package/lib/types/client/remote.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The slice of the Client Remote this package calls: the generated
+ * `workspaceFiles` methods by name, and the stream supervisor structurally, so
+ * the feed and the provider are testable against a scripted face.
+ */
+import type { ClientRemote } from '@deepseek-ai/dsh-api-gateway/client';
+/** One item of a supervised stream; `accept` marks the delivering generation as healthy. */
+export interface SupervisedStreamItem<Item> {
+    /** The decoded frame. */
+    readonly value: Item;
+    /** Reset the reconnect backoff: this generation is delivering. */
+    accept(): void;
+}
+/** A reconnecting single-consumer stream the Remote supervises. */
+export interface SupervisedStream<Item> extends AsyncIterable<SupervisedStreamItem<Item>> {
+    /**
+     * Stop the stream for good.
+     * @returns once the active generation and the consumer iterator are closed.
+     */
+    dispose(): Promise<void>;
+}
+/** What one supervised stream needs from its owner. */
+export interface SupervisedStreamOptions<Item> {
+    /** Diagnostic owner name. */
+    readonly name: string;
+    /** Open one physical generation; `signal` aborts it. */
+    readonly open: (signal: AbortSignal) => AsyncIterable<Item>;
+    /** The error a generation's normal end amounts to; a carrier error asks for a reopen, anything else is terminal. */
+    readonly ended: (accepted: boolean) => Error;
+}
+/** The `workspaceFiles` namespace methods this package calls, as the generated Remote declares them. */
+export type WorkspaceFilesNamespace = Pick<ClientRemote['workspaceFiles'], 'stat' | 'changes'>;
+/** The Client Remote as this package sees it. */
+export interface WorkspaceFilesRemote {
+    /**
+     * Create one reconnecting stream.
+     * @param options - opener and end classification.
+     * @returns the supervised stream, unstarted until iterated.
+     */
+    $stream<Item>(options: SupervisedStreamOptions<Item>): SupervisedStream<Item>;
+    /** The `workspaceFiles` namespace. */
+    readonly workspaceFiles: WorkspaceFilesNamespace;
+}
+//# sourceMappingURL=remote.d.ts.map

package/lib/types/client/remote.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=remote.js.map

package/lib/types/client/types.d.ts

@@ -0,0 +1,65 @@
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface ResourceProtocolMap {
+        /**
+         * One workspace file's metadata, addressed as
+         * `dsh-resource://file/session/<sessionId>/<workspace-relative path>` or
+         * `dsh-resource://file/absolute/<absolute path>`.
+         */
+        file: WorkspaceFileResource;
+    }
+}
+/** What a `file` tab is asked to reveal on open or navigation; JSON-shaped. */
+export interface WorkspaceFileParams {
+    /** 1-based line to scroll into view; absent leaves the position alone. */
+    readonly line?: number;
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /**
+         * The address is not a `dsh-resource://file/` address in a scope the
+         * provider serves: `session/<sessionId>/<workspace-relative path>` or
+         * `absolute/<absolute path>`. Raised by the Client provider; the Host never
+         * emits it.
+         */
+        'workspace-file/unsupported-address': {
+            readonly address: string;
+        };
+        /**
+         * An `absolute` address has no current Session to authorize its Host call.
+         * Raised by the Client provider; the Host never emits it. Session addresses
+         * are resolved by the Host without a Client Session summary.
+         */
+        'workspace-file/unknown-workspace': {
+            readonly address: string;
+        };
+    }
+}
+/**
+ * One workspace file as the resource model carries it: metadata only.
+ *
+ * The stream reports that the file moved on; it never carries content. A
+ * consumer reads the text itself, by page, and uses `version` and `changed` to
+ * know when its pages are stale.
+ */
+export interface WorkspaceFileResource {
+    /** Absolute path in the Host filesystem, as returned by the last successful stat. */
+    readonly absolutePath: string;
+    /** The Host's latest report of the file's version: from `stat` first, then from each reported write. */
+    readonly version: string;
+    /** Byte size as of the last `stat`, when the backend reports it. */
+    readonly bytes?: number;
+    /** The Host reported a write after the last `stat`; a reload (`stat` again) clears it. */
+    readonly changed: boolean;
+}
+/** One Host-reported write inside the session's workspace. */
+export type WorkspaceFileEdit = {
+    readonly kind: 'changed';
+    readonly version: string;
+} | {
+    readonly kind: 'absent';
+};
+/** What one follower of a path receives: a Host write, or a local request to `stat` again. */
+export type WorkspaceFileNotice = WorkspaceFileEdit | {
+    readonly kind: 'restat';
+};
+//# sourceMappingURL=types.d.ts.map

package/lib/types/client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map