@qzhuli/qzhuli-cli 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 H
+
+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/dist/cmd.js

@@ -11435,14 +11435,191 @@ function tf(key, values) {
 
 // src/iostreams.ts
 init_cjs_shims();
+
+// src/internal/config/index.ts
+init_cjs_shims();
+
+// src/internal/config/credentials.ts
+init_cjs_shims();
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+function loadCredentials(configDir) {
+  const path = (0, import_node_path.join)(configDir, "credentials.json");
+  if (!(0, import_node_fs.existsSync)(path)) {
+    return null;
+  }
+  try {
+    const raw = (0, import_node_fs.readFileSync)(path, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    console.error("[WARN] credentials.json is corrupted, skipping \u2014 please re-authenticate");
+    return null;
+  }
+}
+function saveCredentials(configDir, creds) {
+  const path = (0, import_node_path.join)(configDir, "credentials.json");
+  ensureConfigDirectory(configDir);
+  (0, import_node_fs.writeFileSync)(path, JSON.stringify(creds, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+}
+function ensureConfigDirectory(configDir) {
+  if (!(0, import_node_fs.existsSync)(configDir)) {
+    (0, import_node_fs.mkdirSync)(configDir, { recursive: true });
+  }
+}
+function clearCredentials(configDir) {
+  const path = (0, import_node_path.join)(configDir, "credentials.json");
+  if ((0, import_node_fs.existsSync)(path)) {
+    (0, import_node_fs.rmSync)(path);
+  }
+}
+function hasCredentials(configDir) {
+  const creds = loadCredentials(configDir);
+  return !!(creds?.uid && creds?.tk && creds?.token);
+}
+
+// src/internal/config/directory.ts
+init_cjs_shims();
+var import_node_os = require("os");
+var import_node_path2 = require("path");
+var PROJECT_CONFIG_DIR = (0, import_node_path2.resolve)(process.cwd(), ".qzhuli-cli");
+var USER_CONFIG_DIR = (0, import_node_path2.resolve)((0, import_node_os.homedir)(), ".qzhuli-cli");
+function getConfigDirectory(env) {
+  return env === "production" ? USER_CONFIG_DIR : PROJECT_CONFIG_DIR;
+}
+
+// src/internal/config/environment.ts
+init_cjs_shims();
+var TEST_CONFIG = {
+  name: "test",
+  baseURL: "https://test.client.qzhuli.com",
+  wsURL: "wss://test.im.qzhuli.com/ws"
+};
+var PRODUCTION_CONFIG = {
+  name: "production",
+  baseURL: "https://client.qzhuli.com",
+  wsURL: "wss://im.qzhuli.com/ws"
+};
+var ENV_MAP = {
+  test: TEST_CONFIG,
+  production: PRODUCTION_CONFIG
+};
+function getEnvironmentConfig(name) {
+  return ENV_MAP[name];
+}
+function detectEnvironment() {
+  return false ? "test" : "production";
+}
+
+// src/internal/config/preferences.ts
+init_cjs_shims();
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+var DEFAULTS = {
+  locale: "zh"
+};
+function loadPreferences(configDir) {
+  const path = (0, import_node_path3.join)(configDir, "preferences.json");
+  if (!(0, import_node_fs2.existsSync)(path)) {
+    return { ...DEFAULTS };
+  }
+  try {
+    const raw = (0, import_node_fs2.readFileSync)(path, "utf-8");
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULTS, ...parsed };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+function savePreferences(configDir, updates) {
+  if (isDryRun()) {
+    return;
+  }
+  const current = loadPreferences(configDir);
+  const merged = { ...current, ...updates };
+  const path = (0, import_node_path3.join)(configDir, "preferences.json");
+  ensureConfigDirectory2(configDir);
+  (0, import_node_fs2.writeFileSync)(path, JSON.stringify(merged, null, 2), {
+    encoding: "utf-8",
+    mode: 384
+  });
+}
+function ensureConfigDirectory2(configDir) {
+  if (!(0, import_node_fs2.existsSync)(configDir)) {
+    (0, import_node_fs2.mkdirSync)(configDir, { recursive: true });
+  }
+}
+function initDefaultPreferences(configDir) {
+  const path = (0, import_node_path3.join)(configDir, "preferences.json");
+  if (!(0, import_node_fs2.existsSync)(path)) {
+    ensureConfigDirectory2(configDir);
+    (0, import_node_fs2.writeFileSync)(path, JSON.stringify(DEFAULTS, null, 2), {
+      encoding: "utf-8",
+      mode: 384
+    });
+  }
+}
+
+// src/internal/config/index.ts
+function loadAppConfig(env) {
+  const envName = env ?? detectEnvironment();
+  const configDir = getConfigDirectory(envName);
+  initDefaultPreferences(configDir);
+  const envConfig = getEnvironmentConfig(envName);
+  const prefs = loadPreferences(configDir);
+  const creds = loadCredentials(configDir);
+  const uid = creds?.uid || null;
+  const tk = creds?.tk || null;
+  const token = creds?.token || null;
+  const cid = creds?.cid || null;
+  return {
+    uid,
+    tk,
+    token,
+    cid,
+    locale: prefs.locale ?? "en",
+    debug: prefs.debug ?? false,
+    baseURL: envConfig.baseURL,
+    wsURL: envConfig.wsURL
+  };
+}
+
+// src/internal/config/logs.ts
+init_cjs_shims();
+var import_node_fs3 = require("fs");
+var import_node_path4 = require("path");
+function appendCliRunLog(configDir, entry, now = /* @__PURE__ */ new Date()) {
+  const logDir = (0, import_node_path4.join)(configDir, "logs");
+  (0, import_node_fs3.mkdirSync)(logDir, { recursive: true });
+  (0, import_node_fs3.appendFileSync)(
+    (0, import_node_path4.join)(logDir, `${formatLocalDate(now)}.log`),
+    `${JSON.stringify(entry)}
+`,
+    "utf-8"
+  );
+}
+function formatLocalDate(value) {
+  const year = value.getFullYear();
+  const month = String(value.getMonth() + 1).padStart(2, "0");
+  const day = String(value.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+// src/iostreams.ts
 var jqFilter = null;
 var dryRun = false;
+var logDebug = false;
 function setJqFilter(expr) {
   jqFilter = expr;
 }
 function setDryRun(enabled) {
   dryRun = enabled;
 }
+function setLogDebug(enabled) {
+  logDebug = enabled;
+}
 function isDryRun() {
   return dryRun;
 }
@@ -11473,11 +11650,34 @@ function printStatus(status) {
 `);
 }
 function handleCommand(result) {
+  appendStatusLog(result);
   printStatus(result);
   if (!isDryRun() && result.status === "error") {
     process.exit(1);
   }
 }
+function appendStatusLog(status) {
+  const argv = process.argv.slice(2);
+  try {
+    appendCliRunLog(getConfigDirectory(detectEnvironment()), {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      argv,
+      command: argv.join(" "),
+      status: status.status,
+      code: status.code,
+      message: status.message,
+      data: status.data,
+      dryRun
+    });
+  } catch (error) {
+    if (logDebug) {
+      process.stderr.write(
+        `[DEBUG] Failed to write CLI log: ${error instanceof Error ? error.message : String(error)}
+`
+      );
+    }
+  }
+}
 
 // src/commands/auth/login.ts
 init_cjs_shims();
@@ -11914,156 +12114,6 @@ function promptRefresh(controller, onReset) {
   });
 }
 
-// src/internal/config/index.ts
-init_cjs_shims();
-
-// src/internal/config/credentials.ts
-init_cjs_shims();
-var import_node_fs = require("fs");
-var import_node_path = require("path");
-function loadCredentials(configDir) {
-  const path = (0, import_node_path.join)(configDir, "credentials.json");
-  if (!(0, import_node_fs.existsSync)(path)) {
-    return null;
-  }
-  try {
-    const raw = (0, import_node_fs.readFileSync)(path, "utf-8");
-    return JSON.parse(raw);
-  } catch {
-    console.error("[WARN] credentials.json is corrupted, skipping \u2014 please re-authenticate");
-    return null;
-  }
-}
-function saveCredentials(configDir, creds) {
-  const path = (0, import_node_path.join)(configDir, "credentials.json");
-  ensureConfigDirectory(configDir);
-  (0, import_node_fs.writeFileSync)(path, JSON.stringify(creds, null, 2), {
-    encoding: "utf-8",
-    mode: 384
-  });
-}
-function ensureConfigDirectory(configDir) {
-  if (!(0, import_node_fs.existsSync)(configDir)) {
-    (0, import_node_fs.mkdirSync)(configDir, { recursive: true });
-  }
-}
-function clearCredentials(configDir) {
-  const path = (0, import_node_path.join)(configDir, "credentials.json");
-  if ((0, import_node_fs.existsSync)(path)) {
-    (0, import_node_fs.rmSync)(path);
-  }
-}
-function hasCredentials(configDir) {
-  const creds = loadCredentials(configDir);
-  return !!(creds?.uid && creds?.tk && creds?.token);
-}
-
-// src/internal/config/directory.ts
-init_cjs_shims();
-var import_node_os = require("os");
-var import_node_path2 = require("path");
-var PROJECT_CONFIG_DIR = (0, import_node_path2.resolve)(process.cwd(), ".qzhuli-cli");
-var USER_CONFIG_DIR = (0, import_node_path2.resolve)((0, import_node_os.homedir)(), ".qzhuli-cli");
-function getConfigDirectory(env) {
-  return env === "production" ? USER_CONFIG_DIR : PROJECT_CONFIG_DIR;
-}
-
-// src/internal/config/environment.ts
-init_cjs_shims();
-var TEST_CONFIG = {
-  name: "test",
-  baseURL: "https://test.client.qzhuli.com",
-  wsURL: "wss://test.im.qzhuli.com/ws"
-};
-var PRODUCTION_CONFIG = {
-  name: "production",
-  baseURL: "https://client.qzhuli.com",
-  wsURL: "wss://im.qzhuli.com/ws"
-};
-var ENV_MAP = {
-  test: TEST_CONFIG,
-  production: PRODUCTION_CONFIG
-};
-function getEnvironmentConfig(name) {
-  return ENV_MAP[name];
-}
-function detectEnvironment() {
-  return false ? "test" : "production";
-}
-
-// src/internal/config/preferences.ts
-init_cjs_shims();
-var import_node_fs2 = require("fs");
-var import_node_path3 = require("path");
-var DEFAULTS = {
-  locale: "zh"
-};
-function loadPreferences(configDir) {
-  const path = (0, import_node_path3.join)(configDir, "preferences.json");
-  if (!(0, import_node_fs2.existsSync)(path)) {
-    return { ...DEFAULTS };
-  }
-  try {
-    const raw = (0, import_node_fs2.readFileSync)(path, "utf-8");
-    const parsed = JSON.parse(raw);
-    return { ...DEFAULTS, ...parsed };
-  } catch {
-    return { ...DEFAULTS };
-  }
-}
-function savePreferences(configDir, updates) {
-  if (isDryRun()) {
-    return;
-  }
-  const current = loadPreferences(configDir);
-  const merged = { ...current, ...updates };
-  const path = (0, import_node_path3.join)(configDir, "preferences.json");
-  ensureConfigDirectory2(configDir);
-  (0, import_node_fs2.writeFileSync)(path, JSON.stringify(merged, null, 2), {
-    encoding: "utf-8",
-    mode: 384
-  });
-}
-function ensureConfigDirectory2(configDir) {
-  if (!(0, import_node_fs2.existsSync)(configDir)) {
-    (0, import_node_fs2.mkdirSync)(configDir, { recursive: true });
-  }
-}
-function initDefaultPreferences(configDir) {
-  const path = (0, import_node_path3.join)(configDir, "preferences.json");
-  if (!(0, import_node_fs2.existsSync)(path)) {
-    ensureConfigDirectory2(configDir);
-    (0, import_node_fs2.writeFileSync)(path, JSON.stringify(DEFAULTS, null, 2), {
-      encoding: "utf-8",
-      mode: 384
-    });
-  }
-}
-
-// src/internal/config/index.ts
-function loadAppConfig(env) {
-  const envName = env ?? detectEnvironment();
-  const configDir = getConfigDirectory(envName);
-  initDefaultPreferences(configDir);
-  const envConfig = getEnvironmentConfig(envName);
-  const prefs = loadPreferences(configDir);
-  const creds = loadCredentials(configDir);
-  const uid = creds?.uid || null;
-  const tk = creds?.tk || null;
-  const token = creds?.token || null;
-  const cid = creds?.cid || null;
-  return {
-    uid,
-    tk,
-    token,
-    cid,
-    locale: prefs.locale ?? "en",
-    debug: prefs.debug ?? false,
-    baseURL: envConfig.baseURL,
-    wsURL: envConfig.wsURL
-  };
-}
-
 // src/commands/auth/login.ts
 async function authLoginRun(factory, opts) {
   try {
@@ -13529,7 +13579,7 @@ var IMGateway = class {
       return {
         status: "success",
         code: "CONVERSATION_LIST" /* CONVERSATION_LIST */,
-        message: conversations3.length > 0 ? "Conversations ({count}):" : "No conversations found.",
+        message: conversations3.length > 0 ? `Conversations (${conversations3.length}):` : "No conversations found.",
         data: { conversations: conversations3 }
       };
     } catch (error) {
@@ -13589,6 +13639,7 @@ function createFactory(config) {
 }
 
 // src/cmd.ts
+var logDebugEnabled = false;
 var LocalizedHelp = class extends import_commander8.Help {
   /** Format an argument name with <required> or [optional] brackets. */
   argDisplayName(arg) {
@@ -13629,6 +13680,8 @@ async function main() {
   const envName = detectEnvironment();
   const config = loadAppConfig(envName);
   setLocale(config.locale);
+  logDebugEnabled = config.debug;
+  setLogDebug(config.debug);
   const factory = createFactory(config);
   const program = new import_commander8.Command();
   const testModeBanner = `
@@ -13641,7 +13694,7 @@ async function main() {
 ${t("cli.banner")}` : t("cli.banner");
   program.addHelpText("beforeAll", `${banner}
 `);
-  program.name("qz").version(`v${"0.1.0"}`, "-v, --version", t("options.version")).helpOption("-h, --help", t("options.help")).option("-q, --jq <expr>", t("options.jq")).option("--dry-run", t("options.dryRun"));
+  program.name("qz").version(`v${"0.2.1"}`, "-v, --version", t("options.version")).helpOption("-h, --help", t("options.help")).option("-q, --jq <expr>", t("options.jq")).option("--dry-run", t("options.dryRun"));
   program.usage("<command> [subcommand] [options]");
   program.hook("preAction", () => {
     const opts = program.opts();
@@ -13667,6 +13720,27 @@ ${t("messages.helpFooter")}
   await program.parseAsync(process.argv);
 }
 main().catch((err) => {
-  console.error(`Error: ${err.message}`);
+  const envName = detectEnvironment();
+  const message = err instanceof Error ? err.message : String(err);
+  try {
+    appendCliRunLog(getConfigDirectory(envName), {
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      argv: process.argv.slice(2),
+      command: process.argv.slice(2).join(" "),
+      status: "error",
+      code: "INTERNAL_ERROR" /* INTERNAL_ERROR */,
+      message,
+      data: null,
+      dryRun: process.argv.includes("--dry-run")
+    });
+  } catch (logError) {
+    if (logDebugEnabled) {
+      process.stderr.write(
+        `[DEBUG] Failed to write CLI log: ${logError instanceof Error ? logError.message : String(logError)}
+`
+      );
+    }
+  }
+  console.error(`Error: ${message}`);
   process.exit(1);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qzhuli/qzhuli-cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "CLI tool for Q助理 (QZhuli)",
   "main": "dist/cmd.js",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "CONTRIBUTING.md"
   ],
@@ -35,6 +36,7 @@
     "qzhuli"
   ],
   "author": "shootdev <npmjs@aisheshou.com>",
+  "license": "MIT",
   "packageManager": "pnpm@10.33.0",
   "engines": {
     "node": ">=18.0.0"

package/skills/qzhuli-cli/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: qzhuli-cli
+description: Use when operating the QZhuli CLI with qz, including login, auth status, config, friends, relations, users, conversations, messages, JSON filtering, dry-run, command help, and interpreting test-environment banners or config files.
+version: 1
+---
+
+# QZhuli CLI
+
+Use this skill as a concise operating manual for the `qz` command.
+
+## First Checks
+
+1. Check whether the user is logged in:
+   ```bash
+   qz auth status
+   ```
+2. If auth is missing or expired, run QR login and ask the user to scan:
+   ```bash
+   qz auth login
+   ```
+3. For exact syntax, use command help:
+   ```bash
+   qz --help
+   qz <command> --help
+   qz <command> <subcommand> --help
+   ```
+
+## Environment and Config Files
+
+If the CLI prints a `DEVELOPMENT BUILD` / `Running in TEST environment` banner, it is using the test environment and
+stores config under `./.qzhuli-cli/` relative to the process working directory.
+
+| Visible behavior  | Environment | Config directory |
+|-------------------|-------------|------------------|
+| Shows test banner | test        | `./.qzhuli-cli/` |
+| No test banner    | production  | `~/.qzhuli-cli/` |
+
+Treat `credentials.json` as secret. Preferences live in `preferences.json`.
+
+## Output and Global Options
+
+Commands return JSON with `status`, `code`, `message`, and `data`. Check `status`, not only the exit code; ambiguous
+friend lookups can return `status: "needs_resolution"`.
+
+Use `--jq` for simple dot-path filtering:
+
+```bash
+qz --jq ".data.uid" auth status
+qz --jq ".data.links" friend list
+qz --jq ".data" conversation list --limit 5
+```
+
+`--jq` is not full jq. Prefer simple paths such as `.data`, `.data.uid`, `.data.links`.
+
+Use `--dry-run` when you need to avoid side effects. It is wired through output handling, HTTP API calls, IM WebSocket
+actions, auth login/logout, and preference writes.
+
+## Command Map
+
+| Goal                       | Command                                                                                       |
+|----------------------------|-----------------------------------------------------------------------------------------------|
+| Check login                | `qz auth status`                                                                              |
+| QR login                   | `qz auth login [--method qr-code]`                                                            |
+| Clear credentials          | `qz auth logout`                                                                              |
+| Show preferences           | `qz config`                                                                                   |
+| Update preferences         | `qz config [--locale en\|zh] [--debug\|--no-debug]`                                           |
+| Search user (Q助号)          | `qz user search <query>`                                                                      |
+| Search user (UID)          | `qz user search <query> --uid`                                                                |
+| Add friend (Q助号)           | `qz user add <q-number>`                                                                      |
+| List friends               | `qz friend list`                                                                              |
+| Resolve profile (nickname) | `qz friend profile <query>`                                                                   |
+| Resolve profile (UID)      | `qz friend profile <query> --uid`                                                             |
+| Resolve profile (remark)   | `qz friend profile <query> --remark`                                                          |
+| Read relation              | `qz relation get <uid>`                                                                       |
+| Update relation            | `qz relation set <uid> [-r, --remark <name>] [-t, --type <type>]`                             |
+| List conversations         | `qz conversation list [--limit <n>]`                                                          |
+| Create conversation        | `qz conversation create <uid> --agent-id <id>`                                                |
+| Send message               | `qz message send <conversation-id> <target-cid> <content>`                                    |
+| Read message history       | `qz message history <conversation-id> [--from <id>] [--direction newer\|older] [--limit <n>]` |
+
+Relation type values are `0=stranger`, `1=friend`, `2=family`, `3=colleague`.
+
+## Common Workflows
+
+### Find a Friend and Inspect Relation
+
+1. List candidates:
+   ```bash
+   qz friend list
+   ```
+2. Resolve ambiguous names:
+   ```bash
+   qz friend profile "<nickname>"
+   ```
+3. Use the resolved `uid`:
+   ```bash
+   qz relation get <uid>
+   ```
+
+### Update a Friend Relation
+
+1. Resolve the exact `uid` first with `friend list` or `friend profile`.
+2. Confirm with the user before changing data.
+3. Execute one or both updates:
+   ```bash
+   qz relation set <uid> --remark "Product Manager" --type 1
+   ```
+4. Verify:
+   ```bash
+   qz relation get <uid>
+   ```
+
+Do not run `relation set` without `--remark` or `--type`; the CLI returns `INVALID_ARGUMENT`.
+
+### Search and Add a Friend
+
+1. Search by Q助号:
+   ```bash
+   qz user search 10000
+   ```
+2. Add directly by Q助号:
+   ```bash
+   qz user add 10000
+   ```
+
+### Send a Message
+
+1. Confirm auth:
+   ```bash
+   qz auth status
+   ```
+2. Get conversations:
+   ```bash
+   qz conversation list --limit 10
+   ```
+3. Pick the conversation `id`.
+4. Pick `target-cid` from that conversation's `cids`; for one-to-one chats this is usually the other participant's cid,
+   not the current user's own `cid`.
+5. Confirm recipient and content with the user if there is any ambiguity.
+6. Send:
+   ```bash
+   qz message send <conversation-id> <target-cid> "message text"
+   ```
+7. Verify:
+   ```bash
+   qz message history <conversation-id> --limit 5
+   ```
+
+### Page Through Message History
+
+```bash
+qz message history <conversation-id> --limit 20
+qz message history <conversation-id> --from <message-id> --direction older --limit 20
+qz message history <conversation-id> --from <message-id> --direction newer --limit 20
+```
+
+## Troubleshooting
+
+| Symptom                | Action                                                                   |
+|------------------------|--------------------------------------------------------------------------|
+| Command not found      | Confirm `qz` is installed or available on `PATH`.                        |
+| Auth failure           | Run `qz auth status`; then `qz auth login` if needed.                    |
+| Unexpected language    | Run `qz config --locale en` or `qz config --locale zh`.                  |
+| Too much JSON          | Use `--jq ".data"` or another simple dot path.                           |
+| Need a no-op preview   | Use `--dry-run`.                                                         |
+| Message send cid error | Re-check `auth status` and choose `target-cid` from `conversation list`. |