@petercjl/topazlabscli 0.1.1 → 0.2.0

package/README.md

@@ -15,6 +15,8 @@ npm install --global @petercjl/topazlabscli
 topazlabscli skill install --agent all
 ```
 
+The CLI checks npm for a newer stable release before operational commands, at most once every six hours. When an update is available it upgrades itself, refreshes installed Agent Skills, and then resumes the original command. A temporary npm outage does not block video processing. `topazlabscli update` forces an immediate manual update.
+
 ## Configure a target
 
 Use one or more SSH endpoints in priority order. A LAN-only user configures only the LAN entry.
@@ -56,9 +58,11 @@ The worker uses a global Windows mutex and one queue consumer, so jobs from mult
 ## Process a video
 
 ```powershell
-topazlabscli process .\input.mp4 --output .\output-1080p.mp4 --json
+topazlabscli process .\input.mp4 --json
 ```
 
+Without `--output`, the CLI writes `input-topaz-1080p.mp4` beside the source video. An explicit `--output` remains available for automation.
+
 Asynchronous form:
 
 ```powershell
@@ -68,7 +72,7 @@ topazlabscli job wait JOB_ID --json
 topazlabscli job download JOB_ID --output .\output-1080p.mp4 --json
 ```
 
-Version 0.1 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding.
+Version 0.2 includes one preset: `seedance-human-1080p`, using Proteus v4 (`prob-4`), source FPS, aspect-preserving 1080p output, and NVIDIA H.264 encoding.
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/topazlabscli",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Cross-Agent CLI and portable Skill for queued remote Topaz Video AI processing",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && npm test"
+    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/update.mjs && npm test"
   },
   "publishConfig": {
     "access": "public",

package/skill/topazlabscli/SKILL.md

@@ -9,7 +9,7 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 ## Input → Strategy → Output
 
-- Input: a local video path or a job identifier, the user's requested action, and an already configured target.
+- Input: a local video path or a job identifier, the user's requested action, and an already configured target. A processing request needs only the input path.
 - Strategy: inspect capabilities and health, select the configured reachable endpoint, submit one deterministic preset to the serialized Windows queue, observe terminal state, and download only when requested.
 - Output: structured CLI evidence, a job identifier and state, and for completed processing an explicitly requested local output file.
 
@@ -17,28 +17,30 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 1. Run `topazlabscli capabilities --json` when the live contract is not already known.
 2. Run `topazlabscli doctor --json` before the first job in a conversation or after a connection/model failure.
-3. For a processing request, confirm the input exists and the output path is authorized.
-4. Prefer `topazlabscli process INPUT --output OUTPUT --json` for submit, wait, and download as one operation. Use separate `job` commands when the user wants asynchronous control.
+3. For a processing request, confirm the input exists. When the user does not name an output, let the CLI create `INPUT-BASENAME-topaz-1080p.EXT` beside the source.
+4. Prefer `topazlabscli process INPUT --json` for submit, wait, and download as one operation. Add `--output OUTPUT` only when the user explicitly requests another destination. Use separate `job` commands when the user wants asynchronous control.
 5. Inspect the final JSON. Completion requires `state=completed`, a successful download result, and a real local output file.
 6. Report the selected target/endpoint, job ID, output path, preset/model, dimensions, and any warning or failure.
 
 ## Preset Boundary
 
-`seedance-human-1080p` is the only built-in preset in version 0.1. It uses Proteus v4 (`prob-4`), preserves source FPS and aspect ratio, targets a 1080-pixel short edge, and relies on the remote queue's single concurrency slot. Do not silently substitute another model, frame interpolation, stabilization, motion deblur, or 4K output.
+`seedance-human-1080p` is the only built-in preset in version 0.2. It uses Proteus v4 (`prob-4`), preserves source FPS and aspect ratio, targets a 1080-pixel short edge, and relies on the remote queue's single concurrency slot. Do not silently substitute another model, frame interpolation, stabilization, motion deblur, or 4K output.
 
 ## Branches
 
 - Connection failure: report `CONNECTION_FAILED` and the endpoint attempts. The CLI does not start, reconfigure, or grant access to a VPN.
 - Worker/model not ready: run `worker status` or `model status`; stop with the returned dependency error. Installing/licensing Topaz and downloading models remain GUI administration tasks.
 - Long-running work: use `job submit`, return the job ID, then `job wait` when the user asks to remain attached. Do not resubmit merely because a wait timed out.
-- Cancellation: queued work may cancel immediately. A running task records a cancellation request but is not forcibly killed in version 0.1.
+- Cancellation: queued work may cancel immediately. A running task records a cancellation request but is not forcibly killed in version 0.2.
 - Missing capability: return `CAPABILITY_UNAVAILABLE` or the CLI's structured error. Do not invent a platform-specific workaround.
 
 ## Configuration and Safety
 
 Configuration, hostnames, addresses, usernames, SSH identities, VPN details, media, Topaz binaries, models, and credentials are external to this Skill and npm package. Installation does not grant access to a workstation. Treat the configured server and Topaz license as user-managed resources.
 
-Do not overwrite a local output unless the user has authorized that exact existing target. The remote worker retains job inputs, outputs, status, and logs for operator review; cleanup is an administrative action outside version 0.1.
+Before operational commands, the CLI performs a cached npm update check. A newer stable package is installed automatically, installed Agent Skills are refreshed, and the original command resumes under the new version. Registry failures produce a warning and continue with the installed version.
+
+Do not overwrite a local output unless the user has authorized that exact existing target. The remote worker retains job inputs, outputs, status, and logs for operator review; cleanup is an administrative action outside version 0.2.
 
 ## Skill Management
 

package/skill/topazlabscli/adapters/sealseek.json

@@ -8,7 +8,7 @@
       "implementation": { "kind": "cli", "command": "topazlabscli" },
       "features": ["local-process", "stdout-json", "exit-code"],
       "status": "implemented",
-      "configuration": ["topazlabscli must resolve from PATH"],
+      "configuration": ["topazlabscli must resolve from PATH", "The bundled topazlabscli Skill must be installed through the CLI"],
       "permissions": ["local process execution", "network access to configured SSH target"],
       "normalization": "Invoke with --json and consume {ok,data,error}."
     },

package/skill/topazlabscli/capabilities.json

@@ -6,13 +6,13 @@
   "capabilities": [
     {
       "id": "command.execute",
-      "purpose": "Run the stable topazlabscli executable and parse JSON results.",
+      "purpose": "Run the stable, self-updating topazlabscli executable and parse JSON results.",
       "required": true,
       "required_features": ["local-process", "stdout-json", "exit-code"],
       "input_fields": ["argv"],
       "output_fields": ["ok", "data", "error"],
       "side_effects": {
-        "external_mutation": "May upload videos and enqueue remote processing only when the user requests processing.",
+        "external_mutation": "May update the installed npm package and Agent Skill before a command; may upload videos and enqueue remote processing only when the user requests processing.",
         "may_cost_money": false,
         "authorization": "Requires the user's configured SSH access and an explicit processing request."
       },

package/src/cli.mjs

@@ -8,6 +8,7 @@ import { CliError, requireValue } from "./errors.mjs";
 import { run } from "./process.mjs";
 import { psLiteral, runPowerShell, selectEndpoint, sftpGet, sftpPut, startPowerShellDetached } from "./ssh.mjs";
 import { skillInstall, skillSource, skillStatus } from "./skill.mjs";
+import { maybeAutoUpdate } from "./update.mjs";
 
 const require = createRequire(import.meta.url);
 const pkg = require("../package.json");
@@ -17,7 +18,8 @@ const CAPABILITIES = {
   schema_version: 1,
   package: pkg.name,
   version: pkg.version,
-  commands: ["version", "capabilities", "doctor", "target", "connection", "worker", "model", "job", "process", "skill", "update"],
+  commands: ["version", "capabilities", "doctor", "settings", "target", "connection", "worker", "model", "job", "process", "skill", "update"],
+  automatic_updates: { enabled_by_default: true, registry_check_hours: 6, refreshes_installed_skills: true },
   presets: [{ id: PRESET, model: "prob-4", output: "aspect-preserving 1080p", fps: "source", concurrency: 1 }],
   agents: { codex: "tested", sealseek: "implemented" },
   worker_os: ["windows"],
@@ -58,6 +60,7 @@ function help() {
   return `topazlabscli ${pkg.version}\n\n` +
     `Commands:\n` +
     `  version | capabilities | doctor\n` +
+    `  settings show | set auto-update <on|off> | set update-check-hours <hours>\n` +
     `  target add <name> --endpoint <label=host>... --user <user> [--identity <path>] [--workspace <windows-path>] [--default]\n` +
     `  target list\n` +
     `  connection check [--target <name>]\n` +
@@ -66,7 +69,7 @@ function help() {
     `  job submit <video> [--target <name>] [--preset ${PRESET}]\n` +
     `  job list [--target <name>]\n` +
     `  job status|wait|download|cancel <job-id> [--target <name>] [--output <path>]\n` +
-    `  process <video> --output <path> [--target <name>]\n` +
+    `  process <video> [--output <path>] [--target <name>]\n` +
     `  skill source|status|install|update [--agent codex|sealseek|all] [--copy]\n` +
     `  update\n\nUse --json for machine-readable output.`;
 }
@@ -143,6 +146,12 @@ async function downloadJob(id, requestedTarget, outputPath) {
   return { id, target: target.name, endpoint: endpoint.name, output: destination };
 }
 
+export function defaultOutputPath(inputPath) {
+  const resolved = path.resolve(inputPath);
+  const extension = path.extname(resolved) || ".mp4";
+  return path.join(path.dirname(resolved), `${path.basename(resolved, path.extname(resolved))}-topaz-1080p${extension}`);
+}
+
 async function doctor(requestedTarget) {
   const checks = [];
   for (const command of ["ssh", "sftp", "node", "npm"]) {
@@ -177,6 +186,37 @@ export async function main(rawArgs) {
   const command = args.shift();
   if (command === "version" || command === "--version" || command === "-V") return output(pkg.version, json);
   if (command === "capabilities") return output(CAPABILITIES, json);
+
+  if (!["update", "settings"].includes(command)) {
+    const update = await maybeAutoUpdate(rawArgs, pkg);
+    if (update.warning) process.stderr.write(`[AUTO_UPDATE_WARNING] ${update.warning}\n`);
+    if (update.reexecuted) {
+      process.exitCode = update.exitCode;
+      return;
+    }
+  }
+
+  if (command === "settings") {
+    const action = args.shift() || "show";
+    const config = loadConfig();
+    if (action === "show") return output(config.settings, json);
+    if (action === "set") {
+      const name = requireValue(args.shift(), "SETTING_REQUIRED", "settings set requires a setting name.");
+      const value = requireValue(args.shift(), "VALUE_REQUIRED", `settings set ${name} requires a value.`);
+      if (name === "auto-update") {
+        if (!["on", "off"].includes(value)) throw new CliError("SETTING_INVALID", "auto-update must be on or off.");
+        config.settings.auto_update = value === "on";
+      } else if (name === "update-check-hours") {
+        const hours = Number(value);
+        if (!Number.isFinite(hours) || hours < 0) throw new CliError("SETTING_INVALID", "update-check-hours must be zero or a positive number.");
+        config.settings.update_check_hours = hours;
+      } else throw new CliError("SETTING_UNKNOWN", `Unknown setting: ${name}`);
+      const saved = saveConfig(config);
+      return output({ path: saved, settings: config.settings }, json);
+    }
+    throw new CliError("COMMAND_UNKNOWN", `Unknown settings action: ${action}`);
+  }
+
   if (command === "doctor") return output(await doctor(option(args, "--target")), json);
 
   if (command === "target") {
@@ -253,7 +293,7 @@ export async function main(rawArgs) {
 
   if (command === "process") {
     const input = requireValue(args.shift(), "INPUT_REQUIRED", "process requires a video.");
-    const destination = requireValue(option(args, "--output"), "OUTPUT_REQUIRED", "process requires --output.");
+    const destination = option(args, "--output") || defaultOutputPath(input);
     const requested = option(args, "--target");
     const submitted = await submitJob(input, requested, option(args, "--preset") || PRESET);
     const finished = await waitJob(submitted.id, requested, Number(option(args, "--interval") || 10), Number(option(args, "--timeout") || 86400));

package/src/config.mjs

@@ -4,7 +4,12 @@ import { configPath } from "./paths.mjs";
 import { CliError } from "./errors.mjs";
 
 export function emptyConfig() {
-  return { schema_version: 1, default_target: null, targets: {} };
+  return {
+    schema_version: 1,
+    default_target: null,
+    targets: {},
+    settings: { auto_update: true, update_check_hours: 6 }
+  };
 }
 
 export function loadConfig({ required = false } = {}) {
@@ -18,7 +23,15 @@ export function loadConfig({ required = false } = {}) {
     if (parsed.schema_version !== 1 || typeof parsed.targets !== "object") {
       throw new Error("unsupported configuration schema");
     }
-    return parsed;
+    return {
+      ...parsed,
+      settings: {
+        auto_update: parsed.settings?.auto_update !== false,
+        update_check_hours: Number.isFinite(parsed.settings?.update_check_hours)
+          ? parsed.settings.update_check_hours
+          : 6
+      }
+    };
   } catch (error) {
     throw new CliError("CONFIG_INVALID", `Cannot read configuration: ${error.message}`, { path: filename });
   }

package/src/paths.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 export const packageRoot = path.resolve(here, "..");
+export const binScript = path.join(packageRoot, "bin", "topazlabscli.mjs");
 export const bundledSkill = path.join(packageRoot, "skill", "topazlabscli");
 export const workerScript = path.join(packageRoot, "worker", "windows", "topazlabs-worker.ps1");
 
@@ -15,6 +16,11 @@ export function configPath() {
   return path.join(base, "topazlabscli", "config.json");
 }
 
+export function updateStatePath() {
+  if (process.env.TOPAZLABSCLI_UPDATE_STATE) return path.resolve(process.env.TOPAZLABSCLI_UPDATE_STATE);
+  return path.join(path.dirname(configPath()), "update-state.json");
+}
+
 export function skillTarget(agent) {
   const home = os.homedir();
   if (agent === "codex") {

package/src/process.mjs

@@ -19,3 +19,16 @@ export function run(command, args, options = {}) {
     }
   });
 }
+
+export function runInherited(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      env: options.env || process.env,
+      stdio: "inherit",
+      windowsHide: true
+    });
+    child.on("error", reject);
+    child.on("close", (code, signal) => resolve({ code, signal }));
+  });
+}

package/src/update.mjs

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+import path from "node:path";
+import { loadConfig } from "./config.mjs";
+import { binScript, updateStatePath } from "./paths.mjs";
+import { run, runInherited } from "./process.mjs";
+import { skillInstall, skillStatus } from "./skill.mjs";
+
+const DEFAULT_INTERVAL_HOURS = 6;
+const UPDATE_GUARD = "TOPAZLABSCLI_AUTO_UPDATE_GUARD";
+
+function numericParts(version) {
+  return String(version).replace(/^v/, "").split(/[.+-]/).slice(0, 3).map((part) => Number(part) || 0);
+}
+
+export function isNewerVersion(candidate, current) {
+  const left = numericParts(candidate);
+  const right = numericParts(current);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function readState(filename) {
+  try { return JSON.parse(fs.readFileSync(filename, "utf8")); }
+  catch { return {}; }
+}
+
+function writeState(filename, value) {
+  fs.mkdirSync(path.dirname(filename), { recursive: true, mode: 0o700 });
+  const temporary = `${filename}.${process.pid}.tmp`;
+  fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
+  fs.renameSync(temporary, filename);
+  try { fs.chmodSync(filename, 0o600); } catch {}
+}
+
+function automaticUpdateEnabled(config, env) {
+  const override = env.TOPAZLABSCLI_AUTO_UPDATE?.toLowerCase();
+  if (["0", "false", "off", "no"].includes(override)) return false;
+  if (["1", "true", "on", "yes"].includes(override)) return true;
+  return config.settings?.auto_update !== false;
+}
+
+export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
+  const env = dependencies.env || process.env;
+  if (env[UPDATE_GUARD] === "1") return { checked: false, reason: "guard" };
+
+  const config = (dependencies.loadConfig || loadConfig)();
+  if (!automaticUpdateEnabled(config, env)) return { checked: false, reason: "disabled" };
+
+  const stateFile = dependencies.stateFile || updateStatePath();
+  const now = dependencies.now?.() || Date.now();
+  const intervalHours = Number(config.settings?.update_check_hours ?? DEFAULT_INTERVAL_HOURS);
+  const intervalMs = Math.max(0, intervalHours) * 60 * 60 * 1000;
+  const state = readState(stateFile);
+  if (intervalMs > 0 && Number.isFinite(state.last_checked_at) && now - state.last_checked_at < intervalMs) {
+    return { checked: false, reason: "fresh", latest: state.latest || null };
+  }
+
+  const execute = dependencies.run || run;
+  const query = await execute("npm", ["view", pkg.name, "version", "--json"], {
+    env: { ...env, npm_config_fetch_timeout: env.npm_config_fetch_timeout || "5000", npm_config_fetch_retries: "0" }
+  });
+  if (query.code !== 0) {
+    return { checked: true, warning: query.stderr.trim() || "Unable to check npm for updates." };
+  }
+
+  let latest;
+  try { latest = JSON.parse(query.stdout.trim()); }
+  catch { latest = query.stdout.trim().replace(/^"|"$/g, ""); }
+  writeState(stateFile, { last_checked_at: now, latest, current: pkg.version });
+  if (!isNewerVersion(latest, pkg.version)) return { checked: true, updated: false, latest };
+
+  const getSkillStatus = dependencies.skillStatus || skillStatus;
+  const installSkill = dependencies.skillInstall || skillInstall;
+  const installedSkills = getSkillStatus("all").filter((item) => item.installed);
+  const install = await execute("npm", ["install", "--global", `${pkg.name}@latest`], { env });
+  if (install.code !== 0) {
+    return { checked: true, warning: install.stderr.trim() || "Automatic npm update failed.", latest };
+  }
+  for (const item of installedSkills) installSkill(item.agent, item.mode || "link", true);
+
+  const reexecute = dependencies.runInherited || runInherited;
+  const child = await reexecute(process.execPath, [binScript, ...rawArgs], {
+    env: { ...env, [UPDATE_GUARD]: "1" }
+  });
+  return { checked: true, updated: true, latest, reexecuted: true, exitCode: child.code ?? 1 };
+}