@siteoshq/cli 1.0.0

package/README.md

@@ -0,0 +1,190 @@
+# SiteOS CLI
+
+`@siteoshq/cli` is the single command-line client for SiteOS Auth, Pulse, Forms, and Search. The
+package exposes one binary, `siteos`, and starts its public release line at `1.0.0`.
+
+## Install
+
+Run without installing:
+
+```sh
+npx @siteoshq/cli --help
+```
+
+Or install the binary globally:
+
+```sh
+npm install --global @siteoshq/cli
+siteos --version
+```
+
+Node.js 22 or newer is required.
+
+## Authenticate
+
+The CLI authenticates once with central SiteOS Auth. Auth owns the user session and Organization
+selection; each product still owns its own Projects.
+
+```sh
+siteos auth start --email developer@example.com --json
+siteos auth complete --token <one-time-token> --json
+siteos auth organizations --json
+siteos auth select --organization <organization-id> --json
+siteos auth status --json
+```
+
+The one-time token is secret and should only be passed to `auth complete`. The durable session is
+stored privately in `~/.siteos/auth.json`. Product commands exchange it for a short-lived,
+audience-bound service grant; the durable session is never sent to Pulse, Forms, or Search.
+
+## Select product Projects
+
+There is no global SiteOS Project. Pulse, Forms, and Search each create and authorize their own
+Projects inside the selected Auth Organization.
+
+```sh
+siteos pulse project list --json
+siteos pulse project create --slug storefront --name "Storefront" --json
+siteos pulse project use storefront --json
+
+siteos forms project list --json
+siteos forms project create --slug storefront-forms --name "Storefront Forms" --json
+siteos forms project use storefront-forms --json
+
+siteos search project list --json
+siteos search project create --slug storefront-search --name "Storefront Search" --json
+siteos search project use storefront-search --json
+```
+
+Creating or selecting a Project in one service never creates, selects, links, or mutates a Project
+in another service. `project use` writes a secret-free product reference into the repository and a
+private immutable-ID binding into `~/.siteos/project-bindings.json`.
+
+Tracked repository files:
+
+| Service | File | Purpose |
+| --- | --- | --- |
+| Pulse | `siteos.config.json` | Project slug and versioned Playwright Check configuration |
+| Forms | `.siteos/forms/project.json` | Forms Project name and slug, schema version 1 |
+| Search | `.siteos/search/project.json` | Search Project name and slug, schema version 1 |
+
+Private CLI files:
+
+| File | Purpose |
+| --- | --- |
+| `~/.siteos/auth.json` | Central Auth session and selected Organization |
+| `~/.siteos/project-bindings.json` | Version 1 bindings keyed by service, API origin, and real repository path |
+
+Set `SITEOS_HOME` to place both private files in another directory. Writes are atomic and preserve
+private file permissions. Do not commit either private file.
+
+## Pulse
+
+Initialize a Playwright monitoring project, validate it locally, and deploy an immutable bundle:
+
+```sh
+siteos pulse init --project storefront --base-url https://example.com
+siteos pulse project create --slug storefront --name "Storefront" --json
+siteos pulse project use storefront --json
+siteos pulse validate --json
+siteos pulse test
+siteos pulse deploy --dry-run --json
+siteos pulse deploy --json
+```
+
+`deploy --dry-run` builds the same versioned JSON manifest and archive without requiring Auth or
+uploading data. A normal deploy requires an explicit Pulse binding for the current repository and
+uses the bound immutable Project ID. Use `SITEOS_PULSE_API_URL` to override the Pulse origin; the
+default is `https://siteos-pulse.xui.se`.
+
+## Forms
+
+After selecting a Forms Project, manage its Environments, definitions, and scoped credentials:
+
+```sh
+siteos forms environment create --slug production --name "Production" --json
+siteos forms definition check --manifest .siteos/forms/manifest.json --json
+siteos forms definition sync --environment production --manifest .siteos/forms/manifest.json --json
+siteos forms credential issue --environment production --install --json
+```
+
+`definition check` is local and does not need Auth. Management commands obtain a short-lived Forms
+service grant. `credential issue --install` writes the scoped runtime credential to the repository
+`.env` without printing its value. `forms submit` reads `SITEOS_FORMS_SUBMISSION_CREDENTIAL` and
+does not reuse management authority.
+
+Use `SITEOS_FORMS_PUBLIC_URL` to override the Forms origin. The development default is
+`http://localhost:3070`.
+
+## Search
+
+After selecting a Search Project, manage explicit Environments and separate query/indexing
+credentials:
+
+```sh
+siteos search environment create --slug production --name "Production" --json
+siteos search diagnostics --environment production --json
+siteos search credential issue --environment production --install --json
+siteos search indexing-credential issue --environment production --install --json
+```
+
+Installed query and indexing credentials remain separate. The CLI writes the appropriate
+`SITEOS_SEARCH_TOKEN`, `SITEOS_SEARCH_INDEXING_CREDENTIAL`, `SITEOS_SEARCH_ENV`, and
+`SITEOS_SEARCH_PUBLIC_URL` assignments without printing credential values.
+
+Use `SITEOS_SEARCH_PUBLIC_URL` to override the Search origin. The development default is
+`http://localhost:3080`.
+
+## Local diagnostics
+
+```sh
+siteos health-check --json
+```
+
+The health check is read-only. It reports the CLI version, private configuration home, repository
+discovery, and the status of each product-owned Project reference. It does not contact APIs, read
+runtime credentials, or recognize the removed global `.siteos/project.json` format.
+
+## Migrating from the old Pulse CLI
+
+The old Pulse executable package is not retained. On `pulse project status` or `pulse deploy`, the
+new CLI can safely import a matching version 2 binding from:
+
+```text
+${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json
+```
+
+Import occurs only when the API origin, real repository path, selected Auth Organization, and
+`siteos.config.json` Project slug all match. The CLI writes and reads back the new shared binding,
+then leaves the legacy file unchanged for manual comparison or rollback. It never imports the old
+global `.siteos/project.json` contract because that model incorrectly coupled Projects across
+products.
+
+## Environment overrides
+
+| Variable | Purpose |
+| --- | --- |
+| `SITEOS_HOME` | Private CLI state directory; defaults to `~/.siteos` |
+| `SITEOS_AUTH_BASE_URL` | Central Auth origin; defaults to `https://siteos-auth.xui.se` |
+| `SITEOS_PULSE_API_URL` | Pulse API origin |
+| `SITEOS_FORMS_PUBLIC_URL` | Forms API and public origin |
+| `SITEOS_SEARCH_PUBLIC_URL` | Search API and public origin |
+
+Run `siteos <service> --help` for the complete command surface. JSON output is intended for agents
+and automation. Exit code `0` means success, `2` means invalid usage, and Pulse reserves `3`, `4`,
+and `5` for authorization, conflict, and unavailable-service failures. Other operational failures
+return `1`.
+
+## Development and publication checks
+
+From this workspace:
+
+```sh
+pnpm --dir packages/cli format:check
+pnpm --dir packages/cli typecheck
+pnpm --dir packages/cli test
+pnpm --dir packages/cli build
+pnpm --dir packages/cli pack:check
+```
+
+`pack:check` creates the publishable tarball locally. It does not publish the package.