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

package/dist/helpers/instructions.js

@@ -0,0 +1,175 @@
+"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.resolve_instructions = exports.builtin_notice = exports.fetch_instructions = exports.write_cache = exports.read_cache = exports.cache_path = exports.github_url = void 0;
+// The nram server is the canonical source of the agent instructions: it
+// serves them at the public, unauthenticated `GET /instructions` endpoint
+// (`format=agents` for the full text, `format=cursor` for the condensed
+// rules). This module owns fetching that text, caching the last good copy on
+// the machine, and degrading gracefully when nothing is reachable.
+//
+// It deliberately imports only Node built-ins and the dependency-free file
+// helpers from upsert.ts, so the `--session-start` hook path (run at every
+// agent session start) stays cheap to load.
+const os_1 = require("os");
+const path_1 = require("path");
+const upsert_1 = require("./upsert");
+/** Maps our format names onto the server's `?format=` query values */
+const SERVER_FORMATS = {
+    full: 'agents',
+    condensed: 'cursor'
+};
+/** The upstream source files, used when the configured server is unreachable */
+const GITHUB_FILES = {
+    full: 'agent-instructions.md',
+    condensed: 'cursor.md'
+};
+const DEFAULT_GITHUB_BASE = 'https://raw.githubusercontent.com/nram-ai/nram/refs/heads/master/internal/instructions/data';
+/**
+ * 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
+ */
+const github_url = (format) => `${process.env.NRAM_INSTRUCTIONS_FALLBACK_BASE ?? DEFAULT_GITHUB_BASE}/${GITHUB_FILES[format]}`;
+exports.github_url = github_url;
+/**
+ * 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
+ */
+const cache_path = (format) => (0, path_1.join)(process.env.NRAM_CACHE_DIR ?? (0, path_1.join)((0, os_1.homedir)(), '.nram', 'cache'), `instructions-${format}.md`);
+exports.cache_path = cache_path;
+/**
+ * Reads the cached copy of the given format, returning undefined when there
+ * is none (or it cannot be read)
+ *
+ * @param format the instructions format
+ */
+const read_cache = (format) => {
+    try {
+        const text = (0, upsert_1.read_text)((0, exports.cache_path)(format));
+        return text.length !== 0 ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+exports.read_cache = read_cache;
+/**
+ * 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
+ */
+const write_cache = (format, text) => {
+    try {
+        (0, upsert_1.write_text)((0, exports.cache_path)(format), text);
+    }
+    catch {
+        // a read-only home directory must not break the fallback chain
+    }
+};
+exports.write_cache = write_cache;
+/**
+ * Fetches a URL expected to return plain-text instructions, throwing on any
+ * HTTP error, timeout, or empty body
+ *
+ * @param url the URL to fetch
+ * @param timeout_ms the request timeout in milliseconds
+ */
+const fetch_text = async (url, timeout_ms) => {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeout_ms) });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status} from ${url}`);
+    }
+    const text = await response.text();
+    if (text.trim().length === 0) {
+        throw new Error(`empty response from ${url}`);
+    }
+    return text;
+};
+/**
+ * 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
+ */
+const fetch_instructions = async (base_url, format, timeout_ms) => fetch_text(`${base_url}/instructions?format=${SERVER_FORMATS[format]}`, timeout_ms);
+exports.fetch_instructions = fetch_instructions;
+/**
+ * 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
+ */
+const builtin_notice = (format) => format === 'full'
+    ? 'Memory (nram): the canonical nram agent instructions could not be loaded from the configured nram ' +
+        'server, the local cache, or the GitHub fallback. Inform the user that the nram instructions failed to ' +
+        'load and suggest re-running `npx -y @nram-ai/setup-agents` once their nram server is reachable. ' +
+        'nram remains the only memory system: recall before assuming, store what you learn, and never write ' +
+        'local memory files.'
+    : 'Memory (nram): the canonical nram rules could not be loaded from the nram server, the local cache, or ' +
+        'the GitHub fallback. Inform the user and suggest re-running `npx -y @nram-ai/setup-agents` once their ' +
+        'nram server is reachable. nram remains the only memory system; never write local memory files.';
+exports.builtin_notice = builtin_notice;
+/**
+ * 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
+ */
+const resolve_instructions = async (base_url, format, timeout_ms) => {
+    if (base_url !== undefined) {
+        try {
+            const text = await (0, exports.fetch_instructions)(base_url, format, timeout_ms);
+            (0, exports.write_cache)(format, text);
+            return { text, source: 'server' };
+        }
+        catch {
+            // fall through to the cache
+        }
+    }
+    const cached = (0, exports.read_cache)(format);
+    if (cached !== undefined) {
+        return { text: cached, source: 'cache' };
+    }
+    try {
+        const text = await fetch_text((0, exports.github_url)(format), timeout_ms);
+        (0, exports.write_cache)(format, text);
+        return { text, source: 'github' };
+    }
+    catch {
+        return { text: (0, exports.builtin_notice)(format), source: 'builtin' };
+    }
+};
+exports.resolve_instructions = resolve_instructions;
+//# sourceMappingURL=instructions.js.map

package/dist/helpers/instructions.js.map

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

package/dist/helpers/paths.d.ts

@@ -0,0 +1,130 @@
+import { Scope } from '../types';
+/**
+ * Returns the Claude Code configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const claude_dir: (scope: Scope) => string;
+/**
+ * Returns the Codex home directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const codex_dir: (scope: Scope) => string;
+/**
+ * Returns the OpenCode configuration directory for the given scope
+ *
+ * Note: OpenCode documents `~/.config/opencode` as the global location on all
+ * platforms; `XDG_CONFIG_HOME` is honored when set. At project scope, OpenCode
+ * reads `opencode.json` and `AGENTS.md` from the repository root.
+ *
+ * @param scope the configuration scope
+ */
+export declare const opencode_dir: (scope: Scope) => string;
+/**
+ * Returns the Cursor configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const cursor_dir: (scope: Scope) => string;
+/**
+ * Returns the Amp configuration directory for the given scope; Amp documents
+ * `~/.config/amp` on every platform, including `%USERPROFILE%\.config\amp`
+ * on Windows
+ *
+ * @param scope the configuration scope
+ */
+export declare const amp_dir: (scope: Scope) => string;
+/**
+ * Returns the Google Antigravity configuration directory (user level only;
+ * Antigravity documents project-local MCP config as read-but-ignored)
+ */
+export declare const antigravity_dir: () => string;
+/**
+ * Returns the shared `~/.gemini` directory, where Antigravity reads the
+ * cross-tool AGENTS.md (GEMINI.md is avoided deliberately: both Antigravity
+ * and Gemini CLI write it, a documented conflict)
+ */
+export declare const gemini_dir: () => string;
+/**
+ * Returns the OpenClaw state directory (user level only; the gateway has no
+ * project-scoped configuration)
+ */
+export declare const openclaw_dir: () => string;
+/**
+ * Returns the GitHub Copilot CLI configuration directory (user level only
+ * for MCP; honors COPILOT_HOME)
+ */
+export declare const copilot_dir: () => string;
+/**
+ * Returns the Factory (droid) configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const factory_dir: (scope: Scope) => string;
+/**
+ * Returns the Hermes configuration directory (user level only; Hermes has no
+ * project-scoped configuration)
+ */
+export declare const hermes_dir: () => string;
+/**
+ * Returns the JetBrains Junie configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const junie_dir: (scope: Scope) => string;
+/**
+ * Returns the Kilo Code configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const kilo_dir: (scope: Scope) => string;
+/**
+ * Returns the Kimi Code CLI configuration directory (user level only; no
+ * project-scoped configuration is documented)
+ */
+export declare const kimi_dir: () => string;
+/**
+ * Returns the Kiro configuration directory for the given scope (honors
+ * KIRO_HOME at user scope)
+ *
+ * @param scope the configuration scope
+ */
+export declare const kiro_dir: (scope: Scope) => string;
+/**
+ * Returns the Pi coding agent configuration directory (user level; Pi keeps
+ * its agent state under `~/.pi/agent`)
+ */
+export declare const pi_dir: () => string;
+/**
+ * Returns the Vibe (Mistral) home directory for the given scope (honors
+ * VIBE_HOME at user scope)
+ *
+ * @param scope the configuration scope
+ */
+export declare const vibe_dir: (scope: Scope) => string;
+/**
+ * Returns the Grok Build configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const grok_dir: (scope: Scope) => string;
+/**
+ * Returns the Trae configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+export declare const trae_dir: (scope: Scope) => string;
+/**
+ * Resolves the AGENTS.md a harness reads: its own user-level file at user
+ * scope, the shared repository-root AGENTS.md at project scope (where all
+ * AGENTS.md-reading harnesses dedupe into one marker block)
+ *
+ * @param scope the configuration scope
+ * @param user_file the harness's user-level instructions file
+ */
+export declare const agents_md_path: (scope: Scope, user_file: string) => string;
+/**
+ * Returns the VS Code user profile directory per platform
+ */
+export declare const vscode_user_dir: () => string;

package/dist/helpers/paths.js

@@ -0,0 +1,211 @@
+"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.vscode_user_dir = exports.agents_md_path = exports.trae_dir = exports.grok_dir = exports.vibe_dir = exports.pi_dir = exports.kiro_dir = exports.kimi_dir = exports.kilo_dir = exports.junie_dir = exports.hermes_dir = exports.factory_dir = exports.copilot_dir = exports.openclaw_dir = exports.gemini_dir = exports.antigravity_dir = exports.amp_dir = exports.cursor_dir = exports.opencode_dir = exports.codex_dir = exports.claude_dir = void 0;
+const os_1 = require("os");
+const path_1 = require("path");
+const types_1 = require("../types");
+/**
+ * Resolved per call (homedir() consults USERPROFILE/HOME at call time) so
+ * tests can redirect the home directory through the environment
+ */
+const user_home = () => (0, os_1.homedir)();
+/**
+ * The XDG configuration root (`$XDG_CONFIG_HOME` else `~/.config`)
+ */
+const xdg_config = () => process.env.XDG_CONFIG_HOME ?? (0, path_1.resolve)(user_home(), '.config');
+/**
+ * Returns the Claude Code configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const claude_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(process.env.CLAUDE_CONFIG_DIR ?? (0, path_1.resolve)(user_home(), '.claude'))
+    : (0, path_1.resolve)(process.cwd(), '.claude');
+exports.claude_dir = claude_dir;
+/**
+ * Returns the Codex home directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const codex_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(process.env.CODEX_HOME ?? (0, path_1.resolve)(user_home(), '.codex'))
+    : (0, path_1.resolve)(process.cwd(), '.codex');
+exports.codex_dir = codex_dir;
+/**
+ * Returns the OpenCode configuration directory for the given scope
+ *
+ * Note: OpenCode documents `~/.config/opencode` as the global location on all
+ * platforms; `XDG_CONFIG_HOME` is honored when set. At project scope, OpenCode
+ * reads `opencode.json` and `AGENTS.md` from the repository root.
+ *
+ * @param scope the configuration scope
+ */
+const opencode_dir = (scope) => scope === types_1.Scope.USER ? (0, path_1.resolve)(xdg_config(), 'opencode') : (0, path_1.resolve)(process.cwd());
+exports.opencode_dir = opencode_dir;
+/**
+ * Returns the Cursor configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const cursor_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(user_home(), '.cursor')
+    : (0, path_1.resolve)(process.cwd(), '.cursor');
+exports.cursor_dir = cursor_dir;
+/**
+ * Returns the Amp configuration directory for the given scope; Amp documents
+ * `~/.config/amp` on every platform, including `%USERPROFILE%\.config\amp`
+ * on Windows
+ *
+ * @param scope the configuration scope
+ */
+const amp_dir = (scope) => scope === types_1.Scope.USER ? (0, path_1.resolve)(xdg_config(), 'amp') : (0, path_1.resolve)(process.cwd(), '.amp');
+exports.amp_dir = amp_dir;
+/**
+ * Returns the Google Antigravity configuration directory (user level only;
+ * Antigravity documents project-local MCP config as read-but-ignored)
+ */
+const antigravity_dir = () => (0, path_1.resolve)(user_home(), '.gemini', 'antigravity');
+exports.antigravity_dir = antigravity_dir;
+/**
+ * Returns the shared `~/.gemini` directory, where Antigravity reads the
+ * cross-tool AGENTS.md (GEMINI.md is avoided deliberately: both Antigravity
+ * and Gemini CLI write it, a documented conflict)
+ */
+const gemini_dir = () => (0, path_1.resolve)(user_home(), '.gemini');
+exports.gemini_dir = gemini_dir;
+/**
+ * Returns the OpenClaw state directory (user level only; the gateway has no
+ * project-scoped configuration)
+ */
+const openclaw_dir = () => (0, path_1.resolve)(user_home(), '.openclaw');
+exports.openclaw_dir = openclaw_dir;
+/**
+ * Returns the GitHub Copilot CLI configuration directory (user level only
+ * for MCP; honors COPILOT_HOME)
+ */
+const copilot_dir = () => (0, path_1.resolve)(process.env.COPILOT_HOME ?? (0, path_1.resolve)(user_home(), '.copilot'));
+exports.copilot_dir = copilot_dir;
+/**
+ * Returns the Factory (droid) configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const factory_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(user_home(), '.factory')
+    : (0, path_1.resolve)(process.cwd(), '.factory');
+exports.factory_dir = factory_dir;
+/**
+ * Returns the Hermes configuration directory (user level only; Hermes has no
+ * project-scoped configuration)
+ */
+const hermes_dir = () => (0, path_1.resolve)(user_home(), '.hermes');
+exports.hermes_dir = hermes_dir;
+/**
+ * Returns the JetBrains Junie configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const junie_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(user_home(), '.junie')
+    : (0, path_1.resolve)(process.cwd(), '.junie');
+exports.junie_dir = junie_dir;
+/**
+ * Returns the Kilo Code configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const kilo_dir = (scope) => scope === types_1.Scope.USER ? (0, path_1.resolve)(xdg_config(), 'kilo') : (0, path_1.resolve)(process.cwd(), '.kilo');
+exports.kilo_dir = kilo_dir;
+/**
+ * Returns the Kimi Code CLI configuration directory (user level only; no
+ * project-scoped configuration is documented)
+ */
+const kimi_dir = () => (0, path_1.resolve)(user_home(), '.kimi');
+exports.kimi_dir = kimi_dir;
+/**
+ * Returns the Kiro configuration directory for the given scope (honors
+ * KIRO_HOME at user scope)
+ *
+ * @param scope the configuration scope
+ */
+const kiro_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(process.env.KIRO_HOME ?? (0, path_1.resolve)(user_home(), '.kiro'))
+    : (0, path_1.resolve)(process.cwd(), '.kiro');
+exports.kiro_dir = kiro_dir;
+/**
+ * Returns the Pi coding agent configuration directory (user level; Pi keeps
+ * its agent state under `~/.pi/agent`)
+ */
+const pi_dir = () => (0, path_1.resolve)(user_home(), '.pi', 'agent');
+exports.pi_dir = pi_dir;
+/**
+ * Returns the Vibe (Mistral) home directory for the given scope (honors
+ * VIBE_HOME at user scope)
+ *
+ * @param scope the configuration scope
+ */
+const vibe_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(process.env.VIBE_HOME ?? (0, path_1.resolve)(user_home(), '.vibe'))
+    : (0, path_1.resolve)(process.cwd(), '.vibe');
+exports.vibe_dir = vibe_dir;
+/**
+ * Returns the Grok Build configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const grok_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(user_home(), '.grok')
+    : (0, path_1.resolve)(process.cwd(), '.grok');
+exports.grok_dir = grok_dir;
+/**
+ * Returns the Trae configuration directory for the given scope
+ *
+ * @param scope the configuration scope
+ */
+const trae_dir = (scope) => scope === types_1.Scope.USER
+    ? (0, path_1.resolve)(user_home(), '.trae')
+    : (0, path_1.resolve)(process.cwd(), '.trae');
+exports.trae_dir = trae_dir;
+/**
+ * Resolves the AGENTS.md a harness reads: its own user-level file at user
+ * scope, the shared repository-root AGENTS.md at project scope (where all
+ * AGENTS.md-reading harnesses dedupe into one marker block)
+ *
+ * @param scope the configuration scope
+ * @param user_file the harness's user-level instructions file
+ */
+const agents_md_path = (scope, user_file) => scope === types_1.Scope.USER ? user_file : (0, path_1.resolve)(process.cwd(), 'AGENTS.md');
+exports.agents_md_path = agents_md_path;
+/**
+ * Returns the VS Code user profile directory per platform
+ */
+const vscode_user_dir = () => {
+    if (process.platform === 'win32') {
+        return (0, path_1.resolve)(process.env.APPDATA ?? (0, path_1.resolve)(user_home(), 'AppData', 'Roaming'), 'Code', 'User');
+    }
+    if (process.platform === 'darwin') {
+        return (0, path_1.resolve)(user_home(), 'Library', 'Application Support', 'Code', 'User');
+    }
+    return (0, path_1.resolve)(xdg_config(), 'Code', 'User');
+};
+exports.vscode_user_dir = vscode_user_dir;
+//# sourceMappingURL=paths.js.map

package/dist/helpers/paths.js.map

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