@openvulcan/dsh-vulcancode 0.0.0-stage → 0.4.3

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

@@ -0,0 +1,281 @@
+/**
+ * The LuaSkills runtime's lifecycle: absent until the user installs it, then installed in five
+ * steps with progress, started on every dsh start while its versions match, restarted when
+ * settings change, and removable. A failed or cancelled install leaves nothing half-installed.
+ *
+ * Layout below the plugin's folder in the dsh home:
+ * - `sdk/node_modules/` — the SDK and Koffi;
+ * - `runtime/` — the SDK's runtime root (core library, Lua packages, skill layers, state);
+ * - `installed.json` — written last; without it the runtime counts as not installed;
+ * - `settings.json` — the user's settings, kept when the runtime is removed.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { DEFAULT_SKILL, HUB_SITES, LUA_RUNTIME_VERSION, LUASKILLS_VERSION, RUNTIME_SIZE_MB, SDK_PACKAGE, SDK_PACKAGES, } from './constants.js';
+import { LuaSkillsWorker } from './engine.js';
+import { installPackages, packageDir } from './sdk-install.js';
+import { engineOptions, loadSettings, parseSettings, saveSettings, } from './settings.js';
+/** The versions this plugin installs. */
+export const PINNED = { sdk: SDK_PACKAGE.version, luaskills: LUASKILLS_VERSION, luaRuntime: LUA_RUNTIME_VERSION };
+/** Install steps, in the order the SDK fetches the runtime archives. */
+export const PHASES = ['sdk', 'lua', 'core', 'engine', 'skill'];
+export class RuntimeError extends Error {
+    code;
+    constructor(message, code = 'not_ready') {
+        super(message);
+        this.code = code;
+    }
+}
+export class LuaSkillsRuntime {
+    home;
+    changed;
+    runtimeRoot;
+    nodeModules;
+    marker;
+    settingsFile;
+    scratch;
+    state = { kind: 'absent' };
+    worker;
+    loaded;
+    installing;
+    closed = false;
+    /**
+     * @param home - this plugin's folder in the dsh home.
+     * @param changed - called after every state change.
+     */
+    constructor(home, changed) {
+        this.home = home;
+        this.changed = changed;
+        this.runtimeRoot = path.join(home, 'runtime');
+        this.nodeModules = path.join(home, 'sdk', 'node_modules');
+        this.marker = path.join(home, 'installed.json');
+        this.settingsFile = path.join(home, 'settings.json');
+        this.scratch = path.join(home, 'download');
+        this.loaded = loadSettings(this.settingsFile);
+    }
+    get current() {
+        return this.state;
+    }
+    view() {
+        return {
+            state: this.state,
+            location: this.home,
+            sizeMb: RUNTIME_SIZE_MB,
+            versions: PINNED,
+            settings: this.loaded.settings,
+            settingsSource: this.loaded.kind,
+            ...this.loaded.kind === 'invalid' ? { settingsError: this.loaded.error } : {},
+            hubSites: HUB_SITES,
+        };
+    }
+    get settings() {
+        return this.loaded.settings;
+    }
+    /** The running engine. @throws RuntimeError when it is not ready. */
+    engine() {
+        if (this.state.kind !== 'ready' || this.worker === undefined)
+            throw new RuntimeError('the LuaSkills runtime is not running');
+        return this.worker;
+    }
+    /** Start the installed runtime, if there is one this version can use. */
+    async boot() {
+        const installed = this.readMarker();
+        if (installed === undefined)
+            return;
+        if (installed.sdk !== PINNED.sdk || installed.luaskills !== PINNED.luaskills || installed.luaRuntime !== PINNED.luaRuntime) {
+            this.set({ kind: 'outdated', installed: { sdk: installed.sdk, luaskills: installed.luaskills, luaRuntime: installed.luaRuntime } });
+            return;
+        }
+        await this.start();
+    }
+    /** Begin installing in the background; progress shows in the state. */
+    install() {
+        if (this.state.kind === 'installing' || this.state.kind === 'starting')
+            throw new RuntimeError('the LuaSkills runtime is busy', 'busy');
+        if (this.state.kind === 'ready')
+            throw new RuntimeError('the LuaSkills runtime is already installed', 'busy');
+        const controller = new AbortController();
+        this.installing = controller;
+        void this.runInstall(controller.signal).finally(() => {
+            if (this.installing === controller)
+                this.installing = undefined;
+        });
+    }
+    /** Stop the running install; what it wrote is removed. */
+    cancel() {
+        this.installing?.abort(new Error('the install was cancelled'));
+    }
+    /** Stop the engine and delete the runtime; settings are kept. */
+    async remove() {
+        if (this.state.kind === 'installing' || this.state.kind === 'starting')
+            throw new RuntimeError('the LuaSkills runtime is busy', 'busy');
+        await this.stopWorker();
+        await this.wipe();
+        this.set({ kind: 'absent' });
+    }
+    /** Restart the engine with the current settings. */
+    async restart() {
+        if (this.state.kind === 'installing' || this.state.kind === 'starting')
+            throw new RuntimeError('the LuaSkills runtime is busy', 'busy');
+        if (this.readMarker() === undefined)
+            throw new RuntimeError('the LuaSkills runtime is not installed');
+        await this.start();
+    }
+    /**
+     * Check and save the settings, then restart a running engine so they apply.
+     * @throws SettingsError when the value is not valid; nothing is written then.
+     */
+    async saveSettings(value) {
+        if (this.state.kind === 'installing' || this.state.kind === 'starting')
+            throw new RuntimeError('the LuaSkills runtime is busy', 'busy');
+        const settings = parseSettings(value);
+        saveSettings(this.settingsFile, settings);
+        this.loaded = { kind: 'saved', settings };
+        if (this.state.kind === 'ready' || (this.state.kind === 'failed' && this.state.installed))
+            await this.start();
+        else
+            this.changed();
+    }
+    async close() {
+        this.closed = true;
+        this.cancel();
+        await this.stopWorker();
+    }
+    set(state) {
+        this.state = state;
+        if (!this.closed)
+            this.changed();
+    }
+    sdkEntry() {
+        return path.join(packageDir(this.nodeModules, SDK_PACKAGE.name), 'dist', 'index.js');
+    }
+    readMarker() {
+        try {
+            const marker = JSON.parse(readFileSync(this.marker, 'utf8'));
+            if (typeof marker.sdk !== 'string' || typeof marker.luaskills !== 'string' || typeof marker.luaRuntime !== 'string')
+                return undefined;
+            if (!existsSync(this.sdkEntry()) || !existsSync(this.runtimeRoot))
+                return undefined;
+            return marker;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    spawn() {
+        const worker = new LuaSkillsWorker(this.sdkEntry(), (error) => {
+            if (this.worker !== worker)
+                return;
+            this.worker = undefined;
+            if (this.state.kind === 'ready' || this.state.kind === 'starting')
+                this.set({ kind: 'failed', error: error.message, installed: true });
+        });
+        this.worker = worker;
+        return worker;
+    }
+    async stopWorker() {
+        const worker = this.worker;
+        this.worker = undefined;
+        await worker?.stop();
+    }
+    async start() {
+        await this.stopWorker();
+        this.set({ kind: 'starting' });
+        try {
+            const worker = this.spawn();
+            await worker.start({ runtimeRoot: this.runtimeRoot, ...engineOptions(this.loaded.settings) });
+            this.set({ kind: 'ready' });
+        }
+        catch (error) {
+            await this.stopWorker();
+            this.set({ kind: 'failed', error: messageOf(error), installed: true });
+        }
+    }
+    async wipe() {
+        // The marker goes first, so an interrupted removal never looks installed.
+        await rm(this.marker, { force: true });
+        for (const folder of [path.join(this.home, 'sdk'), this.runtimeRoot, this.scratch]) {
+            await rm(folder, { recursive: true, force: true, maxRetries: 3 });
+        }
+    }
+    async runInstall(signal) {
+        const progress = (phase, received = 0, total = null) => {
+            this.set({ kind: 'installing', phase, received, total });
+        };
+        const started = Date.now();
+        try {
+            progress('sdk');
+            await this.stopWorker();
+            await this.wipe();
+            await installPackages(SDK_PACKAGES, this.nodeModules, this.scratch, signal, (_index, received, total) => {
+                throttled(() => { progress('sdk', received, total); }, received === total);
+            });
+            signal.throwIfAborted();
+            progress('lua');
+            const worker = this.spawn();
+            worker.onDownload = (role, received, total) => {
+                throttled(() => { progress(role === 'lua_runtime' ? 'lua' : 'core', received, total); }, received === total || received === 0);
+            };
+            await abortable(worker.installRuntime({ runtimeRoot: this.runtimeRoot, luaskillsVersion: LUASKILLS_VERSION, luaRuntimeVersion: LUA_RUNTIME_VERSION }), signal);
+            worker.onDownload = undefined;
+            progress('engine');
+            await abortable(worker.start({ runtimeRoot: this.runtimeRoot, ...engineOptions(this.loaded.settings) }), signal);
+            progress('skill');
+            const result = await abortable(worker.install('ROOT', {
+                skill_id: DEFAULT_SKILL.skillId, source: DEFAULT_SKILL.source, source_type: DEFAULT_SKILL.sourceType,
+            }), signal);
+            if (!['installed', 'updated', 'up_to_date'].includes(result.status))
+                throw new Error(`${DEFAULT_SKILL.skillId}: ${result.message}`);
+            const marker = { ...PINNED, platform: `${process.platform}-${process.arch}`, installedAt: new Date().toISOString() };
+            await writeFile(this.marker, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+            await rm(this.scratch, { recursive: true, force: true });
+            this.set({ kind: 'ready' });
+        }
+        catch (error) {
+            const worker = this.worker;
+            this.worker = undefined;
+            await worker?.kill();
+            await this.wipe().catch(() => { });
+            if (worker?.pid !== undefined)
+                await removeSdkScratch(worker.pid, started).catch(() => { });
+            if (signal.aborted)
+                this.set({ kind: 'absent' });
+            else
+                this.set({ kind: 'failed', error: messageOf(error), installed: false });
+        }
+    }
+}
+/**
+ * The SDK unpacks runtime archives in `<tmpdir>/luaskills-runtime-assets-<pid>-<ms>` and removes it
+ * itself, unless the worker is stopped first; remove the ones this install left behind.
+ */
+async function removeSdkScratch(pid, since) {
+    const prefix = `luaskills-runtime-assets-${pid}-`;
+    for (const name of await readdir(tmpdir())) {
+        if (name.startsWith(prefix) && Number(name.slice(prefix.length)) >= since) {
+            await rm(path.join(tmpdir(), name), { recursive: true, force: true, maxRetries: 3 });
+        }
+    }
+}
+let lastReport = 0;
+/** Report download progress at most every 200 ms, and always the last one. */
+function throttled(report, final) {
+    const now = Date.now();
+    if (!final && now - lastReport < 200)
+        return;
+    lastReport = now;
+    report();
+}
+async function abortable(work, signal) {
+    signal.throwIfAborted();
+    return await new Promise((resolve, reject) => {
+        const onAbort = () => { reject(signal.reason); };
+        signal.addEventListener('abort', onAbort, { once: true });
+        work.then(resolve, reject).finally(() => { signal.removeEventListener('abort', onAbort); });
+    });
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Install the pinned SDK packages into the runtime's own `node_modules`: download each npm
+ * tarball, check it against the registry's sha512 integrity, check every archive member stays
+ * inside its folder, then unpack it with the system `tar`. No package manager and no install
+ * script runs.
+ */
+import type { PinnedPackage } from './constants.js';
+/** Where one package lives below a `node_modules` folder. */
+export declare function packageDir(nodeModules: string, name: string): string;
+/**
+ * Download one URL whole, reporting bytes as they arrive.
+ * @throws when the answer is not 200 or the signal aborts.
+ */
+export declare function download(url: string, signal: AbortSignal, progress: (received: number, total: number | null) => void): Promise<Buffer>;
+/** @throws when the bytes do not match a `sha512-<base64>` integrity value. */
+export declare function checkIntegrity(bytes: Buffer, integrity: string, name: string): void;
+/**
+ * @throws when an npm tarball member is absolute, climbs out of `package/`, or is a link.
+ * npm tarballs hold one top folder (usually `package/`); it is stripped on extraction.
+ */
+export declare function checkMembers(listing: string, name: string): void;
+/**
+ * Install `packages` below `nodeModules`, each package folder replaced whole.
+ * @param progress - bytes of the package downloading now, with its index.
+ */
+export declare function installPackages(packages: readonly PinnedPackage[], nodeModules: string, scratch: string, signal: AbortSignal, progress: (index: number, received: number, total: number | null) => void): Promise<void>;

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

@@ -0,0 +1,87 @@
+/**
+ * Install the pinned SDK packages into the runtime's own `node_modules`: download each npm
+ * tarball, check it against the registry's sha512 integrity, check every archive member stays
+ * inside its folder, then unpack it with the system `tar`. No package manager and no install
+ * script runs.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const run = promisify(execFile);
+/** Where one package lives below a `node_modules` folder. */
+export function packageDir(nodeModules, name) {
+    return path.join(nodeModules, ...name.split('/'));
+}
+/**
+ * Download one URL whole, reporting bytes as they arrive.
+ * @throws when the answer is not 200 or the signal aborts.
+ */
+export async function download(url, signal, progress) {
+    const response = await fetch(url, { signal });
+    if (!response.ok || response.body === null)
+        throw new Error(`download of ${url} failed: HTTP ${response.status}`);
+    const header = Number(response.headers.get('content-length'));
+    const total = Number.isSafeInteger(header) && header > 0 ? header : null;
+    const chunks = [];
+    let received = 0;
+    progress(0, total);
+    for await (const chunk of response.body) {
+        chunks.push(chunk);
+        received += chunk.byteLength;
+        progress(received, total);
+    }
+    return Buffer.concat(chunks);
+}
+/** @throws when the bytes do not match a `sha512-<base64>` integrity value. */
+export function checkIntegrity(bytes, integrity, name) {
+    const expected = /^sha512-([A-Za-z0-9+/]+={0,2})$/.exec(integrity)?.[1];
+    if (expected === undefined)
+        throw new Error(`${name}: unsupported integrity ${integrity}`);
+    const actual = createHash('sha512').update(bytes).digest('base64');
+    if (actual !== expected)
+        throw new Error(`${name}: the download does not match its published integrity`);
+}
+/**
+ * @throws when an npm tarball member is absolute, climbs out of `package/`, or is a link.
+ * npm tarballs hold one top folder (usually `package/`); it is stripped on extraction.
+ */
+export function checkMembers(listing, name) {
+    const members = listing.split(/\r?\n/).filter(line => line !== '');
+    if (members.length === 0)
+        throw new Error(`${name}: the archive is empty`);
+    const top = members[0].split('/')[0];
+    for (const member of members) {
+        const parts = member.split('/');
+        if (member.startsWith('/') || /^[A-Za-z]:/.test(member) || member.includes('\\') || parts.includes('..') || parts[0] !== top) {
+            throw new Error(`${name}: the archive member ${JSON.stringify(member)} is outside its package folder`);
+        }
+    }
+}
+/**
+ * Install `packages` below `nodeModules`, each package folder replaced whole.
+ * @param progress - bytes of the package downloading now, with its index.
+ */
+export async function installPackages(packages, nodeModules, scratch, signal, progress) {
+    await mkdir(scratch, { recursive: true });
+    for (const [index, pkg] of packages.entries()) {
+        const bytes = await download(pkg.tarball, signal, (received, total) => { progress(index, received, total); });
+        checkIntegrity(bytes, pkg.integrity, pkg.name);
+        const file = `${pkg.name.replace('/', '__')}-${pkg.version}.tgz`;
+        await writeFile(path.join(scratch, file), bytes);
+        // Run beside the archive with relative names, so a GNU tar on PATH never reads a drive colon as a host.
+        const tar = (args) => run('tar', args, { cwd: scratch, maxBuffer: 64 * 1024 * 1024, signal });
+        const { stdout } = await tar(['-tzf', `./${file}`]);
+        checkMembers(stdout, pkg.name);
+        // Symbolic and hard links are refused by listing their types as well.
+        const { stdout: verbose } = await tar(['-tvzf', `./${file}`]);
+        if (verbose.split(/\r?\n/).some(line => /^[lh]/.test(line)))
+            throw new Error(`${pkg.name}: the archive contains links`);
+        const target = packageDir(nodeModules, pkg.name);
+        await rm(target, { recursive: true, force: true });
+        await mkdir(target, { recursive: true });
+        const relative = path.relative(scratch, target).split(path.sep).join('/');
+        await tar(['-xzf', `./${file}`, '-C', relative, '--strip-components=1']);
+    }
+}

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

@@ -0,0 +1,79 @@
+/**
+ * LuaSkills runtime settings. Fields, defaults and limits follow VulcanCode's
+ * `luaskills-runtime-setting.json`; the settings file belongs to this plugin and is written only
+ * when the user saves. A missing file means the defaults, held in memory.
+ */
+/** One VM pool: the size it keeps warm, the size it may grow to, and how long an idle VM lives. */
+export interface PoolSettings {
+    readonly minSize: number;
+    readonly maxSize: number;
+    readonly idleTtlSecs: number;
+}
+export interface LuaSkillsSettings {
+    /** The main pool skill calls run in. */
+    readonly vmPool: PoolSettings;
+    /** The isolated pool `runLua` runs in. */
+    readonly runLuaPool: PoolSettings;
+    readonly toolCache: {
+        readonly maxEntries: number;
+        readonly defaultTtlSecs: number;
+        readonly maxTtlSecs: number;
+    };
+    readonly managedRuntime: {
+        readonly workerPoolMaxSizePerEnvironment: number;
+        readonly workerIdleTtlSecs: number;
+        readonly persistentSessionLimitPerEngine: number;
+        readonly persistentSessionDefaultBufferLimitBytesPerStream: number;
+        readonly invokeDefaultTimeoutMs: number;
+    };
+    readonly capabilities: {
+        /** Null leaves the choice to LuaSkills. */
+        readonly defaultTextEncoding: TextEncoding | null;
+        readonly enableSkillManagementBridge: boolean;
+        readonly enableManagedIoCompat: boolean;
+    };
+    readonly network: {
+        readonly allowDownloads: boolean;
+        /** Null uses `https://github.com`. */
+        readonly githubBaseUrl: string | null;
+        /** Null uses `https://api.github.com`. */
+        readonly githubApiBaseUrl: string | null;
+        readonly officialSkillHubBaseUrl: string;
+    };
+}
+export declare const TEXT_ENCODINGS: readonly ["utf-8", "system", "oem", "gbk", "gb18030", "latin1", "base64"];
+export type TextEncoding = (typeof TEXT_ENCODINGS)[number];
+export declare const DEFAULT_SETTINGS: LuaSkillsSettings;
+export declare class SettingsError extends Error {
+    readonly code = "invalid_settings";
+}
+/**
+ * Check a whole settings value: every field present, nothing extra, counts positive whole
+ * numbers, every maximum at least its minimum, URLs absolute http(s).
+ * @throws SettingsError naming the first offending field.
+ */
+export declare function parseSettings(value: unknown): LuaSkillsSettings;
+/** What reading the settings file found. */
+export type LoadedSettings = {
+    readonly kind: 'defaults';
+    readonly settings: LuaSkillsSettings;
+} | {
+    readonly kind: 'saved';
+    readonly settings: LuaSkillsSettings;
+} | {
+    readonly kind: 'invalid';
+    readonly settings: LuaSkillsSettings;
+    readonly error: string;
+};
+/**
+ * Read the settings file. An unreadable file is reported and the defaults are used in memory;
+ * the file is left untouched so nothing the user wrote is lost.
+ */
+export declare function loadSettings(file: string): LoadedSettings;
+/** Write the settings file whole, through a temporary file so a crash leaves the old one. */
+export declare function saveSettings(file: string, settings: LuaSkillsSettings): void;
+/** The engine options a settings value turns into, in the SDK's wire names. */
+export declare function engineOptions(settings: LuaSkillsSettings): {
+    poolConfig: Record<string, unknown>;
+    hostOptions: Record<string, unknown>;
+};

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

@@ -0,0 +1,165 @@
+/**
+ * LuaSkills runtime settings. Fields, defaults and limits follow VulcanCode's
+ * `luaskills-runtime-setting.json`; the settings file belongs to this plugin and is written only
+ * when the user saves. A missing file means the defaults, held in memory.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { HUB_SITES } from './constants.js';
+export const TEXT_ENCODINGS = ['utf-8', 'system', 'oem', 'gbk', 'gb18030', 'latin1', 'base64'];
+export const DEFAULT_SETTINGS = {
+    vmPool: { minSize: 4, maxSize: 8, idleTtlSecs: 60 },
+    runLuaPool: { minSize: 1, maxSize: 4, idleTtlSecs: 30 },
+    toolCache: { maxEntries: 1000, defaultTtlSecs: 1800, maxTtlSecs: 1800 },
+    managedRuntime: {
+        workerPoolMaxSizePerEnvironment: 4,
+        workerIdleTtlSecs: 60,
+        persistentSessionLimitPerEngine: 256,
+        persistentSessionDefaultBufferLimitBytesPerStream: 1_048_576,
+        invokeDefaultTimeoutMs: 60_000,
+    },
+    capabilities: { defaultTextEncoding: null, enableSkillManagementBridge: false, enableManagedIoCompat: true },
+    network: { allowDownloads: true, githubBaseUrl: null, githubApiBaseUrl: null, officialSkillHubBaseUrl: HUB_SITES[0].url },
+};
+export class SettingsError extends Error {
+    code = 'invalid_settings';
+}
+const POOL = { minSize: 'count', maxSize: 'count', idleTtlSecs: 'count' };
+const SHAPE = {
+    vmPool: POOL,
+    runLuaPool: POOL,
+    toolCache: { maxEntries: 'count', defaultTtlSecs: 'count', maxTtlSecs: 'count' },
+    managedRuntime: {
+        workerPoolMaxSizePerEnvironment: 'count',
+        workerIdleTtlSecs: 'count',
+        persistentSessionLimitPerEngine: 'count',
+        persistentSessionDefaultBufferLimitBytesPerStream: 'count',
+        invokeDefaultTimeoutMs: 'count',
+    },
+    capabilities: { defaultTextEncoding: 'encoding', enableSkillManagementBridge: 'boolean', enableManagedIoCompat: 'boolean' },
+    network: { allowDownloads: 'boolean', githubBaseUrl: 'optional-url', githubApiBaseUrl: 'optional-url', officialSkillHubBaseUrl: 'url' },
+};
+/**
+ * Check a whole settings value: every field present, nothing extra, counts positive whole
+ * numbers, every maximum at least its minimum, URLs absolute http(s).
+ * @throws SettingsError naming the first offending field.
+ */
+export function parseSettings(value) {
+    check(value, SHAPE, 'settings');
+    const settings = value;
+    for (const [name, pool] of [['vmPool', settings.vmPool], ['runLuaPool', settings.runLuaPool]]) {
+        if (pool.maxSize < pool.minSize)
+            throw new SettingsError(`${name}.maxSize must be at least ${name}.minSize`);
+    }
+    if (settings.toolCache.maxTtlSecs < settings.toolCache.defaultTtlSecs) {
+        throw new SettingsError('toolCache.maxTtlSecs must be at least toolCache.defaultTtlSecs');
+    }
+    return settings;
+}
+function check(value, shape, at) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new SettingsError(`${at} must be an object`);
+    const record = value;
+    for (const key of Object.keys(record)) {
+        if (!(key in shape))
+            throw new SettingsError(`${at}.${key} is not a setting`);
+    }
+    for (const [key, kind] of Object.entries(shape)) {
+        const field = record[key];
+        const name = `${at}.${key}`;
+        if (typeof kind === 'object') {
+            check(field, kind, name);
+        }
+        else if (kind === 'count') {
+            if (!Number.isSafeInteger(field) || field <= 0)
+                throw new SettingsError(`${name} must be a whole number above zero`);
+        }
+        else if (kind === 'boolean') {
+            if (typeof field !== 'boolean')
+                throw new SettingsError(`${name} must be true or false`);
+        }
+        else if (kind === 'encoding') {
+            if (field !== null && !TEXT_ENCODINGS.includes(field)) {
+                throw new SettingsError(`${name} must be null or one of ${TEXT_ENCODINGS.join(', ')}`);
+            }
+        }
+        else if (!(kind === 'optional-url' && field === null) && !isHttpUrl(field)) {
+            throw new SettingsError(`${name} must be an absolute http or https URL`);
+        }
+    }
+}
+function isHttpUrl(value) {
+    if (typeof value !== 'string')
+        return false;
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:' || url.protocol === 'http:';
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the settings file. An unreadable file is reported and the defaults are used in memory;
+ * the file is left untouched so nothing the user wrote is lost.
+ */
+export function loadSettings(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return { kind: 'defaults', settings: DEFAULT_SETTINGS };
+        return { kind: 'invalid', settings: DEFAULT_SETTINGS, error: messageOf(error) };
+    }
+    try {
+        return { kind: 'saved', settings: parseSettings(JSON.parse(raw)) };
+    }
+    catch (error) {
+        return { kind: 'invalid', settings: DEFAULT_SETTINGS, error: `${file}: ${messageOf(error)}` };
+    }
+}
+/** Write the settings file whole, through a temporary file so a crash leaves the old one. */
+export function saveSettings(file, settings) {
+    mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    renameSync(temporary, file);
+}
+/** The engine options a settings value turns into, in the SDK's wire names. */
+export function engineOptions(settings) {
+    const pool = (value) => ({ min_size: value.minSize, max_size: value.maxSize, idle_ttl_secs: value.idleTtlSecs });
+    const managed = settings.managedRuntime;
+    return {
+        poolConfig: pool(settings.vmPool),
+        hostOptions: {
+            runlua_pool_config: pool(settings.runLuaPool),
+            cache_config: {
+                max_entries: settings.toolCache.maxEntries,
+                default_ttl_secs: settings.toolCache.defaultTtlSecs,
+                max_ttl_secs: settings.toolCache.maxTtlSecs,
+            },
+            managed_runtime_config: {
+                worker_pool_max_size_per_environment: managed.workerPoolMaxSizePerEnvironment,
+                worker_idle_ttl_secs: managed.workerIdleTtlSecs,
+                persistent_session_limit_per_engine: managed.persistentSessionLimitPerEngine,
+                persistent_session_default_buffer_limit_bytes_per_stream: managed.persistentSessionDefaultBufferLimitBytesPerStream,
+                invoke_default_timeout_ms: managed.invokeDefaultTimeoutMs,
+            },
+            capabilities: {
+                enable_skill_management_bridge: settings.capabilities.enableSkillManagementBridge,
+                enable_managed_io_compat: settings.capabilities.enableManagedIoCompat,
+            },
+            // Read by the Rust core although the SDK's TypeScript type does not list them.
+            ...settings.capabilities.defaultTextEncoding === null ? {} : { default_text_encoding: settings.capabilities.defaultTextEncoding },
+            official_skill_hub_base_url: settings.network.officialSkillHubBaseUrl,
+            allow_network_download: settings.network.allowDownloads,
+            github_base_url: settings.network.githubBaseUrl,
+            github_api_base_url: settings.network.githubApiBaseUrl,
+        },
+    };
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

@@ -0,0 +1,34 @@
+/**
+ * What is installed in the ROOT and USER skill layers, read from the runtime's folders: the
+ * skill folders themselves, their `skill.yaml` name and version, the install record and whether
+ * the skill is disabled. Reading changes nothing.
+ */
+/** The layers this plugin manages; PROJECT skills are left to the project. */
+export declare const LAYERS: readonly [{
+    readonly root: "ROOT";
+    readonly folder: "root_skills";
+}, {
+    readonly root: "USER";
+    readonly folder: "user_skills";
+}];
+export type Layer = (typeof LAYERS)[number]['root'];
+export interface InstalledSkill {
+    readonly skillId: string;
+    readonly root: Layer;
+    readonly name: string;
+    readonly version: string;
+    readonly enabled: boolean;
+    /** Where it was installed from, when an install recorded it. */
+    readonly source?: {
+        readonly type: string;
+        readonly locator: string;
+    };
+}
+/** Top-level `key: value` scalars of a small YAML document; nested blocks are skipped. */
+export declare function topLevelScalars(text: string): Map<string, string>;
+/** `source_type` and `locator` from the `source:` block of an install record. */
+export declare function installSource(text: string): {
+    type: string;
+    locator: string;
+} | undefined;
+export declare function listInstalled(runtimeRoot: string): InstalledSkill[];