@g3nomaly/core 0.3.1 → 0.3.3

package/dist/cli/commands/update.js

@@ -6,15 +6,20 @@ import { register } from "../../registry/registry.mutations";
 import { applyClassifications, classifyFiles, recordedHashes, removeInstalledFiles } from "../../installer";
 import { createInstallerIO } from "../../installer/io";
 import { ConflictDecision, FileState } from "../../installer/types";
-import { runDialogueValue } from "../dialogue";
 import { c, lineSuccess, lineWarn, lineInfo } from "../theme";
 import { latestHashFrom } from "./add";
+import { chooseConflict, forkedFrom, forkEntry } from "./conflict";
 const DRY_RUN_LABELS = {
     [FileState.UpToDate]: chalk.dim("up to date"),
     [FileState.SafeUpdate]: chalk.cyan("would update") + chalk.dim(" (package changed, file unmodified)"),
     [FileState.UserOnly]: chalk.yellow("would keep") + chalk.dim(" — local changes"),
-    [FileState.Conflict]: chalk.red("conflict") + chalk.dim(" — keep or overwrite"),
+    [FileState.Conflict]: chalk.red("conflict") + chalk.dim(" — restore, fork or skip"),
 };
+/**
+ * @brief Prints one dry-run line per file with its state.
+ *
+ * @param classifications - Files to print, each with its state.
+ */
 function printDryRun(classifications) {
     for (const cl of classifications) {
         const rel = c.file(path.relative(process.cwd(), cl.destPath));
@@ -22,10 +27,17 @@ function printDryRun(classifications) {
     }
 }
 /**
- * Re-installs entries already present in a target's manifest; with no keys
- * everything installed is updated. Local changes prompt keep/overwrite
- * through `onCollision` unless `--force`. The caller resolves keys before
- * and saves each target's store after.
+ * @brief Re-installs entries already present in a target's manifest; with no keys
+ * everything installed is updated, forks excepted. Local changes prompt
+ * restore/fork/skip through `onCollision` unless `--force`. The caller
+ * resolves keys before and saves each target's store after.
+ *
+ * @param registry - Entries available to install, by key.
+ * @param targets - Destinations to update.
+ * @param source - Source of each entry's files.
+ * @param keys - Keys to update; empty to update everything installed.
+ * @param options - Force, dry run and preset answers.
+ * @param dialogues - Dialogue for local changes.
  */
 export async function updateEntries(registry, targets, source, keys, options = {}, dialogues = {}) {
     const io = createInstallerIO();
@@ -39,12 +51,17 @@ export async function updateEntries(registry, targets, source, keys, options = {
             continue;
         }
         for (const key of wanted) {
+            const installed = get(target.store, key);
+            const original = installed === undefined ? undefined : forkedFrom(installed);
+            if (original !== undefined) {
+                console.log(lineInfo(`${c.key(key)} is a fork of ${c.key(original)} — not updated`));
+                continue;
+            }
             const meta = registry[key];
             if (!meta) {
                 console.log(lineWarn(`${c.key(key)} is installed but no longer in the package — leaving as is`));
                 continue;
             }
-            const installed = get(target.store, key);
             const fileSource = await source(meta);
             const classifications = await classifyFiles(meta.files, target.installDir, recordedHashes(installed), io, latestHashFrom(fileSource, io));
             const stale = (installed?.files ?? []).filter((f) => !meta.files.some((m) => m.path === f.path));
@@ -56,14 +73,15 @@ export async function updateEntries(registry, targets, source, keys, options = {
                 }
                 continue;
             }
-            let decision = ConflictDecision.Keep;
             const hasLocalChanges = classifications.some((cl) => cl.state >= FileState.UserOnly);
-            if (hasLocalChanges && !options.force && dialogues.onCollision !== undefined) {
-                const answer = await runDialogueValue(dialogues.onCollision, { key: c.key(key), target: c.target(target.label) }, options.answers);
-                if (answer === ConflictDecision.Overwrite)
-                    decision = ConflictDecision.Overwrite;
+            const choice = hasLocalChanges
+                ? await chooseConflict(dialogues.onCollision, key, installed ?? meta, target, options)
+                : { decision: ConflictDecision.Keep };
+            if (choice.decision === ConflictDecision.Fork) {
+                await forkEntry(target, key, installed ?? meta, choice.forkKey, io);
+                continue;
             }
-            const result = await applyClassifications(classifications, fileSource, { decision, force: options.force ?? false }, io);
+            const result = await applyClassifications(classifications, fileSource, { decision: choice.decision, force: options.force ?? false }, io);
             if (stale.length > 0) {
                 const removal = await removeInstalledFiles(stale, target.installDir, { force: options.force }, io);
                 for (const file of removal.kept) {
@@ -77,7 +95,7 @@ export async function updateEntries(registry, targets, source, keys, options = {
                 console.log(lineWarn(`No content for ${c.file(file)} in the package source — skipped`));
             }
             if (result.kept.length > 0) {
-                console.log(lineWarn(`${c.key(key)} — kept ${result.kept.map((f) => c.file(f)).join(", ")}`));
+                console.log(lineWarn(`${c.key(key)} — skipped ${result.kept.map((f) => c.file(f)).join(", ")} ${chalk.dim("(local changes, asked again next update)")}`));
             }
             if (result.written.length > 0) {
                 console.log(lineSuccess(`Updated ${c.key(key)} ${chalk.dim(`(${result.written.length} file${result.written.length === 1 ? "" : "s"})`)}`));

package/dist/cli/commands/update.js.map

@@ -1 +1 @@
-{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/cli/commands/update.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"update.js","sourceRoot":"","sources":["../../../src/cli/commands/update.ts"],"names":[],"mappings":"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"}

package/dist/cli/dialogue.d.ts

@@ -4,8 +4,16 @@ export declare const StepKind: {
     readonly Confirm: 2;
     readonly Text: 3;
 };
+/** Kind of a dialogue step: select, multi-select, confirm or text. */
 export type StepKind = (typeof StepKind)[keyof typeof StepKind];
+/** Answers a dialogue collects, keyed by step id. */
 export type DialogueAnswers = Record<string, unknown>;
+/**
+ * @brief One choice of a select or multi-select step.
+ *
+ * @property value - Value the step answers with.
+ * @property label - Text shown for the choice, with `{name}` placeholders filled from the input.
+ */
 export interface StepChoice<V = unknown> {
     value: V;
     label: string;
@@ -13,61 +21,105 @@ export interface StepChoice<V = unknown> {
 /** A literal value, or a function deriving it from the walk's input. */
 export type Resolvable<Input, V> = V | ((input: Input) => V);
 /**
- * One question of a dialogue. `when` decides whether the step runs at all; a
- * skipped step records no answer and falls through to `next`. `next` links to
- * the following step: a step id for linear flow, a function of the answer for
- * branching, absent to end. `{name}` placeholders in messages and labels are
- * filled from the walk's input.
+ * @brief One question of a dialogue, shared by every kind of step.
+ *
+ * `{name}` placeholders in messages and labels are filled from the walk's input.
+ *
+ * @property message - Question shown to the user.
+ * @property when - Decides whether the step runs at all; a skipped step records no answer and falls through to `next`.
+ * @property next - Following step: a step id for linear flow, a function of the answer for branching, absent to end.
  */
 interface StepBase<Input> {
     message: string;
     when?: (input: Input, answers: DialogueAnswers) => boolean;
     next?: string | ((answer: unknown, answers: DialogueAnswers, input: Input) => string | null);
 }
+/**
+ * @brief A step that asks the user to pick one of its choices.
+ *
+ * @property kind - Always `StepKind.Select`.
+ * @property choices - Choices offered, literal or derived from the input.
+ * @property initial - Choice preselected, literal or derived from the input.
+ */
 export interface SelectStep<Input = DialogueAnswers> extends StepBase<Input> {
     kind: typeof StepKind.Select;
     choices: Resolvable<Input, StepChoice[]>;
     initial?: Resolvable<Input, string | number | boolean>;
 }
+/**
+ * @brief A step that asks the user to pick any number of its choices.
+ *
+ * @property kind - Always `StepKind.MultiSelect`.
+ * @property choices - Choices offered, literal or derived from the input.
+ * @property initial - Choices preselected, literal or derived from the input.
+ * @property required - Whether at least one choice must be picked.
+ */
 export interface MultiSelectStep<Input = DialogueAnswers> extends StepBase<Input> {
     kind: typeof StepKind.MultiSelect;
     choices: Resolvable<Input, StepChoice[]>;
     initial?: Resolvable<Input, unknown[]>;
     required?: boolean;
 }
+/**
+ * @brief A step that asks a yes or no question.
+ *
+ * @property kind - Always `StepKind.Confirm`.
+ * @property initial - Starting answer, literal or derived from the input.
+ */
 export interface ConfirmStep<Input = DialogueAnswers> extends StepBase<Input> {
     kind: typeof StepKind.Confirm;
     initial?: Resolvable<Input, boolean>;
 }
+/**
+ * @brief A step that asks for free text.
+ *
+ * @property kind - Always `StepKind.Text`.
+ * @property initial - Starting text, literal or derived from the input.
+ * @property validate - Returns an error message for an invalid value, or `undefined` when it is valid.
+ */
 export interface TextStep<Input = DialogueAnswers> extends StepBase<Input> {
     kind: typeof StepKind.Text;
     initial?: Resolvable<Input, string>;
     validate?: (value: string | undefined) => string | undefined;
 }
+/** One step of a dialogue, of any kind. */
 export type DialogueStep<Input = DialogueAnswers> = SelectStep<Input> | MultiSelectStep<Input> | ConfirmStep<Input> | TextStep<Input>;
 /**
- * A command's interaction with the user: a graph of steps keyed by id,
+ * @brief A command's interaction with the user: a graph of steps keyed by id,
  * entered at the first key and linked through each step's `next`. Commands
  * take dialogues through named slots (e.g. `onNoValue`, `onCollision`) and
  * run them with `runDialogueValue`; init flows are linked lists run with
  * `runDialogue`. Preset answers (`options.answers`, keyed by step id) skip
  * the terminal prompt — that is how tests and non-interactive runs answer.
+ *
+ * @property steps - Steps keyed by id; the walk enters at the first key.
  */
 export interface Dialogue<Input = DialogueAnswers> {
     steps: Record<string, DialogueStep<Input>>;
 }
 /**
- * Walks a dialogue from its first step, skipping steps whose `when` is
- * false, and collects answers by step id. A preset answer in `answers` is
+ * @brief Walks a dialogue from its first step and collects answers by step id.
+ *
+ * Skips steps whose `when` is false. A preset answer in `answers` is
  * recorded without prompting; anything else renders in the terminal.
- * Returns the cancel symbol as soon as any step is cancelled. Unknown step
- * ids throw.
+ * Returns the cancel symbol as soon as any step is cancelled.
+ *
+ * @param dialogue - Dialogue to walk.
+ * @param input - Input the steps read.
+ * @param answers - Preset answers by step id.
+ * @returns Answers by step id, or the cancel symbol.
+ * @throws {Error} When the walk reaches a step id that is not in the dialogue.
  */
 export declare function runDialogue<Input>(dialogue: Dialogue<Input>, input: Input, answers?: DialogueAnswers): Promise<DialogueAnswers | symbol>;
 /**
- * Runs a dialogue and returns the answer of its last executed step — the
- * contract for the commands' named dialogue slots. Returns undefined when no
- * step ran, or the cancel symbol.
+ * @brief Runs a dialogue and returns the answer of its last executed step.
+ *
+ * This is the contract for the commands' named dialogue slots.
+ *
+ * @param dialogue - Dialogue to run.
+ * @param input - Input the steps read.
+ * @param answers - Preset answers by step id.
+ * @returns The answer of the last step that ran, `undefined` when no step ran, or the cancel symbol.
  */
 export declare function runDialogueValue<Input>(dialogue: Dialogue<Input>, input: Input, answers?: DialogueAnswers): Promise<unknown>;
 export {};

package/dist/cli/dialogue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dialogue.d.ts","sourceRoot":"","sources":["../../src/cli/dialogue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dialogue.d.ts","sourceRoot":"","sources":["../../src/cli/dialogue.ts"],"names":[],"mappings":"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"}

package/dist/cli/dialogue.js

@@ -9,6 +9,13 @@ export const StepKind = {
 // ---------------------------------------------------------------------------
 // Resolving
 // ---------------------------------------------------------------------------
+/**
+ * @brief Fills the `{name}` placeholders of a template from the fields of the input.
+ *
+ * @param template - Text with `{name}` placeholders.
+ * @param input - Object whose fields fill the placeholders; a placeholder without a field stays as written.
+ * @returns The text with its placeholders filled.
+ */
 function interpolate(template, input) {
     const record = (typeof input === "object" && input !== null ? input : {});
     return template.replace(/\{(\w+)\}/g, (match, name) => {
@@ -16,9 +23,24 @@ function interpolate(template, input) {
         return value === undefined ? match : String(value);
     });
 }
+/**
+ * @brief Resolves a value that is literal or a function of the input.
+ *
+ * @param value - Literal value, or a function of `input`; `undefined` passes through.
+ * @param input - Input the function is called with.
+ * @returns The literal, or the function's result.
+ */
 function resolveValue(value, input) {
     return typeof value === "function" ? value(input) : value;
 }
+/**
+ * @brief Resolves every field of a step against the input, ready to render.
+ *
+ * @param id - Id of the step.
+ * @param step - Step to resolve.
+ * @param input - Input the placeholders and functions read.
+ * @returns The resolved step.
+ */
 function resolveStep(id, step, input) {
     const resolved = { id, kind: step.kind, message: interpolate(step.message, input) };
     switch (step.kind) {
@@ -43,6 +65,12 @@ function resolveStep(id, step, input) {
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
+/**
+ * @brief Renders one resolved step in the terminal and returns the answer.
+ *
+ * @param step - Step to render.
+ * @returns The user's answer, or the cancel symbol.
+ */
 async function render(step) {
     switch (step.kind) {
         case StepKind.Select:
@@ -77,11 +105,17 @@ async function render(step) {
 // Walking
 // ---------------------------------------------------------------------------
 /**
- * Walks a dialogue from its first step, skipping steps whose `when` is
- * false, and collects answers by step id. A preset answer in `answers` is
+ * @brief Walks a dialogue from its first step and collects answers by step id.
+ *
+ * Skips steps whose `when` is false. A preset answer in `answers` is
  * recorded without prompting; anything else renders in the terminal.
- * Returns the cancel symbol as soon as any step is cancelled. Unknown step
- * ids throw.
+ * Returns the cancel symbol as soon as any step is cancelled.
+ *
+ * @param dialogue - Dialogue to walk.
+ * @param input - Input the steps read.
+ * @param answers - Preset answers by step id.
+ * @returns Answers by step id, or the cancel symbol.
+ * @throws {Error} When the walk reaches a step id that is not in the dialogue.
  */
 export async function runDialogue(dialogue, input, answers = {}) {
     const collected = {};
@@ -103,9 +137,14 @@ export async function runDialogue(dialogue, input, answers = {}) {
     return collected;
 }
 /**
- * Runs a dialogue and returns the answer of its last executed step — the
- * contract for the commands' named dialogue slots. Returns undefined when no
- * step ran, or the cancel symbol.
+ * @brief Runs a dialogue and returns the answer of its last executed step.
+ *
+ * This is the contract for the commands' named dialogue slots.
+ *
+ * @param dialogue - Dialogue to run.
+ * @param input - Input the steps read.
+ * @param answers - Preset answers by step id.
+ * @returns The answer of the last step that ran, `undefined` when no step ran, or the cancel symbol.
  */
 export async function runDialogueValue(dialogue, input, answers = {}) {
     const record = await runDialogue(dialogue, input, answers);

package/dist/cli/dialogue.js.map

@@ -1 +1 @@
-{"version":3,"file":"dialogue.js","sourceRoot":"","sources":["../../src/cli/dialogue.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dialogue.js","sourceRoot":"","sources":["../../src/cli/dialogue.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,OAAO,KAAK,CAAC,MAAM,gBAAgB,CAAC;AAEpC,MAAM,CAAC,MAAM,QAAQ,GAAG;IACtB,MAAM,EAAO,CAAC;IACd,WAAW,EAAE,CAAC;IACd,OAAO,EAAM,CAAC;IACd,IAAI,EAAS,CAAC;CACN,CAAC;AA8HX,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;GAMG;AACH,SAAS,WAAW,CAAC,QAAgB,EAAE,KAAc;IACnD,MAAM,MAAM,GAAG,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAA4B,CAAC;IACrG,OAAO,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,IAAY,EAAE,EAAE;QAC5D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3B,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,YAAY,CAAW,KAAuC,EAAE,KAAY;IACnF,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAE,KAA6B,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;AACrF,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAQ,EAAU,EAAE,IAAyB,EAAE,KAAY;IAC7E,MAAM,QAAQ,GAAiB,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE,CAAC;IAClG,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC,MAAM,CAAC;QACrB,KAAK,QAAQ,CAAC,WAAW,EAAE,CAAC;YAC1B,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YACxD,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC;YACrG,QAAQ,CAAC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACrD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC,WAAW;gBAAE,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAC1E,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,KAAK,QAAQ,CAAC,OAAO;YACnB,QAAQ,CAAC,OAAO,GAAG,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACrD,OAAO,QAAQ,CAAC;QAClB,KAAK,QAAQ,CAAC,IAAI;YAChB,QAAQ,CAAC,OAAO,GAAI,YAAY,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACtD,QAAQ,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YAClC,OAAO,QAAQ,CAAC;IACpB,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;GAKG;AACH,KAAK,UAAU,MAAM,CAAC,IAAkB;IACtC,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,QAAQ,CAAC,MAAM;YAClB,OAAO,CAAC,CAAC,MAAM,CAAC;gBACd,OAAO,EAAO,IAAI,CAAC,OAAO;gBAC1B,OAAO,EAAO,IAAI,CAAC,OAAO,IAAI,EAAE;gBAChC,YAAY,EAAE,IAAI,CAAC,OAAO;aAC3B,CAAC,CAAC;QACL,KAAK,QAAQ,CAAC,WAAW;YACvB,OAAO,CAAC,CAAC,WAAW,CAAC;gBACnB,OAAO,EAAQ,IAAI,CAAC,OAAO;gBAC3B,OAAO,EAAQ,IAAI,CAAC,OAAO,IAAI,EAAE;gBACjC,aAAa,EAAE,IAAI,CAAC,OAAgC;gBACpD,QAAQ,EAAO,IAAI,CAAC,QAAQ;aAC7B,CAAC,CAAC;QACL,KAAK,QAAQ,CAAC,OAAO;YACnB,OAAO,CAAC,CAAC,OAAO,CAAC;gBACf,OAAO,EAAO,IAAI,CAAC,OAAO;gBAC1B,YAAY,EAAG,IAAI,CAAC,OAA+B,IAAI,KAAK;aAC7D,CAAC,CAAC;QACL,KAAK,QAAQ,CAAC,IAAI;YAChB,OAAO,CAAC,CAAC,IAAI,CAAC;gBACZ,OAAO,EAAO,IAAI,CAAC,OAAO;gBAC1B,YAAY,EAAE,IAAI,CAAC,OAA6B;gBAChD,QAAQ,EAAM,IAAI,CAAC,QAAQ;aAC5B,CAAC,CAAC;QACL;YACE,MAAM,IAAI,KAAK,CAAC,qBAAqB,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAyB,EACzB,KAAY,EACZ,OAAO,GAAoB,EAAE;IAE7B,MAAM,SAAS,GAAoB,EAAE,CAAC;IACtC,IAAI,EAAE,GAAkB,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;IAE/D,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,GAAoC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACjE,IAAI,IAAI,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,EAAE,GAAG,CAAC,CAAC;QAExE,IAAI,MAAM,GAAY,SAAS,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;YAC3D,MAAM,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAAC;YAC3B,MAAM,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC;YACpF,IAAI,OAAO,MAAM,KAAK,QAAQ;gBAAE,OAAO,MAAM,CAAC;YAC9C,SAAS,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC;QACzB,CAAC;QAED,EAAE,GAAG,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC;IACjG,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,QAAyB,EACzB,KAAY,EACZ,OAAO,GAAoB,EAAE;IAE7B,MAAM,MAAM,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3D,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACxC,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AACvD,CAAC"}

package/dist/cli/index.d.ts

@@ -13,7 +13,7 @@ export { lsSourceRegistry } from "./commands/ls";
 export { addSourceEntries, lsSources, removeSourceEntries } from "./commands/sources";
 export type { SourceCommandContext, SourceAddOptions } from "./commands/sources";
 export { pickOffers, selectEntriesDialogue } from "./pick";
-export { overwriteDialogue, removeChangedDialogue, cascadeDialogue, incompleteDialogue, selectRemovalDialogue, notInstalledDialogue } from "./installDialogues";
+export { conflictDialogue, removeChangedDialogue, cascadeDialogue, incompleteDialogue, selectRemovalDialogue, notInstalledDialogue } from "./installDialogues";
 export { addFromSources, updateFromSources, removeFromTargets } from "./commands/installFromSources";
 export type { ManifestTarget, InstallCommandContext, AfterTarget } from "./commands/installFromSources";
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACpE,YAAY,EACV,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAC/D,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,GACnD,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC/G,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACrF,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC/J,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACpG,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AACA,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AACpE,YAAY,EACV,QAAQ,EAAE,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,UAAU,EAC/D,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,GACnD,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAC/G,YAAY,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AACrF,YAAY,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AAChF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9J,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA;AACpG,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA"}

package/dist/cli/index.js

@@ -11,6 +11,6 @@ export { reportSourceRegistry, orExit, reportResolution, entryNotFoundDialogue,
 export { lsSourceRegistry } from "./commands/ls";
 export { addSourceEntries, lsSources, removeSourceEntries } from "./commands/sources";
 export { pickOffers, selectEntriesDialogue } from "./pick";
-export { overwriteDialogue, removeChangedDialogue, cascadeDialogue, incompleteDialogue, selectRemovalDialogue, notInstalledDialogue } from "./installDialogues";
+export { conflictDialogue, removeChangedDialogue, cascadeDialogue, incompleteDialogue, selectRemovalDialogue, notInstalledDialogue } from "./installDialogues";
 export { addFromSources, updateFromSources, removeFromTargets } from "./commands/installFromSources";
 //# sourceMappingURL=index.js.map

package/dist/cli/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAKpE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE/G,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAErF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC/J,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,cAAc,SAAS,CAAA;AACvB,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAKpE,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AACzC,OAAO,EAAE,CAAC,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AAE/G,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAA;AAErF,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,eAAe,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC9J,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAA"}

package/dist/cli/installDialogues.d.ts

@@ -1,14 +1,22 @@
 import type { Dialogue } from "./dialogue";
 import type { InstallInput } from "./types";
-/** Keep or overwrite an entry with local changes, for `add` and `update`; step id `conflict`. */
-export declare const overwriteDialogue: Dialogue<InstallInput>;
+/**
+ * @brief Restore, fork or skip an entry with local changes, for `add` and `update`; step id `conflict`, then
+ * `forkName` for the key of the fork.
+ */
+export declare const conflictDialogue: Dialogue<InstallInput>;
 /** Keep or remove an entry with local changes, for `remove`; step id `conflict`. */
 export declare const removeChangedDialogue: Dialogue<InstallInput>;
 /** Whether to remove the installed entries that depend on one being removed; step id `cascade`. */
 export declare const cascadeDialogue: Dialogue<InstallInput>;
 /** Whether to remove an entry with files already missing on disk; step id `incomplete`. */
 export declare const incompleteDialogue: Dialogue<InstallInput>;
-/** Which installed entries to remove when none were named; step id `selectEntries`. */
+/**
+ * @brief Builds the picker that asks which installed entries to remove.
+ *
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @returns Dialogue with the step `selectEntries`.
+ */
 export declare function selectRemovalDialogue(noun: string): Dialogue<InstallInput>;
 /** Whether to go on when some names given to `update` are not installed; step id `entryNotFound`. */
 export declare const notInstalledDialogue: Dialogue<InstallInput>;

package/dist/cli/installDialogues.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installDialogues.d.ts","sourceRoot":"","sources":["../../src/cli/installDialogues.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C,iGAAiG;AACjG,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,YAAY,CAWpD,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAWxD,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,YAAY,CAQlD,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,YAAY,CAQrD,CAAC;AAEF,uFAAuF;AACvF,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAU1E;AAED,qGAAqG;AACrG,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,YAAY,CAQvD,CAAC"}
+{"version":3,"file":"installDialogues.d.ts","sourceRoot":"","sources":["../../src/cli/installDialogues.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,YAAY,CAoBnD,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,EAAE,QAAQ,CAAC,YAAY,CAWxD,CAAC;AAEF,mGAAmG;AACnG,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC,YAAY,CAQlD,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,YAAY,CAQrD,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAU1E;AAED,qGAAqG;AACrG,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,YAAY,CAQvD,CAAC"}

package/dist/cli/installDialogues.js

@@ -1,16 +1,28 @@
 // packages/core/src/cli/installDialogues.ts
 import { ConflictDecision } from "../installer/types";
 import { StepKind } from "./dialogue";
-/** Keep or overwrite an entry with local changes, for `add` and `update`; step id `conflict`. */
-export const overwriteDialogue = {
+/**
+ * @brief Restore, fork or skip an entry with local changes, for `add` and `update`; step id `conflict`, then
+ * `forkName` for the key of the fork.
+ */
+export const conflictDialogue = {
     steps: {
         conflict: {
             kind: StepKind.Select,
             message: "{key} ({target}) has local changes. What would you like to do?",
             choices: [
-                { value: ConflictDecision.Keep, label: "Keep my changes: skip modified files" },
-                { value: ConflictDecision.Overwrite, label: "Overwrite with the source version" },
+                { value: ConflictDecision.Overwrite, label: "Restore: overwrite my changes with the source version" },
+                { value: ConflictDecision.Fork, label: "Fork: keep my changes as a local entry under a new name" },
+                { value: ConflictDecision.Keep, label: "Skip: leave my changes and ask again next time" },
             ],
+            initial: ConflictDecision.Keep,
+            next: (answer) => (answer === ConflictDecision.Fork ? "forkName" : null),
+        },
+        forkName: {
+            kind: StepKind.Text,
+            message: "Name of the local entry:",
+            initial: (input) => input.forkName ?? "",
+            validate: (value) => (value === undefined || !/^\S+$/.test(value) ? "Enter a name without spaces" : undefined),
         },
     },
 };
@@ -47,7 +59,12 @@ export const incompleteDialogue = {
         },
     },
 };
-/** Which installed entries to remove when none were named; step id `selectEntries`. */
+/**
+ * @brief Builds the picker that asks which installed entries to remove.
+ *
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @returns Dialogue with the step `selectEntries`.
+ */
 export function selectRemovalDialogue(noun) {
     return {
         steps: {

package/dist/cli/installDialogues.js.map

@@ -1 +1 @@
-{"version":3,"file":"installDialogues.js","sourceRoot":"","sources":["../../src/cli/installDialogues.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,iGAAiG;AACjG,MAAM,CAAC,MAAM,iBAAiB,GAA2B;IACvD,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,IAAI,EAAK,QAAQ,CAAC,MAAM;YACxB,OAAO,EAAE,gEAAgE;YACzE,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,EAAO,KAAK,EAAE,sCAAsC,EAAE;gBACpF,EAAE,KAAK,EAAE,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,mCAAmC,EAAE;aAClF;SACF;KACF;CACF,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAA2B;IAC3D,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,IAAI,EAAK,QAAQ,CAAC,MAAM;YACxB,OAAO,EAAE,gEAAgE;YACzE,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,EAAO,KAAK,EAAE,yBAAyB,EAAE;gBACvE,EAAE,KAAK,EAAE,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,wCAAwC,EAAE;aACvF;SACF;KACF;CACF,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,KAAK,EAAE;QACL,OAAO,EAAE;YACP,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,2BAA2B;YACpC,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,KAAK,EAAE;QACL,UAAU,EAAE;YACV,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,gFAAgF;YACzF,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAC;AAEF,uFAAuF;AACvF,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,KAAK,EAAE;YACL,aAAa,EAAE;gBACb,IAAI,EAAK,QAAQ,CAAC,WAAW;gBAC7B,OAAO,EAAE,UAAU,IAAI,cAAc;gBACrC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;aAC3C;SACF;KACF,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAC1D,KAAK,EAAE;QACL,aAAa,EAAE;YACb,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,kEAAkE;YAC3E,OAAO,EAAE,KAAK;SACf;KACF;CACF,CAAC"}
+{"version":3,"file":"installDialogues.js","sourceRoot":"","sources":["../../src/cli/installDialogues.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAA2B;IACtD,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,IAAI,EAAK,QAAQ,CAAC,MAAM;YACxB,OAAO,EAAE,gEAAgE;YACzE,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,uDAAuD,EAAE;gBACrG,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,EAAO,KAAK,EAAE,yDAAyD,EAAE;gBACvG,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,EAAO,KAAK,EAAE,gDAAgD,EAAE;aAC/F;YACD,OAAO,EAAE,gBAAgB,CAAC,IAAI;YAC9B,IAAI,EAAK,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,gBAAgB,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;SAC5E;QACD,QAAQ,EAAE;YACR,IAAI,EAAM,QAAQ,CAAC,IAAI;YACvB,OAAO,EAAG,0BAA0B;YACpC,OAAO,EAAG,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE;YACzC,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;SAC/G;KACF;CACF,CAAC;AAEF,oFAAoF;AACpF,MAAM,CAAC,MAAM,qBAAqB,GAA2B;IAC3D,KAAK,EAAE;QACL,QAAQ,EAAE;YACR,IAAI,EAAK,QAAQ,CAAC,MAAM;YACxB,OAAO,EAAE,gEAAgE;YACzE,OAAO,EAAE;gBACP,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,EAAO,KAAK,EAAE,yBAAyB,EAAE;gBACvE,EAAE,KAAK,EAAE,gBAAgB,CAAC,SAAS,EAAE,KAAK,EAAE,wCAAwC,EAAE;aACvF;SACF;KACF;CACF,CAAC;AAEF,mGAAmG;AACnG,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,KAAK,EAAE;QACL,OAAO,EAAE;YACP,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,2BAA2B;YACpC,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAC;AAEF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,kBAAkB,GAA2B;IACxD,KAAK,EAAE;QACL,UAAU,EAAE;YACV,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,gFAAgF;YACzF,OAAO,EAAE,IAAI;SACd;KACF;CACF,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,KAAK,EAAE;YACL,aAAa,EAAE;gBACb,IAAI,EAAK,QAAQ,CAAC,WAAW;gBAC7B,OAAO,EAAE,UAAU,IAAI,cAAc;gBACrC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;aAC3C;SACF;KACF,CAAC;AACJ,CAAC;AAED,qGAAqG;AACrG,MAAM,CAAC,MAAM,oBAAoB,GAA2B;IAC1D,KAAK,EAAE;QACL,aAAa,EAAE;YACb,IAAI,EAAK,QAAQ,CAAC,OAAO;YACzB,OAAO,EAAE,kEAAkE;YAC3E,OAAO,EAAE,KAAK;SACf;KACF;CACF,CAAC"}

package/dist/cli/pick.d.ts

@@ -2,12 +2,21 @@ import type { OriginEntry } from "../installer/origin";
 import type { SourceOffer } from "../installer/sourceRegistry";
 import type { Dialogue, DialogueAnswers } from "./dialogue";
 import type { InstallInput } from "./types";
-/** The multi-select `pickOffers` asks through, by step id `selectEntries`, for preset answers. */
+/**
+ * @brief Builds the multi-select `pickOffers` asks through, by step id `selectEntries`.
+ *
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @returns Dialogue with the step `selectEntries`.
+ */
 export declare function selectEntriesDialogue(noun: string): Dialogue<InstallInput>;
 /**
- * Asks which offers to install, each as `<key>@<source>`, so two sources
+ * @brief Asks which offers to install, each as `<key>@<source>`, so two sources
  * offering one key stay apart. Exits when the prompt is cancelled.
  *
+ * @param available - Offers to pick from.
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @param answers - Preset answers by step id.
+ *
  * @returns the picked requests, e.g. `["emphasise@g3n-skills"]`
  */
 export declare function pickOffers<T extends OriginEntry>(available: readonly SourceOffer<T>[], noun: string, answers?: DialogueAnswers): Promise<string[]>;

package/dist/cli/pick.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pick.d.ts","sourceRoot":"","sources":["../../src/cli/pick.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C,kGAAkG;AAClG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAU1E;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,SAAS,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQxJ"}
+{"version":3,"file":"pick.d.ts","sourceRoot":"","sources":["../../src/cli/pick.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5C;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,CAU1E;AAED;;;;;;;;;GASG;AACH,wBAAsB,UAAU,CAAC,CAAC,SAAS,WAAW,EAAE,SAAS,EAAE,SAAS,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAQxJ"}

package/dist/cli/pick.js

@@ -5,7 +5,12 @@ import { guardCancel } from "../utils/prompt";
 import { StepKind, runDialogueValue } from "./dialogue";
 import { c } from "./theme";
 const PicksSchema = z.array(z.string());
-/** The multi-select `pickOffers` asks through, by step id `selectEntries`, for preset answers. */
+/**
+ * @brief Builds the multi-select `pickOffers` asks through, by step id `selectEntries`.
+ *
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @returns Dialogue with the step `selectEntries`.
+ */
 export function selectEntriesDialogue(noun) {
     return {
         steps: {
@@ -18,9 +23,13 @@ export function selectEntriesDialogue(noun) {
     };
 }
 /**
- * Asks which offers to install, each as `<key>@<source>`, so two sources
+ * @brief Asks which offers to install, each as `<key>@<source>`, so two sources
  * offering one key stay apart. Exits when the prompt is cancelled.
  *
+ * @param available - Offers to pick from.
+ * @param noun - What one entry is called, e.g. `skill`.
+ * @param answers - Preset answers by step id.
+ *
  * @returns the picked requests, e.g. `["emphasise@g3n-skills"]`
  */
 export async function pickOffers(available, noun, answers) {

package/dist/cli/pick.js.map

@@ -1 +1 @@
-{"version":3,"file":"pick.js","sourceRoot":"","sources":["../../src/cli/pick.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGxD,OAAO,EAAE,CAAC,EAAE,MAAM,SAAS,CAAC;AAE5B,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAExC,kGAAkG;AAClG,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,KAAK,EAAE;YACL,aAAa,EAAE;gBACb,IAAI,EAAK,QAAQ,CAAC,WAAW;gBAC7B,OAAO,EAAE,UAAU,IAAI,eAAe;gBACtC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;aAC3C;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAwB,SAAoC,EAAE,IAAY,EAAE,OAAyB;IACnI,MAAM,UAAU,GAAG,CAAC,GAAG,SAAS,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SACxG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACxB,KAAK,EAAE,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;QACtC,KAAK,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE;KACjI,CAAC,CAAC,CAAC;IACN,OAAO,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,gBAAgB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC5H,CAAC"}
+{"version":3,"file":"pick.js","sourceRoot":"","sources":["../../src/cli/pick.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGxD,OAAO,EAAE,CAAC,EAAE,MAAM,SAAS,CAAC;AAE5B,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO;QACL,KAAK,EAAE;YACL,aAAa,EAAE;gBACb,IAAI,EAAK,QAAQ,CAAC,WAAW;gBAC7B,OAAO,EAAE,UAAU,IAAI,eAAe;gBACtC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE;aAC3C;SACF;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAwB,SAAoC,EAAE,IAAY,EAAE,OAAyB;IACnI,MAAM,UAAU,GAAG,CAAC,GAAG,SAAS,CAAC;SAC9B,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;SACxG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;QACxB,KAAK,EAAE,GAAG,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE;QACtC,KAAK,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE;KACjI,CAAC,CAAC,CAAC;IACN,OAAO,WAAW,CAAC,KAAK,CAAC,WAAW,CAAC,MAAM,gBAAgB,CAAC,qBAAqB,CAAC,IAAI,CAAC,EAAE,EAAE,UAAU,EAAE,EAAE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;AAC5H,CAAC"}