@petercjl/seedaudiocli 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @petercjl/seedaudiocli
 
-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.
+Official Volcengine 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
 
@@ -27,7 +27,7 @@ Credentials persist outside the npm installation:
 
 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`.
+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. Official env configurations are supported. To migrate an existing installation, import the new official configuration with `--replace`. Relay endpoints and relay model IDs are rejected. Obtain a Doubao Speech API key with Seed Audio access; an Ark API key is a different credential.
 
 ## Generate and recover
 
@@ -37,7 +37,13 @@ seedaudiocli generate text --prompt "Generate five seconds of instrumental piano
 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.
+Actual generation can incur provider charges. The official API returns audio synchronously. The CLI records a local ID before its single POST, then saves the response and audio privately. `task get`, `task wait` and `task download` recover saved local results without network calls. There is no remote task polling. A timeout or interrupted submission is marked unknown; inspect its local record and provider billing evidence before explicitly authorizing another attempt with `--force`. A repeated successful request reuses the cached result.
+
+The fixed endpoint is `https://openspeech.bytedance.com/api/v3/tts/create`, using `X-Api-Key` and model `seed-audio-1.0`. Prompts accept 1–3000 characters. Use `--audio-file` for local recordings or `--audio-reference` for preset speakers/public URLs (up to three total); address them with `@音频1` through `@音频3`. Use one `--image-file` or `--image-url` for image guidance. Local files are encoded directly in the official request. References are limited to 10 MiB each; audio must be at most 30 seconds. Audio and image modes are exclusive. `--speech-rate` and `--loudness-rate` are integers from -50 to 100 (0 unchanged), and `--pitch-rate` is -12 to 12. `--subtitle` saves returned subtitle data next to the audio.
+
+Outputs support mp3, wav, pcm and ogg_opus. Select compatible sample rates with the CLI help: mp3 excludes 40000 Hz and ogg_opus requires 48000 Hz. Output files are never silently overwritten. Old history remains on disk; official records are stored separately.
+
+Protocol reference: [Volcengine Seed Audio HTTP documentation](https://docs.volcengine.com/docs/DoubaoVoice/audio-generation-http?lang=zh).
 
 ## Agent installation
 
@@ -57,10 +63,14 @@ npm install -g @petercjl/seedaudiocli@latest
 seedaudiocli skill update --agent codex
 ```
 
-Run `skill update` for each installed Agent, including the configured SealSeek root. `update instructions` prints these operations and the current version's rollback command. Updates are explicit. Review compatibility before a major-version update. For rollback, install the prior exact npm version and synchronize Skills again. Credentials and history remain unchanged; offline or registry errors require retrying the package update when connectivity returns.
+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/capabilities.json

@@ -20,6 +20,7 @@
     "task get",
     "task wait",
     "task url",
+    "task download",
     "task jobs",
     "payload validate",
     "payload submit",
@@ -27,7 +28,8 @@
     "skill status",
     "skill install",
     "skill update",
-    "update instructions"
+    "update check",
+    "update install"
   ],
   "config": {
     "format": [
@@ -49,19 +51,30 @@
     "import": "seedaudiocli config import FILE [--replace]",
     "side_effects": "Local file write, backup on replacement; no remote call",
     "missing": "CONFIG_REQUIRED",
-    "secrets_in_output": false
+    "secrets_in_output": false,
+    "migration": "Import official configuration with --replace; backup is automatic; relay endpoints/models are rejected."
   },
   "update": {
-    "trigger": "explicit",
-    "instructions": "npm install -g @petercjl/seedaudiocli@latest; then skill update for each installed Agent",
-    "compatibility": "Review release notes before major updates",
-    "configuration": "Outside package; preserved"
+    "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",
+    "provider": "Volcengine",
+    "endpoint": "https://openspeech.bytedance.com/api/v3/tts/create",
+    "authentication": "X-Api-Key (Doubao Speech)",
+    "model": "seed-audio-1.0",
+    "mode": "synchronous",
     "paid": true,
     "submit_retry": false,
-    "recovery": "Use saved task ID; unknown submit outcome requires inspection before resubmission"
+    "local_references": true,
+    "remote_polling": false,
+    "recovery": "Persist local record before POST; save response and audio; export locally by record ID. Unknown outcomes require inspection and explicit authorization before --force."
   }
 }

package/npm/cli.mjs

@@ -1,5 +1,6 @@
 #!/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';
@@ -8,7 +9,8 @@ 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 (['version', '--version'].includes(args[0])) console.log(`seedaudiocli ${pkg.version}`);
+  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();
@@ -26,9 +28,11 @@ try {
       else throw fail('INVALID_COMMAND', 'Use skill source|status|install|update.');
     }
   } else if (args[0] === 'update') {
-    print({ ok: true, policy: 'explicit', installed_version: pkg.version, package_command: `npm install -g ${pkg.name}@latest`, skill_command: 'seedaudiocli skill update --agent AGENT [--root SKILLS_DIRECTORY]', rollback: `npm install -g ${pkg.name}@${pkg.version}`, note: 'Run the package command, then update each previously installed Skill. Configuration and task history remain in user directories. Registry/network failures preserve the last saved configuration.' });
+    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 instructions\nRuntime: Node.js 22+, Python 3.9+ (SEEDAUDIO_PYTHON optional).');
+    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);

package/npm/skills.mjs

@@ -2,6 +2,7 @@ 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');
@@ -46,6 +47,10 @@ export function status(target) {
 }
 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 };
@@ -60,7 +65,8 @@ export function install(target) {
   let backup;
   try {
     if (state.installed) {
-      backup = target + '.backup-' + crypto.randomUUID();
+      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.

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,6 @@
 {
   "name": "@petercjl/seedaudiocli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Seed Audio CLI with portable Agent skill and persistent user credentials",
   "type": "module",
   "bin": {

package/seedaudiocli/__init__.py

@@ -1 +1,9 @@
-__version__ = "0.1.0"
+"""Version follows the canonical npm package metadata."""
+import json
+from pathlib import Path
+
+try:
+    __version__ = json.loads((Path(__file__).resolve().parent.parent / "package.json").read_text(encoding="utf-8"))["version"]
+except (OSError, ValueError, KeyError):
+    from importlib.metadata import version
+    __version__ = version("seedaudiocli")