@givolt/i3-composer-agent 3.1.0 → 4.0.0

package/skills/i3-enterprise-sop/references/handoff.py

@@ -1,5 +1,9 @@
 #!/usr/bin/env python3
-"""Path-only SOP handoff helper. Never writes business documents or approvals."""
+"""Business-document SOP handoff for one EBC per project.
+
+Pass spec/handoff.json explicitly for new manifests; relative references use the project root.
+Never writes documents or approvals.
+"""
 import argparse
 import copy
 import json
@@ -8,9 +12,11 @@ from pathlib import Path
 import tempfile
 import uuid
 
-VERSION = '0.2.0'
-GLOBAL_ROLES = {'brd', 'technicalBaseline'}
-TOPIC_ROLES = {'prd', 'ad', 'testCase', 'prototype', 'engineeringSkeleton', 'contracts'}
+VERSION = '0.5.0'
+GLOBAL_ROLES = {'brd'}
+PBC_ROLES = {'prd', 'ad', 'testCase'}
+DOCUMENT_ROLES = GLOBAL_ROLES | PBC_ROLES
+PBC_IDENTITY = ('pbcId', 'pbcName')
 
 
 def _unique(pairs):
@@ -26,38 +32,92 @@ def _nonstandard(value):
     raise ValueError('nonstandard JSON constant: ' + value)
 
 
-def _load(raw):
-    value = json.loads(raw, object_pairs_hook=_unique, parse_constant=_nonstandard)
-    if not isinstance(value, dict) or type(value.get('schemaVersion')) is not int or value['schemaVersion'] != 1:
-        raise ValueError('unsupported handoff schemaVersion; no automatic migration')
-    scope = value.get('scope')
-    if not isinstance(scope, dict) or not isinstance(scope.get('work'), str) or not scope['work'].strip():
-        raise ValueError('scope.work must identify the actual work')
-    if not isinstance(value.get('selected'), dict):
-        raise ValueError('selected must be an object')
-    topics = value['selected'].get('topics', [])
-    if not isinstance(topics, list):
-        raise ValueError('selected.topics must be an array')
-    seen = set()
-    for topic in topics:
-        if not isinstance(topic, dict) or not all(isinstance(topic.get(k), str) and topic[k].strip() for k in ['capabilityId', 'prdId']):
-            raise ValueError('topic requires capabilityId and prdId')
-        identity = (topic['capabilityId'], topic['prdId'])
-        if identity in seen:
-            raise ValueError('ambiguous duplicate topic selection')
-        seen.add(identity)
+def _required_text(value, label):
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(label + ' must be a nonempty string')
     return value
 
 
-def _selected_only(value):
-    """Canonical writes; legacy draft indexes never become selected inputs."""
-    unexpected = set(value) - {'schemaVersion', 'scope', 'selected', 'candidates', 'delivery'}
+def _only_fields(value, allowed, label):
+    if not isinstance(value, dict):
+        raise ValueError(label + ' must be an object')
+    unexpected = set(value) - set(allowed)
     if unexpected:
-        raise ValueError('unrecognized top-level fields; preserve the original and resolve their purpose before writing: '
+        raise ValueError('unrecognized ' + label + ' fields; preserve the original and resolve their purpose: '
                          + ', '.join(sorted(unexpected)))
+
+
+def _validate(value):
+    if not isinstance(value, dict) or type(value.get('schemaVersion')) is not int:
+        raise ValueError('unsupported handoff schemaVersion; expected integer 3')
+    if value['schemaVersion'] in (1, 2):
+        raise ValueError('legacy handoff schemaVersion; preserve the original and review each PBC document set; '
+                         'no automatic migration or merging of partial PRDs')
+    if value['schemaVersion'] != 3:
+        raise ValueError('unsupported handoff schemaVersion; expected 3; no automatic migration')
+    _only_fields(value, {'schemaVersion', 'scope', 'selected'}, 'handoff')
+    scope = value.get('scope')
+    _only_fields(scope, {'ebcId', 'ebcName'}, 'scope')
+    for key in ('ebcId', 'ebcName'):
+        _required_text(scope.get(key), 'scope.' + key)
+    selected = value.get('selected')
+    _only_fields(selected, GLOBAL_ROLES | {'pbcs'}, 'selected')
+    for role in GLOBAL_ROLES & set(selected):
+        _required_text(selected[role], 'selected.' + role)
+    pbcs = selected.get('pbcs')
+    if not isinstance(pbcs, list):
+        raise ValueError('selected.pbcs must be an array')
+    identities, names = set(), set()
+    for pbc in pbcs:
+        _only_fields(pbc, set(PBC_IDENTITY) | PBC_ROLES, 'pbc')
+        for key in PBC_IDENTITY:
+            _required_text(pbc.get(key), 'pbc.' + key)
+        if pbc['pbcId'] in identities:
+            raise ValueError('duplicate pbcId; one current document set per PBC')
+        if pbc['pbcName'] in names:
+            raise ValueError('different PBC identities cannot share a name and default directory')
+        identities.add(pbc['pbcId'])
+        names.add(pbc['pbcName'])
+        roles = PBC_ROLES & set(pbc)
+        if not roles:
+            raise ValueError('PBC must contain at least one selected PRD, AD or TestCase path')
+        for role in roles:
+            _required_text(pbc[role], 'pbc.' + role)
+    return value
+
+
+def _load(raw):
+    return _validate(json.loads(raw, object_pairs_hook=_unique, parse_constant=_nonstandard))
+
+
+def _selected_only(value):
+    """Validate the complete v3 record before writing; never discard unknown fields."""
+    _validate(value)
     return {key: copy.deepcopy(value[key]) for key in ('schemaVersion', 'scope', 'selected')}
 
 
+def _check_scope(value, ebc_id, ebc_name):
+    if value['scope']['ebcId'] != ebc_id:
+        raise ValueError('manifest belongs to a different EBC scope')
+    if ebc_name is not None and _required_text(ebc_name, 'ebcName') != value['scope']['ebcName']:
+        raise ValueError('ebcName conflicts with the selected EBC; verify the document identity before updating')
+
+
+def _pbc_name(selected, pbc_id, pbc_name):
+    _required_text(pbc_id, 'pbcId')
+    matches = [x for x in selected['pbcs'] if x['pbcId'] == pbc_id]
+    if pbc_name is None:
+        if not matches:
+            raise ValueError('a new PBC requires an explicit pbcName')
+        return matches[0]['pbcName']
+    _required_text(pbc_name, 'pbcName')
+    if matches and matches[0]['pbcName'] != pbc_name:
+        raise ValueError('pbcName conflicts with the selected PBC; verify the document identity before updating')
+    if any(x['pbcId'] != pbc_id and x['pbcName'] == pbc_name for x in selected['pbcs']):
+        raise ValueError('pbcName already belongs to a different PBC; default paths would collide')
+    return pbc_name
+
+
 def _manifest_path(root, raw):
     if not raw:
         raise ValueError('an explicit manifest path is required for this operation')
@@ -75,95 +135,126 @@ def _manifest_path(root, raw):
     return path
 
 
-def _reference(root, role, raw, capability_id=None, prd_id=None):
-    if role not in GLOBAL_ROLES | TOPIC_ROLES:
+def _reference(root, role, raw, pbc_id=None, pbc_name=None):
+    if role not in DOCUMENT_ROLES:
         raise ValueError('unknown reference role')
-    if not isinstance(raw, str) or not raw.strip():
-        raise ValueError('reference path must be explicit')
+    _required_text(raw, 'reference path')
     path = Path(raw)
     resolved = (path if path.is_absolute() else root / path).resolve()
     if not path.is_absolute() and not resolved.is_relative_to(root):
         raise ValueError('relative reference escapes project root; use an explicitly adopted absolute source')
-    if resolved.is_file():
-        if not resolved.read_text(encoding='utf-8').strip():
-            raise ValueError('empty document is not a complete handoff reference')
-    elif role != 'engineeringSkeleton' or not resolved.is_dir():
+    if not resolved.is_file():
         raise ValueError('reference missing or unreadable: ' + raw)
-    result = {'role': role, 'path': str(resolved.relative_to(root)) if resolved.is_relative_to(root) else str(resolved)}
-    if role in TOPIC_ROLES:
-        if not all(isinstance(x, str) and x.strip() for x in [capability_id, prd_id]):
-            raise ValueError('topic reference requires explicit capabilityId and prdId')
-        result.update(capabilityId=capability_id, prdId=prd_id)
+    if not resolved.read_text(encoding='utf-8').strip():
+        raise ValueError('empty document is not a complete handoff reference')
+    result = {'role': role,
+              'path': resolved.relative_to(root).as_posix() if resolved.is_relative_to(root) else str(resolved)}
+    if role in PBC_ROLES:
+        result.update(pbcId=_required_text(pbc_id, 'pbcId'), pbcName=_required_text(pbc_name, 'pbcName'))
     return result
 
 
-def _assign(selected, reference, *, transient=False):
+def _assign(selected, reference, *, transient=False, replace_document=False):
     role, path = reference['role'], reference['path']
     target = selected
-    if role in TOPIC_ROLES:
-        topics = selected.setdefault('topics', [])
-        matches = [x for x in topics if x['capabilityId'] == reference['capabilityId'] and x['prdId'] == reference['prdId']]
-        if len(matches) > 1:
-            raise ValueError('ambiguous duplicate topic selection')
+    if role in PBC_ROLES:
+        _pbc_name(selected, reference['pbcId'], reference['pbcName'])
+        matches = [x for x in selected['pbcs'] if x['pbcId'] == reference['pbcId']]
         if matches:
             target = matches[0]
         else:
-            target = {k: reference[k] for k in ['capabilityId', 'prdId']}
-            topics.append(target)
-    if role == 'contracts':
-        values = target.setdefault(role, [])
-        if not isinstance(values, list) or not all(isinstance(x, str) for x in values):
-            raise ValueError('contracts must be a path array')
-        if transient:
-            target[role] = [path]
-        elif path not in values:
-            values.append(path)
-    else:
-        if not transient and role in target and target[role] != path:
-            raise ValueError('existing selection differs; replacement and affected-pair recovery belong to S08')
-        target[role] = path
+            target = {k: reference[k] for k in PBC_IDENTITY}
+            selected['pbcs'].append(target)
+    previous_path = target.get(role)
+    if not transient and previous_path is not None and previous_path != path and not replace_document:
+        raise ValueError('updating a selected document requires --ebc-id matching scope.ebcId')
+    target[role] = path
+    return previous_path
 
 
-def _resolve(root, value, capability_id, prd_id, manual):
+def _resolve(root, value, pbc_id, pbc_name, manual):
     selected = copy.deepcopy(value['selected'])
-    topics = selected.get('topics', [])
-    if bool(capability_id) != bool(prd_id):
-        raise ValueError('provide both capabilityId and prdId')
-    if not capability_id and len(topics) == 1:
-        capability_id, prd_id = topics[0]['capabilityId'], topics[0]['prdId']
+    if pbc_id is None and len(selected['pbcs']) == 1:
+        pbc_id = selected['pbcs'][0]['pbcId']
+    if pbc_name is not None:
+        _pbc_name(selected, pbc_id, pbc_name)
     manual_roles = set()
     for item in manual:
         role, separator, path = item.partition('=')
         if not separator or role in manual_roles:
             raise ValueError('manual references require one unambiguous ROLE=PATH per role')
         manual_roles.add(role)
-        reference = _reference(root, role, path, capability_id, prd_id)
-        _assign(selected, reference, transient=True)
-    topics = selected.get('topics', [])
-    if not capability_id and len(topics) > 1:
-        raise ValueError('multiple topics; explicitly choose capabilityId and prdId')
-    references = []
-    for role in sorted(GLOBAL_ROLES):
-        if role in selected:
-            references.append(_reference(root, role, selected[role]))
-    matches = [x for x in topics if x['capabilityId'] == capability_id and x['prdId'] == prd_id]
-    if capability_id and topics and not matches:
-        raise ValueError('requested topic is not selected; no highest-version fallback')
-    for topic in matches:
-        for role in sorted(TOPIC_ROLES):
-            if role not in topic:
-                continue
-            paths = topic[role] if role == 'contracts' else [topic[role]]
-            if not isinstance(paths, list):
-                raise ValueError('contracts must be a path array')
-            for path in paths:
-                references.append(_reference(root, role, path, capability_id, prd_id))
+        name = _pbc_name(selected, pbc_id, pbc_name) if role in PBC_ROLES else None
+        _assign(selected, _reference(root, role, path, pbc_id, name), transient=True)
+    if pbc_id is None and len(selected['pbcs']) > 1:
+        raise ValueError('multiple PBCs; explicitly choose pbcId')
+    references = [_reference(root, role, selected[role]) for role in sorted(GLOBAL_ROLES) if role in selected]
+    matches = [x for x in selected['pbcs'] if x['pbcId'] == pbc_id]
+    if pbc_id is not None and not matches:
+        raise ValueError('requested PBC is not selected; no highest-version fallback')
+    for pbc in matches:
+        for role in sorted(PBC_ROLES):
+            if role in pbc:
+                references.append(_reference(root, role, pbc[role], pbc_id, pbc['pbcName']))
     for reference in references:
         path = Path(reference['path'])
         reference['resolvedPath'] = str(path if path.is_absolute() else root / path)
-    return {'ok': True, 'changed': False, 'source': 'manual' if manual else 'manifest',
-            'scope': value['scope'], 'references': references,
-            'proof': 'paths read now; caller must verify current identity, upstream, scope and actual human decisions'}
+    result = {'ok': True, 'changed': False, 'source': 'manual' if manual else 'manifest',
+              'scope': copy.deepcopy(value['scope']), 'references': references,
+              'proof': 'document paths read now; caller must verify document identities, versions, upstream '
+                       'and adopted attachments against the declared EBC/PBC scope and actual human decisions'}
+    if matches:
+        result['pbc'] = {key: matches[0][key] for key in PBC_IDENTITY}
+    return result
+
+
+def _component(value, label):
+    _required_text(value, label)
+    if value != value.strip() or value in {'.', '..'} or any(c in value for c in '/\\<>:"|?*') or any(ord(c) < 32 for c in value):
+        raise ValueError(label + ' is not a safe name for a new path; ask for the intended name, do not rename silently')
+    return value
+
+
+def _prepare(root, value, role, pbc_id, pbc_name, path, version):
+    if role not in DOCUMENT_ROLES | {'spec'}:
+        raise ValueError('prepare requires a document role or spec')
+    selected = value['selected']
+    target = selected
+    if role == 'brd' and (pbc_id is not None or pbc_name is not None):
+        raise ValueError('BRD belongs to the EBC, not a PBC')
+    if role != 'brd':
+        if pbc_id is None and len(selected['pbcs']) == 1:
+            pbc_id = selected['pbcs'][0]['pbcId']
+        pbc_name = _pbc_name(selected, pbc_id, pbc_name)
+        target = next((x for x in selected['pbcs'] if x['pbcId'] == pbc_id), {})
+    chosen = path or target.get(role)
+    source = 'explicit' if path else 'selected' if chosen else 'default'
+    if not chosen:
+        name = _component(value['scope']['ebcName'] if role == 'brd' else pbc_name, 'ebcName' if role == 'brd' else 'pbcName')
+        if role == 'spec':
+            chosen = 'spec/SPEC-' + name + '.md'
+        else:
+            tag = _component(_required_text(version, 'business version').removeprefix('v'), 'business version')
+            suffix = {'brd': 'BRD', 'prd': 'PRD', 'ad': 'AD', 'testCase': 'TestCase'}[role]
+            filename = name + '-' + suffix + '_v' + tag + '.md'
+            chosen = 'spec/' + ('' if role == 'brd' else name + '/') + filename
+    raw = Path(chosen)
+    actual = raw if raw.is_absolute() else root / raw
+    if actual.exists():
+        if not actual.is_file() or not actual.read_text(encoding='utf-8').strip():
+            raise ValueError('target is not a readable nonempty document; inspect before writing')
+        if not raw.is_absolute() and not actual.resolve().is_relative_to(root):
+            raise ValueError('relative target escapes project root')
+    else:
+        _manifest_path(root, chosen)
+    resolved = actual.resolve()
+    result = {'ok': True, 'changed': False, 'scope': copy.deepcopy(value['scope']), 'role': role,
+              'source': source, 'path': resolved.relative_to(root).as_posix() if resolved.is_relative_to(root) else str(resolved),
+              'resolvedPath': str(resolved), 'exists': actual.exists(),
+              'proof': 'names and target checked; no directory or document written; existing files require authorized revision'}
+    if role != 'brd':
+        result['pbc'] = {'pbcId': pbc_id, 'pbcName': pbc_name}
+    return result
 
 
 def _store(root, path, old, value):
@@ -209,63 +300,72 @@ def _store(root, path, old, value):
         lock.unlink()
 
 
-def execute(project_root, manifest, action, *, work=None, role=None, path=None,
-            capability_id=None, prd_id=None, manual=()):
+def execute(project_root, manifest, action, *, ebc_id=None, ebc_name=None, role=None, path=None,
+            pbc_id=None, pbc_name=None, version=None, manual=()):
     root = Path(project_root).resolve()
     if not root.is_dir():
         raise ValueError('explicit project root must already exist')
-    if action == 'resolve':
-        if manifest:
-            target = _manifest_path(root, manifest)
-            if not target.is_file():
-                raise ValueError('manifest missing; no automatic creation in read-only resolve')
-            value = _load(target.read_bytes())
-            if work is not None and work != value['scope']['work']:
-                raise ValueError('manifest belongs to a different work scope')
-        elif manual and isinstance(work, str) and work.strip():
-            value = {'schemaVersion': 1, 'scope': {'work': work}, 'selected': {}}
+    _required_text(ebc_id, 'ebcId')
+    if action not in {'init', 'select', 'resolve', 'prepare'}:
+        raise ValueError('unknown handoff action')
+    if action != 'resolve' and manual:
+        raise ValueError('manual overrides are read-only resolve inputs')
+    target = _manifest_path(root, manifest) if manifest else None
+    old = target.read_bytes() if target and target.is_file() else None
+    if action in {'resolve', 'prepare'}:
+        if old is not None:
+            value = _load(old)
+            _check_scope(value, ebc_id, ebc_name)
+        elif action == 'prepare' or (manual and not manifest):
+            value = {'schemaVersion': 3,
+                     'scope': {'ebcId': ebc_id, 'ebcName': _required_text(ebc_name, 'ebcName')},
+                     'selected': {'pbcs': []}}
         else:
-            raise ValueError('resolve requires an explicit manifest or manual references with work scope')
-        return _resolve(root, value, capability_id, prd_id, manual)
-    target = _manifest_path(root, manifest)
-    old = target.read_bytes() if target.is_file() else None
+            raise ValueError('manifest missing; use explicit manual resolve or return to T1; no automatic creation')
+        if action == 'prepare':
+            return _prepare(root, value, role, pbc_id, pbc_name, path, version)
+        return _resolve(root, value, pbc_id, pbc_name, manual)
+    if target is None:
+        raise ValueError('an explicit manifest path is required for this operation')
     if action == 'init':
-        if not isinstance(work, str) or not work.strip():
-            raise ValueError('init requires the actual work scope')
-        value = _load(old) if old is not None else {'schemaVersion': 1, 'scope': {'work': work}, 'selected': {}}
-        if value['scope']['work'] != work:
-            raise ValueError('existing manifest belongs to a different work scope')
-        return _store(root, target, old, value)
-    if action == 'select':
-        if manual:
-            raise ValueError('manual overrides are read-only resolve inputs')
-        if old is None:
-            raise ValueError('manifest missing; initialize the explicit work first or use manual resolve')
-        value = _load(old)
-        if work is not None and work != value['scope']['work']:
-            raise ValueError('manifest belongs to a different work scope')
-        reference = _reference(root, role, path, capability_id, prd_id)
-        _assign(value['selected'], reference)
+        _required_text(ebc_name, 'ebcName')
+        value = _load(old) if old is not None else {
+            'schemaVersion': 3, 'scope': {'ebcId': ebc_id, 'ebcName': ebc_name}, 'selected': {'pbcs': []}}
+        _check_scope(value, ebc_id, ebc_name)
         return _store(root, target, old, value)
-    raise ValueError('handoff operation not implemented in this increment')
+    if old is None:
+        raise ValueError('manifest missing; initialize the explicit EBC first or use manual resolve')
+    value = _load(old)
+    _check_scope(value, ebc_id, ebc_name)
+    if role in GLOBAL_ROLES and (pbc_id is not None or pbc_name is not None):
+        raise ValueError('BRD selection belongs to the EBC and does not take PBC identity')
+    name = _pbc_name(value['selected'], pbc_id, pbc_name) if role in PBC_ROLES else None
+    reference = _reference(root, role, path, pbc_id, name)
+    previous_path = _assign(value['selected'], reference, replace_document=True)
+    result = _store(root, target, old, value)
+    if previous_path is not None and previous_path != reference['path']:
+        result['updatedSelection'] = dict(reference, previousPath=previous_path)
+    return result
 
 
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument('action', choices=['init', 'select', 'resolve'])
-    parser.add_argument('--project-root', required=True)
-    parser.add_argument('--manifest')
-    parser.add_argument('--work')
-    parser.add_argument('--role', choices=sorted(GLOBAL_ROLES | TOPIC_ROLES))
-    parser.add_argument('--path')
-    parser.add_argument('--capability-id')
-    parser.add_argument('--prd-id')
+    parser.add_argument('action', choices=['init', 'select', 'resolve', 'prepare'])
+    parser.add_argument('--project-root', required=True, help='Explicit business project root; one EBC per project')
+    parser.add_argument('--manifest', help='Explicit manifest path; new projects use spec/handoff.json')
+    parser.add_argument('--ebc-id', required=True, help='Expected EBC identity; checked on every operation')
+    parser.add_argument('--ebc-name', help='Required for init and when no manifest exists')
+    parser.add_argument('--role', choices=sorted(DOCUMENT_ROLES | {'spec'}))
+    parser.add_argument('--path', help='Explicit adopted document or authorized new target; relative to the project root')
+    parser.add_argument('--pbc-id', help='PBC identity; no separate PRD theme identity')
+    parser.add_argument('--pbc-name', help='Required for a new PBC; existing names must match')
+    parser.add_argument('--version', help='Business document version for prepare when no path is selected; optional for spec')
     parser.add_argument('--manual', action='append', default=[], metavar='ROLE=PATH')
     args = parser.parse_args()
     try:
-        result = execute(args.project_root, args.manifest, args.action, work=args.work,
-                         role=args.role, path=args.path, capability_id=args.capability_id,
-                         prd_id=args.prd_id, manual=args.manual)
+        result = execute(args.project_root, args.manifest, args.action, ebc_id=args.ebc_id,
+                         ebc_name=args.ebc_name, role=args.role, path=args.path,
+                         pbc_id=args.pbc_id, pbc_name=args.pbc_name, version=args.version, manual=args.manual)
     except (OSError, ValueError, UnicodeError) as error:
         print(json.dumps({'ok': False, 'error': str(error)}, ensure_ascii=False))
         return 1

package/skills/i3-enterprise-sop/references/read_text.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+"""Return one bounded UTF-8 text page; use nextOffset unchanged for the next page."""
+import argparse
+import json
+from pathlib import Path
+
+
+def render(path, text, start, end):
+    return json.dumps({'path': str(path), 'offset': start, 'nextOffset': end,
+                       'eof': end == len(text), 'text': text[start:end]},
+                      ensure_ascii=False, separators=(',', ':'))
+
+
+def read_page(path, offset=0, max_chars=6000):
+    if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+        raise ValueError('offset must be a nonnegative integer')
+    if not isinstance(max_chars, int) or isinstance(max_chars, bool) or not 512 <= max_chars <= 10000:
+        raise ValueError('max-chars must be an integer from 512 to 10000')
+    source = Path(path).resolve(strict=True)
+    text = source.read_bytes().decode('utf-8')
+    if not text.strip():
+        raise ValueError('selected text file is empty')
+    if offset > len(text):
+        raise ValueError('offset is beyond the selected text; use the preceding nextOffset')
+    low, high = offset, min(len(text), offset + max_chars)
+    if len(render(source, text, offset, offset)) + 1 > max_chars:
+        raise ValueError('max-chars is too small for the path metadata')
+    while low < high:
+        end = (low + high + 1) // 2
+        if len(render(source, text, offset, end)) + 1 <= max_chars:
+            low = end
+        else:
+            high = end - 1
+    end = low
+    if end == offset and offset < len(text):
+        raise ValueError('max-chars leaves no room for text')
+    if end < len(text):
+        newline = text.rfind('\n', offset, end)
+        if newline >= offset:
+            end = newline + 1
+    return render(source, text, offset, end)
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--path', required=True)
+    parser.add_argument('--offset', type=int, default=0, help='Character cursor returned by the preceding page; initial value 0')
+    parser.add_argument('--max-chars', type=int, default=6000, help='Maximum serialized page length, including metadata and trailing newline')
+    args = parser.parse_args()
+    try:
+        page = read_page(args.path, args.offset, args.max_chars)
+    except (OSError, ValueError, UnicodeError) as error:
+        print(json.dumps({'ok': False, 'error': str(error)}, ensure_ascii=False))
+        return 1
+    print(page)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())