AGENTS.md · larksuite/cli

Sections

1. Purpose
2. Implementation Discipline
3. Build
4. Choose the Correct Surface
5. Source Layout
6. Hard Contracts
7. Structured Errors
8. Affordance and Skills
9. Tests
10. Validation
11. Maintaining This File
12. Commit and PR

First lines (shown under the repo's MIT license)

# AGENTS.md

## Purpose

`lark-cli` is the official Lark/Feishu CLI for humans and AI agents. Optimize
for predictable machine-readable behavior without making the human CLI worse.

Keep each PR focused on one goal: CLI UX, reliability, simpler explicit code,
or a useful gate. Done means the correct implementation surface, preserved
contracts unless a break was requested, and reported checks.

Public behavior, tests, lint, and CI define current contracts. Existing code is
evidence, but a legacy exception is not precedent; `Proposal` documents are
direction only. Do not mix unrelated cleanup, hand-edit generated files, weaken
gates, or broaden allowlists to make CI pass.

## Implementation Discipline

Use this sequence for product behavior or enforcement changes:

1. Establish the current contract and owner before choosing a solution. Trace the
   flow from the command or shortcut through runtime and internal owners to wire
   output; inspect affected callers and tests, then choose the surface below.
2. Apply YAGNI to scope. Implement the behavior required now; do not add
   speculative modes, configuration, compatibility paths, extension points, or
   scaffolding.
3. Reuse the project's existing machinery before creating a parallel path.
   Prefer the owning generic, runtime, or internal surface, then the Go standard
   library or an existing dependency, while preserving the contracts below.
4. Fix the root cause at the narrowest cohesive boundary shared by affected
   callers. Keep command and domain policy at the caller unless there is a real
   cross-command invariant for an internal owner to enforce.
5. Ship the smallest complete change: implementation, a revert-failing regression
   test for behavior or enforcement, and required contract or guidance updates.

Optimize for minimum owned complexity, not minimum diff or line count. A correct
root-cause fix may touch the owner, callers, tests, and docs; a one-line workaround
at the wrong layer is not simpler. Prefer deletion and boring explicit code, and
avoid one-use abstractions or new dependencies for straightforward behavior.

YAGNI never overrides explicit requirements or output, error, path, security,
compatibility, and data-safety contracts. If a deliberately limited solution has
a real ceiling, document the ceiling and the concrete condition for expanding it
at the decision point.

## Build

Run `make build` for the canonical local build; it writes `./lark-cli` with
version metadata and the committed Catalog Snapshot embedded from
`internal/registry/catalog/manifest.json` plus
`internal/registry/catalog/services/*.json`. Build and test targets consume this
tracked snapshot without a metadata fetch or Python prerequisite.
`make live-skills-test` additionally requires working `npx` and network access.

## Choose the Correct Surface

| Need | Implement in | Rule |
|------|--------------|------|
| Agent/human-friendly workflow, composition, or smart defaults | `shortcuts/<domain>/` via `common.Shortcut` | Must add UX or workflow value beyond exposing one endpoint. |
| One-to-one supported OpenAPI method | Committed Catalog Snapshot under `internal/registry/catalog/manifest.json` plus `services/*.json`, and generic `cmd/service/` machinery | Verify it with `schema`. Update the manifest and matching service snapshot together; do not add a shortcut merely to expose a missing catalog method. |
| Arbitrary OpenAPI endpoint | Generic `cmd/api/` machinery | Keep it endpoint-agnostic. |
| Auth, config, profile, update, or CLI lifecycle | `cmd/<area>/` plus the owning shared/internal package | Keep new Cobra code as wiring when a lower owner exists. |
| EventKey, payload shape, or domain projection | `events/<domain>/` | Shared event mechanics stay in `internal/event/`; CLI assembly stays in `cmd/event/`. |
| Command-independent mechanism or cross-command invariant | Owning `internal/<area>/` package | Keep UX/domain policy at the caller; use a cohesive owner, not a generic utils package. Test the owner and affected caller contracts. |
| Public plugin or host integration | `extension/` | Exported symbols are compatibility commitments; orchestration stays internal. |
| Per-command decision guidance: when, avoid, prerequisites, tips, or examples | `affordance/<domain>.md` | Enrich `--help` and `schema` without restating command descriptions, flags, or field schemas. |
| Domain routing, concepts, safety, or cross-command agent workflow | `skills/<name>/SKILL.md` and `references/` | Keep always-needed decisions in `SKILL.md`, conditional HOW in references, and link commands from affordance. |

Do not duplicate one command surface inside another. Register new shortcuts in
the domain's `Shortcuts()`; declare risk, identities/scopes, flags, and dry-run.

## Source Layout

| Path | What it does |
|------|-------------|
| `cmd/root.go` | Entry point, command registration, strict mode pruning |
| `cmd/profile/` | Multi-profile management (add/list/use/rename/remove) |
| `cmd/config/` | Config init, show, strict-mode |
| `cmd/service/` | Auto-registers API commands from `internal/registry/catalog/manifest.json` and `internal/registry/catalog/services/*.json` |
| `shortcuts/common/runner.go` | Shortcut execution pipeline, Flag.Input (@file/stdin) resolution |
| `shortcuts/` | Domain-specific shortcut implementations |
| `internal/cmdutil/factory.go` | Factory pattern — identity resolution, credential, config |
| `internal/cmdutil/factory_default.go` | Production factory wiring |
| `internal/credential/` | Credential provider chain (extension → default) |
| `extension/credential/` | Plugin-facing credential interfaces and env provider |
| `internal/client/client.go` | APIClient: DoSDKRequest, DoStream |
| `internal/core/config.go` | Multi-profile config loading/saving |
| `internal/vfs/` | Filesystem abstraction (use `vfs.*` instead of `os.*`) |
| `internal/validate/path.go` | Path safety validation |

## Hard Contracts

Read the [JSON output contract](README.md#json-output-contract) before changing
wire output. Read the [source guard guide](lint/README.md) and `.golangci.yml`
before changing or waiving enforcement.

- Command/flag semantics, help/schema metadata, output placement and shapes,
  errors, exit codes, risk/identity, and exported APIs are compatibility contracts.
  When forwarding or echoing accepted input, preserve it verbatim unless its
  contract defines normalization; never silently substitute another behavior.
- Success data goes to stdout; typed failure envelopes, progress, warnings, and
  hints go to stderr. Predicate/self-contained results and partial failures are
  documented exceptions whose complete result remains on stdout.
- Keep new or touched Cobra code as wiring. Lark/Feishu API calls in shortcuts go
  through `*common.RuntimeContext`; direct HTTP is only for non-gateway protocols
  such as presigned storage and requires a precise `//nolint:forbidigo` reason.
- Keep user/workspace FileIO invocation-scoped: use `runtime.FileIO()`,
  `runtime.ValidatePath()`, and `runtime.ResolveSavePath()` so portable commands do
  not assume a local host or process working directory.
- Shortcuts do not use `internal/vfs` for user/workspace files. A narrow
  `//nolint:depguard` waiver is allowed only for CLI-owned state or explicitly
  CLI-managed host configuration; explain that ownership boundary. Other internal
  filesystem code uses `internal/vfs` and validates paths.
- If FileIO lacks a host-local tree operation, prefer an owning `internal/` package
  or optional capability. Direct `os` calls require a stated local-only boundary,
  validated and bounded paths, and a precise `//nolint:forbidigo` reason.
- Do not hardcode resolver-owned hosts. At new API boundaries, or when changed
  behavior consumes fields from a loose map, project that shape into a typed
  struct before downstream use. Extend published interfaces through optional
  interfaces rather than breaking external implementations.
- Source guards enforce raw HTTP/os/vfs, resolver-host, and migrated-error
  constructs; other semantics rely on tests and review. Every exemption must be
  narrow, local, and explain why the safe path does not apply.

## Structured Errors

Before changing a command failure, taxonomy, or error wire field, read the
[error contract](errs/ERROR_CONTRACT.md); it owns constructor selection, wrapping,
extension fields, stability, and CI guards.

- Command-facing failures use typed `errs.*` unless the error contract defines
  an output-control exception. Never return a final plain `fmt.Errorf` /
  `errors.New` or ad hoc envelope; pass typed errors through and preserve causes.
- Lark API failures use a domain typed wrapper, `runtime.CallAPITyped`, or
  `runtime.DoAPIJSONTyped`; raw callers use `runtime.ClassifyAPIResponse` or
  `errclass.BuildAPIError`.
- `param` names only failing user input; recovery belongs in `hint`. Populate
  `missing_scopes`, `log_id`, and similar fields only from known runtime evidence.
- Error tests assert typed metadata and cause preservation, not message text alone.

## Affordance and Skills

Before editing command guidance, read the [affordance guide](affordance/README.md).
For plugin distributions, read [Ship skills and command guidance](extension/platform/README.md#ship-skills-and-command-guidance).

- Go metadata/schema owns WHAT; affordance owns command-level WHEN; `SKILL.md`
  owns domain routing, concepts, safety, and cross-command workflows; `references/`
  owns detailed or conditional HOW.
- Do not duplicate canonical descriptions, schemas, or generic error taxonomy.
  Keep workflow-specific recovery in a skill when it changes agent behavior;
  affordance examples remain runnable, current, and safe.
- Skill frontmatter `description` is a concise WHAT/WHEN/NOT routing trigger. Keep
  always-needed decisions in `SKILL.md`; move conditional detail to `references/`.
- Skill names and reference paths are public pointers. Every path reachable from
  shipped docs must ship. Before referencing a new content directory, update
  `content_embed.go` and add an embedded-FS reachability test; `assets/` and
  `scripts/` stay source-only unless the distribution contract changes.

## Tests