@agentex/agent 0.0.20 → 0.0.22

package/dist/utils/instructions.js

@@ -1,4 +1,7 @@
 import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { createHash } from "node:crypto";
+import { getDefaultRuntimeHome } from "./runtime-homes.js";
 /**
  * Read an instructions file and return its content.
  * Returns null if no path is provided.
@@ -18,4 +21,249 @@ export async function resolveInstructions(filePath) {
         throw err;
     }
 }
+const RUNTIME_INSTRUCTIONS = {
+    claude: { projectFile: "CLAUDE.md", nativeFile: "CLAUDE.md", hasGlobalFile: true },
+    codex: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+    opencode: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+    gemini: { projectFile: "AGENTS.md", nativeFile: "GEMINI.md", hasGlobalFile: true },
+    cursor: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: false },
+    pi: { projectFile: "AGENTS.md", nativeFile: "AGENTS.md", hasGlobalFile: true },
+};
+const ALL_RUNTIMES = ["claude", "codex", "gemini", "cursor", "opencode", "pi"];
+const DEFAULT_MANAGED_TAG = "agentex";
+// ---------------------------------------------------------------------------
+// Path resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve which instruction files would be written for the given options,
+ * without touching disk.
+ *
+ * - "workspace": files dedupe by name under {cwd}/ (the default writes
+ *   CLAUDE.md + AGENTS.md once each). `includeNativeFiles` adds GEMINI.md.
+ * - "global": one file per runtime in each runtime's home dir. Runtimes without
+ *   a file-based global config (Cursor) are omitted.
+ */
+export function resolveInstructionTargets(options) {
+    const location = options?.location ?? "workspace";
+    const runtimes = dedupeRuntimes(options?.runtimes ?? ALL_RUNTIMES);
+    if (location === "workspace") {
+        const cwd = options?.cwd;
+        if (!cwd)
+            throw new Error("cwd is required when location is 'workspace'");
+        const byFile = new Map();
+        const add = (filename, runtime) => {
+            const list = byFile.get(filename) ?? [];
+            list.push(runtime);
+            byFile.set(filename, list);
+        };
+        for (const runtime of runtimes) {
+            const spec = RUNTIME_INSTRUCTIONS[runtime];
+            add(spec.projectFile, runtime);
+            if (options?.includeNativeFiles && spec.nativeFile !== spec.projectFile) {
+                add(spec.nativeFile, runtime);
+            }
+        }
+        return [...byFile.entries()].map(([filename, rts]) => ({
+            filename,
+            targetPath: path.join(cwd, filename),
+            runtimes: dedupeRuntimes(rts),
+        }));
+    }
+    // global: each runtime reads its own native file in its own home dir.
+    const targets = [];
+    for (const runtime of runtimes) {
+        const spec = RUNTIME_INSTRUCTIONS[runtime];
+        if (!spec.hasGlobalFile)
+            continue; // e.g. cursor global = app User Rules, not a file
+        const home = getDefaultRuntimeHome(runtime, options?.homeDir);
+        targets.push({
+            filename: spec.nativeFile,
+            targetPath: path.join(home, spec.nativeFile),
+            runtimes: [runtime],
+        });
+    }
+    return targets;
+}
+function dedupeRuntimes(runtimes) {
+    return [...new Set(runtimes)];
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Install an instruction brief into the right per-runtime files.
+ *
+ * By default merges `content` into a managed region of `{cwd}/CLAUDE.md` and
+ * `{cwd}/AGENTS.md`, preserving any user-authored content outside the markers.
+ * Idempotent: a re-install with unchanged content reports every entry as
+ * "skipped".
+ *
+ * @example
+ * ```ts
+ * // Workspace (repo-root) install — the common case.
+ * await installInstructions(brief, { location: "workspace", cwd: projectDir });
+ * // → {cwd}/CLAUDE.md + {cwd}/AGENTS.md
+ *
+ * // Also drop Gemini's native GEMINI.md (it doesn't read AGENTS.md by default).
+ * await installInstructions(brief, { location: "workspace", cwd, includeNativeFiles: true });
+ *
+ * // Global install — per-runtime home files.
+ * await installInstructions(brief, { location: "global" });
+ * // → ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...
+ * ```
+ */
+export async function installInstructions(content, options) {
+    const managed = options?.managed ?? true;
+    const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
+    const targets = resolveInstructionTargets(options);
+    const entries = [];
+    for (const target of targets) {
+        try {
+            const existing = await readFileOrNull(target.targetPath);
+            const next = managed
+                ? upsertManagedBlock(existing, content, { tag })
+                : ensureTrailingNewline(content);
+            let status;
+            if (existing === null) {
+                status = "created";
+            }
+            else if (existing === next) {
+                status = "skipped";
+            }
+            else {
+                status = "updated";
+            }
+            if (status !== "skipped") {
+                await fs.mkdir(path.dirname(target.targetPath), { recursive: true });
+                await fs.writeFile(target.targetPath, next, { mode: 0o644 });
+            }
+            entries.push({ ...target, status });
+        }
+        catch (err) {
+            entries.push({
+                ...target,
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return {
+        entries,
+        installed: entries.filter((e) => e.status === "created").length,
+        updated: entries.filter((e) => e.status === "updated").length,
+        skipped: entries.filter((e) => e.status === "skipped").length,
+        errors: entries.filter((e) => e.status === "error").length,
+    };
+}
+/**
+ * Remove the managed region installed by {@link installInstructions}, preserving
+ * any user-authored content outside the markers. If the file contains nothing
+ * but the managed block, it is deleted. User-owned files (no managed region) are
+ * left untouched and reported as "skipped".
+ */
+export async function removeInstructions(options) {
+    const tag = options?.managedTag ?? DEFAULT_MANAGED_TAG;
+    const targets = resolveInstructionTargets({
+        runtimes: options?.runtimes,
+        location: options?.location,
+        cwd: options?.cwd,
+        homeDir: options?.homeDir,
+    });
+    const entries = [];
+    for (const target of targets) {
+        try {
+            const existing = await readFileOrNull(target.targetPath);
+            if (existing === null) {
+                entries.push({ ...target, status: "not_found" });
+                continue;
+            }
+            const stripped = stripManagedBlock(existing, { tag });
+            if (stripped === existing) {
+                // No managed region present — never touch user-owned files.
+                entries.push({ ...target, status: "skipped" });
+                continue;
+            }
+            if (stripped === null) {
+                await fs.rm(target.targetPath, { force: true });
+            }
+            else {
+                await fs.writeFile(target.targetPath, stripped, { mode: 0o644 });
+            }
+            entries.push({ ...target, status: "removed" });
+        }
+        catch (err) {
+            entries.push({
+                ...target,
+                status: "error",
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return { entries, removed: entries.filter((e) => e.status === "removed").length };
+}
+// ---------------------------------------------------------------------------
+// Managed-region merge (exported for low-level use / hosts with custom layouts)
+// ---------------------------------------------------------------------------
+/**
+ * Merge `content` into `existing` as a managed region, preserving everything the
+ * user wrote outside the markers.
+ *
+ * - `existing` has a managed region → replace only the bytes between the markers.
+ * - `existing` has no markers → prepend the managed block, keep prior content below.
+ * - `existing` is null/empty → return just the managed block.
+ *
+ * The start marker embeds a short content hash, so re-running with identical
+ * content produces a byte-identical result (enabling cheap skip detection).
+ */
+export function upsertManagedBlock(existing, content, options) {
+    const tag = options?.tag ?? DEFAULT_MANAGED_TAG;
+    const block = buildManagedBlock(content, tag);
+    if (existing === null || existing.length === 0) {
+        return `${block}\n`;
+    }
+    const re = managedBlockRegex(tag);
+    if (re.test(existing)) {
+        return existing.replace(re, block);
+    }
+    // No managed region yet — prepend it, keep the user's file below.
+    return `${block}\n\n${existing.replace(/^\n+/, "")}`;
+}
+/**
+ * Remove the managed region (if any) from `existing`, preserving user content.
+ * Returns the cleaned string, the original string if there was no managed
+ * region, or null if nothing but the managed block remained.
+ */
+export function stripManagedBlock(existing, options) {
+    const tag = options?.tag ?? DEFAULT_MANAGED_TAG;
+    const re = managedBlockRegex(tag);
+    if (!re.test(existing))
+        return existing;
+    const stripped = existing.replace(re, "").replace(/^\n+/, "");
+    return stripped.trim().length === 0 ? null : stripped;
+}
+function buildManagedBlock(content, tag) {
+    const body = content.replace(/\s+$/, "");
+    const hash = createHash("sha256").update(body).digest("hex").slice(0, 12);
+    return `<!-- ${tag}:managed:start hash=${hash} -->\n${body}\n<!-- ${tag}:managed:end -->`;
+}
+function managedBlockRegex(tag) {
+    const t = escapeRegExp(tag);
+    return new RegExp(`<!--\\s*${t}:managed:start[^>]*-->[\\s\\S]*?<!--\\s*${t}:managed:end\\s*-->`);
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ensureTrailingNewline(s) {
+    return s.endsWith("\n") ? s : `${s}\n`;
+}
+async function readFileOrNull(filePath) {
+    try {
+        return await fs.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
 //# sourceMappingURL=instructions.js.map

package/dist/utils/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEvC;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAiB;IACzD,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,GAAI,GAA6B,CAAC,IAAI,CAAC;QACjD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CAAC,gCAAgC,QAAQ,EAAE,CAAC,CAAC;QAC9D,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/utils/instructions.ts"],"names":[],"mappings":"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"}

package/dist/utils/runtime-homes.d.ts

@@ -8,6 +8,9 @@ import type { SkillRuntime } from "./skills.js";
 export declare function getRuntimeHomeEnvVar(runtime: SkillRuntime): string | null;
 /**
  * Returns the default global home directory path for the given runtime.
+ *
+ * Pass `homeDir` to resolve against a base other than the user's real home
+ * directory (useful for sandboxed installs and tests). Defaults to os.homedir().
  */
-export declare function getDefaultRuntimeHome(runtime: SkillRuntime): string;
+export declare function getDefaultRuntimeHome(runtime: SkillRuntime, homeDir?: string): string;
 //# sourceMappingURL=runtime-homes.d.ts.map

package/dist/utils/runtime-homes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-homes.d.ts","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAEnE"}
+{"version":3,"file":"runtime-homes.d.ts","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA2BhD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,GAAG,IAAI,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,GAAE,MAAqB,GAAG,MAAM,CAGnG"}

package/dist/utils/runtime-homes.js

@@ -13,15 +13,15 @@ const ENV_VAR_MAP = {
     pi: "PI_HOME",
 };
 /**
- * Default global home directory path for each runtime.
+ * Home directory subpath (relative to the home base) for each runtime.
  */
-const DEFAULT_HOME_MAP = {
-    claude: path.join(os.homedir(), ".claude"),
-    codex: path.join(os.homedir(), ".codex"),
-    gemini: path.join(os.homedir(), ".gemini"),
-    cursor: path.join(os.homedir(), ".cursor"),
-    opencode: path.join(os.homedir(), ".config", "opencode"),
-    pi: path.join(os.homedir(), ".pi"),
+const HOME_SUBPATH_MAP = {
+    claude: [".claude"],
+    codex: [".codex"],
+    gemini: [".gemini"],
+    cursor: [".cursor"],
+    opencode: [".config", "opencode"],
+    pi: [".pi"],
 };
 /**
  * Returns the environment variable name that overrides the global home
@@ -34,8 +34,12 @@ export function getRuntimeHomeEnvVar(runtime) {
 }
 /**
  * Returns the default global home directory path for the given runtime.
+ *
+ * Pass `homeDir` to resolve against a base other than the user's real home
+ * directory (useful for sandboxed installs and tests). Defaults to os.homedir().
  */
-export function getDefaultRuntimeHome(runtime) {
-    return DEFAULT_HOME_MAP[runtime] ?? path.join(os.homedir(), `.${runtime}`);
+export function getDefaultRuntimeHome(runtime, homeDir = os.homedir()) {
+    const subpath = HOME_SUBPATH_MAP[runtime] ?? [`.${runtime}`];
+    return path.join(homeDir, ...subpath);
 }
 //# sourceMappingURL=runtime-homes.js.map

package/dist/utils/runtime-homes.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtime-homes.js","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9B;;;GAGG;AACH,MAAM,WAAW,GAAwC;IACvD,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,iBAAiB,EAAG,8BAA8B;IAC5D,EAAE,EAAE,SAAS;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,gBAAgB,GAAiC;IACrD,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC;IACxC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,CAAC;IAC1C,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,CAAC;IACxD,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC;CACnC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqB;IACzD,OAAO,gBAAgB,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,IAAI,OAAO,EAAE,CAAC,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"runtime-homes.js","sourceRoot":"","sources":["../../src/utils/runtime-homes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAG9B;;;GAGG;AACH,MAAM,WAAW,GAAwC;IACvD,MAAM,EAAE,mBAAmB;IAC3B,KAAK,EAAE,YAAY;IACnB,MAAM,EAAE,mBAAmB;IAC3B,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,iBAAiB,EAAG,8BAA8B;IAC5D,EAAE,EAAE,SAAS;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,gBAAgB,GAAmC;IACvD,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,KAAK,EAAE,CAAC,QAAQ,CAAC;IACjB,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,MAAM,EAAE,CAAC,SAAS,CAAC;IACnB,QAAQ,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;IACjC,EAAE,EAAE,CAAC,KAAK,CAAC;CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAqB;IACxD,OAAO,WAAW,CAAC,OAAO,CAAC,IAAI,IAAI,CAAC;AACtC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAqB,EAAE,UAAkB,EAAE,CAAC,OAAO,EAAE;IACzF,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;AACxC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentex/agent",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "description": "Programmatic execution of AI coding agents (Claude Code, Codex, OpenClaw)",
   "repository": {
     "type": "git",