@nexus-aethra/dsh-box-sandbox 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nexus Aethra
+
+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/README.md

@@ -0,0 +1,88 @@
+# @nexus-aethra/dsh-box-sandbox
+
+Host-side bridge from a DSH session to the DSH Box daemon.
+
+## Why it exists
+
+Developing a DSH plugin *inside* DSH is a crash story: a bad edit takes
+down the host that is running it. DSH Box stays outside that loop, so the
+development sandbox is the one process the agent is allowed to break. This
+plugin makes that sandbox reachable over a typed transport instead of by
+shelling out to the `dshbox` CLI and scraping stdout.
+
+## Wire contract
+
+Verified against `src-tauri/crates/dshboxd/src/main.rs`. The details below
+are the ones that are easy to get wrong:
+
+- **`POST /rpc` is matched exactly.** `path != "//rpc"` is a 404, so the
+  path must carry no query string.
+- **The token travels in the JSON body**, not in an `Authorization`
+  header. `box-client` also sends `Bearer`, but the daemon never reads it.
+- **Params are flattened** into the top-level request object alongside
+  `token` and `method` — there is no nested `params` field.
+- **Replies**: `{ ok: true, result }` for sync methods,
+  `{ ok: true, task }` for async ones, `{ ok: false, error }` otherwise.
+  The daemon closes the connection after each frame.
+- **`GET /events?token=...`** is the SSE stream; that endpoint takes the
+  token from the query string.
+
+## Discovery
+
+The daemon binds a **dynamic** loopback port and mints a token per launch,
+then publishes both atomically:
+
+    <config-dir>/server/discovery.json
+
+where `<config-dir>` is `DSHBOX_CONFIG_DIR` if set, otherwise `~/.dsh-box` —
+the same precedence `box_foundation::config_path` applies on the Rust side.
+The record is `{ token, pid, startedAt, port }` and is removed on shutdown.
+
+Ports are never hardcoded. The record is re-read on every call, and a
+transport failure is retried exactly once against a fresh read, so a daemon
+restart (new port, new token) is transparent to callers.
+
+## Usage
+
+    import { getRpc, status } from '@nexus-aethra/dsh-box-sandbox'
+
+    const pong = await getRpc().ping()
+    const containers = await getRpc().call('list_containers')
+
+    // Probe without throwing — for prompt surfaces and diagnostics.
+    const s = await status()
+    if (s.problem) console.log('dshbox unavailable:', s.problem)
+
+`status()` never throws: it returns the discovery path, the endpoint when
+reachable, and a `problem` string otherwise. A failed mount is never
+fatal — a missing daemon is a normal first-run state, not a load error.
+
+## Config
+
+    - insert:
+        - id: dsh-box-sandbox
+          name: '@nexus-aethra/dsh-box-sandbox'
+          config: {}
+
+| Field | Default | Meaning |
+|---|---|---|
+| `configDir` | `''` | Empty means resolve like the daemon does. |
+| `timeoutMs` | `30000` | Per-attempt request timeout. |
+
+## Security
+
+The discovery token is full control of the daemon: create and delete
+containers, run builds, install plugins. Anything that can read the record
+can drive dshbox. That is the intent here, but it is a deliberate trust
+boundary — do not mount the host profile directory into an untrusted
+container.
+
+## Development
+
+    pnpm install
+    pnpm typecheck
+    pnpm build
+    node smoke.mjs   # 10 checks against a running DSH Box
+
+`smoke.mjs` needs a live daemon: it reads the real discovery record, pings
+it, forces a stale-port failure, and verifies recovery.

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# @nexus-aethra/dsh-box-sandbox: mounts the host-side development sandbox.
+#
+# Every field is optional. With no config the client honours
+# DSHBOX_CONFIG_DIR and falls back to ~/.dsh-box, which is where DSH Box
+# publishes its discovery record. Overriding configDir is only needed to
+# point at a non-default profile.
+
+- insert:
+    - id: dsh-box-sandbox
+      name: '@nexus-aethra/dsh-box-sandbox'
+      config: {}

package/dist/index.d.mts

@@ -0,0 +1,47 @@
+import { Discovery, DshboxRpc, DshboxUnavailableError, discoveryPath, getRpc, resetRpc } from "./rpc.mjs";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/index.d.ts
+/** Cordis plugin name used by loader diagnostics and the patch overlay. */
+declare const name = "dsh-box-sandbox";
+/**
+ * Services this plugin depends on. Empty for now: the client is pure
+ * transport and needs no host service. Tools built on top of it will
+ * declare their own.
+ */
+declare const inject: string[];
+/**
+ * Plugin config. Both fields carry defaults, so the mount works with an
+ * empty config block; an empty configDir means "resolve it the way the
+ * daemon does" rather than "the current directory".
+ */
+interface Config {
+  /**
+   * Directory holding server/discovery.json. The default empty string
+   * means: honour DSHBOX_CONFIG_DIR, then fall back to ~/.dsh-box.
+   */
+  configDir: string;
+  /** Per-attempt request timeout in milliseconds. */
+  timeoutMs: number;
+}
+/** Snapshot of reachability, for diagnostics and prompt surfaces. */
+interface Status {
+  /** Path the discovery record was looked for at. */
+  discoveryPath: string;
+  /** Endpoint details when the daemon is up, else null. */
+  endpoint: Discovery | null;
+  /** Populated when endpoint is null. */
+  problem: string | null;
+}
+/**
+ * Probe the daemon without throwing.
+ *
+ * Returns the discovery record when the daemon answers, or the reason it
+ * could not be reached. A ping failure is reported rather than raised so
+ * that a status surface can render "dshbox is not running" without every
+ * caller having to catch.
+ */
+declare function status(config?: Partial<Config>): Promise<Status>;
+/** Register the plugin against a freshly mounted Cordis context. */
+declare function apply(ctx: Context, config?: Partial<Config>): void;
+//#endregion
+export { Config, type Discovery, DshboxRpc, DshboxUnavailableError, Status, apply, discoveryPath, getRpc, inject, name, resetRpc, status };