@vibelord/lanes 1.0.3 → 1.1.0

package/payload/lanes/libexec/qr.py

@@ -0,0 +1,217 @@
+"""qr.py — a QR code of one short text, standard library only (W8 B5, LNS-49).
+
+`lanes web --token` draws the view's private URL with it when `qrencode` is not installed, so a phone camera opens the
+page; the login token is never encoded (it does not exist until zellij prints it, after the exec). Scope, chosen for
+that one use: byte mode, error correction level M, versions 1-6 (up to 106 bytes, 41x41 modules), all eight masks
+scored with the four penalty rules of ISO/IEC 18004 §7.8.3 (the rule-3 form zxing uses), lowest penalty wins.
+
+  encode(text, mask=None) -> Symbol(version, mask, modules)   modules[row][col] is True for a dark module;
+                                                              ValueError past 106 UTF-8 bytes
+  render(modules) -> str   half blocks (▀▄█), the light modules lit on a black background with a 4-module quiet
+                           zone: line for line the framing of `qrencode -t ANSIUTF8`
+  penalty(modules) -> int  the mask-selection score
+
+python3 libexec/qr.py TEXT   prints the code (a manual check; nothing calls it).
+"""
+import sys
+from collections import namedtuple
+
+Symbol = namedtuple('Symbol', 'version mask modules')
+
+# ISO/IEC 18004 table 9, level M: version -> (error correction codewords per block, blocks, data codewords per block).
+# Every block of a version has the same size at level M for versions 1-6.
+LEVEL_M = {1: (10, 1, 16), 2: (16, 1, 28), 3: (26, 1, 44), 4: (18, 2, 32), 5: (24, 2, 43), 6: (16, 4, 27)}
+FORMAT_LEVEL_M = 0b00   # the two error-correction bits of the format information (L 01, M 00, Q 11, H 10)
+MASKS = (lambda r, c: (r + c) % 2 == 0, lambda r, c: r % 2 == 0, lambda r, c: c % 3 == 0,
+         lambda r, c: (r + c) % 3 == 0, lambda r, c: (r // 2 + c // 3) % 2 == 0,
+         lambda r, c: (r * c) % 2 + (r * c) % 3 == 0, lambda r, c: ((r * c) % 2 + (r * c) % 3) % 2 == 0,
+         lambda r, c: ((r + c) % 2 + (r * c) % 3) % 2 == 0)
+QUIET = 4                                   # modules of light border on every side (ISO 18004 §6.3.8)
+ON, OFF = '\x1b[40;37;1m', '\x1b[0m'        # black background, bright white blocks: scans on a dark or a light theme
+HALF = ' ▄▀█'                               # index = 2 * (upper module light) + (lower module light)
+
+# GF(256) with the QR polynomial x^8 + x^4 + x^3 + x^2 + 1
+_EXP, _LOG = [0] * 510, [0] * 256
+_x = 1
+for _i in range(255):
+    _EXP[_i] = _EXP[_i + 255] = _x
+    _LOG[_x] = _i
+    _x <<= 1
+    if _x & 0x100:
+        _x ^= 0x11D
+
+
+def _mul(a, b):
+    return 0 if a == 0 or b == 0 else _EXP[_LOG[a] + _LOG[b]]
+
+
+def _ecc(data, degree):
+    """The Reed-Solomon remainder: data * x^degree mod the generator (x - α^0)…(x - α^(degree-1))."""
+    generator = [1]
+    for i in range(degree):
+        generator = [a ^ _mul(b, _EXP[i]) for a, b in zip(generator + [0], [0] + generator)]
+    remainder = [0] * degree
+    for word in data:
+        factor = word ^ remainder[0]
+        remainder = remainder[1:] + [0]
+        for i in range(degree):
+            remainder[i] ^= _mul(generator[i + 1], factor)
+    return remainder
+
+
+def _version(length):
+    for version, (_ecc_words, blocks, per_block) in LEVEL_M.items():
+        if length <= blocks * per_block - 2:   # 4 mode bits + 8 count bits leave room for (codewords - 1.5) bytes
+            return version
+    raise ValueError(f'{length} bytes do not fit a version 1-6 QR code at level M (106 at most)')
+
+
+def _codewords(data, version):
+    """Mode, count, bytes, terminator and pad codewords, split into blocks, each with its error correction, interleaved."""
+    ecc_words, blocks, per_block = LEVEL_M[version]
+    capacity = blocks * per_block * 8
+    bits = [int(b) for b in f'0100{len(data):08b}'] + [int(b) for byte in data for b in f'{byte:08b}']
+    bits += [0] * min(4, capacity - len(bits))
+    bits += [0] * (-len(bits) % 8)
+    words = [int(''.join(map(str, bits[i:i + 8])), 2) for i in range(0, len(bits), 8)]
+    words += [(0xEC, 0x11)[i % 2] for i in range(blocks * per_block - len(words))]
+    data_blocks = [words[b * per_block:(b + 1) * per_block] for b in range(blocks)]
+    ecc_blocks = [_ecc(block, ecc_words) for block in data_blocks]
+    return ([block[i] for i in range(per_block) for block in data_blocks]
+            + [block[i] for i in range(ecc_words) for block in ecc_blocks])
+
+
+def _function_patterns(version):
+    """(modules, reserved): finders with separators, timing, the alignment pattern, the dark module, and the format
+    areas reserved (drawn per mask)."""
+    size = 17 + 4 * version
+    modules = [[False] * size for _ in range(size)]
+    reserved = [[False] * size for _ in range(size)]
+
+    def put(row, col, dark):
+        modules[row][col], reserved[row][col] = dark, True
+    for top, left in ((0, 0), (0, size - 7), (size - 7, 0)):
+        for dr in range(-1, 8):
+            for dc in range(-1, 8):
+                if 0 <= top + dr < size and 0 <= left + dc < size:
+                    ring = max(abs(dr - 3), abs(dc - 3))   # 0-1 centre, 2 light ring, 3 outer ring, 4 separator
+                    put(top + dr, left + dc, ring in (0, 1, 3))
+    for i in range(8, size - 8):
+        put(6, i, i % 2 == 0)
+        put(i, 6, i % 2 == 0)
+    if version > 1:   # versions 2-6 have one alignment pattern, centred at (size - 7, size - 7)
+        centre = size - 7
+        for dr in range(-2, 3):
+            for dc in range(-2, 3):
+                put(centre + dr, centre + dc, max(abs(dr), abs(dc)) != 1)
+    for row, col in _format_cells(size)[0] + _format_cells(size)[1]:
+        put(row, col, False)
+    put(size - 8, 8, True)   # the dark module
+    return modules, reserved
+
+
+def _format_cells(size):
+    """Where bit i of the 15 format bits goes, bit 0 first, in each of the two copies (ISO 18004 figure 25)."""
+    first = [(i, 8) for i in range(6)] + [(7, 8), (8, 8), (8, 7)] + [(8, 5 - i) for i in range(6)]
+    second = [(8, size - 1 - i) for i in range(8)] + [(size - 7 + i, 8) for i in range(7)]
+    return first, second
+
+
+def _format_bits(mask):
+    data = FORMAT_LEVEL_M << 3 | mask
+    remainder = data << 10
+    for shift in range(4, -1, -1):   # BCH(15,5), generator x^10 + x^8 + x^5 + x^4 + x^2 + x + 1
+        if remainder & (1 << (shift + 10)):
+            remainder ^= 0x537 << shift
+    return (data << 10 | remainder) ^ 0x5412
+
+
+def _place(modules, reserved, codewords):
+    """Codeword bits, most significant first, in the two-column zigzag from the bottom-right corner; column 6 (timing)
+    is skipped. Remainder bits stay light."""
+    size = len(modules)
+    bits = [(word >> (7 - i)) & 1 for word in codewords for i in range(8)]
+    index = 0
+    for right in list(range(size - 1, 7, -2)) + [5, 3, 1]:   # right-hand column of each pair; the pairs alternate
+        upward = ((right + 1) & 2) == 0                    # up, down, up… (the size is odd: size - 1 is even)
+        for step in range(size):
+            row = size - 1 - step if upward else step
+            for col in (right, right - 1):
+                if not reserved[row][col] and index < len(bits):
+                    modules[row][col] = bool(bits[index])
+                    index += 1
+    return modules
+
+
+def _with_mask(modules, reserved, mask):
+    size = len(modules)
+    masked = [[modules[r][c] ^ (not reserved[r][c] and MASKS[mask](r, c)) for c in range(size)] for r in range(size)]
+    bits = _format_bits(mask)
+    for cells in _format_cells(size):
+        for i, (row, col) in enumerate(cells):
+            masked[row][col] = bool((bits >> i) & 1)
+    return masked
+
+
+def penalty(modules):
+    """ISO 18004 §7.8.3: N1 runs of five or more (3 + run - 5), N2 2x2 blocks of one colour (3 each), N3 dark-light-
+    dark x3-light-dark with four light modules before or after it, outside the symbol counting as light (40 each),
+    N4 10 per full 5 % that the dark share is away from 50 %."""
+    height, width = len(modules), len(modules[0])
+    columns = [[modules[r][c] for r in range(height)] for c in range(width)]
+    score = 0
+    for line in list(modules) + columns:
+        run, previous = 0, None
+        for cell in line + [None]:
+            if cell == previous:
+                run += 1
+                continue
+            if run >= 5:
+                score += 3 + run - 5
+            run, previous = 1, cell
+        for i in range(len(line) - 6):
+            if line[i:i + 7] == [True, False, True, True, True, False, True]:
+                before, after = line[max(0, i - 4):i], line[i + 7:i + 11]
+                if not any(before) or not any(after):
+                    score += 40
+    for r in range(height - 1):
+        for c in range(width - 1):
+            if modules[r][c] == modules[r][c + 1] == modules[r + 1][c] == modules[r + 1][c + 1]:
+                score += 3
+    dark = sum(map(sum, modules))
+    return score + 10 * (abs(2 * dark - height * width) * 10 // (height * width))
+
+
+def encode(text, mask=None):
+    """The QR code of `text` (its UTF-8 bytes, byte mode, level M) -> Symbol. mask=None picks the mask with the lowest
+    penalty (the lowest index on a tie); 0-7 forces one."""
+    data = text.encode('utf-8')
+    version = _version(len(data))
+    modules, reserved = _function_patterns(version)
+    _place(modules, reserved, _codewords(data, version))
+    if mask is not None:
+        return Symbol(version, mask, _with_mask(modules, reserved, mask))
+    scored = [(penalty(candidate), m, candidate) for m in range(8)
+              for candidate in [_with_mask(modules, reserved, m)]]
+    best = min(scored, key=lambda item: (item[0], item[1]))
+    return Symbol(version, best[1], best[2])
+
+
+def render(modules):
+    """Two module rows per text line; light modules lit, dark ones the black background; a light quiet zone."""
+    size = len(modules)
+    span = size + 2 * QUIET
+
+    def light(row, col):
+        row, col = row - QUIET, col - QUIET
+        return not (0 <= row < size and 0 <= col < size and modules[row][col])
+    lines = []
+    for row in range(0, span, 2):
+        lines.append(ON + ''.join(HALF[2 * light(row, col) + light(row + 1, col)] for col in range(span)) + OFF)
+    return '\n'.join(lines) + '\n'
+
+
+if __name__ == '__main__':
+    if len(sys.argv) != 2:
+        sys.exit('usage: python3 qr.py TEXT')
+    sys.stdout.write(render(encode(sys.argv[1]).modules))

package/payload/lanes/libexec/site_edit.py

@@ -0,0 +1,237 @@
+"""Catalog and workspace-manifest writer (LNS-51). Python 3 stdlib only.
+
+`add_workspace` appends one board to the site's `catalog.json` and writes its `workspaces.<id>.json` — the two files an
+operator used to edit by hand (lanes/workspaces.example/README.md). `lanes workspaces add` is the CLI over it, and
+`lanes onboard` (LNS-52) calls it first.
+
+The readers are `lanes_lib.build_registry` / `manifest_path` / `_workspace_lanes` and `cursor_sync.plan`; every value
+written here passes the rules those readers apply (identifiers, the in-container home-volume path), so a board this
+adds never makes `lanes sync` reject the catalog. Rules:
+
+  * an id already in the catalog is VERIFIED, never rewritten: agreement is a no-op (`exists`), any difference is
+    reported (`mismatch`) and nothing is written. The session is compared only when the caller names one;
+  * an existing manifest file is never overwritten; an orphan (no catalog entry) that declares the same repository
+    is adopted — that is what a run interrupted between its two writes leaves;
+  * a repository belongs to one board: a registry or Cursor projection (same container, same normalised path) that
+    another catalog board already names is refused before any write, because `lanes cursor-sync` rewrites it once
+    per board that names it, each time with that board's lane ids. An adopted orphan is checked with every
+    repository it declares; a board whose manifest cannot be read cannot be checked and refuses the write too;
+  * the manifest is written BEFORE the catalog entry that names it, both under `registry_lock()`, so a concurrent
+    `lanes sync` (which holds the same lock) reads the old catalog or the new one with its manifest present;
+  * the first write keeps `catalog.json.bak-<UTC>Z` beside it (session_actions.rename_registered's idiom);
+  * the site directory is the one `lanes_lib.workspaces_dir()` resolves after the write (`site_dir`).
+"""
+import contextlib
+import difflib
+import json
+import os
+import posixpath
+import time
+from pathlib import Path
+
+import lanes_lib as L
+
+RESERVED_TITLES = ('Host', 'Throttle')   # the layout's own tabs; lanes_lib.ssh_workspaces reserves the same titles
+
+
+def site_dir():
+    """Where a write goes: the directory `lanes_lib.workspaces_dir()` reads ($LANES_WORKSPACES, else
+    ~/.config/lanes/workspaces holding a catalog, else a single-site checkout's workspaces/ holding one). On a host
+    with no catalog anywhere it is ~/.config/lanes/workspaces — where host-install.sh puts the empty catalog and where
+    workspaces_dir() looks once the catalog exists. A fresh catalog is never created inside the checkout."""
+    if os.environ.get('LANES_WORKSPACES'):
+        return Path(os.environ['LANES_WORKSPACES'])
+    current = L.workspaces_dir()
+    if (current / 'catalog.json').exists():
+        return current
+    return Path.home() / '.config/lanes/workspaces'
+
+
+def _ident(value, label):
+    # fullmatch: IDENT's `$` would also accept a trailing newline under re.match.
+    if not isinstance(value, str) or not L.IDENT.fullmatch(value):
+        raise L.LanesError(f'Invalid {label}: {value!r}')
+    return value
+
+
+def _repo_path(value):
+    """The repository folder as the container sees it, normalised; under the home volume, because that is the only
+    place `lanes_lib.host_path` reaches its `.vscode/terminals.json` from the host."""
+    if not isinstance(value, str) or not value.startswith('/') or '..' in value.split('/'):
+        raise L.LanesError(f'Invalid repository path: {value!r} (an absolute path inside the container)')
+    path = '/' + posixpath.normpath(value).lstrip('/')   # normpath keeps a leading '//'
+    if not L.SAFE_PATH.fullmatch(path) or not (path + '/').startswith(L.CONTAINER_HOME + '/'):
+        raise L.LanesError(f'Invalid repository path: {value!r} (must be under {L.CONTAINER_HOME}, the container home '
+                           'volume, in letters, digits and ._-/)')
+    return path
+
+
+def registry_path(repo_path):
+    """`<repo>/.vscode/terminals.json` as the container sees it — the file a board's manifest names (and the one
+    `lanes onboard` looks for before it runs cursor-sync). Validates `repo_path` like add_workspace does."""
+    return _repo_path(repo_path) + '/.vscode/terminals.json'
+
+
+def render(document):
+    return json.dumps(document, indent=2, ensure_ascii=False) + '\n'
+
+
+def _manifest_differences(name, manifest, repo, session):
+    """What an existing manifest says that differs from the board asked for. Extra repositories and extra keys
+    (remoteShell, displayNames, monitor, …) are the operator's and never a difference."""
+    if not isinstance(manifest, dict):
+        return [f'{name}: not a JSON object']
+    differences = []
+    if session is not None and manifest.get('session') != session:
+        differences.append(f"session: {manifest.get('session')!r} (asked {session!r})")
+    repos = [r for r in manifest.get('repositories') or [] if isinstance(r, dict)]
+    match = next((r for r in repos if r.get('host') == repo['host'] and r.get('registry') == repo['registry']), None)
+    if match is None:
+        declared = '; '.join(f"{r.get('host')} {r.get('registry')}" for r in repos) or 'no repository'
+        differences.append(f"{name}: declares {declared}; asked {repo['host']} {repo['registry']}")
+    elif (match.get('prefix') or '') != repo['prefix']:
+        differences.append(f"prefix: {match.get('prefix')!r} (asked {repo['prefix']!r})")
+    return differences
+
+
+def _read_manifest(site, name):
+    try:
+        return L.read_site_json(site / name), None
+    except (OSError, ValueError, TypeError, L.LanesError) as error:   # read_site_json refuses a JSON array (DEF-1718)
+        return None, f'{name}: unreadable ({error})'
+
+
+def _container_path(value):
+    """A hand-written in-container path the way every reader resolves it (host_path joins it onto a pathlib.Path,
+    which drops `//` and `.` segments), so `/home/coder//x/./f` and `/home/coder/x/f` are one file."""
+    if not isinstance(value, str) or not value.startswith('/'):
+        return value
+    return '/' + posixpath.normpath(value).lstrip('/')
+
+
+def _claimed_files(manifest):
+    """{(container, in-container path): what it is} for every file `lanes cursor-sync` writes for a board: each
+    repository's registry and its Cursor projection (`cursor`). cursor_sync.plan walks the catalog and rewrites these
+    for each board that names them, with that board's `lane open <board>--<lane>` commands and `lanes` ids — so a file
+    two boards name is rewritten twice per run, the last board winning."""
+    claims = {}
+    repos = manifest.get('repositories') if isinstance(manifest, dict) else None
+    for repo in repos if isinstance(repos, list) else []:
+        if not isinstance(repo, dict):
+            continue
+        for key, what in (('registry', 'registry'), ('cursor', 'Cursor projection')):
+            if repo.get(key):
+                claims.setdefault((repo.get('host'), _container_path(repo[key])), what)
+    return claims
+
+
+def _refuse_shared_files(site, catalog_path, boards, manifest_name, manifest):
+    """One repository, one board: refuse when a file the new board makes cursor-sync write is already one it writes
+    for another catalog board. A board whose manifest cannot be read is refused too — its files cannot be checked,
+    and `lanes sync` already fails on that catalog (build_registry reads every manifest outside its per-board
+    error handling)."""
+    claims = _claimed_files(manifest)
+    for board in boards:
+        other, error = _read_manifest(site, board.get('manifest'))
+        if error:
+            raise L.LanesError(f"Cannot check the repositories of board {board.get('id')!r} in {catalog_path} against "
+                               f'{manifest_name}: {error}; fix or remove that board first (`lanes sync` fails on it '
+                               'too)')
+        for (container, path), what in _claimed_files(other).items():
+            if (container, path) in claims:
+                raise L.LanesError(
+                    f"{container} {path} is already the {what} of board {board.get('id')!r} ({board.get('manifest')}): "
+                    'a repository belongs to one board, because `lanes cursor-sync` rewrites its terminals.json for '
+                    f"every board that names it — its lanes are on board {board.get('id')!r}; choose another --repo")
+
+
+def add_workspace(workspace_id, title, container, repo_path, session=None, *, write=True):
+    """Add board `workspace_id` (tab `title`) whose lanes come from `<repo_path>/.vscode/terminals.json` inside
+    `container`. Returns {status, site, catalog, manifest, differences, changes, backups}: status is `added`,
+    `would-add` (write=False: nothing touched, `changes` holds the exact texts a real run writes), `exists` or
+    `mismatch` (nothing written; `differences` says what the site already states). Invalid values and collisions
+    with another tab (title, SSH workspace id, a manifest file another board names, a repository another board
+    declares, a board whose manifest cannot be read) raise LanesError before any write — in a dry run too."""
+    _ident(workspace_id, 'workspace id')
+    L._title(title)
+    _ident(container, 'container')
+    path = _repo_path(repo_path)
+    if session is not None:
+        _ident(session, 'session')
+    folder = path.rsplit('/', 1)[1]
+    repo = {'id': folder if L.IDENT.fullmatch(folder) else workspace_id, 'host': container,
+            'registry': registry_path(path), 'prefix': ''}
+    with L.registry_lock() if write else contextlib.nullcontext():
+        return _add(site_dir(), workspace_id, title, repo, session, write)
+
+
+def _add(site, workspace_id, title, repo, session, write):
+    catalog_path = site / 'catalog.json'
+    manifest_name = f'workspaces.{workspace_id}.json'
+    manifest_path = site / manifest_name
+    result = {'status': None, 'site': str(site), 'catalog': str(catalog_path), 'manifest': str(manifest_path),
+              'differences': [], 'changes': [], 'backups': []}
+    if catalog_path.exists():
+        catalog_text = catalog_path.read_text()
+        catalog = L.read_site_json(catalog_path)   # refuses a newer site schema
+    else:
+        catalog_text, catalog = None, {'version': L.SITE_SCHEMA, 'workspaces': []}
+    if not isinstance(catalog, dict):
+        raise L.LanesError(f'{catalog_path}: not a JSON object — refusing to rewrite it')
+    boards = catalog.setdefault('workspaces', [])
+    if not isinstance(boards, list):
+        raise L.LanesError(f'{catalog_path}: "workspaces" is not a list — refusing to rewrite it')
+    boards_seen = [w for w in boards if isinstance(w, dict)]
+    existing = next((w for w in boards_seen if w.get('id') == workspace_id), None)
+    if existing is not None:
+        differences = [] if existing.get('title') == title else [f"title: {existing.get('title')!r} (asked {title!r})"]
+        manifest, error = _read_manifest(site, existing.get('manifest'))
+        differences += [error] if error else _manifest_differences(existing.get('manifest'), manifest, repo, session)
+        result.update(status='mismatch' if differences else 'exists', differences=differences)
+        return result
+    ssh = [s for s in catalog.get('sshWorkspaces') or [] if isinstance(s, dict)]
+    if any(s.get('id') == workspace_id for s in ssh):
+        raise L.LanesError(f'{workspace_id!r} is already an SSH workspace id in {catalog_path}')
+    if title in {w.get('title') for w in boards_seen + ssh} | set(RESERVED_TITLES):
+        raise L.LanesError(f'Title {title!r} is already a tab (tabs are matched by title); choose another --title')
+    if any(w.get('manifest') == manifest_name for w in boards_seen):
+        raise L.LanesError(f'{manifest_name} is already the manifest of another board in {catalog_path}')
+    changes = []
+    if manifest_path.exists():
+        manifest, error = _read_manifest(site, manifest_name)
+        differences = [error] if error else _manifest_differences(manifest_name, manifest, repo, session)
+        if differences:
+            result.update(status='mismatch', differences=[
+                f'{manifest_name} exists without a catalog entry and was not overwritten'] + differences)
+            return result
+    else:
+        manifest = {'session': session or workspace_id, 'repositories': [repo]}
+        changes.append({'path': str(manifest_path), 'before': None, 'after': render(manifest)})
+    # After adoption is decided: an adopted orphan's catalog entry makes cursor-sync write EVERY repository it declares.
+    _refuse_shared_files(site, catalog_path, boards_seen, manifest_name, manifest)
+    boards.append({'id': workspace_id, 'title': title, 'manifest': manifest_name})
+    changes.append({'path': str(catalog_path), 'before': catalog_text, 'after': render(catalog)})
+    result['changes'] = changes
+    if not write:
+        result['status'] = 'would-add'
+        return result
+    for change in changes:   # manifest first: the catalog never names a manifest that is not there yet
+        target = Path(change['path'])
+        if change['before'] is not None and not any(site.glob(target.name + '.bak-*')):
+            backup = site / (target.name + '.bak-' + time.strftime('%Y%m%dT%H%M%SZ', time.gmtime()))
+            L.atomic_write(backup, change['before'], mode=0o644)
+            result['backups'].append(str(backup))
+        L.atomic_write(target, change['after'], mode=0o644)
+    result['status'] = 'added'
+    return result
+
+
+def diff_text(result):
+    """The planned or applied changes as unified diffs (what `lanes workspaces add` and `lanes onboard` print)."""
+    lines = []
+    for change in result['changes']:
+        before = change['before'] or ''
+        lines += difflib.unified_diff(before.splitlines(True), change['after'].splitlines(True),
+                                      f"{change['path']} ({'now' if change['before'] is not None else 'new file'})",
+                                      f"{change['path']} (with the board)")
+    return ''.join(lines)