@nerviq/cli 1.29.0 → 1.30.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 (93) hide show
  1. package/CHANGELOG.md +1764 -1493
  2. package/README.md +568 -538
  3. package/SECURITY.md +78 -82
  4. package/bin/cli.js +2838 -2558
  5. package/docs/api-reference.md +356 -356
  6. package/docs/audit-fix.md +109 -0
  7. package/docs/autofix.md +3 -62
  8. package/docs/getting-started.md +1 -1
  9. package/docs/index.html +592 -592
  10. package/docs/integration-contracts.md +287 -287
  11. package/docs/maintenance.md +128 -128
  12. package/docs/new-platform-guide.md +202 -202
  13. package/docs/release-process.md +63 -0
  14. package/docs/shallow-risk.md +244 -244
  15. package/docs/why-nerviq.md +82 -82
  16. package/package.json +75 -67
  17. package/sdk/README.md +12 -3
  18. package/sdk/examples/langchain-integration.md +128 -0
  19. package/sdk/examples/self-governing-agent.js +135 -0
  20. package/sdk/index.d.ts +115 -0
  21. package/sdk/index.js +94 -0
  22. package/sdk/package.json +11 -0
  23. package/src/activity.js +13 -0
  24. package/src/aider/activity.js +226 -226
  25. package/src/aider/context.js +162 -162
  26. package/src/aider/freshness.js +123 -123
  27. package/src/aider/techniques.js +3465 -3465
  28. package/src/audit/layers.js +180 -180
  29. package/src/audit.js +1133 -1032
  30. package/src/auto-suggest.js +9 -2
  31. package/src/behavioral-drift.js +37 -2
  32. package/src/benchmark.js +299 -299
  33. package/src/codex/activity.js +324 -324
  34. package/src/codex/freshness.js +149 -142
  35. package/src/codex/techniques.js +4895 -4895
  36. package/src/context.js +326 -326
  37. package/src/continuous-ops.js +11 -1
  38. package/src/convert.js +340 -340
  39. package/src/copilot/config-parser.js +280 -280
  40. package/src/copilot/context.js +218 -218
  41. package/src/copilot/freshness.js +184 -177
  42. package/src/copilot/patch.js +238 -238
  43. package/src/copilot/techniques.js +3578 -3578
  44. package/src/cursor/freshness.js +194 -194
  45. package/src/cursor/patch.js +243 -243
  46. package/src/cursor/techniques.js +3735 -3735
  47. package/src/doctor.js +201 -201
  48. package/src/fix-engine.js +511 -8
  49. package/src/formatters/csv.js +86 -86
  50. package/src/formatters/junit.js +123 -123
  51. package/src/formatters/markdown.js +164 -164
  52. package/src/formatters/otel.js +151 -151
  53. package/src/freshness.js +163 -156
  54. package/src/gemini/activity.js +402 -402
  55. package/src/gemini/context.js +290 -290
  56. package/src/gemini/freshness.js +188 -188
  57. package/src/gemini/patch.js +229 -229
  58. package/src/gemini/techniques.js +3811 -3811
  59. package/src/governance.js +533 -533
  60. package/src/harmony/audit.js +306 -306
  61. package/src/i18n.js +63 -63
  62. package/src/insights.js +119 -119
  63. package/src/integrations.js +134 -134
  64. package/src/locales/en.json +33 -33
  65. package/src/locales/es.json +33 -33
  66. package/src/migrate.js +354 -354
  67. package/src/opencode/activity.js +286 -286
  68. package/src/opencode/freshness.js +137 -137
  69. package/src/opencode/techniques.js +3450 -3450
  70. package/src/safe-glyph.js +97 -0
  71. package/src/setup/analysis.js +12 -12
  72. package/src/setup.js +13 -6
  73. package/src/shallow-risk/index.js +113 -56
  74. package/src/shallow-risk/patterns/agent-config-cross-platform-drift.js +51 -50
  75. package/src/shallow-risk/patterns/agent-config-dangerous-autoapprove.js +47 -46
  76. package/src/shallow-risk/patterns/agent-config-deprecated-keys.js +47 -46
  77. package/src/shallow-risk/patterns/agent-config-framework-version-mismatch.js +138 -0
  78. package/src/shallow-risk/patterns/agent-config-missing-file.js +318 -317
  79. package/src/shallow-risk/patterns/agent-config-script-not-in-package-json.js +108 -0
  80. package/src/shallow-risk/patterns/agent-config-secret-literal.js +52 -49
  81. package/src/shallow-risk/patterns/agent-config-stack-contradiction.js +35 -34
  82. package/src/shallow-risk/patterns/hook-script-missing.js +71 -70
  83. package/src/shallow-risk/patterns/mcp-server-no-allowlist.js +53 -52
  84. package/src/shallow-risk/shared.js +653 -648
  85. package/src/source-urls.js +295 -295
  86. package/src/state-paths.js +85 -85
  87. package/src/supplemental-checks.js +805 -805
  88. package/src/telemetry.js +160 -160
  89. package/src/watch.js +46 -0
  90. package/src/windsurf/context.js +359 -359
  91. package/src/windsurf/freshness.js +194 -194
  92. package/src/windsurf/patch.js +231 -231
  93. package/src/windsurf/techniques.js +3779 -3779
@@ -1,359 +1,359 @@
1
- /**
2
- * Windsurf project context.
3
- *
4
- * Extends the shared ProjectContext with Windsurf-specific file lookups:
5
- * - .windsurf/rules/*.md (Markdown + YAML frontmatter, NOT MDC)
6
- * - .windsurfrules (legacy, flat file)
7
- * - .windsurf/mcp.json (MCP server config with team whitelist)
8
- * - .windsurf/workflows/*.md (slash commands / workflows)
9
- * - .windsurf/memories/ (team-syncable memories)
10
- * - .cascadeignore (gitignore-like for Cascade agent)
11
- */
12
-
13
- const fs = require('fs');
14
- const os = require('os');
15
- const path = require('path');
16
- const { ProjectContext } = require('../context');
17
- const { tryParseJson, parseWindsurfRule, detectRuleType, getValueByPath } = require('./config-parser');
18
-
19
- function listFiles(fullPath, filter) {
20
- try {
21
- const entries = fs.readdirSync(fullPath).filter(f => !f.startsWith('.'));
22
- return filter ? entries.filter(filter) : entries;
23
- } catch {
24
- return [];
25
- }
26
- }
27
-
28
- class WindsurfProjectContext extends ProjectContext {
29
-
30
- // ─── Rules (.windsurf/rules/*.md) ──────────────────────────────────────
31
-
32
- /**
33
- * List all .md rule files in .windsurf/rules/.
34
- * Returns array of { name, path, frontmatter, body, ruleType }.
35
- *
36
- * Windsurf uses Markdown + YAML frontmatter (NOT MDC like Cursor).
37
- * 4 activation modes: Always, Auto, Agent-Requested, Manual.
38
- * 10K char limit per rule file.
39
- *
40
- * PP-03: also recognises the `.windsurfrules/` *directory* convention
41
- * (observed in rudrankriyam/Ichi) where the rule files sit in
42
- * `.windsurfrules/*.md` or `*.mdc` instead of `.windsurf/rules/`.
43
- */
44
- windsurfRules() {
45
- const collected = [];
46
-
47
- // Primary: .windsurf/rules/*.md
48
- const primaryDir = path.join(this.dir, '.windsurf', 'rules');
49
- const primaryFiles = listFiles(primaryDir, f => f.endsWith('.md'));
50
- for (const f of primaryFiles) {
51
- const relPath = `.windsurf/rules/${f}`;
52
- const content = this.fileContent(relPath);
53
- if (!content) continue;
54
- const parsed = parseWindsurfRule(content);
55
- const ruleType = detectRuleType(parsed.frontmatter);
56
- collected.push({
57
- name: f.replace('.md', ''),
58
- path: relPath,
59
- frontmatter: parsed.frontmatter,
60
- body: parsed.body,
61
- ruleType,
62
- charCount: content.length,
63
- overLimit: content.length > 10000,
64
- });
65
- }
66
-
67
- // PP-03: fallback — `.windsurfrules/` as a directory.
68
- const altDir = path.join(this.dir, '.windsurfrules');
69
- try {
70
- if (fs.statSync(altDir).isDirectory()) {
71
- const altFiles = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
72
- for (const f of altFiles) {
73
- const relPath = `.windsurfrules/${f}`;
74
- const content = this.fileContent(relPath);
75
- if (!content) continue;
76
- const parsed = parseWindsurfRule(content);
77
- const ruleType = detectRuleType(parsed.frontmatter);
78
- collected.push({
79
- name: f.replace(/\.(md|mdc)$/, ''),
80
- path: relPath,
81
- frontmatter: parsed.frontmatter,
82
- body: parsed.body,
83
- ruleType,
84
- charCount: content.length,
85
- overLimit: content.length > 10000,
86
- });
87
- }
88
- }
89
- } catch { /* not a directory */ }
90
-
91
- return collected;
92
- }
93
-
94
- /**
95
- * Get rules filtered by type.
96
- */
97
- alwaysRules() {
98
- return this.windsurfRules().filter(r => r.ruleType === 'always');
99
- }
100
-
101
- autoRules() {
102
- return this.windsurfRules().filter(r => r.ruleType === 'auto');
103
- }
104
-
105
- agentRequestedRules() {
106
- return this.windsurfRules().filter(r => r.ruleType === 'agent-requested');
107
- }
108
-
109
- manualRules() {
110
- return this.windsurfRules().filter(r => r.ruleType === 'manual');
111
- }
112
-
113
- // ─── Legacy .windsurfrules ────────────────────────────────────────────
114
-
115
- /**
116
- * .windsurfrules content (deprecated).
117
- *
118
- * PP-03: handles three real-world shapes:
119
- * 1. Classic file with rule text.
120
- * 2. Pointer file — a single short line referencing another markdown
121
- * file (e.g. `.ai/instructions.md`, `.llmrules`,
122
- * `.ai/tech-stack.md`). Observed in ShareX/XerahS,
123
- * Brawl345/Image-Reverse-Search-WebExtension, wepublish/wepublish.
124
- * 3. Directory convention — `.windsurfrules/` is itself a directory
125
- * of rule files. Observed in rudrankriyam/Ichi. In that case this
126
- * method returns the concatenated body of all contained rule files
127
- * so consumer checks (architecture / verification / etc.) see the
128
- * effective instruction bundle.
129
- */
130
- legacyWindsurfrules() {
131
- // Directory form first — `.windsurfrules/` as a directory.
132
- const altDir = path.join(this.dir, '.windsurfrules');
133
- try {
134
- if (fs.statSync(altDir).isDirectory()) {
135
- const files = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
136
- const bodies = files
137
- .map(f => this.fileContent(`.windsurfrules/${f}`) || '')
138
- .filter(Boolean);
139
- return bodies.length > 0 ? bodies.join('\n') : '';
140
- }
141
- } catch { /* not a directory */ }
142
-
143
- const raw = this.fileContent('.windsurfrules');
144
- if (!raw) return null;
145
-
146
- // Pointer form — one short line that looks like a relative path.
147
- const trimmed = raw.trim();
148
- if (trimmed.length < 200) {
149
- const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
150
- if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
151
- let combined = raw;
152
- for (const line of lines) {
153
- const referenced = this.fileContent(line);
154
- if (referenced) combined += '\n' + referenced;
155
- }
156
- return combined;
157
- }
158
- }
159
- return raw;
160
- }
161
-
162
- hasLegacyRules() {
163
- return Boolean(this.legacyWindsurfrules());
164
- }
165
-
166
- /**
167
- * PP-03: True only when `.windsurfrules` exists as a regular file
168
- * containing legacy rule text (not a pointer and not a directory).
169
- * Used by checks that warn about the deprecated single-file format.
170
- */
171
- hasRawLegacyWindsurfrules() {
172
- const altDir = path.join(this.dir, '.windsurfrules');
173
- try {
174
- if (fs.statSync(altDir).isDirectory()) return false;
175
- } catch { /* not a dir */ }
176
- const raw = this.fileContent('.windsurfrules');
177
- if (!raw) return false;
178
- const trimmed = raw.trim();
179
- if (trimmed.length < 200) {
180
- const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
181
- if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
182
- // It's a pointer — not a raw legacy file.
183
- return false;
184
- }
185
- }
186
- return true;
187
- }
188
-
189
- /**
190
- * PP-03: surface detection helper — any instruction surface that
191
- * Cascade/Windsurf can pick up.
192
- */
193
- hasAnyInstructionsSurface() {
194
- return (
195
- this.windsurfRules().length > 0 ||
196
- Boolean(this.legacyWindsurfrules()) ||
197
- Boolean(this.fileContent('AGENTS.md')) ||
198
- Boolean(this.fileContent('CLAUDE.md')) ||
199
- Boolean(this.fileContent('.ai/instructions.md'))
200
- );
201
- }
202
-
203
- // ─── MCP config (.windsurf/mcp.json) ──────────────────────────────────
204
-
205
- /**
206
- * .windsurf/mcp.json parsed.
207
- * Windsurf MCP format: { mcpServers: { name: { command, args, env } } }
208
- * Supports team-level whitelist.
209
- */
210
- mcpConfig() {
211
- const content = this.fileContent('.windsurf/mcp.json');
212
- if (!content) {
213
- return { ok: false, data: null, error: 'missing .windsurf/mcp.json', source: '.windsurf/mcp.json' };
214
- }
215
- const parsed = tryParseJson(content);
216
- return { ...parsed, source: '.windsurf/mcp.json' };
217
- }
218
-
219
- /**
220
- * Global MCP config (~/.windsurf/mcp.json).
221
- */
222
- globalMcpConfig() {
223
- const homeDir = os.homedir();
224
- const globalPath = path.join(homeDir, '.windsurf', 'mcp.json');
225
- try {
226
- const content = fs.readFileSync(globalPath, 'utf8');
227
- const parsed = tryParseJson(content);
228
- return { ...parsed, source: globalPath };
229
- } catch {
230
- return { ok: false, data: null, error: 'missing global mcp.json', source: globalPath };
231
- }
232
- }
233
-
234
- /**
235
- * MCP servers from .windsurf/mcp.json.
236
- */
237
- mcpServers() {
238
- const result = this.mcpConfig();
239
- if (!result.ok || !result.data) return {};
240
- return result.data.mcpServers || {};
241
- }
242
-
243
- /**
244
- * Count total MCP tools across all servers.
245
- */
246
- totalMcpTools() {
247
- const servers = this.mcpServers();
248
- let total = 0;
249
- for (const server of Object.values(servers)) {
250
- const toolCount = server.tools ? Object.keys(server.tools).length : 5;
251
- total += toolCount;
252
- }
253
- return total;
254
- }
255
-
256
- // ─── Workflows (.windsurf/workflows/*.md) ─────────────────────────────
257
-
258
- /**
259
- * Workflow files (slash commands).
260
- * Windsurf workflows are Markdown files that define slash commands.
261
- */
262
- workflowFiles() {
263
- const dir = path.join(this.dir, '.windsurf', 'workflows');
264
- return listFiles(dir, f => f.endsWith('.md'))
265
- .map(f => `.windsurf/workflows/${f}`);
266
- }
267
-
268
- // ─── Memories (.windsurf/memories/) ───────────────────────────────────
269
-
270
- /**
271
- * Memory files (team-syncable persistent context).
272
- */
273
- memoryFiles() {
274
- const dir = path.join(this.dir, '.windsurf', 'memories');
275
- return listFiles(dir, f => f.endsWith('.md') || f.endsWith('.json'));
276
- }
277
-
278
- memoryContents() {
279
- const dir = path.join(this.dir, '.windsurf', 'memories');
280
- const files = this.memoryFiles();
281
- return files.map(f => {
282
- const relPath = `.windsurf/memories/${f}`;
283
- const content = this.fileContent(relPath);
284
- return { name: f, path: relPath, content };
285
- }).filter(item => item.content);
286
- }
287
-
288
- // ─── Cascadeignore (.cascadeignore) ───────────────────────────────────
289
-
290
- /**
291
- * .cascadeignore content (gitignore-like for Cascade agent).
292
- */
293
- cascadeignoreContent() {
294
- return this.fileContent('.cascadeignore');
295
- }
296
-
297
- hasCascadeignore() {
298
- return Boolean(this.cascadeignoreContent());
299
- }
300
-
301
- // ─── VS Code compat (.vscode/settings.json) ──────────────────────────
302
-
303
- vscodeSettings() {
304
- const content = this.fileContent('.vscode/settings.json');
305
- if (!content) {
306
- return { ok: false, data: null, error: 'missing .vscode/settings.json', source: '.vscode/settings.json' };
307
- }
308
- const parsed = tryParseJson(content);
309
- return { ...parsed, source: '.vscode/settings.json' };
310
- }
311
-
312
- // ─── CI Workflow files ────────────────────────────────────────────────
313
-
314
- ciWorkflowFiles() {
315
- const dir = path.join(this.dir, '.github', 'workflows');
316
- return listFiles(dir, f => f.endsWith('.yml') || f.endsWith('.yaml'))
317
- .map(f => `.github/workflows/${f}`);
318
- }
319
-
320
- // ─── Surface detection ────────────────────────────────────────────────
321
-
322
- /**
323
- * Detect which Windsurf surfaces are configured.
324
- * Windsurf has NO background agents (unlike Cursor).
325
- */
326
- detectSurfaces() {
327
- const foreground = Boolean(
328
- this.windsurfRules().length > 0 ||
329
- this.legacyWindsurfrules() ||
330
- this.mcpConfig().ok
331
- );
332
- const workflows = this.workflowFiles().length > 0;
333
- const memories = this.memoryFiles().length > 0;
334
- const cascadeignore = this.hasCascadeignore();
335
-
336
- return { foreground, workflows, memories, cascadeignore };
337
- }
338
-
339
- // ─── Static detection ─────────────────────────────────────────────────
340
-
341
- static isWindsurfRepo(dir) {
342
- try {
343
- return fs.existsSync(path.join(dir, '.windsurf')) ||
344
- fs.existsSync(path.join(dir, '.windsurfrules'));
345
- } catch {
346
- return false;
347
- }
348
- }
349
-
350
- // ─── Stack detection (reuse shared) ───────────────────────────────────
351
-
352
- detectStacks(STACKS) {
353
- return super.detectStacks(STACKS);
354
- }
355
- }
356
-
357
- module.exports = {
358
- WindsurfProjectContext,
359
- };
1
+ /**
2
+ * Windsurf project context.
3
+ *
4
+ * Extends the shared ProjectContext with Windsurf-specific file lookups:
5
+ * - .windsurf/rules/*.md (Markdown + YAML frontmatter, NOT MDC)
6
+ * - .windsurfrules (legacy, flat file)
7
+ * - .windsurf/mcp.json (MCP server config with team whitelist)
8
+ * - .windsurf/workflows/*.md (slash commands / workflows)
9
+ * - .windsurf/memories/ (team-syncable memories)
10
+ * - .cascadeignore (gitignore-like for Cascade agent)
11
+ */
12
+
13
+ const fs = require('fs');
14
+ const os = require('os');
15
+ const path = require('path');
16
+ const { ProjectContext } = require('../context');
17
+ const { tryParseJson, parseWindsurfRule, detectRuleType, getValueByPath } = require('./config-parser');
18
+
19
+ function listFiles(fullPath, filter) {
20
+ try {
21
+ const entries = fs.readdirSync(fullPath).filter(f => !f.startsWith('.'));
22
+ return filter ? entries.filter(filter) : entries;
23
+ } catch {
24
+ return [];
25
+ }
26
+ }
27
+
28
+ class WindsurfProjectContext extends ProjectContext {
29
+
30
+ // ─── Rules (.windsurf/rules/*.md) ──────────────────────────────────────
31
+
32
+ /**
33
+ * List all .md rule files in .windsurf/rules/.
34
+ * Returns array of { name, path, frontmatter, body, ruleType }.
35
+ *
36
+ * Windsurf uses Markdown + YAML frontmatter (NOT MDC like Cursor).
37
+ * 4 activation modes: Always, Auto, Agent-Requested, Manual.
38
+ * 10K char limit per rule file.
39
+ *
40
+ * PP-03: also recognises the `.windsurfrules/` *directory* convention
41
+ * (observed in rudrankriyam/Ichi) where the rule files sit in
42
+ * `.windsurfrules/*.md` or `*.mdc` instead of `.windsurf/rules/`.
43
+ */
44
+ windsurfRules() {
45
+ const collected = [];
46
+
47
+ // Primary: .windsurf/rules/*.md
48
+ const primaryDir = path.join(this.dir, '.windsurf', 'rules');
49
+ const primaryFiles = listFiles(primaryDir, f => f.endsWith('.md'));
50
+ for (const f of primaryFiles) {
51
+ const relPath = `.windsurf/rules/${f}`;
52
+ const content = this.fileContent(relPath);
53
+ if (!content) continue;
54
+ const parsed = parseWindsurfRule(content);
55
+ const ruleType = detectRuleType(parsed.frontmatter);
56
+ collected.push({
57
+ name: f.replace('.md', ''),
58
+ path: relPath,
59
+ frontmatter: parsed.frontmatter,
60
+ body: parsed.body,
61
+ ruleType,
62
+ charCount: content.length,
63
+ overLimit: content.length > 10000,
64
+ });
65
+ }
66
+
67
+ // PP-03: fallback — `.windsurfrules/` as a directory.
68
+ const altDir = path.join(this.dir, '.windsurfrules');
69
+ try {
70
+ if (fs.statSync(altDir).isDirectory()) {
71
+ const altFiles = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
72
+ for (const f of altFiles) {
73
+ const relPath = `.windsurfrules/${f}`;
74
+ const content = this.fileContent(relPath);
75
+ if (!content) continue;
76
+ const parsed = parseWindsurfRule(content);
77
+ const ruleType = detectRuleType(parsed.frontmatter);
78
+ collected.push({
79
+ name: f.replace(/\.(md|mdc)$/, ''),
80
+ path: relPath,
81
+ frontmatter: parsed.frontmatter,
82
+ body: parsed.body,
83
+ ruleType,
84
+ charCount: content.length,
85
+ overLimit: content.length > 10000,
86
+ });
87
+ }
88
+ }
89
+ } catch { /* not a directory */ }
90
+
91
+ return collected;
92
+ }
93
+
94
+ /**
95
+ * Get rules filtered by type.
96
+ */
97
+ alwaysRules() {
98
+ return this.windsurfRules().filter(r => r.ruleType === 'always');
99
+ }
100
+
101
+ autoRules() {
102
+ return this.windsurfRules().filter(r => r.ruleType === 'auto');
103
+ }
104
+
105
+ agentRequestedRules() {
106
+ return this.windsurfRules().filter(r => r.ruleType === 'agent-requested');
107
+ }
108
+
109
+ manualRules() {
110
+ return this.windsurfRules().filter(r => r.ruleType === 'manual');
111
+ }
112
+
113
+ // ─── Legacy .windsurfrules ────────────────────────────────────────────
114
+
115
+ /**
116
+ * .windsurfrules content (deprecated).
117
+ *
118
+ * PP-03: handles three real-world shapes:
119
+ * 1. Classic file with rule text.
120
+ * 2. Pointer file — a single short line referencing another markdown
121
+ * file (e.g. `.ai/instructions.md`, `.llmrules`,
122
+ * `.ai/tech-stack.md`). Observed in ShareX/XerahS,
123
+ * Brawl345/Image-Reverse-Search-WebExtension, wepublish/wepublish.
124
+ * 3. Directory convention — `.windsurfrules/` is itself a directory
125
+ * of rule files. Observed in rudrankriyam/Ichi. In that case this
126
+ * method returns the concatenated body of all contained rule files
127
+ * so consumer checks (architecture / verification / etc.) see the
128
+ * effective instruction bundle.
129
+ */
130
+ legacyWindsurfrules() {
131
+ // Directory form first — `.windsurfrules/` as a directory.
132
+ const altDir = path.join(this.dir, '.windsurfrules');
133
+ try {
134
+ if (fs.statSync(altDir).isDirectory()) {
135
+ const files = listFiles(altDir, f => f.endsWith('.md') || f.endsWith('.mdc'));
136
+ const bodies = files
137
+ .map(f => this.fileContent(`.windsurfrules/${f}`) || '')
138
+ .filter(Boolean);
139
+ return bodies.length > 0 ? bodies.join('\n') : '';
140
+ }
141
+ } catch { /* not a directory */ }
142
+
143
+ const raw = this.fileContent('.windsurfrules');
144
+ if (!raw) return null;
145
+
146
+ // Pointer form — one short line that looks like a relative path.
147
+ const trimmed = raw.trim();
148
+ if (trimmed.length < 200) {
149
+ const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
150
+ if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
151
+ let combined = raw;
152
+ for (const line of lines) {
153
+ const referenced = this.fileContent(line);
154
+ if (referenced) combined += '\n' + referenced;
155
+ }
156
+ return combined;
157
+ }
158
+ }
159
+ return raw;
160
+ }
161
+
162
+ hasLegacyRules() {
163
+ return Boolean(this.legacyWindsurfrules());
164
+ }
165
+
166
+ /**
167
+ * PP-03: True only when `.windsurfrules` exists as a regular file
168
+ * containing legacy rule text (not a pointer and not a directory).
169
+ * Used by checks that warn about the deprecated single-file format.
170
+ */
171
+ hasRawLegacyWindsurfrules() {
172
+ const altDir = path.join(this.dir, '.windsurfrules');
173
+ try {
174
+ if (fs.statSync(altDir).isDirectory()) return false;
175
+ } catch { /* not a dir */ }
176
+ const raw = this.fileContent('.windsurfrules');
177
+ if (!raw) return false;
178
+ const trimmed = raw.trim();
179
+ if (trimmed.length < 200) {
180
+ const lines = trimmed.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
181
+ if (lines.length <= 3 && lines.every(l => /^[a-zA-Z0-9_./-]+(\.(md|mdc|txt|rst))?$/.test(l))) {
182
+ // It's a pointer — not a raw legacy file.
183
+ return false;
184
+ }
185
+ }
186
+ return true;
187
+ }
188
+
189
+ /**
190
+ * PP-03: surface detection helper — any instruction surface that
191
+ * Cascade/Windsurf can pick up.
192
+ */
193
+ hasAnyInstructionsSurface() {
194
+ return (
195
+ this.windsurfRules().length > 0 ||
196
+ Boolean(this.legacyWindsurfrules()) ||
197
+ Boolean(this.fileContent('AGENTS.md')) ||
198
+ Boolean(this.fileContent('CLAUDE.md')) ||
199
+ Boolean(this.fileContent('.ai/instructions.md'))
200
+ );
201
+ }
202
+
203
+ // ─── MCP config (.windsurf/mcp.json) ──────────────────────────────────
204
+
205
+ /**
206
+ * .windsurf/mcp.json parsed.
207
+ * Windsurf MCP format: { mcpServers: { name: { command, args, env } } }
208
+ * Supports team-level whitelist.
209
+ */
210
+ mcpConfig() {
211
+ const content = this.fileContent('.windsurf/mcp.json');
212
+ if (!content) {
213
+ return { ok: false, data: null, error: 'missing .windsurf/mcp.json', source: '.windsurf/mcp.json' };
214
+ }
215
+ const parsed = tryParseJson(content);
216
+ return { ...parsed, source: '.windsurf/mcp.json' };
217
+ }
218
+
219
+ /**
220
+ * Global MCP config (~/.windsurf/mcp.json).
221
+ */
222
+ globalMcpConfig() {
223
+ const homeDir = os.homedir();
224
+ const globalPath = path.join(homeDir, '.windsurf', 'mcp.json');
225
+ try {
226
+ const content = fs.readFileSync(globalPath, 'utf8');
227
+ const parsed = tryParseJson(content);
228
+ return { ...parsed, source: globalPath };
229
+ } catch {
230
+ return { ok: false, data: null, error: 'missing global mcp.json', source: globalPath };
231
+ }
232
+ }
233
+
234
+ /**
235
+ * MCP servers from .windsurf/mcp.json.
236
+ */
237
+ mcpServers() {
238
+ const result = this.mcpConfig();
239
+ if (!result.ok || !result.data) return {};
240
+ return result.data.mcpServers || {};
241
+ }
242
+
243
+ /**
244
+ * Count total MCP tools across all servers.
245
+ */
246
+ totalMcpTools() {
247
+ const servers = this.mcpServers();
248
+ let total = 0;
249
+ for (const server of Object.values(servers)) {
250
+ const toolCount = server.tools ? Object.keys(server.tools).length : 5;
251
+ total += toolCount;
252
+ }
253
+ return total;
254
+ }
255
+
256
+ // ─── Workflows (.windsurf/workflows/*.md) ─────────────────────────────
257
+
258
+ /**
259
+ * Workflow files (slash commands).
260
+ * Windsurf workflows are Markdown files that define slash commands.
261
+ */
262
+ workflowFiles() {
263
+ const dir = path.join(this.dir, '.windsurf', 'workflows');
264
+ return listFiles(dir, f => f.endsWith('.md'))
265
+ .map(f => `.windsurf/workflows/${f}`);
266
+ }
267
+
268
+ // ─── Memories (.windsurf/memories/) ───────────────────────────────────
269
+
270
+ /**
271
+ * Memory files (team-syncable persistent context).
272
+ */
273
+ memoryFiles() {
274
+ const dir = path.join(this.dir, '.windsurf', 'memories');
275
+ return listFiles(dir, f => f.endsWith('.md') || f.endsWith('.json'));
276
+ }
277
+
278
+ memoryContents() {
279
+ const dir = path.join(this.dir, '.windsurf', 'memories');
280
+ const files = this.memoryFiles();
281
+ return files.map(f => {
282
+ const relPath = `.windsurf/memories/${f}`;
283
+ const content = this.fileContent(relPath);
284
+ return { name: f, path: relPath, content };
285
+ }).filter(item => item.content);
286
+ }
287
+
288
+ // ─── Cascadeignore (.cascadeignore) ───────────────────────────────────
289
+
290
+ /**
291
+ * .cascadeignore content (gitignore-like for Cascade agent).
292
+ */
293
+ cascadeignoreContent() {
294
+ return this.fileContent('.cascadeignore');
295
+ }
296
+
297
+ hasCascadeignore() {
298
+ return Boolean(this.cascadeignoreContent());
299
+ }
300
+
301
+ // ─── VS Code compat (.vscode/settings.json) ──────────────────────────
302
+
303
+ vscodeSettings() {
304
+ const content = this.fileContent('.vscode/settings.json');
305
+ if (!content) {
306
+ return { ok: false, data: null, error: 'missing .vscode/settings.json', source: '.vscode/settings.json' };
307
+ }
308
+ const parsed = tryParseJson(content);
309
+ return { ...parsed, source: '.vscode/settings.json' };
310
+ }
311
+
312
+ // ─── CI Workflow files ────────────────────────────────────────────────
313
+
314
+ ciWorkflowFiles() {
315
+ const dir = path.join(this.dir, '.github', 'workflows');
316
+ return listFiles(dir, f => f.endsWith('.yml') || f.endsWith('.yaml'))
317
+ .map(f => `.github/workflows/${f}`);
318
+ }
319
+
320
+ // ─── Surface detection ────────────────────────────────────────────────
321
+
322
+ /**
323
+ * Detect which Windsurf surfaces are configured.
324
+ * Windsurf has NO background agents (unlike Cursor).
325
+ */
326
+ detectSurfaces() {
327
+ const foreground = Boolean(
328
+ this.windsurfRules().length > 0 ||
329
+ this.legacyWindsurfrules() ||
330
+ this.mcpConfig().ok
331
+ );
332
+ const workflows = this.workflowFiles().length > 0;
333
+ const memories = this.memoryFiles().length > 0;
334
+ const cascadeignore = this.hasCascadeignore();
335
+
336
+ return { foreground, workflows, memories, cascadeignore };
337
+ }
338
+
339
+ // ─── Static detection ─────────────────────────────────────────────────
340
+
341
+ static isWindsurfRepo(dir) {
342
+ try {
343
+ return fs.existsSync(path.join(dir, '.windsurf')) ||
344
+ fs.existsSync(path.join(dir, '.windsurfrules'));
345
+ } catch {
346
+ return false;
347
+ }
348
+ }
349
+
350
+ // ─── Stack detection (reuse shared) ───────────────────────────────────
351
+
352
+ detectStacks(STACKS) {
353
+ return super.detectStacks(STACKS);
354
+ }
355
+ }
356
+
357
+ module.exports = {
358
+ WindsurfProjectContext,
359
+ };