@soln/cli 0.1.0

package/README.md

@@ -0,0 +1,551 @@
+# Soln CLI
+
+`sl` is the command-line interface for controlling the authenticated Soln tenant.
+
+The current release supports:
+
+- `sl system organization profile get`
+- `sl system organization profile update`
+- `sl system organization structure get`
+- `sl login`
+- `sl whoami`
+- `sl logout`
+- `soln studio init page`
+- `soln studio deploy`
+- `soln studio publish`
+- `soln studio pull`
+- `soln studio status`
+
+## Requirements
+
+- Node.js 22 or newer
+
+## Install
+
+```bash
+npm install -g @soln/cli
+```
+
+## Login
+
+The `sl` executable uses the same existing member login and local session as the legacy `soln` alias:
+
+```bash
+sl login --base-url <api-url> --tenant <tenant-subdomain> --email <email>
+```
+
+Use a tenant member account and password:
+
+```bash
+soln login --base-url <api-url> --tenant <tenant-subdomain> --email <email>
+```
+
+`--tenant` is the tenant subdomain, not the tenant UUID.
+
+If the password is entered incorrectly, the CLI prompts again in the same command. After 3 failed password attempts, the command exits.
+
+Use email verification code login:
+
+```bash
+soln login --base-url <api-url> --tenant <tenant-subdomain> --email <email> --method email
+```
+
+If the verification code is entered incorrectly, the CLI keeps prompting in the same command so the current code can still be used until it expires or reaches the server-side attempt limit.
+
+The CLI stores the authenticated member session in:
+
+```txt
+~/.soln/config.json
+```
+
+The config file is written with `0600` permissions. Passwords are never stored.
+
+## Check Current Session
+
+```bash
+soln whoami
+```
+
+This command reads the local session and verifies it with the Soln API:
+
+```txt
+GET /auth/member/me
+```
+
+Use JSON output from scripts:
+
+```bash
+soln whoami --json
+```
+
+## Logout
+
+```bash
+soln logout
+```
+
+After the Soln API confirms logout, the local session file is removed.
+
+## System Organization Profile
+
+Read the organization profile for the currently authenticated tenant:
+
+```bash
+sl system organization profile get
+```
+
+The command obtains a Runtime identity from the existing member session, then reads the tenant-side profile. It does not accept a tenant ID, role, or arbitrary command string. The Runtime permission `system-organization.page / enter` is enforced before the profile query.
+
+Update the profile through the same Runtime command endpoint:
+
+```bash
+sl system organization profile update --display-name "Acme Corporation"
+```
+
+Read the organization and department trees for the currently authenticated tenant:
+
+```bash
+sl system organization structure get
+```
+
+The structure command requires `system-organization-structure.page / enter` and returns
+organization and department trees without members, extensions, or tenant identifiers.
+
+The same namespace provides read-only organization, department, and member queries:
+
+```bash
+sl system organization structure organization list --keyword "North"
+sl system organization structure organization get --organization-id <uuid>
+sl system organization structure department list --organization-id <uuid>
+sl system organization structure department get --department-id <uuid>
+sl system organization structure member list --department-id <uuid> --include-descendants --page 1 --page-size 20
+sl system organization structure member get --member-id <uuid>
+```
+
+The three list commands accept SDK-compatible profile-field conditions:
+
+```bash
+sl system organization structure member list \
+  --condition-json '{"logic":"and","children":[{"field":"so_avatar","operator":"not_empty"}]}' \
+  --page 1 --page-size 20 --json
+```
+
+Supported operators are `eq`, `neq`, `contains`, `not_contains`, `gt`, `gte`, `lt`, `lte`, `in`, `empty`, and `not_empty`.
+
+Message templates use aggregate authoring definitions. Create and update accept exactly one inline JSON object or JSON file. New templates are drafts; activation and archival are explicit lifecycle commands. Built-in templates are readable but cannot be changed or deleted.
+
+```bash
+sl system message template list --json
+sl system message template get --template-id <uuid> --json
+sl system message template create --definition-file message-template.json --json
+sl system message template update --template-id <uuid> --definition-file message-template.json --json
+sl system message template activate --template-id <uuid> --json
+sl system message template delete --template-id <uuid> [--force] --json
+```
+
+Generic form schemas and records use the following commands:
+
+```bash
+sl system form schema list --keyword "orders" --json
+sl system form schema get --form-api-name orders --json
+```
+
+Form model and field management uses the same fixed Soln Runtime command endpoint. New models are created disabled; enable requires an enabled, visible identifier field. Disable a model before deleting it. Field configuration is passed as one JSON object so formula, option, validation, and display settings remain lossless:
+
+```bash
+sl system form schema create --name Orders --api-name orders --type custom --json
+sl system form field create --form-id <uuid> \
+  --definition-json '{"name":"Order No","apiName":"so_order_no","type":"text","isIdentifier":true,"required":true}' --json
+sl system form schema enable --form-id <uuid> --json
+sl system form field update --field-id <uuid> \
+  --definition-json '{"name":"Order Number","required":true}' --json
+sl system form formula catalog --json
+sl system form formula validate --form-id <uuid> \
+  --expression 'ROUND(FIELD("so_quantity") * FIELD("so_unit_price"), 2)' \
+  --result-data-type number --json
+sl system form formula preview --form-id <uuid> \
+  --expression 'ROUND(FIELD("so_quantity") * FIELD("so_unit_price"), 2)' \
+  --result-data-type number \
+  --values-json '{"so_quantity":3,"so_unit_price":12.345}' --json
+sl system form schema disable --form-id <uuid> --json
+sl system form schema delete --form-id <uuid> --json
+```
+
+Layout design uses five aggregate commands. Create and update definitions can be inline JSON or a JSON file. Canvas definitions are complete snapshots: omitted groups are deleted and omitted fields become hidden. A DEFAULT system layout accepts canvas updates, but its metadata, scopes, and deletion remain protected.
+
+```bash
+sl system form layout list --form-id <uuid> --json
+sl system form layout get --layout-id <uuid> --json
+sl system form layout create --form-id <uuid> --definition-file layout-create.json --json
+sl system form layout update --layout-id <uuid> --definition-file layout-canvas.json --json
+sl system form layout delete --layout-id <uuid> --json
+```
+
+Page-event bindings are stored on a custom layout's form configuration. `main-init` is valid for every custom page layout; field and child-row events are restricted by the layout page type. Binding requires a published Studio script asset and the active script file path.
+
+```bash
+sl system form layout page-event get --asset-id <uuid> --form-id <uuid> --layout-id <uuid> --json
+sl system form layout page-event bind --asset-id <uuid> --file-path src/events/customer.ts \
+  --form-id <uuid> --layout-id <uuid> --event-type main-field-change \
+  --field-mode specified --fields-json '["so_customer_id"]' --json
+sl system form layout page-event verify --asset-id <uuid> --file-path src/events/customer.ts \
+  --form-id <uuid> --layout-id <uuid> --event-type main-field-change \
+  --field-mode specified --fields-json '["so_customer_id"]' --json
+sl system form layout page-event unbind --asset-id <uuid> --file-path src/events/customer.ts \
+  --form-id <uuid> --layout-id <uuid> --event-type main-field-change \
+  --field-mode specified --fields-json '["so_customer_id"]' --json
+```
+
+按钮设计配置和运行时按钮执行是两套命令。设计更新是两个数组的完整替换，必须先读取当前配置再提交；自定义按钮可以单独创建、更新或删除。按钮脚本支持 `beforeClick`、`action`、`afterClick` 三个阶段，绑定后必须执行 `verify`。
+
+```bash
+sl system form button design get --form-id <uuid> --json
+sl system form button design update --form-id <uuid> --definition-file button-design.json --json
+sl system form button design custom create --form-id <uuid> --definition-file button.json --json
+sl system form button design custom update --form-id <uuid> --button-id <uuid> --definition-file button-patch.json --json
+sl system form button design custom delete --form-id <uuid> --button-id <uuid> --json
+
+sl system form button script-binding get --asset-id <uuid> --form-id <uuid> --json
+sl system form button script-binding bind --asset-id <uuid> --file-path src/buttons/order.ts \
+  --form-id <uuid> --button-key custom:<uuid> --phase action --json
+sl system form button script-binding verify --asset-id <uuid> --file-path src/buttons/order.ts \
+  --form-id <uuid> --button-key custom:<uuid> --phase action --json
+sl system form button script-binding unbind --asset-id <uuid> --file-path src/buttons/order.ts \
+  --form-id <uuid> --button-key custom:<uuid> --phase action --json
+```
+
+Generic form records use the same condition engine:
+
+```bash
+sl system form record list \
+  --form-api-name orders \
+  --condition-json '{"logic":"and","children":[{"field":"status","operator":"eq","value":"active"}]}' \
+  --sort-field-api-name createdAt --sort-direction desc \
+  --include-detail --include-total --page 1 --page-size 20 --json
+
+sl system form record list \
+  --form-api-name orders \
+  --keywords-json '["Shanghai","priority"]' \
+  --search-field-api-name customerName \
+  --visibility-states-json '[{"dataStatus":"active","approvalStatus":"approved"}]' \
+  --include-detail --json
+
+sl system form record get --record-id <uuid> --json
+sl system form record cleanup --form-api-name orders --mode restore --condition-json '{"field":"status","operator":"eq","value":"canceled"}' --json
+sl system form record cleanup --form-api-name orders --mode purge --keyword test --json
+```
+
+批量创建和更新使用 Runtime 的正式批量表单 API。每批必须包含 1–100 条显式记录；执行前仍需先用 `form button list` 解析当前成员可执行的 NEW 或 EDIT 按钮：
+
+```bash
+sl system form record batch create \
+  --form-api-name orders \
+  --button-key preset:form.submit \
+  --records-json '[{"title":"SO-1","data":{"orderNo":"SO-1"}},{"title":"SO-2","data":{"orderNo":"SO-2"}}]' \
+  --json
+
+sl system form record batch update \
+  --form-api-name orders \
+  --button-key preset:form.save \
+  --records-json '[{"recordId":"<uuid>","data":{"status":"completed"}}]' \
+  --json
+```
+
+批量写入在租户数据库事务中执行，任意一条失败会回滚整个批次。按钮 `beforeClick` 在事务开始前逐条执行；事务成功后逐条执行 `afterClick`，后置脚本失败会写入返回结果但不会回滚业务数据。
+
+查询当前成员有权使用的表单按钮：
+
+```bash
+sl system form button list \
+  --form-api-name orders \
+  --scope VIEW \
+  --record-id <uuid> \
+  --json
+```
+
+执行一个已解析的按钮。`--payload-json` 只传按钮所需的记录、草稿和业务输入，不能传租户、脚本或任意命令标识：
+
+```bash
+sl system form button execute \
+  --form-api-name orders \
+  --button-key preset:form.save \
+  --payload-json '{"recordId":"<uuid>","draft":{"data":{"status":"approved"}}}' \
+  --json
+```
+
+数据清理页的固定动作不属于表单按钮设计配置。先查询回收站记录，再解析并执行对应动作：
+
+```bash
+sl system form record list \
+  --form-api-name orders \
+  --data-status trashed \
+  --include-detail --json
+
+sl system form button list \
+  --form-api-name orders \
+  --scope VIEW \
+  --record-id <uuid> \
+  --json
+
+sl system form button execute \
+  --form-api-name orders \
+  --button-key preset:dataCleanup.restore \
+  --payload-json '{"recordId":"<uuid>"}' \
+  --json
+
+sl system form button execute \
+  --form-api-name orders \
+  --button-key preset:dataCleanup.purge \
+  --payload-json '{"recordId":"<uuid>"}' \
+  --json
+```
+
+`dataCleanup.purge` 会提交不可恢复的物理清除任务，只接受已经在回收站且没有清除任务进行中的记录。批量操作使用 `preset:dataCleanupBatch.restore` 和 `preset:dataCleanupBatch.purge`，并在 `recordIds` 中传入最多 100 个记录 ID。
+
+处理“当前筛选条件的全部结果”时，不需要先分页收集记录 ID，直接提交筛选条件：
+
+```bash
+sl system form record cleanup \
+  --form-api-name orders \
+  --mode restore \
+  --condition-json '{"field":"status","operator":"eq","value":"canceled"}' \
+  --json
+
+sl system form record cleanup \
+  --form-api-name orders \
+  --mode purge \
+  --keyword test \
+  --excluded-record-ids-json '["<uuid>"]' \
+  --json
+```
+
+该命令固定只处理回收站记录，并在租户 Runtime 内按筛选条件生成批处理任务。`purge` 是不可恢复操作；组织、部门和成员目录不能使用此命令。
+
+Member queries use `active` and `inactive` statuses, while organization and department
+queries use `active` and `disabled`. Organization and department member scopes are
+mutually exclusive, and `--include-descendants` requires one of those scopes.
+
+The update requires `system-organization.page / enter` and the page action `system-organization.page.edit / execute`.
+
+## Document Reading
+
+Document commands operate on an existing tenant file asset. The first read or search
+parses the source with the tenant Docling service and persists searchable chunks in the
+tenant database. Continue large reads with the `position.next` values returned by the
+previous call.
+
+```bash
+sl system document metadata get --file-id <file-uuid> --json
+sl system document read --file-id <file-uuid> --max-chunks 20 --max-chars 30000 --json
+sl system document search --file-id <file-uuid> --query 'payment terms' --limit 8 --json
+```
+
+## Help Center
+
+Help commands answer how-to questions from the released Soln Help Center content that ships
+with the runtime. They read the product manual only and never touch tenant business data.
+Use them before explaining how a page, module, or workflow is used.
+
+```bash
+sl system help list --keyword form --limit 50 --json
+sl system help search --query 'how do I configure an approval process' --json
+sl system help search --query '审批流程怎么配置' --locale zh-CN --limit 3 --json
+sl system help read --doc-id using-soln/approval-processes/process-management --max-chars 12000 --json
+```
+
+`search` returns each matching topic `docId`, `section`, `url`, and a bounded snippet. Continue
+with `system help read` and its `position.next` value when a topic is longer than one response.
+`--locale` accepts `en` or `zh-CN`; a topic without translation falls back to English and reports
+`localeFallback: true`.
+
+## Analysis Datasets
+
+Persistent datasets are tenant-owned definitions. Create and update accept complete JSON
+snapshots; read the existing dataset before update. Physical field keys use
+`t0.<apiName>`, `t1.<apiName>`, and so on. A computed config uses a bare key, while its
+persisted field uses `computed.<key>`.
+
+```json
+{
+  "name": "Order analysis",
+  "description": null,
+  "sourceConfig": {
+    "formId": "<form-uuid>",
+    "joins": [],
+    "computedFields": [{
+      "key": "net_amount",
+      "name": "Net amount",
+      "expression": "FIELD(\"t0.so_amount\") * 0.9",
+      "dataType": "number",
+      "valueSource": "expression"
+    }]
+  },
+  "fields": [{
+    "key": "computed.net_amount",
+    "name": "Net amount",
+    "sourceName": "Net amount",
+    "apiName": "net_amount",
+    "tableAlias": "computed",
+    "tableName": "computed",
+    "formId": null,
+    "dataType": "number",
+    "fieldType": "number",
+    "originType": "COMPUTED",
+    "expression": "FIELD(\"t0.so_amount\") * 0.9",
+    "semanticType": "MEASURE",
+    "aggregationType": "sum",
+    "isVisible": true,
+    "metadata": { "valueSource": "expression" }
+  }]
+}
+```
+
+```bash
+sl system analysis dataset list --json
+sl system analysis dataset get --dataset-id <dataset-uuid> --json
+sl system analysis dataset create --definition-file dataset.json --json
+sl system analysis dataset update --dataset-id <dataset-uuid> --definition-file dataset.json --json
+sl system analysis dataset query --dataset-id <dataset-uuid> --query-file query.json --json
+```
+
+Studio-derived columns are persistent numeric computed measures. Set `valueSource` to
+`studio_script`, leave both expressions empty, discover a published server-script asset
+and file, then provide both UUIDs in the query or chart binding:
+
+```json
+{
+  "mode": "aggregate",
+  "dimensions": ["t0.so_region"],
+  "measures": ["computed.adjusted_amount"],
+  "bindingScript": {
+    "studioScriptAssetId": "<published-asset-uuid>",
+    "studioScriptFileId": "<published-file-uuid>",
+    "matchFields": [{ "datasetFieldKey": "t0.so_region", "resultKey": "region" }],
+    "assignments": [{
+      "computedFieldKey": "computed.adjusted_amount",
+      "resultKey": "adjustedAmount"
+    }],
+    "where": {}
+  }
+}
+```
+
+Session datasets are conversation-scoped and support physical fields plus expression
+computed fields. They do not support `bindingScript`.
+
+```bash
+sl system analysis session-dataset create --thread-id <thread-uuid> --definition-file session-dataset.json --json
+sl system analysis session-dataset list --thread-id <thread-uuid> --json
+sl system analysis session-dataset get --thread-id <thread-uuid> --session-dataset-id <uuid> --json
+sl system analysis session-dataset query --thread-id <thread-uuid> --session-dataset-id <uuid> --query-file query.json --json
+sl system analysis session-dataset delete-for-thread --thread-id <thread-uuid> --json
+```
+
+## Automation Tasks
+
+Automation commands use the Runtime service and tenant repository directly. For AI-authored
+graphs, load the authorized catalog with `draft context`, build a semantic spec, and call
+`draft validate`. Reuse the exact validated `graphSchema` for create or version creation.
+
+```bash
+sl system automation draft context --json
+sl system automation draft validate --spec-file automation-spec.json --locale zh-CN --timezone Asia/Shanghai --json
+sl system automation draft generate --goal "Notify the owner after an order is created" --timezone Asia/Shanghai --json
+sl system automation task list --keyword order --json
+sl system automation task get --definition-id <uuid> --json
+sl system automation task create --definition-file automation-create.json --json
+sl system automation task update --definition-id <uuid> --definition-file automation-update.json --json
+sl system automation task delete --definition-id <uuid> --json
+sl system automation task version list --definition-id <uuid> --json
+sl system automation task version create --definition-id <uuid> --graph-file automation-graph.json --json
+sl system automation task version publish --definition-id <uuid> --version-id <uuid> --json
+sl system automation task run --definition-id <uuid> --payload-json '{"recordId":"<uuid>"}' --json
+sl system automation execution list --definition-id <uuid> --status failed --from 2026-08-01T00:00:00+08:00 --to 2026-08-18T00:00:00+08:00 --json
+sl system automation execution get --execution-id <uuid> --json
+sl system automation execution batch-failure list --execution-id <uuid> --page 1 --page-size 20 --json
+```
+
+`task create` accepts `code`, `name`, optional `description`, and a complete `graphSchema`.
+`task update` only changes definition fields or status; graph changes create a new immutable
+version. A Studio service node requires both the published `studioScriptAssetId` and published
+entry `studioScriptFileId`; a file path is not a file ID. Runtime command help contains the
+trigger, node, message mapping, OpenLink callback, script payload, and return-value contracts.
+
+## Studio Projects
+
+Create a local Studio page project:
+
+```bash
+soln studio init page --code customer-dashboard --name "Customer Dashboard"
+```
+
+This creates:
+
+```txt
+soln.extension.json
+src/App.tsx
+package.json
+tsconfig.json
+```
+
+Deploy the current Studio project to the authenticated tenant:
+
+```bash
+soln studio deploy
+```
+
+Deploy reads `soln.extension.json`, uploads source files to the existing Studio asset API, and asks the Soln API to compile the asset. Server-side compile remains the source of truth.
+When a new Studio asset is created, the CLI writes the returned `assetId` back to `soln.extension.json`.
+
+Publish the deployed Studio asset:
+
+```bash
+soln studio publish --notes "Initial release"
+```
+
+Pull an existing Studio asset into a local project:
+
+```bash
+soln studio pull --asset-id <asset-id> --dir ./customer-dashboard
+```
+
+Pull refuses to overwrite local files with different content unless `--force` is provided.
+
+Inspect a local Studio project:
+
+```bash
+soln studio status
+soln studio status --check
+```
+
+`--check` loads the bound remote asset and reports whether local files need deploy.
+
+Use JSON output from scripts:
+
+```bash
+soln studio deploy --json
+soln studio publish --json
+soln studio pull --asset-id <asset-id> --json
+soln studio status --check --json
+```
+
+### 转发表单记录到聊天
+
+先查询记录、接收人，并通过 `sl system form button list` 确认有转发权限。
+接收人使用 `sl system organization structure member list --keyword 张三 --json` 返回的成员 ID；同名时先确认目标。
+
+单条转发：
+
+```bash
+sl system form button execute \
+  --form-api-name orders \
+  --button-key preset:detail.forward \
+  --payload-json '{"recordId":"<记录UUID>","input":{"targetMemberIds":["<成员UUID>"],"clientBatchId":"<本次操作UUID>"}}' \
+  --json
+```
+
+批量转发使用 `preset:listBatch.forward`，将 `recordId` 改为 `recordIds` 数组。
+每次最多 100 条记录、100 位接收人；生成的消息不得超过 4000 字符。
+同一次操作重试时复用 `clientBatchId`；新的转发使用新的 UUID。
+Runtime 从记录生成名称和详情链接，并执行按钮权限、读取权限、显示条件和按钮脚本。
+结果包含 `succeededCount`、`failedCount`、成功消息 ID 和失败接收人列表。

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@soln/cli",
+  "version": "0.1.0",
+  "description": "Command-line interface for Soln member authentication.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "sl": "soln.mjs",
+    "soln": "soln.mjs"
+  },
+  "files": [
+    "soln.mjs",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}