# Notes for AI coding agents

cloudpin guards commands that touch real cloud accounts. Read [CONTRIBUTING.md](CONTRIBUTING.md) first; its
ground rules are firm. In short:

- When cloudpin can't tell which account a command would use, it blocks. Never change that to allow.
- Never print, log or cache a credential; name environment variables, never their values.
- Never spawn a process through a shell; use `realExec` in `src/exec.ts`.
- Check every CLI behaviour against its documentation or `--help` before coding it, and cite the source.
- Write the test first, with a fake `Exec`. No test may run a real CLI.
- When trying a provider against a real account, run read-only commands only.

## Commands

| Task | Command |
|---|---|
| Install from the lockfile | `npm ci` |
| Type-check | `npm run typecheck` |
| Tests | `npm test` |
| Build | `npm run build` |

Run the type-check and the tests as separate commands and read each exit code.

## Layout

| Path | What it is |
|---|---|
| `src/config.ts` | `.cloudpin.yml` parsing and lookup, environments and which one applies |
| `src/git.ts` | Branch and `cloudpin use` choice, read from the git folder without spawning git |
| `src/readonly.ts` | Which commands only read, so they skip confirmation on a protected environment |
| `src/confirm.ts`, `src/use.ts` | The terminal confirmation and `cloudpin use` |
| `src/providers/` | One file per CLI, implementing `ProviderDef` from `src/types.ts` |
| `src/guard.ts` | The allow-or-block decision |
| `src/check.ts` | `cloudpin check`: the report behind it, its text and JSON output, and `--only` |
| `src/switch.ts` | `cloudpin switch`: plan, confirm, run and re-check; `planSwitch` runs nothing |
| `src/switch-plan.ts`, `src/switch-planners.ts`, `src/switch-plan-files.ts` | The plan's shape; the planners that ask a CLI; the ones that read a config file (kubectl, AWS) |
| `src/aws-config.ts` | Profile names and accounts from the AWS config file, for `cloudpin switch` (nothing else is kept) |
| `src/status.ts`, `src/doctor.ts`, `src/doctor-windows.ts` | `cloudpin status` and `cloudpin doctor` (read-only overviews), and doctor's Windows-only checks |
| `src/explain.ts` | `cloudpin explain`: a verdict and its reasons, from guard's `Trace` |
| `src/mcp.ts`, `src/mcp-tools.ts` | `cloudpin mcp`: the JSON-RPC stdio server, and its read-only tools |
| `plugin/`, `.claude-plugin/marketplace.json` | The Claude Code plugin (hook, MCP server, skill) and its marketplace |
| `src/shellwords.ts` | Finds CLI calls inside a full shell command line |
| `src/line-state.ts` | What `shellwords.ts` keeps while it reads a line: the shell, the folder and the variables so far |
| `src/folder.ts` | The folder a line moves to (`cd`, `pushd`, `Set-Location`...): followed where it can be read, otherwise "can't tell" |
| `src/line-env.ts` | The variables a line's commands set (`set -a`, `export X+=y`, `Set-Item env:X`...): followed where they can be read, otherwise "can't tell" |
| `src/line-code-env.ts` | Variables a line sets that can make a program run code, which stop a call before its identity lookup starts, and the PATH that lookup uses |
| `src/hidden-calls.ts` | Text a line runs without cloudpin reading it (a pipe into a shell, an alias, a bare `$c`): read where it can be, otherwise "can't tell" for the CLIs the line names |
| `src/shell-tokens.ts` | The tokenizer behind it: words, operators, `$( )` and heredocs, read as bash reads them |
| `src/ps-tokens.ts` | The same tokens from a PowerShell line, read as PowerShell reads it, and the arguments Windows PowerShell 5.1 hands a CLI |
| `src/ps-words.ts` | PowerShell variables, assignments and keywords, for `shellwords.ts` |
| `src/wrappers.ts` | Commands that run the command after their own flags (env, sudo, nice, timeout, xargs, npx, pnpm...), each with its flag table from the tool's docs |
| `src/runners.ts` | Commands that run a line or a list they are given: bash -c, watch, cmd /c, powershell and pwsh, Invoke-Expression, Start-Process |
| `src/cmd-line.ts` | The commands cmd.exe runs from a `cmd /c` line |
| `src/cmd-reread.ts` | cmd.exe re-reading the arguments of a `.cmd` or `.bat` CLI on Windows: what it would act on is "can't tell" |
| `src/redirections.ts` | Shell redirections (`2>&1`, `>out`, `*>`), which shellwords drops from a call's arguments |
| `src/hooks/agents.ts` | One adapter per AI agent's hook format |
| `src/cache.ts` | The identity cache |
| `src/update.ts`, `src/install-method.ts` | The daily update notice, and how cloudpin was installed (npm, Homebrew, Scoop, pnpm, Volta, Yarn, Bun, winget, the standalone exe) so upgrade advice names the right command |
| `src/version.ts` | cloudpin's version: package.json's, or the literal the exe bundle inlines |
| `src/cli.ts` | The `cloudpin` command |
| `scripts/build-exe.mjs`, `scripts/check-exe.ps1` | The standalone `cloudpin.exe` (a Node SEA) and its zip, and the Windows checks Nightly runs on it |
| `packaging/winget/`, `docs/winget.md` | The winget manifest templates that `scripts/bump-installers.mjs --winget` fills in, and how the maintainer submits them |
| `DESIGN.md` | Product decisions and why they were made |