@yuou-finance/cli 0.1.0

package/README.md

@@ -0,0 +1,115 @@
+# HSCS CLI
+
+This Go CLI calls the API Key based `CliInvocationController` in `hscs-cli-service`. It stores each profile's API Key in the profile configuration, queries the organization and active roles associated with that key, and sends HTTP requests through `/cli/v1/invoke`.
+
+## Install from npm
+
+After the npm packages have been published to your configured registry, install the command with Node.js 18 or newer. Go is not needed on the installation machine.
+
+```sh
+npm install -g @yuou-finance/cli@0.1.0
+hscs --help
+
+# Run without a global install.
+npx --yes @yuou-finance/cli@0.1.0 --help
+```
+
+The initial packages contain binaries for macOS arm64, macOS x64, and Windows x64. The platform-specific binary is installed as an optional npm dependency. See [the npm release guide](docs/npm-release.md) for building and publishing all four packages.
+
+## Build and install
+
+Use Go 1.24 or newer:
+
+```sh
+go build -trimpath -o hscs ./cmd/hscs
+go test ./...
+go test -race -shuffle=on -count=1 ./...
+go vet ./...
+```
+
+Profiles store the service base URL, an optional local user label, and the API Key. The API Key determines the authenticated user and organization. New profiles use `https://service-api.yuoucn.com` by default; use `--environment URL` to override it. Existing profiles keep their configured URLs. Create a separate profile for each environment so each can keep its own service URL and API Key:
+
+```sh
+hscs profile add prod
+hscs profile add test --environment https://your-test-service.example
+
+# Select the environment to use; profile list marks the current one with '*'.
+hscs profile use test
+hscs profile list
+hscs profile show
+
+# Import the test environment's API Key while the test profile is selected.
+hscs api-key import "API_KEY"
+hscs identity organization-id
+hscs identity roles
+
+# Switch back to production and import its API Key separately.
+hscs profile use prod
+hscs api-key import "PRODUCTION_API_KEY"
+```
+
+Run `hscs profile use test` or `hscs profile use prod` to switch environments. API Keys are kept in their respective profiles. Replace the test service URL with the value for your deployment.
+
+`api-key import` and `api-key rotate` accept the API Key as a positional string and save it in the profile configuration file. The key is stored as plain text in that file; command-line arguments may also appear in shell history and local process inspection. `hscs api-key delete` removes the current profile's key. Profile deletion removes the profile and its API Key.
+
+Pass `--verbose` before or after a command to log HTTP method, endpoint, downstream target, response status and timing to stderr. Verbose output omits authentication headers and request/response bodies.
+
+For a headless deployment, set both `HSCS_SECURESTORE_FILE` and `HSCS_SECURESTORE_KEY`. The key must be base64 encoding of exactly 32 random bytes, supplied through your secret manager's environment injection. Keep the key outside the encrypted store and configuration, preserve it across invocations, and restrict access to the process environment.
+
+## Invocation
+
+`hscs identity organization-id` prints the organization ID for the current API Key. `hscs identity roles` prints the user's active roles as JSON. Use a listed role ID with `--role-id`; when omitted, the service selects the user's first active role.
+
+Static operations send their source-defined path in `X-CLI-Path`; query values are sent on the `/cli/v1/invoke` request and forwarded to the downstream endpoint. The service verifies that any organization ID in the path matches the API Key's organization. Use `--data-file` or `--stdin` for request body bytes and `--output RELATIVE_FILE` to save successful response bytes. For path templates, pass user-supplied values with `--path-params`. The CLI fetches `{organizationId}` from `/cli/v1/invoke/organization-id` using the current API Key; do not pass it yourself. Other values are encoded as individual path segments; missing, unused, or unsafe values are rejected.
+
+The static `hscs-business-manage query-ar-sales-orders` command queries revenue sales orders (营收销售单) through `POST /v1/{organizationId}/ar/sales-orders/query`. It first fetches the current organization ID through the CLI service, then uses it in the downstream path. Provide a JSON object body:
+
+```sh
+hscs hscs-business-manage query-ar-sales-orders \
+  --data-file request.json
+```
+
+The request body can also come from stdin with `--stdin`. For example, `request.json` may contain `{"salesOrderNum":"<sales-order-number>"}`. Replace placeholders with values from the current environment.
+
+The `hscs-business-manage list-cusz-sale-orders` command lists customized CUSZ sales orders through `POST /v1/{organizationId}/cusz/sale-orders/list`. It fetches the current organization ID automatically and accepts a JSON object body with optional filters:
+
+```sh
+hscs hscs-business-manage list-cusz-sale-orders \
+  --data-file request.json
+```
+
+The `hscs-business-manage get-cusz-sale-order-detail` command gets a customized sales order detail through `GET /v1/{organizationId}/cusz/sale-orders/{saleOrderId}`. It fetches the current organization ID automatically; provide the required numeric `saleOrderId` with `--path-params`:
+
+```sh
+hscs hscs-business-manage get-cusz-sale-order-detail \
+  --path-params '{"saleOrderId":12345}'
+```
+
+Static service operations bind HTTP method and target path in source; they do not accept `--method` or `--path`. Additional yecai bill-pipeline commands are available under:
+
+- `hscs-business-maindata` (for example `page-stores`)
+- `hscs-internet-everything` (for example `get-platform-config-lov`, `upload-out-data-file`)
+- `hscs-data-integration` (for example `query-itf-file-records`, `split-itf-imp-batches`)
+- `hscs-business-manage` (receipt, recon, and cust-rec operations such as `query-receipt-headers`, `confirm-recon`)
+- `hzero-iam` (for example `select-self`)
+
+Examples:
+
+```sh
+hscs hscs-internet-everything get-platform-config-lov \
+  --query '{"lovCode":"<lov-code>"}'
+hscs hscs-internet-everything upload-out-data-file \
+  --file ./bill.csv \
+  --form-fields '{"platform":"ALIPAY","shopId":"<shop-id>"}'
+hscs hscs-business-manage get-receipt-header-detail \
+  --path-params '{"receiptHeaderId":"<id>"}'
+hscs hzero-iam select-self
+```
+
+`split-itf-imp-batches` and `import-itf-imp-headers` require a JSON array body; most other POST operations require a JSON object body. See `skills/hscs-cli/REFERENCE.md` for the full static command list.
+
+The CLI does not follow redirects. For an HTTP error response, it writes the service's error body to stderr and exits non-zero; it does not retry automatically. For binary or large successful results, use `--output` so response bytes are streamed to a file.
+
+## Verification limits
+
+Local tests use test servers and do not prove compatibility with a deployed service. Record source commit, clean/dirty status, Go toolchain, target OS/architecture, build command and binary SHA-256 for a release. Windows compilation does not substitute for native Windows execution, ACL verification or keyring validation.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@yuou-finance/cli",
+  "version": "0.1.0",
+  "description": "HSCS command-line interface",
+  "license": "UNLICENSED",
+  "bin": {
+    "hscs": "scripts/run.js"
+  },
+  "scripts": {
+    "pack:release": "node scripts/build-npm-packages.js"
+  },
+  "files": [
+    "scripts/run.js"
+  ],
+  "os": [
+    "darwin",
+    "win32"
+  ],
+  "cpu": [
+    "x64",
+    "arm64"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "optionalDependencies": {
+    "@yuou-finance/cli-darwin-arm64": "0.1.0",
+    "@yuou-finance/cli-darwin-x64": "0.1.0",
+    "@yuou-finance/cli-win32-x64": "0.1.0"
+  }
+}

package/scripts/run.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+'use strict'
+
+const { spawn } = require('node:child_process')
+
+const platforms = {
+  'darwin-arm64': ['@yuou-finance/cli-darwin-arm64', 'hscs'],
+  'darwin-x64': ['@yuou-finance/cli-darwin-x64', 'hscs'],
+  'win32-x64': ['@yuou-finance/cli-win32-x64', 'hscs.exe'],
+}
+
+const platform = `${process.platform}-${process.arch}`
+const selected = platforms[platform]
+if (!selected) {
+  console.error(`hscs: unsupported platform ${platform}`)
+  process.exit(1)
+}
+
+let binary
+try {
+  binary = require.resolve(`${selected[0]}/bin/${selected[1]}`)
+} catch (error) {
+  if (error.code !== 'MODULE_NOT_FOUND') {
+    throw error
+  }
+  console.error(`hscs: platform package ${selected[0]} is missing; reinstall @yuou-finance/cli with optional dependencies enabled`)
+  process.exit(1)
+}
+
+const child = spawn(binary, process.argv.slice(2), { stdio: 'inherit' })
+for (const signal of ['SIGINT', 'SIGTERM']) {
+  process.on(signal, () => {
+    if (child.exitCode === null) {
+      child.kill(signal)
+    }
+  })
+}
+child.on('error', (error) => {
+  console.error(`hscs: cannot start ${binary}: ${error.message}`)
+  process.exitCode = 1
+})
+child.on('exit', (code, signal) => {
+  if (signal === 'SIGINT') {
+    process.exitCode = 130
+  } else if (signal === 'SIGTERM') {
+    process.exitCode = 143
+  } else {
+    process.exitCode = code === null ? 1 : code
+  }
+})