@petercjl/topazlabscli 0.2.0 → 0.2.1

package/README.md

@@ -15,7 +15,9 @@ 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.
+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. It discovers npm through the running Node installation, preserves SealSeek's managed global prefix/cache, and discovers Windows OpenSSH through the standard system location, so it also works in Agent runtimes with a restricted `PATH`. A temporary npm outage does not block video processing. `topazlabscli update` forces an immediate manual update.
+
+On Windows, SealSeek Skills are installed into `%USERPROFILE%\.sealseek\workspace\skills` when that workspace is present. The CLI automatically uses a managed copy because SealSeek rejects junctions that resolve outside the workspace Skill root; subsequent CLI updates refresh the copy from the npm package. The copy includes a local runtime manifest so the Agent can invoke the canonical package even when its PATH is restricted. `SEALSEEK_SKILLS_HOME` remains available as an explicit override.
 
 ## Configure a target
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@petercjl/topazlabscli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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 && node --check src/update.mjs && npm test"
+    "check": "node --check bin/topazlabscli.mjs && node --check src/cli.mjs && node --check src/runtime.mjs && node --check src/update.mjs && npm test"
   },
   "publishConfig": {
     "access": "public",

package/skill/topazlabscli/SKILL.md

@@ -15,12 +15,13 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 ## Main Line
 
-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. 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.
+1. Resolve the CLI invocation once. Prefer `topazlabscli`. In a Windows SealSeek managed-copy installation, if the npm command shim cannot find `node`, read `.topazlabscli-runtime.json` beside this file and execute its `bin` with its `node`; the CLI creates and refreshes that local manifest. SealSeek-managed npm installs must retain its managed global prefix rather than writing into a Node version directory. Reuse the invocation for the rest of the task; do not disable automatic updates.
+2. Run `topazlabscli capabilities --json` when the live contract is not already known.
+3. Run `topazlabscli doctor --json` before the first job in a conversation or after a connection/model failure, and wait for its terminal result before continuing.
+4. 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.
+5. 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.
+6. Inspect the final JSON. Completion requires `state=completed`, a successful download result, and a real local output file.
+7. Report the selected target/endpoint, job ID, output path, preset/model, dimensions, and any warning or failure.
 
 ## Preset Boundary
 
@@ -38,14 +39,14 @@ Use the CLI as the single execution surface. Do not reproduce SSH, SFTP, queue,
 
 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.
 
-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.
+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. The CLI resolves npm through the running Agent's Node installation when PATH is restricted. Registry, npm, and Skill-refresh 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
 
-The npm package is the canonical source. Discover it with `topazlabscli skill source --json`; use `skill status`, `skill install`, and `skill update` for Codex and SealSeek targets. Do not edit installed links or copies as independent sources.
+The npm package is the canonical source. Discover it with `topazlabscli skill source --json`; use `skill status`, `skill install`, and `skill update` for Codex and SealSeek targets. Windows SealSeek automatically receives a managed copy because its Skill loader rejects junctions that escape the workspace root; updates refresh that copy from the package. Do not edit installed links or copies as independent sources.
 
 ## QA and Evolution
 
-Use `doctor --json` plus the final job status as runtime evidence. Treat Codex and SealSeek adapters as `implemented` until each has a recorded real runtime test. New models, presets, cleanup rules, or worker behavior require an authorized package update with CLI, worker, Skill, capability, and test changes together.
+Use `doctor --json` plus the final job status as runtime evidence. Do not leave health checks or job commands running without collecting their terminal result. New models, presets, cleanup rules, or worker behavior require an authorized package update with CLI, worker, Skill, capability, and test changes together.

package/skill/topazlabscli/adapters/sealseek.json

@@ -5,12 +5,20 @@
   "mappings": [
     {
       "capability_id": "command.execute",
-      "implementation": { "kind": "cli", "command": "topazlabscli" },
+      "implementation": {
+        "kind": "cli",
+        "command": "topazlabscli",
+        "fallback": "Read .topazlabscli-runtime.json from the managed Skill copy and run its bin with its node"
+      },
       "features": ["local-process", "stdout-json", "exit-code"],
-      "status": "implemented",
-      "configuration": ["topazlabscli must resolve from PATH", "The bundled topazlabscli Skill must be installed through the CLI"],
+      "status": "tested",
+      "tested_date": "2026-09-21",
+      "evidence": [
+        "A clean Windows SealSeek conversation loaded the managed Skill copy, resolved the global package through its runtime manifest, ran version 0.2.1, capabilities, Skill status, and doctor to terminal results, and reported the bounded remote connection failure without disabling automatic updates."
+      ],
+      "configuration": ["Install the npm package globally", "Install the bundled Skill through the CLI into the SealSeek workspace"],
       "permissions": ["local process execution", "network access to configured SSH target"],
-      "normalization": "Invoke with --json and consume {ok,data,error}."
+      "normalization": "Invoke with --json and consume {ok,data,error}. On Windows with a sanitized PATH, use the CLI-managed runtime manifest in the installed Skill copy."
     },
     {
       "capability_id": "filesystem.local",

package/src/cli.mjs

@@ -21,7 +21,7 @@ const CAPABILITIES = {
   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" },
+  agents: { codex: "tested", sealseek_windows: "tested" },
   worker_os: ["windows"],
   transport: ["ssh", "sftp"]
 };
@@ -159,7 +159,14 @@ async function doctor(requestedTarget) {
     const result = await run(command, args);
     const detail = (result.stdout || result.stderr).trim().split("\n")[0];
     const ok = result.code === 0 || (command === "sftp" && /usage:\s*sftp/i.test(result.stderr));
-    checks.push({ id: `local.${command}`, ok, detail });
+    checks.push({
+      id: `local.${command}`,
+      ok,
+      detail,
+      resolved_command: result.resolvedCommand,
+      resolution: result.resolution,
+      timed_out: Boolean(result.timedOut)
+    });
   }
   checks.push({ id: "config", ok: fs.existsSync(configPath()), detail: configPath() });
   if (requestedTarget || fs.existsSync(configPath())) {

package/src/paths.mjs

@@ -1,4 +1,5 @@
 import os from "node:os";
+import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -21,13 +22,22 @@ export function updateStatePath() {
   return path.join(path.dirname(configPath()), "update-state.json");
 }
 
-export function skillTarget(agent) {
-  const home = os.homedir();
+export function skillTarget(agent, options = {}) {
+  const home = options.home || os.homedir();
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const exists = options.exists || fs.existsSync;
+  const pathApi = platform === "win32" ? path.win32 : path;
   if (agent === "codex") {
-    return path.join(process.env.CODEX_HOME || path.join(home, ".codex"), "skills", "topazlabscli");
+    return pathApi.join(env.CODEX_HOME || pathApi.join(home, ".codex"), "skills", "topazlabscli");
   }
   if (agent === "sealseek") {
-    return path.join(process.env.SEALSEEK_SKILLS_HOME || path.join(home, ".agents", "skills"), "topazlabscli");
+    if (env.SEALSEEK_SKILLS_HOME) return pathApi.join(env.SEALSEEK_SKILLS_HOME, "topazlabscli");
+    const workspace = pathApi.join(home, ".sealseek", "workspace");
+    const root = platform === "win32" && (exists(workspace) || exists(pathApi.dirname(workspace)))
+      ? pathApi.join(workspace, "skills")
+      : pathApi.join(home, ".agents", "skills");
+    return pathApi.join(root, "topazlabscli");
   }
   throw new Error(`Unknown Agent: ${agent}`);
 }

package/src/process.mjs

@@ -1,19 +1,34 @@
 import { spawn } from "node:child_process";
+import { resolveExecutable } from "./runtime.mjs";
 
 export function run(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+  return new Promise((resolve) => {
+    const executable = resolveExecutable(command, { env: options.env || process.env });
+    const child = spawn(executable.command, [...executable.argsPrefix, ...args], {
       cwd: options.cwd,
-      env: options.env || process.env,
+      env: { ...(options.env || process.env), ...(executable.envPatch || {}) },
       stdio: [options.input === undefined ? "ignore" : "pipe", "pipe", "pipe"],
       windowsHide: true
     });
     let stdout = "";
     let stderr = "";
+    let timedOut = false;
+    let timer = null;
+    const finish = (value) => {
+      if (timer) clearTimeout(timer);
+      resolve({ ...value, resolvedCommand: executable.command, resolution: executable.resolution, timedOut });
+    };
     child.stdout.on("data", (chunk) => { stdout += chunk; });
     child.stderr.on("data", (chunk) => { stderr += chunk; });
-    child.on("error", reject);
-    child.on("close", (code, signal) => resolve({ code, signal, stdout, stderr }));
+    child.on("error", (error) => finish({ code: 127, signal: null, stdout, stderr: stderr || error.message, error: error.message }));
+    child.on("close", (code, signal) => finish({ code, signal, stdout, stderr }));
+    if (Number.isFinite(options.timeoutMs) && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+      }, options.timeoutMs);
+      timer.unref?.();
+    }
     if (options.input !== undefined) {
       child.stdin.end(options.input);
     }
@@ -21,14 +36,15 @@ export function run(command, args, options = {}) {
 }
 
 export function runInherited(command, args, options = {}) {
-  return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+  return new Promise((resolve) => {
+    const executable = resolveExecutable(command, { env: options.env || process.env });
+    const child = spawn(executable.command, [...executable.argsPrefix, ...args], {
       cwd: options.cwd,
-      env: options.env || process.env,
+      env: { ...(options.env || process.env), ...(executable.envPatch || {}) },
       stdio: "inherit",
       windowsHide: true
     });
-    child.on("error", reject);
+    child.on("error", (error) => resolve({ code: 127, signal: null, error: error.message }));
     child.on("close", (code, signal) => resolve({ code, signal }));
   });
 }

package/src/runtime.mjs

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+
+function firstExisting(candidates, exists) {
+  return candidates.find((candidate) => candidate && exists(candidate)) || null;
+}
+
+export function resolveExecutable(name, options = {}) {
+  const platform = options.platform || process.platform;
+  const env = options.env || process.env;
+  const execPath = options.execPath || process.execPath;
+  const exists = options.exists || fs.existsSync;
+  const pathApi = platform === "win32" ? path.win32 : path;
+
+  if (name === "node") {
+    return { command: execPath, argsPrefix: [], resolution: "process.execPath" };
+  }
+
+  if (name === "npm") {
+    if (env.TOPAZLABSCLI_NPM) {
+      return { command: env.TOPAZLABSCLI_NPM, argsPrefix: [], resolution: "TOPAZLABSCLI_NPM" };
+    }
+    const npmExecPath = env.npm_execpath && pathApi.resolve(env.npm_execpath);
+    const managedNpm = firstExisting([
+      npmExecPath,
+      pathApi.join(pathApi.dirname(execPath), "node_modules", "npm", "bin", "npm-cli.js")
+    ], exists);
+    if (managedNpm) {
+      const versionDirectory = pathApi.dirname(execPath);
+      const versionsDirectory = pathApi.dirname(versionDirectory);
+      const managedRoot = pathApi.basename(versionsDirectory).toLowerCase() === "versions"
+        ? pathApi.dirname(versionsDirectory)
+        : null;
+      const managedPrefix = managedRoot && pathApi.join(managedRoot, "global");
+      const managedCache = managedRoot && pathApi.join(managedRoot, "cache");
+      const envPatch = managedPrefix && exists(managedPrefix)
+        ? {
+            npm_config_prefix: env.npm_config_prefix || managedPrefix,
+            ...(managedCache && exists(managedCache) ? { npm_config_cache: env.npm_config_cache || managedCache } : {})
+          }
+        : {};
+      return { command: execPath, argsPrefix: [managedNpm], envPatch, resolution: "managed-node-npm-cli" };
+    }
+  }
+
+  if (platform === "win32" && ["ssh", "sftp"].includes(name)) {
+    const override = env[`TOPAZLABSCLI_${name.toUpperCase()}`];
+    if (override) return { command: override, argsPrefix: [], resolution: `TOPAZLABSCLI_${name.toUpperCase()}` };
+    const windowsRoot = env.SystemRoot || env.WINDIR || "C:\\Windows";
+    const openSsh = pathApi.join(windowsRoot, "System32", "OpenSSH", `${name}.exe`);
+    if (exists(openSsh)) return { command: openSsh, argsPrefix: [], resolution: "windows-openssh" };
+  }
+
+  return { command: name, argsPrefix: [], resolution: "PATH" };
+}

package/src/skill.mjs

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { bundledSkill, skillTarget } from "./paths.mjs";
+import { binScript, bundledSkill, packageRoot, skillTarget } from "./paths.mjs";
 import { CliError } from "./errors.mjs";
 
 const agents = ["codex", "sealseek"];
@@ -23,7 +23,24 @@ export function skillStatus(selected = "all") {
   });
 }
 
+export function effectiveSkillMode(agent, requestedMode, platform = process.platform) {
+  if (platform === "win32" && agent === "sealseek" && requestedMode === "link") return "copy";
+  return requestedMode;
+}
+
+function writeRuntimeManifest(target) {
+  const manifest = {
+    schema: "topazlabscli-skill-runtime",
+    schema_version: 1,
+    node: process.execPath,
+    bin: binScript,
+    package_root: packageRoot
+  };
+  fs.writeFileSync(path.join(target, ".topazlabscli-runtime.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+}
+
 function installOne(agent, mode, update) {
+  const effectiveMode = effectiveSkillMode(agent, mode);
   const target = skillTarget(agent);
   fs.mkdirSync(path.dirname(target), { recursive: true });
   if (fs.existsSync(target)) {
@@ -32,9 +49,11 @@ function installOne(agent, mode, update) {
     if (stat.isSymbolicLink()) fs.unlinkSync(target);
     else fs.rmSync(target, { recursive: true, force: true });
   }
-  if (mode === "copy") fs.cpSync(bundledSkill, target, { recursive: true });
-  else fs.symlinkSync(bundledSkill, target, process.platform === "win32" ? "junction" : "dir");
-  return { agent, target, mode };
+  if (effectiveMode === "copy") {
+    fs.cpSync(bundledSkill, target, { recursive: true });
+    writeRuntimeManifest(target);
+  } else fs.symlinkSync(bundledSkill, target, process.platform === "win32" ? "junction" : "dir");
+  return { agent, target, mode: effectiveMode, source: bundledSkill };
 }
 
 export function skillInstall(selected = "all", mode = "link", update = false) {

package/src/ssh.mjs

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { run } from "./process.mjs";
+import { resolveExecutable } from "./runtime.mjs";
 import { CliError } from "./errors.mjs";
 
 function destination(target, endpoint) {
@@ -22,13 +23,15 @@ export function encodePowerShell(script) {
 export async function runPowerShell(target, endpoint, script, { timeout = 7 } = {}) {
   const args = [...commonArgs(target, endpoint, { timeout }), destination(target, endpoint),
     "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
-  return run("ssh", args);
+  return run("ssh", args, { timeoutMs: (timeout + 3) * 1000 });
 }
 
 export function startPowerShellDetached(target, endpoint, script) {
   const args = [...commonArgs(target, endpoint, { timeout: 10 }), destination(target, endpoint),
     "powershell.exe", "-NoLogo", "-NoProfile", "-NonInteractive", "-EncodedCommand", encodePowerShell(script)];
-  const child = spawn("ssh", args, { detached: true, stdio: "ignore", windowsHide: true });
+  const executable = resolveExecutable("ssh");
+  const child = spawn(executable.command, [...executable.argsPrefix, ...args], { detached: true, stdio: "ignore", windowsHide: true });
+  child.on("error", () => {});
   child.unref();
   return child.pid;
 }
@@ -38,7 +41,13 @@ export async function selectEndpoint(target) {
   for (const endpoint of target.endpoints) {
     const result = await runPowerShell(target, endpoint, "[Console]::Out.Write('TOPAZLABSCLI_OK')");
     const ok = result.code === 0 && result.stdout.includes("TOPAZLABSCLI_OK");
-    attempts.push({ name: endpoint.name, host: endpoint.host, ok, error: ok ? null : result.stderr.trim() });
+    attempts.push({
+      name: endpoint.name,
+      host: endpoint.host,
+      ok,
+      timed_out: Boolean(result.timedOut),
+      error: ok ? null : result.stderr.trim()
+    });
     if (ok) return { endpoint, attempts };
   }
   throw new CliError("CONNECTION_FAILED", `No endpoint is reachable for target ${target.name}.`, { attempts });
@@ -61,7 +70,7 @@ export async function sftpPut(target, endpoint, localPath, remotePath) {
   if (endpoint.port) args.push("-P", String(endpoint.port));
   args.push(destination(target, endpoint));
   const input = `put ${quoteSftp(path.resolve(localPath))} ${quoteSftp(windowsToSftp(remotePath))}\n`;
-  const result = await run("sftp", args, { input });
+  const result = await run("sftp", args, { input, timeoutMs: 15000 });
   if (result.code !== 0) throw new CliError("UPLOAD_FAILED", result.stderr.trim() || "SFTP upload failed.");
   return result;
 }
@@ -73,7 +82,7 @@ export async function sftpGet(target, endpoint, remotePath, localPath) {
   if (endpoint.port) args.push("-P", String(endpoint.port));
   args.push(destination(target, endpoint));
   const input = `get ${quoteSftp(windowsToSftp(remotePath))} ${quoteSftp(path.resolve(localPath))}\n`;
-  const result = await run("sftp", args, { input });
+  const result = await run("sftp", args, { input, timeoutMs: 15000 });
   if (result.code !== 0) throw new CliError("DOWNLOAD_FAILED", result.stderr.trim() || "SFTP download failed.");
   return result;
 }

package/src/update.mjs

@@ -58,9 +58,14 @@ export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
   }
 
   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" }
-  });
+  let query;
+  try {
+    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" }
+    });
+  } catch (error) {
+    return { checked: true, warning: `Unable to check npm for updates: ${error.message}` };
+  }
   if (query.code !== 0) {
     return { checked: true, warning: query.stderr.trim() || "Unable to check npm for updates." };
   }
@@ -74,15 +79,29 @@ export async function maybeAutoUpdate(rawArgs, pkg, dependencies = {}) {
   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 });
+  let install;
+  try {
+    install = await execute("npm", ["install", "--global", `${pkg.name}@latest`], { env });
+  } catch (error) {
+    return { checked: true, warning: `Automatic npm update failed: ${error.message}`, latest };
+  }
   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 warnings = [];
+  for (const item of installedSkills) {
+    try { installSkill(item.agent, item.mode || "link", true); }
+    catch (error) { warnings.push(`Skill refresh failed for ${item.agent}: ${error.message}`); }
+  }
 
   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 };
+  try {
+    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, warnings };
+  } catch (error) {
+    warnings.push(`Updated package could not restart the command: ${error.message}`);
+    return { checked: true, updated: true, latest, warning: warnings.join(" ") };
+  }
 }