@wardby/cli 0.2.1 → 0.4.0

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

@@ -8,6 +8,18 @@ export interface PullRequestTestResult {
     command: string;
     outcome: "passed" | "failed" | "skipped";
 }
+/** One package the registry proxy served during the run (RegistryFetch outcome "served"). */
+export interface PackageReport {
+    ecosystem: string;
+    name: string;
+    version: string;
+}
+/** One package the registry proxy refused during the run (RegistryFetch outcome "refused"). */
+export interface PackageRefusal {
+    ecosystem: string;
+    name: string;
+    reason: string;
+}
 export interface PullRequestInput {
     runId: string;
     repository: string;
@@ -17,6 +29,30 @@ export interface PullRequestInput {
     summary?: string;
     tests?: readonly PullRequestTestResult[];
     tag?: string;
+    /** Deduplicated by the caller isn't required — pullRequestBody dedupes itself (ecosystem+name+version / +reason). */
+    packages?: readonly PackageReport[];
+    packageRefusals?: readonly PackageRefusal[];
+    /**
+     * A continuation re-finds the PR its root run opened, and a person may
+     * have marked that PR ready for review since. The push has already updated
+     * it, so it is accepted as found instead of failing the run as
+     * `github_pull_request_not_draft`. A PR this client creates is always a
+     * 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;
@@ -42,6 +78,15 @@ export interface ContinuationCheckRunInput {
 export interface ContinuationCheckRunCompleteInput extends ContinuationCheckRunInput {
     outcome: "succeeded" | "failed";
 }
+/** One file at one ref, read through the API without a clone. */
+export interface RepositoryFileInput {
+    repository: string;
+    ref: string;
+    /** Repository-relative POSIX path. */
+    path: string;
+    /** Refused above this many bytes. */
+    maxBytes: number;
+}
 export interface GitHubRepositoryAccess {
     withRepositoryToken<T>(repository: string, action: (token: string) => Promise<T>): Promise<T>;
     createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
@@ -53,10 +98,29 @@ export interface GitHubRepositoryAccess {
     createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;
     /** Completes the check run if one exists for this run+commit; a no-op otherwise (never creates). */
     completeContinuationCheckRun(input: ContinuationCheckRunCompleteInput): Promise<void>;
+    /**
+     * The raw text of one file at a ref, or null when it does not exist (a
+     * Contents: read token). Optional so test doubles and non-GitHub providers
+     * can omit it: coding-run services then read no declaration.
+     */
+    readFileAtRef?(input: RepositoryFileInput): Promise<string | null>;
 }
 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. */
+export declare const MAX_PR_PACKAGE_LINES = 100;
+/** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
+export declare function pullRequestBody(input: PullRequestInput): string;
 export declare class GitHubAppClient implements GitHubRepositoryAccess {
     private readonly config;
     private readonly fetchImpl;
@@ -78,6 +142,28 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
      * apparently isn't gated the same way a genuine issue comment might be.)
      */
     private withChecksToken;
+    /**
+     * Mints an installation token for exactly `permissions` on one repository,
+     * runs `action`, and always revokes. The building block for the
+     * code-review host (providers/review-host/github.ts), whose calls each
+     * request only what they need.
+     */
+    withScopedToken<T>(repository: string, permissions: Record<string, "read" | "write">, action: (token: string) => Promise<T>): Promise<T>;
+    /**
+     * One file's raw text at a ref, without a clone (a Contents: read token).
+     * Requests the raw media type; GitHub honors it for an ordinary file but
+     * falls back to a JSON metadata response for anything else the raw type
+     * doesn't apply to -- a directory listing (a JSON array) or a symlink /
+     * submodule (a JSON object whose `type` isn't "file"). Either of those, or
+     * a 404, means there's no file text to return.
+     */
+    readFileAtRef(input: RepositoryFileInput): Promise<string | null>;
+    private identity?;
+    /** The App's id and slug (its @-mention handle), read once with the App JWT. */
+    appIdentity(): Promise<{
+        id: number;
+        slug: string;
+    }>;
     upsertContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     updateContinuationStatusComment(input: ContinuationStatusCommentInput): Promise<void>;
     createContinuationCheckRun(input: ContinuationCheckRunInput): Promise<void>;
@@ -85,13 +171,12 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
     createOrFindDraftPullRequest(input: PullRequestInput): Promise<PullRequestResult>;
     private appJwt;
     private mintRepositoryToken;
-    private mintChecksToken;
     /**
      * Shared installation-token mint: requests exactly `permissions`, then
      * verifies the response granted exactly that (no more, no less, modulo
      * the always-implicit `metadata: read`) before trusting the token. Each
      * caller requests the narrowest permission set it needs — see
-     * withIssuesToken/withChecksToken for why these are minted separately
+     * withScopedToken/withChecksToken for why these are minted separately
      * from withRepositoryToken rather than requesting a union of everything.
      */
     private mintScopedToken;
@@ -100,6 +185,12 @@ export declare class GitHubAppClient implements GitHubRepositoryAccess {
     private parsePullRequest;
     private findStatusComment;
     private findCheckRun;
-    private requestJson;
+    /** Public for the code-review host, which issues its own REST calls with tokens minted here. */
+    requestJson(path: string, bearer: string, init?: RequestInit, expectedStatuses?: number[]): Promise<Response>;
+    /**
+     * Public for the code-review host: one GraphQL request, for what REST lacks
+     * (review threads). A response carrying `errors` fails like a REST error.
+     */
+    graphql(bearer: string, query: string, variables: Record<string, unknown>): Promise<Record<string, unknown>>;
 }
 export {};

package/dist/providers/vcs/github.js

@@ -11,6 +11,7 @@ const SAFE_PULL_REQUEST_TAG = /^[A-Za-z0-9][A-Za-z0-9._/-]{0,31}$/;
 /** Mirrors the runId shape validated elsewhere (coding/protocol.ts, git.ts) — validated independently here too. */
 const SAFE_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 const SAFE_COMMIT_SHA = /^[0-9a-f]{40}$/;
+const SAFE_FILE_PATH = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
 function record(value) {
     if (!value || typeof value !== "object" || Array.isArray(value))
         throw new Error("github_api_invalid_response");
@@ -32,17 +33,117 @@ 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
+ * anything Wardby validated, and land inside inline code spans in the PR
+ * body. A backtick or newline in one of those fields could break out of the
+ * span or the line structure, so any entry containing either is dropped
+ * rather than escaped (npm/PyPI names can't contain backticks in practice,
+ * so this should never trigger — it's a cheap belt-and-suspenders guard).
+ */
+function isSafeMarkdownFragment(value) {
+    return !value.includes("`") && !value.includes("\n") && !value.includes("\r");
+}
+/** 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. */
+export const MAX_PR_PACKAGE_LINES = 100;
+/** A hard ceiling on each list's rendered size, whatever the entries
+ *  contain, so the section can never push the body past GitHub's limit. */
+const MAX_PR_PACKAGE_LIST_CHARS = 16 * 1024;
+/** Renders at most MAX_PR_PACKAGE_LINES lines (and at most
+ *  MAX_PR_PACKAGE_LIST_CHARS characters) of `lines`, then a count of the rest. */
+function cappedList(lines) {
+    const shown = [];
+    let chars = 0;
+    for (const line of lines.slice(0, MAX_PR_PACKAGE_LINES)) {
+        if (chars + line.length + 1 > MAX_PR_PACKAGE_LIST_CHARS)
+            break;
+        shown.push(line);
+        chars += line.length + 1;
+    }
+    const more = lines.length - shown.length;
+    return more > 0 ? [...shown, `- …and ${more} more — see get_run for the full list`] : shown;
+}
+function packagesSection(input) {
+    const packages = [
+        ...new Map((input.packages ?? [])
+            .filter((pkg) => isSafeMarkdownFragment(pkg.ecosystem) &&
+            isSafeMarkdownFragment(pkg.name) &&
+            isSafeMarkdownFragment(pkg.version))
+            .map((pkg) => [`${pkg.ecosystem}\0${pkg.name}\0${pkg.version}`, pkg])).values(),
+    ];
+    const refusals = [
+        ...new Map((input.packageRefusals ?? [])
+            .filter((refusal) => isSafeMarkdownFragment(refusal.ecosystem) &&
+            isSafeMarkdownFragment(refusal.name) &&
+            isSafeMarkdownFragment(refusal.reason))
+            .map((refusal) => [`${refusal.ecosystem}\0${refusal.name}\0${refusal.reason}`, refusal])).values(),
+    ];
+    if (packages.length === 0 && refusals.length === 0)
+        return undefined;
+    return [
+        "<details>",
+        `<summary>Packages installed during this run (${packages.length})</summary>`,
+        "",
+        ...cappedList(packages.map((pkg) => `- ${pkg.ecosystem} \`${pkg.name}@${pkg.version}\``)),
+        ...(refusals.length > 0
+            ? [
+                "",
+                "**Refused:**",
+                ...cappedList(refusals.map((refusal) => `- ${refusal.ecosystem} \`${refusal.name}\`: ${refusal.reason}`)),
+            ]
+            : []),
+        "</details>",
+    ].join("\n");
 }
 /** The hidden run marker stays first and unconditional: createOrFindDraftPullRequest's idempotent lookup depends on it. */
-function pullRequestBody(input) {
+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) {
         sections.push(["**Tests:**", ...input.tests.map((test) => `- \`${test.command}\`: ${test.outcome}`)].join("\n"));
     }
+    // The packages section is informational: a failure rendering it (e.g. a
+    // malformed report) omits the section and never fails finalization.
+    try {
+        const packages = packagesSection(input);
+        if (packages)
+            sections.push(packages);
+    }
+    catch {
+        // omitted
+    }
     return sections.join("\n\n");
 }
 /** The hidden marker stays first and unconditional: findStatusComment's lookup depends on it. */
@@ -108,8 +209,17 @@ export class GitHubAppClient {
      * apparently isn't gated the same way a genuine issue comment might be.)
      */
     async withChecksToken(repository, action) {
+        return this.withScopedToken(repository, { checks: "write" }, action);
+    }
+    /**
+     * Mints an installation token for exactly `permissions` on one repository,
+     * runs `action`, and always revokes. The building block for the
+     * code-review host (providers/review-host/github.ts), whose calls each
+     * request only what they need.
+     */
+    async withScopedToken(repository, permissions, action) {
         const normalized = normalizeGitHubRepository(repository);
-        const token = await this.mintChecksToken(normalized);
+        const token = await this.mintScopedToken(normalized, permissions, (name, level) => (name === "metadata" && level === "read") || permissions[name] === level);
         try {
             return await action(token);
         }
@@ -117,6 +227,74 @@ export class GitHubAppClient {
             await this.revokeToken(token).catch(() => undefined);
         }
     }
+    /**
+     * One file's raw text at a ref, without a clone (a Contents: read token).
+     * Requests the raw media type; GitHub honors it for an ordinary file but
+     * falls back to a JSON metadata response for anything else the raw type
+     * doesn't apply to -- a directory listing (a JSON array) or a symlink /
+     * submodule (a JSON object whose `type` isn't "file"). Either of those, or
+     * a 404, means there's no file text to return.
+     */
+    async readFileAtRef(input) {
+        if (!SAFE_FILE_PATH.test(input.path) || input.path.split("/").some((part) => part === "." || part === "..")) {
+            throw new Error("github_file_path_invalid");
+        }
+        const repository = normalizeGitHubRepository(input.repository);
+        const ref = normalizeGitRef(input.ref);
+        const [owner, name] = repository.split("/");
+        const path = input.path.split("/").map(encodeURIComponent).join("/");
+        return this.withScopedToken(repository, { contents: "read" }, async (token) => {
+            const response = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/contents/${path}?ref=${encodeURIComponent(ref)}`, token, { headers: { accept: "application/vnd.github.raw+json" } }, [200, 404]);
+            if (response.status === 404)
+                return null;
+            const declared = Number(response.headers.get("content-length") ?? Number.NaN);
+            if (Number.isFinite(declared) && declared > input.maxBytes)
+                throw new Error("github_file_too_large");
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            if (bytes.byteLength > input.maxBytes)
+                throw new Error("github_file_too_large");
+            let text;
+            try {
+                text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            }
+            catch {
+                throw new Error("github_file_not_utf8");
+            }
+            // Not raw content check: try to read the body as GitHub's own
+            // metadata shape rather than trusting the content-type header, since
+            // the raw media type itself is "application/vnd.github.raw+json" --
+            // a substring check for "json" would misfire on every real file.
+            let metadata;
+            try {
+                metadata = JSON.parse(text);
+            }
+            catch {
+                return text;
+            }
+            if (Array.isArray(metadata))
+                throw new Error("github_file_not_a_file");
+            if (metadata && typeof metadata === "object" && "type" in metadata && metadata.type !== "file") {
+                throw new Error("github_file_not_a_file");
+            }
+            return text;
+        });
+    }
+    identity;
+    /** The App's id and slug (its @-mention handle), read once with the App JWT. */
+    appIdentity() {
+        this.identity ??= (async () => {
+            const response = await this.requestJson("/app", await this.appJwt());
+            const payload = record(await response.json());
+            if (typeof payload.slug !== "string" || !/^[a-z0-9-]{1,64}$/.test(payload.slug)) {
+                throw new Error("github_api_invalid_response");
+            }
+            return { id: positiveInteger(payload.id), slug: payload.slug };
+        })().catch((err) => {
+            this.identity = undefined;
+            throw err;
+        });
+        return this.identity;
+    }
     async upsertContinuationStatusComment(input) {
         const repository = normalizeGitHubRepository(input.repository);
         const baseRef = normalizeGitRef(input.baseRef);
@@ -125,7 +303,13 @@ export class GitHubAppClient {
             throw new Error("github_status_comment_input_invalid");
         }
         await this.withRepositoryToken(repository, async (token) => {
-            const pr = await this.findPullRequest(token, { runId: input.rootRunId, repository, baseRef, headRef });
+            const pr = await this.findPullRequest(token, {
+                runId: input.rootRunId,
+                repository,
+                baseRef,
+                headRef,
+                acceptReadyForReview: true,
+            });
             if (!pr)
                 return;
             const existing = await this.findStatusComment(token, repository, pr.number, input.runId);
@@ -147,7 +331,13 @@ export class GitHubAppClient {
             throw new Error("github_status_comment_input_invalid");
         }
         await this.withRepositoryToken(repository, async (token) => {
-            const pr = await this.findPullRequest(token, { runId: input.rootRunId, repository, baseRef, headRef });
+            const pr = await this.findPullRequest(token, {
+                runId: input.rootRunId,
+                repository,
+                baseRef,
+                headRef,
+                acceptReadyForReview: true,
+            });
             if (!pr)
                 return;
             const existing = await this.findStatusComment(token, repository, pr.number, input.runId);
@@ -253,24 +443,27 @@ export class GitHubAppClient {
             (name === "pull_requests" && level === "write") ||
             (name === "metadata" && level === "read"));
     }
-    async mintChecksToken(repository) {
-        return this.mintScopedToken(repository, { checks: "write" }, (name, level) => (name === "checks" && level === "write") || (name === "metadata" && level === "read"));
-    }
     /**
      * Shared installation-token mint: requests exactly `permissions`, then
      * verifies the response granted exactly that (no more, no less, modulo
      * the always-implicit `metadata: read`) before trusting the token. Each
      * caller requests the narrowest permission set it needs — see
-     * withIssuesToken/withChecksToken for why these are minted separately
+     * withScopedToken/withChecksToken for why these are minted separately
      * from withRepositoryToken rather than requesting a union of everything.
      */
     async mintScopedToken(repository, permissions, isAllowedPermission) {
         const [owner, name] = repository.split("/");
         const appJwt = await this.appJwt();
-        const installationResponse = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/installation`, appJwt);
+        const installationResponse = await this.requestJson(`/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}/installation`, appJwt, {}, [200, 404]);
+        if (installationResponse.status === 404)
+            throw new Error("github_app_not_installed");
         const installation = record(await installationResponse.json());
         const installationId = positiveInteger(installation.id);
-        const tokenResponse = await this.requestJson(`/app/installations/${installationId}/access_tokens`, appJwt, { method: "POST", body: JSON.stringify({ repositories: [name], permissions }) }, [201]);
+        const tokenResponse = await this.requestJson(`/app/installations/${installationId}/access_tokens`, appJwt, { method: "POST", body: JSON.stringify({ repositories: [name], permissions }) }, [201, 422]);
+        // 422: the installation has not granted a requested permission (e.g. a
+        // new permission the owner has not accepted yet).
+        if (tokenResponse.status === 422)
+            throw new Error("github_installation_token_scope_invalid");
         const payload = record(await tokenResponse.json());
         const grantedPermissions = record(payload.permissions);
         const repositories = Array.isArray(payload.repositories) ? payload.repositories.map(record) : [];
@@ -307,17 +500,15 @@ export class GitHubAppClient {
         for (const item of payload) {
             const candidate = record(item);
             if (typeof candidate.body === "string" && candidate.body.includes(marker)) {
-                if (candidate.draft !== true)
-                    throw new Error("github_pull_request_not_draft");
-                return this.parsePullRequest(candidate, input.repository);
+                return this.parsePullRequest(candidate, input.repository, input.acceptReadyForReview === true);
             }
         }
         return null;
     }
-    parsePullRequest(value, repository) {
+    parsePullRequest(value, repository, acceptReadyForReview = false) {
         const payload = record(value);
         const number = positiveInteger(payload.number);
-        if (payload.draft !== true)
+        if (payload.draft !== true && !acceptReadyForReview)
             throw new Error("github_pull_request_not_draft");
         const expectedUrl = `https://github.com/${repository}/pull/${number}`;
         if (typeof payload.html_url !== "string")
@@ -367,6 +558,7 @@ export class GitHubAppClient {
         }
         return null;
     }
+    /** Public for the code-review host, which issues its own REST calls with tokens minted here. */
     async requestJson(path, bearer, init = {}, expectedStatuses = [200]) {
         let response;
         try {
@@ -391,4 +583,18 @@ export class GitHubAppClient {
             throw safeApiError(response);
         return response;
     }
+    /**
+     * Public for the code-review host: one GraphQL request, for what REST lacks
+     * (review threads). A response carrying `errors` fails like a REST error.
+     */
+    async graphql(bearer, query, variables) {
+        const response = await this.requestJson("/graphql", bearer, {
+            method: "POST",
+            body: JSON.stringify({ query, variables }),
+        });
+        const payload = record(await response.json());
+        if (Array.isArray(payload.errors) && payload.errors.length > 0)
+            throw new Error("github_graphql_error");
+        return record(payload.data);
+    }
 }

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

@@ -1,9 +1,12 @@
+import type { RepositoryFileInput } from "./github.js";
 export interface VcsPrepareInput {
     runId: string;
     repository: string;
     baseRef: string;
     headRef: string;
     protectedPaths: string[];
+    /** Repository-relative paths never collected, in addition to the built-in names. */
+    collectExclude?: string[];
     /**
      * Revision-in-place: set when headRef is an EXISTING branch to continue
      * rather than a fresh one
@@ -38,6 +41,7 @@ export interface PreparedWorkspace {
     workspacePath: string;
     gitMetadataPath: string;
     protectedPaths: string[];
+    collectExclude: string[];
     continuation?: {
         rootRunId: string;
     };
@@ -50,6 +54,23 @@ export interface FinalizeChangesDetails {
         outcome: "passed" | "failed" | "skipped";
     }[];
     tag?: string;
+    /** Packages the registry proxy served/refused during this run (RegistryFetch), for the PR body. */
+    packages?: readonly {
+        ecosystem: string;
+        name: string;
+        version: string;
+    }[];
+    packageRefusals?: readonly {
+        ecosystem: string;
+        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";
@@ -110,9 +131,32 @@ export interface VcsProvider {
      * (the same text that goes in the PR body -- see
      * `FinalizeChangesDetails.summary`) so the "done" status reflects what
      * actually happened instead of a caller having to go find out.
+     * `budget_exhausted` is a failure that ran out of budget;
+     * `details.budgetSentence` then says how (see core/budget-wording.ts).
+     * A `failed` run the model provider refused carries `details.providerSentence`.
+     * A `failed` run whose changes touched a protected path carries
+     * `details.protectedPathSentence` (see coding/protected-path-wording.ts).
      */
-    notifyContinuationFinished?(workspace: PreparedWorkspace, outcome: "succeeded" | "failed", details?: {
-        summary?: string;
-        agentName?: string;
-    }): Promise<void>;
+    notifyContinuationFinished?(workspace: PreparedWorkspace, outcome: ContinuationOutcome, details?: ContinuationFinishedDetails): Promise<void>;
+    /**
+     * The raw text of one repository file at a ref, read through the host's API
+     * without a clone, or null when it does not exist. Dispatch reads a coding
+     * run's .wardby/services.yaml from its base branch with it
+     * (docs/coding-services.md). Optional, mirroring notifyContinuationStarted: a
+     * provider (or test double) without it gives runs no services.
+     */
+    readRepositoryFile?(input: RepositoryFileInput): Promise<string | null>;
+}
+export type ContinuationOutcome = "succeeded" | "failed" | "budget_exhausted";
+export interface ContinuationFinishedDetails {
+    summary?: string;
+    agentName?: string;
+    /** Host-safe sentence naming the run's budget; used with `budget_exhausted`. */
+    budgetSentence?: string;
+    /** Host-safe sentence naming a model-provider refusal (see core/provider-wording.ts); used with `failed`. */
+    providerSentence?: string;
+    /** Host-safe sentence naming a coding-run service that never became ready (coding/services/wording.ts); used with `failed`. */
+    serviceSentence?: string;
+    /** Host-safe sentence naming a protected path the run's changes touched (coding/protected-path-wording.ts); used with `failed`. */
+    protectedPathSentence?: string;
 }

package/dist/quickstart/index.d.ts

@@ -1,4 +1,6 @@
 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

@@ -212,8 +212,13 @@ function applyMigrations(paths) {
 }
 async function seedDemo(paths, state, budget) {
     const { createPrismaClient } = await import("../core/db.js");
-    const db = createPrismaClient(readQuickstartEnv(paths).DATABASE_URL);
+    const { resolvePrincipal } = await import("../mcp/auth/principal.js");
+    const env = readQuickstartEnv(paths);
+    const db = createPrismaClient(env.DATABASE_URL);
     try {
+        // The demo agent belongs to the local operator (LOCAL_PRINCIPAL) and is
+        // private: agents are never owner-less (resource-sharing grants).
+        const owner = await resolvePrincipal(env.LOCAL_PRINCIPAL || "local", db);
         const existing = await db.agent.findUnique({ where: { name: DEMO_AGENT } });
         if (existing && existing.systemPrompt !== DEMO_PROMPT) {
             throw new Error(`An agent named "${DEMO_AGENT}" already exists and was not created by quickstart; rename it or use --skip-demo.`);
@@ -221,7 +226,12 @@ async function seedDemo(paths, state, budget) {
         if (existing) {
             await db.agent.update({
                 where: { name: DEMO_AGENT },
-                data: { model: state.model, budgetUsd: budget, maxTurns: 2 },
+                data: {
+                    model: state.model,
+                    budgetUsd: budget,
+                    maxTurns: 2,
+                    ...(existing.ownerId ? {} : { ownerId: owner.id }),
+                },
             });
         }
         else {
@@ -232,6 +242,7 @@ async function seedDemo(paths, state, budget) {
                     budgetUsd: budget,
                     maxTurns: 2,
                     systemPrompt: DEMO_PROMPT,
+                    ownerId: owner.id,
                 },
             });
         }
@@ -255,12 +266,12 @@ function clientInstalled(command) {
 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"
@@ -294,12 +305,16 @@ function configureOneMcpClient(client, paths) {
     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)
@@ -401,12 +416,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);