@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.0

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/constants.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The exact LuaSkills artifacts this plugin installs. Each fact is defined here once; the
+ * installer, the engine and the pages read it from this module.
+ */
+/** One npm package installed into the runtime's own `node_modules`, checked by its lockfile integrity. */
+export interface PinnedPackage {
+    readonly name: string;
+    readonly version: string;
+    readonly tarball: string;
+    /** Subresource integrity (`sha512-…`) published by the npm registry. */
+    readonly integrity: string;
+}
+/** The Node SDK and its one dependency. Koffi ships prebuilt binaries, so no install script runs. */
+export declare const SDK_PACKAGES: readonly PinnedPackage[];
+/** The SDK package the engine imports. */
+export declare const SDK_PACKAGE: PinnedPackage;
+/** LuaSkills core (JSON FFI) release; also the SDK 0.6.7 default. */
+export declare const LUASKILLS_VERSION = "v0.7.2";
+/**
+ * Lua runtime packages release. Pinned, because the SDK otherwise asks the GitHub API for the
+ * newest release of the series on every install.
+ */
+export declare const LUA_RUNTIME_VERSION = "v0.1.8";
+/** Roughly what the runtime takes on disk once installed, for the install prompt. */
+export declare const RUNTIME_SIZE_MB = 190;
+/** The default skill, installed into the ROOT layer with the runtime; it can be disabled, not removed. */
+export declare const DEFAULT_SKILL: {
+    readonly skillId: "vulcan-codekit";
+    readonly source: "LuaSkills/vulcan-codekit";
+    readonly sourceType: "github";
+};
+/**
+ * Codekit entries that only read. Every other LuaSkills entry may change files and follows the
+ * session's sandbox mode.
+ */
+export declare const READ_ONLY_ENTRIES: ReadonlySet<string>;
+/** The two LuaSkills Hub sites; the China site is a read-only mirror. */
+export declare const HUB_SITES: readonly [{
+    readonly site: "global";
+    readonly url: "https://hub.luaskills.com";
+}, {
+    readonly site: "cn";
+    readonly url: "https://hub.luaskills.cn";
+}];
+/** Budget every skill call is given; matches VulcanCode's inline tool result limit. */
+export declare const RESULT_BUDGET_BYTES = 200000;

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/constants.js

@@ -0,0 +1,51 @@
+/**
+ * The exact LuaSkills artifacts this plugin installs. Each fact is defined here once; the
+ * installer, the engine and the pages read it from this module.
+ */
+/** The Node SDK and its one dependency. Koffi ships prebuilt binaries, so no install script runs. */
+export const SDK_PACKAGES = [
+    {
+        name: '@luaskills/sdk',
+        version: '0.6.7',
+        tarball: 'https://registry.npmjs.org/@luaskills/sdk/-/sdk-0.6.7.tgz',
+        integrity: 'sha512-1yEvpMiPiEDDZK3/z1Deq3Hq7fb/SBaznObFjareUyBWoWCurT5jSHpzgex3ioyHnB3i6mXkrfvpukcEoN866Q==',
+    },
+    {
+        name: 'koffi',
+        version: '2.16.3',
+        tarball: 'https://registry.npmjs.org/koffi/-/koffi-2.16.3.tgz',
+        integrity: 'sha512-E9y1AsgYGlaxMhcZzHr8y96QF2U5XzA12GGVAfbWqIubTwPNMXQarfBzePNXHe0xtIEtNd6ifAv3GAKYGUeBAQ==',
+    },
+];
+/** The SDK package the engine imports. */
+export const SDK_PACKAGE = SDK_PACKAGES[0];
+/** LuaSkills core (JSON FFI) release; also the SDK 0.6.7 default. */
+export const LUASKILLS_VERSION = 'v0.7.2';
+/**
+ * Lua runtime packages release. Pinned, because the SDK otherwise asks the GitHub API for the
+ * newest release of the series on every install.
+ */
+export const LUA_RUNTIME_VERSION = 'v0.1.8';
+/** Roughly what the runtime takes on disk once installed, for the install prompt. */
+export const RUNTIME_SIZE_MB = 190;
+/** The default skill, installed into the ROOT layer with the runtime; it can be disabled, not removed. */
+export const DEFAULT_SKILL = { skillId: 'vulcan-codekit', source: 'LuaSkills/vulcan-codekit', sourceType: 'github' };
+/**
+ * Codekit entries that only read. Every other LuaSkills entry may change files and follows the
+ * session's sandbox mode.
+ */
+export const READ_ONLY_ENTRIES = new Set([
+    'vulcan-codekit-repo-map',
+    'vulcan-codekit-ast-detail',
+    'vulcan-codekit-ast-tree',
+    'vulcan-codekit-rg',
+    'vulcan-codekit-markdown-menu',
+    'vulcan-codekit-node-source',
+]);
+/** The two LuaSkills Hub sites; the China site is a read-only mirror. */
+export const HUB_SITES = [
+    { site: 'global', url: 'https://hub.luaskills.com' },
+    { site: 'cn', url: 'https://hub.luaskills.cn' },
+];
+/** Budget every skill call is given; matches VulcanCode's inline tool result limit. */
+export const RESULT_BUDGET_BYTES = 200_000;

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/engine.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The Host side of the LuaSkills worker: one request at a time per call site, answered by id.
+ * The worker owns every SDK call; when it exits, every pending request fails with the reason.
+ *
+ * The worker is a child process, not a thread: the LuaSkills core library it loads stays mapped
+ * until its process ends, and Windows refuses to delete a mapped library, so only a process lets
+ * the runtime be removed or reinstalled while dsh runs. A native crash also stays in the child.
+ */
+import type { ApplyResult, EntryDescriptor, HelpDetail, InvocationResult, SkillHelp } from './protocol.js';
+export type DownloadListener = (role: string, received: number, total: number | null) => void;
+export declare class LuaSkillsWorker {
+    private readonly onExit;
+    private readonly worker;
+    private readonly pending;
+    private next;
+    private exitError;
+    /** Set once the Host asked the worker to stop; its exit is then not a crash. */
+    private stopping;
+    private readonly started;
+    /** Settles once the worker process has ended and released the core library. */
+    private readonly exited;
+    /** Set while a runtime install reports its downloads. */
+    onDownload: DownloadListener | undefined;
+    /**
+     * @param sdkEntry - absolute path of the SDK's entry module.
+     * @param onExit - called once if the worker stops without being asked to.
+     */
+    constructor(sdkEntry: string, onExit: (error: Error) => void);
+    private fail;
+    private request;
+    installRuntime(params: {
+        runtimeRoot: string;
+        luaskillsVersion: string;
+        luaRuntimeVersion: string;
+    }): Promise<void>;
+    start(params: {
+        runtimeRoot: string;
+        poolConfig: object;
+        hostOptions: object;
+    }): Promise<void>;
+    entries(): Promise<EntryDescriptor[]>;
+    help(): Promise<SkillHelp[]>;
+    helpDetail(skillId: string, flow?: string): Promise<HelpDetail | null>;
+    call(name: string, args: unknown, context: unknown): Promise<InvocationResult>;
+    install(root: string, request: object): Promise<ApplyResult>;
+    update(root: string, request: object): Promise<ApplyResult>;
+    uninstall(root: string, skillId: string): Promise<ApplyResult>;
+    setEnabled(skillId: string, enabled: boolean): Promise<unknown>;
+    /** The worker's process id; the SDK names its scratch folders after it. */
+    get pid(): number | undefined;
+    /** Close the engine, then the process; nothing is reported as a crash. */
+    stop(): Promise<void>;
+    /** Stop at once, abandoning whatever the worker is doing; resolves once the process is gone. */
+    kill(): Promise<void>;
+}

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/engine.js

@@ -0,0 +1,149 @@
+/**
+ * The Host side of the LuaSkills worker: one request at a time per call site, answered by id.
+ * The worker owns every SDK call; when it exits, every pending request fails with the reason.
+ *
+ * The worker is a child process, not a thread: the LuaSkills core library it loads stays mapped
+ * until its process ends, and Windows refuses to delete a mapped library, so only a process lets
+ * the runtime be removed or reinstalled while dsh runs. A native crash also stays in the child.
+ */
+import { fork } from 'node:child_process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+export class LuaSkillsWorker {
+    onExit;
+    worker;
+    pending = new Map();
+    next = 0;
+    exitError;
+    /** Set once the Host asked the worker to stop; its exit is then not a crash. */
+    stopping = false;
+    started;
+    /** Settles once the worker process has ended and released the core library. */
+    exited;
+    /** Set while a runtime install reports its downloads. */
+    onDownload;
+    /**
+     * @param sdkEntry - absolute path of the SDK's entry module.
+     * @param onExit - called once if the worker stops without being asked to.
+     */
+    constructor(sdkEntry, onExit) {
+        this.onExit = onExit;
+        this.worker = fork(fileURLToPath(new URL('./worker.js', import.meta.url)), [pathToFileURL(sdkEntry).href], {
+            // Inspector or loader flags of dsh's own process do not apply to the worker; under Electron
+            // the executable runs as plain Node.js.
+            execArgv: [],
+            env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+            serialization: 'advanced',
+            stdio: ['ignore', 'inherit', 'inherit', 'ipc'],
+        });
+        let ready;
+        let failed;
+        this.started = new Promise((resolve, reject) => { ready = resolve; failed = reject; });
+        this.started.catch(() => { });
+        this.exited = new Promise((resolve) => {
+            this.worker.once('exit', () => { resolve(); });
+            // A process that never started has no exit to wait for.
+            this.worker.once('error', () => { if (this.worker.pid === undefined)
+                resolve(); });
+        });
+        this.worker.on('message', (message) => {
+            if ('event' in message) {
+                if (message.event === 'ready')
+                    ready();
+                else
+                    this.onDownload?.(message.role, message.received, message.total);
+                return;
+            }
+            const waiter = this.pending.get(message.id);
+            if (waiter === undefined)
+                return;
+            this.pending.delete(message.id);
+            if (message.ok)
+                waiter.resolve(message.value);
+            else
+                waiter.reject(new Error(message.error));
+        });
+        // A failed SDK import surfaces as `error` or `exit` before `ready`; settling `started` twice is a no-op.
+        this.worker.on('error', (error) => {
+            failed(error);
+            this.fail(error);
+        });
+        this.worker.on('exit', (code, signal) => {
+            const error = new Error(`the LuaSkills worker stopped (${signal === null ? `exit code ${code}` : signal})`);
+            failed(error);
+            this.fail(error);
+        });
+    }
+    fail(error) {
+        if (this.exitError !== undefined)
+            return;
+        this.exitError = this.stopping ? new Error('the LuaSkills worker was stopped') : error;
+        for (const waiter of this.pending.values())
+            waiter.reject(this.exitError);
+        this.pending.clear();
+        if (!this.stopping)
+            this.onExit(error);
+    }
+    async request(method, params = null, internal = false) {
+        await this.started;
+        if (this.exitError !== undefined)
+            throw this.exitError;
+        if (this.stopping && !internal)
+            throw new Error('the LuaSkills worker is stopping');
+        const id = ++this.next;
+        return await new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.worker.send({ id, method, params });
+        });
+    }
+    installRuntime(params) {
+        return this.request('installRuntime', params);
+    }
+    start(params) {
+        return this.request('start', params);
+    }
+    entries() {
+        return this.request('entries');
+    }
+    help() {
+        return this.request('help');
+    }
+    helpDetail(skillId, flow) {
+        return this.request('helpDetail', { skillId, ...flow === undefined ? {} : { flow } });
+    }
+    call(name, args, context) {
+        return this.request('call', { name, args, context });
+    }
+    install(root, request) {
+        return this.request('install', { root, request });
+    }
+    update(root, request) {
+        return this.request('update', { root, request });
+    }
+    uninstall(root, skillId) {
+        return this.request('uninstall', { root, skillId });
+    }
+    setEnabled(skillId, enabled) {
+        return this.request('setEnabled', { skillId, enabled });
+    }
+    /** The worker's process id; the SDK names its scratch folders after it. */
+    get pid() {
+        return this.worker.pid;
+    }
+    /** Close the engine, then the process; nothing is reported as a crash. */
+    async stop() {
+        this.stopping = true;
+        // A call still running holds the engine; it gets a few seconds before the process is ended.
+        await Promise.race([
+            this.request('stop', null, true),
+            new Promise(resolve => setTimeout(resolve, 5000)),
+        ]).catch(() => { });
+        await this.kill();
+    }
+    /** Stop at once, abandoning whatever the worker is doing; resolves once the process is gone. */
+    async kill() {
+        this.stopping = true;
+        if (this.worker.exitCode === null && this.worker.signalCode === null)
+            this.worker.kill();
+        await this.exited;
+    }
+}

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/hub.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Read-only LuaSkills Hub catalog, fetched by the Host for the LuaSkills page. Installing stays
+ * inside LuaSkills through the `official_hub` source, against the same Hub base URL the engine
+ * uses. Limits follow VulcanCode's Hub client.
+ */
+export declare class HubError extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export interface HubContent {
+    readonly requested_locale?: string;
+    readonly locale?: string;
+    /** `original`, `translation`, or `original_fallback` while no translation exists. */
+    readonly kind?: string;
+    readonly summary?: string;
+    readonly intro?: string;
+    readonly features?: readonly string[];
+    readonly readme?: string | null;
+}
+export interface HubSkill {
+    readonly skill_id: string;
+    readonly publisher?: string;
+    readonly display_name?: string;
+    readonly summary?: string;
+    readonly repository_url?: string;
+    readonly homepage_url?: string;
+    readonly license?: string;
+    readonly tags?: readonly string[];
+    readonly latest_version?: string;
+    readonly updated_at?: string;
+    readonly content?: HubContent | null;
+}
+export interface HubPage {
+    readonly hub: string;
+    readonly items: readonly HubSkill[];
+    readonly nextCursor: string | null;
+}
+export interface HubDetail {
+    readonly hub: string;
+    readonly skill: HubSkill;
+    readonly original: HubContent | null;
+    readonly latest: {
+        readonly version: string;
+        readonly readme?: string;
+        readonly published_at?: string;
+    };
+}
+export declare function searchHub(base: string, query: string, cursor: string | null, locale: string | null): Promise<HubPage>;
+export declare function hubSkill(base: string, skillId: string, locale: string | null): Promise<HubDetail>;

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/hub.js

@@ -0,0 +1,116 @@
+/**
+ * Read-only LuaSkills Hub catalog, fetched by the Host for the LuaSkills page. Installing stays
+ * inside LuaSkills through the `official_hub` source, against the same Hub base URL the engine
+ * uses. Limits follow VulcanCode's Hub client.
+ */
+const PAGE_SIZE = 24;
+const MAX_QUERY_CHARS = 100;
+const MAX_CURSOR_CHARS = 12;
+const MAX_SKILL_ID_CHARS = 64;
+const MAX_LOCALE_CHARS = 35;
+const SEARCH_MAX_BYTES = 1024 * 1024;
+/** A translated README can exceed the original. */
+const DETAIL_MAX_BYTES = 2 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+export class HubError extends Error {
+    code;
+    constructor(message, code = 'hub_failed') {
+        super(message);
+        this.code = code;
+    }
+}
+function apiUrl(base, segments) {
+    let url;
+    try {
+        url = new URL(base.endsWith('/') ? base : `${base}/`);
+    }
+    catch {
+        throw new HubError(`the LuaSkills Hub address ${base} is not a URL`, 'invalid_request');
+    }
+    url.pathname = `${url.pathname.replace(/\/+$/, '')}/api/v1/${segments.map(encodeURIComponent).join('/')}`;
+    return url;
+}
+function setLocale(url, locale) {
+    if (locale === null || locale === '')
+        return;
+    if (locale.length > MAX_LOCALE_CHARS)
+        throw new HubError('the language code is too long', 'invalid_request');
+    url.searchParams.set('lang', locale);
+}
+async function fetchJson(url, maxBytes, what) {
+    const response = await fetch(url, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS), headers: { accept: 'application/json' } });
+    const text = await readCapped(response, maxBytes, what);
+    if (!response.ok) {
+        let message = text.slice(0, 200);
+        try {
+            const body = JSON.parse(text);
+            message = body.error?.message ?? message;
+        }
+        catch {
+            // Not JSON; the start of the text is the message.
+        }
+        throw new HubError(`LuaSkills Hub ${what} failed: HTTP ${response.status} ${message}`.trim());
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HubError(`LuaSkills Hub returned an invalid ${what} response`);
+    }
+}
+async function readCapped(response, maxBytes, what) {
+    if (response.body === null)
+        return '';
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+        size += chunk.byteLength;
+        if (size > maxBytes)
+            throw new HubError(`LuaSkills Hub ${what} response is larger than ${maxBytes} bytes`);
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export async function searchHub(base, query, cursor, locale) {
+    const text = query.trim();
+    if ([...text].length > MAX_QUERY_CHARS)
+        throw new HubError(`the search text is longer than ${MAX_QUERY_CHARS} characters`, 'invalid_request');
+    if (cursor !== null && cursor.length > MAX_CURSOR_CHARS)
+        throw new HubError('the page cursor is not valid', 'invalid_request');
+    const url = apiUrl(base, ['skills', 'search']);
+    url.searchParams.set('limit', String(PAGE_SIZE));
+    if (text !== '')
+        url.searchParams.set('q', text);
+    if (cursor !== null && cursor !== '')
+        url.searchParams.set('cursor', cursor);
+    setLocale(url, locale);
+    const body = await fetchJson(url, SEARCH_MAX_BYTES, 'search');
+    if (!Array.isArray(body.items) || !body.items.every(isSkill))
+        throw new HubError('LuaSkills Hub returned an invalid search response');
+    return {
+        hub: base.replace(/\/+$/, ''),
+        items: body.items,
+        nextCursor: typeof body.next_cursor === 'string' && body.next_cursor !== '' ? body.next_cursor : null,
+    };
+}
+export async function hubSkill(base, skillId, locale) {
+    const id = skillId.trim();
+    if (id === '' || [...id].length > MAX_SKILL_ID_CHARS) {
+        throw new HubError(`the skill id must be 1 to ${MAX_SKILL_ID_CHARS} characters`, 'invalid_request');
+    }
+    const url = apiUrl(base, ['skills', id]);
+    setLocale(url, locale);
+    const body = await fetchJson(url, DETAIL_MAX_BYTES, 'skill detail');
+    const latest = body.latest;
+    if (!isSkill(body.skill) || typeof latest?.version !== 'string')
+        throw new HubError('LuaSkills Hub returned an invalid skill detail response');
+    return {
+        hub: base.replace(/\/+$/, ''),
+        skill: body.skill,
+        original: typeof body.original === 'object' && body.original !== null ? body.original : null,
+        latest,
+    };
+}
+function isSkill(value) {
+    return typeof value === 'object' && value !== null && typeof value.skill_id === 'string';
+}

package/node_modules/@openvulcan/dsh-vulcan-luaskills/lib/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * LuaSkills in dsh. The runtime is not part of this package: the user installs it from the
+ * LuaSkills settings page, and from then on every enabled skill entry is a dsh tool, every
+ * loaded skill is in dsh's skill catalog, and the page manages installed skills and the Hub.
+ * The pages talk to the exact `/api/vulcan-luaskills/*` routes inside dsh's authenticated
+ * connection.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type InstalledSkill } from './skills.js';
+export type { RuntimeState, RuntimeView } from './runtime.js';
+export type { LuaSkillsSettings } from './settings.js';
+export type { InstalledSkill } from './skills.js';
+export declare const name = "vulcan-luaskills";
+export declare const inject: string[];
+/** Prefix of every page route, below dsh's `/api`. Also restated in `client/shared.ts`. */
+export declare const ROUTE_PREFIX = "/api/vulcan-luaskills/";
+/** An installed skill with whether the engine loaded it. */
+export interface SkillRow extends InstalledSkill {
+    readonly loaded: boolean;
+    readonly tools: readonly string[];
+}
+export declare function apply(ctx: Context): void;
+/** Fetch-shaped handler of one page route. */
+type Handler = (request: Request, url: URL) => Promise<unknown>;
+/** Answer one page request; failures carry their code, never a stack. */
+export declare function handle(handler: Handler, request: Request): Promise<Response>;