@yswgaicx/yswg-img-cli 0.1.7 → 0.1.8

package/README.md

@@ -2,6 +2,26 @@
 
 `yswg-img` wraps the YSWG Monkey Genius image generation page as a CLI.
 
+## Install
+
+Install from npm on any machine with Node.js 22 or newer:
+
+```bash
+npm install -g @yswgaicx/yswg-img-cli@latest
+yswg-img --help
+```
+
+Upgrade an existing global install:
+
+```bash
+npm install -g @yswgaicx/yswg-img-cli@latest
+yswg-img version --json
+```
+
+`yswg-img` checks npm for newer versions at most once every 12 hours and writes
+upgrade hints to stderr, so `--json` stdout stays parseable. Disable this check
+with `--no-update-check` or `YSWG_IMG_CLI_NO_UPDATE_CHECK=1`.
+
 ## Install Locally
 
 ```bash
@@ -55,6 +75,12 @@ yswg-img models --json
 yswg-img models refresh --json
 ```
 
+- Check whether the globally installed CLI is current:
+
+```bash
+yswg-img version --json
+```
+
 - For up to 4 parallel images in one backend request, call:
 
 ```bash
@@ -224,6 +250,7 @@ overridden.
 - `YSWG_REFRESH_TOKEN`
 - `YSWG_BASE_URL`
 - `YSWG_WS_PATH`
+- `YSWG_IMG_CLI_NO_UPDATE_CHECK`
 
 Default app name: `npm`.
 Default app ID: `2066371323654864898`.
@@ -247,6 +274,30 @@ yswg-img models refresh --json
 If generation reports a model/group validation mismatch, refresh the cache
 before submitting the same task again.
 
+## Version Updates
+
+Use `yswg-img version --json` for a machine-readable version check:
+
+```json
+{
+  "currentVersion": "0.1.7",
+  "latestVersion": "0.1.8",
+  "updateAvailable": true,
+  "upgradeCommand": "npm install -g @yswgaicx/yswg-img-cli@latest"
+}
+```
+
+Use `yswg-img upgrade --json` to print the canonical upgrade command without
+touching npm:
+
+```bash
+yswg-img upgrade --json
+```
+
+The CLI caches npm latest metadata in `~/.yswg-img-cli/update-check.json`.
+Regular commands emit update hints to stderr only, preserving stdout for JSON
+parsers and agents.
+
 ## Code Structure
 
 - `bin/yswg-img.js`: executable entrypoint only.
@@ -255,5 +306,6 @@ before submitting the same task again.
 - `src/api.js`: YSWG HTTP API client.
 - `src/config.js`: config loading, env/flag precedence, email normalization.
 - `src/model-cache.js`: built-in model metadata plus local cache refresh/read helpers.
+- `src/version-check.js`: npm latest lookup, update cache, version comparison, upgrade command.
 - `src/args.js`: minimal CLI argument parsing.
 - `src/image-compress.js`: frontend-compatible reference image compression.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yswgaicx/yswg-img-cli",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "CLI wrapper for YSWG Monkey Genius image generation.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -1,6 +1,7 @@
 import { parseArgs, readFlag, splitCsv } from "./args.js";
 import { loadConfig, normalizeEmail, resolveConfig, saveConfig, DEFAULT_APP_ID, DEFAULT_APP_NAME, DEFAULT_CONFIG_PATH } from "./config.js";
 import { loadModelCache, refreshModelCache } from "./model-cache.js";
+import { buildUpgradeCommand, checkForUpdate, PACKAGE_NAME } from "./version-check.js";
 import { YswgApi } from "./api.js";
 import {
   buildGeneratePayload,
@@ -26,6 +27,8 @@ export function buildHelpText() {
 Commands:
   auth send-code --email <name|email>
   auth login --email <name|email> --code <6 digits>
+  version [--json]
+  upgrade [--json]
   models [refresh] [--json]
   templates [--json]
   amazon asin <asin> [--max 7] [--json]
@@ -46,9 +49,10 @@ Agent usage:
   For long tasks, use --no-wait first, then tasks recover --task-id <id>.
   Keep generated image file paths and short summaries in agent context; do not paste image bytes or base64.
   Amazon ASIN gallery lookup: amazon asin <asin> --max 7 --json returns asin, title, images.
+  Upgrade globally with: ${buildUpgradeCommand()}
 
 Environment:
-  YSWG_TOKEN, YSWG_REFRESH_TOKEN, YSWG_BASE_URL, YSWG_WS_PATH
+  YSWG_TOKEN, YSWG_REFRESH_TOKEN, YSWG_BASE_URL, YSWG_WS_PATH, YSWG_IMG_CLI_NO_UPDATE_CHECK
 
 Config:
   ${DEFAULT_CONFIG_PATH}
@@ -71,6 +75,17 @@ function assertAuthenticated(resolved) {
   if (!resolved.token) throw new Error("missing token; run auth login or set YSWG_TOKEN");
 }
 
+function shouldSkipUpdateCheck(flags) {
+  return Boolean(flags.noUpdateCheck || process.env.YSWG_IMG_CLI_NO_UPDATE_CHECK);
+}
+
+async function emitUpdateHint({ flags, checkForUpdateFn, writeErr }) {
+  if (shouldSkipUpdateCheck(flags)) return;
+  const result = await checkForUpdateFn();
+  if (!result?.updateAvailable) return;
+  writeErr(`yswg-img: 发现新版本 ${result.latestVersion}，当前版本 ${result.currentVersion}。升级：${result.upgradeCommand}\n`);
+}
+
 function getUserId(config) {
   return config.user?.userId || config.user?.id;
 }
@@ -258,8 +273,10 @@ export async function runCli(argv, {
   saveConfigFn = saveConfig,
   loadModelCacheFn = loadModelCache,
   refreshModelCacheFn = refreshModelCache,
+  checkForUpdateFn = checkForUpdate,
   createApi = (resolved) => new YswgApi(resolved),
   write = (text) => process.stdout.write(text),
+  writeErr = (text) => process.stderr.write(text),
 } = {}) {
   const parsed = parseArgs(argv);
   const { command, subcommand, flags, positionals } = parsed;
@@ -268,6 +285,21 @@ export async function runCli(argv, {
     write(buildHelpText());
     return;
   }
+
+  if (command === "version") {
+    writeOutput(write, await checkForUpdateFn({ force: true }), json);
+    return;
+  }
+
+  if (command === "upgrade") {
+    writeOutput(write, {
+      packageName: PACKAGE_NAME,
+      upgradeCommand: buildUpgradeCommand(),
+      checkCommand: "yswg-img version --json",
+    }, json);
+    return;
+  }
+
   rejectAppIdOverride(flags);
 
   const config = await loadConfigFn();
@@ -280,6 +312,7 @@ export async function runCli(argv, {
     if (check?.registered === false) throw new Error(check.message || "email is not registered");
     await api.sendCode(email);
     writeOutput(write, { ok: true, email, message: "验证码已发送，请在企业微信中查收" }, json);
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
     return;
   }
 
@@ -299,6 +332,7 @@ export async function runCli(argv, {
       email,
     });
     writeOutput(write, { ok: true, email, configPath: DEFAULT_CONFIG_PATH }, json);
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
     return;
   }
 
@@ -309,22 +343,32 @@ export async function runCli(argv, {
         fetchModels: () => api.models(resolved.appId),
       });
       writeOutput(write, { ok: true, ...result }, json);
+      await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
       return;
     }
     writeOutput(write, await loadModelCacheFn(), json);
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
     return;
   }
 
   if (command === "templates") {
     assertAuthenticated(resolved);
     writeOutput(write, await api.templates(resolved.appId), json);
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
     return;
   }
 
-  if (command === "amazon" && await handleAmazonCommand({ api, flags, resolved, subcommand, positionals, json, write })) return;
-  if (command === "tasks" && await handleTaskCommand({ api, config, flags, resolved, subcommand, json, write })) return;
+  if (command === "amazon" && await handleAmazonCommand({ api, flags, resolved, subcommand, positionals, json, write })) {
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
+    return;
+  }
+  if (command === "tasks" && await handleTaskCommand({ api, config, flags, resolved, subcommand, json, write })) {
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
+    return;
+  }
   if (command === "generate") {
     await handleGenerate({ api, config, flags, resolved, json, write });
+    await emitUpdateHint({ flags, checkForUpdateFn, writeErr });
     return;
   }
 

package/src/version-check.js

@@ -0,0 +1,97 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+
+const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+
+export const PACKAGE_NAME = packageJson.name;
+export const CURRENT_VERSION = packageJson.version;
+export const DEFAULT_UPDATE_CACHE_PATH = join(homedir(), ".yswg-img-cli", "update-check.json");
+export const UPDATE_CHECK_TTL_MS = 12 * 60 * 60 * 1000;
+
+function parseVersion(version) {
+  return String(version || "")
+    .replace(/^v/i, "")
+    .split("-")[0]
+    .split(".")
+    .map((part) => Number.parseInt(part, 10) || 0);
+}
+
+export function compareVersions(left, right) {
+  const a = parseVersion(left);
+  const b = parseVersion(right);
+  const length = Math.max(a.length, b.length, 3);
+  for (let index = 0; index < length; index += 1) {
+    const diff = (a[index] || 0) - (b[index] || 0);
+    if (diff > 0) return 1;
+    if (diff < 0) return -1;
+  }
+  return 0;
+}
+
+export function buildUpgradeCommand() {
+  return `npm install -g ${PACKAGE_NAME}@latest`;
+}
+
+async function fetchNpmLatestVersion(packageName = PACKAGE_NAME) {
+  const encodedName = encodeURIComponent(packageName);
+  const response = await fetch(`https://registry.npmjs.org/${encodedName}/latest`, {
+    headers: { accept: "application/json" },
+  });
+  if (!response.ok) throw new Error(`npm registry returned ${response.status}`);
+  const data = await response.json();
+  if (!data?.version) throw new Error("npm registry response missing version");
+  return data.version;
+}
+
+async function readFreshCache(cachePath, now, ttlMs) {
+  try {
+    const cache = JSON.parse(await readFile(cachePath, "utf8"));
+    const checkedAt = new Date(cache.checkedAt).getTime();
+    if (!Number.isFinite(checkedAt) || now.getTime() - checkedAt > ttlMs) return null;
+    return cache.latestVersion ? cache : null;
+  } catch (error) {
+    if (error.code === "ENOENT") return null;
+    return null;
+  }
+}
+
+async function writeCache(cachePath, payload) {
+  await mkdir(dirname(cachePath), { recursive: true });
+  await writeFile(cachePath, `${JSON.stringify(payload, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function checkForUpdate({
+  cachePath = DEFAULT_UPDATE_CACHE_PATH,
+  currentVersion = CURRENT_VERSION,
+  fetchLatestVersion = fetchNpmLatestVersion,
+  now = new Date(),
+  ttlMs = UPDATE_CHECK_TTL_MS,
+  force = false,
+} = {}) {
+  try {
+    const cached = force ? null : await readFreshCache(cachePath, now, ttlMs);
+    const latestVersion = cached?.latestVersion || await fetchLatestVersion(PACKAGE_NAME);
+    if (!cached) {
+      await writeCache(cachePath, {
+        checkedAt: now.toISOString(),
+        latestVersion,
+      });
+    }
+    return {
+      currentVersion,
+      latestVersion,
+      updateAvailable: compareVersions(latestVersion, currentVersion) > 0,
+      upgradeCommand: buildUpgradeCommand(),
+    };
+  } catch (error) {
+    return {
+      currentVersion,
+      latestVersion: currentVersion,
+      updateAvailable: false,
+      upgradeCommand: buildUpgradeCommand(),
+      error: error.message,
+    };
+  }
+}