@serviceme/devtools-core 2.0.0 → 2.0.2

package/dist/index-DaW7IYA-.d.ts

@@ -0,0 +1,185 @@
+import { ExternalTool, ToolboxList, ToolboxScope } from "@serviceme/devtools-protocol";
+//#region src/toolbox/sort.d.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[];
+//#endregion
+//#region src/toolbox/types.d.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[];
+}
+//#endregion
+//#region src/toolbox/ToolboxStore.d.ts
+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>;
+  /** Maximum number of `.corrupted.*.bak` snapshots to keep per toolbox file (default: 5). */
+  maxBackupCount?: number;
+}
+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 {
+  maxBackupCount: number;
+  exists(filePath: string): Promise<boolean>;
+  read(filePath: string): Promise<PersistedToolbox | null>;
+  private backupCorruptedFile;
+  private purgeExcessBackups;
+  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;
+}
+//#endregion
+//#region src/toolbox/ToolboxCore.d.ts
+/** 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;
+}
+//#endregion
+export { reindexOrder as _, ToolboxFileBackend as a, touchLastUsedAt as b, ToolboxStoreOptions as c, DefaultToolSeed as d, PersistedToolbox as f, mergeWithDefaults as g, ToolboxPatch as h, FsToolboxFileBackend as i, WORKSPACE_TOOLBOX_RELATIVE_PATH as l, TOOLBOX_JSON_SCHEMA_VERSION as m, ToolboxCore as n, ToolboxStore as o, ResolvedToolbox as p, ToolboxCoreOptions as r, ToolboxStoreHooks as s, DefaultToolImmutableError as t, BUILTIN_DEFAULT_TOOLS as u, sortByRecentFirst as v, sortByUserOrder as y };
+//# sourceMappingURL=index-DaW7IYA-.d.ts.map

package/dist/index-Dp6FwWKh.d.ts

@@ -0,0 +1,331 @@
+import { r as SkillFile } from "./types-BCV3IedE.js";
+import { SpawnOptions } from "node:child_process";
+//#region src/git-client/types.d.ts
+/**
+ * Skill & Agent v2 — Client GitClient Types (M3)
+ *
+ * GitClient wraps the local `git` CLI so all commands the SERVICEME
+ * pipeline issues (clone, fetch, push, ls-remote) flow through the
+ * server's git smart-HTTP proxy instead of talking directly to GitHub.
+ *
+ * The single trick: `git` only cares about the URL we hand it as a
+ * remote. We rewrite `https://github.com/owner/repo.git` to
+ * `http://server:port/git-proxy/<id>` and `git` does the rest — the
+ * server transparently forwards + injects PATs as needed.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §5.4 GitClient
+ */
+/** Result of a `git fetch` (called via the proxy's git-upload-pack). */
+interface PullResult {
+  /** Whether new commits were fetched (false = already up-to-date). */
+  updated: boolean;
+  /** Commit SHA at FETCH_HEAD after the pull. */
+  commitSha: string;
+  /** Branch name that was pulled (e.g. "v2"). */
+  branch: string;
+}
+/** Result of a `git push` (called via the proxy's git-receive-pack). */
+interface PushResult {
+  /** Remote ref updated (e.g. "refs/heads/v2"). */
+  ref: string;
+  /** New commit SHA on the remote. */
+  commitSha: string;
+}
+/** A branch as advertised by `git ls-remote`. */
+interface RemoteBranch {
+  /** Full ref name, e.g. `refs/heads/main`. */
+  ref: string;
+  /** Commit SHA the ref points at. */
+  sha: string;
+}
+/** Outcome of any spawned `git` process. */
+interface GitSpawnResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+/** Strategy for executing git commands. Tests inject a stub. */
+interface GitSpawner {
+  spawn(args: string[], opts: SpawnOptions): Promise<GitSpawnResult>;
+}
+/** Options for instantiating GitClient. */
+interface GitClientOptions {
+  /** Base URL of the server git proxy. e.g. `http://localhost:3000/git-proxy`. */
+  serverProxyBase: string;
+  /** Inject a custom spawner (default: spawn real `git` CLI). */
+  spawner?: GitSpawner;
+  /** Inject an env override for spawned git (default: process.env minus proxy secrets). */
+  env?: NodeJS.ProcessEnv;
+}
+/** Sentinel error when git exits non-zero. */
+declare class GitError extends Error {
+  readonly args: string[];
+  readonly code: number;
+  readonly stderr: string;
+  readonly stdout: string;
+  constructor(args: string[], result: GitSpawnResult);
+}
+//#endregion
+//#region src/git-client/index.d.ts
+/**
+ * Skill & Agent v2 — Client GitClient (M3)
+ *
+ * Wraps `git` so all upstream traffic flows through the server's git
+ * proxy at `serverProxyBase`. See docs/architecture/skill-agent-v2-repo.md
+ * §5.4.
+ *
+ * Why a wrapper instead of using libgit2 directly:
+ *   1. `git` is already installed everywhere we run (extension host,
+ *      CLI). No native deps.
+ *   2. Users can debug their skill repos with plain `git` commands when
+ *      SERVICEME is misbehaving — the wrappers keep a familiar CLI.
+ *   3. libgit2's packfile negotiation has subtle correctness gaps that
+ *      we don't want to debug server-side.
+ *
+ * URL rewrite:
+ *   `https://github.com/owner/repo.git` → `<proxyBase>/<id>`
+ *
+ *   When git hits `<proxyBase>/<id>` it discovers the proxy's
+ *   `/info/refs?service=git-upload-pack` endpoint via the smart-HTTP
+ *   protocol. From there the server takes over.
+ */
+declare class GitClient {
+  private readonly serverProxyBase;
+  private readonly spawner;
+  constructor(opts: GitClientOptions);
+  /**
+   * Rewrite an upstream URL to its proxy form.
+   *
+   * Examples:
+   *   rewriteRemoteUrl("repo-aHR0cHM6Ly9naXRodWIuY29tL21lZGFsc29mdGNoaW5hL21zLXNraWxscy5naXQ",
+   *     "https://github.com/medalsoftchina/ms-skills.git")
+   *     → "http://localhost:3000/git-proxy/repo-aHR0cHM6Ly9naXRodWIuY29tL21lZGFsc29mdGNoaW5hL21zLXNraWxscy5naXQ"
+   *
+   *   rewriteRemoteUrl("repo-aHR0cHM6Ly9naXRodWIuY29tL3RlYW0vaW50ZXJuYWwuZ2l0",
+   *     "git@github.com:medalsoftchina/ms-skills.git")
+   *     → "http://localhost:3000/git-proxy/repo-aHR0cHM6Ly9naXRodWIuY29tL3RlYW0vaW50ZXJuYWwuZ2l0"
+   *
+   * The original URL's host/owner is intentionally DROPPED — the proxy
+   * knows the upstream from the per-repo config, not from the URL. This
+   * means callers can route both default and user repos through the same
+   * dynamic proxy-id scheme.
+   */
+  rewriteRemoteUrl(_repoId: string, originalUrl: string, useProxy?: boolean): string;
+  /**
+   * `git clone <proxyUrl> <localPath>` — initialize a new local repo
+   * from the proxy. Returns when the clone succeeds; throws on failure.
+   *
+   * When `branch` is provided, the clone is restricted to that branch
+   * via `git clone -b <branch> -- <proxyUrl> <localPath>` so the local
+   * checkout lands on the configured `repo.branch` instead of the
+   * upstream default branch. The parameter is optional and backward
+   * compatible — omitting it keeps the original behaviour.
+   */
+  clone(repoId: string, originalUrl: string, localPath: string, branch?: string, useProxy?: boolean): Promise<void>;
+  /**
+   * `git fetch <remote> <branch>` + return the resulting commit SHA.
+   * Operates on an already-cloned repo at `localPath`.
+   *
+   * When `branch` is provided, the pull target is forced to that branch:
+   * if the local working tree is on a different branch, `git checkout
+   * <branch>` is issued first (git auto-tracks `origin/<branch>`), so
+   * the sync leaves the repo parked on the configured `repo.branch`.
+   * When `branch` is omitted the legacy behaviour is preserved — the
+   * current local branch is fast-forwarded. The parameter is optional
+   * and backward compatible.
+   */
+  pull(repoId: string, localPath: string, branch?: string, useProxy?: boolean, originalUrl?: string): Promise<PullResult>;
+  /**
+   * `git push origin <branch>` via the proxy. Caller is responsible
+   * for committing locally first. The server's GitProxy injects the
+   * PAT on the way upstream.
+   */
+  push(repoId: string, localPath: string, branch: string, useProxy?: boolean): Promise<PushResult>;
+  /**
+   * `git ls-remote <proxyUrl>` — list advertised branches without
+   * cloning. Used by addUserRepo to detect the default branch.
+   */
+  lsRemote(repoId: string, originalUrl: string, useProxy?: boolean): Promise<RemoteBranch[]>;
+  /**
+   * Fetch an exact commit and detach HEAD at it. Used by workspace
+   * content restoration, which must never silently advance to a branch
+   * head. Returns the verified commit SHA.
+   */
+  checkoutCommit(localPath: string, commit: string, repoId: string, useProxy?: boolean, originalUrl?: string): Promise<string>;
+  /**
+   * Resolve a repo-relative path inside the git directory using
+   * `git rev-parse --git-path`, which handles linked worktrees and
+   * submodules correctly (their metadata does not live under
+   * `<worktree>/.git` as a directory).
+   */
+  gitPath(localPath: string, pathspec: string): Promise<string>;
+  /**
+   * Resolve the current HEAD commit of a local clone. Returns an empty
+   * string when git cannot resolve it (e.g. an empty repository) so
+   * callers can decide how to surface the failure.
+   */
+  revParseHead(localPath: string): Promise<string>;
+  /**
+   * `git add <pathspec…>` followed by `git commit -m <message>`. The
+   * commit message convention follows the spec: `feat(skills): add
+   * <name>` / `feat(agents): add <name>`.
+   */
+  commit(localPath: string, message: string, addPath?: string): Promise<{
+    commitSha: string;
+  }>;
+  private runOrThrow;
+  private getRemoteUrl;
+  private safeRevParse;
+  private currentBranch;
+}
+declare class NodeGitSpawner implements GitSpawner {
+  spawn(args: string[], opts: {
+    cwd?: string;
+  }): Promise<GitSpawnResult>;
+}
+/** Convenience: a record-based stub spawner for tests. */
+declare class StubGitSpawner implements GitSpawner {
+  /** queue of canned responses, consumed FIFO per spawn() call. */
+  readonly script: GitSpawnResult[];
+  /** All spawn() invocations, in order, for assertions. */
+  readonly calls: Array<{
+    args: string[];
+    cwd: string | undefined;
+  }>;
+  constructor(script: GitSpawnResult[]);
+  spawn(args: string[], opts: {
+    cwd?: string;
+  }): Promise<GitSpawnResult>;
+}
+/**
+ * Helper: encode a bare absolute file URL (`file:///...`) for local
+ * git clone tests. Not used by GitClient directly — exposed for
+ * RepoManager's `localSeed` use case.
+ */
+declare function toFileUrl(absolutePath: string): string;
+/** Path suffix appended to a server base URL to reach its git-proxy route. */
+declare const GIT_PROXY_PATH_SUFFIX = "/git-proxy";
+/**
+ * Single source of truth for deriving a {@link GitClientOptions.serverProxyBase}
+ * from an already-resolved, non-empty server base URL (e.g. the extension's
+ * verified marketplace server). Callers that derive `serverProxyBase` from a
+ * known server base URL — extension bootstrap, the sync scheduler, the CLI
+ * bridge subprocess env — should go through this helper instead of
+ * re-deriving the `/git-proxy` suffix locally, so the route contract only
+ * lives in one place. (Standalone CLI defaults such as
+ * `http://127.0.0.1:3000/git-proxy`, used when no server base URL is known
+ * at all, are a separate concern and don't go through this helper.)
+ *
+ * Callers MUST guard against an empty/falsy `serverBaseUrl` before calling —
+ * this function does not validate its input and will happily return the
+ * non-URL `"/git-proxy"` for an empty string.
+ */
+declare function buildGitProxyBase(serverBaseUrl: string): string;
+//#endregion
+//#region src/submit/types.d.ts
+/**
+ * Skill & Agent v2 — SubmitClient Types (M4)
+ *
+ * Mirrors the server's POST /api/v1/skills/validate contract (M2
+ * SubmitApi). Defined here as a separate types file so the test
+ * fixtures + the client can both import without circular deps.
+ */
+/** Reasons the server may deny a submission. */
+type DenyReason = "repo_not_writable" | "file_too_large" | "path_traversal" | "invalid_frontmatter" | "name_conflict" |
+/** Local-client-side errors that don't come from the server. */
+"network_error" | "write_error" | "commit_error" | "push_error" | "unknown";
+/** Request payload. Identical to the server's SubmitValidationRequest. */
+interface SubmitValidationRequest {
+  repoId: string;
+  skillName: string;
+  files: Array<{
+    path: string;
+    content: string;
+  }>;
+}
+/** Response payload. Identical to the server's SubmitValidationResponse. */
+interface SubmitValidationResponse {
+  allow: boolean;
+  reason?: DenyReason;
+  detail?: string;
+}
+/** Sentinel error thrown by SubmitClient.submit() / validate(). */
+declare class SubmitError extends Error {
+  readonly reason: DenyReason;
+  readonly detail: string;
+  readonly status?: number;
+  constructor(reason: DenyReason, detail: string, options?: {
+    status?: number;
+  });
+}
+//#endregion
+//#region src/submit/index.d.ts
+/**
+ * Skill & Agent v2 — SubmitClient (M4)
+ *
+ * SubmitClient orchestrates the "validate then push" flow described
+ * in docs/architecture/skill-agent-v2-repo.md §5.7:
+ *
+ *   1. **validate** — POST the candidate files to the server's
+ *      `/api/v1/skills/validate` endpoint (5 deny reasons: repo_not_
+ *      writable, file_too_large, path_traversal, invalid_frontmatter,
+ *      name_conflict).
+ *   2. **write** — materialize the files into the local repo clone at
+ *      `~/.serviceme/repos/<repoId>/skills/<name>/` (or `agents/`).
+ *   3. **commit** — `git add . && git commit -m "feat(skills): add <name>"`.
+ *   4. **push** — `git push origin <branch>` via the server proxy.
+ *
+ * The client is intentionally thin: it does NOT do its own validation
+ * (the server is the gate), and it does NOT cache anything across
+ * calls. The single source of truth for "is this submission allowed?"
+ * is the server's validate endpoint.
+ *
+ * @see docs/architecture/skill-agent-v2-repo.md §5.7 SubmitClient
+ */
+interface SubmitOptions {
+  /** Override the server's validate URL. Defaults to `http://localhost:3000/api/v1`. */
+  serverBaseUrl?: string;
+  /** Override the branch to push. Defaults to the repo's `branch` field. */
+  branch?: string;
+  /** Skip the actual push (for tests + dry-runs). When true, step 4 returns a synthetic PushResult. */
+  skipPush?: boolean;
+}
+interface SubmitResult {
+  repoId: string;
+  skillName: string;
+  commitSha: string;
+  pushedRef?: string;
+  pushedSha?: string;
+}
+interface SubmitClientOptions {
+  gitClient: GitClient;
+  /** Lookup the default branch for a repo (config-driven). */
+  getRepoBranch?: (repoId: string) => string | undefined;
+  /** HTTP fetch impl (defaults to the global `fetch`). */
+  fetcher?: typeof fetch;
+  /** Default server base URL when no override is supplied. */
+  defaultServerBaseUrl?: string;
+}
+declare class SubmitClient {
+  private readonly git;
+  private readonly getRepoBranch;
+  private readonly fetcher;
+  private readonly defaultServerBaseUrl;
+  constructor(opts: SubmitClientOptions);
+  /**
+   * Validate-only path. Useful for the UI's "Save Draft" flow which
+   * wants to surface validation errors without committing or pushing.
+   */
+  validate(req: SubmitValidationRequest): Promise<SubmitValidationResponse>;
+  /**
+   * Full submit pipeline. Throws `SubmitError` on:
+   *   - validate deny (reason echoed)
+   *   - network failure (network_error)
+   *   - local write failure
+   *   - commit/push failure
+   */
+  submit(repoId: string, skillName: string, files: SkillFile[], opts?: SubmitOptions): Promise<SubmitResult>;
+}
+//#endregion
+export { SubmitError as a, NodeGitSpawner as c, toFileUrl as d, GitError as f, SubmitResult as i, StubGitSpawner as l, SubmitClientOptions as n, GIT_PROXY_PATH_SUFFIX as o, PullResult as p, SubmitOptions as r, GitClient as s, SubmitClient as t, buildGitProxyBase as u };
+//# sourceMappingURL=index-Dp6FwWKh.d.ts.map