@aryam/fixmap 0.9.0 → 0.9.2

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 (69) hide show
  1. package/README.md +109 -9
  2. package/dist/agent-setup.d.ts +6 -97
  3. package/dist/agent-setup.js +20 -6
  4. package/dist/agent-setup.js.map +1 -1
  5. package/dist/analysis-source.d.ts +1 -0
  6. package/dist/analysis-source.js +6 -2
  7. package/dist/analysis-source.js.map +1 -1
  8. package/dist/annotation-command.d.ts +8 -0
  9. package/dist/annotation-command.js +187 -0
  10. package/dist/annotation-command.js.map +1 -0
  11. package/dist/annotation-tool.d.ts +62 -0
  12. package/dist/annotation-tool.js +64 -0
  13. package/dist/annotation-tool.js.map +1 -0
  14. package/dist/ask-command.d.ts +9 -0
  15. package/dist/ask-command.js +127 -0
  16. package/dist/ask-command.js.map +1 -0
  17. package/dist/capability-command.d.ts +11 -0
  18. package/dist/capability-command.js +540 -0
  19. package/dist/capability-command.js.map +1 -0
  20. package/dist/change-scope-command.d.ts +7 -0
  21. package/dist/change-scope-command.js +162 -0
  22. package/dist/change-scope-command.js.map +1 -0
  23. package/dist/cli-runner.d.ts +2 -1
  24. package/dist/cli-runner.js +165 -47
  25. package/dist/cli-runner.js.map +1 -1
  26. package/dist/cli.js +26 -1
  27. package/dist/cli.js.map +1 -1
  28. package/dist/decode-input.d.ts +4 -0
  29. package/dist/decode-input.js +44 -0
  30. package/dist/decode-input.js.map +1 -0
  31. package/dist/doctor.d.ts +1 -0
  32. package/dist/doctor.js +14 -1
  33. package/dist/doctor.js.map +1 -1
  34. package/dist/editor-command.d.ts +8 -0
  35. package/dist/editor-command.js +46 -0
  36. package/dist/editor-command.js.map +1 -0
  37. package/dist/history-command.d.ts +14 -0
  38. package/dist/history-command.js +145 -0
  39. package/dist/history-command.js.map +1 -0
  40. package/dist/mcp.d.ts +20 -0
  41. package/dist/mcp.js +599 -11
  42. package/dist/mcp.js.map +1 -1
  43. package/dist/migration-command.d.ts +15 -0
  44. package/dist/migration-command.js +142 -0
  45. package/dist/migration-command.js.map +1 -0
  46. package/dist/repository-source.d.ts +1 -0
  47. package/dist/repository-source.js +7 -3
  48. package/dist/repository-source.js.map +1 -1
  49. package/dist/reverse-docs-command.d.ts +16 -0
  50. package/dist/reverse-docs-command.js +114 -0
  51. package/dist/reverse-docs-command.js.map +1 -0
  52. package/dist/runtime-command.d.ts +15 -0
  53. package/dist/runtime-command.js +121 -0
  54. package/dist/runtime-command.js.map +1 -0
  55. package/dist/sandbox-command.d.ts +9 -0
  56. package/dist/sandbox-command.js +158 -0
  57. package/dist/sandbox-command.js.map +1 -0
  58. package/dist/supply-chain-command.d.ts +20 -0
  59. package/dist/supply-chain-command.js +131 -0
  60. package/dist/supply-chain-command.js.map +1 -0
  61. package/dist/watch-command.js +7 -5
  62. package/dist/watch-command.js.map +1 -1
  63. package/dist/watch.d.ts +1 -0
  64. package/dist/watch.js +46 -2
  65. package/dist/watch.js.map +1 -1
  66. package/dist/workspace-command.d.ts +13 -0
  67. package/dist/workspace-command.js +267 -0
  68. package/dist/workspace-command.js.map +1 -0
  69. package/package.json +4 -4
@@ -0,0 +1,162 @@
1
+ import { writeFile } from "node:fs/promises";
2
+ import { basename, isAbsolute, relative, resolve, sep } from "node:path";
3
+ import { buildChangeScope, isFixMapArtifact, renderChangeScopeMarkdown, scanRepo } from "@aryam/fixmap-core";
4
+ export const CHANGE_SCOPE_USAGE = `Usage: fixmap change-scope --touch <path> [--touch <path> ...] [--add <path> ...] [options]
5
+
6
+ Expands explicit planned repository surfaces over deterministic import/dependent evidence.
7
+ It does not interpret product requirements, call an API, use an LLM, or require an account.
8
+
9
+ Options:
10
+ --touch <path> Existing file or directory you intend to change (repeatable)
11
+ --add <path> Planned file/directory surface; missing paths remain unresolved (repeatable)
12
+ --direction <value> dependencies, dependents, or both (default both)
13
+ --depth <0-8> Maximum structural traversal depth (default 2)
14
+ --max-nodes <1-2000> Maximum selected plus affected nodes (default 200)
15
+ --workspace <id> Stable workspace identity for this result (default local)
16
+ --repository <id> Stable repository identity (default sanitized checkout name)
17
+ --repo <path> Local checkout to scan (default current directory)
18
+ --no-cache Bypass repository scan caches
19
+ --format <value> markdown (default) or json
20
+ --output <file> Write output to a file instead of stdout
21
+ --help, -h Show this help
22
+ `;
23
+ export async function runChangeScopeCommand(args, io = {}) {
24
+ const stdout = io.stdout ?? ((text) => process.stdout.write(text));
25
+ const stderr = io.stderr ?? ((text) => process.stderr.write(text));
26
+ if (args.includes("--help") || args.includes("-h")) {
27
+ stdout(CHANGE_SCOPE_USAGE);
28
+ return 0;
29
+ }
30
+ let parsed;
31
+ try {
32
+ parsed = parseChangeScopeArgs(args);
33
+ }
34
+ catch (error) {
35
+ stderr(`${error instanceof Error ? error.message : String(error)}\n\n${CHANGE_SCOPE_USAGE}`);
36
+ return 1;
37
+ }
38
+ try {
39
+ const repoRoot = resolve(parsed.repo ?? process.cwd());
40
+ const repo = await scanRepo({
41
+ repoRoot,
42
+ useCache: !parsed.noCache,
43
+ includeHistory: true
44
+ });
45
+ const scanError = repo.diagnostics.find((diagnostic) => diagnostic.severity === "error");
46
+ if (scanError)
47
+ throw new Error(scanError.message);
48
+ if (parsed.output) {
49
+ const outputRelative = relative(repoRoot, resolve(parsed.output));
50
+ const inside = outputRelative && outputRelative !== ".." && !outputRelative.startsWith(`..${sep}`) && !isAbsolute(outputRelative);
51
+ const existing = inside
52
+ ? repo.files.find((file) => file.path === outputRelative.replace(/\\/g, "/"))
53
+ : undefined;
54
+ if (existing && !isFixMapArtifact(existing)) {
55
+ throw new Error(`--output refuses to overwrite repository file ${existing.path}; choose a new path or a prior FixMap scope artifact.`);
56
+ }
57
+ }
58
+ const result = buildChangeScope(repo, {
59
+ workspace: parsed.workspace ?? "local",
60
+ repository: parsed.repository ?? repositoryId(basename(repoRoot)),
61
+ anchors: parsed.anchors,
62
+ asOf: (io.now ?? (() => new Date().toISOString()))(),
63
+ ...(parsed.direction ? { direction: parsed.direction } : {}),
64
+ ...(parsed.depth !== undefined ? { maxDepth: parsed.depth } : {}),
65
+ ...(parsed.maxNodes !== undefined ? { maxNodes: parsed.maxNodes } : {})
66
+ });
67
+ const rendered = parsed.format === "json"
68
+ ? `${JSON.stringify(result, null, 2)}\n`
69
+ : renderChangeScopeMarkdown(result);
70
+ if (parsed.output) {
71
+ await (io.writeOutput ?? ((path, contents) => writeFile(path, contents, "utf8")))(parsed.output, rendered);
72
+ }
73
+ else {
74
+ stdout(rendered);
75
+ }
76
+ return 0;
77
+ }
78
+ catch (error) {
79
+ stderr(`${error instanceof Error ? error.message : String(error)}\n`);
80
+ return 1;
81
+ }
82
+ }
83
+ function parseChangeScopeArgs(args) {
84
+ const anchors = [];
85
+ const singles = new Map();
86
+ let noCache = false;
87
+ for (let index = 0; index < args.length; index += 1) {
88
+ const arg = args[index];
89
+ if (arg === "--no-cache") {
90
+ if (noCache)
91
+ throw new Error("Pass --no-cache only once.");
92
+ noCache = true;
93
+ continue;
94
+ }
95
+ const equals = arg.match(/^(--[a-z-]+)=(.*)$/);
96
+ const flag = equals?.[1] ?? arg;
97
+ const inline = equals?.[2];
98
+ if (!["--touch", "--add", "--direction", "--depth", "--max-nodes", "--workspace", "--repository", "--repo", "--format", "--output"].includes(flag)) {
99
+ throw new Error(`Unknown change-scope option: ${arg}`);
100
+ }
101
+ const value = inline ?? args[++index];
102
+ if (typeof value !== "string" || !value.trim() || (!equals && value.startsWith("--"))) {
103
+ throw new Error(`${flag} requires a non-blank value.`);
104
+ }
105
+ if (flag === "--touch" || flag === "--add") {
106
+ anchors.push({ operation: flag === "--touch" ? "touch" : "add", path: normalizeAnchorPath(value) });
107
+ continue;
108
+ }
109
+ if (singles.has(flag))
110
+ throw new Error(`Pass ${flag} only once.`);
111
+ singles.set(flag, value.trim());
112
+ }
113
+ if (anchors.length === 0)
114
+ throw new Error("change-scope requires at least one --touch or --add anchor.");
115
+ const direction = singles.get("--direction");
116
+ if (direction !== undefined && direction !== "dependencies" && direction !== "dependents" && direction !== "both") {
117
+ throw new Error("--direction must be dependencies, dependents, or both.");
118
+ }
119
+ const depth = boundedInteger(singles.get("--depth"), "--depth", 0, 8);
120
+ const maxNodes = boundedInteger(singles.get("--max-nodes"), "--max-nodes", 1, 2_000);
121
+ const format = singles.get("--format") ?? "markdown";
122
+ if (format !== "markdown" && format !== "json")
123
+ throw new Error("--format must be markdown or json.");
124
+ const workspace = singles.get("--workspace");
125
+ const repository = singles.get("--repository");
126
+ const repo = singles.get("--repo");
127
+ const output = singles.get("--output");
128
+ return {
129
+ anchors,
130
+ ...(direction ? { direction } : {}),
131
+ ...(depth !== undefined ? { depth } : {}),
132
+ ...(maxNodes !== undefined ? { maxNodes } : {}),
133
+ ...(workspace ? { workspace } : {}),
134
+ ...(repository ? { repository } : {}),
135
+ ...(repo ? { repo } : {}),
136
+ noCache,
137
+ format,
138
+ ...(output ? { output } : {})
139
+ };
140
+ }
141
+ function boundedInteger(value, flag, minimum, maximum) {
142
+ if (value === undefined)
143
+ return undefined;
144
+ const parsed = Number(value);
145
+ if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) {
146
+ throw new Error(`${flag} must be an integer from ${minimum} to ${maximum}.`);
147
+ }
148
+ return parsed;
149
+ }
150
+ function repositoryId(value) {
151
+ const normalized = value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^[^a-z0-9]+|[^a-z0-9]+$/g, "");
152
+ return normalized.slice(0, 64) || "repository";
153
+ }
154
+ function normalizeAnchorPath(value) {
155
+ const path = value.trim().replace(/\\/g, "/").replace(/\/+$/, "");
156
+ if (!path || path.length > 1_000 || path.includes("\0") || /^[\/]/.test(path) || /^[A-Za-z]:/.test(path) ||
157
+ path.split("/").some((segment) => !segment || segment === "." || segment === "..")) {
158
+ throw new Error(`Invalid change-scope path: ${value}`);
159
+ }
160
+ return path;
161
+ }
162
+ //# sourceMappingURL=change-scope-command.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"change-scope-command.js","sourceRoot":"","sources":["../src/change-scope-command.ts"],"names":[],"mappings":"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"}
@@ -23,6 +23,7 @@ export type CliOptions = {
23
23
  workingTree: boolean;
24
24
  includeUntracked: boolean;
25
25
  noCache: boolean;
26
+ semanticModelPath?: string | undefined;
26
27
  unknownArgs: string[];
27
28
  invalidValues: string[];
28
29
  };
@@ -44,7 +45,7 @@ export type CliDependencies = {
44
45
  watchRepository?: (input: WatchRepositoryInput) => Promise<WatchUpdate | undefined>;
45
46
  renderWatchUpdate?: (update: WatchUpdate, format: "markdown" | "json") => string;
46
47
  };
47
- 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\" --format agent\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 benchmark --repo . --last 50\n fixmap context --issue \"Fix login\" --budget 10000\n fixmap graph --issue \"Fix login\" --format mermaid\n fixmap watch --report plan.json --repo .\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 benchmark Backtest BM25, FixMap, and Impact Graph on pre-change snapshots\n context Package the highest-value source ranges within a token budget\n graph Export the evidence-backed Impact Graph as Mermaid or JSON\n watch Recheck working-tree drift and impact whenever edits change\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), json, or compact agent\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";
48
+ 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 \"Keep signed-in users active\" --semantic-model C:\\models\\all-MiniLM-L6-v2\n fixmap plan --issue \"Fix login\" --format json --output plan.json\n fixmap plan --issue \"Fix login\" --format agent\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 benchmark --repo . --last 50\n fixmap change-scope --touch src/auth --touch packages/api --add db/migrations\n fixmap editor --issue \"Investigate authentication\" --repo .\n fixmap capability create checkout --touch src/routes/checkout.ts --touch packages/payments\n fixmap capability checkout\n fixmap capabilities\n fixmap context --issue \"Fix login\" --budget 10000\n fixmap graph --issue \"Fix login\" --format mermaid\n fixmap workspace --config .fixmap/workspace.json --seed auth --format json\n fixmap ask --report plan.json --question \"Which tests should I run?\"\n fixmap migrate --input migration.json --format markdown\n fixmap reverse-docs --input reverse-docs.json --format markdown\n fixmap history --repo . --from v0.9.0 --to HEAD\n fixmap supply-chain --input supply-chain.json\n fixmap runtime --input runtime.json\n fixmap sandbox --request sandbox.json --execute-declared-command\n fixmap watch --report plan.json --repo .\n fixmap annotate src/auth/token.ts --note \"Do not refactor; external contract\"\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 benchmark Backtest BM25, FixMap, and Impact Graph on pre-change snapshots\n change-scope Preview: Expand explicit planned paths into bounded structural consequences\n editor Preview: Serve a local read-only NDJSON editor session\n capability Preview: Create, update, remove, or show a persistent product capability\n capabilities Preview: List persistent product capabilities declared by the repository\n context Package the highest-value source ranges within a token budget\n graph Export the evidence-backed Impact Graph as Mermaid or JSON\n workspace Preview: Map package dependencies and impact across local repositories\n ask Preview: Answer structural questions from a saved report with citations\n migrate Preview: Build a dependency-ordered, review-only migration plan\n reverse-docs Preview: Draft review-only documentation from exact structural evidence\n history Preview: Compare architecture at two committed Git refs without checkout\n supply-chain Preview: Import normalized external scanner and SBOM evidence\n runtime Preview: Map redaction-reviewed runtime evidence to exact files\n sandbox Preview: Run one explicitly consented command in an isolated container\n watch Recheck working-tree drift and impact whenever edits change\n annotate Attach reviewable tribal knowledge to files, symbols, services, or contracts\n features List every FixMap capability and its command\n setup Preview workflows, or explicitly install /fixmap 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 For long text, use this flag or stdin; inline argv can exceed Windows' command-line limit\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 --semantic-model <dir> Use an existing local embedding model; never downloads or uploads source\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), json, or compact agent\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";
48
49
  export declare function runCli(args: string[], dependencies?: CliDependencies): Promise<number>;
49
50
  export declare function expandIssueShorthand(args: string[]): string[];
50
51
  export declare const MAX_CONTEXT_FILE_LIMIT = 20;
@@ -3,10 +3,11 @@ import { realpath, stat, writeFile } from "node:fs/promises";
3
3
  import { homedir } from "node:os";
4
4
  import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
5
5
  import { fileURLToPath } from "node:url";
6
- import { compareReports, explainFile, quoteCliValue as formatCliValue, renderComparisonMarkdown, renderExplanationMarkdown, renderAgentReport, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo, stripByteOrderMark, validateFixMapReport } from "@aryam/fixmap-core";
6
+ import { compareReports, explainFile, quoteCliValue as formatCliValue, renderComparisonMarkdown, renderExplanationMarkdown, renderAgentReport, renderJsonReport, renderVerifyMarkdown, resolveExclusions, verifyPlan, renderMarkdownReport, scanRepo, validateFixMapReport } from "@aryam/fixmap-core";
7
7
  import { runDoctorChecks, renderDoctorReport } from "./doctor.js";
8
8
  import { installAgentCommands, renderFeatureCatalog } from "./agent-setup.js";
9
9
  import { clarifyMissingPath } from "./explain-path.js";
10
+ import { decodeInputText, describeInputReadError, readDecodedTextFile } from "./decode-input.js";
10
11
  import { buildReportForRepository, isSafeGitRefName, parseGitHubIssueSource, progressRequested, tryParseGitHubIssueSource } from "./repository-source.js";
11
12
  export const USAGE = `FixMap maps an issue, prompt, or diff to context files, test routes, and review risks.
12
13
 
@@ -23,6 +24,7 @@ Usage:
23
24
  fixmap plan --diff main...HEAD
24
25
  fixmap plan --working-tree --include-untracked --limit 12 --exclude "docs/**"
25
26
  fixmap plan --no-cache --issue "Fix login" --repo .
27
+ fixmap plan --issue "Keep signed-in users active" --semantic-model C:\\models\\all-MiniLM-L6-v2
26
28
  fixmap plan --issue "Fix login" --format json --output plan.json
27
29
  fixmap plan --issue "Fix login" --format agent
28
30
  fixmap plan --issue "Fix login in auth middleware" --compare plan.json
@@ -33,9 +35,23 @@ Usage:
33
35
  fixmap doctor --format json
34
36
  fixmap validate plan.json
35
37
  fixmap benchmark --repo . --last 50
38
+ fixmap change-scope --touch src/auth --touch packages/api --add db/migrations
39
+ fixmap editor --issue "Investigate authentication" --repo .
40
+ fixmap capability create checkout --touch src/routes/checkout.ts --touch packages/payments
41
+ fixmap capability checkout
42
+ fixmap capabilities
36
43
  fixmap context --issue "Fix login" --budget 10000
37
44
  fixmap graph --issue "Fix login" --format mermaid
45
+ fixmap workspace --config .fixmap/workspace.json --seed auth --format json
46
+ fixmap ask --report plan.json --question "Which tests should I run?"
47
+ fixmap migrate --input migration.json --format markdown
48
+ fixmap reverse-docs --input reverse-docs.json --format markdown
49
+ fixmap history --repo . --from v0.9.0 --to HEAD
50
+ fixmap supply-chain --input supply-chain.json
51
+ fixmap runtime --input runtime.json
52
+ fixmap sandbox --request sandbox.json --execute-declared-command
38
53
  fixmap watch --report plan.json --repo .
54
+ fixmap annotate src/auth/token.ts --note "Do not refactor; external contract"
39
55
  fixmap features
40
56
  fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>]
41
57
  fixmap mcp [--repo <path>]
@@ -46,22 +62,37 @@ Commands:
46
62
  doctor Check the FixMap install for stale global or npx shadows
47
63
  validate Validate a saved FixMap JSON report
48
64
  benchmark Backtest BM25, FixMap, and Impact Graph on pre-change snapshots
65
+ change-scope Preview: Expand explicit planned paths into bounded structural consequences
66
+ editor Preview: Serve a local read-only NDJSON editor session
67
+ capability Preview: Create, update, remove, or show a persistent product capability
68
+ capabilities Preview: List persistent product capabilities declared by the repository
49
69
  context Package the highest-value source ranges within a token budget
50
70
  graph Export the evidence-backed Impact Graph as Mermaid or JSON
71
+ workspace Preview: Map package dependencies and impact across local repositories
72
+ ask Preview: Answer structural questions from a saved report with citations
73
+ migrate Preview: Build a dependency-ordered, review-only migration plan
74
+ reverse-docs Preview: Draft review-only documentation from exact structural evidence
75
+ history Preview: Compare architecture at two committed Git refs without checkout
76
+ supply-chain Preview: Import normalized external scanner and SBOM evidence
77
+ runtime Preview: Map redaction-reviewed runtime evidence to exact files
78
+ sandbox Preview: Run one explicitly consented command in an isolated container
51
79
  watch Recheck working-tree drift and impact whenever edits change
80
+ annotate Attach reviewable tribal knowledge to files, symbols, services, or contracts
52
81
  features List every FixMap capability and its command
53
- setup Install a discoverable /fixmap command for coding agents
82
+ setup Preview workflows, or explicitly install /fixmap for coding agents
54
83
  mcp Run FixMap as an MCP server over stdio for AI coding agents
55
84
 
56
85
  Options:
57
86
  --issue <text|url> Task text, or a public GitHub issue or pull request URL
58
87
  --issue-file <file> Read task text from a UTF-8 or UTF-16 file (use - for stdin)
88
+ For long text, use this flag or stdin; inline argv can exceed Windows' command-line limit
59
89
  --diff <spec> Git diff spec, such as main...HEAD (the repository scan can still rank untracked candidates)
60
90
  --base <ref> Base ref for diffing when --diff is not given
61
91
  --head <ref> Head ref for diffing (defaults to HEAD)
62
92
  --working-tree Map staged and unstaged changes against HEAD
63
93
  --include-untracked With --working-tree, also include untracked files
64
94
  --no-cache Bypass the exact git-state repository scan cache
95
+ --semantic-model <dir> Use an existing local embedding model; never downloads or uploads source
65
96
  --repo <source> Local path or public GitHub HTTPS URL (defaults to current directory)
66
97
  --ref <branch|tag> Branch or tag to scan when --repo is a remote GitHub URL
67
98
  --limit <n> Maximum context files to report (default 8, max 20)
@@ -84,7 +115,7 @@ Set FIXMAP_CACHE_DIR to move the OS scan cache, and FIXMAP_VERBOSE_USAGE=1 to in
84
115
  const DOCTOR_USAGE = `Usage: fixmap doctor [--format markdown|json]\n\nChecks the running FixMap binary, PATH/global shadows, and known install blind spots.\n`;
85
116
  const MCP_USAGE = `Usage: fixmap mcp [--repo <path>]\n\nRuns the FixMap MCP server over stdio. --repo sets the default local repository for tool calls that omit repo.\n`;
86
117
  const FEATURES_USAGE = `Usage: fixmap features [--format markdown|json]\n\nLists every FixMap capability and the command that exposes it.\n`;
87
- const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nInstalls a /fixmap command that lists and runs FixMap workflows.\n`;
118
+ const SETUP_USAGE = `Usage: fixmap setup [--agent claude|cursor|copilot|agents|all] [--repo <path>] [--force]\n\nWith no arguments, previews every workflow without writing files. Pass --agent explicitly to install a /fixmap command.\n`;
88
119
  const VALIDATE_USAGE = `Usage: fixmap validate <report.json> [--format markdown|json]\n\nChecks a saved report against FixMap's structural compatibility contract.\n`;
89
120
  const BENCHMARK_USAGE = `Usage: fixmap benchmark [--repo <local-path>] [--last <1-100>] [--format markdown|json] [--output <file>]\n\nBacktests BM25, FixMap, and Impact Graph against historical parent snapshots without executing repository code.\n`;
90
121
  export async function runCli(args, dependencies = {}) {
@@ -141,6 +172,10 @@ export async function runCli(args, dependencies = {}) {
141
172
  await runMcpServer(defaultRepo);
142
173
  return 0;
143
174
  }
175
+ if (args[0] === "annotate") {
176
+ const module = await import("./annotation-command.js");
177
+ return module.runAnnotateCommand(args.slice(1), { stdout, stderr });
178
+ }
144
179
  if (args[0] === "features") {
145
180
  const featureArgs = args.slice(1);
146
181
  if (featureArgs[0] === "--help" || featureArgs[0] === "-h") {
@@ -169,6 +204,10 @@ export async function runCli(args, dependencies = {}) {
169
204
  stdout(SETUP_USAGE);
170
205
  return 0;
171
206
  }
207
+ if (args.length === 1) {
208
+ stdout(`${renderFeatureCatalog("markdown")}Preview only: no files were changed. Install explicitly with fixmap setup --agent <claude|cursor|copilot|agents|all> [--repo <path>].\n`);
209
+ return 0;
210
+ }
172
211
  let repoRoot = process.cwd();
173
212
  let targets = ["claude", "cursor", "copilot", "agents"];
174
213
  let force = false;
@@ -241,6 +280,14 @@ export async function runCli(args, dependencies = {}) {
241
280
  stderr(`Unknown setup option: ${arg}\n\n${SETUP_USAGE}`);
242
281
  return 1;
243
282
  }
283
+ if (!agentSeen) {
284
+ if (force) {
285
+ stderr(`--force requires an explicit --agent target.\n\n${SETUP_USAGE}`);
286
+ return 1;
287
+ }
288
+ stdout(`${renderFeatureCatalog("markdown")}Preview only: no files were changed. Install explicitly with fixmap setup --agent <claude|cursor|copilot|agents|all> [--repo <path>].\n`);
289
+ return 0;
290
+ }
244
291
  try {
245
292
  const installed = await installAgentCommands({ repoRoot, targets, force });
246
293
  stdout(`${installed.map((entry) => `${entry.status}: ${entry.path}`).join("\n")}\n\nType /fixmap in a supported agent to open the full FixMap feature menu.\n`);
@@ -301,7 +348,7 @@ export async function runCli(args, dependencies = {}) {
301
348
  return 1;
302
349
  }
303
350
  try {
304
- const parsed = JSON.parse(stripByteOrderMark(readFileSync(reportPath, "utf8")));
351
+ const parsed = JSON.parse(readDecodedTextFile(reportPath));
305
352
  const result = validateFixMapReport(parsed, `"${reportPath}"`);
306
353
  if (!result.success) {
307
354
  stderr(`${result.message}\n`);
@@ -319,7 +366,7 @@ export async function runCli(args, dependencies = {}) {
319
366
  return 0;
320
367
  }
321
368
  catch (error) {
322
- stderr(`Could not validate "${reportPath}": ${error instanceof Error ? error.message : String(error)}\n`);
369
+ stderr(`Could not validate "${reportPath}": ${describeInputReadError(reportPath, error)}\n`);
323
370
  return 1;
324
371
  }
325
372
  }
@@ -410,6 +457,34 @@ export async function runCli(args, dependencies = {}) {
410
457
  ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
411
458
  });
412
459
  }
460
+ if (args[0] === "change-scope") {
461
+ const { runChangeScopeCommand } = await import("./change-scope-command.js");
462
+ return runChangeScopeCommand(args.slice(1), {
463
+ stdout,
464
+ stderr,
465
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
466
+ });
467
+ }
468
+ if (args[0] === "editor") {
469
+ const { runEditorCommand } = await import("./editor-command.js");
470
+ return runEditorCommand(args.slice(1), { stdout, stderr });
471
+ }
472
+ if (args[0] === "capability") {
473
+ const { runCapabilityCommand } = await import("./capability-command.js");
474
+ return runCapabilityCommand(args.slice(1), {
475
+ stdout,
476
+ stderr,
477
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
478
+ });
479
+ }
480
+ if (args[0] === "capabilities") {
481
+ const { runCapabilitiesCommand } = await import("./capability-command.js");
482
+ return runCapabilitiesCommand(args.slice(1), {
483
+ stdout,
484
+ stderr,
485
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
486
+ });
487
+ }
413
488
  if (args[0] === "graph") {
414
489
  const { runGraphCommand } = await import("./analysis-commands.js");
415
490
  return runGraphCommand(args.slice(1), {
@@ -418,6 +493,70 @@ export async function runCli(args, dependencies = {}) {
418
493
  ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
419
494
  });
420
495
  }
496
+ if (args[0] === "workspace") {
497
+ const { runWorkspaceCommand } = await import("./workspace-command.js");
498
+ return runWorkspaceCommand(args.slice(1), {
499
+ stdout,
500
+ stderr,
501
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
502
+ });
503
+ }
504
+ if (args[0] === "ask") {
505
+ const { runAskCommand } = await import("./ask-command.js");
506
+ return runAskCommand(args.slice(1), {
507
+ stdout,
508
+ stderr,
509
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
510
+ });
511
+ }
512
+ if (args[0] === "migrate") {
513
+ const { runMigrationCommand } = await import("./migration-command.js");
514
+ return runMigrationCommand(args.slice(1), {
515
+ stdout,
516
+ stderr,
517
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
518
+ });
519
+ }
520
+ if (args[0] === "reverse-docs") {
521
+ const { runReverseDocsCommand } = await import("./reverse-docs-command.js");
522
+ return runReverseDocsCommand(args.slice(1), {
523
+ stdout,
524
+ stderr,
525
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
526
+ });
527
+ }
528
+ if (args[0] === "history") {
529
+ const { runHistoryCommand } = await import("./history-command.js");
530
+ return runHistoryCommand(args.slice(1), {
531
+ stdout,
532
+ stderr,
533
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
534
+ });
535
+ }
536
+ if (args[0] === "supply-chain") {
537
+ const { runSupplyChainCommand } = await import("./supply-chain-command.js");
538
+ return runSupplyChainCommand(args.slice(1), {
539
+ stdout,
540
+ stderr,
541
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
542
+ });
543
+ }
544
+ if (args[0] === "runtime") {
545
+ const { runRuntimeCommand } = await import("./runtime-command.js");
546
+ return runRuntimeCommand(args.slice(1), {
547
+ stdout,
548
+ stderr,
549
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
550
+ });
551
+ }
552
+ if (args[0] === "sandbox") {
553
+ const { runSandboxCommand } = await import("./sandbox-command.js");
554
+ return runSandboxCommand(args.slice(1), {
555
+ stdout,
556
+ stderr,
557
+ ...(dependencies.writeReport ? { writeOutput: dependencies.writeReport } : {})
558
+ });
559
+ }
421
560
  if (args[0] === "watch") {
422
561
  const { runWatchCommand } = await import("./watch-command.js");
423
562
  return runWatchCommand(args.slice(1), {
@@ -478,7 +617,7 @@ export async function runCli(args, dependencies = {}) {
478
617
  return 1;
479
618
  }
480
619
  if (options.command === "verify") {
481
- const planOnly = [options.issueText && "--issue", options.issueFile && "--issue-file", options.comparePath && "--compare", options.limit !== undefined && "--limit", options.exclude.length > 0 && "--exclude", options.explainPath && "--explain"].filter(Boolean);
620
+ const planOnly = [options.issueText && "--issue", options.issueFile && "--issue-file", options.comparePath && "--compare", options.limit !== undefined && "--limit", options.exclude.length > 0 && "--exclude", options.explainPath && "--explain", options.semanticModelPath && "--semantic-model"].filter(Boolean);
482
621
  if (planOnly.length > 0) {
483
622
  stderr(`verify does not accept plan-only option(s): ${planOnly.join(", ")}.\n`);
484
623
  return 1;
@@ -519,7 +658,7 @@ export async function runCli(args, dependencies = {}) {
519
658
  // property of the repository alone. Requiring a task signal for both made the second
520
659
  // unaskable, which is the one you reach for when a file is missing from a report.
521
660
  if (!options.issueText && !options.diffSpec && !options.baseRef && !options.workingTree && !options.explainPath) {
522
- stderr("Provide --issue, --diff, --base/--head, or --working-tree so FixMap has a task signal.\n");
661
+ stderr("Provide --issue, --diff, --base/--head, or --working-tree so FixMap has a task signal. Pipe task text directly, or use --issue-file - for explicit stdin.\n");
523
662
  return 1;
524
663
  }
525
664
  if (options.includeUntracked && !options.workingTree) {
@@ -630,7 +769,8 @@ export async function runCli(args, dependencies = {}) {
630
769
  useCache: !options.noCache,
631
770
  limit: options.limit,
632
771
  exclude: options.exclude,
633
- internalExclude: localPlanArtifactExclusions(options)
772
+ internalExclude: localPlanArtifactExclusions(options),
773
+ semanticModelPath: options.semanticModelPath
634
774
  });
635
775
  }
636
776
  catch (error) {
@@ -673,10 +813,10 @@ export async function runCli(args, dependencies = {}) {
673
813
  let previous;
674
814
  let previousText;
675
815
  try {
676
- previousText = stripByteOrderMark(readFileSync(options.comparePath, "utf8"));
816
+ previousText = readDecodedTextFile(options.comparePath);
677
817
  }
678
818
  catch (error) {
679
- stderr(`Could not read comparison file "${options.comparePath}": ${error instanceof Error ? error.message : String(error)}\n` +
819
+ stderr(`Could not read comparison file "${options.comparePath}": ${describeInputReadError(options.comparePath, error)}\n` +
680
820
  "Save one first with: fixmap plan --issue \"...\" --format json --output plan.json\n");
681
821
  return 1;
682
822
  }
@@ -858,6 +998,7 @@ const SINGLE_VALUE_FLAGS = new Set([
858
998
  "--head",
859
999
  "--ref",
860
1000
  "--repo",
1001
+ "--semantic-model",
861
1002
  "--format",
862
1003
  "--report",
863
1004
  "--explain",
@@ -904,6 +1045,7 @@ export function parseArgs(args) {
904
1045
  let workingTree = false;
905
1046
  let includeUntracked = false;
906
1047
  let noCache = false;
1048
+ let semanticModelPath;
907
1049
  const exclude = [];
908
1050
  const unknownArgs = [];
909
1051
  const invalidValues = [];
@@ -993,6 +1135,13 @@ export function parseArgs(args) {
993
1135
  else
994
1136
  invalidValues.push("--repo requires a local path or public GitHub repository URL");
995
1137
  }
1138
+ else if (arg === "--semantic-model") {
1139
+ consumeValue();
1140
+ if (value?.trim())
1141
+ semanticModelPath = expandHomePath(value.trim());
1142
+ else
1143
+ invalidValues.push("--semantic-model requires a local model directory");
1144
+ }
996
1145
  else if (arg === "--format") {
997
1146
  consumeValue();
998
1147
  const normalized = value?.trim().toLowerCase();
@@ -1108,6 +1257,7 @@ export function parseArgs(args) {
1108
1257
  workingTree,
1109
1258
  includeUntracked,
1110
1259
  noCache,
1260
+ semanticModelPath,
1111
1261
  unknownArgs,
1112
1262
  invalidValues
1113
1263
  };
@@ -1221,9 +1371,9 @@ function loadIssueText(options, read) {
1221
1371
  }
1222
1372
  catch (error) {
1223
1373
  throw new Error(`Could not read issue text from ${path === "-" ? "stdin" : `\"${path}\"`}: ` +
1224
- `${error instanceof Error ? error.message : String(error)}`);
1374
+ `${path === "-" ? (error instanceof Error ? error.message : String(error)) : describeInputReadError(path, error)}`);
1225
1375
  }
1226
- const text = decodeIssueText(raw);
1376
+ const text = decodeInputText(raw);
1227
1377
  if (!text.trim()) {
1228
1378
  throw new Error(`Issue text from ${path === "-" ? "stdin" : `\"${path}\"`} was empty.`);
1229
1379
  }
@@ -1232,38 +1382,6 @@ function loadIssueText(options, read) {
1232
1382
  function defaultReadIssueFile(path) {
1233
1383
  return readFileSync(path);
1234
1384
  }
1235
- /** Decode the encodings commonly produced by editors on every supported platform. */
1236
- function decodeIssueText(raw) {
1237
- if (typeof raw === "string")
1238
- return raw.replace(/^\uFEFF/, "");
1239
- if (raw.length >= 2 && raw[0] === 0xff && raw[1] === 0xfe) {
1240
- return raw.subarray(2).toString("utf16le").replace(/^\uFEFF/, "");
1241
- }
1242
- if (raw.length >= 2 && raw[0] === 0xfe && raw[1] === 0xff) {
1243
- const swapped = Buffer.allocUnsafe(raw.length - 2);
1244
- for (let index = 2; index + 1 < raw.length; index += 2) {
1245
- swapped[index - 2] = raw[index + 1];
1246
- swapped[index - 1] = raw[index];
1247
- }
1248
- return swapped.toString("utf16le").replace(/^\uFEFF/, "");
1249
- }
1250
- if (raw.length >= 4 && raw.length % 2 === 0) {
1251
- let evenNuls = 0;
1252
- let oddNuls = 0;
1253
- for (let index = 0; index < raw.length; index += 2) {
1254
- if (raw[index] === 0)
1255
- evenNuls += 1;
1256
- if (raw[index + 1] === 0)
1257
- oddNuls += 1;
1258
- }
1259
- const pairs = raw.length / 2;
1260
- if (oddNuls / pairs >= 0.3 && evenNuls / pairs < 0.1)
1261
- return raw.toString("utf16le");
1262
- if (evenNuls / pairs >= 0.3 && oddNuls / pairs < 0.1)
1263
- return Buffer.from(raw).swap16().toString("utf16le");
1264
- }
1265
- return raw.toString("utf8").replace(/^\uFEFF/, "");
1266
- }
1267
1385
  function quoteCliValue(value) {
1268
1386
  return formatCliValue(value, process.platform === "win32" ? "powershell" : "posix");
1269
1387
  }
@@ -1319,10 +1437,10 @@ async function runVerify(options, io) {
1319
1437
  }
1320
1438
  let reportText;
1321
1439
  try {
1322
- reportText = stripByteOrderMark(readFileSync(options.reportPath, "utf8"));
1440
+ reportText = readDecodedTextFile(options.reportPath);
1323
1441
  }
1324
1442
  catch (error) {
1325
- io.stderr(`Could not read "${options.reportPath}": ${error instanceof Error ? error.message : String(error)}\n` +
1443
+ io.stderr(`Could not read "${options.reportPath}": ${describeInputReadError(options.reportPath, error)}\n` +
1326
1444
  "Generate one with: fixmap plan --issue \"...\" --format json --output plan.json\n");
1327
1445
  return 1;
1328
1446
  }
@@ -1412,7 +1530,7 @@ function describeUnsupportedTaskUrl(issueText) {
1412
1530
  const value = issueText.trim();
1413
1531
  // `tryParse`, not `parse` — this is a boolean probe, and the throwing variant printed a
1414
1532
  // Node stack here for URLs it could not classify instead of this one-line message.
1415
- if (!/^https?:\/\/\S+$/i.test(value) || tryParseGitHubIssueSource(value))
1533
+ if (!/^[a-z][a-z0-9+.-]*:\/\/\S+$/i.test(value) || tryParseGitHubIssueSource(value))
1416
1534
  return undefined;
1417
1535
  return "Unsupported task URL. Use a public GitHub issue or pull request URL such as " +
1418
1536
  "https://github.com/owner/repository/issues/123 or /pull/123, or pass descriptive task text. " +