@perrylink/dsh-github 0.4.0

package/lib/git.d.ts

@@ -0,0 +1,52 @@
+/** Runs one git command with stdout captured; injectable for tests. */
+export type GitRunner = (args: string[], options: {
+    cwd: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    stdout: string;
+}>;
+/** Read-only snapshot of the git state a PR draft needs. */
+export interface GitState {
+    /** Current branch, or null outside a repository. */
+    branch: string | null;
+    /** Whether the working tree has uncommitted changes. */
+    hasChanges: boolean;
+    /** Porcelain status lines, capped. */
+    changedFiles: string[];
+    /** Oneline log of commits ahead of the upstream (or the latest commits). */
+    commitsAhead: string[];
+    /** `origin` remote URL, when configured. */
+    remote: string | null;
+    /** `owner/repo` parsed from the origin URL, when parseable. */
+    repoFromRemote: string | null;
+    /** First read failure that stopped collection; the rest stays partial. */
+    error?: string;
+}
+/** Run the real git CLI with stdout captured (never logged). */
+export declare function runGitCli(args: string[], options: {
+    cwd: string;
+    signal?: AbortSignal;
+}): Promise<{
+    stdout: string;
+}>;
+/**
+ * Parse `owner/repo` out of common origin URL forms (https, ssh, git), for any
+ * GitHub host. The host must match `apiHost` (the configured REST base's
+ * hostname; `github.com` by default), so a GitHub Enterprise checkout resolves
+ * against its own API without accepting an unrelated host.
+ * @param remote - raw `git remote get-url origin` output.
+ * @param apiHost - expected hostname (lowercased), e.g. `github.com` or `git.example.com`.
+ * @returns `owner/repo`, or null when the URL is unparseable or foreign.
+ */
+export declare function repoFromRemoteUrl(remote: string, apiHost?: string): string | null;
+/**
+ * Collect the read-only git facts a PR draft needs, tolerating partial
+ * failures: each command that fails records `error` and stops collection.
+ * @param cwd - repository working directory.
+ * @param runGit - git CLI runner; the real one by default.
+ * @param signal - cancels collection.
+ * @param apiHost - expected origin host for `owner/repo` parsing (`github.com` by default).
+ * @returns the collected snapshot.
+ */
+export declare function readGitState(cwd: string, runGit?: GitRunner, signal?: AbortSignal, apiHost?: string): Promise<GitState>;
+//# sourceMappingURL=git.d.ts.map

package/lib/git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.d.ts","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"AASA,uEAAuE;AACvE,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEvH,4DAA4D;AAC5D,MAAM,WAAW,QAAQ;IACvB,oDAAoD;IACpD,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,wDAAwD;IACxD,UAAU,EAAE,OAAO,CAAA;IACnB,sCAAsC;IACtC,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,4EAA4E;IAC5E,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IACrB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAKD,gEAAgE;AAChE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAE,GAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAOrH;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAe,GAAG,MAAM,GAAG,IAAI,CAMvF;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,SAAqB,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,SAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsD9I"}

package/lib/git.js

@@ -0,0 +1,113 @@
+/**
+ * Read-only git workspace inspection for `/pr create` drafts.
+ *
+ * The plugin never commits, pushes, or rewrites git identity — dsh-git-identity
+ * and the model's own bash calls own those writes. Everything here is a read.
+ * @module dsh-github/git
+ */
+import { execFile } from 'node:child_process';
+const MAX_CHANGED_FILES = 50;
+const MAX_COMMITS = 20;
+/** Run the real git CLI with stdout captured (never logged). */
+export function runGitCli(args, options) {
+    return new Promise((resolve, reject) => {
+        execFile('git', args, { cwd: options.cwd, windowsHide: true, signal: options.signal, maxBuffer: 8 * 1024 * 1024 }, (error, stdout) => {
+            if (error)
+                reject(error);
+            else
+                resolve({ stdout });
+        });
+    });
+}
+/**
+ * Parse `owner/repo` out of common origin URL forms (https, ssh, git), for any
+ * GitHub host. The host must match `apiHost` (the configured REST base's
+ * hostname; `github.com` by default), so a GitHub Enterprise checkout resolves
+ * against its own API without accepting an unrelated host.
+ * @param remote - raw `git remote get-url origin` output.
+ * @param apiHost - expected hostname (lowercased), e.g. `github.com` or `git.example.com`.
+ * @returns `owner/repo`, or null when the URL is unparseable or foreign.
+ */
+export function repoFromRemoteUrl(remote, apiHost = 'github.com') {
+    const trimmed = remote.trim();
+    const match = /^(?:https?:\/\/|ssh:\/\/git@|git:\/\/|git@)?([^/:]+)(?::\d+)?[:/]([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?\/?$/.exec(trimmed);
+    if (match === null)
+        return null;
+    const host = (match[1] ?? '').toLowerCase();
+    return host === apiHost.toLowerCase() ? (match[2] ?? null) : null;
+}
+/**
+ * Collect the read-only git facts a PR draft needs, tolerating partial
+ * failures: each command that fails records `error` and stops collection.
+ * @param cwd - repository working directory.
+ * @param runGit - git CLI runner; the real one by default.
+ * @param signal - cancels collection.
+ * @param apiHost - expected origin host for `owner/repo` parsing (`github.com` by default).
+ * @returns the collected snapshot.
+ */
+export async function readGitState(cwd, runGit = runGitCli, signal, apiHost = 'github.com') {
+    const state = {
+        branch: null,
+        hasChanges: false,
+        changedFiles: [],
+        commitsAhead: [],
+        remote: null,
+        repoFromRemote: null,
+    };
+    try {
+        const { stdout } = await runGit(['rev-parse', '--abbrev-ref', 'HEAD'], { cwd, signal });
+        state.branch = stdout.trim() || null;
+    }
+    catch (error) {
+        state.error = describeError(error);
+        return state;
+    }
+    try {
+        const { stdout } = await runGit(['status', '--porcelain=v1'], { cwd, signal });
+        const lines = stdout.split(/\r?\n/).filter(line => line.length > 0);
+        state.changedFiles = lines.slice(0, MAX_CHANGED_FILES);
+        state.hasChanges = lines.length > 0;
+    }
+    catch (error) {
+        state.error = describeError(error);
+        return state;
+    }
+    try {
+        const { stdout } = await runGit(['log', '--oneline', '-n', String(MAX_COMMITS), '@{upstream}..HEAD'], { cwd, signal });
+        state.commitsAhead = stdout.split(/\r?\n/).filter(line => line.length > 0);
+    }
+    catch {
+        // No upstream configured: list the latest local commits instead.
+        try {
+            const { stdout } = await runGit(['log', '--oneline', '-n', String(MAX_COMMITS), 'HEAD'], { cwd, signal });
+            state.commitsAhead = stdout.split(/\r?\n/).filter(line => line.length > 0);
+        }
+        catch (error) {
+            state.error = describeError(error);
+            return state;
+        }
+    }
+    try {
+        const { stdout } = await runGit(['remote', 'get-url', 'origin'], { cwd, signal });
+        const remote = stdout.trim();
+        if (remote.length > 0) {
+            state.remote = remote;
+            state.repoFromRemote = repoFromRemoteUrl(remote, apiHost);
+        }
+    }
+    catch {
+        // No origin remote: leave remote facts absent.
+    }
+    return state;
+}
+function describeError(error) {
+    if (error instanceof Error) {
+        if (error.message.includes('not a git repository'))
+            return 'not a git repository';
+        if (error.message.includes('ENOENT'))
+            return 'git CLI not available';
+        return error.message;
+    }
+    return 'git read failed';
+}
+//# sourceMappingURL=git.js.map

package/lib/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../src/git.ts"],"names":[],"mappings":"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"}

package/lib/github.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Minimal GitHub REST client: JSON requests with 429 backoff-retry and
+ * rate-limit surfacing, plus the `application/vnd.github.diff` text endpoint.
+ *
+ * The token travels only in the Authorization header of outgoing requests;
+ * request bodies, error messages, and returned values never contain it.
+ * @module dsh-github/github
+ */
+import type { Config } from './config.ts';
+/** GitHub rate-limit facts, surfaced to the model on every read result. */
+export interface RateLimitInfo {
+    remaining: number | null;
+    /** Epoch ms when the window resets; null when the response omitted it. */
+    resetAt: number | null;
+}
+/** Domain failure of one GitHub API request, token-free by construction. */
+export declare class GithubError extends Error {
+    readonly status: number;
+    readonly rateLimit: RateLimitInfo;
+    constructor(status: number, message: string, rateLimit: RateLimitInfo);
+}
+/** Successful JSON response with its rate-limit facts. */
+export interface GithubJsonResponse<T> {
+    status: number;
+    data: T;
+    rateLimit: RateLimitInfo;
+}
+export interface GithubRequestOptions {
+    /** JSON body for writes. */
+    body?: unknown;
+    /** Override the Accept header (e.g. the diff media type). */
+    accept?: string;
+    signal?: AbortSignal;
+}
+interface ClientOptions {
+    apiBaseUrl: string;
+    maxRetries: number;
+    retryBaseMs: number;
+    retryMaxWaitMs: number;
+    fetchImpl: typeof fetch;
+}
+/**
+ * Authenticated GitHub REST client with 429 retry.
+ *
+ * Retries honor Retry-After / x-ratelimit-reset and the caller's signal;
+ * non-2xx responses surface as {@link GithubError} carrying the status and
+ * current rate-limit facts. Errors never contain the token.
+ */
+export declare class GithubClient {
+    private readonly token;
+    private readonly options;
+    constructor(token: string, options: ClientOptions);
+    /** One JSON request with retry; `GithubError` on any non-2xx status. */
+    requestJson<T>(method: string, path: string, options?: GithubRequestOptions): Promise<GithubJsonResponse<T>>;
+    /** One text request (the diff media type) with retry. */
+    requestText(method: string, path: string, options?: GithubRequestOptions): Promise<{
+        text: string;
+        rateLimit: RateLimitInfo;
+    }>;
+    /** Fetch with Authorization, 429 retry, and signal handling. */
+    private request;
+}
+/** Build a client from config; resolves the base URL once. */
+export declare function clientOptionsFromConfig(config: Config, fetchImpl?: typeof fetch): ClientOptions;
+export {};
+//# sourceMappingURL=github.d.ts.map

package/lib/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,2EAA2E;AAC3E,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CACvB;AAED,4EAA4E;AAC5E,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAA;gBAErB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa;CAMtE;AAED,0DAA0D;AAC1D,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,CAAC,CAAA;IACP,SAAS,EAAE,aAAa,CAAA;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED,UAAU,aAAa;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,SAAS,EAAE,OAAO,KAAK,CAAA;CACxB;AAqDD;;;;;;GAMG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;gBAE3B,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa;IAKjD,wEAAwE;IAClE,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC;IAiBtH,yDAAyD;IACnD,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,aAAa,CAAA;KAAE,CAAC;IAgBxI,gEAAgE;YAClD,OAAO;CA0BtB;AAED,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,KAAK,GAAG,aAAa,CAQ/F"}

package/lib/github.js

@@ -0,0 +1,153 @@
+/** Domain failure of one GitHub API request, token-free by construction. */
+export class GithubError extends Error {
+    status;
+    rateLimit;
+    constructor(status, message, rateLimit) {
+        super(message);
+        this.name = 'GithubError';
+        this.status = status;
+        this.rateLimit = rateLimit;
+    }
+}
+const JSON_ACCEPT = 'application/vnd.github+json';
+const API_VERSION = '2022-11-28';
+const USER_AGENT = 'dsh-github';
+function rateLimitFromHeaders(headers) {
+    const remaining = headers.get('x-ratelimit-remaining');
+    const reset = headers.get('x-ratelimit-reset');
+    const remainingNum = remaining === null ? null : Number(remaining);
+    const resetNum = reset === null ? null : Number(reset);
+    return {
+        remaining: remainingNum !== null && Number.isFinite(remainingNum) ? remainingNum : null,
+        resetAt: resetNum !== null && Number.isFinite(resetNum) ? resetNum * 1000 : null,
+    };
+}
+/** Retry delay for a 429 response: Retry-After seconds or reset-epoch, else backoff. */
+function retryDelayMs(headers, attempt, options) {
+    const retryAfter = headers.get('retry-after');
+    if (retryAfter !== null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.min(seconds * 1000, options.retryMaxWaitMs);
+    }
+    const reset = headers.get('x-ratelimit-reset');
+    if (reset !== null) {
+        const until = Number(reset) * 1000 - Date.now();
+        if (Number.isFinite(until) && until > 0)
+            return Math.min(until, options.retryMaxWaitMs);
+    }
+    return Math.min(options.retryBaseMs * 2 ** attempt, options.retryMaxWaitMs);
+}
+/** Wait while still honoring the caller's abort signal. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const aborter = signal ?? null;
+        if (aborter?.aborted === true) {
+            reject(aborter.reason instanceof Error ? aborter.reason : new Error('aborted'));
+            return;
+        }
+        const timer = setTimeout(done, ms);
+        aborter?.addEventListener('abort', onAbort, { once: true });
+        function done() {
+            aborter?.removeEventListener('abort', onAbort);
+            resolve();
+        }
+        function onAbort() {
+            clearTimeout(timer);
+            reject(aborter?.reason instanceof Error ? aborter.reason : new Error('aborted'));
+        }
+    });
+}
+/**
+ * Authenticated GitHub REST client with 429 retry.
+ *
+ * Retries honor Retry-After / x-ratelimit-reset and the caller's signal;
+ * non-2xx responses surface as {@link GithubError} carrying the status and
+ * current rate-limit facts. Errors never contain the token.
+ */
+export class GithubClient {
+    token;
+    options;
+    constructor(token, options) {
+        this.token = token;
+        this.options = options;
+    }
+    /** One JSON request with retry; `GithubError` on any non-2xx status. */
+    async requestJson(method, path, options = {}) {
+        const response = await this.request(method, path, { ...options, accept: options.accept ?? JSON_ACCEPT });
+        const rateLimit = rateLimitFromHeaders(response.headers);
+        if (!response.ok) {
+            let message = `GitHub API ${response.status} for ${method} ${path}`;
+            try {
+                const parsed = await response.json();
+                if (typeof parsed.message === 'string' && parsed.message.length > 0)
+                    message = parsed.message;
+            }
+            catch {
+                // Non-JSON error body: keep the status-based message.
+            }
+            throw new GithubError(response.status, message, rateLimit);
+        }
+        const data = await response.json();
+        return { status: response.status, data, rateLimit };
+    }
+    /** One text request (the diff media type) with retry. */
+    async requestText(method, path, options = {}) {
+        const response = await this.request(method, path, { ...options, accept: 'application/vnd.github.diff' });
+        const rateLimit = rateLimitFromHeaders(response.headers);
+        if (!response.ok) {
+            let message = `GitHub API ${response.status} for ${method} ${path}`;
+            try {
+                const parsed = await response.json();
+                if (typeof parsed.message === 'string' && parsed.message.length > 0)
+                    message = parsed.message;
+            }
+            catch {
+                // Non-JSON error body: keep the status-based message.
+            }
+            throw new GithubError(response.status, message, rateLimit);
+        }
+        return { text: await response.text(), rateLimit };
+    }
+    /** Fetch with Authorization, 429 retry, and signal handling. */
+    async request(method, path, options) {
+        let attempt = 0;
+        for (;;) {
+            let response;
+            try {
+                response = await this.options.fetchImpl(new URL(path, this.options.apiBaseUrl), {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.token}`,
+                        Accept: options.accept ?? JSON_ACCEPT,
+                        'X-GitHub-Api-Version': API_VERSION,
+                        'User-Agent': USER_AGENT,
+                        ...options.body !== undefined ? { 'Content-Type': 'application/json' } : {},
+                    },
+                    ...options.body !== undefined ? { body: JSON.stringify(options.body) } : {},
+                    signal: options.signal,
+                });
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason instanceof Error ? options.signal.reason : new Error('aborted');
+                throw error;
+            }
+            if (response.status !== 429 || attempt >= this.options.maxRetries)
+                return response;
+            await sleep(retryDelayMs(response.headers, attempt, this.options), options.signal);
+            attempt += 1;
+        }
+    }
+}
+/** Build a client from config; resolves the base URL once. */
+export function clientOptionsFromConfig(config, fetchImpl) {
+    return {
+        apiBaseUrl: config.apiBaseUrl.replace(/\/+$/, ''),
+        maxRetries: config.maxRetries,
+        retryBaseMs: config.retryBaseMs,
+        retryMaxWaitMs: config.retryMaxWaitMs,
+        fetchImpl: fetchImpl ?? globalThis.fetch.bind(globalThis),
+    };
+}
+//# sourceMappingURL=github.js.map

package/lib/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"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"}

package/lib/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * dsh-github: GitHub integration for DeepSeek Harness.
+ *
+ * Tools: pr_create (write), gh_review (read), review_post (write), gh_issue
+ * (read), issue_open / issue_comment / issue_close (writes), gh_search (read).
+ * Commands: /pr create, /review (start|stop|post), /issue open. Background
+ * review jobs run the deterministic analyzer by default; `reviewMode: "model"`
+ * delegates the capped diff to a one-shot subagent through the host's
+ * `subagents` seam. Every GitHub write is gated by the tools/pre-execute
+ * approval listener (default ask) and the allowedActions whitelist; the token
+ * travels only through the credentials seam / environment / gh CLI and never
+ * reaches model-visible text, session events, or logs.
+ *
+ * Model-visible ⇔ logged: the plugin appends NO custom session event types —
+ * the host refuses logs with unknown out-of-repo event types, so all content
+ * the model sees flows through the host's own logged surfaces: tool/result
+ * canonical values, agent-injected user/message notices, command/run +
+ * command/done lifecycle pairs, and the approval/asked + approval/decided
+ * audit pair. See README.md "Architecture".
+ * @module dsh-github
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type GitRunner } from './git.ts';
+import { type GhRunner } from './credential.ts';
+import { Config, type Config as PluginConfig } from './config.ts';
+export declare const name = "dsh-github";
+/** Services this plugin requires; all exist in any profile built on dsh-base. */
+export declare const inject: string[];
+export { Config };
+export type { Config as PluginConfig };
+/** Environment-dependent runners, injectable for tests. */
+export interface PluginDeps {
+    runGit?: GitRunner;
+    runGh?: GhRunner;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Apply the plugin with explicit environment runners.
+ *
+ * The production {@link apply} passes the real git/gh runners; tests inject
+ * fakes through {@link applyWithDeps} so no test touches the network or a
+ * real shell. Every registration is an effect — disposing the plugin fiber
+ * reverses all of them.
+ * @param ctx - plugin context; the injected services are ready at this point.
+ * @param config - validated Schemastery configuration (defaults applied).
+ * @param deps - optional git/gh/fetch runners.
+ */
+export declare function applyWithDeps(ctx: Context, config: PluginConfig, deps?: PluginDeps): void;
+/**
+ * Apply the plugin: register tools, commands, and the write-approval gate.
+ * @param ctx - plugin context; the injected services are ready at this point.
+ * @param config - validated Schemastery configuration (defaults applied).
+ */
+export declare function apply(ctx: Context, config: PluginConfig): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,UAAU,CAAA;AACpD,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAQzD,OAAO,EAAE,MAAM,EAAE,KAAK,MAAM,IAAI,YAAY,EAAE,MAAM,aAAa,CAAA;AAEjE,eAAO,MAAM,IAAI,eAAe,CAAA;AAEhC,iFAAiF;AACjF,eAAO,MAAM,MAAM,UAA2D,CAAA;AAE9E,OAAO,EAAE,MAAM,EAAE,CAAA;AACjB,YAAY,EAAE,MAAM,IAAI,YAAY,EAAE,CAAA;AAEtC,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,EAAE,SAAS,CAAA;IAClB,KAAK,CAAC,EAAE,QAAQ,CAAA;IAChB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,IAAI,GAAE,UAAe,QActF;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,QAEvD"}

package/lib/index.js

@@ -0,0 +1,44 @@
+import { createState } from "./state.js";
+import { runGitCli } from "./git.js";
+import { runGhCli } from "./credential.js";
+import { prCreateTool, ghReviewTool, reviewPostTool, ghIssueTool, issueOpenTool, issueCommentTool, issueCloseTool, ghSearchTool, } from "./tools.js";
+import { registerApprovalGate } from "./approval-gate.js";
+import { registerCommands } from "./commands.js";
+import { Config } from "./config.js";
+export const name = 'dsh-github';
+/** Services this plugin requires; all exist in any profile built on dsh-base. */
+export const inject = ['tools', 'commands', 'jobs', 'approval', 'credentials'];
+export { Config };
+/**
+ * Apply the plugin with explicit environment runners.
+ *
+ * The production {@link apply} passes the real git/gh runners; tests inject
+ * fakes through {@link applyWithDeps} so no test touches the network or a
+ * real shell. Every registration is an effect — disposing the plugin fiber
+ * reverses all of them.
+ * @param ctx - plugin context; the injected services are ready at this point.
+ * @param config - validated Schemastery configuration (defaults applied).
+ * @param deps - optional git/gh/fetch runners.
+ */
+export function applyWithDeps(ctx, config, deps = {}) {
+    const state = createState({ credentials: ctx.credentials, subagents: ctx.get('subagents') }, config, deps.runGit ?? runGitCli, deps.runGh ?? runGhCli, deps.fetchImpl);
+    ctx.tools.register(prCreateTool(state));
+    ctx.tools.register(ghReviewTool(state));
+    ctx.tools.register(reviewPostTool(state));
+    ctx.tools.register(ghIssueTool(state));
+    ctx.tools.register(issueOpenTool(state));
+    ctx.tools.register(issueCommentTool(state));
+    ctx.tools.register(issueCloseTool(state));
+    ctx.tools.register(ghSearchTool(state));
+    ctx.effect(() => registerApprovalGate(ctx, state));
+    ctx.effect(() => registerCommands(ctx.commands, ctx.jobs, state));
+}
+/**
+ * Apply the plugin: register tools, commands, and the write-approval gate.
+ * @param ctx - plugin context; the injected services are ready at this point.
+ * @param config - validated Schemastery configuration (defaults applied).
+ */
+export function apply(ctx, config) {
+    applyWithDeps(ctx, config);
+}
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,SAAS,EAAkB,MAAM,UAAU,CAAA;AACpD,OAAO,EAAE,QAAQ,EAAiB,MAAM,iBAAiB,CAAA;AAEzD,OAAO,EACL,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EACtE,gBAAgB,EAAE,cAAc,EAAE,YAAY,GAC/C,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,MAAM,EAA+B,MAAM,aAAa,CAAA;AAEjE,MAAM,CAAC,MAAM,IAAI,GAAG,YAAY,CAAA;AAEhC,iFAAiF;AACjF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,CAAC,CAAA;AAE9E,OAAO,EAAE,MAAM,EAAE,CAAA;AAUjB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAAC,GAAY,EAAE,MAAoB,EAAE,OAAmB,EAAE;IACrF,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,SAAS,EAAE,GAAG,CAAC,GAAG,CAAC,WAAW,CAAiC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,SAAS,EAAE,IAAI,CAAC,KAAK,IAAI,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IAEtM,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;IACvC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;IACvC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACzC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;IACtC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAA;IACxC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,gBAAgB,CAAC,KAAK,CAAC,CAAC,CAAA;IAC3C,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAA;IACzC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAA;IAEvC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,oBAAoB,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAA;IAClD,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC,CAAA;AACnE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,MAAoB;IACtD,aAAa,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;AAC5B,CAAC"}

package/lib/jobs.d.ts

@@ -0,0 +1,34 @@
+import type { GithubAgent, GithubJobId, JobRegistry } from './types.ts';
+import type { GithubState } from './state.ts';
+/** Producer kind — also the `<kind>-N` id prefix; the host treats it as opaque. */
+export declare const REVIEW_JOB_KIND = "github-review";
+export interface StartReviewJobInput {
+    repo: string;
+    pr: number;
+    label: string;
+    owner: GithubAgent;
+    /** Present in tests where no job registry exists; disables registration. */
+    timeoutMs?: number;
+    /** Diff cap override for this job; defaults to the plugin config. */
+    maxDiffChars?: number;
+    /** Fetch and report CI check runs (default true). */
+    includeCi?: boolean;
+    /** Fetch and count existing review comments (default true). */
+    includeComments?: boolean;
+}
+/**
+ * Start one background review job and register its in-memory record.
+ *
+ * The token is resolved inside the run body (per-operation, per the
+ * credentials-seam contract); a missing token settles the job as `failed`
+ * with configuration guidance, never with a token value. `start` throws when
+ * no job controller serves the owner — callers surface that as a command
+ * error. With `reviewMode: "model"`, the subagent seam must be composed or
+ * this call fails loud before starting the job.
+ * @param registry - `ctx.jobs` of the hosting context.
+ * @param state - plugin state holding config, token resolution, and records.
+ * @param input - target PR, label, owning agent, and job options.
+ * @returns the registry-issued `<kind>-N` id.
+ */
+export declare function startReviewJob(registry: JobRegistry, state: GithubState, input: StartReviewJobInput): GithubJobId;
+//# sourceMappingURL=jobs.d.ts.map

package/lib/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../src/jobs.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAc,WAAW,EAAgB,MAAM,YAAY,CAAA;AACjG,OAAO,KAAK,EAAE,WAAW,EAAmB,MAAM,YAAY,CAAA;AAE9D,mFAAmF;AACnF,eAAO,MAAM,eAAe,kBAAkB,CAAA;AAE9C,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,WAAW,CAAA;IAClB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,qDAAqD;IACrD,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,OAAO,CAAA;CAC1B;AAWD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,mBAAmB,GAAG,WAAW,CAgCjH"}