AGENTS.md

1# HubSpot Local Dev Lib Agent Instructions
2 
3This repository is `@hubspot/local-dev-lib` — a shared TypeScript library that provides core functionality for HubSpot local development tooling. It is consumed by the HubSpot CLI and VS Code extension.
4 
5## Stack
6 
7- Language: TypeScript in strict mode, ESM modules
8- Testing: Vitest (not Jest, not jasmine)
9- Package manager: Yarn
10- Build: `yarn build`
11- Lint: `yarn lint`
12- Format: `yarn prettier:write`
13 
14Do not use Java, Maven, CHIRP, Bend, Trellis, or HubSpot backend/frontend platform workflows for normal work in this repo.
15 
16## This is a Library, Not a CLI
17 
18This repo is consumed via `@hubspot/local-dev-lib` by the CLI and other tools. Key implications:
19 
20- No `process.exit()` — throw errors and let consumers handle them.
21- No direct user prompts — return data and let the CLI prompt.
22- No default exports — named exports only (enforced by ESLint).
23- All exports must be declared in `package.json` `exports` field.
24 
25Key consumers:
26 
27- `hubspot-cli` — the primary consumer
28- VS Code extension — uses config and API functions
29 
30Changes here affect all consumers. Be careful with breaking changes to exported function signatures.
31 
32## Start Here
33 
34Before creating or modifying code, study how the repo already does the same kind of work.
35 
36- Search for similar files and read at least two comparable examples before adding a new file.
37- Check `lib/`, `config/`, `api/`, or `utils/` before adding a new function.
38- Check `types/` before adding a new shared type.
39- Follow the discriminated union pattern used for account types.
40- Check `lang/en.json` before adding user-facing strings. Use the `i18n()` function with `{{ variable }}` interpolation.
41- If existing implementations disagree in a meaningful way, stop and surface the discrepancy instead of silently choosing one pattern.
42 
43## Code Organization
44 
45- `api/` — HTTP calls to HubSpot services. Return `HubSpotPromise<T>`.
46- `config/` — Config file read/write (YAML). Core account resolution logic.
47- `constants/` — Shared constants.
48- `errors/` — Custom error classes (`HubSpotHttpError`, `HubSpotConfigError`, `FileSystemError`).
49- `http/` — Axios wrapper with HubSpot auth.
50- `lang/` — i18n strings (`en.json`).
51- `lib/` — Exported functions and modules. Anything exported from the repo should live here (excluding special cases like `config/`).
52- `utils/` — Internal helper functions that are NOT exported.
53- `models/` — Business logic classes.
54- `types/` — TypeScript type definitions.
55 
56## Error Handling
57 
58- Throw custom error classes from `errors/`, never return error objects.
59- Use `HubSpotHttpError` for API failures, `HubSpotConfigError` for config issues, `FileSystemError` for FS operations.
60- Never call `process.exit()` — that is the consumer's responsibility.
61 
62## Code Style
63 
64- Prefer functions over classes.
65- Use early returns to keep control flow readable.
66- Use descriptive variable names.
67- Do not introduce `any` unless there is a narrow, well-justified reason.
68- Do not add comments unless the code would otherwise be hard to follow.
69- Follow the repo formatter for single quotes, 2-space indentation, trailing commas, and 80-character line length.
70- Do not use the word `comprehensive` in repo copy or generated docs.
71 
72## Tests
73 
74- Tests live in co-located `__tests__/` directories.
75- Test files are named `<source-file>.test.ts`.
76- Use Vitest globals and existing mocks.
77- No try/catch blocks in tests — use `expect().toThrow()`.
78- All cleanup in `afterEach()` using `vi.restoreAllMocks()`.
79- Never skip tests — fix or remove them.
80 
81## Validation
82 
83After code changes, run the smallest useful validation set:
84 
851. `yarn prettier:write`
862. `yarn build`
873. `yarn test <path>` for changed or closely related tests
88 
89Run broader checks when the change touches shared behavior or foundational modules.
90 
91Additional checks:
92 
93- Circular deps: `yarn circular-deps`
94 
95## Testing Changes Against the CLI
96 
97### Option 1: Local linking (for active development)
98 
991. In this repo: `yarn local-dev` — builds, runs `yarn link`, and watches for changes.
1002. In CLI: `yarn local-link` — interactive prompt to symlink local packages.
1013. Changes here are reflected in the CLI after `yarn build`.
102 
103To stop: run `yarn unlink` here, then `yarn install --force` in CLI.
104 
105### Option 2: Experimental NPM release (for CI testing or sharing)
106 
1071. In this repo: `yarn release -v=prerelease -t=experimental`
1082. In CLI: update `package.json` to the experimental version and run `yarn install --force`.
109 
110## Git And PR Workflow
111 
112- Use Conventional Commits for all commit messages and PR titles. Format: `<type>: <short description>`. Types: `feat`, `fix`, `chore`, `refactor`, `test`, `docs`, `perf`, `ci`, `build`.
113- Do not amend commits on an existing PR unless the user explicitly asks for an amend, rebase, squash, or history rewrite.
114- When addressing review feedback on a PR, create a new follow-up commit by default.
115- For stacked PRs, prefer merging parent branch updates into the child branch over rebasing, because PRs are squash-merged into `main`.
116- Ask before committing, pushing, force-pushing, creating PRs, posting comments, merging, closing, or otherwise mutating GitHub state.
117 
118## Shared Skills
119 
120Portable project skills are exposed under `.agents/skills/`. When a task matches one of these workflows, read that skill before proceeding:
121 
122- `code-check`: review branch changes against repo conventions.
123- `push-changes`: run pre-commit checks, commit, and push to remote.
124- `create-pull-request`: commit, push, and create a draft PR.
125 
126Claude-specific skills and orchestration workflows may still live only under `.claude/skills/`.
127 
128## Agent-Specific Config
129 
130`AGENTS.md` is the canonical behavioral entry point. Agent-specific permission or runtime configuration should stay in that agent's own local config, such as `.claude/settings.local.json` for Claude or `.codex/rules/*.rules` for Codex command execution policy. Do not duplicate behavioral rules into permission files.
131