@vibe-commit/capture 0.6.1 → 0.8.0

package/dist/picker.d.ts

@@ -0,0 +1,208 @@
+/**
+ * The `connect` picker — style guide §10.12, design review D5-D35; capture 0.7.0, PR 3.
+ *
+ * Which repositories does the person want captured? This module is the PURE half: it turns a `scan` result and the
+ * grants already on disk into rows, parses what the person types, renders the typed screen and the `You chose:` block,
+ * and says what a choice changes. It reads no file, opens no transcript and writes nothing — `connect` supplies the
+ * facts and applies the change, and `picker_checklist.ts` is the arrow-key driver over the same model.
+ *
+ * ## What the rows are
+ *
+ *   on now      grants and per-clone consents that are already admitting capture. REMOVABLE (D31): unticking one, or
+ *               typing `-N`, deletes the grant. It is not an exclusion (`off` is), so the repo can be chosen again.
+ *   owners      one group per owner NOT yet granted, its repos behind an `aN` "all, including repos you clone later"
+ *               row (D9: at most 8 repos before `+ N more`).
+ *   turned off  slugs in `excluded`. Choosing one is a re-include; the grant block names it on a `turn on` row, inside
+ *               the same y/N (D7 · 3A), and only a yes clears the exclusion.
+ *   on your account  (slice 2) what the account grants that this machine has not named. Unticked until chosen, like any
+ *               row: choosing one is an ordinary addition, so it goes through the same disclosure and y/N (R3-8, R3-9).
+ *
+ * ⛔ **A pre-tick is not a consent** (D34): the working folder's repo starts ticked, and Enter on it leads to the naming
+ * y/N, which defaults to N. It is an ADDITION to the diff, never part of the baseline.
+ */
+import { type Grants } from "./consent.js";
+import type { ScanClone, ScanRepo } from "./commands/scan.js";
+import type { AgentId } from "./agents/types.js";
+/** D9: each owner group shows at most this many repos before the `+ N more` row. */
+export declare const GROUP_CAP = 8;
+/** An agent session summary shared by the repo rows. */
+interface Counts {
+    readonly sessions: number;
+    readonly sinceMs: number;
+    readonly agents: Readonly<Record<AgentId, number>>;
+}
+/** A repo the person can add. `synthetic` rows come from the working folder, not from the scan. */
+export interface PickRepo extends Counts {
+    readonly slug: string;
+    readonly owner: string;
+    readonly name: string;
+    readonly clones: readonly ScanClone[];
+    readonly latestMs: number;
+    /** The working folder's repo (D34). */
+    readonly here: "repo" | "folder" | null;
+    /** Starts ticked in the checklist. Only ever the working folder's repo, and only when it is not `$HOME`. */
+    readonly pre: boolean;
+}
+/** One `on now` row. `kind` says what removing it deletes. */
+export interface OnNowRow {
+    readonly kind: "owner" | "repo" | "clone";
+    /** `alexvibecommit` (owner) or a slug. */
+    readonly key: string;
+    readonly reason: string;
+    readonly counts: Counts | null;
+    /** Repos found here under an owner row. */
+    readonly reposHere: number;
+    /** The common dirs a per-clone row stands for (removed together). */
+    readonly commonDirs: readonly string[];
+}
+export interface OwnerGroup {
+    readonly owner: string;
+    /** `a1`, `a2`, … */
+    readonly token: string;
+    /** Every repo under the owner not already on and not turned off, newest session first. */
+    readonly repos: readonly PickRepo[];
+}
+export interface TurnedOffRow {
+    readonly slug: string;
+    readonly counts: Counts | null;
+    /** The working folder's repo, turned off: `connect` inside it pre-selects the `turn on` (D34 + the re-include rule). */
+    readonly pre: boolean;
+}
+/** One account grant this machine has not named (slice 2): an owner (`key` without its slash) or a repo (`key` is the slug). */
+export interface AccountRow {
+    readonly kind: "owner" | "repo";
+    readonly key: string;
+}
+export interface PickerModel {
+    readonly onNow: readonly OnNowRow[];
+    readonly owners: readonly OwnerGroup[];
+    /** What the account grants that this machine has not named. Empty before a sync, or on a machine with no credential. */
+    readonly account: readonly AccountRow[];
+    readonly turnedOff: readonly TurnedOffRow[];
+    /** The picker's `Not listed here:` lines (no remote, can't be matched, unreadable agents). */
+    readonly notListed: readonly string[];
+    /** Repos the scan listed, for the `Found N repositories` line. */
+    readonly found: number;
+    /** The scan saw no session at all (the not-listed block is empty): the new-laptop screen. */
+    readonly sawNothing: boolean;
+}
+/** What a choice changes. Everything is normalized; the lists are disjoint. */
+export interface PickerChange {
+    readonly addOwners: readonly string[];
+    readonly addRepos: readonly string[];
+    readonly turnOn: readonly string[];
+    readonly stopOwners: readonly string[];
+    readonly stopRepos: readonly string[];
+    /** The slugs of per-clone consents to withdraw. */
+    readonly stopClones: readonly string[];
+}
+export declare const NO_CHANGE: PickerChange;
+export declare function isNoChange(change: PickerChange): boolean;
+/**
+ * What Enter means when the working folder's repo is pre-selected (D34): choosing it, which leads to the y/N and never to
+ * a grant. `null` when nothing is pre-selected, where Enter changes nothing (D5).
+ */
+export declare function preChange(model: PickerModel): PickerChange | null;
+/** Anything the person is ADDING needs the D65 disclosure; removals alone do not. */
+export declare function hasAdditions(change: PickerChange): boolean;
+/** The working folder, as the model needs it (D34). */
+export interface HereRepo {
+    readonly slug: string;
+    readonly toplevel: string;
+    /** `repo`: inside a work tree, pre-ticked. `folder`: `$HOME` is itself a repo — flagged, never pre-ticked. */
+    readonly kind: "repo" | "folder";
+}
+export interface ModelInput {
+    readonly repos: readonly ScanRepo[];
+    readonly grants: Grants;
+    /** Per-clone consents (`projects.json`), resolved to the slug of each clone's remote. `null`: no remote. */
+    readonly perClone: readonly {
+        readonly commonDir: string;
+        readonly slug: string | null;
+    }[];
+    readonly notListed: readonly string[];
+    readonly sawNothing: boolean;
+    readonly here: HereRepo | null;
+    /** The account's grants this machine has not named, as `accountView` lists them: `owner/` for an owner, the slug for a repo. */
+    readonly accountNotHere?: readonly string[];
+}
+export declare function buildModel(input: ModelInput): PickerModel;
+/** What a number on screen stands for. On-now rows come first, then each owner's repos, then turned-off. */
+export type RowRef = {
+    readonly kind: "on";
+    readonly row: OnNowRow;
+} | {
+    readonly kind: "repo";
+    readonly repo: PickRepo;
+} | {
+    readonly kind: "account";
+    readonly row: AccountRow;
+} | {
+    readonly kind: "off";
+    readonly row: TurnedOffRow;
+};
+/**
+ * The numbered rows in screen order. `showAll` is the `more` token: every repo is shown and numbered afresh. Without it
+ * each owner shows `GROUP_CAP` repos and the rest are reachable only by typing `owner/repo` or `more`.
+ */
+export declare function numberedRows(model: PickerModel, showAll: boolean): RowRef[];
+export type Parsed = {
+    readonly kind: "empty";
+} | {
+    readonly kind: "more";
+}
+/** `g`, alone, where it was offered (slice 2, exception 3): use the repositories the account already grants. */
+ | {
+    readonly kind: "account";
+} | {
+    readonly kind: "change";
+    readonly change: PickerChange;
+    readonly noClone: readonly string[];
+} | {
+    readonly kind: "error";
+    readonly tokens: readonly string[];
+};
+/**
+ * Parse one typed answer (D8 · 4A). ⛔ **Never applies part of an answer:** any token that is not understood returns
+ * `error` naming each such token, and nothing is chosen. `owner/` and `owner/repo` are always accepted, a clone here or
+ * not, because a new laptop needs them; the grant block flags `(no clone here yet)`.
+ *
+ * ⛔ **`g` STANDS ALONE** (exception 3, R3-12): where `offerAccount` is true, `g` alone is the account's grants, and `g` mixed with
+ * any other token is refused with nothing applied, so the y/N after it always names a single list. Where it was not offered `g` is
+ * an ordinary token nobody understands.
+ */
+export declare function parseTyped(input: string, model: PickerModel, showAll: boolean, offerAccount?: boolean): Parsed;
+export interface RenderOptions {
+    readonly colour: boolean;
+    readonly nowMs: number;
+    /** Show every repo, numbered afresh (the `more` token). */
+    readonly showAll: boolean;
+    /** Slice 2: the prompt block's `g` line (screen 1a). Only on a machine with no credential, a terminal and a browser to sign in with. */
+    readonly offerAccount?: boolean;
+}
+/** The `Not listed here:` block, muted, or nothing. */
+export declare function notListedBlock(model: PickerModel, colour: boolean): string[];
+/** The screen above the prompt, as lines — the typed picker (§10.12 "The picker, typed"). */
+export declare function renderTyped(model: PickerModel, options: RenderOptions): string[];
+/** The `Not understood:` line the prompt prints before it asks again. */
+export declare function notUnderstoodLines(tokens: readonly string[]): string[];
+/** What the grant block needs to know about the machine, so each row says what it covers. */
+export interface BlockFacts {
+    /** owner -> repos found on this machine under it. */
+    readonly reposHere: ReadonlyMap<string, number>;
+    /** Typed `owner/` and `owner/repo` with no clone here. */
+    readonly noClone: ReadonlySet<string>;
+    /** `turn on` slugs the ACCOUNT has turned off: the row says so, because the yes re-includes them on every machine. */
+    readonly accountOff?: ReadonlySet<string>;
+}
+/**
+ * The `You chose:` block — the thing the y/N is asking about (D7 · 3A), on the §13.5 label gutter. One label per kind of
+ * change; an owner row says how many repos are here and that later clones are covered, and a typed name with no clone
+ * on this machine says so, so a typo shows BEFORE the question.
+ */
+export declare function renderGrantBlock(change: PickerChange, facts: BlockFacts, colour: boolean, 
+/** `You chose:` for the person's picks; the account's own list (`g`, screen 1b) is headed `Your account grants:`. */
+heading?: string): string[];
+/** The grant y/N: additions (with or without removals) get the upload question, removals alone the stop question. */
+export declare function grantQuestion(change: PickerChange, colour: boolean, answers: string): string;
+export {};