@iducky/media-agent 1.1.0

package/src/media_agent/script_map.json

@@ -0,0 +1,23 @@
+{
+  "account_manager": "media_agent.runtime.account_manager",
+  "check_login": "media_agent.platforms.douyin.check_login",
+  "collect_industry_taxonomy": "media_agent.platforms.douyin.collect_industry_taxonomy",
+  "collect_video_rankings": "media_agent.platforms.douyin.collect_video_rankings",
+  "douyin_full_login": "media_agent.platforms.douyin.douyin_full_login",
+  "douyin_hotspot_v2": "media_agent.platforms.douyin.douyin_hotspot_v2",
+  "douyin_publish": "media_agent.platforms.douyin.douyin_publish",
+  "enterprise_login": "media_agent.platforms.douyin.enterprise_login",
+  "export_short_video": "media_agent.platforms.douyin.export_short_video",
+  "login_controller": "media_agent.platforms.douyin.login_controller",
+  "toutiao_check_login": "media_agent.platforms.toutiao.toutiao_check_login",
+  "toutiao_login_controller": "media_agent.platforms.toutiao.toutiao_login_controller",
+  "toutiao_login_evidence": "media_agent.platforms.toutiao.toutiao_login_evidence",
+  "toutiao_login_ipc": "media_agent.platforms.toutiao.toutiao_login_ipc",
+  "validate_industry_taxonomy": "media_agent.platforms.douyin.validate_industry_taxonomy",
+  "validate_rankings": "media_agent.platforms.douyin.validate_rankings",
+  "xiaohongshu_check_login": "media_agent.platforms.xiaohongshu.xiaohongshu_check_login",
+  "xiaohongshu_login_controller": "media_agent.platforms.xiaohongshu.xiaohongshu_login_controller",
+  "xiaohongshu_login_evidence": "media_agent.platforms.xiaohongshu.xiaohongshu_login_evidence",
+  "xiaohongshu_login_ipc": "media_agent.platforms.xiaohongshu.xiaohongshu_login_ipc",
+  "xiaohongshu_publish": "media_agent.platforms.xiaohongshu.xiaohongshu_publish"
+}

package/src/node/config.mjs

@@ -0,0 +1,48 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import {exists, rejectLinks} from './skills.mjs';
+
+// Explicit configuration allowlist; browser sessions never enter the transfer.
+export function transferConfig(home, args) {
+  const [operation, directory, ...options] = args;
+  if (!['export', 'import'].includes(operation) || !directory || directory.startsWith('--') ||
+      options.some(x => x !== '--dry-run') || options.length > 1)
+    throw new Error('Usage: media-agent config export|import DIR [--dry-run] [--home DIR]');
+  const other = path.resolve(directory.startsWith('~/') ? path.join(os.homedir(), directory.slice(2)) : directory);
+  const [source, target] = operation === 'export' ? [home, other] : [other, home];
+  rejectLinks(source); rejectLinks(target);
+  if (source === target || source.startsWith(target + path.sep) || target.startsWith(source + path.sep))
+    throw new Error('Configuration source and destination must be separate');
+  if (!fs.statSync(source).isDirectory()) throw new Error('Configuration source must be a directory');
+  const names = ['accounts.yaml', 'ranking-profiles.yaml'];
+  const profiles = path.join(source, 'profiles');
+  rejectLinks(profiles);
+  if (exists(profiles)) for (const entry of fs.readdirSync(profiles, {withFileTypes:true})) {
+    if (entry.isSymbolicLink()) throw new Error('Linked Profile is not supported');
+    if (entry.isDirectory()) names.push(`profiles/${entry.name}/config.json`);
+  }
+  const files = names.filter(name => exists(path.join(source,name)));
+  // Preflight every path before creating any destination.
+  for (const name of files) {
+    const from = path.join(source,name), to = path.join(target,name);
+    rejectLinks(from); rejectLinks(to);
+    if (!fs.statSync(from).isFile() || (exists(to) && !fs.statSync(to).isFile()))
+      throw new Error(`Expected configuration file: ${name}`);
+    for(let p=path.dirname(to); ; p=path.dirname(p)) {
+      if(exists(p) && !fs.statSync(p).isDirectory()) throw new Error(`Expected directory: ${p}`);
+      if(path.dirname(p)===p) break;
+    }
+  }
+  if (!options.includes('--dry-run')) for (const name of files) {
+    const to = path.join(target,name);
+    fs.mkdirSync(path.dirname(to), {recursive:true});
+    const stage = fs.mkdtempSync(path.join(path.dirname(to), '.config-'));
+    try {
+      fs.copyFileSync(path.join(source,name),path.join(stage,'value'));
+      fs.chmodSync(path.join(stage,'value'),0o600);
+      fs.renameSync(path.join(stage,'value'),to);
+    } finally { fs.rmSync(stage,{recursive:true,force:true}); }
+  }
+  console.log(`${options.length ? '[DRY-RUN] ' : ''}Configuration ${operation}: ${files.length} files; browser data excluded.`);
+}

package/src/node/integrity.mjs

@@ -0,0 +1,34 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export function verifyIntegrity(root) {
+  const marker=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).mediaAgentArtifact;
+  const manifest=path.join(root,'manifest.json');
+  if(!fs.existsSync(manifest) && !marker) return;
+  try {
+    if(fs.lstatSync(manifest).isSymbolicLink()) throw new Error('linked manifest');
+    const files=JSON.parse(fs.readFileSync(manifest,'utf8')).files;
+    if(!files || !Object.keys(files).length) throw new Error('empty manifest');
+    const actual=[];
+    function walk(dir,prefix='') {
+      for(const e of fs.readdirSync(dir,{withFileTypes:true})) {
+        const name=prefix+e.name, full=path.join(dir,e.name);
+        if(e.isSymbolicLink()) throw new Error(`linked file ${name}`);
+        if(e.isDirectory()) walk(full,name+'/');
+        else if(e.isFile()) actual.push(name);
+        else throw new Error(`special file ${name}`);
+      }
+    }
+    walk(root);
+    const expected=[...Object.keys(files),'manifest.json','SHA256SUMS'].sort();
+    if(JSON.stringify(actual.sort())!==JSON.stringify(expected)) throw new Error('missing or unexpected files');
+    for(const [name,record] of Object.entries(files)) {
+      if(name.startsWith('/') || name.includes('\\') || name.split('/').some(p=>p==='..'||p==='.'||!p)) throw new Error('invalid path');
+      const buffer=fs.readFileSync(path.join(root,name));
+      if(buffer.length!==record.size || crypto.createHash('sha256').update(buffer).digest('hex')!==record.sha256) throw new Error(`mismatch ${name}`);
+    }
+    const sums=Object.keys(files).sort().map(n=>`${files[n].sha256}  ${n}\n`).join('');
+    if(fs.readFileSync(path.join(root,'SHA256SUMS'),'utf8')!==sums) throw new Error('invalid SHA256SUMS');
+  } catch(error) { throw new Error(`Artifact integrity: ${error.message}`); }
+}

package/src/node/skills.mjs

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+export const exists = p => { try { fs.lstatSync(p); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } };
+export function rejectLinks(p) {
+  for (let q = path.resolve(p); ; q = path.dirname(q)) {
+    if (exists(q) && fs.lstatSync(q).isSymbolicLink()) {
+      if (!(process.platform === 'darwin' && ['/var','/tmp'].includes(q) && fs.realpathSync(q) === '/private'+q))
+        throw new Error(`Symlink path is not supported: ${q}`);
+    }
+    if (path.dirname(q) === q) break;
+  }
+}
+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))) {
+      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 + '/');
+      else if (e.isFile()) result[relative] = crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex');
+      else throw new Error(`Special file in Skill: ${full}`);
+    }
+  }
+  visit(root); return result;
+}
+function equal(a,b) { return JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort()); }
+function archiveLocation(target, name, prefix) {
+  const parent = path.join(path.dirname(target), 'retired-skills');
+  if (parent === target) throw new Error('Backup directory must be outside the Skill root');
+  rejectLinks(parent);
+  fs.mkdirSync(parent, {recursive:true});
+  return path.join(fs.mkdtempSync(path.join(parent, prefix)), name);
+}
+export function migrateSkills(catalog, target, dryRun = false) {
+  for (const rule of catalog.retired_skills) {
+    const old=path.join(target,rule.name);
+    if (!exists(old)) continue;
+    let hashes;
+    try { rejectLinks(old); hashes=inventory(old); }
+    catch { console.log(`WARNING: preserved linked or unsupported legacy Skill: ${old}`); continue; }
+    if (!equal(hashes,rule.sha256)) { console.log(`WARNING: preserved customized legacy Skill: ${old}`); continue; }
+    if (dryRun) { console.log(`[DRY-RUN] retire ${old} after installing ${rule.replacement}`); continue; }
+    const replacement=path.join(target,rule.replacement);
+    rejectLinks(replacement);
+    if (!rule.required_files.every(f=>fs.existsSync(path.join(replacement,f)))) throw new Error(`Replacement Skill is incomplete: ${rule.replacement}`);
+    const backup=archiveLocation(target,rule.name,'rankings-merge-');
+    fs.renameSync(old,backup); console.log(`RETIRED ${old} -> ${backup}`);
+  }
+}
+export function installSkills(root, target, selected, dryRun=false) {
+  const catalog=JSON.parse(fs.readFileSync(path.join(root,'resources/capabilities.json'),'utf8'));
+  const names=selected.length ? [...new Set(selected)] : catalog.skills;
+  for (const name of names) if (!catalog.skills.includes(name)) throw new Error(`Unknown Skill: ${name}`);
+  rejectLinks(target);
+  // Validate every source and destination before changing any Skill.
+  const jobs=names.map(name=> {
+    const src=path.join(root,'skills',name), dst=path.join(target,name);
+    rejectLinks(src); rejectLinks(dst);
+    if (!fs.existsSync(path.join(src,'SKILL.md'))) throw new Error(`Incomplete Skill: ${name}`);
+    const hashes=inventory(src);
+    const prior=exists(dst) ? inventory(dst) : null;
+    return {name,src,dst,hashes,prior};
+  });
+  for (const {name,src,dst,hashes,prior} of jobs) {
+    if (dryRun) { console.log(`[DRY-RUN] ${src} -> ${dst}`); continue; }
+    if (prior && equal(hashes,prior)) { console.log(`UNCHANGED ${name}`); continue; }
+    // Stage outside the discovery root; restore old directory if activation fails.
+    fs.mkdirSync(path.dirname(target),{recursive:true});
+    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});
+      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); }
+      try { fs.renameSync(staged,dst); }
+      catch (error) { if (backup) fs.renameSync(backup,dst); throw error; }
+      console.log(`INSTALL ${name}${backup ? ` (backup: ${backup})` : ''}`);
+    } finally { fs.rmSync(stage,{recursive:true,force:true}); }
+  }
+  const selectedRules={...catalog,retired_skills:catalog.retired_skills.filter(r=>names.includes(r.replacement))};
+  migrateSkills(selectedRules,target,dryRun);
+}

package/tools/archive_releases.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Move immutable historical archives to GitHub Releases after download verification."""
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import tempfile
+
+ROOT=Path(__file__).resolve().parents[1]
+REPO='myducky/MediaAgentCapabilities'
+
+
+def gh(*args):
+    executable=shutil.which('gh')
+    if executable is None:
+        fallback=Path.home()/'.local/bin/gh'
+        if fallback.is_file(): executable=str(fallback)
+    if not executable: raise RuntimeError('GitHub CLI unavailable')
+    return subprocess.run([executable,*args],capture_output=True,text=True)
+
+
+def checked(*args):
+    result=gh(*args)
+    if result.returncode: raise RuntimeError(result.stderr)
+    return result.stdout
+
+
+def sha(path): return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def migrate(apply=False):
+    archives=sorted((ROOT/'releases').glob('*.tar.gz'),key=lambda p:tuple(map(int,p.name.split('-v')[1].split('.tar')[0].split('.'))))
+    if not archives:
+        print('No local historical archives; index retained.'); return
+    records=[]
+    for archive in archives:
+        sidecar=Path(str(archive)+'.sha256')
+        declared=sidecar.read_text().split()
+        if len(declared)!=2 or declared[0]!=sha(archive) or Path(declared[1]).name!=archive.name:
+            raise ValueError(f'Historical checksum mismatch: {archive.name}')
+        # These immutable archives must be byte-for-byte copies of committed assets.
+        for p in (archive,sidecar):
+            original=subprocess.check_output(['git','show','HEAD:'+p.relative_to(ROOT).as_posix()],cwd=ROOT)
+            if original!=p.read_bytes(): raise ValueError(f'Historical asset differs from HEAD: {p}')
+        version=archive.name.split('-v')[1].removesuffix('.tar.gz')
+        commit=subprocess.check_output(['git','log','-1','--format=%H','--',archive.relative_to(ROOT).as_posix()],cwd=ROOT,text=True).strip()
+        assets=[{'name':p.name,'size':p.stat().st_size,'sha256':sha(p),'url':f'https://github.com/{REPO}/releases/download/v{version}/{p.name}'} for p in (archive,sidecar)]
+        records.append({'version':version,'tag':'v'+version,'artifact_import_commit':commit,'assets':assets})
+    if not apply:
+        print(json.dumps(records,indent=2)); return
+    for record in records:
+        tag=record['tag']; view=gh('release','view',tag,'--repo',REPO,'--json','assets,tagName,isDraft')
+        if view.returncode:
+            if 'not found' not in view.stderr.lower(): raise RuntimeError(view.stderr)
+            with tempfile.TemporaryDirectory() as tmp:
+                notes=Path(tmp)/'notes.md'
+                notes.write_text('历史不可变制品归档。文件与原仓库内的压缩包及 SHA256 边车完全一致。\n\n此标签指向历史制品在本仓库的保存提交；旧版本构建输入以压缩包内的 manifest 为准。未重新构建、未改变旧版本能力或在线验证状态。\n')
+                checked('release','create',tag,'--repo',REPO,'--target',record['artifact_import_commit'],'--title',tag+' 历史制品','--notes-file',str(notes),'--latest=false',*[str(ROOT/'releases'/a['name']) for a in record['assets']])
+        else:
+            info=json.loads(view.stdout)
+            if info.get('isDraft'): raise ValueError(f'Existing release is a draft: {tag}')
+            present={a['name'] for a in info['assets']}
+            missing=[a for a in record['assets'] if a['name'] not in present]
+            if missing: checked('release','upload',tag,'--repo',REPO,*[str(ROOT/'releases'/a['name']) for a in missing])
+        with tempfile.TemporaryDirectory() as tmp:
+            for asset in record['assets']:
+                checked('release','download',tag,'--repo',REPO,'--pattern',asset['name'],'--dir',tmp)
+                downloaded=Path(tmp)/asset['name']
+                if downloaded.stat().st_size!=asset['size'] or sha(downloaded)!=asset['sha256']:
+                    raise ValueError(f'Remote archive mismatch: {tag}/{asset["name"]}')
+        print(f'VERIFIED {tag}: {len(record["assets"])} assets',flush=True)
+    # No deletion until every version has been downloaded and verified.
+    index=ROOT/'docs/releases/index.json'
+    index.write_text(json.dumps({'schema':1,'repository':REPO,'releases':records},ensure_ascii=False,indent=2)+'\n')
+    for record in records:
+        for asset in record['assets']: (ROOT/'releases'/asset['name']).unlink()
+    print('Historical archives moved; docs/releases/index.json retained.')
+
+if __name__=='__main__':
+    parser=argparse.ArgumentParser(description=__doc__); parser.add_argument('--migrate',action='store_true')
+    args=parser.parse_args(); migrate(args.migrate)

package/tools/artifacts.py

@@ -0,0 +1,56 @@
+"""Shared release file inventory and installation integrity verification."""
+import hashlib
+import json
+from pathlib import Path, PurePosixPath
+
+FILES=('README.md','package.json','pyproject.toml')
+DIRECTORIES={'bin':{'.mjs'},'src':{'.py','.json','.sh','.mjs'},'tools':{'.py'},'resources':{'.yaml','.json'},'docs/guides':{'.md'}}
+
+
+
+def source_payload(root):
+    files=[]
+    for name in FILES:
+        p=root/name
+        if not p.is_file() or p.is_symlink(): raise ValueError(f'Missing or linked source: {name}')
+        files.append(p)
+    for folder,suffixes in DIRECTORIES.items():
+        for p in (root/folder).rglob('*'):
+            if p.is_symlink(): raise ValueError(f'Linked source: {p}')
+            if '__pycache__' in p.parts: continue
+            if p.is_file() and p.suffix in suffixes: files.append(p)
+    catalog=json.loads((root/'resources/capabilities.json').read_text())
+    for name in catalog['skills']:
+        for p in (root/'skills'/name).rglob('*'):
+            if p.is_symlink(): raise ValueError(f'Linked source: {p}')
+            if p.is_file():
+                if p.suffix not in ('.md','.yaml') and not p.name.startswith('LICENSE.'):
+                    raise ValueError(f'Unexpected Skill resource: {p}')
+                files.append(p)
+    return sorted(set(files))
+
+
+def file_record(p):
+    return {'size':p.stat().st_size,'sha256':hashlib.sha256(p.read_bytes()).hexdigest()}
+
+
+def verify_integrity(root):
+    marker=json.loads((root/'package.json').read_text()).get('mediaAgentArtifact',False)
+    manifest=root/'manifest.json'
+    if not manifest.exists() and not marker: return  # editable source checkout
+    if not manifest.is_file() or manifest.is_symlink(): raise ValueError('Artifact integrity: manifest missing or linked')
+    data=json.loads(manifest.read_text()); entries=data.get('files',{})
+    if not entries: raise ValueError('Artifact integrity: empty manifest')
+    for name,expected in entries.items():
+        parts=PurePosixPath(name)
+        if parts.is_absolute() or '..' in parts.parts or '\\' in name or name!=parts.as_posix():
+            raise ValueError('Artifact integrity: invalid path')
+        p=root/name
+        if not p.is_file() or p.is_symlink() or file_record(p)!=expected: raise ValueError(f'Artifact integrity: mismatch {name}')
+    actual=set()
+    for p in root.rglob('*'):
+        if p.is_symlink(): raise ValueError(f'Artifact integrity: linked file {p}')
+        if p.is_file(): actual.add(p.relative_to(root).as_posix())
+    if actual != set(entries)|{'manifest.json','SHA256SUMS'}: raise ValueError('Artifact integrity: missing or unexpected files')
+    sums=''.join(f"{entries[n]['sha256']}  {n}\n" for n in sorted(entries))
+    if (root/'SHA256SUMS').read_text()!=sums: raise ValueError('Artifact integrity: invalid SHA256SUMS')

package/tools/build_release.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""Build npm and optional offline artifacts exclusively from current source."""
+import argparse
+import gzip
+import hashlib
+import io
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+sys.dont_write_bytecode=True
+from artifacts import source_payload, file_record, verify_integrity
+from check_catalog import check
+
+ROOT=Path(__file__).resolve().parents[1]
+
+
+def build(output, npm=True):
+    check(ROOT)
+    files=source_payload(ROOT)
+    version=json.loads((ROOT/'package.json').read_text())['version']
+    name='media-agent-capabilities-v'+version
+    output=output.expanduser().resolve()
+    if output == ROOT or ROOT.is_relative_to(output): raise ValueError('Output must not contain the source tree')
+    output.mkdir(parents=True,exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix='.build-',dir=output) as tmp:
+        stage=Path(tmp)/name; stage.mkdir()
+        for src in files:
+            dest=stage/src.relative_to(ROOT); dest.parent.mkdir(parents=True,exist_ok=True); shutil.copy2(src,dest)
+        package=json.loads((stage/'package.json').read_text()); package['mediaAgentArtifact']=True
+        (stage/'package.json').write_text(json.dumps(package,ensure_ascii=False,indent=2)+'\n')
+        entries={p.relative_to(stage).as_posix():file_record(p) for p in sorted(stage.rglob('*')) if p.is_file()}
+        (stage/'manifest.json').write_text(json.dumps({'schema':1,'version':version,'files':entries},ensure_ascii=False,indent=2)+'\n')
+        (stage/'SHA256SUMS').write_text(''.join(f"{entries[n]['sha256']}  {n}\n" for n in sorted(entries)))
+        verify_integrity(stage)
+        archive=output/(name+'.tar.gz')
+        buffer=io.BytesIO()
+        with gzip.GzipFile(fileobj=buffer,mode='wb',filename='',mtime=0) as gz:
+            with tarfile.open(fileobj=gz,mode='w') as tar:
+                for p in sorted(stage.rglob('*')):
+                    if not p.is_file(): continue
+                    info=tar.gettarinfo(str(p),arcname=name+'/'+p.relative_to(stage).as_posix())
+                    info.uid=info.gid=0; info.uname=info.gname=''; info.mtime=0
+                    info.mode=0o755 if p.suffix in ('.sh','.mjs') else 0o644
+                    with p.open('rb') as f: tar.addfile(info,f)
+        candidates={archive.name:buffer.getvalue()}
+        if npm:
+            subprocess.run(['npm','pack','--ignore-scripts','--pack-destination',tmp,'--cache',str(Path(tmp)/'npm-cache')],cwd=stage,check=True,stdout=subprocess.DEVNULL,stderr=subprocess.PIPE)
+            npm_file=next(Path(tmp).glob('*.tgz')); candidates[npm_file.name]=npm_file.read_bytes()
+            # Verify what npm actually included, rather than trusting the files field.
+            unpack=Path(tmp)/'npm-check'; unpack.mkdir()
+            with tarfile.open(npm_file) as tar:
+                for member in tar.getmembers():
+                    parts=Path(member.name).parts
+                    if member.issym() or member.islnk() or member.name.startswith('/') or '..' in parts: raise ValueError('Unsafe npm archive member')
+                tar.extractall(unpack)
+            verify_integrity(unpack/'package')
+        for filename,content in candidates.items():
+            dest=output/filename
+            if dest.exists() and dest.read_bytes()!=content: raise ValueError(f'Refusing to overwrite a different artifact: {dest}; use a fresh output directory')
+        for filename,content in candidates.items():
+            dest=output/filename; dest.write_bytes(content)
+            checksum=hashlib.sha256(content).hexdigest()
+            Path(str(dest)+'.sha256').write_text(f'{checksum}  {filename}\n')
+            print(f'{checksum}  {dest}')
+
+
+def main():
+    parser=argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--output',type=Path,default=ROOT/'dist')
+    parser.add_argument('--no-npm',action='store_true')
+    args=parser.parse_args()
+    try: build(args.output,not args.no_npm)
+    except (OSError,ValueError,subprocess.CalledProcessError) as e:
+        print(f'ERROR: {e}',file=sys.stderr); return 1
+    return 0
+
+if __name__=='__main__': raise SystemExit(main())

package/tools/check_catalog.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python3
+"""Check the one capability catalog and synchronized distribution metadata."""
+import json
+from pathlib import Path
+import re
+
+ROOT=Path(__file__).resolve().parents[1]
+
+def check(root=ROOT):
+    catalog=json.loads((root/'resources/capabilities.json').read_text())
+    names=catalog['skills']
+    actual=sorted(p.name for p in (root/'skills').iterdir() if (p/'SKILL.md').is_file())
+    if sorted(names)!=actual or len(names)!=len(set(names)): raise ValueError('Skill catalog differs from source directories')
+    for name in names:
+        if not re.fullmatch(r'[a-z0-9-]+',name): raise ValueError('Invalid Skill name')
+        text=(root/'skills'/name/'SKILL.md').read_text()
+        if not re.search(r'^name:\s*'+re.escape(name)+r'\s*$',text,re.M): raise ValueError(f'Skill metadata mismatch: {name}')
+    package=json.loads((root/'package.json').read_text())
+    match=re.search(r'^version\s*=\s*"([^"]+)"',(root/'pyproject.toml').read_text(),re.M)
+    if not match or match.group(1)!=package['version']: raise ValueError('Python/npm version mismatch')
+    print(f"Catalog OK: {len(names)} Skills; version {package['version']}")
+
+if __name__=='__main__': check()

package/tools/install_runtime.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Install versioned Python code without moving or replacing account profiles."""
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+sys.dont_write_bytecode = True
+from artifacts import source_payload, verify_integrity
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def reject_links(path):
+    for part in (path, *path.parents):
+        if part.is_symlink():
+            # macOS exposes its normal temporary directory through /var -> /private/var.
+            if sys.platform == 'darwin' and str(part) in ('/var', '/tmp') and str(part.resolve()) == '/private' + str(part):
+                continue
+            raise ValueError(f'Symlink installation path is not supported: {part}')
+
+
+def source_files(root):
+    files = source_payload(root)
+    for name in ('manifest.json', 'SHA256SUMS'):
+        if (root / name).exists():
+            files.append(root / name)
+    return files
+
+
+def digest(files, root):
+    h = hashlib.sha256()
+    for p in sorted(files):
+        h.update(p.relative_to(root).as_posix().encode())
+        h.update(b'\0')
+        h.update(p.read_bytes())
+    return h.hexdigest()
+
+
+def install(target, dry_run=False, no_deps=False):
+    verify_integrity(ROOT)
+    target = Path(os.path.abspath(target.expanduser()))
+    reject_links(target)
+    real_target = target.resolve()
+    if real_target == ROOT or ROOT in real_target.parents or real_target in ROOT.parents:
+        raise ValueError('Runtime home must be separate from the source/package directory')
+    files = source_files(ROOT)
+    version = json.loads((ROOT / 'package.json').read_text())['version']
+    code_id = version + '-' + digest(files, ROOT)[:16]
+    app = target / '.app'
+    releases = app / 'releases'
+    destination = releases / code_id
+    for p in (app, releases, target / '.venv', target / 'configs'):
+        reject_links(p)
+        if p.exists() and not p.is_dir():
+            raise ValueError(f'Expected directory: {p}')
+    current = app / 'current'
+    if current.exists() and not current.is_symlink():
+        raise ValueError(f'Refusing non-symlink activation path: {current}')
+    templates = {
+        'resources/configs/accounts.yaml': 'accounts.yaml',
+        'resources/configs/ranking-profiles.yaml': 'ranking-profiles.yaml',
+        'resources/data/industry-taxonomy.yaml': 'industry-taxonomy.yaml',
+    }
+    templates.update({p.relative_to(ROOT).as_posix(): 'configs/' + p.name for p in (ROOT / 'resources/configs').glob('*.json')})
+    destinations = [target / dst for dst in templates.values()]
+    for p in destinations:
+        reject_links(p)
+        if p.exists() and not p.is_file():
+            raise ValueError(f'Expected regular file: {p}')
+    reject_links(destination)
+    if dry_run:
+        print(f'[DRY-RUN] runtime {version} -> {destination}; dependencies={not no_deps}')
+        return
+    if sys.version_info < (3, 9):
+        raise ValueError('Python >=3.9 required')
+    target.mkdir(parents=True, exist_ok=True)
+    python = target / '.venv/bin/python'
+    if not no_deps:
+        if not python.is_file():
+            if (target / '.venv').exists():
+                raise ValueError('Incomplete .venv; repair it or select a new runtime home')
+            subprocess.run([sys.executable, '-m', 'venv', str(target / '.venv')], check=True)
+        # pip may generate build metadata; build from a disposable copy so the
+        # verified npm artifact and deployed code remain immutable.
+        with tempfile.TemporaryDirectory(prefix='media-agent-python-') as temp:
+            build = Path(temp)
+            shutil.copy2(ROOT / 'pyproject.toml', build / 'pyproject.toml')
+            shutil.copytree(ROOT / 'src/media_agent', build / 'src/media_agent')
+            subprocess.run([str(python), '-m', 'pip', 'install', str(build) + '[browser]'], check=True)
+    releases.mkdir(parents=True, exist_ok=True)
+    if not destination.exists():
+        stage = Path(tempfile.mkdtemp(prefix='.stage-', dir=releases))
+        try:
+            for source in files:
+                out = stage / source.relative_to(ROOT)
+                out.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source, out)
+            if digest(source_files(stage), stage) != digest(files, ROOT):
+                raise ValueError('Runtime copy mismatch')
+            stage.rename(destination)
+        finally:
+            if stage.exists():
+                shutil.rmtree(stage)
+    elif digest(source_files(destination), destination) != digest(files, ROOT):
+        raise ValueError('Existing runtime code was modified; refusing replacement')
+    for src, dst in templates.items():
+        out = target / dst
+        if not out.exists():
+            out.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(ROOT / src, out)
+    link = app / ('.current-' + uuid.uuid4().hex)
+    try:
+        link.symlink_to(Path('releases') / code_id, target_is_directory=True)
+        os.replace(link, current)
+    finally:
+        if link.is_symlink():
+            link.unlink()
+    if (target / 'social.sh').exists() or (target / 'scripts').exists():
+        print('NOTICE: Old runtime entries were left untouched. Upgrade installed Skills together with the media-agent CLI; old entries are no longer maintained.')
+    print(f'Installed runtime {version}: {target}\nCode: {destination}\nProfiles and existing configuration preserved.')
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--target', type=Path, default=Path(os.environ.get('MEDIA_AGENT_HOME', str(Path.home() / '.media-agent/social-accounts'))))
+    parser.add_argument('--dry-run', action='store_true')
+    parser.add_argument('--no-deps', action='store_true', help='Copy code only; dependency provisioning is managed separately')
+    args = parser.parse_args()
+    try:
+        install(args.target, args.dry_run, args.no_deps)
+    except (OSError, ValueError, RuntimeError, subprocess.CalledProcessError) as exc:
+        print(f'ERROR: {exc}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

package/tools/run_tests.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Run every isolated offline test file, including the legacy script suites."""
+import os
+from pathlib import Path
+import subprocess
+import sys
+
+ROOT=Path(__file__).resolve().parents[1]
+
+def main():
+    failed=[]
+    env=dict(os.environ,PYTHONDONTWRITEBYTECODE='1')
+    # Tests choose their own temporary account roots; caller state must not leak in.
+    env.pop('MEDIA_AGENT_HOME',None)
+    for test in sorted((ROOT/'tests').glob('test_*.py')):
+        print(f'\n{test.name}',flush=True)
+        if subprocess.run([sys.executable,str(test)],cwd=ROOT,env=env).returncode: failed.append(test.name)
+    print(f'\nTest files: {len(list((ROOT/"tests").glob("test_*.py")))}; failed: {failed}',flush=True)
+    return bool(failed)
+
+if __name__=='__main__': raise SystemExit(main())