symforge 11.3.8

SymForge — in-memory code intelligence MCP server for Claude Code, Codex, and Gemini CLI
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
const test = require("node:test");
const assert = require("node:assert/strict");
const fs = require("node:fs");
const os = require("node:os");
const path = require("node:path");

const {
  createLauncher,
  whichAllSymforge,
  isOwnShim,
  classifyShadow,
} = require("../bin/launcher.js");

// Create a temp dir that auto-cleans after the test, and return its path.
function tmpDir(t, prefix) {
  const root = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
  return root;
}

// Write a fake `symforge` (or named) file inside `dir` and return its path.
function writeFakeBinary(dir, name = "symforge", contents = "fake") {
  fs.mkdirSync(dir, { recursive: true });
  const file = path.join(dir, name);
  fs.writeFileSync(file, contents);
  return file;
}

test("whichAllSymforge returns existing PATH entries in PATH order", (t) => {
  const root = tmpDir(t, "symforge-which-");
  const dirA = path.join(root, "a");
  const dirB = path.join(root, "b");
  const dirEmpty = path.join(root, "empty");
  fs.mkdirSync(dirEmpty, { recursive: true });

  const binA = writeFakeBinary(dirA);
  const binB = writeFakeBinary(dirB);

  const env = { PATH: [dirA, dirEmpty, dirB].join(path.delimiter) };
  const found = whichAllSymforge(env, "linux");

  assert.deepEqual(found, [binA, binB]);
});

test("whichAllSymforge skips directories with no symforge", (t) => {
  const root = tmpDir(t, "symforge-which-skip-");
  const dirA = path.join(root, "a");
  const dirB = path.join(root, "b");
  fs.mkdirSync(dirA, { recursive: true });
  const binB = writeFakeBinary(dirB);

  const env = { PATH: [dirA, dirB].join(path.delimiter) };
  const found = whichAllSymforge(env, "linux");

  assert.deepEqual(found, [binB]);
});

test("whichAllSymforge ignores a directory that shares the symforge name", (t) => {
  const root = tmpDir(t, "symforge-which-dir-");
  const dir = path.join(root, "a");
  // A *directory* literally named symforge must not count as an executable.
  fs.mkdirSync(path.join(dir, "symforge"), { recursive: true });

  const env = { PATH: dir };
  const found = whichAllSymforge(env, "linux");

  assert.deepEqual(found, []);
});

test("whichAllSymforge returns [] when PATH is unset", () => {
  assert.deepEqual(whichAllSymforge({}, "linux"), []);
  assert.deepEqual(whichAllSymforge({ PATH: "" }, "linux"), []);
});

test("whichAllSymforge resolves Windows extensions via PATHEXT", (t) => {
  const root = tmpDir(t, "symforge-which-win-");
  const dir = path.join(root, "bin");
  const cmd = writeFakeBinary(dir, "symforge.cmd");

  const env = {
    Path: dir,
    PATHEXT: ".COM;.EXE;.BAT;.CMD",
  };
  const found = whichAllSymforge(env, "win32");

  assert.deepEqual(found, [cmd]);
});

test("whichAllSymforge prefers the bare name before the extensioned shim within a dir", (t) => {
  const root = tmpDir(t, "symforge-which-order-");
  const dir = path.join(root, "bin");
  const bare = writeFakeBinary(dir, "symforge");
  const exe = writeFakeBinary(dir, "symforge.exe");

  const env = { Path: dir, PATHEXT: ".EXE" };
  const found = whichAllSymforge(env, "win32");

  // Both exist; the bare candidate is probed first within the directory.
  assert.deepEqual(found, [bare, exe]);
});

test("classifyShadow flags /usr/local as root/system", () => {
  assert.equal(classifyShadow("/usr/local/bin/symforge", {}, "linux"), "root/system");
  assert.equal(classifyShadow("/usr/bin/symforge", {}, "linux"), "root/system");
  assert.equal(classifyShadow("/opt/symforge/bin/symforge", {}, "linux"), "root/system");
});

test("classifyShadow flags a foreign user prefix", () => {
  assert.equal(
    classifyShadow("/home/other/.npm-global/bin/symforge", {}, "linux"),
    "foreign-prefix"
  );
});

test("classifyShadow never returns root/system on Windows", () => {
  // The /usr, /opt heuristics are POSIX-only; Windows always falls through.
  assert.equal(classifyShadow("C:\\tools\\symforge\\symforge.exe", {}, "win32"), "foreign-prefix");
});

test("isOwnShim recognizes a shim in the npm prefix bin dir as ours", (t) => {
  const root = tmpDir(t, "symforge-shim-prefix-");
  // Layout: <prefix>/lib/node_modules/symforge/bin (selfDir) + <prefix>/bin/symforge (shim)
  const selfDir = path.join(root, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  // prefix = dirname(dirname(dirname(selfDir))) = root/lib
  const prefix = path.join(root, "lib");
  const shim = writeFakeBinary(path.join(prefix, "bin"), "symforge", "#!/bin/sh\nnode launcher\n");

  assert.equal(isOwnShim(shim, selfDir), true);
});

test("isOwnShim recognizes a shim by its launcher reference even from a foreign dir", (t) => {
  const root = tmpDir(t, "symforge-shim-content-");
  const selfDir = path.join(root, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const shimDir = path.join(root, "somewhere", "else");
  const shim = writeFakeBinary(
    shimDir,
    "symforge",
    'require("../lib/node_modules/symforge/bin/launcher.js")'
  );

  assert.equal(isOwnShim(shim, selfDir), true);
});

test("isOwnShim treats a genuinely foreign install as not ours", (t) => {
  const root = tmpDir(t, "symforge-shim-foreign-");
  const selfDir = path.join(root, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const foreign = writeFakeBinary(path.join(root, "usr", "local", "bin"), "symforge", "totally different binary");

  assert.equal(isOwnShim(foreign, selfDir), false);
});

test("launcher warns when a different symforge dir is first on PATH", (t) => {
  const root = tmpDir(t, "symforge-warn-");
  const shadowDir = path.join(root, "usr", "local", "bin");
  const shadow = writeFakeBinary(shadowDir, "symforge");
  // selfDir lives in a different prefix entirely.
  const selfDir = path.join(root, "home", "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const resolvedBinary = path.join(root, "home", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  const errors = [];
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: { PATH: shadowDir },
    },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });

  assert.equal(launcher.main([]), 0);
  const joined = errors.join("\n");
  assert.match(joined, /different 'symforge'/);
  assert.match(joined, new RegExp(shadow.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
  assert.match(joined, /symforge init/);
});

test("launcher does NOT warn when its own npm shim is first on PATH", (t) => {
  const root = tmpDir(t, "symforge-noshim-warn-");
  // Realistic global install: <prefix>/lib/node_modules/symforge/bin is selfDir,
  // <prefix>/bin/symforge is the npm shim, and the native binary lives in the
  // sibling platform package.
  const prefix = path.join(root, "prefix");
  const selfDir = path.join(prefix, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const shimDir = path.join(prefix, "lib", "bin");
  const shim = writeFakeBinary(shimDir, "symforge", "#!/bin/sh\nnode launcher\n");
  const resolvedBinary = path.join(
    prefix,
    "lib",
    "node_modules",
    "symforge-linux-x64",
    "bin",
    "symforge"
  );

  const errors = [];
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: { PATH: shimDir },
    },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });

  assert.equal(launcher.main([]), 0);
  assert.deepEqual(errors, []);
  // Sanity: the shim really is the first PATH entry and a different path than
  // the resolved binary, so the "no warn" result is from shim recognition, not
  // an empty PATH.
  assert.notEqual(path.resolve(shim), path.resolve(resolvedBinary));
});

test("launcher does NOT warn when the resolved native binary is itself first on PATH", (t) => {
  const root = tmpDir(t, "symforge-self-warn-");
  const binDir = path.join(root, "bin");
  const resolvedBinary = writeFakeBinary(binDir, "symforge");
  const selfDir = path.join(root, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });

  const errors = [];
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: { PATH: binDir },
    },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });

  assert.equal(launcher.main([]), 0);
  assert.deepEqual(errors, []);
});

// Build a real npm-global-shaped install under `prefix`: the package's bin dir
// holds symforge.js, and `<prefix>/bin/symforge` is a symlink to it (skips the
// test where the OS refuses symlinks).
function linkedInstall(t, prefix) {
  const selfDir = path.join(prefix, "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  fs.writeFileSync(path.join(selfDir, "symforge.js"), "// launcher\n");
  const binDir = path.join(prefix, "bin");
  fs.mkdirSync(binDir, { recursive: true });
  const link = path.join(binDir, "symforge");
  try {
    fs.symlinkSync(path.join(selfDir, "symforge.js"), link);
  } catch (err) {
    t.skip(`symlinks unavailable: ${err.code}`);
    return null;
  }
  return { selfDir, binDir, link };
}

function runLauncher(selfDir, pathDirs, resolvedBinary) {
  const errors = [];
  const launcher = createLauncher({
    process: { platform: "linux", arch: "x64", env: { PATH: pathDirs.join(path.delimiter) } },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });
  assert.equal(launcher.main([]), 0);
  return errors;
}

test("launcher does NOT flag itself when first on PATH through a symlinked bin", (t) => {
  const root = tmpDir(t, "symforge-selflink-");
  // The prefix is NOT the npm-configured one and the shim text never names the
  // package, so only the realpath comparison can prove this is the launcher.
  const install = linkedInstall(t, path.join(root, ".npm-global"));
  if (!install) return;
  const resolvedBinary = path.join(root, ".npm-global", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  assert.deepEqual(runLauncher(install.selfDir, [install.binDir], resolvedBinary), []);
});

test("launcher reached through a symlinked prefix does not flag itself", (t) => {
  const root = tmpDir(t, "symforge-prefixlink-");
  const install = linkedInstall(t, path.join(root, "real-prefix"));
  if (!install) return;
  const aliasPrefix = path.join(root, "alias-prefix");
  try {
    fs.symlinkSync(path.join(root, "real-prefix"), aliasPrefix, "dir");
  } catch (err) {
    t.skip(`symlinks unavailable: ${err.code}`);
    return;
  }
  const resolvedBinary = path.join(root, "real-prefix", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  assert.deepEqual(runLauncher(install.selfDir, [path.join(aliasPrefix, "bin")], resolvedBinary), []);
});

test("a genuinely different first copy still warns even when this launcher is also on PATH", (t) => {
  const root = tmpDir(t, "symforge-twocopies-");
  const mine = linkedInstall(t, path.join(root, "mine"));
  if (!mine) return;
  const other = linkedInstall(t, path.join(root, "other"));
  if (!other) return;
  const resolvedBinary = path.join(root, "mine", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  const errors = runLauncher(mine.selfDir, [other.binDir, mine.binDir], resolvedBinary);
  const joined = errors.join("\n");
  assert.match(joined, /different 'symforge'/);
  assert.ok(joined.includes(other.link), joined);
});

test("SYMFORGE_NO_SHADOW_WARN suppresses the warning entirely", (t) => {
  const root = tmpDir(t, "symforge-suppress-");
  const shadowDir = path.join(root, "usr", "local", "bin");
  writeFakeBinary(shadowDir, "symforge");
  const selfDir = path.join(root, "home", "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const resolvedBinary = path.join(root, "home", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  const errors = [];
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: { PATH: shadowDir, SYMFORGE_NO_SHADOW_WARN: "1" },
    },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });

  assert.equal(launcher.main([]), 0);
  assert.deepEqual(errors, []);
});

test("the shadow warning never writes to stdout", (t) => {
  const root = tmpDir(t, "symforge-stdout-");
  const shadowDir = path.join(root, "usr", "local", "bin");
  writeFakeBinary(shadowDir, "symforge");
  const selfDir = path.join(root, "home", "lib", "node_modules", "symforge", "bin");
  fs.mkdirSync(selfDir, { recursive: true });
  const resolvedBinary = path.join(root, "home", "lib", "node_modules", "symforge-linux-x64", "bin", "symforge");

  const stdoutChunks = [];
  const originalWrite = process.stdout.write;
  process.stdout.write = (chunk, ...rest) => {
    stdoutChunks.push(String(chunk));
    return originalWrite.call(process.stdout, chunk, ...rest);
  };
  t.after(() => {
    process.stdout.write = originalWrite;
  });

  // Real console.error is used here so it would hit stderr (not captured),
  // proving the warning path does not leak onto stdout.
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: { PATH: shadowDir },
    },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: resolvedBinary };
    },
    spawnSync() {
      return { status: 0 };
    },
  });

  assert.equal(launcher.main([]), 0);
  assert.equal(stdoutChunks.join(""), "");
});

test("a thrown error inside the shadow check does not prevent spawn", (t) => {
  const selfDir = path.join(os.tmpdir(), "symforge-throw-self");
  const spawnCalls = [];

  // Force whichAllSymforge to throw by handing it a PATH getter that explodes.
  const explodingEnv = {};
  Object.defineProperty(explodingEnv, "PATH", {
    enumerable: true,
    get() {
      throw new Error("boom: PATH access exploded");
    },
  });

  const errors = [];
  const launcher = createLauncher({
    process: {
      platform: "linux",
      arch: "x64",
      env: explodingEnv,
    },
    console: { error: (message) => errors.push(message) },
    selfDir,
    resolveBinary() {
      return { reason: "ok", binaryPath: "/some/native/symforge" };
    },
    spawnSync(command, args, options) {
      spawnCalls.push({ command, args, options });
      return { status: 0 };
    },
  });

  // Spawn still happens and the exit status is returned despite the thrown
  // detection error.
  assert.equal(launcher.main(["--version"]), 0);
  assert.equal(spawnCalls.length, 1);
  assert.equal(spawnCalls[0].command, "/some/native/symforge");
});