99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# pi-project-map
|
|
|
|
A Pi extension and command-line tool that generates paired project-navigation artifacts: `.pi-map.index.md` files for routing and `.pi-map.md` files for directory orientation. The artifacts help agents navigate a codebase; source remains the authority.
|
|
|
|
## Status and limitations
|
|
|
|
- Generation and repair commands call an LLM and write map artifacts into the target project.
|
|
- `validate` without `--fix` checks artifacts without creating an LLM client; `validate --fix` can modify them and requires an LLM.
|
|
- Token budgeting and relevant-turn detection are best-effort. Retrieved maps route and orient work but do not replace source verification.
|
|
- No Node.js version requirement or deployment configuration is declared in this repository.
|
|
|
|
## Install and develop
|
|
|
|
Install the published CLI globally:
|
|
|
|
```bash
|
|
npm install -g pi-project-map
|
|
```
|
|
|
|
For local development, install dependencies and build from this repository:
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
Available development checks:
|
|
|
|
```bash
|
|
npm run test
|
|
npm run lint
|
|
npm run typecheck
|
|
npm run dev
|
|
```
|
|
|
|
`npm run dev` runs TypeScript in watch mode. The project declares no deployment command.
|
|
|
|
## Use the CLI
|
|
|
|
Run the installed `project-map` command from the project to map. Use `--help` or `--version` for CLI metadata.
|
|
|
|
```bash
|
|
project-map init [path]
|
|
project-map patch <file>
|
|
project-map validate [--fix] [path]
|
|
project-map reinit [path]
|
|
project-map context <query>
|
|
```
|
|
|
|
Typical workflow:
|
|
|
|
1. Run `project-map init` to generate maps for a project.
|
|
2. After editing a file, run `project-map patch <file>`.
|
|
3. Run `project-map validate` before relying on maps; use `--fix` only when you intend to repair artifacts.
|
|
4. Use `project-map context "<query>"` to retrieve a ranked context bundle.
|
|
|
|
`init`, `patch`, `reinit`, and `validate --fix` mutate `.pi-map.md` and/or `.pi-map.index.md` artifacts. `context` retrieves from existing artifacts.
|
|
|
|
### Pi extension
|
|
|
|
The repository exposes `pi-extension.ts` as a Pi extension. Inside Pi it uses Pi's configured model and registers equivalent `project_map_*` tools. The extension can also inject project-map guidance according to `promptInjectionMode`.
|
|
|
|
## LLM configuration
|
|
|
|
Standalone CLI use needs credentials for the selected provider. Do not commit keys.
|
|
|
|
- `openai` (the default) reads `OPENAI_API_KEY`; its model can be set with `OPENAI_MODEL` or `LLM_MODEL`.
|
|
- `kimi` reads `KIMI_API_KEY` (or `KIMI_COM_API_KEY`); its model can be set with `KIMI_MODEL` or `LLM_MODEL`.
|
|
- CLI options `--llm-provider=openai|kimi`, `--llm-model=<model>`, and `--llm-base-url=<url>` override corresponding settings for a command.
|
|
|
|
Create an optional `.pi-project-map.json` in the project being mapped. It is merged with the defaults:
|
|
|
|
```json
|
|
{
|
|
"promptInjectionMode": "strong",
|
|
"contextBudgetPercent": 15,
|
|
"contextBudgetMaxTokens": 100000,
|
|
"llmProvider": "openai",
|
|
"llmModel": "gpt-4o-mini",
|
|
"ignorePatterns": ["node_modules", ".git"],
|
|
"tagCap": 8,
|
|
"workflowHintCap": 5
|
|
}
|
|
```
|
|
|
|
`promptInjectionMode` accepts `off`, `advisory`, `strong`, or `strict`. Supplying `ignorePatterns` **replaces** the built-in ignore list rather than extending it. Additional supported settings include `llmBaseUrl` and `reinitFullThresholdPercent`.
|
|
|
|
## Repository layout
|
|
|
|
- `src/` — CLI, map generation, validation, retrieval, configuration, and LLM clients
|
|
- `pi-extension.ts` — Pi extension entry point
|
|
- `SKILL.md` — Pi skill definition and operator guidance
|
|
- `usage-guide.md`, `design-doc.md`, `troubleshooting.md` — additional usage and design documentation
|
|
- `package.json` — package metadata, dependencies, and npm scripts
|
|
|
|
## Operations
|
|
|
|
There is no server or deployment manifest. Operate the tool from the project being mapped and keep generated maps under the target project's normal review and version-control practices.
|