@papillon6814/copi 0.1.0 → 0.2.0

package/dist/src/catalog.js

@@ -1,6 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm } from "node:fs/promises";
+import { lstat, readFile, readdir, realpath } from "node:fs/promises";
 import path from "node:path";
+import { assertNameAvailable, assertNoNameConflicts, findNameConflicts, nameKey } from "./names.js";
+import { assertPreparedInspection, inspectFixedResource, inspectPreparedResource } from "./inspect.js";
+import { absentStorageRevision, prepareStorageReview, storageTransactions } from "./storage-transaction.js";
+import { readSourceContent, validateContentLocations, validateRuntimeContentLocations } from "./source-content.js";
+const catalogRevisions = new WeakMap();
 const preparedSnapshots = new WeakMap();
 const kinds = new Set(["instruction", "skill", "subagent", "pi-settings", "mcp-config", "model-config", "keybindings"]);
 const scopes = new Set(["user", "project", "shared", "package"]);
@@ -8,7 +13,7 @@ const excludedNames = new Set([".git", ".cache", ".npm", "auth", "node_modules",
 const itemIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const groupIdPattern = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 export function newCatalog() {
-    return { version: 1, items: [], groups: [] };
+    return { version: 2, items: [], groups: [] };
 }
 function record(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -20,7 +25,7 @@ function isWithin(root, target) {
     return relative === "" || (!path.isAbsolute(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`));
 }
 function safeRelativePath(value) {
-    if (typeof value !== "string" || value.length === 0 || value.includes("\\") || path.posix.isAbsolute(value))
+    if (typeof value !== "string" || value.length === 0 || value.includes("\\") || value.includes("\0") || path.posix.isAbsolute(value))
         return false;
     const parts = value.split("/");
     return parts.every((part) => part.length > 0 && part !== "." && part !== "..") && path.posix.normalize(value) === value;
@@ -41,7 +46,7 @@ function parseSnapshotFile(value) {
         return undefined;
     return { path: file.path, mode: file.mode, sha256: file.sha256 };
 }
-function parseSavedItem(value) {
+function parseLegacySavedItem(value) {
     const item = record(value);
     if (!item || typeof item.id !== "string" || !itemIdPattern.test(item.id) || typeof item.kind !== "string" || !kinds.has(item.kind) || typeof item.source !== "string" || typeof item.scope !== "string" || !scopes.has(item.scope) || typeof item.sourcePath !== "string" || !path.isAbsolute(item.sourcePath) || typeof item.name !== "string" || item.name.length === 0 || typeof item.savedAt !== "string" || !Number.isFinite(Date.parse(item.savedAt)) || !Array.isArray(item.files))
         return undefined;
@@ -61,6 +66,14 @@ function parseSavedItem(value) {
         files: files,
     };
 }
+function parseSavedItem(value) {
+    const item = record(value);
+    const legacy = parseLegacySavedItem(value);
+    const content = record(item?.content);
+    if (!legacy || !content || (content.kind !== "file" && content.kind !== "tree") || typeof content.path !== "string")
+        return undefined;
+    return { ...legacy, content: { kind: content.kind, path: content.path } };
+}
 function parseGroup(value) {
     const group = record(value);
     if (!group || typeof group.id !== "string" || !groupIdPattern.test(group.id) || typeof group.name !== "string" || group.name.trim().length === 0 || !Array.isArray(group.itemIds) || group.itemIds.some((id) => typeof id !== "string" || !itemIdPattern.test(id)))
@@ -69,11 +82,12 @@ function parseGroup(value) {
         return undefined;
     return { id: group.id, name: group.name, itemIds: [...group.itemIds] };
 }
-function parseCatalog(value) {
+export function parseStoredCatalog(value) {
     const catalog = record(value);
-    if (!catalog || catalog.version !== 1 || !Array.isArray(catalog.items) || !Array.isArray(catalog.groups))
-        throw new Error("Invalid copi catalog: expected version 1 with item and group arrays.");
-    const items = catalog.items.map(parseSavedItem);
+    if (!catalog || (catalog.version !== 1 && catalog.version !== 2) || !Array.isArray(catalog.items) || !Array.isArray(catalog.groups)) {
+        throw new Error("Invalid copi catalog: expected version 1 or 2 with item and group arrays.");
+    }
+    const items = catalog.items.map(catalog.version === 1 ? parseLegacySavedItem : parseSavedItem);
     const groups = catalog.groups.map(parseGroup);
     if (items.some((item) => item === undefined) || groups.some((group) => group === undefined))
         throw new Error("Invalid copi catalog: an item or group has malformed fields.");
@@ -84,39 +98,17 @@ function parseCatalog(value) {
     const knownItems = new Set(itemIds);
     if (groups.some((group) => group?.itemIds.some((id) => !knownItems.has(id))))
         throw new Error("Invalid copi catalog: a group references an unknown item.");
-    return { version: 1, items: items, groups: groups };
-}
-async function ensurePrivateDirectory(requestedPath, mode) {
-    const absolute = path.resolve(requestedPath);
-    const parsed = path.parse(absolute);
-    const segments = absolute.slice(parsed.root.length).split(path.sep).filter(Boolean);
-    if (segments.length === 0)
-        throw new Error("Refusing to use the filesystem root as a copi directory.");
-    let current = parsed.root;
-    for (let index = 0; index < segments.length; index += 1) {
-        const segment = segments[index];
-        if (!segment)
-            continue;
-        let next = path.join(current, segment);
-        let stat = await lstat(next).catch(() => undefined);
-        if (!stat) {
-            await mkdir(next, { mode: 0o700 });
-            stat = await lstat(next);
-        }
-        if (stat.isSymbolicLink()) {
-            if (index === segments.length - 1)
-                throw new Error("Refusing to follow a symbolic link for a copi storage directory.");
-            next = await realpath(next);
-            stat = await lstat(next);
-        }
-        if (!stat.isDirectory())
-            throw new Error("A copi storage path component is not a directory.");
-        current = next;
-    }
-    await chmod(current, mode);
-    return await realpath(current);
+    if (catalog.version === 1)
+        return { version: 1, items: items, groups: groups };
+    const modern = { version: 2, items: items, groups: groups };
+    validateContentLocations(modern.items);
+    return modern;
+}
+export function assertModernCatalog(catalog) {
+    if (catalog.version !== 2)
+        throw new Error("This operation requires catalog v2; explicitly migrate the v1 library first.");
 }
-async function ensurePrivateSubdirectory(root, relativePath, mode, create) {
+async function existingPrivateSubdirectory(root, relativePath) {
     if (!safeRelativePath(relativePath))
         throw new Error("Unsafe relative path inside copi storage.");
     const canonicalRoot = await realpath(root);
@@ -126,19 +118,13 @@ async function ensurePrivateSubdirectory(root, relativePath, mode, create) {
     let current = canonicalRoot;
     for (const segment of relativePath.split("/")) {
         const next = path.join(current, segment);
-        let stat = await lstat(next).catch((error) => {
+        const stat = await lstat(next).catch((error) => {
             if (error.code === "ENOENT")
                 return undefined;
             throw error;
         });
-        if (!stat && create) {
-            await mkdir(next, { mode: 0o700 });
-            stat = await lstat(next);
-        }
         if (!stat || stat.isSymbolicLink() || !stat.isDirectory())
             throw new Error("Copi storage contains a missing, non-directory, or symbolic-link path component.");
-        if (mode !== undefined)
-            await chmod(next, mode);
         current = next;
     }
     return current;
@@ -264,32 +250,10 @@ function validateCandidate(candidate) {
     if (!candidate || typeof candidate !== "object" || !kinds.has(candidate.kind) || !scopes.has(candidate.scope) || typeof candidate.source !== "string" || !candidate.source || typeof candidate.name !== "string" || !candidate.name || !path.isAbsolute(candidate.sourceRoot) || !path.isAbsolute(candidate.sourcePath))
         throw new Error("Invalid resource candidate.");
     const destination = candidate.destination;
-    if (!destination || (destination.kind !== "global-only" && !(destination.kind === "project" && safeRelativePath(destination.path))))
-        throw new Error("Invalid resource destination.");
-}
-async function writeSnapshotFiles(root, itemId, files) {
-    const itemRoot = await ensurePrivateSubdirectory(root, path.posix.join("items", itemId, "files"), 0o700, true);
-    const snapshots = [];
-    for (const file of files) {
-        const outputPath = path.resolve(itemRoot, ...file.path.split("/"));
-        if (!isWithin(itemRoot, outputPath))
-            throw new Error("Snapshot file path escapes the item directory.");
-        const parentRelative = path.posix.dirname(file.path);
-        const parent = parentRelative === "." ? itemRoot : await ensurePrivateSubdirectory(itemRoot, parentRelative, 0o700, true);
-        const target = path.join(parent, path.basename(outputPath));
-        const handle = await open(target, "wx", 0o600);
-        try {
-            await handle.writeFile(file.bytes);
-            await handle.sync();
-        }
-        finally {
-            await handle.close();
-        }
-        snapshots.push({ path: file.path, mode: file.mode, sha256: createHash("sha256").update(file.bytes).digest("hex") });
-    }
-    return snapshots;
+    if (!destination || (destination.kind !== "global-only" && !(destination.kind === "project" && safeRelativePath(destination.path) && !excludedRelative(destination.path))))
+        throw new Error("Invalid or private/excluded resource destination.");
 }
-export async function loadCatalog(libraryDir) {
+async function loadCatalogUnlocked(libraryDir) {
     const root = await existingStoreRoot(libraryDir);
     if (!root)
         return newCatalog();
@@ -310,95 +274,196 @@ export async function loadCatalog(libraryDir) {
     catch (error) {
         throw new Error("Invalid copi catalog JSON.", { cause: error });
     }
-    return parseCatalog(value);
+    const catalog = parseStoredCatalog(value);
+    if (catalog.version === 2)
+        await validateRuntimeContentLocations(root, catalog.items);
+    return catalog;
+}
+export function catalogBytes(catalog) {
+    const validated = parseStoredCatalog(catalog);
+    assertModernCatalog(validated);
+    return Buffer.from(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
+}
+export async function loadCatalog(libraryDir) {
+    return storageTransactions.run(libraryDir, false, async (session) => {
+        if (!session) {
+            const catalog = newCatalog();
+            catalogRevisions.set(catalog, await absentStorageRevision(libraryDir));
+            return catalog;
+        }
+        const revision = await session.capture();
+        const catalog = await loadCatalogUnlocked(session.root);
+        await session.assertRevision(revision);
+        catalogRevisions.set(catalog, revision);
+        return catalog;
+    }, { requiresNativePlacement: false });
+}
+/** Internal seam: a single lock, checked catalog and all snapshots; no recursive reader locking. */
+export async function withSavedLibrary(libraryDir, operation) {
+    return storageTransactions.run(libraryDir, false, async (session) => {
+        if (!session)
+            throw new Error("Snapshot catalog does not exist.");
+        const revision = await session.capture();
+        const loaded = await loadCatalogUnlocked(session.root);
+        assertModernCatalog(loaded);
+        const catalog = loaded;
+        const files = new Map();
+        for (const item of catalog.items)
+            files.set(item.id, await readSnapshotFilesUnlocked(session.root, catalog, item));
+        await session.assertRevision(revision);
+        return operation({ catalog, revision, files, session });
+    }, { requiresNativePlacement: false });
 }
 export async function saveCatalog(libraryDir, catalog) {
-    const validated = parseCatalog(catalog);
-    const root = await ensurePrivateDirectory(libraryDir, 0o700);
-    const destination = path.join(root, "catalog.json");
-    const temporary = path.join(root, `catalog.${randomUUID()}.tmp`);
-    const handle = await open(temporary, "wx", 0o600);
-    try {
-        await handle.writeFile(`${JSON.stringify(validated, null, 2)}\n`, "utf8");
-        await handle.sync();
-    }
-    catch (error) {
-        await rm(temporary, { force: true });
-        throw error;
-    }
-    finally {
-        await handle.close();
-    }
-    await rename(temporary, destination);
-    await chmod(destination, 0o600);
+    const parsed = parseStoredCatalog(catalog);
+    assertModernCatalog(parsed);
+    const validated = parsed;
+    assertNoNameConflicts(validated);
+    const binding = catalogRevisions.get(catalog);
+    // Invalid new names are rejected without creating a library.
+    const preflight = await loadCatalog(libraryDir);
+    assertNoNameConflicts(preflight);
+    await validateRuntimeContentLocations(libraryDir, validated.items);
+    await storageTransactions.run(libraryDir, true, async (session) => {
+        if (!session)
+            throw new Error("Missing storage session.");
+        const revision = await session.capture();
+        const current = await loadCatalogUnlocked(session.root);
+        assertNoNameConflicts(current);
+        for (const item of current.items)
+            await readSnapshotFilesUnlocked(session.root, current, item);
+        if (binding)
+            await session.assertRevision(binding);
+        else {
+            if (current.items.length > 0 || current.groups.length > 0)
+                throw new Error("Saving an existing catalog requires the original object returned by loadCatalog; detached catalogs have no verified starting revision.");
+            if (JSON.stringify(current) !== JSON.stringify(preflight))
+                throw new Error("Catalog changed before saving.");
+        }
+        for (const item of validated.items) {
+            const old = current.items.find((entry) => entry.id === item.id);
+            if (old?.destination.kind === "global-only" && item.destination.kind !== "global-only")
+                throw new Error("A reference-only/global-only resource cannot become project-applicable.");
+            if (JSON.stringify(old?.destination) !== JSON.stringify(item.destination) && item.destination.kind === "project" && excludedRelative(item.destination.path))
+                throw new Error("Invalid or private/excluded resource destination.");
+            const files = await readSnapshotFilesUnlocked(session.root, validated, item);
+            if (!old || JSON.stringify(old.files) !== JSON.stringify(item.files)) {
+                const inspection = inspectFixedResource({ candidate: { ...item, sourceRoot: path.dirname(item.sourcePath) }, files, excludedPaths: [] });
+                if (inspection.sensitivePaths.length > 0)
+                    throw new Error("Content changes require a prepared inspection and individual approval; use the saved-change API.");
+            }
+        }
+        await session.commit(revision, catalogBytes(validated));
+        catalogRevisions.set(catalog, await session.capture());
+    }, { requiresNativePlacement: false });
 }
-async function storePreparedResource(libraryDir, candidate, sourceFiles, requestedGroupIds) {
+async function storePreparedResource(libraryDir, candidate, sourceFiles, requestedGroupIds, approvedSensitivePaths) {
+    const catalogPreflight = await loadCatalogUnlocked(libraryDir);
+    assertModernCatalog(catalogPreflight);
+    assertNoNameConflicts(catalogPreflight);
+    assertNameAvailable(catalogPreflight, "item", candidate.name);
     const groupIds = [...new Set(requestedGroupIds)];
-    const catalog = await loadCatalog(libraryDir);
-    const groups = new Map(catalog.groups.map((group) => [group.id, group]));
-    if (groupIds.some((id) => !groups.has(id)))
+    if (groupIds.some((id) => !catalogPreflight.groups.some((group) => group.id === id)))
         throw new Error("Cannot import a resource into an unknown group.");
-    const root = await ensurePrivateDirectory(libraryDir, 0o700);
-    const id = randomUUID();
-    const item = {
-        id,
-        kind: candidate.kind,
-        source: candidate.source,
-        scope: candidate.scope,
-        sourcePath: candidate.sourcePath,
-        destination: candidate.destination,
-        name: candidate.name,
-        savedAt: new Date().toISOString(),
-        files: [],
-    };
-    const itemDirectory = path.join(root, "items", id);
-    try {
-        item.files = await writeSnapshotFiles(root, id, sourceFiles);
+    return storageTransactions.run(libraryDir, true, async (session) => {
+        if (!session)
+            throw new Error("Missing storage session.");
+        const revision = await session.capture();
+        const catalog = await loadCatalogUnlocked(session.root);
+        assertModernCatalog(catalog);
+        assertNoNameConflicts(catalog);
+        assertNameAvailable(catalog, "item", candidate.name);
+        for (const saved of catalog.items)
+            await readSnapshotFilesUnlocked(session.root, catalog, saved);
+        const groups = new Map(catalog.groups.map((group) => [group.id, group]));
+        if (groupIds.some((id) => !groups.has(id)))
+            throw new Error("Cannot import a resource into an unknown group.");
+        const id = randomUUID();
+        let content;
+        if (candidate.kind === "skill") {
+            content = { kind: "tree", path: `sources/${id}` };
+        }
+        else {
+            const sourceFile = sourceFiles[0];
+            if (sourceFiles.length !== 1 || !sourceFile || sourceFile.path !== path.posix.basename(sourceFile.path)) {
+                throw new Error("Non-skill resources must be imported from one regular source file.");
+            }
+            content = { kind: "file", path: `sources/${id}/${sourceFile.path}` };
+        }
+        const item = {
+            id, kind: candidate.kind, source: candidate.source, scope: candidate.scope,
+            sourcePath: candidate.sourcePath, destination: { ...candidate.destination }, name: candidate.name.trim(), savedAt: new Date().toISOString(),
+            files: sourceFiles.map((file) => ({ path: file.path, mode: file.mode, sha256: createHash("sha256").update(file.bytes).digest("hex") })),
+            content,
+        };
         catalog.items.push(item);
         for (const groupId of groupIds)
-            groups.get(groupId)?.itemIds.push(id);
-        await saveCatalog(root, catalog);
-    }
-    catch (error) {
-        await rm(itemDirectory, { recursive: true, force: true });
-        throw error;
-    }
-    return item;
+            groups.get(groupId)?.itemIds.push(item.id);
+        const bytes = catalogBytes(catalog);
+        const replacements = [{ itemId: item.id, files: sourceFiles }];
+        const review = prepareStorageReview(bytes, replacements);
+        await session.commit(revision, bytes, replacements, { review, approval: { reviewId: review.reviewId, confirmed: true, approvedSensitivePaths: approvedSensitivePaths.map((filePath) => `${item.id}/${filePath}`) } });
+        return structuredClone(item);
+    }, { requiresNativePlacement: true });
 }
 export async function importPreparedResource(libraryDir, prepared, options) {
-    if (!options.confirmed)
+    if (options.confirmed !== true)
         return null;
     const snapshot = getPreparedSnapshot(prepared);
-    if (options.inspection.preparedResource !== prepared)
-        throw new Error("Inspection does not match the prepared resource.");
-    const inspectedPaths = new Set(options.inspection.sensitivePaths);
-    const approvedPaths = new Set(options.approvedSensitivePaths);
+    const inspection = options.inspection;
+    const approvedSensitivePaths = [...options.approvedSensitivePaths];
+    const groupIds = [...options.groupIds];
+    assertPreparedInspection(inspection, prepared);
+    const internalInspection = await inspectPreparedResource(prepared);
+    const inspectedPaths = new Set(internalInspection.sensitivePaths);
+    const approvedPaths = new Set(approvedSensitivePaths);
     const availablePaths = new Set(snapshot.files.map((file) => file.path));
-    if (inspectedPaths.size !== options.inspection.sensitivePaths.length || approvedPaths.size !== options.approvedSensitivePaths.length ||
+    if (inspectedPaths.size !== inspection.sensitivePaths.length || approvedPaths.size !== approvedSensitivePaths.length ||
         [...inspectedPaths].some((filePath) => !availablePaths.has(filePath)) || inspectedPaths.size !== approvedPaths.size ||
         [...inspectedPaths].some((filePath) => !approvedPaths.has(filePath))) {
         throw new Error("Prepared import requires approval for every suspected sensitive file in its inspection.");
     }
-    return storePreparedResource(libraryDir, snapshot.candidate, snapshot.files, options.groupIds);
+    return storePreparedResource(libraryDir, snapshot.candidate, snapshot.files, groupIds, [...approvedPaths]);
 }
 export async function importResource(libraryDir, candidate, options) {
-    if (!options.confirmed)
+    if (options.confirmed !== true)
         return null;
-    const prepared = await prepareResource(candidate);
+    const capturedCandidate = copyCandidate(candidate);
+    const suppliedInspection = options.inspection;
+    const approvedSensitivePaths = [...(options.approvedSensitivePaths ?? [])];
+    const groupIds = [...options.groupIds];
+    const prepared = suppliedInspection?.preparedResource ?? await prepareResource(capturedCandidate);
     const snapshot = getPreparedSnapshot(prepared);
-    return storePreparedResource(libraryDir, snapshot.candidate, snapshot.files, options.groupIds);
+    if (suppliedInspection) {
+        assertPreparedInspection(suppliedInspection, prepared);
+        const fixed = snapshot.candidate;
+        const sameDestination = capturedCandidate.destination?.kind === fixed.destination.kind &&
+            (fixed.destination.kind !== "project" || (capturedCandidate.destination.kind === "project" && capturedCandidate.destination.path === fixed.destination.path));
+        if (["id", "kind", "source", "scope", "sourceRoot", "sourcePath", "name"].some((key) => capturedCandidate[key] !== fixed[key]) || !sameDestination) {
+            throw new Error("Inspection candidate does not match the prepared resource metadata.");
+        }
+    }
+    const inspection = await inspectPreparedResource(prepared);
+    if (!suppliedInspection && inspection.sensitivePaths.length > 0)
+        throw new Error("A prepared inspection and individual approval are required for sensitive content.");
+    return importPreparedResource(libraryDir, prepared, { confirmed: true, groupIds, inspection: suppliedInspection ?? inspection, approvedSensitivePaths });
 }
-export async function readSnapshotFiles(libraryDir, item) {
+async function readSnapshotFilesUnlocked(libraryDir, catalog, item) {
     if (!itemIdPattern.test(item.id))
         throw new Error("Invalid snapshot identifier.");
     const root = await existingStoreRoot(libraryDir);
     if (!root)
         throw new Error("Snapshot catalog does not exist.");
-    const catalog = await loadCatalog(root);
     const storedItem = catalog.items.find((entry) => entry.id === item.id);
     if (!storedItem)
         throw new Error("Snapshot is not present in the catalog.");
-    const canonicalFilesRoot = await ensurePrivateSubdirectory(root, path.posix.join("items", storedItem.id, "files"), undefined, false);
+    if (catalog.version === 2) {
+        const modernItem = catalog.items.find((entry) => entry.id === item.id);
+        if (!modernItem)
+            throw new Error("Snapshot is not present in the v2 catalog.");
+        return readSourceContent(root, modernItem);
+    }
+    const canonicalFilesRoot = await existingPrivateSubdirectory(root, path.posix.join("items", storedItem.id, "files"));
     const results = [];
     for (const file of storedItem.files) {
         if (!safeRelativePath(file.path))
@@ -418,11 +483,78 @@ export async function readSnapshotFiles(libraryDir, item) {
             throw new Error("Snapshot path resolves outside the item directory.");
         const bytes = await readFile(canonicalFile);
         if (createHash("sha256").update(bytes).digest("hex") !== file.sha256)
-            throw new Error(`Snapshot checksum mismatch for ${file.path}.`);
+            throw new Error(`Snapshot checksum mismatch for ${file.path}: saved bytes were manually changed or damaged. Changes are stopped; inspect the saved copy and its source before re-importing. Checksums are not automatically repaired.`);
         results.push({ ...file, bytes });
     }
     return results;
 }
+export async function readSnapshotFiles(libraryDir, item) {
+    return storageTransactions.run(libraryDir, false, async (session) => {
+        if (!session)
+            throw new Error("Snapshot catalog does not exist.");
+        const revision = await session.capture();
+        const catalog = await loadCatalogUnlocked(session.root);
+        const result = await readSnapshotFilesUnlocked(session.root, catalog, item);
+        await session.assertRevision(revision);
+        return result;
+    }, { requiresNativePlacement: false });
+}
+/** Persist staged, explicit name-only changes together, so cancellation never partially resolves names. */
+export async function saveNameChanges(libraryDir, before, after) {
+    return withSavedLibrary(libraryDir, async ({ catalog: current, revision, session }) => {
+        await saveNameChangesLocked(before, after, current, revision, session);
+    });
+}
+async function saveNameChangesLocked(before, after, current, revision, session) {
+    const parsed = parseStoredCatalog(after);
+    assertModernCatalog(parsed);
+    const validated = parsed;
+    if (JSON.stringify(current) !== JSON.stringify(before))
+        throw new Error("Catalog changed while renaming; reload before trying again.");
+    const restored = structuredClone(validated);
+    const conflicts = findNameConflicts(before);
+    for (const namespace of ["item", "group"]) {
+        const previousEntries = namespace === "item" ? before.items : before.groups;
+        const nextEntries = namespace === "item" ? restored.items : restored.groups;
+        if (previousEntries.length !== nextEntries.length)
+            throw new Error("Renaming must preserve catalog entries.");
+        for (const [index, entry] of nextEntries.entries()) {
+            const previous = previousEntries[index];
+            if (!previous || previous.id !== entry.id)
+                throw new Error("Renaming must preserve catalog identifiers and order.");
+            if (entry.name !== previous.name) {
+                if (conflicts.length > 0 && !conflicts.some((conflict) => conflict.namespace === namespace && conflict.ids.includes(entry.id))) {
+                    throw new Error("Only conflicting names may change until duplicate names are resolved.");
+                }
+                nameKey(entry.name);
+                const finalEntries = namespace === "item" ? validated.items : validated.groups;
+                if (finalEntries.some((other) => other.id !== entry.id && nameKey(other.name) === nameKey(entry.name))) {
+                    throw new Error("Duplicate name; choose a unique display name.");
+                }
+            }
+            entry.name = previous.name;
+        }
+    }
+    if (JSON.stringify(restored) !== JSON.stringify(before))
+        throw new Error("Renaming must preserve metadata, files, destinations, and group references.");
+    const binding = catalogRevisions.get(before);
+    if (!binding)
+        throw new Error("Renaming requires the original before-catalog returned by loadCatalog; reload to obtain a verified revision.");
+    await session.assertRevision(binding);
+    await session.commit(revision, catalogBytes(validated));
+}
+export async function renameSavedItem(libraryDir, itemId, name) {
+    const before = await loadCatalog(libraryDir);
+    assertModernCatalog(before);
+    const after = structuredClone(before);
+    const item = after.items.find((entry) => entry.id === itemId);
+    if (!item)
+        throw new Error("Unknown saved item.");
+    assertNameAvailable(before, "item", name, itemId);
+    item.name = name.trim();
+    await saveNameChanges(libraryDir, before, after);
+    return item;
+}
 export async function listSnapshots(libraryDir) {
     const catalog = await loadCatalog(libraryDir);
     return [...catalog.items].sort((left, right) => right.savedAt.localeCompare(left.savedAt) || left.id.localeCompare(right.id));

package/dist/src/cli.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
-export declare function main(args?: string[], environment?: NodeJS.ProcessEnv, cwd?: string): Promise<number>;
+import { type MigrationCommandRuntime } from "./migrate.ts";
+export declare function main(args?: string[], environment?: NodeJS.ProcessEnv, cwd?: string, migrationRuntime?: MigrationCommandRuntime): Promise<number>;

package/dist/src/cli.js

@@ -3,26 +3,79 @@ import { realpathSync } from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { listSnapshots, loadCatalog } from "./catalog.js";
-import { printGroups, printItems, runApplyDryRun, runApplyWizard, runGroupManager, runSetup } from "./wizard.js";
+import { printGroups, printItems, runApplyDryRun, runApplyWizard, runGroupManager, runSetup, safeDisplay } from "./wizard.js";
+import { runManage } from "./manage.js";
+import { runMigrateCommand } from "./migrate.js";
 function usage() {
     process.stdout.write(`copi — copy and organize reusable Pi coding-agent resources
 
 Usage:
   copi setup
+  copi manage
   copi groups
   copi list
   copi apply <group> [target]
   copi apply <group> [target] --dry-run
+  copi migrate [--dry-run]
+  copi migrate --resolve [--dry-run]
   copi help
 
 Commands:
   setup              Search explicitly selected locations and save copied resources
+  manage             Select saved copies by name; masked view, edit, rename, refresh, groups, apply
   groups             Manage groups interactively; without a TTY, list groups only
   list               List saved snapshots without modifying the library
   apply <group>      Review and apply one group to the current directory or target
   apply --dry-run    Show the masked plan without changing project files
+  migrate            Review and migrate an eligible legacy library (TTY required)
+  migrate --dry-run  Show a read-only masked legacy migration review
+  migrate --resolve  Confirm resolution of eligible post-switch migration leftovers
   help               Show this help
 
+Manage requires an interactive stdin/stdout TTY; UUID input is not required.
+Resource names and group names are unique in separate library-wide namespaces:
+trim, NFKC, Unicode 17 default full case folding, then NFKC. Legacy duplicate
+names require manual resolution; only listing, masked viewing and resolution
+are allowed until resolved. Display name changes leave contents not rewritten
+and are separate from destination changes.
+
+Edit only existing UTF-8 saved files, at most 1_000_000 bytes; binary and unsupported
+encodings are rejected. Ctrl-S submits for diff review, not immediate saving;
+Esc / Ctrl-C cancels. Enter inserts a newline, arrows move, PgUp/PgDn scroll;
+bracketed paste supports multiple lines. Suspected sensitive raw text can expose
+secrets on the screen, scrollback or recordings: individual approval to expose
+is separate from approval to save. Fixed bytes are inspected before saving;
+each suspected sensitive file requires fresh individual approval.
+
+Pi loads only root context files (AGENTS.override.md, AGENTS.md, AGENTS.MD,
+CLAUDE.md, CLAUDE.MD) and .pi/SYSTEM.md or .pi/APPEND_SYSTEM.md automatically.
+apply warns when another instruction is not mentioned by a root context file and
+can add one reference line after a separate default-no approval; --dry-run shows
+the same warning and diff without writing.
+
+Refresh can reselect a same-kind source with explicit read permission; the whole
+saved copy is replaced after masked diff and individual file approvals. Copi-only edits
+will be lost. Originals are not written back. No history, restore or automatic merge
+is provided. Private saved files are 0600; apply reproduces the original source mode.
+File addition, deletion and internal rename through text editing, and applying
+global settings, are outside scope.
+
+Migration dry-runs are read-only and may run without a TTY. Mutating migration and
+resolution require both stdin and stdout to be a TTY; every confirmation defaults to no.
+Resolution first shows the complete masked diff, then asks about each sensitive path,
+then asks for a final confirmation. --resolve never falls back to ordinary migration.
+There is no --yes option. Cancellation, blocked
+reviews, invalid flags and non-TTY mutation exit with status 1. If an ordinary migration
+stops on an internal lock, use copi migrate --resolve --dry-run; never remove a lock by hand.
+
+Resolution only confirms eligible adopted-source edits and cleans up owned migration
+artifacts. A v4 journal has no start inventory, so it stays on the existing recovery/
+hold-stop path. It does not rewrite catalog, sources or items, distribute resources, or delete
+items. Do not use an older copi binary while resolution artifacts remain. v4 journals lack
+the start inventory required for this procedure and remain on the existing hold-stop path.
+A migration backup is not general history or a restore feature. Migration, items deletion,
+main integration and publishing require separate approval.
+
 Interactive changes require a TTY. Setup searches only locations explicitly selected
 and confirmed in the wizard. Directories named auth are excluded entirely; copied
 authentication-specific code may be missing from copied resources. Named authentication files and .env* paths,
@@ -38,12 +91,19 @@ function requireHome(environment) {
 function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-export async function main(args = process.argv.slice(2), environment = process.env, cwd = process.cwd()) {
+export async function main(args = process.argv.slice(2), environment = process.env, cwd = process.cwd(), migrationRuntime = {}) {
     const [command, ...rest] = args;
     if (!command || command === "help" || command === "--help" || command === "-h") {
         usage();
         return 0;
     }
+    if (command === "migrate" && (rest.includes("--help") || rest.includes("-h"))) {
+        if (rest.length === 1) {
+            usage();
+            return 0;
+        }
+        throw new Error("Usage: copi migrate [--dry-run] | copi migrate --resolve [--dry-run].");
+    }
     if (rest.includes("--help") || rest.includes("-h")) {
         usage();
         return 0;
@@ -54,6 +114,16 @@ export async function main(args = process.argv.slice(2), environment = process.e
         ? path.resolve(cwd, environment.PI_CODING_AGENT_DIR)
         : path.join(homeDir || requireHome(environment), ".pi", "agent");
     const projectDir = path.resolve(cwd);
+    if (command === "migrate")
+        return runMigrateCommand(rest, libraryDir, migrationRuntime);
+    if (command === "manage") {
+        if (rest.length > 0)
+            throw new Error("manage does not accept positional arguments.");
+        if (!isInteractive())
+            throw new Error("manage requires an interactive stdin/stdout TTY; no library was created or searched.");
+        await runManage(libraryDir, { homeDir, agentDir, projectDir });
+        return 0;
+    }
     if (command === "setup") {
         if (rest.length > 0)
             throw new Error("setup does not accept positional arguments.");
@@ -102,7 +172,7 @@ if (import.meta.url === invokedPath) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unexpected error.";
-        console.error(`copi: ${message}`);
+        console.error(`copi: ${safeDisplay(message)}`);
         process.exitCode = 1;
     }
 }