context-brake 0.0.0-stage → 1.1.0

package/dist/src/infrastructure/storage/handoff-claim-lock.js

@@ -0,0 +1,32 @@
+import { open, rm, stat } from 'node:fs/promises';
+import { isMissingFileError } from '../runtime/runtime-paths.js';
+const STALE_CLAIM_LOCK_MS = 30_000;
+export async function createExclusive(path) {
+    try {
+        await (await open(path, 'wx')).close();
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return false;
+        throw error;
+    }
+}
+export async function acquireClaimLock(lock, clock) {
+    if (await createExclusive(lock))
+        return true;
+    if (!(await isStale(lock, clock)))
+        return false;
+    await rm(lock, { force: true });
+    return createExclusive(lock);
+}
+async function isStale(lock, clock) {
+    try {
+        return clock.now().getTime() - (await stat(lock)).mtimeMs > STALE_CLAIM_LOCK_MS;
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return true;
+        throw error;
+    }
+}

package/dist/src/infrastructure/storage/json-document-editor.d.ts

@@ -0,0 +1,5 @@
+export { InvalidJsonDocumentError, validateJsonDocument, parseAndValidateJson } from './json-validator.js';
+export declare function setJsonProperty(text: string, path: readonly (string | number)[], value: unknown): string;
+export declare function appendJsonArrayItem(text: string, path: readonly (string | number)[], value: unknown): string;
+export declare function removeJsonProperty(text: string, path: readonly (string | number)[]): string;
+export declare function removeJsonArrayItem(text: string, path: readonly (string | number)[], predicate: (item: unknown) => boolean): string;

package/dist/src/infrastructure/storage/json-document-editor.js

@@ -0,0 +1,53 @@
+import { findNodeAtLocation, getNodeValue } from 'jsonc-parser';
+import { parseAndValidateJson } from './json-validator.js';
+import { detectEol, detectIndent, formatJsonValue, insertArrayItem, insertObjectEntry } from './json-span-utils.js';
+import { removeNodeSpan } from './json-node-removal.js';
+export { InvalidJsonDocumentError, validateJsonDocument, parseAndValidateJson } from './json-validator.js';
+export function setJsonProperty(text, path, value) {
+    const root = parseAndValidateJson(text);
+    const indent = detectIndent(text);
+    const eol = detectEol(text);
+    const format = text.includes('\n') ? indent : '';
+    const existingNode = findNodeAtLocation(root, path);
+    if (existingNode) {
+        const formatted = formatJsonValue(value, { indent: format, eol, depth: path.length });
+        return `${text.slice(0, existingNode.offset)}${formatted}${text.slice(existingNode.offset + existingNode.length)}`;
+    }
+    const parentPath = path.slice(0, -1);
+    const key = String(path[path.length - 1]);
+    const parentNode = parentPath.length === 0 ? root : findNodeAtLocation(root, parentPath);
+    if (!parentNode) {
+        return setJsonProperty(text, parentPath, { [key]: value });
+    }
+    const formattedVal = formatJsonValue(value, { indent: format, eol, depth: path.length });
+    return insertObjectEntry(text, parentNode, { key, formattedVal, indent: format, depth: path.length });
+}
+export function appendJsonArrayItem(text, path, value) {
+    const root = parseAndValidateJson(text);
+    const arrayNode = findNodeAtLocation(root, path);
+    if (!arrayNode) {
+        return setJsonProperty(text, path, [value]);
+    }
+    const indent = detectIndent(text);
+    const eol = detectEol(text);
+    const format = text.includes('\n') ? indent : '';
+    const formattedVal = formatJsonValue(value, { indent: format, eol, depth: path.length + 1 });
+    return insertArrayItem(text, arrayNode, { formattedVal, indent: format, depth: path.length + 1 });
+}
+export function removeJsonProperty(text, path) {
+    const root = parseAndValidateJson(text);
+    const node = findNodeAtLocation(root, path);
+    if (!node || !node.parent || node.parent.type !== 'property')
+        return text;
+    return removeNodeSpan(text, node.parent);
+}
+export function removeJsonArrayItem(text, path, predicate) {
+    const root = parseAndValidateJson(text);
+    const arrayNode = findNodeAtLocation(root, path);
+    if (!arrayNode || !arrayNode.children)
+        return text;
+    const target = arrayNode.children.find((child) => predicate(getNodeValue(child)));
+    if (!target)
+        return text;
+    return removeNodeSpan(text, target);
+}

package/dist/src/infrastructure/storage/json-node-removal.d.ts

@@ -0,0 +1,2 @@
+import type { Node } from 'jsonc-parser';
+export declare function removeNodeSpan(text: string, node: Node): string;

package/dist/src/infrastructure/storage/json-node-removal.js

@@ -0,0 +1,70 @@
+import { findLineEndAfter, findSeparatorComma } from './json-span-utils.js';
+function siblingContext(node) {
+    const list = node.parent?.children;
+    return list ? { list, index: list.indexOf(node) } : undefined;
+}
+function commaAfterPrevious(text, node) {
+    const context = siblingContext(node);
+    if (!context || context.index <= 0)
+        return -1;
+    const previous = context.list[context.index - 1];
+    return findSeparatorComma(text, previous.offset + previous.length, node.offset);
+}
+function commaBeforeNext(text, node) {
+    const context = siblingContext(node);
+    const next = context?.list[context.index + 1];
+    return next ? findSeparatorComma(text, node.offset + node.length, next.offset) : -1;
+}
+function isLastChild(node) {
+    const context = siblingContext(node);
+    return context === undefined || context.index === context.list.length - 1;
+}
+function isOnlyNodeOnLine(text, span) {
+    const leading = text.slice(span.lineStart, span.start);
+    return /^\s*$/.test(leading) && /^[ \t]*,?[ \t]*\r?\n?$/.test(text.slice(span.end, span.lineEnd));
+}
+function removeLastNode(text, node, span) {
+    const ownLine = isOnlyNodeOnLine(text, span);
+    const after = text.slice(ownLine ? span.lineEnd : span.end);
+    const comma = !ownLine || isLastChild(node) ? commaAfterPrevious(text, node) : -1;
+    const cut = ownLine ? span.lineStart : span.start;
+    if (comma === -1)
+        return `${text.slice(0, cut)}${after}`;
+    return `${text.slice(0, comma)}${text.slice(comma + 1, cut)}${after}`;
+}
+function removeBeforeComma(text, node, span) {
+    const before = text.slice(0, span.start);
+    const leadingComma = before.match(/,\s*$/);
+    if (leadingComma?.index !== undefined)
+        return `${before.slice(0, leadingComma.index)}${text.slice(span.end)}`;
+    const comma = commaBeforeNext(text, node);
+    if (comma === -1)
+        return `${before}${text.slice(span.end)}`;
+    return `${before}${text.slice(span.end, comma)}${text.slice(comma + 1)}`;
+}
+function emptyContainer(text, node) {
+    const container = node.parent;
+    if (container?.children?.length !== 1)
+        return undefined;
+    const open = container.offset + 1;
+    const close = container.offset + container.length - 1;
+    const rest = `${text.slice(open, node.offset)}${text.slice(node.offset + node.length, close)}`;
+    return /^\s*$/.test(rest) ? `${text.slice(0, open)}${text.slice(close)}` : undefined;
+}
+export function removeNodeSpan(text, node) {
+    const emptied = emptyContainer(text, node);
+    if (emptied !== undefined)
+        return emptied;
+    const start = node.offset;
+    const end = start + node.length;
+    const lineStart = text.lastIndexOf('\n', start) + 1;
+    const span = { start, end, lineStart, lineEnd: findLineEndAfter(text, end) };
+    if (isOnlyNodeOnLine(text, span))
+        return removeLastNode(text, node, span);
+    const trailingComma = text.slice(end).match(/^\s*,/);
+    if (trailingComma)
+        return `${text.slice(0, start)}${text.slice(end + trailingComma[0].length)}`;
+    if (isLastChild(node))
+        return removeLastNode(text, node, span);
+    return removeBeforeComma(text, node, span);
+}

package/dist/src/infrastructure/storage/json-span-utils.d.ts

@@ -0,0 +1,24 @@
+import type { Node } from 'jsonc-parser';
+export type FormatOptions = {
+    indent: string;
+    eol: string;
+    depth: number;
+};
+export type InsertEntryOptions = {
+    key: string;
+    formattedVal: string;
+    indent: string;
+    depth: number;
+};
+export type InsertItemOptions = {
+    formattedVal: string;
+    indent: string;
+    depth: number;
+};
+export declare function detectEol(text: string): string;
+export declare function detectIndent(text: string): string;
+export declare function findLineEndAfter(text: string, offset: number): number;
+export declare function formatJsonValue(value: unknown, opts: FormatOptions): string;
+export declare function findSeparatorComma(text: string, from: number, to: number): number;
+export declare function insertObjectEntry(text: string, parentNode: Node, opts: InsertEntryOptions): string;
+export declare function insertArrayItem(text: string, arrayNode: Node, opts: InsertItemOptions): string;

package/dist/src/infrastructure/storage/json-span-utils.js

@@ -0,0 +1,57 @@
+export function detectEol(text) {
+    return text.includes('\r\n') ? '\r\n' : '\n';
+}
+export function detectIndent(text) {
+    const match = text.match(/\n([ \t]+)[^\s]/);
+    return match?.[1] ?? '';
+}
+export function findLineEndAfter(text, offset) {
+    const newline = text.indexOf('\n', offset);
+    return newline === -1 ? text.length : newline + 1;
+}
+export function formatJsonValue(value, opts) {
+    const raw = JSON.stringify(value, null, opts.indent);
+    if (!raw.includes('\n'))
+        return raw;
+    const prefix = opts.indent.repeat(opts.depth);
+    return raw.split('\n').map((line, idx) => (idx === 0 ? line : `${prefix}${line}`)).join(opts.eol);
+}
+export function findSeparatorComma(text, from, to) {
+    let index = from;
+    while (index < to) {
+        if (text.startsWith('//', index))
+            index = findLineEndAfter(text, index + 2);
+        else if (text.startsWith('/*', index)) {
+            const close = text.indexOf('*/', index + 2);
+            index = close === -1 ? to : close + 2;
+        }
+        else if (text[index] === ',')
+            return index;
+        else
+            index += 1;
+    }
+    return -1;
+}
+function insertIntoContainer(text, container, opts) {
+    const compact = !text.includes('\n');
+    if (!container.children || container.children.length === 0) {
+        const pos = container.offset + 1;
+        const inner = compact ? opts.item : `${detectEol(text)}${opts.indent.repeat(opts.depth)}${opts.item}${detectEol(text)}${opts.indent.repeat(opts.depth - 1)}`;
+        return `${text.slice(0, pos)}${inner}${text.slice(pos)}`;
+    }
+    const last = container.children[container.children.length - 1];
+    const lastEnd = last.offset + last.length;
+    const closePos = container.offset + container.length - 1;
+    const gap = text.slice(lastEnd, closePos);
+    const closing = gap.match(/\s*$/)?.[0] ?? '';
+    const trivia = gap.slice(0, gap.length - closing.length);
+    const comma = findSeparatorComma(text, lastEnd, closePos) === -1 ? ',' : '';
+    const separator = compact ? '' : `${detectEol(text)}${opts.indent.repeat(opts.depth)}`;
+    return `${text.slice(0, lastEnd)}${comma}${trivia}${separator}${opts.item}${closing}${text.slice(closePos)}`;
+}
+export function insertObjectEntry(text, parentNode, opts) {
+    return insertIntoContainer(text, parentNode, { item: `${JSON.stringify(opts.key)}: ${opts.formattedVal}`, indent: opts.indent, depth: opts.depth });
+}
+export function insertArrayItem(text, arrayNode, opts) {
+    return insertIntoContainer(text, arrayNode, { item: opts.formattedVal, indent: opts.indent, depth: opts.depth });
+}

package/dist/src/infrastructure/storage/json-validator.d.ts

@@ -0,0 +1,13 @@
+import { type Node } from 'jsonc-parser';
+export declare class InvalidJsonDocumentError extends Error {
+    readonly issue: string;
+    readonly filePath?: string | undefined;
+    constructor(issue: string, filePath?: string | undefined);
+}
+export declare function findDuplicateKeys(node: Node): string[];
+export declare function validateJsonDocument(text: string): {
+    valid: boolean;
+    errors: string[];
+    duplicateKeys: string[];
+};
+export declare function parseAndValidateJson(text: string, filePath?: string): Node;

package/dist/src/infrastructure/storage/json-validator.js

@@ -0,0 +1,61 @@
+import { parseTree, printParseErrorCode } from 'jsonc-parser';
+export class InvalidJsonDocumentError extends Error {
+    issue;
+    filePath;
+    constructor(issue, filePath) {
+        super(filePath ? `Invalid JSON document in ${filePath}: ${issue}` : `Invalid JSON document: ${issue}`);
+        this.issue = issue;
+        this.filePath = filePath;
+        this.name = 'InvalidJsonDocumentError';
+    }
+}
+export function findDuplicateKeys(node) {
+    const duplicates = [];
+    function walk(current) {
+        if (current.type === 'object' && current.children) {
+            const seen = new Set();
+            for (const prop of current.children) {
+                if (prop.type === 'property' && prop.children?.[0]) {
+                    const key = String(prop.children[0].value);
+                    if (seen.has(key)) {
+                        duplicates.push(key);
+                    }
+                    else {
+                        seen.add(key);
+                    }
+                }
+            }
+        }
+        if (current.children) {
+            for (const child of current.children) {
+                walk(child);
+            }
+        }
+    }
+    walk(node);
+    return duplicates;
+}
+export function validateJsonDocument(text) {
+    const parseErrors = [];
+    const root = parseTree(text, parseErrors, { disallowComments: false });
+    const errorMessages = parseErrors.map((err) => `${printParseErrorCode(err.error)} at offset ${err.offset}`);
+    if (!root) {
+        const emptyErr = errorMessages.length > 0 ? errorMessages : ['Empty or invalid JSON document'];
+        return { valid: false, errors: emptyErr, duplicateKeys: [] };
+    }
+    const duplicates = findDuplicateKeys(root);
+    const isValid = parseErrors.length === 0 && duplicates.length === 0;
+    return { valid: isValid, errors: errorMessages, duplicateKeys: duplicates };
+}
+export function parseAndValidateJson(text, filePath) {
+    const result = validateJsonDocument(text);
+    if (!result.valid) {
+        const detail = result.duplicateKeys.length > 0 ? `Duplicate key: ${result.duplicateKeys.join(', ')}` : result.errors.join('; ');
+        throw new InvalidJsonDocumentError(detail, filePath);
+    }
+    const root = parseTree(text, [], { disallowComments: false });
+    if (!root) {
+        throw new InvalidJsonDocumentError('Root node not found', filePath);
+    }
+    return root;
+}

package/dist/src/infrastructure/storage/manifest-store.d.ts

@@ -0,0 +1,11 @@
+import { type InstallationManifest, type ManifestStore } from '../../core/contracts/manifest.js';
+import type { FileSnapshot, PlannedChange } from '../../core/contracts/changes.js';
+export declare class NodeManifestStore implements ManifestStore {
+    readonly projectRoot: string;
+    readonly manifestPath: string;
+    constructor(projectRoot: string);
+    load(): Promise<InstallationManifest | null>;
+    planSave(manifest: InstallationManifest, previous: InstallationManifest | null, snapshot?: FileSnapshot | null | undefined): PlannedChange;
+    save(manifest: InstallationManifest): Promise<void>;
+    delete(): Promise<void>;
+}

package/dist/src/infrastructure/storage/manifest-store.js

@@ -0,0 +1,45 @@
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { installationManifestSchema, MANIFEST_RELATIVE_PATH } from '../../core/contracts/manifest.js';
+import { normalizeSeparators } from './path-boundary.js';
+import { deleteFileIfExists, writeFileAtomically } from './atomic-writer.js';
+export class NodeManifestStore {
+    projectRoot;
+    manifestPath;
+    constructor(projectRoot) {
+        this.projectRoot = projectRoot;
+        this.manifestPath = resolve(projectRoot, MANIFEST_RELATIVE_PATH);
+    }
+    async load() {
+        try {
+            const content = await readFile(this.manifestPath, 'utf8');
+            const parsed = JSON.parse(content);
+            return installationManifestSchema.parse(parsed);
+        }
+        catch (err) {
+            if (err.code === 'ENOENT')
+                return null;
+            throw err;
+        }
+    }
+    planSave(manifest, previous, snapshot) {
+        const formatted = `${JSON.stringify(manifest, null, 2)}\n`;
+        const realPath = snapshot?.realPath ?? normalizeSeparators(this.manifestPath);
+        return {
+            path: MANIFEST_RELATIVE_PATH,
+            realPath,
+            kind: previous ? 'update' : 'create',
+            owner: 'manifest',
+            content: formatted,
+            preview: { summary: 'Record installation manifest with managed assets and entries' },
+        };
+    }
+    async save(manifest) {
+        const validated = installationManifestSchema.parse(manifest);
+        const formatted = `${JSON.stringify(validated, null, 2)}\n`;
+        await writeFileAtomically(this.manifestPath, formatted);
+    }
+    async delete() {
+        await deleteFileIfExists(this.manifestPath);
+    }
+}

package/dist/src/infrastructure/storage/node-file-system.d.ts

@@ -0,0 +1,4 @@
+import type { FileSnapshot } from '../../core/contracts/changes.js';
+export declare function computeSha256(content: string): Promise<string>;
+export declare function snapshotFile(projectRoot: string, relativePath: string): Promise<FileSnapshot>;
+export declare function snapshotFiles(projectRoot: string, relativePaths: readonly string[]): Promise<FileSnapshot[]>;

package/dist/src/infrastructure/storage/node-file-system.js

@@ -0,0 +1,33 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { assertWithinRepository, computeFileIdentity } from './path-boundary.js';
+export async function computeSha256(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+export async function snapshotFile(projectRoot, relativePath) {
+    const canonical = await assertWithinRepository(projectRoot, relativePath);
+    const fullPath = resolve(projectRoot, relativePath);
+    const linkStat = await lstat(fullPath).catch(() => null);
+    if (!linkStat) {
+        const identity = computeFileIdentity(canonical);
+        return { path: relativePath, realPath: canonical, exists: false, content: null, sha256: null, isSymlink: false, fileIdentity: identity };
+    }
+    const isSymlink = linkStat.isSymbolicLink();
+    const targetStat = await stat(fullPath).catch(() => null);
+    if (!targetStat || !targetStat.isFile()) {
+        const identity = computeFileIdentity(canonical, targetStat?.dev, targetStat?.ino);
+        return { path: relativePath, realPath: canonical, exists: targetStat !== null, content: null, sha256: null, isSymlink, fileIdentity: identity };
+    }
+    const content = await readFile(canonical, 'utf8');
+    const sha256 = await computeSha256(content);
+    const identity = computeFileIdentity(canonical, targetStat.dev, targetStat.ino);
+    return { path: relativePath, realPath: canonical, exists: true, content, sha256, isSymlink, fileIdentity: identity };
+}
+export async function snapshotFiles(projectRoot, relativePaths) {
+    const results = [];
+    for (const relativePath of relativePaths) {
+        results.push(await snapshotFile(projectRoot, relativePath));
+    }
+    return results;
+}

package/dist/src/infrastructure/storage/node-handoff-store.d.ts

@@ -0,0 +1,11 @@
+import { type HandoffStore } from '../../core/contracts/handoff.js';
+import type { ClaimDeadline } from '../../core/contracts/hook-phase.js';
+import type { Clock } from '../../core/contracts/session-ledger.js';
+export declare class NodeHandoffStore implements HandoffStore {
+    private readonly projectRoot;
+    private readonly clock;
+    constructor(projectRoot: string, clock: Clock);
+    pendingSince(): Promise<number | null>;
+    claim(deadline?: ClaimDeadline): Promise<string | null>;
+    private claimLocked;
+}

package/dist/src/infrastructure/storage/node-handoff-store.js

@@ -0,0 +1,96 @@
+import { constants } from 'node:fs';
+import { copyFile, mkdir, readdir, rename, rm, stat } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { HANDOFF_ARCHIVE_LIMIT, HANDOFF_ARCHIVE_RELATIVE_DIR, HANDOFF_RELATIVE_PATH } from '../../core/contracts/handoff.js';
+import { isMissingFileError } from '../runtime/runtime-paths.js';
+import { acquireClaimLock, createExclusive } from './handoff-claim-lock.js';
+const ARCHIVE_EXTENSION = '.md';
+const CLAIM_LOCK_NAME = '.claim.lock';
+const OPEN_DEADLINE = { isExpired: () => false, commit: () => true };
+export class NodeHandoffStore {
+    projectRoot;
+    clock;
+    constructor(projectRoot, clock) {
+        this.projectRoot = projectRoot;
+        this.clock = clock;
+    }
+    async pendingSince() {
+        try {
+            return (await stat(join(this.projectRoot, HANDOFF_RELATIVE_PATH))).mtimeMs;
+        }
+        catch (error) {
+            if (isMissingFileError(error))
+                return null;
+            throw error;
+        }
+    }
+    async claim(deadline = OPEN_DEADLINE) {
+        if ((await this.pendingSince()) === null)
+            return null;
+        const archive = join(this.projectRoot, HANDOFF_ARCHIVE_RELATIVE_DIR);
+        await mkdir(archive, { recursive: true });
+        const lock = join(archive, CLAIM_LOCK_NAME);
+        if (!(await acquireClaimLock(lock, this.clock)))
+            return null;
+        return this.claimLocked(archive, deadline).finally(() => rm(lock, { force: true }));
+    }
+    async claimLocked(archive, deadline) {
+        if ((await this.pendingSince()) === null || deadline.isExpired())
+            return null;
+        const name = await reserveName(archive, this.clock.now().toISOString().replace(/[-:]/g, ''));
+        const pending = join(this.projectRoot, HANDOFF_RELATIVE_PATH);
+        const archived = join(archive, name);
+        if (!(await moveInto(pending, archived)))
+            return null;
+        if (!deadline.commit()) {
+            await restoreHandoff(archived, pending);
+            return null;
+        }
+        await pruneOrRestore(archive, archived, pending);
+        return `${HANDOFF_ARCHIVE_RELATIVE_DIR}/${name}`;
+    }
+}
+async function pruneOrRestore(archive, archived, pending) {
+    try {
+        await pruneArchive(archive, basename(archived));
+    }
+    catch (error) {
+        await restoreHandoff(archived, pending);
+        throw error;
+    }
+}
+async function reserveName(archive, stamp) {
+    for (let suffix = 0;; suffix += 1) {
+        const name = suffix === 0 ? `${stamp}${ARCHIVE_EXTENSION}` : `${stamp}-${suffix}${ARCHIVE_EXTENSION}`;
+        if (await createExclusive(join(archive, name)))
+            return name;
+    }
+}
+async function moveInto(source, reserved) {
+    try {
+        await rename(source, reserved);
+        return true;
+    }
+    catch (error) {
+        await rm(reserved, { force: true });
+        if (isMissingFileError(error))
+            return false;
+        throw error;
+    }
+}
+async function restoreHandoff(archived, pending) {
+    try {
+        await copyFile(archived, pending, constants.COPYFILE_EXCL);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            return;
+        throw error;
+    }
+    await rm(archived, { force: true });
+}
+async function pruneArchive(archive, delivered) {
+    const names = (await readdir(archive)).filter((name) => name.endsWith(ARCHIVE_EXTENSION) && name !== delivered).sort();
+    const excess = names.slice(0, Math.max(0, names.length - (HANDOFF_ARCHIVE_LIMIT - 1)));
+    await Promise.all(excess.map((name) => rm(join(archive, name), { force: true })));
+}

package/dist/src/infrastructure/storage/package-metadata.d.ts

@@ -0,0 +1,7 @@
+export declare class PackageMetadataError extends Error {
+    readonly issue: string;
+    constructor(issue: string);
+}
+export declare function packageJsonCandidates(baseDir: string): string[];
+export declare function readPackageVersionFrom(baseDir: string): Promise<string>;
+export declare function readPackageVersion(): Promise<string>;

package/dist/src/infrastructure/storage/package-metadata.js

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+import { z } from 'zod';
+const currentDir = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_NAME = 'context-brake';
+const packageJsonSchema = z.object({
+    name: z.string(),
+    version: z.string(),
+}).passthrough();
+export class PackageMetadataError extends Error {
+    issue;
+    constructor(issue) {
+        super(`Unable to read ${PACKAGE_NAME} package metadata: ${issue}`);
+        this.issue = issue;
+        this.name = 'PackageMetadataError';
+    }
+}
+export function packageJsonCandidates(baseDir) {
+    return [
+        resolve(baseDir, '../../../../package.json'),
+        resolve(baseDir, '../../../package.json'),
+    ];
+}
+async function readCandidate(candidate) {
+    const raw = await readFile(candidate, 'utf8');
+    return JSON.parse(raw);
+}
+async function loadPackageJson(baseDir) {
+    const candidates = packageJsonCandidates(baseDir);
+    for (const candidate of candidates) {
+        try {
+            return await readCandidate(candidate);
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new PackageMetadataError(`no package.json found among candidate paths: ${candidates.join(', ')}`);
+}
+export async function readPackageVersionFrom(baseDir) {
+    const raw = await loadPackageJson(baseDir);
+    const parsed = packageJsonSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new PackageMetadataError(`package.json does not match the expected shape: ${parsed.error.message}`);
+    }
+    if (parsed.data.name !== PACKAGE_NAME) {
+        throw new PackageMetadataError(`package.json 'name' is '${parsed.data.name}', expected '${PACKAGE_NAME}'`);
+    }
+    if (!semver.valid(parsed.data.version)) {
+        throw new PackageMetadataError(`package.json 'version' is not valid semver: '${parsed.data.version}'`);
+    }
+    return parsed.data.version;
+}
+export function readPackageVersion() {
+    return readPackageVersionFrom(currentDir);
+}

package/dist/src/infrastructure/storage/path-boundary.d.ts

@@ -0,0 +1,11 @@
+export declare class RepositoryBoundaryError extends Error {
+    readonly targetPath: string;
+    readonly projectRoot: string;
+    constructor(targetPath: string, projectRoot: string);
+}
+export declare function normalizeSeparators(filePath: string): string;
+export declare function arePathsEqual(pathA: string, pathB: string): boolean;
+export declare function resolveCanonicalPath(baseDir: string, targetPath: string): Promise<string>;
+export declare function isWithinRepository(projectRoot: string, targetPath: string): Promise<boolean>;
+export declare function assertWithinRepository(projectRoot: string, targetPath: string): Promise<string>;
+export declare function computeFileIdentity(canonicalPath: string, dev?: number, ino?: number): string;