@aryam/fixmap 0.8.7 → 0.8.9

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.
package/README.md CHANGED
@@ -27,6 +27,15 @@ For private source or working-tree changes, run from a local JavaScript or TypeS
27
27
  fixmap plan --issue "password reset emails fail"
28
28
  ```
29
29
 
30
+ Install a discoverable `/fixmap` command for supported coding agents, then invoke it without a task to see the complete workflow menu:
31
+
32
+ ```bash
33
+ fixmap setup
34
+ fixmap features
35
+ ```
36
+
37
+ `fixmap setup` supports Claude Code, Cursor, GitHub Copilot prompt files, and the open Agent Skills layout. It preflights every target, is idempotent, and refuses to overwrite customized commands unless you explicitly pass `--force` after reviewing them.
38
+
30
39
  Use a real branch diff:
31
40
 
32
41
  ```bash
@@ -41,11 +50,28 @@ fixmap plan --base main --head HEAD --format json --output fixmap-report.json
41
50
 
42
51
  Public GitHub issue, pull request, and repository URL modes are available in the CLI and MCP server for issue-only analysis. FixMap fetches task context anonymously, shallow-clones the default branch into an isolated temporary directory, disables credentials and repository execution surfaces, and removes the checkout before returning. Clone locally to use `--diff`, `--base`, `--head`, or working-tree inputs.
43
52
 
44
- For long task text, use `--issue-file task.md`, `--issue @task.md`, or pipe text to `--issue -`. A one-off `npx -y @aryam/fixmap@latest ...` run is also available, but npm may choose an existing project-local FixMap first. Run `fixmap doctor`, treat its printed running version as authoritative, and update or remove a stale install. For a reproducible clean test, install the exact version into an isolated npm prefix and invoke that prefix's `fixmap` shim directly; the repository README includes complete PowerShell and POSIX commands.
53
+ For long task text, use `--issue-file task.md` or pipe text to `--issue -`. A leading `@` in `--issue` is ordinary task text; only the explicit file flag reads from disk. A one-off `npx -y @aryam/fixmap@latest ...` run is also available, but npm may choose an existing project-local FixMap first. Run `fixmap doctor`, treat its printed running version as authoritative, and update or remove a stale install. For a reproducible clean test, install the exact version into an isolated npm prefix and invoke that prefix's `fixmap` shim directly; the repository README includes complete PowerShell and POSIX commands.
54
+
55
+ ## Complete feature catalog
56
+
57
+ - **Plan** — rank context files, related tests, test commands, risks, changed files, diagnostics, grounding, confidence, and a next action from task text, a task file, stdin, a public GitHub issue or pull request, a branch diff, or the working tree.
58
+ - **Explain** — use `--explain <path>` to distinguish ranked, below-cutoff, tie-truncated, excluded, and not-scanned paths.
59
+ - **Compare** — use `--compare <report.json>` to measure how a refined task changed ranks, scores, confidence, and grounding.
60
+ - **Verify** — compare a saved plan with the completed diff or working tree; errors fail by default and `--fail-on warning` provides an opt-in strict CI gate without pretending FixMap ran tests or proved correctness.
61
+ - **Validate** — run `fixmap validate <report.json>` to check report compatibility without writing custom JavaScript.
62
+ - **Focus controls** — cap output with `--limit`, repeat `--exclude`, or use ordered `.fixmapignore` patterns with negation. Pasted absolute paths inside the repository are normalized, and unmatched patterns produce a warning.
63
+ - **Live changes** — `--working-tree` maps staged and unstaged tracked edits; `--include-untracked` opts new files into the changed-file set.
64
+ - **Exact-state cache** — clean and tracked dirty git states are cached by repository, commit, status, and binary diff. Cache hits report age, entries expire after seven days, and `--no-cache` reports a fresh bypass.
65
+ - **Artifact isolation** — current issue, comparison, verification, and output files are removed from ranking, change detection, and cache state, so a saved plan cannot recommend or invalidate itself.
66
+ - **Doctor** — report the running version, resolved binary, global/PATH shadows, Node compatibility, and an optionally requested npm version.
67
+ - **MCP** — expose Plan, Explain, Compare, Verify, and Doctor as five local stdio tools.
68
+ - **Slash-command discovery** — `fixmap setup` installs `/fixmap`; `fixmap features` prints the same complete catalog in Markdown or JSON.
69
+ - **Safe repository handling** — public repositories use isolated temporary checkouts with credentials, hooks, filters, and submodule recursion disabled. Local source is read without installing dependencies or running repository scripts.
70
+ - **Human and machine output** — Markdown is the default; JSON reports carry `reportVersion: 1` and follow the documented additive compatibility policy.
45
71
 
46
72
  ## MCP server
47
73
 
48
- FixMap ships as a Model Context Protocol server with `fixmap_plan` and `fixmap_verify`, so coding agents can plan first and compare the resulting diff with that plan afterwards.
74
+ FixMap ships five Model Context Protocol tools: `fixmap_plan`, `fixmap_explain`, `fixmap_compare`, `fixmap_verify`, and `fixmap_doctor`. Plan, Explain, and Verify accept `noCache: true` when an agent needs a fresh repository scan rather than an exact-state cache hit.
49
75
 
50
76
  Claude Code:
51
77
 
@@ -72,10 +98,13 @@ Cursor, Windsurf, or any MCP client:
72
98
  fixmap plan Generate a FixMap report for a task or diff
73
99
  fixmap verify Compare a saved plan with the diff that followed
74
100
  fixmap doctor Report the resolved version and any shadowing install
101
+ fixmap validate Validate a saved FixMap JSON report
102
+ fixmap features List every FixMap capability in Markdown or JSON
103
+ fixmap setup Install /fixmap discovery for supported coding agents
75
104
  fixmap mcp Run FixMap as an MCP server over stdio
76
105
 
77
106
  --issue <text|url> Issue text, task description, or public GitHub issue or pull request URL
78
- --issue-file <file> Read task text from a UTF-8 or UTF-16 file, or - for stdin
107
+ --issue-file <file> Read UTF-8/UTF-16 task text (including BOM-less UTF-16), or - for stdin
79
108
  --diff <spec> Git diff spec, such as main...HEAD
80
109
  --base <ref> Base ref for diffing when --diff is not given
81
110
  --head <ref> Head ref for diffing (defaults to HEAD)
@@ -85,9 +114,11 @@ fixmap mcp Run FixMap as an MCP server over stdio
85
114
  --compare <file> Diff this plan against a saved JSON plan
86
115
  --limit <n> Cap reported context files, 1 to 20 (default 8)
87
116
  --exclude <pattern> Leave paths out of ranking; repeatable, gitignore-flavored
117
+ --no-cache Bypass the exact-state repository scan cache
88
118
  --repo <source> Local path, file:// URL, or public GitHub HTTPS/SSH URL
89
119
  --format <fmt> Output format: markdown (default) or json
90
120
  --output <file> Write the report to a file instead of stdout
121
+ --fail-on <level> Verify exit policy: error (default) or warning
91
122
  ```
92
123
 
93
124
  ## Example output
@@ -0,0 +1,89 @@
1
+ export type AgentTarget = "claude" | "cursor" | "copilot" | "agents";
2
+ export declare const FIXMAP_FEATURES: readonly [{
3
+ readonly name: "Plan";
4
+ readonly command: "fixmap plan";
5
+ readonly detail: "Rank context files, test routes, risks, changed files, and uncertainty from a task, issue URL, diff, or working tree.";
6
+ }, {
7
+ readonly name: "Explain";
8
+ readonly command: "fixmap plan --explain <path>";
9
+ readonly detail: "Show whether a path ranked, tied below the limit, was excluded, or was never scanned.";
10
+ }, {
11
+ readonly name: "Compare";
12
+ readonly command: "fixmap plan --compare <report.json>";
13
+ readonly detail: "Compare a refined task and current plan with an earlier JSON report.";
14
+ }, {
15
+ readonly name: "Verify";
16
+ readonly command: "fixmap verify --report <report.json>";
17
+ readonly detail: "Compare the completed diff or working tree with the saved plan; add --fail-on warning for a strict CI gate.";
18
+ }, {
19
+ readonly name: "Validate";
20
+ readonly command: "fixmap validate <report.json>";
21
+ readonly detail: "Check a saved report against FixMap's structural compatibility contract.";
22
+ }, {
23
+ readonly name: "Doctor";
24
+ readonly command: "fixmap doctor";
25
+ readonly detail: "Diagnose stale local, global, PATH, and npx install shadows.";
26
+ }, {
27
+ readonly name: "MCP";
28
+ readonly command: "fixmap mcp";
29
+ readonly detail: "Expose Plan, Explain, Compare, Verify, and Doctor over local stdio.";
30
+ }, {
31
+ readonly name: "Public tasks";
32
+ readonly command: "fixmap owner/repository#123";
33
+ readonly detail: "Fetch public GitHub issue or pull-request text anonymously and scan its repository in an isolated checkout.";
34
+ }, {
35
+ readonly name: "Repository sources";
36
+ readonly command: "--repo <path|url> --ref <branch|tag>";
37
+ readonly detail: "Map a local checkout, file URL, directory archive, or a named branch or tag from a public GitHub repository.";
38
+ }, {
39
+ readonly name: "Task files";
40
+ readonly command: "--issue-file <file|->";
41
+ readonly detail: "Read long task text from UTF-8, UTF-16, or stdin, including BOM-less UTF-16 from common Windows tools.";
42
+ }, {
43
+ readonly name: "Focus";
44
+ readonly command: "--limit, --exclude, .fixmapignore";
45
+ readonly detail: "Narrow ranking without changing the repository.";
46
+ }, {
47
+ readonly name: "Live changes";
48
+ readonly command: "--working-tree --include-untracked";
49
+ readonly detail: "Map staged, unstaged, and optionally untracked work against HEAD.";
50
+ }, {
51
+ readonly name: "Fresh scan";
52
+ readonly command: "--no-cache";
53
+ readonly detail: "Bypass the exact git-state cache with CLI --no-cache, MCP noCache: true, or Action no-cache: true, and report that a fresh scan was used.";
54
+ }, {
55
+ readonly name: "Machine output";
56
+ readonly command: "--format json --output <file>";
57
+ readonly detail: "Emit a versioned JSON contract or readable Markdown without executing repository code.";
58
+ }, {
59
+ readonly name: "Test routing";
60
+ readonly command: "fixmap plan";
61
+ readonly detail: "Detect package, workspace, and language test commands, related tests, and skipped or gated suites.";
62
+ }, {
63
+ readonly name: "Risk and diagnostics";
64
+ readonly command: "fixmap plan";
65
+ readonly detail: "Report bounded risk areas, grounding quality, unread content, scan limits, package-manager conflicts, and unresolved diffs.";
66
+ }, {
67
+ readonly name: "GitHub Action";
68
+ readonly command: "uses: aryamthecodebreaker/FixMap@<version>";
69
+ readonly detail: "Plan or verify pull requests with bounded summaries, outputs, and one updated comment.";
70
+ }, {
71
+ readonly name: "Agent setup";
72
+ readonly command: "fixmap setup";
73
+ readonly detail: "Install the discoverable /fixmap command for Claude Code, Cursor, GitHub Copilot, or Agent Skills.";
74
+ }];
75
+ export declare function renderFeatureCatalog(format?: "markdown" | "json"): string;
76
+ export declare function installAgentCommands(input: {
77
+ repoRoot: string;
78
+ targets: AgentTarget[];
79
+ force?: boolean;
80
+ }, dependencies?: {
81
+ /** Internal seam for deterministic race/failure tests; production setup never supplies it. */
82
+ beforeCommit?: (entry: {
83
+ path: string;
84
+ displayPath: string;
85
+ }, index: number) => Promise<void>;
86
+ }): Promise<Array<{
87
+ path: string;
88
+ status: "created" | "unchanged" | "updated";
89
+ }>>;
@@ -0,0 +1,361 @@
1
+ import { randomUUID } from "node:crypto";
2
+ import { lstat, mkdir, open, readFile, realpath, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
3
+ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
4
+ import { setTimeout as delay } from "node:timers/promises";
5
+ export const FIXMAP_FEATURES = [
6
+ { name: "Plan", command: "fixmap plan", detail: "Rank context files, test routes, risks, changed files, and uncertainty from a task, issue URL, diff, or working tree." },
7
+ { name: "Explain", command: "fixmap plan --explain <path>", detail: "Show whether a path ranked, tied below the limit, was excluded, or was never scanned." },
8
+ { name: "Compare", command: "fixmap plan --compare <report.json>", detail: "Compare a refined task and current plan with an earlier JSON report." },
9
+ { name: "Verify", command: "fixmap verify --report <report.json>", detail: "Compare the completed diff or working tree with the saved plan; add --fail-on warning for a strict CI gate." },
10
+ { name: "Validate", command: "fixmap validate <report.json>", detail: "Check a saved report against FixMap's structural compatibility contract." },
11
+ { name: "Doctor", command: "fixmap doctor", detail: "Diagnose stale local, global, PATH, and npx install shadows." },
12
+ { name: "MCP", command: "fixmap mcp", detail: "Expose Plan, Explain, Compare, Verify, and Doctor over local stdio." },
13
+ { name: "Public tasks", command: "fixmap owner/repository#123", detail: "Fetch public GitHub issue or pull-request text anonymously and scan its repository in an isolated checkout." },
14
+ { name: "Repository sources", command: "--repo <path|url> --ref <branch|tag>", detail: "Map a local checkout, file URL, directory archive, or a named branch or tag from a public GitHub repository." },
15
+ { name: "Task files", command: "--issue-file <file|->", detail: "Read long task text from UTF-8, UTF-16, or stdin, including BOM-less UTF-16 from common Windows tools." },
16
+ { name: "Focus", command: "--limit, --exclude, .fixmapignore", detail: "Narrow ranking without changing the repository." },
17
+ { name: "Live changes", command: "--working-tree --include-untracked", detail: "Map staged, unstaged, and optionally untracked work against HEAD." },
18
+ { name: "Fresh scan", command: "--no-cache", detail: "Bypass the exact git-state cache with CLI --no-cache, MCP noCache: true, or Action no-cache: true, and report that a fresh scan was used." },
19
+ { name: "Machine output", command: "--format json --output <file>", detail: "Emit a versioned JSON contract or readable Markdown without executing repository code." },
20
+ { name: "Test routing", command: "fixmap plan", detail: "Detect package, workspace, and language test commands, related tests, and skipped or gated suites." },
21
+ { name: "Risk and diagnostics", command: "fixmap plan", detail: "Report bounded risk areas, grounding quality, unread content, scan limits, package-manager conflicts, and unresolved diffs." },
22
+ { name: "GitHub Action", command: "uses: aryamthecodebreaker/FixMap@<version>", detail: "Plan or verify pull requests with bounded summaries, outputs, and one updated comment." },
23
+ { name: "Agent setup", command: "fixmap setup", detail: "Install the discoverable /fixmap command for Claude Code, Cursor, GitHub Copilot, or Agent Skills." }
24
+ ];
25
+ export function renderFeatureCatalog(format = "markdown") {
26
+ if (format === "json")
27
+ return `${JSON.stringify({ features: FIXMAP_FEATURES }, null, 2)}\n`;
28
+ return [
29
+ "# FixMap features",
30
+ "",
31
+ ...FIXMAP_FEATURES.flatMap((feature) => [
32
+ `- **${feature.name}** — \`${feature.command}\``,
33
+ ` ${feature.detail}`
34
+ ]),
35
+ "",
36
+ "Run `fixmap setup` to install `/fixmap` discovery for supported coding agents.",
37
+ ""
38
+ ].join("\n");
39
+ }
40
+ const SHARED_INSTRUCTIONS = `You are the FixMap workflow assistant for this repository.
41
+
42
+ When this command is invoked without a task, run \`fixmap features\` and present every feature in a compact menu. Do not edit files. Ask which workflow the user wants.
43
+
44
+ When the invocation includes a task, issue URL, diff, file path, or workflow name:
45
+
46
+ 1. Run \`fixmap features\` if the requested capability is ambiguous.
47
+ 2. Use the matching local command: Plan, Explain, Compare, Verify, Validate, Doctor, or MCP.
48
+ 3. Preserve the user's repository and never imply that FixMap ran tests or proved correctness; it produces a starting map and verification findings.
49
+ 4. Report the exact command used and summarize files, checks, risks, and diagnostics.
50
+
51
+ Prefer \`fixmap plan --issue "$ARGUMENTS" --repo .\` for task text. Use a canonical public GitHub issue URL directly when one is provided.`;
52
+ const templates = {
53
+ claude: {
54
+ path: ".claude/skills/fixmap/SKILL.md",
55
+ contents: `---\nname: fixmap\ndescription: Discover and run every FixMap repository-mapping workflow\ndisable-model-invocation: true\nargument-hint: [task, issue URL, file, diff, or workflow]\n---\n\n${SHARED_INSTRUCTIONS}\n`
56
+ },
57
+ cursor: {
58
+ path: ".cursor/commands/fixmap.md",
59
+ contents: `---\ndescription: List or run every FixMap repository-mapping workflow\n---\n\n${SHARED_INSTRUCTIONS}\n`
60
+ },
61
+ copilot: {
62
+ path: ".github/prompts/fixmap.prompt.md",
63
+ contents: `---\nagent: 'agent'\ndescription: 'List or run every FixMap repository-mapping workflow'\n---\n\n${SHARED_INSTRUCTIONS}\n`
64
+ },
65
+ agents: {
66
+ path: ".agents/skills/fixmap/SKILL.md",
67
+ contents: `---\nname: fixmap\ndescription: Discover and run every FixMap repository-mapping workflow\n---\n\n${SHARED_INSTRUCTIONS}\n`
68
+ }
69
+ };
70
+ export async function installAgentCommands(input, dependencies = {}) {
71
+ const requestedRoot = resolve(input.repoRoot);
72
+ try {
73
+ if (!(await stat(requestedRoot)).isDirectory())
74
+ throw new Error("not a directory");
75
+ }
76
+ catch {
77
+ throw new Error(`Setup repository "${requestedRoot}" does not exist or is not a directory.`);
78
+ }
79
+ const root = await realpath(requestedRoot);
80
+ const setupLock = await acquireSetupLock(root);
81
+ try {
82
+ const prepared = [];
83
+ // Preflight every target before writing any of them. A customized command or unsafe link
84
+ // must not leave a half-installed multi-agent setup behind.
85
+ for (const target of input.targets) {
86
+ const template = templates[target];
87
+ const path = join(root, template.path);
88
+ const displayPath = relative(root, path).replace(/\\/g, "/");
89
+ await assertSafeTarget(root, path, displayPath);
90
+ let existing;
91
+ try {
92
+ existing = await readFile(path, "utf8");
93
+ }
94
+ catch (error) {
95
+ if (error.code !== "ENOENT") {
96
+ throw new Error(`Could not inspect existing ${displayPath}: ${error instanceof Error ? error.message : String(error)}`);
97
+ }
98
+ }
99
+ if (existing !== undefined && !input.force) {
100
+ if (existing !== template.contents) {
101
+ throw new Error(`Refusing to overwrite existing ${displayPath}. Re-run with --force after reviewing it.`);
102
+ }
103
+ }
104
+ prepared.push({ path, displayPath, contents: template.contents, existing });
105
+ }
106
+ const changed = prepared.filter((entry) => entry.existing !== entry.contents);
107
+ const staged = [];
108
+ const committed = [];
109
+ const createdDirectories = new Set();
110
+ try {
111
+ // Stage every new command beside its destination before mutating any destination. The
112
+ // random sibling name means a parent link swapped after preflight cannot redirect the
113
+ // final rename: that name will not exist in the attacker's directory, so rename fails.
114
+ for (const entry of changed) {
115
+ const parent = dirname(entry.path);
116
+ const firstCreated = await mkdir(parent, { recursive: true });
117
+ if (firstCreated)
118
+ rememberCreatedDirectories(createdDirectories, firstCreated, parent);
119
+ await assertSafeTarget(root, entry.path, entry.displayPath);
120
+ const stagedPath = join(parent, `.${basename(entry.path)}.fixmap-${randomUUID()}.tmp`);
121
+ await writeFile(stagedPath, entry.contents, { encoding: "utf8", flag: "wx" });
122
+ await assertSafeTarget(root, stagedPath, `${entry.displayPath} staging file`);
123
+ staged.push({ ...entry, stagedPath });
124
+ }
125
+ for (let index = 0; index < staged.length; index += 1) {
126
+ const entry = staged[index];
127
+ await dependencies.beforeCommit?.({ path: entry.path, displayPath: entry.displayPath }, index);
128
+ // Close the original check-then-write window. rename replaces a final symlink or
129
+ // hardlink directory entry rather than following it, but rejecting one is clearer and
130
+ // preserves an unexpected concurrent change instead of silently replacing it.
131
+ await assertTargetUnchanged(root, entry.path, entry.displayPath, entry.existing);
132
+ await assertSafeTarget(root, entry.stagedPath, `${entry.displayPath} staging file`);
133
+ await rename(entry.stagedPath, entry.path);
134
+ committed.push(entry);
135
+ }
136
+ }
137
+ catch (error) {
138
+ const rollbackErrors = [];
139
+ for (const entry of committed.reverse()) {
140
+ try {
141
+ if (entry.existing === undefined) {
142
+ await assertSafeTarget(root, entry.path, entry.displayPath);
143
+ const current = await readFile(entry.path, "utf8");
144
+ if (current !== entry.contents) {
145
+ throw new Error("the installed file changed before rollback");
146
+ }
147
+ await unlink(entry.path);
148
+ }
149
+ else {
150
+ await replaceWithContents(root, entry.path, entry.displayPath, entry.existing);
151
+ }
152
+ }
153
+ catch (rollbackError) {
154
+ rollbackErrors.push(`${entry.displayPath}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
155
+ }
156
+ }
157
+ await cleanupStagingFiles(staged);
158
+ await cleanupCreatedDirectories(createdDirectories);
159
+ const detail = error instanceof Error ? error.message : String(error);
160
+ if (rollbackErrors.length > 0) {
161
+ throw new Error(`${detail} Setup rollback also failed for ${rollbackErrors.join("; ")}.`);
162
+ }
163
+ throw error;
164
+ }
165
+ const results = prepared.map((entry) => ({
166
+ path: entry.displayPath,
167
+ status: entry.existing === entry.contents
168
+ ? "unchanged"
169
+ : entry.existing === undefined
170
+ ? "created"
171
+ : "updated"
172
+ }));
173
+ return results;
174
+ }
175
+ finally {
176
+ await releaseSetupLock(setupLock);
177
+ }
178
+ }
179
+ async function assertTargetUnchanged(root, target, displayPath, expectedContents) {
180
+ await assertSafeTarget(root, target, displayPath);
181
+ try {
182
+ const currentContents = await readFile(target, "utf8");
183
+ if (expectedContents === undefined || currentContents !== expectedContents) {
184
+ throw new Error(`Refusing to write ${displayPath} because it changed while setup was running.`);
185
+ }
186
+ }
187
+ catch (error) {
188
+ if (error.code !== "ENOENT")
189
+ throw error;
190
+ if (expectedContents !== undefined) {
191
+ throw new Error(`Refusing to write ${displayPath} because it changed while setup was running.`);
192
+ }
193
+ }
194
+ }
195
+ async function assertSafeTarget(root, target, displayPath) {
196
+ try {
197
+ const targetMetadata = await lstat(target);
198
+ if (targetMetadata.isSymbolicLink()) {
199
+ throw new Error(`Refusing to write ${displayPath} because the target is a symbolic link.`);
200
+ }
201
+ if (!targetMetadata.isFile()) {
202
+ throw new Error(`Refusing to write ${displayPath} because the target is not a regular file.`);
203
+ }
204
+ if (targetMetadata.nlink > 1) {
205
+ throw new Error(`Refusing to write ${displayPath} because the target is hard-linked to another file.`);
206
+ }
207
+ }
208
+ catch (error) {
209
+ if (error.code !== "ENOENT")
210
+ throw error;
211
+ }
212
+ let ancestor = dirname(target);
213
+ while (true) {
214
+ try {
215
+ const ancestorMetadata = await lstat(ancestor);
216
+ if (!ancestorMetadata.isDirectory() && !ancestorMetadata.isSymbolicLink()) {
217
+ throw new Error(`Refusing to write ${displayPath} because ${ancestor} is not a directory.`);
218
+ }
219
+ const resolvedAncestor = await realpath(ancestor);
220
+ const distance = relative(root, resolvedAncestor);
221
+ if (distance === ".." || distance.startsWith(`..${sep}`) || isAbsolute(distance)) {
222
+ throw new Error(`Refusing to write ${displayPath} because its parent resolves outside the setup repository.`);
223
+ }
224
+ if (ancestorMetadata.isSymbolicLink()) {
225
+ throw new Error(`Refusing to write ${displayPath} because parent ${ancestor} is a symbolic link.`);
226
+ }
227
+ return;
228
+ }
229
+ catch (error) {
230
+ if (error.code !== "ENOENT")
231
+ throw error;
232
+ const parent = dirname(ancestor);
233
+ if (parent === ancestor) {
234
+ throw new Error(`Could not find a safe parent directory for ${displayPath}.`);
235
+ }
236
+ ancestor = parent;
237
+ }
238
+ }
239
+ }
240
+ async function replaceWithContents(root, target, displayPath, contents) {
241
+ const parent = dirname(target);
242
+ await assertSafeTarget(root, target, displayPath);
243
+ const stagedPath = join(parent, `.${basename(target)}.fixmap-rollback-${randomUUID()}.tmp`);
244
+ try {
245
+ await writeFile(stagedPath, contents, { encoding: "utf8", flag: "wx" });
246
+ await assertSafeTarget(root, stagedPath, `${displayPath} rollback file`);
247
+ await assertSafeTarget(root, target, displayPath);
248
+ await rename(stagedPath, target);
249
+ }
250
+ finally {
251
+ try {
252
+ await unlink(stagedPath);
253
+ }
254
+ catch (error) {
255
+ if (error.code !== "ENOENT")
256
+ throw error;
257
+ }
258
+ }
259
+ }
260
+ async function cleanupStagingFiles(entries) {
261
+ for (const entry of entries) {
262
+ try {
263
+ await unlink(entry.stagedPath);
264
+ }
265
+ catch (error) {
266
+ if (error.code !== "ENOENT") {
267
+ // Cleanup cannot make the original installation failure safer or more actionable.
268
+ // A unique .tmp file may remain, but no /fixmap command points at it.
269
+ }
270
+ }
271
+ }
272
+ }
273
+ function rememberCreatedDirectories(paths, firstCreated, leaf) {
274
+ const boundary = dirname(resolve(firstCreated));
275
+ let current = resolve(leaf);
276
+ while (current !== boundary) {
277
+ paths.add(current);
278
+ const parent = dirname(current);
279
+ if (parent === current)
280
+ break;
281
+ current = parent;
282
+ }
283
+ }
284
+ async function cleanupCreatedDirectories(paths) {
285
+ const deepestFirst = [...paths].sort((left, right) => right.length - left.length);
286
+ for (const path of deepestFirst) {
287
+ try {
288
+ await rmdir(path);
289
+ }
290
+ catch (error) {
291
+ if (!new Set(["ENOENT", "ENOTEMPTY", "EEXIST"]).has(String(error.code))) {
292
+ // Never turn cleanup of an empty setup directory into a broader deletion.
293
+ }
294
+ }
295
+ }
296
+ }
297
+ async function acquireSetupLock(root) {
298
+ const path = join(root, ".fixmap-setup.lock");
299
+ const deadline = Date.now() + 10_000;
300
+ while (true) {
301
+ const token = `${process.pid}:${Date.now()}:${randomUUID()}`;
302
+ try {
303
+ const handle = await open(path, "wx", 0o600);
304
+ try {
305
+ await handle.writeFile(token, "utf8");
306
+ return { handle, path, token };
307
+ }
308
+ catch (error) {
309
+ await handle.close();
310
+ try {
311
+ await unlink(path);
312
+ }
313
+ catch { /* preserve the original lock creation error */ }
314
+ throw error;
315
+ }
316
+ }
317
+ catch (error) {
318
+ const code = String(error.code ?? "");
319
+ if (!new Set(["EEXIST", "EPERM", "EACCES"]).has(code))
320
+ throw error;
321
+ // Windows can briefly report EPERM while another setup closes and removes the lock.
322
+ // Retry that directory-entry transition, but preserve a persistent permission error
323
+ // when no lock file actually exists instead of misreporting it as another setup.
324
+ let lockPresent = code === "EEXIST";
325
+ if (!lockPresent) {
326
+ try {
327
+ await lstat(path);
328
+ lockPresent = true;
329
+ }
330
+ catch (inspectionError) {
331
+ if (inspectionError.code !== "ENOENT")
332
+ lockPresent = true;
333
+ }
334
+ }
335
+ if (Date.now() >= deadline) {
336
+ if (!lockPresent && code !== "EEXIST")
337
+ throw error;
338
+ throw new Error(`Another FixMap setup is still using "${path}". Wait for it to finish, or remove the lock only after confirming no setup process is running.`);
339
+ }
340
+ await delay(25);
341
+ }
342
+ }
343
+ }
344
+ async function releaseSetupLock(lock) {
345
+ await lock.handle.close();
346
+ try {
347
+ const [contents, metadata] = await Promise.all([
348
+ readFile(lock.path, "utf8"),
349
+ lstat(lock.path)
350
+ ]);
351
+ if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.nlink > 1 || contents !== lock.token) {
352
+ throw new Error(`FixMap setup lock "${lock.path}" changed while setup was running; it was left in place for review.`);
353
+ }
354
+ await unlink(lock.path);
355
+ }
356
+ catch (error) {
357
+ if (error.code !== "ENOENT")
358
+ throw error;
359
+ }
360
+ }
361
+ //# sourceMappingURL=agent-setup.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-setup.js","sourceRoot":"","sources":["../src/agent-setup.ts"],"names":[],"mappings":"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"}
@@ -9,29 +9,32 @@ export type CliOptions = {
9
9
  diffSpec?: string | undefined;
10
10
  baseRef?: string | undefined;
11
11
  headRef?: string | undefined;
12
+ checkoutRef?: string | undefined;
12
13
  format: "markdown" | "json";
13
14
  output?: string | undefined;
14
15
  explainPath?: string | undefined;
15
16
  reportPath?: string | undefined;
16
17
  comparePath?: string | undefined;
17
18
  limit?: number | undefined;
19
+ failOn?: "error" | "warning" | undefined;
18
20
  exclude: string[];
19
21
  workingTree: boolean;
20
22
  includeUntracked: boolean;
23
+ noCache: boolean;
21
24
  unknownArgs: string[];
22
25
  invalidValues: string[];
23
26
  };
24
27
  export type CliDependencies = {
25
28
  buildReport?: (input: RepositoryPlanInput) => Promise<FixMapReport>;
26
29
  readVersion?: () => string;
27
- runMcpServer?: () => Promise<void>;
30
+ runMcpServer?: (defaultRepo?: string) => Promise<void>;
28
31
  runDoctor?: () => Promise<DoctorReport>;
29
32
  stderr?: (text: string) => void;
30
33
  stdout?: (text: string) => void;
31
34
  writeReport?: (path: string, contents: string) => Promise<void>;
32
35
  readIssueFile?: (path: string | number) => string | Buffer;
33
36
  };
34
- export declare const USAGE = "FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.\n\nUsage:\n fixmap owner/repository#123\n fixmap https://github.com/owner/repository/issues/123\n fixmap plan --issue \"Users cannot reset passwords\"\n fixmap plan --issue https://github.com/owner/repository/issues/123\n fixmap plan --issue https://github.com/owner/repository/pull/123\n fixmap plan --issue-file task.md\n fixmap plan --issue -\n fixmap plan --issue \"Fix login\" --repo https://github.com/owner/repository\n fixmap plan --diff main...HEAD\n fixmap plan --working-tree --include-untracked --limit 12 --exclude \"docs/**\"\n fixmap plan --issue \"Fix login\" --format json --output current.json --compare previous.json\n fixmap plan --base main --head HEAD --format json\n fixmap verify --report fixmap-report.json --diff main...HEAD\n fixmap verify --report fixmap-report.json --working-tree\n fixmap doctor --format json\n fixmap mcp\n\nCommands:\n plan Generate a FixMap report for a task or diff\n verify Compare a saved report against the diff that followed it\n doctor Check the FixMap install for stale global or npx shadows\n mcp Run FixMap as an MCP server over stdio for AI coding agents\n\nOptions:\n --issue <text|url> Task text, or a public GitHub issue or pull request URL\n --issue-file <file> Read task text from a UTF-8 or UTF-16 file (use - for stdin)\n --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)\n --base <ref> Base ref for diffing when --diff is not given\n --head <ref> Head ref for diffing (defaults to HEAD)\n --working-tree Map staged and unstaged changes against HEAD\n --include-untracked With --working-tree, also include untracked files\n --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)\n --limit <n> Maximum context files to report (default 8, max 20)\n --exclude <glob> Path pattern to leave out of ranking (repeatable)\n --format <fmt> Output format: markdown (default) or json\n --output <file> Write the report or verification to a file instead of stdout\n --explain <path> Explain why one file was ranked where it was, or left out\n --compare <file> Compare this plan against an earlier JSON report\n --report <file> Verify command only: the JSON report the change was planned from\n --help, -h Show this help\n --version, -v Show the FixMap version\n\nA repository may also list exclusion patterns in .fixmapignore, one per line. Supported\nsyntax is *, **, ?, root-leading /, directory-trailing /, comments, and ! negation.\nSet FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.\n";
37
+ export declare const USAGE = "FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.\n\nUsage:\n fixmap owner/repository#123\n fixmap https://github.com/owner/repository/issues/123\n fixmap plan --issue \"Users cannot reset passwords\"\n fixmap plan --issue https://github.com/owner/repository/issues/123\n fixmap plan --issue https://github.com/owner/repository/pull/123\n fixmap plan --issue-file task.md\n fixmap plan --issue -\n fixmap plan --issue \"Fix login\" --repo https://github.com/owner/repository\n fixmap plan --issue \"Fix login\" --repo https://github.com/owner/repository --ref release-2.x\n fixmap plan --diff main...HEAD\n fixmap plan --working-tree --include-untracked --limit 12 --exclude \"docs/**\"\n fixmap plan --no-cache --issue \"Fix login\" --repo .\n fixmap plan --issue \"Fix login\" --format json --output plan.json\n fixmap plan --issue \"Fix login in auth middleware\" --compare plan.json\n fixmap plan --base main --head HEAD --format json\n fixmap verify --report plan.json --diff main...HEAD\n fixmap verify --report plan.json --working-tree\n fixmap verify --report plan.json --working-tree --fail-on warning\n fixmap doctor --format json\n fixmap validate plan.json\n fixmap features\n fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>]\n fixmap mcp [--repo <path>]\n\nCommands:\n plan Generate a FixMap report for a task or diff\n verify Compare a saved report against the diff that followed it\n doctor Check the FixMap install for stale global or npx shadows\n validate Validate a saved FixMap JSON report\n features List every FixMap capability and its command\n setup Install a discoverable /fixmap command for coding agents\n mcp Run FixMap as an MCP server over stdio for AI coding agents\n\nOptions:\n --issue <text|url> Task text, or a public GitHub issue or pull request URL\n --issue-file <file> Read task text from a UTF-8 or UTF-16 file (use - for stdin)\n --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)\n --base <ref> Base ref for diffing when --diff is not given\n --head <ref> Head ref for diffing (defaults to HEAD)\n --working-tree Map staged and unstaged changes against HEAD\n --include-untracked With --working-tree, also include untracked files\n --no-cache Bypass the exact git-state repository scan cache\n --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)\n --ref <branch|tag> Branch or tag to scan when --repo is a remote GitHub URL\n --limit <n> Maximum context files to report (default 8, max 20)\n --exclude <glob> Path pattern to leave out of ranking (repeatable)\n --format <fmt> Output format: markdown (default) or json\n --output <file> Write the report or verification to a file instead of stdout\n --explain <path> Explain why one file was ranked where it was, or left out\n --compare <file> Compare this plan against an earlier JSON report\n --report <file> Verify command only: the JSON report the change was planned from\n --fail-on <level> Verify exit policy: error (default) or warning\n --help, -h Show this help\n --version, -v Show the FixMap version\n\nA repository may also list exclusion patterns in .fixmapignore, one per line. Supported\nsyntax is *, **, ?, repository-root-leading /, directory-trailing /, comments, and ! negation.\nAbsolute paths pasted from inside the repository are normalized to repository-relative patterns.\nSet FIXMAP_PROGRESS=1 to print scan and clone phases to stderr.\nSet FIXMAP_CACHE_DIR to move the OS scan cache, and FIXMAP_VERBOSE_USAGE=1 to include this full help after argument errors.\n";
35
38
  export declare function runCli(args: string[], dependencies?: CliDependencies): Promise<number>;
36
39
  export declare function expandIssueShorthand(args: string[]): string[];
37
40
  export declare const MAX_CONTEXT_FILE_LIMIT = 20;