@papillon6814/copi 0.1.0 → 0.2.1

package/dist/src/groups.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { assertNameAvailable, assertNoNameConflicts, nameKey } from "./names.js";
 function findGroup(catalog, groupId) {
     const group = catalog.groups.find((item) => item.id === groupId);
     if (!group)
@@ -6,20 +7,24 @@ function findGroup(catalog, groupId) {
     return group;
 }
 function normalizedName(name) {
-    if (name.trim().length === 0)
-        throw new Error("Group name must not be empty.");
+    nameKey(name);
     return name.trim();
 }
 export function createGroup(catalog, name) {
+    assertNoNameConflicts(catalog);
+    assertNameAvailable(catalog, "group", name);
     const group = { id: randomUUID(), name: normalizedName(name), itemIds: [] };
     catalog.groups.push(group);
     return group;
 }
 export function renameGroup(catalog, groupId, name) {
+    const group = findGroup(catalog, groupId);
     const nextName = normalizedName(name);
-    findGroup(catalog, groupId).name = nextName;
+    assertNameAvailable(catalog, "group", nextName, groupId);
+    group.name = nextName;
 }
 export function setGroupItems(catalog, groupId, itemIds) {
+    assertNoNameConflicts(catalog);
     const group = findGroup(catalog, groupId);
     if (!Array.isArray(itemIds) || new Set(itemIds).size !== itemIds.length)
         throw new Error("Group membership must contain unique item identifiers.");

package/dist/src/inspect.d.ts

@@ -1,5 +1,7 @@
-import { type PreparedResource, type PreparedInspection } from "./catalog.ts";
+import { type PreparedResource, type PreparedInspection, type PreparedResourceContents } from "./catalog.ts";
 import type { InspectionResult, ResourceCandidate } from "./types.ts";
+export declare function inspectFixedResource({ candidate, files, excludedPaths }: PreparedResourceContents): InspectionResult;
 export declare function inspectPreparedResource(prepared: PreparedResource): Promise<PreparedInspection>;
+export declare function assertPreparedInspection(inspection: PreparedInspection, prepared: PreparedResource): void;
 export declare function inspectResource(candidate: ResourceCandidate): Promise<InspectionResult>;
 export declare function maskSensitiveText(value: string): string;

package/dist/src/inspect.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { prepareResource, readPreparedResource } from "./catalog.js";
+const inspections = new WeakSet();
 const maxInspectionBytes = 1_000_000;
 const relativePathReference = /(?:^|[\s"'`])(?:\.{1,2}\/)?[A-Za-z0-9_.@-]+(?:\/[A-Za-z0-9_.@-]+)+(?:$|[\s"'`),;!?])/m;
 function addWarning(warnings, code, message, relativePath) {
@@ -13,8 +14,7 @@ function containsInlineSecret(text) {
     const bearer = /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/i;
     return namedValue.test(text) || recognizableToken.test(text) || bearer.test(text);
 }
-export async function inspectPreparedResource(prepared) {
-    const { candidate, files, excludedPaths } = readPreparedResource(prepared);
+export function inspectFixedResource({ candidate, files, excludedPaths }) {
     const warnings = [];
     const sensitivePaths = [];
     addWarning(warnings, "secret-detection-limited", "Secret detection is heuristic and cannot guarantee completeness.");
@@ -64,12 +64,22 @@ export async function inspectPreparedResource(prepared) {
     }
     if (candidate.destination.kind === "global-only")
         addWarning(warnings, "global-only", "This resource is saved for reference and cannot be applied to a project.");
-    return Object.freeze({
-        warnings: Object.freeze(warnings.map((warning) => Object.freeze({ ...warning }))),
-        sensitivePaths: Object.freeze([...new Set(sensitivePaths)].sort((left, right) => left.localeCompare(right))),
-        excludedPaths: Object.freeze([...new Set(excludedPaths)].sort((left, right) => left.localeCompare(right))),
+    return { warnings, sensitivePaths: [...new Set(sensitivePaths)].sort((left, right) => left.localeCompare(right)), excludedPaths: [...new Set(excludedPaths)].sort((left, right) => left.localeCompare(right)) };
+}
+export async function inspectPreparedResource(prepared) {
+    const result = inspectFixedResource(readPreparedResource(prepared));
+    const inspection = Object.freeze({
+        warnings: Object.freeze(result.warnings.map((warning) => Object.freeze({ ...warning }))),
+        sensitivePaths: Object.freeze(result.sensitivePaths),
+        excludedPaths: Object.freeze(result.excludedPaths),
         preparedResource: prepared,
     });
+    inspections.add(inspection);
+    return inspection;
+}
+export function assertPreparedInspection(inspection, prepared) {
+    if (!inspections.has(inspection) || inspection.preparedResource !== prepared)
+        throw new Error("Inspection does not match the prepared resource or is not an authentic inspection.");
 }
 export async function inspectResource(candidate) {
     const prepared = await prepareResource(candidate);

package/dist/src/instruction-reference.d.ts

@@ -0,0 +1,6 @@
+export declare const contextFileNames: readonly string[];
+export declare function isAutoLoadedInstruction(destination: string): boolean;
+export declare function referenceLine(instructionPath: string): string;
+export declare function unreferencedPaths(instructionPaths: readonly string[], contextTexts: readonly string[]): string[];
+export declare function chooseReferenceTarget(existingNames: readonly string[]): string;
+export declare function appendReferenceLines(existing: string | undefined, instructionPaths: readonly string[]): string;

package/dist/src/instruction-reference.js

@@ -0,0 +1,21 @@
+import path from "node:path";
+export const contextFileNames = ["AGENTS.override.md", "AGENTS.md", "AGENTS.MD", "CLAUDE.md", "CLAUDE.MD"];
+const systemPromptPaths = new Set([".pi/SYSTEM.md", ".pi/APPEND_SYSTEM.md"]);
+export function isAutoLoadedInstruction(destination) {
+    return contextFileNames.includes(path.posix.basename(destination)) || systemPromptPaths.has(destination);
+}
+export function referenceLine(instructionPath) {
+    return `- 作業を始める前に \`${instructionPath}\` を読み、その指示に従うこと。`;
+}
+export function unreferencedPaths(instructionPaths, contextTexts) {
+    return [...new Set(instructionPaths)].filter((value) => !contextTexts.some((text) => text.includes(value)));
+}
+export function chooseReferenceTarget(existingNames) {
+    return contextFileNames.find((name) => existingNames.includes(name)) ?? "AGENTS.md";
+}
+export function appendReferenceLines(existing, instructionPaths) {
+    const lines = `${instructionPaths.map(referenceLine).join("\n")}\n`;
+    if (!existing)
+        return lines;
+    return `${existing.endsWith("\n") ? existing : `${existing}\n`}\n${lines}`;
+}

package/dist/src/manage.d.ts

@@ -0,0 +1,2 @@
+import { type SearchRoots } from "./wizard.ts";
+export declare function runManage(libraryDir: string, roots: SearchRoots): Promise<void>;

package/dist/src/manage.js

@@ -0,0 +1,329 @@
+import { confirm, intro, isCancel, note, outro, select, text } from "@clack/prompts";
+import path from "node:path";
+import { lstat } from "node:fs/promises";
+import { assertModernCatalog, loadCatalog, readSnapshotFiles, saveCatalog, saveNameChanges } from "./catalog.js";
+import { assertNameAvailable, assertNoNameConflicts, findNameConflicts } from "./names.js";
+import { commitSavedChange, prepareSavedChange, prepareSavedEdit, readSavedChange, readSavedEdit } from "./resource-mutations.js";
+import { editTerminalText } from "./terminal-editor.js";
+import { commitRefresh, discoverRefreshOrigin, prepareRefresh, readRefresh, resolveRefreshPath } from "./refresh.js";
+import { resolveNameConflicts, runApplyWizard, runGroupManager, runSetup, safeDisplay, withEditorInput, withWizardLifecycle } from "./wizard.js";
+class Cancelled extends Error {
+}
+function checked(value, signal) {
+    if (isCancel(value) || signal.aborted)
+        throw new Cancelled();
+    return value;
+}
+async function choose(message, options, signal) {
+    return checked(await select({ message, signal, options: options.map(option => ({ ...option, label: safeDisplay(option.label), ...(option.hint === undefined ? {} : { hint: safeDisplay(option.hint) }) })) }), signal);
+}
+async function yes(message, signal) {
+    return checked(await confirm({ message: safeDisplay(message), initialValue: false, signal }), signal) === true;
+}
+function show(body, title) { note(safeDisplay(body), safeDisplay(title)); }
+function hint(catalog, item, order) {
+    const groups = catalog.groups.filter(group => group.itemIds.includes(item.id)).map(group => group.name).join(", ") || "no groups";
+    return `${groups} · ${item.destination.kind === "project" ? item.destination.path : "saved only"} · ${item.source} · saved ${item.savedAt} · entry ${order + 1}`;
+}
+async function savedFile(item, signal) {
+    if (item.files.length === 0) {
+        show("No registered saved files.", item.name);
+        return undefined;
+    }
+    return choose("Select saved file", item.files.map(file => ({ value: file.path, label: file.path })), signal);
+}
+async function view(libraryDir, item, signal) {
+    const filePath = await savedFile(item, signal);
+    if (filePath === undefined)
+        return;
+    const file = (await readSnapshotFiles(libraryDir, item)).find(file => file.path === filePath);
+    if (!file)
+        throw new Error("Selected saved file is no longer registered; reload the library.");
+    if (file.bytes.length > 1_000_000 || file.bytes.includes(0)) {
+        show(`${file.path}: [binary or large file, ${file.bytes.length} bytes; content not displayed]`, "Masked saved view");
+        return;
+    }
+    try {
+        const content = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(file.bytes);
+        // Full text, not a silently truncated preview. Display safety never alters stored bytes.
+        process.stdout.write(`\nMasked saved view: ${safeDisplay(item.name)} · ${safeDisplay(file.path)}\n${safeDisplay(content)}\n`);
+    }
+    catch {
+        show(`${file.path}: [unsupported encoding, ${file.bytes.length} bytes; content not displayed]`, "Masked saved view");
+    }
+}
+async function edit(libraryDir, item, signal) {
+    const filePath = await savedFile(item, signal);
+    if (filePath === undefined)
+        return;
+    const prepared = await prepareSavedEdit(libraryDir, item.id, filePath);
+    const original = readSavedEdit(prepared);
+    show(original.warnings.map(w => `${w.path ? `${w.path}: ` : ""}${w.message}`).join("\n"), "Editing warnings · original files will not be changed");
+    if (original.sensitivePaths.includes(filePath) && !await yes(`Expose raw text of ${filePath} from ${item.name} in the editor? Suspected secrets may be exposed on the screen, scrollback or terminal recordings. Detection is heuristic. This individual approval is not approval to save.`, signal)) {
+        outro("Raw text was not exposed; nothing was saved.");
+        return;
+    }
+    if (signal.aborted)
+        throw new Cancelled();
+    const initial = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(original.file.bytes);
+    const result = await withEditorInput(() => editTerminalText(initial));
+    if (result.kind === "cancelled" || signal.aborted)
+        throw new Cancelled();
+    const change = await prepareSavedChange(prepared, Buffer.from(result.text, "utf8"));
+    const review = readSavedChange(change);
+    if (!review.bytesChanged) {
+        outro("No byte changes; nothing was saved.");
+        return;
+    }
+    process.stdout.write(`\n${safeDisplay(`Full masked saved diff: ${item.name}`)}\n`);
+    for (const diff of review.diffs)
+        process.stdout.write(`${safeDisplay(diff.path)}\n${safeDisplay(diff.summary)}\n${safeDisplay(diff.diff)}\n`);
+    show(review.warnings.map(w => `${w.path ? `${w.path}: ` : ""}${w.message}`).join("\n"), "Save warnings · masked text can hide byte changes");
+    if (!await yes("Approve this masked diff for saving? All hunks and byte summaries are shown above.", signal)) {
+        outro("Diff was not approved; nothing was saved.");
+        return;
+    }
+    const approvedSensitivePaths = [];
+    for (const file of review.sensitivePaths) {
+        if (!await yes(`Save suspected sensitive file ${file} from ${item.name}? This is a new approval for the prepared edited bytes, separate from raw text exposure. Detection is heuristic.`, signal)) {
+            outro("Sensitive saved bytes were not approved; nothing was saved.");
+            return;
+        }
+        approvedSensitivePaths.push(file);
+    }
+    if (!await yes(`Save edited copy of ${filePath}? Original files stay unchanged; no history or restore is provided.`, signal)) {
+        outro("Nothing was saved.");
+        return;
+    }
+    if (signal.aborted)
+        throw new Cancelled();
+    await commitSavedChange(change, { reviewId: change.reviewId, confirmed: true, approvedSensitivePaths });
+    outro("Edited saved copy committed with matching checksums.");
+}
+async function rename(libraryDir, catalog, item, signal) {
+    const name = checked(await text({ message: `New display name for ${safeDisplay(item.name)}`, signal, validate: value => {
+            try {
+                assertNameAvailable(catalog, "item", value ?? "", item.id);
+                return undefined;
+            }
+            catch (error) {
+                return safeDisplay(error instanceof Error ? error.message : "Choose a unique non-empty name.");
+            }
+        } }), signal);
+    show(`${item.name} → ${name}\nSaved contents, file names, group references and destination remain unchanged.`, "Display name change");
+    if (await yes("Save display name only?", signal)) {
+        const after = structuredClone(catalog);
+        after.items.find(entry => entry.id === item.id).name = name.trim();
+        // Keep the UI's original object/revision; never reload and overwrite a newer name.
+        await saveNameChanges(libraryDir, catalog, after);
+        outro("Display name saved; contents and destination unchanged.");
+    }
+    else
+        outro("Display name was not changed.");
+}
+async function placement(libraryDir, catalog, item, signal) {
+    const kind = await choose("Destination kind", [
+        ...(item.destination.kind === "project" ? [{ value: "project", label: "Project-relative path" }] : []),
+        { value: "global-only", label: "Saved only (cannot later become project-applicable)" },
+    ], signal);
+    let destination = { kind: "global-only" };
+    if (kind === "project") {
+        const destinationPath = checked(await text({ message: "New project-relative destination (separate from display name)", signal, validate: value => value?.trim() ? undefined : "Enter a project-relative path." }), signal);
+        destination = { kind: "project", path: destinationPath };
+    }
+    show(`${item.destination.kind === "project" ? item.destination.path : "saved only"} → ${destination.kind === "project" ? destination.path : "saved only"}\nDisplay name and saved contents remain unchanged.`, "Destination change");
+    if (await yes("Save destination only?", signal)) {
+        item.destination = destination;
+        // saveCatalog verifies this original loadCatalog object's revision under its commit lock.
+        await saveCatalog(libraryDir, catalog);
+        outro("Destination saved; display name and contents unchanged.");
+    }
+    else
+        outro("Destination was not changed.");
+}
+async function refresh(libraryDir, catalog, item, roots, signal) {
+    show("sourceRoot was not stored in the saved catalog. No HOME or parent tree will be searched implicitly. Select only a same-kind source; a skill uses a directory tree, other kinds use one regular file. Private/auth/.env*/cache/history paths remain excluded.", "Refresh source boundary");
+    let requested = item.sourcePath;
+    let exists;
+    try {
+        await lstat(requested);
+        exists = true;
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        exists = false;
+    }
+    let source;
+    if (exists && (item.source.startsWith("package:") || requested.split(path.sep).some(part => part.toLowerCase() === "node_modules"))) {
+        const route = await choose("Registered package source", [{ value: "discover", label: "Rediscover declared origin in explicitly permitted locations" }, { value: "manual", label: "Choose a different non-excluded source path" }], signal);
+        if (route === "discover") {
+            const scopes = await choose("Select origin search scope", [{ value: "project", label: `Current project: ${roots.projectDir}` }, { value: "home", label: `HOME and Pi agent directory: ${roots.homeDir} · ${roots.agentDir}` }, { value: "both", label: "HOME, Pi agent directory and current project" }], signal);
+            const home = scopes !== "project", project = scopes !== "home";
+            const options = { ...roots, scopes: { home, project } };
+            if (home) {
+                options.homeDir = await resolveRefreshPath(roots.homeDir);
+                options.agentDir = await resolveRefreshPath(roots.agentDir);
+            }
+            if (project)
+                options.projectDir = await resolveRefreshPath(roots.projectDir);
+            show(`Original path: ${requested}\nHOME: ${home ? roots.homeDir : "not selected"}\nPhysical HOME: ${home ? options.homeDir : "not selected"}\nPi agent: ${home ? roots.agentDir : "not selected"}\nPhysical Pi agent: ${home ? options.agentDir : "not selected"}\nProject: ${project ? roots.projectDir : "not selected"}\nPhysical project: ${project ? options.projectDir : "not selected"}\nDiscovery uses existing declarations, exclusions and package checks; no arbitrary node_modules exception is granted.`, "Explicit origin discovery");
+            if (!await yes("Authorize origin discovery only in these selected locations?", signal)) {
+                outro("Origin discovery not authorized; nothing was saved.");
+                return;
+            }
+            source = await discoverRefreshOrigin(item, options);
+            if (!source)
+                show("Declared origin is no longer available in the approved locations. Choose another non-excluded source explicitly, or cancel; the saved copy remains available.", "Origin unavailable");
+        }
+        exists = Boolean(source);
+    }
+    if (!exists) {
+        show("The original source is unavailable or was not selected. The old saved copy can still be viewed. Choose a new source path explicitly, or Esc / Ctrl-C to cancel.", "Source selection");
+        requested = checked(await text({ message: "New source path (absolute; same resource kind)", signal, validate: value => value && path.isAbsolute(value) ? undefined : "Enter an absolute source path." }), signal);
+        const scope = await choose("Source scope (metadata only; does not authorize wider searches)", [{ value: "project", label: "Project" }, { value: "user", label: "User" }, { value: "shared", label: "Shared" }, { value: "package", label: "Package (no private path exception)" }], signal);
+        const physical = await resolveRefreshPath(requested);
+        source = { id: item.id, kind: item.kind, name: item.name, source: "explicit-refresh-path", scope, sourcePath: physical, sourceRoot: path.dirname(physical), destination: { ...item.destination } };
+    }
+    if (!source) {
+        const physical = await resolveRefreshPath(requested);
+        source = { id: item.id, kind: item.kind, name: item.name, source: item.source, scope: item.scope, sourcePath: physical, sourceRoot: path.dirname(physical), destination: { ...item.destination } };
+    }
+    show(`Requested path: ${requested}\nPhysical source: ${source.sourcePath}\nValidation boundary: ${source.sourceRoot}\nRead only: ${item.kind === "skill" ? "selected directory tree" : "selected regular file"}\nKind: ${source.kind}; source: ${source.source}; scope: ${source.scope}\nNo parent-tree search. Existing exclusions and symlink checks apply.`, "Source read permission");
+    if (!await yes("Authorize reading only this selected source file or directory tree now?", signal)) {
+        outro("Source reading not authorized; nothing was saved.");
+        return;
+    }
+    if (signal.aborted)
+        throw new Cancelled();
+    const prepared = await prepareRefresh(libraryDir, item.id, source), review = readRefresh(prepared);
+    if (JSON.stringify(review.originalCatalog) !== JSON.stringify(catalog))
+        throw new Error("Saved metadata, memberships or copy state changed since selection; reload and review again.");
+    const original = review.originalCatalog.items.find(entry => entry.id === item.id);
+    show(`${original.name} · ${hint(review.originalCatalog, original, review.originalCatalog.items.indexOf(original))}\nSource: ${original.sourcePath} → ${review.item.sourcePath}\nSource metadata: ${original.source} / ${original.scope} → ${review.item.source} / ${review.item.scope}\nID, display name, all memberships, savedAt and destination are retained.`, "Prepared refresh identity and source");
+    process.stdout.write(`\n${safeDisplay(`Full masked refresh diff: ${review.item.name}`)}\n`);
+    for (const diff of review.diffs)
+        process.stdout.write(`${safeDisplay(diff.path)}\n${safeDisplay(diff.summary)}\n${safeDisplay(diff.diff)}\n`);
+    show(review.warnings.map(w => `${w.path ? `${w.path}: ` : ""}${w.message}`).join("\n"), "Fixed source inspection warnings · masking can hide byte changes");
+    if (review.excludedPaths.length)
+        show(review.excludedPaths.join("\n"), "Fixed source excluded paths");
+    show("All copi-only edits will be lost when this source snapshot replaces the saved copy, including added/removed bundle files and mode changes shown above. Original files will not be changed or written back. There is no history, restore or automatic merge.", "Replacement warning");
+    if (!await yes("Approve this refresh diff and source metadata? All masked hunks and byte/mode summaries are shown above.", signal)) {
+        outro("Refresh diff not approved; nothing was saved.");
+        return;
+    }
+    const approvedSensitivePaths = [];
+    for (const file of review.sensitivePaths) {
+        if (!await yes(`Save suspected sensitive file ${file} from ${review.item.name}? This individual approval covers only the fixed prepared source bytes. Detection is heuristic; raw source is not displayed.`, signal)) {
+            outro("Sensitive source bytes not approved; nothing was saved.");
+            return;
+        }
+        approvedSensitivePaths.push(file);
+    }
+    if (!await yes("Replace saved copy with this approved source snapshot? Copi edits will be lost; originals stay unchanged; no history, restore or automatic merge.", signal)) {
+        outro("Refresh cancelled; nothing was saved.");
+        return;
+    }
+    if (signal.aborted)
+        throw new Cancelled();
+    await commitRefresh(prepared, { reviewId: prepared.reviewId, confirmed: true, approvedSensitivePaths });
+    outro("Refreshed saved copy committed with matching checksums; originals unchanged.");
+}
+async function resource(libraryDir, catalog, conflict, roots, signal) {
+    const id = await choose("Select saved resource", catalog.items.map((item, index) => ({ value: item.id, label: `[${item.kind}] ${item.name}`, hint: hint(catalog, item, index) })), signal);
+    if (catalog.version === 1) {
+        const item = catalog.items.find(item => item.id === id);
+        if (!item)
+            throw new Error("Selected resource is unavailable; reload the library.");
+        const action = await choose("Resource action", [{ value: "view", label: "View saved file (masked)" }, { value: "back", label: "Back" }], signal);
+        if (action === "view")
+            await view(libraryDir, item, signal);
+        return;
+    }
+    const item = catalog.items.find(item => item.id === id);
+    if (!item)
+        throw new Error("Selected resource is unavailable; reload the library.");
+    const action = await choose("Resource action", [
+        { value: "view", label: "View saved file (masked)" },
+        ...(!conflict ? [
+            { value: "edit", label: "Edit saved text" }, { value: "rename", label: "Rename display name" }, { value: "placement", label: "Change destination" },
+            { value: "refresh", label: "Refresh from source (replace saved copy)" },
+        ] : []), { value: "back", label: "Back" },
+    ], signal);
+    if (action === "view") {
+        await view(libraryDir, item, signal);
+        return;
+    }
+    if (action === "back")
+        return;
+    const current = await loadCatalog(libraryDir);
+    assertModernCatalog(current);
+    assertNoNameConflicts(current);
+    if (action === "edit")
+        await edit(libraryDir, item, signal);
+    else if (action === "rename")
+        await rename(libraryDir, catalog, item, signal);
+    else if (action === "refresh")
+        await refresh(libraryDir, catalog, item, roots, signal);
+    else
+        await placement(libraryDir, catalog, item, signal);
+}
+export async function runManage(libraryDir, roots) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        throw new Error("manage requires an interactive stdin/stdout TTY; no library was created or searched.");
+    await withWizardLifecycle(async (signal) => {
+        intro("copi manage · names, not IDs · Esc / Ctrl-C cancels");
+        try {
+            while (!signal.aborted) {
+                const catalog = await loadCatalog(libraryDir);
+                const modern = catalog.version === 2;
+                const conflict = findNameConflicts(catalog).length > 0;
+                if (conflict)
+                    show(modern ? "Duplicate names: only listing, masked viewing, and explicit name conflict resolution are allowed." : "Legacy catalog v1 is read-only; duplicate names are not changed here. Only listing and masked viewing are available.", "Duplicate names");
+                else if (!modern)
+                    show("Legacy catalog v1 is read-only until explicit migration.", "Read-only library");
+                else if (catalog.items.length === 0)
+                    show("No saved resources. Setup searches only explicitly selected and approved locations.", "Private library");
+                const action = await choose("Manage saved resources", [
+                    ...(catalog.items.length ? [{ value: "resource", label: "Select resource by name" }] : []),
+                    ...(modern ? (conflict ? [{ value: "resolve", label: "Resolve name conflicts" }] : [
+                        { value: "groups", label: "Manage groups" }, { value: "apply", label: "Apply group" }, { value: "setup", label: "Setup copied resources" },
+                    ]) : []), { value: "done", label: "Finish" },
+                ], signal);
+                if (action === "done")
+                    break;
+                if (action === "resource")
+                    await resource(libraryDir, catalog, conflict, roots, signal);
+                else if (action === "resolve")
+                    await resolveNameConflicts(libraryDir);
+                else {
+                    assertModernCatalog(catalog);
+                    const current = await loadCatalog(libraryDir);
+                    assertModernCatalog(current);
+                    assertNoNameConflicts(current);
+                    if (action === "groups")
+                        await runGroupManager(libraryDir);
+                    else if (action === "setup")
+                        await runSetup(libraryDir, roots);
+                    else {
+                        if (catalog.groups.length === 0) {
+                            show("No groups to apply. Create a group and assign resources first.", "Apply group");
+                            continue;
+                        }
+                        const group = await choose("Select group to apply", catalog.groups.map(g => ({ value: g.id, label: g.name, hint: `${g.itemIds.length} resources` })), signal);
+                        const target = checked(await text({ message: "Apply target directory", initialValue: roots.projectDir, signal }), signal);
+                        await runApplyWizard(libraryDir, group, path.resolve(roots.projectDir, target));
+                    }
+                }
+            }
+            outro("Manage finished.");
+        }
+        catch (error) {
+            if (error instanceof Cancelled || signal.aborted) {
+                outro("Manage cancelled; unconfirmed changes were not saved.");
+                return;
+            }
+            throw new Error(safeDisplay(`${error instanceof Error ? error.message : "Management failed."}\nChanges stopped. Inspect the cause and reload before trying again; unknown locks and checksums are not automatically repaired.`), { cause: error });
+        }
+    });
+}

package/dist/src/migrate.d.ts

@@ -0,0 +1,25 @@
+import { commitMigration, prepareMigration, readMigration } from "./migration.ts";
+import type { MigrationResolutionView, MigrationResult, PreparedMigrationResolution } from "./migration.ts";
+import type { ChangeApproval } from "./resource-mutations.ts";
+export interface MigrationCommandApi {
+    prepareMigration: typeof prepareMigration;
+    readMigration: typeof readMigration;
+    commitMigration: typeof commitMigration;
+    prepareMigrationResolution(libraryDir: string): Promise<PreparedMigrationResolution>;
+    readMigrationResolution(plan: PreparedMigrationResolution): MigrationResolutionView;
+    commitMigrationResolution(plan: PreparedMigrationResolution, approval: ChangeApproval): Promise<MigrationResult>;
+}
+export interface MigrationCommandRuntime {
+    api?: MigrationCommandApi;
+    stdinIsTTY?: boolean;
+    stdoutIsTTY?: boolean;
+    confirm?: (message: string, initialValue: false, signal: AbortSignal) => Promise<unknown>;
+    withLifecycle?: (operation: (signal: AbortSignal) => Promise<number>) => Promise<number>;
+    write?: (text: string) => void;
+}
+export interface MigrationCommandFlags {
+    readonly resolve: boolean;
+    readonly dryRun: boolean;
+}
+export declare function parseMigrationArgs(args: readonly string[]): MigrationCommandFlags;
+export declare function runMigrateCommand(args: readonly string[], libraryDir: string, runtime?: MigrationCommandRuntime): Promise<number>;

package/dist/src/migrate.js

@@ -0,0 +1,171 @@
+import { confirm as clackConfirm } from "@clack/prompts";
+import { commitMigration, prepareMigration, readMigration, } from "./migration.js";
+import { safeDisplay, withWizardLifecycle } from "./wizard.js";
+const usageError = () => new Error("Usage: copi migrate [--dry-run] | copi migrate --resolve [--dry-run].");
+async function runWithWizardLifecycle(operation) {
+    let result = 1;
+    await withWizardLifecycle(async (signal) => { result = await operation(signal); });
+    return result;
+}
+export function parseMigrationArgs(args) {
+    let resolve = false;
+    let dryRun = false;
+    for (const argument of args) {
+        if (argument === "--resolve" && !resolve)
+            resolve = true;
+        else if (argument === "--dry-run" && !dryRun)
+            dryRun = true;
+        else
+            throw usageError();
+    }
+    return { resolve, dryRun };
+}
+function writeSafe(write, text) {
+    write(safeDisplay(text));
+}
+function displayReview(write, title, view) {
+    writeSafe(write, `${title}: ${view.status}\n`);
+    if ("backupDir" in view && view.backupDir)
+        writeSafe(write, `Verified backup: ${view.backupDir}\n`);
+    for (const item of view.items) {
+        writeSafe(write, `Resource: ${item.name} → ${item.target} (${item.selection})\n`);
+    }
+    for (const diff of view.maskedDiffs) {
+        writeSafe(write, `\n${diff.path}\n${diff.summary}\n`);
+    }
+    for (const warning of view.warnings) {
+        writeSafe(write, `Warning${warning.path ? ` (${warning.path})` : ""}: ${warning.message}\n`);
+    }
+    if (view.conflicts.length > 0)
+        writeSafe(write, `Conflicts:\n${view.conflicts.map((entry) => `- ${entry}`).join("\n")}\n`);
+    if (view.preservedPaths.length > 0)
+        writeSafe(write, `Preserved paths:\n${view.preservedPaths.map((entry) => `- ${entry}`).join("\n")}\n`);
+}
+function isMigrationLockConflict(view) {
+    return view.conflicts.some((conflict) => conflict.includes(".copi-transaction") || conflict.includes(".copi-migration-resolution.json") ||
+        conflict.includes(".copi-transaction-recovery"));
+}
+async function defaultApi() {
+    const module = await import("./migration.js");
+    return module;
+}
+function requireResolutionApi(api) {
+    if (typeof api.prepareMigrationResolution !== "function" ||
+        typeof api.readMigrationResolution !== "function" ||
+        typeof api.commitMigrationResolution !== "function") {
+        throw new Error("This build does not include the approved migration-resolution API.");
+    }
+}
+async function promptForApproval(view, resolve, confirm, signal) {
+    const approvedSensitivePaths = [];
+    const reviewQuestion = resolve
+        ? "この masked diff をすべて確認し、解消手順の対象としてよいですか。"
+        : "この masked diff をすべて確認し、移行内容の対象としてよいですか。";
+    if (await confirm(reviewQuestion, false, signal) !== true || signal.aborted)
+        return undefined;
+    for (const sensitivePath of view.sensitivePaths) {
+        const question = `秘密情報候補 ${sensitivePath} を個別に確認しましたか。内容は表示されません。`;
+        if (await confirm(question, false, signal) !== true || signal.aborted)
+            return undefined;
+        approvedSensitivePaths.push(sensitivePath);
+    }
+    const finalQuestion = resolve
+        ? "確認した sources の編集をそのまま保持し、移行終了を確定しますか。catalog・sources・items は書き換えません。検証済みバックアップを残し、所有を確認できる内部残物だけを片付けます。配布と items の削除は行いません。"
+        : "移行を実行しますか。catalog を v2 に切り替え、検証済みバックアップを保持します。";
+    if (await confirm(finalQuestion, false, signal) !== true || signal.aborted)
+        return undefined;
+    return { reviewId: view.reviewId, confirmed: true, approvedSensitivePaths };
+}
+function emitBlockedResolution(write, view) {
+    const baselineInsufficient = view.conflicts.some((conflict) => /v4|baseline-insufficient/i.test(conflict));
+    if (baselineInsufficient) {
+        writeSafe(write, "開始時 inventory が無いためこの解消手順では扱えません。従来の復旧／保持停止を維持します。\n");
+    }
+    else {
+        writeSafe(write, "安全に解消できないため停止しました。編集と残物は保持しています。\n");
+    }
+    for (const conflict of view.conflicts)
+        writeSafe(write, `- ${conflict}\n`);
+    if (view.preservedPaths.length > 0) {
+        writeSafe(write, `残している path:\n${view.preservedPaths.map((entry) => `- ${entry}`).join("\n")}\n`);
+    }
+    writeSafe(write, "原因を確認し、新しい検証buildやfresh reviewが必要な場合はその結果を確認してから再実行してください。\n");
+}
+async function runResolution(api, libraryDir, flags, runtime) {
+    requireResolutionApi(api);
+    const plan = await api.prepareMigrationResolution(libraryDir);
+    const view = api.readMigrationResolution(plan);
+    displayReview(runtime.write, "Migration resolution", view);
+    if (view.status === "blocked") {
+        emitBlockedResolution(runtime.write, view);
+        return 1;
+    }
+    if (view.status === "not-needed") {
+        writeSafe(runtime.write, "解消が必要な移行残物はありません。\n");
+        return 0;
+    }
+    if (flags.dryRun)
+        return 0;
+    return runtime.withLifecycle(async (signal) => {
+        const approval = await promptForApproval(view, true, runtime.confirm, signal);
+        if (!approval || signal.aborted) {
+            writeSafe(runtime.write, "解消は確定されませんでした。編集と残物は保持しています。\n");
+            return 1;
+        }
+        const result = await api.commitMigrationResolution(plan, approval);
+        writeSafe(runtime.write, "確認付き解消が完了しました。catalog・sources・items は書き換えていません。\n");
+        if (result.backupDir)
+            writeSafe(runtime.write, `検証済みバックアップ: ${result.backupDir}\n`);
+        for (const preserved of result.preservedPaths)
+            writeSafe(runtime.write, `保持: ${preserved}\n`);
+        return 0;
+    });
+}
+async function runOrdinaryMigration(api, libraryDir, flags, runtime) {
+    const plan = await api.prepareMigration(libraryDir);
+    const view = api.readMigration(plan);
+    displayReview(runtime.write, "Legacy migration", view);
+    if (view.status === "blocked") {
+        if (isMigrationLockConflict(view)) {
+            writeSafe(runtime.write, "移行終了確認が未完了です。編集とバックアップを保持しています。`copi migrate --resolve --dry-run` で確認してください。内部 lock を手で削除しないでください。\n");
+        }
+        return 1;
+    }
+    if (view.status === "already-v2") {
+        writeSafe(runtime.write, "catalog はすでに v2 です。移行は必要ありません。\n");
+        return 0;
+    }
+    if (flags.dryRun)
+        return 0;
+    return runtime.withLifecycle(async (signal) => {
+        const approval = await promptForApproval(view, false, runtime.confirm, signal);
+        if (!approval || signal.aborted) {
+            writeSafe(runtime.write, "移行は確定されませんでした。library は変更していません。\n");
+            return 1;
+        }
+        const result = await api.commitMigration(plan, approval);
+        writeSafe(runtime.write, "移行が完了しました。\n");
+        if (result.backupDir)
+            writeSafe(runtime.write, `検証済みバックアップ: ${result.backupDir}\n`);
+        for (const preserved of result.preservedPaths)
+            writeSafe(runtime.write, `保持: ${preserved}\n`);
+        return 0;
+    });
+}
+export async function runMigrateCommand(args, libraryDir, runtime = {}) {
+    const flags = parseMigrationArgs(args);
+    const stdinIsTTY = runtime.stdinIsTTY ?? Boolean(process.stdin.isTTY);
+    const stdoutIsTTY = runtime.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
+    const write = runtime.write ?? ((text) => process.stdout.write(text));
+    if (!flags.dryRun && (!stdinIsTTY || !stdoutIsTTY)) {
+        writeSafe(write, "migrate の変更には stdin/stdout の interactive TTY が必要です。--dry-run は read-only です。\n");
+        return 1;
+    }
+    const api = runtime.api ?? await defaultApi();
+    const confirm = runtime.confirm ?? (async (message, initialValue, signal) => clackConfirm({ message: safeDisplay(message), initialValue, signal }));
+    const withLifecycle = runtime.withLifecycle ?? runWithWizardLifecycle;
+    const dependencies = { confirm, withLifecycle, write };
+    return flags.resolve
+        ? runResolution(api, libraryDir, flags, dependencies)
+        : runOrdinaryMigration(api, libraryDir, flags, dependencies);
+}