@petercjl/seedaudiocli 0.0.0-stage → 0.1.2

package/README.md

@@ -1,3 +1,70 @@
-# Temporary Holding Version
+# @petercjl/seedaudiocli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+EvoLink Seed Audio CLI with a portable companion Skill. Requires Node.js 22+ and Python 3.9+ with SSL; no Python third-party packages are needed.
+
+## Install and configure
+
+```bash
+npm install -g @petercjl/seedaudiocli
+seedaudiocli setup
+```
+
+On first use, provide the path to the configuration file supplied by your administrator. For an Agent or noninteractive terminal:
+
+```bash
+seedaudiocli config import "/path/to/seedaudio-config.json"
+seedaudiocli auth status
+seedaudiocli doctor --json
+```
+
+Copy `seedaudiocli.config.example.json`, fill `SEEDAUDIO_API_KEY`, and deliver the file privately to the authorized recipient. A `.env` file using the same field names is also accepted. The CLI parses data; it does not execute configuration as a script. The package includes only blank examples. Each recipient with the file can use the key. Per-user service keys allow independent revocation and limits.
+
+Credentials persist outside the npm installation:
+
+- macOS/Linux: `~/.config/seedaudiocli/seedaudiocli.env`
+- Windows: `%APPDATA%/seedaudiocli/seedaudiocli.env`
+- Explicit override: `SEEDAUDIO_CONFIG_DIR`
+
+macOS/Linux files use mode 0600. Windows relies on the user's profile directory ACL; administrators should keep that directory private. Import validates local structure and does not make a paid API call. `auth status` reports local availability, not remote key validity. Environment variables override saved configuration. Network errors do not clear credentials.
+
+An existing configuration requires `--replace`; replacement creates a recoverable sibling backup before atomic write. Backups contain credentials too. Keep them private. Package uninstall/reinstall preserves configuration and task history. Existing env configurations remain supported. Legacy `config init --import-key-file FILE` remains available for older note-format files; new distribution uses `config import`.
+
+## Generate and recover
+
+```bash
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --dry-run
+seedaudiocli generate text --prompt "Generate five seconds of instrumental piano." --wait --download ./audio
+seedaudiocli task wait TASK_ID --download ./audio
+```
+
+Actual generation can incur provider charges. Save the returned task ID and recover it instead of submitting again. Unknown submission outcomes require provider/history inspection. Reference modes and parameter limits are documented by `generate --help` and the bundled Skill.
+
+## Agent installation
+
+```bash
+seedaudiocli skill source --json
+seedaudiocli skill install --agent codex
+seedaudiocli skill status --agent codex --json
+seedaudiocli skill install --agent sealseek --root "/actual/skills-directory"
+```
+
+SealSeek's discovery directory is explicit (`--root` or `SEALSEEK_SKILLS_DIR`). Unknown Agents and unmanaged targets are refused. Managed copies have ownership/hash records; updates back up prior contents, preserve customized UI metadata and refuse local edits. In-place synchronization supports directory handles held open by an Agent. Failed synchronization reports the recovery backup.
+
+## Update and rollback
+
+```bash
+npm install -g @petercjl/seedaudiocli@latest
+seedaudiocli skill update --agent codex
+```
+
+Global installs check and install stable latest before every run and synchronize previously registered managed Skills. Use `update check` to inspect availability and `update install` to apply it immediately. For a deliberate rollback, set `SEEDAUDIO_AUTO_UPDATE=0`, install the prior exact npm version and synchronize Skills. Configuration and history remain unchanged.
+
+Python discovery checks an explicit `SEEDAUDIO_PYTHON`, configured Agent runtime directories and platform commands. `SEEDAUDIO_RUNTIME_ROOT` can point to a managed runtime root. A missing or broken runtime produces `PYTHON_REQUIRED` with installation guidance.
+
+## Development and evidence
+
+Run `npm test` for isolated CLI, configuration and lifecycle tests, and `npm pack --dry-run` to inspect published contents. Tests use synthetic keys and do not submit paid jobs. GitHub QA covers macOS, Windows and Linux package entry points. Host Skill discovery and paid audio output require separate runtime evidence; adapter status remains `implemented` until those checks are recorded. Publishing uses the committed GitHub Actions OIDC workflow after QA. Public distribution does not include credentials.
+
+## Automatic updates
+
+Global npm installs check stable latest before every command, install newer releases and sync managed Skills before running the requested command once. No TTL cache is used. Offline checks keep the installed version; updates back up the package for rollback. Configuration and task history remain outside the package. Use `seedaudiocli update check` or `seedaudiocli update install`. For a deliberately pinned run set `SEEDAUDIO_AUTO_UPDATE=0`. Development checkouts are Git-managed; taobao-ai-ops owns suite component updates.

package/adapters/codex.json

@@ -0,0 +1,6 @@
+{
+  "agent": "codex",
+  "skill": "skills/seedaudiocli",
+  "status": "implemented",
+  "installation": "seedaudiocli skill install --agent codex"
+}

package/adapters/sealseek.json

@@ -0,0 +1,6 @@
+{
+  "agent": "sealseek",
+  "skill": "skills/seedaudiocli",
+  "status": "implemented",
+  "installation": "seedaudiocli skill install --agent sealseek --root SKILLS_DIRECTORY"
+}

package/capabilities.json

@@ -0,0 +1,73 @@
+{
+  "schema_version": "1.0.0",
+  "package": "@petercjl/seedaudiocli",
+  "runtime": {
+    "node": ">=22",
+    "python": ">=3.9",
+    "python_override": "SEEDAUDIO_PYTHON"
+  },
+  "commands": [
+    "version",
+    "capabilities",
+    "doctor",
+    "setup",
+    "config import",
+    "auth status",
+    "models list",
+    "generate text",
+    "generate audio-ref",
+    "generate image-ref",
+    "task get",
+    "task wait",
+    "task url",
+    "task jobs",
+    "payload validate",
+    "payload submit",
+    "skill source",
+    "skill status",
+    "skill install",
+    "skill update",
+    "update check",
+    "update install"
+  ],
+  "config": {
+    "format": [
+      "json",
+      "env"
+    ],
+    "fields": [
+      "SEEDAUDIO_API_KEY",
+      "SEEDAUDIO_BASE_URL",
+      "SEEDAUDIO_MODEL",
+      "SEEDAUDIO_DEFAULT_FORMAT",
+      "SEEDAUDIO_DEFAULT_SAMPLE_RATE"
+    ],
+    "precedence": [
+      "environment",
+      "saved config",
+      "defaults"
+    ],
+    "import": "seedaudiocli config import FILE [--replace]",
+    "side_effects": "Local file write, backup on replacement; no remote call",
+    "missing": "CONFIG_REQUIRED",
+    "secrets_in_output": false
+  },
+  "update": {
+    "trigger": "before-every-run",
+    "channel": "latest",
+    "automatic_install": true,
+    "configuration": "Outside package; preserved",
+    "offline": "keep-current",
+    "source_checkout": "git-managed",
+    "suite_install": "suite-managed",
+    "opt_out": "SEEDAUDIO_AUTO_UPDATE=0",
+    "managed_skills": "synchronized with backups; edited content preserved"
+  },
+  "generation": {
+    "provider": "EvoLink",
+    "model": "doubao-seed-audio-1-0",
+    "paid": true,
+    "submit_retry": false,
+    "recovery": "Use saved task ID; unknown submit outcome requires inspection before resubmission"
+  }
+}

package/npm/cli.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { beforeRun, checkUpdate, installUpdate } from './update.mjs';
+import path from 'node:path';
+import { root, pkg, fail, findPython, runPython } from './runtime.mjs';
+import { source, targetPath, status, install } from './skills.mjs';
+
+const args = process.argv.slice(2);
+const print = value => console.log(JSON.stringify(value, null, 2));
+const flag = name => { const i = args.indexOf(name); return i < 0 ? undefined : args[i + 1]; };
+try {
+  if (await beforeRun(args)) { /* child completed */ }
+  else if (['version', '--version'].includes(args[0])) console.log(`seedaudiocli ${pkg.version}`);
+  else if (args[0] === 'capabilities') print(JSON.parse(fs.readFileSync(path.join(root, 'capabilities.json'), 'utf8')));
+  else if (args[0] === 'doctor') {
+    const python = findPython();
+    const auth = runPython(['auth', 'status'], { encoding: 'utf8', stdio: 'pipe' });
+    let config;
+    try { config = JSON.parse(auth.stdout); } catch { throw fail('RUNTIME_FAILED', 'Python CLI did not return JSON.'); }
+    print({ ok: auth.status === 0, version: pkg.version, python, skill_source: source, config });
+    process.exitCode = auth.status === 0 ? 0 : 1;
+  } else if (args[0] === 'skill') {
+    if (args[1] === 'source') print({ ok: true, source, version: pkg.version });
+    else {
+      const target = targetPath(flag('--agent') || 'codex', flag('--root'));
+      if (args[1] === 'status') print({ ok: true, ...status(target), record: undefined });
+      else if (['install', 'update'].includes(args[1])) print(install(target));
+      else throw fail('INVALID_COMMAND', 'Use skill source|status|install|update.');
+    }
+  } else if (args[0] === 'update') {
+    const check = await checkUpdate();
+    if (args[1] === 'install' && check.updateAvailable) print(installUpdate(check));
+    else print({ ...check, policy: 'before-every-run', opt_out: 'SEEDAUDIO_AUTO_UPDATE=0' });
+  } else if (!args.length || ['--help', '-h'].includes(args[0])) {
+    console.log('seedaudiocli: setup | config import FILE [--replace] | auth status | generate | task | payload\nPackage: version | capabilities --json | doctor --json | skill source/status/install/update [--agent codex|sealseek] [--root SKILLS_DIRECTORY] | update check/install\nRuntime: Node.js 22+, Python 3.9+ (SEEDAUDIO_PYTHON optional).');
+    process.exitCode = runPython(['--help']).status || 0;
+  } else {
+    const result = runPython(args);
+    process.exitCode = result.status ?? 1;
+  }
+} catch (e) {
+  print({ ok: false, code: e.code || 'LOCAL_OPERATION_FAILED', error: e.code ? e.message : 'Local operation failed.' });
+  process.exitCode = 1;
+}

package/npm/runtime.mjs

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+export const fail = (code, message) => Object.assign(new Error(message), { code });
+export function pythonCandidates(env = process.env) {
+  if (env.SEEDAUDIO_PYTHON) return [[env.SEEDAUDIO_PYTHON]];
+  const result = [];
+  // Discover bundled Agent runtimes within declared runtime directories, never through credentials.
+  const bases = [env.CODEX_HOME || path.join(os.homedir(), '.codex'), env.SEALSEEK_HOME, env.SEEDAUDIO_RUNTIME_ROOT].filter(Boolean);
+  function visit(dir, depth) {
+    if (depth < 0) return;
+    for (const item of fs.readdirSync(dir, { withFileTypes: true, throwIfNoEntry: false }) || []) {
+      const file = path.join(dir, item.name);
+      if ((item.isFile() || item.isSymbolicLink()) && /^(python3?(\.exe)?)$/.test(item.name)) result.push([file]);
+      else if (item.isDirectory()) visit(file, depth - 1);
+    }
+  }
+  for (const base of bases) {
+    for (const sub of ['runtimes', 'runtime', 'dependencies', 'python']) {
+      try { visit(path.join(base, sub), 4); } catch { /* missing/inaccessible candidate */ }
+    }
+  }
+  if (process.platform === 'win32') result.push(['py', '-3'], ['python'], ['python3']);
+  else result.push(['python3'], ['python'], ['/opt/homebrew/bin/python3'], ['/usr/local/bin/python3']);
+  return result;
+}
+export function findPython(env = process.env) {
+  for (const command of pythonCandidates(env)) {
+    const probe = spawnSync(command[0], [...command.slice(1), '-c', 'import sys,json,ssl,urllib.request,pathlib; assert sys.version_info >= (3,9); print(json.dumps({"executable":sys.executable,"version":sys.version.split()[0]}))'], { encoding: 'utf8', timeout: 5000, env, windowsHide: true });
+    if (probe.status === 0) {
+      try { return { command, ...JSON.parse(probe.stdout.trim()) }; } catch { /* invalid runtime */ }
+    }
+  }
+  throw fail('PYTHON_REQUIRED', 'Install Python 3.9+ with SSL support, or set SEEDAUDIO_PYTHON to its executable. Then run seedaudiocli doctor --json.');
+}
+export function runPython(args, options = {}) {
+  const env = { ...process.env, ...options.env, PYTHONUTF8: '1', PYTHONIOENCODING: 'utf-8' };
+  const runtime = findPython(env);
+  // Resolve only the bundled implementation; user PYTHONPATH cannot shadow it.
+  const boot = 'import sys; sys.path.insert(0,sys.argv.pop(1)); from seedaudiocli.cli import main; sys.exit(main())';
+  return spawnSync(runtime.command[0], [...runtime.command.slice(1), '-c', boot, root, ...args], { stdio: 'inherit', windowsHide: true, ...options, env });
+}

package/npm/skills.mjs

@@ -0,0 +1,88 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { stateRoot } from './update.mjs';
+import { root, pkg, fail } from './runtime.mjs';
+
+export const source = path.join(root, 'skills', 'seedaudiocli');
+const marker = '.seedaudiocli-managed.json';
+const metadata = 'agents/openai.yaml';
+function exists(file) { try { return fs.lstatSync(file); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
+export function inventory(dir) {
+  const result = {};
+  function walk(at, prefix = '') {
+    for (const entry of fs.readdirSync(at, { withFileTypes: true })) {
+      if (entry.name === marker) continue;
+      const relative = prefix + entry.name;
+      if (entry.isSymbolicLink()) throw fail('SKILL_UNSAFE_TARGET', 'Skill files must not contain symlinks.');
+      if (entry.isDirectory()) walk(path.join(at, entry.name), relative + '/');
+      else result[relative] = crypto.createHash('sha256').update(fs.readFileSync(path.join(at, entry.name))).digest('hex');
+    }
+  }
+  walk(dir);
+  return result;
+}
+export function targetPath(agent, targetRoot) {
+  if (!['codex', 'sealseek'].includes(agent)) throw fail('INVALID_AGENT', 'Choose --agent codex or sealseek.');
+  let base = targetRoot;
+  if (!base && agent === 'codex') base = path.join(process.env.CODEX_HOME || path.join(os.homedir(), '.codex'), 'skills');
+  if (!base && agent === 'sealseek') base = process.env.SEALSEEK_SKILLS_DIR;
+  if (!base) throw fail('AGENT_PATH_REQUIRED', 'Provide the actual SealSeek skills directory through --root or SEALSEEK_SKILLS_DIR.');
+  return path.join(path.resolve(base), 'seedaudiocli');
+}
+export function status(target) {
+  const st = exists(target);
+  if (!st) return { installed: false, managed: false, current: false, target };
+  if (st.isSymbolicLink() || !st.isDirectory()) return { installed: true, managed: false, current: false, target };
+  let record;
+  try { record = JSON.parse(fs.readFileSync(path.join(target, marker), 'utf8')); } catch { return { installed: true, managed: false, current: false, target }; }
+  if (record.package !== pkg.name || !record.files || typeof record.files !== 'object') return { installed: true, managed: false, current: false, target };
+  if (Object.keys(record.files).some(file => !file || path.isAbsolute(file) || file.includes('\\') || file.split('/').some(part => ['.', '..', ''].includes(part)))) throw fail('SKILL_UNSAFE_TARGET', 'Invalid managed-file path in Skill ownership record.');
+  const files = inventory(target);
+  const edited = Object.entries(record.files).some(([file, hash]) => file !== metadata && files[file] !== hash);
+  const expected = inventory(source);
+  const current = !edited && Object.entries(expected).every(([file, hash]) => file === metadata || files[file] === hash);
+  return { installed: true, managed: true, current, edited, target, version: record.version, record };
+}
+export function install(target) {
+  const state = status(target);
+  const registry = path.join(stateRoot(), 'skill-targets');
+  fs.mkdirSync(registry, { recursive: true });
+  const registration = path.join(registry, crypto.createHash('sha256').update(target).digest('hex') + '.json');
+  if (!exists(registration)) fs.writeFileSync(registration, JSON.stringify({ target }), { flag: 'wx', mode: 0o600 });
+  if (state.installed && !state.managed) throw fail('SKILL_UNMANAGED', 'An existing user-owned Skill occupies this target; preserve it and choose a new root or explicitly migrate it.');
+  if (state.edited) throw fail('SKILL_EDITED', 'Managed Skill files contain local edits; preserve and reconcile those edits before updating.');
+  if (state.current && state.version === pkg.version) return { ...state, record: undefined, ok: true, changed: false };
+  const expected = inventory(source);
+  for (const file of Object.keys(expected)) {
+    if (state.installed && exists(path.join(target, file)) && !(file in state.record.files) && file !== metadata) throw fail('SKILL_UNMANAGED_FILE', 'A new bundled file would overwrite a user-owned file.');
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  const lock = target + '.install-lock';
+  let lockfd;
+  try { lockfd = fs.openSync(lock, 'wx', 0o600); } catch (e) { if (e.code === 'EEXIST') throw fail('SKILL_BUSY', 'Another Skill installation holds the lock.'); throw e; }
+  let backup;
+  try {
+    if (state.installed) {
+      backup = path.join(stateRoot(), 'skill-backups', crypto.randomUUID());
+      fs.mkdirSync(path.dirname(backup), { recursive: true });
+      fs.cpSync(target, backup, { recursive: true, errorOnExist: true, force: false });
+    } else fs.mkdirSync(target);
+    // In-place updates support hosts holding a directory handle open. Backup is recoverable.
+    for (const file of Object.keys(expected)) {
+      if (file === metadata && exists(path.join(target, file))) continue;
+      fs.mkdirSync(path.dirname(path.join(target, file)), { recursive: true });
+      fs.copyFileSync(path.join(source, file), path.join(target, file));
+    }
+    for (const file of Object.keys(state.record?.files || {})) {
+      if (file !== metadata && !(file in expected)) fs.unlinkSync(path.join(target, file));
+    }
+    const actual = inventory(target);
+    if (Object.entries(expected).some(([file, hash]) => file !== metadata && actual[file] !== hash)) throw fail('SKILL_VERIFY_FAILED', 'Installed Skill hashes differ from the package.');
+    fs.writeFileSync(path.join(target, marker), JSON.stringify({ package: pkg.name, version: pkg.version, files: expected }, null, 2));
+    return { ok: true, installed: true, managed: true, current: true, changed: true, target, version: pkg.version, backup: backup || null };
+  } catch (e) {
+    throw fail('SKILL_INSTALL_FAILED', `Skill installation failed; ${backup ? 'restore from ' + backup : 'inspect the partial target at ' + target}.`);
+  } finally { fs.closeSync(lockfd); fs.unlinkSync(lock); }
+}

package/npm/update.mjs

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { root, pkg, fail } from './runtime.mjs';
+
+export const stateRoot = () => process.env.SEEDAUDIO_STATE_DIR || (process.platform === 'win32' ? path.join(process.env.LOCALAPPDATA || os.homedir(), 'seedaudiocli') : path.join(os.homedir(), '.local', 'state', 'seedaudiocli'));
+export function newer(a, b) {
+  if (!/^\d+\.\d+\.\d+$/.test(a)) return false;
+  const x=a.split('.').map(Number), y=b.split('.').map(Number);
+  for(let i=0;i<3;i++) { if(x[i]!==y[i]) return x[i]>y[i]; }
+  return false;
+}
+export function globalPrefix(location=root, platform=process.platform) {
+  const modules=path.dirname(path.dirname(location));
+  if(path.basename(modules)!=='node_modules' || fs.existsSync(path.join(location,'.git'))) return null;
+  if(platform==='win32') return path.dirname(modules);
+  return path.basename(path.dirname(modules))==='lib' ? path.dirname(path.dirname(modules)) : null;
+}
+export async function checkUpdate(registry=fetch) {
+  try {
+    const r=await registry(`https://registry.npmjs.org/${encodeURIComponent(pkg.name)}/latest`,{signal:AbortSignal.timeout(8000)});
+    if(!r.ok) throw Error('Registry unavailable');
+    const data=await r.json();
+    if(data.name!==pkg.name || !/^\d+\.\d+\.\d+$/.test(data.version)) throw Error('Invalid stable package');
+    return {ok:true,current:pkg.version,available:data.version,updateAvailable:newer(data.version,pkg.version),tag:'latest'};
+  } catch { return {ok:false,code:'REGISTRY_UNAVAILABLE',current:pkg.version,updateAvailable:false,offline:'keep-current'}; }
+}
+function npm(args) {
+  let cli=process.env.npm_execpath;
+  if(!cli?.endsWith('npm-cli.js')) {
+    const found=spawnSync(process.platform==='win32'?'where':'which',[process.platform==='win32'?'npm.cmd':'npm'],{encoding:'utf8',timeout:10000});
+    const launcher=found.stdout?.trim().split(/\r?\n/)[0];
+    cli=launcher && (process.platform==='win32' ? path.join(path.dirname(launcher),'node_modules','npm','bin','npm-cli.js') : fs.realpathSync(launcher));
+  }
+  if(!cli || !fs.existsSync(cli)) throw fail('NPM_UNAVAILABLE','npm is required for updates.');
+  const r=spawnSync(process.execPath,[cli,...args],{encoding:'utf8',timeout:180000});
+  if(r.status!==0) throw fail('UPDATE_FAILED','npm update failed; check npm connectivity and installation permissions.');
+  return r.stdout;
+}
+export function installUpdate(check, services={}) {
+  const prefix=services.prefix || globalPrefix();
+  if(!prefix) throw fail('UPDATE_OWNER_REQUIRED','This installation is managed by its source checkout or parent package.');
+  const state=stateRoot(); fs.mkdirSync(state,{recursive:true});
+  const lock=path.join(state,'update.lock');
+  try { fs.mkdirSync(lock); } catch { throw fail('UPDATE_BUSY','Another update is running. Retry this command after it finishes.'); }
+  const run=services.npm || npm, spawn=services.spawn || spawnSync;
+  const backup=path.join(state,'package-backups',crypto.randomUUID());
+  const targets=[];
+  try {
+    // Recheck the live package under the lock; another process may have updated it.
+    const live=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8'));
+    if(!newer(check.available,live.version)) return {ok:true,changed:false,version:live.version};
+    fs.mkdirSync(backup,{recursive:true});
+    const archive=JSON.parse(run(['pack',root,'--ignore-scripts','--pack-destination',backup,'--json']))[0];
+    const registered=path.join(state,'skill-targets');
+    const known=[path.join(process.env.CODEX_HOME || path.join(os.homedir(),'.codex'),'skills','seedaudiocli')];
+    for(const f of (fs.existsSync(registered) ? fs.readdirSync(registered) : [])) {
+      try { known.push(JSON.parse(fs.readFileSync(path.join(registered,f),'utf8')).target); } catch { /* invalid registration */ }
+    }
+    for(const target of new Set(known)) {
+      try { if(JSON.parse(fs.readFileSync(path.join(target,'.seedaudiocli-managed.json'),'utf8')).package===pkg.name) targets.push(target); } catch { /* unmanaged or absent */ }
+    }
+    const entry=path.join(root,'npm','cli.mjs');
+    const sync=target=>spawn(process.execPath,[entry,'skill','update','--root',path.dirname(target)],{encoding:'utf8',timeout:30000,env:{...process.env,SEEDAUDIO_AUTO_UPDATE:'0'}});
+    let mutated=false;
+    try {
+      mutated=true;
+      run(['install','--global','--prefix',prefix,'--ignore-scripts','--no-audit','--no-fund',`${pkg.name}@${check.available}`]);
+      const version=JSON.parse(fs.readFileSync(path.join(root,'package.json'),'utf8')).version;
+      if(version!==check.available) throw fail('UPDATE_VERIFY_FAILED','Installed package version mismatch.');
+      for(const target of targets) if(sync(target).status!==0) throw fail('SKILL_SYNC_FAILED','A managed Skill needs reconciliation.');
+      return {ok:true,changed:true,from:pkg.version,version,backup:path.join(backup,archive.filename)};
+    } catch(e) {
+      if(mutated) {
+        try { run(['install','--global','--prefix',prefix,'--ignore-scripts',path.join(backup,archive.filename)]); }
+        catch { throw fail('ROLLBACK_REQUIRED','Automatic recovery failed; restore the package archive before running commands.'); }
+        for(const target of targets) if(sync(target).status!==0) throw fail('ROLLBACK_SYNC_REQUIRED','Package restored; reconcile edited Skill files before updating.');
+      }
+      throw e;
+    }
+  } finally { fs.rmdirSync(lock); }
+}
+export async function beforeRun(args, services={}) {
+  if(process.env.SEEDAUDIO_AUTO_UPDATE==='0' || !globalPrefix() || args[0]==='update') return false;
+  const check=await (services.check || checkUpdate)();
+  if(!check.ok) console.error('[seedaudiocli] Update check unavailable; using installed version.');
+  if(!check.updateAvailable) return false;
+  try {
+    const result=(services.install || installUpdate)(check);
+    console.error(`[seedaudiocli] Using latest ${result.version}.`);
+  } catch(e) {
+    if(['UPDATE_BUSY','ROLLBACK_SYNC_REQUIRED','ROLLBACK_REQUIRED'].includes(e.code)) throw e;
+    console.error(`[seedaudiocli] ${e.code || 'UPDATE_FAILED'}; using restored installed version.`);
+  }
+  // Delegate once only after update/rollback; never replay a business request.
+  const r=spawnSync(process.execPath,[path.join(root,'npm','cli.mjs'),...args],{stdio:'inherit',env:{...process.env,SEEDAUDIO_AUTO_UPDATE:'0'}});
+  process.exitCode=r.status??1;
+  return true;
+}

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@petercjl/seedaudiocli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Seed Audio CLI with portable Agent skill and persistent user credentials",
+  "type": "module",
+  "bin": {
+    "seedaudiocli": "npm/cli.mjs"
+  },
+  "files": [
+    "npm/",
+    "seedaudiocli/*.py",
+    "skills/",
+    "capabilities.json",
+    "adapters/",
+    "seedaudiocli.env.example",
+    "seedaudiocli.config.example.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "check": "node --check npm/cli.mjs && node --check npm/runtime.mjs && node --check npm/skills.mjs",
+    "test": "node --test test/*.test.mjs",
+    "prepack": "npm run check && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/petercjl/seedaudiocli.git"
+  },
+  "license": "UNLICENSED"
+}

package/seedaudiocli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

package/seedaudiocli/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())