ras-stack 0.28.0 → 0.29.0

package/README.md

@@ -438,6 +438,29 @@ await reportPreviewStatus(
 
 The reporter keeps one marked comment and one named check run, preserves the last ready commit while a replacement builds, bounds comment pagination, and validates repository, pull request, commit, marker, and URL inputs. Applications retain their preview hostname, access note, seed credentials, and product cleanup hooks.
 
+Trusted preview wrappers can delegate each status transition to the reusable workflow instead of checking out and running a repository-owned comment script:
+
+```yaml
+mark-preview-ready:
+  permissions:
+    contents: read
+    checks: write
+    issues: write
+  uses: richardsolomou/ras-stack/.github/workflows/report-preview-status.yml@v0.29.0
+  with:
+    state: ready
+    pr-number: ${{ github.event.workflow_run.pull_requests[0].number }}
+    sha: ${{ github.event.workflow_run.head_sha }}
+    preview-url: https://pr-${{ github.event.workflow_run.pull_requests[0].number }}.example.com
+    run-url: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+    marker: <!-- app-preview -->
+    note: Preview data is disposable.
+  secrets:
+    token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+The workflow uses the `ras-stack-preview` CLI from the consuming repository's pinned package. It owns only GitHub check/comment reporting; the caller retains the trusted event conditions, permissions, deployment, deletion, secret mapping, and product verification.
+
 The reusable `build-preview-image.yml` workflow publishes same-repository pull requests directly but turns fork builds into one-day artifacts without exposing a token or secret. A trusted `workflow_run` job can publish that artifact with `actions/publish-preview-image` before running its repository-owned deployment command. The event wrapper and secret-to-environment mapping remain in each application so the trust boundary is visible locally.
 
 Self-hosted images that run the app, Centrifugo, and Caddy together can share the lifecycle without sharing a Dockerfile:

package/dist/preview/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/preview/cli.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { previewStatusFromEnvironment } from './environment.js';
+import { reportPreviewStatus } from './github.js';
+const { options, status } = previewStatusFromEnvironment(process.argv[2]);
+await reportPreviewStatus(options, status);
+console.log(`Preview status set to ${status.state}`);
+//# sourceMappingURL=cli.js.map

package/dist/preview/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/preview/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAEjD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,4BAA4B,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;AACzE,MAAM,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AAC1C,OAAO,CAAC,GAAG,CAAC,yBAAyB,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA","sourcesContent":["#!/usr/bin/env node\nimport { previewStatusFromEnvironment } from './environment.js'\nimport { reportPreviewStatus } from './github.js'\n\nconst { options, status } = previewStatusFromEnvironment(process.argv[2])\nawait reportPreviewStatus(options, status)\nconsole.log(`Preview status set to ${status.state}`)\n"]}

package/dist/preview/environment.d.ts

@@ -0,0 +1,5 @@
+import type { GitHubPreviewOptions, PreviewStatus } from './github.js';
+export declare function previewStatusFromEnvironment(stateValue: string | undefined, environment?: NodeJS.ProcessEnv): {
+    options: GitHubPreviewOptions;
+    status: PreviewStatus;
+};

package/dist/preview/environment.js

@@ -0,0 +1,38 @@
+const states = new Set(['awaiting', 'building', 'ready', 'failed', 'deleted']);
+export function previewStatusFromEnvironment(stateValue, environment = process.env) {
+    if (!stateValue || !states.has(stateValue)) {
+        throw new Error('preview state must be awaiting, building, ready, failed, or deleted');
+    }
+    const state = stateValue;
+    const note = optionalEnvironment(environment, 'PREVIEW_NOTE');
+    const checkName = optionalEnvironment(environment, 'PREVIEW_CHECK_NAME');
+    const options = {
+        repository: requiredEnvironment(environment, 'GITHUB_REPOSITORY'),
+        token: requiredEnvironment(environment, 'GH_TOKEN'),
+        marker: requiredEnvironment(environment, 'PREVIEW_MARKER'),
+        ...(note ? { note } : {}),
+        ...(checkName ? { checkName } : {}),
+    };
+    const prNumber = requiredEnvironment(environment, 'PR_NUMBER');
+    const runUrl = optionalEnvironment(environment, 'RUN_URL');
+    const status = state === 'deleted'
+        ? { state, prNumber }
+        : {
+            state,
+            prNumber,
+            sha: requiredEnvironment(environment, 'COMMIT_SHA'),
+            previewUrl: requiredEnvironment(environment, 'PREVIEW_URL'),
+            ...(runUrl ? { runUrl } : {}),
+        };
+    return { options, status };
+}
+function requiredEnvironment(environment, name) {
+    const value = optionalEnvironment(environment, name);
+    if (!value)
+        throw new Error(`${name} is required`);
+    return value;
+}
+function optionalEnvironment(environment, name) {
+    return environment[name]?.trim() || undefined;
+}
+//# sourceMappingURL=environment.js.map

package/dist/preview/environment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environment.js","sourceRoot":"","sources":["../../src/preview/environment.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,GAAG,IAAI,GAAG,CAAqB,CAAC,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAA;AAElG,MAAM,UAAU,4BAA4B,CAAC,UAA8B,EAAE,WAAW,GAAsB,OAAO,CAAC,GAAG;IACvH,IAAI,CAAC,UAAU,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,UAAgC,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,KAAK,CAAC,qEAAqE,CAAC,CAAA;IACxF,CAAC;IACD,MAAM,KAAK,GAAG,UAAgC,CAAA;IAC9C,MAAM,IAAI,GAAG,mBAAmB,CAAC,WAAW,EAAE,cAAc,CAAC,CAAA;IAC7D,MAAM,SAAS,GAAG,mBAAmB,CAAC,WAAW,EAAE,oBAAoB,CAAC,CAAA;IACxE,MAAM,OAAO,GAAyB;QACpC,UAAU,EAAE,mBAAmB,CAAC,WAAW,EAAE,mBAAmB,CAAC;QACjE,KAAK,EAAE,mBAAmB,CAAC,WAAW,EAAE,UAAU,CAAC;QACnD,MAAM,EAAE,mBAAmB,CAAC,WAAW,EAAE,gBAAgB,CAAC;QAC1D,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzB,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpC,CAAA;IACD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,WAAW,EAAE,WAAW,CAAC,CAAA;IAC9D,MAAM,MAAM,GAAG,mBAAmB,CAAC,WAAW,EAAE,SAAS,CAAC,CAAA;IAC1D,MAAM,MAAM,GACV,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE;QACrB,CAAC,CAAC;YACE,KAAK;YACL,QAAQ;YACR,GAAG,EAAE,mBAAmB,CAAC,WAAW,EAAE,YAAY,CAAC;YACnD,UAAU,EAAE,mBAAmB,CAAC,WAAW,EAAE,aAAa,CAAC;YAC3D,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAA;IACP,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,CAAA;AAC5B,CAAC;AAED,SAAS,mBAAmB,CAAC,WAA8B,EAAE,IAAY;IACvE,MAAM,KAAK,GAAG,mBAAmB,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;IACpD,IAAI,CAAC,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,cAAc,CAAC,CAAA;IAClD,OAAO,KAAK,CAAA;AACd,CAAC;AAED,SAAS,mBAAmB,CAAC,WAA8B,EAAE,IAAY;IACvE,OAAO,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,SAAS,CAAA;AAC/C,CAAC","sourcesContent":["import type { GitHubPreviewOptions, PreviewStatus, PreviewStatusState } from './github.js'\n\nconst states = new Set<PreviewStatusState>(['awaiting', 'building', 'ready', 'failed', 'deleted'])\n\nexport function previewStatusFromEnvironment(stateValue: string | undefined, environment: NodeJS.ProcessEnv = process.env) {\n  if (!stateValue || !states.has(stateValue as PreviewStatusState)) {\n    throw new Error('preview state must be awaiting, building, ready, failed, or deleted')\n  }\n  const state = stateValue as PreviewStatusState\n  const note = optionalEnvironment(environment, 'PREVIEW_NOTE')\n  const checkName = optionalEnvironment(environment, 'PREVIEW_CHECK_NAME')\n  const options: GitHubPreviewOptions = {\n    repository: requiredEnvironment(environment, 'GITHUB_REPOSITORY'),\n    token: requiredEnvironment(environment, 'GH_TOKEN'),\n    marker: requiredEnvironment(environment, 'PREVIEW_MARKER'),\n    ...(note ? { note } : {}),\n    ...(checkName ? { checkName } : {}),\n  }\n  const prNumber = requiredEnvironment(environment, 'PR_NUMBER')\n  const runUrl = optionalEnvironment(environment, 'RUN_URL')\n  const status: PreviewStatus =\n    state === 'deleted'\n      ? { state, prNumber }\n      : {\n          state,\n          prNumber,\n          sha: requiredEnvironment(environment, 'COMMIT_SHA'),\n          previewUrl: requiredEnvironment(environment, 'PREVIEW_URL'),\n          ...(runUrl ? { runUrl } : {}),\n        }\n  return { options, status }\n}\n\nfunction requiredEnvironment(environment: NodeJS.ProcessEnv, name: string) {\n  const value = optionalEnvironment(environment, name)\n  if (!value) throw new Error(`${name} is required`)\n  return value\n}\n\nfunction optionalEnvironment(environment: NodeJS.ProcessEnv, name: string) {\n  return environment[name]?.trim() || undefined\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -18,7 +18,8 @@
   },
   "bin": {
     "ras-stack-assets": "./dist/build/cli.js",
-    "ras-stack-policy": "./dist/policy/cli.js"
+    "ras-stack-policy": "./dist/policy/cli.js",
+    "ras-stack-preview": "./dist/preview/cli.js"
   },
   "files": [
     "dist",