@north-light/api 0.3.580 → 0.3.588

package/dist/commands/pkg/browse/list-panel.js

@@ -0,0 +1,168 @@
+import { matchesKey, truncateToWidth, visibleWidth } from '@earendil-works/pi-tui';
+import { padAnsi, theme, visibleRange } from '../../../core/tui/panel.js';
+import { displayVersion, plural } from './model.js';
+/** The middle column of the plugin browser. It owns filtering and row position;
+ * the shell owns horizontal navigation and actions. */
+export class PkgListPanel {
+    onChange;
+    source;
+    index = 0;
+    filter = "";
+    filtering = false;
+    notice;
+    hasMarketplaces = false;
+    constructor(onChange) {
+        this.onChange = onChange;
+    }
+    get selected() {
+        const entries = this.entries();
+        this.index = Math.max(0, Math.min(this.index, entries.length - 1));
+        return entries[this.index];
+    }
+    get ownsKeyboard() {
+        return this.filtering;
+    }
+    setSource(source, selectedKey) {
+        const changed = this.source?.id !== source.id;
+        this.source = source;
+        const entries = this.entries();
+        const found = selectedKey === undefined ? -1 : entries.findIndex((entry) => entry.key === selectedKey);
+        this.index = found >= 0 ? found : changed ? 0 : Math.min(this.index, Math.max(0, entries.length - 1));
+        if (changed) {
+            this.filter = "";
+            this.filtering = false;
+        }
+    }
+    setEmptyState(hasMarketplaces) {
+        this.hasMarketplaces = hasMarketplaces;
+    }
+    move(delta) {
+        const entries = this.entries();
+        if (entries.length === 0)
+            return;
+        this.index = Math.max(0, Math.min(entries.length - 1, this.index + delta));
+        this.onChange();
+    }
+    /** Returns true only when a live filter consumed the input. */
+    handleInput(data) {
+        if (this.filtering) {
+            if (matchesKey(data, "escape")) {
+                this.filter = "";
+                this.filtering = false;
+            }
+            else if (matchesKey(data, "enter")) {
+                // Enter leaves entry mode but deliberately keeps the narrowed list.
+                this.filtering = false;
+            }
+            else if (matchesKey(data, "backspace")) {
+                this.filter = this.filter.slice(0, -1);
+                this.index = 0;
+            }
+            else if (data.length === 1 && data.charCodeAt(0) >= 32) {
+                this.filter += data;
+                this.index = 0;
+            }
+            this.onChange();
+            return true;
+        }
+        if (data === "/" || matchesKey(data, "/")) {
+            this.filtering = true;
+            this.onChange();
+            return true;
+        }
+        // Escape has a useful local meaning only while a committed filter remains.
+        if (matchesKey(data, "escape") && this.filter !== "") {
+            this.filter = "";
+            this.index = 0;
+            this.onChange();
+            return true;
+        }
+        return false;
+    }
+    setNotice(notice) {
+        this.notice = notice;
+    }
+    entries() {
+        const entries = this.source?.entries ?? [];
+        const needle = this.filter.trim().toLowerCase();
+        if (needle === "")
+            return entries;
+        return entries.filter((entry) => [entry.name, entry.description ?? "", ...entry.keywords]
+            .join("\n")
+            .toLowerCase()
+            .includes(needle));
+    }
+    render(width, height, focused) {
+        const out = [];
+        const source = this.source;
+        const entries = this.entries();
+        const sourceLabel = source?.kind === "installed" ? "Installed" : source?.label ?? "Library";
+        const filterLabel = this.filtering
+            ? ` /${this.filter} · ${plural(entries.length, "match", "matches")}`
+            : this.filter === ""
+                ? ` ${plural(entries.length, "plugin", "plugins")}`
+                : ` ${plural(entries.length, "match", "matches")} · esc clears`;
+        // A marketplace name can be wider than this whole column, so the source
+        // label yields first: how many rows matched and how to get back out are
+        // what a filtering user needs, and truncating the pair together drops
+        // exactly that half off the end.
+        const labelRoom = Math.max(3, width - visibleWidth(filterLabel));
+        out.push(truncateToWidth(`${theme.fg("accent", theme.bold(truncateToWidth(sourceLabel, labelRoom)))}${theme.fg("dim", filterLabel)}`, width));
+        if (this.notice !== undefined) {
+            out.push(truncateToWidth(theme.fg("warning", `! ${this.notice}`), width));
+        }
+        if (entries.length === 0) {
+            out.push("");
+            const firstRun = source?.kind === "installed" && !this.hasMarketplaces;
+            if (firstRun) {
+                out.push(truncateToWidth(theme.fg("accent", "No marketplaces yet."), width));
+                out.push(truncateToWidth(theme.fg("dim", "Press a to add a marketplace."), width));
+            }
+            else {
+                out.push(truncateToWidth(theme.fg("dim", "No plugins installed yet."), width));
+                out.push(truncateToWidth(theme.fg("dim", "Press tab to browse marketplaces."), width));
+            }
+            return this.fit(out, height);
+        }
+        const available = Math.max(1, height - out.length);
+        const range = visibleRange(entries.length, this.index, available);
+        for (let position = range.start; position < range.end; position += 1) {
+            const entry = entries[position];
+            const selected = position === this.index;
+            const glyph = this.stateGlyph(entry);
+            const version = displayVersion(entry);
+            const prefix = `${glyph} ${entry.name}`;
+            const suffix = version === undefined ? "" : ` ${version}`;
+            const fixed = visibleWidth(prefix) + visibleWidth(suffix);
+            const descriptionWidth = width - fixed - 2;
+            const description = descriptionWidth >= 12 && entry.description
+                ? theme.fg("dim", `  ${truncateToWidth(entry.description, descriptionWidth)}`)
+                : "";
+            const row = truncateToWidth(`${prefix}${suffix}${description}`, width);
+            out.push(selected && focused
+                ? theme.bg("selectedBg", padAnsi(row, width))
+                : selected
+                    ? `${theme.fg("accent", "▌")}${truncateToWidth(theme.fg("accent", row), Math.max(0, width - 1))}`
+                    : row);
+        }
+        return this.fit(out, height);
+    }
+    /** Pad rather than trim: this column sets the length of the divider drawn
+     *  beside it, and a divider that stops where the content runs out makes the
+     *  page look half-drawn. */
+    fit(lines, height) {
+        while (lines.length < height)
+            lines.push("");
+        return lines.slice(0, height);
+    }
+    stateGlyph(entry) {
+        if (entry.install.kind === "absent")
+            return " ";
+        if (entry.install.scope === "builtin")
+            return theme.fg("muted", "⌂");
+        if (entry.install.enabled) {
+            return entry.install.updateAvailable ? theme.fg("warning", "↑") : theme.fg("success", "✓");
+        }
+        return theme.fg("dim", "○");
+    }
+}

package/dist/commands/pkg/browse/model.d.ts

@@ -0,0 +1,223 @@
+import type { Field, InputParam } from '../../../core/help.js';
+import type { RuleSpec } from '../../../core/graph/types.js';
+import type { OwnerRef, Scope } from '../../../types.js';
+/** The scopes that can hold a marketplace, and that a plugin can be installed
+ *  into. Narrower than `Scope`: `builtin` names plugins that ship with crtr, and
+ *  `listAllMarketplaces()` never yields it, so a builtin marketplace or a
+ *  builtin install target is not a state this surface can reach. */
+export type WritableScope = Exclude<Scope, "builtin">;
+/** Rail row identity: `installed`, or `market:<scope>:<name>`.
+ *
+ *  A marketplace id carries its scope because the same name can be registered
+ *  in both the user and the project scope. Collapsing those to one id makes two
+ *  distinct marketplaces share a row, and an action on it reach whichever one
+ *  the leaf's unscoped lookup resolves first — including a destructive one. */
+export type SourceId = string;
+export declare const INSTALLED_SOURCE_ID: SourceId;
+export declare function marketplaceSourceId(name: string, scope: WritableScope): SourceId;
+export type PluginInstallState = {
+    kind: "absent";
+} | {
+    kind: "installed";
+    scope: Scope;
+    enabled: boolean;
+    /** Version recorded for the installed copy, when it declares one. */
+    version?: string;
+    path: string;
+    /** The marketplace offers a version newer than the installed one. */
+    updateAvailable: boolean;
+};
+/** One command node a plugin contributes to the `crtr` tree, with the whole
+ *  contract an agent would read from `-h`. The browser renders the tree, so
+ *  children hang off their parent rather than arriving pre-flattened. */
+export interface CommandNode {
+    /** Path words from the crtr root, e.g. `['search', 'web']`. */
+    path: string[];
+    kind: "branch" | "leaf";
+    description: string;
+    /** The selection rubric — when to reach for this command. */
+    whenToUse: string;
+    summary: string;
+    tier?: "hidden" | "normal" | "common" | "important";
+    /** Empty for a leaf and for a passthrough branch. */
+    children: CommandNode[];
+    /** Branch only: forwards every argv token to an external binary instead of
+     *  parsing children. */
+    passthrough?: {
+        bin: string;
+        installHint: string;
+    };
+    /** Top-level branch only: its entry in the crtr root listing. */
+    rootEntry?: {
+        concept: string;
+        description: string;
+        whenToUse: string;
+    };
+    /** Leaf only: the exact invocation schema, straight from the manifest. */
+    params: InputParam[];
+    output: Field[];
+    effects: string[];
+    /** Leaf on an http-transport plugin only: the REST call it maps to. */
+    rest?: {
+        method: string;
+        path: string;
+        streaming: boolean;
+    };
+}
+/** `crtr exa-search web` — how a user types the command a node names. The one place
+ *  a command path becomes a label, so no corner of the page invents its own. */
+export declare function commandLabel(node: CommandNode): string;
+/** Every node in a command forest, parents before their children. */
+export declare function flattenCommands(nodes: CommandNode[]): CommandNode[];
+/** One memory doc a plugin provides — whole, because the resolver already read
+ *  the file to report the doc exists, so the body costs nothing extra.
+ *
+ *  Two fields sound alike and are not: `shortForm` is the human-facing hook —
+ *  what this doc SAYS — and is the description the page shows beside a doc's
+ *  name. `routingLine` is agent read-routing — WHEN to open it — and belongs
+ *  under the doc view's own heading, never in the description slot. */
+export interface DocDetail {
+    /** `<plugin>/<path>` — the identifier `crtr canvas read` takes. */
+    name: string;
+    kind: "knowledge" | "preference";
+    /** Frontmatter `short-form`: the abbreviated content. */
+    shortForm?: string;
+    /** Frontmatter `when-and-why-to-read`: one sentence routing a reading agent. */
+    routingLine?: string;
+    /** Absolute path to the `.md` on disk. */
+    path: string;
+    sizeBytes?: number;
+    /** Routing rules: when the doc delivers, and how much. Empty = reachable
+     *  through listings and explicit reads only. */
+    rules: RuleSpec[];
+    /** Suppressed from directory listings. */
+    unlisted: boolean;
+    /** The observed failure the doc exists to close. Maintainer-facing — never
+     *  delivered to a reading agent. */
+    rationale?: string;
+    /** Markdown body, frontmatter stripped. */
+    body: string;
+}
+/** A plugin as one list row: everything cheap enough to load for every row. */
+export interface PluginEntry {
+    /** Stable row key, unique across the whole catalog: `<sourceId>:<scope>:<name>`.
+     *  Scope participates because one name can name two different installations. */
+    key: string;
+    name: string;
+    /** What `pkg plugin install` takes: `<marketplace>/<plugin>`, else the name. */
+    ref: string;
+    sourceId: SourceId;
+    /** The marketplace offering it; absent for a plugin installed from a URL or path. */
+    marketplace?: string;
+    /** Version the marketplace offers (installed version lives in `install`). */
+    version?: string;
+    description?: string;
+    keywords: string[];
+    owner?: OwnerRef;
+    /** Upstream repo the marketplace entry points at. */
+    source?: string;
+    install: PluginInstallState;
+    /** Directory holding the plugin's files — the installed copy when there is
+     *  one, else the marketplace clone's vendored copy. Absent when neither
+     *  exists on disk, which is the only case where capability is unknowable. */
+    root?: string;
+}
+/** The version to show beside a plugin's name, anywhere in the page.
+ *
+ *  One rule, one place: the version beside a name is always the one in play on
+ *  THIS machine — what is installed, or what installing would get you. The
+ *  marketplace's offer for an already-installed plugin is a different fact, and
+ *  it appears only as the right-hand side of the update arrow in the status
+ *  line. Headline and list row both call this so they cannot disagree. */
+export declare function displayVersion(entry: PluginEntry): string | undefined;
+/** `<count> <noun>`, with the noun agreeing with the count. Every count this
+ *  page renders goes through here so no corner of it reads "1 docs". */
+export declare function plural(count: number, one: string, many: string): string;
+/** What a plugin adds to this machine — read from its directory on demand. */
+export interface PluginCapability {
+    /** Directory these facts were read from. */
+    root: string;
+    /** How crtr invokes its commands; null for a docs-only plugin. */
+    transport: "exec" | "http" | null;
+    /** Local executable (exec) or remote endpoint (http) — the trust-relevant fact. */
+    transportTarget?: string;
+    /** The command forest this plugin mounts, as a tree. */
+    commands: CommandNode[];
+    /** Static validation problems that stop a declared command from mounting. */
+    commandIssues: {
+        message: string;
+        next?: string;
+    }[];
+    docs: DocDetail[];
+    /** Total bytes on disk, when cheap to measure. */
+    sizeBytes?: number;
+}
+export interface MarketplaceDetail {
+    name: string;
+    scope: WritableScope;
+    url: string;
+    ref: string;
+    /** Absolute path to the clone. */
+    path: string;
+    owner?: OwnerRef;
+    version?: string;
+    pluginCount: number;
+    installedCount: number;
+    /** Installed plugins from this marketplace with a newer version offered. */
+    updatableCount: number;
+    /** Short sha of the clone's checked-out commit. */
+    revision?: string;
+    /** ISO date of that commit. */
+    revisionDate?: string;
+}
+export interface CatalogSource {
+    id: SourceId;
+    kind: "installed" | "marketplace";
+    label: string;
+    /** Present exactly when `kind === 'marketplace'`. */
+    marketplace?: MarketplaceDetail;
+    entries: PluginEntry[];
+}
+export interface Catalog {
+    sources: CatalogSource[];
+    /** Scopes a plugin can be installed into on this machine, in offer order. */
+    installScopes: WritableScope[];
+    /** Non-fatal problems loading the catalog — a broken clone, an unreadable
+     *  manifest. Surfaced in the page rather than thrown, so one bad marketplace
+     *  never takes the browser down. */
+    warnings: string[];
+}
+export type ActionKind = "install" | "remove" | "enable" | "disable" | "update" | "market-add" | "market-update" | "market-remove";
+export interface ActionRequest {
+    kind: ActionKind;
+    /** Required for every plugin-scoped action. */
+    entry?: PluginEntry;
+    /** Required for every marketplace-scoped action on an already-registered
+     *  marketplace (`market-update`, `market-remove`). */
+    marketplace?: string;
+    /** Git URL of the marketplace repo. Required by `market-add` only. */
+    url?: string;
+    /** Git ref the added marketplace tracks. `market-add` only; defaults to main. */
+    ref?: string;
+    /** The scope this action operates in — where `install` and `market-add` put
+     *  their result, and which of two same-named marketplaces `market-remove`
+     *  destroys. Ignored by actions that do not resolve a scope. */
+    scope?: WritableScope;
+}
+export interface ActionOutcome {
+    ok: boolean;
+    /** One line for the status row. */
+    message: string;
+    /** Extra lines for the detail pane — mounted commands, issues, git output. */
+    detail?: string[];
+}
+/** How an action presents before it runs: the progress line, and the question
+ *  to put in a confirm modal when the action destroys something. */
+export interface ActionPresentation {
+    /** Imperative label for the footer/menu, e.g. "Install into user scope". */
+    label: string;
+    /** Present-tense progress line, e.g. "Installing capture…". */
+    progress: string;
+    /** Non-empty only for destructive actions; the shell must confirm first. */
+    confirm?: string;
+}

package/dist/commands/pkg/browse/model.js

@@ -0,0 +1,36 @@
+// The read model behind `crtr pkg browse` — one shape the catalog produces, the
+// action layer consumes, and the panels render.
+//
+// The browser answers one question the flat `pkg market browse` listing cannot:
+// *what does installing this actually do to my crtr?* So an entry carries its
+// marketplace metadata (cheap, from the manifest index) separately from its
+// capability surface (commands mounted, memory docs provided, transport), which
+// costs a directory read and is resolved on demand for the focused row only.
+export const INSTALLED_SOURCE_ID = "installed";
+export function marketplaceSourceId(name, scope) {
+    return `market:${scope}:${name}`;
+}
+/** `crtr exa-search web` — how a user types the command a node names. The one place
+ *  a command path becomes a label, so no corner of the page invents its own. */
+export function commandLabel(node) {
+    return `crtr ${node.path.join(" ")}`;
+}
+/** Every node in a command forest, parents before their children. */
+export function flattenCommands(nodes) {
+    return nodes.flatMap((node) => [node, ...flattenCommands(node.children)]);
+}
+/** The version to show beside a plugin's name, anywhere in the page.
+ *
+ *  One rule, one place: the version beside a name is always the one in play on
+ *  THIS machine — what is installed, or what installing would get you. The
+ *  marketplace's offer for an already-installed plugin is a different fact, and
+ *  it appears only as the right-hand side of the update arrow in the status
+ *  line. Headline and list row both call this so they cannot disagree. */
+export function displayVersion(entry) {
+    return entry.install.kind === "installed" ? entry.install.version ?? entry.version : entry.version;
+}
+/** `<count> <noun>`, with the noun agreeing with the count. Every count this
+ *  page renders goes through here so no corner of it reads "1 docs". */
+export function plural(count, one, many) {
+    return `${count} ${count === 1 ? one : many}`;
+}

package/dist/commands/pkg/browse/shell.d.ts

@@ -0,0 +1,93 @@
+import { type Component, type Focusable, type TUI } from '@earendil-works/pi-tui';
+import { type BindingId, type BindingResolution } from '../../../core/keybindings/index.js';
+/** Full-screen plugin browser. The data and mutation boundaries stay in the
+ * catalog/actions collaborators, leaving this class responsible for movement,
+ * disclosure, and the rendered page grammar. */
+export declare class PkgBrowseShell implements Component, Focusable {
+    private readonly tui;
+    private readonly terminalRows;
+    private readonly bindings;
+    private catalog;
+    private sourceIndex;
+    private zone;
+    private readonly list;
+    private readonly detail;
+    private readonly capabilities;
+    private modal;
+    private busy;
+    private notice;
+    private _focused;
+    onCancel?: () => void;
+    constructor(tui: TUI, terminalRows: () => number, bindings: BindingResolution<BindingId>);
+    /** The page follows the user's own `crtr.setup.*` navigation gestures, the
+     *  same ones `crtr sys settings` resolves, alongside its literal defaults —
+     *  a remap must not leave one full-screen page moving and the other stuck. */
+    private matches;
+    /** The footer names keys, so it names the gestures actually bound. */
+    private label;
+    private isDown;
+    private isUp;
+    /** Move one zone to the right, or open the focused row. */
+    private isDescend;
+    /** Move one zone to the left. Escape is deliberately separate: in the dossier
+     *  it pops the whole view stack where `h` folds one branch. */
+    private isAscend;
+    /** Tab cycles rail sources from anywhere. The resolved `tab-next` gesture
+     *  also carries the horizontal arrows, which mean "into the panel" here, so
+     *  those are excluded exactly as the settings shell excludes them. */
+    private cyclesSource;
+    set focused(value: boolean);
+    get focused(): boolean;
+    /** Required by pi-tui's `Component`, and deliberately a no-op: this page
+     *  holds no render cache to drop. Every panel is recomputed each frame
+     *  because capability reads and action results land between input events. */
+    invalidate(): void;
+    dispose(): void;
+    private sources;
+    private get source();
+    private syncSource;
+    private syncDetail;
+    private reload;
+    private goSource;
+    private moveList;
+    private clearActionNotice;
+    /** A live filter, an open modal, or a running action holds every key — the
+     *  one predicate both `handleInput` and the footer consult, so the footer can
+     *  never advertise a key the filter is swallowing. */
+    private panelOwnsKeyboard;
+    handleInput(data: string): void;
+    private enterRail;
+    private enterList;
+    private enterDetail;
+    private jumpToInitial;
+    /** The focused rail row as an action subject. Carries the marketplace's scope
+     *  as well as its name: two marketplaces can share a name across the user and
+     *  project scopes, and without the scope `availableActions` cannot tell which
+     *  one a remove would destroy, so it offers nothing at all. */
+    private marketplaceSubject;
+    private triggerAction;
+    private openAdd;
+    private handleModal;
+    private submitAdd;
+    /** Where `a` registers a marketplace. Named once so the modal can state
+     *  exactly what the action will do. */
+    private addScope;
+    private execute;
+    private beginBusy;
+    private finishAction;
+    /** The source rail. It scrolls like the list does: marketplace count is user
+     *  controlled, so a fixed slice would let the selection sit below the last
+     *  drawn row, moving invisibly while the badge the user is aiming for never
+     *  appears. Group headings scroll with their group. */
+    private renderRail;
+    private renderPanel;
+    private renderModal;
+    private wrapModal;
+    private footer;
+    /** The footer names KEYS, not actions. An absent plugin offers a user-scope
+     *  and a project-scope install — two actions behind one `i`, which the scope
+     *  modal then chooses between — so the hints are deduped before joining. */
+    private availableActionHints;
+    render(width: number): string[];
+}
+export declare function runPkgBrowse(): Promise<void>;