Files
Anya Tokugawa bee03094f3
Test and release pages-cli / linux (push) Successful in 9s
Test and release pages-cli / macos (push) Skipped
feat(auth): support explicit trusted login and expired session recovery
2026-11-08 20:29:10 +09:00

922 lines
54 KiB
Python
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
#!/usr/bin/env python3
"""pages — navigate and edit PagesWiki from your terminal (pages-cli)."""
import argparse
import email.policy
import email.parser
import email.utils
import datetime
import uuid
import base64
import contextlib
import difflib
import fcntl
import getpass
import hashlib
from html.parser import HTMLParser
import json
import os
from pathlib import Path
import posixpath
import re
import secrets
import shlex
import ssl
import stat
import subprocess
import sys
import tempfile
import time
import unicodedata
import urllib.error
import urllib.parse as url
import urllib.request as http
import webbrowser
VERSION = '0.5.0'
class Failure(Exception):
def __init__(self, message, status=0, payload=None):
super().__init__(message)
self.status, self.payload = status, payload or {}
def safe_text(value):
return ''.join(c for c in str(value) if c in '\n\t' or not unicodedata.category(c).startswith('C'))
def origin(value):
if not isinstance(value, str): raise Failure('Origin must be an HTTPS URL string.')
p = url.urlsplit(value)
if (p.scheme not in ('https', 'http') or not p.hostname or p.username or p.password
or p.path not in ('', '/') or p.query or p.fragment or any(c.isspace() for c in value)):
raise Failure('Use an HTTPS origin without credentials, path, query or fragment.')
if p.scheme == 'http' and p.hostname not in ('127.0.0.1', '::1', 'localhost'):
raise Failure('HTTP is permitted only for loopback development; use HTTPS remotely.')
return url.urlunsplit((p.scheme, p.netloc.lower(), '', '', ''))
def semantic(value, cwd='/'):
value = value.removeprefix('path:')
if '://' in value or '\\' in value or any(unicodedata.category(c).startswith('C') for c in value):
raise Failure('Expected a semantic Path, not a URL or control characters.')
return '/' + posixpath.normpath('/' + posixpath.join(cwd, value)).lstrip('/')
def address(value, cwd='/'):
if value.startswith(('uuid:', 'rev:')):
kind, ident = value.split(':', 1)
if not re.fullmatch(r'[0-9a-fA-F-]{36}', ident):
raise Failure('Invalid UUID address.')
return kind + ':' + ident
if re.match(r'^[a-zA-Z]+:', value) and not value.startswith('path:'):
raise Failure('This client supports path:, uuid: and read-only rev: addresses.')
return 'path:' + semantic(value, cwd)
class NoRedirect(http.HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None # Never forward credentials or turn a login HTML page into success.
class Client:
def __init__(self, base, token='', lang='auto', *, insecure=False):
self.base, self.token, self.lang = origin(base), token, lang
self.insecure = insecure
handlers = [NoRedirect()]
if insecure:
# This client's TLS policy only; never change Python's global defaults.
context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
context.check_hostname = False
context.verify_mode = ssl.CERT_NONE
context.set_alpn_protocols(['http/1.1'])
handlers.append(http.HTTPSHandler(context=context))
self.opener = http.build_opener(*handlers)
def request(self, route, method='GET', data=None, form=None, limit=4 << 20, etag=None, content_type=None):
if not route.startswith('/') or route.startswith('//'):
raise Failure('Invalid API route.')
headers = {'Accept': 'application/json', 'User-Agent': 'pages-cli/' + VERSION}
if etag is not None:
headers['If-Match'] = etag
if self.token:
headers['Authorization'] = 'Bearer ' + self.token
body = None
if data is not None:
body = data if isinstance(data, bytes) else json.dumps(data, ensure_ascii=False).encode()
headers['Content-Type'] = content_type or 'application/json'
if form is not None:
body = url.urlencode(form).encode()
headers['Content-Type'] = 'application/x-www-form-urlencoded'
if body is not None and len(body) > 2 << 20:
raise Failure('Request exceeds the 2 MiB client limit.')
req = http.Request(self.base + route, body, headers, method=method)
try:
with self.opener.open(req, timeout=20) as response:
raw = response.read(limit + 1)
if len(raw) > limit:
raise Failure('Response exceeds client limit; use the browser for large files.')
return raw, response.headers
except urllib.error.HTTPError as e:
raw = e.read(65536)
e.close()
try:
payload = json.loads(raw)
except (ValueError, UnicodeError):
payload = {}
if not isinstance(payload, dict):
payload = {}
messages = {303: 'Login redirect refused; log in again.', 401: 'Session expired or authentication required.', 403: 'Access denied.',
404: 'Not found or not readable.', 409: 'Conflict: remote revision changed.',
412: 'Conflict: remote item changed; reload before saving.', 422: 'Invalid fields; check dates, project and required settings.'}
raise Failure(messages.get(e.code, 'HTTP request failed (%d); redirects are not followed.' % e.code), e.code, payload) from None
except (urllib.error.URLError, TimeoutError, OSError):
raise Failure('Connection/TLS failure; no automatic write retry was attempted.') from None
def json(self, route, **kwargs):
raw, headers = self.request(route, **kwargs)
if headers.get_content_type() != 'application/json':
raise Failure('Expected JSON, not a login page or other projection.')
try:
value = json.loads(raw)
if not isinstance(value, dict):
raise ValueError()
return value
except (ValueError, UnicodeError):
raise Failure('Invalid JSON response.') from None
def login(self, username, password, otp=getpass.getpass, *, remember=False):
form={'username':username,'password':password}
if remember:form['remember']='1'
try:
result = self.json('/_/auth/login', method='POST', form=form)
except Failure as e:
if e.status != 401 or not e.payload.get('mfa_required') or not e.payload.get('challenge_token'):
raise
result = self.json('/_/auth/totp', method='POST', form={
'challenge_token': e.payload['challenge_token'], 'code': otp('TOTP: ')})
return self.accept_session(result)
def accept_session(self, result):
token = result.get('access_token')
if not isinstance(token, str) or not re.fullmatch(r'[A-Za-z0-9_.~-]{16,1024}', token) or result.get('token_type') != 'Bearer':
raise Failure('Server did not issue a Bearer session.')
duration = result.get('expires_in')
if not isinstance(duration, int) or isinstance(duration, bool) or not 1 <= duration <= 30*24*60*60:
raise Failure('Invalid session lifetime.')
self.token = token
return time.time() + duration
def login_oidc(self, no_browser=False, expected_username='', *, remember=False, sleep=time.sleep, clock=time.monotonic):
verifier = secrets.token_urlsafe(32)
challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).decode().rstrip('=')
try:
form={'code_challenge':challenge,'code_challenge_method':'S256'}
if remember:form['remember']='1'
started = self.json('/_/auth/cli/start', method='POST', form=form)
except Failure as e:
if e.status in (404, 405, 501):
raise Failure('CLI OIDC login is unavailable on this server. Check the configured server URL and deploy a server version supporting /_/auth/cli/start.', e.status) from None
if e.status == 403 and e.payload.get('error') == 'oidc_disabled':
raise Failure('OIDC login is not enabled for this domain. Ask your administrator to enable it.', e.status) from None
raise
device, route, code = (started.get(k) for k in ('device_code', 'verification_uri', 'user_code'))
if (not isinstance(device, str) or not re.fullmatch(r'[A-Za-z0-9_-]{43}', device)
or not isinstance(route, str) or not re.fullmatch(r'/_/auth/cli/verify\?request=[A-Za-z0-9_-]{43}', route)
or not isinstance(code, str) or not re.fullmatch(r'[A-F0-9]{4}-[A-F0-9]{4}', code)):
raise Failure('Invalid browser login response; no browser was opened.')
lifetime, interval = int(started.get('expires_in', 0)), int(started.get('interval', 0))
if not 1 <= lifetime <= 300 or not 5 <= interval <= 30:
raise Failure('Invalid browser login lifetime or polling interval.')
deadline = clock() + lifetime
print('Open this URL and approve only the request you started:')
print(self.base + route)
print('Confirmation code:', code)
print('Waiting for approval (up to 5 minutes). Ctrl+C cancels locally.', flush=True)
if not no_browser:
try: webbrowser.open(self.base + route, new=2)
except (webbrowser.Error, OSError): pass # URL remains usable on another device.
while clock() + interval < deadline:
sleep(interval)
try:
result = self.json('/_/auth/cli/token', method='POST', form={
'device_code': device, 'code_verifier': verifier})
except Failure as e:
reason = e.payload.get('error')
if e.status == 400 and reason == 'authorization_pending': continue
if e.status == 400 and reason == 'slow_down':
interval = min(30, interval + 5); continue
if reason in ('access_denied', 'expired_token', 'oidc_disabled'):
raise Failure('Browser login denied, expired or disabled. Restart pages login --oidc.') from None
raise # Never retry an ambiguous token exchange or a network failure.
name = result.get('username')
expires = self.accept_session(result)
if (not isinstance(name, str) or not name or any(unicodedata.category(c).startswith('C') for c in name)
or (expected_username and name.lower() != expected_username.lower())):
try: self.json('/_/auth/logout', method='POST')
except Failure: pass
self.token = ''
raise Failure('The browser account differs from the configured username; attempted to revoke the new session.')
return expires, name
raise Failure('Browser login expired. Restart pages login --oidc.')
def listing(self, path, prefix=''):
return self.json('/_/api/v1/path-picker?' + url.urlencode({'path': path, 'mode': 'children', 'prefix': prefix}))
def raw(self, addr, method='GET'):
query = '' if self.lang == 'auto' else '?' + url.urlencode({'lang': self.lang})
raw, headers = self.request('/v/raw/' + url.quote(addr, safe='/:') + query, method=method, limit=64 << 20)
digest = headers.get('X-PagesWiki-Document-SHA256')
if method == 'GET' and (not digest or hashlib.sha256(raw).hexdigest() != digest):
raise Failure('Document SHA-256 mismatch.')
return raw, headers
def snapshot(self, addr, lang=None):
if addr.startswith('rev:'):
raise Failure('Revision addresses are immutable; edit a path: or uuid: address.')
_, headers = self.raw(addr, 'HEAD')
ident = headers.get('X-PagesWiki-Object-UUID')
if not ident:
raise Failure('Missing Object UUID metadata.')
target = self.lang if lang is None else lang
visible = headers.get('X-PagesWiki-Revision-UUID', '')
def load(language, **extra):
return self.json('/_/api/v1/editor/state?' + url.urlencode({'uuid': ident, 'lang': language, **extra}))
if target == 'auto':
# Resolve the viewer's language, then obtain that exact language's
# current head. Never save against a head from a different language.
target = load('und', revision=visible, metadata=1)['lang'] if visible else 'und'
state = load(target)
if not state.get('editable') or not state.get('principal_uuid'):
raise Failure('Not an authenticated editable text document; use the browser.')
if not state.get('head_revision_uuid'):
# An empty CAS base asserts absence of this language. Seed from the
# visible source without changing it or pretending it is the base.
if visible:
source = load(state['lang'], revision=visible)
if not source.get('editable') or source.get('principal_uuid') != state['principal_uuid']:
raise Failure('Cannot fork this document or the editing account changed.')
for key in ('body', 'markdown', 'content_type', 'filename'):
state[key] = source[key]
state['source_revision_uuid'] = visible
state['source_language'] = source['lang']
state['new_language'] = True
if not state.get('content_type'):
raise Failure('Missing document format; use the browser.')
state['object_uuid'] = ident
return state
def save(self, state, text, markdown=False):
if len(text.encode()) > 1 << 20:
raise Failure('Text edit exceeds the 1 MiB client limit.')
if markdown:
if not state['content_type'].startswith('text/html'):
raise Failure('Markdown authoring is supported only for HTML Wiki documents.')
text = self.json('/_/api/v1/render/markdown', method='POST', data={
'markdown': text, 'authoring': True, 'projection': False})['html']
if state['head_revision_uuid'] and text == state['body']:
return {'status': 'unchanged', 'revision_uuid': state['head_revision_uuid']}
return self.json('/_/api/v1/revisions/save', method='POST', data={
'object_uuid': state['object_uuid'], 'body': text, 'lang': state['lang'],
'content_type': state['content_type'], 'filename': state['filename'],
'base_revision_uuid': state['head_revision_uuid'],
'editor_principal_uuid': state['principal_uuid'], 'message': 'Remote CLI edit'})
def private_file(path):
info = path.lstat()
if not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
raise Failure('Credential file must be a user-owned regular file with mode 0600.')
class PrivateJSON:
def __init__(self, root, filename):
self.root = Path(root)
self.root.mkdir(mode=0o700, parents=True, exist_ok=True)
info = self.root.lstat()
if not stat.S_ISDIR(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
raise Failure('Profile directory must be owned by you with mode 0700; symlinks are not accepted.')
self.path = self.root / filename
self.data = {}
@contextlib.contextmanager
def locked(self):
fd = os.open(str(self.path) + '.lock', os.O_RDWR | os.O_CREAT | os.O_NOFOLLOW, 0o600)
with os.fdopen(fd, 'w') as lock:
try:
fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
except BlockingIOError:
raise Failure('This profile is already in use by another CLI process.') from None
if self.path.exists() or self.path.is_symlink():
private_file(self.path)
self.data = json.loads(self.path.read_text())
if not isinstance(self.data, dict):
raise Failure('Invalid configuration object.')
yield self
def save(self):
fd, temp = tempfile.mkstemp(dir=self.root, prefix='.profile-')
try:
with os.fdopen(fd, 'w') as out:
json.dump(self.data, out)
out.flush()
os.fsync(out.fileno())
os.replace(temp, self.path)
finally:
if os.path.exists(temp):
os.unlink(temp)
def config_root(root=None):
return Path(root or os.environ.get('XDG_CONFIG_HOME', str(Path.home() / '.config'))) / 'pages-cli'
def profile_name(name):
if not isinstance(name, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', name):
raise Failure('Profile names use 1–64 letters, digits, underscores or hyphens.')
return name
def language(value):
if not isinstance(value, str) or not re.fullmatch(r'[A-Za-z]{1,8}(?:-[A-Za-z0-9]{1,8})*', value):
raise Failure('Use auto or a language tag such as und, ja or en-US; the server validates the exact tag.')
return value
class Profile(PrivateJSON):
def __init__(self, name, root=None):
self.name = profile_name(name)
# Validate the parent before creating sessions, including on first use.
PrivateJSON(config_root(root), 'config.json')
super().__init__(config_root(root) / 'sessions', profile_name(name) + '.json')
class Configuration(PrivateJSON):
def __init__(self, root=None):
super().__init__(config_root(root), 'config.json')
def validated(self):
if not self.data:
return {'version': 1, 'default_profile': 'default', 'profiles': {}}
if set(self.data) - {'version', 'default_profile', 'profiles'} or self.data.get('version') != 1:
raise Failure('Unsupported configuration format; credentials belong in sessions/, not config.json.')
default = profile_name(self.data.get('default_profile', 'default'))
profiles = self.data.get('profiles', {})
if not isinstance(profiles, dict): raise Failure('Invalid profiles configuration.')
normalized = {}
for name, spec in profiles.items():
profile_name(name)
if not isinstance(spec, dict) or set(spec) - {'origin', 'username', 'lang'}:
raise Failure('Profiles accept only origin, username and lang; never store a password here.')
if not isinstance(spec.get('username', ''), str) or any(unicodedata.category(c).startswith('C') for c in spec.get('username', '')):
raise Failure('Invalid configured username.')
normalized[name] = dict(spec, origin=origin(spec.get('origin', '')), lang=language(spec.get('lang', 'auto')))
if profiles and default not in profiles: raise Failure('Default profile does not exist.')
return {'version': 1, 'default_profile': default, 'profiles': normalized}
def configure(words, root=None):
parser = argparse.ArgumentParser(prog='pages configure', description='Manage connections and defaults. No network requests are made.')
sub = parser.add_subparsers(dest='action', required=True)
p = sub.add_parser('set', help='Create or update a connection profile')
p.add_argument('--profile'); p.add_argument('--origin'); p.add_argument('--username'); p.add_argument('--lang')
p = sub.add_parser('use', help='Select the default profile'); p.add_argument('profile')
sub.add_parser('show', help='Show settings, never session tokens')
sub.add_parser('list', help='List configured connections')
if not words: words = ['show']
elif words[0].startswith('--') and words[0] != '--help': words = ['set'] + words
args = parser.parse_args(words)
with Configuration(root).locked() as config:
data = config.validated()
if args.action == 'show':
print(json.dumps(data, ensure_ascii=False, indent=2)); return
if args.action == 'list':
for name, spec in data['profiles'].items():
print(safe_text(('★ ' if name == data['default_profile'] else ' ') + name + ' ' + spec['origin'] + ' ' + spec.get('username', '') + ' [' + spec.get('lang', 'auto') + ']'))
if not data['profiles']: print('No connections. Use: pages configure --origin https://wiki.example --username NAME')
return
if args.action == 'use':
name = profile_name(args.profile)
if name not in data['profiles']: raise Failure('Configure this profile before selecting it.')
data['default_profile'] = name
else:
name = profile_name(args.profile or data['default_profile'])
spec = dict(data['profiles'].get(name, {'lang': 'auto'}))
if args.origin is not None: spec['origin'] = origin(args.origin)
if args.username is not None: spec['username'] = args.username.strip()
if args.lang is not None: spec['lang'] = language(args.lang)
if not spec.get('origin'): raise Failure('A new connection requires --origin https://HOST.')
# Configuration and session locks use this order. Never retarget an
# active credential to a different Domain or account.
with Profile(name, root).locked() as session:
if session.data.get('token') and (spec['origin'] != session.data.get('origin') or spec.get('username', '') != session.data.get('configured_username', session.data.get('username'))):
raise Failure('Log out this profile before changing its origin or username.')
data['profiles'][name] = spec
if len(data['profiles']) == 1: data['default_profile'] = name
config.data = data
config.validated()
config.save()
print('Configured:', name); return
config.data = data; config.save()
print('Default profile:', data['default_profile'])
def editor(client, addr, mode):
state = client.snapshot(addr)
print('Editing language:', safe_text(state['lang']))
if state.get('new_language'):
print('Creating a new language revision; source remains unchanged:', safe_text(state.get('source_language', '(empty)')))
markdown = mode == 'markdown' or (mode == 'auto' and state['content_type'].startswith('text/html'))
initial = state['markdown'] if markdown else state['body']
directory = Path(tempfile.mkdtemp(prefix='pageswiki-edit-'))
file = directory / ('document.md' if markdown else 'document.txt')
file.touch(mode=0o600)
file.write_text(initial, encoding='utf-8')
success = False
try:
command = shlex.split(os.environ.get('EDITOR', 'vi'))
if not command or subprocess.run(command + [str(file)], check=False).returncode:
raise Failure('Editor exited unsuccessfully.')
text = file.read_text(encoding='utf-8')
if text == initial:
print('Unchanged.')
else:
try:
result = client.save(state, text, markdown)
except Failure as error:
if error.status == 409:
latest = client.snapshot('uuid:' + state['object_uuid'], lang=state['lang'])
remote = latest['markdown'] if markdown else latest['body']
print(safe_text(''.join(difflib.unified_diff(remote.splitlines(True), text.splitlines(True), fromfile='remote', tofile='local'))))
raise
print('Saved revision:', safe_text(result['revision_uuid']))
success = True
finally:
if success:
file.unlink()
directory.rmdir()
else:
metadata = directory / 'recovery.json'
metadata.touch(mode=0o600)
metadata.write_text(json.dumps({'origin': client.base, 'address': 'uuid:' + state['object_uuid'],
'base_revision_uuid': state['head_revision_uuid'], 'source_revision_uuid': state.get('source_revision_uuid', ''),
'lang': state['lang'], 'format': 'markdown' if markdown else 'raw'}))
print('Local edit retained:', safe_text(file), file=sys.stderr)
TASK_API = '/_/api/v1/extension/organizer.tasks/'
def task_uuid(value):
try:
parsed = str(uuid.UUID(value))
if parsed != value: raise ValueError()
return parsed
except (ValueError, AttributeError):
raise Failure('Use a canonical task or project UUID.') from None
def task_project(client, value):
if value == '': return ''
try: return task_uuid(value)
except Failure: pass
data = client.json(TASK_API+'items?'+url.urlencode({'kind':'project','view':'all','q':value,'limit':100}))
matches = [item['uuid'] for item in data.get('items',[]) if item['title'] == value]
if len(matches) != 1 or data.get('next'):
raise Failure('Project name is missing or ambiguous; use its UUID.')
return matches[0]
class MailText(HTMLParser):
"""Extract inert text; never load links, images, styles or attachments."""
def __init__(self):
super().__init__(convert_charrefs=True)
self.parts, self.hidden = [], []
def handle_starttag(self, tag, attrs):
if tag in ('script','style','head'): self.hidden.append(tag)
if not self.hidden and tag in ('br','p','div','li','tr','h1','h2','h3','pre'): self.parts.append('\n')
def handle_endtag(self, tag):
if self.hidden and tag == self.hidden[-1]: self.hidden.pop()
if not self.hidden and tag in ('p','div','li','tr','h1','h2','h3','pre'): self.parts.append('\n')
def handle_data(self, data):
if not self.hidden: self.parts.append(data)
def mail_subject(value):
# Remove only leading mailing-list sequence markers, preserving meaningful
# tags such as [Important], and any Re:/Fwd: prefix before the marker.
marker = re.compile(r'^(?P<reply>(?:(?:re|fw|fwd)\s*:\s*)*)\[[^\[\]\r\n]+[\s:#]\s*[0-9]+\]\s*', re.IGNORECASE)
while True:
match = marker.match(value)
if not match: return value.strip()
value = match.group('reply') + value[match.end():]
def task_mail_suffix(raw, request_id, now=None):
message = email.parser.BytesParser(policy=email.policy.default).parsebytes(raw)
subject = ' '.join(safe_text(str(message.get('Subject') or '')).split())
marker = re.match(r'^(?:(?:re|fw|fwd)\s*:\s*)*\[([A-Za-z0-9][A-Za-z0-9._-]{0,99})[\s:#]+([0-9]{1,20})\]',subject,re.IGNORECASE)
if marker:
return marker[1]+'/'+str(int(marker[2]))
try: date = email.utils.parsedate_to_datetime(str(message.get('Date') or ''))
except (ValueError, TypeError, OverflowError): date = now or datetime.datetime.now(datetime.timezone.utc)
# Preserve the month in the sender's Date timezone, not the receiving host's.
ident = request_id if ' '.join(safe_text(str(message.get('Message-ID') or '')).split()) else hashlib.sha256(raw).hexdigest()
return f'{date.year:04d}/{date.month:02d}/{ident}'
def task_mail(raw, include_body=True, override_title=None):
if len(raw) > 2 << 20: raise Failure('Mail input exceeds 2 MiB; pipe one message at a time.')
message = email.parser.BytesParser(policy=email.policy.default).parsebytes(raw)
clean = lambda value: ' '.join(safe_text(str(value or '')).split())
subject = clean(message.get('Subject'))
title = override_title or mail_subject(subject) or '(No subject)'
if not override_title and len(title.encode()) > 300:
title = title.encode()[:297].decode('utf-8',errors='ignore').rstrip() + '…'
if len(title.encode()) > 300: raise Failure('Mail subject exceeds 300 UTF-8 bytes; use --title.')
notes = '\n'.join(key+': '+clean(message.get(key)) for key in ('From','Date','Message-ID') if message.get(key))
wiki_body = None
if include_body:
content = ''
part = message.get_body(preferencelist=('plain','html'))
if part:
try: content = part.get_content()
except (LookupError, UnicodeError, ValueError) as e: raise Failure('Mail body encoding is not supported; convert to UTF-8 first.') from e
if not isinstance(content,str): raise Failure('Mail body is not readable text.')
if part.get_content_type() == 'text/html':
parser = MailText();parser.feed(content);parser.close();content = ''.join(parser.parts).strip()
# Retain the original subject when its mailing-list marker was removed.
wiki_body = (('Subject: '+subject+'\n') if title != subject else '') + notes + '\n\n' + content
if '\0' in wiki_body or len(wiki_body.encode()) > 256 << 10: raise Failure('Mail Wiki body must be valid text of at most 256 KiB; nothing was uploaded.')
if len(notes.encode()) > 16384: raise Failure('Mail metadata exceeds 16 KiB.')
return title, notes, clean(message.get('Message-ID')) or hashlib.sha256(raw).hexdigest(), wiki_body
def tasks(client, profile, words):
parser = argparse.ArgumentParser(prog='pages task',description='Private task capture, planning and work-time records. Stops do not complete a task.')
sub = parser.add_subparsers(dest='action',required=True)
p=sub.add_parser('list');p.add_argument('--view',default='all',choices=['all','today','inbox','backlog','someday','review','done','archived','carryover']);p.add_argument('--project');p.add_argument('--q',default='');p.add_argument('--before',default='')
sub.add_parser('projects')
p=sub.add_parser('project-add');p.add_argument('title');p.add_argument('--notes',default='')
p=sub.add_parser('show');p.add_argument('uuid',type=task_uuid)
for name in ('add','from-mail','update'):
p=sub.add_parser(name)
if name=='add':p.add_argument('title')
elif name=='update':p.add_argument('uuid',type=task_uuid);p.add_argument('--title')
else:
p.add_argument('--title');p.add_argument('--wiki-prefix',help='Wiki parent Path (otherwise use personal default or project Wiki subtree)')
body=p.add_mutually_exclusive_group();body.add_argument('--include-body',action='store_true',help='Save body to Wiki (default; retained for compatibility)');body.add_argument('--metadata-only',action='store_true',help='Do not upload body or create a Wiki document')
p.add_argument('--notes');p.add_argument('--project');p.add_argument('--assignee')
p.add_argument('--due');p.add_argument('--start-on');p.add_argument('--planned');p.add_argument('--review')
p.add_argument('--estimate',type=int);p.add_argument('--complexity',type=int,choices=range(1,6))
if name=='add':p.add_argument('--request-id',type=task_uuid)
for name in ('done','reopen','archive','start'):
p=sub.add_parser(name);p.add_argument('uuid',type=task_uuid)
sub.add_parser('stop');sub.add_parser('status')
p=sub.add_parser('retry');p.add_argument('request_id',type=task_uuid);p.add_argument('--recreate-deleted',action='store_true',help='Explicitly recreate a deleted capture with a new UUID; preserve and relink any existing Wiki page')
p=sub.add_parser('report');p.add_argument('--from',dest='start');p.add_argument('--to',dest='end')
p=sub.add_parser('preferences');p.add_argument('--wiki-prefix');p.add_argument('--project');p.add_argument('--assignee');p.add_argument('--due-days',type=int);p.add_argument('--start-days',type=int);p.add_argument('--planned-days',type=int);p.add_argument('--review-days',type=int);p.add_argument('--estimate',type=int);p.add_argument('--complexity',type=int);p.add_argument('--digest',choices=['on','off']);p.add_argument('--at');p.add_argument('--timezone')
for child in sub.choices.values():child.add_argument('--json',action='store_true')
a=parser.parse_args(words);action=a.action
def emit(data): print(json.dumps(data,ensure_ascii=False,indent=2))
def capture(payload):
pending=profile.data.setdefault('task_outbox',{})
if len(pending)>=20 and payload['request_id'] not in pending:raise Failure('20 pending captures retained. Retry them before adding more.')
replaced=payload['request_id'] in pending and pending[payload['request_id']] != payload
pending[payload['request_id']]=payload;profile.save()
if replaced:print('Replaced the retained draft with the current input.',file=sys.stderr)
try: result=client.json(TASK_API+'capture',method='POST',data=payload)
except Failure as e:
if e.status==410 and e.payload.get('error')=='deleted':
raise Failure('Draft retained. This task was deleted; normal retry will not restore it. To explicitly create a new task (preserving any existing Wiki body), use: pages task retry '+payload['request_id']+' --recreate-deleted',e.status,e.payload) from e
if e.status==409 and e.payload.get('error')=='capture_missing':
raise Failure('Draft retained. The server has a capture receipt but no task or deletion record. Server-side consistency repair is required; retry will not fix it.',e.status,e.payload) from e
if e.status==412:
raise Failure('Draft retained. This request ID conflicts with a server capture or task. An unchanged retry will not resolve it; inspect with: pages task show '+payload['request_id'],e.status,e.payload) from e
if e.status==409 and e.payload.get('error')=='note_exists':
raise Failure('Draft retained. A Wiki page already occupies the destination; it was not overwritten.',e.status,e.payload) from e
print('Draft retained; retry with: pages task retry '+payload['request_id'],file=sys.stderr)
if e.payload.get('error') == 'wiki_prefix_required': raise Failure('Set a private Wiki destination first: pages task preferences --wiki-prefix /YOUR/MAIL/PATH',e.status) from e
raise
del pending[payload['request_id']];profile.save();return result
if action in ('list','projects'):
query={'kind':'project' if action=='projects' else 'task','view':getattr(a,'view','all'),'limit':100,'q':getattr(a,'q',''),'before':getattr(a,'before','')}
if getattr(a,'project',None) is not None:query['project']=task_project(client,a.project)
data=client.json(TASK_API+'items?'+url.urlencode(query))
if a.json:emit(data)
else:
for item in data.get('items',[]):print(safe_text('\t'.join([item['uuid'],item['status'],item.get('due_on',''),item['title']])))
if data.get('next'):print('Next page: --before '+data['next'],file=sys.stderr)
return
if action=='show':emit(client.json(TASK_API+'items/'+a.uuid));return
if action=='preferences':
data=client.json(TASK_API+'preferences');p=data['preferences'];changed=False
for attr,key in [('wiki_prefix','wiki_prefix'),('project','project_uuid'),('assignee','assignee_uuid'),('due_days','due_days'),('start_days','start_days'),('planned_days','planned_days'),('review_days','review_days'),('estimate','estimate_minutes'),('complexity','complexity'),('at','digest_time'),('timezone','timezone')]:
value=getattr(a,attr)
if value is not None:p[key]=task_project(client,value) if attr=='project' else value;changed=True
if a.digest:p['digest_enabled']=a.digest=='on';changed=True
emit(client.json(TASK_API+'preferences',method='PUT',data=p) if changed else data);return
if action=='retry':
payload=profile.data.get('task_outbox',{}).get(a.request_id)
if not payload:raise Failure('No retained task capture with this request ID.')
if a.recreate_deleted:
pending=profile.data['task_outbox']
replacement=str(uuid.uuid5(uuid.NAMESPACE_URL,'pages:task-recreate:'+a.request_id))
payload=dict(payload,request_id=replacement,replaces_deleted=a.request_id)
if replacement in pending and pending[replacement]!=payload:
raise Failure('A different recreation draft already exists; inspect or retry it first: '+replacement)
previous=pending.copy()
pending[replacement]=payload;del pending[a.request_id]
try:profile.save()
except Exception:
profile.data['task_outbox']=previous
raise
print('Recreation draft saved. Existing Wiki content will be preserved. Retry ID: '+replacement,file=sys.stderr)
emit(capture(payload));return
if action in ('add','from-mail'):
payload={'request_id':getattr(a,'request_id',None) or str(uuid.uuid4()),'title':a.title,'notes':a.notes or ''}
if action=='from-mail':
if a.metadata_only and a.wiki_prefix is not None: raise Failure('--wiki-prefix cannot be combined with --metadata-only.')
raw=sys.stdin.buffer.read((2<<20)+1)
title,notes,message_id,wiki_body=task_mail(raw,not a.metadata_only,a.title)
payload.update(title=a.title or title,notes=a.notes if a.notes is not None else notes,request_id=str(uuid.uuid5(uuid.NAMESPACE_URL,client.base+'\n'+profile.data.get('username','')+'\n'+message_id)))
if wiki_body is not None:
payload['wiki_body']=wiki_body
payload['wiki_suffix']=task_mail_suffix(raw,payload['request_id'])
if a.wiki_prefix is not None: payload['wiki_prefix']=a.wiki_prefix
for attr,key in [('project','project_uuid'),('assignee','assignee_uuid'),('due','due_on'),('start_on','start_on'),('planned','planned_on'),('review','review_on'),('estimate','estimate_minutes'),('complexity','complexity')]:
value=getattr(a,attr)
if value is not None:payload[key]=task_project(client,value) if attr=='project' else value
# A retry of the same pending mail must not drift across a month boundary
# when Date was missing. Changed input replaces the pending draft below.
old=profile.data.get('task_outbox',{}).get(payload['request_id'])
if action=='from-mail' and old and {k:v for k,v in old.items() if k!='wiki_suffix'}=={k:v for k,v in payload.items() if k!='wiki_suffix'}:
payload=old.copy()
emit(capture(payload));return
if action=='project-add':
emit(client.json(TASK_API+'items',method='POST',data={'uuid':str(uuid.uuid4()),'kind':'project','title':a.title,'notes':a.notes,'status':'todo','bucket':'inbox','priority':1}));return
if action in ('update','done','reopen','archive'):
item=client.json(TASK_API+'items/'+a.uuid)['item']
if item['kind']!='task':raise Failure('This operation requires a task.')
for attr,key in [('title','title'),('notes','notes'),('project','project_uuid'),('assignee','assignee_uuid'),('due','due_on'),('start_on','start_on'),('planned','planned_on'),('review','review_on'),('estimate','estimate_minutes'),('complexity','complexity')]:
value=getattr(a,attr,None)
if value is not None:item[key]=task_project(client,value) if attr=='project' else value
if action=='done':item['status']='done'
elif action=='reopen':item['status']='todo'
elif action=='archive':item['archived']=True
emit(client.json(TASK_API+'items/'+a.uuid,method='PUT',data=item,etag='"'+str(item['version'])+'"'));return
if action=='start':
emit(client.json(TASK_API+'work',method='POST',data={'action':'start','uuid':str(uuid.uuid4()),'task_uuid':a.uuid,'version':0}));return
if action in ('stop','status'):
data=client.json(TASK_API+'work')
if action=='stop':
if not data['item']:raise Failure('No running work timer in this Domain.')
data=client.json(TASK_API+'work',method='POST',data={**data['item'],'action':'stop'})
emit(data);return
if action=='report':
query={k:v for k,v in [('from',a.start),('to',a.end)] if v}
data=client.json(TASK_API+'report?'+url.urlencode(query))
if a.json:emit(data);return
print('Timezone:',safe_text(data['timezone']))
print('Date\tCompleted\tPoints\tWork minutes\tPomodoro minutes')
for day in data['days']:
if day['completed'] or day['work_ms'] or day['focus_ms']:print('%s\t%d\t%d\t%.1f\t%.1f'%(day['date'],day['completed'],day['points'],day['work_ms']/60000,day['focus_ms']/60000))
print('\nTask UUID\tWork minutes\tTitle')
for task in data['tasks']:print(safe_text('%s\t%.1f\t%s'%(task['uuid'],task['work_ms']/60000,task['title'])))
if data['partial']:print('Partial report: narrow the date range.',file=sys.stderr)
def contacts(client, words):
parser=argparse.ArgumentParser(prog='pages contacts',description='Private address book; never links contacts to login accounts.')
sub=parser.add_subparsers(dest='action',required=True)
p=sub.add_parser('list');p.add_argument('--query',default='');p.add_argument('--after',default='')
p=sub.add_parser('query');p.add_argument('query');p.add_argument('--neomutt',action='store_true')
p=sub.add_parser('show');p.add_argument('uuid',type=task_uuid)
p=sub.add_parser('export');p.add_argument('uuid',type=task_uuid)
p=sub.add_parser('import');p.add_argument('file',type=Path)
a=parser.parse_args(words);api='/_/api/v1/extension/organizer.contacts/'
if a.action=='import':
with a.file.open('rb') as f:raw=f.read(65537)
if len(raw)>65536:raise Failure('One UTF-8 vCard per import, up to 64 KiB. Use the Web importer for multiple cards.')
data=client.json(api+'import',method='POST',data=raw,content_type='text/vcard')
elif a.action=='export':
data=client.json(api+'items/'+a.uuid);sys.stdout.write(data['item']['vcard']);return
elif a.action=='show':data=client.json(api+'items/'+a.uuid)
else:
try: data=client.json(api+'items?'+url.urlencode({'q':a.query,'after':getattr(a,'after','')}))
except Failure:
if a.action=='query' and a.neomutt: print('PagesWiki address query failed; check login and permissions.')
raise
if a.action=='query' and a.neomutt:
if not any(item['emails'] for item in data.get('items',[])):
print('No matching email addresses.')
raise Failure('No matching email addresses.')
print('PagesWiki contacts'+(' (first 100; narrow query)' if data.get('next') else ''))
for item in data.get('items',[]):
clean=lambda v:' '.join(safe_text(v).split())
for address in item['emails']:
# Do not let imported metadata forge query result columns.
if '\t' not in address and '\n' not in address and '\r' not in address:
print(clean(address)+'\t'+clean(item['name'])+'\t'+clean(item['organization']))
return
print(json.dumps(data,ensure_ascii=False,indent=2))
def execute(client, profile, words):
if words and words[0] in ('contact','contacts'):
return contacts(client,words[1:])
if words and words[0] in ('task','tasks'):
return tasks(client,profile,words[1:])
parser = argparse.ArgumentParser(prog='pages')
sub = parser.add_subparsers(dest='command', required=True)
for command in ('ls', 'cd', 'cat', 'view', 'edit', 'open'):
p = sub.add_parser(command)
p.add_argument('path', nargs='?', default='.')
if command == 'edit':
p.add_argument('--format', choices=['auto', 'raw', 'markdown'], default='auto')
p.add_argument('--lang', help='auto edits the visible language; an explicit tag can create a language revision')
p = sub.add_parser('get'); p.add_argument('path'); p.add_argument('local')
p = sub.add_parser('put'); p.add_argument('local'); p.add_argument('path'); p.add_argument('--base', required=True)
p.add_argument('--format', choices=['raw', 'markdown'], default='raw')
p = sub.add_parser('search'); p.add_argument('query')
sub.add_parser('pwd'); sub.add_parser('logout'); sub.add_parser('status')
args = parser.parse_args(words)
cwd = profile.data.get('cwd', '/')
cmd = args.command
if cmd == 'logout':
client.json('/_/auth/logout', method='POST')
profile.data.pop('token', None); profile.data.pop('expires', None); profile.save()
print('Session revoked.'); return
if cmd == 'pwd':
print(safe_text(cwd)); return
if cmd == 'status':
print(safe_text(client.base + '\n' + profile.data.get('username', '') + '\nPath: ' + cwd))
print('Language:', safe_text(client.lang))
print('Expires:', time.strftime('%Y-%m-%d %H:%M:%S %Z', time.localtime(profile.data.get('expires', 0))))
return
if cmd == 'search':
result = client.json('/_/api/v1/search/suggest?' + url.urlencode({'q': args.query}))
for item in result.get('items', []):
print(safe_text(item['path'] + '\t' + item['label']))
return
addr = address(args.path, cwd)
if cmd in ('ls', 'cd'):
if not addr.startswith('path:'): raise Failure('ls/cd require a Path.')
path = addr[5:]
result = client.listing(path)
if cmd == 'cd':
profile.data['cwd'] = path; profile.save()
else:
for item in result['entries']:
print(safe_text(item['name'] + ('/' if item['kind'] == 'folder' else '')))
if result.get('truncated'): print('Listing truncated; narrow the Path.', file=sys.stderr)
elif cmd == 'open':
route = addr[5:] if addr.startswith('path:') else '/o/' + addr if addr.startswith('uuid:') else '/r/view/' + addr[4:]
webbrowser.open(client.base + url.quote(route, safe='/:'), new=2)
elif cmd == 'edit':
editing = Client(client.base, client.token, language(args.lang), insecure=client.insecure) if args.lang else client
editor(editing, addr, args.format)
elif cmd == 'put':
state = client.snapshot(addr)
if not state['head_revision_uuid']:
raise Failure('No revision in the target language; use edit --lang to create a language revision.')
if state['head_revision_uuid'] != args.base: raise Failure('Conflict: supplied base is not the current language head.', 409)
text = Path(args.local).read_text(encoding='utf-8')
print('Revision:', safe_text(client.save(state, text, args.format == 'markdown')['revision_uuid']))
else:
raw, headers = client.raw(addr)
if cmd == 'get':
fd = os.open(args.local, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, 'wb') as out: out.write(raw)
print('Revision:', safe_text(headers.get('X-PagesWiki-Revision-UUID', 'unknown')))
elif cmd == 'cat' and not sys.stdout.isatty():
sys.stdout.buffer.write(raw)
else:
if not (headers.get_content_type().startswith('text/') or headers.get_content_type() in ('application/json', 'application/xml')):
raise Failure('Binary document: use get or open.')
text = safe_text(raw.decode('utf-8'))
if cmd == 'view' and sys.stdout.isatty():
subprocess.run(shlex.split(os.environ.get('PAGER', 'less')) , input=text.encode(), check=False)
else: print(text, end='')
def shell(client, profile):
import readline
print(safe_text('pages · ' + client.base + ' · ' + profile.data.get('username', '') + ' · ' + client.lang))
# History remains in memory, never on disk; login/password commands are not supported here.
readline.set_history_length(200)
readline.set_completer_delims(' \t\n')
matches = []
def complete(text, index):
if index == 0:
matches.clear()
try:
p = semantic(text, profile.data.get('cwd', '/'))
parent = p if text.endswith('/') else posixpath.dirname(p)
prefix = '' if text.endswith('/') else posixpath.basename(p)
for item in client.listing(parent, prefix)['entries']:
if any(unicodedata.category(c).startswith('C') for c in item['path']):
continue
candidate = item['path'] + ('/' if item['kind'] == 'folder' else '')
if not text.startswith('/'): candidate = posixpath.relpath(candidate, profile.data.get('cwd', '/')) + ('/' if item['kind'] == 'folder' else '')
matches.append(shlex.quote(candidate))
except Failure:
pass
return matches[index] if index < len(matches) else None
readline.set_completer(complete)
readline.parse_and_bind('tab: complete')
while True:
try:
line = input('pages[' + profile.name + ']:' + safe_text(profile.data.get('cwd', '/')) + '> ')
words = shlex.split(line)
if not words: continue
if words[0] in ('exit', 'quit'): break
if words[0] == 'login': raise Failure('Exit shell and use the login command.')
if words[0] != 'logout' and profile.data.get('expires', 0) <= time.time(): raise Failure('Session expired; log in again.')
execute(client, profile, words)
if words[0] == 'logout': break
except (Failure, ValueError, OSError) as e: print(safe_text(str(e)), file=sys.stderr)
except SystemExit: pass
except KeyboardInterrupt: print()
except EOFError: break
def main(argv=None):
parser = argparse.ArgumentParser(prog='pages', description=__doc__, epilog='Commands: configure, login, logout, status, shell, ls, cd, pwd, cat, view, get, put, edit, search, open, task, contacts. Use pages COMMAND --help.')
parser.add_argument('--version', action='version', version='pages-cli ' + VERSION)
parser.add_argument('--profile', help='Use another configured connection for this invocation')
parser.add_argument('--lang', help='auto or an exact language tag for this invocation')
parser.add_argument('-k', '--insecure', action='store_true', help='Skip TLS certificate and hostname verification for this invocation only (unsafe; place before COMMAND)')
parser.add_argument('command', nargs='?', default='shell')
parser.add_argument('args', nargs=argparse.REMAINDER)
args = parser.parse_args(argv)
if args.command == 'configure':
if args.profile or args.lang: parser.error('Use pages configure set --profile NAME --lang TAG.')
if args.insecure: parser.error('--insecure is invocation-only; configure does not connect or save a TLS bypass.')
configure(args.args); return
if args.command == 'help':
parser.print_help(); return
if args.command == 'login':
login = argparse.ArgumentParser(prog='pages login', description='Log into the configured connection. Password and TOTP are prompted privately.')
login.add_argument('--oidc', action='store_true', help='Authenticate and approve in a browser; no local password required')
login.add_argument('--no-browser', action='store_true', help='Print the browser login URL without opening it (requires --oidc)')
login.add_argument('--remember', action='store_true', help='Keep this trusted device signed in for up to 30 days, subject to server policy')
login_args = login.parse_args(args.args)
if login_args.no_browser and not login_args.oidc: login.error('--no-browser requires --oidc')
elif '--help' in args.args:
execute(None, None, [args.command] + args.args); return
with contextlib.ExitStack() as stack:
with Configuration().locked() as config:
settings = config.validated()
name = profile_name(args.profile or settings['default_profile'])
spec = settings['profiles'].get(name)
if spec is None:
raise Failure('No connection configured. Run: pages configure --origin https://HOST --username NAME')
lang = language(args.lang or spec.get('lang', 'auto'))
# Hold the profile lock before releasing the configuration lock.
profile = stack.enter_context(Profile(name).locked())
if args.insecure:
print('WARNING: --insecure disables TLS certificate and hostname verification for this invocation. Credentials and data can be intercepted; this option is not saved.', file=sys.stderr)
if args.command == 'login':
if not login_args.oidc and not spec.get('username'): raise Failure('Set your account with pages configure --username NAME, or use pages login --oidc.')
if profile.data.get('token') and profile.data.get('expires',0)>time.time(): raise Failure('Log out this profile before replacing its active session.')
client = Client(spec['origin'], lang=lang, insecure=args.insecure)
if login_args.oidc:
expires, username = client.login_oidc(login_args.no_browser, spec.get('username', ''), remember=login_args.remember)
else:
username = spec['username']
expires = client.login(username, getpass.getpass('Password: '), remember=login_args.remember)
same_identity = profile.data.get('origin') == client.base and profile.data.get('username') == username
pending = profile.data.get('task_outbox', {})
if pending and not same_identity:
try: client.json('/_/auth/logout', method='POST')
except Failure: pass
raise Failure('Pending task drafts belong to the previous account. Use a separate profile; the drafts were retained.')
cwd = profile.data.get('cwd', '/') if same_identity else '/'
profile.data = {'origin': client.base, 'username': username, 'configured_username': spec.get('username', ''), 'token': client.token, 'expires': expires, 'cwd': cwd}
if pending: profile.data['task_outbox'] = pending
try:
profile.save()
except OSError:
# Do not intentionally leave a usable session behind when its
# local credential cannot be persisted. Expiry is the fallback
# if the revocation request itself cannot reach the server.
try: client.json('/_/auth/logout', method='POST')
except Failure: pass
raise Failure('Could not save credentials; attempted to revoke the new session.') from None
print('Logged in. Session saved privately.'); return
if not profile.data.get('token'): raise Failure('Log in first.')
if args.command != 'logout' and (profile.data.get('origin') != spec['origin'] or profile.data.get('configured_username', profile.data.get('username')) != spec.get('username', '')):
raise Failure('Session and configured identity differ. Log out before reconnecting.')
if args.command not in ('logout', 'status') and profile.data.get('expires', 0) <= time.time(): raise Failure('Session expired; log out and log in again.')
client = Client(profile.data['origin'], profile.data['token'], lang, insecure=args.insecure)
if args.command == 'shell': shell(client, profile)
else: execute(client, profile, [args.command] + args.args)
if __name__ == '__main__':
try:
main()
except (Failure, OSError, ValueError, KeyError, KeyboardInterrupt) as e:
print(safe_text(str(e)) or 'Interrupted.', file=sys.stderr)
sys.exit(1)