@wardby/cli 0.3.0 → 0.4.1

package/dist/providers/review-host/github-events.js

@@ -7,6 +7,10 @@ import { normalizeGitHubRepository } from "../../coding/protocol.js";
 const PR_ACTIONS = new Set(["opened", "synchronize", "reopened", "ready_for_review"]);
 const TRUSTED_ASSOCIATIONS = new Set(["OWNER", "MEMBER", "COLLABORATOR"]);
 const SAFE_SHA = /^[0-9a-f]{40}$/;
+// GitHub's push payload includes at most 2048 commits.
+const PUSH_MAX_COMMITS = 2048;
+const SAFE_BRANCH = /^[A-Za-z0-9._/-]{1,100}$/;
+const PUSH_MAX_PATHS = 1000;
 /** Mirrors the runId shape validated in providers/vcs (github.ts, git.ts). */
 const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 /** The hidden marker a coding run writes at the top of every PR it opens (providers/vcs/github.ts); legacy prefix too. */
@@ -75,10 +79,52 @@ export function normalizeGitHubEvent(eventName, payload, app) {
     const repository = repositoryOf(p);
     if (!repository)
         return null;
+    if (eventName === "push") {
+        const defaultBranch = obj(p.repository)?.default_branch;
+        const { before, after } = p;
+        if (typeof defaultBranch !== "string" || !SAFE_BRANCH.test(defaultBranch))
+            return null;
+        if (p.ref !== `refs/heads/${defaultBranch}` || p.deleted === true)
+            return null;
+        if (typeof before !== "string" || typeof after !== "string")
+            return null;
+        if (!SAFE_SHA.test(before) || !SAFE_SHA.test(after) || /^0+$/.test(after))
+            return null;
+        const commits = Array.isArray(p.commits) ? p.commits : [];
+        const paths = new Set();
+        for (const commit of commits) {
+            const c = obj(commit);
+            for (const list of [c?.added, c?.modified, c?.removed]) {
+                if (Array.isArray(list))
+                    for (const path of list)
+                        if (typeof path === "string")
+                            paths.add(path);
+            }
+        }
+        return {
+            kind: "push",
+            provider: "github",
+            repository,
+            branch: defaultBranch,
+            before,
+            after,
+            changedPaths: [...paths].sort().slice(0, PUSH_MAX_PATHS),
+            // GitHub includes at most 2048 commits, so a full list may be truncated.
+            changedPathsComplete: commits.length < PUSH_MAX_COMMITS && paths.size <= PUSH_MAX_PATHS,
+        };
+    }
     if (eventName === "pull_request") {
+        const pr = obj(p.pull_request);
+        if (p.action === "closed") {
+            // No author or fork gate: this only marks issue/PR pairs wardby itself
+            // recorded for this repository and number, never acting on PR text.
+            const prNumber = int(pr?.number);
+            if (!prNumber)
+                return null;
+            return { kind: "pr_closed", provider: "github", repository, prNumber, merged: pr?.merged === true };
+        }
         if (typeof p.action !== "string" || !PR_ACTIONS.has(p.action))
             return null;
-        const pr = obj(p.pull_request);
         const head = obj(pr?.head);
         const prNumber = int(pr?.number);
         const headSha = head?.sha;

package/dist/providers/review-host/github.js

@@ -335,6 +335,7 @@ export class GitHubReviewHost {
                 endLine: window.startLine + slice.length - 1,
                 truncated: window.startLine - 1 + slice.length < lines.length,
                 content: slice.map((line, i) => `${window.startLine + i}: ${line}`).join("\n"),
+                text: slice.join("\n"),
             };
         });
     }
@@ -343,15 +344,15 @@ export class GitHubReviewHost {
         return this.withToken(repository, { contents: "read" }, async (get) => {
             const resolvedRef = ref ?? str(record(await (await get(base)).json()).default_branch);
             const tree = record(await (await get(`${base}/git/trees/${encodeURIComponent(resolvedRef)}?recursive=1`)).json());
-            const files = list(tree.tree)
+            const entries = list(tree.tree)
                 .filter((e) => e.type === "blob" && typeof e.path === "string" && e.path.startsWith(pathPrefix))
-                .filter((e) => !VENDORED.test(str(e.path)) && !str(e.path).endsWith("package-lock.json"))
-                .map((e) => `${str(e.path)} (${num(e.size)} bytes)`);
+                .filter((e) => !VENDORED.test(str(e.path)) && !str(e.path).endsWith("package-lock.json"));
             return {
                 ref: resolvedRef,
-                count: files.length,
-                truncated: tree.truncated === true || files.length > MAX_LISTED_FILES,
-                files: files.slice(0, MAX_LISTED_FILES),
+                count: entries.length,
+                truncated: tree.truncated === true || entries.length > MAX_LISTED_FILES,
+                files: entries.slice(0, MAX_LISTED_FILES).map((e) => `${str(e.path)} (${num(e.size)} bytes)`),
+                paths: entries.slice(0, MAX_LISTED_FILES).map((e) => str(e.path)),
             };
         });
     }

package/dist/providers/review-host/types.d.ts

@@ -70,7 +70,10 @@ export type FileReadResult = {
     startLine: number;
     endLine: number;
     truncated: boolean;
+    /** The window with `N: ` line-number prefixes: the display form shown to agents. */
     content: string;
+    /** The same window without line-number prefixes, lines joined by "\n": for machine parsing. */
+    text: string;
 } | {
     kind: "directory";
     path: string;
@@ -83,7 +86,10 @@ export interface FileListView {
     ref: string;
     count: number;
     truncated: boolean;
+    /** Display strings (path plus size) shown to agents. */
     files: string[];
+    /** Bare repository paths, same order and length as `files`. */
+    paths: string[];
 }
 export interface InlineComment {
     path: string;
@@ -247,12 +253,31 @@ export type HostUserAuthorizerRegistry = Partial<Record<ReviewHostProvider, Host
  * provider payload into, for src/core/host-events.ts to route.
  */
 export type HostEvent = {
+    kind: "push";
+    provider: ReviewHostProvider;
+    repository: string;
+    /** The branch pushed (without refs/heads/), always the repository's default branch. */
+    branch: string;
+    before: string;
+    after: string;
+    /** Union of added/modified/removed paths over the payload's commits, deduplicated, at most 1000. */
+    changedPaths: string[];
+    /** False when GitHub truncated the commit list (> 20 commits) or paths were capped: treat every concept as in scope. */
+    changedPathsComplete: boolean;
+} | {
     kind: "pr_updated";
     provider: ReviewHostProvider;
     repository: string;
     prNumber: number;
     headSha: string;
     isFork: boolean;
+} | {
+    /** The PR was merged or closed; only drives bookkeeping on issue/PR pairs wardby recorded. */
+    kind: "pr_closed";
+    provider: ReviewHostProvider;
+    repository: string;
+    prNumber: number;
+    merged: boolean;
 } | {
     kind: "check_rerun";
     provider: ReviewHostProvider;

package/dist/providers/vcs/git.js

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { gitExcludePathspecs, normalizeCollectExclusions } from "../../coding/collect-exclude.js";
 import { WARDBY_PROTECTED_PATHS, isProtectedPathException, isWellFormedProtectedPath, protectedPathBody, protectsSomePath, } from "../../coding/protected-paths.js";
 import { ensurePrivateDirectory } from "../../core/private-directory.js";
+import { globRegex } from "../../core/glob.js";
 import { MAX_REDACTED_SPAN, redactTokenShapedValues, normalizeGitHubRepository, normalizeGitRef, } from "../../coding/protocol.js";
 import { isSafeGitHubInstallationToken } from "./github.js";
 export const DEFAULT_MAX_CHANGED_FILES = 1_000;
@@ -149,28 +150,6 @@ function validateProtectedPath(value) {
     }
     return path;
 }
-function globRegex(pattern) {
-    let source = "^";
-    for (let index = 0; index < pattern.length; index += 1) {
-        const character = pattern[index];
-        if (character === "*") {
-            if (pattern[index + 1] === "*") {
-                source += ".*";
-                index += 1;
-            }
-            else {
-                source += "[^/]*";
-            }
-        }
-        else if (character === "?") {
-            source += "[^/]";
-        }
-        else {
-            source += character.replace(/[|\\{}()[\]^$+?.]/g, "\\$&");
-        }
-    }
-    return new RegExp(`${source}$`);
-}
 /** The fixed baseline, split once: its literal exceptions and its protected globs. */
 const WARDBY_UNPROTECTED = new Set(WARDBY_PROTECTED_PATHS.filter(isProtectedPathException).map(protectedPathBody));
 const WARDBY_PROTECTED = WARDBY_PROTECTED_PATHS.filter((pattern) => !isProtectedPathException(pattern)).map((pattern) => globRegex(pattern));
@@ -458,6 +437,7 @@ export class GitVcsProvider {
             tag: details?.tag,
             packages: details?.packages,
             packageRefusals: details?.packageRefusals,
+            ...(details?.issue ? { issue: details.issue } : {}),
         });
         return {
             outcome: prepared.continuation ? "pull_request_updated" : "pull_request_opened",

package/dist/providers/vcs/github.d.ts

@@ -40,6 +40,19 @@ export interface PullRequestInput {
      * draft either way; unset (a fresh run), only a draft PR is accepted.
      */
     acceptReadyForReview?: boolean;
+    /**
+     * The originating issue-tracker issue (control-plane data, never model
+     * output). Provider-neutral: the title gets a `[KEY] ` prefix and the body a
+     * first line linking it ("Resolves <trackerName> issue …"). The key is
+     * re-validated here, a non-https `url` is dropped, and so is a `trackerName`
+     * that isn't a short plain name. The PR lookup keys on the hidden run
+     * marker, never the title.
+     */
+    issue?: {
+        key: string;
+        url?: string;
+        trackerName?: string;
+    };
 }
 export interface PullRequestResult {
     number: number;
@@ -95,6 +108,13 @@ export interface GitHubRepositoryAccess {
 type Fetch = typeof globalThis.fetch;
 /** Accepts bounded opaque installation tokens without allowing control characters. */
 export declare function isSafeGitHubInstallationToken(value: unknown): value is string;
+/**
+ * Same shape as ISSUE_KEY (issue-tracker/types.ts); duplicated so the VCS layer
+ * stays free of issue-tracker imports (a test keeps the two in step). The
+ * executor validates with the shared one.
+ */
+export declare const PR_ISSUE_KEY: RegExp;
+export declare function pullRequestTitle(input: PullRequestInput): string;
 /** At most this many packages, and separately this many refusals, are listed
  *  in a PR body; the rest are counted in a "…and N more" line pointing at
  *  get_run, which returns the full list. */

package/dist/providers/vcs/github.js

@@ -33,8 +33,30 @@ export function isSafeGitHubInstallationToken(value) {
         Buffer.byteLength(value, "utf8") <= 512 &&
         /^[A-Za-z0-9._-]+$/.test(value));
 }
-function pullRequestTitle(input) {
-    return input.tag ? `[${input.tag}] Wardby run ${input.runId}` : `Wardby run ${input.runId}`;
+/**
+ * Same shape as ISSUE_KEY (issue-tracker/types.ts); duplicated so the VCS layer
+ * stays free of issue-tracker imports (a test keeps the two in step). The
+ * executor validates with the shared one.
+ */
+export const PR_ISSUE_KEY = /^[A-Z][A-Z0-9_]{0,254}-[1-9]\d{0,9}$/;
+/** The issue key when it is well-formed; a malformed one is dropped everywhere it would be rendered. */
+function validIssueKey(input) {
+    const key = input.issue?.key;
+    return typeof key === "string" && PR_ISSUE_KEY.test(key) ? key : undefined;
+}
+export function pullRequestTitle(input) {
+    const base = input.tag ? `[${input.tag}] Wardby run ${input.runId}` : `Wardby run ${input.runId}`;
+    const key = validIssueKey(input);
+    return key ? `[${key}] ${base}` : base;
+}
+function issueLine(input) {
+    const key = validIssueKey(input);
+    const url = input.issue?.url;
+    if (!key || typeof url !== "string" || !url.startsWith("https://") || /[\s<>()]/.test(url))
+        return undefined;
+    const name = input.issue?.trackerName;
+    const tracker = typeof name === "string" && /^[A-Za-z][A-Za-z0-9 .-]{0,39}$/.test(name) ? `${name.trim()} ` : "";
+    return `Resolves ${tracker}issue [${key}](${url})`;
 }
 /**
  * Package names/versions/reasons come from registry metadata, not from
@@ -103,6 +125,10 @@ function packagesSection(input) {
 /** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
 export function pullRequestBody(input) {
     const sections = [`${RUN_MARKER_PREFIX}${input.runId} -->`];
+    // Hidden marker stays first; the issue link is the first visible line.
+    const issue = issueLine(input);
+    if (issue)
+        sections.push(issue);
     if (input.summary)
         sections.push(input.summary);
     if (input.tests?.length) {

package/dist/providers/vcs/types.d.ts

@@ -65,6 +65,12 @@ export interface FinalizeChangesDetails {
         name: string;
         reason: string;
     }[];
+    /** Originating issue (control-plane data): named in the PR title and body. Provider-neutral. */
+    issue?: {
+        key: string;
+        url?: string;
+        trackerName?: string;
+    };
 }
 export type FinalizeChangesResult = {
     outcome: "no_changes";

package/dist/quickstart/index.d.ts

@@ -1,4 +1,12 @@
+/**
+ * Arguments for `<client> mcp add`. The server name comes right after `add`:
+ * Claude Code's `-e/--env <env...>` is variadic and would otherwise read the
+ * name as another KEY=value ("Invalid environment variable format: wardby").
+ */
+export declare function mcpAddArgs(client: "codex" | "claude", projectDir: string, packageSpec: string): string[];
 export declare function quickstartCommand(args: string[]): Promise<void>;
+/** The closing "build your first agent" hint; the assistant prompts only make sense once an MCP client is configured. */
+export declare function nextStepLines(mcpConfigured: boolean): string[];
 export declare function doctorCommand(args: string[]): Promise<void>;
 export declare function statusCommand(args: string[]): Promise<void>;
 export declare function logsCommand(args: string[]): Promise<void>;

package/dist/quickstart/index.js

@@ -263,54 +263,41 @@ function runDemo(paths) {
 function clientInstalled(command) {
     return runCommand(command, ["--version"]).status === 0;
 }
+/**
+ * Arguments for `<client> mcp add`. The server name comes right after `add`:
+ * Claude Code's `-e/--env <env...>` is variadic and would otherwise read the
+ * name as another KEY=value ("Invalid environment variable format: wardby").
+ */
+export function mcpAddArgs(client, projectDir, packageSpec) {
+    const env = `WARDBY_PROJECT_DIR=${projectDir}`;
+    const options = client === "codex" ? ["--env", env] : ["--scope", "local", "-e", env];
+    return ["mcp", "add", "wardby", ...options, "--", "npx", "--yes", packageSpec, "mcp"];
+}
 function configureOneMcpClient(client, paths) {
     if (!clientInstalled(client)) {
         console.warn(`! ${client} is not installed; skipped its MCP configuration.`);
-        return;
+        return false;
     }
     const existing = runCommand(client, ["mcp", "get", "wardby"], { cwd: paths.projectDir });
     if (existing.status === 0) {
         console.log(`✓ ${client} already has an MCP server named wardby.`);
-        return;
+        return true;
     }
-    const packageSpec = `@wardby/cli@${packageJson.version}`;
-    const args = client === "codex"
-        ? [
-            "mcp",
-            "add",
-            "--env",
-            `WARDBY_PROJECT_DIR=${paths.projectDir}`,
-            "wardby",
-            "--",
-            "npx",
-            "--yes",
-            packageSpec,
-            "mcp",
-        ]
-        : [
-            "mcp",
-            "add",
-            "--scope",
-            "local",
-            "-e",
-            `WARDBY_PROJECT_DIR=${paths.projectDir}`,
-            "wardby",
-            "--",
-            "npx",
-            "--yes",
-            packageSpec,
-            "mcp",
-        ];
+    const args = mcpAddArgs(client, paths.projectDir, `@wardby/cli@${packageJson.version}`);
     const result = runCommand(client, args, { cwd: paths.projectDir });
     if (result.status !== 0)
         commandFailure(`${client} MCP configuration`, result);
     console.log(`✓ Configured Wardby MCP for ${client}.`);
+    return true;
 }
+/** True when at least one requested client ended up with the wardby MCP server. */
 function configureMcpClients(client, paths) {
+    const results = [];
     if (client === "codex" || client === "both")
-        configureOneMcpClient("codex", paths);
+        results.push(configureOneMcpClient("codex", paths));
     if (client === "claude" || client === "both")
-        configureOneMcpClient("claude", paths);
+        results.push(configureOneMcpClient("claude", paths));
+    return results.some(Boolean);
 }
 async function chooseClient(nonInteractive) {
     if (nonInteractive)
@@ -412,12 +399,25 @@ export async function quickstartCommand(args) {
             console.log(`Skipped the billed run. Start it later with: npx @wardby/cli@latest run ${DEMO_AGENT}`);
     }
     const client = parseClient(values.client) ?? (await chooseClient(nonInteractive));
-    if (client !== "none")
-        configureMcpClients(client, paths);
+    const mcpConfigured = client !== "none" && configureMcpClients(client, paths);
     console.log("\nWardby is ready.");
     console.log("  npx @wardby/cli@latest status");
     console.log("  npx @wardby/cli@latest doctor");
     console.log("  npx @wardby/cli@latest down");
+    for (const line of nextStepLines(mcpConfigured))
+        console.log(line);
+}
+/** The closing "build your first agent" hint; the assistant prompts only make sense once an MCP client is configured. */
+export function nextStepLines(mcpConfigured) {
+    const guide = "the guide: npx @wardby/cli@latest help open agent-recipes";
+    const lines = ["", "Next: build your first agent."];
+    if (mcpConfigured) {
+        lines.push("Ask your assistant one of:", '  "Set up the Wardby architecture keeper for this repository"', '  "Set up a Wardby builder for this repository"', `Or read ${guide}`);
+    }
+    else {
+        lines.push(`Read ${guide}`);
+    }
+    return lines;
 }
 async function databaseHealthy(paths) {
     const env = readQuickstartEnv(paths);

package/dist/serve.js

@@ -33,12 +33,18 @@ export async function startServe(options = {}) {
     const concurrency = loadCodingConcurrencyConfig();
     const providers = options.providers ?? buildMcpProviders().providers;
     const mcp = await startMcp({ providers, schedulerAttached: true });
-    const reconciler = startReconciler({ executor: providers.executor, reviewHosts: providers.reviewHosts });
+    const reconciler = startReconciler({
+        executor: providers.executor,
+        reviewHosts: providers.reviewHosts,
+        issueTrackers: providers.issueTrackers,
+    });
+    const selfDefects = { db: prisma, issueTrackers: providers.issueTrackers };
     const scheduler = startScheduler({
         executor: providers.executor,
         scope: options.scope,
+        selfDefects,
         onLeaderTick: async () => {
-            await drainCodingQueue({ db: prisma, executor: providers.executor, ...concurrency });
+            await drainCodingQueue({ db: prisma, executor: providers.executor, ...concurrency, selfDefects });
         },
     });
     return {