@jobshimo/browser-link 0.8.0 → 0.8.2

package/dist/agent-instructions/content.d.ts

@@ -21,8 +21,21 @@ export declare const BEGIN_RE: RegExp;
 export declare const END_RE: RegExp;
 /** Full fenced block to write into the file, including a trailing newline.
  * The line between markers carries the managed-by stamp so a user reading
- * the file knows it is auto-generated and how to refresh it. */
-export declare function block(version?: string): string;
+ * the file knows it is auto-generated and how to refresh it.
+ *
+ * `eol` controls the line separator. Default is LF; pass CRLF to match a
+ * Windows-edited file's dominant line ending. The body() helper composes
+ * its own lines with `\n`; we replace them when joining so the produced
+ * block is uniformly LF or CRLF — never mixed. */
+export declare function block(version?: string, eol?: '\n' | '\r\n'): string;
+/** Count occurrences of the BEGIN marker in `text`. The base BEGIN_RE has
+ * no `g` flag (it's used for single-span detection); this helper compiles
+ * the same pattern with `g` so duplicates can be diagnosed. */
+export declare function countBeginMarkers(text: string): number;
+/** Pick the dominant line ending of `text`. CRLF wins only when it is the
+ * majority of newline sequences; otherwise LF. Used by installAt to keep
+ * Windows-edited files from acquiring a mixed-EOL block. */
+export declare function detectEol(text: string): '\n' | '\r\n';
 /** Locate the block boundaries in the given file text. Returns null when
  * either marker is missing. Used by detect/install/uninstall to act on the
  * exact span the installer owns. */

package/dist/agent-instructions/content.js

@@ -60,9 +60,14 @@ function body() {
 }
 /** Full fenced block to write into the file, including a trailing newline.
  * The line between markers carries the managed-by stamp so a user reading
- * the file knows it is auto-generated and how to refresh it. */
-export function block(version = VERSION) {
-    return [
+ * the file knows it is auto-generated and how to refresh it.
+ *
+ * `eol` controls the line separator. Default is LF; pass CRLF to match a
+ * Windows-edited file's dominant line ending. The body() helper composes
+ * its own lines with `\n`; we replace them when joining so the produced
+ * block is uniformly LF or CRLF — never mixed. */
+export function block(version = VERSION, eol = '\n') {
+    const parts = [
         beginMarker(version),
         `<!-- managed-by: browser-link v${version}; do not edit between markers; run \`browser-link instructions install\` to refresh. -->`,
         '',
@@ -70,7 +75,27 @@ export function block(version = VERSION) {
         '',
         END_MARKER,
         '',
-    ].join('\n');
+    ];
+    if (eol === '\n')
+        return parts.join('\n');
+    // body() returned a multi-line string joined with \n; flip each \n to \r\n.
+    return parts.map((p) => p.replace(/\n/g, '\r\n')).join('\r\n');
+}
+/** Count occurrences of the BEGIN marker in `text`. The base BEGIN_RE has
+ * no `g` flag (it's used for single-span detection); this helper compiles
+ * the same pattern with `g` so duplicates can be diagnosed. */
+export function countBeginMarkers(text) {
+    return (text.match(/<!--\s*browser-link:instructions:begin(?:\s+v\d+\.\d+\.\d+)?\s*-->/g) ?? [])
+        .length;
+}
+/** Pick the dominant line ending of `text`. CRLF wins only when it is the
+ * majority of newline sequences; otherwise LF. Used by installAt to keep
+ * Windows-edited files from acquiring a mixed-EOL block. */
+export function detectEol(text) {
+    const crlf = (text.match(/\r\n/g) ?? []).length;
+    const lfTotal = (text.match(/\n/g) ?? []).length;
+    const loneLf = lfTotal - crlf;
+    return crlf > loneLf && crlf > 0 ? '\r\n' : '\n';
 }
 export function findBlockSpan(text) {
     const begin = BEGIN_RE.exec(text);

package/dist/agent-instructions/content.js.map

@@ -1 +1 @@
-{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC;;;;;;;;;;GAUG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,sCAAsC,CAAC;AACnE,MAAM,CAAC,MAAM,UAAU,GAAG,wCAAwC,CAAC;AAEnE,MAAM,UAAU,WAAW,CAAC,OAAO,GAAG,OAAO;IAC3C,OAAO,GAAG,YAAY,KAAK,OAAO,MAAM,CAAC;AAC3C,CAAC;AAED;;;;yCAIyC;AACzC,MAAM,CAAC,MAAM,QAAQ,GACnB,gFAAgF,CAAC;AACnF,MAAM,CAAC,MAAM,MAAM,GAAG,4CAA4C,CAAC;AAEnE;6EAC6E;AAC7E,SAAS,IAAI;IACX,OAAO;QACL,wCAAwC;QACxC,EAAE;QACF,sEAAsE;QACtE,qEAAqE;QACrE,kEAAkE;QAClE,qEAAqE;QACrE,aAAa;QACb,EAAE;QACF,uCAAuC;QACvC,EAAE;QACF,uEAAuE;QACvE,yEAAyE;QACzE,gEAAgE;QAChE,qEAAqE;QACrE,6DAA6D;QAC7D,0EAA0E;QAC1E,wEAAwE;QACxE,uEAAuE;QACvE,uEAAuE;QACvE,uDAAuD;QACvD,sEAAsE;QACtE,+DAA+D;QAC/D,kEAAkE;QAClE,wBAAwB;QACxB,EAAE;QACF,6BAA6B;QAC7B,EAAE;QACF,oEAAoE;QACpE,sEAAsE;QACtE,0DAA0D;KAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED;;gEAEgE;AAChE,MAAM,UAAU,KAAK,CAAC,OAAO,GAAG,OAAO;IACrC,OAAO;QACL,WAAW,CAAC,OAAO,CAAC;QACpB,kCAAkC,OAAO,0FAA0F;QACnI,EAAE;QACF,IAAI,EAAE;QACN,EAAE;QACF,UAAU;QACV,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAWD,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACjD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IAChD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,sBAAsB,GAAG,UAAU,GAAG,GAAG,CAAC,KAAK,CAAC;IACtD,MAAM,oBAAoB,GAAG,sBAAsB,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACpE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,oBAAoB,GAAG,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAC;IACrF,OAAO;QACL,UAAU,EAAE,KAAK,CAAC,KAAK;QACvB,QAAQ;QACR,gBAAgB,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI;KAChD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/agent-instructions/content.ts"],"names":[],"mappings":"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"}

package/dist/agent-instructions/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Typed errors thrown by the agent-instructions file operations. Surfaced
+ * in the Ink screen as red banners; the CLI prints them straight to stderr.
+ * Keeping them in their own module avoids cycles between file-ops and the
+ * UI / command layers that catch them.
+ */
+/** Thrown when the target file is a symlink. We refuse to write through
+ * symlinks because the user's intent is ambiguous: editing the target
+ * may not be what they meant when they installed the symlink. The error
+ * message embeds a paste-ready block so the user can install it manually
+ * in the resolved target. */
+export declare class SymlinkRefusedError extends Error {
+    readonly source: string;
+    readonly target: string;
+    readonly blockContent: string;
+    constructor(source: string, target: string, blockContent: string);
+}
+/** Thrown when the target file contains more than one BEGIN marker. The
+ * installer cannot know which span to refresh; the user must resolve the
+ * duplication by hand before install/uninstall can proceed. */
+export declare class CorruptBlockError extends Error {
+    readonly filePath: string;
+    readonly reason: 'multiple-begin-markers';
+    constructor(filePath: string, reason: 'multiple-begin-markers');
+}
+/** Thrown when a write would land outside the resolved `$HOME` directory
+ * and the caller did not opt into the override. The block is meant for
+ * the user's own dotfile area; refusing to touch anything outside that
+ * tree is the safer failure mode (a tampered `HOME` or a typo'd config
+ * path should not let the installer scribble in `/etc` or `C:\Windows`).
+ * Clients with an explicit env-var override (e.g. Copilot's `COPILOT_HOME`)
+ * pass `{ allowOutsideHome: true }` through `installAt` / `uninstallAt`
+ * — that is the user opting in. */
+export declare class OutsideHomeError extends Error {
+    readonly filePath: string;
+    readonly home: string;
+    constructor(filePath: string, home: string);
+}

package/dist/agent-instructions/errors.js

@@ -0,0 +1,59 @@
+/**
+ * Typed errors thrown by the agent-instructions file operations. Surfaced
+ * in the Ink screen as red banners; the CLI prints them straight to stderr.
+ * Keeping them in their own module avoids cycles between file-ops and the
+ * UI / command layers that catch them.
+ */
+/** Thrown when the target file is a symlink. We refuse to write through
+ * symlinks because the user's intent is ambiguous: editing the target
+ * may not be what they meant when they installed the symlink. The error
+ * message embeds a paste-ready block so the user can install it manually
+ * in the resolved target. */
+export class SymlinkRefusedError extends Error {
+    source;
+    target;
+    blockContent;
+    constructor(source, target, blockContent) {
+        super(`${source} is a symlink to ${target}. Refusing to write through it. ` +
+            `Paste the block below into ${target} manually:\n\n${blockContent}`);
+        this.source = source;
+        this.target = target;
+        this.blockContent = blockContent;
+        this.name = 'SymlinkRefusedError';
+    }
+}
+/** Thrown when the target file contains more than one BEGIN marker. The
+ * installer cannot know which span to refresh; the user must resolve the
+ * duplication by hand before install/uninstall can proceed. */
+export class CorruptBlockError extends Error {
+    filePath;
+    reason;
+    constructor(filePath, reason) {
+        super(`${filePath} contains multiple browser-link instruction blocks ` +
+            `(${reason}). Refusing to touch it — please resolve the duplication manually.`);
+        this.filePath = filePath;
+        this.reason = reason;
+        this.name = 'CorruptBlockError';
+    }
+}
+/** Thrown when a write would land outside the resolved `$HOME` directory
+ * and the caller did not opt into the override. The block is meant for
+ * the user's own dotfile area; refusing to touch anything outside that
+ * tree is the safer failure mode (a tampered `HOME` or a typo'd config
+ * path should not let the installer scribble in `/etc` or `C:\Windows`).
+ * Clients with an explicit env-var override (e.g. Copilot's `COPILOT_HOME`)
+ * pass `{ allowOutsideHome: true }` through `installAt` / `uninstallAt`
+ * — that is the user opting in. */
+export class OutsideHomeError extends Error {
+    filePath;
+    home;
+    constructor(filePath, home) {
+        super(`Refusing to write ${filePath}: target is outside the user home directory ` +
+            `(${home}). Set the client-specific override env var (e.g. COPILOT_HOME) ` +
+            `if this path is intentional.`);
+        this.filePath = filePath;
+        this.home = home;
+        this.name = 'OutsideHomeError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/agent-instructions/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/agent-instructions/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;6BAI6B;AAC7B,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAE1B;IACA;IACA;IAHlB,YACkB,MAAc,EACd,MAAc,EACd,YAAoB;QAEpC,KAAK,CACH,GAAG,MAAM,oBAAoB,MAAM,kCAAkC;YACnE,8BAA8B,MAAM,iBAAiB,YAAY,EAAE,CACtE,CAAC;QAPc,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAQ;QACd,iBAAY,GAAZ,YAAY,CAAQ;QAMpC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;+DAE+D;AAC/D,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAExB;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAgC;QAEhD,KAAK,CACH,GAAG,QAAQ,qDAAqD;YAC9D,IAAI,MAAM,oEAAoE,CACjF,CAAC;QANc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAA0B;QAMhD,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;mCAOmC;AACnC,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAEvB;IACA;IAFlB,YACkB,QAAgB,EAChB,IAAY;QAE5B,KAAK,CACH,qBAAqB,QAAQ,8CAA8C;YACzE,IAAI,IAAI,kEAAkE;YAC1E,8BAA8B,CACjC,CAAC;QAPc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,SAAI,GAAJ,IAAI,CAAQ;QAO5B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF"}

package/dist/agent-instructions/file-ops.d.ts

@@ -1,8 +1,14 @@
 import type { InstructionsDetect } from './types.js';
+/** Options for the write-side helpers. `allowOutsideHome` opts out of the
+ * outside-`$HOME` guard for clients that honour an explicit user-controlled
+ * override (e.g. Copilot CLI's `COPILOT_HOME`). */
+export interface FileOpOptions {
+    allowOutsideHome?: boolean;
+}
 export declare function detectAt(filePath: string): InstructionsDetect;
 /**
  * Insert or refresh the block in `filePath`. Returns a one-line description
  * of what changed, suitable for surfacing to the user.
  */
-export declare function installAt(filePath: string, displayName: string): string;
-export declare function uninstallAt(filePath: string, displayName: string): string;
+export declare function installAt(filePath: string, displayName: string, options?: FileOpOptions): string;
+export declare function uninstallAt(filePath: string, displayName: string, options?: FileOpOptions): string;

package/dist/agent-instructions/file-ops.js

@@ -1,33 +1,103 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname } from 'node:path';
+import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, join, resolve, sep } from 'node:path';
 import { VERSION } from '../version.js';
-import { block, findBlockSpan } from './content.js';
+import { compareSemver } from '../utils/semver.js';
+import { block, countBeginMarkers, detectEol, findBlockSpan } from './content.js';
+import { CorruptBlockError, OutsideHomeError, SymlinkRefusedError } from './errors.js';
 /**
  * Shared file-level operations for the three agent-instructions installers.
  * Per-client modules only know which path their target file lives at; the
  * marker handling and the text splice are the same everywhere.
  */
-function compareSemver(a, b) {
-    const pa = a.split('.').map(Number);
-    const pb = b.split('.').map(Number);
-    for (let i = 0; i < 3; i++) {
-        const da = pa[i] ?? 0;
-        const db = pb[i] ?? 0;
-        if (da !== db)
-            return da - db;
+/** Atomic write via a sibling temp file + fsync + rename. Closes the
+ * TOCTOU window between existsSync()/stat and writeFileSync() that
+ * CodeQL flagged as js/file-system-race. Cleans up the temp file if
+ * the rename fails (or any earlier step throws). The 0o600 create-mode
+ * keeps the temp file private while it lives. */
+function atomicWrite(filePath, content) {
+    const dir = dirname(filePath);
+    const tmp = join(dir, `.${basename(filePath)}.${process.pid}-${Date.now()}.tmp`);
+    let fd = null;
+    try {
+        fd = openSync(tmp, 'w', 0o600);
+        writeSync(fd, content, null, 'utf8');
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = null;
+        renameSync(tmp, filePath);
     }
-    return 0;
+    catch (err) {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                /* swallow — we're already on the error path */
+            }
+        }
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            /* swallow — the tmp may never have been created */
+        }
+        throw err;
+    }
+}
+/** Refuse to touch paths that land outside the user's home directory. The
+ * block we manage is meant for the user's own dotfiles; writing into
+ * `/etc`, `C:\Windows`, or anywhere unrelated is almost always a bug or a
+ * tampered config. `allowOutsideHome: true` skips the check — used when
+ * the user opted in through a client-specific env var (e.g. `COPILOT_HOME`).
+ * The home directory itself counts as "under" home (the equality branch). */
+function assertUnderHome(filePath) {
+    const home = resolve(homedir());
+    const resolved = resolve(filePath);
+    if (resolved === home)
+        return;
+    if (resolved.startsWith(home + sep))
+        return;
+    throw new OutsideHomeError(filePath, home);
+}
+/** Throw SymlinkRefusedError if `filePath` is a symlink. existsSync follows
+ * symlinks, so callers must use this lstat-based check separately. */
+function guardSymlink(filePath) {
+    let st;
+    try {
+        st = lstatSync(filePath);
+    }
+    catch {
+        return; // file does not exist — not our problem here
+    }
+    if (!st.isSymbolicLink())
+        return;
+    const rawTarget = readlinkSync(filePath);
+    // realpath gives us the absolute resolved path even when readlink returns
+    // something relative. Fall back to the raw readlink output if realpath
+    // throws (broken symlink) so the error message still names a target.
+    let resolved;
+    try {
+        resolved = realpathSync(filePath);
+    }
+    catch {
+        resolved = rawTarget;
+    }
+    throw new SymlinkRefusedError(filePath, resolved, block());
 }
 export function detectAt(filePath) {
     if (!existsSync(filePath)) {
         return { filePath, state: { kind: 'no-file' } };
     }
     const text = readFileSync(filePath, 'utf8');
+    if (countBeginMarkers(text) > 1) {
+        return { filePath, state: { kind: 'corrupt', reason: 'multiple-begin-markers' } };
+    }
     const span = findBlockSpan(text);
     if (!span) {
         return { filePath, state: { kind: 'not-installed' } };
     }
-    const installedVersion = span.installedVersion ?? '0.0.0';
+    const installedVersion = span.installedVersion;
     const cmp = compareSemver(installedVersion, VERSION);
     return {
         filePath,
@@ -40,32 +110,50 @@ export function detectAt(filePath) {
  * Insert or refresh the block in `filePath`. Returns a one-line description
  * of what changed, suitable for surfacing to the user.
  */
-export function installAt(filePath, displayName) {
-    const fresh = block();
+export function installAt(filePath, displayName, options = {}) {
+    if (!options.allowOutsideHome)
+        assertUnderHome(filePath);
+    guardSymlink(filePath);
     if (!existsSync(filePath)) {
         mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, fresh, 'utf8');
+        // New file: portable markdown — LF by default. We do NOT pick CRLF on
+        // Windows because the content is going into a tool-managed .md file
+        // that may be synced to other OSes.
+        atomicWrite(filePath, block());
         return `Created ${filePath} and inserted the browser-link instructions block for ${displayName}.`;
     }
     const text = readFileSync(filePath, 'utf8');
+    if (countBeginMarkers(text) > 1) {
+        throw new CorruptBlockError(filePath, 'multiple-begin-markers');
+    }
+    const eol = detectEol(text);
+    const fresh = block(VERSION, eol);
     const span = findBlockSpan(text);
     if (!span) {
-        // Append. Ensure a blank line separator from prior content.
-        const separator = text.length === 0 || text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
-        writeFileSync(filePath, text + separator + fresh, 'utf8');
+        // Append. Ensure a blank line separator from prior content, matching
+        // the file's dominant line ending.
+        const doubleEol = `${eol}${eol}`;
+        const separator = text.length === 0 || text.endsWith(doubleEol) ? '' : text.endsWith(eol) ? eol : doubleEol;
+        atomicWrite(filePath, text + separator + fresh);
         return `Appended the browser-link instructions block to ${filePath} (${displayName}).`;
     }
     const before = text.slice(0, span.startIndex);
     const after = text.slice(span.endIndex);
-    writeFileSync(filePath, before + fresh + after, 'utf8');
+    atomicWrite(filePath, before + fresh + after);
     const prev = span.installedVersion ?? 'unversioned';
     return `Refreshed the browser-link instructions block in ${filePath} (${displayName}, was v${prev}).`;
 }
-export function uninstallAt(filePath, displayName) {
+export function uninstallAt(filePath, displayName, options = {}) {
+    if (!options.allowOutsideHome)
+        assertUnderHome(filePath);
     if (!existsSync(filePath)) {
         return `No ${displayName} instructions file at ${filePath}; nothing to remove.`;
     }
+    guardSymlink(filePath);
     const text = readFileSync(filePath, 'utf8');
+    if (countBeginMarkers(text) > 1) {
+        throw new CorruptBlockError(filePath, 'multiple-begin-markers');
+    }
     const span = findBlockSpan(text);
     if (!span) {
         return `browser-link instructions block was not present in ${filePath}; nothing to remove.`;
@@ -73,11 +161,16 @@ export function uninstallAt(filePath, displayName) {
     const before = text.slice(0, span.startIndex);
     const after = text.slice(span.endIndex);
     // Collapse double blank lines created by removing the block, but keep the
-    // user's own content. A single trailing newline at EOF is restored.
-    let next = (before + after).replace(/\n{3,}/g, '\n\n');
-    if (next.length > 0 && !next.endsWith('\n'))
-        next += '\n';
-    writeFileSync(filePath, next, 'utf8');
+    // user's own content. A single trailing newline at EOF is restored,
+    // matching whatever EOL the remaining content uses.
+    const remaining = before + after;
+    const eol = detectEol(remaining);
+    const collapsePattern = eol === '\r\n' ? /(?:\r\n){3,}/g : /\n{3,}/g;
+    const doubleEol = `${eol}${eol}`;
+    let next = remaining.replace(collapsePattern, doubleEol);
+    if (next.length > 0 && !next.endsWith(eol))
+        next += eol;
+    atomicWrite(filePath, next);
     return `Removed the browser-link instructions block from ${filePath} (${displayName}).`;
 }
 //# sourceMappingURL=file-ops.js.map

package/dist/agent-instructions/file-ops.js.map

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

package/dist/agent-instructions/index.d.ts

@@ -1,4 +1,31 @@
 import type { ClientId, InstructionsInstaller } from './types.js';
+/**
+ * Claude Code reads `~/.claude/CLAUDE.md` as the user-level global
+ * instructions file (applied to every project). That is where the block
+ * lives so the trigger list reaches every Claude session, regardless of
+ * which repo the user is in.
+ */
+export declare const claudeInstructionsInstaller: InstructionsInstaller;
+/**
+ * OpenCode follows the AGENTS.md convention (https://agents.md). Global
+ * instructions live next to the MCP config at
+ * `~/.config/opencode/AGENTS.md` on every OS — same dir as `opencode.json`.
+ * Project-level AGENTS.md still applies in addition; the global file is
+ * the one we manage so the agent gets the trigger list everywhere.
+ */
+export declare const opencodeInstructionsInstaller: InstructionsInstaller;
+/**
+ * GitHub Copilot CLI keeps its config under `~/.copilot/` (overridable via
+ * COPILOT_HOME, same env var the rest of our Copilot integration honours).
+ * AGENTS.md alongside `mcp-config.json` is the convention recent versions
+ * pick up; older releases ignore the file, in which case the block sits
+ * there harmlessly until they catch up.
+ *
+ * When `COPILOT_HOME` is set the resolved path may sit outside `$HOME`.
+ * That is the user opting in explicitly, so the outside-`$HOME` guard is
+ * relaxed for this client only when the env var is present.
+ */
+export declare const copilotInstructionsInstaller: InstructionsInstaller;
 /**
  * Order matches the MCP `INSTALLERS` array so the agent-instructions screen
  * and the MCP installers screen list clients in the same sequence.
@@ -6,3 +33,4 @@ import type { ClientId, InstructionsInstaller } from './types.js';
 export declare const INSTRUCTIONS_INSTALLERS: InstructionsInstaller[];
 export declare function getInstructionsInstaller(id: ClientId): InstructionsInstaller;
 export type { ClientId, InstructionsDetect, InstructionsInstaller, InstructionsState, } from './types.js';
+export { CorruptBlockError, OutsideHomeError, SymlinkRefusedError } from './errors.js';

package/dist/agent-instructions/index.js

@@ -1,6 +1,71 @@
-import { claudeInstructionsInstaller } from './claude.js';
-import { copilotInstructionsInstaller } from './copilot.js';
-import { opencodeInstructionsInstaller } from './opencode.js';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { detectAt, installAt, uninstallAt } from './file-ops.js';
+function createInstructionsInstaller(spec) {
+    const { id, displayName, file, allowOutsideHome } = spec;
+    const opts = () => ({
+        allowOutsideHome: allowOutsideHome?.() ?? false,
+    });
+    return {
+        id,
+        displayName,
+        filePath() {
+            return file();
+        },
+        detect() {
+            return detectAt(file());
+        },
+        install() {
+            return installAt(file(), displayName, opts());
+        },
+        uninstall() {
+            return uninstallAt(file(), displayName, opts());
+        },
+    };
+}
+/**
+ * Claude Code reads `~/.claude/CLAUDE.md` as the user-level global
+ * instructions file (applied to every project). That is where the block
+ * lives so the trigger list reaches every Claude session, regardless of
+ * which repo the user is in.
+ */
+export const claudeInstructionsInstaller = createInstructionsInstaller({
+    id: 'claude',
+    displayName: 'Claude Code',
+    file: () => join(homedir(), '.claude', 'CLAUDE.md'),
+});
+/**
+ * OpenCode follows the AGENTS.md convention (https://agents.md). Global
+ * instructions live next to the MCP config at
+ * `~/.config/opencode/AGENTS.md` on every OS — same dir as `opencode.json`.
+ * Project-level AGENTS.md still applies in addition; the global file is
+ * the one we manage so the agent gets the trigger list everywhere.
+ */
+export const opencodeInstructionsInstaller = createInstructionsInstaller({
+    id: 'opencode',
+    displayName: 'OpenCode',
+    file: () => join(homedir(), '.config', 'opencode', 'AGENTS.md'),
+});
+/**
+ * GitHub Copilot CLI keeps its config under `~/.copilot/` (overridable via
+ * COPILOT_HOME, same env var the rest of our Copilot integration honours).
+ * AGENTS.md alongside `mcp-config.json` is the convention recent versions
+ * pick up; older releases ignore the file, in which case the block sits
+ * there harmlessly until they catch up.
+ *
+ * When `COPILOT_HOME` is set the resolved path may sit outside `$HOME`.
+ * That is the user opting in explicitly, so the outside-`$HOME` guard is
+ * relaxed for this client only when the env var is present.
+ */
+export const copilotInstructionsInstaller = createInstructionsInstaller({
+    id: 'copilot',
+    displayName: 'GitHub Copilot CLI',
+    file: () => {
+        const root = process.env.COPILOT_HOME ?? join(homedir(), '.copilot');
+        return join(root, 'AGENTS.md');
+    },
+    allowOutsideHome: () => process.env.COPILOT_HOME !== undefined,
+});
 /**
  * Order matches the MCP `INSTALLERS` array so the agent-instructions screen
  * and the MCP installers screen list clients in the same sequence.
@@ -16,4 +81,5 @@ export function getInstructionsInstaller(id) {
         throw new Error(`Unknown or unsupported client: ${id}`);
     return found;
 }
+export { CorruptBlockError, OutsideHomeError, SymlinkRefusedError } from './errors.js';
 //# sourceMappingURL=index.js.map

package/dist/agent-instructions/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,4BAA4B,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,6BAA6B,EAAE,MAAM,eAAe,CAAC;AAG9D;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA4B;IAC9D,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;CAC7B,CAAC;AAEF,MAAM,UAAU,wBAAwB,CAAC,EAAY;IACnD,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent-instructions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAwBjE,SAAS,2BAA2B,CAAC,IAAmB;IACtD,MAAM,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,gBAAgB,EAAE,GAAG,IAAI,CAAC;IACzD,MAAM,IAAI,GAAG,GAAkC,EAAE,CAAC,CAAC;QACjD,gBAAgB,EAAE,gBAAgB,EAAE,EAAE,IAAI,KAAK;KAChD,CAAC,CAAC;IACH,OAAO;QACL,EAAE;QACF,WAAW;QACX,QAAQ;YACN,OAAO,IAAI,EAAE,CAAC;QAChB,CAAC;QACD,MAAM;YACJ,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC1B,CAAC;QACD,OAAO;YACL,OAAO,SAAS,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,SAAS;YACP,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAA0B,2BAA2B,CAAC;IAC5F,EAAE,EAAE,QAAQ;IACZ,WAAW,EAAE,aAAa;IAC1B,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC;CACpD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAA0B,2BAA2B,CAAC;IAC9F,EAAE,EAAE,UAAU;IACd,WAAW,EAAE,UAAU;IACvB,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC;CAChE,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAA0B,2BAA2B,CAAC;IAC7F,EAAE,EAAE,SAAS;IACb,WAAW,EAAE,oBAAoB;IACjC,IAAI,EAAE,GAAG,EAAE;QACT,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,UAAU,CAAC,CAAC;QACrE,OAAO,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACjC,CAAC;IACD,gBAAgB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,KAAK,SAAS;CAC/D,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA4B;IAC9D,2BAA2B;IAC3B,6BAA6B;IAC7B,4BAA4B;CAC7B,CAAC;AAEF,MAAM,UAAU,wBAAwB,CAAC,EAAY;IACnD,MAAM,KAAK,GAAG,uBAAuB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,EAAE,EAAE,CAAC,CAAC;IACpE,OAAO,KAAK,CAAC;AACf,CAAC;AASD,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}

package/dist/agent-instructions/types.d.ts

@@ -8,10 +8,13 @@ export type InstructionsState = {
     kind: 'not-installed';
 } | {
     kind: 'installed';
-    version: string;
+    version: string | null;
 } | {
     kind: 'installed-outdated';
-    version: string;
+    version: string | null;
+} | {
+    kind: 'corrupt';
+    reason: 'multiple-begin-markers';
 };
 export interface InstructionsDetect {
     /** Absolute path to the markdown file we manage. Returned even when it does not exist. */