source-map-php

name: source-map-php description: Drive the source-map-php Rust CLI to build, search, and manage Meilisearch-backed code indexes for Laravel and Hyperf PHP repositories. Invoke this whenever the user wants to index or reindex a PHP project, search indexed code (symbols, routes, tests, packages, schema), ask which tests cover a PHP symbol, run source-map-php subcommands (init, doctor, index, search, validate, verify, promote, remove), set up LLM-friendly code search for a PHP app, or troubleshoot Meilisearch-backed PHP code search — including casual phrasings like "index my laravel repo", "build code search for my hyperf service", "find routes for POST /foo in project X", "what tests cover App\Services\Foo::bar", "rebuild the php index after I added a class", or any mention of the source-map-php binary, Meilisearch + PHP code search, or the saved project registry at ~/.config/meilisearch/project.json. Prefer this skill over ad-hoc grep/rg when the user wants structured, framework-aware search against an existing or new source-map-php index.

source-map-php

source-map-php is a Rust CLI that extracts symbols, routes, tests, Composer ownership, and schema hints from Laravel and Hyperf PHP repositories and stores them in Meilisearch for LLM-friendly code search.

This skill helps operate the CLI on behalf of the user. It is not a replacement for general PHP help — invoke it when the user wants to work with the index: build it, search it, validate a symbol, clean it up, or diagnose why it's misbehaving.

When to reach for this skill

• The user names a PHP repo and asks to index, reindex, or search it.
• The user mentions source-map-php, Meilisearch + PHP, or LLM-friendly code search.
• The user wants the tests or routes related to a specific PHP symbol.
• The user hits an error from the binary and wants help.

If the user only wants to understand PHP code without the index, answer directly — don't reach for the indexer.

Pre-flight (once per session, then cache)

Before running indexing or search commands:

1. Binary present and version. Run source-map-php --version. If missing, tell the user how to install (cargo install source-map-php, or brew install dickwu/tap/source-map-php) and stop.
2. Meilisearch reachable. The CLI reads MEILI_HOST + MEILI_MASTER_KEY from env, then falls back to ~/.config/meilisearch/connect.json, then the project config default. Check the values resolve — do not print secrets.
3. Project config. source-map-php init writes config/indexer.toml plus a placeholder ~/.config/meilisearch/connect.json. First-time users in a fresh directory need this. init will not overwrite an existing connect.json.

For a thorough environment check, run source-map-php doctor --repo <path> and relay what it reports. doctor still expects Phpactor on PATH; the extractor has fallback parsing if Phpactor is missing, so mention it's a warning not a blocker.

There is a helper at scripts/env_probe.sh that runs these checks in one shot — use it when the user explicitly wants a health probe.

The six workflows

1. First-time setup

source-map-php init --dir .
cp .env.example .env     # user fills MEILI_HOST and MEILI_MASTER_KEY
source-map-php doctor --repo /absolute/path/to/php-repo

Ask the user to fill the .env before moving on. Don't guess the Meili host — if it isn't already configured, pause and ask.

2. Build or rebuild an index

source-map-php index \
  --repo /absolute/path/to/php-repo \
  --project-name <short-name> \
  --framework auto \
  --mode clean

• --mode clean is the default and what you want almost always — full rebuild.
• --mode staged is for a safe rollout where the user wants to verify before promote. Don't reach for it on routine reindex.
• --framework auto works for standard layouts. Only override if the user explicitly names Laravel or Hyperf, or auto-detection was wrong.
• --project-name is the handle the user will pass to search --project later. Default it to the repo's directory name if the user doesn't supply one.

After indexing, surface the run id from the output (also written to build/index-runs/<run_id>.json) — needed for promote in staged mode.

3. Search the index

source-map-php search --project <name-or-path> --query "<natural query>"

• --project accepts either the saved project name or the absolute repo path.
• Omit --index for the default all — grouped results across symbols, routes, tests, packages, and schema. Narrow it only when the user's intent is clearly scoped (see the slice guide below).
• Add --json when another tool will consume the output (piping into jq, feeding back into the conversation, etc.).
• Show the CLI's output verbatim instead of paraphrasing — the user wants to see where matches live.

4. Validation commands for a symbol

source-map-php validate --symbol 'App\\Services\\ConsentService::sign'

Double-escape backslashes in shell arguments. Add --json for structured output. The CLI returns ranked test/validation commands. Surface the list — only execute the commands if the user asks you to.

5. Staged → verify → promote

Reach for this only when the user explicitly wants a safe rollout:

source-map-php index --mode staged --repo <path> --project-name <name>
source-map-php verify
source-map-php promote --run-id <id>

If the user just wants to search, --mode clean is correct — skip staged.

6. Remove a project

source-map-php remove --project <name>

Add --keep-indexes when the user wants to forget the saved name but keep the Meili indexes intact (useful during a project rename). Confirm before removing — the Meili side is not recoverable from the CLI.

Choosing an --index slice

Grouped all results are usually more informative than guessing a slice.

Sanity-first error recovery

1. Empty results, no error. The query just didn't match — suggest broader terms or a different --index.
2. Meilisearch connection refused. Daemon isn't up, or env points to the wrong host. Show the resolution order (env → ~/.config/meilisearch/connect.json → project default) and ask which the user expects to win.
3. doctor warns about Phpactor. Fallback parsing still works; optionally suggest installing Phpactor for better symbol coverage.
4. Auto-detect picks the wrong framework. Rerun with explicit --framework laravel or --framework hyperf.
5. Non-UTF-8 files in the tree crash the indexer. Known limitation (README roadmap item) — call it out honestly, don't thrash trying to fix it.

When a command errors, read the Rust CLI's message carefully before speculating — it usually prints the actionable thing.

See references/troubleshooting.md for deeper diagnosis steps.

Safety model (context, not a lecture)

The indexer has a built-in sanitizer that drops strings matching patterns for API keys, JWTs, private keys, passwords/DSNs, emails, phone numbers, long numeric IDs, DOB-like strings, and medical-record-style identifiers before they reach Meilisearch. That's by design — this tool is for source-code metadata, not application data.

Don't reiterate this on every command. If the user asks whether it's safe to index repo X, the honest answer is: yes for source code, and the sanitizer catches most accidental secrets, but avoid pointing it at repos whose fixtures contain real PII.

Output style for results

• Print the exact command you ran on one line so the user can copy it.
• For search and validate, show the CLI output verbatim.
• For doctor, verify, promote, summarize — those outputs are long and the user just wants the verdict.

Multi-project workflows

~/.config/meilisearch/project.json is the registry of saved projects. When the user juggles several PHP repos:

• Give each project a distinct name (patient-api, billing-svc, admin-panel).
• Scope searches with --project <name>.
• Only search across everything when the user clearly wants that.

What this skill does NOT do

• Edit PHP code inside the target repo.
• Run PHPUnit / Pest suites — validate surfaces the commands; the user or a separate step runs them.
• Manage the Meilisearch daemon. If Meili isn't running, tell the user to start it and stop.

Reference files

• references/commands.md — full flag reference for every subcommand. Read this when you need exact syntax you can't remember.
• references/troubleshooting.md — deeper diagnosis steps for failure modes that pre-flight doesn't catch.
• scripts/env_probe.sh — health check for the binary and Meili connectivity.
• scripts/sync_to_repo.sh — keep the in-repo copy under <repo>/skills/source-map-php/ in sync with the installed version at ~/.claude/skills/source-map-php/.