AGENTS.md

# AGENTS.md

## Command pattern - always use RegisterCLICommand

All new commands must use the struct-based pattern.
**Do not copy the old flat `var cmd = &cobra.Command{...}` commands** - they
exist in `cmd/storage/`, `cmd/dns/`, `cmd/dbaas/` and are legacy.

Read this file before writing any new command:
`cmd/aiservices/deployment/deployment_create.go`

For subcommand placement in an existing group, also read `## Folder layout` below.

Skeleton:

```go
type myResourceCreateCmd struct {
    exocmd.CliCommandSettings `cli-cmd:"-"`

    _ bool `cli-cmd:"create"`

    Name string `cli-arg:"#"  cli-usage:"NAME"`        // required positional
    Tag  string `cli-arg:"?"  cli-usage:"TAG"`          // optional positional
    Zone string `cli-short:"z" cli-usage:"zone"`        // becomes --zone / -z flag
}

func (c *myResourceCreateCmd) CmdAliases() []string { return exocmd.GCreateAlias }
func (c *myResourceCreateCmd) CmdShort() string     { return "Create a resource" }
func (c *myResourceCreateCmd) CmdLong() string      { return "..." }

func (c *myResourceCreateCmd) CmdPreRun(cmd *cobra.Command, args []string) error {
    exocmd.CmdSetZoneFlagFromDefault(cmd)
    return exocmd.CliCommandDefaultPreRun(c, cmd, args)
}

func (c *myResourceCreateCmd) CmdRun(_ *cobra.Command, _ []string) error {
    // c.Name, c.Zone are already populated here
    return nil
}

func init() {
    cobra.CheckErr(exocmd.RegisterCLICommand(parentCmd, &myResourceCreateCmd{
        CliCommandSettings: exocmd.DefaultCLICmdSettings(),
    }))
}
```

Supported struct tags:

| Tag | Purpose |
|---|---|
| `cli-cmd:"-"` | Exclude field from CLI processing |
| `cli-cmd:"name"` | Sets the cobra command name (use on a `_ bool` field) |
| `cli-arg:"#"` | Required positional argument |
| `cli-arg:"?"` | Optional positional argument; `[]string` becomes variadic |
| `cli-flag:"flag-name"` | Override the auto-derived kebab-case flag name |
| `cli-short:"z"` | Single-character shorthand |
| `cli-usage:"text"` | Flag usage string; also used as positional arg label in help |
| `cli-hidden:""` | Mark flag hidden |
| `cli-deprecated:"msg"` | Mark flag deprecated |

Supported field types: `string`, `int64`, `bool`, `[]string`, `map[string]string`.
Any other type panics at startup.

Global alias vars to use for `CmdAliases()`:
`exocmd.GListAlias`, `GShowAlias`, `GCreateAlias`, `GDeleteAlias`, `GRemoveAlias`.

## Folder layout

**Anti-pattern: don't extend flat layouts.** `cmd/storage/`, `cmd/dns/`,
`cmd/dbaas/` and similar are legacy flat groups. Adding or refactoring a
subcommand under one of them MUST promote the cluster to its own subpackage
following the layout already used elsewhere in the repo —
`cmd/aiservices/deployment/` is the canonical example (`deployment.go`
declares `var Cmd`; siblings live as `deployment_<verb>.go` in the same dir).
Concrete case in flight: `cmd/storage/storage_bucket_lifecycle*.go` ->
`cmd/storage/bucket/lifecycle/{lifecycle,lifecycle_show,lifecycle_set,lifecycle_delete}.go`.

New command group:

```
cmd/<domain>/<subdomain>/
  <subdomain>.go          <- var Cmd; init -> parent.AddCommand(Cmd)
  <subdomain>_list.go
  <subdomain>_show.go
  <subdomain>_create.go
  <subdomain>_delete.go
  <subdomain>_list_test.go
  ...
```

Then add a blank import to `cmd/subcommands/init.go` - nothing else needs wiring.

## Tests

Tests live in the same package (white-box). Construct the struct directly and
call `CmdRun(nil, nil)`. Use `pkg/testutils` for HTTP test servers and client
setup. See `cmd/aiservices/deployment/deployment_create_test.go`.

### E2E tests for new features

Every new feature must ship with at least one `.txtar` scenario under
`tests/e2e/scenarios/with-api/<domain>/`. A single scenario covering only
the happy path is not enough - cover the primary CLI usages:

- The main command (create/list/show/delete or equivalent)
- At least one flag or option variant that changes the output or behaviour
- Any path-syntax shorthand the user would reach for (e.g. `sos://bucket/`)

Keep scenarios focused: one file per logical feature or sub-command cluster.
Name files `<feature>_<scenario>.txtar` (e.g. `bucket_lifecycle_crud.txtar`).

Register the domain under `TestScriptsAPI<Domain>` in
`tests/e2e/testscript_api_test.go` and `TestAPI<Domain>Local` in
`tests/e2e/local_test.go`.

Run locally with:

```
cd tests/e2e
go test -v -tags=local_integration -timeout 30m -run TestAPI<Domain>Local -account=<name>
```

## File header on every AI-touched file

Add a comment at the top of every file you create or modify. Use the
appropriate syntax for the language, and pick the right verb. Substitute
`<model>` with your own identifier (e.g. `claude-sonnet-4.6`, `gpt-5`, etc.):

```go
// AI-generated by <model> - not reviewed yet   // new file
// AI-modified by <model> - not reviewed yet    // existing file
```
```yaml
# AI-generated by <model> - not reviewed yet
# AI-modified by <model> - not reviewed yet
```
```html
<!-- AI-generated by <model> - not reviewed yet -->
<!-- AI-modified by <model> - not reviewed yet -->
```

The reviewer removes the line once they have read and approved the file.
It must be the very first line (before `package`, shebangs, etc.) except
where the language requires otherwise (e.g. after `<?xml` declarations).

## Marking AI-assisted commits and PRs

Add these trailers to every commit that contains agent-generated code:

    AI-assisted: true
    Co-authored-by: copilot-swe-agent <203248971+copilot-swe-agent@users.noreply.github.com>

This makes AI-touched commits greppable across history:

    git log --grep="AI-assisted"

and shows Copilot as a co-author in GitHub's commit view.

For PRs, append this footer to the description (after a `---`), listing only categories that apply:

```
> [!NOTE]
> AI assistance: PR description, test scaffolding, boilerplate code.
```

Omit categories that don't apply. Omit the footer entirely if AI contributed nothing.

## Before opening a PR or issue

Use the existing templates - don't replace them with free-form text:
- PRs: `.github/pull_request_template.md`
- Issues: `.github/ISSUE_TEMPLATE/` (bug-report, feature_request, other_request)

Keep every heading, fill each section in.

## Before opening a PR

```
make build
make test-verbose
golangci-lint run --timeout 4m
```

Update `CHANGELOG.md` under `## Unreleased` with the PR number.