@petercjl/seedaudiocli 0.0.0-bootstrap.0 → 0.1.1

package/README.md

@@ -1,3 +1,66 @@
-# Seed Audio CLI bootstrap
+# @petercjl/seedaudiocli
 
-This placeholder establishes the package for npm Trusted Publishing. It contains no executable, credentials, or functional release. Use the stable release after it becomes available.
+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
+```
+
+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.
+
+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.

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,67 @@
+{
+  "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 instructions"
+  ],
+  "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": "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"
+  },
+  "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,40 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+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 (['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') {
+    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.' });
+  } 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).');
+    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,82 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+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);
+  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 = target + '.backup-' + crypto.randomUUID();
+      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/package.json

@@ -1,10 +1,29 @@
 {
   "name": "@petercjl/seedaudiocli",
-  "version": "0.0.0-bootstrap.0",
-  "description": "Bootstrap placeholder for configuring npm Trusted Publishing.",
+  "version": "0.1.1",
+  "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"
   },

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())