@alisio/core 0.8.0 → 0.10.0

package/dist/plugins/tarball.d.ts

@@ -0,0 +1,39 @@
+import type { Readable } from "node:stream";
+export declare const MAX_TARBALL_BYTES: number;
+export declare const MAX_PACKAGE_JSON_BYTES: number;
+export declare const MAX_TARBALL_ENTRIES = 20000;
+export declare const MAX_EXPANDED_BYTES: number;
+export interface TarballLimits {
+    maxPackageJsonBytes?: number;
+    maxEntries?: number;
+    maxExpandedBytes?: number;
+}
+export declare class TarballError extends Error {
+}
+/**
+ * Reads `package/package.json` from a gzip ustar stream. Throws `TarballError` with a user-facing
+ * reason for anything unusable (not gzip, corrupt, unsafe path, over a limit, no manifest).
+ */
+export declare function readTarballPackageJson(source: Readable, limits?: TarballLimits): Promise<{
+    packageJson: unknown;
+    entries: number;
+}>;
+export interface PluginTarballInfo {
+    name?: string;
+    version?: string;
+    description?: string;
+    author?: string;
+    license?: string;
+    /** `peerDependencies["@alisio/sdk"]`. */
+    sdkRange?: string;
+    /** True when every check passed; `reasons` lists what failed otherwise. */
+    isAlisioPlugin: boolean;
+    reasons: string[];
+    /** Declared `preinstall`/`install`/`postinstall` scripts (npm runs them on install). */
+    lifecycleScripts: string[];
+    size: number;
+}
+/** Validates a tarball on disk as an Alisio plugin package; never throws for bad content. */
+export declare function inspectPluginTarball(path: string, limits?: TarballLimits & {
+    maxBytes?: number;
+}): Promise<PluginTarballInfo>;

package/dist/plugins/tarball.js

@@ -0,0 +1,277 @@
+/**
+ * Inspection of a plugin tarball (`.tgz` from `npm pack`/`pnpm pack`) without extracting it and
+ * without any external `tar`: a streaming gzip + ustar reader that only keeps `package/package.json`.
+ * Everything is bounded (compressed size, expanded size, entry count, manifest size) and any entry
+ * path that could escape the package directory rejects the whole archive.
+ */
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createGunzip } from "node:zlib";
+import { PLUGIN_KEYWORD } from "../runtime/modules.js";
+import { parsePluginSpec } from "./install.js";
+import { comparePluginVersions } from "./version-compat.js";
+export const MAX_TARBALL_BYTES = 50 * 1024 * 1024;
+export const MAX_PACKAGE_JSON_BYTES = 1024 * 1024;
+export const MAX_TARBALL_ENTRIES = 20_000;
+export const MAX_EXPANDED_BYTES = 1024 * 1024 * 1024;
+const MAX_META_BYTES = 64 * 1024;
+const LIFECYCLE = ["preinstall", "install", "postinstall"];
+export class TarballError extends Error {
+}
+const str = (block, start, length) => {
+    const slice = block.subarray(start, start + length);
+    const end = slice.indexOf(0);
+    return slice.subarray(0, end < 0 ? slice.length : end).toString("utf8");
+};
+function parseSize(block) {
+    if ((block[124] ?? 0) & 0x80)
+        throw new TarballError("The archive has an entry that is too large");
+    const value = Number.parseInt(str(block, 124, 12).trim() || "0", 8);
+    if (!Number.isFinite(value) || value < 0)
+        throw new TarballError("The archive is corrupt");
+    return value;
+}
+function checksumOk(block) {
+    const stored = Number.parseInt(str(block, 148, 8).trim() || "x", 8);
+    let sum = 0;
+    for (let i = 0; i < 512; i++)
+        sum += i >= 148 && i < 156 ? 0x20 : (block[i] ?? 0);
+    return stored === sum;
+}
+/** Path of the `path=` record of a pax extended header, if any. */
+function paxPath(data) {
+    let offset = 0;
+    while (offset < data.length) {
+        const space = data.indexOf(0x20, offset);
+        if (space < 0)
+            return undefined;
+        const length = Number.parseInt(data.subarray(offset, space).toString("utf8"), 10);
+        if (!Number.isFinite(length) || length <= 0)
+            return undefined;
+        const record = data.subarray(space + 1, offset + length - 1).toString("utf8");
+        if (record.startsWith("path="))
+            return record.slice(5);
+        offset += length;
+    }
+    return undefined;
+}
+/** Normalized entry name; throws for anything that is absolute or climbs out with `..`. */
+function safeName(raw) {
+    const name = raw.replace(/\/+$/, "");
+    if (name.startsWith("/") || name.includes("\\") || /^[A-Za-z]:/.test(name))
+        throw new TarballError(`The archive has an unsafe path: ${raw.slice(0, 80)}`);
+    if (name.split("/").some((part) => part === ".."))
+        throw new TarballError(`The archive has an unsafe path: ${raw.slice(0, 80)}`);
+    return name;
+}
+/**
+ * Reads `package/package.json` from a gzip ustar stream. Throws `TarballError` with a user-facing
+ * reason for anything unusable (not gzip, corrupt, unsafe path, over a limit, no manifest).
+ */
+export async function readTarballPackageJson(source, limits = {}) {
+    const maxJson = limits.maxPackageJsonBytes ?? MAX_PACKAGE_JSON_BYTES;
+    const maxEntries = limits.maxEntries ?? MAX_TARBALL_ENTRIES;
+    const maxExpanded = limits.maxExpandedBytes ?? MAX_EXPANDED_BYTES;
+    const gunzip = createGunzip();
+    source.on("error", (error) => gunzip.destroy(error));
+    source.pipe(gunzip);
+    let state = "header";
+    let buf = Buffer.alloc(0);
+    let remaining = 0;
+    let mode = "skip";
+    let collected = [];
+    let pendingName;
+    let entries = 0;
+    let expanded = 0;
+    let manifest;
+    let padding = 0;
+    const finishData = () => {
+        const data = Buffer.concat(collected);
+        collected = [];
+        if (mode === "manifest")
+            manifest = data;
+        else if (mode === "pax")
+            pendingName = paxPath(data) ?? pendingName;
+        else if (mode === "longname")
+            pendingName = str(data, 0, data.length);
+        mode = "skip";
+    };
+    const header = (block) => {
+        if (block.every((byte) => byte === 0)) {
+            state = "end";
+            return;
+        }
+        if (!checksumOk(block))
+            throw new TarballError("The file is not a valid tar archive (corrupt header checksum)");
+        const prefix = str(block, 345, 155);
+        const own = str(block, 0, 100);
+        const size = parseSize(block);
+        const type = String.fromCharCode(block[156] || 0x30);
+        padding = (512 - (size % 512)) % 512;
+        if (type === "x" || type === "L" || type === "g") {
+            if (size > MAX_META_BYTES)
+                throw new TarballError("The archive has an oversized header record");
+            mode = type === "x" ? "pax" : type === "L" ? "longname" : "skip";
+        }
+        else {
+            entries++;
+            if (entries > maxEntries)
+                throw new TarballError("The archive has too many entries");
+            const name = safeName(pendingName ?? (prefix ? `${prefix}/${own}` : own));
+            pendingName = undefined;
+            mode = "skip";
+            if (name === "package/package.json" && (type === "0" || type === "7")) {
+                if (size > maxJson)
+                    throw new TarballError("package.json is too large");
+                mode = "manifest";
+            }
+        }
+        remaining = size;
+        state = remaining > 0 ? "data" : padding > 0 ? "pad" : "header";
+        if (remaining === 0 && mode !== "skip")
+            finishData();
+    };
+    const pump = () => {
+        for (;;) {
+            if (state === "end")
+                return;
+            if (state === "header") {
+                if (buf.length < 512)
+                    return;
+                const block = buf.subarray(0, 512);
+                buf = buf.subarray(512);
+                header(block);
+                continue;
+            }
+            const take = Math.min(remaining, buf.length);
+            if (take === 0)
+                return;
+            if (state === "data" && mode !== "skip") {
+                collected.push(buf.subarray(0, take));
+            }
+            buf = buf.subarray(take);
+            remaining -= take;
+            if (remaining > 0)
+                return;
+            if (state === "data") {
+                if (mode !== "skip")
+                    finishData();
+                remaining = padding;
+                state = padding > 0 ? "pad" : "header";
+            }
+            else
+                state = "header";
+        }
+    };
+    try {
+        for await (const chunk of gunzip) {
+            expanded += chunk.length;
+            if (expanded > maxExpanded)
+                throw new TarballError("The archive expands beyond the allowed size");
+            buf = buf.length ? Buffer.concat([buf, chunk]) : chunk;
+            pump();
+        }
+    }
+    catch (error) {
+        if (error instanceof TarballError)
+            throw error;
+        throw new TarballError("The file is not a gzip archive (.tgz)");
+    }
+    finally {
+        source.unpipe(gunzip);
+        source.destroy();
+    }
+    const last = state;
+    if (last !== "end" && last !== "header")
+        throw new TarballError("The archive is truncated");
+    if (entries === 0 && last !== "end")
+        throw new TarballError("The file is not a valid tar archive");
+    if (!manifest)
+        throw new TarballError("The archive has no package/package.json");
+    let packageJson;
+    try {
+        packageJson = JSON.parse(manifest.toString("utf8"));
+    }
+    catch {
+        throw new TarballError("package/package.json is not valid JSON");
+    }
+    return { packageJson, entries };
+}
+const text = (value, max = 500) => typeof value === "string" && value.trim() && value.length <= max ? value.trim() : undefined;
+/** Validates a tarball on disk as an Alisio plugin package; never throws for bad content. */
+export async function inspectPluginTarball(path, limits = {}) {
+    const size = (await stat(path)).size;
+    const info = {
+        isAlisioPlugin: false,
+        reasons: [],
+        lifecycleScripts: [],
+        size,
+    };
+    const maxBytes = limits.maxBytes ?? MAX_TARBALL_BYTES;
+    if (size > maxBytes) {
+        info.reasons.push(`The file is larger than ${Math.round(maxBytes / (1024 * 1024))} MB`);
+        return info;
+    }
+    let json;
+    try {
+        json = (await readTarballPackageJson(createReadStream(path), limits)).packageJson;
+    }
+    catch (error) {
+        info.reasons.push(error instanceof TarballError ? error.message : "The file could not be read");
+        return info;
+    }
+    if (!json || typeof json !== "object" || Array.isArray(json)) {
+        info.reasons.push("package/package.json is not an object");
+        return info;
+    }
+    const pkg = json;
+    const name = text(pkg.name, 214);
+    const version = text(pkg.version, 64);
+    let nameOk = false;
+    if (name) {
+        try {
+            const parsed = parsePluginSpec(name);
+            nameOk = parsed.version === undefined && parsed.name === name;
+        }
+        catch {
+            nameOk = false;
+        }
+    }
+    if (nameOk)
+        info.name = name;
+    else
+        info.reasons.push("The package name is missing or not a valid npm package name");
+    if (version && comparePluginVersions(version, version) !== undefined)
+        info.version = version;
+    else
+        info.reasons.push("The package version is missing or not a valid semver version");
+    const keywords = Array.isArray(pkg.keywords) ? pkg.keywords : [];
+    if (!keywords.includes(PLUGIN_KEYWORD))
+        info.reasons.push(`Not an Alisio plugin: package.json keywords must include "${PLUGIN_KEYWORD}"`);
+    const hasExports = (typeof pkg.exports === "string" && pkg.exports.length > 0) ||
+        (!!pkg.exports && typeof pkg.exports === "object" && Object.keys(pkg.exports).length > 0);
+    if (!hasExports && !text(pkg.main))
+        info.reasons.push('The package has no entry point ("exports" or "main" in package.json)');
+    const description = text(pkg.description, 600);
+    if (description)
+        info.description = description;
+    const author = text(pkg.author) ??
+        (pkg.author && typeof pkg.author === "object"
+            ? text(pkg.author.name)
+            : undefined);
+    if (author)
+        info.author = author;
+    const license = text(pkg.license, 80);
+    if (license)
+        info.license = license;
+    const peers = pkg.peerDependencies;
+    const range = peers && typeof peers === "object"
+        ? text(peers["@alisio/sdk"], 80)
+        : undefined;
+    if (range)
+        info.sdkRange = range;
+    const scripts = pkg.scripts && typeof pkg.scripts === "object" ? pkg.scripts : {};
+    info.lifecycleScripts = LIFECYCLE.filter((key) => typeof scripts[key] === "string");
+    info.isAlisioPlugin = info.reasons.length === 0;
+    return info;
+}

package/dist/plugins/version-compat.d.ts

@@ -0,0 +1,20 @@
+/** Negative, zero or positive like a comparator; `undefined` when either version is malformed. */
+export declare function comparePluginVersions(a: string, b: string): number | undefined;
+/** Whether `version` satisfies `range`. An unparseable range or version never satisfies. */
+export declare function satisfiesRange(version: string, range: string): boolean;
+export interface CatalogPluginStateInput {
+    catalogVersion: string;
+    installedVersion?: string;
+    /** The plugin's declared `@alisio/sdk` range. */
+    sdkRange?: string;
+    /** The installed `@alisio/sdk` version, when known. */
+    sdkVersion?: string;
+}
+export interface CatalogPluginState {
+    installedVersion?: string;
+    /** False only when both the range and the SDK version are known and do not match. */
+    compatible: boolean;
+    updateAvailable: boolean;
+}
+/** Install state of one catalog entry against what is installed and the running SDK. */
+export declare function catalogPluginState(input: CatalogPluginStateInput): CatalogPluginState;

package/dist/plugins/version-compat.js

@@ -0,0 +1,154 @@
+function parse(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version.trim());
+    if (!match)
+        return undefined;
+    return {
+        triple: [Number(match[1]), Number(match[2]), Number(match[3])],
+        pre: match[4] ? match[4].split(".") : [],
+    };
+}
+function compareTriples(a, b) {
+    for (let i = 0; i < 3; i++) {
+        const diff = a[i] - b[i];
+        if (diff)
+            return diff;
+    }
+    return 0;
+}
+/** Negative, zero or positive like a comparator; `undefined` when either version is malformed. */
+export function comparePluginVersions(a, b) {
+    const left = parse(a);
+    const right = parse(b);
+    if (!left || !right)
+        return undefined;
+    const core = compareTriples(left.triple, right.triple);
+    if (core)
+        return core;
+    if (!left.pre.length || !right.pre.length)
+        return right.pre.length - left.pre.length;
+    const length = Math.max(left.pre.length, right.pre.length);
+    for (let i = 0; i < length; i++) {
+        const x = left.pre[i];
+        const y = right.pre[i];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        const xn = /^\d+$/.test(x);
+        const yn = /^\d+$/.test(y);
+        if (xn && yn) {
+            if (Number(x) !== Number(y))
+                return Number(x) - Number(y);
+        }
+        else if (xn !== yn)
+            return xn ? -1 : 1;
+        else if (x !== y)
+            return x < y ? -1 : 1;
+    }
+    return 0;
+}
+/** A partial version (`1`, `1.2`, `1.x`, `*`) as its numeric parts (`undefined` = wildcard). */
+function partial(text) {
+    const parts = text.replace(/^v/, "").split(".");
+    if (parts.length > 3 || parts[0] === "")
+        return undefined;
+    const out = [];
+    for (const part of parts) {
+        if (part === "x" || part === "X" || part === "*")
+            out.push(undefined);
+        else if (/^\d+$/.test(part))
+            out.push(Number(part));
+        else
+            return undefined;
+    }
+    while (out.length < 3)
+        out.push(undefined);
+    return out;
+}
+function comparator(token) {
+    const match = /^(\^|~|>=|<=|>|<|=)?\s*(.+)$/.exec(token);
+    if (!match)
+        return undefined;
+    const op = match[1] ?? "";
+    const nums = partial(match[2]);
+    if (!nums)
+        return undefined;
+    const [maj, min, pat] = nums;
+    const floor = [maj ?? 0, min ?? 0, pat ?? 0];
+    const ge = (v) => compareTriples(v, floor) >= 0;
+    if (maj === undefined)
+        return () => true;
+    switch (op) {
+        case "^": {
+            const upper = maj > 0
+                ? [maj + 1, 0, 0]
+                : min === undefined
+                    ? [1, 0, 0]
+                    : min > 0 || pat === undefined
+                        ? [0, min + 1, 0]
+                        : [0, 0, pat + 1];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+        case "~": {
+            const upper = min === undefined ? [maj + 1, 0, 0] : [maj, min + 1, 0];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+        case ">=":
+            return ge;
+        case ">": {
+            const next = pat !== undefined
+                ? [maj, min ?? 0, pat]
+                : min !== undefined
+                    ? [maj, min + 1, 0]
+                    : [maj + 1, 0, 0];
+            return pat !== undefined
+                ? (v) => compareTriples(v, next) > 0
+                : (v) => compareTriples(v, next) >= 0;
+        }
+        case "<":
+            return (v) => compareTriples(v, floor) < 0;
+        case "<=": {
+            const top = pat !== undefined
+                ? [maj, min ?? 0, pat + 1]
+                : min !== undefined
+                    ? [maj, min + 1, 0]
+                    : [maj + 1, 0, 0];
+            return (v) => compareTriples(v, top) < 0;
+        }
+        default: {
+            // Exact or wildcard (`1.2.x`, `1`).
+            if (pat !== undefined)
+                return (v) => compareTriples(v, floor) === 0;
+            const upper = min === undefined ? [maj + 1, 0, 0] : [maj, min + 1, 0];
+            return (v) => ge(v) && compareTriples(v, upper) < 0;
+        }
+    }
+}
+/** Whether `version` satisfies `range`. An unparseable range or version never satisfies. */
+export function satisfiesRange(version, range) {
+    const parsed = parse(version);
+    if (!parsed)
+        return false;
+    const alternatives = range.split("||").map((part) => part.trim());
+    return alternatives.some((alt) => {
+        const tokens = alt
+            .replace(/(\^|~|>=|<=|>|<|=)\s+/g, "$1")
+            .split(/\s+/)
+            .filter(Boolean);
+        if (tokens.length === 0)
+            return false;
+        const checks = tokens.map(comparator);
+        return checks.every((check) => check?.(parsed.triple) === true);
+    });
+}
+/** Install state of one catalog entry against what is installed and the running SDK. */
+export function catalogPluginState(input) {
+    const compatible = !input.sdkRange || !input.sdkVersion ? true : satisfiesRange(input.sdkVersion, input.sdkRange);
+    const updateAvailable = input.installedVersion !== undefined &&
+        (comparePluginVersions(input.catalogVersion, input.installedVersion) ?? 0) > 0;
+    return {
+        compatible,
+        updateAvailable,
+        ...(input.installedVersion !== undefined ? { installedVersion: input.installedVersion } : {}),
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/core",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Embeddable provider-agnostic Alisio agent core: tool loop, context compaction, local tools, MCP, plugin host and SQLite session store. Runs on Node >=22.16 and Bun.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",
@@ -45,7 +45,7 @@
     "node": ">=22.16"
   },
   "dependencies": {
-    "@alisio/sdk": "0.8.0",
+    "@alisio/sdk": "0.10.0",
     "@mixmark-io/domino": "2.2.0",
     "@modelcontextprotocol/client": "2.1.0",
     "ajv": "8.20.0",