Skip to content

Commit 0a9d829

Browse files
SutuSebastianSutuSebastian
authored
feat(agents): interactive init, multi-IDE wiring, .gitignore, CLI fixes (#4)
* feat(agents): ensure .codemap.* in .gitignore on agents init - Require a Git repo (.git): create .gitignore with .codemap.* when missing, or append the pattern when .gitignore exists - Consolidate repo .gitignore to .codemap.* - Tests for Git vs non-Git and create vs append * chore: add patch changeset for agents init gitignore * feat(agents): interactive init, multi-IDE wiring, docs/agents.md - @clack/prompts: codemap agents init -i; symlink/copy for rule mirrors - Integrations: Cursor, Copilot, Windsurf, Continue, Cline, Amazon Q, CLAUDE/AGENTS/GEMINI - Git .gitignore .codemap.*; expand changeset; PR template + doc hub - docs/agents.md; README/architecture/packaging/roadmap/templates links * feat(agents): granular init, pointer upsert, per-file IDE symlinks - Template and IDE wiring use per-file copy/symlink; --force only removes template paths under .agents/rules|skills - CLAUDE.md/AGENTS.md/GEMINI.md/Copilot: managed codemap-pointer sections; merge, legacy migration, --force full replace - CLI: reject stray positional args on codemap agents init - Docs: hub index, single-source table, agents.md pointer section
1 parent bb817af commit 0a9d829

22 files changed

Lines changed: 1258 additions & 89 deletions

‎.changeset/agents-init-gitignore.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
"@stainless-code/codemap": patch
3+
---
4+
5+
**`codemap agents init`:** For Git repos, ensure **`.codemap.*`** is in **`.gitignore`** (create the file or append the line once). **`--force`** removes only template file paths (same relpaths under **`.agents/rules/`** and **`.agents/skills/`** as **`templates/agents`**) before merging; other files under **`.agents/`**, **`rules/`**, or **`skills/`** are kept. **`--interactive` / `-i`** — pick IDE integrations (Cursor, GitHub Copilot, Windsurf, Continue, Cline, Amazon Q, **`CLAUDE.md`**, **`AGENTS.md`**, **`GEMINI.md`**) and symlink vs copy for rule mirrors; requires a TTY. Unknown positional arguments (e.g. `interactive` without `--interactive`) are rejected. Depends on **`@clack/prompts`**.
6+
7+
**Docs:** **[`docs/agents.md`](https://github.com/stainless-code/codemap/blob/main/docs/agents.md)**; **[`docs/README.md`](https://github.com/stainless-code/codemap/blob/main/docs/README.md)** index updated. Root **[`.gitignore`](https://github.com/stainless-code/codemap/blob/main/.gitignore)** uses a single **`.codemap.*`** line.

‎.github/CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ Releases: **[@changesets/cli](https://github.com/changesets/changesets)** — ru
5252

5353
## Agent rules and skills (`.agents/`)
5454

55-
**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
55+
**Upstream** skill and rules in this repo (e.g. `codemap`) stay **generic** — placeholder SQL and triggers, no product-specific paths. Consumer projects can run **`codemap agents init`** (ships **`templates/agents`** on npm; see [docs/agents.md](../docs/agents.md)) or **copy/symlink** manually, then **edit their copy** for team aliases and queries. Customization always belongs in the **consumer** repo.
5656

5757
Rules live under **`.agents/rules/`**; skills under **`.agents/skills/<name>/SKILL.md`**. Symlink each into **`.cursor/`** (see [agents-first-convention.mdc](../.agents/rules/agents-first-convention.mdc)):
5858

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
- [ ] `bun run check` passes (format, lint, test, typecheck, build)
88
- [ ] User-facing change? **Add a [Changeset](https://github.com/changesets/changesets)** (`bun run changeset`) and commit the `.changeset/*.md` file
9-
- [ ] Docs updated if behavior or public API changed
9+
- [ ] Docs updated if behavior or public API changed — hub: [`docs/README.md`](../docs/README.md); CLI/agents: [`docs/agents.md`](../docs/agents.md)
1010

1111
## Notes
1212

‎.gitignore‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,5 @@
11
node_modules/
2-
.codemap.db
3-
.codemap.db-wal
4-
.codemap.db-shm
2+
.codemap.*
53
.DS_Store
64
dist/
75
*.tgz

‎README.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
- **Not** full-text search or grep on arbitrary strings — use those when you need raw file-body search.
66
- **Is** a fast, token-efficient way to navigate **structure**: definitions, imports, dependency direction, components, and other extracted facts.
77

8-
**Documentation:** [docs/README.md](docs/README.md) is the index for technical docs (architecture, packaging, roadmap, benchmarks). **AI / editor agents:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md); Cursor uses `.cursor/` symlinks — [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
8+
**Documentation:** [docs/README.md](docs/README.md) is the hub (topic index + single-source rules). Topics: [architecture](docs/architecture.md), [agents](docs/agents.md) (`codemap agents init`), [benchmark](docs/benchmark.md), [packaging](docs/packaging.md), [roadmap](docs/roadmap.md), [why Codemap](docs/why-codemap.md). **Bundled rules/skills:** [`.agents/rules/`](.agents/rules/), [`.agents/skills/codemap/SKILL.md`](.agents/skills/codemap/SKILL.md). **Consumers:** [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md).
99

1010
---
1111

@@ -47,9 +47,10 @@ codemap --config /path/to/codemap.config.json --full
4747
# Re-index only given paths (relative to project root)
4848
codemap --files src/a.ts src/b.tsx
4949

50-
# Scaffold .agents/ rules and skills from bundled templates (see CONTRIBUTING)
50+
# Scaffold .agents/ from bundled templates — full matrix: docs/agents.md
5151
codemap agents init
5252
codemap agents init --force
53+
codemap agents init --interactive # -i; IDE wiring + symlink vs copy
5354
```
5455

5556
**Environment / flags:** `--root` overrides **`CODEMAP_ROOT`** / **`CODEMAP_TEST_BENCH`**, then **`process.cwd()`**. Indexing a project outside this clone: [docs/benchmark.md § Indexing another project](docs/benchmark.md#indexing-another-project).

‎bun.lock‎

Lines changed: 13 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/README.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,31 @@
11
# Codemap — documentation index
22

3-
Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code/codemap)**. Quick start: [../README.md](../README.md).
3+
Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code/codemap)**.
44

5-
| File | Topic |
6-
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
7-
| [architecture.md](./architecture.md) | Schema, layering, CLI, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files) |
8-
| [benchmark.md](./benchmark.md) | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
9-
| [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets) |
10-
| [roadmap.md](./roadmap.md) | Forward-looking backlog (not a `src/` inventory) |
11-
| [why-codemap.md](./why-codemap.md) | Why index + SQL for agents (speed, tokens, accuracy) |
5+
**Start here:** [../README.md](../README.md) (install, CLI, API, dev commands). **This folder** is deeper reference — pick a row below.
126

13-
**Cross-cutting:** Runtime splits (SQLite, workers, globs, JSON config I/O) — [packaging § Node vs Bun](./packaging.md#node-vs-bun) only (link it; don’t copy the table). **User config** shape/validation — [architecture § User config](./architecture.md#user-config) only.
7+
| File | Topic |
8+
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9+
| [why-codemap.md](./why-codemap.md) | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme |
10+
| [architecture.md](./architecture.md) | Schema, layering, CLI internals, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files) |
11+
| [agents.md](./agents.md) | **`codemap agents init`** — granular **`templates/agents`** → **`.agents/`**, per-file IDE symlink/copy, **[pointer files](./agents.md#pointer-files)** (`codemap-pointer` markers), **`--interactive`**, **`.gitignore` / `.codemap.*`** |
12+
| [benchmark.md](./benchmark.md) | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
13+
| [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets) |
14+
| [roadmap.md](./roadmap.md) | Forward-looking backlog (not a `src/` inventory) |
1415

15-
**Conventions:** One topic per file; relative links; avoid stale file/symbol counts in narrative docs (use `codemap query` / `bun run dev query` after indexing; methodology tables in [benchmark.md](./benchmark.md) are fine). **This repo:** `bun run dev` → `bun src/index.ts`; `bun run build` → tsdown → `dist/`; `bun run clean` / `bun run check-updates` — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md). **Contributors:** branch + PR into **`main`** ([CI](../.github/workflows/ci.yml)), `bun run check`, JSDoc on public API.
16+
## Single source of truth (do not duplicate)
17+
18+
| Topic | Canonical doc | Elsewhere |
19+
| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
20+
| Runtime splits (SQLite, workers, globs, JSON config I/O) | [packaging § Node vs Bun](./packaging.md#node-vs-bun) — **the table lives here** | [architecture § Runtime](./architecture.md#runtime-and-database) links here; do not copy the table |
21+
| **`codemap.config.*`** shape / Zod validation | [architecture § User config](./architecture.md#user-config) | Root [README § Configuration](../README.md#configuration) points here |
22+
| **`codemap agents init`**: **`--force`** on **`.agents/`** (template file paths only), IDE matrix, per-file symlink/copy, **`templates/agents`** | [agents.md](./agents.md) | Link here; do not paste the integration table into README or packaging |
23+
| **`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot** — managed **`codemap-pointer`** sections, merge vs **`--force`** | [agents.md § Pointer files](./agents.md#pointer-files) | Link here; do not duplicate the situation table |
24+
| End-user CLI (index, query, agents, flags, env) | [../README.md § CLI](../README.md#cli) | [architecture § CLI usage](./architecture.md#cli-usage) summarizes and links back |
25+
26+
## Conventions
27+
28+
- **One topic per file**; prefer relative links between these docs.
29+
- **Avoid stale file/symbol counts** in narrative text — use `codemap query` / `bun run dev query` after indexing; methodology tables in [benchmark.md](./benchmark.md) are fine.
30+
- **This repo:** `bun run dev` is **`bun src/index.ts`**; `bun run build` → tsdown → `dist/`; `bun run clean` / `bun run check-updates` — [.github/CONTRIBUTING.md](../.github/CONTRIBUTING.md).
31+
- **Contributors:** branch + PR into **`main`** ([CI](../.github/workflows/ci.yml)), `bun run check`, JSDoc on public API.

0 commit comments

Comments
 (0)