jupyter-link 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roberto Arce
+
+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,93 @@
+# jupyter-link
+
+CLI and AgentSkill to execute code in running Jupyter kernels and persist outputs back to `.ipynb` notebooks.
+
+## Features
+
+- Discover running sessions and match by notebook path or name
+- Read/write notebooks via Jupyter Contents API (nbformat v4)
+- Insert or update code cells with agent metadata (`metadata.agent`)
+- Open persistent kernel WebSocket channels for execution
+- Send `execute_request` and collect iopub/shell outputs
+- Map outputs to nbformat v4 format (stream, execute_result, display_data, error)
+- Persistent config — set URL and token once, use everywhere
+
+## Requirements
+
+- Node.js 20+
+- A running Jupyter Server (JupyterLab/Notebook)
+
+## Installation
+
+### As a global CLI
+```bash
+npm install -g jupyter-link
+```
+
+### Via npx (no install)
+```bash
+echo '{}' | npx jupyter-link@0.1.0 check:env
+```
+
+### As an AgentSkill
+```bash
+npx skills add <owner/repo>
+```
+
+## Quick Start
+
+```bash
+# 1. Configure connection (saved to ~/.config/jupyter-link/config.json)
+echo '{"url":"http://localhost:8888","token":"your-token"}' | npx jupyter-link@0.1.0 config:set
+
+# 2. Verify connectivity
+echo '{}' | npx jupyter-link@0.1.0 check:env
+
+# 3. List running sessions
+echo '{}' | npx jupyter-link@0.1.0 list:sessions
+
+# 4. Read cell outputs
+echo '{"path":"notebook.ipynb","cells":[0,1,2]}' | npx jupyter-link@0.1.0 cell:read
+```
+
+## Commands
+
+All commands read JSON from stdin and write JSON to stdout.
+
+| Command | Description |
+|---------|-------------|
+| `config:set` | Save connection settings (url, token, port) |
+| `config:get` | Show effective config with source per field |
+| `check:env` | Verify Jupyter Server connectivity |
+| `list:sessions` | List sessions, filter by path or name |
+| `cell:read` | Read specific cells with outputs (preferred) |
+| `cell:insert` | Insert a code cell with agent metadata |
+| `cell:update` | Update cell source, outputs, execution_count |
+| `contents:read` | Read full notebook JSON |
+| `contents:write` | Write notebook JSON |
+| `open:kernel-channels` | Open persistent WebSocket to kernel |
+| `execute:code` | Send execute_request, get parent_msg_id |
+| `collect:outputs` | Wait for outputs/reply/idle |
+| `close:channels` | Close a channel |
+| `save:notebook` | Save notebook (round-trip PUT) |
+
+## Configuration
+
+Priority: environment variables > config file > defaults.
+
+| Source | URL | Token | Daemon Port |
+|--------|-----|-------|-------------|
+| Env var | `JUPYTER_URL` | `JUPYTER_TOKEN` | `JUPYTER_LINK_PORT` |
+| Config file | `url` | `token` | `port` |
+| Default | `http://127.0.0.1:8888` | — | `32123` |
+
+## Tests
+
+```bash
+npm test                    # Run all tests
+npm run test:coverage       # With coverage report
+```
+
+## License
+
+MIT

package/bin/run

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { run } from '@oclif/core';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+run(process.argv.slice(2), { root: resolve(__dirname, '..') }).then(() => {
+  // ok
+}).catch((err) => {
+  // Print minimal error and exit non-zero
+  const msg = (err && err.message) || String(err);
+  process.stderr.write(msg + '\n');
+  try {
+    // emit JSON error for AgentSkills
+    process.stdout.write(JSON.stringify({ error: msg, stack: err && err.stack }) + '\n');
+  } catch {}
+  process.exit(1);
+});
+

package/oclif.manifest.json

@@ -0,0 +1,299 @@
+{
+  "commands": {
+    "cell:insert": {
+      "aliases": [],
+      "args": {},
+      "description": "Insert a code cell with agent metadata",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "cell:insert",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "cell",
+        "insert.mjs"
+      ]
+    },
+    "cell:read": {
+      "aliases": [],
+      "args": {},
+      "description": "Read specific cells from a notebook with their outputs, source, and metadata",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "cell:read",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "cell",
+        "read.mjs"
+      ]
+    },
+    "cell:update": {
+      "aliases": [],
+      "args": {},
+      "description": "Update a code cell (source/outputs/execution_count/metadata)",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "cell:update",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "cell",
+        "update.mjs"
+      ]
+    },
+    "check:env": {
+      "aliases": [],
+      "args": {},
+      "description": "Verify connectivity and basic Jupyter Server compatibility",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "check:env",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "check",
+        "env.mjs"
+      ]
+    },
+    "close:channels": {
+      "aliases": [],
+      "args": {},
+      "description": "Close a previously opened channel_ref",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "close:channels",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "close",
+        "channels.mjs"
+      ]
+    },
+    "collect:outputs": {
+      "aliases": [],
+      "args": {},
+      "description": "Wait for outputs/reply/idle for a parent_msg_id on a channel",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "collect:outputs",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "collect",
+        "outputs.mjs"
+      ]
+    },
+    "contents:read": {
+      "aliases": [],
+      "args": {},
+      "description": "Read a notebook JSON via Contents API",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "contents:read",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "contents",
+        "read.mjs"
+      ]
+    },
+    "contents:write": {
+      "aliases": [],
+      "args": {},
+      "description": "Write notebook JSON via Contents API",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "contents:write",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "contents",
+        "write.mjs"
+      ]
+    },
+    "execute:code": {
+      "aliases": [],
+      "args": {},
+      "description": "Send execute_request on an open channel and return parent_msg_id",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "execute:code",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "execute",
+        "code.mjs"
+      ]
+    },
+    "list:sessions": {
+      "aliases": [],
+      "args": {},
+      "description": "List sessions and optionally filter by path or name",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "list:sessions",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "list",
+        "sessions.mjs"
+      ]
+    },
+    "config:get": {
+      "aliases": [],
+      "args": {},
+      "description": "Show effective configuration (env vars > config file > defaults)",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "config:get",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "config",
+        "get.mjs"
+      ]
+    },
+    "config:set": {
+      "aliases": [],
+      "args": {},
+      "description": "Save Jupyter connection settings to ~/.config/jupyter-link/config.json",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "config:set",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "config",
+        "set.mjs"
+      ]
+    },
+    "open:kernel-channels": {
+      "aliases": [],
+      "args": {},
+      "description": "Open persistent kernel WS channels and return a channel_ref",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "open:kernel-channels",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "open",
+        "kernel-channels.mjs"
+      ]
+    },
+    "save:notebook": {
+      "aliases": [],
+      "args": {},
+      "description": "Save notebook (round-trip PUT)",
+      "flags": {},
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "save:notebook",
+      "pluginAlias": "jupyter-link",
+      "pluginName": "jupyter-link",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "src",
+        "commands",
+        "save",
+        "notebook.mjs"
+      ]
+    }
+  },
+  "version": "0.1.0"
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "jupyter-link",
+  "version": "0.1.0",
+  "description": "CLI and AgentSkill to execute code in Jupyter kernels and persist outputs to notebooks",
+  "type": "module",
+  "license": "MIT",
+  "author": "Roberto Arce",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rarce/jupyter-link.git"
+  },
+  "homepage": "https://github.com/rarce/jupyter-link",
+  "keywords": [
+    "jupyter",
+    "notebook",
+    "kernel",
+    "agentskills",
+    "cli",
+    "execute",
+    "ipynb",
+    "nbformat"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "oclif.manifest.json"
+  ],
+  "dependencies": {
+    "@oclif/core": "^3.26.3"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^1.6.1",
+    "vitest": "^1.5.0",
+    "yaml": "^2.4.1"
+  },
+  "scripts": {
+    "build": "npx oclif manifest",
+    "test": "vitest run --reporter=dot",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "prepublishOnly": "npm run build"
+  },
+  "bin": {
+    "jupyter-link": "bin/run"
+  },
+  "oclif": {
+    "bin": "jupyter-link",
+    "commands": "./src/commands",
+    "plugins": []
+  }
+}

package/scripts/check_env.mjs

@@ -0,0 +1,18 @@
+import { getConfig, httpJson, ok, fail, assertNodeVersion } from './util.mjs';
+
+async function main() {
+  assertNodeVersion();
+  const { baseUrl, token } = getConfig();
+  // Try sessions and contents root
+  const sessions = await httpJson('GET', `${baseUrl}/api/sessions`, token).catch(e => ({ error: e.message }));
+  const contents = await httpJson('GET', `${baseUrl}/api/contents`, token).catch(e => ({ error: e.message }));
+  ok({
+    ok: !sessions.error && !contents.error,
+    sessions_ok: !sessions.error,
+    contents_ok: !contents.error,
+    details: { sessions, contents }
+  });
+}
+
+main().catch(fail);
+

package/scripts/close_channels.mjs

@@ -0,0 +1,16 @@
+import { readStdinJson, ok, fail, assertNodeVersion } from './util.mjs';
+import { ensureDaemon, request } from './ipc_client.mjs';
+
+async function main() {
+  assertNodeVersion();
+  const input = await readStdinJson();
+  const ref = input.channel_ref ?? input.ref;
+  if (!ref) throw new Error('channel_ref is required');
+  await ensureDaemon();
+  const out = await request('close', { channel_ref: ref });
+  if (out.error) throw new Error(out.error);
+  ok(out);
+}
+
+main().catch(fail);
+

package/scripts/collect_outputs.mjs

@@ -0,0 +1,18 @@
+import { readStdinJson, ok, fail, assertNodeVersion } from './util.mjs';
+import { ensureDaemon, request } from './ipc_client.mjs';
+
+async function main() {
+  assertNodeVersion();
+  const input = await readStdinJson();
+  const ref = input.channel_ref ?? input.ref;
+  const parent = input.parent_msg_id ?? input.parent_id;
+  if (!ref) throw new Error('channel_ref is required');
+  if (!parent) throw new Error('parent_msg_id is required');
+  await ensureDaemon();
+  const out = await request('collect', { channel_ref: ref, parent_msg_id: parent, timeout_s: input.timeout_s || 60 });
+  if (out.error) throw new Error(out.error);
+  ok(out);
+}
+
+main().catch(fail);
+

package/scripts/daemon.mjs

@@ -0,0 +1,133 @@
+import net from 'node:net';
+import crypto from 'node:crypto';
+import { URL } from 'node:url';
+import { mapIopubToOutput, isStatusIdle, isParent, makeExecuteRequest } from './jupyter_proto.mjs';
+import { nowIso, newSessionId, getConfig } from '../src/lib/common.mjs';
+
+const PORT = getConfig().port;
+// helper functions imported from jupyter_proto.mjs
+
+// State
+const channels = new Map(); // ref -> { ws, sessionId, kernelId, url, outputsByParent }
+
+export function wsUrlFor(baseUrl, token, kernelId, sessionId) {
+  const url = new URL(baseUrl);
+  const wsScheme = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  const query = new URLSearchParams();
+  if (token) query.set('token', token);
+  query.set('session_id', sessionId);
+  const u = `${wsScheme}//${url.host}${url.pathname.replace(/\/$/, '')}/api/kernels/${kernelId}/channels?${query.toString()}`;
+  return u;
+}
+
+function handleOpen({ baseUrl, token, kernelId }) {
+  if (!baseUrl || !kernelId) throw new Error('baseUrl and kernelId are required');
+  const sessionId = newSessionId();
+  const url = wsUrlFor(baseUrl, token, kernelId, sessionId);
+  const WS = globalThis.WebSocket;
+  if (!WS) throw new Error('WebSocket API not available in Node. Use Node >=20 or enable experimental WebSocket');
+  const ws = new WS(url);
+  const ref = 'ch-' + crypto.randomBytes(6).toString('hex');
+  const state = { ws, sessionId, kernelId, url, outputsByParent: new Map(), ready: false };
+  channels.set(ref, state);
+  ws.on('open', () => { state.ready = true; });
+  ws.on('message', (data) => {
+    let msg; try { msg = JSON.parse(data.toString()); } catch { return; }
+    const parentId = msg.parent_header && msg.parent_header.msg_id;
+    if (!parentId) return;
+    let agg = state.outputsByParent.get(parentId);
+    if (!agg) return;
+    const channel = msg.channel;
+    const msgType = msg.header && msg.header.msg_type;
+    if (channel === 'iopub' && isParent(msg, parentId)) {
+      const out = mapIopubToOutput(msg);
+      if (out) agg.outputs.push(out);
+      if (isStatusIdle(msg)) agg.gotIdle = true;
+    }
+    if (channel === 'shell' && msgType === 'execute_reply' && isParent(msg, parentId)) {
+      agg.gotReply = true;
+      agg.status = (msg.content && msg.content.status) || agg.status;
+      agg.execution_count = (msg.content && msg.content.execution_count) || agg.execution_count;
+    }
+    if (agg.gotReply && agg.gotIdle && !agg.resolved) {
+      agg.resolved = true;
+      if (agg.resolve) agg.resolve();
+    }
+  });
+  ws.on('close', () => { state.ready = false; state.dead = true; });
+  ws.on('error', () => { state.ready = false; state.dead = true; });
+  return { channel_ref: ref, session_id: sessionId };
+}
+
+function handleExec({ channel_ref, code, allow_stdin = false, stop_on_error = true }) {
+  const ch = channels.get(channel_ref);
+  if (!ch) throw new Error('unknown channel_ref');
+  if (ch.dead) throw new Error('channel is closed or errored');
+  if (!ch.ready) throw new Error('channel not ready');
+  const msg = makeExecuteRequest(code, ch.sessionId, allow_stdin, stop_on_error);
+  const parentId = msg.header.msg_id;
+  ch.outputsByParent.set(parentId, { outputs: [], execution_count: null, status: 'unknown', gotReply: false, gotIdle: false, resolved: false });
+  ch.ws.send(JSON.stringify(msg));
+  return { parent_msg_id: parentId };
+}
+
+async function handleCollect({ channel_ref, parent_msg_id, timeout_s = 60 }) {
+  const ch = channels.get(channel_ref);
+  if (!ch) throw new Error('unknown channel_ref');
+  const agg = ch.outputsByParent.get(parent_msg_id);
+  if (!agg) throw new Error('unknown parent_msg_id');
+  let timedOut = false;
+  if (!(agg.gotReply && agg.gotIdle)) {
+    await new Promise((resolve, reject) => {
+      const timer = setTimeout(() => { if (agg.resolve === resolve) agg.resolve = undefined; timedOut = true; resolve(); }, timeout_s * 1000);
+      agg.resolve = () => { clearTimeout(timer); resolve(); };
+    });
+  }
+  const status = timedOut ? 'timeout' : (agg.status || (agg.gotReply ? 'ok' : 'unknown'));
+  // Clean up to prevent memory leak
+  ch.outputsByParent.delete(parent_msg_id);
+  return { outputs: agg.outputs, execution_count: agg.execution_count, status };
+}
+
+function handleClose({ channel_ref }) {
+  const ch = channels.get(channel_ref);
+  if (!ch) return { ok: true };
+  try { ch.ws.close(); } catch {}
+  channels.delete(channel_ref);
+  return { ok: true };
+}
+
+function handleList() {
+  const arr = [];
+  for (const [ref, st] of channels.entries()) arr.push({ channel_ref: ref, kernel_id: st.kernelId, url: st.url, ready: st.ready });
+  return { channels: arr };
+}
+
+const server = net.createServer((socket) => {
+  let buf = '';
+  socket.on('data', (chunk) => {
+    buf += chunk.toString('utf8');
+    let idx;
+    while ((idx = buf.indexOf('\n')) >= 0) {
+      const line = buf.slice(0, idx); buf = buf.slice(idx + 1);
+      let req; try { req = JSON.parse(line); } catch { socket.write(JSON.stringify({ error: 'bad json' }) + '\n'); continue; }
+      try {
+        let res;
+        switch (req.op) {
+          case 'ping': res = { ok: true }; break;
+          case 'open': res = handleOpen(req.args || {}); break;
+          case 'exec': res = handleExec(req.args || {}); break;
+          case 'collect': res = handleCollect(req.args || {}); break;
+          case 'close': res = handleClose(req.args || {}); break;
+          case 'list': res = handleList(); break;
+          default: res = { error: 'unknown op' };
+        }
+        Promise.resolve(res).then((out) => socket.write(JSON.stringify(out) + '\n')).catch((e) => { try { socket.write(JSON.stringify({ error: e.message || String(e) }) + '\n'); } catch {} });
+      } catch (e) {
+        socket.write(JSON.stringify({ error: e.message || String(e) }) + '\n');
+      }
+    }
+  });
+});
+
+server.listen(PORT, '127.0.0.1');