Two files, one repository
HubSpot/hubspot-local-dev-lib ships 3 formats across 3 indexed files. The question worth asking is whether the second one says anything the first does not.
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 15 | 1 | 0% |
| Commands | 0 | 11 | 0 | 0% |
| Section tags | 1 | 7 | 0 | 13% |
What each file covers
Sections
0 shared · 15 only in A · 1 only in B- − HubSpot Local Dev Lib Agent Instructions
- − Stack
- − This is a Library, Not a CLI
- − Start Here
- − Code Organization
- − Error Handling
- − Code Style
- − Tests
- − Validation
- − Testing Changes Against the CLI
- − Option 1: Local linking (for active development)
- − Option 2: Experimental NPM release (for CI testing or sharing)
- − Git And PR Workflow
- − Shared Skills
- − Agent-Specific Config
- + Claude Code Instructions
Commands
0 shared · 11 only in A · 0 only in B- − yarn build
- − yarn lint
- − yarn prettier:write
- − yarn test <path>
- − yarn circular-deps
- − yarn local-dev
- − yarn link
- − yarn local-link
- − yarn unlink
- − yarn install --force
- − yarn release -v=prerelease -t=experimental
Section tags
1 shared · 7 only in A · 0 only in B- − setup
- − test
- − lint-format
- − code-style
- − types
- − git-pr
- − deployment
- agent-behaviour
Line diff
HubSpot/hubspot-local-dev-lib · AGENTS.md
@@ −1 @@
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
HubSpot/hubspot-local-dev-lib · .claude/CLAUDE.md
@@ +1 @@
1# Claude Code Instructions
2
3@../AGENTS.md
4
5Use `.claude/rules/` for Claude-specific scoped rule files and `.claude/skills/` for Claude project skills. Some Claude skills may be symlinks to portable skills exposed under `.agents/skills/`.
6
@@ −1 +1 @@
1−# HubSpot Local Dev Lib Agent Instructions
1+# Claude Code Instructions
22
3−This 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.
3+@../AGENTS.md
44
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−
14−Do 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−
18−This 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−
25−Key consumers:
26−
27−- `hubspot-cli` — the primary consumer
28−- VS Code extension — uses config and API functions
29−
30−Changes here affect all consumers. Be careful with breaking changes to exported function signatures.
31−
32−## Start Here
33−
34−Before 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−
83−After code changes, run the smallest useful validation set:
84−
85−1. `yarn prettier:write`
86−2. `yarn build`
87−3. `yarn test <path>` for changed or closely related tests
88−
89−Run broader checks when the change touches shared behavior or foundational modules.
90−
91−Additional 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−
99−1. In this repo: `yarn local-dev` — builds, runs `yarn link`, and watches for changes.
100−2. In CLI: `yarn local-link` — interactive prompt to symlink local packages.
101−3. Changes here are reflected in the CLI after `yarn build`.
102−
103−To stop: run `yarn unlink` here, then `yarn install --force` in CLI.
104−
105−### Option 2: Experimental NPM release (for CI testing or sharing)
106−
107−1. In this repo: `yarn release -v=prerelease -t=experimental`
108−2. 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−
120−Portable 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−
126−Claude-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.
5+Use `.claude/rules/` for Claude-specific scoped rule files and `.claude/skills/` for Claude project skills. Some Claude skills may be symlinks to portable skills exposed under `.agents/skills/`.
1316
