@itookit/dsht 0.2.4 → 0.3.2

package/dist/session/types.d.ts

@@ -0,0 +1,18 @@
+/** Session-domain result types shared by the controller facade and the terminal UI. */
+/** Resolved navigation-removal identity; empty marks a fresh blank, idle session eligible for immediate archival. */
+export interface RemovalTarget {
+    kind: 'workspace' | 'session';
+    id: string;
+    name: string;
+    path?: string;
+    empty?: boolean;
+}
+/** Bounded search results contain navigation summaries, never complete message bodies. */
+export interface HistorySearch {
+    items: {
+        seq: number;
+        role: string;
+        preview: string;
+    }[];
+    truncated: boolean;
+}

package/dist/session/types.js

@@ -0,0 +1,2 @@
+/** Session-domain result types shared by the controller facade and the terminal UI. */
+export {};

package/dist/state.d.ts

@@ -0,0 +1,41 @@
+/** Application state shared by the controller facade and every domain controller. */
+import { Transcript } from './session/transcript.ts';
+import type { HistorySearch, RemovalTarget } from './session/types.ts';
+import type { ObjectValue } from './transport/wire.ts';
+/** State shared by the picker and conversation view. */
+export interface State {
+    version: number;
+    online: boolean;
+    busy: boolean;
+    screen: 'workspaces' | 'sessions' | 'chat' | 'path';
+    status: string;
+    error: string;
+    workspaces: ObjectValue[];
+    sessions: ObjectValue[];
+    showAllSessions: boolean;
+    workspaceId?: string;
+    sessionId?: string;
+    pending: ObjectValue[];
+    controlError?: string;
+    modelError?: string;
+    presetError?: string;
+    presets?: ObjectValue[];
+    defaultModel?: ObjectValue;
+    transcript: Transcript;
+}
+/** The state contract every domain controller writes through. */
+export interface ControllerStore {
+    /** Current immutable state snapshot. */
+    readonly state: State;
+    /** Publish a state patch and notify observers. */
+    update(patch: Partial<State>): void;
+    /** Monotonic selector generation; a changed value discards in-flight session work. */
+    selection(): number;
+    /** Advance the selector generation when the selected workspace or session changes. */
+    bumpSelection(): void;
+}
+/** Build the initial state before any connection exists.
+ * @returns A fresh state whose transcript is empty and disconnected.
+ */
+export declare function initialState(): State;
+export type { HistorySearch, RemovalTarget };

package/dist/state.js

@@ -0,0 +1,9 @@
+/** Application state shared by the controller facade and every domain controller. */
+import { Transcript } from "./session/transcript.js";
+/** Build the initial state before any connection exists.
+ * @returns A fresh state whose transcript is empty and disconnected.
+ */
+export function initialState() {
+    return { version: 0, online: false, busy: false, screen: 'workspaces', status: 'Connecting…',
+        error: '', workspaces: [], sessions: [], showAllSessions: false, pending: [], transcript: new Transcript() };
+}

package/dist/storage/directories.d.ts

@@ -0,0 +1,14 @@
+/** Create a directory tree with owner-only permissions, leaving an existing directory as it is.
+ * @param path - Directory path.
+ */
+export declare function ensureDirectory(path: string): Promise<void>;
+/** Create a directory tree and require it to stay owner-only.
+ * @param path - Directory path.
+ * @param label - Name used in the validation error, such as `Cookie directory`.
+ */
+export declare function ensurePrivateDirectory(path: string, label: string): Promise<void>;
+/** List the entry names of one directory.
+ * @param path - Directory path.
+ * @returns Entry names in filesystem order.
+ */
+export declare function listEntries(path: string): Promise<string[]>;

package/dist/storage/directories.js

@@ -0,0 +1,24 @@
+/** Private directory creation and listing for the client's configuration and state. */
+import { lstat, mkdir, readdir } from 'node:fs/promises';
+/** Create a directory tree with owner-only permissions, leaving an existing directory as it is.
+ * @param path - Directory path.
+ */
+export async function ensureDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+}
+/** Create a directory tree and require it to stay owner-only.
+ * @param path - Directory path.
+ * @param label - Name used in the validation error, such as `Cookie directory`.
+ */
+export async function ensurePrivateDirectory(path, label) {
+    await ensureDirectory(path);
+    const stat = await lstat(path);
+    if (!stat.isDirectory() || process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
+        throw new Error(`${label} must be owned by the current user with permissions 0700`);
+    }
+}
+/** List the entry names of one directory.
+ * @param path - Directory path.
+ * @returns Entry names in filesystem order.
+ */
+export async function listEntries(path) { return readdir(path); }

package/dist/storage/files.d.ts

@@ -0,0 +1,43 @@
+/** Read a UTF-8 file; an absent file is an ordinary result, not a failure.
+ * @param path - Absolute file path.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export declare function readText(path: string): Promise<string | undefined>;
+/** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
+ * @param path - Absolute file path.
+ * @param label - Name used in the validation error, such as `Cookie file`.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export declare function readPrivateFile(path: string, label: string): Promise<string | undefined>;
+/** Replace a file atomically with owner-only contents, leaving no partial file behind.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ */
+export declare function writePrivateFile(path: string, contents: string): Promise<void>;
+/** Create an owner-only file only when it does not exist.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ * @returns False when the file already existed, leaving it untouched.
+ */
+export declare function createPrivateFile(path: string, contents: string): Promise<boolean>;
+/** Stream bytes into a new owner-only file, removing it unless the write completed.
+ *
+ * The destination is created before the source is requested, so an existing file fails without
+ * contacting the host, and a source or streaming failure removes the partial file.
+ * @param path - Destination path; an existing file is never replaced.
+ * @param source - Produces the byte stream once the destination exists.
+ * @param signal - Cancels the write and removes the partial file.
+ */
+export declare function writeExclusiveStream(path: string, source: () => Promise<AsyncIterable<Uint8Array>>, signal?: AbortSignal): Promise<void>;
+/** Append to an owner-only file, creating it when absent.
+ *
+ * Appending keeps a long-lived diagnostic file cheap to extend; callers that need a bounded file
+ * rewrite it periodically with `writePrivateFile`.
+ * @param path - Destination path.
+ * @param contents - Text to append.
+ */
+export declare function appendPrivateFile(path: string, contents: string): Promise<void>;
+/** Remove a file, treating an already absent file as success.
+ * @param path - File to remove.
+ */
+export declare function removeFile(path: string): Promise<void>;

package/dist/storage/files.js

@@ -0,0 +1,135 @@
+/** Every filesystem read and write the client performs; no other module opens a file. */
+import { constants } from 'node:fs';
+import { open, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+/** Read a UTF-8 file; an absent file is an ordinary result, not a failure.
+ * @param path - Absolute file path.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export async function readText(path) {
+    try {
+        return await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+}
+/** Read a user-private file, rejecting a symlink, a foreign owner, or group/other access.
+ * @param path - Absolute file path.
+ * @param label - Name used in the validation error, such as `Cookie file`.
+ * @returns File contents, or undefined when the file does not exist.
+ */
+export async function readPrivateFile(path, label) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return undefined;
+        throw error;
+    }
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.())) {
+            throw new Error(`${label} must be owned by the current user with permissions 0600`);
+        }
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Replace a file atomically with owner-only contents, leaving no partial file behind.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ */
+export async function writePrivateFile(path, contents) {
+    const temporary = join(dirname(path), `${randomUUID()}.tmp`);
+    try {
+        await writeFile(temporary, contents, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, path);
+    }
+    finally {
+        await removeFile(temporary);
+    }
+}
+/** Create an owner-only file only when it does not exist.
+ * @param path - Destination path.
+ * @param contents - Complete file contents.
+ * @returns False when the file already existed, leaving it untouched.
+ */
+export async function createPrivateFile(path, contents) {
+    try {
+        await writeFile(path, contents, { mode: 0o600, flag: 'wx' });
+        return true;
+    }
+    catch (error) {
+        if (isCode(error, 'EEXIST'))
+            return false;
+        throw error;
+    }
+}
+/** Stream bytes into a new owner-only file, removing it unless the write completed.
+ *
+ * The destination is created before the source is requested, so an existing file fails without
+ * contacting the host, and a source or streaming failure removes the partial file.
+ * @param path - Destination path; an existing file is never replaced.
+ * @param source - Produces the byte stream once the destination exists.
+ * @param signal - Cancels the write and removes the partial file.
+ */
+export async function writeExclusiveStream(path, source, signal) {
+    const file = await open(path, 'wx', 0o600);
+    let complete = false;
+    try {
+        await file.writeFile(await source(), { signal });
+        signal?.throwIfAborted();
+        complete = true;
+    }
+    finally {
+        try {
+            await file.close();
+        }
+        finally {
+            if (!complete)
+                await removeFile(path);
+        }
+    }
+}
+/** Append to an owner-only file, creating it when absent.
+ *
+ * Appending keeps a long-lived diagnostic file cheap to extend; callers that need a bounded file
+ * rewrite it periodically with `writePrivateFile`.
+ * @param path - Destination path.
+ * @param contents - Text to append.
+ */
+export async function appendPrivateFile(path, contents) {
+    const handle = await open(path, 'a', 0o600);
+    try {
+        await handle.writeFile(contents);
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Remove a file, treating an already absent file as success.
+ * @param path - File to remove.
+ */
+export async function removeFile(path) {
+    try {
+        await unlink(path);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+}
+/** Recognize one error code without assuming the error's prototype. */
+function isCode(error, code) {
+    return error instanceof Error && 'code' in error && error.code === code;
+}
+/** Whether an operation failed because the path does not exist. */
+function isMissing(error) { return isCode(error, 'ENOENT'); }

package/dist/storage/index.d.ts

@@ -0,0 +1,3 @@
+/** Storage domain: every filesystem operation the client performs. */
+export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, writeExclusiveStream, writePrivateFile } from './files.ts';
+export { ensureDirectory, ensurePrivateDirectory, listEntries } from './directories.ts';

package/dist/storage/index.js

@@ -0,0 +1,3 @@
+/** Storage domain: every filesystem operation the client performs. */
+export { appendPrivateFile, createPrivateFile, readPrivateFile, readText, removeFile, writeExclusiveStream, writePrivateFile } from "./files.js";
+export { ensureDirectory, ensurePrivateDirectory, listEntries } from "./directories.js";

package/dist/transport/auth.js

@@ -0,0 +1,65 @@
+/** Origin-scoped cookie persistence; launch tokens are never written to disk. */
+import { createHash } from 'node:crypto';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ensurePrivateDirectory, readPrivateFile, writePrivateFile } from "../storage/index.js";
+import { HttpError } from "./client.js";
+/** Fatal authentication failure requiring a new startup token. */
+export class AuthenticationRequired extends Error {
+}
+/** Private, atomic cookie files, separated by the complete HTTP origin. */
+export class CookieStore {
+    directory;
+    constructor(directory = process.env.DSHT_AUTH_DIR
+        ?? join(process.env.XDG_STATE_HOME ?? join(homedir(), '.local', 'state'), 'dsht', 'auth')) {
+        this.directory = directory;
+    }
+    /** Read an unexpired cookie, rejecting unsafe permissions or malformed storage. */
+    async load(origin) {
+        const raw = await readPrivateFile(this.path(origin), 'Cookie file');
+        if (raw === undefined)
+            return undefined;
+        let saved;
+        try {
+            saved = JSON.parse(raw);
+        }
+        catch {
+            throw new Error('Invalid cookie file JSON. Remove the origin cookie file and log in again.');
+        }
+        if (saved === null || typeof saved !== 'object' || !('version' in saved) || saved.version !== 1
+            || !('origin' in saved) || saved.origin !== origin || !('cookie' in saved) || typeof saved.cookie !== 'string'
+            || !('expiresAt' in saved) || typeof saved.expiresAt !== 'number' || !Number.isSafeInteger(saved.expiresAt)) {
+            throw new Error('Invalid saved cookie. Remove the origin cookie file and log in again.');
+        }
+        return saved.expiresAt > Date.now() ? saved.cookie : undefined;
+    }
+    /** Atomically save a persistent host cookie with owner-only POSIX permissions. */
+    async save(origin, cookie, expiresAt) {
+        await ensurePrivateDirectory(this.directory, 'Cookie directory');
+        await writePrivateFile(this.path(origin), JSON.stringify({ version: 1, origin, cookie, expiresAt }) + '\n');
+    }
+    path(origin) {
+        return join(this.directory, `${createHash('sha256').update(origin).digest('hex')}.json`);
+    }
+}
+/** Reuse a validated cookie first; only authentication rejection permits token fallback. */
+export async function login(client, token, store) {
+    const cookie = await store.load(client.base.origin);
+    if (cookie) {
+        client.restoreCookie(cookie);
+        try {
+            await client.call('session/list', { _request: {} });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof HttpError) || error.status !== 401)
+                throw error;
+        }
+    }
+    if (!token)
+        throw new AuthenticationRequired('Login required: export DSH_TOKEN, or export DSH_URL as the URL printed by dsh web');
+    await client.authenticate(token);
+    const session = client.persistentCookie;
+    if (session)
+        await store.save(client.base.origin, session.cookie, session.expiresAt);
+}

package/dist/{client.d.ts → transport/client.d.ts}

@@ -37,13 +37,20 @@ export declare class Client {
         cookie: string;
         expiresAt: number;
     } | undefined;
+    /** Download the authenticated host ZIP without using a mutation or ordinary RPC deadline.
+     * @param sessionId - Selected session identity.
+     * @param signal - Cancels the streaming response.
+     * @returns Response whose body the caller must consume or cancel.
+     */
+    sessionLog(sessionId: string, signal: AbortSignal): Promise<Response>;
     /** Invoke an exact endpoint once. Mutations are never automatically retried.
      * @param endpoint - Namespace/method endpoint.
      * @param args - Host parameter names and JSON values.
      * @param signal - Optional caller cancellation, combined with client close and timeout.
+     * @param timeoutMs - Per-call timeout; null waits for caller cancellation or client close.
      * @returns The decoded result value; HTTP, remote, and cancellation errors reject.
      */
-    call(endpoint: string, args?: ObjectValue, signal?: AbortSignal): Promise<Json | undefined>;
+    call(endpoint: string, args?: ObjectValue, signal?: AbortSignal, timeoutMs?: number | null): Promise<Json | undefined>;
     /** Connect the physical mux. A disconnected instance may reconnect with its cookie. */
     connect(): Promise<void>;
     /** Subscribe on the existing mux; each subscription has a fresh stream identity. */

package/dist/{client.js → transport/client.js}

@@ -69,18 +69,35 @@ export class Client {
     get persistentCookie() {
         return this.expiresAt === undefined ? undefined : { cookie: this.cookie, expiresAt: this.expiresAt };
     }
+    /** Download the authenticated host ZIP without using a mutation or ordinary RPC deadline.
+     * @param sessionId - Selected session identity.
+     * @param signal - Cancels the streaming response.
+     * @returns Response whose body the caller must consume or cancel.
+     */
+    async sessionLog(sessionId, signal) {
+        const url = new URL('/api/session.export', this.base);
+        url.searchParams.set('sessionId', sessionId);
+        const response = await fetch(url, { redirect: 'error', headers: { cookie: this.cookie },
+            signal: AbortSignal.any([this.lifetime.signal, signal]) });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new HttpError(response.status, 'Session log export');
+        }
+        return response;
+    }
     /** Invoke an exact endpoint once. Mutations are never automatically retried.
      * @param endpoint - Namespace/method endpoint.
      * @param args - Host parameter names and JSON values.
      * @param signal - Optional caller cancellation, combined with client close and timeout.
+     * @param timeoutMs - Per-call timeout; null waits for caller cancellation or client close.
      * @returns The decoded result value; HTTP, remote, and cancellation errors reject.
      */
-    async call(endpoint, args = {}, signal) {
+    async call(endpoint, args = {}, signal, timeoutMs = this.timeoutMs) {
         if (!/^[\w$-]+\/[\w$-]+$/.test(endpoint))
             throw new Error('Invalid RPC endpoint');
         const rpcId = randomUUID();
         const response = await fetch(new URL(`/api/${endpoint}`, this.base), {
-            method: 'POST', redirect: 'error', signal: signal ? AbortSignal.any([this.signal(), signal]) : this.signal(),
+            method: 'POST', redirect: 'error', signal: signal ? AbortSignal.any([this.signal(timeoutMs), signal]) : this.signal(timeoutMs),
             headers: { 'content-type': 'application/json', cookie: this.cookie },
             body: JSON.stringify({ type: 'client-request', rpcId, method: endpoint, payload: { args } }),
         });
@@ -215,8 +232,8 @@ export class Client {
             await closed;
         }
     }
-    signal() {
-        return AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(this.timeoutMs)]);
+    signal(timeoutMs = this.timeoutMs) {
+        return timeoutMs === null ? this.lifetime.signal : AbortSignal.any([this.lifetime.signal, AbortSignal.timeout(timeoutMs)]);
     }
     fail(error) {
         const listeners = [...this.listeners.values()];

package/dist/transport/host.d.ts

@@ -0,0 +1,13 @@
+/** Host access contract every domain controller uses for the active connection generation. */
+import type { Client } from './client.ts';
+/** One authenticated host connection, as seen by a domain that never owns it. */
+export interface HostAccess {
+    /** Connected client, or undefined while offline or between generations. */
+    client(): Client | undefined;
+    /** Connected client, or a `Not connected` failure. */
+    require(): Client;
+    /** Whether the current generation has applied its host baseline. */
+    online(): boolean;
+    /** Client lifetime signal, aborted when the process closes the connection. */
+    signal(): AbortSignal;
+}

package/dist/transport/host.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/app.d.ts

@@ -0,0 +1,11 @@
+import { type Theme } from './theme/index.ts';
+import { Controller } from '../controller/controller.ts';
+/** The caller owns starting and stopping the controller around the Ink render lifetime.
+ * @param props - Controller, panel lifetime and semantic theme.
+ * @returns The rendered terminal interface.
+ */
+export declare function App({ controller, panelLifetimeMs, theme }: {
+    controller: Controller;
+    panelLifetimeMs?: number;
+    theme?: Theme;
+}): import("react").JSX.Element;