@termfleet/core 0.1.0

package/dist/background-runner.d.ts

@@ -0,0 +1,3 @@
+export declare function leaseDirForPaneTarget(target: string): string;
+export declare function ensureBackgroundRunner(): string;
+export declare function ensureLeaseDir(target: string): string;

package/dist/background-runner.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+const RUNNER_PATH = join(tmpdir(), "termfleet-background-runner.sh");
+export function leaseDirForPaneTarget(target) {
+    if (!target) {
+        throw new Error("A pane target is required for lifecycle leases.");
+    }
+    return join(tmpdir(), "termfleet-background-leases", encodeURIComponent(target));
+}
+export function ensureBackgroundRunner() {
+    const script = `#!/bin/sh
+set -eu
+# Lease files record the full command line — keep them owner-only (0600) and the
+# lease dir 0700 so other local users can't read them while a job runs.
+umask 077
+if [ "$#" -lt 1 ]; then
+  echo "usage: $0 command [args...]" >&2
+  exit 64
+fi
+if [ -z "\${TERMFLEET_BACKGROUND_LEASE_DIR:-}" ]; then
+  echo "TERMFLEET_BACKGROUND_LEASE_DIR is required" >&2
+  exit 64
+fi
+mkdir -p "$TERMFLEET_BACKGROUND_LEASE_DIR"
+"$@" &
+pid="$!"
+start_time="$(ps -p "$pid" -o lstart= | sed 's/^ *//;s/ *$//')"
+if [ -z "$start_time" ]; then
+  echo "Could not read process start time for $pid" >&2
+  kill "$pid" 2>/dev/null || true
+  exit 70
+fi
+lease="$TERMFLEET_BACKGROUND_LEASE_DIR/$pid.json"
+tmp="$lease.$$"
+printf '{"pid":%s,"processStartTime":%s,"command":%s}\\n' \
+  "$pid" \
+  "$(printf '%s' "$start_time" | node -pe 'JSON.stringify(require("fs").readFileSync(0, "utf8"))')" \
+  "$(printf '%s' "$*" | node -pe 'JSON.stringify(require("fs").readFileSync(0, "utf8"))')" > "$tmp"
+mv "$tmp" "$lease"
+wait "$pid"
+status="$?"
+rm -f "$lease"
+exit "$status"
+`;
+    if (!existsSync(RUNNER_PATH)) {
+        writeFileSync(RUNNER_PATH, script, { mode: 0o700 });
+    }
+    return RUNNER_PATH;
+}
+export function ensureLeaseDir(target) {
+    const dir = leaseDirForPaneTarget(target);
+    mkdirSync(dir, { mode: 0o700, recursive: true });
+    return dir;
+}

package/dist/boot-queue.d.ts

@@ -0,0 +1,35 @@
+/**
+ * BootQueue — a small FIFO async concurrency gate for agent boots ("the door").
+ *
+ * Booting an agent (`agent:create`: open a window, wait for the shell, send the
+ * launch command, wait for the agent's first response) is the scarce, slow,
+ * roughly-serial operation on a provider. A burst of concurrent boots stampedes
+ * it and the later ones exceed their timeout.
+ *
+ * This gate holds a slot ONLY for the duration of one boot and releases it the
+ * instant the boot resolves or rejects (ready-or-timeout) — never for the
+ * agent's running life. So the queue moves at boot-speed: it only ever paces how
+ * many boots are in flight at once (`maxConcurrent`), not how many agents run.
+ *
+ * It is intentionally a queue (wait your turn) rather than a reject: getting
+ * through the door is transient, so a brief wait is correct; rejecting would
+ * just churn. (Steady-state run-concurrency is a separate concern handled by the
+ * caller via reject + reconcile.)
+ */
+export declare class BootQueue {
+    private active;
+    private readonly waiters;
+    private readonly maxConcurrent;
+    constructor(maxConcurrent: number);
+    /** Boots currently holding a slot (in flight). */
+    get inFlight(): number;
+    /** Boots waiting for a slot. */
+    get queued(): number;
+    /**
+     * Run a boot through the gate. Waits (FIFO) until a slot is free, runs the
+     * boot, and releases the slot when it settles — success or failure alike.
+     */
+    run<T>(boot: () => Promise<T>): Promise<T>;
+    private acquire;
+    private release;
+}

package/dist/boot-queue.js

@@ -0,0 +1,66 @@
+/**
+ * BootQueue — a small FIFO async concurrency gate for agent boots ("the door").
+ *
+ * Booting an agent (`agent:create`: open a window, wait for the shell, send the
+ * launch command, wait for the agent's first response) is the scarce, slow,
+ * roughly-serial operation on a provider. A burst of concurrent boots stampedes
+ * it and the later ones exceed their timeout.
+ *
+ * This gate holds a slot ONLY for the duration of one boot and releases it the
+ * instant the boot resolves or rejects (ready-or-timeout) — never for the
+ * agent's running life. So the queue moves at boot-speed: it only ever paces how
+ * many boots are in flight at once (`maxConcurrent`), not how many agents run.
+ *
+ * It is intentionally a queue (wait your turn) rather than a reject: getting
+ * through the door is transient, so a brief wait is correct; rejecting would
+ * just churn. (Steady-state run-concurrency is a separate concern handled by the
+ * caller via reject + reconcile.)
+ */
+export class BootQueue {
+    active = 0;
+    waiters = [];
+    maxConcurrent;
+    constructor(maxConcurrent) {
+        this.maxConcurrent = Math.max(1, Math.floor(maxConcurrent));
+    }
+    /** Boots currently holding a slot (in flight). */
+    get inFlight() {
+        return this.active;
+    }
+    /** Boots waiting for a slot. */
+    get queued() {
+        return this.waiters.length;
+    }
+    /**
+     * Run a boot through the gate. Waits (FIFO) until a slot is free, runs the
+     * boot, and releases the slot when it settles — success or failure alike.
+     */
+    async run(boot) {
+        await this.acquire();
+        try {
+            return await boot();
+        }
+        finally {
+            this.release();
+        }
+    }
+    acquire() {
+        if (this.active < this.maxConcurrent) {
+            this.active += 1;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    release() {
+        const next = this.waiters.shift();
+        if (next) {
+            // Hand the held slot directly to the next waiter (active count unchanged).
+            next();
+        }
+        else {
+            this.active -= 1;
+        }
+    }
+}

package/dist/build-info.d.ts

@@ -0,0 +1,5 @@
+export type TermfleetBuildInfo = {
+    buildSha?: string;
+    version: string;
+};
+export declare function getTermfleetBuildInfo(): TermfleetBuildInfo;

package/dist/build-info.js

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedBuildInfo;
+export function getTermfleetBuildInfo() {
+    if (cachedBuildInfo) {
+        return cachedBuildInfo;
+    }
+    const version = process.env.TERMFLEET_VERSION?.trim() || readPackageVersion();
+    const buildSha = process.env.TERMFLEET_BUILD_SHA?.trim() || readGitBuildSha();
+    cachedBuildInfo = {
+        ...(buildSha ? { buildSha } : {}),
+        version
+    };
+    return cachedBuildInfo;
+}
+function readPackageVersion() {
+    try {
+        const packageFile = join(dirname(dirname(dirname(fileURLToPath(import.meta.url)))), "package.json");
+        const packageJson = JSON.parse(readFileSync(packageFile, "utf8"));
+        return typeof packageJson.version === "string" && packageJson.version.trim() ? packageJson.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function readGitBuildSha() {
+    try {
+        return execFileSync("git", ["rev-parse", "--short=12", "HEAD"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"]
+        }).trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/collab/canvas-doc.d.ts

@@ -0,0 +1,47 @@
+import type { AuthOrganizationId } from "../contracts/auth.js";
+import type { CanvasComment, CanvasPoint } from "../contracts/canvas.js";
+import type { ConsoleLayout, ProviderGroupAppearance } from "../contracts/console-layout.js";
+import * as Y from "yjs";
+export declare const LAYOUT_GROUPS_KEY = "providerGroups";
+export declare const META_KEY = "meta";
+export declare const COMMENTS_KEY = "comments";
+export declare const VIEWPORT_FIELD = "viewport";
+export type CanvasGroupLayout = {
+    appearance?: ProviderGroupAppearance;
+    position?: {
+        x: number;
+        y: number;
+    };
+};
+export declare function layoutGroups(doc: Y.Doc): Y.Map<CanvasGroupLayout>;
+export declare function commentsMap(doc: Y.Doc): Y.Map<CanvasComment>;
+export declare function metaMap(doc: Y.Doc): Y.Map<unknown>;
+export declare function readCanvasLayout(doc: Y.Doc): ConsoleLayout;
+export declare function writeCanvasLayout(doc: Y.Doc, layout: ConsoleLayout): void;
+export declare function writeCanvasGroup(doc: Y.Doc, groupId: string, group: CanvasGroupLayout): void;
+export declare function readCanvasComments(doc: Y.Doc): CanvasComment[];
+export declare function upsertCanvasComment(doc: Y.Doc, comment: CanvasComment): void;
+export type CanvasAwarenessUser = {
+    color?: string;
+    email: string;
+    fullName: string;
+    id: string;
+    imageUrl?: string;
+};
+export type CanvasAwarenessState = {
+    canvasId: string;
+    cursor?: CanvasPoint;
+    organizationId: AuthOrganizationId;
+    selection?: string[];
+    user: CanvasAwarenessUser;
+    viewport?: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+};
+export declare function canvasRoom(organizationId: AuthOrganizationId, canvasId: string): string;
+export declare function parseCanvasRoom(room: string): {
+    canvasId: string;
+    organizationId: AuthOrganizationId;
+} | undefined;

package/dist/collab/canvas-doc.js

@@ -0,0 +1,83 @@
+// The shared-canvas state, modeled as ONE Y.Doc (the Track C collab engine). CRDT
+// merge replaces the socket "last write wins" broadcast, so two people dragging
+// different machines — or commenting at once — converge instead of clobbering.
+//
+//   providerGroups : Y.Map<groupId, { appearance?, position? }>  (per-machine merge)
+//   meta           : Y.Map (the shared viewport, doc-version marker)
+//   comments       : Y.Map<commentId, CanvasComment>             (keyed ⇒ idempotent)
+//
+// This IS the one-owner layout seam (machineLayoutKey / console-layout), not a
+// rival store — readCanvasLayout/writeCanvasLayout translate the SAME ConsoleLayout
+// shape the rest of the app uses. Ephemeral presence (cursor / viewport / selection
+// per user) lives in awareness (canvas-awareness.ts), never in the doc.
+export const LAYOUT_GROUPS_KEY = "providerGroups";
+export const META_KEY = "meta";
+export const COMMENTS_KEY = "comments";
+export const VIEWPORT_FIELD = "viewport";
+export function layoutGroups(doc) {
+    return doc.getMap(LAYOUT_GROUPS_KEY);
+}
+export function commentsMap(doc) {
+    return doc.getMap(COMMENTS_KEY);
+}
+export function metaMap(doc) {
+    return doc.getMap(META_KEY);
+}
+// --- Layout (the shared ConsoleLayout) ---
+export function readCanvasLayout(doc) {
+    const providerGroups = {};
+    for (const [id, value] of layoutGroups(doc).entries()) {
+        providerGroups[id] = value;
+    }
+    const viewport = metaMap(doc).get(VIEWPORT_FIELD);
+    return { providerGroups, ...(viewport ? { viewport } : {}) };
+}
+// Reconcile the doc to a full ConsoleLayout: upsert every group, prune the ones
+// that no longer exist, and set the shared viewport — all in ONE transaction so
+// observers see a single coherent change, not a partial layout mid-write.
+export function writeCanvasLayout(doc, layout) {
+    doc.transact(() => {
+        const groups = layoutGroups(doc);
+        const next = new Set(Object.keys(layout.providerGroups));
+        for (const id of [...groups.keys()]) {
+            if (!next.has(id)) {
+                groups.delete(id);
+            }
+        }
+        for (const [id, value] of Object.entries(layout.providerGroups)) {
+            groups.set(id, value);
+        }
+        if (layout.viewport) {
+            metaMap(doc).set(VIEWPORT_FIELD, layout.viewport);
+        }
+    });
+}
+// Merge ONE group's layout without touching the others — the granular write the
+// board issues when a single machine is dragged or restyled (the CRDT win over
+// broadcasting the whole layout).
+export function writeCanvasGroup(doc, groupId, group) {
+    layoutGroups(doc).set(groupId, group);
+}
+// --- Comments ---
+export function readCanvasComments(doc) {
+    return [...commentsMap(doc).values()].sort((left, right) => left.createdAt - right.createdAt);
+}
+export function upsertCanvasComment(doc, comment) {
+    commentsMap(doc).set(comment.id, comment);
+}
+// The room name a canvas syncs under — org-scoped so two orgs never share a doc.
+export function canvasRoom(organizationId, canvasId) {
+    return `canvas:${organizationId}:${canvasId}`;
+}
+// Inverse of canvasRoom: recover the org + canvas from a room name, so the collab
+// server can authorize a connection against the right organization. Returns
+// undefined for anything that isn't a canvas room.
+export function parseCanvasRoom(room) {
+    const match = /^canvas:([^:]+):(.+)$/.exec(room);
+    const organizationId = match?.[1];
+    const canvasId = match?.[2];
+    if (!organizationId || !canvasId) {
+        return undefined;
+    }
+    return { canvasId, organizationId: organizationId };
+}

package/dist/contracts/auth.d.ts

@@ -0,0 +1,77 @@
+export type AuthUserId = `user_${string}`;
+export type AuthOrganizationId = `org_${string}`;
+export type AuthSessionId = `sess_${string}`;
+export type AuthEmailAddress = {
+    id: string;
+    emailAddress: string;
+    verification: {
+        status: "verified" | "unverified";
+    };
+};
+export type AuthUser = {
+    id: AuthUserId;
+    object: "user";
+    username: string | null;
+    firstName: string | null;
+    lastName: string | null;
+    fullName: string;
+    primaryEmailAddressId: string;
+    primaryEmailAddress: AuthEmailAddress;
+    emailAddresses: AuthEmailAddress[];
+    imageUrl: string;
+    createdAt: number;
+    updatedAt: number;
+};
+export type AuthOrganization = {
+    id: AuthOrganizationId;
+    object: "organization";
+    name: string;
+    slug: string;
+    imageUrl: string;
+    createdBy: AuthUserId;
+    createdAt: number;
+    updatedAt: number;
+};
+export type AuthOrganizationMembershipRole = "org:admin" | "org:member";
+export type AuthOrganizationMembership = {
+    id: string;
+    object: "organization_membership";
+    role: AuthOrganizationMembershipRole;
+    organization: AuthOrganization;
+    publicUserData: {
+        userId: AuthUserId;
+        firstName: string | null;
+        lastName: string | null;
+        imageUrl: string;
+        identifier: string;
+    };
+    createdAt: number;
+    updatedAt: number;
+};
+export type AuthSessionStatus = "active" | "ended";
+export type AuthSession = {
+    id: AuthSessionId;
+    object: "session";
+    status: AuthSessionStatus;
+    userId: AuthUserId;
+    activeOrganizationId: AuthOrganizationId | null;
+    lastActiveAt: number;
+    expireAt: number;
+    abandonAt: number;
+    createdAt: number;
+    updatedAt: number;
+};
+export type AuthSessionResource = {
+    object: "session_resource";
+    session: AuthSession;
+    user: AuthUser;
+    organizationMemberships: AuthOrganizationMembership[];
+    activeOrganization: AuthOrganization | null;
+};
+export type AuthSignInResponse = {
+    object: "sign_in";
+    status: "complete";
+    createdSessionId: AuthSessionId;
+    sessionToken: string;
+    sessionResource: AuthSessionResource;
+};

package/dist/contracts/auth.js

@@ -0,0 +1 @@
+export {};

package/dist/contracts/canvas.d.ts

@@ -0,0 +1,34 @@
+import type { AuthOrganizationId } from "./auth.js";
+export type CanvasPoint = {
+    x: number;
+    y: number;
+};
+export type CanvasCommentsFilter = "open" | "resolved";
+export type CanvasComment = {
+    author: {
+        fullName: string;
+        id: string;
+        imageUrl?: string;
+    };
+    body: string;
+    canvasId: string;
+    coordinateSpace: "canvas";
+    createdAt: number;
+    id: string;
+    organizationId: AuthOrganizationId;
+    position: CanvasPoint;
+    replies: CanvasCommentReply[];
+    resolvedAt?: number;
+};
+export type CanvasCommentReply = {
+    author: {
+        fullName: string;
+        id: string;
+        imageUrl?: string;
+    };
+    body: string;
+    createdAt: number;
+    id: string;
+};
+export declare function parseCanvasCommentsList(payload: unknown): CanvasComment[];
+export declare function parseCanvasComment(payload: unknown): CanvasComment;

package/dist/contracts/canvas.js

@@ -0,0 +1,76 @@
+export function parseCanvasCommentsList(payload) {
+    const source = payload && typeof payload === "object" ? payload.comments : undefined;
+    return Array.isArray(source)
+        ? source.map((comment) => {
+            try {
+                return parseCanvasComment(comment);
+            }
+            catch {
+                return undefined;
+            }
+        }).filter((comment) => Boolean(comment))
+        : [];
+}
+export function parseCanvasComment(payload) {
+    if (!payload || typeof payload !== "object") {
+        throw new Error("Canvas comment payload is required.");
+    }
+    const source = payload;
+    const createdAt = Number(source.createdAt);
+    const x = Number(source.position?.x);
+    const y = Number(source.position?.y);
+    if (typeof source.id !== "string" ||
+        typeof source.canvasId !== "string" ||
+        source.coordinateSpace !== "canvas" ||
+        typeof source.organizationId !== "string" ||
+        typeof source.body !== "string" ||
+        !source.author ||
+        typeof source.author.id !== "string" ||
+        typeof source.author.fullName !== "string" ||
+        !Number.isFinite(createdAt) ||
+        !Number.isFinite(x) ||
+        !Number.isFinite(y)) {
+        throw new Error("Canvas comment payload is malformed.");
+    }
+    return {
+        author: {
+            fullName: source.author.fullName,
+            id: source.author.id,
+            imageUrl: source.author.imageUrl
+        },
+        body: source.body,
+        canvasId: source.canvasId,
+        coordinateSpace: "canvas",
+        createdAt,
+        id: source.id,
+        organizationId: source.organizationId,
+        position: { x, y },
+        replies: Array.isArray(source.replies) ? source.replies.map(parseCanvasCommentReply).filter((reply) => Boolean(reply)) : [],
+        resolvedAt: source.resolvedAt
+    };
+}
+function parseCanvasCommentReply(payload) {
+    if (!payload || typeof payload !== "object") {
+        return undefined;
+    }
+    const source = payload;
+    const createdAt = Number(source.createdAt);
+    if (typeof source.id !== "string" ||
+        typeof source.body !== "string" ||
+        !source.author ||
+        typeof source.author.id !== "string" ||
+        typeof source.author.fullName !== "string" ||
+        !Number.isFinite(createdAt)) {
+        return undefined;
+    }
+    return {
+        author: {
+            fullName: source.author.fullName,
+            id: source.author.id,
+            imageUrl: source.author.imageUrl
+        },
+        body: source.body,
+        createdAt,
+        id: source.id
+    };
+}

package/dist/contracts/console-layout.d.ts

@@ -0,0 +1,39 @@
+export type ConsoleLayout = {
+    providerGroups: Record<string, {
+        appearance?: ProviderGroupAppearance;
+        position?: {
+            x: number;
+            y: number;
+        };
+    }>;
+    viewport?: {
+        x: number;
+        y: number;
+        zoom: number;
+    };
+};
+export type ProviderGroupAppearance = {
+    accentColor?: string;
+    backgroundBlur?: number;
+    backgroundColor?: string;
+    backgroundOpacity?: number;
+    desktopGrid?: boolean;
+    icon?: string;
+    mode?: ProviderAppearanceMode;
+    terminalCursorBlink?: boolean;
+    terminalCursorStyle?: ProviderTerminalCursorStyle;
+    terminalFontFamily?: string;
+    wallpaper?: string;
+    wallpaperFit?: ProviderWallpaperFit;
+    wallpaperUrl?: string;
+    windowCornerRadius?: number;
+    windowFrost?: number;
+    windowOpacity?: number;
+    windowTitlebar?: ProviderWindowTitlebarStyle;
+};
+export type ProviderAppearanceMode = "dark" | "light";
+export type ProviderTerminalCursorStyle = "bar" | "block" | "underline";
+export type ProviderWallpaperFit = "center" | "fill" | "fit" | "tile";
+export type ProviderWindowTitlebarStyle = "minimal" | "plain" | "traffic";
+export declare function parseConsoleLayout(payload: unknown): ConsoleLayout;
+export declare function parseConsoleLayoutPatch(payload: unknown): ConsoleLayout;