tabby-clip-image 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 barton
+
+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

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# tabby-clip-image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Paste **images** into remote TUIs (Claude Code, Codex, …) running over SSH in Tabby.
+
+In an SSH tab, paste with any of `Ctrl+V`, `Cmd+V`, `Ctrl+Shift+V`, `Shift+Insert`, right-click or middle-click. If the clipboard holds
+
+| Clipboard | Result |
+|---|---|
+| a screenshot / copied image (pixels) | uploaded as `.png` |
+| image **file(s)** copied in the file manager (png, jpg, gif, webp, bmp, tif, heic/heif, avif, svg, ico) | uploaded **unchanged**, original format kept, multiple files supported (Windows lists them via the built-in PowerShell) |
+| text, or non-image files | normal paste |
+
+the bytes go over the tab's **existing SSH connection** (new exec channel — no extra login; works through jump hosts/proxies) into `~/.cache/clip-recv/shots/shot-<time>-<pid>-<name>.<ext>` on the host, and the absolute path is pasted at the cursor.
+
+**Nothing to install on the host**: it only uses POSIX `sh`, `mkdir`, `date`, `cat`, `chmod`, `find`. No X11/Wayland needed.
+
+Client side: Linux (X11/Wayland), macOS, Windows — local tabs and text pastes are untouched.
+
+## Install
+
+Tabby → Settings → Plugins → search `clip-image` → Install → restart Tabby.
+
+## Configuration
+
+- Path prefix: `PATH_PREFIX` in `index.js` (default `''`). When the app enabled bracketed paste (Claude Code, Codex, …) each path is sent as a paste, exactly like drag-and-drop, so the TUI shows `[Image #1]`; otherwise (a shell prompt) the plain path is typed. Verified with real Claude Code and Codex; `'@'` only works as a file mention in Claude Code.
+- Max file size: `MAX_FILE_BYTES` (default 50 MB).
+- Target directory on the host: `CLIP_RECV_DIR` (must be visible to non-interactive `sh`). Files older than 2 days are pruned (`-mtime +2` in `REMOTE_SH`).
+
+## Notes
+
+- Uploaded files are mode 600.
+- Only triggers when the clipboard has an image (or image files) and no text; on failure a notification is shown and the normal paste/`Ctrl+V` is passed through.
+- File-copy detection reads OS clipboard formats (`text/uri-list` / `x-special/gnome-copied-files` on Linux, `NSFilenamesPboardType` / `public.file-url` on macOS, `FileNameW` on Windows).
+
+## Troubleshooting (copied files not detected)
+
+Open Tabby's DevTools (`Ctrl+Shift+I` / `Cmd+Option+I`), Console, copy a file in the file manager, then run:
+
+```js
+require('electron').clipboard.availableFormats()
+```
+
+then check what the plugin itself would upload for the current clipboard (empty array = it would paste normally):
+
+```js
+require('electron').clipboard && require(require('path').join(require('os').homedir(), '.config/tabby/plugins/node_modules/tabby-clip-image')).collectItems(require('electron').clipboard).map(i => i.error || `${i.base}.${i.ext}`)
+```
+
+(on Windows use `%APPDATA%\\tabby\\plugins\\node_modules\\tabby-clip-image`, on macOS `~/Library/Application Support/tabby/plugins/node_modules/tabby-clip-image`), and open an issue with the output and your OS. Expected: `text/uri-list` (Linux), `NSFilenamesPboardType`/`public.file-url` (macOS), `FileNameW` (Windows).
+
+## Verification status
+
+- Linux client, real Tabby 1.0.238 over SSH, real Claude Code and Codex in remote tmux: screenshot and copied files (png/jpg/webp) pasted as `[Image #1]`.
+- macOS and Windows clients: clipboard-format parsing covered by unit tests with simulated clipboards only; not yet run on real machines.
+
+MIT

package/index.js

@@ -0,0 +1,264 @@
+'use strict'
+// tabby-clip-image: paste images into remote TUIs (claude/codex/...) over SSH.
+//
+// When you paste in an SSH tab (Ctrl+V, Cmd+V, Ctrl+Shift+V, Shift+Insert, right/middle click)
+// and the clipboard holds
+//   - copied image FILE(s)  (png/jpg/gif/webp/bmp/tiff/heic/avif/svg/ico) -> uploaded as-is, or
+//   - a screenshot / copied image (pixels)                                  -> uploaded as PNG,
+// the bytes are streamed over the tab's existing SSH connection to a fixed directory on the host
+// (plain `sh` + `cat`; nothing to install there) and the absolute path is typed at the cursor.
+// Anything else (text, non-image files, local tabs) pastes normally.
+const fs = require('fs')
+const path = require('path')
+const { fileURLToPath } = require('url')
+const { NgModule } = require('@angular/core')
+const { TerminalDecorator, SessionMiddleware } = require('tabby-terminal')
+
+// Typed before each path. '' (plain absolute path) is recognised as an image attachment by both
+// Claude Code and Codex when it arrives as a bracketed paste; '@' only works as a file mention in Claude Code.
+const PATH_PREFIX = ''
+const MAX_FILE_BYTES = 50 * 1024 * 1024
+const CHUNK = 32 * 1024
+const IMAGE_EXTS = new Set(['png', 'jpg', 'jpeg', 'jfif', 'gif', 'webp', 'bmp', 'tif', 'tiff', 'heic', 'heif', 'avif', 'svg', 'ico'])
+
+// Runs on the host via the SSH exec channel as: sh -c '<script>' sh <name> <ext>
+// Saves stdin to $CLIP_RECV_DIR (default ~/.cache/clip-recv/shots), prunes files older than
+// 2 days and prints "ok <ext> <absolute path>".
+const REMOTE_SH = [
+    'd="${CLIP_RECV_DIR:-$HOME/.cache/clip-recv/shots}"',
+    'mkdir -p "$d"',
+    'f="$d/shot-$(date +%Y%m%d-%H%M%S)-$$-$1.$2"',
+    'cat > "$f"',
+    '[ -s "$f" ] || { rm -f "$f"; false; }',
+    'chmod 600 "$f"',
+    '{ find "$d" -maxdepth 1 -type f -name "shot-*" -mtime +2 -delete 2>/dev/null || true; }',
+    'echo "ok $2 $f"',
+].join(' && ')
+
+function getClipboard () {
+    try { return require('electron').clipboard } catch { return null }
+}
+
+// ---------- reading the local clipboard ----------
+
+function decodeXml (s) {
+    return s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&')
+}
+
+function parseUriList (text) {
+    const out = []
+    for (const line of String(text).split(/\r?\n/)) {
+        const l = line.trim()
+        if (!l.startsWith('file://')) { continue }
+        try { out.push(fileURLToPath(l)) } catch { /* ignore */ }
+    }
+    return out
+}
+
+/** Windows only: every copied file via the built-in PowerShell (FileNameW holds just the first one). */
+function winFileDropList () {
+    const { execFileSync } = require('child_process')
+    const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-STA', '-Command',
+        '[Console]::OutputEncoding=[Text.Encoding]::UTF8; Add-Type -AssemblyName System.Windows.Forms; [Windows.Forms.Clipboard]::GetFileDropList() | ForEach-Object { $_ }',
+    ], { timeout: 4000, windowsHide: true, encoding: 'utf8' })
+    return out.split(/\r?\n/).map(x => x.trim()).filter(Boolean)
+}
+
+/** Paths of files currently copied in the OS file manager (empty if none). */
+function clipboardFilePaths (cb, platform = process.platform, deps = { winFileDropList }) {
+    const read = (fn) => { try { return fn() } catch { return null } }
+    let paths = []
+    if (platform === 'win32') {
+        const buf = read(() => cb.readBuffer('FileNameW'))
+        if (buf && buf.length) {
+            const p = Buffer.from(buf).toString('ucs2').replace(/\0.*$/s, '')
+            if (p) {
+                paths.push(p)
+                try { const all = deps.winFileDropList(); if (all.length > 1) { paths = all } } catch { /* keep the first file */ }
+            }
+        }
+    } else if (platform === 'darwin') {
+        const plist = read(() => cb.read('NSFilenamesPboardType'))
+        if (plist) {
+            for (const m of plist.matchAll(/<string>([\s\S]*?)<\/string>/g)) { paths.push(decodeXml(m[1])) }
+        }
+        if (!paths.length) {
+            const u = read(() => cb.read('public.file-url'))
+            if (u) { paths = parseUriList(u) }
+        }
+    } else {
+        for (const fmt of ['text/uri-list', 'x-special/gnome-copied-files']) {
+            const t = read(() => Buffer.from(cb.readBuffer(fmt)).toString('utf8')) // renderer returns Uint8Array, not Buffer
+            if (t) { paths = parseUriList(t) }
+            if (paths.length) { break }
+        }
+    }
+    return [...new Set(paths)]
+}
+
+function safeBase (file) {
+    const b = path.basename(file, path.extname(file)).replace(/[^A-Za-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '').slice(0, 32)
+    return b || 'img'
+}
+
+/**
+ * Image items to upload for the current clipboard, or [] when this is a normal (text) paste.
+ * Each item: { base, ext, size?, load: () => Promise<Buffer> }  or { error } for unusable files.
+ */
+function collectItems (cb, platform = process.platform, deps) {
+    if (!cb) { return [] }
+    const files = clipboardFilePaths(cb, platform, deps)
+    if (files.length) {
+        const items = []
+        for (const f of files) {
+            const ext = path.extname(f).slice(1).toLowerCase()
+            if (!IMAGE_EXTS.has(ext)) { continue }
+            let st
+            try { st = fs.statSync(f) } catch { continue }
+            if (!st.isFile()) { continue }
+            if (st.size > MAX_FILE_BYTES) { items.push({ error: `${path.basename(f)} is larger than ${MAX_FILE_BYTES >> 20} MB` }); continue }
+            items.push({ base: safeBase(f), ext: ext === 'jpeg' || ext === 'jfif' ? 'jpg' : ext === 'tiff' ? 'tif' : ext, size: st.size, load: () => fs.promises.readFile(f) })
+        }
+        return items // [] when only non-image files are copied -> normal paste
+    }
+    try {
+        if (cb.readText()) { return [] }
+        const img = cb.readImage()
+        if (!img || img.isEmpty()) { return [] }
+        return [{ base: 'clip', ext: 'png', load: async () => img.toPNG() }]
+    } catch { return [] }
+}
+
+// ---------- uploading ----------
+
+async function uploadOne (ssh, item) {
+    const bytes = await item.load()
+    if (!bytes.length) { throw new Error('empty image') }
+    const ch = await ssh.activateChannel(await ssh.openSessionChannel())
+    let out = ''
+    const subs = []
+    const done = new Promise(resolve => {
+        subs.push(ch.data$.subscribe(b => { out += Buffer.from(b).toString() }))
+        subs.push(ch.extendedData$.subscribe(b => { out += Buffer.from(b).toString() }))
+        subs.push(ch.closed$.subscribe({ next: resolve, complete: resolve }))
+        subs.push(ch.eof$.subscribe({ next: () => {}, complete: () => {} }))
+    })
+    let timer
+    const timeout = new Promise((_, reject) => { timer = setTimeout(() => reject(new Error('timeout')), 15000 + bytes.length / 50) })
+    try {
+        await ch.requestExec(`sh -c '${REMOTE_SH}' sh ${item.base} ${item.ext}`)
+        for (let i = 0; i < bytes.length; i += CHUNK) {
+            await ch.write(bytes.subarray(i, i + CHUNK))
+        }
+        await ch.eof()
+        await Promise.race([done, timeout])
+    } finally {
+        clearTimeout(timer)
+        subs.forEach(s => s.unsubscribe?.())
+    }
+    const m = /^ok (\S+) (.+)$/m.exec(out.trim())
+    if (!m) { throw new Error(out.trim() || 'no output from host (is `sh` available?)') }
+    return m[2].trim()
+}
+
+const busyTabs = new WeakSet()
+
+/**
+ * Upload all items and call emit(buffer) with the typed paths.
+ * Resolves true when at least one path was emitted.
+ */
+async function pasteItems (tab, items, emit) {
+    const notify = (kind, msg) => { try { tab.notifications?.[kind]?.(msg) } catch { /* ignore */ } }
+    const ssh = tab.sshSession?.ssh
+    if (!ssh || typeof ssh.openSessionChannel !== 'function') { notify('error', 'Image paste failed: SSH session not ready'); return false }
+    const paths = []
+    for (const item of items) {
+        if (item.error) { notify('error', `Image paste: ${item.error}`); continue }
+        try { paths.push(await uploadOne(ssh, item)) } catch (e) { notify('error', `Image paste failed: ${e.message || e}`) }
+    }
+    if (!paths.length) { return false }
+    notify('notice', paths.length === 1 ? `Image saved on host: ${paths[0]}` : `${paths.length} images saved on host`)
+    // Like a drag-and-drop: one bracketed paste per path when the app enabled it (TUIs then attach the image),
+    // plain text otherwise (shell prompt).
+    const bracketed = !!(tab.frontend && tab.frontend.supportsBracketedPaste && tab.frontend.supportsBracketedPaste())
+    emit(Buffer.from(paths.map(p => bracketed ? `\x1b[200~${PATH_PREFIX}${p} \x1b[201~` : `${PATH_PREFIX}${p} `).join('')))
+    return true
+}
+
+// ---------- Tabby integration ----------
+
+// Ctrl+V sends 0x16 into the session on Windows/Linux (and Ctrl+V on macOS).
+class ClipImageMiddleware extends SessionMiddleware {
+    constructor (tab, clipboardProvider) {
+        super()
+        this.tab = tab
+        this.getClipboard = clipboardProvider || getClipboard
+        this.busy = false // only true while *this middleware* holds keystrokes during an upload
+        this.queue = []
+    }
+
+    feedFromTerminal (data) {
+        if (this.busy) { this.queue.push(data); return }
+        if (data.length === 1 && data[0] === 0x16) {
+            const items = collectItems(this.getClipboard())
+            if (items.length) {
+                if (busyTabs.has(this.tab)) { return } // a paste is already uploading
+                this.busy = true
+                busyTabs.add(this.tab)
+                pasteItems(this.tab, items, buf => this.outputToSession.next(buf))
+                    .then(ok => { if (!ok) { this.outputToSession.next(data) } })
+                    .catch(() => this.outputToSession.next(data))
+                    .then(() => {
+                        this.busy = false
+                        busyTabs.delete(this.tab)
+                        const q = this.queue; this.queue = []
+                        q.forEach(d => this.feedFromTerminal(d))
+                    })
+                return
+            }
+        }
+        this.outputToSession.next(data)
+    }
+}
+
+class ClipImageDecorator extends TerminalDecorator {
+    attachToSession (tab) {
+        if (!tab.session || !tab.sshSession) { return }
+        tab.session.middleware.unshift(new ClipImageMiddleware(tab))
+    }
+
+    // Cmd+V, Ctrl+Shift+V, Shift+Insert, right-click and middle-click paste all call tab.paste().
+    hookPaste (tab) {
+        if (tab.__clipImageHooked || typeof tab.paste !== 'function') { return }
+        tab.__clipImageHooked = true
+        const original = tab.paste.bind(tab)
+        tab.paste = () => {
+            if (!tab.sshSession) { return original() }
+            if (busyTabs.has(tab)) { return Promise.resolve() }
+            const items = collectItems(getClipboard())
+            if (!items.length) { return original() }
+            busyTabs.add(tab)
+            return pasteItems(tab, items, buf => tab.sendInput(buf))
+                .catch(() => false)
+                .then(ok => { busyTabs.delete(tab); if (!ok) { return original() } })
+        }
+    }
+
+    attach (tab) {
+        if (!('sshSession' in tab)) { return } // SSH tabs only; local tabs paste natively
+        this.hookPaste(tab)
+        setTimeout(() => {
+            this.attachToSession(tab)
+            this.subscribeUntilDetached(tab, tab.sessionChanged$.subscribe(() => this.attachToSession(tab)))
+        })
+    }
+}
+
+class ClipImageModule {}
+NgModule({
+    providers: [
+        { provide: TerminalDecorator, useFactory: () => new ClipImageDecorator(), multi: true },
+    ],
+})(ClipImageModule)
+
+module.exports = { default: ClipImageModule, ClipImageMiddleware, collectItems, clipboardFilePaths, pasteItems, REMOTE_SH }

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "tabby-clip-image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.0",
+  "description": "Paste images (screenshots or copied image files: png/jpg/gif/webp/heic/...) in a Tabby SSH tab: uploaded over the existing SSH connection to a fixed dir on the host and the path is typed at the cursor. Nothing to install on the host.",
+  "keywords": [
+    "tabby-plugin",
+    "tabby",
+    "ssh",
+    "clipboard",
+    "image",
+    "paste",
+    "claude",
+    "codex"
+  ],
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "barton",
+  "license": "MIT"
+}