windows-development-sandbox 1.4.1 → 1.5.0

package/dist/shared/paths.js

@@ -1,28 +0,0 @@
-// Path translation between this PC and the sandbox (shared by the host history sync and the guest plugin fix-up).
-import { sandboxFolder } from './guest-paths.js';
-/** Claude Code's per-project folder name: every non-alphanumeric character becomes '-' (F:\A\b -> F--A-b). */
-export const projectFolderName = (workspace) => workspace.replace(/[^a-zA-Z0-9]/g, '-');
-/**
- * Every path the guest may know its workspace by, the real one first: a mirrored F:\A\b is a subst drive onto
- * C:\Mirror\F\A\b, and programs that resolve real paths (realpath, GetFinalPathNameByHandle) report that one.
- */
-export const guestWorkspaceAliases = (guestWorkspace) => {
-    const real = sandboxFolder(guestWorkspace);
-    return real.toLowerCase() === guestWorkspace.toLowerCase() ? [guestWorkspace] : [real, guestWorkspace];
-};
-const DEVICE_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$/i;
-/**
- * A file or folder name that is safe to recreate on this PC. The sandbox can create names Windows would treat as devices
- * (CON.jsonl opens the console), as streams (a:b), or that end in a dot or space (silently renamed); none of them are copied.
- */
-export const isSafeFileName = (name) => name !== '' && name.length <= 200 && name !== '.' && name !== '..' && !/[<>:"|?*/\\\x00-\x1f]/.test(name) && !/[. ]$/.test(name) && !DEVICE_NAME.test(name);
-const jsonEscaped = (p) => JSON.stringify(p).slice(1, -1);
-const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const forward = (p) => p.replace(/\\/g, '/');
-/** Rewrites `from` to `to` wherever it appears as a whole path (raw, JSON-escaped or with forward slashes). */
-export const translatePaths = (text, from, to) => {
-    if (from.toLowerCase() === to.toLowerCase())
-        return text;
-    const pairs = [[jsonEscaped(from), jsonEscaped(to)], [from, to], [forward(from), forward(to)]];
-    return pairs.reduce((out, [a, b]) => out.replace(new RegExp(escapeRegex(a) + '(?=\\\\|/|"|\'|\\s|$)', 'gi'), b.replace(/\$/g, '$$$$')), text);
-};

package/dist/shared/projects.d.ts

@@ -1,76 +0,0 @@
-/** Where project roots appear inside the sandbox. */
-export declare const PROJECTS_GUEST = "C:\\Projects";
-/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
-export declare const WORKSPACES_GUEST = "C:\\Workspace";
-/**
- * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
- * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
- */
-export declare const autoGuestFolder: (hostDir: string) => string;
-/** How a project got into the sandbox. */
-export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
-/** One project the running sandbox works on. */
-export interface ProjectEntry {
-    name: string;
-    host: string;
-    guest: string;
-    primary: boolean;
-    mechanism: Mechanism;
-}
-/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
-export declare const isWithin: (parent: string, child: string) => boolean;
-/**
- * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
- * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
- */
-export declare const hubName: (hostDir: string, taken: Iterable<string>) => string;
-/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
-export declare const projectForHostDir: <P extends {
-    host: string;
-}>(projects: P[], hostDir: string) => P | null;
-/** The same for a folder inside the sandbox. */
-export declare const projectForGuestDir: <P extends {
-    guest: string;
-}>(projects: P[], guestDir: string) => P | null;
-/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
-export declare const guestDirFor: (mapped: {
-    host: string;
-    guest: string;
-}, hostDir: string) => string;
-/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
-export declare const hostDirFor: (mapped: {
-    host: string;
-    guest: string;
-}, guestDir: string) => string;
-/** Strictly below `parent` (never `parent` itself). */
-export declare const isBelow: (parent: string, child: string) => boolean;
-/**
- * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
- * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
- */
-export declare const insideProjects: (guestDir: string, roots?: string[], projectsDir?: string) => boolean;
-export interface RootMapping {
-    host: string;
-    guest: string;
-}
-/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
-export declare const usableRoots: (roots: string[], exists: (dir: string) => boolean) => string[];
-/**
- * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
- * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
- */
-export declare const ownGuestFolder: (hostDir: string, mirror: boolean, taken?: string[]) => string;
-/**
- * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
- * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each
- * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
- */
-export declare const planProjectMappings: (roots: string[], projects: string[], mirror: boolean, taken?: string[]) => {
-    roots: RootMapping[];
-    projects: RootMapping[];
-};
-/**
- * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
- * the sandbox. Null when it is in no root.
- */
-export declare const rootGuestDir: (roots: string[], mirror: boolean, hostDir: string) => string | null;

package/dist/shared/projects.js

@@ -1,126 +0,0 @@
-// Several projects in one running sandbox. Windows Sandbox fixes its mapped folders at boot, so a project can only
-// join a running sandbox when it is already visible inside:
-//  - the launch folder (mapped directly, or shown by the project root it is in);
-//  - a folder inside a project root (projects.roots: whole folders of projects, mapped at every start), including
-//    projects created after boot;
-//  - projects mapped at boot because they were in use when the sandbox was restarted to add them;
-//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested).
-// A project is at the same place inside the sandbox whichever project started it (git worktrees and Claude's project
-// folders store absolute paths):
-//  - a project inside a root is always under the root's folder, C:\Projects\<root>\<name> (also as the launch folder);
-//  - any other project, mapped on its own, is always at C:\Workspace\<name> (also when it is mapped at boot or shared).
-// With guestWorkspace "mirror" both appear at their PC paths when the sandbox can show them there.
-// Pure functions only: used by the host (registration, commands), the guest (daemon checks) and the tests.
-import path from 'node:path';
-import { isValidGuestPath, planMirrorWorkspace } from './guest-paths.js';
-/** Where project roots appear inside the sandbox. */
-export const PROJECTS_GUEST = 'C:\\Projects';
-/** Where projects mapped on their own appear (the launch folder with guestWorkspace "auto", boot-mapped and shared ones). */
-export const WORKSPACES_GUEST = 'C:\\Workspace';
-/**
- * guestWorkspace "auto" for a folder: C:\Workspace\<folder name>. Keeping the real folder name means Claude's
- * per-project history and claude-mem's project name match this PC instead of every project being "Workspace".
- */
-export const autoGuestFolder = (hostDir) => {
-    const name = path.win32.basename(hostDir.replace(/[\\/]+$/, '')).replace(/[^A-Za-z0-9._ -]/g, '_').replace(/^[. ]+|[. ]+$/g, '');
-    return WORKSPACES_GUEST + '\\' + (name || 'project');
-};
-const norm = (p) => path.win32.resolve(p).replace(/[\\/]+$/, '').toLowerCase();
-/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
-export const isWithin = (parent, child) => {
-    const a = norm(parent);
-    const b = norm(child);
-    return a === b || b.startsWith(a.endsWith('\\') ? a : a + '\\');
-};
-/**
- * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
- * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
- */
-export const hubName = (hostDir, taken) => {
-    const base = path.win32.basename(path.win32.resolve(hostDir)).replace(/[^A-Za-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'project';
-    const used = new Set([...taken].map((t) => t.toLowerCase()));
-    if (!used.has(base.toLowerCase()))
-        return base;
-    for (let i = 2;; i++)
-        if (!used.has((base + '-' + i).toLowerCase()))
-            return base + '-' + i;
-};
-/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
-export const projectForHostDir = (projects, hostDir) => projects.filter((p) => isWithin(p.host, hostDir)).sort((a, b) => b.host.length - a.host.length)[0] ?? null;
-/** The same for a folder inside the sandbox. */
-export const projectForGuestDir = (projects, guestDir) => projects.filter((p) => isWithin(p.guest, guestDir)).sort((a, b) => b.guest.length - a.guest.length)[0] ?? null;
-/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
-export const guestDirFor = (mapped, hostDir) => {
-    const rel = path.win32.relative(path.win32.resolve(mapped.host), path.win32.resolve(hostDir));
-    return rel ? path.win32.join(mapped.guest, rel) : mapped.guest;
-};
-/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
-export const hostDirFor = (mapped, guestDir) => {
-    const rel = path.win32.relative(path.win32.resolve(mapped.guest), path.win32.resolve(guestDir));
-    return rel ? path.win32.join(mapped.host, rel) : mapped.host;
-};
-/** Strictly below `parent` (never `parent` itself). */
-export const isBelow = (parent, child) => isWithin(parent, child) && norm(parent) !== norm(child);
-/**
- * A guest folder some project can be in: below C:\Projects or C:\Workspace (projects mapped on their own, also shared
- * after boot), or inside one of `roots` (the roots' and boot-mapped projects' guest paths).
- */
-export const insideProjects = (guestDir, roots = [], projectsDir = PROJECTS_GUEST) => isBelow(projectsDir, guestDir) || isBelow(WORKSPACES_GUEST, guestDir) || roots.some((r) => isWithin(r, guestDir));
-const resolveDir = (dir) => path.win32.resolve(dir).replace(/[\\/]+$/, '');
-/** The project roots that are mapped, in order: existing folders, none inside a root listed before it. */
-export const usableRoots = (roots, exists) => {
-    const out = [];
-    for (const root of roots.map(resolveDir))
-        if (exists(root) && !out.some((r) => isWithin(r, root)))
-            out.push(root);
-    return out;
-};
-/**
- * Where a project mapped on its own appears, the same place it has as the launch folder: with "mirror" its PC path
- * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
- */
-export const ownGuestFolder = (hostDir, mirror, taken = []) => {
-    const host = resolveDir(hostDir);
-    const free = (guest) => !taken.some((t) => isWithin(t, guest) || isWithin(guest, t));
-    const mirrored = mirror ? planMirrorWorkspace(host, '').guest : '';
-    if (mirrored && !isWithin(PROJECTS_GUEST, mirrored) && !isWithin(WORKSPACES_GUEST, mirrored) && free(mirrored))
-        return mirrored;
-    const base = autoGuestFolder(host);
-    if (free(base))
-        return base;
-    for (let i = 2;; i++)
-        if (free(base + '-' + i))
-            return base + '-' + i;
-};
-/**
- * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
- * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each
- * other). A root's folder depends only on the roots, so every launch with the same roots shows them at the same place.
- */
-export const planProjectMappings = (roots, projects, mirror, taken = []) => {
-    const names = [];
-    const placeRoot = (host) => {
-        const resolved = resolveDir(host);
-        if (mirror && isValidGuestPath(resolved) && !isWithin(PROJECTS_GUEST, resolved))
-            return { host: resolved, guest: resolved };
-        const name = hubName(resolved, names);
-        names.push(name);
-        return { host: resolved, guest: path.win32.join(PROJECTS_GUEST, name) };
-    };
-    const planned = roots.map(placeRoot);
-    const used = [...taken, ...planned.map((r) => r.guest)];
-    const placed = projects.map((p) => {
-        const guest = ownGuestFolder(p, mirror, used);
-        used.push(guest);
-        return { host: resolveDir(p), guest };
-    });
-    return { roots: planned, projects: placed };
-};
-/**
- * Where a folder inside one of the (usable) roots appears: under the root's guest folder, whichever project started
- * the sandbox. Null when it is in no root.
- */
-export const rootGuestDir = (roots, mirror, hostDir) => {
-    const root = projectForHostDir(planProjectMappings(roots, [], mirror).roots, hostDir);
-    return root ? guestDirFor(root, hostDir) : null;
-};

package/dist/shared/pty-client.d.ts

@@ -1,108 +0,0 @@
-import net from 'node:net';
-export declare const FrameType: {
-    readonly Hello: 1;
-    readonly Input: 2;
-    readonly Resize: 3;
-    readonly Restart: 4;
-    readonly Ping: 5;
-    readonly Output: 16;
-    readonly Exit: 17;
-    readonly Error: 18;
-    readonly Restarting: 19;
-    readonly Status: 20;
-    readonly Console: 21;
-};
-/** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
-export declare const HelloFlag: {
-    readonly ControlOnly: 1;
-    readonly Query: 2;
-};
-/** Viewers ping this often; ptyhost counts a viewer as gone after 15 s of silence (e.g. its terminal tab was closed). */
-export declare const PING_INTERVAL_MS = 5000;
-export interface Frame {
-    type: number;
-    payload: Buffer;
-}
-export interface Endpoint {
-    addresses: string[];
-    port: number;
-    token: string;
-}
-export type ClientResult = {
-    reason: 'exit';
-    exitCode: number;
-} | {
-    reason: 'detach' | 'closed';
-} | {
-    reason: 'error';
-    message: string;
-};
-/** Turns off every mouse tracking mode a program may have turned on in your terminal (normal, button, any, UTF-8, SGR, urxvt). */
-export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
-/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
-export declare const DETACH_KEY = 29;
-export declare const encodeFrame: (type: number, payload?: Buffer) => Buffer;
-export declare const helloFrame: (token: string, cols: number, rows: number, flags?: number) => Buffer;
-export declare const resizeFrame: (cols: number, rows: number) => Buffer;
-/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
-export declare const MAX_FRAME_BYTES: number;
-/** Splits a TCP byte stream back into frames. */
-export declare class FrameReader {
-    private pending;
-    push(chunk: Buffer): Frame[];
-}
-/**
- * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
- * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
- * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
- * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
- */
-export declare class OutputFilter {
-    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
-    private state;
-    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
-    private body;
-    push(chunk: Buffer): Buffer;
-}
-/** Tries every address the sandbox published and returns the first one that answers. */
-export declare const connect: (endpoint: Endpoint, timeoutMs?: number) => Promise<net.Socket>;
-/** Sends one control frame (e.g. RESTART) without taking over the screen. */
-export declare const sendControl: (endpoint: Endpoint, type: number) => Promise<void>;
-/** Who is watching a session right now: `remote` counts viewers on the PC (not the sandbox's own tabs). */
-export interface Viewers {
-    viewers: number;
-    remote: number;
-}
-/**
- * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
- * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
- * treats the query as a silent control connection, so the caller must not assume anything.
- */
-export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => Promise<Viewers | null>;
-/**
- * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
- * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
- */
-export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
-/** How long an unfinished escape sequence is held back waiting for the rest (a lone Esc key press waits this long). */
-export declare const JOIN_MS = 30;
-/**
- * Keeps each escape sequence typed into your terminal (keys, mouse reports, the terminal's replies) in one INPUT frame.
- * The console can hand one over in pieces; ConPTY reads a lone "ESC[" as Alt+[ and the rest as typed text, so a split
- * Right arrow (ESC[C) left a stray "C" in the agent's prompt. An unfinished sequence at the end of a chunk is held
- * until the rest arrives (or JOIN_MS passes).
- */
-export declare class InputJoiner {
-    private held;
-    /** The bytes to send now; an unfinished sequence at the end is kept for the next chunk. */
-    push(chunk: Buffer): Buffer;
-    holding(): boolean;
-    flush(): Buffer;
-}
-/**
- * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
- * the detach key. Restores the terminal before resolving.
- */
-export declare const runTerminalClient: (socket: net.Socket, token: string, options?: {
-    detachKey?: number;
-}) => Promise<ClientResult>;