@deepseek-ai/dsh-plugin-detail 0.0.0-stage → 0.2.2-alpha.2

package/lib/types/files.d.ts

@@ -0,0 +1,126 @@
+import type { DetailFailureReason, NpmFileSource } from './types.ts';
+/** A read that must not fall back: the source exists but refused, failed, or exceeded a limit. */
+export declare class DetailFailure extends Error {
+    readonly reason: DetailFailureReason;
+    /**
+     * @param reason - the failure kind a reader reports.
+     * @param message - the diagnostic, naming the source.
+     * @param options - the underlying error.
+     */
+    constructor(reason: DetailFailureReason, message: string, options?: ErrorOptions);
+}
+/** One file found by name lookup. */
+export interface FoundFile {
+    /** `/`-separated path relative to the source root. */
+    readonly path: string;
+    readonly bytes: Uint8Array;
+}
+/** Files below one root, read by `/`-separated relative paths that never start with `/` or contain `.` or `..` segments. */
+export interface DetailFiles {
+    /** Identity of the files' content: two sources with the same key read the same bytes. */
+    readonly key: string;
+    /**
+     * Read one regular file.
+     * @param path - path relative to the root.
+     * @param maxBytes - largest accepted size.
+     * @param signal - cancellation of the read.
+     * @returns the file's bytes, or undefined when it does not exist.
+     * @throws {DetailFailure} when the source fails or the file exceeds `maxBytes`.
+     */
+    read(path: string, maxBytes: number, signal: AbortSignal): Promise<Uint8Array | undefined>;
+    /**
+     * Read the README of a directory: `README.md`, `README.markdown`, or `README` in any letter case.
+     * @param dir - directory relative to the root; `''` for the root.
+     * @param maxBytes - largest accepted size.
+     * @param signal - cancellation of the read.
+     * @returns the file, or undefined when the directory has none.
+     * @throws {DetailFailure} when the source fails or the file exceeds `maxBytes`.
+     */
+    readme(dir: string, maxBytes: number, signal: AbortSignal): Promise<FoundFile | undefined>;
+}
+/** README names tried in order where a source cannot list a directory. */
+export declare const README_NAMES: readonly string[];
+/**
+ * Join a directory and a file name into a root-relative path.
+ * @param dir - directory relative to the root, `''` for the root.
+ * @param name - path relative to `dir`.
+ * @returns the joined path.
+ */
+export declare function joinPath(dir: string, name: string): string;
+/**
+ * Pick the README entry of a directory listing by the order of {@link README_NAMES}, then by name.
+ * @param names - file names of the directory.
+ * @returns the README name, or undefined.
+ */
+export declare function readmeName(names: readonly string[]): string | undefined;
+/** Reads one file: its bytes, or undefined when it is absent. */
+export type ReadFile = (path: string, maxBytes: number, signal: AbortSignal) => Promise<Uint8Array | undefined>;
+/**
+ * Read the first README of `names` that exists, for sources that cannot list a directory.
+ * @param read - reads one file.
+ * @param dir - directory relative to the root; `''` for the root.
+ * @param maxBytes - largest accepted size.
+ * @param signal - cancellation of the reads.
+ * @param names - the names to try, in order.
+ * @returns the file, or undefined when none exists.
+ * @throws {DetailFailure} what `read` throws.
+ */
+export declare function readmeByName(read: ReadFile, dir: string, maxBytes: number, signal: AbortSignal, names?: readonly string[]): Promise<FoundFile | undefined>;
+/**
+ * Files of a local package directory. A path whose real location leaves the directory reads as absent.
+ * @param root - absolute package directory.
+ * @param revision - the installed version, so a reinstalled package reads as different files.
+ * @returns the files.
+ */
+export declare function localFiles(root: string, revision: string): DetailFiles;
+/** Request settings of a remote file source. */
+export interface RemoteFileOptions {
+    readonly timeoutMs: number;
+    /** Cancellation that outlives one read, such as the owning service's disposal. */
+    readonly lifetime: AbortSignal;
+}
+/** One HTTP answer: the body of a 2xx response, or the status of any other. */
+export type FetchedBody = {
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+} | {
+    readonly ok: false;
+    readonly status: number;
+};
+/**
+ * GET a URL, following redirects within its origin, and read the body up to `maxBytes`.
+ * @param url - the request URL.
+ * @param maxBytes - largest accepted body.
+ * @param signal - cancellation of the read.
+ * @param options - deadline and service lifetime.
+ * @returns the body, or the status of a non-2xx response, including a redirect to another origin.
+ * @throws {DetailFailure} `network` when no response arrives or the body fails, `too-large` over `maxBytes`.
+ */
+export declare function fetchBody(url: string, maxBytes: number, signal: AbortSignal, options: RemoteFileOptions): Promise<FetchedBody>;
+/** Every npm file CDN, in the default order. */
+export declare const NPM_FILE_SOURCES: readonly ["jsdelivr", "unpkg", "npmmirror"];
+/**
+ * Order the configured npm file CDNs by a caller's preference: the preferred ones that are configured, in the preferred
+ * order, then the other configured ones in configured order. A preferred CDN that is not configured is not asked.
+ * @param configured - the configured CDNs in order.
+ * @param preferred - CDNs to ask first, such as those a Client measured as fastest; names other than CDNs are ignored.
+ * @returns the CDNs to ask, first to last.
+ */
+export declare function npmFileSourceOrder(configured: readonly NpmFileSource[], preferred?: readonly string[]): NpmFileSource[];
+/**
+ * Percent-encode each segment of a `/`-separated path for a URL.
+ * @param path - the path.
+ * @returns the encoded path.
+ */
+export declare function encodePath(path: string): string;
+/**
+ * Files of one published npm package version, read from public file CDNs in order. A 404 from a CDN means the package
+ * does not contain the file; a network failure or another status asks the next CDN.
+ * @param name - package name.
+ * @param version - exact version.
+ * @param sources - the CDNs to ask, first to last; never empty.
+ * @param options - deadline and service lifetime.
+ * @returns the files.
+ */
+export declare function npmFiles(name: string, version: string, sources: readonly NpmFileSource[], options: RemoteFileOptions): DetailFiles;
+//# sourceMappingURL=files.d.ts.map

package/lib/types/files.js

@@ -0,0 +1,242 @@
+/**
+ * Read-only file sources for plugin detail documents: a local package directory and published npm package versions on
+ * public file CDNs, with bounded HTTP reads. Sources keep no state between calls.
+ */
+import { lstat, readdir, readFile, realpath } from 'node:fs/promises';
+import { join, relative, sep } from 'node:path';
+/** A read that must not fall back: the source exists but refused, failed, or exceeded a limit. */
+export class DetailFailure extends Error {
+    reason;
+    /**
+     * @param reason - the failure kind a reader reports.
+     * @param message - the diagnostic, naming the source.
+     * @param options - the underlying error.
+     */
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+        this.name = 'DetailFailure';
+    }
+}
+/** README names tried in order where a source cannot list a directory. */
+export const README_NAMES = ['README.md', 'readme.md', 'Readme.md', 'README.markdown', 'README'];
+const README_PATTERN = /^readme(?:\.md|\.markdown)?$/iu;
+/**
+ * Join a directory and a file name into a root-relative path.
+ * @param dir - directory relative to the root, `''` for the root.
+ * @param name - path relative to `dir`.
+ * @returns the joined path.
+ */
+export function joinPath(dir, name) {
+    return dir === '' ? name : `${dir}/${name}`;
+}
+/**
+ * Pick the README entry of a directory listing by the order of {@link README_NAMES}, then by name.
+ * @param names - file names of the directory.
+ * @returns the README name, or undefined.
+ */
+export function readmeName(names) {
+    const rank = (name) => {
+        const index = README_NAMES.indexOf(name);
+        return index === -1 ? README_NAMES.length : index;
+    };
+    return names.filter(name => README_PATTERN.test(name)).sort((a, b) => rank(a) - rank(b) || (a < b ? -1 : 1))[0];
+}
+/**
+ * Read the first README of `names` that exists, for sources that cannot list a directory.
+ * @param read - reads one file.
+ * @param dir - directory relative to the root; `''` for the root.
+ * @param maxBytes - largest accepted size.
+ * @param signal - cancellation of the reads.
+ * @param names - the names to try, in order.
+ * @returns the file, or undefined when none exists.
+ * @throws {DetailFailure} what `read` throws.
+ */
+export async function readmeByName(read, dir, maxBytes, signal, names = README_NAMES) {
+    for (const name of names) {
+        const path = joinPath(dir, name);
+        const bytes = await read(path, maxBytes, signal);
+        if (bytes !== undefined)
+            return { path, bytes };
+    }
+    return undefined;
+}
+function tooLarge(label, maxBytes) {
+    return new DetailFailure('too-large', `${label} exceeds ${String(maxBytes)} bytes`);
+}
+/**
+ * Files of a local package directory. A path whose real location leaves the directory reads as absent.
+ * @param root - absolute package directory.
+ * @param revision - the installed version, so a reinstalled package reads as different files.
+ * @returns the files.
+ */
+export function localFiles(root, revision) {
+    const files = {
+        key: `local:${root}@${revision}`,
+        async read(path, maxBytes) {
+            let file;
+            try {
+                const base = await realpath(root);
+                file = await realpath(join(base, ...path.split('/')));
+                const inside = relative(base, file);
+                if (inside === '' || inside === '..' || inside.startsWith(`..${sep}`))
+                    return undefined;
+                const info = await lstat(file);
+                if (!info.isFile())
+                    return undefined;
+                if (info.size > maxBytes)
+                    throw tooLarge(path, maxBytes);
+            }
+            catch (error) {
+                if (error instanceof DetailFailure)
+                    throw error;
+                // A missing file or directory, or one the process may not read, is a file the package does not provide.
+                return undefined;
+            }
+            const bytes = await readFile(file);
+            /* v8 ignore next -- the file grew between its size check and its read; no test controls that timing */
+            if (bytes.byteLength > maxBytes)
+                throw tooLarge(path, maxBytes);
+            return bytes;
+        },
+        async readme(dir, maxBytes, signal) {
+            let names;
+            try {
+                names = (await readdir(join(root, ...dir === '' ? [] : dir.split('/')), { withFileTypes: true }))
+                    .filter(entry => entry.isFile() || entry.isSymbolicLink()).map(entry => entry.name);
+            }
+            catch (_missing) {
+                // An absent or unreadable directory has no README.
+                return undefined;
+            }
+            const name = readmeName(names);
+            if (name === undefined)
+                return undefined;
+            const path = joinPath(dir, name);
+            const bytes = await files.read(path, maxBytes, signal);
+            return bytes === undefined ? undefined : { path, bytes };
+        },
+    };
+    return files;
+}
+/** Redirects followed within one origin, such as a renamed repository's raw files; a redirect to another origin is not followed. */
+const MAX_REDIRECTS = 3;
+/**
+ * GET a URL, following redirects within its origin, and read the body up to `maxBytes`.
+ * @param url - the request URL.
+ * @param maxBytes - largest accepted body.
+ * @param signal - cancellation of the read.
+ * @param options - deadline and service lifetime.
+ * @returns the body, or the status of a non-2xx response, including a redirect to another origin.
+ * @throws {DetailFailure} `network` when no response arrives or the body fails, `too-large` over `maxBytes`.
+ */
+export async function fetchBody(url, maxBytes, signal, options) {
+    const combined = AbortSignal.any([signal, options.lifetime, AbortSignal.timeout(options.timeoutMs)]);
+    let response;
+    let target = url;
+    for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+        try {
+            response = await fetch(target, { signal: combined, redirect: 'manual' });
+        }
+        catch (error) {
+            // A cancelled read says nothing about the source, so it keeps the caller's reason.
+            signal.throwIfAborted();
+            options.lifetime.throwIfAborted();
+            throw new DetailFailure('network', `Could not fetch ${target}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        }
+        const location = response.status >= 300 && response.status < 400 ? response.headers.get('location') : null;
+        if (location === null || !URL.canParse(location, target) || new URL(location, target).origin !== new URL(url).origin)
+            break;
+        await response.body?.cancel();
+        target = new URL(location, target).href;
+    }
+    // The loop runs at least once.
+    const answer = response;
+    if (!answer.ok) {
+        await answer.body?.cancel();
+        return { ok: false, status: answer.status };
+    }
+    if (Number(answer.headers.get('content-length') ?? 0) > maxBytes) {
+        await answer.body?.cancel();
+        throw tooLarge(url, maxBytes);
+    }
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of answer.body ?? []) {
+            size += chunk.byteLength;
+            if (size > maxBytes)
+                throw tooLarge(url, maxBytes);
+            chunks.push(chunk);
+        }
+    }
+    catch (error) {
+        if (error instanceof DetailFailure)
+            throw error;
+        throw new DetailFailure('network', `Could not read ${url}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    return { ok: true, bytes: Buffer.concat(chunks) };
+}
+/** Every npm file CDN, in the default order. */
+export const NPM_FILE_SOURCES = ['jsdelivr', 'unpkg', 'npmmirror'];
+/**
+ * Order the configured npm file CDNs by a caller's preference: the preferred ones that are configured, in the preferred
+ * order, then the other configured ones in configured order. A preferred CDN that is not configured is not asked.
+ * @param configured - the configured CDNs in order.
+ * @param preferred - CDNs to ask first, such as those a Client measured as fastest; names other than CDNs are ignored.
+ * @returns the CDNs to ask, first to last.
+ */
+export function npmFileSourceOrder(configured, preferred = []) {
+    const first = configured.filter(source => preferred.includes(source)).sort((a, b) => preferred.indexOf(a) - preferred.indexOf(b));
+    return [...first, ...configured.filter(source => !first.includes(source))];
+}
+/**
+ * Percent-encode each segment of a `/`-separated path for a URL.
+ * @param path - the path.
+ * @returns the encoded path.
+ */
+export function encodePath(path) {
+    return path.split('/').map(encodeURIComponent).join('/');
+}
+const NPM_FILE_URLS = {
+    jsdelivr: (name, version, path) => `https://cdn.jsdelivr.net/npm/${name}@${version}/${encodePath(path)}`,
+    unpkg: (name, version, path) => `https://unpkg.com/${name}@${version}/${encodePath(path)}`,
+    npmmirror: (name, version, path) => `https://registry.npmmirror.com/${name}/${version}/files/${encodePath(path)}`,
+};
+/**
+ * Files of one published npm package version, read from public file CDNs in order. A 404 from a CDN means the package
+ * does not contain the file; a network failure or another status asks the next CDN.
+ * @param name - package name.
+ * @param version - exact version.
+ * @param sources - the CDNs to ask, first to last; never empty.
+ * @param options - deadline and service lifetime.
+ * @returns the files.
+ */
+export function npmFiles(name, version, sources, options) {
+    const files = {
+        key: `npm:${name}@${version}`,
+        async read(path, maxBytes, signal) {
+            const failures = [];
+            for (const source of sources) {
+                const url = NPM_FILE_URLS[source](name, version, path);
+                try {
+                    const body = await fetchBody(url, maxBytes, signal, options);
+                    if (body.ok)
+                        return body.bytes;
+                    if (body.status === 404)
+                        return undefined;
+                    failures.push(`${url}: HTTP ${String(body.status)}`);
+                }
+                catch (error) {
+                    if (!(error instanceof DetailFailure) || error.reason !== 'network')
+                        throw error;
+                    failures.push(error.message);
+                }
+            }
+            throw new DetailFailure('network', failures.join('; '));
+        },
+        readme: (dir, maxBytes, signal) => readmeByName((path, max, readSignal) => files.read(path, max, readSignal), dir, maxBytes, signal),
+    };
+    return files;
+}
+//# sourceMappingURL=files.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Plugin detail documents without state: language chains, the `meta.detail` or README selection of a package, image
+ * destinations beside a document, and read-only file sources for local packages and published npm versions.
+ * @module @deepseek-ai/dsh-plugin-detail
+ */
+export { DetailFailure, encodePath, fetchBody, joinPath, localFiles, NPM_FILE_SOURCES, npmFileSourceOrder, npmFiles, README_NAMES, readmeByName, readmeName, type DetailFiles, type FetchedBody, type FoundFile, type ReadFile, type RemoteFileOptions, } from './files.ts';
+export { detailImage, languageChain, markdownOf, readPackageDocument, type PackageDocument } from './document.ts';
+export { detailImageResponse, type DetailImage } from './response.ts';
+export type { DetailFailureReason, NpmFileSource } from './types.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,9 @@
+/**
+ * Plugin detail documents without state: language chains, the `meta.detail` or README selection of a package, image
+ * destinations beside a document, and read-only file sources for local packages and published npm versions.
+ * @module @deepseek-ai/dsh-plugin-detail
+ */
+export { DetailFailure, encodePath, fetchBody, joinPath, localFiles, NPM_FILE_SOURCES, npmFileSourceOrder, npmFiles, README_NAMES, readmeByName, readmeName, } from "./files.js";
+export { detailImage, languageChain, markdownOf, readPackageDocument } from "./document.js";
+export { detailImageResponse } from "./response.js";
+//# sourceMappingURL=index.js.map

package/lib/types/response.d.ts

@@ -0,0 +1,17 @@
+/** HTTP responses of Host routes that serve images beside detail documents. */
+import type { DetailFailureReason } from './types.ts';
+/** An image read beside a detail document. */
+export interface DetailImage {
+    readonly bytes: Uint8Array;
+    readonly mediaType: string;
+}
+/**
+ * The response of an image route: the image, 404 when there is none, or the failure's status with its reason as the
+ * body. Every response carries `X-Content-Type-Options: nosniff` and a sandbox content security policy, because an SVG
+ * opened directly would otherwise run scripts on the authenticated API origin; only an image gets `cacheControl`.
+ * @param outcome - the image, undefined when none exists, or why it cannot be read; `invalid` also answers a malformed request.
+ * @param cacheControl - the `Cache-Control` value of an image.
+ * @returns the response.
+ */
+export declare function detailImageResponse(outcome: DetailImage | DetailFailureReason | undefined, cacheControl: string): Response;
+//# sourceMappingURL=response.d.ts.map

package/lib/types/response.js

@@ -0,0 +1,28 @@
+/** HTTP status of each detail failure. */
+const FAILURE_STATUS = {
+    'too-large': 413, 'network': 502, 'denied': 403, 'git-unavailable': 503, 'invalid': 400,
+};
+/**
+ * The response of an image route: the image, 404 when there is none, or the failure's status with its reason as the
+ * body. Every response carries `X-Content-Type-Options: nosniff` and a sandbox content security policy, because an SVG
+ * opened directly would otherwise run scripts on the authenticated API origin; only an image gets `cacheControl`.
+ * @param outcome - the image, undefined when none exists, or why it cannot be read; `invalid` also answers a malformed request.
+ * @param cacheControl - the `Cache-Control` value of an image.
+ * @returns the response.
+ */
+export function detailImageResponse(outcome, cacheControl) {
+    const [status, body, type] = typeof outcome === 'object'
+        // A copy into a fresh buffer is a body `Response` accepts whatever buffer the bytes view.
+        ? [200, new Uint8Array(outcome.bytes), outcome.mediaType]
+        : outcome === undefined ? [404, 'not found', undefined] : [FAILURE_STATUS[outcome], outcome, undefined];
+    return new Response(body, {
+        status,
+        headers: {
+            'Content-Type': type ?? 'text/plain; charset=utf-8',
+            'Cache-Control': status === 200 ? cacheControl : 'no-store',
+            'X-Content-Type-Options': 'nosniff',
+            'Content-Security-Policy': "sandbox; default-src 'none'; style-src 'unsafe-inline'",
+        },
+    });
+}
+//# sourceMappingURL=response.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,11 @@
+/** Plugin detail records that Remote methods and their clients share. */
+/**
+ * Why a detail document or one of its images cannot be read: `too-large` beyond a size limit, `network` when a source
+ * cannot be reached, `denied` when Git refuses the repository with the user's credentials, `git-unavailable` when a
+ * repository must be cloned and Git cannot run, and `invalid` for a malformed locale file or `meta.detail`, or a named
+ * file that does not exist.
+ */
+export type DetailFailureReason = 'too-large' | 'network' | 'denied' | 'git-unavailable' | 'invalid';
+/** A public CDN that serves single files of published npm package versions. */
+export type NpmFileSource = 'jsdelivr' | 'unpkg' | 'npmmirror';
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,3 @@
+/** Plugin detail records that Remote methods and their clients share. */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@deepseek-ai/dsh-plugin-detail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Plugin detail documents: meta.detail or README selection, image paths, and local and npm CDN file sources",
+  "version": "0.2.2-alpha.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/util/plugin-detail"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "~4.0.6-alpha.1"
+  }
 }