@serviceme/devtools-core 0.1.8 → 0.2.0

package/dist/index-Dmyy4urr.d.mts

@@ -0,0 +1,277 @@
+import { SpawnOptions } from 'node:child_process';
+import { b as SkillFile } from './types-B9gk3dXH.mjs';
+
+/**
+ * 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);
+}
+
+/**
+ * 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("medalsoftchina-ms-skills",
+     *     "https://github.com/medalsoftchina/ms-skills.git")
+     *     → "http://localhost:3000/git-proxy/medalsoftchina-ms-skills"
+     *
+     *   rewriteRemoteUrl("my-team-internal",
+     *     "git@github.com:medalsoftchina/ms-skills.git")
+     *     → "http://localhost:3000/git-proxy/my-team-internal"
+     *
+     * 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't accidentally route a user-repo URL through the
+     * default-repo proxy slot.
+     */
+    rewriteRemoteUrl(_repoId: string, _originalUrl: string): string;
+    /**
+     * `git clone <proxyUrl> <localPath>` — initialize a new local repo
+     * from the proxy. Returns when the clone succeeds; throws on failure.
+     */
+    clone(repoId: string, originalUrl: string, localPath: string): Promise<void>;
+    /**
+     * `git fetch <remote> <branch>` + return the resulting commit SHA.
+     * Operates on an already-cloned repo at `localPath`.
+     */
+    pull(repoId: string, localPath: 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): Promise<PushResult>;
+    /**
+     * `git ls-remote <proxyUrl>` — list advertised branches without
+     * cloning. Used by addUserRepo to detect the default branch.
+     */
+    lsRemote(repoId: string, originalUrl: string): Promise<RemoteBranch[]>;
+    /**
+     * `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;
+
+/**
+ * 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;
+    });
+}
+
+/**
+ * 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>;
+}
+
+export { GitClient as G, NodeGitSpawner as N, type PullResult as P, StubGitSpawner as S, GitError as a, SubmitClient as b, type SubmitClientOptions as c, SubmitError as d, type SubmitOptions as e, type SubmitResult as f, toFileUrl as t };