@alisio/server 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/host/dir-listing.d.ts

@@ -0,0 +1,20 @@
+import type { DirectoryListing } from "@alisio/sdk";
+/** Absolute paths only; on Windows `""` is the drive list above every drive root. */
+export declare function isBrowsablePath(path: string, platform?: NodeJS.Platform): boolean;
+/** Breadcrumbs from the filesystem root to `path` (server-built: the web assumes no separator). */
+export declare function directorySegments(path: string, platform?: NodeJS.Platform): Array<{
+    name: string;
+    path: string;
+}>;
+/** Parent directory; a Windows drive root's parent is the drive list (`""`); none at the top. */
+export declare function directoryParent(path: string, platform?: NodeJS.Platform): string | undefined;
+/** The absolute path of `name` inside `dir` (inside the drive list, `name` is a drive root). */
+export declare function childPath(dir: string, name: string, platform?: NodeJS.Platform): string;
+/**
+ * One listing page: subdirectories of `path` (symlinks included when they point at a directory),
+ * sorted by name, dot-folders only when `hidden`. `path` defaults to the home directory.
+ */
+export declare function listDirectories(input: {
+    path?: string | null;
+    hidden?: boolean;
+}, platform?: NodeJS.Platform): Promise<DirectoryListing>;

package/dist/host/dir-listing.js

@@ -0,0 +1,119 @@
+import { readdir, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { HttpError } from "../http/errors.js";
+const api = (platform) => (platform === "win32" ? win32 : posix);
+/** Absolute paths only; on Windows `""` is the drive list above every drive root. */
+export function isBrowsablePath(path, platform = process.platform) {
+    if (path === "")
+        return platform === "win32";
+    return api(platform).isAbsolute(path);
+}
+/** Breadcrumbs from the filesystem root to `path` (server-built: the web assumes no separator). */
+export function directorySegments(path, platform = process.platform) {
+    if (path === "")
+        return [];
+    const p = api(platform);
+    const normalized = p.normalize(path);
+    const root = p.parse(normalized).root;
+    const segments = [{ name: root, path: root }];
+    let current = root;
+    for (const part of normalized.slice(root.length).split(p.sep).filter(Boolean)) {
+        current = p.join(current, part);
+        segments.push({ name: part, path: current });
+    }
+    return segments;
+}
+/** Parent directory; a Windows drive root's parent is the drive list (`""`); none at the top. */
+export function directoryParent(path, platform = process.platform) {
+    if (path === "")
+        return undefined;
+    const p = api(platform);
+    const normalized = p.normalize(path);
+    const root = p.parse(normalized).root;
+    if (normalized === root || `${normalized}${p.sep}` === root)
+        return platform === "win32" && /^[A-Za-z]:\\$/.test(root) ? "" : undefined;
+    return p.dirname(normalized);
+}
+/** The absolute path of `name` inside `dir` (inside the drive list, `name` is a drive root). */
+export function childPath(dir, name, platform = process.platform) {
+    if (dir === "" && platform === "win32")
+        return name;
+    return api(platform).join(dir, name);
+}
+const MAX_ENTRIES = 2_000;
+/** Drive roots that exist (`A:\` … `Z:\`), for the top of the Windows browser. */
+async function drives() {
+    const letters = Array.from({ length: 26 }, (_, i) => `${String.fromCharCode(65 + i)}:\\`);
+    const found = await Promise.all(letters.map(async (root) => ((await isDirectory(root)) ? root : undefined)));
+    return found.filter((root) => !!root);
+}
+async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Filesystem errors become 403 `permission_denied` or 404 `not_found`, never a 500. */
+function fsError(error, path) {
+    const code = error?.code;
+    if (code === "EACCES" || code === "EPERM")
+        return new HttpError("permission_denied", `Cannot read ${path}`, { path });
+    return new HttpError("not_found", `Directory not found: ${path}`, { path });
+}
+/**
+ * One listing page: subdirectories of `path` (symlinks included when they point at a directory),
+ * sorted by name, dot-folders only when `hidden`. `path` defaults to the home directory.
+ */
+export async function listDirectories(input, platform = process.platform) {
+    const p = api(platform);
+    const home = homedir();
+    const raw = input.path ?? home;
+    if (!isBrowsablePath(raw, platform))
+        throw new HttpError("validation_failed", "path must be absolute", { fields: ["path"] });
+    const path = raw === "" ? "" : p.normalize(raw);
+    const base = {
+        home,
+        separator: p.sep,
+        segments: directorySegments(path, platform),
+        ...(directoryParent(path, platform) !== undefined
+            ? { parent: directoryParent(path, platform) }
+            : {}),
+    };
+    if (path === "") {
+        const roots = await drives();
+        return {
+            ...base,
+            path,
+            entries: roots.map((root) => ({ name: root, path: root, hidden: false })),
+        };
+    }
+    let dirents;
+    try {
+        if (!(await stat(path)).isDirectory())
+            throw Object.assign(new Error(), { code: "ENOTDIR" });
+        dirents = await readdir(path, { withFileTypes: true });
+    }
+    catch (error) {
+        throw fsError(error, path);
+    }
+    const entries = [];
+    for (const dirent of dirents) {
+        const hidden = dirent.name.startsWith(".");
+        if (hidden && !input.hidden)
+            continue;
+        const full = childPath(path, dirent.name, platform);
+        const directory = dirent.isDirectory() || (dirent.isSymbolicLink() && (await isDirectory(full)));
+        if (directory)
+            entries.push({ name: dirent.name, path: full, hidden });
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name, undefined, { sensitivity: "base" }));
+    return {
+        ...base,
+        path,
+        entries: entries.slice(0, MAX_ENTRIES),
+        ...(entries.length > MAX_ENTRIES ? { truncated: true } : {}),
+    };
+}

package/dist/host/folder-picker.d.ts

@@ -0,0 +1,95 @@
+export type PickerTool = "zenity" | "kdialog" | "yad" | "osascript" | "powershell";
+/** The dialog tool chosen for this machine. */
+export interface PickerStrategy {
+    tool: PickerTool;
+    /** Absolute path of the executable. */
+    file: string;
+    platform: NodeJS.Platform;
+}
+type Env = Record<string, string | undefined>;
+type Exists = (file: string) => Promise<boolean>;
+/**
+ * First `name` on `PATH` (no `which`/`where`): splits `PATH` with the platform's delimiter and, on
+ * Windows, tries every `PATHEXT` extension.
+ */
+export declare function findOnPath(name: string, options?: {
+    platform?: NodeJS.Platform;
+    env?: Env;
+    exists?: Exists;
+}): Promise<string | undefined>;
+/**
+ * The dialog tool for a platform, or `undefined` when none can show a dialog here:
+ * Linux/BSD need a desktop session (`DISPLAY` or `WAYLAND_DISPLAY`) and zenity, kdialog or yad;
+ * macOS uses `osascript`; Windows uses Windows PowerShell (or `pwsh`).
+ * `ALISIO_NATIVE_PICKER=0` turns the native dialog off (the in-app browser is used instead).
+ */
+export declare function selectPicker(options?: {
+    platform?: NodeJS.Platform;
+    env?: Env;
+    exists?: Exists;
+}): Promise<PickerStrategy | undefined>;
+/** The exact executable, arguments and extra environment for one dialog. */
+export declare function pickerCommand(strategy: PickerStrategy, options: {
+    title: string;
+    start?: string;
+}): {
+    file: string;
+    args: string[];
+    env?: Record<string, string>;
+};
+export interface PickerProcessResult {
+    /** Exit code (`null` when killed). */
+    code: number | null;
+    stdout: string;
+    stderr?: string;
+    /** Killed by the timeout: treated as a cancellation. */
+    timedOut?: boolean;
+}
+export type PickerOutcome = {
+    path: string;
+} | {
+    cancelled: true;
+} | {
+    error: string;
+};
+/**
+ * Maps a dialog's exit to the chosen absolute folder (normalized with the platform's own path
+ * rules: macOS trailing slash, Windows backslashes and drive roots, CRLF), a cancellation, or an
+ * error.
+ */
+export declare function parsePickerOutput(platform: NodeJS.Platform, result: PickerProcessResult): PickerOutcome;
+/** Runs one dialog process: resolves with its exit, never rejects on a non-zero exit. */
+export type PickerRun = (file: string, args: string[], options: {
+    env?: Record<string, string>;
+    timeoutMs: number;
+    signal?: AbortSignal;
+}) => Promise<PickerProcessResult>;
+export interface FolderPicker {
+    /** A dialog can be shown on this machine. */
+    available(): Promise<boolean>;
+    /** A dialog is open right now. */
+    readonly busy: boolean;
+    /**
+     * Opens the dialog and waits for the user. Rejects with 409 `picker_busy` while another dialog
+     * is open and 503 `picker_unavailable` when no dialog can be shown or it fails to start.
+     */
+    pick(options: {
+        title: string;
+        start?: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        path: string;
+    } | {
+        cancelled: true;
+    }>;
+}
+/**
+ * A picker over the selected strategy. `strategy` defaults to `selectPicker()` (detected once);
+ * `run` is injectable so tests never open a real dialog.
+ */
+export declare function createNativePicker(options?: {
+    strategy?: PickerStrategy | undefined;
+    run?: PickerRun;
+    timeoutMs?: number;
+}): FolderPicker;
+export {};

package/dist/host/folder-picker.js

@@ -0,0 +1,273 @@
+/**
+ * Native folder dialog for "Open a workspace". Browsers cannot hand a page an absolute folder path
+ * (`showDirectoryPicker` returns a handle, never a path), so the local server opens the operating
+ * system's dialog on its own desktop and returns the chosen path. Every command is spawned with
+ * `execFile` (no shell) and fixed arguments; the only inputs are the dialog title and an optional,
+ * already validated start directory, passed as separate arguments or environment variables and
+ * never interpolated into a script.
+ *
+ * The pure pieces (PATH lookup, strategy selection, command construction, output parsing) take the
+ * platform as a parameter, so all three operating systems are unit tested on any host.
+ */
+import { execFile } from "node:child_process";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { HttpError } from "../http/errors.js";
+const pathApi = (platform) => (platform === "win32" ? win32 : posix);
+/** Case-insensitive environment lookup (Windows spells it `Path`). */
+function envValue(env, name) {
+    if (env[name] !== undefined)
+        return env[name];
+    const key = Object.keys(env).find((k) => k.toLowerCase() === name.toLowerCase());
+    return key ? env[key] : undefined;
+}
+const executable = async (file) => {
+    try {
+        await access(file, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * First `name` on `PATH` (no `which`/`where`): splits `PATH` with the platform's delimiter and, on
+ * Windows, tries every `PATHEXT` extension.
+ */
+export async function findOnPath(name, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? executable;
+    const api = pathApi(platform);
+    const dirs = (envValue(env, "PATH") ?? "").split(api.delimiter).filter(Boolean);
+    const extensions = platform === "win32" && !api.extname(name)
+        ? (envValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean)
+        : [""];
+    for (const dir of dirs)
+        for (const extension of extensions) {
+            const file = api.join(dir, `${name}${extension}`);
+            if (await exists(file))
+                return file;
+        }
+    return undefined;
+}
+const LINUX_TOOLS = ["zenity", "kdialog", "yad"];
+const UNIX_DESKTOPS = new Set(["linux", "freebsd", "openbsd", "netbsd"]);
+/**
+ * The dialog tool for a platform, or `undefined` when none can show a dialog here:
+ * Linux/BSD need a desktop session (`DISPLAY` or `WAYLAND_DISPLAY`) and zenity, kdialog or yad;
+ * macOS uses `osascript`; Windows uses Windows PowerShell (or `pwsh`).
+ * `ALISIO_NATIVE_PICKER=0` turns the native dialog off (the in-app browser is used instead).
+ */
+export async function selectPicker(options = {}) {
+    const platform = options.platform ?? process.platform;
+    const env = options.env ?? process.env;
+    const exists = options.exists ?? executable;
+    const lookup = { platform, env, exists };
+    if (["0", "off", "false", "no"].includes((envValue(env, "ALISIO_NATIVE_PICKER") ?? "").toLowerCase()))
+        return undefined;
+    if (UNIX_DESKTOPS.has(platform)) {
+        if (!envValue(env, "DISPLAY") && !envValue(env, "WAYLAND_DISPLAY"))
+            return undefined;
+        for (const tool of LINUX_TOOLS) {
+            const file = await findOnPath(tool, lookup);
+            if (file)
+                return { tool, file, platform };
+        }
+        return undefined;
+    }
+    if (platform === "darwin") {
+        // `osascript` ships with every macOS; PATH may be minimal when launched from a GUI.
+        const file = (await findOnPath("osascript", lookup)) ?? "/usr/bin/osascript";
+        return { tool: "osascript", file, platform };
+    }
+    if (platform === "win32") {
+        const file = (await findOnPath("powershell", lookup)) ??
+            (await findOnPath("pwsh", lookup)) ??
+            (await (async () => {
+                const root = envValue(env, "SystemRoot") ?? "C:\\Windows";
+                const system = win32.join(root, "System32", "WindowsPowerShell", "v1.0", "powershell.exe");
+                return (await exists(system)) ? system : undefined;
+            })());
+        return file ? { tool: "powershell", file, platform } : undefined;
+    }
+    return undefined;
+}
+/** AppleScript run with `osascript -e … title [start]`: inputs arrive as `argv`, never inlined. */
+const APPLESCRIPT = [
+    "on run argv",
+    "set promptText to item 1 of argv",
+    "if (count of argv) > 1 then",
+    "set chosen to choose folder with prompt promptText default location (POSIX file (item 2 of argv))",
+    "else",
+    "set chosen to choose folder with prompt promptText",
+    "end if",
+    "return POSIX path of chosen",
+    "end run",
+];
+/**
+ * Fixed PowerShell script (`-STA` is required by WinForms dialogs). Title and start directory come
+ * from environment variables. Output is UTF-8; a cancelled dialog prints nothing. Falls back to
+ * the Shell.Application folder browser when WinForms is unavailable.
+ */
+const POWERSHELL = [
+    "$ErrorActionPreference = 'Stop'",
+    "[Console]::OutputEncoding = [System.Text.Encoding]::UTF8",
+    "try {",
+    "  Add-Type -AssemblyName System.Windows.Forms",
+    "  $dialog = New-Object System.Windows.Forms.FolderBrowserDialog",
+    "  $dialog.Description = $env:ALISIO_PICKER_TITLE",
+    "  $dialog.ShowNewFolderButton = $true",
+    "  if ($env:ALISIO_PICKER_START) { $dialog.SelectedPath = $env:ALISIO_PICKER_START }",
+    "  $owner = New-Object System.Windows.Forms.Form",
+    "  $owner.TopMost = $true",
+    "  if ($dialog.ShowDialog($owner) -eq [System.Windows.Forms.DialogResult]::OK) { [Console]::Out.Write($dialog.SelectedPath) }",
+    "  $owner.Dispose()",
+    "} catch {",
+    "  $shell = New-Object -ComObject Shell.Application",
+    "  $folder = $shell.BrowseForFolder(0, $env:ALISIO_PICKER_TITLE, 0x51, 0)",
+    "  if ($folder) { [Console]::Out.Write($folder.Self.Path) }",
+    "}",
+].join("\n");
+/** The exact executable, arguments and extra environment for one dialog. */
+export function pickerCommand(strategy, options) {
+    const { title, start } = options;
+    // A trailing separator makes zenity/yad open *inside* the start directory.
+    const inside = start ? `${posix.join(start, "/")}` : undefined;
+    switch (strategy.tool) {
+        case "zenity":
+            return {
+                file: strategy.file,
+                args: [
+                    "--file-selection",
+                    "--directory",
+                    `--title=${title}`,
+                    ...(inside ? [`--filename=${inside}`] : []),
+                ],
+            };
+        case "yad":
+            return {
+                file: strategy.file,
+                args: [
+                    "--file",
+                    "--directory",
+                    `--title=${title}`,
+                    ...(inside ? [`--filename=${inside}`] : []),
+                ],
+            };
+        case "kdialog":
+            return {
+                file: strategy.file,
+                args: ["--getexistingdirectory", ...(start ? [start] : []), "--title", title],
+            };
+        case "osascript":
+            return {
+                file: strategy.file,
+                args: [...APPLESCRIPT.flatMap((line) => ["-e", line]), title, ...(start ? [start] : [])],
+            };
+        case "powershell":
+            return {
+                file: strategy.file,
+                args: ["-NoProfile", "-STA", "-Command", POWERSHELL],
+                env: { ALISIO_PICKER_TITLE: title, ...(start ? { ALISIO_PICKER_START: start } : {}) },
+            };
+    }
+}
+/** Cancel exit codes: 1 (zenity, kdialog, yad, osascript), 5 (zenity timeout), 252 (yad close). */
+const CANCEL_CODES = new Set([1, 5, 252]);
+/**
+ * Maps a dialog's exit to the chosen absolute folder (normalized with the platform's own path
+ * rules: macOS trailing slash, Windows backslashes and drive roots, CRLF), a cancellation, or an
+ * error.
+ */
+export function parsePickerOutput(platform, result) {
+    if (result.timedOut)
+        return { cancelled: true };
+    if (result.code !== 0) {
+        if (result.code !== null && CANCEL_CODES.has(result.code))
+            return { cancelled: true };
+        if (/\(-128\)/.test(result.stderr ?? ""))
+            return { cancelled: true };
+        const detail = (result.stderr ?? "").trim().slice(0, 300);
+        return {
+            error: `Folder dialog exited with ${result.code ?? "a signal"}${detail ? `: ${detail}` : ""}`,
+        };
+    }
+    const line = result.stdout
+        .replace(/^\uFEFF/, "")
+        .split(/\r?\n/)[0]
+        ?.trim() ?? "";
+    if (!line)
+        return { cancelled: true };
+    const api = pathApi(platform);
+    if (!api.isAbsolute(line))
+        return { error: "Folder dialog returned a relative path" };
+    let path = api.normalize(line);
+    const root = api.parse(path).root;
+    while (path.length > root.length && (path.endsWith("/") || path.endsWith(api.sep)))
+        path = path.slice(0, -1);
+    return { path };
+}
+const defaultRun = (file, args, options) => new Promise((resolve) => {
+    execFile(file, args, {
+        encoding: "utf8",
+        timeout: options.timeoutMs,
+        maxBuffer: 64 * 1024,
+        windowsHide: true,
+        env: { ...process.env, ...options.env },
+        ...(options.signal ? { signal: options.signal } : {}),
+    }, (error, stdout, stderr) => {
+        const failure = error;
+        const code = failure ? (typeof failure.code === "number" ? failure.code : null) : 0;
+        resolve({
+            code,
+            stdout: String(stdout ?? ""),
+            stderr: String(stderr ?? failure?.message ?? ""),
+            ...(failure?.killed || failure?.name === "AbortError" ? { timedOut: true } : {}),
+        });
+    });
+});
+/**
+ * A picker over the selected strategy. `strategy` defaults to `selectPicker()` (detected once);
+ * `run` is injectable so tests never open a real dialog.
+ */
+export function createNativePicker(options = {}) {
+    const detected = "strategy" in options
+        ? Promise.resolve(options.strategy)
+        : selectPicker().catch(() => undefined);
+    const run = options.run ?? defaultRun;
+    const timeoutMs = options.timeoutMs ?? 5 * 60_000;
+    let open = false;
+    return {
+        available: async () => !!(await detected),
+        get busy() {
+            return open;
+        },
+        async pick({ title, start, signal }) {
+            if (open)
+                throw new HttpError("picker_busy", "A folder dialog is already open");
+            open = true;
+            try {
+                const strategy = await detected;
+                if (!strategy)
+                    throw new HttpError("picker_unavailable", "No native folder dialog on this server");
+                const command = pickerCommand(strategy, { title, ...(start ? { start } : {}) });
+                const result = await run(command.file, command.args, {
+                    timeoutMs,
+                    ...(command.env ? { env: command.env } : {}),
+                    ...(signal ? { signal } : {}),
+                });
+                const outcome = parsePickerOutput(strategy.platform, result);
+                if ("error" in outcome)
+                    throw new HttpError("picker_unavailable", "The folder dialog could not be opened", {
+                        reason: outcome.error,
+                    });
+                return outcome;
+            }
+            finally {
+                open = false;
+            }
+        },
+    };
+}

package/dist/host/workspace-host.d.ts

@@ -32,6 +32,8 @@ export interface WorkspaceHostOptions {
     create?: typeof createApplication;
     now?: () => number;
 }
+/** Whether a workspace folder is still an accessible directory (a known one may be deleted). */
+export declare function workspaceExists(path: string): Promise<boolean>;
 /** Opaque, stable workspace id: a short sha256 of the canonical path (never a path in URLs). */
 export declare const workspaceId: (path: string) => string;
 /**
@@ -72,14 +74,20 @@ export declare class WorkspaceHost {
     recycle(id: string): Promise<OpenWorkspace | undefined>;
     /** Closes every app in parallel (each close is capped by the core's teardown timeouts). */
     closeAll(): Promise<void>;
-    /** Every known workspace: recorded or with root sessions, the default one and the open ones. */
-    list(): Promise<WorkspaceInfo[]>;
+    /**
+     * Every known workspace: recorded or with root sessions, the default one and the open ones.
+     * `archived` filters like `GET /api/sessions` (`all` by default).
+     */
+    list(archived?: "true" | "false" | "all"): Promise<WorkspaceInfo[]>;
+    /** Whether a canonical workspace path is archived. */
+    archived(path: string): boolean;
     /** The `WorkspaceInfo` of one canonical path. */
     info(path: string, meta?: {
         path: string;
         label?: string;
         pinned: boolean;
         lastOpenedAt?: number;
+        archivedAt?: number;
         sessions: number;
     } | undefined): Promise<WorkspaceInfo>;
     /** Canonical path of a workspace id among the known ones. */

package/dist/host/workspace-host.js

@@ -2,6 +2,17 @@ import { createHash } from "node:crypto";
 import { stat } from "node:fs/promises";
 import { createApplication, findWorkspace, resolveTrust, } from "@alisio/core";
 import { HttpError } from "../http/errors.js";
+const MISSING_ERRNO = new Set(["ENOENT", "ENOTDIR", "EACCES", "EPERM", "ELOOP"]);
+const missing = (path) => new HttpError("workspace_missing", `Workspace folder not found: ${path}`, { path });
+/** Whether a workspace folder is still an accessible directory (a known one may be deleted). */
+export async function workspaceExists(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 /** Opaque, stable workspace id: a short sha256 of the canonical path (never a path in URLs). */
 export const workspaceId = (path) => createHash("sha256").update(path).digest("hex").slice(0, 16);
 /**
@@ -48,6 +59,9 @@ export class WorkspaceHost {
     async openPath(path) {
         if (this.closed)
             throw new HttpError("shutting_down", "Server is shutting down");
+        // A known workspace (from old sessions) may have been deleted or moved: 404, never a 500.
+        if (!(await workspaceExists(path)))
+            throw missing(path);
         const id = workspaceId(path);
         const existing = this.open.get(id);
         if (existing) {
@@ -70,12 +84,22 @@ export class WorkspaceHost {
         const explicit = !!base.trustProject || !!base.config;
         const trust = explicit ? undefined : await resolveTrust(path);
         const trusted = explicit || !!trust?.trusted;
-        const app = await (this.options.create ?? createApplication)({
-            ...base,
-            trustProject: explicit ? base.trustProject : trusted,
-            cwd: path,
-            ...(this.options.wire?.(id, path) ?? {}),
-        });
+        let app;
+        try {
+            app = await (this.options.create ?? createApplication)({
+                ...base,
+                trustProject: explicit ? base.trustProject : trusted,
+                cwd: path,
+                ...(this.options.wire?.(id, path) ?? {}),
+            });
+        }
+        catch (error) {
+            // The folder vanished between the check and the open (the core canonicalizes it).
+            const code = error?.code;
+            if (code && MISSING_ERRNO.has(code) && !(await workspaceExists(path)))
+                throw missing(path);
+            throw error;
+        }
         const entry = {
             id,
             path,
@@ -145,8 +169,11 @@ export class WorkspaceHost {
         await Promise.allSettled([...this.opening.values()]);
         await Promise.allSettled(this.entries().map((w) => this.close(w.id)));
     }
-    /** Every known workspace: recorded or with root sessions, the default one and the open ones. */
-    async list() {
+    /**
+     * Every known workspace: recorded or with root sessions, the default one and the open ones.
+     * `archived` filters like `GET /api/sessions` (`all` by default).
+     */
+    async list(archived = "all") {
         const known = new Map(this.options.catalog.workspaces().map((w) => [w.path, w]));
         const paths = new Set(known.keys());
         for (const w of this.open.values())
@@ -156,7 +183,12 @@ export class WorkspaceHost {
             : undefined;
         if (fallback)
             paths.add(fallback);
-        return Promise.all([...paths].sort().map((path) => this.info(path, known.get(path))));
+        const infos = await Promise.all([...paths].sort().map((path) => this.info(path, known.get(path))));
+        return archived === "all" ? infos : infos.filter((w) => w.archived === (archived === "true"));
+    }
+    /** Whether a canonical workspace path is archived. */
+    archived(path) {
+        return this.options.catalog.workspaces().some((w) => w.path === path && !!w.archivedAt);
     }
     /** The `WorkspaceInfo` of one canonical path. */
     async info(path, meta = this.options.catalog.workspaces().find((w) => w.path === path)) {
@@ -164,7 +196,8 @@ export class WorkspaceHost {
         const entry = this.open.get(id);
         let trusted = entry?.trusted ?? false;
         let untrusted = entry?.untrustedResources ?? false;
-        if (!entry) {
+        const exists = await workspaceExists(path);
+        if (!entry && exists) {
             const base = this.options.base;
             if (base.trustProject || base.config)
                 trusted = true;
@@ -180,8 +213,10 @@ export class WorkspaceHost {
             ...(meta?.label ? { label: meta.label } : {}),
             pinned: meta?.pinned ?? false,
             open: !!entry,
+            exists,
             trusted,
             untrustedResources: untrusted,
+            archived: !!meta?.archivedAt,
             ...(meta?.lastOpenedAt !== undefined ? { lastOpenedAt: meta.lastOpenedAt } : {}),
         };
     }

package/dist/http/errors.js

@@ -9,6 +9,7 @@ export const STATUS = {
     session_busy: 409,
     session_locked: 409,
     workspace_limit: 503,
+    workspace_missing: 404,
     payload_too_large: 413,
     unsupported_media_type: 415,
     path_outside_workspace: 403,
@@ -22,6 +23,11 @@ export const STATUS = {
     protocol_mismatch: 426,
     shutting_down: 503,
     stream_limit: 503,
+    workspace_archived: 409,
+    picker_busy: 409,
+    picker_unavailable: 503,
+    permission_denied: 403,
+    cancelled: 409,
     internal: 500,
 };
 /** A typed API failure; routes throw it and the server renders it as an `ApiError` body. */