@cat-factory/server 0.294.0 → 0.295.0

package/dist/github/repoContents.d.ts

@@ -0,0 +1,31 @@
+import type { GitHubRepoRef, RepoContentEntry, RepoEntry, RepoFileContent } from '@cat-factory/kernel';
+/** The narrow slice of `FetchGitHubClient.request` these reads need. */
+export type ContentsRequest = (path: string, opts: {
+    installationId: number;
+}) => Promise<{
+    json: unknown;
+}>;
+/** The repo root's entries, or `[]` for a repository with no commits yet. */
+export declare function readRootEntries(request: ContentsRequest, installationId: number, ref: GitHubRepoRef): Promise<RepoEntry[]>;
+/** One directory's entries on `gitRef`, or `[]` for a missing path (mirrors {@link readRootEntries}). */
+export declare function readDirectory(request: ContentsRequest, installationId: number, ref: GitHubRepoRef, path: string, gitRef?: string): Promise<RepoContentEntry[]>;
+/**
+ * The WHOLE tree in one recursive git-trees read, so file search never walks the contents API
+ * directory by directory. `HEAD` resolves to the repository's default branch.
+ */
+export declare function readTree(request: ContentsRequest, installationId: number, ref: GitHubRepoRef, gitRef?: string): Promise<RepoContentEntry[]>;
+/**
+ * One file's content and blob sha on `gitRef`, or null when the path is absent.
+ *
+ * The two refusals this endpoint states badly are translated HERE, because this is the only layer
+ * that knows the contents API's own ceiling:
+ *
+ *   - An over-limit blob arrives EITHER as a `403` whose body says `too_large`, or as a `200` with
+ *     an empty body and `encoding: 'none'`. Left bare, the first reaches a consumer as the same fact
+ *     as a revoked token (the public file read turned it into a `503` telling an operator to re-mint
+ *     a credential that worked), and the second as a file that is genuinely empty.
+ *   - A file whose bytes are not UTF-8 rides back with `lossy: true` rather than pretending the
+ *     replacement characters are its content.
+ */
+export declare function readFileContent(request: ContentsRequest, installationId: number, ref: GitHubRepoRef, path: string, gitRef?: string): Promise<RepoFileContent | null>;
+//# sourceMappingURL=repoContents.d.ts.map

package/dist/github/repoContents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repoContents.d.ts","sourceRoot":"","sources":["../../src/github/repoContents.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,eAAe,EAChB,MAAM,qBAAqB,CAAA;AAyB5B,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,cAAc,EAAE,MAAM,CAAA;CAAE,KAC7B,OAAO,CAAC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAA;AAE/B,6EAA6E;AAC7E,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,aAAa,GACjB,OAAO,CAAC,SAAS,EAAE,CAAC,CActB;AAED,yGAAyG;AACzG,wBAAsB,aAAa,CACjC,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuB7B;AAED;;;GAGG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,aAAa,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,gBAAgB,EAAE,CAAC,CA2B7B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,eAAe,EACxB,cAAc,EAAE,MAAM,EACtB,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC"}

package/dist/github/repoContents.js

@@ -0,0 +1,121 @@
+import { VcsBlobTooLargeError } from '@cat-factory/kernel';
+import { GITHUB_CONTENTS_MAX_BYTES, decodeRepoFileBase64, githubApiStatus, isGitHubBlobTooLarge, } from './githubHttpHelpers.js';
+/** The repo root's entries, or `[]` for a repository with no commits yet. */
+export async function readRootEntries(request, installationId, ref) {
+    let json;
+    try {
+        ;
+        ({ json } = await request(`/repos/${ref.owner}/${ref.repo}/contents/`, { installationId }));
+    }
+    catch (err) {
+        // An empty repository has no default branch, so the contents endpoint 404s. That's the signal we
+        // want — treat it as "no entries", not an error.
+        if (githubApiStatus(err) === 404)
+            return [];
+        throw err;
+    }
+    const entries = Array.isArray(json)
+        ? json
+        : [];
+    return entries.map((e) => ({ path: e.path ?? e.name ?? '', type: e.type ?? 'file' }));
+}
+/** One directory's entries on `gitRef`, or `[]` for a missing path (mirrors {@link readRootEntries}). */
+export async function readDirectory(request, installationId, ref, path, gitRef) {
+    const clean = path.replace(/^\/+|\/+$/g, '');
+    const query = gitRef ? `?ref=${encodeURIComponent(gitRef)}` : '';
+    let json;
+    try {
+        ;
+        ({ json } = await request(`/repos/${ref.owner}/${ref.repo}/contents/${clean}${query}`, {
+            installationId,
+        }));
+    }
+    catch (err) {
+        if (githubApiStatus(err) === 404)
+            return [];
+        throw err;
+    }
+    // A directory returns an array; a single file returns an object — coerce both.
+    const arr = Array.isArray(json) ? json : [json];
+    return arr.map((e) => ({
+        path: e.path ?? e.name ?? '',
+        name: e.name ?? (e.path ?? '').split('/').pop() ?? '',
+        type: e.type ?? 'file',
+        sha: e.sha ?? '',
+        ...(typeof e.size === 'number' ? { size: e.size } : {}),
+    }));
+}
+/**
+ * The WHOLE tree in one recursive git-trees read, so file search never walks the contents API
+ * directory by directory. `HEAD` resolves to the repository's default branch.
+ */
+export async function readTree(request, installationId, ref, gitRef) {
+    const treeRef = encodeURIComponent(gitRef && gitRef !== 'HEAD' ? gitRef : 'HEAD');
+    let json;
+    try {
+        ;
+        ({ json } = await request(`/repos/${ref.owner}/${ref.repo}/git/trees/${treeRef}?recursive=1`, {
+            installationId,
+        }));
+    }
+    catch (err) {
+        // Empty repo / unknown ref → no entries (mirrors readDirectory).
+        if (githubApiStatus(err) === 404)
+            return [];
+        throw err;
+    }
+    const body = json;
+    const entries = Array.isArray(body.tree) ? body.tree : [];
+    // GitHub git-tree `type` is `blob` | `tree` | `commit` (submodule); normalise to the neutral
+    // file/dir vocabulary and drop submodules (they have no browsable content here).
+    return entries
+        .filter((e) => e.type === 'blob' || e.type === 'tree')
+        .map((e) => ({
+        path: e.path ?? '',
+        name: (e.path ?? '').split('/').pop() ?? '',
+        type: e.type === 'tree' ? 'dir' : 'file',
+        sha: e.sha ?? '',
+        ...(typeof e.size === 'number' ? { size: e.size } : {}),
+    }));
+}
+/**
+ * One file's content and blob sha on `gitRef`, or null when the path is absent.
+ *
+ * The two refusals this endpoint states badly are translated HERE, because this is the only layer
+ * that knows the contents API's own ceiling:
+ *
+ *   - An over-limit blob arrives EITHER as a `403` whose body says `too_large`, or as a `200` with
+ *     an empty body and `encoding: 'none'`. Left bare, the first reaches a consumer as the same fact
+ *     as a revoked token (the public file read turned it into a `503` telling an operator to re-mint
+ *     a credential that worked), and the second as a file that is genuinely empty.
+ *   - A file whose bytes are not UTF-8 rides back with `lossy: true` rather than pretending the
+ *     replacement characters are its content.
+ */
+export async function readFileContent(request, installationId, ref, path, gitRef) {
+    const clean = path.replace(/^\/+/, '');
+    const query = gitRef ? `?ref=${encodeURIComponent(gitRef)}` : '';
+    let json;
+    try {
+        ;
+        ({ json } = await request(`/repos/${ref.owner}/${ref.repo}/contents/${clean}${query}`, {
+            installationId,
+        }));
+    }
+    catch (err) {
+        if (githubApiStatus(err) === 404)
+            return null;
+        if (isGitHubBlobTooLarge(err))
+            throw new VcsBlobTooLargeError('github', GITHUB_CONTENTS_MAX_BYTES);
+        throw err;
+    }
+    const file = json;
+    if (file.type !== 'file' || typeof file.content !== 'string')
+        return null;
+    if (file.encoding === 'none')
+        throw new VcsBlobTooLargeError('github', GITHUB_CONTENTS_MAX_BYTES);
+    const { content, lossy } = file.encoding === 'base64'
+        ? decodeRepoFileBase64(file.content)
+        : { content: file.content, lossy: false };
+    return { content, sha: file.sha ?? '', ...(lossy ? { lossy: true } : {}) };
+}
+//# sourceMappingURL=repoContents.js.map

package/dist/github/repoContents.js.map

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

package/dist/http/env.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from 'hono';
-import type { AgentRunRepository, AuthAttemptRepository, ExecutionRepository, MachineNodeRepository, NotificationChannel, PlatformAlertSink, ResolveBinaryArtifactStore, ConsensusSessionRepository, ResolveRunRepoContext, LocalVcsSetup, Logger, SealedSecretInventory, SecretCipher, ToolSecretResolver, UserRepoAccessRepository, VcsIdentityRegistry, VcsProviderRegistry, VcsWebhookSink, WorkspacePermission, WorkspaceRole } from '@cat-factory/kernel';
+import type { AgentRunRepository, AuthAttemptRepository, ExecutionRepository, MachineNodeRepository, NotificationChannel, PlatformAlertSink, ResolveBinaryArtifactStore, ConsensusSessionRepository, ResolveRepoFilesForCoords, ResolveRunRepoContext, LocalVcsSetup, Logger, SealedSecretInventory, SecretCipher, ToolSecretResolver, UserRepoAccessRepository, VcsIdentityRegistry, VcsProviderRegistry, VcsWebhookSink, WorkspacePermission, WorkspaceRole } from '@cat-factory/kernel';
 import type { ApiKeyService, EnvironmentBackendRegistry, LocalModelEndpointService, LocalSettingsService, OpenRouterCatalogService, PersonalSubscriptionService, ProviderSubscriptionService, NotificationWebhookService, McpAuthorizationServer, PublicApiKeyService, RunnerBackendRegistry, TestSecretsService, CapabilityCredentialsService, McpOAuthService, ValidationConfigService, UserSecretService } from '@cat-factory/integrations';
 import type { Core } from '@cat-factory/orchestration';
 import type { AgentKindRegistry } from '@cat-factory/agents';
@@ -76,6 +76,15 @@ export interface ServerContainer extends Core {
      * spec endpoint returns an empty view.
      */
     resolveRunRepoContext?: ResolveRunRepoContext;
+    /**
+     * The BLOCK-LESS sibling of {@link resolveRunRepoContext}: the same checkout-free
+     * {@link RepoFiles}, from repo coordinates a caller names.
+     * `GET /api/v1/repos/:owner/:name/contents?path=` reads through it (the path is a QUERY value, not
+     * a path segment: see the contract), so the public file read is scoped to what this workspace has
+     * LINKED rather than to whatever the deployment's credential can reach. Present only when a VCS is
+     * wired (both facades compose it with `makeResolveRepoFilesForCoords`); absent → the read is a 503.
+     */
+    resolveRepoFilesForCoords?: ResolveRepoFilesForCoords;
     /**
      * Resolve the repo (installation + owner/name + default branch) linked to a
      * block's enclosing service frame — the same ancestry walk the container executor

package/dist/http/env.d.ts.map

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

package/dist/modules/publicApi/PublicProvisioningController.d.ts

@@ -1,5 +1,6 @@
-import { type BootstrapJob, type GitHubAvailableRepo, type GitHubConnection, type KubernetesManifestSource, type PublicAvailableRepo, type PublicBootstrapJob, type PublicKubernetesManifestSource, type ServiceProvisioning, type UpdatePublicServiceInput } from '@cat-factory/contracts';
+import { type BootstrapJob, type EnvironmentHandlerView, type GitHubAvailableRepo, type GitHubConnection, type KubernetesManifestSource, type PublicAvailableRepo, type PublicBootstrapJob, type PublicEnvironmentHandler, type PublicKubernetesManifestSource, type ServiceProvisioning, type UpdatePublicServiceInput } from '@cat-factory/contracts';
 import type { RepoUseByRepoId } from '@cat-factory/orchestration';
+import { type RepoFileContent, type RunRepoContext } from '@cat-factory/kernel';
 import { Hono } from 'hono';
 import type { AppEnv, ServerContainer } from '../../http/env.js';
 /**
@@ -64,11 +65,66 @@ export declare function toPublicAvailableRepo(repo: GitHubAvailableRepo, use: Re
  * prevent, on the deployment least able to tell that is what happened.
  */
 export declare function asVcsRefusal(error: unknown): unknown;
+/**
+ * Read one file, turning the two answers only this layer can name into the refusals it documents.
+ *
+ * **A blob past the PROVIDER's own contents ceiling is the same refusal as one past ours.** GitHub
+ * reports it as a `403`, which {@link asVcsRefusal} would otherwise read as a rejected credential,
+ * so an operator whose lockfile is 1.4 MB would be told to re-mint a token that works. The adapter
+ * names the fact (`VcsBlobTooLargeError`) and this maps it onto `file_too_large` with the provider's
+ * limit and NO size, because nothing here measured one.
+ *
+ * **Bytes that are not UTF-8 are refused rather than answered.** The decode is lossy for a PNG, a
+ * tarball or a Latin-1 source file, and handing back replacement characters under a field documented
+ * as the file's content is the same lie the truncation above refuses to tell: a caller comparing
+ * against its own copy sees a mismatch it cannot attribute. The `sha` rides the refusal, so the
+ * byte-exact join a grader wanted is still available.
+ *
+ * Anything else is a fact about the provider and goes through {@link asVcsRefusal} unchanged.
+ */
+export declare function readGradableFile(repo: RunRepoContext['repo'], at: string, path: string, ref: string | undefined): Promise<RepoFileContent | null>;
 /**
  * Lower a public manifest source onto the internal one, for the same reason and with the same
  * exhaustiveness as the URL source above.
  */
 export declare function toKubernetesManifestSource(source: PublicKubernetesManifestSource): KubernetesManifestSource;
+/**
+ * Project a handler for the LIST, whatever engine services it.
+ *
+ * `engine` and `backendKind` are open strings here rather than the connect view's literal, because
+ * this read reports handlers the deployment SEEDED from its composition root, and a deployment may
+ * register an environment backend of its own: the whole point of the registry. Reporting one as
+ * `kubernetes` would be the coercion the board projection refuses next door, and omitting it would
+ * make a seeded handler indistinguishable from an absent one, which is the state this read exists to
+ * make checkable.
+ *
+ * `endpoint` and not `apiServerUrl`: the Kubernetes noun is false of every other engine, and stating
+ * it anyway is what sends an operator whose environment is a VM looking for an apiserver.
+ *
+ * BOTH manifest-id fields are reported, because the engine's own resolution
+ * (`resolveInfraHandler` → `matchesCustom`) matches a service's pinned `manifestId` against EITHER,
+ * and the two ways of registering a handler each set only one: a deployment SEEDING one keys it with
+ * `manifestId`, while a `remote-custom` connection declares `acceptsManifestId`. Publishing only the
+ * second made the commonest seed shape read as a handler serving nothing, so a setup script checking
+ * that its own seed landed found no entry naming it while a run against it resolved fine.
+ *
+ * No `config`, though `EnvironmentHandlerView` carries one for the app's connect-form prefill: it is
+ * the internal per-engine bag, deliberately open, and this surface may not freeze it (ADR 0034).
+ */
+export declare function toPublicHandler(view: EnvironmentHandlerView): PublicEnvironmentHandler;
+/**
+ * Order handlers by what IDENTIFIES one, comparing code units rather than collating.
+ *
+ * `localeCompare` is ICU- and locale-dependent, so the same set of handlers can serialise in one
+ * order from a workerd isolate and in another from a Node build with a different ICU: precisely the
+ * spurious diff the ordering was added to prevent. A code-unit comparison answers the same everywhere,
+ * which is what a wire ordering needs.
+ *
+ * Both manifest ids join the key, since two `custom` handlers keyed to different manifests are
+ * otherwise equal here. A handler that ties on all four keys keeps its position from the repository
+ * read (the sort is stable), which is the honest fallback: nothing published distinguishes them.
+ */
+export declare function byHandlerIdentity(left: PublicEnvironmentHandler, right: PublicEnvironmentHandler): number;
 /**
  * Lower a public service patch onto the board patch.
  *

package/dist/modules/publicApi/PublicProvisioningController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PublicProvisioningController.d.ts","sourceRoot":"","sources":["../../../src/modules/publicApi/PublicProvisioningController.ts"],"names":[],"mappings":"AAAA,OAAO,EAaL,KAAK,YAAY,EAEjB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAErB,KAAK,wBAAwB,EAI7B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAGvB,KAAK,8BAA8B,EAQnC,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAKV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAWnC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAgEhE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAQlC;AA6FD,wBAAgB,4BAA4B,IAAI,IAAI,CAAC,MAAM,CAAC,CAQ3D;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,kBAAkB,CAgB1E;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,eAAe,GACnB,mBAAmB,CAsBrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBpD;AAyID;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CAW1B;AAmFD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,mBAAmB,GAAG,SAAS,GACtC;IACD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,mBAAmB,CAAA;CACnC,CAQA"}
+{"version":3,"file":"PublicProvisioningController.d.ts","sourceRoot":"","sources":["../../../src/modules/publicApi/PublicProvisioningController.ts"],"names":[],"mappings":"AAAA,OAAO,EAgBL,KAAK,YAAY,EACjB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EAErB,KAAK,wBAAwB,EAI7B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EAGvB,KAAK,wBAAwB,EAC7B,KAAK,8BAA8B,EAQnC,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC9B,MAAM,wBAAwB,CAAA;AAC/B,OAAO,KAAK,EAKV,eAAe,EAEhB,MAAM,4BAA4B,CAAA;AAEnC,OAAO,EASL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAA;AAE3B,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AAgEhE;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,iBAAiB,CACrC,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAQlC;AA6FD,wBAAgB,4BAA4B,IAAI,IAAI,CAAC,MAAM,CAAC,CAQ3D;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,YAAY,GAAG,kBAAkB,CAgB1E;AAiDD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,mBAAmB,EACzB,GAAG,EAAE,eAAe,GACnB,mBAAmB,CAsBrB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAoBpD;AAoJD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAC5B,EAAE,EAAE,MAAM,EACV,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,GACtB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAsBjC;AA6DD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,8BAA8B,GACrC,wBAAwB,CAW1B;AA8BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,wBAAwB,CAYtF;AA8CD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,wBAAwB,EAC9B,KAAK,EAAE,wBAAwB,GAC9B,MAAM,CAOR;AAiCD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,wBAAwB,EAC/B,MAAM,EAAE,mBAAmB,GAAG,SAAS,GACtC;IACD,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,YAAY,CAAC,EAAE,mBAAmB,CAAA;CACnC,CAQA"}

package/dist/modules/publicApi/PublicProvisioningController.js

@@ -1,5 +1,5 @@
-import { connectPublicEnvironmentContract, getPublicRepoBootstrapContract, getPublicVcsConnectionContract, linkPublicRepoContract, listPublicAvailableReposContract, listPublicModelPresetsContract, listPublicRiskPoliciesContract, listPublicWiredModelsContract, startPublicRepoBootstrapContract, testPublicEnvironmentConnectionContract, updatePublicServiceContract, UNATTRIBUTED_BLOCK_EDIT_AUTHORITY, } from '@cat-factory/contracts';
-import { NotFoundError, RateLimitedError, UnavailableError, VcsApiError, individualVendorForModelId, isVcsRateLimited, } from '@cat-factory/kernel';
+import { connectPublicEnvironmentContract, getPublicRepoBootstrapContract, getPublicRepoFileContract, getPublicVcsConnectionContract, linkPublicRepoContract, listPublicAvailableReposContract, listPublicEnvironmentConnectionsContract, listPublicModelPresetsContract, listPublicRiskPoliciesContract, listPublicWiredModelsContract, MAX_REPO_FILE_CHARS, startPublicRepoBootstrapContract, testPublicEnvironmentConnectionContract, updatePublicServiceContract, UNATTRIBUTED_BLOCK_EDIT_AUTHORITY, } from '@cat-factory/contracts';
+import { NotFoundError, RateLimitedError, UnavailableError, ValidationError, VcsApiError, VcsBlobTooLargeError, individualVendorForModelId, isVcsRateLimited, } from '@cat-factory/kernel';
 import { buildHonoRoute } from '@toad-contracts/hono';
 import { Hono } from 'hono';
 import { requireCapability } from '../../http/guards.js';
@@ -365,6 +365,99 @@ function registerRepoAdoptionRoutes(app) {
         }
         return c.json(toPublicRepo(adopted), 200);
     });
+    registerRepoFileRoute(app);
+}
+/**
+ * ONE file out of a linked repository, so a caller can grade what a run COMMITTED.
+ *
+ * It closes the loop on everything else this surface can start. A caller could create a repository,
+ * adopt one, file work against it and watch a run merge, and then had nothing to read but the
+ * agent's own final reply, which is asserting on model prose: swap the model and it goes red having
+ * found nothing wrong. The only real alternative was a SECOND VCS credential in the caller's config,
+ * with its own scopes to get right, for data the workspace's own connection already reads.
+ *
+ * Five outcomes, kept apart because each takes a different action, and because folding any of them
+ * onto "no such file" is the same mistake `PublicSpecController` documents at length: a repository
+ * that answers nothing and a file that is genuinely absent look identical from a provider. Two of the
+ * five are what {@link readGradableFile} exists to name.
+ */
+function registerRepoFileRoute(app) {
+    buildHonoRoute(app, getPublicRepoFileContract, async (c) => {
+        const auth = await authorizeOrThrow(c, getPublicRepoFileContract.minScope);
+        const resolve = requireCapability(c.get('container').resolveRepoFilesForCoords, 'No version-control integration is configured for this deployment', 'vcs_not_configured');
+        const { owner, name } = c.req.valid('param');
+        const { path, ref } = c.req.valid('query');
+        // Resolved against the workspace's PROJECTED repos, so this reads only what this workspace has
+        // LINKED. A repository the deployment's credential could reach and nobody adopted is absent
+        // here exactly as it is from `GET /api/v1/repos`, which is what stops the endpoint becoming a
+        // way to read any repository an installation happens to cover.
+        const context = await resolve(auth.workspaceId, { owner, repo: name });
+        if (!context) {
+            throw new NotFoundError('repository', `${owner}/${name}`, { reason: 'repo_not_linked' });
+        }
+        // `ref` is passed through EXACTLY as the request gave it, absent included, because the port
+        // resolves the repository's own default branch for an omitted one. `context.baseBranch` is the
+        // wrong value to substitute: `makeResolveRepoFilesForCoords` INVENTS `main` for a projection row
+        // carrying no default branch, so a repository whose default is `master` would be read at a
+        // branch it does not have and answer `file_not_found` for a file that is right there, while the
+        // response named the invented branch as the thing graded.
+        const at = `${owner}/${name}:${path}`;
+        const file = await readGradableFile(context.repo, at, path, ref);
+        if (!file) {
+            throw new NotFoundError('file', `${at}@${ref ?? 'the default branch'}`, {
+                reason: 'file_not_found',
+            });
+        }
+        if (file.content.length > MAX_REPO_FILE_CHARS) {
+            // REFUSED, never truncated. A caller reading a file to grade what an agent committed is
+            // joining on its exact bytes, and a silently shortened answer is indistinguishable from an
+            // agent that wrote a shorter file. The size and the limit ride `details` because those are
+            // facts a caller can act on where a truncation is not.
+            //
+            // A 422 and not a 413: `Content Too Large` is a statement about the REQUEST entity, and this
+            // request is perfectly well formed. The status class is "structurally valid, refused by a
+            // domain rule", which is the same reading `resolveRepoTarget` takes for an unlinked service,
+            // and the machine-readable cause is `details.reason` as it is everywhere else on this surface.
+            throw new ValidationError(`${at} is ${file.content.length} characters, past the ${MAX_REPO_FILE_CHARS} this read ` +
+                `answers with`, { reason: 'file_too_large', size: file.content.length, limit: MAX_REPO_FILE_CHARS });
+        }
+        return c.json({ owner, name, path, ref: ref ?? null, sha: file.sha, content: file.content }, 200);
+    });
+}
+/**
+ * Read one file, turning the two answers only this layer can name into the refusals it documents.
+ *
+ * **A blob past the PROVIDER's own contents ceiling is the same refusal as one past ours.** GitHub
+ * reports it as a `403`, which {@link asVcsRefusal} would otherwise read as a rejected credential,
+ * so an operator whose lockfile is 1.4 MB would be told to re-mint a token that works. The adapter
+ * names the fact (`VcsBlobTooLargeError`) and this maps it onto `file_too_large` with the provider's
+ * limit and NO size, because nothing here measured one.
+ *
+ * **Bytes that are not UTF-8 are refused rather than answered.** The decode is lossy for a PNG, a
+ * tarball or a Latin-1 source file, and handing back replacement characters under a field documented
+ * as the file's content is the same lie the truncation above refuses to tell: a caller comparing
+ * against its own copy sees a mismatch it cannot attribute. The `sha` rides the refusal, so the
+ * byte-exact join a grader wanted is still available.
+ *
+ * Anything else is a fact about the provider and goes through {@link asVcsRefusal} unchanged.
+ */
+export async function readGradableFile(repo, at, path, ref) {
+    let file;
+    try {
+        file = await repo.getFile(path, ref);
+    }
+    catch (error) {
+        if (error instanceof VcsBlobTooLargeError) {
+            throw new ValidationError(`${at} is past the ${error.limitBytes} bytes ${error.provider} will serve through its ` +
+                `contents API, so this read cannot answer with it`, { reason: 'file_too_large', limit: error.limitBytes });
+        }
+        throw asVcsRefusal(error);
+    }
+    if (file?.lossy) {
+        throw new ValidationError(`${at} is not UTF-8 text, so this read cannot answer with its content; its blob sha is ` +
+            `${file.sha}`, { reason: 'file_not_text', sha: file.sha });
+    }
+    return file;
 }
 // ---- the environment connection (the ENGINE half) ---------------------------
 /**
@@ -449,6 +542,10 @@ function toInfraHandlerConfig(connection) {
  *
  * `baseUrl` is the connection's own endpoint, which for a Kubernetes engine is the apiserver, so it
  * is reported under the name the caller supplied it as rather than the engine's generic one.
+ *
+ * The CONNECT response only, which is why `engine` can be the literal: this surface registers
+ * kubernetes and nothing else, so it is true of every handler this call can produce. The LIST is a
+ * different question and takes {@link toPublicHandler}.
  */
 function toPublicConnectionView(view) {
     return {
@@ -459,6 +556,42 @@ function toPublicConnectionView(view) {
         secretKeys: view.secretKeys,
     };
 }
+/**
+ * Project a handler for the LIST, whatever engine services it.
+ *
+ * `engine` and `backendKind` are open strings here rather than the connect view's literal, because
+ * this read reports handlers the deployment SEEDED from its composition root, and a deployment may
+ * register an environment backend of its own: the whole point of the registry. Reporting one as
+ * `kubernetes` would be the coercion the board projection refuses next door, and omitting it would
+ * make a seeded handler indistinguishable from an absent one, which is the state this read exists to
+ * make checkable.
+ *
+ * `endpoint` and not `apiServerUrl`: the Kubernetes noun is false of every other engine, and stating
+ * it anyway is what sends an operator whose environment is a VM looking for an apiserver.
+ *
+ * BOTH manifest-id fields are reported, because the engine's own resolution
+ * (`resolveInfraHandler` → `matchesCustom`) matches a service's pinned `manifestId` against EITHER,
+ * and the two ways of registering a handler each set only one: a deployment SEEDING one keys it with
+ * `manifestId`, while a `remote-custom` connection declares `acceptsManifestId`. Publishing only the
+ * second made the commonest seed shape read as a handler serving nothing, so a setup script checking
+ * that its own seed landed found no entry naming it while a run against it resolved fine.
+ *
+ * No `config`, though `EnvironmentHandlerView` carries one for the app's connect-form prefill: it is
+ * the internal per-engine bag, deliberately open, and this surface may not freeze it (ADR 0034).
+ */
+export function toPublicHandler(view) {
+    return {
+        provisionType: view.provisionType,
+        manifestId: view.manifestId,
+        acceptsManifestId: view.acceptsManifestId,
+        engine: view.engine,
+        backendKind: view.backendKind,
+        label: view.label,
+        endpoint: view.baseUrl,
+        secretKeys: view.secretKeys,
+        connectedAt: view.connectedAt,
+    };
+}
 function registerEnvironmentRoutes(app) {
     // Probe without persisting. `ok: false` is an ANSWER (the cluster refused the token), so it is a
     // 200 carrying the verdict rather than an error: a caller distinguishes "the cluster said no"
@@ -490,6 +623,41 @@ function registerEnvironmentRoutes(app) {
         });
         return c.json(toPublicConnectionView(view), 201);
     });
+    // The read half. Ordered so a caller diffing two workspaces (or its own setup before and after)
+    // compares two stable lists rather than two insertion orders.
+    buildHonoRoute(app, listPublicEnvironmentConnectionsContract, async (c) => {
+        const auth = await authorizeOrThrow(c, listPublicEnvironmentConnectionsContract.minScope);
+        const environments = requireEnvironments(c);
+        const handlers = await environments.connectionService.listHandlers(auth.workspaceId);
+        const connections = handlers.map(toPublicHandler).sort(byHandlerIdentity);
+        return c.json({ connections }, 200);
+    });
+}
+/**
+ * Order handlers by what IDENTIFIES one, comparing code units rather than collating.
+ *
+ * `localeCompare` is ICU- and locale-dependent, so the same set of handlers can serialise in one
+ * order from a workerd isolate and in another from a Node build with a different ICU: precisely the
+ * spurious diff the ordering was added to prevent. A code-unit comparison answers the same everywhere,
+ * which is what a wire ordering needs.
+ *
+ * Both manifest ids join the key, since two `custom` handlers keyed to different manifests are
+ * otherwise equal here. A handler that ties on all four keys keeps its position from the repository
+ * read (the sort is stable), which is the honest fallback: nothing published distinguishes them.
+ */
+export function byHandlerIdentity(left, right) {
+    return (compareCodeUnits(left.provisionType, right.provisionType) ||
+        compareCodeUnits(left.manifestId, right.manifestId) ||
+        compareCodeUnits(left.acceptsManifestId, right.acceptsManifestId) ||
+        compareCodeUnits(left.label, right.label));
+}
+/** An absent id sorts first, which is the only ordering a null can honestly take. */
+function compareCodeUnits(left, right) {
+    const a = left ?? '';
+    const b = right ?? '';
+    if (a === b)
+        return 0;
+    return a < b ? -1 : 1;
 }
 // ---- a service's provisioning (the SOURCE half) -----------------------------
 function registerServiceRoutes(app) {
@@ -529,7 +697,7 @@ export function toBlockPatch(input, stored) {
  * Overlay a public provisioning patch onto what the service already declares.
  *
  * `provisioning` is ONE JSON column and `updateBlock` REPLACES it wholesale, where this surface
- * publishes two of its dozen fields. Writing just the pair would therefore delete every field the
+ * publishes a few of its dozen fields. Writing just those would therefore delete every field the
  * public shape cannot express: a Kubernetes service's `images`, `secretInjections` and
  * `helmReleases`, authored in the app by someone who is not the caller. The next deploy would
  * render manifests with no image overrides and no Secrets, which is the "empty environment that
@@ -539,14 +707,42 @@ export function toBlockPatch(input, stored) {
  * A patch that CHANGES the provision type replaces instead of overlaying: the stored remainder
  * belongs to the type being left behind, so carrying it forward would attach one engine's
  * configuration to another.
+ *
+ * Exhaustive over the public variant through a `never`, so a member added there cannot reach the
+ * stored column as an unlowered shape.
  */
 function mergeProvisioning(patch, stored) {
     const base = stored?.type === patch.type ? stored : undefined;
-    return {
-        ...base,
-        type: patch.type,
-        manifestSource: toKubernetesManifestSource(patch.manifestSource),
-    };
+    switch (patch.type) {
+        case 'kubernetes':
+            return {
+                ...base,
+                type: 'kubernetes',
+                manifestSource: toKubernetesManifestSource(patch.manifestSource),
+            };
+        case 'custom': {
+            // `manifestPath` is the one stored field this surface PUBLISHES, so it is also the only one a
+            // patch can be said to have left out on purpose: omitted, it is CLEARED, and the manifest
+            // type's own default applies again. Carried over from the stored row (which is what a plain
+            // `...base` does), a caller correcting a path back to the default would keep deploying the old
+            // one and have no way to say so, since the public shape has no other way to express "none".
+            // Every field the public shape cannot express still rides `...rest`, for the reason the
+            // function's own doc gives.
+            const { manifestPath: _cleared, ...rest } = base ?? {};
+            return {
+                ...rest,
+                type: 'custom',
+                manifestId: patch.manifestId,
+                ...(patch.manifestPath === undefined ? {} : { manifestPath: patch.manifestPath }),
+            };
+        }
+        default:
+            return unreachableProvisioning(patch);
+    }
+}
+/** The compile-time half of the lowering above: a new public member has to be lowered explicitly. */
+function unreachableProvisioning(value) {
+    throw new Error(`unmapped public service provisioning: ${JSON.stringify(value)}`);
 }
 // ---- what this deployment has WIRED -----------------------------------------
 /**