@dev-sergeev/datalab-kit 0.1.1 → 0.1.3

package/node_modules/@zigai/pi-mention-anything/docs/providers.md

@@ -0,0 +1,128 @@
+# Mention providers
+
+Providers supply candidates and resolve targets. The shared engine handles pickers, caching, selection history, and context expansion.
+
+```ts
+import { createListProvider, registerMention } from "@zigai/pi-mention-anything/api";
+
+registerMention(pi, {
+  id: "environments",
+  configuration: () => ({ trigger: "env:", cache: true }),
+  provider: () =>
+    createListProvider(async () => [
+      {
+        id: "staging",
+        label: "Staging",
+        segment: "staging",
+        selectable: true,
+        navigable: false,
+        replacement: "deployment environment staging",
+      },
+    ]),
+});
+```
+
+## Candidates
+
+| Field           | Meaning                                            |
+| --------------- | -------------------------------------------------- |
+| `id`            | Stable identity within the source and parent path  |
+| `label`         | Picker label                                       |
+| `segment`       | Text inserted into the mention path                |
+| `selectable`    | Can be selected as a completed target              |
+| `navigable`     | Has a child picker                                 |
+| `description`   | Optional secondary picker text                     |
+| `searchText`    | Optional search text                               |
+| `data`          | Optional JSON data passed to child requests        |
+| `replacement`   | Optional text sent to the model                    |
+| `insertionText` | Optional replacement for the entire editor mention |
+
+Duplicate IDs within a response are invalid. Labels and segments can repeat; manually typed ambiguous segments remain unresolved. Picker selections retain the chosen ID. Provider data is separate from model context.
+
+## Chains
+
+`separator` enables chained selections. Branches open child pickers; leaves complete the mention with `completionSuffix`, which defaults to one space. Selectable branches also have a **Use this target** row.
+
+Segments support independent quoting and escaping. Changing a parent removes its descendants when a new candidate is selected. Escape closes the popup and leaves the text intact.
+
+## Provider interface
+
+| Member              | Contract                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------ |
+| `filtering`         | `local` for engine fuzzy matching; `provider` for source-owned search and ranking          |
+| `discover(request)` | Returns `{ items, nextCursor? }`                                                           |
+| `resolve(request)`  | Returns `{ status: "resolved", path, replacement? }` or `{ status: "unresolved", reason }` |
+| `dispose()`         | Optional cleanup, synchronous or asynchronous; awaited once at disposal                    |
+
+Discovery requests contain `sourceId`, `cwd`, `trusted`, `query`, resolved ancestor `path`, `limit`, optional `cursor`, and `signal`. Resolution requests contain the same scope, `segments`, and `signal`. The signal covers cancellable provider I/O.
+
+Exact resolution is independent of discovery pages. A parent can resolve for navigation without being selectable. Only selectable targets expand into context.
+
+Local results use fuzzy matching and selection history. Provider-ranked results retain their order. **More…** loads the next page without changing the mention.
+
+`createListProvider` adapts small enumerable lists and trees. It resolves each level by an unambiguous segment match. Larger sources can provide direct lookup through `resolve`.
+
+## Expansion
+
+| Policy                           | Behavior                                               |
+| -------------------------------- | ------------------------------------------------------ |
+| `selected-or-resolved` (default) | Picker selections and resolvable typed mentions expand |
+| `selected-only`                  | Only picker selections expand                          |
+
+Incomplete and unresolved mentions remain literal. Selected targets retain their identity through refreshes. A whole chain expands once; replacement text is not interpreted as further mentions. Resolved submissions remain stable across retries and context rebuilds.
+
+Replacement precedence:
+
+1. Registration callback: `replacement(path, ctx, { signal })`
+2. `replacementTemplate`
+3. Exact-resolution replacement
+4. Candidate replacement
+5. Segment text
+
+Templates accept `{{id}}`, `{{label}}`, `{{segment}}`, `{{path}}`, and `{{ids}}`. Unknown fields are invalid. Templates substitute these fields only, without evaluating code or traversing provider data.
+
+## Cache options
+
+These options belong to the API's `configuration` result or a settings command source.
+
+| Option                                                    | Default                              | Behavior                                                        |
+| --------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `cache`                                                   | `false`                              | Reuse of successful discovery results                           |
+| `cacheTtlMs`                                              | None                                 | Cache lifetime; expired results remain available during refresh |
+| `refreshOnStartup`                                        | `false`                              | Background root discovery at startup; requires caching          |
+| `refreshIntervalMs`                                       | None                                 | Periodic refresh of active entries; requires caching            |
+| `watchFiles`                                              | None                                 | File changes invalidate cached results; requires caching        |
+| `persistentCachePath` (API), `persistentCache` (settings) | None / `false`                       | Local disk cache scoped by configuration, cwd, and trust        |
+| `debounceMs`                                              | `0` (API), `100` (settings commands) | Delay before discovery starts                                   |
+| `maxEntries` (API)                                        | `64`                                 | Retained cache scopes                                           |
+| `maxConcurrent` (API)                                     | `4`                                  | Concurrent requests per source                                  |
+
+Cache entries distinguish parent IDs, provider-owned queries, and page cursors. Equivalent requests share work. Cancelling one caller leaves other callers active. Failed refreshes preserve the previous results, including empty lists. Disposal cancels work and closes timers and watchers.
+
+Persistent API caches require a `configurationKey` that changes with the source configuration. Settings sources calculate this key automatically.
+
+## Limits
+
+| Resource                      | Limit                                             |
+| ----------------------------- | ------------------------------------------------- |
+| Provider-ranked page          | 100 candidates                                    |
+| Local response                | 10,000 candidates; searched before display limits |
+| Picker paging scope           | 10 pages / 1,000 candidates                       |
+| Retained paging scopes        | 32                                                |
+| Selected branch continuations | 64                                                |
+| Path                          | 64 segments                                       |
+| Candidate ID                  | 4,096 characters                                  |
+| Display/search field          | 16,384 characters                                 |
+| Literal replacement           | 1 MiB                                             |
+| Persistent cache file         | 8 MiB                                             |
+
+## Examples
+
+- [Static values](../examples/static.ts)
+- [Declarative tree settings](../examples/tree-settings.json)
+- [Recursive tree](../examples/recursive-tree.ts)
+- [tmux sessions, windows, and panes](../examples/tmux.ts)
+- [Query and pagination command](../examples/query-command.mjs)
+- [Command protocol](command-protocol.md)
+
+TypeScript examples run with `pi -e ./example.ts`.

package/node_modules/@zigai/pi-mention-anything/examples/query-command.mjs

@@ -0,0 +1,96 @@
+// Version 1 protocol example. Read one JSON request on stdin.
+// Search one million synthetic tickets using numeric prefix ranges, without enumerating the list.
+import { readFileSync, writeFileSync } from "node:fs";
+
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+const requestSchema = Type.Union([
+    Type.Object({
+        version: Type.Literal(1),
+        method: Type.Literal("discover"),
+        sourceId: Type.String(),
+        cwd: Type.String(),
+        trusted: Type.Boolean(),
+        query: Type.String(),
+        path: Type.Array(Type.Unknown()),
+        limit: Type.Number(),
+        cursor: Type.Optional(Type.String()),
+    }),
+    Type.Object({
+        version: Type.Literal(1),
+        method: Type.Literal("resolve"),
+        sourceId: Type.String(),
+        cwd: Type.String(),
+        trusted: Type.Boolean(),
+        segments: Type.Array(Type.String()),
+    }),
+]);
+
+const input = readFileSync(0, "utf8");
+const request = Value.Parse(requestSchema, JSON.parse(input));
+
+/** @param {number} id */
+function ticket(id) {
+    return {
+        id: String(id),
+        label: `Ticket ${id}`,
+        segment: String(id),
+        selectable: true,
+        navigable: false,
+        replacement: `issue tracker ticket #${id}`,
+    };
+}
+
+/** @type {unknown} */
+let result;
+if (request.method === "resolve") {
+    let value = "";
+    if (request.segments.length === 1) value = request.segments[0] ?? "";
+
+    const id = Number(value);
+    if (/^[1-9]\d*$/.test(value) && id <= 1000000) {
+        result = { status: "resolved", path: [ticket(id)] };
+    } else {
+        result = { status: "unresolved", reason: "missing" };
+    }
+} else {
+    const cursor = Number(request.cursor ?? "1");
+    const query = request.query.replace(/^Ticket\s+/i, "");
+
+    /** @type {Array<[number, number]>} */
+    const ranges = [];
+    if (query === "") ranges.push([1, 1000000]);
+    else if (/^[1-9]\d*$/.test(query)) {
+        for (let scale = 1; Number(query) * scale <= 1000000; scale *= 10) {
+            ranges.push([
+                Number(query) * scale,
+                Math.min((Number(query) + 1) * scale - 1, 1000000),
+            ]);
+        }
+    }
+
+    const limit = Math.min(request.limit, 100);
+
+    /** @type {Array<ReturnType<typeof ticket>>} */
+    const items = [];
+    let nextCursor;
+    for (const [start, end] of ranges) {
+        for (let id = Math.max(start, cursor); id <= end; id += 1) {
+            if (items.length === limit) {
+                nextCursor = String(id);
+                break;
+            }
+
+            items.push(ticket(id));
+        }
+
+        if (nextCursor !== undefined) break;
+    }
+
+    const discovery = { items };
+    if (nextCursor !== undefined) Object.assign(discovery, { nextCursor });
+    result = discovery;
+}
+
+writeFileSync(1, JSON.stringify({ version: 1, method: request.method, result }), "utf8");

package/node_modules/@zigai/pi-mention-anything/examples/recursive-tree.ts

@@ -0,0 +1,28 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+    createListProvider,
+    registerMention,
+    type Candidate,
+} from "@zigai/pi-mention-anything/api";
+
+/** A synthetic recursive tree: every branch can be selected or explored another level. */
+export default function (pi: ExtensionAPI): void {
+    registerMention(pi, {
+        id: "tree",
+        configuration: () => ({ trigger: "tree:", separator: ":", cache: true }),
+        provider: () =>
+            createListProvider(async (request) => {
+                const parent = request.path.map((item) => item.id).join("/");
+                const candidates: Candidate[] = ["left", "right"].map((segment) => ({
+                    id: `${parent}/${segment}`,
+                    label: segment,
+                    segment,
+                    selectable: true,
+                    navigable: true,
+                    replacement: `tree node ${parent}/${segment}`,
+                }));
+
+                return candidates;
+            }),
+    });
+}

package/node_modules/@zigai/pi-mention-anything/examples/static.ts

@@ -0,0 +1,28 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createListProvider, registerMention } from "@zigai/pi-mention-anything/api";
+
+export default function (pi: ExtensionAPI): void {
+    registerMention(pi, {
+        id: "environments",
+        configuration: () => ({ trigger: "env:", cache: true }),
+        provider: () =>
+            createListProvider(async () => [
+                {
+                    id: "staging",
+                    label: "Staging",
+                    segment: "staging",
+                    selectable: true,
+                    navigable: false,
+                    replacement: "deployment environment staging",
+                },
+                {
+                    id: "production",
+                    label: "Production",
+                    segment: "production",
+                    selectable: true,
+                    navigable: false,
+                    replacement: "deployment environment production",
+                },
+            ]),
+    });
+}

package/node_modules/@zigai/pi-mention-anything/examples/tmux.ts

@@ -0,0 +1,90 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { execFile } from "node:child_process";
+import {
+    createListProvider,
+    registerMention,
+    type Candidate,
+} from "@zigai/pi-mention-anything/api";
+
+export default function (pi: ExtensionAPI): void {
+    registerMention(pi, {
+        id: "tmux",
+        configuration: () => ({ trigger: "t:", separator: ":", cache: true, cacheTtlMs: 5000 }),
+        provider: (ctx) =>
+            createListProvider(async (request) => {
+                const parent = request.path.at(-1);
+                const level = request.path.length;
+                if (level > 2) return [];
+
+                let args: string[];
+                if (level === 0) args = ["list-sessions", "-F", "#{session_id}\t#{session_name}"];
+                else if (level === 1 && parent !== undefined)
+                    args = ["list-windows", "-t", parent.id, "-F", "#{window_id}\t#{window_name}"];
+                else if (parent !== undefined)
+                    args = [
+                        "list-panes",
+                        "-t",
+                        parent.id,
+                        "-F",
+                        "#{pane_id}\t#{pane_index}\t#{pane_current_command}",
+                    ];
+                else return [];
+
+                const stdout = await new Promise<string>((resolve, reject) => {
+                    execFile(
+                        "tmux",
+                        args,
+                        {
+                            cwd: ctx.cwd,
+                            signal: request.signal,
+                            timeout: 5000,
+                            maxBuffer: 1048576,
+                        },
+                        (cause, output) => {
+                            if (cause instanceof Error) reject(cause);
+                            else if (cause !== null)
+                                reject(new Error("tmux listing failed.", { cause }));
+                            else resolve(output);
+                        },
+                    );
+                });
+
+                return stdout
+                    .trim()
+                    .split("\n")
+                    .filter(Boolean)
+                    .map((line): Candidate => {
+                        const columns = line.split("\t");
+                        const id = columns.at(0);
+                        const segment = columns.at(1);
+                        const command = columns.at(2);
+
+                        if (
+                            id === undefined ||
+                            id.length === 0 ||
+                            segment === undefined ||
+                            segment.length === 0
+                        )
+                            throw new Error("Invalid tmux listing.");
+
+                        let description = id;
+                        if (command !== undefined) description = `${id} ${command}`;
+
+                        const candidate: Candidate = {
+                            id,
+                            label: segment,
+                            segment,
+                            description,
+                            selectable: level === 2,
+                            navigable: level < 2,
+                        };
+                        if (level !== 2) return candidate;
+
+                        return {
+                            ...candidate,
+                            replacement: `tmux pane ${id} in session ${request.path[0]?.segment}, window ${parent?.segment} (window ID ${parent?.id})`,
+                        };
+                    });
+            }),
+    });
+}

package/node_modules/@zigai/pi-mention-anything/examples/tree-settings.json

@@ -0,0 +1,25 @@
+{
+  "mentions": [
+    {
+      "id": "targets",
+      "trigger": "target:",
+      "separator": ":",
+      "replacementTemplate": "Selected target {{id}} at {{path}}",
+      "source": {
+        "type": "static",
+        "items": [
+          { "id": "team-1", "name": "platform", "navigable": true },
+          {
+            "id": "service-1",
+            "name": "api",
+            "parentPath": ["team-1"],
+            "navigable": true,
+            "selectable": true
+          },
+          { "id": "env-1", "name": "staging", "parentPath": ["team-1", "service-1"] },
+          { "id": "env-2", "name": "production", "parentPath": ["team-1", "service-1"] }
+        ]
+      }
+    }
+  ]
+}

package/node_modules/@zigai/pi-mention-anything/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@zigai/pi-mention-anything",
+  "version": "0.1.4",
+  "description": "Define arbitrary mention sources and triggers for Pi.",
+  "keywords": [
+    "autocomplete",
+    "custom",
+    "mention",
+    "pi-extension",
+    "pi-package"
+  ],
+  "homepage": "https://github.com/zigai/pi-tweaks/tree/main/packages/pi-mention-anything#readme",
+  "bugs": {
+    "url": "https://github.com/zigai/pi-tweaks/issues"
+  },
+  "license": "MIT",
+  "author": "zigai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zigai/pi-tweaks.git",
+    "directory": "packages/pi-mention-anything"
+  },
+  "files": [
+    "src",
+    "docs",
+    "examples",
+    "config.schema.json",
+    "README.md"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./api": "./src/api.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zigai/pi-extension-internals": "0.1.5",
+    "@zigai/pi-extension-settings": "0.5.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "piExtensionSettings": {
+    "definition": "./src/settings-input.ts",
+    "schema": "./config.schema.json",
+    "readme": "./README.md",
+    "prevalidation": "./src/settings.prevalidated.ts"
+  }
+}

package/node_modules/@zigai/pi-mention-anything/src/api.ts

@@ -0,0 +1,75 @@
+export {
+    createMentionAutocompleteProvider,
+    type MentionAutocompleteOptions,
+} from "./autocomplete.ts";
+export {
+    applyMentionEditor,
+    type MentionEditorContext,
+    type MentionEditorOptions,
+} from "./editor.ts";
+export {
+    contextContainsMentionTrigger,
+    expandMentions,
+    expandMentionsInMessages,
+    type MentionExpansionOptions,
+} from "./expand-mentions.ts";
+export {
+    createLazySelectionHistory,
+    rankInitialSuggestions,
+    rankWithSelectionHistory,
+    type InitialSuggestions,
+    type InitialSuggestionStrategy,
+    type Selection,
+    type SelectionHistory,
+    type SelectionHistoryOptions,
+} from "./initial-suggestions.ts";
+export {
+    autocompleteTriggerCharacter,
+    escapeRegExp,
+    extractMentionPrefix,
+    formatMention,
+    isMentionContext,
+    mentionPattern,
+    parseMentionName,
+    type MentionPrefix,
+    type ParsedMention,
+} from "./mention-syntax.ts";
+export {
+    registerMention,
+    type MentionConfiguration,
+    type MentionContext,
+    type MentionExtensionApi,
+    type MentionRegistration,
+} from "./register-mention.ts";
+export { createListProvider } from "./list-provider.ts";
+export {
+    createSourceController,
+    type SourceController,
+    type SourceControllerOptions,
+} from "./source-controller.ts";
+export {
+    createCommandProvider,
+    type CommandRequestV1,
+    type CommandResponseV1,
+} from "./command-provider.ts";
+export { parseMentions, formatChain } from "./chain-syntax.ts";
+export {
+    createChainAutocompleteProvider,
+    type ChainCompletionSource,
+} from "./chain-autocomplete.ts";
+export {
+    expandMentionText,
+    renderReplacementTemplate,
+    type ExpansionSource,
+} from "./mention-resolution.ts";
+export type {
+    Candidate,
+    DiscoveryRequest,
+    DiscoveryResponse,
+    JsonValue,
+    Provider,
+    Resolution,
+    ResolveRequest,
+} from "./source-contract.ts";
+export { autocompleteStartIndex, colorMentions, type MentionColorContext } from "./rendering.ts";
+export { createSelectionHistory } from "./selection-history.ts";