openlore 2.0.1 → 2.0.2

package/dist/cli/install/adapters/cursor.js

@@ -0,0 +1,195 @@
+/**
+ * cursor adapter — writes an OpenLore-managed block to `.cursorrules`, a
+ * companion `.cursor/rules/openlore.mdc` file describing the orient() workflow,
+ * and registers the OpenLore MCP server in `.cursor/mcp.json`.
+ */
+import { mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyMarkdownBlock, uninstallMarkdownBlock } from './markdown-block.js';
+import { fingerprint } from '../block.js';
+import { mergeEntries, readMeta, removeManaged, isHandEdited } from '../json-managed.js';
+import { previewCreate, previewDiff } from '../diff.js';
+const RULES_FILE = '.cursorrules';
+const MDC_FILE = '.cursor/rules/openlore.mdc';
+const MCP_FILE = '.cursor/mcp.json';
+const MCP_ENTRY = {
+    command: 'npx',
+    args: ['--yes', 'openlore', 'mcp'],
+};
+async function loadMdcTemplate() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // adapters/ → ../templates/cursor-openlore.mdc (dist + tsx run share this layout)
+        join(here, '..', 'templates', 'cursor-openlore.mdc'),
+        // tsx fallback if for any reason we're not co-located with templates
+        join(here, '..', '..', '..', '..', 'src', 'cli', 'install', 'templates', 'cursor-openlore.mdc'),
+    ];
+    for (const p of candidates) {
+        try {
+            return await readFile(p, 'utf8');
+        }
+        catch {
+            /* try next */
+        }
+    }
+    throw new Error('cursor adapter: could not locate cursor-openlore.mdc template');
+}
+async function renderMdc(instructions) {
+    const tmpl = await loadMdcTemplate();
+    return tmpl
+        .replace('{{fingerprint}}', fingerprint(instructions.trimEnd()))
+        .replace('{{instructions}}', instructions.trimEnd());
+}
+export const cursorAdapter = {
+    name: 'cursor',
+    async apply(ctx) {
+        const rulesResult = await applyMarkdownBlock(ctx, {
+            fileName: RULES_FILE,
+            createIfMissing: true,
+            blockBody: ctx.instructionTemplate,
+        });
+        const mdcPath = join(ctx.root, MDC_FILE);
+        const desired = await renderMdc(ctx.instructionTemplate);
+        let existing = null;
+        try {
+            existing = await readFile(mdcPath, 'utf8');
+        }
+        catch {
+            existing = null;
+        }
+        if (existing === desired) {
+            rulesResult.changes.push({
+                path: mdcPath,
+                kind: 'noop',
+                summary: `${MDC_FILE}: already up to date`,
+            });
+            return rulesResult;
+        }
+        const isOurs = existing === null ||
+            /^openlore-fingerprint:/m.test(existing);
+        if (existing !== null && !isOurs && !ctx.force) {
+            rulesResult.changes.push({
+                path: mdcPath,
+                kind: 'noop',
+                summary: `${MDC_FILE}: refused to overwrite non-OpenLore file (use --force)`,
+            });
+            rulesResult.warnings.push(`${MDC_FILE} exists but was not written by OpenLore`);
+            rulesResult.conflict = true;
+            return rulesResult;
+        }
+        const change = {
+            path: mdcPath,
+            kind: existing === null ? 'create' : 'update',
+            summary: existing === null ? `create ${MDC_FILE}` : `update ${MDC_FILE}`,
+            preview: existing === null
+                ? previewCreate(mdcPath, desired)
+                : previewDiff(mdcPath, existing, desired),
+        };
+        if (!ctx.dryRun) {
+            await mkdir(dirname(mdcPath), { recursive: true });
+            await writeFile(mdcPath, desired, 'utf8');
+        }
+        rulesResult.changes.push(change);
+        // MCP server registration via .cursor/mcp.json (standard Cursor path).
+        const mcpPath = join(ctx.root, MCP_FILE);
+        let mcpExisting = {};
+        let mcpHad = true;
+        try {
+            const parsed = JSON.parse(await readFile(mcpPath, 'utf8'));
+            mcpExisting =
+                parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+                    ? parsed
+                    : {};
+        }
+        catch {
+            mcpHad = false;
+        }
+        const mcpMeta = readMeta(mcpExisting);
+        if (mcpMeta && isHandEdited(mcpExisting, mcpMeta) && !ctx.force) {
+            rulesResult.changes.push({
+                path: mcpPath,
+                kind: 'noop',
+                summary: `${MCP_FILE}: refused to overwrite hand-edited OpenLore entries (use --force)`,
+            });
+            rulesResult.warnings.push(`${MCP_FILE} has hand-edits in OpenLore-managed paths — pass --force to overwrite`);
+            rulesResult.conflict = true;
+            return rulesResult;
+        }
+        const { next: nextMcp, action: mcpAction } = mergeEntries(mcpExisting, [
+            { path: 'mcpServers.openlore', value: MCP_ENTRY },
+        ]);
+        const beforeMcp = mcpHad ? JSON.stringify(mcpExisting, null, 2) + '\n' : '';
+        const afterMcp = JSON.stringify(nextMcp, null, 2) + '\n';
+        rulesResult.changes.push({
+            path: mcpPath,
+            kind: !mcpHad ? 'create' : mcpAction === 'noop' ? 'noop' : 'update',
+            summary: !mcpHad
+                ? `create ${MCP_FILE} with mcpServers.openlore`
+                : mcpAction === 'noop'
+                    ? `${MCP_FILE}: already up to date`
+                    : `update mcpServers.openlore in ${MCP_FILE}`,
+            preview: !mcpHad
+                ? previewCreate(mcpPath, afterMcp)
+                : mcpAction === 'noop'
+                    ? undefined
+                    : previewDiff(mcpPath, beforeMcp, afterMcp),
+        });
+        if (!ctx.dryRun && (mcpAction !== 'noop' || !mcpHad)) {
+            await mkdir(dirname(mcpPath), { recursive: true });
+            await writeFile(mcpPath, JSON.stringify(nextMcp, null, 2) + '\n', 'utf8');
+        }
+        return rulesResult;
+    },
+    async uninstall(ctx) {
+        const rules = await uninstallMarkdownBlock(ctx, RULES_FILE, true);
+        const mdcPath = join(ctx.root, MDC_FILE);
+        try {
+            const raw = await readFile(mdcPath, 'utf8');
+            if (/^openlore-fingerprint:/m.test(raw)) {
+                if (!ctx.dryRun)
+                    await unlink(mdcPath);
+                rules.changes.push({
+                    path: mdcPath,
+                    kind: 'delete',
+                    summary: `remove ${MDC_FILE}`,
+                });
+            }
+        }
+        catch {
+            /* not present, nothing to do */
+        }
+        // Strip our MCP entry from .cursor/mcp.json.
+        const mcpPath = join(ctx.root, MCP_FILE);
+        try {
+            const parsed = JSON.parse(await readFile(mcpPath, 'utf8'));
+            const { next, removed } = removeManaged(parsed);
+            if (removed) {
+                const isEmpty = Object.keys(next).length === 0;
+                if (isEmpty) {
+                    if (!ctx.dryRun)
+                        await unlink(mcpPath);
+                    rules.changes.push({
+                        path: mcpPath,
+                        kind: 'delete',
+                        summary: `remove ${MCP_FILE} (was OpenLore-only)`,
+                    });
+                }
+                else {
+                    if (!ctx.dryRun)
+                        await writeFile(mcpPath, JSON.stringify(next, null, 2) + '\n', 'utf8');
+                    rules.changes.push({
+                        path: mcpPath,
+                        kind: 'update',
+                        summary: `strip OpenLore entries from ${MCP_FILE}`,
+                    });
+                }
+            }
+        }
+        catch {
+            /* not present, nothing to do */
+        }
+        return rules;
+    },
+};
+//# sourceMappingURL=cursor.js.map

package/dist/cli/install/adapters/cursor.js.map

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

package/dist/cli/install/adapters/markdown-block.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared helper for adapters that append/update a managed markdown block in
+ * a single file at the project root (CLAUDE.md, AGENTS.md, .cursorrules,
+ * .clinerules). Centralises the read/upsert/write logic so each adapter is
+ * just a one-liner.
+ */
+import type { ApplyContext, ApplyResult } from './types.js';
+export interface MarkdownBlockOptions {
+    /** File name, relative to ctx.root. */
+    fileName: string;
+    /** Whether the file should be created if it doesn't yet exist. */
+    createIfMissing: boolean;
+    /** Optional adapter-specific prefix added above the template (e.g. heading). */
+    blockBody: string;
+}
+export declare function applyMarkdownBlock(ctx: ApplyContext, opts: MarkdownBlockOptions): Promise<ApplyResult>;
+export declare function uninstallMarkdownBlock(ctx: ApplyContext, fileName: string, 
+/** If true, delete the file when removing the block empties it. */
+deleteIfBlockOnly: boolean): Promise<ApplyResult>;
+//# sourceMappingURL=markdown-block.d.ts.map

package/dist/cli/install/adapters/markdown-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-block.d.ts","sourceRoot":"","sources":["../../../../src/cli/install/adapters/markdown-block.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAE3E,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,eAAe,EAAE,OAAO,CAAC;IACzB,gFAAgF;IAChF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,oBAAoB,GACzB,OAAO,CAAC,WAAW,CAAC,CAqEtB;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,MAAM;AAChB,mEAAmE;AACnE,iBAAiB,EAAE,OAAO,GACzB,OAAO,CAAC,WAAW,CAAC,CAkCtB"}

package/dist/cli/install/adapters/markdown-block.js

@@ -0,0 +1,114 @@
+/**
+ * Shared helper for adapters that append/update a managed markdown block in
+ * a single file at the project root (CLAUDE.md, AGENTS.md, .cursorrules,
+ * .clinerules). Centralises the read/upsert/write logic so each adapter is
+ * just a one-liner.
+ */
+import { readFile, writeFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { upsertBlock, extractBlock, isHandEdited, removeBlock, renderBlock, } from '../block.js';
+import { previewCreate, previewDiff } from '../diff.js';
+export async function applyMarkdownBlock(ctx, opts) {
+    const filePath = join(ctx.root, opts.fileName);
+    const warnings = [];
+    let existing = null;
+    try {
+        existing = await readFile(filePath, 'utf8');
+    }
+    catch {
+        existing = null;
+    }
+    if (existing === null && !opts.createIfMissing) {
+        return { changes: [], warnings, conflict: false };
+    }
+    const base = existing ?? '';
+    const block = existing ? extractBlock(existing) : null;
+    const handEdited = block ? isHandEdited(block) : false;
+    if (handEdited && !ctx.force) {
+        return {
+            changes: [
+                {
+                    path: filePath,
+                    kind: 'noop',
+                    summary: `${opts.fileName}: refused to overwrite hand-edited OpenLore block (use --force)`,
+                },
+            ],
+            warnings: [`${opts.fileName} has hand-edits inside the OpenLore block — pass --force to overwrite`],
+            conflict: true,
+        };
+    }
+    let next;
+    let action;
+    if (handEdited && ctx.force && block) {
+        // Force-overwrite a tampered block regardless of fingerprint match.
+        const rendered = renderBlock(opts.blockBody);
+        next = base.slice(0, block.beginIndex) + rendered + base.slice(block.endIndex);
+        action = 'updated';
+    }
+    else {
+        ({ next, action } = upsertBlock(base, opts.blockBody));
+    }
+    const change = {
+        path: filePath,
+        kind: existing === null
+            ? 'create'
+            : action === 'noop'
+                ? 'noop'
+                : 'update',
+        summary: existing === null
+            ? `create ${opts.fileName} with OpenLore block`
+            : action === 'noop'
+                ? `${opts.fileName}: already up to date`
+                : `update OpenLore block in ${opts.fileName}`,
+        preview: existing === null
+            ? previewCreate(filePath, next)
+            : action === 'noop'
+                ? undefined
+                : previewDiff(filePath, base, next),
+    };
+    if (!ctx.dryRun && action !== 'noop') {
+        await writeFile(filePath, next, 'utf8');
+    }
+    return { changes: [change], warnings, conflict: false };
+}
+export async function uninstallMarkdownBlock(ctx, fileName, 
+/** If true, delete the file when removing the block empties it. */
+deleteIfBlockOnly) {
+    const filePath = join(ctx.root, fileName);
+    let existing;
+    try {
+        existing = await readFile(filePath, 'utf8');
+    }
+    catch {
+        return { changes: [], warnings: [], conflict: false };
+    }
+    const removed = removeBlock(existing);
+    if (removed === null)
+        return { changes: [], warnings: [], conflict: false };
+    // Trim whitespace-only artifacts to decide if the file is now "empty".
+    const stripped = removed.trim();
+    if (stripped.length === 0 && deleteIfBlockOnly) {
+        if (!ctx.dryRun)
+            await unlink(filePath);
+        return {
+            changes: [{ path: filePath, kind: 'delete', summary: `remove ${fileName} (was OpenLore-only)` }],
+            warnings: [],
+            conflict: false,
+        };
+    }
+    if (!ctx.dryRun)
+        await writeFile(filePath, removed, 'utf8');
+    return {
+        changes: [
+            {
+                path: filePath,
+                kind: 'update',
+                summary: `strip OpenLore block from ${fileName}`,
+                preview: previewDiff(filePath, existing, removed),
+            },
+        ],
+        warnings: [],
+        conflict: false,
+    };
+}
+//# sourceMappingURL=markdown-block.js.map

package/dist/cli/install/adapters/markdown-block.js.map

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

package/dist/cli/install/adapters/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Shared types for OpenLore install adapters.
+ *
+ * An adapter knows how to plan, apply, and uninstall OpenLore's footprint on
+ * one specific agent surface. Adapters never write to disk directly when
+ * `dryRun` is true; instead they return a list of `PlannedChange` entries that
+ * the caller renders.
+ */
+import type { AgentName } from '../detect.js';
+export interface PlannedChange {
+    /** Absolute path the change applies to. */
+    path: string;
+    /** What we'd do to that file. */
+    kind: 'create' | 'update' | 'noop' | 'delete';
+    /** Short human-readable summary (one line). */
+    summary: string;
+    /** Optional unified-diff-ish preview for `--dry-run`. */
+    preview?: string;
+}
+export interface ApplyContext {
+    root: string;
+    /** Template content for the markdown instruction block. */
+    instructionTemplate: string;
+    dryRun: boolean;
+    force: boolean;
+}
+export interface ApplyResult {
+    changes: PlannedChange[];
+    /** Warnings to surface to the user (e.g. hand-edited block, unsure-of-path TODO). */
+    warnings: string[];
+    /** If true, install should exit non-zero (hand-edit conflict without --force). */
+    conflict: boolean;
+}
+export interface Adapter {
+    name: AgentName;
+    apply(ctx: ApplyContext): Promise<ApplyResult>;
+    uninstall(ctx: ApplyContext): Promise<ApplyResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cli/install/adapters/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/cli/install/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;IAC9C,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,mBAAmB,EAAE,MAAM,CAAC;IAC5B,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,qFAAqF;IACrF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,kFAAkF;IAClF,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/C,SAAS,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACpD"}

package/dist/cli/install/adapters/types.js

@@ -0,0 +1,10 @@
+/**
+ * Shared types for OpenLore install adapters.
+ *
+ * An adapter knows how to plan, apply, and uninstall OpenLore's footprint on
+ * one specific agent surface. Adapters never write to disk directly when
+ * `dryRun` is true; instead they return a list of `PlannedChange` entries that
+ * the caller renders.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli/install/adapters/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/cli/install/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/cli/install/block.d.ts

@@ -0,0 +1,53 @@
+/**
+ * OpenLore managed-block utilities.
+ *
+ * A "managed block" is a region inside an existing text file (typically Markdown)
+ * delimited by canonical comments. Re-running `openlore install` rewrites the
+ * block in place. A SHA-256 fingerprint over the canonical content lets us
+ * detect hand-edits and refuse to clobber them unless `--force` is passed.
+ */
+export declare const BLOCK_BEGIN = "<!-- BEGIN OPENLORE (managed \u2014 edits inside this block will be overwritten) -->";
+export declare const BLOCK_END = "<!-- END OPENLORE -->";
+export interface ExtractedBlock {
+    /** Index of the BEGIN marker in the source file. */
+    beginIndex: number;
+    /** Index just past the END marker. */
+    endIndex: number;
+    /** The raw text between BEGIN and END markers (excluding markers themselves). */
+    inner: string;
+    /** The fingerprint we previously wrote, if present. */
+    fingerprint: string | null;
+}
+export declare function fingerprint(content: string): string;
+/** Build the full managed block (markers + fingerprint comment + content). */
+export declare function renderBlock(content: string): string;
+export declare function extractBlock(source: string): ExtractedBlock | null;
+/**
+ * Compute the fingerprint of the *current* inner content as it would be if we
+ * had written `expectedContent`. Used to decide whether the block on disk
+ * still matches what we last wrote.
+ */
+export declare function blockMatchesExpected(block: ExtractedBlock, expectedContent: string): boolean;
+export interface UpsertResult {
+    /** The file contents to write back. */
+    next: string;
+    /** What happened: 'created' (file/block was new), 'updated' (re-rendered), 'noop' (already matched). */
+    action: 'created' | 'updated' | 'noop';
+}
+/**
+ * Upsert the managed block in `existing`. If a block exists, replace it; otherwise
+ * append. If the existing block's fingerprint matches the new content, do nothing.
+ *
+ * Caller is responsible for the `--force` / hand-edit check (use `isHandEdited`).
+ */
+export declare function upsertBlock(existing: string, content: string): UpsertResult;
+/**
+ * True iff a block exists on disk and its inner contents no longer hash to its
+ * fingerprint (i.e. someone edited inside the markers).
+ */
+export declare function isHandEdited(block: ExtractedBlock): boolean;
+/**
+ * Remove the managed block from `existing`. Returns null if no block was present.
+ */
+export declare function removeBlock(existing: string): string | null;
+//# sourceMappingURL=block.d.ts.map

package/dist/cli/install/block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block.d.ts","sourceRoot":"","sources":["../../../src/cli/install/block.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,eAAO,MAAM,WAAW,yFAC2D,CAAC;AACpF,eAAO,MAAM,SAAS,0BAA0B,CAAC;AAKjD,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CASnD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAgBlE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAG5F;AAED,MAAM,WAAW,YAAY;IAC3B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,wGAAwG;IACxG,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;CACxC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,YAAY,CAiB3E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAO3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS3D"}

package/dist/cli/install/block.js

@@ -0,0 +1,106 @@
+/**
+ * OpenLore managed-block utilities.
+ *
+ * A "managed block" is a region inside an existing text file (typically Markdown)
+ * delimited by canonical comments. Re-running `openlore install` rewrites the
+ * block in place. A SHA-256 fingerprint over the canonical content lets us
+ * detect hand-edits and refuse to clobber them unless `--force` is passed.
+ */
+import { createHash } from 'node:crypto';
+export const BLOCK_BEGIN = '<!-- BEGIN OPENLORE (managed — edits inside this block will be overwritten) -->';
+export const BLOCK_END = '<!-- END OPENLORE -->';
+const FINGERPRINT_PREFIX = '<!-- openlore-fingerprint: ';
+const FINGERPRINT_SUFFIX = ' -->';
+export function fingerprint(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex').slice(0, 16);
+}
+/** Build the full managed block (markers + fingerprint comment + content). */
+export function renderBlock(content) {
+    const trimmed = content.trimEnd();
+    const fp = fingerprint(trimmed);
+    return [
+        BLOCK_BEGIN,
+        `${FINGERPRINT_PREFIX}${fp}${FINGERPRINT_SUFFIX}`,
+        trimmed,
+        BLOCK_END,
+    ].join('\n');
+}
+export function extractBlock(source) {
+    const beginIndex = source.indexOf(BLOCK_BEGIN);
+    if (beginIndex === -1)
+        return null;
+    const endMarkerIndex = source.indexOf(BLOCK_END, beginIndex + BLOCK_BEGIN.length);
+    if (endMarkerIndex === -1)
+        return null;
+    const endIndex = endMarkerIndex + BLOCK_END.length;
+    const inner = source.slice(beginIndex + BLOCK_BEGIN.length, endMarkerIndex);
+    const fpMatch = inner.match(/<!-- openlore-fingerprint: ([0-9a-f]+) -->/);
+    return {
+        beginIndex,
+        endIndex,
+        inner,
+        fingerprint: fpMatch ? fpMatch[1] : null,
+    };
+}
+/**
+ * Compute the fingerprint of the *current* inner content as it would be if we
+ * had written `expectedContent`. Used to decide whether the block on disk
+ * still matches what we last wrote.
+ */
+export function blockMatchesExpected(block, expectedContent) {
+    if (!block.fingerprint)
+        return false;
+    return block.fingerprint === fingerprint(expectedContent.trimEnd());
+}
+/**
+ * Upsert the managed block in `existing`. If a block exists, replace it; otherwise
+ * append. If the existing block's fingerprint matches the new content, do nothing.
+ *
+ * Caller is responsible for the `--force` / hand-edit check (use `isHandEdited`).
+ */
+export function upsertBlock(existing, content) {
+    const rendered = renderBlock(content);
+    const block = extractBlock(existing);
+    if (!block) {
+        const sep = existing.length === 0 || existing.endsWith('\n') ? '' : '\n';
+        const leading = existing.length === 0 ? '' : '\n';
+        return { next: `${existing}${sep}${leading}${rendered}\n`, action: 'created' };
+    }
+    if (blockMatchesExpected(block, content)) {
+        return { next: existing, action: 'noop' };
+    }
+    const before = existing.slice(0, block.beginIndex);
+    const after = existing.slice(block.endIndex);
+    return { next: `${before}${rendered}${after}`, action: 'updated' };
+}
+/**
+ * True iff a block exists on disk and its inner contents no longer hash to its
+ * fingerprint (i.e. someone edited inside the markers).
+ */
+export function isHandEdited(block) {
+    if (!block.fingerprint)
+        return false;
+    const innerWithoutFingerprintLine = block.inner
+        .replace(/<!-- openlore-fingerprint: [0-9a-f]+ -->\n?/, '')
+        .replace(/^\n+/, '')
+        .trimEnd();
+    return fingerprint(innerWithoutFingerprintLine) !== block.fingerprint;
+}
+/**
+ * Remove the managed block from `existing`. Returns null if no block was present.
+ */
+export function removeBlock(existing) {
+    const block = extractBlock(existing);
+    if (!block)
+        return null;
+    const before = existing.slice(0, block.beginIndex).replace(/\n+$/, '');
+    const after = existing.slice(block.endIndex).replace(/^\n+/, '');
+    if (before.length === 0 && after.length === 0)
+        return '';
+    if (before.length === 0)
+        return after.endsWith('\n') ? after : after + '\n';
+    if (after.length === 0)
+        return before + '\n';
+    return `${before}\n\n${after}`;
+}
+//# sourceMappingURL=block.js.map

package/dist/cli/install/block.js.map

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

package/dist/cli/install/detect.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Detect which agent surfaces are present in a project tree.
+ *
+ * We walk up from `cwd` checking up to 3 parent directories for marker files.
+ * The first directory that has any marker becomes the "project root" for that
+ * surface. `agents-md` is the universal fallback and is always included.
+ */
+export type AgentName = 'claude-code' | 'cursor' | 'cline' | 'continue' | 'agents-md';
+export declare const ALL_AGENTS: AgentName[];
+export interface DetectedSurface {
+    agent: AgentName;
+    /** Absolute path to the directory we will treat as the project root. */
+    root: string;
+    /** Which marker(s) triggered detection (for the dry-run summary). */
+    markers: string[];
+}
+/**
+ * Detect surfaces by walking up from `startDir` up to PARENTS_TO_CHECK levels.
+ * Each surface is reported at most once, anchored at the deepest dir where its
+ * marker was found. `agents-md` is always appended last as a universal fallback.
+ */
+export declare function detect(startDir: string): Promise<DetectedSurface[]>;
+//# sourceMappingURL=detect.d.ts.map

package/dist/cli/install/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../../src/cli/install/detect.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,CAAC;AAEtF,eAAO,MAAM,UAAU,EAAE,SAAS,EAMjC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,SAAS,CAAC;IACjB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAqED;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC,CAkBzE"}