@nram-ai/setup-agents 0.0.1-pre.0

package/dist/helpers/configure/trae.js

@@ -0,0 +1,63 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_trae = void 0;
+const path_1 = require("path");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Configures Trae (ByteDance): writes the agent instructions as a project
+ * rules file. Trae's MCP config schema could not be verified against
+ * accessible documentation, so MCP registration is reported as a manual
+ * step through Trae's own UI rather than risking a guessed write; the
+ * user-level rules location is likewise undocumented
+ *
+ * @param options the collected setup options
+ */
+const configure_trae = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        results.push({
+            action: 'MCP registration',
+            kind: 'manual',
+            detail: 'Trae\'s MCP config file schema is not verifiable against accessible docs; add the server ' +
+                `through Trae's UI (MCP, Add) with the URL ${options.mcp_url}`
+        });
+    }
+    if (options.instructions) {
+        if (options.scope !== types_1.Scope.PROJECT) {
+            results.push({
+                action: 'Agent instructions',
+                kind: 'skipped',
+                detail: 'Trae user-level rules are managed through the IDE UI (no documented file path); ' +
+                    'rerun at project scope to write .trae/rules/nram.md'
+            });
+        }
+        else {
+            const rule_path = (0, path_1.resolve)((0, paths_1.trae_dir)(options.scope), 'rules', 'nram.md');
+            results.push((0, upsert_1.upsert_own_file)(rule_path, options.instructions.condensed, 'Agent instructions'));
+        }
+    }
+    return results;
+};
+exports.configure_trae = configure_trae;
+//# sourceMappingURL=trae.js.map

package/dist/helpers/configure/trae.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trae.js","sourceRoot":"","sources":["../../../src/helpers/configure/trae.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ,+BAA+B;AAC/B,uCAAgE;AAChE,oCAAoC;AACpC,sCAA4C;AAE5C;;;;;;;;GAQG;AACI,MAAM,cAAc,GAAG,KAAK,EAAE,OAAqB,EAA2B,EAAE;IACnF,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,OAAO,CAAC,IAAI,CAAC;YACT,MAAM,EAAE,kBAAkB;YAC1B,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,2FAA2F;gBAC/F,6CAA6C,OAAO,CAAC,OAAO,EAAE;SACrE,CAAC,CAAC;IACP,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACvB,IAAI,OAAO,CAAC,KAAK,KAAK,aAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC;gBACT,MAAM,EAAE,oBAAoB;gBAC5B,IAAI,EAAE,SAAS;gBACf,MAAM,EAAE,kFAAkF;oBACtF,qDAAqD;aAC5D,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,MAAM,SAAS,GAAG,IAAA,cAAO,EAAC,IAAA,gBAAQ,EAAC,OAAO,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;YAEvE,OAAO,CAAC,IAAI,CAAC,IAAA,wBAAe,EAAC,SAAS,EAAE,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC,CAAC;QACnG,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AA5BW,QAAA,cAAc,kBA4BzB"}

package/dist/helpers/configure/vibe.d.ts

@@ -0,0 +1,24 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the marker-fenced `[[mcp_servers]]` TOML block. nram serves MCP over
+ * streamable HTTP, so the matching Vibe transport is declared explicitly. In
+ * API-key mode the key itself is never written to disk; Vibe's documented
+ * `api_key_env` substitution references the NRAM_API_KEY environment variable
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+export declare const vibe_mcp_block: (mcp_url: string, api_key?: string) => string;
+/**
+ * Configures Vibe (Mistral): upserts a marker-fenced `[[mcp_servers]]` block
+ * in config.toml and the agent instructions into the AGENTS.md Vibe reads
+ * (`~/.vibe/AGENTS.md` at user scope, the repository root at project scope).
+ *
+ * Vibe reads exactly ONE config.toml (`./.vibe/config.toml` when present,
+ * else `~/.vibe/config.toml` as a whole-file fallback, never a merge), so a
+ * project config.toml is only ever updated, not created: creating one would
+ * silently shadow everything in the user-level file
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_vibe: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/vibe.js

@@ -0,0 +1,106 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_vibe = exports.vibe_mcp_block = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const smol_toml_1 = require("smol-toml");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Returns whether the parsed config carries an `[[mcp_servers]]` entry named
+ * `nram` (Vibe keys its MCP servers as an array of tables, not a keyed table)
+ *
+ * @param parsed the parsed config.toml
+ */
+const has_nram_entry = (parsed) => Array.isArray(parsed?.mcp_servers) &&
+    parsed.mcp_servers.some((server) => server?.name === 'nram');
+/**
+ * Builds the marker-fenced `[[mcp_servers]]` TOML block. nram serves MCP over
+ * streamable HTTP, so the matching Vibe transport is declared explicitly. In
+ * API-key mode the key itself is never written to disk; Vibe's documented
+ * `api_key_env` substitution references the NRAM_API_KEY environment variable
+ *
+ * @param mcp_url the MCP endpoint URL
+ * @param api_key the API key, when API-key authentication was chosen
+ */
+const vibe_mcp_block = (mcp_url, api_key) => {
+    const lines = [
+        '[[mcp_servers]]',
+        'name = "nram"',
+        'transport = "streamable-http"',
+        `url = "${mcp_url}"`
+    ];
+    if (api_key !== undefined) {
+        lines.push('api_key_env = "NRAM_API_KEY"', 'api_key_header = "Authorization"', 'api_key_format = "Bearer {token}"');
+    }
+    return lines.join('\n');
+};
+exports.vibe_mcp_block = vibe_mcp_block;
+/**
+ * Configures Vibe (Mistral): upserts a marker-fenced `[[mcp_servers]]` block
+ * in config.toml and the agent instructions into the AGENTS.md Vibe reads
+ * (`~/.vibe/AGENTS.md` at user scope, the repository root at project scope).
+ *
+ * Vibe reads exactly ONE config.toml (`./.vibe/config.toml` when present,
+ * else `~/.vibe/config.toml` as a whole-file fallback, never a merge), so a
+ * project config.toml is only ever updated, not created: creating one would
+ * silently shadow everything in the user-level file
+ *
+ * @param options the collected setup options
+ */
+const configure_vibe = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        const config_path = (0, path_1.resolve)((0, paths_1.vibe_dir)(options.scope), 'config.toml');
+        if (options.scope === types_1.Scope.PROJECT && !(0, fs_1.existsSync)(config_path)) {
+            results.push({
+                action: 'MCP registration',
+                kind: 'manual',
+                detail: `refusing to create ${config_path}: Vibe reads one config.toml, and a new project ` +
+                    'file would shadow the user-level one entirely; if you want a project config, create ' +
+                    'it yourself and re-run, or add this block to it:\n' +
+                    (0, exports.vibe_mcp_block)(options.mcp_url, options.api_key)
+            });
+        }
+        else {
+            const mcp = (0, upsert_1.upsert_block_with_validation)(config_path, (0, exports.vibe_mcp_block)(options.mcp_url, options.api_key), smol_toml_1.parse, 'TOML', (parsed, text) => has_nram_entry(parsed) && !(0, upsert_1.has_marker_block)(text, 'hash')
+                ? {
+                    action: 'MCP registration',
+                    kind: 'skipped',
+                    detail: `an [[mcp_servers]] entry named "nram" already exists in ${config_path} ` +
+                        '(outside the nram setup markers)'
+                }
+                : undefined, has_nram_entry);
+            results.push(mcp);
+            if ((mcp.kind === 'written' || mcp.kind === 'updated') && options.api_key !== undefined) {
+                results.push((0, upsert_1.api_key_manual_result)());
+            }
+        }
+    }
+    if (options.instructions) {
+        results.push((0, upsert_1.agents_md_result)((0, paths_1.agents_md_path)(options.scope, (0, path_1.resolve)((0, paths_1.vibe_dir)(options.scope), 'AGENTS.md')), options.instructions.full));
+    }
+    return results;
+};
+exports.configure_vibe = configure_vibe;
+//# sourceMappingURL=vibe.js.map

package/dist/helpers/configure/vibe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vibe.js","sourceRoot":"","sources":["../../../src/helpers/configure/vibe.ts"],"names":[],"mappings":"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"}

package/dist/helpers/configure/vscode.d.ts

@@ -0,0 +1,18 @@
+import { ActionResult, SetupOptions } from '../../types';
+/**
+ * Builds the instructions file VS Code loads for Copilot
+ * (`applyTo: '**'` front matter applies it to every request)
+ *
+ * @param instructions the agent instructions text
+ */
+export declare const vscode_instruction_file: (instructions: string) => string;
+/**
+ * Configures VS Code (Copilot agent mode): merges the nram MCP server into
+ * the project `.vscode/mcp.json` (the user-profile mcp.json filename is not
+ * documented, so user scope reports the Command Palette path instead) and
+ * writes the agent instructions as an `*.instructions.md` file in the
+ * profile prompts dir (user) or `.github/instructions` (project)
+ *
+ * @param options the collected setup options
+ */
+export declare const configure_vscode: (options: SetupOptions) => Promise<ActionResult[]>;

package/dist/helpers/configure/vscode.js

@@ -0,0 +1,81 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configure_vscode = exports.vscode_instruction_file = void 0;
+const path_1 = require("path");
+const types_1 = require("../../types");
+const paths_1 = require("../paths");
+const upsert_1 = require("../upsert");
+/**
+ * Builds the instructions file VS Code loads for Copilot
+ * (`applyTo: '**'` front matter applies it to every request)
+ *
+ * @param instructions the agent instructions text
+ */
+const vscode_instruction_file = (instructions) => '---\n' +
+    'applyTo: \'**\'\n' +
+    'description: nram (Neural Ram) persistent memory protocol\n' +
+    '---\n\n' +
+    `${instructions.trimEnd()}\n`;
+exports.vscode_instruction_file = vscode_instruction_file;
+/**
+ * Configures VS Code (Copilot agent mode): merges the nram MCP server into
+ * the project `.vscode/mcp.json` (the user-profile mcp.json filename is not
+ * documented, so user scope reports the Command Palette path instead) and
+ * writes the agent instructions as an `*.instructions.md` file in the
+ * profile prompts dir (user) or `.github/instructions` (project)
+ *
+ * @param options the collected setup options
+ */
+const configure_vscode = async (options) => {
+    const results = [];
+    if (options.mcp_url !== undefined) {
+        if (options.scope !== types_1.Scope.PROJECT) {
+            results.push({
+                action: 'MCP registration',
+                kind: 'manual',
+                detail: 'VS Code keeps user-level MCP servers in a profile file with no documented path; run ' +
+                    'the "MCP: Open User Configuration" command in VS Code and add under "servers": ' +
+                    `"nram": { "type": "http", "url": "${options.mcp_url}" }`
+            });
+        }
+        else {
+            const config_path = (0, path_1.resolve)(process.cwd(), '.vscode', 'mcp.json');
+            const mcp = (0, upsert_1.mcp_json_result)(config_path, ['servers', 'nram'], {
+                type: 'http',
+                url: options.mcp_url
+            });
+            results.push(mcp);
+            if (mcp.kind !== 'manual' && options.api_key !== undefined) {
+                results.push((0, upsert_1.api_key_header_manual_result)(config_path));
+            }
+        }
+    }
+    if (options.instructions) {
+        const instructions_path = options.scope === types_1.Scope.USER
+            ? (0, path_1.resolve)((0, paths_1.vscode_user_dir)(), 'prompts', 'nram.instructions.md')
+            : (0, path_1.resolve)(process.cwd(), '.github', 'instructions', 'nram.instructions.md');
+        results.push((0, upsert_1.upsert_own_file)(instructions_path, (0, exports.vscode_instruction_file)(options.instructions.condensed), 'Agent instructions'));
+    }
+    return results;
+};
+exports.configure_vscode = configure_vscode;
+//# sourceMappingURL=vscode.js.map

package/dist/helpers/configure/vscode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vscode.js","sourceRoot":"","sources":["../../../src/helpers/configure/vscode.ts"],"names":[],"mappings":";AAAA,iEAAiE;AACjE,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;;;AAEZ,+BAA+B;AAC/B,uCAAgE;AAChE,oCAA2C;AAC3C,sCAA2F;AAE3F;;;;;GAKG;AACI,MAAM,uBAAuB,GAAG,CAAC,YAAoB,EAAU,EAAE,CACpE,OAAO;IACP,mBAAmB;IACnB,6DAA6D;IAC7D,SAAS;IACT,GAAG,YAAY,CAAC,OAAO,EAAE,IAAI,CAAC;AALrB,QAAA,uBAAuB,2BAKF;AAElC;;;;;;;;GAQG;AACI,MAAM,gBAAgB,GAAG,KAAK,EAAE,OAAqB,EAA2B,EAAE;IACrF,MAAM,OAAO,GAAmB,EAAE,CAAC;IAEnC,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,CAAC,KAAK,KAAK,aAAK,CAAC,OAAO,EAAE,CAAC;YAClC,OAAO,CAAC,IAAI,CAAC;gBACT,MAAM,EAAE,kBAAkB;gBAC1B,IAAI,EAAE,QAAQ;gBACd,MAAM,EAAE,sFAAsF;oBAC1F,iFAAiF;oBACjF,qCAAqC,OAAO,CAAC,OAAO,KAAK;aAChE,CAAC,CAAC;QACP,CAAC;aAAM,CAAC;YACJ,MAAM,WAAW,GAAG,IAAA,cAAO,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;YAElE,MAAM,GAAG,GAAG,IAAA,wBAAe,EAAC,WAAW,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE;gBAC1D,IAAI,EAAE,MAAM;gBACZ,GAAG,EAAE,OAAO,CAAC,OAAO;aACvB,CAAC,CAAC;YAEH,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YAElB,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBACzD,OAAO,CAAC,IAAI,CAAC,IAAA,qCAA4B,EAAC,WAAW,CAAC,CAAC,CAAC;YAC5D,CAAC;QACL,CAAC;IACL,CAAC;IAED,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;QACvB,MAAM,iBAAiB,GAAG,OAAO,CAAC,KAAK,KAAK,aAAK,CAAC,IAAI;YAClD,CAAC,CAAC,IAAA,cAAO,EAAC,IAAA,uBAAe,GAAE,EAAE,SAAS,EAAE,sBAAsB,CAAC;YAC/D,CAAC,CAAC,IAAA,cAAO,EAAC,OAAO,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,sBAAsB,CAAC,CAAC;QAEhF,OAAO,CAAC,IAAI,CACR,IAAA,wBAAe,EAAC,iBAAiB,EAAE,IAAA,+BAAuB,EAAC,OAAO,CAAC,YAAY,CAAC,SAAS,CAAC,EACtF,oBAAoB,CAAC,CAAC,CAAC;IACnC,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC,CAAC;AAvCW,QAAA,gBAAgB,oBAuC3B"}

package/dist/helpers/harnesses.d.ts

@@ -0,0 +1,8 @@
+import { Harness, HarnessDescriptor, Scope } from '../types';
+export { Harness, Scope };
+/**
+ * The harnesses this tool knows how to configure, ordered alphabetically by
+ * label, with per-scope detection: user scope checks the tool's home
+ * directory, project scope checks the tool's directory in the repository
+ */
+export declare const HARNESSES: HarnessDescriptor[];

package/dist/helpers/harnesses.js

@@ -0,0 +1,161 @@
+"use strict";
+// Copyright (c) 2026, Brandon Lehmann <brandonlehmann@gmail.com>
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HARNESSES = exports.Scope = exports.Harness = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const types_1 = require("../types");
+Object.defineProperty(exports, "Harness", { enumerable: true, get: function () { return types_1.Harness; } });
+Object.defineProperty(exports, "Scope", { enumerable: true, get: function () { return types_1.Scope; } });
+const paths_1 = require("./paths");
+const amp_1 = require("./configure/amp");
+const antigravity_1 = require("./configure/antigravity");
+const claude_code_1 = require("./configure/claude_code");
+const codex_1 = require("./configure/codex");
+const copilot_1 = require("./configure/copilot");
+const cursor_1 = require("./configure/cursor");
+const droid_1 = require("./configure/droid");
+const grok_1 = require("./configure/grok");
+const hermes_1 = require("./configure/hermes");
+const junie_1 = require("./configure/junie");
+const kilo_1 = require("./configure/kilo");
+const kimi_1 = require("./configure/kimi");
+const kiro_1 = require("./configure/kiro");
+const openclaw_1 = require("./configure/openclaw");
+const opencode_1 = require("./configure/opencode");
+const pi_1 = require("./configure/pi");
+const trae_1 = require("./configure/trae");
+const vibe_1 = require("./configure/vibe");
+const vscode_1 = require("./configure/vscode");
+/**
+ * The harnesses this tool knows how to configure, ordered alphabetically by
+ * label, with per-scope detection: user scope checks the tool's home
+ * directory, project scope checks the tool's directory in the repository
+ */
+exports.HARNESSES = [{
+        harness: types_1.Harness.AMP,
+        label: 'Amp',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.amp_dir)(scope)),
+        configure: amp_1.configure_amp
+    }, {
+        harness: types_1.Harness.GOOGLE_ANTIGRAVITY,
+        label: 'Antigravity',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, paths_1.antigravity_dir)())
+            : (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), '.agent')),
+        configure: antigravity_1.configure_antigravity
+    }, {
+        harness: types_1.Harness.ANTHROPIC_CLAUDE_CODE,
+        label: 'Claude Code',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.claude_dir)(scope)),
+        configure: claude_code_1.configure_claude_code
+    }, {
+        harness: types_1.Harness.OPENAI_CODEX,
+        label: 'Codex',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.codex_dir)(scope)),
+        configure: codex_1.configure_codex
+    }, {
+        harness: types_1.Harness.CURSOR,
+        label: 'Cursor',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.cursor_dir)(scope)),
+        configure: cursor_1.configure_cursor
+    }, {
+        harness: types_1.Harness.FACTORY_DROID,
+        label: 'Droid',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.factory_dir)(scope)),
+        configure: droid_1.configure_droid
+    }, {
+        harness: types_1.Harness.GITHUB_COPILOT_CLI,
+        label: 'GitHub Copilot CLI',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, paths_1.copilot_dir)())
+            : (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), '.github', 'copilot-instructions.md')),
+        configure: copilot_1.configure_copilot
+    }, {
+        harness: types_1.Harness.XAI_GROK_BUILD,
+        label: 'Grok Build',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.grok_dir)(scope)),
+        configure: grok_1.configure_grok
+    }, {
+        harness: types_1.Harness.HERMES,
+        label: 'Hermes',
+        detected: scope => scope === types_1.Scope.USER && (0, fs_1.existsSync)((0, paths_1.hermes_dir)()),
+        configure: hermes_1.configure_hermes
+    }, {
+        harness: types_1.Harness.JETBRAINS_JUNIE,
+        label: 'Junie',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.junie_dir)(scope)),
+        configure: junie_1.configure_junie
+    }, {
+        harness: types_1.Harness.KILO_CODE,
+        label: 'Kilo Code',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, paths_1.kilo_dir)(scope))
+            : (0, fs_1.existsSync)((0, paths_1.kilo_dir)(scope)) || (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), 'kilo.jsonc')),
+        configure: kilo_1.configure_kilo
+    }, {
+        harness: types_1.Harness.KIMI_CODE,
+        label: 'Kimi Code',
+        detected: scope => scope === types_1.Scope.USER && (0, fs_1.existsSync)((0, paths_1.kimi_dir)()),
+        configure: kimi_1.configure_kimi
+    }, {
+        harness: types_1.Harness.KIRO,
+        label: 'Kiro',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.kiro_dir)(scope)),
+        configure: kiro_1.configure_kiro
+    }, {
+        harness: types_1.Harness.OPENCLAW,
+        label: 'OpenClaw',
+        detected: scope => scope === types_1.Scope.USER && (0, fs_1.existsSync)((0, paths_1.openclaw_dir)()),
+        configure: openclaw_1.configure_openclaw
+    }, {
+        harness: types_1.Harness.OPENCODE,
+        label: 'OpenCode',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, paths_1.opencode_dir)(scope))
+            : (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), 'opencode.json')) || (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), '.opencode')),
+        configure: opencode_1.configure_opencode
+    }, {
+        harness: types_1.Harness.PI,
+        label: 'Pi',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, path_1.resolve)((0, paths_1.pi_dir)(), '..'))
+            : (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), '.pi')),
+        configure: pi_1.configure_pi
+    }, {
+        harness: types_1.Harness.TRAE,
+        label: 'Trae',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.trae_dir)(scope)),
+        configure: trae_1.configure_trae
+    }, {
+        harness: types_1.Harness.MISTRAL_VIBE,
+        label: 'Vibe',
+        detected: scope => (0, fs_1.existsSync)((0, paths_1.vibe_dir)(scope)),
+        configure: vibe_1.configure_vibe
+    }, {
+        harness: types_1.Harness.VSCODE,
+        label: 'VS Code',
+        detected: scope => scope === types_1.Scope.USER
+            ? (0, fs_1.existsSync)((0, paths_1.vscode_user_dir)())
+            : (0, fs_1.existsSync)((0, path_1.resolve)(process.cwd(), '.vscode')),
+        configure: vscode_1.configure_vscode
+    }];
+//# sourceMappingURL=harnesses.js.map

package/dist/helpers/harnesses.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harnesses.js","sourceRoot":"","sources":["../../src/helpers/harnesses.ts"],"names":[],"mappings":"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"}

package/dist/helpers/instructions.d.ts

@@ -0,0 +1,63 @@
+export type Format = 'full' | 'condensed';
+export type InstructionsSource = 'server' | 'cache' | 'github' | 'builtin';
+/**
+ * The GitHub raw URL serving the fallback copy of the given format; the base
+ * is env-overridable so tests can stay off the network
+ *
+ * @param format the instructions format
+ */
+export declare const github_url: (format: Format) => string;
+/**
+ * The machine-local cache file holding the last successfully fetched copy of
+ * the given format; the directory is env-overridable so tests can isolate it
+ *
+ * @param format the instructions format
+ */
+export declare const cache_path: (format: Format) => string;
+/**
+ * Reads the cached copy of the given format, returning undefined when there
+ * is none (or it cannot be read)
+ *
+ * @param format the instructions format
+ */
+export declare const read_cache: (format: Format) => string | undefined;
+/**
+ * Caches a successfully fetched copy of the given format, creating the cache
+ * directory as needed; failures are swallowed because the cache is an
+ * optimization, never a requirement
+ *
+ * @param format the instructions format
+ * @param text the instructions text
+ */
+export declare const write_cache: (format: Format, text: string) => void;
+/**
+ * Fetches the canonical instructions from an nram server's public
+ * `/instructions` endpoint, throwing on failure
+ *
+ * @param base_url the normalized nram base URL
+ * @param format the instructions format
+ * @param timeout_ms the request timeout in milliseconds
+ */
+export declare const fetch_instructions: (base_url: string, format: Format, timeout_ms: number) => Promise<string>;
+/**
+ * The last-resort text emitted when the canonical instructions could not be
+ * loaded from anywhere; it tells the agent to surface the failure to the user
+ * instead of silently proceeding without the memory protocol
+ *
+ * @param format the instructions format
+ */
+export declare const builtin_notice: (format: Format) => string;
+/**
+ * Resolves the instructions text through the fallback chain: the configured
+ * server (skipped when no base URL is known), then the machine-local cache,
+ * then the GitHub raw copy, then the built-in notice. Any successful network
+ * fetch refreshes the cache. Never throws
+ *
+ * @param base_url the normalized nram base URL, or undefined to skip the server
+ * @param format the instructions format
+ * @param timeout_ms the per-attempt network timeout in milliseconds
+ */
+export declare const resolve_instructions: (base_url: string | undefined, format: Format, timeout_ms: number) => Promise<{
+    text: string;
+    source: InstructionsSource;
+}>;