@zleap-ai/dsh-sag 0.1.0

package/lib/config.js

@@ -0,0 +1,120 @@
+import z from '@deepseek-ai/schemastery';
+import { sagNamespaceId } from './brand.js';
+const DEFAULT_DISCOVERY_URLS = ['http://127.0.0.1:8000', 'http://localhost:8000'];
+const DEFAULT_MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+const localConfigSchema = z.object({
+    mode: z.const('local').default('local'),
+    discoveryUrls: z.array(z.string()).default(null),
+    requestTimeoutMs: z.number().default(30_000),
+    maxUploadBytes: z.number().default(DEFAULT_MAX_UPLOAD_BYTES),
+    maxReadChars: z.number().default(40_000),
+    connectionCacheTtlMs: z.number().default(5_000),
+});
+const embeddedConfigSchema = z.object({
+    mode: z.const('embedded').required(),
+    pythonCommand: z.string().required(),
+    envFile: z.string().required(),
+    cwd: z.string(),
+    namespaces: z.array(z.object({ id: z.string().required(), label: z.string().required() })).required(),
+    defaultMode: z.union(['fast', 'precise']).default('fast'),
+    maxResults: z.number().default(20),
+    maxSnippetChars: z.number().default(1200),
+    maxReadChars: z.number().default(40_000),
+    maxReadEngines: z.number().default(4),
+    requestTimeoutMs: z.number().default(30_000),
+    shutdownGraceMs: z.number().default(5_000),
+    allowDegraded: z.boolean().default(false),
+});
+export const Config = z.union([localConfigSchema, embeddedConfigSchema]);
+function integer(name, value, maximum) {
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new Error(`dsh-sag: ${name} must be an integer from 1 to ${maximum}`);
+    }
+    return value;
+}
+function nonEmpty(name, value) {
+    if (typeof value !== 'string')
+        throw new Error(`dsh-sag: ${name} must not be empty`);
+    const normalized = value.trim();
+    if (!normalized)
+        throw new Error(`dsh-sag: ${name} must not be empty`);
+    return normalized;
+}
+function normalizeHttpUrl(name, value) {
+    const normalized = nonEmpty(name, value);
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw new Error(`dsh-sag: ${name} must be an http or https URL`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`dsh-sag: ${name} must be an http or https URL`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error(`dsh-sag: ${name} must not contain a username or password`);
+    }
+    return parsed.toString().replace(/\/$/, '');
+}
+function resolveLocalConfig(config) {
+    const discoveryUrls = config.discoveryUrls ?? DEFAULT_DISCOVERY_URLS;
+    if (!Array.isArray(discoveryUrls) || discoveryUrls.length === 0) {
+        throw new Error('dsh-sag: discoveryUrls must contain at least one URL');
+    }
+    return {
+        mode: 'local',
+        discoveryUrls: discoveryUrls.map((url, index) => normalizeHttpUrl(`discoveryUrls[${index}]`, url)),
+        requestTimeoutMs: integer('requestTimeoutMs', config.requestTimeoutMs ?? 30_000, 2_147_483_647),
+        maxUploadBytes: integer('maxUploadBytes', config.maxUploadBytes ?? DEFAULT_MAX_UPLOAD_BYTES, 2_147_483_647),
+        maxReadChars: integer('maxReadChars', config.maxReadChars ?? 40_000, 200_000),
+        connectionCacheTtlMs: integer('connectionCacheTtlMs', config.connectionCacheTtlMs ?? 5_000, 2_147_483_647),
+    };
+}
+function resolveEmbeddedConfig(config) {
+    const pythonCommand = nonEmpty('pythonCommand', config.pythonCommand);
+    const envFile = nonEmpty('envFile', config.envFile);
+    if (!Array.isArray(config.namespaces) || config.namespaces.length === 0) {
+        throw new Error('dsh-sag: at least one namespace is required');
+    }
+    const seen = new Set();
+    const namespaces = config.namespaces.map((namespace) => {
+        let id;
+        try {
+            id = sagNamespaceId(namespace.id.trim());
+        }
+        catch {
+            throw new Error('dsh-sag: namespace id must be 1-36 URL-safe characters');
+        }
+        if (seen.has(id))
+            throw new Error(`dsh-sag: duplicate namespace ${JSON.stringify(id)}`);
+        seen.add(id);
+        return { id, label: nonEmpty('namespace label', namespace.label) };
+    });
+    const defaultMode = config.defaultMode ?? 'fast';
+    if (defaultMode !== 'fast' && defaultMode !== 'precise') {
+        throw new Error('dsh-sag: defaultMode must be fast or precise');
+    }
+    return {
+        mode: 'embedded',
+        pythonCommand,
+        envFile,
+        cwd: config.cwd === undefined ? process.cwd() : nonEmpty('cwd', config.cwd),
+        namespaces,
+        defaultMode,
+        maxResults: integer('maxResults', config.maxResults ?? 20, 50),
+        maxSnippetChars: integer('maxSnippetChars', config.maxSnippetChars ?? 1200, 20_000),
+        maxReadChars: integer('maxReadChars', config.maxReadChars ?? 40_000, 200_000),
+        maxReadEngines: integer('maxReadEngines', config.maxReadEngines ?? 4, 32),
+        requestTimeoutMs: integer('requestTimeoutMs', config.requestTimeoutMs ?? 30_000, 2_147_483_647),
+        shutdownGraceMs: integer('shutdownGraceMs', config.shutdownGraceMs ?? 5_000, 2_147_483_647),
+        allowDegraded: config.allowDegraded ?? false,
+    };
+}
+/** Apply and validate every default before a local client or sidecar observes config. */
+export function resolveConfig(config) {
+    if (config.mode === 'embedded')
+        return resolveEmbeddedConfig(config);
+    return resolveLocalConfig(config);
+}
+//# sourceMappingURL=config.js.map

package/lib/connection/descriptor.d.ts

@@ -0,0 +1,4 @@
+import type { SagConnectionDescriptor } from './types.js';
+/** Parse a complete, versioned connection descriptor from a JSON or file boundary. */
+export declare function parseConnectionDescriptor(value: unknown): SagConnectionDescriptor;
+//# sourceMappingURL=descriptor.d.ts.map

package/lib/connection/descriptor.js

@@ -0,0 +1,66 @@
+const descriptorFields = new Set([
+    'schemaVersion',
+    'name',
+    'apiUrl',
+    'mcpUrl',
+    'accessToken',
+    'defaultSourceId',
+]);
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function requiredString(object, field) {
+    const value = object[field];
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error(`dsh-sag: connection descriptor ${field} must be a non-empty string`);
+    }
+    return value;
+}
+function httpUrl(object, field) {
+    const value = requiredString(object, field);
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        throw new Error(`dsh-sag: connection descriptor ${field} must be an http or https URL`);
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error(`dsh-sag: connection descriptor ${field} must be an http or https URL`);
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error(`dsh-sag: connection descriptor ${field} must not contain a username or password`);
+    }
+    return parsed;
+}
+/** Parse a complete, versioned connection descriptor from a JSON or file boundary. */
+export function parseConnectionDescriptor(value) {
+    if (!isPlainObject(value))
+        throw new Error('dsh-sag: connection descriptor must be a plain object');
+    for (const field of Object.keys(value)) {
+        if (!descriptorFields.has(field)) {
+            throw new Error(`dsh-sag: connection descriptor has unknown field ${field}`);
+        }
+    }
+    if (value.schemaVersion !== 1) {
+        throw new Error('dsh-sag: connection descriptor requires schemaVersion 1');
+    }
+    const defaultSourceId = value.defaultSourceId;
+    if (defaultSourceId !== undefined && defaultSourceId !== null && (typeof defaultSourceId !== 'string' || !defaultSourceId.trim())) {
+        throw new Error('dsh-sag: connection descriptor defaultSourceId must be a non-empty string or null');
+    }
+    const apiUrl = httpUrl(value, 'apiUrl');
+    const mcpUrl = httpUrl(value, 'mcpUrl');
+    return {
+        schemaVersion: 1,
+        name: requiredString(value, 'name'),
+        apiUrl: apiUrl.toString().replace(/\/$/, ''),
+        mcpUrl: mcpUrl.toString(),
+        accessToken: requiredString(value, 'accessToken'),
+        ...(defaultSourceId === undefined ? {} : { defaultSourceId }),
+    };
+}
+//# sourceMappingURL=descriptor.js.map

package/lib/connection/discovery.d.ts

@@ -0,0 +1,40 @@
+import type { FileSystem } from '@deepseek-ai/dsh-fs';
+import type { SagConnectionDescriptor } from './types.js';
+/** An HTTP response sufficient to parse a SAG connection descriptor. */
+export interface DiscoveryHttpResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+/** The injected HTTP boundary used for loopback discovery. */
+export type DiscoveryFetch = (url: string, init: {
+    readonly signal: AbortSignal;
+}) => Promise<DiscoveryHttpResponse>;
+/** One failed discovery candidate with a remediation a caller can present. */
+export interface DiscoveryDiagnostic {
+    readonly source: 'file' | 'loopback';
+    readonly candidate: string;
+    readonly message: string;
+    readonly action: string;
+}
+/** A connection found without changing the saved dsh-sag settings. */
+export interface DiscoveryResult {
+    readonly source: 'file' | 'loopback' | undefined;
+    readonly descriptor: SagConnectionDescriptor | undefined;
+    readonly diagnostics: readonly DiscoveryDiagnostic[];
+}
+/** The filesystem and network candidates to inspect in their supplied order. */
+export interface DiscoverConnectionOptions {
+    readonly fs: Pick<FileSystem, 'resolve' | 'readText'>;
+    readonly paths: readonly string[];
+    readonly urls: readonly string[];
+    readonly fetch: DiscoveryFetch;
+}
+/** Return the one explicit export path or the platform-standard SAG connection path. */
+export declare function platformConnectionPaths(env: Readonly<NodeJS.ProcessEnv>, platform: NodeJS.Platform, home: string): readonly string[];
+/**
+ * Inspect connection files before configured loopback URLs, returning the first strict v1 descriptor.
+ * Discovery never saves a descriptor; its caller decides whether a valid result should be persisted.
+ */
+export declare function discoverConnection(options: DiscoverConnectionOptions, signal: AbortSignal): Promise<DiscoveryResult>;
+//# sourceMappingURL=discovery.d.ts.map

package/lib/connection/discovery.js

@@ -0,0 +1,139 @@
+import { posix, win32 } from 'node:path';
+import { parseConnectionDescriptor } from './descriptor.js';
+import { SAG_SETUP_COMMAND } from './guidance.js';
+const LOOPBACK_CONNECTION_PATH = '/api/v1/system/dsh-connection';
+const LOOPBACK_TIMEOUT_MS = 1_500;
+function joinForPlatform(platform, ...parts) {
+    return (platform === 'win32' ? win32 : posix).join(...parts);
+}
+/** Return the one explicit export path or the platform-standard SAG connection path. */
+export function platformConnectionPaths(env, platform, home) {
+    const explicit = env.SAG_DSH_CONNECTION_FILE;
+    if (explicit)
+        return [explicit];
+    if (platform === 'darwin') {
+        return [joinForPlatform(platform, home, 'Library', 'Application Support', 'SAG', 'dsh-connection.json')];
+    }
+    if (platform === 'win32') {
+        return [joinForPlatform(platform, env.APPDATA || joinForPlatform(platform, home, 'AppData', 'Roaming'), 'SAG', 'dsh-connection.json')];
+    }
+    return [joinForPlatform(platform, env.XDG_CONFIG_HOME || joinForPlatform(platform, home, '.config'), 'sag', 'dsh-connection.json')];
+}
+function message(error) {
+    return error instanceof Error && error.message ? error.message : String(error);
+}
+function abortIfNeeded(signal) {
+    if (signal.aborted)
+        throw signal.reason;
+}
+function fileDiagnostic(candidate, error) {
+    return {
+        source: 'file',
+        candidate,
+        message: message(error),
+        action: `Check the SAG connection export at ${candidate} or run ${SAG_SETUP_COMMAND}.`,
+    };
+}
+function loopbackDiagnostic(candidate, error) {
+    return {
+        source: 'loopback',
+        candidate,
+        message: message(error),
+        action: `Start SAG for ${candidate} or run ${SAG_SETUP_COMMAND} --url <SAG loopback URL>.`,
+    };
+}
+function safeLoopbackCandidate(url) {
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        return parsed.toString();
+    }
+    catch {
+        return url.replace(/(\/\/)[^/?#]*@/, '$1<redacted>@');
+    }
+}
+function connectionEndpoint(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+        throw new Error('discovery URL must be an http or https URL');
+    }
+    if (parsed.username || parsed.password) {
+        throw new Error('discovery URL must not include a username or password');
+    }
+    return new URL(LOOPBACK_CONNECTION_PATH, parsed).toString();
+}
+async function fetchWithTimeout(fetch, url, signal) {
+    abortIfNeeded(signal);
+    const controller = new AbortController();
+    let rejectCallerAbort;
+    const callerAbort = new Promise((_resolve, reject) => { rejectCallerAbort = reject; });
+    const abortFromCaller = () => {
+        controller.abort(signal.reason);
+        rejectCallerAbort(signal.reason);
+    };
+    signal.addEventListener('abort', abortFromCaller, { once: true });
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            const error = new Error(`timed out after ${LOOPBACK_TIMEOUT_MS}ms`);
+            controller.abort(error);
+            reject(error);
+        }, LOOPBACK_TIMEOUT_MS);
+    });
+    try {
+        const response = await Promise.race([fetch(url, { signal: controller.signal }), timeout, callerAbort]);
+        abortIfNeeded(signal);
+        return response;
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        signal.removeEventListener('abort', abortFromCaller);
+    }
+}
+/**
+ * Inspect connection files before configured loopback URLs, returning the first strict v1 descriptor.
+ * Discovery never saves a descriptor; its caller decides whether a valid result should be persisted.
+ */
+export async function discoverConnection(options, signal) {
+    const diagnostics = [];
+    for (const candidate of options.paths) {
+        abortIfNeeded(signal);
+        try {
+            const target = await options.fs.resolve(candidate, { signal });
+            const text = await options.fs.readText(target, signal);
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch (error) {
+                throw new Error(`invalid JSON: ${message(error)}`);
+            }
+            return { source: 'file', descriptor: parseConnectionDescriptor(value), diagnostics };
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            diagnostics.push(fileDiagnostic(candidate, error));
+        }
+    }
+    for (const url of options.urls) {
+        abortIfNeeded(signal);
+        let candidate = safeLoopbackCandidate(url);
+        try {
+            candidate = connectionEndpoint(url);
+            const response = await fetchWithTimeout(options.fetch, candidate, signal);
+            if (!response.ok)
+                throw new Error(`HTTP ${response.status}`);
+            return { source: 'loopback', descriptor: parseConnectionDescriptor(await response.json()), diagnostics };
+        }
+        catch (error) {
+            if (signal.aborted)
+                throw error;
+            diagnostics.push(loopbackDiagnostic(candidate, error));
+        }
+    }
+    return { source: undefined, descriptor: undefined, diagnostics };
+}
+//# sourceMappingURL=discovery.js.map

package/lib/connection/guidance.d.ts

@@ -0,0 +1,7 @@
+/** Profile-scoped command prefix that reaches the installed dsh-sag bin. */
+export declare const SAG_PROFILE_CLI = "dsh plugin --profile web exec dsh-sag";
+/** Default local SAG discovery/setup command shown in recovery guidance. */
+export declare const SAG_SETUP_COMMAND = "dsh plugin --profile web exec dsh-sag setup";
+/** Non-mutating connection diagnostic command shown in recovery guidance. */
+export declare const SAG_DOCTOR_COMMAND = "dsh plugin --profile web exec dsh-sag doctor";
+//# sourceMappingURL=guidance.d.ts.map

package/lib/connection/guidance.js

@@ -0,0 +1,7 @@
+/** Profile-scoped command prefix that reaches the installed dsh-sag bin. */
+export const SAG_PROFILE_CLI = 'dsh plugin --profile web exec dsh-sag';
+/** Default local SAG discovery/setup command shown in recovery guidance. */
+export const SAG_SETUP_COMMAND = `${SAG_PROFILE_CLI} setup`;
+/** Non-mutating connection diagnostic command shown in recovery guidance. */
+export const SAG_DOCTOR_COMMAND = `${SAG_PROFILE_CLI} doctor`;
+//# sourceMappingURL=guidance.js.map

package/lib/connection/manager.d.ts

@@ -0,0 +1,67 @@
+import type { DiscoveryResult } from './discovery.js';
+import type { SagCapabilityDescriptor, SagConnectionDescriptor } from './types.js';
+import { type SagGateway } from '../local/gateway.js';
+import { type McpProbeResult } from '../local/mcp-probe.js';
+/** The only connection states exposed to setup, doctor, and tools. */
+export type SagConnectionStatus = 'ready' | 'not-found' | 'unreachable' | 'incompatible';
+/** Non-mutating checks made against one candidate connection. */
+export interface ConnectionInspection {
+    readonly status: SagConnectionStatus;
+    readonly health: boolean;
+    readonly ready: boolean;
+    readonly capabilities?: SagCapabilityDescriptor;
+    readonly sourceCount: number;
+    readonly mcp?: McpProbeResult;
+    readonly errors?: readonly string[];
+}
+/** A manager result suitable for tools and human-readable doctor output. */
+export interface SagConnectionReport extends ConnectionInspection {
+    readonly descriptor?: SagConnectionDescriptor;
+    readonly gateway?: SagGateway;
+    readonly discovery?: DiscoveryResult;
+}
+/** Read access to the explicitly saved connection; runtime discovery never mutates it. */
+export interface SagManagerStore {
+    load(): Promise<SagConnectionDescriptor | undefined>;
+}
+/** Injectable connection lifecycle operations. */
+export interface SagConnectionManagerDeps {
+    readonly store: SagManagerStore;
+    readonly discover: (signal: AbortSignal) => Promise<DiscoveryResult>;
+    readonly inspect?: (descriptor: SagConnectionDescriptor, signal: AbortSignal) => Promise<ConnectionInspection>;
+    readonly gateway?: (descriptor: SagConnectionDescriptor) => SagGateway;
+    /** Hard deadline for one complete discovery and inspection flight. */
+    readonly requestTimeoutMs?: number;
+    /** Maximum reuse window for a matching validated descriptor and gateway. */
+    readonly readyCacheTtlMs?: number;
+}
+/** Run health, readiness, capabilities, source count, and MCP compatibility checks without mutations. */
+export declare function inspectSagConnection(descriptor: SagConnectionDescriptor, signal: AbortSignal, gateway?: SagGateway, mcpProbe?: (descriptor: SagConnectionDescriptor, signal: AbortSignal, capabilities: readonly string[]) => Promise<McpProbeResult>): Promise<ConnectionInspection>;
+/** Lazy, single-flight manager for saved and automatically discovered local SAG connections. */
+export declare class SagConnectionManager {
+    private readonly deps;
+    private flight;
+    private connected;
+    private readonly gateway;
+    private readonly requestTimeoutMs;
+    private readonly readyCacheTtlMs;
+    private connectedAt;
+    private generation;
+    private requestSequence;
+    private latestAdmittedRequest;
+    /** @param deps - saved-connection reader, discovery, and optional testable network seams. */
+    constructor(deps: SagConnectionManagerDeps);
+    private report;
+    private inspectCandidate;
+    private connect;
+    private deadline;
+    private static fingerprint;
+    private closeDetached;
+    private replaceConnected;
+    private reusableConnected;
+    /** Load the caller's latest saved descriptor, then share only a matching connection flight. */
+    ensureConnected(signal: AbortSignal): Promise<SagConnectionReport>;
+    /** Re-run only non-mutating connection checks for setup and diagnostics. */
+    doctor(signal: AbortSignal): Promise<SagConnectionReport>;
+}
+//# sourceMappingURL=manager.d.ts.map