@ever-works/github-actions-build-plugin 1.0.2 → 1.0.4

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { BuildValue, JsonSchema, IBuildPlugin, PluginCategory, BuildStrategy, PluginContext, BuildAuth, PluginManifest, PrepareRepositoryInput, RepositoryWriter, PrepareRepositoryResult, StartBuildInput, BuildRef, BuildSnapshot, AppBuildBlock, RepositoryWriteErrorCode } from '@ever-works/plugin';
+import { BuildValue, JsonSchema, IBuildPlugin, PluginCategory, BuildStrategy, PluginContext, BuildAuth, PluginManifest, PrepareRepositoryInput, RepositoryWriter, PrepareRepositoryResult, StartBuildInput, BuildRef, BuildSnapshot, BuildRunRef, AppBuildBlock, RepositoryWriteErrorCode } from '@ever-works/plugin';
 import { AppBuildBlockedReason, AppBuildKind, AppBuildRunnerClass, APP_BUILD_GENERATOR_VERSION } from '@ever-works/contracts';
 import sodiumType from 'libsodium-wrappers';
 
@@ -47,6 +47,10 @@ interface ActionsRun {
     readonly pull_requests?: ReadonlyArray<{
         readonly number?: number | null;
     }> | null;
+    /** The repository the run's head commit lives in — a fork's for a fork pull request (§7.5, ACC-05-06). */
+    readonly head_repository?: {
+        readonly full_name?: string | null;
+    } | null;
 }
 /** One job of a run (`GET /repos/{o}/{r}/actions/runs/{id}/jobs`). */
 interface ActionsJob {
@@ -105,6 +109,24 @@ interface ActionsRunsPort {
         readonly headSha?: string;
         readonly event?: string;
     }): Promise<readonly ActionsRun[]>;
+    /**
+     * Run discovery's conditional read (§7.4a): the same list as
+     * {@link ActionsRunsPort.listWorkflowRuns}, sent with `If-None-Match` when an
+     * `etag` is given. A 304 answers `{ notModified: true, runs: [] }`.
+     *
+     * Optional — an adapter without it is read unconditionally through
+     * `listWorkflowRuns`, which costs a request but is never wrong.
+     */
+    listWorkflowRunsConditional?(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly workflowFile: string;
+        readonly perPage: number;
+        readonly etag?: string;
+    }): Promise<{
+        readonly notModified: boolean;
+        readonly etag?: string;
+        readonly runs: readonly ActionsRun[];
+    }>;
     /** `GET /repos/{o}/{r}/actions/runs/{id}`. `null` when GitHub answers 404. */
     getWorkflowRun(input: {
         readonly repository: ActionsRepositoryRef;
@@ -331,6 +353,53 @@ declare function isSecretLimitError(error: unknown): boolean;
  */
 declare function createBuildValueSecretSync(dependencies: SecretSyncDependencies): BuildValueSecretSync;
 
+/**
+ * APW-05 T16 remainder (outstanding-work A0.4, ledger D19) — the clone-free
+ * {@link RepositoryWriter} over GitHub's REST API.
+ *
+ * ## Why the build plugin carries its own writer
+ *
+ * `prepareRepository` needs four repository operations — read a file, land one
+ * commit, create a branch, open a pull request — and plan §4.1 says the facade
+ * binds them "to `GitFacadeService`". That facade has three of the four but no
+ * `commitFiles` (APW-03 T22 declares it and has not landed), so every production
+ * prepare answered `pluginUnavailable` before the request was even built. This
+ * plugin already holds Octokit and the member's token, and every one of the four
+ * is a plain REST call, so it supplies the writer itself
+ * (`IBuildPlugin.repositoryWriter?`) and the facade prefers it. When APW-03 T22
+ * lands a git-provider `commitFiles`, the facade may bind that instead; nothing
+ * in `workflow-writer.ts` changes either way.
+ *
+ * ## The refusal codes the contract names
+ *
+ * A refusal is THROWN with `code` set, which is what `repositoryWriteErrorCode`
+ * reads:
+ *
+ *  - `nonFastForward` — `PATCH …/git/refs/heads/<branch>` answered 422 "not a
+ *    fast forward": the branch moved under us, and the caller retries from a
+ *    fresh head (never a force-push);
+ *  - `refRejectedByRule` — 409/422 mentioning a protection rule or a
+ *    required status/review: the caller switches to the pull-request path;
+ *  - `pullRequestExists` — 422 "A pull request already exists";
+ *  - `workflowPermissionMissing` (2026-10-17) — the credential cannot write
+ *    under `.github/workflows/`: an OAuth token or classic PAT without the
+ *    `workflow` scope, or a GitHub App installation without `Workflows: write`
+ *    (APW-02 plan §4's permission matrix). Checked BEFORE the commit when the
+ *    scopes are known or readable (`x-oauth-scopes`), and translated from
+ *    GitHub's own refusal otherwise, so the member is told to reconnect GitHub
+ *    with the `workflow` scope instead of seeing a bare 403/404.
+ *
+ * Every other failure is rethrown untouched.
+ */
+/** The subset of Octokit's surface this writer uses. */
+interface OctokitRequester {
+    request(route: string, params?: Record<string, unknown>): Promise<{
+        data: unknown;
+        status?: number;
+        headers?: Record<string, unknown>;
+    }>;
+}
+
 /**
  * APW-05 T7 — the `github-actions-build` plugin settings (plan §4.4, setting by
  * setting), and the one place the two platform-managed keys are declared.
@@ -519,10 +588,11 @@ declare const gitHubActionsBuildSettingsSchema: GitHubActionsBuildSettingsSchema
  * always, and `AppBuildsService.finalize` does the comparison, because it is the
  * only party holding both the Build row and the `pullToken` setting.
  *
- * `listRecentRuns?` (T12's run discovery, §7.4a) is still deliberately **not
- * declared**: it is optional on the contract and a caller materialises the member
- * before calling it, so declaring a throwing placeholder would buy nothing and
- * would tell a future reader the capability is wired when it is not.
+ * `listRecentRuns?` (T21a's run discovery, §7.4a) is declared now that it does
+ * something (2026-10-17): it reads the build workflow's newest runs with
+ * `If-None-Match` and maps them through contracts' `githubRunToBuildRunRef`, the
+ * same mapping the `workflow_run` consumer uses. `repositoryWriter?` (the
+ * clone-free writer `prepareRepository` delivers through) landed with it.
  */
 declare class GitHubActionsBuildPlugin implements IBuildPlugin {
     readonly id = "github-actions-build";
@@ -741,6 +811,66 @@ declare class GitHubActionsBuildPlugin implements IBuildPlugin {
      * nor `ghcr.io`, and that module's spec watches every call for exactly that.
      */
     protected registryFetch(): GhcrFetch;
+    /**
+     * APW-05 T21a / T12 remainder — run discovery (plan §7.4a, `APW05-G01`).
+     *
+     * The newest runs of the build workflow, so a push or pull-request Build is
+     * recorded even when no `workflow_run` delivery reaches the platform (a
+     * personal fork connected through OAuth has no App installation to deliver
+     * from). `If-None-Match` with the stored `etag` makes an idle repository cost
+     * a 304 — which GitHub does not count against the rate limit.
+     *
+     * The mapping is `githubRunToBuildRunRef` from contracts, the SAME function
+     * the webhook consumer uses, so a polled run and a delivered run are the same
+     * `BuildRunRef` and converge on one Build row.
+     */
+    listRecentRuns(input: {
+        repository: {
+            owner: string;
+            name: string;
+        };
+        workflowPath: string;
+        perPage: number;
+        etag?: string;
+    }, auth: BuildAuth): Promise<{
+        notModified: boolean;
+        etag?: string;
+        runs: BuildRunRef[];
+    }>;
+    /**
+     * APW-05 T16 remainder — the clone-free writer `prepareRepository` delivers the
+     * workflow through, over this plugin's own Octokit (see
+     * `repo/octokit-repository-writer.ts` on why the plugin supplies it).
+     */
+    repositoryWriter(repository: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly trackedBranch?: string;
+    }, auth: BuildAuth): RepositoryWriter;
+    /**
+     * Plan §5 — a Rebuild's `commitSha` must be reachable from the tracked branch
+     * (2026-10-17). `GET …/compare/{sha}...{branch}`: `ahead` or `identical` means
+     * the commit is in the branch's history; `behind` / `diverged` means it is not
+     * (a commit only a fork's network carries is `diverged`), and 404/422 means
+     * GitHub does not know it here. Any other failure is a throw.
+     */
+    isCommitReachable(input: {
+        readonly repository: {
+            readonly owner: string;
+            readonly repo: string;
+        };
+        readonly sha: string;
+        readonly branch: string;
+    }, auth: BuildAuth): Promise<boolean>;
+    /** §4.10 — the per-run prompted-value secret's removal (T12's `secret-sync.ts`, now on the contract). */
+    deleteVerifyPromptedSecret(repository: {
+        readonly owner: string;
+        readonly repo: string;
+    }, auth: BuildAuth): Promise<{
+        readonly deleted: boolean;
+    }>;
+    /** The Octokit client for one call — a seam a spec overrides, like {@link actionsPort}. */
+    protected octokitFor(auth: BuildAuth): OctokitRequester;
     /** APW-05 T12 — the run's own page, which is where a member reads its logs. */
     getLogsUrl(ref: BuildRef, auth: BuildAuth): Promise<string | null>;
 }
@@ -1447,6 +1577,13 @@ interface WorkflowWriteResult {
         readonly detail: {
             readonly cause: string;
         };
+    } | {
+        readonly reason: 'workflowPermissionMissing';
+        readonly detail: {
+            readonly cause: string;
+            readonly credential: string;
+            readonly missing: string;
+        };
     };
 }
 /** The refusal code of a thrown write error, if it is one of the codes the contract names. */

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BuildValue, JsonSchema, IBuildPlugin, PluginCategory, BuildStrategy, PluginContext, BuildAuth, PluginManifest, PrepareRepositoryInput, RepositoryWriter, PrepareRepositoryResult, StartBuildInput, BuildRef, BuildSnapshot, AppBuildBlock, RepositoryWriteErrorCode } from '@ever-works/plugin';
+import { BuildValue, JsonSchema, IBuildPlugin, PluginCategory, BuildStrategy, PluginContext, BuildAuth, PluginManifest, PrepareRepositoryInput, RepositoryWriter, PrepareRepositoryResult, StartBuildInput, BuildRef, BuildSnapshot, BuildRunRef, AppBuildBlock, RepositoryWriteErrorCode } from '@ever-works/plugin';
 import { AppBuildBlockedReason, AppBuildKind, AppBuildRunnerClass, APP_BUILD_GENERATOR_VERSION } from '@ever-works/contracts';
 import sodiumType from 'libsodium-wrappers';
 
@@ -47,6 +47,10 @@ interface ActionsRun {
     readonly pull_requests?: ReadonlyArray<{
         readonly number?: number | null;
     }> | null;
+    /** The repository the run's head commit lives in — a fork's for a fork pull request (§7.5, ACC-05-06). */
+    readonly head_repository?: {
+        readonly full_name?: string | null;
+    } | null;
 }
 /** One job of a run (`GET /repos/{o}/{r}/actions/runs/{id}/jobs`). */
 interface ActionsJob {
@@ -105,6 +109,24 @@ interface ActionsRunsPort {
         readonly headSha?: string;
         readonly event?: string;
     }): Promise<readonly ActionsRun[]>;
+    /**
+     * Run discovery's conditional read (§7.4a): the same list as
+     * {@link ActionsRunsPort.listWorkflowRuns}, sent with `If-None-Match` when an
+     * `etag` is given. A 304 answers `{ notModified: true, runs: [] }`.
+     *
+     * Optional — an adapter without it is read unconditionally through
+     * `listWorkflowRuns`, which costs a request but is never wrong.
+     */
+    listWorkflowRunsConditional?(input: {
+        readonly repository: ActionsRepositoryRef;
+        readonly workflowFile: string;
+        readonly perPage: number;
+        readonly etag?: string;
+    }): Promise<{
+        readonly notModified: boolean;
+        readonly etag?: string;
+        readonly runs: readonly ActionsRun[];
+    }>;
     /** `GET /repos/{o}/{r}/actions/runs/{id}`. `null` when GitHub answers 404. */
     getWorkflowRun(input: {
         readonly repository: ActionsRepositoryRef;
@@ -331,6 +353,53 @@ declare function isSecretLimitError(error: unknown): boolean;
  */
 declare function createBuildValueSecretSync(dependencies: SecretSyncDependencies): BuildValueSecretSync;
 
+/**
+ * APW-05 T16 remainder (outstanding-work A0.4, ledger D19) — the clone-free
+ * {@link RepositoryWriter} over GitHub's REST API.
+ *
+ * ## Why the build plugin carries its own writer
+ *
+ * `prepareRepository` needs four repository operations — read a file, land one
+ * commit, create a branch, open a pull request — and plan §4.1 says the facade
+ * binds them "to `GitFacadeService`". That facade has three of the four but no
+ * `commitFiles` (APW-03 T22 declares it and has not landed), so every production
+ * prepare answered `pluginUnavailable` before the request was even built. This
+ * plugin already holds Octokit and the member's token, and every one of the four
+ * is a plain REST call, so it supplies the writer itself
+ * (`IBuildPlugin.repositoryWriter?`) and the facade prefers it. When APW-03 T22
+ * lands a git-provider `commitFiles`, the facade may bind that instead; nothing
+ * in `workflow-writer.ts` changes either way.
+ *
+ * ## The refusal codes the contract names
+ *
+ * A refusal is THROWN with `code` set, which is what `repositoryWriteErrorCode`
+ * reads:
+ *
+ *  - `nonFastForward` — `PATCH …/git/refs/heads/<branch>` answered 422 "not a
+ *    fast forward": the branch moved under us, and the caller retries from a
+ *    fresh head (never a force-push);
+ *  - `refRejectedByRule` — 409/422 mentioning a protection rule or a
+ *    required status/review: the caller switches to the pull-request path;
+ *  - `pullRequestExists` — 422 "A pull request already exists";
+ *  - `workflowPermissionMissing` (2026-10-17) — the credential cannot write
+ *    under `.github/workflows/`: an OAuth token or classic PAT without the
+ *    `workflow` scope, or a GitHub App installation without `Workflows: write`
+ *    (APW-02 plan §4's permission matrix). Checked BEFORE the commit when the
+ *    scopes are known or readable (`x-oauth-scopes`), and translated from
+ *    GitHub's own refusal otherwise, so the member is told to reconnect GitHub
+ *    with the `workflow` scope instead of seeing a bare 403/404.
+ *
+ * Every other failure is rethrown untouched.
+ */
+/** The subset of Octokit's surface this writer uses. */
+interface OctokitRequester {
+    request(route: string, params?: Record<string, unknown>): Promise<{
+        data: unknown;
+        status?: number;
+        headers?: Record<string, unknown>;
+    }>;
+}
+
 /**
  * APW-05 T7 — the `github-actions-build` plugin settings (plan §4.4, setting by
  * setting), and the one place the two platform-managed keys are declared.
@@ -519,10 +588,11 @@ declare const gitHubActionsBuildSettingsSchema: GitHubActionsBuildSettingsSchema
  * always, and `AppBuildsService.finalize` does the comparison, because it is the
  * only party holding both the Build row and the `pullToken` setting.
  *
- * `listRecentRuns?` (T12's run discovery, §7.4a) is still deliberately **not
- * declared**: it is optional on the contract and a caller materialises the member
- * before calling it, so declaring a throwing placeholder would buy nothing and
- * would tell a future reader the capability is wired when it is not.
+ * `listRecentRuns?` (T21a's run discovery, §7.4a) is declared now that it does
+ * something (2026-10-17): it reads the build workflow's newest runs with
+ * `If-None-Match` and maps them through contracts' `githubRunToBuildRunRef`, the
+ * same mapping the `workflow_run` consumer uses. `repositoryWriter?` (the
+ * clone-free writer `prepareRepository` delivers through) landed with it.
  */
 declare class GitHubActionsBuildPlugin implements IBuildPlugin {
     readonly id = "github-actions-build";
@@ -741,6 +811,66 @@ declare class GitHubActionsBuildPlugin implements IBuildPlugin {
      * nor `ghcr.io`, and that module's spec watches every call for exactly that.
      */
     protected registryFetch(): GhcrFetch;
+    /**
+     * APW-05 T21a / T12 remainder — run discovery (plan §7.4a, `APW05-G01`).
+     *
+     * The newest runs of the build workflow, so a push or pull-request Build is
+     * recorded even when no `workflow_run` delivery reaches the platform (a
+     * personal fork connected through OAuth has no App installation to deliver
+     * from). `If-None-Match` with the stored `etag` makes an idle repository cost
+     * a 304 — which GitHub does not count against the rate limit.
+     *
+     * The mapping is `githubRunToBuildRunRef` from contracts, the SAME function
+     * the webhook consumer uses, so a polled run and a delivered run are the same
+     * `BuildRunRef` and converge on one Build row.
+     */
+    listRecentRuns(input: {
+        repository: {
+            owner: string;
+            name: string;
+        };
+        workflowPath: string;
+        perPage: number;
+        etag?: string;
+    }, auth: BuildAuth): Promise<{
+        notModified: boolean;
+        etag?: string;
+        runs: BuildRunRef[];
+    }>;
+    /**
+     * APW-05 T16 remainder — the clone-free writer `prepareRepository` delivers the
+     * workflow through, over this plugin's own Octokit (see
+     * `repo/octokit-repository-writer.ts` on why the plugin supplies it).
+     */
+    repositoryWriter(repository: {
+        readonly owner: string;
+        readonly repo: string;
+        readonly trackedBranch?: string;
+    }, auth: BuildAuth): RepositoryWriter;
+    /**
+     * Plan §5 — a Rebuild's `commitSha` must be reachable from the tracked branch
+     * (2026-10-17). `GET …/compare/{sha}...{branch}`: `ahead` or `identical` means
+     * the commit is in the branch's history; `behind` / `diverged` means it is not
+     * (a commit only a fork's network carries is `diverged`), and 404/422 means
+     * GitHub does not know it here. Any other failure is a throw.
+     */
+    isCommitReachable(input: {
+        readonly repository: {
+            readonly owner: string;
+            readonly repo: string;
+        };
+        readonly sha: string;
+        readonly branch: string;
+    }, auth: BuildAuth): Promise<boolean>;
+    /** §4.10 — the per-run prompted-value secret's removal (T12's `secret-sync.ts`, now on the contract). */
+    deleteVerifyPromptedSecret(repository: {
+        readonly owner: string;
+        readonly repo: string;
+    }, auth: BuildAuth): Promise<{
+        readonly deleted: boolean;
+    }>;
+    /** The Octokit client for one call — a seam a spec overrides, like {@link actionsPort}. */
+    protected octokitFor(auth: BuildAuth): OctokitRequester;
     /** APW-05 T12 — the run's own page, which is where a member reads its logs. */
     getLogsUrl(ref: BuildRef, auth: BuildAuth): Promise<string | null>;
 }
@@ -1447,6 +1577,13 @@ interface WorkflowWriteResult {
         readonly detail: {
             readonly cause: string;
         };
+    } | {
+        readonly reason: 'workflowPermissionMissing';
+        readonly detail: {
+            readonly cause: string;
+            readonly credential: string;
+            readonly missing: string;
+        };
     };
 }
 /** The refusal code of a thrown write error, if it is one of the codes the contract names. */