@steve31415/baselib 2.3.0 → 2.4.0

package/dist/deploy/types.d.ts

@@ -0,0 +1,119 @@
+export interface ServiceHealth {
+    /** How the shared smoke reaches /health:
+     *  - public-canonical: unauthenticated GET on the canonical URL
+     *  - oidc-run-url: OIDC identity token with the service's run.app URL audience
+     *  - oidc-audience: OIDC identity token with a fixed custom audience
+     *  - none: no shared health check (app hook covers it) */
+    kind: 'public-canonical' | 'oidc-run-url' | 'oidc-audience' | 'none';
+    audience?: string;
+    path?: string;
+}
+export interface ServiceConfig {
+    name: string;
+    /** Canonical public URL (used by public-canonical health and printed). */
+    canonicalUrl?: string;
+    health: ServiceHealth;
+}
+export interface DeployConfig {
+    /** Short app name; prefixes the lock/hold/release objects. */
+    app: string;
+    project: string;
+    region: string;
+    /** GCS bucket holding lock, hold, release records, and retained assets. */
+    bucket: string;
+    /** Expected gcloud account (defaults to the fleet coding agent). */
+    account?: string;
+    image: {
+        arRepo: string;
+        name: string;
+        buildServiceAccount: string;
+    };
+    build: {
+        /** Command producing the deployable outputs; run with BUILD_ID=<sha>. */
+        command: string;
+        /** Repo-relative files/dirs copied into the sealed build context
+         *  alongside Dockerfile, cloudbuild.yaml, package.json, package-lock.json. */
+        contextFiles: string[];
+    };
+    /** Gate commands run while the image builds; all must pass before traffic. */
+    gates: string[];
+    /** Default retained-asset publish (omit when a publishAssets hook or no
+     *  assets exist): dir is repo-relative, prefix is bucket-relative. */
+    assets?: {
+        dir: string;
+        prefix: string;
+    };
+    /** Bucket-relative prefix for shared release records, e.g. "todo/pw-releases/". */
+    releasePrefix: string;
+    /** Secrets re-pinned on every routine deploy (name -> secret:version). */
+    updateSecrets?: Record<string, string>;
+    /** Refuse to deploy across a migrations/ diff (notes2 semantics). */
+    refuseMigrationDiffOnDeploy?: boolean;
+    /** Repo-relative path of an optional ES module exporting hooks. */
+    hooks?: string;
+    services: ServiceConfig[];
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+}
+export interface ExecOptions {
+    timeoutMs?: number;
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    input?: string;
+}
+/** Injected process runner; never throws on nonzero exit (code reports it). */
+export type Runner = (file: string, args: string[], opts?: ExecOptions) => Promise<ExecResult>;
+export interface ReleaseRecord {
+    sha: string;
+    at: string;
+    app: string;
+    services: {
+        name: string;
+        revision: string;
+        imageDigest: string;
+    }[];
+    timingsMs?: Record<string, number>;
+}
+export interface HoldRecord {
+    /** SHAs that must not deploy without an explicit override. */
+    heldShas: string[];
+    reason: string;
+    at: string;
+}
+export interface ServingState {
+    service: string;
+    revision: string;
+    /** BUILD_ID env of the serving revision; null before unification. */
+    buildSha: string | null;
+    imageDigest: string | null;
+}
+export interface HookContext {
+    sha: string;
+    /** Consistent serving base SHA across services, when determinable. */
+    baseSha: string | null;
+    config: DeployConfig;
+    repoRoot: string;
+    contextDir: string;
+    evidenceDir: string;
+    /** Resolved image digest (release phase onward). */
+    imageDigest?: string;
+    serving: ServingState[];
+    exec: Runner;
+    log: (message: string) => void;
+}
+export interface DeployHooks {
+    /** Runs after the local build, before the context is sealed. Overrides the
+     *  default retained-asset publish when present. */
+    publishAssets?: (ctx: HookContext) => Promise<void>;
+    /** Runs after all gates pass, immediately before the first traffic switch. */
+    preRelease?: (ctx: HookContext) => Promise<void>;
+    /** Runs right after traffic moves (e.g. todo2's announce-build). */
+    postTraffic?: (ctx: HookContext) => Promise<void>;
+    /** Extra smoke checks after the shared health checks. */
+    smoke?: (ctx: HookContext) => Promise<void>;
+    /** Runs after everything else succeeded (e.g. notes2's release state). */
+    postSuccess?: (ctx: HookContext) => Promise<void>;
+}

package/dist/deploy/types.js

@@ -0,0 +1,3 @@
+// Shared deploy/rollback types for the fleet-wide `pw-deploy` / `pw-rollback`
+// bins (design: ~/migration/research/deploy-procedure-design.md, 2026-08-31).
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steve31415/baselib",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Plasticine new-world shared platform library: logging, auth, service-to-service auth, db, HTTP, sync, app updates",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,9 @@
     }
   },
   "bin": {
-    "check-test-owners": "./dist/bin/check-test-owners.js"
+    "check-test-owners": "./dist/bin/check-test-owners.js",
+    "pw-deploy": "./dist/bin/pw-deploy.js",
+    "pw-rollback": "./dist/bin/pw-rollback.js"
   },
   "engines": {
     "node": "22.x"