@siteoshq/cli 1.0.0 → 1.1.1

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/README.md +114 -119
  2. package/dist/cli.js +3014 -1945
  3. package/dist/cli.js.map +1 -1
  4. package/package.json +7 -3
package/README.md CHANGED
@@ -1,179 +1,174 @@
1
1
  # SiteOS CLI
2
2
 
3
- `@siteoshq/cli` is the single command-line client for SiteOS Auth, Pulse, Forms, and Search. The
4
- package exposes one binary, `siteos`, and starts its public release line at `1.0.0`.
5
-
6
- ## Install
7
-
8
- Run without installing:
9
-
10
- ```sh
11
- npx @siteoshq/cli --help
12
- ```
3
+ `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
4
+ Search, Trace and Integrations. This source prepares version 1.1.1; publishing is a separate release.
5
+ Node.js 22 or newer is required.
13
6
 
14
- Or install the binary globally:
7
+ ## Install and authenticate
15
8
 
16
9
  ```sh
17
10
  npm install --global @siteoshq/cli
18
11
  siteos --version
12
+ siteos auth start --email developer@example.com --json
13
+ siteos auth complete --token '<one-time-token>' --json
14
+ siteos auth organizations --json
15
+ siteos auth select --organization '<organization-id>' --json
16
+ siteos auth status --json
19
17
  ```
20
18
 
21
- Node.js 22 or newer is required.
19
+ The one-time token is secret. Only `auth complete` receives it. The durable session is stored
20
+ privately in `~/.siteos/auth.json`. Product commands exchange it for short-lived, audience-bound
21
+ grants; the durable session never reaches a product endpoint.
22
+
23
+ ## Hosted origins
22
24
 
23
- ## Authenticate
25
+ CLI 1.1.1 defaults to `https://app.siteos.sh` for Auth and every service. Existing credentials
26
+ and repository bindings retain their selected origin; sign in again when moving installations.
27
+ Never copy private state between production and staging.
24
28
 
25
- The CLI authenticates once with central SiteOS Auth. Auth owns the user session and Organization
26
- selection; each product still owns its own Projects.
29
+ For the separate SiteOS staging installation, set all four overrides before authentication:
27
30
 
28
31
  ```sh
29
- siteos auth start --email developer@example.com --json
30
- siteos auth complete --token <one-time-token> --json
31
- siteos auth organizations --json
32
- siteos auth select --organization <organization-id> --json
33
- siteos auth status --json
32
+ export SITEOS_AUTH_BASE_URL=https://siteosapp.xui.se
33
+ export SITEOS_PULSE_API_URL=https://siteosapp.xui.se
34
+ export SITEOS_FORMS_PUBLIC_URL=https://siteosapp.xui.se
35
+ export SITEOS_SEARCH_PUBLIC_URL=https://siteosapp.xui.se
34
36
  ```
35
37
 
36
- The one-time token is secret and should only be passed to `auth complete`. The durable session is
37
- stored privately in `~/.siteos/auth.json`. Product commands exchange it for a short-lived,
38
- audience-bound service grant; the durable session is never sent to Pulse, Forms, or Search.
38
+ These select the SiteOS installation. A Project's Production or Staging Environment is a separate,
39
+ project-level selection inside that installation.
39
40
 
40
- ## Select product Projects
41
+ ## Select one Project
41
42
 
42
- There is no global SiteOS Project. Pulse, Forms, and Search each create and authorize their own
43
- Projects inside the selected Auth Organization.
43
+ From the website repository:
44
44
 
45
45
  ```sh
46
- siteos pulse project list --json
47
- siteos pulse project create --slug storefront --name "Storefront" --json
48
- siteos pulse project use storefront --json
49
-
50
- siteos forms project list --json
51
- siteos forms project create --slug storefront-forms --name "Storefront Forms" --json
52
- siteos forms project use storefront-forms --json
53
-
54
- siteos search project list --json
55
- siteos search project create --slug storefront-search --name "Storefront Search" --json
56
- siteos search project use storefront-search --json
46
+ siteos project list --json
47
+ siteos project create --name "Storefront" --slug storefront --url https://example.com --json
48
+ siteos project use storefront --json
49
+ siteos project status --json
50
+ siteos project connect forms --json
51
+ siteos project connect search --json
52
+ siteos project environment create --name Staging --slug staging --url https://staging.example.com --json
53
+ siteos project environment use staging --json
57
54
  ```
58
55
 
59
- Creating or selecting a Project in one service never creates, selects, links, or mutates a Project
60
- in another service. `project use` writes a secret-free product reference into the repository and a
61
- private immutable-ID binding into `~/.siteos/project-bindings.json`.
56
+ Creating a common Project records its catalog and a Production Environment. It does not create
57
+ service resources. Each explicit `connect` creates the requested resource and, where supported,
58
+ the selected common environment atomically. Cookie and Trace setup remains unpublished; Pulse monitoring remains
59
+ disabled until configured. Use `--resource '<service-resource-id>'` to adopt an existing resource.
60
+ No name, slug or URL matching is used for adoption.
62
61
 
63
- Tracked repository files:
62
+ Existing resource environments also require explicit adoption:
64
63
 
65
- | Service | File | Purpose |
66
- | --- | --- | --- |
67
- | Pulse | `siteos.config.json` | Project slug and versioned Playwright Check configuration |
68
- | Forms | `.siteos/forms/project.json` | Forms Project name and slug, schema version 1 |
69
- | Search | `.siteos/search/project.json` | Search Project name and slug, schema version 1 |
70
-
71
- Private CLI files:
64
+ ```sh
65
+ siteos project environment resources forms --json
66
+ siteos project environment connect forms --environment production --resource '<forms-environment-id>' --json
67
+ ```
72
68
 
73
- | File | Purpose |
74
- | --- | --- |
75
- | `~/.siteos/auth.json` | Central Auth session and selected Organization |
76
- | `~/.siteos/project-bindings.json` | Version 1 bindings keyed by service, API origin, and real repository path |
69
+ Omit `--resource` to create a new local environment. `siteos project environment list` reports the
70
+ common catalog and connections. Forms/Search/Trace operational `--environment` flags accept common
71
+ slugs and resolve explicit native bindings; without the flag, commands use the selected environment.
72
+ Pulse/Cookie use separate bound resources per environment. Missing bindings fail without a fallback.
73
+ Manage names and website URLs with `project update` and `project environment update <slug>`.
74
+ Cookie/Trace published addresses remain unchanged until explicit republication.
77
75
 
78
- Set `SITEOS_HOME` to place both private files in another directory. Writes are atomic and preserve
79
- private file permissions. Do not commit either private file.
76
+ `project use` writes one private binding keyed by real repository path and application origin in
77
+ `~/.siteos/project-bindings.json`. It does not write a tracked global Project file. All service
78
+ management commands use this selection and their own runtime authority. An Organization mismatch
79
+ requires selecting the Project in the active Organization again.
80
80
 
81
- ## Pulse
81
+ ## Service workflows
82
82
 
83
- Initialize a Playwright monitoring project, validate it locally, and deploy an immutable bundle:
83
+ ### Pulse
84
84
 
85
85
  ```sh
86
- siteos pulse init --project storefront --base-url https://example.com
87
- siteos pulse project create --slug storefront --name "Storefront" --json
88
- siteos pulse project use storefront --json
86
+ siteos project connect pulse --json
87
+ siteos pulse project list --json
88
+ siteos pulse init
89
89
  siteos pulse validate --json
90
90
  siteos pulse test
91
91
  siteos pulse deploy --dry-run --json
92
- siteos pulse deploy --json
93
92
  ```
94
93
 
95
- `deploy --dry-run` builds the same versioned JSON manifest and archive without requiring Auth or
96
- uploading data. A normal deploy requires an explicit Pulse binding for the current repository and
97
- uses the bound immutable Project ID. Use `SITEOS_PULSE_API_URL` to override the Pulse origin; the
98
- default is `https://siteos-pulse.xui.se`.
99
-
100
- ## Forms
94
+ Initialization uses the common Project identity and selected environment URL. Deployments resolve
95
+ the bound Pulse resource and current URL; local tests use this URL unless explicitly overridden.
96
+ `siteos.config.json` remains the tracked Playwright check configuration. Deployment and enabling
97
+ monitoring are explicit operations. `deploy --dry-run` builds locally without uploading.
101
98
 
102
- After selecting a Forms Project, manage its Environments, definitions, and scoped credentials:
99
+ ### Forms and Search
103
100
 
104
101
  ```sh
105
- siteos forms environment create --slug production --name "Production" --json
102
+ siteos forms environment list --json
106
103
  siteos forms definition check --manifest .siteos/forms/manifest.json --json
107
104
  siteos forms definition sync --environment production --manifest .siteos/forms/manifest.json --json
108
105
  siteos forms credential issue --environment production --install --json
106
+ siteos search environment list --json
107
+ siteos search diagnostics --environment production --json
108
+ siteos search credential issue --environment production --install --json
109
+ siteos search indexing-credential issue --environment production --install --json
109
110
  ```
110
111
 
111
- `definition check` is local and does not need Auth. Management commands obtain a short-lived Forms
112
- service grant. `credential issue --install` writes the scoped runtime credential to the repository
113
- `.env` without printing its value. `forms submit` reads `SITEOS_FORMS_SUBMISSION_CREDENTIAL` and
114
- does not reuse management authority.
115
-
116
- Use `SITEOS_FORMS_PUBLIC_URL` to override the Forms origin. The development default is
117
- `http://localhost:3070`.
112
+ Credential installation writes only the owned assignments to a safely ignored `.env` and never
113
+ prints values. Forms submission credentials and Search query/indexing credentials remain separate
114
+ and environment-scoped. `forms submit --input '<path>'` uses only its runtime credential; it does
115
+ not acquire management authority. Definition checks remain local.
118
116
 
119
- ## Search
120
-
121
- After selecting a Search Project, manage explicit Environments and separate query/indexing
122
- credentials:
117
+ ### Cookie, Trace and Integrations
123
118
 
124
119
  ```sh
125
- siteos search environment create --slug production --name "Production" --json
126
- siteos search diagnostics --environment production --json
127
- siteos search credential issue --environment production --install --json
128
- siteos search indexing-credential issue --environment production --install --json
120
+ siteos project connect cookie --json
121
+ siteos cookie status --json
122
+ siteos cookie installation --json
123
+ siteos cookie draft get --json
124
+ siteos project connect trace --json
125
+ siteos trace environments --json
126
+ siteos trace installation show --environment production --json
127
+ siteos trace report --environment production --json
128
+ siteos integrations status --json
129
+ siteos integrations connect --json
129
130
  ```
130
131
 
131
- Installed query and indexing credentials remain separate. The CLI writes the appropriate
132
- `SITEOS_SEARCH_TOKEN`, `SITEOS_SEARCH_INDEXING_CREDENTIAL`, `SITEOS_SEARCH_ENV`, and
133
- `SITEOS_SEARCH_PUBLIC_URL` assignments without printing credential values.
132
+ Cookie/Trace draft editing and publication are separate commands with separate authorization
133
+ scopes. Save commands take versioned JSON input; inspect `--help` and the focused plugin skill.
134
+ Installation commands return the service-owned snippet and actual publication state. A Trace
135
+ snippet is unavailable until runtime publication succeeds. Integrations connections belong to the
136
+ Organization; provider authorization opens the shared browser flow, and notification destinations
137
+ are connected explicitly by each service.
134
138
 
135
- Use `SITEOS_SEARCH_PUBLIC_URL` to override the Search origin. The development default is
136
- `http://localhost:3080`.
137
-
138
- ## Local diagnostics
139
+ ## Local state and diagnostics
139
140
 
140
141
  ```sh
141
142
  siteos health-check --json
142
143
  ```
143
144
 
144
- The health check is read-only. It reports the CLI version, private configuration home, repository
145
- discovery, and the status of each product-owned Project reference. It does not contact APIs, read
146
- runtime credentials, or recognize the removed global `.siteos/project.json` format.
145
+ Diagnostics report local Project selection and legacy service references without contacting APIs
146
+ or reading runtime credentials. A selected Project means local setup exists, not remote health.
147
+ Set `SITEOS_HOME` to relocate private CLI state. Never commit `auth.json` or private bindings.
147
148
 
148
- ## Migrating from the old Pulse CLI
149
+ Legacy `pulse project`, `forms project` and `search project` selections remain supported for existing
150
+ repositories. Their service-aware bindings and tracked references (`siteos.config.json`,
151
+ `.siteos/forms/project.json`, `.siteos/search/project.json`) are fallback context when no common
152
+ Project is selected. They do not create common attachments. Old global `.siteos/project.json` and
153
+ old shared API keys are not imported or interpreted.
149
154
 
150
- The old Pulse executable package is not retained. On `pulse project status` or `pulse deploy`, the
151
- new CLI can safely import a matching version 2 binding from:
155
+ The retained Pulse migration can import a matching version 2 private binding from
156
+ `${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json` only when the origin, repository,
157
+ Organization and tracked Pulse slug agree. It leaves the original file untouched.
152
158
 
153
- ```text
154
- ${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json
155
- ```
159
+ ## Origins and errors
160
+
161
+ `SITEOS_AUTH_BASE_URL` selects the shared application origin for common Projects and all service
162
+ commands using that context (default `https://app.siteos.sh`). The legacy service flows retain
163
+ `SITEOS_PULSE_API_URL`, `SITEOS_FORMS_PUBLIC_URL` and `SITEOS_SEARCH_PUBLIC_URL` overrides. Runtime
164
+ integration uses its service's configured public URL and scoped credential.
165
+
166
+ Run `siteos <group> --help` for supported commands. Exit code 0 means success, 2 invalid usage,
167
+ and 1 an operational failure. Legacy Pulse additionally uses 3, 4 and 5 for authorization,
168
+ conflict and unavailable-service failures. JSON output is intended for agents and automation.
156
169
 
157
- Import occurs only when the API origin, real repository path, selected Auth Organization, and
158
- `siteos.config.json` Project slug all match. The CLI writes and reads back the new shared binding,
159
- then leaves the legacy file unchanged for manual comparison or rollback. It never imports the old
160
- global `.siteos/project.json` contract because that model incorrectly coupled Projects across
161
- products.
162
-
163
- ## Environment overrides
164
-
165
- | Variable | Purpose |
166
- | --- | --- |
167
- | `SITEOS_HOME` | Private CLI state directory; defaults to `~/.siteos` |
168
- | `SITEOS_AUTH_BASE_URL` | Central Auth origin; defaults to `https://siteos-auth.xui.se` |
169
- | `SITEOS_PULSE_API_URL` | Pulse API origin |
170
- | `SITEOS_FORMS_PUBLIC_URL` | Forms API and public origin |
171
- | `SITEOS_SEARCH_PUBLIC_URL` | Search API and public origin |
172
-
173
- Run `siteos <service> --help` for the complete command surface. JSON output is intended for agents
174
- and automation. Exit code `0` means success, `2` means invalid usage, and Pulse reserves `3`, `4`,
175
- and `5` for authorization, conflict, and unavailable-service failures. Other operational failures
176
- return `1`.
170
+ One SiteOS plugin supports Codex and Claude Code, with a general workflow and focused service
171
+ skills. Common Projects require CLI 1.1.0 and plugin 1.3.0 or newer.
177
172
 
178
173
  ## Development and publication checks
179
174