adispatchd 0.0.0-stage → 0.1.0

package/dist/service/install.js

@@ -0,0 +1,250 @@
+/**
+ * `service install | status | uninstall` (Spec §4, §14, §20.1): plans as
+ * plain data (pure, testable, printable with `--dry-run`) plus an executor
+ * that applies a plan through an injectable {@link SystemRunner}.
+ *
+ * Install never touches the contents of config-dir/data-dir beyond ownership
+ * and permissions, never overwrites an existing environment file and never
+ * deletes anything on uninstall except the unit file.
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { chmod, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { OrchestratorError, errorMessage } from '../core/index.js';
+import { renderSystemdUnit } from './unit.js';
+/** Error of the service commands (`code` = `service_*`). */
+export class ServiceError extends OrchestratorError {
+}
+/** Path of the unit file. */
+export function unitFilePath(unitDir, unitName) {
+    return path.join(unitDir, `${unitName}.service`);
+}
+/** Template of a new environment file (no secrets, only placeholders). */
+export function environmentFileTemplate(unitName) {
+    return [
+        `# Environment of the ${unitName} service (loaded via EnvironmentFile=).`,
+        '# Keep this file at mode 0640, owner root, group = service group. Never commit it.',
+        '# GitHub App private keys referenced by identities.yaml (private_key_env), PEM with \\n escapes or quoted:',
+        '# GITHUB_MAINTAINER_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\\n...\\n-----END RSA PRIVATE KEY-----"',
+        '# Webhook URLs/headers referenced by notifications.channels (url_env / headers_env):',
+        '# SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...',
+        '',
+    ].join('\n');
+}
+/**
+ * System directories that must never be config-dir or data-dir (`install`
+ * runs `chown -R` / `chmod -R` on both).
+ */
+export const PROTECTED_PATHS = [
+    '/', '/bin', '/boot', '/dev', '/etc', '/home', '/lib', '/lib32', '/lib64', '/libx32', '/media', '/mnt', '/opt', '/proc',
+    '/root', '/run', '/sbin', '/snap', '/srv', '/sys', '/tmp', '/usr', '/usr/bin', '/usr/lib', '/usr/lib64', '/usr/libexec',
+    '/usr/local', '/usr/local/bin', '/usr/local/lib', '/usr/sbin', '/usr/share', '/var', '/var/cache', '/var/lib', '/var/log',
+    '/var/opt', '/var/run', '/var/spool', '/var/tmp', '/Users', '/Library', '/System', '/Applications', '/private', '/private/var',
+    '/private/tmp', '/private/etc', '/etc/systemd', '/etc/systemd/system', '/etc/default',
+];
+/** Directories whose direct children are user homes (a home itself must not be chowned either). */
+const HOME_ROOTS = ['/home', '/Users'];
+function depth(p) {
+    return p.split('/').filter(Boolean).length;
+}
+function isInside(child, parent) {
+    const rel = path.relative(parent, child);
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+/**
+ * Reject config-dir/data-dir values on which a recursive `chown`/`chmod`
+ * would be harmful: system directories, top-level directories (depth < 2),
+ * user home directories, and config-dir/data-dir that are equal or nested.
+ * Throws {@link ServiceError} (`service_unsafe_path`).
+ */
+export function assertSafeServicePaths(dirs) {
+    const fail = (msg) => {
+        throw new ServiceError('service_unsafe_path', msg);
+    };
+    for (const [label, raw] of [
+        ['config dir', dirs.configDir],
+        ['data dir', dirs.dataDir],
+    ]) {
+        const p = path.resolve(raw);
+        if (PROTECTED_PATHS.includes(p))
+            fail(`${label} ${p} is a system directory – use a dedicated directory such as /etc/adispatchd or /var/lib/adispatchd`);
+        if (depth(p) < 2)
+            fail(`${label} ${p} is too close to the file system root (at least two levels, e.g. /srv/adispatchd)`);
+        for (const home of HOME_ROOTS) {
+            if (path.dirname(p) === home)
+                fail(`${label} ${p} is a user home directory – use a dedicated subdirectory`);
+        }
+    }
+    const c = path.resolve(dirs.configDir);
+    const d = path.resolve(dirs.dataDir);
+    if (isInside(c, d) || isInside(d, c))
+        fail(`config dir ${c} and data dir ${d} must be separate, non-nested directories (different owners/permissions)`);
+}
+/** Plan `service install`. Throws {@link ServiceError} if the user is missing and `createUser` is false (not in dry runs). */
+export function planInstall(input) {
+    const { unit } = input;
+    assertSafeServicePaths(unit);
+    const content = renderSystemdUnit(unit);
+    const steps = [];
+    const notes = [];
+    const owner = `${unit.user}:${unit.group}`;
+    if (!input.userExists) {
+        if (input.createUser) {
+            steps.push({
+                kind: 'exec',
+                description: `create system user ${unit.user}`,
+                argv: [
+                    'useradd',
+                    '--system',
+                    ...(unit.group === unit.user ? ['--user-group'] : ['--gid', unit.group]),
+                    '--home-dir',
+                    unit.dataDir,
+                    '--no-create-home',
+                    '--shell',
+                    '/usr/sbin/nologin',
+                    unit.user,
+                ],
+            });
+        }
+        else {
+            const hint = `user "${unit.user}" does not exist – rerun with --create-user or create it yourself: ` +
+                `useradd --system --user-group --home-dir ${unit.dataDir} --no-create-home --shell /usr/sbin/nologin ${unit.user}`;
+            if (!input.dryRun)
+                throw new ServiceError('service_user_missing', hint);
+            notes.push(hint);
+        }
+    }
+    steps.push({
+        kind: 'exec',
+        description: `create data dir ${unit.dataDir} (owner ${owner}, 0750)`,
+        argv: ['install', '-d', '-m', '0750', '-o', unit.user, '-g', unit.group, unit.dataDir],
+    }, {
+        kind: 'exec',
+        description: `data dir owned by the service user (database, logs, runs, workspaces)`,
+        argv: ['chown', '-R', owner, unit.dataDir],
+    }, {
+        kind: 'exec',
+        description: `config dir owned by root, readable by group ${unit.group} (the service cannot modify its own configuration/scripts)`,
+        argv: ['chown', '-R', `root:${unit.group}`, unit.configDir],
+    }, {
+        kind: 'exec',
+        description: 'config dir permissions: dirs 0750, files 0640 (executable scripts keep their x bit for the group)',
+        argv: ['chmod', '-R', 'u=rwX,g=rX,o=', unit.configDir],
+    });
+    if (unit.envFile !== null) {
+        if (!input.envFileExists) {
+            steps.push({
+                kind: 'write',
+                description: `create environment file template ${unit.envFile}`,
+                path: unit.envFile,
+                content: environmentFileTemplate(unit.unitName),
+                mode: 0o640,
+            });
+        }
+        else {
+            notes.push(`environment file ${unit.envFile} exists and is kept unchanged (only owner/mode are set)`);
+        }
+        steps.push({ kind: 'exec', description: `environment file owned by root:${unit.group}`, argv: ['chown', `root:${unit.group}`, unit.envFile] }, { kind: 'exec', description: 'environment file mode 0640', argv: ['chmod', '0640', unit.envFile] });
+    }
+    const file = unitFilePath(input.unitDir, unit.unitName);
+    steps.push({ kind: 'write', description: `write unit file ${file}`, path: file, content, mode: 0o644 }, { kind: 'exec', description: 'reload systemd units', argv: ['systemctl', 'daemon-reload'] }, {
+        kind: 'exec',
+        description: input.startNow ? `enable and start ${unit.unitName}` : `enable ${unit.unitName} (start at boot)`,
+        argv: ['systemctl', 'enable', ...(input.startNow ? ['--now'] : []), `${unit.unitName}.service`],
+    });
+    if (!input.startNow)
+        notes.push(`start the service with: systemctl start ${unit.unitName}`);
+    return { steps, notes };
+}
+/** Plan `service uninstall`: stop + disable, remove the unit file, reload. Config, data and user stay. */
+export function planUninstall(input) {
+    const file = unitFilePath(input.unitDir, input.unitName);
+    return {
+        steps: [
+            {
+                kind: 'exec',
+                description: `stop (SIGTERM → drain) and disable ${input.unitName}`,
+                argv: ['systemctl', 'disable', '--now', `${input.unitName}.service`],
+                optional: true,
+            },
+            { kind: 'remove', description: `remove unit file ${file}`, path: file },
+            { kind: 'exec', description: 'reload systemd units', argv: ['systemctl', 'daemon-reload'] },
+        ],
+        notes: [
+            'config dir, data dir (database, logs, workspaces) and the service user are kept; remove them manually if no longer needed',
+            `for a graceful stop of long runs, run "adispatch drain --wait" before uninstalling`,
+        ],
+    };
+}
+/** Human-readable listing of a plan (for `--dry-run`). */
+export function formatPlan(plan) {
+    const out = [];
+    plan.steps.forEach((s, i) => {
+        const n = `${i + 1}.`;
+        if (s.kind === 'exec')
+            out.push(`${n} ${s.description}\n     $ ${s.argv.map(shellQuote).join(' ')}`);
+        else if (s.kind === 'write')
+            out.push(`${n} ${s.description} (mode ${s.mode.toString(8).padStart(4, '0')})`);
+        else
+            out.push(`${n} ${s.description}\n     $ rm -f ${shellQuote(s.path)}`);
+    });
+    return `${out.join('\n')}\n`;
+}
+function shellQuote(s) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(s) ? s : `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/** Real runner (`execFile`, no shell). */
+export const systemRunner = {
+    exec: (argv) => new Promise((resolve) => {
+        const [cmd, ...args] = argv;
+        if (!cmd) {
+            resolve({ code: 127, stdout: '', stderr: 'empty command' });
+            return;
+        }
+        execFile(cmd, args, { encoding: 'utf8' }, (err, stdout, stderr) => {
+            if (!err) {
+                resolve({ code: 0, stdout, stderr });
+                return;
+            }
+            const code = typeof err.code === 'number' ? (err.code) : 127;
+            resolve({ code, stdout: stdout ?? '', stderr: stderr || errorMessage(err) });
+        });
+    }),
+    writeFile: async (file, content, mode) => {
+        await writeFile(file, content, { mode });
+        await chmod(file, mode);
+    },
+    remove: (file) => rm(file, { force: true }),
+    exists: (file) => existsSync(file),
+};
+/** Apply a plan step by step; stops at the first failing non-optional step. */
+export async function executePlan(plan, runner, log) {
+    for (const step of plan.steps) {
+        log(`- ${step.description}\n`);
+        try {
+            if (step.kind === 'exec') {
+                const r = await runner.exec(step.argv);
+                if (r.code !== 0) {
+                    const msg = `${step.argv.join(' ')} exited with ${r.code}: ${r.stderr.trim()}`;
+                    if (step.optional) {
+                        log(`  (ignored) ${msg}\n`);
+                        continue;
+                    }
+                    return { ok: false, failedStep: step, error: msg };
+                }
+            }
+            else if (step.kind === 'write') {
+                await runner.writeFile(step.path, step.content, step.mode);
+            }
+            else {
+                await runner.remove(step.path);
+            }
+        }
+        catch (err) {
+            return { ok: false, failedStep: step, error: errorMessage(err) };
+        }
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=install.js.map

package/dist/service/install.js.map

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

package/dist/service/unit.d.ts

@@ -0,0 +1,50 @@
+/** Exit code of `start` for configuration/startup errors that a restart cannot fix (sysexits EX_CONFIG). */
+export declare const EXIT_CONFIG = 78;
+/** Default unit / service name. */
+export declare const DEFAULT_UNIT_NAME = "adispatchd";
+/** Default dedicated service user (and group). */
+export declare const DEFAULT_SERVICE_USER = "adispatchd";
+/** Default directory for unit files. */
+export declare const DEFAULT_UNIT_DIR = "/etc/systemd/system";
+/** Extra time on top of drain + cancel + grace before systemd kills the cgroup. */
+export declare const DEFAULT_STOP_BUFFER_MS = 60000;
+/** Input of {@link renderSystemdUnit}. */
+export interface UnitOptions {
+    /** Unit name without `.service`. */
+    unitName: string;
+    description?: string;
+    /** Dedicated service user and group. */
+    user: string;
+    group: string;
+    /** Absolute path of the node executable. */
+    nodePath: string;
+    /** Absolute path of the installed package entry point (`…/dist/cli/main.js`). */
+    entryPath: string;
+    /** Absolute config and data directories. */
+    configDir: string;
+    dataDir: string;
+    /** Optional environment file with secrets (GitHub App keys, webhook URLs); `null` = none. */
+    envFile: string | null;
+    /** Drain timeout on SIGTERM before cancel-all (passed to `start --drain-timeout`). */
+    drainTimeoutMs: number;
+    /** Time for cancelled runs incl. `on_cancel` (passed to `start --cancel-timeout`). */
+    cancelTimeoutMs: number;
+    /** Largest `execute.cancel_grace` of all workflows (SIGTERM → SIGKILL of a worker group). */
+    maxCancelGraceMs: number;
+    /** Additional stop buffer (default {@link DEFAULT_STOP_BUFFER_MS}). */
+    stopBufferMs?: number;
+}
+/** `TimeoutStopSec` in whole seconds: drain + cancel + grace + buffer, rounded up. */
+export declare function computeTimeoutStopSec(opts: Pick<UnitOptions, 'drainTimeoutMs' | 'cancelTimeoutMs' | 'maxCancelGraceMs' | 'stopBufferMs'>): number;
+/** Duration in the CLI's own syntax (`10m`, `90s`, `1500ms`), parseable by `parseDuration`. */
+export declare function formatCliDuration(ms: number): string;
+/**
+ * Quote one `ExecStart` word for systemd: `%` → `%%` (specifiers), `$` → `$$`
+ * (no variable expansion); words with whitespace, quotes or backslashes are
+ * wrapped in double quotes with C-style escaping.
+ */
+export declare function quoteSystemdArg(value: string): string;
+/** Validate unit options; throws {@link ValidationError}. */
+export declare function validateUnitOptions(opts: UnitOptions): void;
+/** Render the systemd unit file. Pure: same input → same output. */
+export declare function renderSystemdUnit(opts: UnitOptions): string;

package/dist/service/unit.js

@@ -0,0 +1,171 @@
+/**
+ * systemd unit generation (Spec §4, §14, §20.1) – pure functions.
+ *
+ * The unit starts a fixed, globally installed package version directly with
+ * absolute paths (`<node> <package>/dist/cli/main.js start …`), never through
+ * `npx`. Stop behaviour is aligned with the orchestrator's shutdown contract
+ * (docs/handoff/WI-08.md, docs/operations.md):
+ *
+ * - `KillMode=mixed`: `systemctl stop` sends SIGTERM only to the main process
+ *   (workers keep running while the orchestrator drains); after
+ *   `TimeoutStopSec` systemd SIGKILLs the whole cgroup including workers.
+ * - `TimeoutStopSec` = drain timeout + cancel timeout + max. `cancel_grace`
+ *   + buffer. The worker's SIGTERM → SIGKILL grace runs *inside* the cancel
+ *   timeout (after it, hooks are interrupted and the orchestrator exits), so
+ *   the grace term is only a safety margin; `cancel_grace` must be smaller
+ *   than the cancel timeout to be effective (the CLI warns otherwise).
+ * - `Restart=on-failure`: an orderly shutdown (API drain / cancel-all, SIGTERM)
+ *   exits with 0 and is not restarted; a crash (exit ≠ 0, signal) is.
+ *   Configuration/start errors exit with {@link EXIT_CONFIG} (78, EX_CONFIG),
+ *   excluded via `RestartPreventExitStatus=78` (no restart loop).
+ */
+import path from 'node:path';
+import { ValidationError } from '../core/index.js';
+/** Exit code of `start` for configuration/startup errors that a restart cannot fix (sysexits EX_CONFIG). */
+export const EXIT_CONFIG = 78;
+/** Default unit / service name. */
+export const DEFAULT_UNIT_NAME = 'adispatchd';
+/** Default dedicated service user (and group). */
+export const DEFAULT_SERVICE_USER = 'adispatchd';
+/** Default directory for unit files. */
+export const DEFAULT_UNIT_DIR = '/etc/systemd/system';
+/** Extra time on top of drain + cancel + grace before systemd kills the cgroup. */
+export const DEFAULT_STOP_BUFFER_MS = 60_000;
+const NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/;
+const USER_PATTERN = /^[a-z_][a-z0-9_-]{0,31}$/;
+/** `TimeoutStopSec` in whole seconds: drain + cancel + grace + buffer, rounded up. */
+export function computeTimeoutStopSec(opts) {
+    const total = opts.drainTimeoutMs + opts.cancelTimeoutMs + opts.maxCancelGraceMs + (opts.stopBufferMs ?? DEFAULT_STOP_BUFFER_MS);
+    return Math.ceil(total / 1000);
+}
+/** Duration in the CLI's own syntax (`10m`, `90s`, `1500ms`), parseable by `parseDuration`. */
+export function formatCliDuration(ms) {
+    if (!Number.isSafeInteger(ms) || ms < 0)
+        throw new ValidationError(`Invalid duration ${ms}`);
+    if (ms === 0)
+        return '0s';
+    if (ms % 3_600_000 === 0)
+        return `${ms / 3_600_000}h`;
+    if (ms % 60_000 === 0)
+        return `${ms / 60_000}m`;
+    if (ms % 1000 === 0)
+        return `${ms / 1000}s`;
+    return `${ms}ms`;
+}
+/**
+ * Quote one `ExecStart` word for systemd: `%` → `%%` (specifiers), `$` → `$$`
+ * (no variable expansion); words with whitespace, quotes or backslashes are
+ * wrapped in double quotes with C-style escaping.
+ */
+export function quoteSystemdArg(value) {
+    if (/[\0\n\r]/.test(value))
+        throw new ValidationError('Unit values must not contain NUL or line breaks');
+    const escaped = value.replace(/%/g, '%%').replace(/\$/g, '$$$$');
+    if (escaped !== '' && !/[\s"'\\;]/.test(escaped))
+        return escaped;
+    return `"${escaped.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Value for `key=value` lines that take a single path (escapes specifiers). */
+function pathValue(value) {
+    if (/[\0\n\r]/.test(value))
+        throw new ValidationError('Unit values must not contain NUL or line breaks');
+    return value.replace(/%/g, '%%');
+}
+function assertAbsolute(label, p) {
+    if (!path.isAbsolute(p))
+        throw new ValidationError(`${label} must be an absolute path (got "${p}")`);
+}
+/** Validate unit options; throws {@link ValidationError}. */
+export function validateUnitOptions(opts) {
+    if (!NAME_PATTERN.test(opts.unitName))
+        throw new ValidationError(`Invalid unit name "${opts.unitName}"`);
+    if (!USER_PATTERN.test(opts.user))
+        throw new ValidationError(`Invalid user name "${opts.user}"`);
+    if (!USER_PATTERN.test(opts.group))
+        throw new ValidationError(`Invalid group name "${opts.group}"`);
+    if (opts.user === 'root')
+        throw new ValidationError('The service must run as a dedicated user, not root (Spec §20.1)');
+    assertAbsolute('node path', opts.nodePath);
+    assertAbsolute('package entry point', opts.entryPath);
+    assertAbsolute('config dir', opts.configDir);
+    assertAbsolute('data dir', opts.dataDir);
+    if (opts.envFile !== null)
+        assertAbsolute('environment file', opts.envFile);
+    for (const [label, p] of [
+        ['node path', opts.nodePath],
+        ['package entry point', opts.entryPath],
+    ]) {
+        if (/(^|\/)(npx|_npx)(\/|$)/.test(p)) {
+            throw new ValidationError(`${label} "${p}" points into an npx cache – install a fixed version permanently (npm install -g adispatchd@<version>, or a tarball from npm pack) and run "service install" from there`);
+        }
+    }
+    if (/\.ts$/.test(opts.entryPath)) {
+        throw new ValidationError(`package entry point "${opts.entryPath}" is a TypeScript source – build the package (npm run build) or install it`);
+    }
+    for (const [label, ms] of [
+        ['drain timeout', opts.drainTimeoutMs],
+        ['cancel timeout', opts.cancelTimeoutMs],
+        ['cancel grace', opts.maxCancelGraceMs],
+    ]) {
+        if (!Number.isSafeInteger(ms) || ms < 0)
+            throw new ValidationError(`Invalid ${label} ${ms}`);
+    }
+}
+/** Render the systemd unit file. Pure: same input → same output. */
+export function renderSystemdUnit(opts) {
+    validateUnitOptions(opts);
+    const timeoutStopSec = computeTimeoutStopSec(opts);
+    const exec = [
+        opts.nodePath,
+        opts.entryPath,
+        'start',
+        '--config-dir',
+        opts.configDir,
+        '--data-dir',
+        opts.dataDir,
+        '--drain-timeout',
+        formatCliDuration(opts.drainTimeoutMs),
+        '--cancel-timeout',
+        formatCliDuration(opts.cancelTimeoutMs),
+    ]
+        .map(quoteSystemdArg)
+        .join(' ');
+    const lines = [
+        '# Generated by "adispatch service install". Changes are overwritten by the next install.',
+        '# Stop contract: SIGTERM drains (drain timeout), then cancels all runs (cancel timeout);',
+        `# TimeoutStopSec = drain ${formatCliDuration(opts.drainTimeoutMs)} + cancel ${formatCliDuration(opts.cancelTimeoutMs)} + grace margin ${formatCliDuration(opts.maxCancelGraceMs)} + buffer ${formatCliDuration(opts.stopBufferMs ?? DEFAULT_STOP_BUFFER_MS)}.`,
+        '# For planned stops/updates run "adispatch drain --wait" first (see docs/operations.md).',
+        '[Unit]',
+        `Description=${opts.description ?? 'Agent Dispatch Daemon'}`,
+        'After=network-online.target',
+        'Wants=network-online.target',
+        '',
+        '[Service]',
+        'Type=simple',
+        `User=${opts.user}`,
+        `Group=${opts.group}`,
+        `ExecStart=${exec}`,
+        `WorkingDirectory=${pathValue(opts.dataDir)}`,
+        ...(opts.envFile !== null ? [`EnvironmentFile=-${pathValue(opts.envFile)}`] : []),
+        'Environment=NODE_ENV=production',
+        // Orderly shutdown → exit 0 → no restart; crash → restart → recovery.
+        'Restart=on-failure',
+        'RestartSec=5s',
+        // Configuration/start errors (invalid YAML, instance lock held, newer DB schema): do not restart in a loop.
+        `RestartPreventExitStatus=${EXIT_CONFIG}`,
+        // SIGTERM only to the orchestrator; workers stay alive while it drains.
+        'KillMode=mixed',
+        'KillSignal=SIGTERM',
+        `TimeoutStopSec=${timeoutStopSec}`,
+        'UMask=0027',
+        'NoNewPrivileges=true',
+        'PrivateTmp=true',
+        'LimitNOFILE=65536',
+        '',
+        '[Install]',
+        'WantedBy=multi-user.target',
+        '',
+    ];
+    return lines.join('\n');
+}
+//# sourceMappingURL=unit.js.map

package/dist/service/unit.js.map

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

package/dist/sources/github/adapter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Source adapter `github` (Spec §5.2, §6, §10): issues and pull requests of
+ * one repository, native "blocked by" dependencies, labels and comments.
+ */
+import { type CommentRef, type FieldDefinition, type FieldResolution, type IdentityRef, type ListCandidatesOptions, type SourceAdapter, type SourceAdapterDeps, type SourceAdapterFactory, type SourceItem, type SourceUpdate, type SourceUpdateResult, type Timers } from '../../core/index.js';
+import { GitHubHttpClient, type GitHubHttpClientOptions } from './http.js';
+/** Adapter type name. */
+export declare const GITHUB_SOURCE_TYPE = "github";
+/** Validated configuration of one GitHub source (normalised, camelCase). */
+export interface GitHubSourceConfig {
+    owner: string;
+    repository: string;
+    /** Default identity for reads (and fallback for writes). */
+    identity: IdentityRef;
+    /** REST API base URL; default `https://api.github.com`. */
+    apiBaseUrl?: string;
+    /** Web base URL for parsing item references; default `https://github.com`. */
+    webBaseUrl?: string;
+}
+/** Subset of the GitHub issue JSON used by the adapter. */
+export interface GitHubIssueJson {
+    id?: number;
+    number: number;
+    title?: string;
+    state?: string;
+    html_url?: string;
+    repository_url?: string;
+    labels?: Array<{
+        name?: string;
+    } | string>;
+    assignees?: Array<{
+        login?: string;
+    }> | null;
+    user?: {
+        login?: string;
+    } | null;
+    pull_request?: unknown;
+    created_at?: string;
+    updated_at?: string;
+    repository?: {
+        full_name?: string;
+    } | null;
+    issue_dependencies_summary?: {
+        blocked_by?: number;
+        total_blocked_by?: number;
+    } | null;
+}
+/** Options beyond {@link SourceAdapterDeps}. */
+export interface GitHubAdapterOptions {
+    timers?: Timers;
+    /** Pre-built HTTP client (tests / sharing); otherwise one is created from deps. */
+    http?: GitHubHttpClient;
+    /** Extra HTTP client settings (retries, timeouts). */
+    httpOptions?: Partial<Omit<GitHubHttpClientOptions, 'fetch' | 'clock' | 'timers' | 'logger' | 'baseUrl'>>;
+}
+/** {@link SourceAdapter} for one GitHub repository. */
+export declare class GitHubSourceAdapter implements SourceAdapter {
+    readonly type = "github";
+    readonly sourceId: string;
+    readonly repository: string;
+    private readonly config;
+    private readonly http;
+    private readonly credentials;
+    private readonly logger;
+    private readonly repoPath;
+    constructor(sourceId: string, config: GitHubSourceConfig, deps: SourceAdapterDeps, options?: GitHubAdapterOptions);
+    fieldDefinitions(): readonly FieldDefinition[];
+    listCandidates(options?: ListCandidatesOptions): Promise<SourceItem[]>;
+    getItem(itemId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<SourceItem | null>;
+    parseItemRef(ref: string): string | null;
+    resolveFields(item: SourceItem, fields: readonly string[], options?: {
+        signal?: AbortSignal;
+    }): Promise<Record<string, FieldResolution>>;
+    applyUpdate(item: SourceItem, update: SourceUpdate, identity: IdentityRef): Promise<SourceUpdateResult>;
+    postComment(item: SourceItem, body: string, marker: string, identity: IdentityRef): Promise<CommentRef>;
+    findCommentByMarker(item: SourceItem, marker: string, identity: IdentityRef): Promise<CommentRef | null>;
+    /**
+     * Only comments written by the identity's own app count as carrying a
+     * marker; otherwise anybody could suppress an orchestrator comment by
+     * posting the marker. With a known app ID (CredentialProvider.describe) the
+     * comment must have `performed_via_github_app.id === appId`; without one,
+     * at least a bot author (`user.type === 'Bot'`) is required.
+     */
+    private authorPredicate;
+    private resolveDependencies;
+    private fetchIssue;
+    /** Run `fn` with a token; on 401 invalidate the cached token and retry once. */
+    private withToken;
+    private toItem;
+    private assertOwnItem;
+}
+/** Factory registered under type `github`. */
+export declare function createGitHubSourceFactory(options?: GitHubAdapterOptions): SourceAdapterFactory<GitHubSourceConfig>;
+/** Default factory (real timers). */
+export declare const githubSourceFactory: SourceAdapterFactory<GitHubSourceConfig>;
+/** Render the HTML comment that carries an idempotency marker. */
+export declare function renderMarker(marker: string): string;