@qoder-ai/qmind-cli 1.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @qoder-ai/qmind-cli
+
+## 1.1.0
+
+### Minor Changes
+
+- 858c2f4: QMind CLI is now available on npm as `@qoder-ai/qmind-cli`. Install it with `npm install --global @qoder-ai/qmind-cli` to use the `qmind` command for signing in, managing notebooks and sources, retrieving knowledge, running RAG and compilation workflows, and safely synchronizing folders. The CLI supports automation-friendly JSON and NDJSON output, stable exit codes, and npm-managed upgrades on macOS, Linux, and Windows with Node.js 20.18.1 or later.
+
+## 1.0.0
+
+### Initial release
+
+- Introduced the `qmind` command for QMind knowledge workflows.
+- Added browser-based sign-in and secure local credential management, with environment and token configuration for automation.
+- Added notebook create/list/get/delete, card list/search, retrieval, RAG, compilation, lint, source create/list/get/upload/download/move/content/delete, website import, image presign, and folder upload workflows.
+- Added human-readable tables, JSON, agent, and NDJSON output, plus structured errors and script-friendly exit codes.

package/README.md

@@ -0,0 +1,82 @@
+# `@qoder-ai/qmind-cli`
+
+QMind 的可执行 CLI 产品与 Node host layer。它把 SDK 内置的 `sash` access profile 与 CLI 专属的命令解析、稳定输出/退出码、认证、凭证持久化、filesystem source、folder sync、proxy/TLS policy 和 raw SSE transport 组装在一起。
+
+本包有意不再拆一个独立 `transport-node` package。Browser/custom host 使用 `@ali/qmind-sdk/fetch` 或实现小型 `QMindTransport` port；Node-only policy 留在这里。
+
+公共 npm 包只暴露 `qmind` 可执行命令。内部 SDK 会打进 CLI 产物，安装者不会解析或安装任何 `@ali/*` runtime dependency；Node host/application 的 TypeScript 源码继续作为 monorepo 内部测试与 real-E2E 边界，但不属于公共 npm API。
+
+## Install and run
+
+```sh
+npm install --global @qoder-ai/qmind-cli
+qmind version
+qmind --help
+```
+
+`package.json#bin.qmind` 指向可执行的 `bin/cli.js`；这个稳定 wrapper 只保留 Node shebang 并导入 `dist/qmind.js`。npm package 由独立公共 registry job 发布，首个公开版本由 Changesets 从 `1.0.0` 基线提升到 `1.1.0`。
+
+## Internal workspace application API
+
+```ts
+import { createQMindCliHost } from '@qoder-ai/qmind-cli';
+
+const host = await createQMindCliHost({
+  flags: { token: process.env.QMIND_TOKEN },
+});
+
+const notebooks = await host.client.listNotebooks();
+await host.close();
+```
+
+Embedding/test host 也可以通过一个深 application interface 执行完整 CLI，而不接触 Commander：
+
+```ts
+import { runQMindCli } from '@qoder-ai/qmind-cli';
+
+const exitCode = await runQMindCli(['notebook', 'list', '--format', 'json']);
+```
+
+`runQMindCli()` 返回 `0 | 1 | 2`，不修改 embedding process 的 `exitCode`；可执行入口只负责把返回值赋给进程。它可注入 host factory、stdout/stderr 与确认器，生产与测试走同一命令 application Module。该源码接口不从公共 tarball 导出。
+
+## Command compatibility
+
+命令面覆盖 `login/logout`、`notebook`、`cards` 与顶层 `list/search`、`retrieve`、`source`、`image`、`rag/compile/lint`、`task create/list/get`、`upload-folder|sync`、`self-update` 和 `version`。Go 风格 `-nb`、`-page-size=50` 等单横线长参数在解析前兼容转换；`-h/-V/-o/-q` 与 `--` 后 positional 保持原样。
+
+- 领域结果支持 `table | json | agent | ndjson`；未知 format 按历史合同回退 table；
+- stdout 只承载结果，诊断、progress 与 download 信息进入 stderr；
+- 成功/help 为 `0`，运行失败/部分成功/取消为 `1`，usage 与 `INVALID_ARGUMENT` 为 `2`；
+- JSON runtime error 使用稳定 `{ "error": { "code", "message", "status", "errorCode", "requestId", "rawBody", "details" } }` envelope；
+- `source upload` 复用 SDK 的 50/500 MiB strategy；download 默认不覆盖并流式原子落盘；
+- `upload-folder` 支持默认扩展/隐藏文件过滤、`--ignore` glob、`skip|overwrite|if-changed`、`--delete`、`--dry-run`、mapping、1..10 并发与 retryable-only 三次上传。`--delete` 明确把 notebook source root 当作该本地目录的镜像，会删除远端多余项；为避免空计划误删，它不能与 `--skip-upload` 组合，建议先用 `--dry-run` 审阅 stats。
+
+为兼容已有脚本，`self-update` 命令名仍保留，但 npm 安装稳定返回 `UNSUPPORTED_OPERATION`。npm 安装的版本升级必须交给 `npm update --global @qoder-ai/qmind-cli`，CLI 不会替换 Node 或 npm 管理的文件。
+
+`createQMindCliHost()` 是主要 module boundary，返回：
+
+- `client`：使用 SDK-owned Sash routes/codecs 的标准 `QMindClient`；
+- `login()` / `logout()`：Device Flow + PKCE 与完整凭证清理；
+- `createFileSource()`：可重复打开、流式读取的 `QMindBinarySource`；
+- `downloadToFile()`：credential-free signed URL 的流式、原子、默认 no-clobber 下载；
+- `config`：不含 token、proxy credentials 或 TLS material 的安全 runtime metadata；
+- `close()`：释放 host-owned Undici dispatchers。
+
+测试和 embedding host 可通过 `adapters` 注入 raw `QMindTransport`、fake clock/browser/reporter 或 secret store。注入的 transport 仍由调用方持有。
+
+## Authentication and credentials
+
+配置优先级为 flags → environment → `~/.qmind/config.json` → stored credential Sash origin → named environment defaults。legacy `~/.qmind-env` 只读取 `QMIND_*`，且不会覆盖当前 process environment。
+
+- `pt-*` personal token 只交换为 job token，从不持久化；
+- device token 在过期前 30 秒主动 refresh；
+- host `401` 触发一次 refresh 和严格一次 retry，并发失败共享同一个 refresh；
+- credential schema v1 在 refresh 时先备份，再原子迁移为 schema v2；
+- `credentials.json` 位于 mode `0700` 目录中，自身为 mode `0600` regular file；
+- `@napi-rs/keyring` 是可选、仍维护的 OS-keyring 增强；不可用时确定性回退到私有文件；
+- secrets 不进入 public config、debug URL、error 或 login result。
+
+## Node network policy
+
+内置 adapter 基于 Undici，支持 `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`、private CA、默认 strict TLS、total request deadline、SSE idle timeout、idempotent retry、streaming multipart/binary upload 和 raw UTF-8 SSE decoding。
+
+signed upload URL 必须是 credential-free HTTPS。Authorization、Cookie、Proxy Authorization 和 CSRF headers 会在请求离开进程之前被拒绝。

package/bin/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../dist/qmind.js';