@alisio/server 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import { type AppOptions } from "@alisio/core";
 import { type FolderPicker } from "./host/folder-picker.ts";
 import { type ServerAppOptions } from "./host/workspace-host.ts";
 import { type Logger } from "./log.ts";
+import { type CatalogServiceOptions } from "./plugins/catalog-service.ts";
 export { isLoopbackHost } from "./auth/guard.ts";
 export { ApprovalBridge } from "./bridges/approval-bridge.ts";
 export { InteractionBridge } from "./bridges/interaction-bridge.ts";
@@ -12,6 +13,11 @@ export { HttpError } from "./http/errors.ts";
 export { contentSecurityPolicy, PLACEHOLDER_HTML } from "./http/static.ts";
 export { createLogger, type Logger, type LogLevel, logLevel } from "./log.ts";
 export { PROTOCOL_VERSION } from "./routes/health.ts";
+/**
+ * Exit code of a host that restarts on request (`POST /api/server/restart`): its supervisor (the
+ * desktop app) takes it as "start me again", not as a crash. 75 is `EX_TEMPFAIL`.
+ */
+export declare const RESTART_EXIT_CODE = 75;
 export interface ServerOptions {
     /** Bind address (default `127.0.0.1`). Anything but loopback requires `allowRemote`. */
     host?: string;
@@ -64,6 +70,25 @@ export interface ServerOptions {
         timeoutMs?: number;
         maxBytes?: number;
     };
+    /**
+     * Restart on request. `supervised` (default: env `ALISIO_SUPERVISED=1`, set by the desktop app)
+     * says a supervisor respawns this process when it exits with `RESTART_EXIT_CODE`. `exit`
+     * replaces the default (close the server, then `process.exit`) for tests.
+     */
+    restart?: {
+        supervised?: boolean;
+        exit?: (code: number) => void;
+    };
+    /**
+     * Plugin catalog knobs (the CLI leaves them alone; tests inject a fake catalog, npm and fetch):
+     * catalog URL (else `ALISIO_PLUGIN_CATALOG_URL`), cache TTL, fetch, clock and SDK version.
+     */
+    pluginCatalog?: CatalogServiceOptions & {
+        installRunner?: import("@alisio/core").InstallRunner;
+        sdkVersion?: string;
+        maxUploadBytes?: number;
+        jobTtlMs?: number;
+    };
     /** Background-task runtime knobs (notification timing, kill grace, limits): tests tune them. */
     tasks?: Pick<NonNullable<AppOptions["tasks"]>, "timing" | "sweepDelayMs" | "killGraceMs" | "maxPerProcess">;
 }

package/dist/index.js

@@ -21,6 +21,8 @@ import { HttpError, toApiError } from "./http/errors.js";
 import { Router } from "./http/router.js";
 import { StaticAssets } from "./http/static.js";
 import { createLogger } from "./log.js";
+import { CatalogService } from "./plugins/catalog-service.js";
+import { installedSdkVersion } from "./plugins/sdk-version.js";
 import { registerAgentDefinitionRoutes } from "./routes/agent-definitions.js";
 import { registerApprovalRoutes } from "./routes/approvals.js";
 import { registerArtifactViewRoutes, VIEW_PREFIX, viewerBaseHeaders, } from "./routes/artifact-view.js";
@@ -37,11 +39,13 @@ import { registerGoalRoutes } from "./routes/goal.js";
 import { registerHealthRoutes } from "./routes/health.js";
 import { registerIconThemeRoutes } from "./routes/icon-theme.js";
 import { registerManagementRoutes, WorkspaceRecycler } from "./routes/management.js";
+import { registerPluginCatalogRoutes } from "./routes/plugin-catalog.js";
 import { registerPluginViewRoutes } from "./routes/plugin-views.js";
 import { registerPromptRoutes } from "./routes/prompts.js";
 import { registerProofRoutes } from "./routes/proof.js";
 import { registerProviderRoutes } from "./routes/providers.js";
 import { registerScratchRoutes } from "./routes/scratch.js";
+import { registerRestartRoutes } from "./routes/server-restart.js";
 import { registerSessionViewRoutes } from "./routes/session-views.js";
 import { registerSessionRoutes } from "./routes/sessions.js";
 import { registerSideQuestionRoutes } from "./routes/side-questions.js";
@@ -58,6 +62,11 @@ export { HttpError } from "./http/errors.js";
 export { contentSecurityPolicy, PLACEHOLDER_HTML } from "./http/static.js";
 export { createLogger, logLevel } from "./log.js";
 export { PROTOCOL_VERSION } from "./routes/health.js";
+/**
+ * Exit code of a host that restarts on request (`POST /api/server/restart`): its supervisor (the
+ * desktop app) takes it as "start me again", not as a crash. 75 is `EX_TEMPFAIL`.
+ */
+export const RESTART_EXIT_CODE = 75;
 const REQUEST_ID = /^[A-Za-z0-9_-]{1,64}$/;
 /** Security headers of §11.2 (the CSP comes from the served web build). */
 function securityHeaders(res, csp, api) {
@@ -108,6 +117,7 @@ export async function startServer(options = {}) {
     // itself, the user decides.
     new GoalStore(catalog.db).pauseOrphans(Date.now());
     let shutdown;
+    let runningServer;
     let sessions;
     const inflight = new InflightTracker();
     let recycler;
@@ -444,6 +454,31 @@ export async function startServer(options = {}) {
     registerTaskRoutes(router, { sessions });
     registerApprovalRoutes(router, { approvals, interactions });
     registerManagementRoutes(router, management, recycler);
+    const supervised = options.restart?.supervised ?? process.env.ALISIO_SUPERVISED === "1";
+    registerRestartRoutes(router, {
+        ...(base.readOnly ? { readOnly: true } : {}),
+        ...(supervised
+            ? {
+                restart: () => {
+                    if (options.restart?.exit)
+                        return options.restart.exit(RESTART_EXIT_CODE);
+                    // After the response is out: stop cleanly, then leave for the supervisor to respawn.
+                    setTimeout(() => void runningServer?.close().finally(() => process.exit(RESTART_EXIT_CODE)), 100);
+                },
+            }
+            : {}),
+    });
+    {
+        const { installRunner, sdkVersion, maxUploadBytes, jobTtlMs, ...catalogOptions } = options.pluginCatalog ?? {};
+        const resolvedSdk = sdkVersion ?? installedSdkVersion();
+        registerPluginCatalogRoutes(router, management, recycler, {
+            service: new CatalogService(catalogOptions),
+            ...(resolvedSdk ? { sdkVersion: resolvedSdk } : {}),
+            ...(installRunner ? { installRunner } : {}),
+            ...(maxUploadBytes ? { maxUploadBytes } : {}),
+            ...(jobTtlMs ? { jobTtlMs } : {}),
+        });
+    }
     registerAgentDefinitionRoutes(router, management, recycler);
     registerProviderRoutes(router, management, recycler);
     registerEventRoutes(router, {
@@ -511,7 +546,9 @@ export async function startServer(options = {}) {
             // Every write is JSON (it forces a CORS preflight) except the raw image upload, which
             // checks its own image content types (also non-safelisted, so also preflighted).
             const upload = method === "POST" &&
-                (url.pathname === "/api/blobs" || /^\/api\/sessions\/[^/]+\/datasets$/.test(url.pathname));
+                (url.pathname === "/api/blobs" ||
+                    url.pathname === "/api/plugins/local/inspect" ||
+                    /^\/api\/sessions\/[^/]+\/datasets$/.test(url.pathname));
             if (!["GET", "HEAD", "OPTIONS"].includes(method) && !upload) {
                 const type = String(req.headers["content-type"] ?? "")
                     .split(";")[0]
@@ -566,7 +603,7 @@ export async function startServer(options = {}) {
     guard = new AuthGuard({ host, port, ...(options.token ? { token: options.token } : {}) });
     const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
     const url = `http://${displayHost.includes(":") ? `[${displayHost}]` : displayHost}:${port}`;
-    return {
+    runningServer = {
         host,
         port,
         url,
@@ -598,6 +635,7 @@ export async function startServer(options = {}) {
             return shutdown;
         },
     };
+    return runningServer;
 }
 /** Writes a JSON response. */
 export function sendJson(res, status, body) {

package/dist/plugins/catalog-schema.d.ts

@@ -0,0 +1,37 @@
+export declare const SUPPORTED_SCHEMA_VERSION = 1;
+export interface CatalogPlugin {
+    id: string;
+    slug: string;
+    name: string;
+    package: string;
+    version: string;
+    description: string;
+    categories: string[];
+    tags: string[];
+    /** The plugin's declared `@alisio/sdk` range. */
+    sdk?: string;
+    author?: string;
+    license?: string;
+    homepage?: string;
+    npmUrl?: string;
+    repository?: string;
+    publishedAt?: string;
+    featured: boolean;
+    /** Where the cover is fetched from (on the catalog origin); never sent to the browser. */
+    coverSource?: string;
+}
+export interface SanitizedCatalog {
+    generatedAt?: string;
+    categories: Array<{
+        id: string;
+        count: number;
+    }>;
+    plugins: CatalogPlugin[];
+}
+export declare function isLoopbackHostname(hostname: string): boolean;
+/** A plain `https:` URL without credentials (loopback `http:` is accepted only for tests/dev). */
+export declare function safeUrl(value: unknown, max?: number, allowHttpLoopback?: boolean): URL | undefined;
+/** Whether `url` is on the same origin as the catalog document itself. */
+export declare function sameOrigin(url: URL, catalogUrl: URL): boolean;
+/** Validates a parsed catalog document; throws a short error for an unusable document. */
+export declare function sanitizeCatalog(raw: unknown, catalogUrl: string): SanitizedCatalog;

package/dist/plugins/catalog-schema.js

@@ -0,0 +1,141 @@
+/**
+ * Validation and sanitization of the published plugin catalog (`catalog.json`). The catalog is
+ * remote, untrusted data: every field is type-checked and length-capped, links must be `https:`,
+ * the cover must live on the catalog's own origin, and an entry with an invalid npm name or
+ * version is dropped. Counts are recomputed, never trusted.
+ */
+import { comparePluginVersions, parsePluginSpec } from "@alisio/core";
+export const SUPPORTED_SCHEMA_VERSION = 1;
+const MAX_PLUGINS = 500;
+const SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const TAG_RE = /^[\p{L}\p{N}][\p{L}\p{N} ._+#/-]{0,39}$/u;
+const isRecord = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+function text(value, max) {
+    if (typeof value !== "string")
+        return undefined;
+    // Control characters have no place in a catalog label.
+    const cleaned = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+    return cleaned.length > 0 && cleaned.length <= max ? cleaned : undefined;
+}
+export function isLoopbackHostname(hostname) {
+    return (hostname === "localhost" ||
+        hostname === "127.0.0.1" ||
+        hostname === "[::1]" ||
+        hostname === "::1");
+}
+/** A plain `https:` URL without credentials (loopback `http:` is accepted only for tests/dev). */
+export function safeUrl(value, max = 500, allowHttpLoopback = false) {
+    if (typeof value !== "string" || value.length > max)
+        return undefined;
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.username || url.password)
+        return undefined;
+    if (url.protocol === "https:")
+        return url;
+    if (url.protocol === "http:" && allowHttpLoopback && isLoopbackHostname(url.hostname))
+        return url;
+    return undefined;
+}
+/** Whether `url` is on the same origin as the catalog document itself. */
+export function sameOrigin(url, catalogUrl) {
+    return url.origin === catalogUrl.origin;
+}
+function stringList(value, itemMax, cap, pattern) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const item of value) {
+        const entry = text(item, itemMax);
+        if (!entry || (pattern && !pattern.test(entry)) || out.includes(entry))
+            continue;
+        out.push(entry);
+        if (out.length >= cap)
+            break;
+    }
+    return out;
+}
+function sanitizePlugin(raw, catalogUrl, loopbackOk) {
+    if (!isRecord(raw))
+        return undefined;
+    const slug = text(raw.slug, 64);
+    const name = text(raw.name, 100);
+    const pkg = text(raw.package, 214);
+    const version = text(raw.version, 64);
+    if (!slug || !SLUG_RE.test(slug) || !name || !pkg || !version)
+        return undefined;
+    if (comparePluginVersions(version, version) === undefined)
+        return undefined;
+    try {
+        const parsed = parsePluginSpec(pkg);
+        if (parsed.version !== undefined || parsed.name !== pkg)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    const link = (value) => safeUrl(value, 500, loopbackOk)?.href;
+    const cover = safeUrl(raw.cover, 500, loopbackOk);
+    const sdk = text(raw.sdk, 60);
+    const author = text(raw.author, 100);
+    const license = text(raw.license, 60);
+    const homepage = link(raw.homepage);
+    const npmUrl = link(raw.npmUrl);
+    const repository = link(raw.repository);
+    const publishedAt = text(raw.publishedAt, 40);
+    return {
+        id: text(raw.id, 100) ?? slug,
+        slug,
+        name,
+        package: pkg,
+        version,
+        description: text(raw.description, 600) ?? "",
+        categories: stringList(raw.categories, 40, 8, /^[a-z0-9][a-z0-9-]*$/),
+        tags: stringList(raw.tags, 40, 12, TAG_RE),
+        ...(sdk ? { sdk } : {}),
+        ...(author ? { author } : {}),
+        ...(license ? { license } : {}),
+        ...(homepage ? { homepage } : {}),
+        ...(npmUrl ? { npmUrl } : {}),
+        ...(repository ? { repository } : {}),
+        ...(publishedAt ? { publishedAt } : {}),
+        featured: raw.featured === true,
+        ...(cover && sameOrigin(cover, catalogUrl) ? { coverSource: cover.href } : {}),
+    };
+}
+/** Validates a parsed catalog document; throws a short error for an unusable document. */
+export function sanitizeCatalog(raw, catalogUrl) {
+    if (!isRecord(raw))
+        throw new Error("The plugin catalog is not a JSON object");
+    if (raw.schemaVersion !== SUPPORTED_SCHEMA_VERSION)
+        throw new Error(`Unsupported plugin catalog schema version (expected ${SUPPORTED_SCHEMA_VERSION})`);
+    if (!Array.isArray(raw.plugins))
+        throw new Error("The plugin catalog has no plugin list");
+    const base = new URL(catalogUrl);
+    const loopbackOk = base.protocol === "http:" && isLoopbackHostname(base.hostname);
+    const plugins = [];
+    const slugs = new Set();
+    const packages = new Set();
+    for (const entry of raw.plugins.slice(0, MAX_PLUGINS)) {
+        const plugin = sanitizePlugin(entry, base, loopbackOk);
+        if (!plugin || slugs.has(plugin.slug) || packages.has(plugin.package))
+            continue;
+        slugs.add(plugin.slug);
+        packages.add(plugin.package);
+        plugins.push(plugin);
+    }
+    const counts = new Map();
+    for (const plugin of plugins)
+        for (const id of plugin.categories)
+            counts.set(id, (counts.get(id) ?? 0) + 1);
+    const categories = [...counts.entries()]
+        .map(([id, count]) => ({ id, count }))
+        .sort((a, b) => b.count - a.count || a.id.localeCompare(b.id));
+    const generatedAt = text(raw.generatedAt, 40);
+    return { ...(generatedAt ? { generatedAt } : {}), categories, plugins };
+}

package/dist/plugins/catalog-service.d.ts

@@ -0,0 +1,89 @@
+import { type CatalogPlugin, type SanitizedCatalog } from "./catalog-schema.ts";
+export declare const DEFAULT_CATALOG_URL = "https://gustavogutierrez.github.io/alisio-plugins/catalog.json";
+export declare const CATALOG_TTL_MS: number;
+export declare const CATALOG_TIMEOUT_MS = 10000;
+export declare const MAX_CATALOG_BYTES: number;
+export declare const MAX_COVER_BYTES: number;
+export interface CatalogMeta {
+    etag?: string;
+    lastModified?: string;
+    /** When the catalog content was last downloaded (ms since epoch). */
+    fetchedAt: number;
+    /** When the catalog was last confirmed current (download or 304). */
+    checkedAt: number;
+}
+export interface CatalogResult {
+    catalog: SanitizedCatalog;
+    meta: {
+        checkedAt: number;
+        fetchedAt: number;
+        fromCache: boolean;
+        stale: boolean;
+        offline: boolean;
+        error?: string;
+    };
+}
+export interface CatalogServiceOptions {
+    /** Catalog document URL (default: `ALISIO_PLUGIN_CATALOG_URL`, else the published catalog). */
+    url?: string;
+    fetch?: typeof fetch;
+    now?: () => number;
+    ttlMs?: number;
+    timeoutMs?: number;
+}
+export declare class CatalogUnavailableError extends Error {
+}
+export interface Cover {
+    body: Buffer;
+    etag: string;
+    contentType: string;
+}
+/** Image types a cover may have, recognised by their bytes (never by the origin's header). */
+declare const COVER_TYPES: readonly [{
+    readonly type: "image/svg+xml";
+    readonly ext: "svg";
+}, {
+    readonly type: "image/webp";
+    readonly ext: "webp";
+}, {
+    readonly type: "image/png";
+    readonly ext: "png";
+}, {
+    readonly type: "image/jpeg";
+    readonly ext: "jpg";
+}];
+export declare function sniffCover(body: Buffer): (typeof COVER_TYPES)[number] | undefined;
+export declare class CatalogService {
+    private options;
+    private inflight;
+    private coverInflight;
+    private fetcher;
+    private clock;
+    constructor(options?: CatalogServiceOptions);
+    get url(): string;
+    private get ttl();
+    private get cacheFile();
+    private coverFile;
+    private coverMetaFile;
+    private readCache;
+    /** The catalog: from cache when fresh, else revalidated (`refresh` forces the check). */
+    get(refresh?: boolean): Promise<CatalogResult>;
+    private load;
+    private result;
+    private revalidate;
+    private assertSameOrigin;
+    /** A plugin of the current catalog by slug (cache, revalidated only when stale). */
+    plugin(slug: string): Promise<{
+        plugin: CatalogPlugin;
+        result: CatalogResult;
+    } | undefined>;
+    /**
+     * The cover SVG of a catalog plugin. It is fetched from the sanitized catalog URL only and kept
+     * on disk; it is revalidated (conditionally) only when the catalog content changed since it was
+     * last checked, and an unreachable origin falls back to the copy on disk.
+     */
+    cover(plugin: CatalogPlugin, catalogFetchedAt: number): Promise<Cover | undefined>;
+    private loadCover;
+    private etagOf;
+}
+export {};