@vesk/adapter 0.2.10 → 0.2.12

package/dist/dev-api.js

@@ -0,0 +1,338 @@
+/**
+ * DevTools API router — `createDevApiRouter` (B2 of plans/devtools.md).
+ *
+ * A self-contained, dependency-injectable router for ALL dev-panel HTTP
+ * endpoints under `/__vesk/*`. It generalizes the earlier plugin-only router
+ * into a capability-scoped surface:
+ *
+ *     config       GET/POST /__vesk/config
+ *     plugins      GET /__vesk/plugins + POST activate/deactivate/install/
+ *                  uninstall/update + GET search/icon/exports
+ *     diagnostics  GET /__vesk/diagnostics
+ *     build        POST /__vesk/build
+ *     file.read    GET  /__vesk/file?path=
+ *     command      POST /__vesk/command
+ *
+ * ARCHITECTURE: the Dev Server is the ONLY path from browser → project files /
+ * build system. Every endpoint is gated by a capability in `CapabilityTable`
+ * (server-enforced — the browser cannot bypass it). There is NO raw
+ * `child_process` reach: commands route through the gated, allowlisted
+ * `runCommand` hook, and file access is read-only + containment-checked.
+ *
+ * Pure (fake injectable inputs, no socket/listener), mirroring the shape of
+ * `createPluginStateRouter`: returns `{ route(method, pathname, body, search) }`,
+ * yielding `null` for non-`/__vesk/*` paths so the dev server falls through.
+ */
+import { readFileSync, statSync, existsSync, readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getPluginRecords, setPluginActive, installPlugin, uninstallPlugin, updatePlugin, enrichPluginRecords, searchPlugins, introspectPlugin, findPluginIcon, } from './plugins';
+import { readConfig, writeConfigSource, applyConfigToggle, findConfigFile, addPluginToConfig, removePluginFromConfig } from './dev-config';
+import { resolveWithin } from './paths';
+/** Default DevTools capability set — `command` is gated off by default. */
+export const DEFAULT_CAPABILITIES = {
+    'config.read': true,
+    'config.write': true,
+    'plugins': true,
+    'diagnostics': true,
+    'build': true,
+    'file.read': true,
+    'command': false,
+};
+/** Gated-command allowlist (read-only/status commands only by default). */
+export const DEFAULT_COMMAND_ALLOWLIST = [
+    /^node -v$/,
+    /^npm -v$/,
+    /^git status/,
+    /^git log/,
+    /^git branch/,
+    /^pwd$/,
+    /^ls($|\s)/,
+    /^cat($|\s)/,
+    /^head($|\s)/,
+];
+/** Server-enforced capability/permission table. */
+export class CapabilityTable {
+    caps;
+    commandAllowlist;
+    constructor(caps, commandAllowlist = DEFAULT_COMMAND_ALLOWLIST) {
+        this.caps = { ...DEFAULT_CAPABILITIES, ...(caps || {}) };
+        this.commandAllowlist = commandAllowlist;
+    }
+    allows(cap) {
+        return this.caps[cap] === true;
+    }
+    commandAllowed(argv) {
+        const joined = argv.join(' ');
+        return this.commandAllowlist.some((re) => re.test(joined));
+    }
+}
+function jsonStatus(status, data) {
+    return { status, headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(data) };
+}
+/**
+ * Build the unified DevTools API router. Exportable and dependency-injectable
+ * so the adapter + CLI dev servers can both route through it.
+ */
+export function createDevApiRouter(opts) {
+    const veskDir = opts.veskDir;
+    const caps = new CapabilityTable(opts.caps, opts.commandAllowlist);
+    const projectDir = opts.projectDir || resolve(opts.appDir, '..');
+    const getState = opts.getHmrState || (() => ({ status: 'up', lastCompileMs: null, error: null, hasError: false, componentCount: 0 }));
+    function denied(cap) {
+        return jsonStatus(403, { error: `capability denied: ${cap}` });
+    }
+    function badRequest(message) {
+        return jsonStatus(400, { error: message });
+    }
+    async function onChanged(event) {
+        if (typeof opts.onPluginChange === 'function')
+            await opts.onPluginChange(event);
+    }
+    async function route(method, pathname, body, search) {
+        // ── HMR state ──────────────────────────────────────────────────────────
+        if (pathname === '/__vesk/hmr/state') {
+            if (method !== 'GET' && method !== 'HEAD')
+                return jsonStatus(405, { error: 'method not allowed' });
+            return jsonStatus(200, getState());
+        }
+        // ── Config (B1) ────────────────────────────────────────────────────────
+        if (pathname === '/__vesk/config' && method === 'GET') {
+            if (!caps.allows('config.read'))
+                return denied('config.read');
+            try {
+                const cfg = await readConfig(projectDir);
+                return jsonStatus(200, { path: cfg.path, exists: cfg.exists, source: cfg.source, config: cfg.config });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/config' && method === 'POST') {
+            if (!caps.allows('config.write'))
+                return denied('config.write');
+            const b = (body || {});
+            try {
+                if (typeof b.source === 'string') {
+                    const cfg = await writeConfigSource(projectDir, b.source);
+                    return jsonStatus(200, { ok: true, path: cfg.path, source: cfg.source, config: cfg.config });
+                }
+                if (typeof b.key === 'string' && b.key) {
+                    const { path, isTs } = findConfigFile(projectDir);
+                    if (!path)
+                        return badRequest('no vesk.config file to edit');
+                    if (!isTs)
+                        return badRequest('single-key toggle edits only apply to vesk.config.ts (use the source editor for .js)');
+                    const patched = applyConfigToggle(readFileSync(path, 'utf-8'), b.key, b.value);
+                    if (patched === null)
+                        return badRequest('could not safely edit the config object; use the source editor');
+                    const cfg = await writeConfigSource(projectDir, patched);
+                    return jsonStatus(200, { ok: true, path: cfg.path, source: cfg.source, config: cfg.config });
+                }
+                return badRequest('expected { source } or { key, value }');
+            }
+            catch (e) {
+                return jsonStatus(400, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        // ── Diagnostics (B3) ───────────────────────────────────────────────────
+        if (pathname === '/__vesk/diagnostics' && method === 'GET') {
+            if (!caps.allows('diagnostics'))
+                return denied('diagnostics');
+            const list = typeof opts.getDiagnostics === 'function' ? opts.getDiagnostics() : [];
+            return jsonStatus(200, { diagnostics: list });
+        }
+        // ── Build ──────────────────────────────────────────────────────────────
+        if (pathname === '/__vesk/build' && method === 'POST') {
+            if (!caps.allows('build'))
+                return denied('build');
+            if (typeof opts.rebuild !== 'function')
+                return jsonStatus(503, { error: 'build hook unavailable' });
+            try {
+                const result = await opts.rebuild();
+                return jsonStatus(200, { ok: result.ok, error: result.error || null, ms: result.ms ?? null });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        // ── Read-only file access (B2) ─────────────────────────────────────────
+        if (pathname === '/__vesk/file' && method === 'GET') {
+            if (!caps.allows('file.read'))
+                return denied('file.read');
+            const target = new URLSearchParams(search ?? '').get('path') || '';
+            if (!target)
+                return badRequest('missing "path" query param');
+            try {
+                const resolved = resolveWithin(projectDir, target);
+                if (!resolved)
+                    return jsonStatus(403, { error: 'path escapes project root' });
+                if (!existsSync(resolved))
+                    return jsonStatus(404, { error: 'not found' });
+                if (statSync(resolved).isDirectory()) {
+                    const entries = readdirSync(resolved, { withFileTypes: true }).map((e) => e.name);
+                    return jsonStatus(200, { ok: true, path: target, directory: true, entries });
+                }
+                if (statSync(resolved).isFile()) {
+                    return jsonStatus(200, { ok: true, path: target, directory: false, content: readFileSync(resolved, 'utf-8') });
+                }
+                return badRequest('unsupported file type');
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        // ── Gated command runner (B2) ──────────────────────────────────────────
+        if (pathname === '/__vesk/command' && method === 'POST') {
+            if (!caps.allows('command'))
+                return denied('command');
+            const b = (body || {});
+            const argv = Array.isArray(b.argv) ? b.argv.filter((a) => typeof a === 'string') : [];
+            if (argv.length === 0)
+                return badRequest('expected { argv: string[] }');
+            if (!caps.commandAllowed(argv))
+                return jsonStatus(403, { error: 'command not in allowlist' });
+            if (typeof opts.runCommand !== 'function')
+                return jsonStatus(503, { error: 'command runner unavailable' });
+            try {
+                const result = await opts.runCommand(argv);
+                return jsonStatus(200, { ok: result.ok, code: result.code, stdout: result.stdout, stderr: result.stderr });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        // ── Plugins (existing surface, capability-gated) ───────────────────────
+        if (pathname === '/__vesk/plugins' && method === 'GET') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            try {
+                const records = await enrichPluginRecords(getPluginRecords(opts.appDir, veskDir, opts.configPluginNames));
+                return jsonStatus(200, { plugins: records });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/activate' && method === 'POST') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const name = body?.name;
+            if (typeof name !== 'string' || !name)
+                return badRequest('missing "name" in body');
+            try {
+                setPluginActive(veskDir, name, true);
+                const record = getPluginRecords(opts.appDir, veskDir, opts.configPluginNames).find((r) => r.name === name);
+                await onChanged({ type: 'activate', name });
+                return jsonStatus(200, { ok: true, record: record || null });
+            }
+            catch (e) {
+                return jsonStatus(400, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/deactivate' && method === 'POST') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const name = body?.name;
+            if (typeof name !== 'string' || !name)
+                return badRequest('missing "name" in body');
+            try {
+                setPluginActive(veskDir, name, false);
+                const record = getPluginRecords(opts.appDir, veskDir, opts.configPluginNames).find((r) => r.name === name);
+                await onChanged({ type: 'deactivate', name });
+                return jsonStatus(200, { ok: true, record: record || null });
+            }
+            catch (e) {
+                return jsonStatus(400, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/install' && method === 'POST') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const pkg = body?.package;
+            if (typeof pkg !== 'string' || !pkg)
+                return badRequest('missing "package" in body');
+            try {
+                const record = await installPlugin(opts.appDir, veskDir, pkg);
+                // auto-register in vesk.config.ts (best-effort, does not fail install)
+                try {
+                    await addPluginToConfig(projectDir, pkg);
+                }
+                catch { }
+                await onChanged({ type: 'install', name: record.name });
+                return jsonStatus(200, { ok: true, record });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/uninstall' && method === 'POST') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const pkg = body?.package;
+            if (typeof pkg !== 'string' || !pkg)
+                return badRequest('missing "package" in body');
+            try {
+                await uninstallPlugin(opts.appDir, veskDir, pkg);
+                // auto-remove from vesk.config.ts (best-effort, surgical) + npm uninstall already done in uninstallPlugin
+                try {
+                    await removePluginFromConfig(projectDir, pkg);
+                }
+                catch { }
+                await onChanged({ type: 'uninstall', name: pkg });
+                return jsonStatus(200, { ok: true });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/update' && method === 'POST') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const pkg = body?.package;
+            if (typeof pkg !== 'string' || !pkg)
+                return badRequest('missing "package" in body');
+            try {
+                const record = await updatePlugin(opts.appDir, veskDir, pkg);
+                await onChanged({ type: 'update', name: record.name });
+                return jsonStatus(200, { ok: true, record });
+            }
+            catch (e) {
+                return jsonStatus(500, { error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+        if (pathname === '/__vesk/plugins/search' && method === 'GET') {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const q = new URLSearchParams(search ?? '').get('q') ?? '';
+            const results = await searchPlugins(q);
+            return jsonStatus(200, { results });
+        }
+        const perPlugin = /^\/__vesk\/plugins\/([^/]+)\/(icon|exports)$/.exec(pathname);
+        if (perPlugin) {
+            if (!caps.allows('plugins'))
+                return denied('plugins');
+            const pluginName = decodeURIComponent(perPlugin[1]);
+            if (perPlugin[2] === 'icon') {
+                if (method !== 'GET' && method !== 'HEAD')
+                    return jsonStatus(405, { error: 'method not allowed' });
+                const icon = findPluginIcon(opts.appDir, pluginName);
+                if (!icon)
+                    return jsonStatus(404, { error: `no icon for plugin "${pluginName}"` });
+                return {
+                    status: 200,
+                    headers: { 'Content-Type': icon.mime, 'Cache-Control': 'private, max-age=60' },
+                    body: readFileSync(icon.file).toString('base64'),
+                    encoding: 'base64',
+                };
+            }
+            if (method !== 'GET' && method !== 'HEAD')
+                return jsonStatus(405, { error: 'method not allowed' });
+            return jsonStatus(200, introspectPlugin(opts.appDir, pluginName));
+        }
+        if (pathname.startsWith('/__vesk/')) {
+            return jsonStatus(404, { error: 'Not found' });
+        }
+        return null;
+    }
+    return { route };
+}

package/dist/dev-config.d.ts

@@ -0,0 +1,48 @@
+import type { VeskConfig } from '@vesk/types';
+export interface ConfigReadResult {
+    path: string | null;
+    exists: boolean;
+    source: string;
+    config: VeskConfig;
+}
+export interface ConfigFileInfo {
+    path: string | null;
+    isTs: boolean;
+}
+/** Locate the project's config file (vesk.config.ts preferred, then .js). */
+export declare function findConfigFile(projectDir: string): ConfigFileInfo;
+/**
+ * Transpile+parse a config source into a validated VeskConfig. Shared by read
+ * and write paths so they agree on what "valid" means. Host code is executed
+ * in an isolated temp module so edits re-evaluate fresh on every call.
+ */
+export declare function parseConfigSource(source: string, isTs: boolean, projectDir?: string): Promise<VeskConfig>;
+/** Read + parse the project config. Throws on an invalid config. */
+export declare function readConfig(projectDir: string): Promise<ConfigReadResult>;
+/**
+ * Write a full new config source back, after validation. Guarantees an invalid
+ * config never clobbers the file (throws before writing).
+ */
+export declare function writeConfigSource(projectDir: string, source: string): Promise<ConfigReadResult>;
+/**
+ * Apply a single `key` → `value` toggle to a `vesk.config.ts` source by
+ * editing the object literal passed to `defineConfig(...)`, preserving all
+ * other formatting/comments. Returns the new source, or `null` when there is
+ * no safe literal-edit point (caller falls back to the direct editor).
+ */
+export declare function applyConfigToggle(source: string, key: string, value: unknown): string | null;
+/** Derive a safe import identifier for a package spec. `importNameForPackage('@vesk/plugin-tailwind')` -> `tailwindcss` (known) else `myPlugin` etc. */
+export declare function importNameForPackage(pkg: string): string;
+/**
+ * Surgically add a plugin import + `plugins: [...]` entry to `vesk.config.ts`.
+ * Idempotent - no duplicate import/entry if already present. Validates via
+ * `parseConfigSource` before writing so an invalid file is never clobbered.
+ * Uses AST for all syntax analysis (no regex for import/plugins detection).
+ */
+export declare function addPluginToConfig(projectDir: string, pkg: string): Promise<void>;
+/**
+ * Surgically remove a plugin's import and its `plugins: [...]` entry.
+ * Returns true if file was changed. Uses AST for import/plugins detection.
+ */
+export declare function removePluginFromConfig(projectDir: string, pkg: string): Promise<boolean>;
+//# sourceMappingURL=dev-config.d.ts.map

package/dist/dev-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-config.d.ts","sourceRoot":"","sources":["../src/dev-config.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,UAAU,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,6EAA6E;AAC7E,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,cAAc,CAMjE;AAQD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAmC/G;AAED,oEAAoE;AACpE,wBAAsB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAM9E;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAQrG;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAc5F;AAoID,wJAAwJ;AACxJ,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAcxD;AAyYD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA2EtF;AAED;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAqC9F"}