@yandy0725/mediagen-cli 0.1.1 → 0.3.0

package/README.md

@@ -39,6 +39,7 @@ Node >= 18, two runtime dependencies, a DashScope and/or Ark API key.
 | `mediagen login` / `logout` / `auth status` | store, remove, inspect API keys |
 | `mediagen config show` / `config path` | resolved config, and where it lives |
 | `mediagen config add <name>` | create a provider in config.toml; everything else is a manual edit |
+| `mediagen skill install --dir <path>` | copy the packaged agent skill into `<path>/mediagen/`; re-run to replace it |
 
 `mediagen image generate --help` and `mediagen video generate --help` are the
 reference: every flag, the model table, the size reference, examples. Everything below
@@ -122,15 +123,30 @@ code `TaskNotFinished`, and `video status <id>` resumes it without paying again.
 ## Configuration
 
 `config.toml` — the file you edit — lives in the first of
-`$MEDIAGEN_CLI_CONFIG_DIR`, `$XDG_CONFIG_HOME/mediagen-cli`, `~/.config/mediagen-cli`.
+`$MEDIAGEN_CLI_CONFIG_DIR`, `$XDG_CONFIG_HOME/mediagen`, `~/.config/mediagen`.
 
 `auth.json` (mode `600`) is **state, not config**, and lives apart from it: the first
-of `$MEDIAGEN_CLI_STATE_DIR`, `$XDG_STATE_HOME/mediagen-cli`,
-`~/.local/state/mediagen-cli`. `~/.config` is the directory people sync, share and
+of `$MEDIAGEN_CLI_STATE_DIR`, `$XDG_STATE_HOME/mediagen`,
+`~/.local/state/mediagen`. `~/.config` is the directory people sync, share and
 commit; a key store there is one `.gitignore` mistake away from a leaked key. The
 state directory is machine-local by definition, which is what a device-bound
 credential is.
 
+Upgrading from 0.1.1 or earlier: both directories dropped the `-cli` suffix, and nothing
+migrates them for you. Move the files, not the directories — a first run of this version
+already creates the new directories, and `mv dir dir` would bury your config inside them:
+
+```bash
+mkdir -p ~/.config/mediagen ~/.local/state/mediagen
+mv ~/.config/mediagen-cli/config.toml ~/.config/mediagen/config.toml
+mv ~/.local/state/mediagen-cli/auth.json ~/.local/state/mediagen/auth.json
+```
+
+(With `XDG_CONFIG_HOME` or `XDG_STATE_HOME` set, the paths are `<that>/mediagen-cli` →
+`<that>/mediagen` instead. If you set `MEDIAGEN_CLI_CONFIG_DIR` or
+`MEDIAGEN_CLI_STATE_DIR`, the names are unchanged and there is nothing to move. Skip a
+line whose `mediagen-cli` path does not exist — most users never had an `auth.json`.)
+
 ```toml
 default_provider = "volcengine"
 # output_dir = "./media-output"
@@ -238,9 +254,11 @@ download and 600 s per video download. For video that budget is the *whole* poll
 window, not one request: each create or poll gets 60 s, so a hung request cannot eat
 the budget, and the download has its own 600 s and is not counted against it.
 
-Working from an agent? `skills/mediagen/SKILL.md` describes what this CLI does, which tool
-to prefer when the project already generates media another way, and the rules that keep a
-paid request from being wasted.
+Working from an agent? `mediagen skill install --dir <skills dir>` puts
+`skills/mediagen/SKILL.md` where your agent already looks — e.g. `--dir ~/.claude/skills` — and
+re-running it after an upgrade replaces the old copy. The skill describes what this CLI does,
+which tool to prefer when the project already generates media another way, and the rules that
+keep a paid request from being wasted.
 
 ---
 
@@ -253,6 +271,10 @@ npm test         # vitest, fully offline: fetch is stubbed everywhere
 npm run dev -- image generate --help
 ```
 
+Tests live in `tests/` — one file per module, imported from `../src/` — and never
+beside the sources; `vitest.config.ts` picks up `tests/**/*.test.ts` and nothing else.
+`tsc --noEmit` typechecks them too.
+
 `src/cli.ts` wires commander and maps errors to exit codes; `src/generate.ts` runs
 the pipeline (validate → resolve → call → download → report); `src/api/{qwen,ark,dashscope}.ts`
 are the dialect adapters behind the `DialectAdapter` seam in `src/types.ts`, with

package/README.zh-CN.md

@@ -38,6 +38,7 @@ Node >= 18，两个运行时依赖，需要 DashScope 和/或方舟的 API key
 | `mediagen login` / `logout` / `auth status` | 保存、删除、查看 API key |
 | `mediagen config show` / `config path` | 解析后的配置，以及它存在哪里 |
 | `mediagen config add <name>` | 在 config.toml 里新建一条 provider（其余修改手写文件） |
+| `mediagen skill install --dir <path>` | 把自带的 agent 技能装到 `<path>/mediagen/`；重跑即覆盖 |
 
 `mediagen image generate --help` 与 `mediagen video generate --help` 才是参考手册：
 全部参数、模型表、尺寸表、示例。下面只是简化版。
@@ -110,15 +111,29 @@ stdout 上每行打印一个绝对路径；`--json` 打印一个对象：
 ## 配置
 
 `config.toml` —— 你手动编辑的那个文件 —— 位于
-`$MEDIAGEN_CLI_CONFIG_DIR`、`$XDG_CONFIG_HOME/mediagen-cli`、
-`~/.config/mediagen-cli` 三者中第一个存在的。
+`$MEDIAGEN_CLI_CONFIG_DIR`、`$XDG_CONFIG_HOME/mediagen`、
+`~/.config/mediagen` 三者中第一个存在的。
 
 `auth.json`（权限 `600`）属于**状态而非配置**，单独存放：取
-`$MEDIAGEN_CLI_STATE_DIR`、`$XDG_STATE_HOME/mediagen-cli`、
-`~/.local/state/mediagen-cli` 三者中第一个。`~/.config` 是人们会同步、分享、提交到
+`$MEDIAGEN_CLI_STATE_DIR`、`$XDG_STATE_HOME/mediagen`、
+`~/.local/state/mediagen` 三者中第一个。`~/.config` 是人们会同步、分享、提交到
 仓库的目录，把密钥放在那里，一次 `.gitignore` 疏忽就等于泄露。state 目录按定义是
 「本机状态、不该被同步」，正合设备绑定的凭证。
 
+从 0.1.1 及更早版本升级：两个目录都去掉了 `-cli` 后缀，程序不会替你迁移。挪文件，别挪目录
+—— 新版本第一次运行就已经建好了新目录，`mv 目录 目录` 只会把你的配置埋进去：
+
+```bash
+mkdir -p ~/.config/mediagen ~/.local/state/mediagen
+mv ~/.config/mediagen-cli/config.toml ~/.config/mediagen/config.toml
+mv ~/.local/state/mediagen-cli/auth.json ~/.local/state/mediagen/auth.json
+```
+
+（设置了 `XDG_CONFIG_HOME` 或 `XDG_STATE_HOME` 的，路径相应改为 `<该目录>/mediagen-cli` →
+`<该目录>/mediagen`。用了 `MEDIAGEN_CLI_CONFIG_DIR` 或 `MEDIAGEN_CLI_STATE_DIR` 的，变量名
+没变，不需要动。`mediagen-cli` 路径不存在的那一行跳过就好 —— 大多数用户本来就没有
+`auth.json`。）
+
 ```toml
 default_provider = "volcengine"
 # output_dir = "./media-output"
@@ -214,7 +229,9 @@ OpenAI 兼容端点（`compatible-mode`）只在业务空间专属域名上提
 `timeout_seconds` 是**整个轮询窗口**，不是单次请求：建任务与每次轮询各自 60 秒，这样一个挂住
 的请求吃不掉预算；下载另有 600 秒，不计入预算。
 
-在 Agent 里用？`skills/mediagen/SKILL.md` 说明这个 CLI 能做什么、项目已有别的生成工具时该用哪个，
+在 Agent 里用？`mediagen skill install --dir <技能目录>` 会把这个包自带的
+`skills/mediagen/SKILL.md` 装到你 agent 已经在读的位置（例如 `--dir ~/.claude/skills`），升级后
+重跑一次即可覆盖旧版本。这份技能说明这个 CLI 能做什么、项目已有别的生成工具时该用哪个，
 以及哪些规则能避免白花钱。
 
 ---
@@ -228,6 +245,9 @@ npm test         # vitest，完全离线：所有地方的 fetch 都被打桩
 npm run dev -- image generate --help
 ```
 
+测试统一放在 `tests/`：一个模块一个文件，从 `../src/` 引入，不再与源码同目录；
+`vitest.config.ts` 只收集 `tests/**/*.test.ts`，`tsc --noEmit` 也一并检查它们。
+
 `src/cli.ts` 负责 commander 接线和错误到退出码的映射；`src/generate.ts` 是流水线
 （校验 → 解析 → 调用 → 下载 → 汇报）；`src/api/{qwen,ark,dashscope}.ts` 是
 `src/types.ts` 中 `DialectAdapter` 接缝背后的方言适配器，周围是 `config.ts`、

package/dist/cli.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import fs6 from "fs";
+import fs7 from "fs";
+import path7 from "path";
 import readline from "readline";
 import { Writable } from "stream";
-import { fileURLToPath, pathToFileURL } from "url";
+import { fileURLToPath as fileURLToPath2, pathToFileURL } from "url";
 import { Command, CommanderError } from "commander";
 import { parse as parseToml } from "smol-toml";
 
@@ -753,19 +754,20 @@ function getAdapter(apiType, task) {
 }
 
 // src/config.ts
+var APP_DIR_NAME = "mediagen";
 function configDir() {
   const override = process.env.MEDIAGEN_CLI_CONFIG_DIR;
   if (override) return override;
   const xdgConfigHome = process.env.XDG_CONFIG_HOME;
-  if (xdgConfigHome) return path2.join(xdgConfigHome, "mediagen-cli");
-  return path2.join(os.homedir(), ".config", "mediagen-cli");
+  if (xdgConfigHome) return path2.join(xdgConfigHome, APP_DIR_NAME);
+  return path2.join(os.homedir(), ".config", APP_DIR_NAME);
 }
 function stateDir() {
   const override = process.env.MEDIAGEN_CLI_STATE_DIR;
   if (override) return override;
   const xdgStateHome = process.env.XDG_STATE_HOME;
-  if (xdgStateHome) return path2.join(xdgStateHome, "mediagen-cli");
-  return path2.join(os.homedir(), ".local", "state", "mediagen-cli");
+  if (xdgStateHome) return path2.join(xdgStateHome, APP_DIR_NAME);
+  return path2.join(os.homedir(), ".local", "state", APP_DIR_NAME);
 }
 function configPath() {
   return path2.join(configDir(), "config.toml");
@@ -2352,6 +2354,130 @@ function describeError(err) {
   return "unknown error";
 }
 
+// src/skill.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import fs6 from "fs";
+import os3 from "os";
+import path6 from "path";
+import { fileURLToPath } from "url";
+function installSkill(sourceDir, targetDir, deps = {}) {
+  const root = path6.dirname(targetDir);
+  fs6.mkdirSync(root, { recursive: true });
+  const staging = stashPath(root, "install");
+  const retired = stashPath(root, "retired");
+  const cp = deps.cp ?? ((from, to) => fs6.cpSync(from, to, { recursive: true }));
+  const rename = deps.rename ?? ((from, to) => fs6.renameSync(from, to));
+  const existing = lstatOrUndefined(targetDir);
+  if (existing !== void 0 && !existing.isDirectory()) {
+    throw new UsageError(
+      `${targetDir} exists and is not a directory: move it aside, then run the command again`
+    );
+  }
+  let retiredPath;
+  let replaced = false;
+  try {
+    cp(sourceDir, staging);
+    if (existing !== void 0) {
+      rename(targetDir, retired);
+      retiredPath = retired;
+      replaced = true;
+    }
+    rename(staging, targetDir);
+    if (retiredPath !== void 0) {
+      fs6.rmSync(retiredPath, { recursive: true, force: true });
+      retiredPath = void 0;
+    }
+  } catch (error) {
+    if (retiredPath !== void 0) {
+      try {
+        rename(retiredPath, targetDir);
+        retiredPath = void 0;
+      } catch {
+        throw new Error(
+          `${messageOf(error)}; the previous copy could not be put back and is at ${retiredPath}`
+        );
+      }
+    }
+    throw error;
+  } finally {
+    try {
+      fs6.rmSync(staging, { recursive: true, force: true });
+    } catch {
+    }
+  }
+  return replaced;
+}
+function lstatOrUndefined(target) {
+  try {
+    return fs6.lstatSync(target);
+  } catch {
+    return void 0;
+  }
+}
+function stashPath(root, kind) {
+  return path6.join(root, `.mediagen-${kind}-${process.pid}-${randomUUID3().slice(0, 8)}`);
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function bundledSkillsDir() {
+  return fileURLToPath(new URL("../skills/", import.meta.url));
+}
+function bundledSkillNames(root = bundledSkillsDir()) {
+  try {
+    return fs6.readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
+  } catch (error) {
+    throw new Error(
+      `the skills this package ships were not found at ${root} (${messageOf(error)}); run mediagen from a normal npm install, where the skills/ directory ships beside dist/cli.js`
+    );
+  }
+}
+function installSkills(targetDir, deps = {}) {
+  const sourceRoot = deps.sourceRoot ?? bundledSkillsDir();
+  const names = bundledSkillNames(sourceRoot);
+  if (names.length === 0) {
+    throw new Error(
+      `no skills were found in ${sourceRoot}: the package is incomplete, reinstall mediagen`
+    );
+  }
+  const root = prepareTargetDir(targetDir);
+  return names.map((name) => ({
+    name,
+    path: path6.join(root, name),
+    replaced: installSkill(path6.join(sourceRoot, name), path6.join(root, name), deps)
+  }));
+}
+function prepareTargetDir(value) {
+  const trimmed = value.trim();
+  if (trimmed === "") {
+    throw new UsageError(
+      'a destination is required: pass --dir <path>, e.g. --dir "~/.claude/skills"'
+    );
+  }
+  const expanded = trimmed === "~" || trimmed.startsWith("~/") ? path6.join(os3.homedir(), trimmed.slice(1)) : trimmed;
+  const dir = path6.resolve(expanded);
+  if (fs6.existsSync(dir) && !fs6.statSync(dir).isDirectory()) {
+    throw new UsageError(
+      `--dir ${dir} is a file, not a directory: name the directory that holds skills`
+    );
+  }
+  try {
+    fs6.mkdirSync(dir, { recursive: true });
+  } catch (error) {
+    throw new UsageError(
+      `cannot create the skills directory ${dir}: ${messageOf(error)}; check --dir`
+    );
+  }
+  try {
+    fs6.accessSync(dir, fs6.constants.W_OK);
+  } catch (error) {
+    throw new UsageError(
+      `cannot write to the skills directory ${dir}: ${messageOf(error)}; check --dir`
+    );
+  }
+  return dir;
+}
+
 // src/cli.ts
 var ROOT_HELP = `
 Built for AI agents: explicit flags, no interactive prompts, machine-readable output.
@@ -2374,6 +2500,7 @@ Subcommands:
   config show       the resolved configuration, with a source note for each value
   config path       where config.toml lives
   config add        create a provider in config.toml (edit the file for anything else)
+  skill install     copy the agent skill this package ships into a directory you name
   video generate    create and pay for a video task, then save the result
   video status      look at one task once, and save its video if it finished
 
@@ -2579,7 +2706,7 @@ function addVideoOptions(command) {
 }
 function packageVersion() {
   try {
-    const raw = fs6.readFileSync(new URL("../package.json", import.meta.url), "utf8");
+    const raw = fs7.readFileSync(new URL("../package.json", import.meta.url), "utf8");
     const parsed = JSON.parse(raw);
     return typeof parsed.version === "string" ? parsed.version : void 0;
   } catch {
@@ -2619,6 +2746,10 @@ function createProgram(options = {}) {
   config.command("add <name>").description("Create a [providers.<name>] table in config.toml").option("--api-type <dialect>", "protocol dialect: openai, dashscope, ark or minimax").option("--base-url <url>", "the provider's origin, e.g. https://ark.cn-beijing.volces.com").option("--task <image|video>", "which task table to create (default: image)").option("--model <id>", "the model id this task defaults to").option("--api-key-env <VAR>", "environment variable holding this provider's key").option("--json", "print a JSON result").action(async (name, flags) => {
     runConfigAdd(name, flags);
   });
+  const skill = program.command("skill").description("Install the agent skill this package ships");
+  skill.command("install").description("Copy the skill into a directory an agent reads skills from, replacing an older copy").option("--dir <path>", "the skills directory, e.g. ~/.claude/skills (the skill lands in <path>/mediagen)").option("--json", "print a JSON result").action(async (flags) => {
+    runSkillInstall(flags);
+  });
   const image = program.command("image").description("Generate and edit images");
   const generate = image.command("generate").description("Generate an image from a prompt; add --image to edit").argument("<prompt>", "what to draw; quote it and describe the subject, style and text");
   addImageOptions(generate).addHelpText("after", imageHelpText("generate"));
@@ -2941,6 +3072,23 @@ function runConfigPath(flags) {
   }
   writeLine(configPath());
 }
+function runSkillInstall(flags) {
+  const installed = installSkills(flags.dir ?? "");
+  const container = path7.dirname(installed[0].path);
+  if (fs7.existsSync(path7.join(container, "SKILL.md"))) {
+    writeErrLine(
+      `note: ${container} already holds a SKILL.md; --dir names the directory that contains skills, so the skill landed in ${installed[0].path}`
+    );
+  }
+  if (flags.json === true) {
+    writeLine(JSON.stringify({ skills: installed }));
+    return;
+  }
+  for (const entry of installed) {
+    if (entry.replaced) writeErrLine(`replaced the existing copy at ${entry.path}`);
+  }
+  for (const entry of installed) writeLine(entry.path);
+}
 function runConfigAdd(name, flags) {
   const provider = name.trim();
   if (provider === "") throw new UsageError("a provider name is required");
@@ -2974,7 +3122,7 @@ function runConfigAdd(name, flags) {
     base_url: originBaseUrl(flags.baseUrl)
   };
   if (apiKeyEnv !== void 0) fields.api_key_env = apiKeyEnv;
-  const before = fs6.existsSync(file) ? fs6.readFileSync(file, "utf8") : "";
+  const before = fs7.existsSync(file) ? fs7.readFileSync(file, "utf8") : "";
   const beforeTable = before.trim() === "" ? void 0 : parseToml(before);
   if (apiType === "qwen") {
     writeErrLine('note: api_type "qwen" is a deprecated alias; writing api_type = "openai"');
@@ -3018,8 +3166,8 @@ function runConfigAdd(name, flags) {
 function runConfigShow(flags) {
   const config = loadConfig();
   const file = configPath();
-  const exists = fs6.existsSync(file);
-  const declared = exists ? parseToml(fs6.readFileSync(file, "utf8")) : {};
+  const exists = fs7.existsSync(file);
+  const declared = exists ? parseToml(fs7.readFileSync(file, "utf8")) : {};
   const defaultProvider = configuredValue(
     config.default_provider,
     declared.default_provider
@@ -3156,17 +3304,17 @@ function buildProviderView(name, entry) {
       if (block.path !== void 0) {
         taskView.path = { value: block.path, source: "config.toml" };
       }
-      const path6 = block.path ?? (effectiveDialect === void 0 ? void 0 : adapterPath(effectiveDialect, task));
+      const path8 = block.path ?? (effectiveDialect === void 0 ? void 0 : adapterPath(effectiveDialect, task));
       if (effectiveDialect === void 0) {
         taskView.endpoint_note = "api_type is not set";
-      } else if (path6 === void 0) {
+      } else if (path8 === void 0) {
         taskView.endpoint_note = `the ${effectiveDialect} dialect has no ${task} task`;
       } else if (base === void 0) {
         taskView.endpoint_note = "base_url is not a URL yet";
       } else if (block.path === void 0 && vendorPathIssue(base) !== void 0) {
         taskView.endpoint_note = "base_url carries a path; declare path = ... or use the origin";
       } else {
-        taskView.endpoint = `${base}${path6}`;
+        taskView.endpoint = `${base}${path8}`;
       }
       return taskView;
     }
@@ -3282,14 +3430,14 @@ function sameInstant(before, after) {
 function realHref(modulePath) {
   if (modulePath === void 0) return void 0;
   try {
-    return pathToFileURL(fs6.realpathSync(modulePath)).href;
+    return pathToFileURL(fs7.realpathSync(modulePath)).href;
   } catch {
     return void 0;
   }
 }
 function selfHref(moduleUrl) {
   try {
-    return realHref(fileURLToPath(moduleUrl));
+    return realHref(fileURLToPath2(moduleUrl));
   } catch {
     return void 0;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yandy0725/mediagen-cli",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Non-interactive image generation and editing, plus short video generation, for agents: qwen-image, doubao/seedream, doubao/seedance, MiniMax H3, files on disk, JSON output.",
   "type": "module",
   "license": "MIT",