@papillon6814/copi 0.2.0 → 0.3.0

package/README.md

@@ -26,7 +26,11 @@ copi migrate --resolve [--dry-run]
 copi help
 ```
 
-`setup` requires an interactive terminal. It asks which locations may be searched and asks for explicit authorization before searching. Selecting the entire `HOME` is broad: it can inspect supported resources throughout that directory, including Pi profiles and the configured Pi agent directory. Selecting the current project scopes discovery to that project. The wizard then lets you choose individual resources, review masked previews, assign each saved resource to one or more groups, and confirm before anything is copied into the library. Declining authorization performs no search.
+`setup` requires an interactive terminal. It first asks where copi may look: your whole `HOME` (the default; this can take a minute or more), this project only, or both. Selecting the entire `HOME` is broad: it can inspect supported resources throughout that directory, including Pi profiles and the configured Pi agent directory. Selecting the current project scopes discovery to that project. Copi then asks for explicit authorization before searching; declining performs no search. Search warnings are summarized (for example, resources found outside the selected roots are counted rather than listed one by one), and missing files are skipped silently.
+
+Candidates are listed with a source label, size and modification date, and entries whose name matches an already saved resource are marked `already saved`. After you select resources, name conflicts are resolved right away, before any preview: keep one of the same-named selections, rename the display name only (the files, body and destination are not changed), skip the resource (keeping the saved copy), or go back to the list.
+
+A group is a named set of saved resources that you later apply together with `copi apply <group> <project>`. If no group exists yet, setup asks you to create the first one. With several resources, setup asks once how to group them: by default all of them go into the same group(s); you can instead choose groups for each resource. Each resource is then reviewed in turn with a masked preview titled with its progress (for example `1/3`) and its source directory. A suspected sensitive file needs its own approval; answering No means that resource is not saved at all. Finally, one confirmation lists everything that will be copied into the library; the original files are never changed. When it is done, setup prints the next step, for example `copi apply <group> <project> --dry-run`.
 
 `manage` requires both stdin and stdout to be an interactive TTY. Choose saved resources and groups by name; UUID input is not required and normal screens identify resources by display name, kind, groups and destination. It provides masked viewing, terminal text editing, display-name changes, separate destination changes, source refresh, group management and apply. Running without arguments, or with `help`, `--help` or `-h`, still shows help.
 

package/dist/src/discovery.js

@@ -117,6 +117,10 @@ async function canonicalDirectory(directory) {
         return undefined;
     }
 }
+/** False only when the entry itself does not exist (lstat ENOENT); dangling symlinks count as existing. */
+async function exists(target) {
+    return lstat(target).then(() => true, (error) => error.code !== "ENOENT");
+}
 export async function discoverResources(options) {
     const scopes = options.scopes ?? inferSearchScopes(options);
     if (!scopes.home && !scopes.project)
@@ -143,6 +147,8 @@ export async function discoverResources(options) {
     if (project)
         roots.push({ path: project, scope: "project", source: "project", destinationRoot: ".pi/skills", destinationKind: "project" });
     const addCandidate = async (kind, root, sourcePath, name, scope, source, destination) => {
+        if (!(await exists(sourcePath)))
+            return;
         const canonicalSource = await realpath(sourcePath).catch(() => undefined);
         const canonicalRoot = await realpath(root).catch(() => undefined);
         if (!canonicalSource || !canonicalRoot || !isWithin(canonicalRoot, canonicalSource)) {
@@ -209,6 +215,8 @@ export async function discoverResources(options) {
         };
         const canonicalStart = await realpath(startPath).catch(() => undefined);
         if (!canonicalStart || !isWithin(canonicalRoot, canonicalStart)) {
+            if (!(await exists(startPath)))
+                return;
             addWarning(warnings, "resource-outside-root", startPath, "A configured resource root resolves outside its allowed search root.");
             return;
         }

package/dist/src/setup-display.d.ts

@@ -0,0 +1,43 @@
+import type { ResourceCandidate } from "./types.ts";
+/** Replace a leading home directory with `~` (only on a path-segment boundary). */
+export declare function displayPath(p: string, home: string): string;
+/** Keep head and tail joined by `…`; return `s` unchanged when `max` is missing, tiny, or not smaller than the length. */
+export declare function truncateMiddle(s: string, max: number | undefined): string;
+export declare function formatBytes(n: number): string;
+/** Summarize skipped out-of-root resources into one note (undefined when none). */
+export declare function formatOutsideRootSummary(paths: readonly string[], home: string): {
+    title: string;
+    body: string;
+} | undefined;
+export interface CandidateStats {
+    size?: string;
+    mtime?: Date;
+}
+/**
+ * `[kind] name — ~/source/dir`, plus `(already saved)`. Shared with conflict-resolution options.
+ * When `columns` is given the source directory is middle-truncated (tail kept) so the row does not wrap.
+ */
+export declare function candidateLabel(c: ResourceCandidate, home: string, alreadySaved: boolean, columns?: number): string;
+/**
+ * Labels for a whole list. Rows sharing kind + nameKey must stay distinguishable: when truncation makes their
+ * source labels collide, that group falls back to whole trailing segments (`…/a/b`), widened until they differ.
+ */
+export declare function candidateLabels(list: readonly ResourceCandidate[], home: string, isSaved: (c: ResourceCandidate) => boolean, columns?: number): Map<string, string>;
+/** Sort by kind, then nameKey, then source path (new array). */
+export declare function sortCandidates(list: readonly ResourceCandidate[]): ResourceCandidate[];
+export declare function formatLocalDate(d: Date): string;
+/** `<size> · modified <date> · <destination>`; missing parts are omitted. Truncated to the terminal width minus label and prompt chrome. */
+export declare function candidateHint(c: ResourceCandidate, stats: CandidateStats, home: string, columns: number | undefined, labelLength: number): string;
+/** Cheap, never-throwing stats for the shown candidates, gathered in parallel. */
+export declare function gatherCandidateStats(list: readonly ResourceCandidate[]): Promise<Map<string, CandidateStats>>;
+/** Groups of 2+ selected candidates sharing a `nameKey` (any kind), each in input order; groups ordered by first member. */
+export declare function findSelectionConflicts(list: readonly ResourceCandidate[]): ResourceCandidate[][];
+/**
+ * Suggested rename `<name> (<segment>)`. Within a conflict group the segment is the nearest ancestor directory
+ * (walking up from the source's parent) whose name tells this member apart from the others — unique if possible,
+ * otherwise the first level where the members differ at all. Without such a level (or alone), the segment is the
+ * grandparent of the source, falling back to its parent, e.g. `jandel.md (agent-rbx)`.
+ */
+export declare function defaultRenameName(c: ResourceCandidate, group?: readonly ResourceCandidate[]): string;
+/** Validation message for a new display name, or undefined when it is non-empty and its `nameKey` is not taken. */
+export declare function pendingNameError(name: string | undefined, taken: ReadonlySet<string>): string | undefined;

package/dist/src/setup-display.js

@@ -0,0 +1,195 @@
+import { lstat, readdir } from "node:fs/promises";
+import path from "node:path";
+import { nameKey } from "./names.js";
+/** Replace a leading home directory with `~` (only on a path-segment boundary). */
+export function displayPath(p, home) {
+    if (!home)
+        return p;
+    const base = home.length > 1 && home.endsWith(path.sep) ? home.slice(0, -1) : home;
+    if (p === base)
+        return "~";
+    if (p.startsWith(base + path.sep))
+        return `~${p.slice(base.length)}`;
+    return p;
+}
+/** Keep head and tail joined by `…`; return `s` unchanged when `max` is missing, tiny, or not smaller than the length. */
+export function truncateMiddle(s, max) {
+    if (max === undefined || !Number.isFinite(max) || max < 4 || s.length <= max)
+        return s;
+    const keep = max - 1;
+    const head = Math.ceil(keep / 2);
+    const tail = keep - head;
+    return `${s.slice(0, head)}…${tail > 0 ? s.slice(s.length - tail) : ""}`;
+}
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(1)} MB`;
+}
+const outsideRootPreview = 5;
+/** Summarize skipped out-of-root resources into one note (undefined when none). */
+export function formatOutsideRootSummary(paths, home) {
+    if (paths.length === 0)
+        return undefined;
+    const lines = paths.slice(0, outsideRootPreview).map((p) => displayPath(p, home));
+    if (paths.length > outsideRootPreview)
+        lines.push(`+${paths.length - outsideRootPreview} more`);
+    return { title: `Skipped ${paths.length} resource(s) outside the selected locations`, body: lines.join("\n") };
+}
+/**
+ * `[kind] name — ~/source/dir`, plus `(already saved)`. Shared with conflict-resolution options.
+ * When `columns` is given the source directory is middle-truncated (tail kept) so the row does not wrap.
+ */
+export function candidateLabel(c, home, alreadySaved, columns) {
+    const head = `[${c.kind}] ${c.name} \u2014 `;
+    const tail = alreadySaved ? " (already saved)" : "";
+    let dir = displayPath(path.dirname(c.sourcePath), home);
+    if (columns !== undefined && Number.isFinite(columns))
+        dir = truncateMiddle(dir, Math.max(columns - head.length - tail.length - 6, 8));
+    return `${head}${dir}${tail}`;
+}
+/**
+ * Labels for a whole list. Rows sharing kind + nameKey must stay distinguishable: when truncation makes their
+ * source labels collide, that group falls back to whole trailing segments (`…/a/b`), widened until they differ.
+ */
+export function candidateLabels(list, home, isSaved, columns) {
+    const out = new Map();
+    const groups = new Map();
+    for (const c of list) {
+        out.set(c.id, candidateLabel(c, home, isSaved(c), columns));
+        const key = `${c.kind}\0${nameKey(c.name)}`;
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    for (const group of groups.values()) {
+        if (group.length < 2)
+            continue;
+        const labels = group.map((c) => out.get(c.id));
+        if (new Set(labels).size === labels.length)
+            continue;
+        const dirs = group.map((c) => displayPath(path.dirname(c.sourcePath), home));
+        const segs = dirs.map((d) => d.split(path.sep));
+        const max = Math.max(...segs.map((x) => x.length));
+        for (let k = 1; k <= max; k += 1) {
+            const cut = segs.map((x, i) => (x.length <= k ? dirs[i] : `\u2026${path.sep}${x.slice(-k).join(path.sep)}`));
+            const rendered = group.map((c, i) => `[${c.kind}] ${c.name} \u2014 ${cut[i]}${isSaved(c) ? " (already saved)" : ""}`);
+            if (new Set(rendered).size === rendered.length || k === max) {
+                group.forEach((c, i) => out.set(c.id, rendered[i]));
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** Sort by kind, then nameKey, then source path (new array). */
+export function sortCandidates(list) {
+    const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+    return [...list].sort((a, b) => cmp(a.kind, b.kind) || cmp(nameKey(a.name), nameKey(b.name)) || cmp(a.sourcePath, b.sourcePath));
+}
+export function formatLocalDate(d) {
+    const p = (n) => String(n).padStart(2, "0");
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())}`;
+}
+/** `<size> · modified <date> · <destination>`; missing parts are omitted. Truncated to the terminal width minus label and prompt chrome. */
+export function candidateHint(c, stats, home, columns, labelLength) {
+    const parts = [];
+    if (stats.size !== undefined)
+        parts.push(stats.size);
+    if (stats.mtime !== undefined)
+        parts.push(`modified ${formatLocalDate(stats.mtime)}`);
+    parts.push(c.destination.kind === "global-only" ? "save only" : displayPath(c.destination.path, home));
+    const hint = parts.join(" · ");
+    if (columns === undefined || !Number.isFinite(columns))
+        return hint;
+    return truncateMiddle(hint, Math.max(columns - labelLength - 10, 12));
+}
+const countCap = 1000;
+async function countFiles(dir, budget) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (budget.left <= 0)
+            return;
+        if (entry.isDirectory())
+            await countFiles(path.join(dir, entry.name), budget);
+        else if (entry.isFile())
+            budget.left -= 1;
+    }
+}
+async function hasMoreFiles(dir, cap) {
+    const budget = { left: cap + 1 };
+    await countFiles(dir, budget);
+    return budget.left <= 0;
+}
+async function statOne(c) {
+    try {
+        const st = await lstat(c.sourcePath);
+        if (st.isDirectory()) {
+            const budget = { left: countCap };
+            await countFiles(c.sourcePath, budget);
+            const n = countCap - budget.left;
+            return { size: budget.left <= 0 && (await hasMoreFiles(c.sourcePath, countCap)) ? `${countCap}+ files` : `${n} file${n === 1 ? "" : "s"}`, mtime: st.mtime };
+        }
+        return { size: formatBytes(st.size), mtime: st.mtime };
+    }
+    catch {
+        return {};
+    }
+}
+/** Cheap, never-throwing stats for the shown candidates, gathered in parallel. */
+export async function gatherCandidateStats(list) {
+    const entries = await Promise.all(list.map(async (c) => [c.id, await statOne(c)]));
+    return new Map(entries);
+}
+/** Groups of 2+ selected candidates sharing a `nameKey` (any kind), each in input order; groups ordered by first member. */
+export function findSelectionConflicts(list) {
+    const groups = new Map();
+    for (const c of list) {
+        const key = nameKey(c.name);
+        groups.set(key, [...(groups.get(key) ?? []), c]);
+    }
+    return [...groups.values()].filter((group) => group.length > 1);
+}
+/**
+ * Suggested rename `<name> (<segment>)`. Within a conflict group the segment is the nearest ancestor directory
+ * (walking up from the source's parent) whose name tells this member apart from the others — unique if possible,
+ * otherwise the first level where the members differ at all. Without such a level (or alone), the segment is the
+ * grandparent of the source, falling back to its parent, e.g. `jandel.md (agent-rbx)`.
+ */
+export function defaultRenameName(c, group = [c]) {
+    const ancestors = (x) => {
+        const out = [];
+        for (let dir = path.dirname(x.sourcePath); path.basename(dir); dir = path.dirname(dir))
+            out.push(path.basename(dir));
+        return out;
+    };
+    const mine = ancestors(c);
+    const others = group.filter((x) => x.id !== c.id).map(ancestors);
+    let segment;
+    if (others.length > 0) {
+        const unique = mine.findIndex((name, level) => others.every((other) => other[level] !== name));
+        const differing = mine.findIndex((name, level) => others.some((other) => other[level] !== name));
+        const level = unique !== -1 ? unique : differing;
+        if (level !== -1)
+            segment = mine[level];
+    }
+    segment ??= mine[1] ?? mine[0];
+    return segment ? `${c.name} (${segment})` : c.name;
+}
+/** Validation message for a new display name, or undefined when it is non-empty and its `nameKey` is not taken. */
+export function pendingNameError(name, taken) {
+    let key;
+    try {
+        key = nameKey(name ?? "");
+    }
+    catch {
+        return "Enter a non-empty display name.";
+    }
+    return taken.has(key) ? "That name is already used by a saved or selected resource; choose another." : undefined;
+}

package/dist/src/wizard.d.ts

@@ -6,6 +6,7 @@ import type { LegacySavedItem, ResourceCandidate, SavedItem, StoredCatalog } fro
 export declare function safeDisplay(value: string): string;
 /** The editor parses literal paste versus cancel keys; stream EOF/errors/signals stay global. */
 export declare function withEditorInput<T>(operation: () => Promise<T>): Promise<T>;
+export declare const multiselectKeyHint = "(Tab: select, Enter: confirm)";
 /** One process-wide interactive lifecycle shared by manage and its existing wizard routes. */
 export declare function withWizardLifecycle(operation: (signal: AbortSignal) => Promise<void>): Promise<void>;
 export interface SearchRoots {
@@ -29,6 +30,14 @@ export declare function prepareCandidateForReview(candidate: ResourceCandidate):
 export declare function saveReviewedCandidate(libraryDir: string, review: CandidateReview, groupIds: string[], approvedSensitivePaths: string[], confirmed: boolean): Promise<SavedItem | null>;
 /** Resolve all staged conflicts in one name-only catalog save; cancellation writes nothing. */
 export declare function resolveNameConflicts(libraryDir: string): Promise<void>;
+/**
+ * Rename prompt text. The suggestion is prefilled only when it renders unchanged through `safeDisplay`
+ * (`initialValue` is echoed raw); otherwise the field stays empty and the masked suggestion is shown in the message.
+ */
+export declare function renamePrompt(name: string, sourceDir: string, suggestion: string): {
+    message: string;
+    initialValue?: string;
+};
 export declare function runSetup(libraryDir: string, roots: SearchRoots): Promise<void>;
 export declare function runGroupManager(libraryDir: string): Promise<void>;
 export declare function printGroups(catalog: StoredCatalog): void;

package/dist/src/wizard.js

@@ -1,9 +1,10 @@
-import { autocompleteMultiselect as clackMultiselect, cancel as clackCancel, confirm as clackConfirm, intro as clackIntro, isCancel, log, note as clackNote, outro as clackOutro, select as clackSelect, text as clackText } from "@clack/prompts";
+import { autocompleteMultiselect as clackMultiselect, cancel as clackCancel, confirm as clackConfirm, intro as clackIntro, isCancel, log, note as clackNote, outro as clackOutro, select as clackSelect, spinner as clackSpinner, text as clackText } from "@clack/prompts";
 import { lstat } from "node:fs/promises";
 import path from "node:path";
 import { assertModernCatalog, importPreparedResource, loadCatalog, prepareResource, readPreparedResource, readSnapshotFiles, saveCatalog, saveNameChanges } from "./catalog.js";
 import { discoverResources } from "./discovery.js";
 import { createGroup, renameGroup, setGroupItems } from "./groups.js";
+import { candidateHint, candidateLabels, defaultRenameName, displayPath, findSelectionConflicts, formatOutsideRootSummary, gatherCandidateStats, pendingNameError, sortCandidates } from "./setup-display.js";
 import { inspectPreparedResource, maskSensitiveText } from "./inspect.js";
 import { assertNameAvailable, assertNoNameConflicts, findNameConflicts, nameKey } from "./names.js";
 import { executeApply, planApply } from "./apply.js";
@@ -34,8 +35,10 @@ const select = (options) => clackSelect({
     ...options, ...inheritedSignal(options.signal), message: safeDisplay(options.message),
     options: options.options.map((option) => ({ ...option, label: safeDisplay(option.label ?? "Unavailable entry"), ...(option.hint === undefined ? {} : { hint: safeDisplay(option.hint) }) })),
 });
+// Clack's own key legend is dim and below the list; repeat it in the question so Tab-to-select is not missed.
+export const multiselectKeyHint = "(Tab: select, Enter: confirm)";
 const autocompleteMultiselect = (options) => clackMultiselect({
-    ...options, ...inheritedSignal(options.signal), message: safeDisplay(options.message),
+    ...options, ...inheritedSignal(options.signal), message: `${safeDisplay(options.message)} ${multiselectKeyHint}`,
     options: typeof options.options === "function" ? options.options : options.options.map((option) => ({ ...option, label: safeDisplay(option.label ?? "Unavailable entry"), ...(option.hint === undefined ? {} : { hint: safeDisplay(option.hint) }) })),
 });
 const text = (options) => clackText({ ...options, ...inheritedSignal(options.signal), message: safeDisplay(options.message) });
@@ -131,6 +134,12 @@ export async function saveReviewedCandidate(libraryDir, review, groupIds, approv
         approvedSensitivePaths,
     });
 }
+function showSearchWarnings(warnings, home) {
+    const summary = formatOutsideRootSummary(warnings.filter((warning) => warning.code === "resource-outside-root" && warning.path !== undefined).map((warning) => warning.path), home);
+    if (summary)
+        note(summary.body, summary.title);
+    showWarnings(warnings.filter((warning) => warning.code !== "resource-outside-root" || warning.path === undefined), "Search warnings");
+}
 function showWarnings(warnings, title) {
     if (warnings.length === 0)
         return;
@@ -265,12 +274,17 @@ async function handleNameConflicts(libraryDir) {
             await resolveNameConflicts(libraryDir);
     }
 }
-function groupOptions(groups) {
-    return groups.map((group) => ({ value: group.id, label: group.name, hint: `${group.itemIds.length} saved resources` }));
+function groupOptions(groups, pendingCounts) {
+    return groups.map((group) => ({
+        value: group.id,
+        label: group.name,
+        hint: pendingCounts ? `${group.itemIds.length} saved \u00b7 ${pendingCounts.get(group.id) ?? 0} pending` : `${group.itemIds.length} saved resources`,
+    }));
 }
-async function askForGroupName(message) {
+async function askForGroupName(message, placeholder) {
     const value = await text({
         message,
+        ...(placeholder !== undefined ? { placeholder } : {}),
         validate: (name) => {
             try {
                 nameKey(name ?? "");
@@ -283,6 +297,106 @@ async function askForGroupName(message) {
     });
     return isCancel(value) ? undefined : value.trim();
 }
+/**
+ * Rename prompt text. The suggestion is prefilled only when it renders unchanged through `safeDisplay`
+ * (`initialValue` is echoed raw); otherwise the field stays empty and the masked suggestion is shown in the message.
+ */
+export function renamePrompt(name, sourceDir, suggestion) {
+    const message = `New display name for ${name} \u2014 ${sourceDir} (display name only; files are not changed)`;
+    return safeDisplay(suggestion) === suggestion
+        ? { message, initialValue: suggestion }
+        : { message: `${message}. Suggestion: ${suggestion}` };
+}
+/**
+ * Resolve display-name conflicts right after selection (#9): within the selection first, one group at a time,
+ * then against saved library names. Returns the candidates to review (renamed ones are copies with a new
+ * display name only), "back" to re-show the list, or "cancel".
+ */
+async function resolveSelectedNames(selection, library, labels, homeDir) {
+    let pending = [...selection];
+    const libraryKeys = new Set(library.items.map((item) => nameKey(item.name)));
+    const askNewName = async (candidate, group = [candidate]) => {
+        // Taken: every saved name and every other pending name (assertNameAvailable semantics for the library).
+        const taken = new Set([...libraryKeys, ...pending.filter((other) => other.id !== candidate.id).map((other) => nameKey(other.name))]);
+        const value = await text({
+            ...renamePrompt(candidate.name, displayPath(path.dirname(candidate.sourcePath), homeDir), defaultRenameName(candidate, group)),
+            validate: (name) => {
+                const error = pendingNameError(name, taken);
+                if (error)
+                    return error;
+                try {
+                    assertNameAvailable(library, "item", name ?? "");
+                    return undefined;
+                }
+                catch {
+                    return "That name is already used by a saved or selected resource; choose another.";
+                }
+            },
+        });
+        return isCancel(value) ? undefined : value.trim();
+    };
+    const rename = (candidate, name) => {
+        pending = pending.map((entry) => (entry.id === candidate.id ? { ...entry, name } : entry));
+    };
+    for (const group of findSelectionConflicts(pending)) {
+        const choice = await select({
+            message: `${group.length} selected resources share the name ${group[0].name}; choose what to save`,
+            options: [
+                ...group.map((candidate) => ({ value: `keep:${candidate.id}`, label: `Keep ${labels.get(candidate.id) ?? candidate.name}` })),
+                { value: "rename", label: "Keep all and rename the others" },
+                { value: "back", label: "Go back to the list" },
+            ],
+        });
+        if (isCancel(choice))
+            return "cancel";
+        if (choice === "back")
+            return "back";
+        if (choice === "rename") {
+            for (const candidate of group.slice(1)) {
+                const name = await askNewName(pending.find((entry) => entry.id === candidate.id), group);
+                if (name === undefined)
+                    return "cancel";
+                rename(candidate, name);
+            }
+        }
+        else {
+            const kept = choice.slice("keep:".length);
+            const dropped = new Set(group.filter((candidate) => candidate.id !== kept).map((candidate) => candidate.id));
+            pending = pending.filter((candidate) => !dropped.has(candidate.id));
+        }
+    }
+    for (const candidate of [...pending]) {
+        if (!libraryKeys.has(nameKey(candidate.name)))
+            continue;
+        const choice = await select({
+            message: `${candidate.name} \u2014 ${displayPath(path.dirname(candidate.sourcePath), homeDir)}: a saved resource already uses this name. To update the saved copy, use Refresh in copi manage.`,
+            options: [
+                { value: "skip", label: "Skip (keep the saved copy)" },
+                { value: "rename", label: "Rename" },
+                { value: "back", label: "Go back to the list" },
+            ],
+        });
+        if (isCancel(choice))
+            return "cancel";
+        if (choice === "back")
+            return "back";
+        if (choice === "skip") {
+            pending = pending.filter((entry) => entry.id !== candidate.id);
+            continue;
+        }
+        const name = await askNewName(candidate);
+        if (name === undefined)
+            return "cancel";
+        rename(candidate, name);
+    }
+    return pending;
+}
+/** Quote for POSIX shells only when needed (single quotes, embedded quotes escaped as '\\''). */
+function shellQuote(value) {
+    if (value === "<group>" || /^[A-Za-z0-9_.\/@%+=:,-]+$/.test(value))
+        return value;
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
 export async function runSetup(libraryDir, roots) {
     if (await handleNameConflicts(libraryDir))
         return;
@@ -290,35 +404,34 @@ export async function runSetup(libraryDir, roots) {
     assertModernCatalog(initial);
     assertNoNameConflicts(initial);
     intro("copi setup");
-    const scopeOptions = [];
-    if (roots.homeDir) {
-        scopeOptions.push({
-            value: "home",
-            label: `Search entire HOME: ${roots.homeDir}`,
-            hint: `Includes supported Pi resources under HOME and Pi agent directory ${roots.agentDir}`,
-        });
-    }
-    scopeOptions.push({ value: "project", label: `Search current project: ${roots.projectDir}`, hint: "Supported Pi resources and instruction files in this project" });
-    const selectedScopes = await autocompleteMultiselect({
+    const homeDir = roots.homeDir;
+    const projectLabel = displayPath(roots.projectDir, homeDir);
+    const homeBase = homeDir.length > 1 && homeDir.endsWith(path.sep) ? homeDir.slice(0, -1) : homeDir;
+    const projectIsHome = Boolean(homeDir) && roots.projectDir === homeBase;
+    const projectInsideHome = Boolean(homeDir) && !projectIsHome && roots.projectDir.startsWith(homeBase + path.sep);
+    const locationOptions = [];
+    if (homeDir)
+        locationOptions.push({ value: "home", label: "HOME and Pi agent directory \u2014 ~ (can take a minute or more)" });
+    if (!projectIsHome)
+        locationOptions.push({ value: "project", label: `This project only \u2014 ${projectLabel} (fast)` });
+    if (homeDir && !projectIsHome && !projectInsideHome)
+        locationOptions.push({ value: "both", label: "Both" });
+    locationOptions.push({ value: "cancel", label: "Cancel" });
+    const choice = await select({
         message: "Choose the locations copi may inspect",
-        options: scopeOptions,
-        required: false,
-        placeholder: "Search locations...",
+        options: locationOptions,
+        initialValue: locationOptions[0].value,
     });
-    if (isCancel(selectedScopes)) {
+    if (isCancel(choice) || choice === "cancel") {
         cancel("Setup cancelled.");
         return;
     }
-    const scopes = { home: selectedScopes.includes("home"), project: selectedScopes.includes("project") };
-    const searchOptions = buildSearchOptions(roots, scopes);
-    if (!searchOptions) {
-        outro("No locations selected; nothing was searched or saved.");
-        return;
-    }
+    const scopes = { home: choice === "home" || choice === "both", project: choice === "project" || choice === "both" };
+    const searchOptions = buildSearchOptions(roots, scopes); // every non-cancel choice enables at least one scope
     note([
-        `HOME: ${scopes.home ? roots.homeDir : "not selected"}`,
-        `Pi agent directory: ${scopes.home ? roots.agentDir : "not selected"}`,
-        `Project: ${scopes.project ? roots.projectDir : "not selected"}`,
+        `HOME: ${scopes.home ? displayPath(roots.homeDir, homeDir) : "not selected"}`,
+        `Pi agent directory: ${scopes.home ? displayPath(roots.agentDir, homeDir) : "not selected"}`,
+        `Project: ${scopes.project ? projectLabel : "not selected"}`,
         "Always excluded: entire directories named auth (authentication-specific code may be missing), auth.json, mcp-auth.json, oauth.json, .env* paths, history, cache/caches, .cache, .npm, node_modules, and .git.",
         "Secret detection is heuristic and cannot guarantee completeness. Preview text is masked by default.",
     ].join("\n"), "Search scope and exclusions");
@@ -330,36 +443,64 @@ export async function runSetup(libraryDir, roots) {
         outro("Search not authorized; no resources were inspected or saved.");
         return;
     }
-    const discovery = await discoverResources(searchOptions);
-    showWarnings(discovery.warnings, "Search warnings");
+    const progress = clackSpinner(inheritedSignal());
+    progress.start("Searching selected locations (searching all of HOME can take a minute or more)");
+    let discovery;
+    try {
+        discovery = await discoverResources(searchOptions);
+    }
+    catch (error) {
+        progress.error("Search failed");
+        throw error;
+    }
+    progress.stop(`Search complete: ${discovery.candidates.length} supported resource(s) found`);
+    showSearchWarnings(discovery.warnings, roots.homeDir);
     if (discovery.excludedPaths.length > 0)
-        note(discovery.excludedPaths.join("\n"), "Excluded paths");
+        note(discovery.excludedPaths.map((excluded) => displayPath(excluded, homeDir)).join("\n"), "Excluded paths");
     if (discovery.candidates.length === 0) {
         outro("No supported resources were found.");
         return;
     }
-    const selectedIds = await autocompleteMultiselect({
-        message: "Select resources to review and save as copied snapshots",
-        options: discovery.candidates.map((candidate) => ({
-            value: candidate.id,
-            label: `[${candidate.kind}] ${candidate.name}`,
-            hint: `${candidate.scope} · ${candidate.sourcePath} · ${candidate.destination.kind === "global-only" ? "save only" : candidate.destination.path}`,
-        })),
-        required: false,
-        placeholder: "Filter resources...",
-    });
-    if (isCancel(selectedIds)) {
-        cancel("Setup cancelled; no resources were saved.");
-        return;
+    const sortedCandidates = sortCandidates(discovery.candidates);
+    const candidateStats = await gatherCandidateStats(sortedCandidates);
+    const savedNames = new Set(initial.items.map((item) => nameKey(item.name)));
+    const candidateLabelMap = candidateLabels(sortedCandidates, homeDir, (candidate) => savedNames.has(nameKey(candidate.name)), process.stdout.columns);
+    let previousSelection = [];
+    let resolvedCandidates;
+    while (true) {
+        const selectedIds = await autocompleteMultiselect({
+            message: "Select resources to review and save as copied snapshots",
+            options: sortedCandidates.map((candidate) => {
+                const label = candidateLabelMap.get(candidate.id);
+                return { value: candidate.id, label, hint: candidateHint(candidate, candidateStats.get(candidate.id) ?? {}, homeDir, process.stdout.columns, label.length) };
+            }),
+            required: false,
+            initialValues: previousSelection,
+            placeholder: "Filter resources...",
+        });
+        if (isCancel(selectedIds)) {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        previousSelection = selectedIds;
+        const outcome = await resolveSelectedNames(sortedCandidates.filter((candidate) => selectedIds.includes(candidate.id)), initial, candidateLabelMap, homeDir);
+        if (outcome === "cancel") {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        if (outcome === "back")
+            continue;
+        resolvedCandidates = outcome;
+        break;
     }
-    if (selectedIds.length === 0) {
+    if (resolvedCandidates.length === 0) {
         outro("No resources selected; nothing was saved.");
         return;
     }
     const catalog = await loadCatalog(libraryDir);
     assertModernCatalog(catalog);
     if (catalog.groups.length === 0) {
-        const name = await askForGroupName("Create the first resource group");
+        const name = await askForGroupName("Create the first resource group \u2014 used later with: copi apply <group>", "e.g. game-review");
         if (name === undefined) {
             cancel("Setup cancelled; no resources were saved.");
             return;
@@ -383,12 +524,53 @@ export async function runSetup(libraryDir, roots) {
             createGroup(catalog, name);
         }
     }
-    const selectedCandidates = discovery.candidates.filter((candidate) => selectedIds.includes(candidate.id));
+    // Keep discovery order for review; renamed copies replace their originals by id.
+    const resolvedById = new Map(resolvedCandidates.map((candidate) => [candidate.id, candidate]));
+    const selectedCandidates = discovery.candidates.flatMap((candidate) => resolvedById.get(candidate.id) ?? []);
     const approvedCandidates = [];
-    for (const candidate of selectedCandidates) {
+    // Decide the assignment mode once; "bulk" assigns every approved resource to bulkGroupIds.
+    let bulkGroupIds;
+    const count = selectedCandidates.length;
+    const onlyGroup = catalog.groups.length === 1 ? catalog.groups[0] : undefined;
+    let bulk = count === 1;
+    if (count >= 2) {
+        const mode = await select({
+            message: "How should these resources be grouped?",
+            options: [
+                { value: "all", label: onlyGroup ? `Put all ${count} resources in "${onlyGroup.name}"` : `Put all ${count} resources in the same groups` },
+                { value: "each", label: "Choose groups for each resource" },
+            ],
+            initialValue: "all",
+        });
+        if (isCancel(mode)) {
+            cancel("Setup cancelled; no resources were saved.");
+            return;
+        }
+        bulk = mode === "all";
+    }
+    if (bulk) {
+        if (onlyGroup)
+            bulkGroupIds = [onlyGroup.id];
+        else {
+            const chosen = await autocompleteMultiselect({
+                message: count === 1 ? `Assign ${selectedCandidates[0].name} to one or more groups` : `Put all ${count} resources in these groups`,
+                options: groupOptions(catalog.groups),
+                required: true,
+                placeholder: "Filter groups...",
+            });
+            if (isCancel(chosen)) {
+                cancel("Setup cancelled; no resources were saved.");
+                return;
+            }
+            bulkGroupIds = chosen;
+        }
+    }
+    for (const [index, candidate] of selectedCandidates.entries()) {
         const review = await prepareCandidateForReview(candidate);
-        note(review.preview.length > 0 ? review.preview.join("\n\n") : "No previewable files.", `Masked preview: ${review.candidate.name}`);
-        showWarnings(review.inspection.warnings, `${review.candidate.name} inspection warnings`);
+        const previewTitle = `Masked preview (${index + 1}/${count}): ${review.candidate.name} \u2014 ${displayPath(path.dirname(candidate.sourcePath), homeDir)}`;
+        note(review.preview.length > 0 ? review.preview.join("\n\n") : "No previewable files.", previewTitle);
+        // The heuristic caveat is stated once in the scope note and the summary; per-resource it would only repeat.
+        showWarnings(review.inspection.warnings.filter((warning) => warning.code !== "secret-detection-limited"), `${review.candidate.name} inspection warnings`);
         if (review.inspection.excludedPaths.length > 0) {
             note(review.inspection.excludedPaths.join("\n"), `${review.candidate.name} excluded paths`);
         }
@@ -396,7 +578,7 @@ export async function runSetup(libraryDir, roots) {
         const approvedSensitivePaths = [];
         for (const relativePath of review.inspection.sensitivePaths) {
             const approval = await confirm({
-                message: `Save suspected sensitive file ${relativePath} from ${review.candidate.name}? Detection is heuristic; the file content remains masked in previews.`,
+                message: `Save suspected sensitive file ${relativePath} from ${review.candidate.name}? Detection is heuristic; the file content remains masked in previews. No = ${review.candidate.name} will not be saved at all.`,
                 initialValue: false,
             });
             if (isCancel(approval)) {
@@ -412,9 +594,17 @@ export async function runSetup(libraryDir, roots) {
             log.warn(safeDisplay(`${review.candidate.name} was not selected for saving because a suspected sensitive file was not approved.`));
             continue;
         }
+        if (bulkGroupIds) {
+            approvedCandidates.push({ review, groupIds: bulkGroupIds, approvedSensitivePaths });
+            continue;
+        }
+        const pendingCounts = new Map();
+        for (const approved of approvedCandidates)
+            for (const id of approved.groupIds)
+                pendingCounts.set(id, (pendingCounts.get(id) ?? 0) + 1);
         const groupIds = await autocompleteMultiselect({
             message: `Assign ${review.candidate.name} to one or more groups`,
-            options: groupOptions(catalog.groups),
+            options: groupOptions(catalog.groups, pendingCounts),
             required: true,
             placeholder: "Filter groups...",
         });
@@ -432,9 +622,10 @@ export async function runSetup(libraryDir, roots) {
         const names = groupIds.map((id) => catalog.groups.find((group) => group.id === id)?.name ?? "Unavailable group").join(", ");
         return `${review.candidate.name} → ${names}`;
     }).join("\n");
-    note(summary, "Resources ready to copy");
+    note(`${summary}\n\nSecret detection is heuristic and cannot guarantee completeness.`, "Resources ready to copy");
+    const libraryLabel = displayPath(libraryDir, homeDir);
     const save = await confirm({
-        message: `Save ${approvedCandidates.length} copied resource(s) in ${libraryDir}? Original files will not be changed.`,
+        message: `Save ${approvedCandidates.length} copied resource(s) in ${libraryLabel}? Original files will not be changed.`,
         initialValue: false,
     });
     if (isCancel(save) || !save) {
@@ -457,7 +648,10 @@ export async function runSetup(libraryDir, roots) {
     for (const { review, groupIds, approvedSensitivePaths } of approvedCandidates) {
         await saveReviewedCandidate(libraryDir, review, groupIds, approvedSensitivePaths, true);
     }
-    outro(`Saved ${approvedCandidates.length} copied resource(s) in ${libraryDir}.`);
+    const usedGroupIds = new Set(approvedCandidates.flatMap(({ groupIds }) => groupIds));
+    const usedGroups = catalog.groups.filter((group) => usedGroupIds.has(group.id)).map((group) => group.name);
+    log.info(safeDisplay(`Saved ${approvedCandidates.length} copied resource(s) in ${libraryLabel} (group: ${usedGroups.join(", ")}).`));
+    outro(`Next: copi apply ${shellQuote(usedGroups[0] ?? "<group>")} <project> --dry-run   (edit or rename: copi manage)`);
 }
 export async function runGroupManager(libraryDir) {
     if (await handleNameConflicts(libraryDir))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papillon6814/copi",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Collect and organize reusable Pi coding-agent resources",
   "license": "MIT",
   "type": "module",