persona-test-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 persona-test-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# persona-test-cli
+
+Ops CLI for a [persona-test](https://github.com/) deployment — admin and approved regular
+users can both use it. A regular user only ever sees/edits campaigns and personas they created
+themselves; admin sees and can edit everything.
+
+## Install
+
+```bash
+npm install -g persona-test-cli
+```
+
+## Getting started
+
+```bash
+# New account: register, then wait for an admin to approve it at /admin/users
+persona-test-cli register https://your-app.example.com
+
+# Log in — opens a browser to approve the CLI (device-code flow), no password typed into the terminal
+persona-test-cli login https://your-app.example.com
+
+# See everything at once
+persona-test-cli examples
+```
+
+`login` works for both admin (approve with the admin password login) and regular users (approve
+with their email/password login) — whichever session is active in the browser when the
+authorize page loads decides the scope of the issued token.
+
+## Commands
+
+| Command | Who | What |
+|---|---|---|
+| `register <baseUrl>` | anyone | Self-register (pending admin approval) |
+| `login <baseUrl>` | anyone | Device-code browser login |
+| `logout` | anyone | Clear the stored token |
+| `whoami` | anyone | Show current identity + available commands |
+| `campaigns list/create/edit/link/stats` | anyone | Share links — scoped to your own unless admin |
+| `personas list/create/edit` | anyone | Ad-copy personas — scoped to your own unless admin |
+| `events tail` | anyone | Poll new impression/click events |
+| `users list/approve/reject` | **admin only** | Registration approval queue |
+
+Run any command with `--help` for its full options and copy-pasteable examples.
+
+## Scripting / agent use
+
+- `--json` (or `PERSONA_TEST_CLI_JSON=1`): every command prints machine-readable JSON instead of
+  a table — success to stdout, `{"error": ..., "usage": ...}` to stderr on failure.
+- Exit codes: `0` ok · `1` unclassified · `2` not logged in / invalid token · `3` bad arguments ·
+  `4` not found · `5` forbidden (not yours).
+- `PERSONA_TEST_CLI_TOKEN=<token>`: skip login entirely — set once by a human via the normal
+  device-code flow, then exported into an automated environment.
+- `register --email <e> --password <p>`: non-interactive registration (fails fast instead of
+  hanging on a prompt when stdin isn't a TTY).
+- `login --no-open`: print the authorize URL instead of trying to launch a browser (headless/
+  sandboxed environments).
+
+## License
+
+MIT

package/dist/browser.js

@@ -0,0 +1,8 @@
+import { exec } from "node:child_process";
+/** Best-effort — callers shouldn't treat a failure to open a browser as fatal, just print the URL instead. */
+export function openBrowser(url) {
+    return new Promise((resolve) => {
+        const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+        exec(`${cmd} "${url}"`, () => resolve());
+    });
+}

package/dist/commands/campaigns.js

@@ -0,0 +1,132 @@
+import { apiRequest } from "../http.js";
+import { requireSession } from "../session.js";
+import { fail, EXIT_CODES } from "../errors.js";
+import { action, printJsonOrText, printTable } from "../output.js";
+export const CAMPAIGNS_LIST_USAGE = `  persona-test-cli campaigns list
+  persona-test-cli campaigns list --json`;
+export const CAMPAIGNS_CREATE_USAGE = `  persona-test-cli campaigns create --name "夏季活动" --slug summer --category MyApp
+  persona-test-cli campaigns create --name "夏季活动" --slug summer --category MyApp --persona-keys A,B1 --poster-headline "..." --poster-body "..."
+
+注:入口图(entryImageUrl)无法在终端里裁剪压缩,建好后请到网页后台(/dashboard 或 /admin)补传。`;
+export const CAMPAIGNS_EDIT_USAGE = `  persona-test-cli campaigns edit summer --poster-caption "扫码入群"
+  persona-test-cli campaigns edit summer --no-active`;
+export const CAMPAIGNS_LINK_USAGE = `  persona-test-cli campaigns link summer
+  persona-test-cli campaigns link summer --persona A`;
+export const CAMPAIGNS_STATS_USAGE = `  persona-test-cli campaigns stats summer`;
+const LIST_USAGE = CAMPAIGNS_LIST_USAGE;
+const CREATE_USAGE = CAMPAIGNS_CREATE_USAGE;
+const EDIT_USAGE = CAMPAIGNS_EDIT_USAGE;
+const LINK_USAGE = CAMPAIGNS_LINK_USAGE;
+const STATS_USAGE = CAMPAIGNS_STATS_USAGE;
+export function campaignsCommand(program) {
+    const cmd = program.command("campaigns").description("管理分享链接(campaigns)——admin 看到全部,普通用户只看到/编辑自己创建的");
+    cmd
+        .command("list")
+        .description("列出分享链接")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${LIST_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "GET", "/api/cli/campaigns");
+        const campaigns = data.campaigns;
+        printJsonOrText(data, () => printTable(campaigns.map((c) => ({
+            slug: String(c.slug),
+            name: String(c.name),
+            category: String(c.category),
+            active: c.active ? "是" : "否",
+            owner: String(c.owner ?? "内置/admin"),
+            展示: String(c.impressions),
+            点击: String(c.clicks),
+            CTR: `${c.ctr.toFixed(1)}%`,
+        }))));
+    }));
+    cmd
+        .command("create")
+        .description("创建一条分享链接(v1 仅支持文本字段,入口图请到网页后台补传)")
+        .requiredOption("--name <name>", "后台辨识用的名称")
+        .requiredOption("--slug <slug>", "分享链接 /s/xxx 里的 xxx,只能用字母/数字/短横线")
+        .requiredOption("--category <category>", "所属类别/项目")
+        .option("--persona-keys <keys>", "逗号分隔的画像 key(必须是你自己拥有、且属于这个 category 的画像)")
+        .option("--poster-caption <text>", "海报二维码下方文案", "扫码入群")
+        .option("--poster-headline <text>", "通用海报标题")
+        .option("--poster-body <text>", "通用海报正文")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${CREATE_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const personaKeys = opts.personaKeys ? opts.personaKeys.split(",").map((k) => k.trim()) : [];
+        const data = await apiRequest(baseUrl, token, "POST", "/api/cli/campaigns", {
+            name: opts.name,
+            slug: opts.slug,
+            category: opts.category,
+            personaKeys,
+            posterCaption: opts.posterCaption,
+            posterHeadline: opts.posterHeadline,
+            posterBody: opts.posterBody,
+        });
+        printJsonOrText(data, () => console.log(`已创建:${data.slug}`));
+    }));
+    cmd
+        .command("edit <slug>")
+        .description("编辑一条分享链接(只能改自己拥有的,admin 可以改任意一条)")
+        .option("--name <name>")
+        .option("--poster-caption <text>")
+        .option("--poster-headline <text>")
+        .option("--poster-body <text>")
+        .option("--active", "启用")
+        .option("--no-active", "停用")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${EDIT_USAGE}`)
+        .action(action(async (slug, opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const patch = {};
+        if (opts.name !== undefined)
+            patch.name = opts.name;
+        if (opts.posterCaption !== undefined)
+            patch.posterCaption = opts.posterCaption;
+        if (opts.posterHeadline !== undefined)
+            patch.posterHeadline = opts.posterHeadline;
+        if (opts.posterBody !== undefined)
+            patch.posterBody = opts.posterBody;
+        if (opts.active !== undefined)
+            patch.active = opts.active;
+        if (Object.keys(patch).length === 0) {
+            fail("至少要传一个要改的字段", { usage: EDIT_USAGE, exitCode: EXIT_CODES.validation });
+        }
+        const data = await apiRequest(baseUrl, token, "PATCH", `/api/cli/campaigns/${slug}`, patch);
+        printJsonOrText(data, () => console.log(`已更新:${slug}`));
+    }));
+    cmd
+        .command("link <slug>")
+        .description("打印分享链接;加 --persona 打印锁定某个画像的专属链接")
+        .option("--persona <key>", "锁定某个画像的 key")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${LINK_USAGE}`)
+        .action(action(async (slug, opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "GET", `/api/cli/campaigns/${slug}`);
+        const personas = data.personas;
+        if (opts.persona && !personas.some((p) => p.key === opts.persona)) {
+            fail(`画像 key "${opts.persona}" 不在这个分享链接里,可选:${personas.map((p) => p.key).join(", ") || "(无)"}`, { usage: LINK_USAGE, exitCode: EXIT_CODES.validation });
+        }
+        const url = opts.persona
+            ? `${baseUrl}/s/${slug}?p=${encodeURIComponent(opts.persona)}`
+            : `${baseUrl}/s/${slug}`;
+        printJsonOrText({ url }, () => console.log(url));
+    }));
+    cmd
+        .command("stats <slug>")
+        .description("查看一条分享链接的展示/点击/CTR")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${STATS_USAGE}`)
+        .action(action(async (slug, opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "GET", `/api/cli/campaigns/${slug}`);
+        printJsonOrText(data, () => {
+            console.log(`${data.name}(${data.slug}) · ${data.category}`);
+            console.log(`归属:${data.owner ?? "内置/admin"} · ${data.active ? "启用" : "停用"}`);
+            console.log(`展示 ${data.impressions} · 点击 ${data.clicks} · CTR ${data.ctr.toFixed(1)}%`);
+            console.log(`${data.personas.length} 个关联画像`);
+        });
+    }));
+}

package/dist/commands/events.js

@@ -0,0 +1,46 @@
+import { apiRequest } from "../http.js";
+import { requireSession } from "../session.js";
+import { jsonMode } from "../output.js";
+import { action } from "../output.js";
+export const EVENTS_TAIL_USAGE = `  persona-test-cli events tail
+  persona-test-cli events tail --slug summer --interval 3`;
+const TAIL_USAGE = EVENTS_TAIL_USAGE;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function eventsCommand(program) {
+    const cmd = program.command("events").description("查看展示/点击事件");
+    cmd
+        .command("tail")
+        .description("轮询打印新的展示/点击事件,Ctrl+C 退出")
+        .option("--slug <slug>", "只看某条分享链接的事件")
+        .option("--interval <seconds>", "轮询间隔秒数", "5")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${TAIL_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const intervalMs = Math.max(1, Number(opts.interval) || 5) * 1000;
+        let since = new Date(0).toISOString();
+        if (!jsonMode) {
+            console.log(`轮询中(每 ${opts.interval} 秒)... Ctrl+C 退出`);
+        }
+        for (;;) {
+            const query = new URLSearchParams({ since, limit: "50" });
+            if (opts.slug)
+                query.set("slug", opts.slug);
+            const data = await apiRequest(baseUrl, token, "GET", `/api/cli/events?${query}`);
+            const events = data.events;
+            since = data.nextSince;
+            for (const e of events) {
+                if (jsonMode) {
+                    console.log(JSON.stringify(e));
+                }
+                else {
+                    const label = e.type === "click" ? "点击" : "展示";
+                    console.log(`[${e.createdAt}] ${label} ${e.campaignSlug} · ${e.personaCategory}/${e.personaKey} · ${e.deviceType ?? "未知"}${e.isWeChat ? " · 微信内" : ""}`);
+                }
+            }
+            await sleep(intervalMs);
+        }
+    }));
+}

package/dist/commands/examples.js

@@ -0,0 +1,39 @@
+import { REGISTER_EXAMPLES } from "./register.js";
+import { LOGIN_EXAMPLES } from "./login.js";
+import { LOGOUT_EXAMPLES } from "./logout.js";
+import { WHOAMI_EXAMPLES } from "./whoami.js";
+import { CAMPAIGNS_LIST_USAGE, CAMPAIGNS_CREATE_USAGE, CAMPAIGNS_EDIT_USAGE, CAMPAIGNS_LINK_USAGE, CAMPAIGNS_STATS_USAGE, } from "./campaigns.js";
+import { PERSONAS_LIST_USAGE, PERSONAS_CREATE_USAGE, PERSONAS_EDIT_USAGE } from "./personas.js";
+import { EVENTS_TAIL_USAGE } from "./events.js";
+import { USERS_LIST_USAGE, USERS_APPROVE_USAGE, USERS_REJECT_USAGE } from "./users.js";
+const SECTIONS = [
+    ["register", REGISTER_EXAMPLES],
+    ["login", LOGIN_EXAMPLES],
+    ["logout", LOGOUT_EXAMPLES],
+    ["whoami", WHOAMI_EXAMPLES],
+    ["campaigns list", CAMPAIGNS_LIST_USAGE],
+    ["campaigns create", CAMPAIGNS_CREATE_USAGE],
+    ["campaigns edit", CAMPAIGNS_EDIT_USAGE],
+    ["campaigns link", CAMPAIGNS_LINK_USAGE],
+    ["campaigns stats", CAMPAIGNS_STATS_USAGE],
+    ["personas list", PERSONAS_LIST_USAGE],
+    ["personas create", PERSONAS_CREATE_USAGE],
+    ["personas edit", PERSONAS_EDIT_USAGE],
+    ["events tail", EVENTS_TAIL_USAGE],
+    ["users list [仅 admin]", USERS_LIST_USAGE],
+    ["users approve [仅 admin]", USERS_APPROVE_USAGE],
+    ["users reject [仅 admin]", USERS_REJECT_USAGE],
+];
+export function examplesCommand(program) {
+    program
+        .command("examples")
+        .description("一次性打印所有子命令的示例(agent 第一次用之前可以先跑这个)")
+        .action(() => {
+        console.log("退出码约定:0 成功 · 1 未分类错误 · 2 未登录/token 失效 · 3 参数校验失败 · 4 不存在 · 5 无权限\n");
+        for (const [name, examples] of SECTIONS) {
+            console.log(`# ${name}`);
+            console.log(examples);
+            console.log("");
+        }
+    });
+}

package/dist/commands/login.js

@@ -0,0 +1,62 @@
+import { publicRequest, apiRequest } from "../http.js";
+import { openBrowser } from "../browser.js";
+import { fail, EXIT_CODES } from "../errors.js";
+import { action, printJsonOrText } from "../output.js";
+import { normalizeBaseUrl, saveProfile } from "../config.js";
+export const LOGIN_EXAMPLES = `  persona-test-cli login https://your-app.example.com
+  persona-test-cli login https://your-app.example.com --no-open
+  persona-test-cli login https://your-app.example.com --token <已有的 token,跳过整个设备码流程>`;
+const POLL_INTERVAL_MS = 2000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export function loginCommand(program) {
+    program
+        .command("login <baseUrl>")
+        .description("设备码登录:自动打开浏览器授权,或用 --token 直接注入一个已有 token")
+        .option("--no-open", "不自动打开浏览器,只打印授权链接(无 GUI/沙盒环境用)")
+        .option("--wait <seconds>", "轮询超时秒数", "300")
+        .option("--token <token>", "跳过设备码流程,直接用这个 token(会先校验有效性)")
+        .addHelpText("after", `\n示例:\n${LOGIN_EXAMPLES}`)
+        .action(action(async (baseUrlArg, opts) => {
+        const baseUrl = normalizeBaseUrl(baseUrlArg);
+        if (opts.token) {
+            const who = await apiRequest(baseUrl, opts.token, "GET", "/api/cli/whoami");
+            const scope = who.scope;
+            const email = who.email;
+            saveProfile(baseUrl, { token: opts.token, scope, email, savedAt: new Date().toISOString() });
+            printJsonOrText({ ok: true, scope, email }, () => {
+                console.log(`已登录(${scope === "admin" ? "管理员" : email})`);
+            });
+            return;
+        }
+        const start = await publicRequest(baseUrl, "POST", "/api/auth/device/start");
+        const code = start.code;
+        const fullUrl = `${baseUrl}${start.authorizeUrl}`;
+        console.error(`请在浏览器里完成授权:${fullUrl}`);
+        if (opts.open) {
+            await openBrowser(fullUrl);
+        }
+        const timeoutMs = Math.max(10, Number(opts.wait) || 300) * 1000;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const poll = await publicRequest(baseUrl, "GET", `/api/auth/device/poll?code=${code}`);
+            const status = poll.status;
+            if (status === "approved") {
+                const token = poll.token;
+                const scope = poll.scope;
+                const email = poll.email;
+                saveProfile(baseUrl, { token, scope, email, savedAt: new Date().toISOString() });
+                printJsonOrText({ ok: true, scope, email }, () => {
+                    console.log(`已登录(${scope === "admin" ? "管理员" : email})`);
+                });
+                return;
+            }
+            if (status === "denied") {
+                fail("授权请求被拒绝", { exitCode: EXIT_CODES.forbidden });
+            }
+            await sleep(POLL_INTERVAL_MS);
+        }
+        fail(`等待授权超时(${opts.wait} 秒),请重新运行 login`, { usage: LOGIN_EXAMPLES });
+    }));
+}

package/dist/commands/logout.js

@@ -0,0 +1,23 @@
+import { fail, EXIT_CODES } from "../errors.js";
+import { action, printJsonOrText } from "../output.js";
+import { normalizeBaseUrl, resolveBaseUrl, clearProfile } from "../config.js";
+export const LOGOUT_EXAMPLES = `  persona-test-cli logout
+  persona-test-cli logout --base-url https://your-app.example.com`;
+export function logoutCommand(program) {
+    program
+        .command("logout")
+        .description("清除本地存的登录 token")
+        .option("--base-url <url>", "默认清除上次登录的那个 base url")
+        .addHelpText("after", `\n示例:\n${LOGOUT_EXAMPLES}`)
+        .action(action(async (opts) => {
+        const baseUrl = resolveBaseUrl(opts.baseUrl);
+        if (!baseUrl) {
+            fail("没有已登录的 base url,加 --base-url 指定一个", {
+                usage: LOGOUT_EXAMPLES,
+                exitCode: EXIT_CODES.validation,
+            });
+        }
+        clearProfile(normalizeBaseUrl(baseUrl));
+        printJsonOrText({ ok: true, baseUrl }, () => console.log(`已退出登录:${baseUrl}`));
+    }));
+}

package/dist/commands/personas.js

@@ -0,0 +1,93 @@
+import { apiRequest } from "../http.js";
+import { requireSession } from "../session.js";
+import { fail, EXIT_CODES } from "../errors.js";
+import { action, printJsonOrText, printTable } from "../output.js";
+export const PERSONAS_LIST_USAGE = `  persona-test-cli personas list
+  persona-test-cli personas list --category MyApp --json`;
+export const PERSONAS_CREATE_USAGE = `  persona-test-cli personas create --category MyApp --key A --title "核心契合" --headline "..." --body "..."`;
+export const PERSONAS_EDIT_USAGE = `  persona-test-cli personas edit --category MyApp --key A --title "新标题"
+  persona-test-cli personas edit --category MyApp --key A --no-active`;
+const LIST_USAGE = PERSONAS_LIST_USAGE;
+const CREATE_USAGE = PERSONAS_CREATE_USAGE;
+const EDIT_USAGE = PERSONAS_EDIT_USAGE;
+export function personasCommand(program) {
+    const cmd = program.command("personas").description("管理画像(personas)——admin 看到全部,普通用户只看到/编辑自己创建的");
+    cmd
+        .command("list")
+        .description("列出画像")
+        .option("--category <category>", "只看某个类别")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${LIST_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const query = opts.category ? `?category=${encodeURIComponent(opts.category)}` : "";
+        const data = await apiRequest(baseUrl, token, "GET", `/api/cli/personas${query}`);
+        const personas = data.personas;
+        printJsonOrText(data, () => printTable(personas.map((p) => ({
+            category: String(p.category),
+            key: String(p.key),
+            title: String(p.title),
+            active: p.active ? "是" : "否",
+            weight: String(p.weight),
+            owner: String(p.owner ?? "内置/admin"),
+        }))));
+    }));
+    cmd
+        .command("create")
+        .description("创建一个画像")
+        .requiredOption("--category <category>")
+        .requiredOption("--key <key>", "同一类别内唯一")
+        .requiredOption("--title <title>")
+        .requiredOption("--headline <headline>", "文案标题")
+        .requiredOption("--body <body>", "文案正文")
+        .option("--weight <n>", "抽取权重,默认 1", "1")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${CREATE_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "POST", "/api/cli/personas", {
+            category: opts.category,
+            key: opts.key,
+            title: opts.title,
+            headline: opts.headline,
+            body: opts.body,
+            weight: Number(opts.weight) || 1,
+        });
+        printJsonOrText(data, () => console.log(`已创建:${opts.category}/${opts.key}`));
+    }));
+    cmd
+        .command("edit")
+        .description("编辑一个画像(只能改自己拥有的,admin 可以改任意一个)")
+        .requiredOption("--category <category>", "定位用")
+        .requiredOption("--key <key>", "定位用")
+        .option("--title <title>")
+        .option("--headline <headline>")
+        .option("--body <body>")
+        .option("--weight <n>")
+        .option("--active")
+        .option("--no-active")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${EDIT_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const patch = { category: opts.category, key: opts.key };
+        if (opts.title !== undefined)
+            patch.title = opts.title;
+        if (opts.headline !== undefined)
+            patch.headline = opts.headline;
+        if (opts.body !== undefined)
+            patch.body = opts.body;
+        if (opts.weight !== undefined)
+            patch.weight = Number(opts.weight) || 1;
+        if (opts.active !== undefined)
+            patch.active = opts.active;
+        if (Object.keys(patch).length <= 2) {
+            fail("至少要传一个要改的字段(title/headline/body/weight/active)", {
+                usage: EDIT_USAGE,
+                exitCode: EXIT_CODES.validation,
+            });
+        }
+        const data = await apiRequest(baseUrl, token, "PATCH", "/api/cli/personas", patch);
+        printJsonOrText(data, () => console.log(`已更新:${opts.category}/${opts.key}`));
+    }));
+}

package/dist/commands/register.js

@@ -0,0 +1,35 @@
+import { publicRequest } from "../http.js";
+import { isInteractive, promptText, promptHidden } from "../prompt.js";
+import { fail, EXIT_CODES } from "../errors.js";
+import { action, printJsonOrText } from "../output.js";
+import { normalizeBaseUrl } from "../config.js";
+export const REGISTER_EXAMPLES = `  persona-test-cli register https://your-app.example.com
+  persona-test-cli register https://your-app.example.com --email me@example.com --password ******** --json`;
+export function registerCommand(program) {
+    program
+        .command("register <baseUrl>")
+        .description("自助注册一个普通用户账号(注册后需要 admin 在 /admin/users 审核通过才能登录)")
+        .option("--email <email>", "邮箱(作为用户名)")
+        .option("--password <password>", "密码(至少 8 位)")
+        .addHelpText("after", `\n示例:\n${REGISTER_EXAMPLES}`)
+        .action(action(async (baseUrlArg, opts) => {
+        const baseUrl = normalizeBaseUrl(baseUrlArg);
+        let email = opts.email;
+        let password = opts.password;
+        if (!email || !password) {
+            if (!isInteractive()) {
+                fail("非交互式环境需要传 --email 和 --password", {
+                    usage: REGISTER_EXAMPLES,
+                    exitCode: EXIT_CODES.validation,
+                });
+            }
+            email ??= await promptText("邮箱: ");
+            password ??= await promptHidden("密码(至少 8 位): ");
+        }
+        await publicRequest(baseUrl, "POST", "/api/auth/register", { email, password });
+        printJsonOrText({ ok: true, email, status: "pending" }, () => {
+            console.log(`注册成功:${email}`);
+            console.log("等待管理员审核通过后即可登录(admin 在 /admin/users 里操作)。");
+        });
+    }));
+}

package/dist/commands/users.js

@@ -0,0 +1,56 @@
+import { apiRequest } from "../http.js";
+import { requireSession } from "../session.js";
+import { action, printJsonOrText, printTable } from "../output.js";
+export const USERS_LIST_USAGE = `  persona-test-cli users list
+  persona-test-cli users list --status pending`;
+export const USERS_APPROVE_USAGE = `  persona-test-cli users approve <userId>`;
+export const USERS_REJECT_USAGE = `  persona-test-cli users reject <userId>`;
+const LIST_USAGE = USERS_LIST_USAGE;
+const APPROVE_USAGE = USERS_APPROVE_USAGE;
+const REJECT_USAGE = USERS_REJECT_USAGE;
+/** [仅 admin] — a non-admin token gets a clear 403 from /api/cli/users*, surfaced as a normal CliError. */
+export function usersCommand(program) {
+    const cmd = program.command("users").description("[仅 admin] 审核注册申请");
+    cmd
+        .command("list")
+        .description("[仅 admin] 列出注册用户")
+        .option("--status <status>", "pending | active | rejected")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${LIST_USAGE}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const query = opts.status ? `?status=${encodeURIComponent(opts.status)}` : "";
+        const data = await apiRequest(baseUrl, token, "GET", `/api/cli/users${query}`);
+        const users = data.users;
+        printJsonOrText(data, () => printTable(users.map((u) => ({
+            id: String(u.id),
+            email: String(u.email),
+            status: String(u.status),
+            注册于: String(u.createdAt),
+        }))));
+    }));
+    cmd
+        .command("approve <userId>")
+        .description("[仅 admin] 批准一个待审核用户")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${APPROVE_USAGE}`)
+        .action(action(async (userId, opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "PATCH", `/api/cli/users/${userId}`, {
+            status: "active",
+        });
+        printJsonOrText(data, () => console.log(`已批准:${userId}`));
+    }));
+    cmd
+        .command("reject <userId>")
+        .description("[仅 admin] 拒绝一个待审核用户")
+        .option("--base-url <url>")
+        .addHelpText("after", `\n示例:\n${REJECT_USAGE}`)
+        .action(action(async (userId, opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const data = await apiRequest(baseUrl, token, "PATCH", `/api/cli/users/${userId}`, {
+            status: "rejected",
+        });
+        printJsonOrText(data, () => console.log(`已拒绝:${userId}`));
+    }));
+}

package/dist/commands/whoami.js

@@ -0,0 +1,26 @@
+import { apiRequest } from "../http.js";
+import { requireSession } from "../session.js";
+import { action, printJsonOrText } from "../output.js";
+export const WHOAMI_EXAMPLES = `  persona-test-cli whoami
+  persona-test-cli whoami --base-url https://your-app.example.com --json`;
+export function whoamiCommand(program) {
+    program
+        .command("whoami")
+        .description("查看当前登录身份;登录成功时也会自动打印一次角色和可用命令")
+        .option("--base-url <url>", "默认用上次登录的 base url")
+        .addHelpText("after", `\n示例:\n${WHOAMI_EXAMPLES}`)
+        .action(action(async (opts) => {
+        const { baseUrl, token } = requireSession(opts.baseUrl);
+        const who = await apiRequest(baseUrl, token, "GET", "/api/cli/whoami");
+        const scope = who.scope;
+        const email = who.email;
+        const commands = scope === "admin"
+            ? "campaigns, personas, events, users"
+            : "campaigns, personas, events";
+        printJsonOrText({ baseUrl, scope, email }, () => {
+            console.log(`身份: ${scope === "admin" ? "管理员" : email}`);
+            console.log(`base url: ${baseUrl}`);
+            console.log(`可用命令: ${commands}`);
+        });
+    }));
+}

package/dist/config.js

@@ -0,0 +1,56 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function configDir() {
+    const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
+    return join(base, "persona-test-cli");
+}
+function configPath() {
+    return join(configDir(), "config.json");
+}
+function readConfig() {
+    try {
+        return JSON.parse(readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        return { profiles: {} };
+    }
+}
+function writeConfig(config) {
+    mkdirSync(configDir(), { recursive: true });
+    writeFileSync(configPath(), JSON.stringify(config, null, 2), { mode: 0o600 });
+}
+export function normalizeBaseUrl(url) {
+    return url.replace(/\/+$/, "");
+}
+export function saveProfile(baseUrl, profile) {
+    const config = readConfig();
+    config.profiles[normalizeBaseUrl(baseUrl)] = profile;
+    config.lastBaseUrl = normalizeBaseUrl(baseUrl);
+    writeConfig(config);
+}
+export function clearProfile(baseUrl) {
+    const config = readConfig();
+    delete config.profiles[normalizeBaseUrl(baseUrl)];
+    writeConfig(config);
+}
+export function getProfile(baseUrl) {
+    return readConfig().profiles[normalizeBaseUrl(baseUrl)];
+}
+/** Explicit --base-url wins; then PERSONA_TEST_CLI_URL; then whichever base URL was last logged into. */
+export function resolveBaseUrl(explicit) {
+    if (explicit)
+        return normalizeBaseUrl(explicit);
+    if (process.env.PERSONA_TEST_CLI_URL)
+        return normalizeBaseUrl(process.env.PERSONA_TEST_CLI_URL);
+    return readConfig().lastBaseUrl;
+}
+/** PERSONA_TEST_CLI_TOKEN always wins (agent-friendly: skip login entirely) — falls back to the stored profile. */
+export function resolveToken(baseUrl) {
+    if (process.env.PERSONA_TEST_CLI_TOKEN)
+        return process.env.PERSONA_TEST_CLI_TOKEN;
+    return getProfile(baseUrl)?.token;
+}
+export function configFileExists() {
+    return existsSync(configPath());
+}

package/dist/errors.js

@@ -0,0 +1,23 @@
+// Exit code convention (documented in `persona-test-cli examples` and each
+// command's --help): agents/scripts can branch on the code alone without
+// parsing text.
+export const EXIT_CODES = {
+    ok: 0,
+    generic: 1,
+    unauthorized: 2,
+    validation: 3,
+    notFound: 4,
+    forbidden: 5,
+};
+export class CliError extends Error {
+    exitCode;
+    usage;
+    constructor(message, opts = {}) {
+        super(message);
+        this.exitCode = opts.exitCode ?? EXIT_CODES.generic;
+        this.usage = opts.usage;
+    }
+}
+export function fail(message, opts = {}) {
+    throw new CliError(message, opts);
+}

package/dist/http.js

@@ -0,0 +1,71 @@
+import { CliError, EXIT_CODES } from "./errors.js";
+function exitCodeForStatus(status) {
+    if (status === 401)
+        return EXIT_CODES.unauthorized;
+    if (status === 403)
+        return EXIT_CODES.forbidden;
+    if (status === 404)
+        return EXIT_CODES.notFound;
+    if (status === 400 || status === 409 || status === 410)
+        return EXIT_CODES.validation;
+    return EXIT_CODES.generic;
+}
+export async function apiRequest(baseUrl, token, method, path, body) {
+    if (!token) {
+        throw new CliError("未登录,请先运行 `persona-test-cli login <baseUrl>`", {
+            exitCode: EXIT_CODES.unauthorized,
+        });
+    }
+    let res;
+    try {
+        res = await fetch(`${baseUrl}${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(body !== undefined ? { "Content-Type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (err) {
+        throw new CliError(`无法连接到 ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let json = null;
+    try {
+        json = (await res.json());
+    }
+    catch {
+        // Non-JSON response body — fall through with json=null.
+    }
+    if (!res.ok) {
+        const message = json?.error ?? `请求失败(HTTP ${res.status})`;
+        throw new CliError(message, { exitCode: exitCodeForStatus(res.status) });
+    }
+    return json ?? {};
+}
+/** Unauthenticated request — used only by the register/device-flow endpoints under /api/auth/*. */
+export async function publicRequest(baseUrl, method, path, body) {
+    let res;
+    try {
+        res = await fetch(`${baseUrl}${path}`, {
+            method,
+            headers: body !== undefined ? { "Content-Type": "application/json" } : undefined,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    }
+    catch (err) {
+        throw new CliError(`无法连接到 ${baseUrl}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    let json = null;
+    try {
+        json = (await res.json());
+    }
+    catch {
+        // ignore
+    }
+    if (!res.ok) {
+        const message = json?.error ?? `请求失败(HTTP ${res.status})`;
+        throw new CliError(message, { exitCode: exitCodeForStatus(res.status) });
+    }
+    return json ?? {};
+}

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerCommand } from "./commands/register.js";
+import { loginCommand } from "./commands/login.js";
+import { logoutCommand } from "./commands/logout.js";
+import { whoamiCommand } from "./commands/whoami.js";
+import { campaignsCommand } from "./commands/campaigns.js";
+import { personasCommand } from "./commands/personas.js";
+import { eventsCommand } from "./commands/events.js";
+import { usersCommand } from "./commands/users.js";
+import { examplesCommand } from "./commands/examples.js";
+const program = new Command();
+program
+    .name("persona-test-cli")
+    .description("persona-test 运维 CLI —— admin 和已审核通过的普通用户都能用,普通用户只能看到/编辑自己创建的 campaigns/personas。\n" +
+    "先跑一次 `persona-test-cli examples` 看全部子命令的可复制示例。")
+    .option("--json", "所有命令输出纯 JSON(成功到 stdout,失败到 stderr),适合脚本/agent 调用")
+    .configureHelp({ sortSubcommands: true });
+registerCommand(program);
+loginCommand(program);
+logoutCommand(program);
+whoamiCommand(program);
+campaignsCommand(program);
+personasCommand(program);
+eventsCommand(program);
+usersCommand(program); // [仅 admin] — see the description on each of its subcommands
+examplesCommand(program);
+program.parseAsync(process.argv);

package/dist/output.js

@@ -0,0 +1,64 @@
+import { CliError, EXIT_CODES } from "./errors.js";
+// Checked directly against argv/env rather than through commander's option
+// inheritance — simpler to get right, and needs to be readable from any
+// command module without threading commander's Command instance around.
+export const jsonMode = process.argv.includes("--json") || process.env.PERSONA_TEST_CLI_JSON === "1";
+export function printJsonOrText(data, text) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data));
+    }
+    else {
+        text();
+    }
+}
+export function printError(err) {
+    if (err instanceof CliError) {
+        if (jsonMode) {
+            console.error(JSON.stringify({ error: err.message, usage: err.usage }));
+        }
+        else {
+            console.error(`错误: ${err.message}`);
+            if (err.usage) {
+                console.error(`\n用法示例:\n${err.usage}`);
+            }
+            else {
+                console.error("\n加 --help 查看完整参数说明。");
+            }
+        }
+        process.exitCode = err.exitCode;
+        return;
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    if (jsonMode) {
+        console.error(JSON.stringify({ error: message }));
+    }
+    else {
+        console.error(`错误: ${message}`);
+    }
+    process.exitCode = EXIT_CODES.generic;
+}
+/** Wraps a command action so thrown CliErrors (or anything else) are printed uniformly and set the right exit code. */
+export function action(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            printError(err);
+        }
+    };
+}
+export function printTable(rows) {
+    if (rows.length === 0) {
+        console.log("(无数据)");
+        return;
+    }
+    const columns = Object.keys(rows[0]);
+    const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => (r[c] ?? "").length)));
+    const line = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join("  ");
+    console.log(line(columns));
+    console.log(line(widths.map((w) => "-".repeat(w))));
+    for (const row of rows) {
+        console.log(line(columns.map((c) => row[c] ?? "")));
+    }
+}

package/dist/prompt.js

@@ -0,0 +1,45 @@
+import readline from "node:readline";
+export function isInteractive() {
+    return Boolean(process.stdin.isTTY);
+}
+export function promptText(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+/** Hand-rolled masked input (no readline echo suppression built in) — no extra dependency needed for this. */
+export function promptHidden(question) {
+    return new Promise((resolve) => {
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        stdout.write(question);
+        stdin.resume();
+        stdin.setRawMode?.(true);
+        stdin.setEncoding("utf8");
+        let input = "";
+        function onData(char) {
+            const code = char.charCodeAt(0);
+            if (char === "\n" || char === "\r" || code === 4) {
+                stdin.setRawMode?.(false);
+                stdin.pause();
+                stdin.removeListener("data", onData);
+                stdout.write("\n");
+                resolve(input);
+                return;
+            }
+            if (code === 3) {
+                process.exit(130); // Ctrl+C
+            }
+            if (code === 127 || code === 8) {
+                input = input.slice(0, -1);
+                return;
+            }
+            input += char;
+        }
+        stdin.on("data", onData);
+    });
+}

package/dist/session.js

@@ -0,0 +1,18 @@
+import { fail, EXIT_CODES } from "./errors.js";
+import { resolveBaseUrl, resolveToken } from "./config.js";
+/** Shared by every data command (campaigns/personas/events/users/whoami) — resolves --base-url + token, or fails with a clear "please login" message. */
+export function requireSession(baseUrlOpt) {
+    const baseUrl = resolveBaseUrl(baseUrlOpt);
+    if (!baseUrl) {
+        fail("不知道要连哪个地址,加 --base-url <url> 或先运行 `persona-test-cli login <baseUrl>`", {
+            exitCode: EXIT_CODES.validation,
+        });
+    }
+    const token = resolveToken(baseUrl);
+    if (!token) {
+        fail(`未登录 ${baseUrl},请先运行 \`persona-test-cli login ${baseUrl}\``, {
+            exitCode: EXIT_CODES.unauthorized,
+        });
+    }
+    return { baseUrl, token };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "persona-test-cli",
+  "version": "0.1.0",
+  "description": "运维 CLI for persona-test — admin 和已审核通过的普通用户都能用；设备码浏览器授权登录，管理分享链接(campaigns)和画像(personas)，普通用户只能看到/编辑自己创建的。",
+  "type": "module",
+  "bin": {
+    "persona-test-cli": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && chmod +x dist/index.js",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx index.ts"
+  },
+  "dependencies": {
+    "commander": "^15.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.23.12",
+    "typescript": "^5"
+  },
+  "license": "MIT"
+}