@toddzheng024/dscode-desktop 0.0.0-stage → 0.7.34

package/extensions/browser/popup.html

@@ -0,0 +1,11 @@
+<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>DSCODE Browser</title>
+<link rel="stylesheet" href="popup.css">
+<body><h1>DSCODE Browser</h1>
+<p>Share the current tab with a local DSCODE session. The agent can read and operate shared pages and create new tabs. Other existing tabs stay private.</p>
+<label for="pairing">Pairing link</label><input id="pairing" type="password" autocomplete="off" spellcheck="false" placeholder="Paste from DSCODE">
+<button id="pair">Connect and share this tab</button>
+<button id="share" hidden>Share this tab too</button>
+<button id="stop" hidden>Stop all sharing</button>
+<p id="status" role="status"></p><ul id="tabs"></ul>
+<script type="module" src="popup.mjs"></script></body></html>

package/extensions/browser/popup.mjs

@@ -0,0 +1,47 @@
+/* global chrome, document */
+const element = id => document.getElementById(id);
+let operation = 0;
+async function run(action, background = false) {
+  const current = ++operation;
+  let pending = false;
+  if (!background) {
+    for (const id of ['pair', 'share']) element(id).disabled = true;
+    element('stop').disabled = action === 'stop';
+  }
+  if (action === 'pair') element('stop').hidden = false;
+  try {
+    const request = { action };
+    if (action === 'pair') request.url = element('pairing').value.trim();
+    if (action === 'pair' || action === 'share') {
+      const [tab] = await chrome.tabs.query({ active: true, lastFocusedWindow: true });
+      if (current !== operation) return;
+      request.tabId = tab?.id;
+    }
+    const result = await chrome.runtime.sendMessage(request);
+    if (current !== operation) return;
+    if (result.error) throw Error(result.error);
+    pending = !!result.pending;
+    element('status').textContent = result.message;
+    element('pair').hidden = result.connected;
+    element('pairing').hidden = result.connected;
+    element('share').hidden = !result.connected;
+    element('stop').hidden = !result.connected && !pending;
+    if (result.connected) element('pairing').value = '';
+    element('tabs').replaceChildren(...result.shared.map(tab => {
+      const item = document.createElement('li'); item.textContent = tab.title || tab.url; return item;
+    }));
+    if (pending || result.connected) setTimeout(() => { if (current === operation) return run('status', true); }, pending ? 250 : 1000);
+  } catch (error) {
+    if (current !== operation) return;
+    element('status').textContent = error.message;
+    if (action === 'pair') element('stop').hidden = true;
+  }
+  finally {
+    if (current === operation) {
+      for (const id of ['pair', 'share']) element(id).disabled = pending;
+      element('stop').disabled = false;
+    }
+  }
+}
+for (const action of ['pair', 'share', 'stop']) element(action).addEventListener('click', () => run(action));
+await run('status');

package/extensions/browser/protocol.mjs

@@ -0,0 +1,168 @@
+/** Map a scoped chrome.debugger connection to the CDP browser/target envelope. */
+export class SharedTabs {
+  constructor(api, emit) {
+    this.api = api;
+    this.emit = emit;
+    this.tabs = new Map();
+    this.attachedTabs = new Set();
+    this.sessions = new Map();
+    this.discover = false;
+    this.autoAttach = false;
+    this.sequence = 0;
+    this.closed = false;
+  }
+
+  info(tab, type = 'page') {
+    return { targetId: type === 'tab' ? `tab-${tab.id}` : tab.targetId, type,
+      title: tab.title ?? '', url: tab.url, attached: true, canAccessOpener: false, browserContextId: 'shared' };
+  }
+
+  event(method, params, sessionId) { this.emit({ method, params, ...(sessionId ? { sessionId } : {}) }); }
+
+  attach(tab, type, parent) {
+    const sessionId = `dscode-${++this.sequence}`;
+    this.sessions.set(sessionId, { tabId: tab.id, type, parent });
+    this.event('Target.attachedToTarget', { sessionId, targetInfo: this.info(tab, type), waitingForDebugger: false }, parent);
+    return { sessionId };
+  }
+
+  async share(tabId) {
+    if (this.closed) throw Error('Sharing has ended. Pair again.');
+    if (this.tabs.has(tabId)) return;
+    const tab = await this.api.tabs.get(tabId);
+    // activeTab is granted by the toolbar gesture. A popup reopened from another
+    // extension surface still gets metadata only for the explicitly chosen ID.
+    if (!tab.url) {
+      const target = (await this.api.debugger.getTargets()).find(t => t.tabId === tabId);
+      tab.url = target?.url; tab.title = target?.title;
+    }
+    if (!/^https?:\/\//.test(tab.url ?? '') && tab.url !== 'about:blank') throw Error('Only HTTP(S) pages can be shared.');
+    if (this.closed) throw Error('Sharing has ended.');
+    await this.api.debugger.attach({ tabId }, '1.3');
+    this.attachedTabs.add(tabId);
+    try {
+      if (this.closed) throw Error('Sharing has ended.');
+      const { targetInfo } = await this.api.debugger.sendCommand({ tabId }, 'Target.getTargetInfo');
+      if (this.closed || !this.attachedTabs.has(tabId)) throw Error('Sharing has ended.');
+      const shared = { id: tabId, targetId: targetInfo.targetId, url: tab.url, title: tab.title };
+      this.tabs.set(tabId, shared);
+      if (this.discover) for (const type of ['tab', 'page']) this.event('Target.targetCreated', { targetInfo: this.info(shared, type) });
+      if (this.autoAttach) this.attach(shared, 'tab');
+    } catch (error) {
+      if (this.attachedTabs.delete(tabId)) await this.api.debugger.detach({ tabId }).catch(() => {});
+      throw error;
+    }
+  }
+
+  async stop() {
+    this.closed = true;
+    const ids = [...this.attachedTabs];
+    this.attachedTabs.clear();
+    this.tabs.clear();
+    this.sessions.clear();
+    await Promise.allSettled(ids.map(tabId => this.api.debugger.detach({ tabId })));
+  }
+
+  update(tabId, change) {
+    const tab = this.tabs.get(tabId);
+    if (!tab) return;
+    if (change.url !== undefined) tab.url = change.url;
+    if (change.title !== undefined) tab.title = change.title;
+    for (const type of ['tab', 'page']) this.event('Target.targetInfoChanged', { targetInfo: this.info(tab, type) });
+  }
+
+  detach(sessionId, params = {}) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return false;
+    // A detached ancestor invalidates every descendant route. Notify clients
+    // while those descendants' parent routes still exist in their session tree.
+    for (const [id, child] of [...this.sessions]) if (child.parent === sessionId) this.detach(id);
+    this.sessions.delete(sessionId);
+    this.event('Target.detachedFromTarget', { ...params, sessionId }, session.parent);
+    return true;
+  }
+
+  remove(tabId) {
+    this.attachedTabs.delete(tabId);
+    const tab = this.tabs.get(tabId);
+    if (!tab) return;
+    this.tabs.delete(tabId);
+    for (const [id, session] of [...this.sessions]) if (session.tabId === tabId) this.detach(id);
+    for (const type of ['page', 'tab']) this.event('Target.targetDestroyed', { targetId: this.info(tab, type).targetId });
+  }
+
+  debuggerEvent(source, method, params) {
+    if (!this.tabs.has(source.tabId)) return;
+    for (const [sessionId, session] of [...this.sessions]) {
+      if (session.tabId !== source.tabId || session.type !== 'page' || session.child !== source.sessionId) continue;
+      if (method === 'Target.attachedToTarget') {
+        const child = `${sessionId}:${params.sessionId}`;
+        this.sessions.set(child, { tabId: source.tabId, type: 'page', child: params.sessionId, parent: sessionId });
+        this.event(method, { ...params, sessionId: child }, sessionId);
+      } else if (method === 'Target.detachedFromTarget') {
+        const child = `${sessionId}:${params.sessionId}`;
+        this.detach(child, params);
+      } else this.event(method, params, sessionId);
+    }
+  }
+
+  async command({ method, params = {}, sessionId }) {
+    if (this.closed) throw Error('Sharing has ended.');
+    const session = sessionId ? this.sessions.get(sessionId) : undefined;
+    if (sessionId && !session) throw Error('Unknown shared session.');
+    const tab = session ? this.tabs.get(session.tabId) : undefined;
+    if (method === 'Target.getBrowserContexts') return { browserContextIds: [] };
+    if (method === 'Target.getTargets') return { targetInfos: [...this.tabs.values()].flatMap(t => [this.info(t, 'tab'), this.info(t)]) };
+    if (method === 'Target.setDiscoverTargets' && !session) {
+      this.discover = !!params.discover;
+      if (this.discover) for (const t of this.tabs.values()) for (const type of ['tab', 'page']) this.event('Target.targetCreated', { targetInfo: this.info(t, type) });
+      return {};
+    }
+    if (method === 'Target.setAutoAttach' && (!session || session.type === 'tab')) {
+      if (!params.flatten || !params.autoAttach) throw Error('Only flattened automatic attachment is supported.');
+      if (!session) {
+        if (!this.autoAttach) { this.autoAttach = true; for (const t of this.tabs.values()) this.attach(t, 'tab'); }
+      } else if (!session.attached) { session.attached = true; this.attach(tab, 'page', sessionId); }
+      return {};
+    }
+    if (method === 'Runtime.runIfWaitingForDebugger' && session?.type === 'tab') return {};
+    if (method === 'Target.attachToTarget') {
+      const found = [...this.tabs.values()].find(t => t.targetId === params.targetId || `tab-${t.id}` === params.targetId);
+      if (!found || !params.flatten) throw Error('Target is not shared.');
+      return this.attach(found, params.targetId.startsWith('tab-') ? 'tab' : 'page', sessionId);
+    }
+    if (method === 'Target.detachFromTarget') {
+      if (!this.detach(params.sessionId)) throw Error('Unknown shared session.');
+      return {};
+    }
+    if (method === 'Target.createTarget' && !session) {
+      if (params.browserContextId || (!/^https?:\/\//.test(params.url) && params.url !== 'about:blank')) throw Error('Only HTTP(S) or blank tabs in the shared browser are supported.');
+      const created = await this.api.tabs.create({ url: params.url, active: !params.background });
+      await this.share(created.id);
+      return { targetId: this.tabs.get(created.id).targetId };
+    }
+    if (['Target.closeTarget', 'Target.activateTarget'].includes(method)) {
+      const found = [...this.tabs.values()].find(t => t.targetId === params.targetId || `tab-${t.id}` === params.targetId);
+      if (!found) throw Error('Target is not shared.');
+      if (method === 'Target.closeTarget') { await this.api.tabs.remove(found.id); return { success: true }; }
+      await this.api.tabs.update(found.id, { active: true }); return {};
+    }
+    if (method === 'Browser.getVersion') return this.api.version();
+    if (!session || session.type !== 'page') throw Error(`Unsupported browser command: ${method}`);
+    // Target discovery and cookie APIs can escape the selected tab's scope.
+    if (method.startsWith('Browser.') ||
+        (method.startsWith('Target.') && !['Target.setAutoAttach', 'Target.getTargetInfo'].includes(method)) ||
+        (method.startsWith('Storage.') && method !== 'Storage.getStorageKeyForFrame') ||
+        ['Network.getAllCookies', 'Network.getCookies', 'Network.setCookie', 'Network.setCookies', 'Network.deleteCookies', 'Network.clearBrowserCookies', 'Network.clearBrowserCache'].includes(method)) {
+      throw Error(`Command is outside shared-tab scope: ${method}`);
+    }
+    if (method === 'Target.getTargetInfo') {
+      if (params.targetId && params.targetId !== tab.targetId) throw Error('Target is not shared in this session.');
+      if (!session.child) return { targetInfo: this.info(tab) };
+    }
+    if (method === 'Target.setAutoAttach') {
+      params = { ...params, flatten: true, filter: [{ type: 'iframe', exclude: false }, { type: 'worker', exclude: false }, { exclude: true }] };
+    }
+    return this.api.debugger.sendCommand({ tabId: session.tabId, ...(session.child ? { sessionId: session.child } : {}) }, method, params);
+  }
+}

package/extensions/browser/worker.mjs

@@ -0,0 +1,94 @@
+/* global chrome */
+import { SharedTabs } from './protocol.mjs';
+
+let state;
+let pending = false;
+let message = 'Not sharing.';
+
+async function stop(reason = 'Sharing stopped.') {
+  const current = state;
+  state = undefined;
+  message = reason;
+  if (current) {
+    clearInterval(current.timer);
+    current.cancelConnect?.();
+    current.socket?.close();
+    await current.tabs.stop();
+  }
+  // Detaching may finish after the user pairs a different tab. That new
+  // connection owns the badge; an older stop must not hide active sharing.
+  if (!state) await chrome.action.setBadgeText({ text: '' });
+}
+
+async function pair(url, tabId) {
+  if (state || pending) throw Error('Stop sharing before pairing another session.');
+  const endpoint = new URL(url);
+  if (endpoint.protocol !== 'ws:' || endpoint.hostname !== '127.0.0.1' || !endpoint.port ||
+      endpoint.username || endpoint.password || endpoint.hash || endpoint.pathname !== '/extension' ||
+      !/^\?token=[a-f0-9]{64}$/.test(endpoint.search)) throw Error('Paste the local pairing link from DSCODE.');
+  pending = true;
+  message = 'Pairing with DSCODE.';
+  const current = { tabs: new SharedTabs({
+    tabs: chrome.tabs, debugger: chrome.debugger,
+    version: () => ({ protocolVersion: '1.3', product: `Chrome/${navigator.userAgent.match(/Chrome\/([\d.]+)/)?.[1] ?? 'unknown'}`,
+      revision: '', userAgent: navigator.userAgent, jsVersion: '' }),
+  }, event => { if (current.socket?.readyState === WebSocket.OPEN) current.socket.send(JSON.stringify(event)); }) };
+  state = current;
+  try {
+    await current.tabs.share(tabId);
+    if (state !== current) throw Error('Pairing was cancelled.');
+    current.socket = new WebSocket(endpoint.href);
+    await new Promise((resolve, reject) => {
+      const finish = error => {
+        clearTimeout(timer);
+        current.cancelConnect = undefined;
+        current.socket.onopen = current.socket.onerror = current.socket.onclose = null;
+        if (error) reject(error); else resolve();
+      };
+      const timer = setTimeout(() => finish(Error('Could not connect to DSCODE. Generate a new pairing link.')), 10000);
+      current.cancelConnect = () => finish(Error('Pairing was cancelled.'));
+      current.socket.onopen = () => finish();
+      current.socket.onerror = current.socket.onclose = () => finish(Error('Could not connect to DSCODE.'));
+    });
+    if (state !== current) throw Error('Pairing was cancelled.');
+    current.socket.onclose = () => { if (state === current) void stop('DSCODE disconnected. Pair again to share.'); };
+    current.socket.onerror = () => { if (state === current) void stop('Connection failed. Pair again to share.'); };
+    current.socket.onmessage = async event => {
+      let command;
+      try { command = JSON.parse(event.data); } catch { await stop('Invalid connection message.'); return; }
+      if (!Number.isSafeInteger(command.id) || typeof command.method !== 'string') { await stop('Invalid connection command.'); return; }
+      let response;
+      try { response = { result: await current.tabs.command(command) }; }
+      catch (error) { response = { error: { code: -32000, message: error.message } }; }
+      if (state === current && current.socket.readyState === WebSocket.OPEN) current.socket.send(JSON.stringify({ id: command.id, ...(command.sessionId ? { sessionId: command.sessionId } : {}), ...response }));
+    };
+    current.socket.send(JSON.stringify({ type: 'ready' }));
+    current.timer = setInterval(() => { if (current.socket.readyState === WebSocket.OPEN) current.socket.send(JSON.stringify({ type: 'keepalive' })); }, 20000);
+    message = 'Sharing with DSCODE.';
+    await chrome.action.setBadgeText({ text: 'ON' });
+    await chrome.action.setBadgeBackgroundColor({ color: '#bd4520' });
+  } catch (error) { if (state === current) await stop(error.message); throw error; }
+  finally { pending = false; }
+}
+
+chrome.runtime.onMessage.addListener((request, sender, respond) => {
+  if (sender.id !== chrome.runtime.id || sender.url !== chrome.runtime.getURL('popup.html')) return false;
+  (async () => {
+    if (request.action === 'pair') await pair(request.url, request.tabId);
+    else if (request.action === 'share') {
+      if (!state || pending) throw Error('Pair with DSCODE first.');
+      await state.tabs.share(request.tabId);
+    } else if (request.action === 'stop') await stop();
+    else if (request.action !== 'status') throw Error('Unknown action.');
+    return { message, pending, shared: [...(state?.tabs.tabs.values() ?? [])].map(t => ({ title: t.title, url: t.url })), connected: !!state && !pending };
+  })().then(respond, error => respond({ error: error.message }));
+  return true;
+});
+chrome.debugger.onEvent.addListener((source, method, params) => state?.tabs.debuggerEvent(source, method, params));
+chrome.debugger.onDetach.addListener((source, reason) => {
+  if (!state?.tabs.tabs.has(source.tabId)) return;
+  if (reason === 'target_closed') state.tabs.remove(source.tabId);
+  else void stop('Browser debugging was cancelled. Pair again to share.');
+});
+chrome.tabs.onUpdated.addListener((id, change) => state?.tabs.update(id, change));
+chrome.tabs.onRemoved.addListener(id => state?.tabs.remove(id));

package/icon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="128" height="128" viewBox="0 0 128 128">
+  <rect width="128" height="128" rx="28" fill="#0e1a2e"/>
+  <g stroke="#7dd3fc" stroke-width="6" stroke-linecap="round" fill="none">
+    <path d="M24 64h80M44 29l40 70M44 99l40-70"/>
+    <path d="m32 51 13 13-13 13m64-26L83 64l13 13M44 44l18 5 5-18m-6 66 5-18 18 5M44 84l18-5 5 18m-6-66 5 18 18-5"/>
+  </g>
+</svg>

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSCODE",
+    "description": "Coding collaboration, session memory, browser workflows and community plugin discovery for Harness Desktop."
+  }
+}

package/locale/zh-cn.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DSCODE",
+    "description": "为 Harness Desktop 提供编码协作、会话记忆、浏览器工作流和社区插件发现。"
+  }
+}

package/node_modules/@deepseek-ai/node-addon-system/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/node_modules/@deepseek-ai/node-addon-system/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write native/system/packages/entry/README.md
+README.md: 8f6a4d341c8f9e4c104e5706e08d9a7d45c065e1
+README.zh.md: 152257916df0cf40511b9743d389ae753ab6c85c

package/node_modules/@deepseek-ai/node-addon-system/README.md

@@ -0,0 +1,15 @@
+---
+description: "JavaScript entry for the prebuilt Landlock launcher and asynchronous POSIX flock."
+kind: "package-library"
+---
+# @deepseek-ai/node-addon-system
+
+English | [中文](README.zh.md)
+
+The `./landlock-run` entry exports the Landlock launcher path, enforcement probe, grant arguments, and protocol constants. The independent `./flock` entry exports `tryLockExclusive(fd): Promise<void>`; importing either entry does not load `system.node`. The package has no root export.
+
+The lock operation attempts `LOCK_EX | LOCK_NB` asynchronously. Keep the caller-owned descriptor open until completion; contention rejects with `EAGAIN`/`EWOULDBLOCK`, other syscall failures also reject, and errors carry their code, positive errno, and `syscall: 'flock'`. Native setup errors reject the same promise. Closing the last descriptor for the open file description releases the lock. The binding does not open, duplicate, close, or explicitly unlock descriptors.
+
+Optional OS/CPU platform packages carry the binaries. Linux has `bin/landlock-run` and separate `bin/glibc/system.node` / `bin/musl/system.node`; macOS has `bin/system.node`. Missing or unloadable flock bindings reject acquisition, without installation-time compilation. Landlock remains a separate executable with its existing fail-closed protocol; unsupported kernels/platforms probe unusable.
+
+The two C sources ship for auditability. See the workspace [architecture](../../docs/architecture.md), [support matrix](../../docs/support-matrix.md), and [CLI contract](../../docs/cli-contract.md).

package/node_modules/@deepseek-ai/node-addon-system/README.zh.md

@@ -0,0 +1,15 @@
+---
+description: "预编译 Landlock 启动器与异步 POSIX flock 的 JavaScript 入口。"
+kind: "package-library"
+---
+# @deepseek-ai/node-addon-system
+
+[English](README.md) | 中文
+
+`./landlock-run` 入口导出 Landlock 启动器路径、强制执行探测、授权参数和协议常量。独立的 `./flock` 入口导出 `tryLockExclusive(fd): Promise<void>`；导入任一入口都不会加载 `system.node`。包不提供根导出。
+
+锁操作异步尝试 `LOCK_EX | LOCK_NB`。在完成前保持调用方拥有的描述符打开；竞争以 `EAGAIN`/`EWOULDBLOCK` 拒绝，其他系统调用失败也会拒绝，错误携带 code、正 errno 和 `syscall: 'flock'`。原生调用准备阶段的错误也会拒绝同一个 promise。关闭该打开文件描述的最后一个描述符即释放锁。绑定不打开、复制、关闭或显式解锁描述符。
+
+可选操作系统/CPU 平台包携带二进制。Linux 包含 `bin/landlock-run` 和分别用于两种 libc 的 `bin/glibc/system.node` / `bin/musl/system.node`；macOS 包含 `bin/system.node`。flock 绑定缺失或无法加载时拒绝获取，不在安装时编译。Landlock 仍是遵循既有失败关闭协议的独立可执行文件；不支持的内核或平台探测为不可用。
+
+两个 C 源文件随包分发以供审计。参见工作区[架构](../../docs/architecture.md)、[支持矩阵](../../docs/support-matrix.md)和 [CLI 约定](../../docs/cli-contract.md)。

package/node_modules/@deepseek-ai/node-addon-system/lib/flock.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Attempt an exclusive, nonblocking POSIX flock on the caller's descriptor.
+ * The syscall runs in asynchronous work, so acquisition can occur after this
+ * call returns. Keep fd open until the promise settles; the binding never
+ * opens, duplicates, or closes it. Closing the locked descriptor releases the
+ * lock once all descriptors for its open file description are closed.
+ * @param fd - Open file descriptor to lock; ownership remains with the caller.
+ * @returns A promise resolving to void on acquisition. Contention rejects with
+ *   EAGAIN/EWOULDBLOCK; other syscall failures also reject. Syscall errors carry
+ *   code, positive errno, and syscall='flock'. Native setup errors, unsupported
+ *   platforms, and addon loading failures reject; importing alone does not load it.
+ */
+export declare function tryLockExclusive(fd: number): Promise<void>;

package/node_modules/@deepseek-ai/node-addon-system/lib/flock.js

@@ -0,0 +1,51 @@
+/** Lazy POSIX flock entry; importing it does not load a native addon. */
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { getSystemErrorName } from 'node:util';
+let binding;
+function loadBinding() {
+    if (binding)
+        return binding;
+    const { platform, arch } = process;
+    if (platform !== 'linux' && platform !== 'darwin') {
+        throw Object.assign(new Error(`flock is not supported on ${platform}-${arch}`), {
+            code: 'ERR_FLOCK_UNSUPPORTED_PLATFORM',
+            syscall: 'flock',
+        });
+    }
+    let filename = 'system.node';
+    if (platform === 'linux') {
+        // Node's report types omit the libc field supplied by Linux reports.
+        const report = process.report.getReport();
+        filename = join(report.header.glibcVersionRuntime ? 'glibc' : 'musl', filename);
+    }
+    const require = createRequire(import.meta.url);
+    const manifest = require.resolve(`@deepseek-ai/node-addon-system-${platform}-${arch}/package.json`);
+    binding = require(join(dirname(manifest), 'bin', filename));
+    return binding;
+}
+/**
+ * Attempt an exclusive, nonblocking POSIX flock on the caller's descriptor.
+ * The syscall runs in asynchronous work, so acquisition can occur after this
+ * call returns. Keep fd open until the promise settles; the binding never
+ * opens, duplicates, or closes it. Closing the locked descriptor releases the
+ * lock once all descriptors for its open file description are closed.
+ * @param fd - Open file descriptor to lock; ownership remains with the caller.
+ * @returns A promise resolving to void on acquisition. Contention rejects with
+ *   EAGAIN/EWOULDBLOCK; other syscall failures also reject. Syscall errors carry
+ *   code, positive errno, and syscall='flock'. Native setup errors, unsupported
+ *   platforms, and addon loading failures reject; importing alone does not load it.
+ */
+export async function tryLockExclusive(fd) {
+    const errno = await new Promise((resolve) => {
+        loadBinding().tryLock(fd, resolve);
+    });
+    if (errno === 0)
+        return;
+    const code = getSystemErrorName(-errno);
+    throw Object.assign(new Error(`${code}: flock failed`), {
+        code,
+        errno,
+        syscall: 'flock',
+    });
+}

package/node_modules/@deepseek-ai/node-addon-system/lib/index.d.ts

@@ -0,0 +1,73 @@
+/** The launcher binary's file name inside each platform package's `bin/`. */
+export declare const LAUNCHER_BIN = "landlock-run";
+/**
+ * The exit code for every launcher-level failure (usage error, unenforcing
+ * kernel, unopenable grant root, failed exec). After a successful `exec`, the
+ * wrapped command may also return 125, so consumers also require a matching
+ * launcher-owned fatal diagnostic to attribute launcher failure. Part of the
+ * CLI contract.
+ */
+export declare const LAUNCHER_FAILURE_EXIT = 125;
+/**
+ * The probe's verdict on this host: `full` when the running kernel enforces
+ * every access the launcher can govern, `partial` when an older Landlock ABI
+ * governs only a subset (still confined for everything it supports), and
+ * `unusable` when nothing can be enforced — a kernel without Landlock, a
+ * disabled LSM, or a missing binary, all indistinguishable on purpose
+ * because the consumer's answer is the same: do not trust this launcher.
+ */
+export type LandlockEnforcement = 'full' | 'partial' | 'unusable';
+/**
+ * Filesystem grants for one confined run. Everything not granted is denied —
+ * Landlock rulesets are allow-lists.
+ */
+export interface LauncherGrants {
+    /** Roots granted read + execute beneath (the launcher's `--ro`). */
+    readonly readOnly?: readonly string[];
+    /** Roots granted full filesystem access beneath (the launcher's `--rw`). */
+    readonly readWrite?: readonly string[];
+}
+/**
+ * Path of the launcher binary for this host: resolved from the per-platform
+ * npm package `@deepseek-ai/node-addon-system-<platform>-<arch>` (npm's
+ * `os`/`cpu` fields make installers fetch only the matching one). When the
+ * package is not resolvable — a platform without one, or an install that
+ * skipped the optional dependency — the returned fallback path points inside
+ * this package's own `node_modules` and simply never exists. Existence is
+ * deliberately not checked either way: {@link probe} is the single
+ * availability signal (a missing binary probes `unusable` the same way an
+ * unenforcing kernel does).
+ * @param resolvePackageJson - test hook over `require.resolve` (the default
+ *   covers real installs); receives the platform package's `package.json`
+ *   specifier and returns its absolute path, throwing when unresolvable.
+ * @returns the absolute launcher path to probe and exec.
+ */
+export declare function launcherPath(resolvePackageJson?: (specifier: string) => string): string;
+/**
+ * The launcher grant arguments for one set of filesystem grants — everything
+ * before the `--` argv separator. A caller spawns
+ * `[launcherPath(), ...grantArgs(grants), '--', ...command]`; the flag
+ * spellings stay private to this package.
+ * @param grants - the read-only and read-write roots to allow.
+ * @returns the `--ro <path>` / `--rw <path>` argument list, read-only roots
+ *   first, in the caller's order.
+ */
+export declare function grantArgs(grants: LauncherGrants): string[];
+/**
+ * Functional probe: `landlock-run --probe` builds and enforces a maximal
+ * ruleset in a short-lived child and exits 0 only when the running kernel
+ * actually enforces it — `--version`-style checks would miss a kernel that
+ * has the syscalls but refuses enforcement. The probe's one report line is
+ * part of the CLI contract and distinguishes complete from per-ABI-subset
+ * enforcement; a zero exit without the partial marker reads as `full`. A
+ * failed or timed-out spawn (missing binary, wrong architecture, unenforcing
+ * kernel) probes `unusable`. Synchronous by design: consumers run it once
+ * and cache the verdict.
+ * @param launcher - the launcher path to probe; defaults to
+ *   {@link launcherPath}'s resolution for this host.
+ * @param options - `timeoutMs` bounds the probe child (default 2000).
+ * @returns the enforcement verdict for this host.
+ */
+export declare function probe(launcher?: string, options?: {
+    timeoutMs?: number;
+}): LandlockEnforcement;

package/node_modules/@deepseek-ai/node-addon-system/lib/index.js

@@ -0,0 +1,98 @@
+/**
+ * The JavaScript API over the prebuilt `landlock-run` launcher: resolve the
+ * binary for this host, build its grant argv, and run its functional probe.
+ *
+ * This module owns the launcher's CLI contract (`docs/cli-contract.md`) so
+ * consumers never parse launcher output or spell launcher flags themselves —
+ * the contract and the binaries version together in one package family,
+ * which makes probe-parsing drift against the binary structurally
+ * impossible. Policy stays with the consumer: this package does not know
+ * what a "sandbox mode" is, only which paths are granted read or write.
+ *
+ * Deliberately no environment-variable overrides anywhere in this module:
+ * which binary confines a process must never be decidable by the ambient
+ * environment. Test injection is by function parameter.
+ */
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** The launcher binary's file name inside each platform package's `bin/`. */
+export const LAUNCHER_BIN = 'landlock-run';
+/**
+ * The exit code for every launcher-level failure (usage error, unenforcing
+ * kernel, unopenable grant root, failed exec). After a successful `exec`, the
+ * wrapped command may also return 125, so consumers also require a matching
+ * launcher-owned fatal diagnostic to attribute launcher failure. Part of the
+ * CLI contract.
+ */
+export const LAUNCHER_FAILURE_EXIT = 125;
+/**
+ * Path of the launcher binary for this host: resolved from the per-platform
+ * npm package `@deepseek-ai/node-addon-system-<platform>-<arch>` (npm's
+ * `os`/`cpu` fields make installers fetch only the matching one). When the
+ * package is not resolvable — a platform without one, or an install that
+ * skipped the optional dependency — the returned fallback path points inside
+ * this package's own `node_modules` and simply never exists. Existence is
+ * deliberately not checked either way: {@link probe} is the single
+ * availability signal (a missing binary probes `unusable` the same way an
+ * unenforcing kernel does).
+ * @param resolvePackageJson - test hook over `require.resolve` (the default
+ *   covers real installs); receives the platform package's `package.json`
+ *   specifier and returns its absolute path, throwing when unresolvable.
+ * @returns the absolute launcher path to probe and exec.
+ */
+export function launcherPath(resolvePackageJson = createRequire(import.meta.url).resolve) {
+    const platformPackage = `@deepseek-ai/node-addon-system-${process.platform}-${process.arch}`;
+    try {
+        return join(dirname(resolvePackageJson(`${platformPackage}/package.json`)), 'bin', LAUNCHER_BIN);
+    }
+    catch {
+        // Unresolvable platform package: no such package exists for this host, or
+        // it was not installed. Fall back to the path pnpm's layout WOULD use —
+        // absolute, inside this package's boundary (never cwd-relative: a
+        // spawnable relative path here would hand cwd control over which binary
+        // confines), and nonexistent exactly when the package is absent.
+        return fileURLToPath(new URL(`../node_modules/${platformPackage}/bin/${LAUNCHER_BIN}`, import.meta.url));
+    }
+}
+/**
+ * The launcher grant arguments for one set of filesystem grants — everything
+ * before the `--` argv separator. A caller spawns
+ * `[launcherPath(), ...grantArgs(grants), '--', ...command]`; the flag
+ * spellings stay private to this package.
+ * @param grants - the read-only and read-write roots to allow.
+ * @returns the `--ro <path>` / `--rw <path>` argument list, read-only roots
+ *   first, in the caller's order.
+ */
+export function grantArgs(grants) {
+    return [
+        ...(grants.readOnly ?? []).flatMap(root => ['--ro', root]),
+        ...(grants.readWrite ?? []).flatMap(root => ['--rw', root]),
+    ];
+}
+/**
+ * Functional probe: `landlock-run --probe` builds and enforces a maximal
+ * ruleset in a short-lived child and exits 0 only when the running kernel
+ * actually enforces it — `--version`-style checks would miss a kernel that
+ * has the syscalls but refuses enforcement. The probe's one report line is
+ * part of the CLI contract and distinguishes complete from per-ABI-subset
+ * enforcement; a zero exit without the partial marker reads as `full`. A
+ * failed or timed-out spawn (missing binary, wrong architecture, unenforcing
+ * kernel) probes `unusable`. Synchronous by design: consumers run it once
+ * and cache the verdict.
+ * @param launcher - the launcher path to probe; defaults to
+ *   {@link launcherPath}'s resolution for this host.
+ * @param options - `timeoutMs` bounds the probe child (default 2000).
+ * @returns the enforcement verdict for this host.
+ */
+export function probe(launcher = launcherPath(), options = {}) {
+    const result = spawnSync(launcher, ['--probe'], {
+        timeout: options.timeoutMs ?? 2000,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0)
+        return 'unusable';
+    return /partially enforced/.test(result.stdout) ? 'partial' : 'full';
+}