@pooriaarab/foxden 0.0.0-stage → 0.1.0

package/dist/protocol.js

@@ -0,0 +1,47 @@
+// The messages between the page that opens a den (the host) and the
+// sandbox page. Both sides parse what they receive with these functions and
+// ignore anything that does not match exactly.
+export const PROTOCOL_VERSION = 1;
+const ERROR_KINDS = ["python", "timeout", "crashed", "storage"];
+const isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+const isCount = (x) => Number.isSafeInteger(x) && x >= 0;
+const isTime = (x) => typeof x === "number" && Number.isFinite(x) && x >= 0;
+const isFile = (x, allowNull) => Array.isArray(x) && x.length === 2 && typeof x[0] === "string" && (x[1] instanceof Uint8Array || (allowNull && x[1] === null));
+const isFiles = (x, allowNull) => Array.isArray(x) && x.every((f) => isFile(f, allowNull));
+function isReply(r) {
+    if (!isObj(r))
+        return false;
+    const error = r.error;
+    const errorOk = error === null || (isObj(error) && ERROR_KINDS.includes(error.kind) && typeof error.message === "string");
+    return (isCount(r.id) &&
+        typeof r.stdout === "string" &&
+        typeof r.stderr === "string" &&
+        (r.result === null || typeof r.result === "string") &&
+        errorOk &&
+        typeof r.truncated === "boolean" &&
+        isFiles(r.files, true) &&
+        isTime(r.durationMs));
+}
+/** Parse a message from the sandbox page. Returns null for anything unexpected. */
+export function parseDenMessage(data) {
+    if (!isObj(data) || data.v !== PROTOCOL_VERSION)
+        return null;
+    switch (data.t) {
+        case "ready":
+            return typeof data.origin === "string" && typeof data.extensionApi === "boolean" && isTime(data.loadMs) ? data : null;
+        case "load-error":
+            return typeof data.message === "string" ? data : null;
+        case "reply":
+            return isReply(data.reply) ? data : null;
+        default:
+            return null;
+    }
+}
+/** Parse a message from the host. Returns null for anything unexpected. */
+export function parseHostMessage(data) {
+    if (!isObj(data) || data.v !== PROTOCOL_VERSION || data.t !== "run" || !isObj(data.request))
+        return null;
+    const r = data.request;
+    const ok = isCount(r.id) && typeof r.code === "string" && isFiles(r.files, false) && isTime(r.timeoutMs) && isCount(r.maxOutputBytes);
+    return ok ? data : null;
+}

package/dist/shell.d.ts

@@ -0,0 +1,16 @@
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    /** 0 = success, 1 = a file or match problem, 2 = bad usage, 127 = unknown command. */
+    code: number;
+    /** True when stdout or stderr was cut at maxOutputBytes. */
+    truncated: boolean;
+}
+export interface ShellOptions {
+    /** The most characters of stdout (and of stderr) to keep. Default 1 MiB. */
+    maxOutputBytes?: number;
+}
+type Files = ReadonlyMap<string, Uint8Array>;
+/** Run one command line over the den files. It never throws for bad input. */
+export declare function runShell(line: string, files: Files, opts?: ShellOptions): ShellResult;
+export {};

package/dist/shell.js

@@ -0,0 +1,208 @@
+// A small shell-like command language over den files: ls, cat, head, wc,
+// grep and echo, joined by |. It is not a real shell. It never runs user
+// text as code, and grep matches plain text only, so a pattern cannot hang
+// the page that calls it.
+import { normalizePath } from "./paths.js";
+class Usage extends Error {
+}
+const UNSUPPORTED = /[;&<>$`*?(){}]/;
+const decode = (bytes) => new TextDecoder().decode(bytes);
+function tokenize(line) {
+    const commands = [[]];
+    let word = null;
+    let quote = null;
+    for (const ch of line) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                word += ch;
+        }
+        else if (ch === "'" || ch === '"') {
+            quote = ch;
+            word ??= "";
+        }
+        else if (/\s/.test(ch) || ch === "|") {
+            if (word !== null)
+                commands.at(-1).push(word);
+            word = null;
+            if (ch === "|")
+                commands.push([]);
+        }
+        else if (UNSUPPORTED.test(ch)) {
+            throw new Usage(`foxden sh: ${ch} is not supported. foxden sh has only ls, cat, head, wc, grep, echo and |. Quote special characters.`);
+        }
+        else {
+            word = (word ?? "") + ch;
+        }
+    }
+    if (quote)
+        throw new Usage("foxden sh: a quote is not closed.");
+    if (word !== null)
+        commands.at(-1).push(word);
+    if (commands.some((c) => c.length === 0))
+        throw new Usage("foxden sh: an empty command is not supported.");
+    return commands;
+}
+// Split leading options from the other arguments. `spec` maps each allowed
+// flag to true when it takes a value.
+function options(name, args, spec) {
+    const flags = new Map();
+    let i = 0;
+    while (i < args.length && /^-./.test(args[i])) {
+        const flag = args[i];
+        if (!(flag in spec))
+            throw new Usage(`${name}: unknown option ${flag}`);
+        if (spec[flag]) {
+            const value = args[i + 1];
+            if (value === undefined)
+                throw new Usage(`${name}: ${flag} needs a value`);
+            flags.set(flag, value);
+            i += 2;
+        }
+        else {
+            flags.set(flag, "");
+            i += 1;
+        }
+    }
+    return { flags, rest: args.slice(i) };
+}
+// Read each named file, or stdin when there are none. Missing and bad paths
+// go to stderr and set code 1; the other files still count.
+function inputs(name, paths, files, stdin) {
+    if (paths.length === 0)
+        return { texts: [["", stdin]], err: "" };
+    const texts = [];
+    let err = "";
+    for (const raw of paths) {
+        try {
+            const path = normalizePath(raw);
+            const body = files.get(path);
+            if (body)
+                texts.push([path, decode(body)]);
+            else
+                err += `${name}: ${path}: No such file\n`;
+        }
+        catch (error) {
+            err += `${name}: ${error.message}\n`;
+        }
+    }
+    return { texts, err };
+}
+const lines = (text) => (text === "" ? [] : text.replace(/\n$/, "").split("\n"));
+function ls(args, files) {
+    if (args.length === 0)
+        return { out: "drop/\nout/\nwork/\n", err: "", code: 0 };
+    let out = "";
+    let err = "";
+    for (const raw of args) {
+        if (files.has(raw)) {
+            out += `${raw}\n`;
+            continue;
+        }
+        let folder;
+        try {
+            folder = normalizePath(`${raw.replace(/\/+$/, "")}/_`).slice(0, -1);
+        }
+        catch (error) {
+            err += `ls: ${error.message}\n`;
+            continue;
+        }
+        const names = new Set();
+        for (const path of files.keys()) {
+            if (!path.startsWith(folder))
+                continue;
+            const [first, ...more] = path.slice(folder.length).split("/");
+            names.add(more.length > 0 ? `${first}/` : first);
+        }
+        out += [...names].toSorted().map((n) => `${n}\n`).join("");
+    }
+    return { out, err, code: err ? 1 : 0 };
+}
+function head(args, files, stdin) {
+    const { flags, rest } = options("head", args, { "-n": true });
+    const count = Number(flags.get("-n") ?? "10");
+    if (!Number.isInteger(count) || count < 0)
+        throw new Usage(`head: ${flags.get("-n")} is not a line count`);
+    const { texts, err } = inputs("head", rest, files, stdin);
+    const out = texts.map(([, t]) => lines(t).slice(0, count).map((l) => `${l}\n`).join("")).join("");
+    return { out, err, code: err ? 1 : 0 };
+}
+function wc(args, files, stdin) {
+    const { flags, rest } = options("wc", args, { "-l": false, "-w": false, "-c": false });
+    const { texts, err } = inputs("wc", rest, files, stdin);
+    const out = texts
+        .map(([path, text]) => {
+        const counts = { "-l": lines(text).length, "-w": text.split(/\s+/).filter(Boolean).length, "-c": new TextEncoder().encode(text).length };
+        const shown = flags.size > 0 ? [...flags.keys()].map((f) => counts[f]) : Object.values(counts);
+        return `${[...shown, ...(path ? [path] : [])].join(" ")}\n`;
+    })
+        .join("");
+    return { out, err, code: err ? 1 : 0 };
+}
+function grep(args, files, stdin) {
+    const { flags, rest } = options("grep", args, { "-i": false, "-v": false, "-c": false, "-n": false });
+    const [pattern, ...paths] = rest;
+    if (pattern === undefined)
+        throw new Usage("grep: a pattern is needed");
+    const fold = (s) => (flags.has("-i") ? s.toLowerCase() : s);
+    const needle = fold(pattern);
+    const { texts, err } = inputs("grep", paths, files, stdin);
+    let out = "";
+    let matched = 0;
+    for (const [path, text] of texts) {
+        const prefix = texts.length > 1 ? `${path}:` : "";
+        const hits = lines(text)
+            .map((line, i) => ({ line, n: i + 1 }))
+            .filter(({ line }) => fold(line).includes(needle) !== flags.has("-v"));
+        matched += hits.length;
+        if (flags.has("-c"))
+            out += `${prefix}${hits.length}\n`;
+        else
+            out += hits.map(({ line, n }) => `${prefix}${flags.has("-n") ? `${n}:` : ""}${line}\n`).join("");
+    }
+    return { out, err, code: err || matched === 0 ? 1 : 0 };
+}
+function step(command, files, stdin) {
+    const [name, ...args] = command;
+    switch (name) {
+        case "ls":
+            return ls(args, files);
+        case "cat": {
+            const { texts, err } = inputs("cat", args, files, stdin);
+            return { out: texts.map(([, t]) => t).join(""), err, code: err ? 1 : 0 };
+        }
+        case "head":
+            return head(args, files, stdin);
+        case "wc":
+            return wc(args, files, stdin);
+        case "grep":
+            return grep(args, files, stdin);
+        case "echo":
+            return { out: `${args.join(" ")}\n`, err: "", code: 0 };
+        default:
+            return { out: "", err: `foxden sh: ${name}: command not found\n`, code: 127 };
+    }
+}
+/** Run one command line over the den files. It never throws for bad input. */
+export function runShell(line, files, opts = {}) {
+    const max = opts.maxOutputBytes ?? 1024 * 1024;
+    let stdout = "";
+    let stderr = "";
+    let code = 0;
+    try {
+        for (const command of tokenize(line)) {
+            const result = step(command, files, stdout);
+            stdout = result.out;
+            stderr += result.err;
+            code = result.code;
+        }
+    }
+    catch (error) {
+        if (!(error instanceof Usage))
+            throw error;
+        return { stdout: "", stderr: `${error.message}\n`, code: 2, truncated: false };
+    }
+    const truncated = stdout.length > max || stderr.length > max;
+    return { stdout: stdout.slice(0, max), stderr: stderr.slice(0, max), code, truncated };
+}

package/dist/snapshot.d.ts

@@ -0,0 +1,7 @@
+/** Pack the files of a den into snapshot bytes. */
+export declare function encodeSnapshot(name: string, files: ReadonlyMap<string, Uint8Array>): Promise<Uint8Array>;
+/** Read snapshot bytes back into a name and a file map, or throw SnapshotError. */
+export declare function decodeSnapshot(bytes: Uint8Array): Promise<{
+    name: string;
+    files: Map<string, Uint8Array>;
+}>;

package/dist/snapshot.js

@@ -0,0 +1,99 @@
+// The snapshot file format. A snapshot holds the files of one den.
+//
+//   bytes 0-7    "FDNSNAP1"
+//   bytes 8-11   header length N, unsigned 32-bit big-endian
+//   next N bytes header, UTF-8 JSON: { v: 1, name, files: [{ path, size, sha256 }] }
+//   the rest     the file bodies, in header order, with no gaps
+//
+// decodeSnapshot checks every length before it reads, checks each SHA-256,
+// and runs each path through normalizePath. Python globals are not saved.
+import { PathError, SnapshotError } from "./errors.js";
+import { normalizePath } from "./paths.js";
+const MAGIC = "FDNSNAP1";
+const MAX_HEADER = 16 * 1024 * 1024;
+async function sha256(bytes) {
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/** Pack the files of a den into snapshot bytes. */
+export async function encodeSnapshot(name, files) {
+    const entries = [];
+    for (const [path, body] of files)
+        entries.push({ path: normalizePath(path), size: body.length, sha256: await sha256(body) });
+    const header = new TextEncoder().encode(JSON.stringify({ v: 1, name, files: entries }));
+    const total = entries.reduce((sum, e) => sum + e.size, 12 + header.length);
+    const out = new Uint8Array(total);
+    out.set(new TextEncoder().encode(MAGIC), 0);
+    new DataView(out.buffer).setUint32(8, header.length);
+    out.set(header, 12);
+    let at = 12 + header.length;
+    for (const body of files.values()) {
+        out.set(body, at);
+        at += body.length;
+    }
+    return out;
+}
+function parseHeader(text) {
+    let header;
+    try {
+        header = JSON.parse(text);
+    }
+    catch {
+        throw new SnapshotError("The snapshot header is not valid JSON.");
+    }
+    if (typeof header !== "object" || header === null)
+        throw new SnapshotError("The snapshot header is not an object.");
+    const { v, name, files } = header;
+    if (v !== 1)
+        throw new SnapshotError(`The snapshot version is ${String(v)}. This foxden reads version 1.`);
+    if (typeof name !== "string" || !Array.isArray(files))
+        throw new SnapshotError("The snapshot header has no name or no file list.");
+    for (const e of files) {
+        const { path, size, sha256: hash } = (e ?? {});
+        if (typeof path !== "string" || typeof hash !== "string" || !Number.isSafeInteger(size) || size < 0) {
+            throw new SnapshotError("A snapshot file entry has a bad path, size or hash.");
+        }
+    }
+    return { name, files: files };
+}
+/** Read snapshot bytes back into a name and a file map, or throw SnapshotError. */
+export async function decodeSnapshot(bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length < 12)
+        throw new SnapshotError("The bytes are too short to be a snapshot.");
+    if (new TextDecoder().decode(bytes.subarray(0, 8)) !== MAGIC)
+        throw new SnapshotError("The bytes are not a foxden snapshot.");
+    const headerLength = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(8);
+    if (headerLength > MAX_HEADER || 12 + headerLength > bytes.length)
+        throw new SnapshotError("The snapshot header length is larger than the snapshot.");
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(12, 12 + headerLength));
+    }
+    catch {
+        throw new SnapshotError("The snapshot header is not valid UTF-8.");
+    }
+    const header = parseHeader(text);
+    const files = new Map();
+    let at = 12 + headerLength;
+    for (const entry of header.files) {
+        let path;
+        try {
+            path = normalizePath(entry.path);
+        }
+        catch (error) {
+            throw new SnapshotError(`The snapshot holds a bad path: ${error.message}`);
+        }
+        if (files.has(path))
+            throw new SnapshotError(`The snapshot lists ${path} two times.`);
+        if (entry.size > bytes.length - at)
+            throw new SnapshotError(`The snapshot is cut short inside ${path}.`);
+        const body = bytes.slice(at, at + entry.size);
+        at += entry.size;
+        if ((await sha256(body)) !== entry.sha256)
+            throw new SnapshotError(`The bytes of ${path} do not match their SHA-256 hash.`);
+        files.set(path, body);
+    }
+    if (at !== bytes.length)
+        throw new SnapshotError(`The snapshot has ${bytes.length - at} extra bytes after the last file.`);
+    return { name: header.name, files };
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@pooriaarab/foxden",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A sandbox in a browser tab that runs Python and shell with no network.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Pooria Arab",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pooriaarab/foxden.git"
+  },
+  "homepage": "https://github.com/pooriaarab/foxden#readme",
+  "packageManager": "pnpm@11.10.0",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node scripts/build-den.mjs",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint --deny-warnings",
+    "test": "vitest run --passWithNoTests",
+    "ci:local": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && pnpm build:ext && pnpm lint:ext",
+    "build:ext": "node scripts/build-ext.mjs",
+    "lint:ext": "node scripts/lint-ext.mjs",
+    "e2e": "pnpm build && pnpm build:ext && node e2e/run.mjs",
+    "e2e:web": "pnpm build && pnpm build:ext && node e2e/web.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "^24.19.1",
+    "oxlint": "^1.87.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3",
+    "create-foxkit": "^0.1.0",
+    "esbuild": "^0.28.2",
+    "web-ext": "^10.7.0"
+  },
+  "dependencies": {
+    "pyodide": "314.0.7"
+  }
+}