@yandy0725/mediagen-cli 0.2.0 → 0.3.1

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
@@ -253,9 +254,21 @@ 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? Inside pi, install the skill as a pi package:
+
+```bash
+pi install npm:@yandy0725/mediagen-cli
+```
+
+That delivers `skills/mediagen/SKILL.md` only: pi never puts the `mediagen` command on
+`PATH`, so the CLI still comes from `npm install -g @yandy0725/mediagen-cli`. For any other
+agent, `mediagen skill install --dir <skills dir>` puts the same file where that agent
+already looks — e.g. `--dir ~/.claude/skills` — and re-running it after an upgrade replaces
+the old copy. Use one route, not both: pi loads skills by name, so the two copies collide — the
+directory you copied wins and pi only reports a `name "mediagen" collision` warning, which
+means a stale copy silently shadows the upgraded package. 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.
 
 ---
 
@@ -268,6 +281,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` 才是参考手册：
 全部参数、模型表、尺寸表、示例。下面只是简化版。
@@ -228,8 +229,18 @@ OpenAI 兼容端点（`compatible-mode`）只在业务空间专属域名上提
 `timeout_seconds` 是**整个轮询窗口**，不是单次请求：建任务与每次轮询各自 60 秒，这样一个挂住
 的请求吃不掉预算；下载另有 600 秒，不计入预算。
 
-在 Agent 里用？`skills/mediagen/SKILL.md` 说明这个 CLI 能做什么、项目已有别的生成工具时该用哪个，
-以及哪些规则能避免白花钱。
+在 Agent 里用？在 pi 里，把这份技能当成 pi 包安装：
+
+```bash
+pi install npm:@yandy0725/mediagen-cli
+```
+
+它只送 `skills/mediagen/SKILL.md`：pi 不会把 `mediagen` 命令放进 `PATH`，命令仍来自
+`npm install -g @yandy0725/mediagen-cli`。其他 agent 用 `mediagen skill install --dir <技能目录>`
+把同一个文件装到它已经在读的位置（例如 `--dir ~/.claude/skills`），升级后重跑一次即可覆盖。
+两条路线只选一条：pi 按技能名加载，两份同名技能会冲突——复制出来的那份胜出，pi 只给一条
+name "mediagen" collision 警告，于是旧副本会静默盖住升级后的包。这份技能说明这个 CLI
+能做什么、项目已有别的生成工具时该用哪个，以及哪些规则能避免白花钱。
 
 ---
 
@@ -242,6 +253,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";
 
@@ -2353,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.
@@ -2375,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
 
@@ -2580,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 {
@@ -2620,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"));
@@ -2942,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");
@@ -2975,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"');
@@ -3019,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
@@ -3157,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;
     }
@@ -3283,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.2.0",
+  "version": "0.3.1",
   "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",
@@ -11,7 +11,13 @@
     "dist",
     "skills"
   ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
   "keywords": [
+    "pi-package",
     "cli",
     "image",
     "image-generation",

package/skills/mediagen/SKILL.md

@@ -42,6 +42,15 @@ project has, or when the user asks for it by name.
 
 ## Setup, once
 
+This skill carries no binary: `mediagen` must already be on `PATH`, and the pi package that
+delivered this skill does not put it there. If `command -v mediagen` prints nothing:
+
+```bash
+npm install -g @yandy0725/mediagen-cli
+```
+
+Then one pass per machine:
+
 ```bash
 mediagen config show                          # any command writes and validates config.toml on first use
 mediagen login --api-key sk-...               # the key for the default provider; --provider <name> for another