@alisio/core 0.1.0-alpha.9 → 0.1.1

package/dist/artifacts/kinds.js

@@ -0,0 +1,177 @@
+const MB = 1024 * 1024;
+const TEXT_PREVIEW = 2 * MB;
+/** Tables are read through paged queries, not loaded whole: the limit is the ingestion limit. */
+const TABLE_PREVIEW = 200 * MB;
+const UTF8 = "; charset=utf-8";
+const OOXML = "application/vnd.openxmlformats-officedocument";
+const text = (kind, mimeType, previewMax = TEXT_PREVIEW) => ({
+    kind,
+    mimeType,
+    magic: "text",
+    previewMax,
+});
+const RULES = {
+    html: text("dashboard", `text/html${UTF8}`, 20 * MB),
+    htm: text("dashboard", `text/html${UTF8}`, 20 * MB),
+    md: text("document", `text/markdown${UTF8}`),
+    markdown: text("document", `text/markdown${UTF8}`),
+    pdf: { kind: "document", mimeType: "application/pdf", magic: "pdf", previewMax: 50 * MB },
+    docx: { kind: "document", mimeType: `${OOXML}.wordprocessingml.document`, magic: "zip" },
+    pptx: { kind: "document", mimeType: `${OOXML}.presentationml.presentation`, magic: "zip" },
+    odt: { kind: "document", mimeType: "application/vnd.oasis.opendocument.text", magic: "zip" },
+    // Tables open in SpreadsheetView (phase 3): CSV/TSV may be windows-1252 or UTF-16, which the
+    // ingestion decodes, so their bytes only have to look like delimited text, not like UTF-8.
+    csv: {
+        kind: "spreadsheet",
+        mimeType: `text/csv${UTF8}`,
+        magic: "delimited",
+        previewMax: TABLE_PREVIEW,
+    },
+    tsv: {
+        kind: "spreadsheet",
+        mimeType: `text/tab-separated-values${UTF8}`,
+        magic: "delimited",
+        previewMax: TABLE_PREVIEW,
+    },
+    xlsx: {
+        kind: "spreadsheet",
+        mimeType: `${OOXML}.spreadsheetml.sheet`,
+        magic: "zip",
+        previewMax: TABLE_PREVIEW,
+    },
+    png: { kind: "image", mimeType: "image/png", magic: "png", previewMax: 20 * MB },
+    jpg: { kind: "image", mimeType: "image/jpeg", magic: "jpeg", previewMax: 20 * MB },
+    jpeg: { kind: "image", mimeType: "image/jpeg", magic: "jpeg", previewMax: 20 * MB },
+    gif: { kind: "image", mimeType: "image/gif", magic: "gif", previewMax: 20 * MB },
+    webp: { kind: "image", mimeType: "image/webp", magic: "webp", previewMax: 20 * MB },
+    svg: text("image", "image/svg+xml", 20 * MB),
+    json: text("data", "application/json"),
+    geojson: text("data", "application/json"),
+    zip: { kind: "archive", mimeType: "application/zip", magic: "zip" },
+};
+for (const ext of ["txt", "log", "sql", "yaml", "yml", "xml", "py", "js", "ts", "r"])
+    RULES[ext] = text("code", `text/plain${UTF8}`);
+export const DOWNLOAD_ONLY = { kind: "file", mimeType: "application/octet-stream" };
+/** Lower-case extension without the dot (`""` when none). */
+export const extensionOf = (fileName) => {
+    const base = fileName.split(/[\\/]/).pop() ?? "";
+    const dot = base.lastIndexOf(".");
+    return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+};
+const startsWith = (bytes, signature, at = 0) => bytes.length >= at + signature.length && signature.every((b, i) => bytes[at + i] === b);
+/** Text: no NUL byte in the sampled head and the sample decodes as UTF-8. */
+export function looksLikeText(head) {
+    if (head.includes(0))
+        return false;
+    try {
+        // A cut multi-byte character at the end of the sample is not a decoding failure.
+        new TextDecoder("utf-8", { fatal: true }).decode(head.subarray(0, Math.max(0, head.length - 3)));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function matches(magic, head) {
+    switch (magic) {
+        case "text":
+            return looksLikeText(head);
+        case "delimited":
+            // Text in any of the encodings the ingestion reads: UTF-8, windows-1252 (no NUL bytes) or
+            // UTF-16 with a BOM.
+            return (looksLikeText(head) ||
+                startsWith(head, [0xff, 0xfe]) ||
+                startsWith(head, [0xfe, 0xff]) ||
+                !head.includes(0));
+        case "pdf":
+            return startsWith(head, [0x25, 0x50, 0x44, 0x46, 0x2d]);
+        case "png":
+            return startsWith(head, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+        case "jpeg":
+            return startsWith(head, [0xff, 0xd8, 0xff]);
+        case "gif":
+            return startsWith(head, [0x47, 0x49, 0x46, 0x38]);
+        case "webp":
+            return (startsWith(head, [0x52, 0x49, 0x46, 0x46]) && startsWith(head, [0x57, 0x45, 0x42, 0x50], 8));
+        case "zip":
+            return (startsWith(head, [0x50, 0x4b, 0x03, 0x04]) || startsWith(head, [0x50, 0x4b, 0x05, 0x06]));
+    }
+}
+/**
+ * The type of a file from its name and its first bytes (at least 4 KiB is a good sample). An
+ * unknown extension, or bytes that contradict the extension, yield `file` (download only).
+ * An empty file keeps the type of its extension.
+ */
+export function classifyArtifact(fileName, head) {
+    const rule = RULES[extensionOf(fileName)];
+    if (!rule)
+        return DOWNLOAD_ONLY;
+    if (head.length > 0 && !matches(rule.magic, head))
+        return DOWNLOAD_ONLY;
+    return { kind: rule.kind, mimeType: rule.mimeType };
+}
+/** Whether a rich client may preview a file of this name, type and size. */
+export function isPreviewable(fileName, type, bytes) {
+    if (type.kind === "file" || type.kind === "archive")
+        return false;
+    const rule = RULES[extensionOf(fileName)];
+    return !!rule?.previewMax && rule.mimeType === type.mimeType && bytes <= rule.previewMax;
+}
+/** English labels of each kind (the web localizes its own; text surfaces use these). */
+export const KIND_LABELS = {
+    dashboard: "Dashboard",
+    document: "Document",
+    spreadsheet: "Spreadsheet",
+    image: "Image",
+    data: "Data",
+    code: "Text",
+    archive: "Archive",
+    file: "File",
+};
+/**
+ * Content types of the files of an artifact served by the isolated viewer (spec §14.2): a
+ * multi-file dashboard needs its scripts, styles and fonts with their real types (under
+ * `nosniff` a script served as text never runs). Only that sandboxed route uses this table;
+ * every other route serves the registry type above.
+ */
+const VIEWER_TYPES = {
+    html: `text/html${UTF8}`,
+    htm: `text/html${UTF8}`,
+    css: `text/css${UTF8}`,
+    js: `text/javascript${UTF8}`,
+    mjs: `text/javascript${UTF8}`,
+    json: `application/json${UTF8}`,
+    geojson: `application/json${UTF8}`,
+    csv: `text/csv${UTF8}`,
+    tsv: `text/tab-separated-values${UTF8}`,
+    txt: `text/plain${UTF8}`,
+    md: `text/markdown${UTF8}`,
+    svg: "image/svg+xml",
+    png: "image/png",
+    jpg: "image/jpeg",
+    jpeg: "image/jpeg",
+    gif: "image/gif",
+    webp: "image/webp",
+    ico: "image/x-icon",
+    woff: "font/woff",
+    woff2: "font/woff2",
+    ttf: "font/ttf",
+    otf: "font/otf",
+    pdf: "application/pdf",
+    mp4: "video/mp4",
+    webm: "video/webm",
+    mp3: "audio/mpeg",
+    wav: "audio/wav",
+};
+/** The type the sandboxed viewer serves for one file (`application/octet-stream` when unknown). */
+export const viewerContentType = (fileName) => VIEWER_TYPES[extensionOf(fileName)] ?? "application/octet-stream";
+/**
+ * The registry type of one file inside an artifact (for the authenticated `files/*` route):
+ * the extension and the leading bytes decide, exactly like a published file.
+ */
+export function fileType(fileName, head) {
+    const type = classifyArtifact(fileName, head);
+    // HTML never renders on the app origin; download-only kinds never render inline.
+    const inline = type.kind !== "file" && type.kind !== "archive" && type.kind !== "dashboard";
+    return { ...type, inline };
+}

package/dist/artifacts/publisher.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `ToolContext.artifacts` of one tool call: binds the artifact store to the calling session
+ * (and its root), run and call, and announces every publication (`artifact_published`).
+ */
+import type { CoreArtifactPublisher, PublishedArtifactInfo } from "../core/contracts.ts";
+import type { ArtifactOwner, ArtifactStore } from "./store.ts";
+export declare function createArtifactPublisher(store: ArtifactStore, owner: ArtifactOwner, announce: (published: PublishedArtifactInfo) => void): CoreArtifactPublisher;

package/dist/artifacts/publisher.js

@@ -0,0 +1,29 @@
+export function createArtifactPublisher(store, owner, announce) {
+    const done = (published, executionId) => {
+        const info = { ...published, ...(executionId ? { executionId } : {}) };
+        announce(info);
+        return info;
+    };
+    return {
+        async publish(input) {
+            return done(await store.publish(input, owner)).artifact;
+        },
+        async publishText(input) {
+            return done(await store.publishText(input, owner)).artifact;
+        },
+        async publishTextDetailed(input) {
+            return done(await store.publishText(input, owner));
+        },
+        async publishOutputs(staging, options) {
+            const published = await store.publishOutputs(staging, {
+                ...owner,
+                executionId: options.executionId,
+                ...(options.partial ? { partial: true } : {}),
+                ...(options.provenance
+                    ? { provenance: { ...owner.provenance, ...options.provenance } }
+                    : {}),
+            }, options.title ? { title: options.title } : {});
+            return published.map((p) => done(p, options.executionId));
+        },
+    };
+}

package/dist/artifacts/store.d.ts

@@ -0,0 +1,119 @@
+import type { ArtifactKind, ArtifactPublishInput, ArtifactRef, SqlDatabase } from "@alisio/sdk";
+export interface ArtifactLimits {
+    maxFiles: number;
+    maxFileBytes: number;
+    /** Total bytes of one publication (one execution). */
+    maxOutputBytes: number;
+}
+export declare const DEFAULT_ARTIFACT_LIMITS: ArtifactLimits;
+/** Who publishes: the session (and its root), the call that produced the files, provenance. */
+export interface ArtifactOwner {
+    sessionId: string;
+    rootSessionId: string;
+    workspace: string;
+    runId?: string;
+    callId?: string;
+    executionId?: string;
+    partial?: boolean;
+    /** Extra public provenance (runtime, script hash, inputs, model, provider). No paths. */
+    provenance?: Record<string, unknown>;
+}
+export interface PublishedArtifact {
+    artifact: ArtifactRef;
+    /** Absolute path of the file, or of the entry of a multi-file artifact. */
+    path: string;
+    /** Non-fatal notes (e.g. a dashboard reference to a missing file). */
+    warnings: string[];
+}
+export interface ArtifactFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface ArtifactRecord extends ArtifactRef {
+    entry?: string;
+    executionId?: string;
+    runId?: string;
+    callId?: string;
+    provenance: Record<string, unknown>;
+    /** Folder relative to the store root. */
+    relDir: string;
+}
+/** A rejected publication: the message is user-readable and names the offending path. */
+export declare class ArtifactRejected extends Error {
+}
+/** `title` → `[a-z0-9-]`, at most 48 characters (`artifact` when nothing remains). */
+export declare function slugify(title: string): string;
+/** The first bytes of a file (the sample `classifyArtifact` needs). */
+export declare function readHead(path: string): Promise<Uint8Array>;
+/** The public part of a record (what the SDK `ArtifactRef` carries). */
+export declare const toRef: (record: ArtifactRecord) => ArtifactRef;
+export declare class ArtifactStore {
+    private options;
+    readonly limits: ArtifactLimits;
+    private readonly now;
+    constructor(options: {
+        /** State root (`stateHome()` or the folder of `--db`); artifacts live under `artifacts/`. */
+        root: string;
+        db: SqlDatabase;
+        limits?: Partial<ArtifactLimits>;
+        now?: () => number;
+    });
+    get root(): string;
+    /** Session folder of an owner (artifacts of child sessions live with their root). */
+    private sessionDir;
+    /**
+     * Publishes the outputs a script left in `staging`: the entries of `staging/outputs.json`, or
+     * else every top-level file (and every top-level folder; with `index.html` a multi-file
+     * dashboard, otherwise one ZIP archive). Everything or nothing is published.
+     */
+    publishOutputs(staging: string, owner: ArtifactOwner, defaults?: {
+        title?: string;
+    }): Promise<PublishedArtifact[]>;
+    /** Publishes one caller-owned file or directory. */
+    publish(input: ArtifactPublishInput, owner: ArtifactOwner): Promise<PublishedArtifact>;
+    /** Publishes a single text file the caller holds in memory. */
+    publishText(input: {
+        fileName: string;
+        title?: string;
+        text: string;
+    }, owner: ArtifactOwner): Promise<PublishedArtifact>;
+    private scan;
+    private publishAll;
+    private build;
+    /** Artifacts of a root session, newest first. */
+    list(rootSessionId: string, options?: {
+        kind?: ArtifactKind;
+        limit?: number;
+        before?: number;
+        /** Also `deleted` and `expired` rows (the folder is gone, the row remains). */
+        includeDeleted?: boolean;
+        /** Also `expired` rows (retention), but not `deleted` ones. */
+        includeExpired?: boolean;
+    }): ArtifactRecord[];
+    get(id: string): ArtifactRecord | undefined;
+    /** Absolute folder holding `manifest.json` and `files/`. */
+    folder(record: ArtifactRecord): string;
+    /** Absolute path of the file (or the entry of a multi-file artifact). */
+    localPath(record: ArtifactRecord): string;
+    /** Files of an artifact from its manifest, with absolute paths (inside `files/`). */
+    files(record: ArtifactRecord): Promise<Array<ArtifactFile & {
+        abs: string;
+    }>>;
+    /**
+     * One file of a ready artifact by its manifest path (`files/` only, never `manifest.json`):
+     * the path must be listed in the manifest and its real path must stay inside `files/`.
+     */
+    resolveFile(record: ArtifactRecord, path: string): Promise<(ArtifactFile & {
+        abs: string;
+    }) | undefined>;
+    /**
+     * Retention: marks a `ready` artifact `expired` and removes its folder; the row stays so cards
+     * and listings keep showing it as `Expired`. False when it is not `ready`.
+     */
+    markExpired(id: string): Promise<boolean>;
+    /** Ready artifacts created before `cutoff` (epoch ms), oldest first (for the retention sweep). */
+    readyBefore(cutoff: number): ArtifactRecord[];
+    /** Marks an artifact deleted and removes its folder (the row stays for references). */
+    delete(id: string): Promise<boolean>;
+}