@papillon6814/copi 0.1.0 → 0.2.1

package/dist/src/refresh.js

@@ -0,0 +1,143 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { types } from "node:util";
+import { prepareResource, readPreparedResource, withSavedLibrary } from "./catalog.js";
+import { discoverResources } from "./discovery.js";
+import { inspectPreparedResource } from "./inspect.js";
+import { commitSavedChange, prepareSavedReplacement, readSavedChange } from "./resource-mutations.js";
+const refreshes = new WeakMap();
+// Only an actual declared-package discovery result can authorize node_modules, not caller strings.
+const discoveredOrigins = new WeakMap();
+const candidateFields = ["id", "kind", "source", "scope", "sourceRoot", "sourcePath", "name", "destination"];
+// Capture only plain own data, without executing caller accessors, Proxy traps,
+// toJSON or coercion. The same detached capture is checked and later read.
+function ownData(value) {
+    if (typeof value !== "object" || value === null || types.isProxy(value) || Object.getPrototypeOf(value) !== Object.prototype)
+        throw new Error("Refresh candidate must contain plain own data without proxies or custom prototypes.");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const captured = {};
+    for (const key of Reflect.ownKeys(descriptors)) {
+        const descriptor = typeof key === "string" ? descriptors[key] : undefined;
+        if (!descriptor || !descriptor.enumerable || !("value" in descriptor))
+            throw new Error("Refresh candidate must not contain accessors, symbols or non-enumerable fields.");
+        Object.defineProperty(captured, key, { value: descriptor.value, enumerable: true });
+    }
+    return captured;
+}
+function captureCandidate(source) {
+    const values = ownData(source);
+    if (Object.keys(values).length !== candidateFields.length || candidateFields.some(key => !Object.hasOwn(values, key)) || candidateFields.some(key => key !== "destination" && typeof values[key] !== "string"))
+        throw new Error("Invalid refresh candidate fields.");
+    const destination = ownData(values.destination);
+    let fixedDestination;
+    if (destination.kind === "global-only" && Object.keys(destination).length === 1)
+        fixedDestination = { kind: "global-only" };
+    else if (destination.kind === "project" && Object.keys(destination).length === 2 && typeof destination.path === "string")
+        fixedDestination = { kind: "project", path: destination.path };
+    else
+        throw new Error("Invalid refresh candidate destination fields.");
+    return {
+        id: values.id, kind: values.kind, source: values.source,
+        scope: values.scope, sourceRoot: values.sourceRoot,
+        sourcePath: values.sourcePath, name: values.name, destination: fixedDestination,
+    };
+}
+function matchesOrigin(fixed, origin) {
+    return candidateFields.every(key => key === "destination" || fixed[key] === origin[key]) &&
+        fixed.destination.kind === origin.destination.kind &&
+        (fixed.destination.kind !== "project" || (origin.destination.kind === "project" && fixed.destination.path === origin.destination.path));
+}
+const excluded = new Set(["auth", "auth.json", "mcp-auth.json", "oauth.json", "cache", "caches", ".cache", ".npm", ".git", "history", "sessions"]);
+function within(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+/** Metadata checks only. Never follows arbitrary links, including links above the selected boundary. */
+export async function resolveRefreshPath(requested) {
+    if (!path.isAbsolute(requested) || requested.includes("\0") || requested.includes("\\"))
+        throw new Error("Select an absolute source path without unsafe path characters.");
+    let physical = path.resolve(requested);
+    for (const [alias, target] of [["/tmp", "/private/tmp"], ["/var", "/private/var"]]) {
+        if (physical === alias || physical.startsWith(`${alias}/`)) {
+            const stat = await lstat(alias);
+            if (stat.isSymbolicLink()) {
+                if (process.platform !== "darwin" || await realpath(alias) !== target)
+                    throw new Error("Unsafe source ancestor symbolic link.");
+                physical = target + physical.slice(alias.length);
+            }
+        }
+    }
+    let current = path.parse(physical).root;
+    for (const component of physical.slice(current.length).split(path.sep).filter(Boolean)) {
+        current = path.join(current, component);
+        if ((await lstat(current)).isSymbolicLink())
+            throw new Error("Symbolic links in source or source ancestors are not followed.");
+    }
+    return physical;
+}
+/** Call only after explicit discovery-root/scope consent; no implicit HOME or parent search. */
+export async function discoverRefreshOrigin(item, options) {
+    if (!options.scopes || (!options.scopes.home && !options.scopes.project))
+        throw new Error("Refresh origin discovery requires explicitly selected search scopes.");
+    const original = await resolveRefreshPath(item.sourcePath);
+    const discovery = await discoverResources(options);
+    const candidate = discovery.candidates.find(entry => entry.kind === item.kind && entry.sourcePath === original);
+    if (!candidate)
+        return undefined;
+    // Discovery validates declarations, authorized package roots and exclusions. Manual paths never inherit this authority.
+    if (candidate.scope === "package" && candidate.source.startsWith("package:")) {
+        const evidence = captureCandidate(candidate);
+        Object.freeze(evidence.destination);
+        discoveredOrigins.set(candidate, Object.freeze(evidence));
+    }
+    return candidate;
+}
+function stateOf(prepared) {
+    const state = refreshes.get(prepared);
+    if (!state)
+        throw new Error("Invalid or unavailable prepared refresh token.");
+    return state;
+}
+export async function prepareRefresh(libraryDir, itemId, source) {
+    const fixed = captureCandidate(source); // One capture, before any await.
+    const origin = discoveredOrigins.get(source);
+    if (origin && !matchesOrigin(fixed, origin))
+        throw new Error("Declared refresh origin changed after discovery; rediscover and review before reading.");
+    const registeredPackage = origin !== undefined;
+    const before = await withSavedLibrary(libraryDir, async (state) => ({ catalog: structuredClone(state.catalog), revision: state.revision }));
+    const item = before.catalog.items.find(entry => entry.id === itemId);
+    if (!item)
+        throw new Error("Unknown saved resource.");
+    if (fixed.kind !== item.kind)
+        throw new Error("Refresh source must have the same resource kind.");
+    fixed.sourcePath = await resolveRefreshPath(fixed.sourcePath);
+    fixed.sourceRoot = await resolveRefreshPath(fixed.sourceRoot);
+    if (!within(fixed.sourceRoot, fixed.sourcePath))
+        throw new Error("Refresh source escapes its physical boundary.");
+    for (const component of fixed.sourcePath.split(path.sep)) {
+        const lower = component.toLowerCase();
+        if (excluded.has(lower) || lower.startsWith(".env") || (lower === "node_modules" && !registeredPackage))
+            throw new Error("Selected source is in a private/excluded ancestor; choose a non-excluded path or explicitly rediscover its declared package origin.");
+    }
+    const stat = await lstat(fixed.sourcePath);
+    if (fixed.kind === "skill" ? !stat.isDirectory() : !stat.isFile())
+        throw new Error("Refresh source shape must match: skill directory, or regular file for other resource kinds.");
+    if ((fixed.kind === "model-config" || fixed.kind === "keybindings") && fixed.destination.kind !== "global-only")
+        throw new Error("Reference-only source kind cannot become project-applicable.");
+    const preparedSource = await prepareResource(fixed);
+    await inspectPreparedResource(preparedSource);
+    const change = await prepareSavedReplacement(libraryDir, itemId, preparedSource);
+    // Ensure the old state captured here is the state reviewed by the replacement kernel.
+    // Sessions never escape their callbacks or remain open across UI prompts.
+    await withSavedLibrary(libraryDir, async (state) => { await state.session.assertRevision(before.revision); });
+    const prepared = Object.freeze({ reviewId: change.reviewId });
+    refreshes.set(prepared, { change, originalCatalog: before.catalog, source: readPreparedResource(preparedSource).candidate });
+    return prepared;
+}
+export function readRefresh(prepared) {
+    const state = stateOf(prepared);
+    return { ...readSavedChange(state.change), originalCatalog: structuredClone(state.originalCatalog), source: structuredClone(state.source) };
+}
+export async function commitRefresh(prepared, approval) {
+    return commitSavedChange(stateOf(prepared).change, approval);
+}

package/dist/src/resource-mutations.d.ts

@@ -0,0 +1,45 @@
+import { type PreparedResource } from "./catalog.ts";
+import type { InspectionWarning, ResourceDestination, SavedItem, SnapshotFileContents } from "./types.ts";
+declare const editBrand: unique symbol;
+declare const changeBrand: unique symbol;
+export interface PreparedSavedEdit {
+    readonly [editBrand]: true;
+}
+export interface PreparedSavedChange {
+    readonly [changeBrand]: true;
+    readonly reviewId: string;
+}
+export interface ChangeApproval {
+    reviewId: string;
+    confirmed: boolean;
+    approvedSensitivePaths: readonly string[];
+}
+export interface SavedEditView {
+    readonly item: SavedItem;
+    readonly file: SnapshotFileContents;
+    readonly sensitivePaths: readonly string[];
+    readonly warnings: readonly InspectionWarning[];
+}
+export interface SavedFileDiff {
+    readonly path: string;
+    readonly bytesChanged: boolean;
+    readonly diff: string;
+    readonly summary: string;
+}
+export interface SavedChangeView {
+    readonly reviewId: string;
+    readonly item: SavedItem;
+    readonly diffs: readonly SavedFileDiff[];
+    readonly sensitivePaths: readonly string[];
+    readonly excludedPaths: readonly string[];
+    readonly warnings: readonly InspectionWarning[];
+    readonly bytesChanged: boolean;
+}
+export declare function prepareSavedEdit(libraryDir: string, itemId: string, filePath: string): Promise<PreparedSavedEdit>;
+export declare function prepareSavedChange(edit: PreparedSavedEdit, bytes: Buffer): Promise<PreparedSavedChange>;
+export declare function readSavedEdit(edit: PreparedSavedEdit): SavedEditView;
+export declare function readSavedChange(change: PreparedSavedChange): SavedChangeView;
+export declare function commitSavedChange(change: PreparedSavedChange, approval: ChangeApproval): Promise<SavedItem>;
+export declare function changeSavedDestination(libraryDir: string, itemId: string, destination: ResourceDestination): Promise<SavedItem>;
+export declare function prepareSavedReplacement(libraryDir: string, itemId: string, preparedSource: PreparedResource): Promise<PreparedSavedChange>;
+export {};

package/dist/src/resource-mutations.js

@@ -0,0 +1,225 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { catalogBytes, readPreparedResource, withSavedLibrary } from "./catalog.js";
+import { inspectFixedResource, maskSensitiveText } from "./inspect.js";
+import { assertNoNameConflicts } from "./names.js";
+import { privateStoragePath as privatePath, readStorageBeforeReviewFiles, safeStoragePath } from "./storage-transaction.js";
+const edits = new WeakMap();
+const changes = new WeakMap();
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function editable(bytes) {
+    if (!Buffer.isBuffer(bytes))
+        throw new Error("Editing requires UTF-8 bytes.");
+    if (bytes.length > 1_000_000)
+        throw new Error("Saved text editing is limited to 1_000_000 bytes (1 MB).");
+    if (bytes.includes(0))
+        throw new Error("Binary/NUL content is not editable as UTF-8 text.");
+    try {
+        return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        throw new Error("Unsupported encoding: saved text must be valid UTF-8.");
+    }
+}
+function candidate(item) { return { ...structuredClone(item), sourceRoot: path.dirname(item.sourcePath) }; }
+function findItem(state, itemId) {
+    const item = state.catalog.items.find((entry) => entry.id === itemId);
+    if (!item)
+        throw new Error("Unknown saved item.");
+    return item;
+}
+function assertKnownLayout(item, files) {
+    const current = new Map(files.map((file) => [file.path, file]));
+    if (current.size !== files.length)
+        throw new Error("Registered sources content has duplicate paths.");
+    if (item.content.kind === "file" && (files.length !== 1 || files[0]?.path !== path.posix.basename(item.content.path))) {
+        throw new Error("Registered sources file must resolve to its single catalog path.");
+    }
+}
+function editState(edit) {
+    const state = edits.get(edit);
+    if (!state)
+        throw new Error("Invalid or unavailable prepared edit token.");
+    return state;
+}
+function changeState(change) {
+    const state = changes.get(change);
+    if (!state)
+        throw new Error("Invalid or unavailable prepared change token.");
+    return state;
+}
+function inspect(item, files, excludedPaths = []) {
+    return inspectFixedResource({ candidate: candidate(item), files, excludedPaths });
+}
+function fileDiffs(before, after) {
+    const previous = new Map(before.map((file) => [file.path, file]));
+    const next = new Map(after.map((file) => [file.path, file]));
+    return [...new Set([...previous.keys(), ...next.keys()])].sort().map((filePath) => {
+        const old = previous.get(filePath);
+        const current = next.get(filePath);
+        const bytesChanged = !old || !current || !old.bytes.equals(current.bytes);
+        let diff = "";
+        try {
+            diff = createTwoFilesPatch(old ? filePath : "(new)", current ? filePath : "(removed)", maskSensitiveText(old ? editable(old.bytes) : ""), maskSensitiveText(current ? editable(current.bytes) : ""));
+        }
+        catch { /* Binary/large replacement files are summarized, never decoded or exposed. */ }
+        return { path: filePath, bytesChanged, diff, summary: `${bytesChanged ? "Bytes changed" : "Bytes unchanged"}; ${old?.bytes.length ?? 0} → ${current?.bytes.length ?? 0} bytes; mode ${old?.mode.toString(8) ?? "absent"} → ${current?.mode.toString(8) ?? "absent"}.` };
+    });
+}
+function sameIncludedFiles(before, current) {
+    if (before.length !== current.length)
+        return false;
+    const byPath = new Map(current.map((file) => [file.path, file]));
+    return byPath.size === current.length && before.every((file) => {
+        const listed = byPath.get(file.path);
+        return listed !== undefined && file.bytes.equals(listed.bytes);
+    });
+}
+async function makeChange(state, session, nextFiles, nextItem, excludedPaths = []) {
+    const files = nextFiles.map((file) => ({ path: file.path, mode: file.mode, bytes: Buffer.from(file.bytes) }));
+    for (const file of files)
+        if (!safeStoragePath(file.path) || privatePath(file.path))
+            throw new Error("Unsafe or excluded snapshot path in saved change.");
+    if (files.length === 0 || new Set(files.map((file) => file.path)).size !== files.length)
+        throw new Error("Saved replacement must contain unique registered files.");
+    const item = structuredClone(nextItem);
+    item.files = files.map((file) => ({ path: file.path, mode: file.mode, sha256: sha256(file.bytes) }));
+    const catalog = structuredClone(state.catalog);
+    const itemIndex = catalog.items.findIndex((entry) => entry.id === item.id);
+    if (itemIndex < 0)
+        throw new Error("Saved item changed after preparation.");
+    catalog.items[itemIndex] = structuredClone(item);
+    const replacements = [{ itemId: item.id, files }];
+    const storageReview = await session.prepareSourcesReview(state.revision, catalogBytes(catalog), replacements);
+    const capturedBefore = readStorageBeforeReviewFiles(storageReview, item.id);
+    if (!sameIncludedFiles(capturedBefore, state.files))
+        throw new Error("Before-reviewed source list does not match the current included files for this revision.");
+    const currentByPath = new Map(state.files.map((file) => [file.path, file]));
+    const beforeFiles = capturedBefore.map((file) => ({
+        ...file,
+        mode: currentByPath.get(file.path).mode,
+    }));
+    const diffs = fileDiffs(beforeFiles, files);
+    const change = Object.freeze({ reviewId: randomUUID() });
+    changes.set(change, { ...state, storageReview, nextFiles: files, nextItem: item, excludedPaths: [...excludedPaths], inspection: inspect(item, files, excludedPaths), diffs, changed: diffs.some((diff) => diff.bytesChanged) || JSON.stringify(item) !== JSON.stringify(state.item), used: false });
+    return change;
+}
+export async function prepareSavedEdit(libraryDir, itemId, filePath) {
+    if (!safeStoragePath(filePath) || privatePath(filePath))
+        throw new Error("Unsafe or excluded saved edit path.");
+    return withSavedLibrary(libraryDir, async (state) => {
+        assertNoNameConflicts(state.catalog);
+        const item = findItem(state, itemId);
+        const files = state.files.get(item.id);
+        assertKnownLayout(item, files);
+        if (!item.files.some((entry) => entry.path === filePath))
+            throw new Error("Only an existing registered snapshot file can be edited.");
+        const file = files.find((entry) => entry.path === filePath);
+        if (!file)
+            throw new Error("Only an existing registered snapshot file can be edited.");
+        editable(file.bytes);
+        const edit = Object.freeze({});
+        edits.set(edit, { libraryDir: state.session.root, revision: state.revision, catalog: structuredClone(state.catalog), item: structuredClone(item), files, filePath });
+        return edit;
+    });
+}
+export async function prepareSavedChange(edit, bytes) {
+    const prepared = editState(edit);
+    const fixed = Buffer.from(bytes);
+    editable(fixed);
+    return withSavedLibrary(prepared.libraryDir, async (state) => {
+        await state.session.assertRevision(prepared.revision);
+        assertNoNameConflicts(state.catalog);
+        const item = findItem(state, prepared.item.id);
+        const files = state.files.get(item.id);
+        assertKnownLayout(item, files);
+        if (!item.files.some((entry) => entry.path === prepared.filePath))
+            throw new Error("Only an existing registered snapshot file can be edited.");
+        const sourceFile = files.find((file) => file.path === prepared.filePath);
+        if (!sourceFile)
+            throw new Error("Registered source file disappeared before edit preparation.");
+        const current = {
+            libraryDir: state.session.root,
+            revision: state.revision,
+            catalog: structuredClone(state.catalog),
+            item: structuredClone(item),
+            files,
+        };
+        return makeChange(current, state.session, files.map((file) => ({ ...file, bytes: file.path === prepared.filePath ? fixed : file.bytes })), item);
+    });
+}
+export function readSavedEdit(edit) {
+    const state = editState(edit);
+    const file = state.files.find((file) => file.path === state.filePath);
+    const inspection = inspect(state.item, [file]);
+    return { item: structuredClone(state.item), file: { ...file, bytes: Buffer.from(file.bytes) }, sensitivePaths: [...inspection.sensitivePaths], warnings: structuredClone(inspection.warnings) };
+}
+export function readSavedChange(change) {
+    const state = changeState(change);
+    return { reviewId: change.reviewId, item: structuredClone(state.nextItem), diffs: structuredClone(state.diffs), sensitivePaths: [...state.inspection.sensitivePaths], excludedPaths: [...state.excludedPaths], warnings: structuredClone(state.inspection.warnings), bytesChanged: state.diffs.some((diff) => diff.bytesChanged) };
+}
+export async function commitSavedChange(change, approval) {
+    const state = changeState(change);
+    if (state.used)
+        throw new Error("Prepared change was already committed; prepare and review again.");
+    if (approval.confirmed !== true)
+        throw new Error("Saved change was not confirmed; no bytes were written.");
+    if (approval.reviewId !== change.reviewId)
+        throw new Error("Approval reviewId does not match this prepared change.");
+    const inspected = inspect(state.nextItem, state.nextFiles, state.excludedPaths);
+    const approved = new Set(approval.approvedSensitivePaths);
+    if (approved.size !== approval.approvedSensitivePaths.length || approved.size !== inspected.sensitivePaths.length || inspected.sensitivePaths.some((filePath) => !approved.has(filePath)))
+        throw new Error("Individual approval is required for every suspected sensitive file in this saved change.");
+    return withSavedLibrary(state.libraryDir, async ({ catalog, session }) => {
+        assertNoNameConflicts(catalog);
+        await session.assertRevision(state.revision);
+        const item = catalog.items.find((item) => item.id === state.item.id);
+        if (!item)
+            throw new Error("Saved item changed after preparation.");
+        if (!state.changed) {
+            state.used = true;
+            return structuredClone(item);
+        }
+        catalog.items[catalog.items.indexOf(item)] = structuredClone(state.nextItem);
+        const bytes = catalogBytes(catalog);
+        const replacements = [{ itemId: item.id, files: state.nextFiles }];
+        const review = state.storageReview;
+        await session.commit(state.revision, bytes, replacements, { review, approval: { reviewId: review.reviewId, confirmed: true, approvedSensitivePaths: [...approved].map((filePath) => `${item.id}/${filePath}`) } });
+        state.used = true;
+        return structuredClone(state.nextItem);
+    });
+}
+export async function changeSavedDestination(libraryDir, itemId, destination) {
+    if (!destination || (destination.kind !== "global-only" && (destination.kind !== "project" || !safeStoragePath(destination.path) || privatePath(destination.path))))
+        throw new Error("Unsafe or private/excluded saved destination.");
+    const fixed = { ...destination };
+    return withSavedLibrary(libraryDir, async ({ catalog, revision, session }) => {
+        assertNoNameConflicts(catalog);
+        const item = catalog.items.find((entry) => entry.id === itemId);
+        if (!item)
+            throw new Error("Unknown saved item.");
+        if (item.destination.kind === "global-only" && fixed.kind !== "global-only")
+            throw new Error("A reference-only/global-only resource cannot become project-applicable.");
+        if (JSON.stringify(item.destination) === JSON.stringify(fixed))
+            return structuredClone(item);
+        item.destination = fixed;
+        await session.commit(revision, catalogBytes(catalog));
+        return structuredClone(item);
+    });
+}
+export async function prepareSavedReplacement(libraryDir, itemId, preparedSource) {
+    const source = readPreparedResource(preparedSource);
+    return withSavedLibrary(libraryDir, async (state) => {
+        assertNoNameConflicts(state.catalog);
+        const item = findItem(state, itemId);
+        const currentFiles = state.files.get(item.id);
+        assertKnownLayout(item, currentFiles);
+        if (source.candidate.kind !== item.kind)
+            throw new Error("Replacement source must have the same resource kind.");
+        if (source.candidate.destination.kind === "global-only" && item.destination.kind !== "global-only")
+            throw new Error("A reference-only/global-only replacement source cannot become project-applicable.");
+        const next = { ...structuredClone(item), source: source.candidate.source, scope: source.candidate.scope, sourcePath: source.candidate.sourcePath };
+        return makeChange({ libraryDir: state.session.root, revision: state.revision, catalog: structuredClone(state.catalog), item: structuredClone(item), files: currentFiles }, state.session, source.files, next, source.excludedPaths);
+    });
+}

package/dist/src/source-content.d.ts

@@ -0,0 +1,4 @@
+import type { SavedItem, SnapshotFileContents } from "./types.ts";
+export declare function validateContentLocations(items: readonly SavedItem[]): void;
+export declare function validateRuntimeContentLocations(libraryDir: string, items: readonly SavedItem[]): Promise<void>;
+export declare function readSourceContent(libraryDir: string, item: SavedItem): Promise<SnapshotFileContents[]>;

package/dist/src/source-content.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, open, readdir, realpath } from "node:fs/promises";
+import path from "node:path";
+const excludedNames = new Set([
+    ".git", ".cache", ".npm", "auth", "node_modules", "cache", "caches", "history", "sessions",
+    "auth.json", "mcp-auth.json", "oauth.json",
+]);
+const digest = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function safeRelativePath(value) {
+    return typeof value === "string" && value.length > 0 && !value.includes("\\") && !value.includes("\0") &&
+        !path.posix.isAbsolute(value) && value.split("/").every((part) => part !== "" && part !== "." && part !== "..") &&
+        path.posix.normalize(value) === value;
+}
+function isWithin(root, target) {
+    const relative = path.relative(root, target);
+    return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
+}
+function excludedPath(value) {
+    return value.split("/").some((part) => {
+        const lower = part.toLowerCase();
+        return excludedNames.has(lower) || lower === ".env" || lower.startsWith(".env");
+    });
+}
+function assertContentLocation(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new Error("Invalid content location in copi catalog.");
+    const content = value;
+    if ((content.kind !== "file" && content.kind !== "tree") || typeof content.path !== "string" ||
+        !safeRelativePath(content.path) || !content.path.startsWith("sources/") || excludedPath(content.path.slice("sources/".length))) {
+        throw new Error("Invalid or unsafe content path in copi catalog; content must be a safe path below sources/.");
+    }
+}
+export function validateContentLocations(items) {
+    const locations = [];
+    for (const item of items) {
+        assertContentLocation(item.content);
+        if (item.content.kind !== (item.kind === "skill" ? "tree" : "file")) {
+            throw new Error(`Invalid content kind for ${item.kind} item ${item.id}.`);
+        }
+        if (item.files.length === 0)
+            throw new Error(`Content item ${item.id} has no registered files.`);
+        if (item.content.kind === "file") {
+            const registered = item.files.length === 1 && item.files[0]?.path === path.posix.basename(item.content.path);
+            if (!registered)
+                throw new Error(`File content for ${item.id} must register exactly its content file.`);
+        }
+        locations.push({ id: item.id, location: item.content });
+    }
+    for (let index = 0; index < locations.length; index += 1) {
+        const current = locations[index];
+        for (const other of locations.slice(index + 1)) {
+            const left = current.location.path;
+            const right = other.location.path;
+            if (left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`)) {
+                throw new Error(`Duplicate or overlapping content locations for items ${current.id} and ${other.id}.`);
+            }
+        }
+    }
+}
+function sameInode(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameFileState(left, right) {
+    return sameInode(left, right) && left.size === right.size && left.mtimeNs === right.mtimeNs &&
+        left.ctimeNs === right.ctimeNs && left.mode === right.mode;
+}
+async function safeLibraryRoot(libraryDir) {
+    const requested = path.resolve(libraryDir);
+    const rootStat = await lstat(requested);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error("Copi content root is not a safe directory.");
+    const root = await realpath(requested);
+    if (root !== requested)
+        throw new Error("Copi content root changed through a symbolic link.");
+    return root;
+}
+async function checkedPath(root, relative, directory) {
+    if (!safeRelativePath(relative))
+        throw new Error("Catalog contains an unsafe content path.");
+    const target = path.resolve(root, ...relative.split("/"));
+    if (!isWithin(root, target))
+        throw new Error("Content path escapes the copi library.");
+    let current = root;
+    for (const segment of relative.split("/")) {
+        current = path.join(current, segment);
+        const stat = await lstat(current);
+        if (stat.isSymbolicLink())
+            throw new Error("Content contains an unsafe symbolic link.");
+    }
+    const canonical = await realpath(target);
+    if (!isWithin(root, canonical))
+        throw new Error("Content path resolves outside the copi library.");
+    const stat = await lstat(target);
+    if (directory ? !stat.isDirectory() : !stat.isFile())
+        throw new Error(`Content path is not a regular ${directory ? "directory" : "file"}.`);
+    return canonical;
+}
+export async function validateRuntimeContentLocations(libraryDir, items) {
+    if (items.length === 0)
+        return;
+    validateContentLocations(items);
+    const libraryRoot = await safeLibraryRoot(libraryDir);
+    const sourcesRoot = await checkedPath(libraryRoot, "sources", true);
+    const locations = [];
+    for (const item of items) {
+        const canonical = await checkedPath(libraryRoot, item.content.path, item.content.kind === "tree");
+        if (!isWithin(sourcesRoot, canonical))
+            throw new Error("Content path escapes the canonical sources root.");
+        const stat = await lstat(canonical, { bigint: true });
+        for (const other of locations) {
+            if (sameInode(stat, other.identity) || isWithin(other.path, canonical) || isWithin(canonical, other.path)) {
+                throw new Error(`Duplicate or overlapping physical content locations for items ${other.id} and ${item.id}.`);
+            }
+        }
+        locations.push({ id: item.id, path: canonical, identity: stat });
+    }
+}
+async function readRegularFile(libraryRoot, contentRoot, target) {
+    const before = await lstat(target, { bigint: true });
+    if (!before.isFile() || before.isSymbolicLink())
+        throw new Error("Source content is not a regular file or is a symbolic link.");
+    const canonical = await realpath(target);
+    if (!isWithin(libraryRoot, canonical) || !isWithin(contentRoot, canonical))
+        throw new Error("Source content resolves outside its registered content location.");
+    const handle = await open(target, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const opened = await handle.stat({ bigint: true });
+        if (!opened.isFile() || !sameFileState(before, opened))
+            throw new Error("Source content changed while it was being opened.");
+        const bytes = await handle.readFile();
+        const [afterHandle, after] = await Promise.all([handle.stat({ bigint: true }), lstat(target, { bigint: true })]);
+        if (after.isSymbolicLink() || !sameFileState(opened, afterHandle) || !sameFileState(opened, after)) {
+            throw new Error("Source content changed while it was being read.");
+        }
+        return { bytes, mode: Number(opened.mode & 511n) };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readSourceContent(libraryDir, item) {
+    validateContentLocations([item]);
+    const libraryRoot = await safeLibraryRoot(libraryDir);
+    const sourcesRoot = await checkedPath(libraryRoot, "sources", true);
+    const contentRoot = await checkedPath(libraryRoot, item.content.path, item.content.kind === "tree");
+    if (!isWithin(sourcesRoot, contentRoot))
+        throw new Error("Content path escapes the canonical sources root.");
+    const descriptors = new Map(item.files.map((file) => [file.path, file]));
+    const results = [];
+    const readAt = async (absolutePath, relativePath) => {
+        if (!safeRelativePath(relativePath))
+            throw new Error("Source content contains an unsafe relative file path.");
+        if (excludedPath(relativePath))
+            return;
+        const value = await readRegularFile(libraryRoot, contentRoot, absolutePath);
+        const descriptor = descriptors.get(relativePath);
+        results.push({
+            path: relativePath,
+            mode: descriptor?.mode ?? value.mode,
+            sha256: digest(value.bytes),
+            bytes: value.bytes,
+        });
+    };
+    if (item.content.kind === "file") {
+        const filePath = path.posix.basename(item.content.path);
+        if (excludedPath(filePath))
+            throw new Error("Registered source content is in an excluded path.");
+        await readAt(contentRoot, filePath);
+    }
+    else {
+        const visit = async (directory, relative) => {
+            const before = await lstat(directory);
+            const canonicalDirectory = await realpath(directory);
+            if (!before.isDirectory() || before.isSymbolicLink() || !isWithin(contentRoot, canonicalDirectory))
+                throw new Error("Source tree contains an unsafe non-directory or symbolic link.");
+            const names = await readdir(directory);
+            for (const name of names.sort((left, right) => left.localeCompare(right))) {
+                const childRelative = relative ? `${relative}/${name}` : name;
+                if (excludedPath(childRelative))
+                    continue;
+                const childPath = path.join(directory, name);
+                const stat = await lstat(childPath);
+                if (stat.isSymbolicLink())
+                    throw new Error("Source tree contains an unsafe symbolic link.");
+                if (stat.isDirectory())
+                    await visit(childPath, childRelative);
+                else if (stat.isFile())
+                    await readAt(childPath, childRelative);
+                else
+                    throw new Error("Source tree contains an unsupported special file.");
+            }
+            const after = await lstat(directory);
+            const finalNames = await readdir(directory);
+            if (after.isSymbolicLink() || after.dev !== before.dev || after.ino !== before.ino || JSON.stringify(finalNames.sort((left, right) => left.localeCompare(right))) !== JSON.stringify(names.sort((left, right) => left.localeCompare(right)))) {
+                throw new Error("Source tree directory changed while it was being read.");
+            }
+        };
+        await visit(contentRoot, "");
+        if (item.kind === "skill" && !results.some((file) => file.path === "SKILL.md")) {
+            throw new Error("Skill content is missing required root SKILL.md.");
+        }
+    }
+    if (results.length === 0)
+        throw new Error("Source content contains no readable files.");
+    results.sort((left, right) => left.path.localeCompare(right.path));
+    return results;
+}