@youzan-cloud/zan-saas-cli 0.0.0-stage → 0.1.0-beta.3

package/DEPENDENCIES.json

@@ -0,0 +1,50 @@
+[
+  {
+    "path": "node_modules/ajv",
+    "name": "ajv",
+    "version": "8.20.0",
+    "license": "MIT",
+    "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==",
+    "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz"
+  },
+  {
+    "path": "node_modules/commander",
+    "name": "commander",
+    "version": "12.1.0",
+    "license": "MIT",
+    "integrity": "sha512-Vw8qHK3bZM9y/P10u3Vib8o/DdkvA2OtPtZvD871QKjy74Wj1WSKFILMPRPSdUSx5RFK1arlJzEtA4PkFgnbuA==",
+    "resolved": "https://registry.npmjs.org/commander/-/commander-12.1.0.tgz"
+  },
+  {
+    "path": "node_modules/fast-deep-equal",
+    "name": "fast-deep-equal",
+    "version": "3.1.3",
+    "license": "MIT",
+    "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+    "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz"
+  },
+  {
+    "path": "node_modules/fast-uri",
+    "name": "fast-uri",
+    "version": "3.1.9",
+    "license": "BSD-3-Clause",
+    "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==",
+    "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz"
+  },
+  {
+    "path": "node_modules/json-schema-traverse",
+    "name": "json-schema-traverse",
+    "version": "1.0.0",
+    "license": "MIT",
+    "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+    "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz"
+  },
+  {
+    "path": "node_modules/require-from-string",
+    "name": "require-from-string",
+    "version": "2.0.2",
+    "license": "MIT",
+    "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+    "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz"
+  }
+]

package/INSTALL.md

@@ -0,0 +1,79 @@
+# 有赞 SaaS CLI 安装指南
+
+本指南面向 AI Agent。安装 CLI 和当前宿主的入口 Skill 后，再按用户任务登录和选店。
+
+发布包名为 `@youzan-cloud/zan-saas-cli`，终端命令为 `zan-saas`。安装入口统一使用 `latest` 标签，实际版本及 beta 状态以包版本号为准。
+
+## 1. 检查环境
+
+确认 Node.js 18+、npm 8 至 11，以及 npm/npx 可用。缺少环境时说明需要安装的组件。保留用户现有的 npm registry、凭证及其他 Agent Skill。
+
+## 2. 安装
+
+交互终端运行：
+
+```sh
+npx @youzan-cloud/zan-saas-cli@latest install
+```
+
+安装器检测常用 Agent，提示选择，默认个人安装。它会持久安装同版 CLI，并将轻量入口放到所选宿主。无需克隆仓库、查找 npm 目录或手工复制 Skill。
+
+Agent 使用非交互命令，明确当前宿主，例如：
+
+```sh
+npx --yes @youzan-cloud/zan-saas-cli@latest install --yes --host workbuddy
+```
+
+`--host` 可选 `workbuddy`、`codebuddy`、`codex`、`claude-code`、`cursor`、`trae`。`trae` 表示 Trae 中国版。多个宿主用逗号分隔。已在检测范围内时也可省略 `--host`，使用 `--yes` 安装到检测到的宿主；没有检测结果时须补充宿主。
+
+用户指定只用于当前项目时，在该项目目录追加 `--scope project`。其他宿主已知 Skill 目录时可用 `--directory <目录>`；不猜未知宿主路径。
+
+WorkBuddy 个人目录为 `~/.workbuddy/skills`，CodeBuddy 为 `~/.codebuddy/skills`；项目目录均为 `.codebuddy/skills`。
+
+安装器只迁移本项目旧的 `zan-saas-cli` 开发链接或 `@youzan-cloud/zan-saas` 候选包占用的命令入口；同名外部命令、外部 Skill 或被手工修改的入口会保留并报错。发生冲突时报告具体路径，让用户处理，不使用 `--force`。
+
+## 3. 验证
+
+```sh
+zan-saas --version
+zan-saas skills read zan-saas
+```
+
+核对安装器返回的 Skill 路径，并在宿主技能列表确认 `zan-saas` 已启用，再打开新会话。Skill 内已记录持久 CLI 的 Node.js 与入口路径；宿主没有加载 nvm 时，也按该启动方式调用后续指引中的 `zan-saas`。
+
+安装文件与 CLI 验证通过后，报告版本、宿主和安装位置。JSON 结果的 `success: true` 表示安装完成，`skillLoading: not_verified` 表示尚未验证宿主加载；按 `nextStep` 在宿主中检查。未发现入口时，先确认宿主配置的 Skill 根目录，再用 `--directory <目录>` 重新安装入口，不根据目录是否存在猜测加载路径。
+
+安装失败时读取错误的 `details`：`operation` 是失败步骤，`npmCode` 是已识别的错误码，`nextStep` 是处理建议。`ENOTEMPTY` 表示 npm 目录冲突，先核对返回的冲突路径，备份并移走确认属于旧版本的残留目录，再重试。不要自动删除全局目录或强制覆盖。未识别的错误不猜根因，保留本次失败并查看 npm 本机日志。
+
+## 4. 按需登录和选店
+
+用户开始业务查询时，先运行 `zan-saas auth status`。未登录则执行 `zan-saas auth login`，把授权地址交给用户，等待命令成功后再次检查状态。浏览器授权完成但命令失败时，按认证错误核查并停止。
+
+先运行 `zan-saas shop current`，已有有效上下文且用户未要求切店时沿用。需要选店时，运行 `zan-saas shop list`，按入口 Skill 核对用户指定的店名或展示候选店名供选择；Agent 将明确目标映射为 `kdtId`，执行 `zan-saas shop use <kdtId>` 后用 `zan-saas shop current` 核对实际生效的店铺。后续按入口 Skill 读取同版领域指引、help 和 schema。安装器本身不登录、不选店，也不执行业务请求。
+
+## 本地候选包测试
+
+收到 `.tgz` 后，用 `npm exec` 准备候选包的依赖并运行其安装器；不依赖旧版全局 CLI 是否支持 `install`，也不直接运行尚未安装依赖的解包目录。下面的 `candidate` 和 `skill_dir` 替换为实际绝对路径；`skill_dir` 是宿主配置的 Skill 根目录，安装器会在其下创建 `zan-saas/SKILL.md`。
+
+```sh
+candidate=/absolute/path/candidate.tgz
+skill_dir=/absolute/path/skills
+# 准备候选运行环境并查看计划；不改全局 CLI 和 Skill
+npm exec --yes --package "$candidate" -- zan-saas install --yes \
+  --directory "$skill_dir" --package "$candidate" --dry-run --json
+
+# 核对计划后安装同一份包
+npm exec --yes --package "$candidate" -- zan-saas install --yes \
+  --directory "$skill_dir" --package "$candidate" --json
+
+zan-saas --version
+zan-saas skills read zan-saas
+```
+
+也可将 `--directory "$skill_dir"` 替换为已有支持的 `--host <宿主>`。安装沿用 npm 的全局 prefix；仅做隔离验收时，应事先配置临时 prefix 和临时 Skill 目录。终端找不到 `zan-saas` 时，用安装结果的 `launcher` 与本次 Node.js 执行相同检查。
+
+`npm exec` 首次准备运行环境可能下载依赖并写入 npm 缓存；`--dry-run` 只约束随后运行的安装器，不会改变全局 CLI 或 Skill。本地候选不保证首次安装可以断网完成，不代表候选已发布到 npm，也不会自动登录或选店。
+
+## 当前交付状态
+
+本指南随新版 npm 包发行。发布后的包页面为 https://www.npmjs.com/package/@youzan-cloud/zan-saas-cli；Agent 可通过 https://unpkg.com/@youzan-cloud/zan-saas-cli@latest/INSTALL.md 读取同一包内的原始 Markdown。只有包已发布到官方 npm registry 并设置 `latest` 标签后，上述地址和 npx 命令才能供外部用户使用。本地候选用 `--package <候选.tgz>` 验证，不能把候选测试称为 npm 已发布。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 有赞
+
+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/NOTICE

@@ -0,0 +1 @@
+Youzan SaaS CLI preview. Project code: MIT. See THIRD_PARTY_NOTICES.txt.

package/README.md

@@ -1,3 +1,152 @@
-# Temporary Holding Version
+# 有赞 SaaS CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在终端查询有赞商品、订单、客户、会员权益和履约数据，也可以让 AI Agent 使用自然语言完成查询。适用于商家员工、自动化脚本和支持 Skill 的 AI 助手。
+
+包名为 `@youzan-cloud/zan-saas-cli`，安装后的命令为 `zan-saas`。当前为 beta 版本。
+
+[安装](#安装) · [快速开始](#快速开始) · [Agent 使用](#在-agent-中使用) · [支持范围](#支持范围) · [常见问题](#常见问题)
+
+## 安装
+
+需要 **Node.js 18+、npm 8 至 11**，以及可访问 npm registry 的网络环境。
+
+### 手动安装
+
+```sh
+npx @youzan-cloud/zan-saas-cli@latest install
+```
+
+按提示选择 Agent。安装向导会安装 CLI 和对应的入口 Skill，默认使用个人目录；无需克隆仓库或手动复制文件。
+
+仅需要命令行工具时，也可以使用：
+
+```sh
+npm install -g @youzan-cloud/zan-saas-cli@latest --ignore-scripts --engine-strict
+```
+
+### 让 AI Agent 安装
+
+把下面这句话发给你的 AI 助手：
+
+> 帮我安装有赞 SaaS CLI：https://unpkg.com/@youzan-cloud/zan-saas-cli@latest/INSTALL.md
+
+支持为 WorkBuddy、CodeBuddy、Codex、Claude Code、Cursor 和 Trae 中国版安装入口 Skill。其他宿主可指定 Skill 目录，详见[安装指南](https://unpkg.com/@youzan-cloud/zan-saas-cli@latest/INSTALL.md)。
+
+## 快速开始
+
+### 1. 登录
+
+```sh
+zan-saas auth login
+```
+
+按提示在浏览器完成授权，等待终端显示登录成功。
+
+### 2. 选择店铺
+
+```sh
+zan-saas shop list
+```
+
+从列表中找到目标店铺，用它的 `kdtId` 替换下方的 `<kdtId>`：
+
+```sh
+zan-saas shop use <kdtId>
+zan-saas shop current
+```
+
+已有有效店铺上下文时可跳过选店。切换店铺不需要重新登录。
+
+### 3. 开始查询
+
+查询当前店铺的一页待发货订单：
+
+```sh
+zan-saas order order list --status WAIT_SELLER_SEND_GOODS
+```
+
+先预览同一查询的请求计划，不访问业务接口：
+
+```sh
+zan-saas order order list --status WAIT_SELLER_SEND_GOODS --dry-run
+```
+
+## 在 Agent 中使用
+
+安装 Skill 后，在宿主中新建对话，例如：
+
+> 使用 zan-saas，帮我查询当前店铺的待发货订单。
+
+Agent 会读取当前安装版的使用指引，选择命令并解释查询结果。需要登录时，你在浏览器完成授权；需要选店时，可以提供店名或选择它展示的候选店铺。
+
+CLI 与领域指引随同一个 npm 包发行。升级后，入口 Skill 会按需读取同版内容，无需手工维护各领域的副本。
+
+## 支持范围
+
+| 领域 | 查询内容 |
+| --- | --- |
+| 商品 | 商品资料、规格、图文、分组、分类、品牌和属性 |
+| 订单与售后 | 交易订单、支付事实、售后单和退款资金记录 |
+| 客户与会员 | 客户档案、标签、分群、会员身份、等级和成长值 |
+| 积分与权益 | 积分账户、流水、规则，权益卡定义、持卡实例和发放记录 |
+| 储值卡 | 持卡、状态和余额 |
+| 履约与库存 | 发货单、配送单、物流轨迹和库存变化日志 |
+| 组织与访问控制 | 组织、员工、角色关联和权限点 |
+| 互动营销 | 抽奖活动及其配置与统计 |
+
+具体命令、产品适用范围和参数以当前安装版的 help、schema 和 Skill 为准。
+
+## 查找命令
+
+| 目标 | 命令 |
+| --- | --- |
+| 浏览命令目录 | `zan-saas --help` |
+| 查看订单列表用法 | `zan-saas help order order list` |
+| 获取简洁的能力目录 | `zan-saas schema --summary` |
+| 读取某条命令的输入契约 | `zan-saas schema order.order.list --section input` |
+| 读取返回字段说明 | `zan-saas schema order.order.list --section output` |
+| 阅读 Agent 入口指引 | `zan-saas skills read zan-saas` |
+| 检查本地安装环境 | `zan-saas doctor` |
+
+## 输出与权限
+
+业务查询成功时输出 JSON，退出码为 `0`；失败时退出码非零，错误 JSON 写入 stderr。脚本应检查退出码并分别处理 stdout 和 stderr。
+
+列表默认读取一页，跨页范围和数量限制由具体命令定义。金额单位、时间格式及分页含义可从 schema 读取。
+
+当前已发布的业务命令均为只读查询。业务访问需要有效账号、目标店铺和相应的服务端权限。`api` 是独立的原始接口调用入口，使用前须核对目标 API 的副作用，不能自动替代未提供的业务操作。
+
+## 升级与卸载
+
+升级 CLI，并同步所选 Agent 的入口：
+
+```sh
+npx @youzan-cloud/zan-saas-cli@latest install
+```
+
+查看版本或卸载 CLI：
+
+```sh
+zan-saas --version
+npm uninstall -g @youzan-cloud/zan-saas-cli
+```
+
+卸载 CLI 后，如不再使用，请在 Agent 中移除对应的 `zan-saas` 入口 Skill。
+
+## 常见问题
+
+### 安装后找不到 `zan-saas`
+
+重新打开终端，并确认当前 Node.js 环境的 npm 全局命令目录已加入 PATH。使用 nvm 切换 Node.js 版本后，需要在新环境下重新安装。安装器生成的 Skill 记录了 CLI 的持久启动路径，供桌面 Agent 调用。
+
+### 登录成功，但查询提示权限不足
+
+先运行 `zan-saas shop current` 确认目标店铺，再根据命令帮助核对产品支持范围和账号权限。登录成功不代表已获得所有接口的访问权限。
+
+### 查询提示店铺没有可用应用
+
+部分查询遇到网关错误 `1106` 时会尝试初始化店铺应用，该操作需要店铺高级管理员身份。设置 `ZAN_SAAS_SHOP_APP_INIT=0` 可关闭自动初始化。权益卡持卡列表和单笔订单读取禁用此流程，具体行为以同版命令契约为准。
+
+## 许可证
+
+采用 MIT 许可证。第三方依赖的许可材料随包附带，见 `LICENSE`、`NOTICE` 和 `THIRD_PARTY_NOTICES.txt`。

package/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,162 @@
+ajv@8.20.0 (MIT)
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Evgeny Poberezkin
+
+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.
+
+
+
+-----
+
+commander@12.1.0 (MIT)
+(The MIT License)
+
+Copyright (c) 2011 TJ Holowaychuk <tj@vision-media.ca>
+
+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.
+
+
+-----
+
+fast-deep-equal@3.1.3 (MIT)
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+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.
+
+
+-----
+
+fast-uri@3.1.9 (BSD-3-Clause)
+Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
+Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * The names of any contributors may not be used to endorse or promote
+      products derived from this software without specific prior written
+      permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+                                  *   *   *
+
+The complete list of contributors can be found at:
+- https://github.com/garycourt/uri-js/graphs/contributors
+
+-----
+
+json-schema-traverse@1.0.0 (MIT)
+MIT License
+
+Copyright (c) 2017 Evgeny Poberezkin
+
+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.
+
+
+-----
+
+require-from-string@2.0.2 (MIT)
+The MIT License (MIT)
+
+Copyright (c) Vsevolod Strukchinsky <floatdrop@gmail.com> (github.com/floatdrop)
+
+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/bin/zan-saas-cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createProgram } = require('../src/cli/program');
+const { runWithApiSession } = require('../src/transport/api');
+const { finalizeError } = require('../src/execution/error-details');
+const { visibleCommands } = require('../src/commands/system/schema');
+const { commandSchema } = require('../src/execution/command-schema');
+
+let program;
+Promise.resolve().then(() =>
+  runWithApiSession(() => {
+    program = createProgram();
+    if (process.argv.length === 2) {
+      program.outputHelp();
+      return undefined;
+    }
+    return program.parseAsync(process.argv);
+  })
+).catch(error => {
+  if (['commander.helpDisplayed', 'commander.version'].includes(error.code)) return;
+  if (error.code === 'commander.help' && error.exitCode === 0) return;
+  const registered = program && visibleCommands(program)
+    .find(entry => entry.path === error.cliDetails?.command);
+  const context = registered && { ...registered, schema: commandSchema(registered.command) };
+  process.stderr.write(`${JSON.stringify(finalizeError(error, context))}\n`);
+  process.exitCode = 1;
+});

package/internal/registry/index.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+const { validateAt } = require('../../src/execution/command-policy');
+const { nativeCommandLocation } = require('../../src/cli/native-path');
+const { validateAvailability } = require('../../src/cli/command-paths');
+
+const manifestFile = path.join(__dirname, 'manifest.json');
+const nativeRoot = path.join(__dirname, '../../src/commands/native');
+const domainNamePattern = /^[a-z][a-z0-9-]*$/;
+const risks = new Set(['read', 'low', 'medium', 'high']);
+const digestPattern = /^[a-f0-9]{64}$/;
+
+function validateManifest(manifest) {
+  if (!manifest || manifest.schemaVersion !== 6 ||
+      !Number.isSafeInteger(manifest.businessCommandCount) ||
+      manifest.businessCommandCount < 0 ||
+      !Array.isArray(manifest.domains) || !Array.isArray(manifest.skills)) {
+    throw new Error('Invalid command catalog manifest');
+  }
+
+  const domains = new Set();
+  let commandCount = 0;
+  for (const entry of manifest.domains) {
+    if (!entry || !domainNamePattern.test(entry.name) || domains.has(entry.name) ||
+        typeof entry.description !== 'string' || !entry.description.trim() ||
+        entry.skill !== `zan-saas-${entry.name}` ||
+        entry.indexFile !== `${entry.name}/commands.index.json` ||
+        !Number.isSafeInteger(entry.commandCount) || entry.commandCount < 0 ||
+        !Number.isSafeInteger(entry.indexSize) || entry.indexSize < 1 ||
+        !digestPattern.test(entry.indexSha256) ||
+        !digestPattern.test(entry.fingerprint)) {
+      throw new Error(`Invalid command catalog domain entry: ${entry?.name}`);
+    }
+    domains.add(entry.name);
+    commandCount += entry.commandCount;
+  }
+  if (commandCount !== manifest.businessCommandCount) {
+    throw new Error('Command catalog business command count does not match its domains');
+  }
+  return manifest;
+}
+
+function validateDomainIndex(index, domain, { historical = false } = {}) {
+  const legacy = historical && [1, 2].includes(index?.schemaVersion);
+  if (!index || (!legacy && index.schemaVersion !== 3) || index.domain !== domain.name ||
+      !Array.isArray(index.businessCommands) ||
+      index.businessCommands.length !== domain.commandCount) {
+    throw new Error(`Invalid command index for domain: ${domain.name}`);
+  }
+
+  const paths = new Set();
+  for (const entry of index.businessCommands) {
+    if (!entry || typeof entry.path !== 'string' || paths.has(entry.path) ||
+        typeof entry.module !== 'string' || !digestPattern.test(entry.fingerprint)) {
+      throw new Error(`Invalid command index entry in domain: ${domain.name}`);
+    }
+    const location = nativeCommandLocation(entry.module, entry.resourcePath);
+    const risk = legacy ? entry.mutationRisk : entry.risk;
+    if (!location || location.domain !== domain.name || entry.path !== location.path || entry.kind !== location.kind ||
+        !risks.has(risk) || (!legacy && Object.hasOwn(entry, 'mutationRisk'))) {
+      throw new Error(`Invalid command index entry: ${entry.path}`);
+    }
+    if (index.schemaVersion !== 1) validateAt(entry.at);
+    validateAvailability(entry.availability);
+    paths.add(entry.path);
+  }
+  return index;
+}
+
+function createRegistry(manifest, readIndex, { historical = false } = {}) {
+  validateManifest(manifest);
+  if (typeof readIndex !== 'function') throw new Error('Command catalog reader is missing');
+
+  const domains = new Map(manifest.domains.map(entry => [entry.name, entry]));
+  const cache = new Map();
+
+  function loadDomain(name) {
+    if (cache.has(name)) return cache.get(name);
+    const entry = domains.get(name);
+    if (!entry) throw new Error(`Native domain not published: ${name}`);
+
+    const raw = readIndex(entry);
+    const bytes = Buffer.isBuffer(raw) ? raw : Buffer.from(raw);
+    if (bytes.length !== entry.indexSize) {
+      throw new Error(`Command index size does not match manifest: ${name}`);
+    }
+    const digest = crypto.createHash('sha256').update(bytes).digest('hex');
+    if (digest !== entry.indexSha256) {
+      throw new Error(`Command index fingerprint does not match manifest: ${name}`);
+    }
+
+    let index;
+    try {
+      index = JSON.parse(bytes.toString('utf8'));
+    } catch {
+      throw new Error(`Command index is not valid JSON: ${name}`);
+    }
+    validateDomainIndex(index, entry, { historical });
+    cache.set(name, index);
+    return index;
+  }
+
+  return Object.freeze({ manifest, loadDomain });
+}
+
+function openRegistry({ manifestPath = manifestFile, commandsRoot = nativeRoot } = {}) {
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    throw new Error('Command catalog manifest is missing or invalid');
+  }
+  validateManifest(manifest);
+  return createRegistry(manifest, entry => {
+    const filename = path.join(commandsRoot, entry.indexFile);
+    return fs.readFileSync(filename);
+  });
+}
+
+module.exports = { createRegistry, openRegistry, validateManifest, validateDomainIndex };