codebase-conventions

Files (1)

• SKILL.md

SKILL.md (first lines)

# Codebase Conventions — scai

These rules apply to every change. The CLI is published to npm and used by
end users (humans and agents) — the bar is high.

## Package manager: pnpm for agent work

Agents working in scai use `pnpm` for everything: install, dev, test,
build. Never `npm`, `yarn`, `bun`, or `npx` in an agent session.

End users install scai via any of npm/pnpm/yarn/bun (per the README and
because scai is a public CLI). That's a documentation concern, not an
agent-workflow concern.

For one-off binaries, use `pnpm exec <bin>`.

## Module structure

`src/` is 22 **domain areas** plus three cross-cutting layers. A domain
area owns one product surface — its API client, task runners, and (where
it has one) an `index.ts` SDK barrel.

```
src/
├── cli.ts             ← entrypoint; src/program.ts builds the Commander tree
├── commands/          ← Commander command definitions; thin parsers
│   ├── deploy/, serialization/, recipe/, brand/, ...  ← per-area subcommands
│   └── shared.ts      ← shared option helpers
├── config/            ← sitecoreai.cli.json + module schemas, config resolution
├── shared/            ← cross-cutting: errors, logger, spinner, HTTP/GraphQL
│                        transport, redaction
└── <domain areas>/    ← deploy, serialization, setup, recipe, brand,
                          brief, campaigns, sites, publishing, content,
                          hygiene, webhooks, workflow, agents, policy, mcp,
                          scripting, sync, auth, authoring, doctor,
                          telemetry
```

A typical domain area (e.g. `serialization/`) holds `tasks/` (task
runners), an API-client subdir, and an `index.ts` barrel exporting the
SDK surface for that subpath.

**Direction of imports:**

- `commands/` may import any domain area, `config/`, and `shared/`.
- A domain area may import **peer domain areas**, `config/`, and
  `shared/` — never `commands/`.
- `config/` may import `shared/` only.
- **`src/shared/` is a leaf** — it imports no domain area and no
  `commands/` (type-only `@/config` imports are allowed). `allow-write`
  and `env` were moved into `policy/`; `content/` must not import
  `publishing/`. Those two boundaries killed the former `shared↔policy`
  and `content↔publishing` cycles.
- `tests/unit/architecture/module-boundaries.test.ts` enforces those
  two invariants. It is not a full cycle detector — peer domain areas
  may still cross-import; the hard rule is that `shared/` stays a leaf.

When adding a new command group (like `recipe`), follow the existing
pattern: a parser dir under `commands/<group>/`, and a peer domain area
`src/<group>/` if it owns runtime logic.

## Error handling: createCliError

Throw structured CLI errors so the top-level handler can render them with
hints and exit codes. Pattern (from `src/shared/errors.ts`):

```typescript
import { createCliError } from "@/shared/errors";

throw createCliError("Invalid module configuration at ${moduleFile}.", "CONFIG_INVALID", {
  hint: "Fix the module JSON to match the serialization module schema.",
  details,
});
```

- First arg: human-readable message
- Second arg: stable `CODE` for telemetry/log filtering
- Options: `hint` (always include — tells the user the next step), `details` (structured)

Don't `throw new Error("...")` from command paths. Reserve raw `Error` for
truly internal/programmer errors.

## Logging: consola via toLogger(options)

Commands receive `options` from commander; convert to a logger via
`toLogger(options)` in `serialization/tasks/shared.ts`. The logger honors
`--json`, `--quiet`, `--log-file`.

- `--json` → emit JSON lines, no decoration. **No banners, no colors, no
  spinner.** Spinner code paths must check `logger.isJson()` before
  starting an `ora` instance.
- `--quiet` → suppress info; warnings + errors still emit.
- `--log-file` → also write to file at the given path.

Don't `console.log`. Don't write color codes outside consola/ora.

## Credentials: keychain-only

- Tokens are stored via `keytar` in `src/setup/deploy-token.ts`
  (and similar for OAuth tokens) under the `sitecoreai-cli` service.
- Never write a token to `sitecoreai.cli.json` directly. The `accessToken`
  / `deployToken` fields in the example config are placeholders showing
  where keychain values are loaded into.
- Env-var overrides (`SITECOREAI_DEPLOY_TOKEN`, `SITECOREAI_ENV_<NAME>_DEPLOY_TOKEN`)
  are read at startup and held in memory only — never persisted.
- Telemetry: the schema explicitly forbids token-shaped payloads; don't
  add fields that could leak.

## Agent / CI contract

Every command must work non-interactively:

- Honor `--non-interactive` (don't prompt; fail fast on missing required input)
- Honor `SITECOREAI_AUTO_WIZARD=0` (skip auto-init/auto-login wizards)
- Default `allowWrite: false` on environments — destructive operations
  require explicit `--allow-write` or `allowWrite: true` in config
- Honor `--what-if` on push-style operations (preview without applying)
- `--json` output is structured + machine-parseable; never include
  decorative text in JSON-mode output. **Wrap your output in

From Sitecore-Studio-Labs/sitecoreai-cli, MIT.

More from Sitecore-Studio-Labs/sitecoreai-cli