@hyperscale0/cli 1.0.235 → 1.0.248

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/AGENTS.md +75 -0
  2. package/README.md +121 -66
  3. package/hyperscale.js +49 -51
  4. package/package.json +10 -3
package/AGENTS.md ADDED
@@ -0,0 +1,75 @@
1
+ # Hyperscale CLI for agents
2
+
3
+ Use `hyperscale help --json` for the complete tree, flags and examples.
4
+ Use `hyperscale <group> <command> --help --json` for one command.
5
+
6
+ ```text
7
+ auth login, signup, logout
8
+ whoami verify login and show the selected product
9
+ product create, list, show, select
10
+ hsx pull, check, plan, apply, watch
11
+ key create, list, revoke
12
+ action list, show, run
13
+ object kinds, list, show, create, actions, run
14
+ activity list, tail
15
+ architect chat
16
+ api list, call, resume
17
+ open Launch or Build product page
18
+ help command tree
19
+ ```
20
+
21
+ Start with `hyperscale auth login --no-open --json`. The URL and code go to
22
+ stderr. A person approves them in the browser. Rerun to resume a pending login.
23
+ Verify with `hyperscale whoami --json`. Signup uses `auth signup --email <email>
24
+ --name <name> --company <company>`. Do not print or persist credentials in
25
+ project files.
26
+
27
+ Browser login creates a named agent member with its own CLI grant. Access
28
+ tokens last ten minutes; the CLI rotates the refresh token and keeps both in
29
+ Keychain or a mode 0600 file. Logout removes them locally. Revoke the member or
30
+ grant in the browser; `--revoke` only revokes a human PAT. Sandbox work within
31
+ the grant runs directly. A live action exits 3 with `agent_approval_required`
32
+ and a browser link; a human approves it with their password. The CLI cannot
33
+ approve its own work.
34
+
35
+ Every command accepts `--json`. Ordinary success is one JSON value on stdout;
36
+ failure is an error object on stderr. Errors retain status, code, message,
37
+ fix, details and available request, operation, receipt and trace IDs.
38
+ JSON output has no ANSI codes, banners, spinners or prompts.
39
+ Exit codes: 0 success, 1 failure, 2 HSX check or plan cannot proceed,
40
+ 3 live action waiting for human approval.
41
+
42
+ `hsx watch --json` emits one JSON object per line with `type` set to `check`,
43
+ `plan` or `error`. Check and plan events contain `data`; errors contain `error`.
44
+ `--plan` plans only after a successful check. `activity tail --json` emits
45
+ `{"type":"activity","data":...}` per line; `--follow` polls until interrupted.
46
+
47
+ Select a product with `product select <id>` or use `--product <id>` once.
48
+ Pull its source with `hsx pull product.hsx`. Check, plan to JSON, then apply
49
+ with `--plan-file plan.json --config settings.json --yes`. Settings contain a
50
+ `partyBindings` map. Do not apply an unreviewed or changed plan.
51
+
52
+ Use `object kinds`, `object actions <kind> <object>` and `action show <action>`
53
+ to discover fields. Object create and run accept `--fields-file`; run also
54
+ accepts `--input-file`. Object run reads revision and action settings itself.
55
+ Use `--attachment` or `--instance` if an action has multiple agreements.
56
+
57
+ Mutations generate an idempotency key unless you pass `--idempotency-key`.
58
+ Reuse a key only for the same request. Browser review returns a saved reference;
59
+ resume it with `api resume <reference> --json`. Review is not execution proof.
60
+
61
+ Set HYPERSCALE_BASE_URL, HYPERSCALE_ENVIRONMENT (sandbox or live),
62
+ HYPERSCALE_TOKEN for member access or HYPERSCALE_API_KEY for product access.
63
+ Cloudflare Access requires both HYPERSCALE_CF_ACCESS_CLIENT_ID and
64
+ HYPERSCALE_CF_ACCESS_CLIENT_SECRET. Use environment lookups for secrets.
65
+ `open --json` returns a URL and never launches a browser.
66
+
67
+ Portal origins follow the API host, including workspace-launch and
68
+ workspace-build for the workspace API. Loopback APIs have no derived portals.
69
+ `hyperscale --version --json` includes the resolved install path, API origin,
70
+ environment, portal origins and cached npm latest version when known. A colour
71
+ TTY shows these with the locally saved identity, company and selected product.
72
+ Interactive update checks run in the background at most once a day. JSON,
73
+ pipes, CI and `HYPERSCALE_NO_UPDATE_CHECK=1` suppress checks and notices.
74
+ Read the [docs](https://hyperscale0.ai/docs) and
75
+ [agent guide](https://hyperscale0.ai/agents/SKILL.md).
package/README.md CHANGED
@@ -1,85 +1,140 @@
1
- # @hyperscale0/cli
1
+ # Hyperscale CLI
2
2
 
3
- The Hyperscale developer command line.
3
+ Build and operate financial products from your terminal. Work in HSX, manage
4
+ products and keys, and run actions. Use Launch and Build for the visual editor
5
+ and richer product design.
4
6
 
5
- ## Start
7
+ Install with Node 20 or later:
6
8
 
7
9
  ```sh
8
- bunx @hyperscale0/cli@latest auth status
9
- bunx @hyperscale0/cli@latest auth login
10
+ npm install -g @hyperscale0/cli
11
+ hyperscale
10
12
  ```
11
13
 
12
- The CLI prints a URL and code. Approve them in your browser. A rerun resumes a
13
- pending request. Use `--no-open` to open the URL on another device. New
14
- founders can run:
14
+ ## Sign in
15
15
 
16
16
  ```sh
17
- bunx @hyperscale0/cli@latest signup --email founder@example.com --name 'Founder Name' --company 'Company Name'
17
+ hyperscale auth login
18
+ hyperscale whoami
18
19
  ```
19
20
 
20
- Browser consent grants the agent scope set for sandbox Product work. The CLI
21
- stores the token in macOS Keychain or an owner-only 0600 file. Never search for
22
- or ask the founder to paste a token. `HYPERSCALE_TOKEN` remains available for
23
- existing automation. See https://hyperscale0.ai/auth.md for MCP setup.
21
+ Approve the URL and code in your browser. The CLI saves your login on this
22
+ device. Use `--no-open` to approve on another device. A pending sign-in resumes
23
+ when you run the command again. To create an account:
24
24
 
25
- ## Product commands
25
+ ```sh
26
+ hyperscale auth signup --email you@example.com --name "Your name" --company Acme
27
+ ```
28
+
29
+ `hyperscale auth logout` removes the local login. Add `--revoke` to revoke the
30
+ token too. Tokens and saved requests use macOS Keychain when available, with
31
+ an owner-only file fallback (mode 0600). `HYPERSCALE_CREDENTIAL_STORE=file`
32
+ selects file storage. `HYPERSCALE_CONFIG_DIR` sets its directory.
33
+
34
+ ## Work on a product
35
+
36
+ ```sh
37
+ hyperscale product list
38
+ hyperscale product select <id>
39
+ hyperscale hsx pull product.hsx
40
+ hyperscale hsx check product.hsx
41
+ hyperscale hsx plan product.hsx --config settings.json --json > plan.json
42
+ hyperscale hsx apply product.hsx --config settings.json --plan-file plan.json --yes
43
+ hyperscale hsx watch product.hsx --plan --config settings.json
44
+ hyperscale open --portal build
45
+ ```
46
+
47
+ Edit the HSX file in your editor. Watch checks each saved change. With `--plan`,
48
+ it also plans after each successful check. Apply uses the saved plan and
49
+ requires `--confirm` for a person or `--yes` for automation. Product settings
50
+ contain `partyBindings`, a map of participant names to IDs.
51
+
52
+ Create a new product with `product create --source product.hsx --name Savings
53
+ --config settings.json`. Use `product show` for the current product, or pass
54
+ an ID. `--product <id>` selects a product for one command.
55
+
56
+ ## Run actions and work with objects
57
+
58
+ ```sh
59
+ hyperscale action list
60
+ hyperscale action show <action>
61
+ hyperscale action run <action> --input-file request.json
62
+ hyperscale object kinds
63
+ hyperscale object list <kind>
64
+ hyperscale object create <kind> --fields-file fields.json
65
+ hyperscale object show <kind> <object>
66
+ hyperscale object actions <kind> <object>
67
+ hyperscale object run <kind> <object> <action> --fields-file fields.json --input-file request.json
68
+ ```
69
+
70
+ Object fields are plain business data. The CLI fetches the object's current
71
+ revision and the action's product settings before running it. If several
72
+ agreements offer the same action, choose `--attachment` or `--instance`.
73
+ Use `--on-behalf-of` to act for a customer. Mutations accept
74
+ `--idempotency-key`; reuse a key only for the same request.
26
75
 
27
- `product select <id>` saves a Product. Member PATs use that Product's route.
28
- Use a Product API key in `HYPERSCALE_API_KEY` for object operations.
29
- Keep Product identity in the input and omit the global `--product` flag:
76
+ ## Keys, activity and API access
30
77
 
31
78
  ```sh
32
- bunx @hyperscale0/cli@latest call product.objects.discover --input '{"productId":"<product-id>"}' --json
33
- bunx @hyperscale0/cli@latest call product.objects.create --input '{"productId":"<product-id>","kind":"<kind>"}' --idempotency-key object-001 --json
34
- bunx @hyperscale0/cli@latest call product.objects.actions --input '{"productId":"<product-id>","kind":"<kind>","objectId":"<object-id>"}' --json
35
- bunx @hyperscale0/cli@latest call product.objects.execute --input-file action.json --idempotency-key action-001 --json
79
+ hyperscale key create --name Agent
80
+ hyperscale key list
81
+ hyperscale key revoke <id> --confirm
82
+ hyperscale activity list
83
+ hyperscale activity tail --follow
84
+ hyperscale api list --catalog
85
+ hyperscale api call <operation> --input-file request.json --json
86
+ hyperscale api resume <reference> --json
87
+ hyperscale architect chat --brief "Review this product" --json
88
+ hyperscale open
36
89
  ```
37
90
 
38
- Copy action.name, productBuildId, digest and target from the chosen available
39
- action into action.json. Also include productId, kind, objectId, expectedRevision
40
- from the actions response, and required fields and input. Copy instanceId when
41
- present in target. Object creation never enters an agreement or moves money.
42
- Use product.objects.list and product.objects.retrieve for stored objects.
43
- See https://hyperscale0.ai/docs/runtime.md for the complete request shape.
44
-
45
- Low-level `product actions` and `product run` remain for admitted operations.
46
- Instrument creation stays internal to object attachment execution.
47
-
48
- `ops list --catalog` browses catalog command data without authentication.
49
- `ops list` discovers operations for the active credential and Product.
50
- `call <operation>` calls one with `--input` or `--input-file`.
51
- `compose check/plan/apply <file.hsx>` uses the server composer.
52
- Run `bunx @hyperscale0/cli@latest help <command>` for options and examples.
53
-
54
- ## Resume
55
-
56
- A transport failure or interrupted dispatch prints a local resume reference.
57
- Then run `bunx @hyperscale0/cli@latest resume <reference>`. Resume replays the same origin,
58
- environment, credential, path, body bytes and idempotency key from secure local
59
- storage. Body and credential overrides are refused.
60
-
61
- A lost response does not mean failure. Keep the printed operation reference
62
- and read its status before retrying. Resume never creates a new idempotency key.
63
- Successful requests remove their saved credential copy. Uncertain
64
- requests remain local until they complete. Logout removes the login credential;
65
- it does not revoke separately saved pending requests. Use portal token revocation
66
- if those requests must lose server authority.
67
-
68
- ## Automation and storage
69
-
70
- `--json` writes success to stdout and one error object to stderr on failure.
71
- Errors retain HTTP status, code, message, fix, details and available correlation
72
- IDs. Exit 0 means success, 1 means failure, and 2 means composer refusal. JSON help is also available.
73
-
74
- Human output honors non-TTY streams, narrow terminals and NO_COLOR, including
75
- an empty NO_COLOR value. Identifiers are never shortened.
76
-
77
- Credentials and saved requests use macOS Keychain with an owner-only 0600 file
78
- fallback under `HYPERSCALE_CONFIG_DIR` or `~/.config/hyperscale`.
79
- `HYPERSCALE_CREDENTIAL_STORE=file` explicitly selects file storage.
80
- Use `--base-url` or `HYPERSCALE_BASE_URL` for the API origin and
81
- `--environment sandbox|live` for the environment partition.
82
- Neither current estate connects to real bank infrastructure.
91
+ API access covers all published operations. A request that needs browser
92
+ review prints a URL and a saved reference. Approve it, then use `api resume`.
93
+ Approval alone does not mean the request completed.
94
+
95
+ ## Output and settings
96
+
97
+ Every command supports `--json`. Success goes to stdout and errors go to stderr.
98
+ Ordinary commands print one JSON value. `hsx watch --json` prints one event per
99
+ line with type `check`, `plan` or `error`. `activity tail --json` prints one
100
+ `activity` event per line. Stop watch and follow with Ctrl+C.
101
+
102
+ Piped output is plain. TTY output uses the Hyperscale wordmark, blue headers,
103
+ aligned fields and tables. `NO_COLOR` suppresses colour, banners and animation.
104
+ `FORCE_COLOR=0` also disables colour. Truecolor terminals use brand RGB colours;
105
+ other terminals use 256 or 16 colours. A non-TTY stream never receives ANSI codes.
106
+
107
+ `hyperscale -v` shows the version, resolved install path, active API and
108
+ environment, portal origins and saved identity, company and product on a colour
109
+ TTY. It also links to [docs](https://hyperscale0.ai/docs) and the
110
+ [agent guide](https://hyperscale0.ai/agents/SKILL.md). Plain output stays one
111
+ version string. `--version --json` returns install and origin fields too.
112
+
113
+ Interactive commands show one update notice after their output when npm has a
114
+ newer CLI. A detached check caches each attempt for a day in the config directory
115
+ and times out after 1.5 seconds. The next run can use its result. JSON, pipes,
116
+ CI and `HYPERSCALE_NO_UPDATE_CHECK=1` suppress checks and notices. To upgrade,
117
+ run `npm install -g @hyperscale0/cli@latest`.
118
+
119
+ `hyperscale help --json` returns the whole command tree with flags and examples.
120
+ Use `hyperscale <group> <command> --help` for one command. Exit codes are 0 for
121
+ success, 1 for failure and 2 for an HSX check or plan that cannot proceed.
122
+
123
+ Set `HYPERSCALE_BASE_URL` for the API origin and `HYPERSCALE_ENVIRONMENT` for
124
+ `sandbox` or `live`. `HYPERSCALE_TOKEN` supplies a login token and
125
+ `HYPERSCALE_API_KEY` supplies a product key. Each has a matching command flag.
126
+ An origin behind Cloudflare Access also needs both
127
+ `HYPERSCALE_CF_ACCESS_CLIENT_ID` and `HYPERSCALE_CF_ACCESS_CLIENT_SECRET`.
128
+
129
+ The API defaults to `https://hyperscale0.ai`. Portal origins follow the API
130
+ host: the workspace API uses workspace-launch and workspace-build. `open`
131
+ refuses loopback APIs because they do not identify a portal host. The about
132
+ screen reads local profile data. Login and human `whoami` save the company name
133
+ when the API supplies it; older profiles show "not saved" until then.
134
+
135
+ The terminal covers HSX files and product operations. The portals own the visual
136
+ editor, full product design, company administration and provider setup.
137
+ Infrastructure logs have no public CLI endpoint; activity is the public record.
83
138
 
84
139
  License: LicenseRef-Hyperscale-Proprietary.
85
140
  Hyperscale is a trademark of Hyperscale LLC.