@siteoshq/cli 1.0.0 → 1.1.0

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 +99 -122
  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,156 @@
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.0; 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
19
- ```
20
-
21
- Node.js 22 or newer is required.
22
-
23
- ## Authenticate
24
-
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.
27
-
28
- ```sh
29
12
  siteos auth start --email developer@example.com --json
30
- siteos auth complete --token <one-time-token> --json
13
+ siteos auth complete --token '<one-time-token>' --json
31
14
  siteos auth organizations --json
32
- siteos auth select --organization <organization-id> --json
15
+ siteos auth select --organization '<organization-id>' --json
33
16
  siteos auth status --json
34
17
  ```
35
18
 
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.
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.
39
22
 
40
- ## Select product Projects
23
+ ## Select one Project
41
24
 
42
- There is no global SiteOS Project. Pulse, Forms, and Search each create and authorize their own
43
- Projects inside the selected Auth Organization.
25
+ From the website repository:
44
26
 
45
27
  ```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
28
+ siteos project list --json
29
+ siteos project create --name "Storefront" --slug storefront --url https://example.com --json
30
+ siteos project use storefront --json
31
+ siteos project status --json
32
+ siteos project connect forms --json
33
+ siteos project connect search --json
34
+ siteos project environment create --name Staging --slug staging --url https://staging.example.com --json
35
+ siteos project environment use staging --json
57
36
  ```
58
37
 
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`.
62
-
63
- Tracked repository files:
38
+ Creating a common Project records its catalog and a Production Environment. It does not create
39
+ service resources. Each explicit `connect` creates the requested resource and, where supported,
40
+ the selected common environment atomically. Cookie and Trace setup remains unpublished; Pulse monitoring remains
41
+ disabled until configured. Use `--resource '<service-resource-id>'` to adopt an existing resource.
42
+ No name, slug or URL matching is used for adoption.
64
43
 
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 |
44
+ Existing resource environments also require explicit adoption:
70
45
 
71
- Private CLI files:
46
+ ```sh
47
+ siteos project environment resources forms --json
48
+ siteos project environment connect forms --environment production --resource '<forms-environment-id>' --json
49
+ ```
72
50
 
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 |
51
+ Omit `--resource` to create a new local environment. `siteos project environment list` reports the
52
+ common catalog and connections. Forms/Search/Trace operational `--environment` flags accept common
53
+ slugs and resolve explicit native bindings; without the flag, commands use the selected environment.
54
+ Pulse/Cookie use separate bound resources per environment. Missing bindings fail without a fallback.
55
+ Manage names and website URLs with `project update` and `project environment update <slug>`.
56
+ Cookie/Trace published addresses remain unchanged until explicit republication.
77
57
 
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.
58
+ `project use` writes one private binding keyed by real repository path and application origin in
59
+ `~/.siteos/project-bindings.json`. It does not write a tracked global Project file. All service
60
+ management commands use this selection and their own runtime authority. An Organization mismatch
61
+ requires selecting the Project in the active Organization again.
80
62
 
81
- ## Pulse
63
+ ## Service workflows
82
64
 
83
- Initialize a Playwright monitoring project, validate it locally, and deploy an immutable bundle:
65
+ ### Pulse
84
66
 
85
67
  ```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
68
+ siteos project connect pulse --json
69
+ siteos pulse project list --json
70
+ siteos pulse init
89
71
  siteos pulse validate --json
90
72
  siteos pulse test
91
73
  siteos pulse deploy --dry-run --json
92
- siteos pulse deploy --json
93
74
  ```
94
75
 
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
76
+ Initialization uses the common Project identity and selected environment URL. Deployments resolve
77
+ the bound Pulse resource and current URL; local tests use this URL unless explicitly overridden.
78
+ `siteos.config.json` remains the tracked Playwright check configuration. Deployment and enabling
79
+ monitoring are explicit operations. `deploy --dry-run` builds locally without uploading.
101
80
 
102
- After selecting a Forms Project, manage its Environments, definitions, and scoped credentials:
81
+ ### Forms and Search
103
82
 
104
83
  ```sh
105
- siteos forms environment create --slug production --name "Production" --json
84
+ siteos forms environment list --json
106
85
  siteos forms definition check --manifest .siteos/forms/manifest.json --json
107
86
  siteos forms definition sync --environment production --manifest .siteos/forms/manifest.json --json
108
87
  siteos forms credential issue --environment production --install --json
88
+ siteos search environment list --json
89
+ siteos search diagnostics --environment production --json
90
+ siteos search credential issue --environment production --install --json
91
+ siteos search indexing-credential issue --environment production --install --json
109
92
  ```
110
93
 
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`.
94
+ Credential installation writes only the owned assignments to a safely ignored `.env` and never
95
+ prints values. Forms submission credentials and Search query/indexing credentials remain separate
96
+ and environment-scoped. `forms submit --input '<path>'` uses only its runtime credential; it does
97
+ not acquire management authority. Definition checks remain local.
118
98
 
119
- ## Search
120
-
121
- After selecting a Search Project, manage explicit Environments and separate query/indexing
122
- credentials:
99
+ ### Cookie, Trace and Integrations
123
100
 
124
101
  ```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
102
+ siteos project connect cookie --json
103
+ siteos cookie status --json
104
+ siteos cookie installation --json
105
+ siteos cookie draft get --json
106
+ siteos project connect trace --json
107
+ siteos trace environments --json
108
+ siteos trace installation show --environment production --json
109
+ siteos trace report --environment production --json
110
+ siteos integrations status --json
111
+ siteos integrations connect --json
129
112
  ```
130
113
 
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.
114
+ Cookie/Trace draft editing and publication are separate commands with separate authorization
115
+ scopes. Save commands take versioned JSON input; inspect `--help` and the focused plugin skill.
116
+ Installation commands return the service-owned snippet and actual publication state. A Trace
117
+ snippet is unavailable until runtime publication succeeds. Integrations connections belong to the
118
+ Organization; provider authorization opens the shared browser flow, and notification destinations
119
+ are connected explicitly by each service.
134
120
 
135
- Use `SITEOS_SEARCH_PUBLIC_URL` to override the Search origin. The development default is
136
- `http://localhost:3080`.
137
-
138
- ## Local diagnostics
121
+ ## Local state and diagnostics
139
122
 
140
123
  ```sh
141
124
  siteos health-check --json
142
125
  ```
143
126
 
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.
127
+ Diagnostics report local Project selection and legacy service references without contacting APIs
128
+ or reading runtime credentials. A selected Project means local setup exists, not remote health.
129
+ Set `SITEOS_HOME` to relocate private CLI state. Never commit `auth.json` or private bindings.
147
130
 
148
- ## Migrating from the old Pulse CLI
131
+ Legacy `pulse project`, `forms project` and `search project` selections remain supported for existing
132
+ repositories. Their service-aware bindings and tracked references (`siteos.config.json`,
133
+ `.siteos/forms/project.json`, `.siteos/search/project.json`) are fallback context when no common
134
+ Project is selected. They do not create common attachments. Old global `.siteos/project.json` and
135
+ old shared API keys are not imported or interpreted.
149
136
 
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:
137
+ The retained Pulse migration can import a matching version 2 private binding from
138
+ `${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json` only when the origin, repository,
139
+ Organization and tracked Pulse slug agree. It leaves the original file untouched.
152
140
 
153
- ```text
154
- ${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json
155
- ```
141
+ ## Origins and errors
142
+
143
+ `SITEOS_AUTH_BASE_URL` selects the shared application origin for common Projects and all service
144
+ commands using that context (default `https://siteoapp.xui.se`). The legacy service flows retain
145
+ `SITEOS_PULSE_API_URL`, `SITEOS_FORMS_PUBLIC_URL` and `SITEOS_SEARCH_PUBLIC_URL` overrides. Runtime
146
+ integration uses its service's configured public URL and scoped credential.
147
+
148
+ Run `siteos <group> --help` for supported commands. Exit code 0 means success, 2 invalid usage,
149
+ and 1 an operational failure. Legacy Pulse additionally uses 3, 4 and 5 for authorization,
150
+ conflict and unavailable-service failures. JSON output is intended for agents and automation.
156
151
 
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`.
152
+ One SiteOS plugin supports Codex and Claude Code, with a general workflow and focused service
153
+ skills. Common Projects require CLI 1.1.0 and plugin 1.3.0 or newer.
177
154
 
178
155
  ## Development and publication checks
179
156