@wardby/cli 0.2.0 → 0.3.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,17 @@ 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;
 }
 export interface PullRequestResult {
     number: number;
@@ -42,6 +65,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 +85,22 @@ 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;
+/** 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 +122,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 +151,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 +165,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");
@@ -35,14 +36,88 @@ export function isSafeGitHubInstallationToken(value) {
 function pullRequestTitle(input) {
     return input.tag ? `[${input.tag}] Wardby run ${input.runId}` : `Wardby run ${input.runId}`;
 }
+/**
+ * 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} -->`];
     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 +183,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 +201,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 +277,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 +305,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 +417,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 +474,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 +532,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 +557,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,17 @@ 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;
+    }[];
 }
 export type FinalizeChangesResult = {
     outcome: "no_changes";
@@ -110,9 +125,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.js

@@ -1,5 +1,4 @@
 import { spawnSync } from "node:child_process";
-import { createRequire } from "node:module";
 import { createServer } from "node:net";
 import { readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -7,12 +6,11 @@ import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import { createInterface } from "node:readline/promises";
 import { composeProjectName, defaultModel, ensureWardbyIgnored, generatedSecret, providerKeyName, quickstartPaths, readQuickstartEnv, readQuickstartState, resolveProjectDir, writeQuickstartEnv, writeQuickstartState, } from "./config.js";
+import { FETCH_NOTICE, migrateFailureReason, prismaMigrateInvocation, REGISTRY_FAILURE_MESSAGE, runPrismaMigrateInvocation, } from "./migrate.js";
 const packageRoot = fileURLToPath(new URL("../../", import.meta.url));
 const composeFile = join(packageRoot, "deploy/local/docker-compose.yml");
-const schemaFile = join(packageRoot, "prisma/schema.prisma");
 const wardbyBin = join(packageRoot, "bin/wardby.js");
 const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-const require = createRequire(import.meta.url);
 const DEMO_AGENT = "hello-wardby";
 const DEMO_PROMPT = "You are the Wardby quickstart agent. Reply with a short greeting, then explain in one sentence that Wardby admitted this run against an explicit maximum budget. Do not call tools.";
 function runCommand(command, args, options = {}) {
@@ -200,23 +198,27 @@ async function chooseProvider(requested, previous, existing, nonInteractive) {
         return "anthropic";
     throw new Error(`Unknown provider selection "${answer}".`);
 }
-function prismaCliPath() {
-    return require.resolve("prisma/build/index.js");
-}
 function applyMigrations(paths) {
-    const result = runCommand(process.execPath, [prismaCliPath(), "migrate", "deploy", "--schema", schemaFile], {
-        cwd: paths.projectDir,
-        env: runtimeEnv(paths),
-    });
+    const invocation = prismaMigrateInvocation("deploy", runtimeEnv(paths));
+    if (!invocation.local)
+        console.log(FETCH_NOTICE);
+    const result = runPrismaMigrateInvocation(invocation, paths.projectDir);
+    if (result.registryFailure) {
+        const detail = /^npm (?:error|ERR!) code .*$/m.exec(result.stderr)?.[0] ?? result.stderr.trim().split("\n")[0];
+        throw new Error(`${REGISTRY_FAILURE_MESSAGE}${detail ? ` (${detail})` : ""}`);
+    }
     if (result.status !== 0)
         commandFailure("Database migration", result);
 }
 async function seedDemo(paths, state, budget) {
-    const previousDatabaseUrl = process.env.DATABASE_URL;
-    process.env.DATABASE_URL = readQuickstartEnv(paths).DATABASE_URL;
-    const { PrismaClient } = await import("@prisma/client");
-    const db = new PrismaClient();
+    const { createPrismaClient } = await import("../core/db.js");
+    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.`);
@@ -224,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 {
@@ -235,16 +242,13 @@ async function seedDemo(paths, state, budget) {
                     budgetUsd: budget,
                     maxTurns: 2,
                     systemPrompt: DEMO_PROMPT,
+                    ownerId: owner.id,
                 },
             });
         }
     }
     finally {
         await db.$disconnect();
-        if (previousDatabaseUrl === undefined)
-            delete process.env.DATABASE_URL;
-        else
-            process.env.DATABASE_URL = previousDatabaseUrl;
     }
 }
 function runDemo(paths) {
@@ -419,10 +423,8 @@ async function databaseHealthy(paths) {
     const env = readQuickstartEnv(paths);
     if (!env.DATABASE_URL)
         return false;
-    const previous = process.env.DATABASE_URL;
-    process.env.DATABASE_URL = env.DATABASE_URL;
-    const { PrismaClient } = await import("@prisma/client");
-    const db = new PrismaClient();
+    const { createPrismaClient } = await import("../core/db.js");
+    const db = createPrismaClient(env.DATABASE_URL);
     try {
         await db.$queryRawUnsafe("SELECT 1");
         return true;
@@ -432,10 +434,6 @@ async function databaseHealthy(paths) {
     }
     finally {
         await db.$disconnect();
-        if (previous === undefined)
-            delete process.env.DATABASE_URL;
-        else
-            process.env.DATABASE_URL = previous;
     }
 }
 export async function doctorCommand(args) {
@@ -468,11 +466,15 @@ export async function doctorCommand(args) {
         const ps = runCompose(paths, state, ["ps", "--status", "running", "--quiet"]);
         checks.push(["PostgreSQL container", ps.status === 0 && ps.stdout.trim().length > 0]);
         checks.push(["Database connection", await databaseHealthy(paths)]);
-        const migrations = runCommand(process.execPath, [prismaCliPath(), "migrate", "status", "--schema", schemaFile], {
-            cwd: paths.projectDir,
-            env: runtimeEnv(paths),
-        });
-        checks.push(["Database migrations", migrations.status === 0]);
+        const invocation = prismaMigrateInvocation("status", runtimeEnv(paths));
+        if (!invocation.local)
+            console.log(FETCH_NOTICE);
+        const migrations = runPrismaMigrateInvocation(invocation, paths.projectDir);
+        checks.push([
+            "Database migrations",
+            migrations.status === 0,
+            migrations.status === 0 ? undefined : migrateFailureReason(migrations),
+        ]);
     }
     let failed = false;
     for (const [name, ok, detail] of checks) {

package/dist/quickstart/migrate.d.ts

@@ -0,0 +1,23 @@
+export declare const PRISMA_CLI_VERSION = "7.10.0";
+export declare const FETCH_NOTICE = "Fetching the Prisma CLI (prisma@7.10.0)\u2026";
+export declare const REGISTRY_FAILURE_MESSAGE: string;
+export declare const migrateConfigFile: string;
+export interface MigrateResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    registryFailure?: boolean;
+}
+export interface MigrateInvocation {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    local: boolean;
+}
+export declare function parseLocalPrismaVersion(stdout: string): string | undefined;
+export declare function probeLocalPrismaVersion(env: NodeJS.ProcessEnv): string | undefined;
+export declare function prismaMigrateInvocation(subcommand: "deploy" | "status", env: NodeJS.ProcessEnv, probe?: (env: NodeJS.ProcessEnv) => string | undefined): MigrateInvocation;
+export declare function classifyMigrateResult(result: MigrateResult, spawnError?: Error, local?: boolean): MigrateResult;
+export declare function migrateFailureReason(result: MigrateResult): string;
+export declare function runPrismaMigrateInvocation(invocation: MigrateInvocation, cwd: string): MigrateResult;
+export declare function runPrismaMigrate(subcommand: "deploy" | "status", env: NodeJS.ProcessEnv, cwd: string, probe?: (env: NodeJS.ProcessEnv) => string | undefined): MigrateResult;