Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

feat(hosts): marker-fenced section upsert for agent instruction files

Shrish Dwivedibf484924972c
diff --git a/src/hosts/sections.ts b/src/hosts/sections.ts
new file mode 100644
index 00000000..bec6ca07
--- /dev/null
+++ b/src/hosts/sections.ts
@@ -0,0 +1,46 @@
+/**
+ * Marker-fenced section upsert. Graft owns exactly the region between the
+ * markers; everything else in the file belongs to the user and is preserved.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export const START = '<!-- graft:start -->';
+export const END = '<!-- graft:end -->';
+
+export type UpsertAction = 'created' | 'appended' | 'replaced' | 'unchanged';
+
+export function fencedBlock(body: string): string {
+ return `${START}\n${body.replace(/\s+$/, '')}\n${END}`;
+}
+
+/** Index of a marker that sits alone on its own line, or -1. */
+function markerLineIndex(lines: string[], marker: string, from = 0): number {
+ for (let i = from; i < lines.length; i++) {
+ if (lines[i].trim() === marker) return i;
+ }
+ return -1;
+}
+
+export function upsertSection(filePath: string, body: string): { action: UpsertAction } {
+ const block = fencedBlock(body);
+ if (!existsSync(filePath)) {
+ mkdirSync(dirname(filePath), { recursive: true });
+ writeFileSync(filePath, `${block}\n`);
+ return { action: 'created' };
+ }
+ const text = readFileSync(filePath, 'utf8');
+ const lines = text.split('\n');
+ const s = markerLineIndex(lines, START);
+ const e = s === -1 ? -1 : markerLineIndex(lines, END, s + 1);
+ if (s !== -1 && e !== -1) {
+ const current = lines.slice(s, e + 1).join('\n');
+ if (current === block) return { action: 'unchanged' };
+ const next = [...lines.slice(0, s), ...block.split('\n'), ...lines.slice(e + 1)];
+ writeFileSync(filePath, next.join('\n'));
+ return { action: 'replaced' };
+ }
+ const sep = text.endsWith('\n\n') ? '' : text.endsWith('\n') ? '\n' : '\n\n';
+ writeFileSync(filePath, `${text}${sep}${block}\n`);
+ return { action: 'appended' };
+}
diff --git a/test/hosts-sections.test.ts b/test/hosts-sections.test.ts
new file mode 100644
index 00000000..7f67f58b
--- /dev/null
+++ b/test/hosts-sections.test.ts
@@ -0,0 +1,56 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { upsertSection, fencedBlock } from '../src/hosts/sections.js';
+
+function fresh(): string { return mkdtempSync(join(tmpdir(), 'graft-sections-')); }
+
+test('creates the file with a fenced block when missing', () => {
+ const f = join(fresh(), 'AGENTS.md');
+ const r = upsertSection(f, '## Graft\nuse graft ask');
+ assert.equal(r.action, 'created');
+ const text = readFileSync(f, 'utf8');
+ assert.ok(text.includes('<!-- graft:start -->'));
+ assert.ok(text.includes('use graft ask'));
+ assert.ok(text.endsWith('\n'));
+});
+
+test('appends after existing content, separated by a blank line', () => {
+ const f = join(fresh(), 'AGENTS.md');
+ writeFileSync(f, '# My rules\n\nBe nice.\n');
+ const r = upsertSection(f, 'graft body');
+ assert.equal(r.action, 'appended');
+ const text = readFileSync(f, 'utf8');
+ assert.ok(text.startsWith('# My rules\n\nBe nice.\n'));
+ assert.match(text, /Be nice\.\n\n<!-- graft:start -->/);
+});
+
+test('replaces only the fenced region on re-run with new body', () => {
+ const f = join(fresh(), 'AGENTS.md');
+ writeFileSync(f, `above\n\n${fencedBlock('old body')}\nbelow\n`);
+ const r = upsertSection(f, 'new body');
+ assert.equal(r.action, 'replaced');
+ const text = readFileSync(f, 'utf8');
+ assert.ok(text.includes('above'));
+ assert.ok(text.includes('below'));
+ assert.ok(text.includes('new body'));
+ assert.ok(!text.includes('old body'));
+ assert.equal(text.match(/graft:start/g)!.length, 1, 'exactly one block');
+});
+
+test('reports unchanged when the fenced body already matches', () => {
+ const f = join(fresh(), 'AGENTS.md');
+ upsertSection(f, 'same body');
+ const r = upsertSection(f, 'same body');
+ assert.equal(r.action, 'unchanged');
+});
+
+test('ignores inline marker mentions (marker must be alone on its line)', () => {
+ const f = join(fresh(), 'AGENTS.md');
+ writeFileSync(f, 'talking about `<!-- graft:start -->` in prose\n');
+ const r = upsertSection(f, 'body');
+ assert.equal(r.action, 'appended');
+ assert.equal(readFileSync(f, 'utf8').match(/^<!-- graft:start -->$/gm)!.length, 1);
+});