@iducky/media-agent 1.1.0 → 1.1.1

package/src/media_agent/runtime/diagnostics.py

@@ -0,0 +1,186 @@
+"""Read-only inventory for task inspection and upgrade planning."""
+import argparse
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+from .locking import guard, process_alive
+from .paths import runtime_home
+
+UNFINISHED = {'prepared', 'preparing', 'uploading', 'confirming', 'submitting',
+              'verifying', 'indeterminate'}
+SETTLED = {'submitted', 'reviewing', 'published', 'scheduled', 'rejected', 'failed', 'aborted'}
+
+
+def tasks(home):
+    latest, errors = {}, []
+    for ledger in sorted((Path(home) / 'tasks').glob('**/*ledger*.jsonl')):
+        try:
+            for number, line in enumerate(ledger.read_text().splitlines(), 1):
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                    if not isinstance(entry, dict) or not entry.get('task_id'):
+                        raise ValueError('task_id missing')
+                    platform = ledger.parent.name
+                    latest[(platform, entry.get('profile_id'), entry['task_id'])] = {
+                        **entry, 'ledger': str(ledger.relative_to(home)), 'platform': platform}
+                except (ValueError, TypeError):
+                    errors.append(f'{ledger.relative_to(home)}:{number}: invalid task record')
+        except OSError as exc:
+            errors.append(f'{ledger.relative_to(home)}: {exc.strerror}')
+    retired_path = Path(home) / 'tasks/.retired-publish-tasks.json'
+    retired = {}
+    if retired_path.exists():
+        try:
+            retired = json.loads(retired_path.read_text())
+            if not isinstance(retired, dict):
+                raise ValueError('invalid retirement records')
+        except (OSError, ValueError):
+            errors.append('Invalid retirement records; upgrade blocked')
+            retired = {}
+    for entry in latest.values():
+        fingerprint = hashlib.sha256(json.dumps(entry, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+        entry['record_hash'] = fingerprint
+        entry['retired'] = fingerprint in retired
+    return list(latest.values()), errors
+
+
+def upgrade_report(home):
+    home = Path(home).expanduser().resolve()
+    active, stale, errors = [], [], []
+    for p in sorted((home / 'locks').glob('*.lock')):
+        try:
+            owner = json.loads(p.read_text())
+            if not isinstance(owner, dict):
+                raise ValueError('invalid owner')
+            record = {k: owner.get(k) for k in ('pid', 'task_id', 'phase')}
+            record['profile_id'] = p.stem
+            (active if process_alive(owner.get('pid')) else stale).append(record)
+        except (OSError, ValueError):
+            errors.append(f'locks/{p.name}: unreadable owner')
+    events, task_errors = tasks(home)
+    errors.extend(task_errors)
+    unfinished = [e for e in events if not e['retired'] and e.get('state') not in SETTLED]
+    processes = []
+    try:
+        output = subprocess.check_output(['ps', '-axo', 'pid=,args='], text=True)
+        for line in output.splitlines():
+            bits = line.strip().split(None, 1)
+            if len(bits) == 2 and str(home / 'profiles') + '/' in bits[1] and 'browser_data' in bits[1]:
+                processes.append({'pid': int(bits[0]), 'kind': 'profile-browser'})
+    except (OSError, ValueError, subprocess.SubprocessError):
+        errors.append('Cannot inspect active browser processes')
+    active_version = None
+    current = home / '.app/current'
+    if current.exists() or current.is_symlink():
+        try:
+            active_version = json.loads((current / 'package.json').read_text())['version']
+        except (OSError, ValueError, KeyError):
+            errors.append('Activated runtime is incomplete')
+    return {'runtime_home': str(home), 'active_version': active_version,
+            'legacy_entries': [n for n in ('social.sh', 'scripts') if (home / n).exists()],
+            'active_locks': active, 'stale_locks': stale, 'active_browsers': processes,
+            'unfinished_tasks': unfinished, 'retired_tasks': [e for e in events if e['retired']], 'errors': errors,
+            'safe_to_upgrade': not (active or processes or unfinished or errors),
+            'note': 'Snapshot only. Drain callers before setup; preserve and resolve unfinished publishing without retrying.'}
+
+
+def retire_task(home, profile_id, task_id, reason):
+    """Record an explicit decision to stop a historical task; never rewrite its result."""
+    report = upgrade_report(home)
+    if report['active_locks'] or report['active_browsers'] or report['errors']:
+        raise ValueError('Cannot retire tasks while runtime is active or unreadable')
+    entries, _ = tasks(home)
+    matches = [e for e in entries if e.get('profile_id') == profile_id and e.get('task_id') == task_id]
+    if len(matches) != 1:
+        raise ValueError('Select exactly one existing task with --profile-id')
+    record = matches[0]
+    path = Path(home) / 'tasks/.retired-publish-tasks.json'
+    with guard(path):
+        data = json.loads(path.read_text()) if path.exists() else {}
+        data[record['record_hash']] = {'profile_id': profile_id, 'task_id': task_id,
+                                     'state_preserved': record.get('state'), 'reason': reason,
+                                     'retired_at': datetime.now(timezone.utc).isoformat()}
+        fd, temporary = tempfile.mkstemp(prefix='.retired-', dir=path.parent)
+        try:
+            with os.fdopen(fd, 'w') as f:
+                json.dump(data, f, ensure_ascii=False, indent=2)
+            os.replace(temporary, path)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+    return {'task_id': task_id, 'profile_id': profile_id, 'retired': True,
+            'state_preserved': record.get('state'), 'reason': reason}
+
+
+def validate_config(home):
+    errors, profiles, warnings = [], [], []
+    for p in sorted((Path(home) / 'profiles').glob('*/config.json')):
+        issues = []
+        notes = []
+        try:
+            d = json.loads(p.read_text())
+            account = d.get('account', {})
+            if account.get('platform') is None:
+                notes.append('legacy config has no platform; verify before platform-specific operations')
+            elif account.get('platform') not in ('douyin', 'xiaohongshu', 'toutiao'):
+                issues.append('unsupported or missing platform')
+            if 'capabilities' not in account:
+                notes.append('legacy capability fallback; explicit capabilities recommended')
+            elif not isinstance(account['capabilities'], list):
+                issues.append('capabilities must be a list')
+            if not isinstance(d.get('fingerprint'), dict):
+                issues.append('fingerprint missing')
+        except (OSError, ValueError, AttributeError):
+            issues.append('invalid config.json')
+        profiles.append({'profile_id': p.parent.name, 'issues': issues, 'warnings': notes})
+        errors.extend(f'{p.parent.name}: {issue}' for issue in issues)
+        warnings.extend(f'{p.parent.name}: {note}' for note in notes)
+    return {'valid': not errors, 'profiles': profiles, 'errors': errors, 'warnings': warnings}
+
+
+def main(argv):
+    parser = argparse.ArgumentParser(prog='media-agent ' + argv[0])
+    command = argv[0]
+    if command == 'upgrade':
+        parser.add_argument('--check', action='store_true', required=True)
+    elif command == 'tasks':
+        parser.add_argument('operation', choices=['list', 'show', 'retire'])
+        parser.add_argument('task_id', nargs='?')
+        parser.add_argument('--profile-id')
+        parser.add_argument('--reason')
+    elif command == 'config':
+        parser.add_argument('operation', choices=['validate'])
+    parser.add_argument('--json', action='store_true')
+    args = parser.parse_args(argv[1:])
+    home = runtime_home()
+    if command == 'upgrade':
+        result = upgrade_report(home)
+        code = 0 if result['safe_to_upgrade'] else 6
+    elif command == 'config':
+        result = validate_config(home)
+        code = 0 if result['valid'] else 1
+    else:
+        if args.operation in ('show', 'retire') and not args.task_id:
+            parser.error(args.operation + ' requires task_id')
+        if args.operation == 'retire':
+            if not args.profile_id or not args.reason or not args.reason.strip():
+                parser.error('retire requires --profile-id and --reason; explicit user disposition is required')
+            try:
+                result = retire_task(home, args.profile_id, args.task_id, args.reason)
+            except ValueError as exc:
+                parser.error(str(exc))
+            print(json.dumps(result, ensure_ascii=False, indent=2))
+            return 0
+        events, errors = tasks(home)
+        events = [e for e in events if (not args.profile_id or e.get('profile_id') == args.profile_id)
+                  and (not args.task_id or e.get('task_id') == args.task_id)]
+        result = {'tasks': events, 'errors': errors}
+        code = 1 if errors else (5 if args.operation == 'show' and not events else 0)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return code

package/src/media_agent/runtime/locking.py

@@ -0,0 +1,74 @@
+"""Process-owned profile locks shared by all supported runtime entry points."""
+from contextlib import contextmanager
+from datetime import datetime, timezone
+import errno
+import fcntl
+import json
+import os
+from pathlib import Path
+
+
+def process_alive(pid):
+    # Missing/invalid ownership is unknown, never permission to steal a lock.
+    if isinstance(pid, bool) or not isinstance(pid, int) or pid <= 1:
+        return True
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError as exc:
+        return exc.errno != errno.ESRCH
+
+
+@contextmanager
+def guard(path):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(str(path) + '.guard', os.O_CREAT | os.O_RDWR | os.O_NOFOLLOW, 0o600)
+    try:
+        fcntl.flock(fd, fcntl.LOCK_EX)
+        yield
+    finally:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+        os.close(fd)
+
+
+def acquire(path, task_id, initialize=None, **metadata):
+    path = Path(path)
+    with guard(path):
+        if path.is_symlink():
+            return False
+        if path.exists():
+            try:
+                old = json.loads(path.read_text())
+                if not isinstance(old, dict) or process_alive(old.get('pid')):
+                    return False
+            except (OSError, ValueError):
+                return False
+            path.unlink()
+        if initialize is not None:
+            initialize()
+        data = {**metadata, 'pid': os.getpid(), 'task_id': task_id,
+                'locked_at': datetime.now(timezone.utc).isoformat()}
+        try:
+            with path.open('x') as f:
+                json.dump(data, f)
+            return True
+        except FileExistsError:
+            return False
+
+
+def release(path, task_id):
+    path = Path(path)
+    with guard(path):
+        if path.is_symlink():
+            return False
+        if not path.exists():
+            return True
+        try:
+            owner = json.loads(path.read_text())
+        except (OSError, ValueError):
+            return False
+        if not isinstance(owner, dict) or owner.get('pid') != os.getpid() or owner.get('task_id') != task_id:
+            return False
+        path.unlink()
+        return True

package/src/media_agent/runtime/publish_control.py

@@ -0,0 +1,98 @@
+"""Task-bound signals: confirmation never starts a new browser or guesses a task."""
+import json
+import os
+from pathlib import Path
+import tempfile
+from .locking import guard, process_alive
+
+
+def click_publish_once(page):
+    button = page.get_by_role('button', name='发布', exact=True)
+    if button.count() != 1 or not button.is_visible() or not button.is_enabled():
+        return False
+    # Playwright additionally verifies actionability/occlusion. If this raises,
+    # the caller records an indeterminate result and must not retry the click.
+    button.click(timeout=5000)
+    return True
+
+
+def send_confirmation(lock_file, signal_file, entries, profile_id, task_id):
+    if not task_id:
+        raise ValueError('TASK_ID_REQUIRED')
+    with guard(lock_file):
+        try:
+            owner = json.loads(Path(lock_file).read_text())
+        except (OSError, ValueError):
+            raise ValueError('PREPARED_PROCESS_REQUIRED')
+        if not isinstance(owner, dict):
+            raise ValueError('PREPARED_PROCESS_REQUIRED')
+        if (owner.get('task_id') != task_id or owner.get('phase') != 'publish'
+                or not isinstance(owner.get('pid'), int) or owner['pid'] <= 1
+                or not process_alive(owner['pid'])):
+            raise ValueError('PREPARED_PROCESS_REQUIRED')
+        matching = [e for e in entries if e.get('profile_id') == profile_id and e.get('task_id') == task_id]
+        if not matching or matching[-1].get('state') != 'prepared' or not matching[-1].get('sha256'):
+            raise ValueError('MATCHING_PREPARED_TASK_REQUIRED')
+        signal_file = Path(signal_file)
+        signal_file.parent.mkdir(parents=True, exist_ok=True)
+        if signal_file.exists():
+            raise ValueError('CONFIRMATION_ALREADY_PENDING')
+        # Link a complete file atomically, without replacing an existing signal.
+        fd, temp = tempfile.mkstemp(prefix='.confirm-', dir=signal_file.parent)
+        try:
+            with os.fdopen(fd, 'w') as f:
+                json.dump({'action': 'confirm', 'task_id': task_id,
+                           'profile_id': profile_id, 'sha256': matching[-1].get('sha256'),
+                           'pid': owner['pid']}, f)
+            try:
+                os.link(temp, signal_file)
+            except FileExistsError:
+                raise ValueError('CONFIRMATION_ALREADY_PENDING')
+        finally:
+            os.unlink(temp)
+
+
+def consume_confirmation(signal_file, profile_id, task_id, sha256):
+    try:
+        p = Path(signal_file)
+        data = json.loads(p.read_text())
+        p.unlink()
+        return (data.get('action') == 'confirm' and data.get('profile_id') == profile_id
+                and data.get('task_id') == task_id and data.get('sha256') == sha256
+                and data.get('pid') == os.getpid())
+    except (OSError, ValueError, AttributeError):
+        return False
+
+
+def consume_close(signal_file, task_id):
+    p = Path(signal_file)
+    try:
+        data = json.loads(p.read_text())
+        return (data.get('action') == 'close' and data.get('task_id') == task_id
+                and data.get('pid') == os.getpid())
+    except (OSError, ValueError, AttributeError):
+        return False
+    finally:
+        p.unlink(missing_ok=True)
+
+
+def request_close(lock_file, signal_file):
+    with guard(lock_file):
+        try:
+            owner = json.loads(Path(lock_file).read_text())
+        except (OSError, ValueError):
+            raise ValueError('PUBLISH_PROCESS_REQUIRED')
+        if (not isinstance(owner, dict) or owner.get('phase') != 'publish'
+                or not isinstance(owner.get('pid'), int) or owner['pid'] <= 1
+                or not owner.get('task_id') or not process_alive(owner['pid'])):
+            raise ValueError('PUBLISH_PROCESS_REQUIRED')
+        destination = Path(signal_file)
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        fd, temporary = tempfile.mkstemp(prefix='.close-', dir=destination.parent)
+        try:
+            with os.fdopen(fd, 'w') as f:
+                json.dump({'action': 'close', 'task_id': owner['task_id'], 'pid': owner['pid']}, f)
+            os.replace(temporary, destination)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)

package/src/node/skills.mjs

@@ -16,6 +16,7 @@ function inventory(root) {
   const result = {};
   function visit(dir, prefix = '') {
     for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a,b)=>a.name.localeCompare(b.name))) {
+      if (e.name === '.DS_Store') continue;
       const relative = prefix + e.name, full = path.join(dir,e.name);
       if (e.isSymbolicLink()) throw new Error(`Symlink in Skill: ${full}`);
       if (e.isDirectory()) visit(full, relative + '/');
@@ -71,7 +72,7 @@ export function installSkills(root, target, selected, dryRun=false) {
     const stage=fs.mkdtempSync(path.join(path.dirname(target),'.media-agent-skill-'));
     const staged=path.join(stage,name); let backup;
     try {
-      fs.cpSync(src,staged,{recursive:true,errorOnExist:true,force:false});
+      fs.cpSync(src,staged,{recursive:true,errorOnExist:true,force:false,filter:source=>path.basename(source)!=='.DS_Store'});
       if (!equal(inventory(staged),hashes)) throw new Error(`Skill copy verification failed: ${name}`);
       fs.mkdirSync(target,{recursive:true});
       if (prior) { backup=archiveLocation(target,name,'upgrade-'); fs.renameSync(dst,backup); }

package/tools/artifacts.py

@@ -23,6 +23,7 @@ def source_payload(root):
     for name in catalog['skills']:
         for p in (root/'skills'/name).rglob('*'):
             if p.is_symlink(): raise ValueError(f'Linked source: {p}')
+            if p.name == '.DS_Store': continue
             if p.is_file():
                 if p.suffix not in ('.md','.yaml') and not p.name.startswith('LICENSE.'):
                     raise ValueError(f'Unexpected Skill resource: {p}')

package/tools/install_runtime.py

@@ -74,6 +74,11 @@ def install(target, dry_run=False, no_deps=False):
         if p.exists() and not p.is_file():
             raise ValueError(f'Expected regular file: {p}')
     reject_links(destination)
+    sys.path.insert(0, str(ROOT / 'src'))
+    from media_agent.runtime.diagnostics import upgrade_report
+    readiness = upgrade_report(target)
+    if not readiness['safe_to_upgrade']:
+        raise ValueError('Upgrade blocked: active or unfinished tasks, or unreadable state. Run media-agent upgrade --check --json; no dependencies or runtime code were changed.')
     if dry_run:
         print(f'[DRY-RUN] runtime {version} -> {destination}; dependencies={not no_deps}')
         return