@vibelord/lanes 1.0.0 → 1.0.2

package/payload/lanes/libexec/connection.py

@@ -0,0 +1,178 @@
+#!/usr/bin/env python3
+"""A quiet connection screen with input custody until the viewer answers."""
+import argparse
+import errno
+import fcntl
+import os
+import pty
+import select
+import signal
+import sys
+import termios
+import time
+import tty
+
+RESET = b'\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1005l\x1b[?1006l\x1b[?1015l\x1b[?1016l\x1b[?2004l\x1b[<u\x1b[0m'
+
+
+def screen(title, frame):
+    title = ''.join(c for c in title if c.isprintable())[:100]
+    spinner = '|/-\\'[frame % 4]
+    os.write(1, b'\x1b[H\x1b[2J\x1b[?25l' + f'\n  {spinner} Syncing {title}…\n\n  Connecting to the workspace\n'.encode())
+
+
+def drain():
+    termios.tcflush(0, termios.TCIFLUSH)
+
+
+def wait_screen(title, seconds, preserve_screen=False):
+    saved = termios.tcgetattr(0)
+    handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGTERM, signal.SIGHUP)}
+    def stop(sig, _frame):
+        raise SystemExit(128 + sig)
+    for sig in handlers:
+        signal.signal(sig, stop)
+    try:
+        tty.setraw(0)
+        os.write(1, RESET)
+        drain()
+        end, frame = time.monotonic() + seconds, 0
+        while time.monotonic() < end:
+            if not preserve_screen:
+                screen(title, frame)
+            frame += 1
+            if select.select([0], [], [], min(.15, max(0, end - time.monotonic())))[0]:
+                if not os.read(0, 4096):
+                    break  # disconnected terminal
+    finally:
+        for sig, handler in handlers.items():
+            signal.signal(sig, handler)
+        drain()
+        termios.tcsetattr(0, termios.TCSANOW, saved)
+        os.write(1, RESET + b'\x1b[?25h')
+
+
+def connect(title, command):
+    if not os.isatty(0):
+        raise SystemExit('The workspace viewer needs a terminal')
+    saved = termios.tcgetattr(0)
+    error_fd = os.dup(2)
+    child = None
+    stopping = False
+    master = None
+
+    def stop(_sig, _frame):
+        nonlocal stopping
+        stopping = True
+        if child:
+            try:
+                os.killpg(child, signal.SIGTERM)
+            except ProcessLookupError:
+                pass
+
+    def resize(_sig=None, _frame=None):
+        if master is not None:
+            size = fcntl.ioctl(0, termios.TIOCGWINSZ, b'\0' * 8)
+            fcntl.ioctl(master, termios.TIOCSWINSZ, size)
+
+    old_handlers = {sig: signal.getsignal(sig) for sig in (signal.SIGTERM, signal.SIGHUP, signal.SIGWINCH)}
+    try:
+        tty.setraw(0)
+        drain()
+        os.write(1, RESET)
+        screen(title, 0)
+        child, master = pty.fork()
+        if child == 0:
+            os.dup2(error_fd, 2)  # diagnostics belong in the view's error file
+            os.close(error_fd)
+            try:
+                os.execvp(command[0], command)
+            except OSError as error:
+                print(error, file=sys.stderr)
+                os._exit(127)
+        os.close(error_fd)
+        error_fd = -1
+        resize()
+        signal.signal(signal.SIGTERM, stop)
+        signal.signal(signal.SIGHUP, stop)
+        signal.signal(signal.SIGWINCH, resize)
+        connected, frame = False, 0
+        while not stopping:
+            ready, _, _ = select.select([0, master], [], [], .15)
+            # Consume old mouse/keyboard input BEFORE accepting the first output.
+            if 0 in ready:
+                data = os.read(0, 4096)
+                if not data:
+                    stop(None, None)
+                    break
+                if connected:
+                    os.write(master, data)
+            if master in ready:
+                try:
+                    data = os.read(master, 65536)
+                except OSError as error:
+                    if error.errno != errno.EIO:
+                        raise
+                    break
+                if not data:
+                    break
+                if not connected:
+                    drain()
+                    os.write(1, RESET + b'\x1b[?25h\x1b[H\x1b[2J')
+                    connected = True
+                os.write(1, data)
+            if not connected:
+                frame += 1
+                screen(title, frame)
+        if stopping:
+            # This kills only the attach client group, never the persistent lane.
+            deadline = time.monotonic() + 2
+            while time.monotonic() < deadline:
+                pid, status = os.waitpid(child, os.WNOHANG)
+                if pid:
+                    return -signal.SIGTERM
+                time.sleep(.05)
+            try:
+                os.killpg(child, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+        _, status = os.waitpid(child, 0)
+        return -signal.SIGTERM if stopping else os.waitstatus_to_exitcode(status)
+    finally:
+        for sig, handler in old_handlers.items():
+            signal.signal(sig, handler)
+        if master is not None:
+            os.close(master)
+        if error_fd >= 0:
+            os.close(error_fd)
+        drain()
+        termios.tcsetattr(0, termios.TCSANOW, saved)
+        os.write(1, RESET + b'\x1b[?25h')
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--title', default='workspace')
+    parser.add_argument('--wait', type=float)
+    parser.add_argument('--preserve-screen', action='store_true')
+    parser.add_argument('--retry', action='store_true')
+    parser.add_argument('command', nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+    command = args.command[1:] if args.command[:1] == ['--'] else args.command
+    if args.wait is not None:
+        wait_screen(args.title, args.wait, args.preserve_screen)
+        return 0
+    if not command:
+        parser.error('viewer command required')
+    delay = 1
+    while True:
+        started = time.monotonic()
+        code = connect(args.title, command)
+        if not args.retry or code < 0:
+            return max(0, code) if code < 0 else code
+        delay = 1 if time.monotonic() - started >= 30 else min(delay * 2, 15)
+        wait_screen(args.title, delay)
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/payload/lanes/libexec/cursor_sync.py

@@ -12,12 +12,23 @@ The repository's `.vscode/terminals.json` stays the source of truth for WHICH la
 
 Text is edited minimally (command strings replaced in place, the `lanes` block inserted before the final brace) so
 git diffs stay small. Dry-run by default: prints a unified diff. `--write` applies (with a timestamped backup).
+
+`--canonicalize` additionally replaces every tmux lane's `create` that cannot create the lane — null, attach-only
+(`attach-session` without `new`), naming the retired in-container coder-launch config (the three classes `lanes
+doctor` warns about), or naming a script that is missing in the container — with
+`lanes_lib.canonical_recipe()` (the recorded binding + the repository folder + `bash -l`), which is also what gives a
+NEW lane its identity (LANE_ID, LANE_WS, the lanes/<ws>/<id> trace). `--identity` additionally gives a WORKING
+recipe of the plain shape `[exec] tmux -L <socket> new -ADs <session> [-c <dir>] <command…>` the same identity
+(`plain_tmux_new`: the command argv is kept, only the `-e` flags are added); any other working recipe is left
+alone and its lane carries no identity. The old value is kept as `createPrevious` in both cases. Identity reaches a
+tmux lane ONLY through these `-e` flags: `lane open` never exports it (DEF-1478, lanes/docs/ARCHITECTURE.md).
 Boards whose registry lives outside a repository are additionally PROJECTED into the file Cursor
 reads for that folder, named by `"cursor": "<path>"` on the repository entry of the workspace manifest.
 """
 import difflib
 import json
 import re
+import shlex
 import time
 from pathlib import Path
 
@@ -31,8 +42,110 @@ def _indent_of(text):
     return match.group(1) if match else '  '
 
 
-def normalized_text(text, lanes_by_name):
-    """Return the file text with uniform commands + the `lanes` block. Minimal textual edits when possible."""
+ATTACH_VERBS = {'attach-session'[:n] for n in range(1, 15)}             # tmux takes any unique prefix + `attach`
+NEW_VERBS = {'new-session'[:n] for n in range(3, 12)}
+TMUX_OPTION_ARGS = {'-L', '-S', '-f', '-T', '-c'}
+SCRIPT_SUFFIXES = ('.sh', '.bash', '.py', '.js', '.mjs', '.cjs', '.rb', '.pl')
+CLASS_REASONS = {'null': 'no create recipe', 'attach-only': 'attach-only',
+                 'retired-path': 'retired coder-launch path'}
+
+
+def _words(text, depth=3):
+    """Shell words of a recipe, with quoted command strings split again (`new … 'script.sh arg'`)."""
+    try:
+        words = shlex.split(text)
+    except ValueError:
+        return None
+    out = []
+    for word in words:
+        out.append(word)
+        if depth and any(c.isspace() for c in word):
+            out += _words(word, depth - 1) or []
+    return out
+
+
+def _tmux_verbs(words):
+    verbs = []
+    for i, word in enumerate(words):
+        if word == 'tmux' or word.endswith('/tmux'):
+            j = i + 1
+            while j < len(words) and words[j].startswith('-'):
+                j += 2 if words[j] in TMUX_OPTION_ARGS else 1
+            if j < len(words):
+                verbs.append(words[j])
+    return verbs
+
+
+def needs_canonical(create, folder, exists):
+    """Why `create` cannot create its lane (None when it can, or when that is not knowable).
+    `exists(container_path)` answers True / False / None (unknown — never counted as missing)."""
+    if not isinstance(create, str) or not create.strip():
+        return 'no create recipe'
+    recipe = create.replace('${workspaceFolder}', folder).replace('[workspaceFolder]', folder)
+    # Every class `lanes doctor` warns about (lanes_lib.classify_recipe: null, attach-only, retired-path) is one this
+    # repairs, read by the same parser, so the doctor's "fix with --canonicalize" is never a no-op (DEF-1460).
+    reason = CLASS_REASONS.get(L.classify_recipe(recipe))
+    if reason:
+        return reason
+    words = _words(recipe)
+    if words is None:
+        return None
+    verbs = _tmux_verbs(words)
+    if any(v in ATTACH_VERBS for v in verbs) and not any(v in NEW_VERBS for v in verbs):
+        return 'attach-only'
+    for word in words:
+        if word.startswith('/') and word.endswith(SCRIPT_SUFFIXES) and exists(word) is False:
+            return f'missing script {word}'
+    return None
+
+
+OPERATORS = set('();<>|&')
+UNSAFE_TO_REQUOTE = set('$`*?[{\\')
+
+
+def plain_tmux_new(create, folder, socket, session):
+    """`(folder, command)` of a WORKING recipe of exactly the shape `[exec] tmux -L <socket> new[-session] -A -D -s
+    <session> [-c <dir>] <command…>` — this lane's binding, no `-e`, no shell operators — else None. `--identity`
+    rewrites such a recipe to `canonical_recipe(…, folder, command)`: the command words are re-quoted one for one, so
+    tmux receives the same argv and the rewrite only ADDS the identity `-e` flags. Anything the re-quoting could change
+    (an expansion, a glob, a backslash, a leading `~`) or any other shape is left alone."""
+    if not isinstance(create, str):
+        return None
+    recipe = create.replace('${workspaceFolder}', folder).replace('[workspaceFolder]', folder)
+    try:
+        lexer = shlex.shlex(recipe, posix=True, punctuation_chars=True)
+        lexer.whitespace_split = True
+        words = list(lexer)
+    except ValueError:
+        return None
+    if any(set(w) <= OPERATORS or set(w) & UNSAFE_TO_REQUOTE or w.startswith('~') for w in words):
+        return None
+    if words[:1] == ['exec']:
+        words = words[1:]
+    if words[:3] != ['tmux', '-L', socket] or len(words) < 4 or words[3] not in NEW_VERBS:
+        return None
+    i, flags, sess, cdir = 4, set(), None, None
+    while i < len(words) and words[i].startswith('-'):
+        letters = words[i][1:]
+        if letters == 'c' and i + 1 < len(words):
+            cdir, i = words[i + 1], i + 2
+        elif letters and set(letters) <= {'A', 'D'}:
+            flags, i = flags | set(letters), i + 1
+        elif letters.endswith('s') and set(letters[:-1]) <= {'A', 'D'} and i + 1 < len(words):
+            flags, sess, i = flags | set(letters[:-1]), words[i + 1], i + 2
+        else:
+            return None   # -e (already has an identity, or a partial one), -d, -n, -x, …: not the plain shape
+    command = words[i:]
+    cdir = cdir or folder
+    if sess != session or flags != {'A', 'D'} or not command or not cdir.startswith('/'):
+        return None
+    return cdir, ' '.join(shlex.quote(w) for w in command)
+
+
+def normalized_text(text, lanes_by_name, canonicalize=None):
+    """Return the file text with uniform commands + the `lanes` block. Minimal textual edits when possible.
+    `canonicalize` = {'ws': workspace id, 'exists': container path -> True/False/None, 'repair': bool (default True,
+    `--canonicalize`), 'identity': bool (default False, `--identity`)}."""
     data = json.loads(text)
     block = {'version': 1, 'terminals': {}}
     commands = {}
@@ -47,6 +160,25 @@ def normalized_text(text, lanes_by_name):
             entry['tmux'] = {'socketName': lane['tmux']['socket'], 'sessionName': lane['tmux']['session']}
         if create:
             entry['create'] = create
+        if 'createPrevious' in previous:
+            entry['createPrevious'] = previous['createPrevious']
+        if canonicalize and lane.get('holder') == 'tmux' and lane.get('tmux'):
+            folder = lane.get('folder') or L.CONTAINER_HOME
+            socket, session = lane['tmux']['socket'], lane['tmux']['session']
+            kept = plain_tmux_new(create, folder, socket, session) if canonicalize.get('identity') else None
+            if canonicalize.get('repair', True) and needs_canonical(create, folder, canonicalize['exists']):
+                entry.pop('create', None)
+                entry['create'] = L.canonical_recipe(lane['id'], canonicalize['ws'], socket, session, folder)
+                entry['createPrevious'] = create
+            elif kept:
+                try:
+                    recipe = L.canonical_recipe(lane['id'], canonicalize['ws'], socket, session, kept[0], cmd=kept[1])
+                except L.LanesError:
+                    recipe = None   # a trace the proxy would reject: no identity to give, the recipe stays
+                if recipe:
+                    entry.pop('create', None)
+                    entry['create'] = recipe
+                    entry['createPrevious'] = create
         block['terminals'][term['name']] = entry
         commands[term['name']] = ENTRY + lane['id']
     # Nothing to do: leave the file byte-identical (never reformat somebody else's JSON).
@@ -104,7 +236,7 @@ def projected_text(source_text, source_path):
     return json.dumps({**note, **data}, ensure_ascii=False, indent=2) + '\n'
 
 
-def plan(registry, only=()):
+def plan(registry, only=(), canonicalize=False, identity=False):
     """Yield (workspace id, host path, container path, old text, new text, note)."""
     catalog = L.read_site_json(L.workspaces_dir() / 'catalog.json')['workspaces']
     containers = registry['containers']
@@ -123,7 +255,14 @@ def plan(registry, only=()):
             lanes = {name[len(prefix):] if prefix and name.startswith(prefix) else name: lane for name, lane in lanes.items()}
             host_file = L.host_path(info, repo['registry'])
             old = host_file.read_text()
-            new = normalized_text(old, lanes)
+
+            def exists(container_path, info=info):
+                try:
+                    return L.host_path(info, container_path).exists()
+                except (L.LanesError, OSError):
+                    return None   # outside the home volume / container unknown: not knowable, never "missing"
+            mode = {'ws': item['id'], 'exists': exists, 'repair': canonicalize, 'identity': identity}
+            new = normalized_text(old, lanes, mode if canonicalize or identity else None)
             yield item['id'], host_file, repo['registry'], old, new, 'registry'
             if repo.get('cursor'):
                 target = L.host_path(info, repo['cursor'])
@@ -136,7 +275,8 @@ def run(args):
     only = [a for a in args if not a.startswith('--')]
     registry = L.load_registry()
     changed = 0
-    for workspace, host_file, container_path, old, new, note in plan(registry, only):
+    plans = plan(registry, only, '--canonicalize' in args, '--identity' in args)
+    for workspace, host_file, container_path, old, new, note in plans:
         if host_file is None:
             print(f'== {workspace}: {note}')
             continue
@@ -162,5 +302,6 @@ def run(args):
             L.atomic_write(host_file, new, mode=mode)
             print(f'   written (backup in {backup_dir})')
     if not write and changed:
-        print(f'\n{changed} file(s) would change. Apply with:  lanes cursor-sync <workspace> --write')
+        again = ''.join(f' {flag}' for flag in ('--canonicalize', '--identity') if flag in args)
+        print(f'\n{changed} file(s) would change. Apply with:  lanes cursor-sync <workspace>{again} --write')
     return 0

package/payload/lanes/libexec/device_sync.py

@@ -0,0 +1,134 @@
+"""Reconcile catalog tabs without switching focus or touching persistent agents."""
+import fcntl
+import json
+import shlex
+
+import lanes_lib as L
+
+
+def observe(device, call):
+    values = []
+    for action in ('list-tabs', 'list-panes'):
+        rc, output, error = call(['-s', device, 'action', action, '--json'], 20)
+        if rc != 0:
+            raise L.LanesError(f'{device}: cannot read {action}: {error or "no answer"}')
+        try:
+            value = json.loads(output)
+            if not isinstance(value, list):
+                raise ValueError('expected a list')
+        except (ValueError, TypeError) as error:
+            raise L.LanesError(f'{device}: invalid {action} response') from error
+        values.append(value)
+    tabs, panes = values
+    if tabs and not panes:
+        raise L.LanesError(f"{device}: pane identities unavailable")
+    if any(type(t.get('tab_id')) is not int or type(t.get('position')) is not int for t in tabs):
+        raise L.LanesError(f'{device}: tab identities unavailable')
+    return tabs, panes
+
+
+def identities(device, tabs, panes, registry, mobile):
+    """Read workspace IDs from the launched commands, independent of tab labels."""
+    by_tab = {}
+    for pane in panes:
+        if pane.get('is_plugin'):
+            continue
+        try:
+            args = shlex.split(pane.get('terminal_command') or pane.get('pane_command') or '')
+        except ValueError:
+            continue
+        for script in ('sidebar', 'view.sh'):
+            path = str(L.REPO / 'libexec' / script)
+            if path not in args:
+                continue
+            tail = args[args.index(path) + 1:]
+            if len(tail) < 2 or tail[0] != device:
+                continue
+            workspace = tail[1]
+            if workspace.startswith('_'):
+                key = 'tool/' + workspace
+            else:
+                role = 'picker' if mobile and script == 'sidebar' else 'view'
+                key = f'workspace/{workspace}/{role}'
+            by_tab.setdefault(pane['tab_id'], set()).add(key)
+        holder = str(L.REPO / 'holders/ssh.sh')
+        if holder in args:
+            tail = args[args.index(holder) + 1:]
+            for workspace in registry.get('ssh_workspaces', []):
+                if (len(tail) == 3 and tail[:2] == [workspace['host'], workspace['command']]
+                        and any(pane['id'] == tail[2] for pane in workspace['panes'])):
+                    by_tab.setdefault(pane['tab_id'], set()).add('ssh/' + workspace['id'])
+    result = {}
+    for tab in tabs:
+        keys = by_tab.get(tab['tab_id'], set())
+        if not keys and tab['name'] == 'Host':
+            keys = {'host'}
+        if len(keys) > 1:
+            raise L.LanesError(f'{device}: ambiguous workspace tab {tab["tab_id"]}')
+        for key in keys:
+            if key in result:
+                raise L.LanesError(f'{device}: duplicate workspace identity {key}')
+            result[key] = tab
+    return result
+
+
+def reconcile(device, registry, specs, mobile, call):
+    lock = L.STATE / 'locks' / f'device-sync.{device}.lock'
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    with lock.open('a') as handle:
+        fcntl.flock(handle, fcntl.LOCK_EX)
+        tabs, panes = observe(device, call)
+        known = identities(device, tabs, panes, registry, mobile)
+        wanted = []
+        changes = []
+
+        def action(args):
+            rc, output, error = call(['-s', device, 'action'] + args, 30)
+            if rc != 0:
+                raise L.LanesError(f'{device}: {args[0]} failed: {error or "no answer"}')
+            return output
+
+        for spec in specs:
+            tab = known.get(spec['key'])
+            if tab is None:
+                if any(t['name'] == spec['title'] for t in tabs):
+                    raise L.LanesError(f'{device}: tab {spec["title"]!r} has no matching workspace identity; left intact')
+                # Zellij 0.45.1 acknowledges background tabs without spawning their
+                # panes when no client is attached. Wait for a client; the ensure
+                # timer retries after attach without leaving empty tabs behind.
+                if not any(t.get('active') is True for t in tabs):
+                    continue
+                output = action(['new-tab', '--no-focus', '--name', spec['title'],
+                                 '--layout-string', spec['layout']])
+                # Zellij 0.45.1 returns the stable ID. Do not guess after a timeout
+                # or repeat creation if the answer is missing: next sync observes it.
+                try:
+                    tab_id = int(output.strip())
+                except ValueError as error:
+                    raise L.LanesError(f'{device}: created tab ID unavailable; retry sync after observation') from error
+                tab = {'tab_id': tab_id, 'name': spec['title'], 'position': len(tabs)}
+                tabs.append(tab)
+                changes.append('added ' + spec['title'])
+            elif tab['name'] != spec['title']:
+                action(['rename-tab', spec['title'], '--tab-id', str(tab['tab_id'])])
+                changes.append('renamed ' + tab['name'] + ' to ' + spec['title'])
+            wanted.append(tab['tab_id'])
+
+        # Sort managed tabs by adjacent moves using stable IDs. Each observation
+        # must answer. Unmanaged tabs remain open; no close/rebuild/focus action exists.
+        for position, tab_id in enumerate(wanted):
+            for _ in range(len(tabs) + 1):
+                rc, output, error = call(['-s', device, 'action', 'list-tabs', '--json'], 20)
+                if rc != 0:
+                    raise L.LanesError(f'{device}: cannot check tab order: {error or "no answer"}')
+                live = json.loads(output)
+                tab = next((t for t in live if t.get('tab_id') == tab_id), None)
+                if tab is None:
+                    raise L.LanesError(f'{device}: workspace tab changed during sync')
+                if tab['position'] == position:
+                    break
+                action(['move-tab', 'left' if tab['position'] > position else 'right',
+                        '--tab-id', str(tab_id)])
+            else:
+                raise L.LanesError(f'{device}: tab order did not settle')
+        return changes