@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/toolbox.d.ts

@@ -0,0 +1,240 @@
+import { ExternalTool, ToolboxScope, ToolboxList } from '@serviceme/devtools-protocol';
+
+/**
+ * toolbox sort + dedup — pure helpers, no I/O.
+ *
+ * The Extension's `ToolBoxService` keeps a stable `order` index and
+ * surfaces "recently used" via the `lastUsedAt` ISO timestamp. These
+ * helpers codify that algorithm so the CLI and Extension agree on the
+ * "最近使用置顶" UX.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.3 — `sort.ts 排序与去重纯函数`
+ */
+
+/**
+ * Sort by "recently used" — entries with newer `lastUsedAt` float to
+ * the top, entries with no `lastUsedAt` sort to the bottom (preserving
+ * their relative `order` index when both are absent).
+ *
+ * Ties (same `lastUsedAt` or both missing) are broken by `order`, then
+ * by `id` for determinism.
+ */
+declare function sortByRecentFirst(tools: readonly ExternalTool[]): ExternalTool[];
+/**
+ * Sort by user-defined `order` field. Entries without `order` are
+ * appended in their input order (stable sort via `id` tiebreaker).
+ */
+declare function sortByUserOrder(tools: readonly ExternalTool[]): ExternalTool[];
+/**
+ * Merge built-in defaults with user-stored tools. Defaults keep
+ * `isDefault: true` and their `order`; user tools are appended with
+ * their stored metadata. Output is sorted by user order.
+ */
+declare function mergeWithDefaults(defaults: readonly ExternalTool[], userTools: readonly ExternalTool[]): ExternalTool[];
+/**
+ * Re-number `order` for a list of tool ids. Used by
+ * `toolbox.update` when the user drags-and-drops entries in the UI.
+ */
+declare function reindexOrder(tools: ExternalTool[], newOrderIds: readonly string[]): ExternalTool[];
+/**
+ * Stamp `lastUsedAt` on the targeted tool (clones the array). Returns
+ * a new array; the input is left untouched.
+ */
+declare function touchLastUsedAt(tools: readonly ExternalTool[], id: string, when?: Date): ExternalTool[];
+
+/**
+ * toolbox types — internal-only data shapes.
+ *
+ * The public data model lives in `@serviceme/devtools-protocol/toolbox`
+ * (`ExternalTool`, `ToolboxScope`, `ToolboxList`). The types below are
+ * the persisted on-disk shape and the patch helpers, scoped to the
+ * toolbox domain only.
+ *
+ * Refs:
+ * - 4.功能规划.md §2.3 — `toolbox/types.ts`
+ */
+
+/** Schema version of the on-disk toolbox JSON files. Bumped on breaking changes. */
+declare const TOOLBOX_JSON_SCHEMA_VERSION = 1;
+interface PersistedToolbox {
+    version: number;
+    tools: ExternalTool[];
+}
+/** Patch payload accepted by `ToolboxCore.update` (mirrors `ExternalToolPatch`). */
+type ToolboxPatch = Partial<Omit<ExternalTool, "id" | "isDefault">>;
+/**
+ * Built-in (default) tool seeds. Mirrors the Extension's
+ * `apps/extension/src/config/external-tools.ts`. The Core stores these
+ * verbatim and never mutates them — the Extension's `ToolBoxService`
+ * runs the same merge on top of the Core's view.
+ */
+interface DefaultToolSeed {
+    id: string;
+    name: string;
+    description: string;
+    icon: string;
+    url: string;
+}
+/** Built-in tools rendered when the JSON file is missing or empty. */
+declare const BUILTIN_DEFAULT_TOOLS: readonly DefaultToolSeed[];
+/** Resolved toolbox shape returned by `ToolboxStore.read()`. */
+interface ResolvedToolbox {
+    scope: ToolboxScope;
+    tools: ExternalTool[];
+}
+
+/**
+ * ToolboxStore — JSON persistence for the toolbox entries.
+ *
+ * Two scopes:
+ *   - `user`      → `~/.serviceme/toolbox.json`
+ *   - `workspace` → `<cwd>/.github/.serviceme-toolbox.json`
+ *
+ * Both files share the `PersistedToolbox` shape and the same atomic
+ * write pattern (tmp + rename + fsync) as `IdentityStore`. Concurrent
+ * writers are serialized via a mkdir-based file lock (Phase 6+ may
+ * upgrade to `proper-lockfile`).
+ *
+ * Refs:
+ * - 4.功能规划.md §2.3 — `ToolboxStore.ts JSON 持久化(user + workspace scope)`
+ * - `3.功能拆分.md` §3 — toolbox wire shape
+ */
+
+declare const WORKSPACE_TOOLBOX_RELATIVE_PATH: string;
+interface ToolboxFileBackend {
+    read(filePath: string): Promise<PersistedToolbox | null>;
+    write(filePath: string, payload: PersistedToolbox): Promise<void>;
+    exists(filePath: string): Promise<boolean>;
+}
+interface ToolboxStoreOptions {
+    /** Override the user-scope file path (default: `getToolboxJsonPath()`). */
+    userFilePath?: string;
+    /** Override the workspace-scope file path resolver (default: cwd-relative). */
+    resolveWorkspacePath?: () => string | null;
+    /** Injectable built-in tool seeds (default: `BUILTIN_DEFAULT_TOOLS`). */
+    defaultTools?: readonly DefaultToolSeed[];
+    hooks?: ToolboxStoreHooks;
+    backend?: ToolboxFileBackend;
+    lockTimeoutMs?: number;
+    lockRetryMs?: number;
+}
+interface ToolboxStoreHooks {
+    beforeWrite?: (scope: ToolboxScope, payload: PersistedToolbox) => void | Promise<void>;
+    afterWrite?: (scope: ToolboxScope, payload: PersistedToolbox) => void | Promise<void>;
+}
+declare class FsToolboxFileBackend implements ToolboxFileBackend {
+    exists(filePath: string): Promise<boolean>;
+    read(filePath: string): Promise<PersistedToolbox | null>;
+    private backupCorruptedFile;
+    write(filePath: string, payload: PersistedToolbox): Promise<void>;
+}
+declare class ToolboxStore {
+    private readonly userFilePath;
+    private readonly resolveWorkspacePath;
+    private readonly defaults;
+    private readonly hooks;
+    private readonly backend;
+    private readonly lockTimeoutMs;
+    private readonly lockRetryMs;
+    constructor(opts?: ToolboxStoreOptions);
+    /** Read a scope; returns the resolved toolbox (with defaults merged when empty). */
+    read(scope: ToolboxScope): Promise<ResolvedToolbox>;
+    /**
+     * Atomic write under a file lock. Replaces the entire `tools` array
+     * with the provided snapshot.
+     */
+    write(scope: ToolboxScope, tools: readonly ExternalTool[]): Promise<void>;
+    /**
+     * Read-modify-write under the file lock. The mutator receives the
+     * current user-only list (defaults not included) and returns the
+     * replacement list. Throwing inside the mutator aborts the write.
+     */
+    mutate(scope: ToolboxScope, mutator: (current: ExternalTool[]) => Promise<ExternalTool[]>): Promise<ExternalTool[]>;
+    /** Wipe a scope entirely (used by `toolbox.remove --all` extensions). */
+    clear(scope: ToolboxScope): Promise<void>;
+    /** Test seam — resolve the user-scope file path. */
+    getUserFilePath(): string;
+    /** Test seam — resolve the workspace-scope file path (or null when disabled). */
+    getWorkspaceFilePath(): string | null;
+    private filePathFor;
+}
+
+/**
+ * ToolboxCore — Main entry for the toolbox domain.
+ *
+ * Orchestrates the user + workspace scopes via `ToolboxStore`, applies
+ * the "最近使用置顶" sort, and exposes a small surface that mirrors
+ * the Phase 5.1 bridge methods:
+ *
+ *   - `list(scope?)`     → `toolbox.list`
+ *   - `add(tool, scope)` → `toolbox.add`
+ *   - `remove(id, scope?)` → `toolbox.remove`
+ *   - `update(id, patch, scope?)` → `toolbox.update`
+ *
+ * Default tools (built-in seeds) are never user-deletable. `remove()`
+ * is a no-op for default tools and surfaces a structured error so
+ * callers can map it to `TOOLBOX_DEFAULT_IMMUTABLE` (Phase 5.3 error
+ * code).
+ *
+ * Refs:
+ * - 4.功能规划.md §2.3 — `ToolboxCore.ts 主入口`
+ * - `3.功能拆分.md` §3 — wire shape
+ */
+
+/** Sentinel — caller tried to remove a built-in (immutable) tool. */
+declare class DefaultToolImmutableError extends Error {
+    readonly toolId: string;
+    constructor(toolId: string);
+}
+interface ToolboxCoreOptions {
+    store?: ToolboxStore;
+    defaultTools?: readonly DefaultToolSeed[];
+    /** Sort applied to the merged list returned by `list()`. Default: `sortByUserOrder`. */
+    listSort?: (tools: readonly ExternalTool[]) => ExternalTool[];
+}
+declare class ToolboxCore {
+    private readonly store;
+    private readonly defaults;
+    private readonly listSort;
+    constructor(opts?: ToolboxCoreOptions);
+    /** List all tools in a scope. Built-in defaults are merged in. */
+    list(scope?: ToolboxScope): Promise<ToolboxList>;
+    /**
+     * Append a new tool to the requested scope. Default tools are
+     * rejected (they are seeds, not user entries).
+     */
+    add(tool: ExternalTool, scope?: ToolboxScope): Promise<ToolboxList>;
+    /**
+     * Remove a tool by id. Returns `success: false` when the id is a
+     * built-in default (idempotent, never throws on missing entries).
+     */
+    remove(id: string, scope?: ToolboxScope): Promise<{
+        scope: ToolboxScope;
+        toolId: string;
+        success: boolean;
+    }>;
+    /**
+     * Patch a tool by id. Default tools can only have their `order`
+     * updated; other patches are silently ignored for default entries
+     * (callers can compare before/after to detect the ignore).
+     */
+    update(id: string, patch: ToolboxPatch, scope?: ToolboxScope): Promise<ToolboxList>;
+    /**
+     * Stamp `lastUsedAt` on the targeted tool. This is the "recently
+     * used" hook the Extension's webview uses when a user clicks a
+     * toolbox entry.
+     */
+    recordUsage(id: string, scope?: ToolboxScope, when?: Date): Promise<ExternalTool | null>;
+    /**
+     * Combined view: user + workspace scopes merged, sorted by recent
+     * usage. Workspace tools overlay user tools (workspace entries win
+     * on `id` collision).
+     */
+    listMerged(): Promise<ToolboxList>;
+    /** Expose the underlying store (CLI / Bridge use it for path-level access). */
+    getStore(): ToolboxStore;
+    private isDefaultId;
+}
+
+export { BUILTIN_DEFAULT_TOOLS, DefaultToolImmutableError, type DefaultToolSeed, FsToolboxFileBackend, type PersistedToolbox, type ResolvedToolbox, TOOLBOX_JSON_SCHEMA_VERSION, ToolboxCore, type ToolboxCoreOptions, type ToolboxFileBackend, type ToolboxPatch, ToolboxStore, type ToolboxStoreHooks, type ToolboxStoreOptions, WORKSPACE_TOOLBOX_RELATIVE_PATH, mergeWithDefaults, reindexOrder, sortByRecentFirst, sortByUserOrder, touchLastUsedAt };