@ushiradineth/veil 0.2.2 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +119 -80
  2. package/dist/bin.js +16001 -4199
  3. package/package.json +7 -2
package/README.md CHANGED
@@ -1,134 +1,173 @@
1
- # Veil CLI
1
+ # Veil Agent Toolkit
2
2
 
3
- Veil is a fast CLI and skill for local code retrieval and agent context workflows.
3
+ Veil helps coding agents find the right code fast.
4
4
 
5
- It indexes a repository and provides focused commands for files, symbols, semantic lookup,
6
- web/fetch context, and git or GitHub reads.
5
+ Without Veil, agents often:
7
6
 
8
- ## What It Is For
7
+ - search too many files
8
+ - guess where symbols are
9
+ - repeat the same scans after each change
10
+
11
+ With Veil, agents can:
12
+
13
+ - use `discover` to get files, symbols, and code chunks in one step
14
+ - use `lookup` to get the most relevant context for the task
15
+ - use `files`, `symbols`, and `search` for focused follow-up
16
+ - use built-in git and web tools instead of ad hoc shell commands
9
17
 
10
- Veil is built for agent workflows that need fast, token-lean context before editing code.
18
+ Agents should:
11
19
 
12
20
  - Start broad with `discover`
13
21
  - Narrow with `lookup`, `search`, `files`, or `symbols`
14
22
  - Use built-in git and web commands instead of ad hoc shell fallbacks
15
23
 
16
- ## Install
24
+ ## What It Is For
17
25
 
18
- Requires Node.js 20 or later.
26
+ Veil is built for agents that need to move from prompt to implementation quickly.
19
27
 
20
- ### Homebrew
28
+ It gives the agent indexed access to files, symbols, and relevant code chunks, so it can retrieve precise context before writing code. This reduces broad file reads and repeated text scans, improves token efficiency, and shortens time to first meaningful code change.
21
29
 
22
- ```bash
23
- brew tap ushiradineth/homebrew https://github.com/ushiradineth/homebrew
24
- brew install veil
25
- ```
30
+ In practice, Veil acts as a local retrieval layer for coding agents: discover where code lives, resolve symbols, pull focused context, then execute edits.
26
31
 
27
- ### Nix
32
+ ## Setup
28
33
 
29
- Run without installing:
34
+ ### Initialize using the CLI (recommended)
30
35
 
31
36
  ```bash
32
- nix run github:ushiradineth/veil
37
+ npx -y @ushiradineth/veil@latest init
33
38
  ```
34
39
 
35
- ### npm
40
+ ### Setup manually
41
+
42
+ #### Install the CLI
43
+
44
+ Package managers:
36
45
 
37
46
  ```bash
38
47
  npm i -g @ushiradineth/veil
48
+ pnpm add -g @ushiradineth/veil
49
+ yarn global add @ushiradineth/veil
50
+ bun add -g @ushiradineth/veil
39
51
  ```
40
52
 
41
- Or run without install:
53
+ Homebrew:
42
54
 
43
55
  ```bash
44
- npx -y @ushiradineth/veil@latest status --workspace .
56
+ brew tap ushiradineth/homebrew https://github.com/ushiradineth/homebrew
57
+ brew install veil
45
58
  ```
46
59
 
47
- ## Install Skill
60
+ #### Install the Skill (based on your preference)
61
+
62
+ CLI skill:
48
63
 
49
64
  ```bash
50
- npx -y skills add https://github.com/ushiradineth/veil/tree/main --skill veil
65
+ npx -y skills add https://github.com/ushiradineth/veil --skill veil-cli
51
66
  ```
52
67
 
53
- ## CLI Examples
68
+ MCP skill:
54
69
 
55
70
  ```bash
56
- # status and refresh
57
- veil status --workspace .
58
- veil init --workspace .
59
- veil refresh --workspace . --mode changed
60
-
61
- # local index retrieval
62
- veil discover --workspace . --query "find build logic"
63
- veil lookup --workspace . --query "where is parseNdjson defined"
64
- veil search --workspace . --query "pnpm install"
65
-
66
- # web and fetch
67
- veil web-search --query "typescript language server" --limit 5
68
- veil fetch-url --url https://www.iana.org/domains/reserved --format markdown
69
-
70
- # git and github context
71
- veil git-status --workspace .
72
- veil git-log --workspace . --limit 10
73
- veil git-diff --workspace .
74
- veil git-show --workspace . --rev HEAD
75
- veil gh-lookup --repo ushiradineth/veil --kind repo_context
71
+ npx -y skills add https://github.com/ushiradineth/veil --skill veil-mcp
72
+ ```
76
73
 
77
- # diagnostics
78
- veil diagnostics
74
+ ### MCP Client Configuration
79
75
 
80
- # optional MCP server
81
- veil mcp server
76
+ <details>
77
+ <summary>Codex</summary>
78
+ Follow the <a href="https://developers.openai.com/codex/mcp/#configure-with-the-cli">configure MCP guide</a>
79
+ using the standard config from above. You can also install Veil using the Codex CLI:
82
80
 
81
+ ```bash
82
+ codex mcp add veil -- npx -y @ushiradineth/veil@latest mcp server
83
83
  ```
84
84
 
85
- ## Commands
85
+ </details>
86
86
 
87
- - `status`, `init`, `refresh`
88
- - `discover`, `lookup`, `files`, `symbols`, `search`
89
- - `web-search`, `fetch-url`
90
- - `git-status`, `git-log`, `git-diff`, `git-show`, `gh-lookup`
91
- - `diagnostics`
87
+ <details>
88
+ <summary>Claude Code</summary>
92
89
 
93
- ## Development Commands
90
+ Install via CLI:
94
91
 
95
92
  ```bash
96
- nix run nixpkgs#bun -- install
97
- nix run nixpkgs#bun -- run lint
98
- nix run nixpkgs#bun -- test ./src/test.ts
93
+ claude mcp add --scope user veil -- npx -y @ushiradineth/veil@latest mcp server
99
94
  ```
100
95
 
101
- ## Benchmark A/B
96
+ See the <a href="https://code.claude.com/docs/en/mcp">Claude Code MCP guide</a> for more details.
102
97
 
103
- Run A/B strategy benchmarks (Veil MCP vs Veil CLI+skill) with competitor cells:
98
+ </details>
104
99
 
105
- ```bash
106
- nix run nixpkgs#bun -- run src/bench-suite.ts --workspace /path/to/repo --agents veil,firecrawl --strategies mcp_transport,cli_skill --profile smoke --cold 1 --warm 1
107
- ```
100
+ <details>
101
+ <summary>OpenCode</summary>
108
102
 
109
- ## Release
103
+ Add the following configuration to your `opencode.json` file. If you do not have one, create it at `~/.config/opencode/opencode.json` (<a href="https://opencode.ai/docs/mcp-servers">guide</a>):
110
104
 
111
- Releases follow a trunk-gated PR promotion flow.
105
+ ```json
106
+ {
107
+ "$schema": "https://opencode.ai/config.json",
108
+ "mcp": {
109
+ "veil": {
110
+ "type": "local",
111
+ "command": ["npx", "-y", "@ushiradineth/veil@latest", "mcp", "server"]
112
+ }
113
+ }
114
+ }
115
+ ```
112
116
 
113
- 1. Dispatch the `Release` workflow from `main` with a bump type (`patch`, `minor`, `major`).
114
- This creates a `release/vX.Y.Z` branch and opens a PR to `main`.
115
- 2. CI runs on the PR. Merge when checks pass.
116
- 3. Merging triggers the `Publish` workflow which tags, publishes to npm, creates a GitHub release,
117
- and updates the Homebrew formula in the tap repository.
117
+ </details>
118
118
 
119
- Required GitHub secrets:
119
+ <details>
120
+ <summary>Cursor</summary>
120
121
 
121
- | Secret | Purpose |
122
- | --------------------------- | ---------------------------------------------- |
123
- | `NPM_TOKEN` | Publish to npm registry |
124
- | `RELEASE_PR_TOKEN` | PAT to open release PR so CI triggers on it |
125
- | `HOMEBREW_TAP_GITHUB_TOKEN` | PAT with write access to the Homebrew tap repo |
122
+ Click to install:
126
123
 
127
- Optional repository variables:
124
+ [<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=veil&config=eyJjb21tYW5kIjoibnB4IC15IEB1c2hpcmFkaW5ldGgvdmVpbEBsYXRlc3QgbWNwIHNlcnZlciJ9)
128
125
 
129
- | Variable | Default | Purpose |
130
- | ----------------------- | ----------------------- | ------------------------ |
131
- | `HOMEBREW_TAP_REPO` | `ushiradineth/homebrew` | Tap owner/repo |
132
- | `HOMEBREW_FORMULA_PATH` | `Formula/veil.rb` | Formula file path in tap |
126
+ Or install manually in `Cursor Settings` -> `MCP` -> `New MCP Server` with:
127
+
128
+ ```json
129
+ {
130
+ "mcpServers": {
131
+ "veil": {
132
+ "command": "npx",
133
+ "args": ["-y", "@ushiradineth/veil@latest", "mcp", "server"]
134
+ }
135
+ }
136
+ }
137
+ ```
133
138
 
134
- Branch protection on `main` should require the `CI / test` check context before merge.
139
+ </details>
140
+
141
+ <details>
142
+ <summary>Windsurf</summary>
143
+ Follow the <a href="https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json">configure MCP guide</a>
144
+ using the standard config from above.
145
+ </details>
146
+
147
+ ## Capabilities
148
+
149
+ Use the same capability surface from either CLI or MCP.
150
+
151
+ | Capability | What it does | CLI command | MCP tool |
152
+ | ------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------- | ------------- |
153
+ | Index status | Shows index freshness, manifest health, and stale reasons. | `veil status --workspace .` | `status` |
154
+ | Incremental index refresh | Rebuilds index records from changed files only. | `veil refresh --workspace . --mode changed` | `refresh` |
155
+ | Discover files, symbols, chunks | Returns a mixed set of high-signal retrieval context in one call. | `veil discover --workspace . --query "<query>"` | `discover` |
156
+ | Intent-aware ranked lookup | Ranks relevant context with intent-aware scoring for coding tasks. | `veil lookup --workspace . --query "<query>"` | `lookup` |
157
+ | File path retrieval | Finds matching file paths for quick navigation. | `veil files --workspace . --query "<query>"` | `files` |
158
+ | Symbol retrieval | Finds functions, classes, types, and methods by name. | `veil symbols --workspace . --query "<query>"` | `symbols` |
159
+ | Content search | Searches indexed code and docs chunks by query. | `veil search --workspace . --query "<query>"` | `search` |
160
+ | Web search | Runs multi-provider web search for external context. | `veil web-search --query "<query>"` | `web_search` |
161
+ | URL fetch and markdown normalization | Fetches web content and normalizes output for agent-friendly reading. | `veil fetch-url --url <url> --format markdown` | `fetch_url` |
162
+ | Git status | Shows branch state, dirty files, and untracked changes. | `veil git-status --workspace .` | `git_status` |
163
+ | Git log | Returns recent commits with metadata for project history checks. | `veil git-log --workspace . --limit 10` | `git_log` |
164
+ | Git diff | Returns working tree or revision-range diffs. | `veil git-diff --workspace .` | `git_diff` |
165
+ | Git show | Shows full details for a specific revision. | `veil git-show --workspace . --rev HEAD` | `git_show` |
166
+ | GitHub context lookup | Pulls repository or pull request context via `gh` integration. | `veil gh-lookup --repo <owner/repo> --kind repo_context` | `gh_lookup` |
167
+ | Runtime diagnostics | Surfaces cache counters and latency diagnostics. | `veil diagnostics` | `diagnostics` |
168
+
169
+ CLI-only setup/runtime helpers:
170
+
171
+ - `veil init --workspace . --mode mcp|cli`
172
+ - `veil build --workspace .`
173
+ - `veil mcp server`