@sitecoreai-labs/sitecoreai-cli 0.0.4

package/AGENTS.md

@@ -0,0 +1,67 @@
+# Agent Guidelines
+
+This document is for agents assisting with the **SitecoreAI Deploy & Sync CLI**. It focuses on how to
+use the CLI, not how to develop the repository.
+
+## Agent assets
+
+- Machine-readable config: [`agent.json`](./agent.json)
+- Skills index: [`skills/README.md`](./skills/README.md)
+- Skill library: [`skills/`](./skills/)
+
+## CLI Basics
+
+- CLI name: `scai` (alias: `sitecoreai-cli`)
+- Config file: `sitecoreai.cli.json` in the project root (use `--config` to point elsewhere)
+- Default environment: `defaultEnvProfile` in `sitecoreai.cli.json`
+- Command groups: `serialization` (alias: `ser`) and `deploy`
+
+## Common Commands
+
+Configure an environment:
+
+```
+npm run dev -- init --environment-name demo --cm https://<cm-host>
+```
+
+Use `--skip-deploy-lookup` to avoid Deploy API lookups and prompt for the CM host.
+
+Check configured environments:
+
+```
+npm run dev -- status
+```
+
+Run serialization:
+
+```
+npm run dev -- serialization pull --environment-name demo
+npm run dev -- serialization push --environment-name demo
+```
+
+Deploy API examples:
+
+```
+npm run dev -- deploy organizations get
+npm run dev -- deploy projects list
+npm run dev -- deploy environments list --project <id-or-name> --type cm
+```
+
+Interactive shell (TTY only):
+
+```
+npm run dev -- shell
+```
+
+## Authentication Notes
+
+- Deploy API uses `deployToken` (stored per environment).
+- Use `login` to refresh the SitecoreAI access token for an environment.
+- Serialization uses the Management API and requires `authority` plus OAuth credentials.
+- Set `authority`, `clientId`, `clientSecret`, and `useClientCredentials` in `sitecoreai.cli.json` when needed.
+
+## Safety
+
+- Writes require `allowWrite: true` in the environment config.
+- Use `--what-if` on serialization commands to preview changes.
+- In CI/non-TTY, prefer `--non-interactive` and set `SITECOREAI_AUTO_WIZARD=0`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sitecore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,357 @@
+# SitecoreAI Deploy & Sync CLI
+
+TypeScript CLI modeled after the Sitecore DotNet SDK and aligned with the serialization commands in `Sitecore.DevEx`.
+This implementation runs natively (no dependency on the official `sitecore` CLI).
+It also includes a first-class SitecoreAI Deploy API client.
+
+CLI command: `scai` (alias: `sitecoreai-cli`)
+
+Examples below use the installed CLI command `scai` (alias: `sitecoreai-cli`).
+For local development without installation, replace `scai` with `npm run dev --`.
+
+## Quick start
+
+Install dependencies (npm/pnpm/yarn/bun are all supported):
+
+```
+npm install
+pnpm install
+yarn install
+bun install
+```
+
+Configure an environment (writes to `sitecoreai.cli.json` and creates it if missing):
+
+```
+scai init
+scai init --environment-name local --project "My Project" --environment "Dev"
+```
+
+Interactive wizard setup:
+
+```
+scai init --wizard
+```
+
+Running `init` without flags defaults to the wizard. Provide flags to skip prompts.
+Use `--skip-deploy-lookup` to avoid Deploy API lookups and just enter the CM host.
+
+Auto-setup on startup:
+
+- When you run a command and no config or auth token is found, the CLI launches the init/login wizard.
+- In non-interactive/CI mode, it skips auto-setup and prints a hint instead.
+- Disable auto-setup with `SITECOREAI_AUTO_WIZARD=0`.
+
+Check configured environments:
+
+```
+scai status
+```
+
+Validate configuration:
+
+```
+scai config validate
+```
+
+Run a serialization command:
+
+```
+scai serialization pull --environment-name local
+```
+
+List environments from the Deploy API:
+
+```
+scai deploy environments list --project "My Project" --type cm
+```
+
+Upload deployment source from a directory:
+
+```
+scai deploy deployments source --id <deploymentId> --directory ./my-app
+```
+
+## Agent/CI usage
+
+For non-interactive usage, authentication flows, and CM vs Editing Host guidance, see
+[`AGENT_CI.md`](./AGENT_CI.md).
+
+Future enhancements: see [`ROADMAP.md`](./ROADMAP.md).
+
+Agent metadata and skills:
+
+- Machine-readable config: [`agent.json`](./agent.json)
+- Skills index: [`skills/README.md`](./skills/README.md)
+
+## Configuration
+
+Configuration is read from `sitecoreai.cli.json` at your project root (use `--config` to
+point at a different directory). `init` creates or updates an environment in the
+`envProfiles` section, creates the config if it does not exist, and can set the default
+environment with `--set-default`.
+
+Key behaviors:
+
+- `--environment-name` selects the environment key inside `envProfiles`.
+- Global output flags: `--json`, `--quiet`, and `--log-file <path>`.
+- `--ref` lets an environment inherit auth/settings from another environment.
+- Deploy API access uses a SitecoreAI access token cached in the OS keychain (`deployToken`).
+  This token includes SitecoreAI CM/admin scopes in addition to Deploy scopes.
+- `init` can accept `--deploy-token` directly or obtain a token via interactive login or client credentials.
+- `login` only refreshes the SitecoreAI access token for an existing environment.
+- CM access/refresh tokens are cached in the OS keychain when
+  `settings.cacheAuthenticationToken` is `true` (default: `true`).
+- For client credentials, provide secrets via environment variables
+  (`SITECOREAI_CLIENT_SECRET` or `SITECOREAI_ENV_<NAME>_CLIENT_SECRET`).
+- Environment settings can be overridden with environment variables for CI or secrets.
+  Global overrides (`SITECOREAI_CLIENT_SECRET`, etc.) apply only to the active environment,
+  while per-environment overrides (`SITECOREAI_ENV_DEMO_DEPLOY_TOKEN`) always apply.
+- CLI history is written to `~/.sitecoreai/cli-history.log` (override with `SITECOREAI_HISTORY_PATH`).
+- Use `history` to view recent CLI activity from that log.
+- Use `history --show-path` to print the log file path.
+- Module files (`*.module.json`) are validated against the serialization module schema.
+
+Telemetry:
+
+- Modeled after the Vercel Skills CLI: anonymous usage events and opt-out via env vars. [github.com/vercel-labs/skills](https://github.com/vercel-labs/skills/)
+- On first use, the CLI prompts for consent and stores it in `settings.telemetryEnabled` in `sitecoreai.cli.json`.
+- If `settings.telemetryEnabled` is unset, telemetry is disabled until consent is recorded.
+- Override with env vars: `SITECOREAI_TELEMETRY=false`, `DISABLE_TELEMETRY=1`, or `DO_NOT_TRACK=1`.
+- Uses a `ci=1` flag when running in CI.
+- Sends command names, durations, and a random nonce (no full args); sensitive flags are redacted.
+- The telemetry service derives an approximate region from CDN headers (e.g., `US-CA`) and does not store raw IPs.
+- The CLI uses a built-in production telemetry endpoint. For development, override with
+  `SITECOREAI_TELEMETRY_URL`.
+- Telemetry schema: `https://schemas.sitecoreai.dev/v1/telemetry.schema.json`.
+- Telemetry payloads are validated against the telemetry schema before sending.
+
+Telemetry status:
+
+```
+scai telemetry status
+```
+
+## Privacy
+
+Telemetry is strictly anonymous and minimal. We do not send file contents, full arguments,
+tokens, or user identifiers. The payload includes only the command name, duration, CLI
+version, schema version, a CI flag when applicable, and an approximate region derived
+from CDN headers (client-supplied region values are ignored). The telemetry service uses
+client IPs only for rate limiting and does not store raw IPs (logs keep only anonymized IP
+prefixes). You can opt out at any time via `settings.telemetryEnabled` or the environment
+variables above.
+
+## Data handling and retention
+
+- Local history is stored in `~/.sitecoreai/cli-history.log` (override with `SITECOREAI_HISTORY_PATH`)
+  and grows until you delete or rotate it.
+- Telemetry payloads are minimal and do not include full arguments or credentials. Retention
+  and aggregation are determined by the telemetry service.
+
+## Troubleshooting
+
+- **Config not found:** run `scai init` or pass `--config <path>`.
+- **Auth required:** run `scai login` or `scai init` to refresh tokens.
+- **Network/timeouts:** verify the CM host/authority, and increase
+  `settings.apiClientTimeoutInMinutes` if needed.
+- **Deploy token missing:** provide `--deploy-token` or configure
+  `SITECOREAI_DEPLOY_TOKEN`.
+
+## Release management
+
+This repo uses Changesets for versioning and release automation.
+
+Local workflow:
+
+```
+npm run changeset
+```
+
+- Select the version bump type (patch/minor/major).
+- Commit the generated `.changeset/*.md` file.
+
+CI workflow:
+
+- Push to `main` and the Changesets GitHub Action will open a release PR.
+- Merge the release PR to publish to npm (requires `NPM_TOKEN` secret).
+
+Manual release:
+
+```
+npm run version
+npm run release
+```
+
+## Serialization API usage
+
+Serialization commands use the Sitecore Management API (GraphQL) at
+`/sitecore/api/management` on the configured CM host.
+
+- **Authentication:** OAuth2 via the configured `authority`. The CLI supports client credentials
+  and interactive browser login, and caches access tokens in `sitecoreai.cli.json`.
+- **Items:** GraphQL queries to read items, metadata, and history for pull/push/diff workflows.
+- **Roles/Users:** GraphQL queries for role/user sync (pull/push).
+- **Watch:** GraphQL history polling to detect remote changes and pull deltas.
+- **Filesystem:** YAML files in the module serialization paths using deterministic YAML output.
+
+## Commands
+
+Serialization commands (alias: `ser`):
+
+- `serialization info`
+- `serialization explain`
+- `serialization pull`
+- `serialization push`
+- `serialization diff`
+- `serialization validate`
+- `serialization watch`
+- `serialization package create` (alias: `pkg`)
+- `serialization package install` (alias: `pkg`)
+
+Environment commands:
+
+- `init`
+- `login`
+- `logout`
+- `status`
+- `history`
+
+Deploy API commands:
+
+- `deploy organizations get`
+- `deploy organizations health`
+- `deploy organizations license`
+- `deploy organizations launch-demo`
+- `deploy projects list`
+- `deploy projects limitation`
+- `deploy projects validate-name`
+- `deploy projects get`
+- `deploy projects create`
+- `deploy projects update`
+- `deploy projects link-repository`
+- `deploy projects unlink-repository`
+- `deploy projects delete`
+- `deploy environments list`
+- `deploy environments limitation`
+- `deploy environments get`
+- `deploy environments create`
+- `deploy environments variables list`
+- `deploy environments variables create`
+- `deploy environments variables delete`
+- `deploy environments deployments list`
+- `deploy environments deployments create`
+- `deploy environments get-edge-token`
+- `deploy environments get-editing-secret`
+- `deploy environments regenerate-context`
+- `deploy environments promote`
+- `deploy environments restart`
+- `deploy environments link-repository`
+- `deploy environments unlink-repository`
+- `deploy environments delete`
+- `deploy logs list`
+- `deploy logs view`
+- `deploy logs data`
+- `deploy editing-host list`
+- `deploy editing-host create`
+- `deploy editing-host update`
+- `deploy editing-host delete`
+- `deploy editing-host deploy`
+- `deploy source-control list`
+- `deploy source-control state`
+- `deploy source-control access-token`
+- `deploy source-control validate`
+- `deploy source-control repository get`
+- `deploy source-control repository branches`
+- `deploy source-control repository validate`
+- `deploy source-control repository create-from-template`
+- `deploy source-control providers`
+- `deploy source-control templates`
+- `deploy source-control get`
+- `deploy source-control delete`
+- `deploy deployments list`
+- `deploy deployments get`
+- `deploy deployments status`
+- `deploy deployments deploy`
+- `deploy deployments cancel`
+- `deploy deployments source`
+- `deploy deployments watch`
+- `deploy deployments logs`
+
+Aliases:
+
+- `deploy org` → `deploy organizations`
+- `deploy proj` → `deploy projects`
+- `deploy env` → `deploy environments`
+- `deploy sc` → `deploy source-control`
+- `deploy dep` → `deploy deployments`
+- `deploy log` → `deploy logs`
+- `deploy eh` → `deploy editing-host`
+
+Deploy selection rules:
+
+- Projects: use `--id` or `--name`. Project link/unlink requires `--id`.
+- Environments: use `--id` or `--name`, optionally scoped with `--project`.
+- Environment create requires `--project`.
+- Environment create supports `--cm-only` to create a CM-only environment.
+- Project create requires `--name`.
+- Tenant types: `0` = nonprod, `1` = prod.
+- Project source control ID mapping: create uses `integrationId`, update uses `sourceControlIntegrationId`.
+- Source control integrations and deployments: use `--id`.
+- Project link-repository requires `repositoryId` and `integrationId` (others optional).
+- Environment link-repository requires `repositoryName`, `repositoryId`, `integrationId`,
+  `repositoryRelativePath`, and `repositoryBranch`.
+- Source control repository create-from-template requires `--provider` (`ado` or `github`)
+  and template fields (`templateRepository`, `templateOwner`, `repositoryName`, `owner`,
+  `integrationId`).
+- Deploy deployments source accepts `--file` (archive) or `--directory` (auto-zip).
+
+Aliases:
+
+- `serialization` -> `ser`
+- `serialization package` -> `pkg`
+
+## Development
+
+Run in dev mode:
+
+```
+npm run dev -- serialization info --help
+```
+
+Lint and format:
+
+```
+npm run lint
+npm run format
+```
+
+Build:
+
+```
+npm run build
+```
+
+Run tests:
+
+```
+npm run test
+```
+
+Integration tests (requires env vars):
+
+```
+npm run test:integration
+```
+
+Watch tests:
+
+```
+npm run test:watch
+```
+
+Run built CLI:
+
+```
+node dist/cli.js serialization info --help
+```

package/bin/sitecoreai-cli

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require("../dist/cli.js");

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}