@serviceme/devtools-core 2.0.0 → 2.0.2

package/dist/index-2rX86yMq.d.mts

@@ -0,0 +1,331 @@
+import { r as SkillFile } from "./types-BCV3IedE.mjs";
+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-2rX86yMq.d.mts.map