socialcli 0.3.0__py3-none-any.whl

socialctl/scheduler_launchd.py

@@ -0,0 +1,319 @@
+"""Workspace-owned macOS queue agents; unknown supervisor evidence fails closed."""
+import hashlib
+import os
+from pathlib import Path
+import plistlib
+import re
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+
+from socialctl.scheduler_systemd import SupervisorError
+
+
+def unit_name(brand: str, root: Path) -> str:
+    identity = str(Path(root).resolve()) + '\0' + brand
+    return 'com.socialcli.' + hashlib.sha256(identity.encode()).hexdigest()[:20] + '.run-due'
+
+
+def _plan(brand, root):
+    from socialctl.rutas import validar_componente_de_ruta
+    root = Path(root).resolve()
+    selected = validar_componente_de_ruta(root, brand, SupervisorError, 'brand name')
+    if not root.is_dir() or not (selected / 'brand.md').is_file():
+        raise SupervisorError('Select an existing brand and its explicit workspace root.')
+    # Preserve a venv interpreter symlink, rather than resolving to base Python.
+    argv = [str(Path(sys.executable).absolute()), '-m', 'socialctl', 'run-due',
+            '--brand', brand, '--root', str(root)]
+    if any(any(ord(c) < 32 or ord(c) == 127 for c in arg) for arg in argv):
+        raise SupervisorError('Scheduler paths and names must not contain control characters.')
+    name = unit_name(brand, root)
+    directory = Path.home() / 'Library/LaunchAgents'
+    log_dir = selected / '.socialctl'
+    payload = {'Label': name, 'ProgramArguments': argv, 'WorkingDirectory': str(root),
+               'StartInterval': 60, 'RunAtLoad': True, 'Umask': 0o077,
+               'StandardOutPath': str(log_dir / 'run-due.log'),
+               'StandardErrorPath': str(log_dir / 'run-due.error.log'), 'ProcessType': 'Background'}
+    return directory / (name + '.plist'), payload, plistlib.dumps(payload, sort_keys=False)
+
+
+def _run(args, *, check=True):
+    executable = shutil.which('launchctl')
+    if not executable:
+        raise SupervisorError('No launchd supervisor is available. Nothing was verified or changed.')
+    try:
+        result = subprocess.run([executable, *args], capture_output=True, text=True,
+                                timeout=15, check=False)
+    except (OSError, subprocess.TimeoutExpired):
+        raise SupervisorError('Could not contact the macOS user supervisor; inspect launchctl before retrying.') from None
+    if check and result.returncode:
+        raise SupervisorError('The macOS user supervisor rejected the operation; inspect launchctl before retrying.')
+    return result
+
+
+def _domain():
+    domain = f'gui/{os.getuid()}'
+    _run(['print', domain])
+    return domain
+
+
+def _job(domain, name):
+    result = _run(['print', domain + '/' + name], check=False)
+    if result.returncode == 0:
+        return result.stdout
+    # A successful domain probe plus the specific missing-service diagnostic is
+    # necessary: arbitrary command failures are not evidence of absence.
+    if (result.returncode == 113 and
+            f'Could not find service "{name}" in domain' in result.stderr):
+        return None
+    raise SupervisorError('Could not verify whether the macOS scheduler is registered; nothing was replaced or removed.')
+
+
+def _safe_parents(path):
+    if not path.is_absolute() or any(parent.is_symlink() for parent in path.parents):
+        raise SupervisorError('Refusing a symlinked supervisor configuration directory.')
+
+
+def _configuration(path, expected):
+    _safe_parents(path)
+    if not path.exists() and not path.is_symlink():
+        return False
+    # Read without following the final link and validate the opened inode.
+    if path.is_symlink() or not path.is_file():
+        raise SupervisorError('Existing scheduler configuration is unsafe; review it manually.')
+    with os.fdopen(os.open(path, os.O_RDONLY | os.O_NOFOLLOW), 'rb') as stream:
+        info = os.fstat(stream.fileno())
+        if (not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid()
+                or stat.S_IMODE(info.st_mode) != 0o600 or stream.read() != expected):
+            raise SupervisorError('Existing scheduler configuration differs or is not private and owned; nothing was replaced or removed.')
+    return True
+
+
+def _mkdir(directory):
+    _safe_parents(directory / '.scheduler-check')
+    missing = []
+    while not directory.exists():
+        missing.append(directory)
+        directory = directory.parent
+    for directory in reversed(missing):
+        directory.mkdir(mode=0o700)
+
+
+def _save_new(path, content):
+    # Link a complete private file into place without ever replacing a target,
+    # including one created between the preflight check and this operation.
+    with tempfile.NamedTemporaryFile(dir=path.parent, prefix='.' + path.name, delete=False) as stream:
+        temporary = Path(stream.name)
+        try:
+            os.fchmod(stream.fileno(), 0o600)
+            stream.write(content)
+            stream.flush()
+            os.fsync(stream.fileno())
+        except BaseException:
+            temporary.unlink(missing_ok=True)
+            raise
+    try:
+        os.link(temporary, path, follow_symlinks=False)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def _fields(output, target):
+    """Read only unambiguous direct job fields, never nested environment fields.
+
+    Apple explicitly documents `print` as diagnostic output, not an API. A
+    changed/missing format therefore yields unverified evidence, not success.
+    """
+    lines = output.strip().splitlines()
+    if not lines or lines[0].strip() != target + ' = {' or lines[-1].strip() != '}':
+        return {}, []
+    fields, argv, depth, arguments = {}, [], 1, False
+    for line in lines[1:-1]:
+        text = line.strip()
+        if text == '}':
+            depth -= 1
+            if depth < 1:
+                return {}, []
+            if depth == 1:
+                arguments = False
+        elif text.endswith(' = {'):
+            if depth == 1 and text == 'arguments = {':
+                if 'arguments' in fields:
+                    return {}, []
+                fields['arguments'] = True
+                arguments = True
+            depth += 1
+        elif depth == 2 and arguments:
+            if not text:
+                return {}, []
+            argv.append(text)
+        elif depth == 1 and ' = ' in text:
+            key, value = text.split(' = ', 1)
+            if key in fields:
+                return {}, []
+            fields[key] = value
+    return (fields, argv) if depth == 1 else ({}, [])
+
+
+def _loaded_matches(output, domain, path, payload):
+    fields, argv = _fields(output, domain + '/' + payload['Label'])
+    expected = {'path': str(path), 'type': 'LaunchAgent',
+                'program': payload['ProgramArguments'][0],
+                'working directory': payload['WorkingDirectory'],
+                'stdout path': payload['StandardOutPath'], 'stderr path': payload['StandardErrorPath'],
+                'run interval': '60 seconds'}
+    conflicts = (any(key in fields and fields[key] != value for key, value in expected.items())
+                 or ('arguments' in fields and argv != payload['ProgramArguments']))
+    return (all(fields.get(key) == value for key, value in expected.items())
+            and argv == payload['ProgramArguments']
+            and fields.get('state') in {'running', 'not running'}), fields, conflicts
+
+
+def _enabled(domain, name):
+    result = _run(['print-disabled', domain], check=False)
+    if result.returncode:
+        return None
+    lines = result.stdout.strip().splitlines()
+    if not lines or lines[0].strip() != 'disabled services = {' or lines[-1].strip() != '}':
+        return None
+    # Current macOS prints enabled/disabled; retain the boolean spelling used
+    # by earlier diagnostic fixtures without treating unknowns as on.
+    states = r'(true|false|enabled|disabled)'
+    entries = []
+    for line in lines[1:-1]:
+        if not re.fullmatch(r'\s*"[^"\n]+"\s*=>\s*' + states + r'\s*', line):
+            return None
+        match = re.fullmatch(r'\s*"' + re.escape(name) + r'"\s*=>\s*' + states + r'\s*', line)
+        if match:
+            entries.append(match.group(1))
+        elif '"' + name + '"' in line:
+            return None
+    return entries[0] in {'false', 'enabled'} if len(entries) == 1 else None
+
+
+def _legacy_present(brand, path, domain):
+    name = f'com.socialctl.{brand.lower()}.run-due'
+    legacy_path = path.parent / (name + '.plist')
+    return legacy_path.exists() or legacy_path.is_symlink() or _job(domain, name) is not None
+
+
+def inspect(brand: str, root: Path) -> dict:
+    report = {'kind': 'launchd_user', 'unit': unit_name(brand, root),
+              'configuration_matches': False, 'registered': False, 'enabled': None,
+              'active': False, 'survives_logout': False, 'service_failed': None,
+              'last_exit_code': None, 'last_terminating_signal': None,
+              'reason': 'configuration_missing'}
+    try:
+        path, payload, content = _plan(brand, root)
+        if not _configuration(path, content):
+            return report
+        domain = _domain()
+        if _legacy_present(brand, path, domain):
+            report['reason'] = 'legacy_job_present'
+            return report
+        observed = _job(domain, payload['Label'])
+        report['registered'] = observed is not None
+        if observed is None:
+            report['reason'] = 'job_unregistered'
+            return report
+        matches, fields, conflicts = _loaded_matches(observed, domain, path, payload)
+        report['configuration_matches'] = matches
+        code, signal = fields.get('last exit code', ''), fields.get('last terminating signal', '')
+        if re.fullmatch(r'-?\d+', code):
+            report['last_exit_code'] = int(code)
+            report['service_failed'] = int(code) != 0
+        if re.fullmatch(r'\d+', signal):
+            report['last_terminating_signal'] = int(signal)
+            if int(signal) != 0:
+                report['service_failed'] = True
+        elif 'last terminating signal' in fields and report['service_failed'] is not True:
+            # Unknown signal text must not inherit success from an older exit.
+            report['service_failed'] = None
+        if not matches:
+            report['reason'] = 'loaded_configuration_mismatch' if conflicts else 'loaded_configuration_unverified'
+            return report
+        report['active'] = True  # Registered interval task; a PID need not run between ticks.
+        report['enabled'] = _enabled(domain, payload['Label'])
+        report['reason'] = ('last_execution_failed' if report['service_failed'] is True
+                            else 'verified_now' if report['enabled'] is True and report['service_failed'] is False
+                            else 'execution_or_enabled_state_unverified')
+    except SupervisorError:
+        report['reason'] = 'configuration_or_supervisor_unverified'
+    except (OSError, ValueError):
+        report['reason'] = 'configuration_unreadable'
+    return report
+
+
+def install(brand: str, root: Path) -> dict:
+    path, payload, content = _plan(brand, root)
+    saved = _configuration(path, content)
+    domain = _domain()
+    if _legacy_present(brand, path, domain):
+        raise SupervisorError('A legacy brand-only scheduler exists. Review and explicitly migrate it first; nothing was replaced. See docs/local-scheduler.md.')
+    observed = _job(domain, payload['Label'])
+    if observed is not None and (not saved or not _loaded_matches(observed, domain, path, payload)[0]):
+        raise SupervisorError('An existing launchd job differs or is unverified; nothing was replaced.')
+    # launchd opens the log targets. Do not direct it through caller-supplied links.
+    log_dir = Path(payload['StandardOutPath']).parent
+    _safe_parents(log_dir / '.scheduler-check')
+    for key in ('StandardOutPath', 'StandardErrorPath'):
+        log = Path(payload[key])
+        if log.is_symlink() or (log.exists() and (not log.is_file() or log.stat().st_uid != os.getuid())):
+            raise SupervisorError('The scheduler log destination is unsafe; nothing was installed.')
+    _mkdir(path.parent)
+    _mkdir(log_dir)
+    if not saved:
+        _save_new(path, content)
+    if not _configuration(path, content):
+        raise SupervisorError('The scheduler configuration disappeared during inspection; nothing was loaded.')
+    _run(['enable', domain + '/' + payload['Label']])
+    if observed is None:
+        _run(['bootstrap', domain, str(path)])
+    # A new bootstrap can return before a complete diagnostic snapshot exists.
+    # Obtain fresh positive proof for a short bounded period; never replay a
+    # mutation or reinterpret missing evidence as a successful installation.
+    attempts = 5 if observed is None else 1
+    deadline = time.monotonic() + 1.0
+    retryable = {'job_unregistered', 'loaded_configuration_unverified',
+                 'configuration_or_supervisor_unverified', 'execution_or_enabled_state_unverified'}
+    for attempt in range(attempts):
+        if attempt and time.monotonic() >= deadline:
+            break
+        if not _configuration(path, content):
+            break
+        report = inspect(brand, root)
+        if not _configuration(path, content):
+            break
+        if report['service_failed'] is True or report['enabled'] is False:
+            break
+        if all(report[key] is True for key in ('configuration_matches', 'registered', 'enabled', 'active')):
+            return report
+        if (report['reason'] not in retryable or attempt + 1 == attempts
+                or time.monotonic() + 0.2 >= deadline):
+            break
+        time.sleep(0.2)
+    raise SupervisorError('The scheduler configuration was saved, but a working enabled launchd job was not verified; run schedule-doctor.')
+
+
+def uninstall(brand: str, root: Path) -> bool:
+    path, payload, content = _plan(brand, root)
+    saved = _configuration(path, content)
+    domain = _domain()
+    observed = _job(domain, payload['Label'])
+    if observed is None and not saved:
+        return False
+    if observed is not None:
+        if not saved or not _loaded_matches(observed, domain, path, payload)[0]:
+            raise SupervisorError('The registered scheduler differs or is unverified; nothing was removed.')
+        if not _configuration(path, content):
+            raise SupervisorError('The scheduler ownership file disappeared during inspection; nothing was removed.')
+        _run(['bootout', domain + '/' + payload['Label']])
+        if _job(domain, payload['Label']) is not None:
+            raise SupervisorError('The scheduler is still registered; its configuration was preserved.')
+    # Recheck before unlinking; never delete an edited/foreign file after bootout.
+    if _configuration(path, content):
+        path.unlink()
+    return True

socialctl/scheduler_systemd.py

@@ -0,0 +1,167 @@
+"""Customer-owned Linux user timers. No shell, media transfer or policy changes."""
+import hashlib
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+class SupervisorError(ValueError):
+    pass
+
+
+def unit_name(brand: str, root: Path) -> str:
+    identity = str(Path(root).resolve()) + '\0' + brand
+    return 'socialcli-' + hashlib.sha256(identity.encode()).hexdigest()[:20] + '-run-due'
+
+
+def _quote(value, *, command=False):
+    value = str(value)
+    if not value or any(ord(c) < 32 or ord(c) == 127 for c in value):
+        raise SupervisorError('Scheduler paths and names must not contain control characters')
+    value = value.replace('\\', '\\\\').replace('"', '\\"').replace('%', '%%')
+    if command:
+        value = value.replace('$', '$$')
+    return '"' + value + '"'
+
+
+def render(brand: str, root: Path, *, executable=None) -> tuple[str, str]:
+    root = Path(root).resolve()
+    executable = Path(executable or sys.executable).absolute()
+    name = unit_name(brand,root)
+    argv = [str(executable), '-m', 'socialctl', 'run-due', '--brand', brand, '--root', str(root)]
+    command = ' '.join(_quote(arg,command=True) for arg in argv)
+    # WorkingDirectory consumes the raw value, unlike ExecStart's word parser.
+    # Reject suffixes the unit-file parser would strip or join to the next line.
+    directory = str(root)
+    if directory != directory.rstrip() or directory.endswith('\\'):
+        raise SupervisorError('Scheduler workspace must not end with whitespace or a backslash')
+    directory = directory.replace('%','%%')
+    service = ('# Managed by SocialCli\n[Unit]\nDescription=SocialCli local queue executor\n\n'
+        '[Service]\nType=oneshot\nWorkingDirectory=' + directory + '\nExecStart=' + command +
+        '\nTimeoutStartSec=0\nUMask=0077\n')
+    timer = ('# Managed by SocialCli\n[Unit]\nDescription=SocialCli local queue timer\n\n'
+        '[Timer]\nOnActiveSec=5s\nOnUnitInactiveSec=60s\nAccuracySec=1s\nUnit=' + name +
+        '.service\n\n[Install]\nWantedBy=timers.target\n')
+    return service,timer
+
+
+def _directory():
+    configured = os.environ.get('XDG_CONFIG_HOME','').strip()
+    base = Path(configured) if configured else Path.home()/'.config'
+    if not base.is_absolute():
+        raise SupervisorError('XDG_CONFIG_HOME must be an absolute directory')
+    return base/'systemd'/'user'
+
+
+def _run(tool, args, *, check=True):
+    executable = shutil.which(tool)
+    if not executable:
+        raise SupervisorError(f'{tool} is unavailable; no working Linux user supervisor was verified')
+    try:
+        result = subprocess.run([executable,*args],capture_output=True,text=True,timeout=15,check=False)
+    except (OSError,subprocess.TimeoutExpired) as exc:
+        raise SupervisorError('Could not contact the Linux user supervisor; inspect the user service manager') from exc
+    if check and result.returncode:
+        raise SupervisorError('Linux user supervisor operation failed; inspect systemctl --user status and journalctl --user')
+    return result
+
+
+def _atomic(path, text):
+    if path.is_symlink():
+        raise SupervisorError('Refusing to replace a symlinked scheduler unit')
+    with tempfile.NamedTemporaryFile(mode='w',dir=path.parent,prefix='.'+path.name,delete=False) as stream:
+        temporary = Path(stream.name)
+        try:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        except BaseException:
+            temporary.unlink(missing_ok=True)
+            raise
+    try:
+        temporary.chmod(0o600)
+        os.replace(temporary,path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def inspect(brand: str, root: Path) -> dict:
+    name = unit_name(brand,root)
+    result = {'kind':'systemd_user','unit':name, 'configuration_matches':False,
+              'enabled':False,'active':False,'survives_logout':None,'service_failed':None}
+    try:
+        directory = _directory()
+        expected = render(brand,root)
+        paths = [directory/(name+suffix) for suffix in ('.service','.timer')]
+        if any(path.is_symlink() or not path.is_file() or path.read_text()!=text
+               for path,text in zip(paths,expected)):
+            return result
+        for path in paths:
+            observed = _run('systemctl',['--user','show','--property=NeedDaemonReload,DropInPaths,FragmentPath,ActiveState,Result',path.name])
+            properties = dict(line.split('=',1) for line in observed.stdout.splitlines() if '=' in line)
+            if (properties.get('NeedDaemonReload')!='no' or properties.get('DropInPaths')!=''
+                    or properties.get('FragmentPath')!=str(path)):
+                return result
+            if path.suffix == '.service':
+                result['service_failed'] = (properties.get('Result') != 'success'
+                    or properties.get('ActiveState') not in {'active','inactive','activating'})
+        result['configuration_matches']=True
+        enabled = _run('systemctl',['--user','is-enabled',name+'.timer'],check=False)
+        result['enabled']=enabled.returncode==0 and enabled.stdout.strip()=='enabled'
+        active = _run('systemctl',['--user','is-active',name+'.timer'],check=False)
+        result['active']=active.returncode==0 and active.stdout.strip()=='active'
+        linger = _run('loginctl',['show-user',str(os.getuid()),'--property=Linger','--value'],check=False)
+        if linger.returncode==0 and linger.stdout.strip() in {'yes','no'}:
+            result['survives_logout']=linger.stdout.strip()=='yes'
+    except (SupervisorError,OSError,ValueError):
+        # Fixed fields only; do not echo manager output or environment variables.
+        pass
+    return result
+
+
+def install(brand: str, root: Path) -> dict:
+    expected = render(brand,root)  # Validate paths before effects.
+    _run('systemctl',['--user','show','--property=Version','--value'])
+    directory = _directory()
+    directory.mkdir(parents=True,exist_ok=True)
+    name = unit_name(brand,root)
+    for suffix,text in zip(('.service','.timer'),expected):
+        _atomic(directory/(name+suffix),text)
+    _run('systemctl',['--user','daemon-reload'])
+    _run('systemctl',['--user','enable','--now',name+'.timer'])
+    report = inspect(brand,root)
+    if not all(report[key] for key in ('configuration_matches','enabled','active')):
+        raise SupervisorError('Scheduler units were saved, but an enabled active timer was not verified; run schedule-doctor')
+    return report
+
+
+def uninstall(brand: str, root: Path) -> bool:
+    directory = _directory()
+    name = unit_name(brand,root)
+    paths = [directory/(name+suffix) for suffix in ('.timer','.service')]
+    has_files = any(path.exists() or path.is_symlink() for path in paths)
+    if any(path.is_symlink() for path in paths):
+        raise SupervisorError('Refusing to remove a symlinked scheduler unit')
+    # A manager can retain an active timer after its files disappear. Missing
+    # files alone must never be reported as successful absence.
+    _run('systemctl',['--user','show','--property=Version','--value'])
+    observed = _run('systemctl',['--user','show','--property=LoadState,ActiveState,UnitFileState',name+'.timer'],check=False)
+    properties = dict(line.split('=',1) for line in observed.stdout.splitlines() if '=' in line)
+    absent = (properties.get('LoadState') == 'not-found'
+              and properties.get('ActiveState') == 'inactive'
+              and properties.get('UnitFileState') in {'','disabled','not-found'})
+    if not has_files and absent:
+        return False
+    if properties.get('ActiveState') != 'inactive':
+        # Stop first: disable --now can fail before its stop phase when the
+        # on-disk configuration is damaged. Never stop the paired service.
+        _run('systemctl',['--user','stop',name+'.timer'])
+    _run('systemctl',['--user','disable','--now',name+'.timer'])
+    # An in-flight approved write may finish. Killing it would create uncertainty.
+    for path in paths:
+        path.unlink(missing_ok=True)
+    _run('systemctl',['--user','daemon-reload'])
+    return True

socialctl/source_links.py

@@ -0,0 +1,119 @@
+"""Resolve explicit creator-owned source IDs before the existing approval flow."""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from urllib.parse import parse_qs, urlsplit
+
+import yaml
+
+from socialctl.models import Platform
+
+
+class StrictLoader(yaml.SafeLoader):
+    pass
+
+
+def _mapping(loader, node):
+    result = {}
+    for key_node, value_node in node.value:
+        key = loader.construct_object(key_node)
+        if not isinstance(key, str) or key in result:
+            raise ValueError('source-videos.yml contains duplicate/non-string keys')
+        result[key] = loader.construct_object(value_node)
+    return result
+
+
+StrictLoader.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, _mapping)
+
+
+def _entry(brand, slug):
+    path = brand.raiz / 'source-videos.yml'
+    try:
+        with path.open('rb') as handle:
+            raw = handle.read(256 * 1024 + 1)
+    except FileNotFoundError:
+        return None
+    except OSError:
+        raise ValueError('cannot read source-videos.yml') from None
+    try:
+        if len(raw) > 256 * 1024:
+            raise ValueError('source-videos.yml exceeds 256 KiB')
+        data = yaml.load(raw.decode('utf-8'), Loader=StrictLoader)
+        if (not isinstance(data, dict) or set(data) != {'version', 'clips'}
+                or type(data['version']) is not int or data['version'] != 1
+                or not isinstance(data['clips'], dict)):
+            raise ValueError('source-videos.yml requires version: 1 and an explicit clips mapping')
+        for key, row in data['clips'].items():
+            if (not isinstance(key, str) or not key or '/' in key or '\\' in key
+                    or key in {'.', '..'} or not isinstance(row, dict)
+                    or not {'video_id'} <= set(row) <= {'video_id', 'series'}
+                    or not isinstance(row['video_id'], str)
+                    or not re.fullmatch(r'[A-Za-z0-9_-]{11}', row['video_id'])
+                    or ('series' in row and (not isinstance(row['series'], str) or not row['series'].strip()))):
+                raise ValueError('invalid exact clip mapping: use a quoted 11-character video_id and optional series')
+        return data['clips'].get(slug)
+    except (yaml.YAMLError, UnicodeError):
+        raise ValueError('source-videos.yml is not valid strict YAML') from None
+
+
+def resolve_source_link(brand, post_slug):
+    entry = _entry(brand, post_slug)
+    return f"https://www.youtube.com/watch?v={entry['video_id']}" if entry else None
+
+
+def _digest(slug, entry):
+    return hashlib.sha256(json.dumps({'version': 1, 'slug': slug, 'entry': entry},
+        sort_keys=True, separators=(',', ':')).encode()).hexdigest()
+
+
+def _video_links(text):
+    for raw in re.findall(r'(?:https?://|www\.)[^\s<>]+', text or ''):
+        url = urlsplit(raw if '://' in raw else f'https://{raw}')
+        host = (url.hostname or '').casefold()
+        parts = url.path.strip('/').split('/')
+        if host in {'youtube.com', 'www.youtube.com', 'm.youtube.com', 'music.youtube.com'}:
+            ids = parse_qs(url.query).get('v', []) if url.path == '/watch' else parts[1:2] if parts[0] in {'shorts', 'embed', 'live'} else []
+            for ident in ids:
+                yield ident
+        elif host in {'youtu.be', 'www.youtu.be'}:
+            yield parts[0]
+
+
+def apply_source_mapping(brand, post, *, required=False):
+    entry = _entry(brand, post.slug)
+    if entry is None:
+        if required:
+            raise ValueError('source link unresolved: add this exact post slug to source-videos.yml')
+        return post
+    post = post.model_copy(deep=True)
+    ident = entry['video_id']
+    url = f'https://www.youtube.com/watch?v={ident}'
+    generated = f'Full video: {url}'
+    for platform, pp in post.platforms.items():
+        if (pp.source_video_id not in {None, ident} or pp.content_origin not in {None, 'youtube_long'}
+                or any(link != ident for field in (pp.body, pp.link, pp.first_comment)
+                       for link in _video_links(field))):
+            raise ValueError(f'{platform.value}: explicit source/link conflicts with source-videos.yml')
+        pp.source_video_id, pp.content_origin = ident, 'youtube_long'
+        if platform is Platform.TIKTOK:
+            if pp.first_comment:
+                raise ValueError('TikTok source linking uses the caption; first comments are unsupported')
+            if ident not in set(_video_links(pp.body)):
+                pp.body = f'{pp.body}\n\n{generated}'
+        elif ident not in set(_video_links(pp.first_comment)):
+            pp.first_comment = f'{pp.first_comment}\n{generated}' if pp.first_comment else generated
+    post.source_mapping_digest = _digest(post.slug, entry)
+    return post
+
+
+def verify_source_binding(brand, slug, mapping_digest):
+    if mapping_digest is not None:
+        entry = _entry(brand, slug)
+        if entry is None or _digest(slug, entry) != mapping_digest:
+            raise ValueError('source mapping changed after preview; run --dry-run and approve again')
+
+
+def verify_source_mapping(brand, post):
+    verify_source_binding(brand, post.slug, post.source_mapping_digest)

socialctl/ui/__init__.py

@@ -0,0 +1 @@
+"""Shared SocialCli visual system. Assets are compiled by scripts/build_ui_assets.py."""