scoutline 0.2.0 → 0.6.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 (110) hide show
  1. package/README.md +240 -18
  2. package/dist/capabilities/diagnostics.d.ts +70 -32
  3. package/dist/capabilities/diagnostics.d.ts.map +1 -1
  4. package/dist/capabilities/diagnostics.js +97 -46
  5. package/dist/capabilities/diagnostics.js.map +1 -1
  6. package/dist/capabilities/reader.d.ts +227 -0
  7. package/dist/capabilities/reader.d.ts.map +1 -0
  8. package/dist/capabilities/reader.js +100 -0
  9. package/dist/capabilities/reader.js.map +1 -0
  10. package/dist/capabilities/repository.d.ts +221 -0
  11. package/dist/capabilities/repository.d.ts.map +1 -0
  12. package/dist/capabilities/repository.js +172 -0
  13. package/dist/capabilities/repository.js.map +1 -0
  14. package/dist/commands/cache.d.ts +106 -0
  15. package/dist/commands/cache.d.ts.map +1 -0
  16. package/dist/commands/cache.js +203 -0
  17. package/dist/commands/cache.js.map +1 -0
  18. package/dist/commands/doctor.d.ts +17 -6
  19. package/dist/commands/doctor.d.ts.map +1 -1
  20. package/dist/commands/doctor.js +42 -17
  21. package/dist/commands/doctor.js.map +1 -1
  22. package/dist/commands/read.d.ts +74 -14
  23. package/dist/commands/read.d.ts.map +1 -1
  24. package/dist/commands/read.js +257 -117
  25. package/dist/commands/read.js.map +1 -1
  26. package/dist/commands/repo.d.ts +53 -7
  27. package/dist/commands/repo.d.ts.map +1 -1
  28. package/dist/commands/repo.js +104 -123
  29. package/dist/commands/repo.js.map +1 -1
  30. package/dist/commands/repository-explorer.d.ts +147 -0
  31. package/dist/commands/repository-explorer.d.ts.map +1 -0
  32. package/dist/commands/repository-explorer.js +550 -0
  33. package/dist/commands/repository-explorer.js.map +1 -0
  34. package/dist/index.d.ts +20 -0
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +209 -34
  37. package/dist/index.js.map +1 -1
  38. package/dist/lib/cache.d.ts +123 -18
  39. package/dist/lib/cache.d.ts.map +1 -1
  40. package/dist/lib/cache.js +324 -49
  41. package/dist/lib/cache.js.map +1 -1
  42. package/dist/lib/errors.d.ts +24 -1
  43. package/dist/lib/errors.d.ts.map +1 -1
  44. package/dist/lib/errors.js +33 -2
  45. package/dist/lib/errors.js.map +1 -1
  46. package/dist/lib/execution.d.ts +119 -5
  47. package/dist/lib/execution.d.ts.map +1 -1
  48. package/dist/lib/execution.js +216 -10
  49. package/dist/lib/execution.js.map +1 -1
  50. package/dist/lib/index.d.ts +1 -1
  51. package/dist/lib/index.d.ts.map +1 -1
  52. package/dist/lib/index.js +1 -1
  53. package/dist/lib/index.js.map +1 -1
  54. package/dist/lib/mcp-client.d.ts +29 -5
  55. package/dist/lib/mcp-client.d.ts.map +1 -1
  56. package/dist/lib/mcp-client.js +88 -88
  57. package/dist/lib/mcp-client.js.map +1 -1
  58. package/dist/lib/tool-cache.d.ts +86 -0
  59. package/dist/lib/tool-cache.d.ts.map +1 -0
  60. package/dist/lib/tool-cache.js +123 -0
  61. package/dist/lib/tool-cache.js.map +1 -0
  62. package/dist/providers/minimax/adapter.d.ts +6 -4
  63. package/dist/providers/minimax/adapter.d.ts.map +1 -1
  64. package/dist/providers/minimax/adapter.js +64 -57
  65. package/dist/providers/minimax/adapter.js.map +1 -1
  66. package/dist/providers/minimax/coding-plan-client.d.ts +60 -0
  67. package/dist/providers/minimax/coding-plan-client.d.ts.map +1 -0
  68. package/dist/providers/minimax/coding-plan-client.js +204 -0
  69. package/dist/providers/minimax/coding-plan-client.js.map +1 -0
  70. package/dist/providers/minimax/media.d.ts +60 -6
  71. package/dist/providers/minimax/media.d.ts.map +1 -1
  72. package/dist/providers/minimax/media.js +147 -7
  73. package/dist/providers/minimax/media.js.map +1 -1
  74. package/dist/providers/minimax/quota-client.d.ts +13 -6
  75. package/dist/providers/minimax/quota-client.d.ts.map +1 -1
  76. package/dist/providers/minimax/quota-client.js +5 -0
  77. package/dist/providers/minimax/quota-client.js.map +1 -1
  78. package/dist/providers/minimax/vision-attestations.d.ts +23 -0
  79. package/dist/providers/minimax/vision-attestations.d.ts.map +1 -1
  80. package/dist/providers/minimax/vision-attestations.js +35 -10
  81. package/dist/providers/minimax/vision-attestations.js.map +1 -1
  82. package/dist/providers/minimax/vision-conformance.d.ts +8 -6
  83. package/dist/providers/minimax/vision-conformance.d.ts.map +1 -1
  84. package/dist/providers/minimax/vision-conformance.js +8 -6
  85. package/dist/providers/minimax/vision-conformance.js.map +1 -1
  86. package/dist/providers/minimax/vision-revisions.d.ts +8 -1
  87. package/dist/providers/minimax/vision-revisions.d.ts.map +1 -1
  88. package/dist/providers/minimax/vision-revisions.js +13 -6
  89. package/dist/providers/minimax/vision-revisions.js.map +1 -1
  90. package/dist/providers/selection.d.ts +3 -3
  91. package/dist/providers/selection.js +3 -3
  92. package/dist/providers/types.d.ts +66 -32
  93. package/dist/providers/types.d.ts.map +1 -1
  94. package/dist/providers/types.js.map +1 -1
  95. package/dist/providers/zai/adapter.d.ts.map +1 -1
  96. package/dist/providers/zai/adapter.js +71 -5
  97. package/dist/providers/zai/adapter.js.map +1 -1
  98. package/dist/providers/zai/encoded-error.d.ts +90 -0
  99. package/dist/providers/zai/encoded-error.d.ts.map +1 -0
  100. package/dist/providers/zai/encoded-error.js +169 -0
  101. package/dist/providers/zai/encoded-error.js.map +1 -0
  102. package/dist/providers/zai/reader.d.ts +82 -0
  103. package/dist/providers/zai/reader.d.ts.map +1 -0
  104. package/dist/providers/zai/reader.js +490 -0
  105. package/dist/providers/zai/reader.js.map +1 -0
  106. package/dist/providers/zai/repository.d.ts +76 -0
  107. package/dist/providers/zai/repository.d.ts.map +1 -0
  108. package/dist/providers/zai/repository.js +715 -0
  109. package/dist/providers/zai/repository.js.map +1 -0
  110. package/package.json +3 -3
@@ -1,11 +1,30 @@
1
1
  /**
2
- * Repo commands for GitHub repository exploration (ZRead)
2
+ * Repo commands thin handlers over the Repository Explorer (P6-07,
3
+ * DESIGN.md §18, §11, PRD FR-080–FR-088).
3
4
  *
4
- * P1-05: each command returns a CommandResult instead of writing
5
- * directly to stdout/stderr. Validation errors are thrown and converted
6
- * by invokeCommand.
5
+ * Each handler applies parse-level defaults/validation, builds the
6
+ * Explorer request, and returns the normalized Explorer result as
7
+ * base data. The handlers own NO Provider client, raw MCP name,
8
+ * ZRead parser, traversal transport, cache policy, retry, or close.
9
+ *
10
+ * Provider selection, capability support, configuration, Adapter
11
+ * construction, and adapter.repository agreement live in
12
+ * `src/index.ts`. The Explorer receives a `RepositoryCapability`
13
+ * plus shared `ExecutionDependencies` and owns path canonicalization,
14
+ * BFS, maxChars projection, and result projection.
15
+ *
16
+ * Handler interface (P6-07A): mirrors the shared Search command
17
+ * pattern. `deps: RepoHandlerDependencies` is REQUIRED — production
18
+ * and direct tests cross the same compile-checked Interface. An
19
+ * optional trailing `CommandContext` follows when a caller wants to
20
+ * surface per-invocation context; the handlers do not currently read
21
+ * it. A `CommandContext` is NOT a valid substitute for `deps`: a
22
+ * direct caller who omits `deps` fails loudly with a TypeError
23
+ * before reaching the Explorer rather than silently degrading.
7
24
  */
8
25
  import type { CommandContext, CommandResult } from "../command-invocation.js";
26
+ import type { RepositoryCapability } from "../capabilities/repository.js";
27
+ import type { ExecutionDependencies } from "../lib/execution.js";
9
28
  export interface RepoSearchOptions {
10
29
  language?: "en" | "zh";
11
30
  maxChars?: number;
@@ -20,8 +39,35 @@ export interface RepoReadOptions {
20
39
  maxChars?: number;
21
40
  noCache?: boolean;
22
41
  }
23
- export declare function repoSearch(repo: string, query: string, options?: RepoSearchOptions, _context?: CommandContext): Promise<CommandResult>;
24
- export declare function repoTree(repo: string, options?: RepoTreeOptions, _context?: CommandContext): Promise<CommandResult>;
25
- export declare function repoRead(repo: string, path: string, options?: RepoReadOptions, _context?: CommandContext): Promise<CommandResult>;
42
+ /**
43
+ * Dependencies injected by `src/index.ts` after Provider selection,
44
+ * capability support check, configuration check, Adapter
45
+ * construction, and adapter.repository agreement. The handlers
46
+ * never resolve a Provider descriptor themselves. Required — a
47
+ * caller that omits `deps` is malformed and fails loudly.
48
+ */
49
+ export interface RepoHandlerDependencies {
50
+ readonly capability: RepositoryCapability;
51
+ readonly execution: ExecutionDependencies;
52
+ }
53
+ /**
54
+ * Repository Search. Validates parse-level request shape, delegates
55
+ * to the Explorer with the injected Repository Capability, and
56
+ * returns the normalized Search result as base data.
57
+ */
58
+ export declare function repoSearch(repo: string, query: string, options: RepoSearchOptions, deps: RepoHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
59
+ /**
60
+ * Repository Tree. Validates parse-level request shape (including
61
+ * depth), delegates to the Explorer's BFS traversal, and returns
62
+ * the normalized Tree result as base data. Tree is never
63
+ * character-limited; `maxChars` is intentionally not accepted.
64
+ */
65
+ export declare function repoTree(repo: string, options: RepoTreeOptions, deps: RepoHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
66
+ /**
67
+ * Repository File read. Validates parse-level request shape,
68
+ * delegates to the Explorer with the injected Repository Capability,
69
+ * and returns the normalized File result as base data.
70
+ */
71
+ export declare function repoRead(repo: string, path: string, options: RepoReadOptions, deps: RepoHandlerDependencies, _context?: CommandContext): Promise<CommandResult>;
26
72
  export declare const REPO_HELP: string;
27
73
  //# sourceMappingURL=repo.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAW9E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAiFD,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,iBAAsB,EAC/B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAcxB;AAED,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CA+BxB;AAED,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,eAAoB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAGD,eAAO,MAAM,SAAS,QA2Cd,CAAC"}
1
+ {"version":3,"file":"repo.d.ts","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAC1E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AA2BjE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;CAC3C;AAMD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,iBAAiB,EAC1B,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAgBxB;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,EACxB,IAAI,EAAE,uBAAuB,EAC7B,QAAQ,CAAC,EAAE,cAAc,GACxB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAcD,eAAO,MAAM,SAAS,QAkEd,CAAC"}
@@ -1,97 +1,67 @@
1
1
  /**
2
- * Repo commands for GitHub repository exploration (ZRead)
2
+ * Repo commands thin handlers over the Repository Explorer (P6-07,
3
+ * DESIGN.md §18, §11, PRD FR-080–FR-088).
3
4
  *
4
- * P1-05: each command returns a CommandResult instead of writing
5
- * directly to stdout/stderr. Validation errors are thrown and converted
6
- * by invokeCommand.
5
+ * Each handler applies parse-level defaults/validation, builds the
6
+ * Explorer request, and returns the normalized Explorer result as
7
+ * base data. The handlers own NO Provider client, raw MCP name,
8
+ * ZRead parser, traversal transport, cache policy, retry, or close.
9
+ *
10
+ * Provider selection, capability support, configuration, Adapter
11
+ * construction, and adapter.repository agreement live in
12
+ * `src/index.ts`. The Explorer receives a `RepositoryCapability`
13
+ * plus shared `ExecutionDependencies` and owns path canonicalization,
14
+ * BFS, maxChars projection, and result projection.
15
+ *
16
+ * Handler interface (P6-07A): mirrors the shared Search command
17
+ * pattern. `deps: RepoHandlerDependencies` is REQUIRED — production
18
+ * and direct tests cross the same compile-checked Interface. An
19
+ * optional trailing `CommandContext` follows when a caller wants to
20
+ * surface per-invocation context; the handlers do not currently read
21
+ * it. A `CommandContext` is NOT a valid substitute for `deps`: a
22
+ * direct caller who omits `deps` fails loudly with a TypeError
23
+ * before reaching the Explorer rather than silently degrading.
7
24
  */
8
- import { ZReadMcpClient } from "../lib/mcp-client.js";
25
+ import { OUTPUT_MODES } from "../lib/output.js";
26
+ import { explorerSearch, explorerReadFile, explorerTree } from "./repository-explorer.js";
9
27
  import { ValidationError } from "../lib/errors.js";
10
- import path from "node:path";
28
+ // ---------------------------------------------------------------------------
29
+ // Parse-level validation
30
+ // ---------------------------------------------------------------------------
31
+ /**
32
+ * Validate the repository string at parse time. Preserves the
33
+ * existing at-least-one-slash rule and exact message so direct
34
+ * handler tests keep their contract. The Explorer re-runs an
35
+ * identical check as a defensive backstop.
36
+ */
11
37
  function validateRepo(repo) {
12
38
  if (!repo.includes("/")) {
13
39
  throw new ValidationError(`Invalid repository format: "${repo}". Use "owner/repo" format (e.g., "facebook/react")`);
14
40
  }
15
41
  }
16
- function truncateText(text, max) {
17
- if (!max || max <= 0 || text.length <= max)
18
- return text;
19
- return text.slice(0, max - 1).trimEnd() + "…";
20
- }
21
- function extractStructureBlock(structure) {
22
- const match = structure.match(/<structure>\n([\s\S]*?)\n<\/structure>/);
23
- const block = match ? match[1] : structure;
24
- return block
25
- .split("\n")
26
- .map((line) => line.replace(/\r/g, ""))
27
- .filter(Boolean);
28
- }
29
- function extractImmediateDirectories(structure, basePath) {
30
- const lines = extractStructureBlock(structure);
31
- const directories = [];
32
- for (const line of lines) {
33
- const match = line.match(/^([│\s]*)(├──|└──)\s(.+)$/);
34
- if (!match)
35
- continue;
36
- const prefix = match[1] || "";
37
- const name = (match[3] || "").trim();
38
- const normalizedPrefix = prefix.replace(/│/g, " ");
39
- const level = Math.floor(normalizedPrefix.length / 4);
40
- if (level !== 0)
41
- continue;
42
- if (!name.endsWith("/"))
43
- continue;
44
- const dirName = name.slice(0, -1);
45
- const fullPath = basePath ? path.posix.join(basePath, dirName) : dirName;
46
- directories.push(fullPath);
47
- }
48
- return directories;
49
- }
50
- function normalizeDirPath(value) {
51
- if (!value)
52
- return undefined;
53
- const trimmed = value.trim();
54
- if (!trimmed || trimmed === "/" || trimmed === ".")
55
- return undefined;
56
- return trimmed.replace(/^\/+/, "").replace(/\/+$/, "");
57
- }
58
- async function collectTreeSnapshots(client, repo, basePath, depth) {
59
- const snapshots = [];
60
- const seen = new Set();
61
- const queue = [{ path: basePath || "", level: 1 }];
62
- while (queue.length > 0) {
63
- const current = queue.shift();
64
- const key = current.path;
65
- if (seen.has(key))
66
- continue;
67
- seen.add(key);
68
- const structure = await client.getRepoStructure(repo, current.path || undefined);
69
- snapshots.push({ path: current.path || "/", structure });
70
- if (current.level >= depth)
71
- continue;
72
- const children = extractImmediateDirectories(structure, current.path);
73
- for (const child of children) {
74
- queue.push({ path: child, level: current.level + 1 });
75
- }
76
- }
77
- return snapshots;
78
- }
79
- export async function repoSearch(repo, query, options = {}, _context) {
42
+ // ---------------------------------------------------------------------------
43
+ // Handlers thin wrappers over the Explorer
44
+ // ---------------------------------------------------------------------------
45
+ /**
46
+ * Repository Search. Validates parse-level request shape, delegates
47
+ * to the Explorer with the injected Repository Capability, and
48
+ * returns the normalized Search result as base data.
49
+ */
50
+ export async function repoSearch(repo, query, options, deps, _context) {
80
51
  validateRepo(repo);
81
52
  if (options.language && options.language !== "en" && options.language !== "zh") {
82
53
  throw new ValidationError('Language must be "en" or "zh"');
83
54
  }
84
- const client = new ZReadMcpClient({ enableVision: false, noCache: options.noCache });
85
- try {
86
- const language = options.language || "en";
87
- const results = await client.searchDoc(repo, query, language);
88
- return { kind: "data", data: truncateText(results, options.maxChars) };
89
- }
90
- finally {
91
- await client.close().catch(() => { });
92
- }
55
+ const result = await explorerSearch(deps.capability, { repository: repo, query, language: options.language }, { noCache: options.noCache, maxChars: options.maxChars }, deps.execution);
56
+ return { kind: "data", data: result };
93
57
  }
94
- export async function repoTree(repo, options = {}, _context) {
58
+ /**
59
+ * Repository Tree. Validates parse-level request shape (including
60
+ * depth), delegates to the Explorer's BFS traversal, and returns
61
+ * the normalized Tree result as base data. Tree is never
62
+ * character-limited; `maxChars` is intentionally not accepted.
63
+ */
64
+ export async function repoTree(repo, options, deps, _context) {
95
65
  validateRepo(repo);
96
66
  if (options.depth !== undefined) {
97
67
  const depthValue = Number(options.depth);
@@ -99,43 +69,31 @@ export async function repoTree(repo, options = {}, _context) {
99
69
  throw new ValidationError("Depth must be a positive integer");
100
70
  }
101
71
  }
102
- const client = new ZReadMcpClient({ enableVision: false, noCache: options.noCache });
103
- try {
104
- const depth = Math.max(1, Math.floor(options.depth || 1));
105
- const dirPath = normalizeDirPath(options.path);
106
- if (depth === 1) {
107
- const structure = await client.getRepoStructure(repo, dirPath);
108
- return { kind: "data", data: structure };
109
- }
110
- const snapshots = await collectTreeSnapshots(client, repo, dirPath, depth);
111
- return {
112
- kind: "data",
113
- data: {
114
- repo,
115
- depth,
116
- basePath: dirPath || "/",
117
- snapshots,
118
- },
119
- };
120
- }
121
- finally {
122
- await client.close().catch(() => { });
123
- }
72
+ const result = await explorerTree(deps.capability, { repository: repo, path: options.path, depth: options.depth }, { noCache: options.noCache }, deps.execution);
73
+ return { kind: "data", data: result };
124
74
  }
125
- export async function repoRead(repo, path, options = {}, _context) {
75
+ /**
76
+ * Repository File read. Validates parse-level request shape,
77
+ * delegates to the Explorer with the injected Repository Capability,
78
+ * and returns the normalized File result as base data.
79
+ */
80
+ export async function repoRead(repo, path, options, deps, _context) {
126
81
  validateRepo(repo);
127
- const client = new ZReadMcpClient({ enableVision: false, noCache: options.noCache });
128
- try {
129
- const content = await client.readFile(repo, path);
130
- return { kind: "data", data: truncateText(content, options.maxChars) };
131
- }
132
- finally {
133
- await client.close().catch(() => { });
134
- }
82
+ const result = await explorerReadFile(deps.capability, { repository: repo, path }, { noCache: options.noCache, maxChars: options.maxChars }, deps.execution);
83
+ return { kind: "data", data: result };
135
84
  }
136
- // Help text
85
+ // ---------------------------------------------------------------------------
86
+ // Help
87
+ // ---------------------------------------------------------------------------
88
+ /**
89
+ * Canonical output-mode list for `--output-format`. Derived from the
90
+ * shared `OUTPUT_MODES` contract so the help text cannot drift from
91
+ * the accepted set. Joined with " | " for inline display under
92
+ * Common Options below.
93
+ */
94
+ const OUTPUT_MODE_LIST = OUTPUT_MODES.join(" | ");
137
95
  export const REPO_HELP = `
138
- Repo Commands - Explore GitHub repositories using ZRead
96
+ Repo Commands - Explore GitHub repositories (Provider Capability)
139
97
 
140
98
  Usage: scoutline repo <command> <owner/repo> [args]
141
99
 
@@ -155,6 +113,37 @@ Tree Options:
155
113
  Read Options:
156
114
  --max-chars <n> Truncate file content to <n> chars
157
115
 
116
+ Common Options:
117
+ --no-cache Bypass the response cache for this invocation
118
+ --provider <id> Override the active Provider (zai | minimax)
119
+ --output-format <mode> One of: ${OUTPUT_MODE_LIST} (default: data)
120
+ -O <mode> Alias for --output-format
121
+
122
+ Provider selection (precedence: --provider, then SCOUTLINE_PROVIDER,
123
+ then zai):
124
+ - The 'repo' command participates in Provider selection.
125
+ - Z.AI advertises the repository-exploration Capability and supplies
126
+ the Adapter; selecting zai routes Search/File/Tree through it.
127
+ - MiniMax does NOT advertise repository-exploration. Selecting
128
+ minimax (explicitly or via SCOUTLINE_PROVIDER) returns
129
+ UNSUPPORTED_CAPABILITY with no fallback to Z.AI.
130
+
131
+ Output format (intentional schema-version-1 migration):
132
+ - search: {schemaVersion, repository, query, language, excerpts:[{text}],
133
+ truncated, originalTextLength}
134
+ - read: {schemaVersion, repository, path, content, truncated,
135
+ originalContentLength}
136
+ - tree: {schemaVersion, repository, path, depth,
137
+ snapshots:[{repository, path, entries:[{name, path, kind}]}]}
138
+ Root path is the empty string "". --max-chars applies only to
139
+ search/read content; tree is never character-limited.
140
+ Output modes for repo results:
141
+ - data: raw schema-version-1 value as plain JSON (no envelope).
142
+ - json / pretty: standard {success, data, timestamp} envelope
143
+ (indent 0 for json, indent 2 for pretty).
144
+ - compact / markdown / refs / tty: JSON fallback (same value as
145
+ data mode). Repo never supplies a per-mode prose presentation.
146
+
158
147
  Examples:
159
148
  scoutline repo search facebook/react "server components"
160
149
  scoutline repo search facebook/react "server components" --language en --max-chars 2000
@@ -162,20 +151,12 @@ Examples:
162
151
  scoutline repo tree vercel/next.js --path packages --depth 2
163
152
  scoutline repo read anthropics/anthropic-sdk-python src/anthropic/client.py
164
153
  scoutline repo read facebook/react README.md --max-chars 3000
154
+ scoutline --provider minimax repo search owner/repo query # UNSUPPORTED_CAPABILITY
165
155
 
166
156
  Notes:
167
157
  - Repository must be public
168
158
  - Use "owner/repo" format (e.g., "facebook/react")
169
159
  - Paths are relative to repository root
170
- - Depth >1 returns structured snapshots (use --output-format pretty for readability)
171
-
172
- Output format (search):
173
- Search results array
174
-
175
- Output format (tree):
176
- Repository structure object
177
-
178
- Output format (read):
179
- File contents
160
+ - Depth >= 1 returns structured snapshots; depth 1 is also structured
180
161
  `.trim();
181
162
  //# sourceMappingURL=repo.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"repo.js","sourceRoot":"","sources":["../../src/commands/repo.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,147 @@
1
+ /**
2
+ * Provider-neutral Repository Explorer (P6-05, DESIGN.md §18, §11,
3
+ * PRD FR-081, FR-083–FR-086, FR-088, FR-091; NFR-004, NFR-005, NFR-007).
4
+ *
5
+ * The Explorer is the single non-Adapter consumer of the Repository
6
+ * Capability contract. It owns canonical repository-path handling,
7
+ * deterministic breadth-first traversal, duplicate-directory
8
+ * protection, and local Search/File `--max-chars` projection. It
9
+ * constructs canonical Capability requests, hands them to shared
10
+ * execution, and projects the normalized results.
11
+ *
12
+ * Boundary rules (ARCHITECTURE.md §2, NFR-004):
13
+ * - Imports ONLY provider-neutral Repository Capability types and
14
+ * shared `executeRepositoryOperation` / `ExecutionDependencies`,
15
+ * plus the normalized `ValidationError`.
16
+ * - Imports NO concrete Provider Adapter, MCP/UTCP client, raw tool
17
+ * name, or Provider response type. Provider-specific facts (ZRead
18
+ * grammar, credentials, transports) remain Adapter-internal.
19
+ * - Owns canonicalization, BFS, and projection; never owns
20
+ * transport, credentials, Provider selection, or command
21
+ * presentation.
22
+ *
23
+ * Fixed ordering (DESIGN.md §18):
24
+ * 1. Apply Explorer-level defaults (Search `language`, Tree
25
+ * `depth`) and canonicalize paths.
26
+ * 2. Validate `repository` (at-least-one-slash), `query`
27
+ * (non-whitespace), `language`, and `depth`.
28
+ * 3. Construct the canonical Capability request.
29
+ * 4. Delegate to `executeRepositoryOperation`, which runs
30
+ * `operation.validate`, `operation.cacheIdentity`, the
31
+ * provider-partitioned cache read, ordered legacy candidates,
32
+ * retry-wrapped invoke, and the normalized cache write.
33
+ * 5. Apply post-execution `--max-chars` projection (Search/File
34
+ * only). Tree is never character-limited.
35
+ *
36
+ * `--max-chars` is post-execution projection. It never appears in
37
+ * the canonical request, the cache identity, or the cache itself.
38
+ */
39
+ import type { RepositoryCapability, RepositoryFileResult, RepositorySearchResult, RepositoryTreeResult } from "../capabilities/repository.js";
40
+ import { type ExecutionDependencies, type RetryPolicy } from "../lib/execution.js";
41
+ /**
42
+ * The kind of path being canonicalized. Governs root handling and
43
+ * the File-only leading `./` convenience.
44
+ */
45
+ export type RepositoryPathKind = "file" | "directory";
46
+ /**
47
+ * Canonicalize a repository-relative POSIX path.
48
+ *
49
+ * Rules (DESIGN.md §18, technical plan):
50
+ * - Backslashes (`\\`) and ASCII control characters (C0 plus DEL,
51
+ * code points 0–31 and 127) always throw `ValidationError`.
52
+ * - Whole-string root aliases (`undefined`, `""`, `"/"`, `"."`)
53
+ * map to root (`""`). For File (`kind: "file"`), root is
54
+ * invalid and throws.
55
+ * - File accepts a single leading `./` and any leading `/` as
56
+ * convenience; both are stripped. Directory does NOT get the
57
+ * leading `./` convenience (a leading `.` segment is unsafe and
58
+ * is rejected below); leading `/` is naturally stripped by the
59
+ * empty-segment collapse.
60
+ * - Repeated `/` collapses and trailing `/` is removed via the
61
+ * empty-segment skip.
62
+ * - Actual `.` or `..` segments at any position throw.
63
+ * - Percent escapes are never decoded.
64
+ *
65
+ * Returns the canonical repository-relative POSIX path. `""` is the
66
+ * repository root.
67
+ */
68
+ export declare function canonicalizeRepositoryPath(input: string | undefined, kind: RepositoryPathKind): string;
69
+ /**
70
+ * Request shape accepted by {@link explorerSearch}. `language` is
71
+ * optional; the Explorer applies the `"en"` default before the
72
+ * Capability sees the request. `repository` and `query` preserve
73
+ * their exact case and text.
74
+ */
75
+ export interface ExplorerSearchRequest {
76
+ readonly repository: string;
77
+ readonly query: string;
78
+ readonly language?: "en" | "zh";
79
+ }
80
+ /**
81
+ * Request shape accepted by {@link explorerReadFile}. `path` is
82
+ * canonicalized through the File rules: leading `./` and `/` are
83
+ * stripped, root is rejected, and unsafe segments throw.
84
+ */
85
+ export interface ExplorerReadFileRequest {
86
+ readonly repository: string;
87
+ readonly path: string;
88
+ }
89
+ /**
90
+ * Request shape accepted by {@link explorerTree}. `path` is
91
+ * canonicalized through the Directory/Tree rules:
92
+ * omitted/empty/`/`/`.` map to root, and unsafe segments throw.
93
+ * `depth` defaults to 1.
94
+ */
95
+ export interface ExplorerTreeRequest {
96
+ readonly repository: string;
97
+ readonly path?: string;
98
+ readonly depth?: number;
99
+ }
100
+ /**
101
+ * Options for Search and File. `noCache` and `retryPolicy` are
102
+ * forwarded to `executeRepositoryOperation`. `maxChars` is
103
+ * post-execution projection only and never enters the canonical
104
+ * request or cache identity.
105
+ */
106
+ export interface ExplorerOptions {
107
+ readonly noCache?: boolean;
108
+ readonly retryPolicy?: RetryPolicy;
109
+ readonly maxChars?: number;
110
+ }
111
+ /**
112
+ * Options for Tree. Tree is never character-limited; `maxChars` is
113
+ * intentionally absent.
114
+ */
115
+ export interface ExplorerTreeOptions {
116
+ readonly noCache?: boolean;
117
+ readonly retryPolicy?: RetryPolicy;
118
+ }
119
+ /**
120
+ * Provider-neutral Repository Search (DESIGN.md §18, PRD FR-081,
121
+ * FR-083). Applies the `language` default, validates `repository`
122
+ * (at-least-one-slash) and `query` (non-whitespace), constructs the
123
+ * canonical request, delegates to shared execution, and applies the
124
+ * `--max-chars` budget to `excerpts[].text` only.
125
+ *
126
+ * Defaults and canonicalization precede `operation.validate` /
127
+ * `operation.cacheIdentity`. The Provider sees the canonical
128
+ * request; the Explorer never widens into Provider-specific fields.
129
+ */
130
+ export declare function explorerSearch(capability: RepositoryCapability, request: ExplorerSearchRequest, options: ExplorerOptions, dependencies: ExecutionDependencies): Promise<RepositorySearchResult>;
131
+ /**
132
+ * Provider-neutral Repository File read (DESIGN.md §18, PRD FR-086).
133
+ * Canonicalizes the File path (root rejected, leading `./` and `/`
134
+ * stripped, unsafe segments throw), delegates to shared execution,
135
+ * and applies the `--max-chars` budget to `content` only.
136
+ */
137
+ export declare function explorerReadFile(capability: RepositoryCapability, request: ExplorerReadFileRequest, options: ExplorerOptions, dependencies: ExecutionDependencies): Promise<RepositoryFileResult>;
138
+ /**
139
+ * Provider-neutral Repository Tree (DESIGN.md §18, PRD FR-088).
140
+ * Canonicalizes the starting path (root allowed), projects depth
141
+ * (default 1, finite positive integer), and drives a deterministic
142
+ * breadth-first traversal that preserves Provider sibling order,
143
+ * requests each canonical directory at most once, and never returns
144
+ * partial success. Tree is never character-limited.
145
+ */
146
+ export declare function explorerTree(capability: RepositoryCapability, request: ExplorerTreeRequest, options: ExplorerTreeOptions, dependencies: ExecutionDependencies): Promise<RepositoryTreeResult>;
147
+ //# sourceMappingURL=repository-explorer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"repository-explorer.d.ts","sourceRoot":"","sources":["../../src/commands/repository-explorer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EACV,oBAAoB,EAKpB,oBAAoB,EAEpB,sBAAsB,EACtB,oBAAoB,EACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAEL,KAAK,qBAAqB,EAC1B,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAc7B;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEtD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,MAAM,GAAG,SAAS,EACzB,IAAI,EAAE,kBAAkB,GACvB,MAAM,CAmER;AAoaD;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;CACpC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,qBAAqB,EAC9B,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,sBAAsB,CAAC,CAmBjC;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CACpC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,uBAAuB,EAChC,OAAO,EAAE,eAAe,EACxB,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAiB/B;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,oBAAoB,EAChC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,mBAAmB,EAC5B,YAAY,EAAE,qBAAqB,GAClC,OAAO,CAAC,oBAAoB,CAAC,CAyB/B"}