@gjsify/cli 0.59.1 → 0.60.0

package/lib/utils/publish-status.js

@@ -0,0 +1,193 @@
+// What happened to a version npm ACCEPTED and the packument does not serve?
+//
+// THE INCIDENT (v0.59.0 / v0.59.1). A handful of packages — `@gjsify/adwaita-fonts`
+// and five `@gjsify/example-*` — got HTTP 202 on the PUT and never appeared in the
+// public packument; a re-PUT is answered 409. The npm website shows them as
+// "Validating" ("Automated review hasn't finished. The version will remain
+// unavailable until review completes."). Both read-back verdicts that existed
+// for them — `not-published` and `recorded-not-served` — were wrong in spirit: the
+// first told the operator to re-publish (answered 409), the second to wait (it
+// would not come). The packument has no field that says which.
+//
+// The registry does: `GET /-/package/{name}/version/{version}/status` answers
+// `published | validating | staged | blocked | deleted`. It accepts an npm access
+// token or a granular access token with publish access to the package — NOT the
+// short-lived OIDC exchange token the release sweep publishes with, and not
+// anonymous requests (401). So in CI the answer is only available when a
+// read-only token is provided as `NPM_STATUS_TOKEN`; without one this module says
+// so (`no-credential`) instead of guessing, and the callers keep the old behaviour
+// plus a hold, which needs no status to be safe.
+import { escapePackageName } from './publish-headers.js';
+const KNOWN_STATUSES = ['published', 'validating', 'staged', 'blocked', 'deleted'];
+/**
+ * The token to ask the status endpoint with: the dedicated `NPM_STATUS_TOKEN`
+ * first, then a `NODE_AUTH_TOKEN` that is a real token and not the
+ * `XXXXX-XXXXX-XXXXX-XXXXX` literal `actions/setup-node` injects when given a
+ * `registry-url`. Empty string and the placeholder both mean "none".
+ */
+export function statusTokenFromEnv(env) {
+    for (const candidate of [env['NPM_STATUS_TOKEN'], env['NODE_AUTH_TOKEN']]) {
+        const token = candidate?.trim();
+        if (token && !/^X+(-X+)+$/.test(token))
+            return token;
+    }
+    return undefined;
+}
+/** `GET {registry}/-/package/{name}/version/{version}/status`, classified. Never throws. */
+export async function fetchVersionStatus(input) {
+    if (!input.token) {
+        return {
+            state: 'unavailable',
+            reason: 'no-credential',
+            detail: 'the status endpoint needs an npm access token (set NPM_STATUS_TOKEN); OIDC publish tokens are not accepted',
+        };
+    }
+    const doFetch = input.fetchImpl ?? ((...args) => globalThis.fetch(...args));
+    const registryClean = input.registry.endsWith('/') ? input.registry.slice(0, -1) : input.registry;
+    const url = `${registryClean}/-/package/${escapePackageName(input.name)}/version/${encodeURIComponent(input.version)}/status`;
+    let res;
+    try {
+        res = await doFetch(url, {
+            headers: {
+                accept: 'application/json',
+                authorization: `Bearer ${input.token}`,
+            },
+            signal: AbortSignal.timeout(input.probeTimeoutMs ?? 30_000),
+        });
+    }
+    catch (err) {
+        return {
+            state: 'unavailable',
+            reason: 'error',
+            detail: err instanceof Error ? err.message : String(err),
+        };
+    }
+    if (res.status === 401) {
+        return {
+            state: 'unavailable',
+            reason: 'rejected',
+            detail: '401 — the token is missing, invalid or expired',
+        };
+    }
+    if (res.status === 403) {
+        return {
+            state: 'unavailable',
+            reason: 'not-enabled',
+            detail: '403 — package version status is not enabled for this package',
+        };
+    }
+    if (res.status === 404) {
+        return {
+            state: 'unavailable',
+            reason: 'not-found',
+            detail: '404 — no such version, or the token cannot see this package',
+        };
+    }
+    if (!res.ok) {
+        return {
+            state: 'unavailable',
+            reason: 'error',
+            detail: `${res.status} ${res.statusText}`,
+        };
+    }
+    let body;
+    try {
+        body = await res.json();
+    }
+    catch (err) {
+        return {
+            state: 'unavailable',
+            reason: 'error',
+            detail: `status body is not JSON (${err instanceof Error ? err.message : String(err)})`,
+        };
+    }
+    const status = body?.status;
+    if (typeof status !== 'string' || !KNOWN_STATUSES.includes(status)) {
+        return {
+            state: 'unavailable',
+            reason: 'error',
+            detail: `unrecognised status ${JSON.stringify(status)}`,
+        };
+    }
+    return { state: 'known', status: status };
+}
+/** `classifyUnserved(...).terminal` for a class read back from the ledger. */
+export function isTerminalClass(cls) {
+    return cls !== 'validating' && cls !== 'published-lagging' && cls !== 'unchecked';
+}
+/** Why the status could not be asked, in the words the `unchecked` line uses. */
+function whyUnchecked(probe) {
+    return probe.reason === 'no-credential' ? 'status endpoint not asked: no NPM_STATUS_TOKEN' : probe.detail;
+}
+/**
+ * Fold the registry's lifecycle status and the read-back verdict into ONE class.
+ *
+ * The status wins when it answered. When it did not, the read-back verdict is
+ * kept in the detail but never promoted to `missing`: `not-published` from the
+ * packument alone is exactly the observation a `validating` version produces, so
+ * "missing — re-publish" would send the operator into a 409. Only a status 404
+ * (the registry itself has no such version) earns `missing`.
+ */
+export function classifyUnserved(verdict, probe) {
+    if (probe.state === 'known') {
+        switch (probe.status) {
+            case 'validating':
+                return {
+                    cls: 'validating',
+                    detail: 'npm accepted the upload and its automated review has not finished',
+                    terminal: false,
+                };
+            case 'staged':
+                return {
+                    cls: 'staged',
+                    detail: 'awaiting maintainer approval on npm',
+                    terminal: true,
+                };
+            case 'blocked':
+                return {
+                    cls: 'blocked',
+                    detail: 'failed npm automated validation',
+                    terminal: true,
+                };
+            case 'deleted':
+                return { cls: 'deleted', detail: 'deleted on npm', terminal: true };
+            case 'published':
+                return {
+                    cls: 'published-lagging',
+                    detail: 'npm reports it published; the install document does not serve it yet',
+                    terminal: false,
+                };
+        }
+    }
+    if (probe.reason === 'not-found') {
+        return {
+            cls: 'missing',
+            detail: `the registry has no such version (${probe.detail}); the PUT did not land`,
+            terminal: true,
+        };
+    }
+    return {
+        cls: 'unchecked',
+        detail: `not served (read-back: ${verdict}); ${whyUnchecked(probe)}`,
+        terminal: false,
+    };
+}
+/** The class as a human label for tables. */
+export function describeClass(cls) {
+    switch (cls) {
+        case 'validating':
+            return 'validating (npm automated review pending)';
+        case 'staged':
+            return 'staged (needs maintainer approval)';
+        case 'blocked':
+            return 'blocked (failed automated validation)';
+        case 'deleted':
+            return 'deleted';
+        case 'published-lagging':
+            return 'published, not yet served';
+        case 'missing':
+            return 'missing (never recorded)';
+        case 'unchecked':
+            return 'not served (status not checked)';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.59.1",
+    "version": "0.60.0",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "^0.59.1",
-        "@gjsify/buffer": "^0.59.1",
-        "@gjsify/create-app": "^0.59.1",
-        "@gjsify/node-globals": "^0.59.1",
-        "@gjsify/node-polyfills": "^0.59.1",
-        "@gjsify/npm-registry": "^0.59.1",
-        "@gjsify/resolve-npm": "^0.59.1",
-        "@gjsify/rolldown-plugin-gjsify": "^0.59.1",
-        "@gjsify/vite-plugin-blueprint": "^0.59.1",
-        "@gjsify/rolldown-plugin-pnp": "^0.59.1",
-        "@gjsify/semver": "^0.59.1",
-        "@gjsify/tar": "^0.59.1",
-        "@gjsify/tsc": "^0.59.1",
-        "@gjsify/utils": "^0.59.1",
-        "@gjsify/web-polyfills": "^0.59.1",
-        "@gjsify/workspace": "^0.59.1",
+        "@gjsify/blueprint": "^0.60.0",
+        "@gjsify/buffer": "^0.60.0",
+        "@gjsify/create-app": "^0.60.0",
+        "@gjsify/node-globals": "^0.60.0",
+        "@gjsify/node-polyfills": "^0.60.0",
+        "@gjsify/npm-registry": "^0.60.0",
+        "@gjsify/resolve-npm": "^0.60.0",
+        "@gjsify/rolldown-plugin-gjsify": "^0.60.0",
+        "@gjsify/vite-plugin-blueprint": "^0.60.0",
+        "@gjsify/rolldown-plugin-pnp": "^0.60.0",
+        "@gjsify/semver": "^0.60.0",
+        "@gjsify/tar": "^0.60.0",
+        "@gjsify/tsc": "^0.60.0",
+        "@gjsify/utils": "^0.60.0",
+        "@gjsify/web-polyfills": "^0.60.0",
+        "@gjsify/workspace": "^0.60.0",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.59.1",
+        "@gjsify/unit": "^0.60.0",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.59.1",
-        "@gjsify/rolldown-native": "^0.59.1"
+        "@gjsify/oxfmt-native": "^0.60.0",
+        "@gjsify/rolldown-native": "^0.60.0"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {

package/showcases.json

@@ -1,48 +1,6 @@
 {
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "showcases": [
-        {
-            "name": "canvas2d-fireworks",
-            "category": "dom",
-            "package": "@gjsify/example-dom-canvas2d-fireworks",
-            "description": "Colorful fireworks Canvas 2D example with Adwaita controls"
-        },
-        {
-            "name": "excalibur-jelly-jumper",
-            "category": "dom",
-            "package": "@gjsify/example-dom-excalibur-jelly-jumper",
-            "description": "Excalibur.js jelly-jumper game"
-        },
-        {
-            "name": "three-geometry-teapot",
-            "category": "dom",
-            "package": "@gjsify/example-dom-three-geometry-teapot",
-            "description": "Three.js Utah teapot"
-        },
-        {
-            "name": "three-loader-ldraw",
-            "category": "dom",
-            "package": "@gjsify/example-dom-three-loader-ldraw",
-            "description": "Three.js LDraw viewer — loads packed .mpd models over fetch and steps through their building instructions"
-        },
-        {
-            "name": "three-postprocessing-pixel",
-            "category": "dom",
-            "package": "@gjsify/example-dom-three-postprocessing-pixel",
-            "description": "Three.js postprocessing pixel demo"
-        },
-        {
-            "name": "webrtc-loopback",
-            "category": "dom",
-            "package": "@gjsify/example-dom-webrtc-loopback",
-            "description": "WebRTC data-channel loopback: two local peers exchange offer/answer + ICE, then echo messages over an RTCDataChannel"
-        },
-        {
-            "name": "minimalist-browser",
-            "category": "dom",
-            "package": "@gjsify/example-dom-minimalist-browser",
-            "description": "Minimalist browser with URL bar + back/forward + iframe content area; same code runs in browser (real iframe) and GJS (IFrameBridge over WebKit.WebView)"
-        },
         {
             "name": "express-webserver",
             "category": "node",