@wardby/cli 0.2.1 → 0.4.0

package/dist/providers/issue-tracker/types.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Host-neutral issue-tracker surface for native agents. Jira Cloud is the
+ * first implementation (./jira.ts). The control plane holds the credential;
+ * no method takes a token. See docs/private/2026-09-30-jira-issue-tracker-design.md.
+ */
+export type IssueTrackerProvider = "jira";
+export declare const ISSUE_TRACKER_PROVIDERS: readonly IssueTrackerProvider[];
+/** The product name shown to people (e.g. in a pull request's "Resolves Jira issue …" line). */
+export declare const ISSUE_TRACKER_NAMES: Readonly<Record<IssueTrackerProvider, string>>;
+export interface IssuePerson {
+    accountId: string;
+    displayName: string;
+}
+export interface IssueCommentView {
+    id: string;
+    author: IssuePerson | null;
+    created: string;
+    body: string;
+    /** Written by the bot and carrying this agent's footer: editable with jira_edit_own_comment. */
+    byThisAgent: boolean;
+}
+export interface IssueView {
+    key: string;
+    projectKey: string;
+    summary: string;
+    description: string;
+    status: string;
+    /** The status's category (Jira statusCategory.key): "done" is what dedupe treats as resolved. */
+    statusCategory: IssueStatusCategory;
+    issueType: string;
+    priority: string | null;
+    labels: string[];
+    assignee: IssuePerson | null;
+    reporter: IssuePerson | null;
+    url: string;
+    /** Most recent last; capped. */
+    comments: IssueCommentView[];
+    commentsTruncated: boolean;
+    /** Capped list; contents are read with readAttachmentText. Filenames are untrusted. */
+    attachments: IssueAttachmentView[];
+    /** Issue links (e.g. "relates to PROJ-9"), capped. Summaries are untrusted issue text. */
+    links: IssueLinkView[];
+}
+export interface IssueLinkView {
+    /** How this issue relates to the other, as Jira words it from this side ("relates to", "is blocked by"). */
+    relation: string;
+    key: string;
+    summary: string;
+    status: string;
+}
+export type IssueStatusCategory = "new" | "indeterminate" | "done";
+export interface IssueAttachmentView {
+    id: string;
+    filename: string;
+    mimeType: string;
+    size: number;
+}
+export interface CreateIssueInput {
+    projectKey: string;
+    /** Issue type name (case-insensitive); resolved to an id from the project's create metadata. */
+    issueType: string;
+    summary: string;
+    descriptionMarkdown: string;
+    labels?: string[];
+    /** Priority name. */
+    priority?: string;
+    /** Component names. */
+    components?: string[];
+    parentKey?: string;
+    /** customfield_N -> raw JSON value. */
+    customFields?: Record<string, unknown>;
+    /** Issue properties, set in the create call itself. */
+    properties?: Record<string, unknown>;
+    /** Projects whose bare issue keys in the description become smart links. */
+    issueKeyProjects?: readonly string[];
+}
+export interface CreateMetaIssueType {
+    id: string;
+    name: string;
+    subtask: boolean;
+}
+export interface CreateMetaField {
+    fieldId: string;
+    name: string;
+    required: boolean;
+    hasDefault: boolean;
+    allowedValues?: string[];
+}
+export interface IssueSearchHit {
+    key: string;
+    summary: string;
+    status: string;
+    issueType: string;
+    updated: string;
+    url: string;
+}
+export interface IssueSearchResult {
+    issues: IssueSearchHit[];
+    truncated: boolean;
+}
+/** Who the tracker credential acts as (Jira: GET /myself). */
+export interface IssueTrackerIdentity {
+    accountId: string;
+    displayName: string;
+    accountType: string;
+}
+/**
+ * Bounds one tracker call for callers on a latency budget (e.g. inside a database transaction).
+ * `timeoutMs` caps the WHOLE call, every request it makes included; with `retryOn429: false` a 429 fails
+ * at once instead of sleeping for Retry-After, so the call cannot outlive `timeoutMs`.
+ */
+export interface TrackerCallOptions {
+    timeoutMs?: number;
+    retryOn429?: boolean;
+}
+/** What cost attribution keeps about an issue (src/core/attribution.ts): the hierarchy as of now. */
+export interface IssueSnapshot {
+    /** The key that was asked for (WorkItem.key). */
+    key: string;
+    title?: string;
+    type?: string;
+    url: string;
+    /** The project (Jira) / team (Linear) the issue is in now. */
+    scopeKey: string;
+    parent?: {
+        key: string;
+        title?: string;
+        kind: string;
+    };
+}
+export interface IssueTracker {
+    readonly provider: IssueTrackerProvider;
+    /** The bot's own accountId (cached after the first call). */
+    botAccountId(): Promise<string>;
+    /** The account the credential acts as, from the same cached call as botAccountId. */
+    identity(): Promise<IssueTrackerIdentity>;
+    getIssue(key: string, opts: {
+        maxComments: number;
+        agentMarker: string;
+    } & TrackerCallOptions): Promise<IssueView>;
+    /** The project the issue is in now; an old key (kept as an alias after a move) resolves to its new project. */
+    issueProject(key: string): Promise<string>;
+    /** Title, type, scope and parent of `key` in one call, for cost attribution. Throws IssueTrackerError. */
+    snapshotIssue(key: string, opts?: {
+        timeoutMs?: number;
+        retryOn429?: boolean;
+    }): Promise<IssueSnapshot>;
+    search(jql: string, opts: {
+        maxResults: number;
+    }): Promise<IssueSearchResult>;
+    /** Whether issue `key` matches `jql` (used for a link's jqlFilter). Callers on a latency budget pass a short timeout and no 429 retry. */
+    matchesJql(key: string, jql: string, opts?: TrackerCallOptions): Promise<boolean>;
+    comment(key: string, 
+    /** issueKeyProjects: projects whose bare issue keys in the text become smart links. */
+    input: {
+        markdown: string;
+        visibilityRole?: string;
+        issueKeyProjects?: readonly string[];
+    }, opts?: TrackerCallOptions): Promise<{
+        id: string;
+        url: string;
+    }>;
+    editComment(key: string, commentId: string, input: {
+        markdown: string;
+        issueKeyProjects?: readonly string[];
+    }): Promise<void>;
+    /** The comment's author accountId and plain text (uncapped: only for ownership checks, never shown to a model), or null when it doesn't exist. */
+    readComment(key: string, commentId: string): Promise<{
+        authorId: string | null;
+        body: string;
+    } | null>;
+    issueUrl(key: string): string;
+    /** Transitions the service account can perform now: target status name + category. */
+    transitions(key: string): Promise<Array<{
+        id: string;
+        name: string;
+        toStatus: string;
+        toCategory: string;
+    }>>;
+    /** Performs the transition whose target status name matches (case-insensitive). */
+    transitionTo(key: string, toStatus: string): Promise<{
+        transitionId: string;
+        toStatus: string;
+    }>;
+    /** Field ids the service account may edit on this issue (from editmeta). */
+    editableFields(key: string): Promise<string[]>;
+    /** Sets fields: labels (string[]), components (names), priority (name), customfield_N (raw JSON value). */
+    editFields(key: string, fields: Record<string, unknown>): Promise<void>;
+    linkTypes(opts?: TrackerCallOptions): Promise<Array<{
+        name: string;
+        inward: string;
+        outward: string;
+    }>>;
+    linkIssues(input: {
+        type: string;
+        inwardKey: string;
+        outwardKey: string;
+    }, opts?: TrackerCallOptions): Promise<void>;
+    /** Adds (or, for an existing globalId, updates) a web link on the issue: Jira's remote link, shown under "Web links". */
+    addRemoteLink(key: string, input: {
+        globalId: string;
+        url: string;
+        title: string;
+        status?: {
+            resolved: boolean;
+        };
+    }): Promise<void>;
+    /** The property's JSON value, or null when it does not exist. */
+    getProperty(key: string, property: string): Promise<unknown>;
+    setProperty(key: string, property: string, value: unknown): Promise<void>;
+    /** Issue types creatable in the project by the service account. */
+    createMeta(projectKey: string): Promise<{
+        issueTypes: CreateMetaIssueType[];
+    }>;
+    /** Create-screen fields for one issue type (by id). */
+    fieldMeta(projectKey: string, issueTypeId: string): Promise<CreateMetaField[]>;
+    /** Creates an issue; missing required fields (without defaults) fail with tracker_invalid_request naming them. */
+    createIssue(input: CreateIssueInput, opts?: TrackerCallOptions): Promise<{
+        key: string;
+        url: string;
+    }>;
+    /** First `maxBytes` of a text-like attachment, decoded as UTF-8; other types fail with tracker_invalid_request. */
+    readAttachmentText(id: string, maxBytes: number): Promise<{
+        filename: string;
+        mimeType: string;
+        text: string;
+        truncated: boolean;
+    }>;
+}
+export type IssueTrackerErrorCode = "tracker_not_found" | "tracker_permission_denied" | "tracker_rate_limited" | "tracker_invalid_request" | "tracker_api_error" | "tracker_invalid_response";
+export declare class IssueTrackerError extends Error {
+    readonly code: IssueTrackerErrorCode;
+    constructor(code: IssueTrackerErrorCode, message?: string);
+}
+export type IssueTrackerRegistry = Partial<Record<IssueTrackerProvider, IssueTracker>>;
+export type IssueEventKind = "created" | "transitioned" | "labeled" | "assigned" | "mention";
+/** What a webhook adapter (jira-events.ts) normalises a payload into, for src/core/issue-events.ts. */
+export interface IssueEvent {
+    provider: IssueTrackerProvider;
+    projectKey: string;
+    issueKey: string;
+    /** Every kind this one delivery represents (an update can transition AND label). */
+    kinds: IssueEventKind[];
+    actor: {
+        accountId: string;
+        displayName: string;
+    };
+    /** The new status name, with "transitioned". */
+    toStatus?: string;
+    /** Labels added by this change, with "labeled". */
+    addedLabels: string[];
+    /** The new assignee's accountId, with "assigned". */
+    assigneeAccountId?: string;
+    /** The mentioning comment, with "mention". */
+    comment?: {
+        id: string;
+        body: string;
+    };
+    /** Untrusted: whoever wrote them was not gated. Absent when the payload lacked the issue. */
+    subject?: {
+        summary: string;
+        description: string;
+    };
+}
+/** Shared by the ingress and the tools: a Jira issue key, e.g. PROJ-123. */
+export declare const ISSUE_KEY: RegExp;
+/** A Jira project key. */
+export declare const PROJECT_KEY: RegExp;
+export declare const projectOf: (issueKey: string) => string;

package/dist/providers/issue-tracker/types.js

@@ -0,0 +1,16 @@
+export const ISSUE_TRACKER_PROVIDERS = ["jira"];
+/** The product name shown to people (e.g. in a pull request's "Resolves Jira issue …" line). */
+export const ISSUE_TRACKER_NAMES = { jira: "Jira" };
+export class IssueTrackerError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = "IssueTrackerError";
+    }
+}
+/** Shared by the ingress and the tools: a Jira issue key, e.g. PROJ-123. */
+export const ISSUE_KEY = /^[A-Z][A-Z0-9_]{0,254}-[1-9]\d{0,9}$/;
+/** A Jira project key. */
+export const PROJECT_KEY = /^[A-Z][A-Z0-9_]{0,254}$/;
+export const projectOf = (issueKey) => issueKey.slice(0, issueKey.lastIndexOf("-"));

package/dist/providers/jobs/claude-tool-setup.d.ts

@@ -0,0 +1,23 @@
+import type { JobSpec } from "./types.js";
+/**
+ * The tool runner's parseToolSetup bounds (src/claude-tool-runner/command.mjs; a test keeps them
+ * equal). A setup past any of them would stop the tool runner before it reports ready, so the
+ * launcher refuses to build one instead.
+ */
+export declare const CLAUDE_TOOL_SETUP_LIMITS: {
+    readonly maxEnvEntries: 1024;
+    readonly maxEnvValueBytes: 4096;
+    readonly maxFiles: 8;
+    readonly maxFileBytes: number;
+    readonly maxSetupBytes: number;
+};
+export interface ClaudeToolSetup {
+    schemaVersion: 1;
+    env: Record<string, string>;
+    files: {
+        path: string;
+        content: string;
+        mode: number;
+    }[];
+}
+export declare function claudeToolSetup(spec: JobSpec, capability: string): string;

package/dist/providers/jobs/claude-tool-setup.js

@@ -0,0 +1,50 @@
+/**
+ * What Claude Code's tool runner (the credential-free container that runs commands in the
+ * repository) needs from the trusted launcher: the package-registry settings every Codex shell
+ * gets, built from the run's registry-only token (deriveRegistryToken, never the capability), and
+ * the run's service test variables. Delivered as CLAUDE_TOOL_SETUP_ENV: a Kubernetes Secret key, or
+ * `docker create --env NAME` with the value in the CLI's own environment.
+ */
+import { serviceEnvironment } from "../../coding-worker/driver.js";
+import { registryWorkerSetup } from "../../coding/registry/worker-config.js";
+import { CODING_PROXY_ALIAS, CODING_PROXY_PORT } from "./docker-isolation.js";
+/** Where the tool runner mounts the repository; the registry's config files live under its .cache. */
+const TOOL_WORKSPACE = "/workspace";
+/**
+ * The tool runner's parseToolSetup bounds (src/claude-tool-runner/command.mjs; a test keeps them
+ * equal). A setup past any of them would stop the tool runner before it reports ready, so the
+ * launcher refuses to build one instead.
+ */
+export const CLAUDE_TOOL_SETUP_LIMITS = {
+    maxEnvEntries: 1024,
+    maxEnvValueBytes: 4096,
+    maxFiles: 8,
+    maxFileBytes: 16 * 1024,
+    maxSetupBytes: 96 * 1024,
+};
+export function claudeToolSetup(spec, capability) {
+    if (spec.provider !== "claude-code")
+        throw new Error("claude_tool_setup_provider");
+    const registry = registryWorkerSetup({
+        proxyBaseUrl: `http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
+        capability,
+        cacheRoot: `${TOOL_WORKSPACE}/.cache`,
+    });
+    const setup = {
+        schemaVersion: 1,
+        // Same precedence as the Codex driver: the registry's own settings win over a service's.
+        env: { ...serviceEnvironment(spec.services), ...registry.env },
+        files: registry.files,
+    };
+    const raw = JSON.stringify(setup);
+    const limits = CLAUDE_TOOL_SETUP_LIMITS;
+    const entries = Object.values(setup.env);
+    if (entries.length > limits.maxEnvEntries ||
+        entries.some((value) => Buffer.byteLength(value) > limits.maxEnvValueBytes) ||
+        setup.files.length > limits.maxFiles ||
+        setup.files.some((file) => Buffer.byteLength(file.content) > limits.maxFileBytes) ||
+        Buffer.byteLength(raw) > limits.maxSetupBytes) {
+        throw new Error("claude_tool_setup_too_large");
+    }
+    return raw;
+}

package/dist/providers/jobs/collect-prune.d.ts

@@ -0,0 +1,7 @@
+import { type CollectExclusions } from "../../coding/collect-exclude.js";
+/**
+ * Deletes every excluded path from a staging copy of a workspace before it is
+ * validated. Walks with lstat and never descends through a symlink; `rm` removes
+ * a symlink itself, not its target.
+ */
+export declare function pruneCollectExcluded(root: string, exclusions: CollectExclusions): Promise<void>;

package/dist/providers/jobs/collect-prune.js

@@ -0,0 +1,27 @@
+import { lstat, opendir, rm } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { isCollectExcluded } from "../../coding/collect-exclude.js";
+/**
+ * Deletes every excluded path from a staging copy of a workspace before it is
+ * validated. Walks with lstat and never descends through a symlink; `rm` removes
+ * a symlink itself, not its target.
+ */
+export async function pruneCollectExcluded(root, exclusions) {
+    const visit = async (directory) => {
+        const handle = await opendir(directory);
+        const children = [];
+        for await (const entry of handle)
+            children.push(join(directory, entry.name));
+        for (const child of children) {
+            const relativePath = relative(root, child).split(sep).join("/");
+            if (isCollectExcluded(relativePath, exclusions)) {
+                await rm(child, { recursive: true, force: true });
+                continue;
+            }
+            const metadata = await lstat(child);
+            if (metadata.isDirectory() && !metadata.isSymbolicLink())
+                await visit(child);
+        }
+    };
+    await visit(root);
+}

package/dist/providers/jobs/docker-isolation.d.ts

@@ -1,8 +1,22 @@
+import type { CodingProvider } from "../../coding/provider.js";
 import type { JobSpec } from "./types.js";
 export declare const CODING_WORKER_UID = 10001;
 export declare const CODING_WORKER_GID = 10001;
+/**
+ * The network keeper (a run with services only): owns the run's network namespace so each
+ * service and the worker can share it with `--network container:`, as a pod's containers do.
+ */
+export declare const NETWORK_KEEPER_PIDS_LIMIT = 32;
+export declare const NETWORK_KEEPER_MEMORY_MB = 64;
+/** Idles until stopped, on the worker image's own `node` (every worker image ships it for the storage keeper). */
+export declare const NETWORK_KEEPER_SCRIPT = "process.once('SIGTERM', () => process.exit(0)); setInterval(() => {}, 2147483647);";
 export declare const CODING_PROXY_ALIAS = "wardby-proxy";
 export declare const CODING_PROXY_PORT = 8787;
+/**
+ * The one variable Claude's tool runner receives: its package-registry and service settings as JSON
+ * (claude-tool-setup.ts). Never the run capability.
+ */
+export declare const CLAUDE_TOOL_SETUP_ENV = "WARDBY_TOOL_SETUP";
 /**
  * The proxy's deny port. Nothing is served here (see coding-proxy/deny-port.ts);
  * it is the enforcement witness — the one destination a run's NetworkPolicy must
@@ -25,6 +39,7 @@ export interface DockerIsolationNames {
     keeperContainer: string;
     workerContainer: string;
     toolContainer: string;
+    networkKeeperContainer: string;
 }
 export interface DockerIsolationPlan {
     names: DockerIsolationNames;
@@ -35,6 +50,8 @@ export interface DockerIsolationPlan {
     keeperCreateArgs: string[];
     workerCreateArgs: string[];
     toolCreateArgs?: string[];
+    /** Present only for a run with services (docs/coding-services.md). */
+    networkKeeperCreateArgs?: string[];
     proxyNetworkConnectArgs: string[];
 }
 export interface DockerHostInfo {
@@ -70,11 +87,14 @@ export interface DockerVolumeInspection {
     Options?: Record<string, string>;
 }
 export interface DockerContainerInspection {
+    Id?: string;
     Config?: {
         Env?: string[];
         User?: string;
         Image?: string;
         Labels?: Record<string, string>;
+        Entrypoint?: string[] | null;
+        Cmd?: string[] | null;
     };
     HostConfig?: {
         AutoRemove?: boolean;
@@ -140,18 +160,42 @@ export interface DockerContainerInspection {
         Ports?: Record<string, unknown>;
     };
 }
+/**
+ * Which runs the Docker launcher starts services for: Codex and Claude Code. The container that runs
+ * the run's commands (Codex's worker, Claude Code's tool runner) joins the network keeper's
+ * namespace and reaches the services on 127.0.0.1; Claude Code's agent stays on the run network.
+ */
+export declare function dockerSupportsServicesFor(provider: CodingProvider): boolean;
 /** A registry digest reference (`[host[:port]/]path@sha256:<64 hex>`); no local image IDs, no tags. */
 export declare function isRepositoryDigest(image: string): boolean;
 /** Accepts a registry digest or Docker's content-addressed local image ID. */
 export declare function isImmutableDockerImage(image: string): boolean;
+/** The opaque per-run token in every Docker object name; never the run ID itself. */
+export declare function isolationToken(runId: string): string;
 export declare function isolationNames(runId: string): DockerIsolationNames;
+/** The fixed isolation labels every run object carries (docker-services.ts builds with them). */
+export declare function isolationLabelArgs(runId: string): string[];
+export declare function hasIsolationLabels(labels: Record<string, string> | undefined, runId: string): boolean;
 export declare function buildIsolationNetworkCreateArgs(runId: string): string[];
 export declare function buildStorageVolumeCreateArgs(spec: JobSpec): string[];
 export declare function buildKeeperCreateArgs(spec: JobSpec): string[];
+export declare function buildNetworkKeeperCreateArgs(spec: JobSpec): string[];
 export declare function buildWorkerCreateArgs(spec: JobSpec, proxyPort?: number): string[];
+export declare function claudeToolLimits(spec: JobSpec): {
+    cpus: number;
+    memoryMb: number;
+    pids: number;
+};
 /** The Claude agent sees the task/result and socket, never the repository workspace. */
 export declare function buildClaudeAgentCreateArgs(spec: JobSpec, proxyPort?: number): string[];
-/** The tool runner receives only the checkout and socket; it never joins the proxy network. */
+/**
+ * The tool runner receives only the checkout and its own storage subpath; it shares the run's
+ * proxy network with the agent (one room) but holds no capability, so the proxy grants it only
+ * registry access via its own WARDBY_TOOL_SETUP value. For a run with services it joins the network
+ * keeper's namespace instead, which is on that same run network: it reaches the proxy by its alias
+ * and the services on 127.0.0.1, and nothing else. It talks to the agent over the Unix socket in
+ * their shared `tool` storage subpath, which does not depend on either container's network.
+ */
 export declare function buildClaudeToolRunnerCreateArgs(spec: JobSpec): string[];
 export declare function buildProxyNetworkConnectArgs(runId: string, proxyContainer: string): string[];
 export declare function buildDockerIsolationPlan(spec: JobSpec, proxyContainer: string): DockerIsolationPlan;
@@ -160,7 +204,8 @@ export declare function assertIsolationNetworkInspection(network: DockerNetworkI
 export declare function assertIsolationNetworkParticipants(network: DockerNetworkInspection, expectedContainerNames: string[]): void;
 export declare function assertStorageVolumeInspection(volume: DockerVolumeInspection, spec: JobSpec): void;
 export declare function assertKeeperContainerInspection(container: DockerContainerInspection, spec: JobSpec): void;
+export declare function assertNetworkKeeperContainerInspection(container: DockerContainerInspection, spec: JobSpec): void;
 export declare function assertProxyContainerInspection(container: DockerContainerInspection, runId: string): void;
-export declare function assertWorkerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string): void;
+export declare function assertWorkerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string, networkKeeperId?: string): void;
 export declare function assertClaudeAgentContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedCapability: string): void;
-export declare function assertClaudeToolRunnerContainerInspection(container: DockerContainerInspection, spec: JobSpec): void;
+export declare function assertClaudeToolRunnerContainerInspection(container: DockerContainerInspection, spec: JobSpec, expectedSetup: string, networkKeeperId?: string): void;