@pepys/source-github 0.2.0 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@
 
   <p>
     <a href="../../docs/README.md">Documentation</a> •
-    <a href="../../docs/design/v1-plug-ins.md">The plug-ins of v1</a>
+    <a href="../../docs/architecture/plug-ins/github.md">The GitHub plug-in</a>
   </p>
 </div>
 
@@ -20,7 +20,23 @@ with its consumer.
 ## Install
 
 ```sh
-bun add @pepys/source-github
+bun add @pepys/source-github @pepys/kit
+bun add -d @pepys/cli
+```
+
+Add the plug-in to a deployment, then build its consumers. The build compiles each consumer, which
+needs zig and wasm-tools, as the [CLI README](../cli/README.md) says.
+
+```ts
+// deployment.ts
+import { defineDeployment } from '@pepys/kit';
+import { githubPlugin } from '@pepys/source-github';
+
+export const deployment = defineDeployment({ name: 'home', plugins: [githubPlugin] });
+```
+
+```sh
+bunx pepys build deployment.ts --out build
 ```
 
 ## Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pepys/source-github",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The pepys GitHub plug-in: pull requests, releases, commits and deploys",
   "license": "MIT",
   "repository": {
@@ -19,9 +19,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@pepys/api": "0.2.0",
-    "@pepys/ingest": "0.2.0",
-    "@pepys/kit": "0.2.0",
+    "@pepys/api": "0.3.0",
+    "@pepys/ingest": "0.3.0",
+    "@pepys/kit": "0.3.0",
     "@zgeoff/std": "0.4.3",
     "kysely": "0.29.8",
     "ts-pattern": "5.9.2",
@@ -29,7 +29,8 @@
   },
   "devDependencies": {
     "@msw/data": "1.1.8",
-    "@pepys/testing": "0.2.0",
+    "@orpc/client": "2.0.0-beta.50",
+    "@pepys/testing": "0.3.0",
     "msw": "3.0.3",
     "tiny-invariant": "1.3.3"
   }

package/src/api/serve-api.ts

@@ -2,7 +2,8 @@ import { serveAPI } from '@pepys/api';
 import { defineDeployment } from '@pepys/kit';
 import { githubPlugin } from '../github-plugin.ts';
 
-serveAPI({
+await serveAPI({
   deployment: defineDeployment({ name: 'github', plugins: [githubPlugin] }),
   environment: process.env,
+  argv: process.argv.slice(2),
 });

package/src/generated/github-deploy-boundary.ts

@@ -85,6 +85,10 @@ export function updateGithubDeployModel(model: GithubDeployModel, message: Githu
   return message.kind === 'reset' ? initGithubDeployModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubRefPushedPayload {
   ref: string;
   repository: GithubRefPushedPayloadRepository;
@@ -103,8 +107,8 @@ export interface GithubDeploymentPayloadDeployment {
 }
 
 export type GithubDeployFact =
-  | { id: string; type: 'github.ref.pushed'; entity: string; at: string; payload: GithubRefPushedPayload }
-  | { id: string; type: 'github.deployment.created' | 'github.deployment.status_created'; entity: string; at: string; payload: GithubDeploymentPayload };
+  | { id: FactID; type: 'github.ref.pushed'; entity: EntityID; at: string; payload: GithubRefPushedPayload }
+  | { id: FactID; type: 'github.deployment.created' | 'github.deployment.status_created'; entity: EntityID; at: string; payload: GithubDeploymentPayload };
 
 export function parseGithubDeployFact(factJSON: string): GithubDeployFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -127,6 +131,10 @@ function decodeGithubDeployFact(value: unknown): GithubDeployFact | undefined {
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.ref.pushed') {
     const decoded = decodeGithubRefPushedPayload(payload);
 
@@ -150,6 +158,14 @@ function decodeGithubDeployFact(value: unknown): GithubDeployFact | undefined {
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubRefPushedPayload(value: unknown): GithubRefPushedPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-pull-request-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubPullRequestModel(model: GithubPullRequestModel, mess
   return message.kind === 'reset' ? initGithubPullRequestModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubPullRequestPayload {
   action: string;
   pull_request: GithubPullRequestPayloadPullRequest;
@@ -56,7 +60,7 @@ export interface GithubPullRequestPayloadPullRequest {
 }
 
 export type GithubPullRequestFact =
-  | { id: string; type: 'github.pull_request.assigned' | 'github.pull_request.auto_merge_disabled' | 'github.pull_request.auto_merge_enabled' | 'github.pull_request.closed' | 'github.pull_request.converted_to_draft' | 'github.pull_request.demilestoned' | 'github.pull_request.dequeued' | 'github.pull_request.edited' | 'github.pull_request.enqueued' | 'github.pull_request.labeled' | 'github.pull_request.locked' | 'github.pull_request.milestoned' | 'github.pull_request.opened' | 'github.pull_request.ready_for_review' | 'github.pull_request.reopened' | 'github.pull_request.resynced' | 'github.pull_request.review_request_removed' | 'github.pull_request.review_requested' | 'github.pull_request.synchronize' | 'github.pull_request.unassigned' | 'github.pull_request.unlabeled' | 'github.pull_request.unlocked'; entity: string; at: string; payload: GithubPullRequestPayload };
+  | { id: FactID; type: 'github.pull_request.assigned' | 'github.pull_request.auto_merge_disabled' | 'github.pull_request.auto_merge_enabled' | 'github.pull_request.closed' | 'github.pull_request.converted_to_draft' | 'github.pull_request.demilestoned' | 'github.pull_request.dequeued' | 'github.pull_request.edited' | 'github.pull_request.enqueued' | 'github.pull_request.labeled' | 'github.pull_request.locked' | 'github.pull_request.milestoned' | 'github.pull_request.opened' | 'github.pull_request.ready_for_review' | 'github.pull_request.reopened' | 'github.pull_request.resynced' | 'github.pull_request.review_request_removed' | 'github.pull_request.review_requested' | 'github.pull_request.synchronize' | 'github.pull_request.unassigned' | 'github.pull_request.unlabeled' | 'github.pull_request.unlocked'; entity: EntityID; at: string; payload: GithubPullRequestPayload };
 
 export function parseGithubPullRequestFact(factJSON: string): GithubPullRequestFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -79,6 +83,10 @@ function decodeGithubPullRequestFact(value: unknown): GithubPullRequestFact | un
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.pull_request.assigned' || type === 'github.pull_request.auto_merge_disabled' || type === 'github.pull_request.auto_merge_enabled' || type === 'github.pull_request.closed' || type === 'github.pull_request.converted_to_draft' || type === 'github.pull_request.demilestoned' || type === 'github.pull_request.dequeued' || type === 'github.pull_request.edited' || type === 'github.pull_request.enqueued' || type === 'github.pull_request.labeled' || type === 'github.pull_request.locked' || type === 'github.pull_request.milestoned' || type === 'github.pull_request.opened' || type === 'github.pull_request.ready_for_review' || type === 'github.pull_request.reopened' || type === 'github.pull_request.resynced' || type === 'github.pull_request.review_request_removed' || type === 'github.pull_request.review_requested' || type === 'github.pull_request.synchronize' || type === 'github.pull_request.unassigned' || type === 'github.pull_request.unlabeled' || type === 'github.pull_request.unlocked') {
     const decoded = decodeGithubPullRequestPayload(payload);
 
@@ -92,6 +100,14 @@ function decodeGithubPullRequestFact(value: unknown): GithubPullRequestFact | un
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubPullRequestPayload(value: unknown): GithubPullRequestPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-ref-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubRefModel(model: GithubRefModel, message: GithubRefMe
   return message.kind === 'reset' ? initGithubRefModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubRefPushedPayload {
   ref: string;
   repository: GithubRefPushedPayloadRepository;
@@ -55,7 +59,7 @@ export interface GithubRefPushedPayloadRepository {
 }
 
 export type GithubRefFact =
-  | { id: string; type: 'github.ref.pushed'; entity: string; at: string; payload: GithubRefPushedPayload };
+  | { id: FactID; type: 'github.ref.pushed'; entity: EntityID; at: string; payload: GithubRefPushedPayload };
 
 export function parseGithubRefFact(factJSON: string): GithubRefFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -78,6 +82,10 @@ function decodeGithubRefFact(value: unknown): GithubRefFact | undefined {
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.ref.pushed') {
     const decoded = decodeGithubRefPushedPayload(payload);
 
@@ -91,6 +99,14 @@ function decodeGithubRefFact(value: unknown): GithubRefFact | undefined {
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubRefPushedPayload(value: unknown): GithubRefPushedPayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-release-boundary.ts

@@ -45,6 +45,10 @@ export function updateGithubReleaseModel(model: GithubReleaseModel, message: Git
   return message.kind === 'reset' ? initGithubReleaseModel() : { ...model, input: message.input };
 }
 
+declare const factTag: unique symbol;
+
+export type FactID = string & { readonly [factTag]: 'FactID' };
+
 export interface GithubReleasePayload {
   action: string;
   release: GithubReleasePayloadRelease;
@@ -55,7 +59,7 @@ export interface GithubReleasePayloadRelease {
 }
 
 export type GithubReleaseFact =
-  | { id: string; type: 'github.release.created' | 'github.release.deleted' | 'github.release.edited' | 'github.release.prereleased' | 'github.release.published' | 'github.release.released' | 'github.release.resynced' | 'github.release.unpublished'; entity: string; at: string; payload: GithubReleasePayload };
+  | { id: FactID; type: 'github.release.created' | 'github.release.deleted' | 'github.release.edited' | 'github.release.prereleased' | 'github.release.published' | 'github.release.released' | 'github.release.resynced' | 'github.release.unpublished'; entity: EntityID; at: string; payload: GithubReleasePayload };
 
 export function parseGithubReleaseFact(factJSON: string): GithubReleaseFact | undefined {
   const parsed: unknown = JSON.parse(factJSON);
@@ -78,6 +82,10 @@ function decodeGithubReleaseFact(value: unknown): GithubReleaseFact | undefined
     return undefined;
   }
 
+  if (!isFactID(id) || !isFactEntityID(entity)) {
+    return undefined;
+  }
+
   if (type === 'github.release.created' || type === 'github.release.deleted' || type === 'github.release.edited' || type === 'github.release.prereleased' || type === 'github.release.published' || type === 'github.release.released' || type === 'github.release.resynced' || type === 'github.release.unpublished') {
     const decoded = decodeGithubReleasePayload(payload);
 
@@ -91,6 +99,14 @@ function decodeGithubReleaseFact(value: unknown): GithubReleaseFact | undefined
   return undefined;
 }
 
+function isFactID(text: string): text is FactID {
+  return text.length > 0;
+}
+
+function isFactEntityID(text: string): text is EntityID {
+  return text.length > 0;
+}
+
 function decodeGithubReleasePayload(value: unknown): GithubReleasePayload | undefined {
   if (typeof value !== 'object' || value === null || Array.isArray(value)) {
     return undefined;

package/src/generated/github-release.sql

@@ -29,4 +29,5 @@ SELECT
   "url" AS "url",
   NULL AS "actor",
   "updated_at" AS "updated_at"
-FROM "github_release";
+FROM "github_release"
+WHERE "deleted_at" IS NULL;

package/src/github-release-consumer.ts

@@ -1,7 +1,8 @@
 import { defineConsumer, defineTable } from '@pepys/kit';
 import { releaseFamily } from './families/release-family.ts';
 
-// One row per release, never deleted: a release GitHub deleted keeps its row with `deleted_at`.
+// One row per release, never deleted: a release GitHub deleted keeps its row with `deleted_at`,
+// which leaves it out of the `entity` view.
 export const githubReleaseConsumer = defineConsumer({
   name: 'github_release',
   entry: new URL('consumers/github-release.ts', import.meta.url),
@@ -36,6 +37,7 @@ export const githubReleaseConsumer = defineConsumer({
       url: 'url',
       actor: null,
       updatedAt: 'updated_at',
+      deletedAt: 'deleted_at',
     },
   ],
   reads: ['github_release'],

package/src/ingest/recovery/pull-failed-deliveries.ts

@@ -19,7 +19,7 @@ export async function pullFailedDeliveries(
   cursor: string | null,
   context: PullContext,
 ): Promise<Pulled> {
-  const appJWT = findAppJWT(context.env, Date.now());
+  const appJWT = findAppJWT(context.env, context.now());
 
   if (appJWT === undefined) {
     return { kind: 'rejected', reason: 'the GitHub App private key cannot sign a token' };

package/src/ingest/resync/collect-resync-targets.ts

@@ -1,10 +1,10 @@
-import type { ResyncMark } from '@pepys/kit';
+import type { EntityID, ResyncMark } from '@pepys/kit';
 
 // One marked object that the resync pull reads again: its repository, `owner/name`, its API path,
 // and the digest of the last body ingest stored for it.
 export interface ResyncTarget {
   kind: 'pull_request' | 'release';
-  entity: string;
+  entity: EntityID;
   repository: string;
   path: string;
   lastBodyDigest: string | undefined;

package/src/ingest/resync/pull-marked-objects.ts

@@ -23,7 +23,7 @@ export async function pullMarkedObjects(
     return { kind: 'batch', batch: { facts: [] }, cursor: 'resynced', isDone: true };
   }
 
-  const appJWT = findAppJWT(context.env, Date.now());
+  const appJWT = findAppJWT(context.env, context.now());
 
   if (appJWT === undefined) {
     return { kind: 'rejected', reason: 'the GitHub App private key cannot sign a token' };

package/src/queries/pull-request-delivery-query.ts

@@ -1,4 +1,4 @@
-import { defineQuery } from '@pepys/kit';
+import { defineQuery, entityIDSchema, isEntityID } from '@pepys/kit';
 import { z } from 'zod';
 import { deploySignals } from '../utils/deploy-signals.ts';
 import { githubDeliveryConsumers } from './github-delivery-consumers.ts';
@@ -9,12 +9,12 @@ import {
 
 const pullRequestsSchema = z.array(z.string()).max(200);
 const nameSchema = z.string().min(1);
-const releaseSchema = z.object({ id: z.string(), tag: z.string(), at: z.string() });
+const releaseSchema = z.object({ id: entityIDSchema, tag: z.string(), at: z.string() });
 const signalSchema = z.enum(deploySignals);
-const deploySchema = z.object({ id: z.string(), at: z.string(), signal: signalSchema });
+const deploySchema = z.object({ id: entityIDSchema, at: z.string(), signal: signalSchema });
 
 const deliverySchema = z.object({
-  pullRequest: z.string(),
+  pullRequest: entityIDSchema,
   mergedAt: z.string().nullable(),
   release: releaseSchema.nullable(),
   deploy: deploySchema.nullable(),
@@ -32,7 +32,8 @@ export const pullRequestDeliveryQuery = defineQuery({
   output: z.array(deliverySchema),
   reads: githubDeliveryConsumers,
   handler: async (call) => {
-    const [first, ...rest] = call.input.pullRequests;
+    // text that is no entity ID names no stored pull request, so it has no row either way
+    const [first, ...rest] = call.input.pullRequests.filter((id) => isEntityID(id));
 
     if (first === undefined) {
       return [];

package/src/queries/select-pull-request-delivery.ts

@@ -1,3 +1,5 @@
+import { entityIDSchema } from '@pepys/kit';
+import type { EntityID } from '@pepys/kit';
 import { sql } from 'kysely';
 import type { RawBuilder } from 'kysely';
 import { z } from 'zod';
@@ -6,7 +8,7 @@ import type { DeploySignal } from '../utils/deploy-signals.ts';
 
 interface DeliveryOptions {
   // at least one
-  pullRequests: readonly [string, ...string[]];
+  pullRequests: readonly [EntityID, ...EntityID[]];
   environment: string;
 
   // Absent: a deploy of any target, and of none, counts. Given: only a deploy of that target.
@@ -14,8 +16,8 @@ interface DeliveryOptions {
 }
 
 // The statement that ties pull requests to releases and deploys. The rules it holds are in the
-// "Delivery query" section of the plug-ins design doc. Run it with `.execute(db)`, and turn its rows
-// into deliveries with the parse function below.
+// "The delivery query" section of docs/architecture/plug-ins/github.md. Run it with `.execute(db)`,
+// and turn its rows into deliveries with the parse function below.
 export function selectPullRequestDelivery(options: DeliveryOptions): RawBuilder<unknown> {
   return sql`select
     pull_request.id as "pullRequest",
@@ -115,22 +117,22 @@ function selectFirstDeployID(options: DeliveryOptions): RawBuilder<unknown> {
 }
 
 export interface PullRequestDelivery {
-  pullRequest: string;
+  pullRequest: EntityID;
   mergedAt: string | null;
-  release: { id: string; tag: string; at: string } | null;
-  deploy: { id: string; at: string; signal: DeploySignal } | null;
+  release: { id: EntityID; tag: string; at: string } | null;
+  deploy: { id: EntityID; at: string; signal: DeploySignal } | null;
 }
 
 const textSchema = z.string().nullable();
 
 // One row per pull request, as the statement selects it.
 const deliveryRowSchema = z.object({
-  pullRequest: z.string(),
+  pullRequest: entityIDSchema,
   mergedAt: textSchema,
-  releaseID: textSchema,
+  releaseID: entityIDSchema.nullable(),
   releaseTag: textSchema,
   releaseAt: textSchema,
-  deployID: textSchema,
+  deployID: entityIDSchema.nullable(),
   deployAt: textSchema,
   deploySignal: z.enum(deploySignals).nullable(),
 });