@opengsd/gsd-core 1.7.0 → 1.9.0

package/scripts/registry-schema.cjs

@@ -36,6 +36,11 @@
  *     (`{ namedDispatch, nested, maxDepth, background, subagentToolkit }`) —
  *     this registry accepts a free-form human summary string instead, so it
  *     carries the `AXES_FREE_STRING` sentinel rather than an enum array.
+ *     `OPTIONAL_AXES` adds one further, OPTIONAL key on top of those eight:
+ *     `effortSurface` (ADR-1239 amendment #2481). An entry may omit it
+ *     (every entry published before the amendment stays valid) or declare
+ *     it as `argv` | `none`, mirroring `HOST_INTEGRATION_AXES.effortSurface`
+ *     in `src/host-integration.cts`.
  *   - `CAPABILITY_REQUIRED` / `EOS_REQUIRED` mirror the required top-level
  *     fields for each entry type, including `enginesGsd` (ADR-1244 D1
  *     "Versioned capability manifest" — the `engines.gsd` semver-range gate,
@@ -90,6 +95,18 @@ const AXES = Object.freeze({
   runtime: Object.freeze(['node', 'bun', 'sandboxed-web', 'python', 'go', 'rust', 'electron', 'other']),
 });
 
+// ─── ADR-1239 amendment #2481 — one additional, OPTIONAL negotiated axis ─────
+// `effortSurface` was added to the runtime-descriptor vocabulary AFTER the
+// original eight (`HOST_INTEGRATION_AXES.effortSurface` in
+// `src/host-integration.cts`). It is kept OPTIONAL here — not folded into
+// `AXES` — because registry entries mirror their upstream
+// `registry/eos-entry.json` byte-for-byte, and requiring it would
+// retroactively invalidate every entry published before the amendment.
+// Values must match `HOST_INTEGRATION_AXES.effortSurface` exactly.
+const OPTIONAL_AXES = Object.freeze({
+  effortSurface: Object.freeze(['argv', 'none']),
+});
+
 // ─── Required top-level fields ───────────────────────────────────────────────
 const CAPABILITY_REQUIRED = Object.freeze([
   'id',
@@ -246,15 +263,39 @@ function validateEosInteractions(interactions, addError) {
     if (typeof axes !== 'object' || axes === null || Array.isArray(axes)) {
       addError('interactions.axes', 'axes must be an object');
     } else {
-      const expectedKeys = Object.keys(AXES);
+      const requiredKeys = Object.keys(AXES);
+      const optionalKeys = Object.keys(OPTIONAL_AXES);
       const actualKeys = Object.keys(axes);
       const actualKeySet = new Set(actualKeys);
-      const keysMatch = expectedKeys.length === actualKeys.length && expectedKeys.every((k) => actualKeySet.has(k));
-      if (!keysMatch) {
-        addError('interactions.axes', 'axes key set must exactly match the eight negotiated axes');
-      } else {
-        for (const key of expectedKeys) {
-          const allowedValues = AXES[key];
+
+      // Every AXES key is mandatory; an extra key is tolerated ONLY when it is
+      // a recognized OPTIONAL_AXES key (currently just `effortSurface`) — any
+      // other extra key is still rejected as unknown.
+      const missingRequiredKeys = requiredKeys.filter((k) => !actualKeySet.has(k));
+      const unknownKeys = actualKeys.filter((k) => !requiredKeys.includes(k) && !optionalKeys.includes(k));
+
+      if (missingRequiredKeys.length > 0) {
+        addError('interactions.axes', `axes is missing required key(s): ${missingRequiredKeys.join(', ')}`);
+      }
+      if (unknownKeys.length > 0) {
+        addError('interactions.axes', `axes has unknown key(s): ${unknownKeys.join(', ')}`);
+      }
+
+      // Only validate individual values once the key set itself is sound —
+      // mirrors the original gate (values were never checked against a
+      // malformed key set either).
+      if (missingRequiredKeys.length === 0 && unknownKeys.length === 0) {
+        for (const key of actualKeys) {
+          // Inline literal guards — CodeQL barrier pattern. Reaching here already
+          // implies `key` is one of the nine literal axis names (the unknown-key
+          // gate above rejected everything else), so this is unreachable in
+          // practice; it is written inline anyway because CodeQL cannot follow
+          // that gate across the `.includes()` filter and would otherwise flag
+          // the bracket reads below as prototype-pollution sinks.
+          if (key === '__proto__') continue;
+          if (key === 'constructor') continue;
+          if (key === 'prototype') continue;
+          const allowedValues = Object.hasOwn(AXES, key) ? AXES[key] : OPTIONAL_AXES[key];
           const v = axes[key];
           if (allowedValues === AXES_FREE_STRING) {
             if (typeof v !== 'string' || v.trim() === '') {
@@ -496,7 +537,14 @@ function renderMarkdown(entries, opts) {
     lines.push(`- **Author:** ${mdInline(entry.author)}`);
 
     if (isEos) {
-      const axesSummary = Object.keys(AXES)
+      // Required AXES keys always render, in their fixed order; an OPTIONAL_AXES
+      // key (e.g. `effortSurface`) renders ONLY when the entry actually carries
+      // it — an entry that omits it must render byte-identical to before
+      // OPTIONAL_AXES existed (no `effortSurface=undefined` noise).
+      const presentOptionalKeys = Object.keys(OPTIONAL_AXES).filter(
+        (key) => interactions.axes && Object.hasOwn(interactions.axes, key),
+      );
+      const axesSummary = [...Object.keys(AXES), ...presentOptionalKeys]
         .map((key) => `${key}=${interactions.axes ? interactions.axes[key] : undefined}`)
         .join(', ');
       const summary =
@@ -556,6 +604,7 @@ module.exports = {
   INTERFACE_POINTS,
   PROFILES,
   AXES,
+  OPTIONAL_AXES,
   AXES_FREE_STRING,
   CAPABILITY_REQUIRED,
   EOS_REQUIRED,

package/scripts/release-notes/conventional-title.cjs

@@ -30,18 +30,36 @@ const HEADER_RE = /^([a-z]+)(\([^)]*\))?(!)?:/i;
 // An issue reference inside a scope: `(#123)`, `(#123, core)`, etc.
 const ISSUE_REF_IN_SCOPE_RE = /#\d+/;
 
+// #2716: recognized non-user-facing conventional-commit types. A title whose
+// START-anchored type prefix is one of these is internal work (tests, chores,
+// CI, docs, refactors, perf, reverts) and must NOT render under the user-facing
+// "Enhancement" heading in release notes. Only a CLEAN prefix match qualifies —
+// untyped or anchor-defeated titles fall through to the visible Enhancement
+// fallback (a safety net so possibly-user-facing content is never hidden).
+const NON_USER_FACING_TYPES = new Set([
+  'docs', 'refactor', 'test', 'ci', 'chore', 'perf', 'revert',
+]);
+
 /**
  * Classify a clean conventional title into a changelog bucket.
  * Callers that hold a full changelog bullet line (with a `* ` marker and a
  * ` by @author` suffix) must strip those first; this operates on the title.
  *
  * @param {string} title
- * @returns {'Feature'|'Fix'|'Enhancement'}
+ * @returns {'Feature'|'Fix'|'Enhancement'|'Internal'}
  */
 function classifyBucket(title) {
   const t = String(title == null ? '' : title).trim();
   if (FEATURE_RE.test(t)) return 'Feature';
   if (FIX_RE.test(t)) return 'Fix';
+  // #2716: a clean non-user-facing type prefix → Internal (omitted from user-facing
+  // release-note sections). The HEADER_RE anchor ensures a leading tag/prefix
+  // (e.g. `[security] fix(...)`) does NOT match here — those keep falling through
+  // to the visible Enhancement fallback.
+  const headerMatch = HEADER_RE.exec(t);
+  if (headerMatch && NON_USER_FACING_TYPES.has(headerMatch[1].toLowerCase())) {
+    return 'Internal';
+  }
   return 'Enhancement';
 }
 

package/scripts/release-notes/format-github-release-notes.cjs

@@ -8,9 +8,9 @@ const { runMain, ExitError } = require('../lib/cli-exit.cjs');
 const { classifyBucket } = require('./conventional-title.cjs');
 
 /**
- * Classify a What's-Changed bullet line into 'Feature', 'Fix', or 'Enhancement'.
+ * Classify a What's-Changed bullet line into 'Feature', 'Fix', 'Enhancement', or 'Internal'.
  * @param {string} bulletLine - Full bullet line including the leading `* ` or `- ` marker.
- * @returns {'Feature'|'Fix'|'Enhancement'}
+ * @returns {'Feature'|'Fix'|'Enhancement'|'Internal'}
  */
 function classifyTitle(bulletLine) {
   // Strip leading `* ` or `- ` marker
@@ -83,7 +83,11 @@ function formatReleaseNotes({ generatedBody, version, prerelease, packageName })
       const category = classifyTitle(trimmed);
       if (category === 'Feature') featureBullets.push(trimmed);
       else if (category === 'Fix') fixBullets.push(trimmed);
-      else enhancementBullets.push(trimmed);
+      else if (category === 'Internal') {
+        // #2716: non-user-facing work (test/chore/ci/docs/refactor/perf/revert)
+        // is omitted from the user-facing "What's Changed" section entirely.
+        continue;
+      } else enhancementBullets.push(trimmed);
       continue;
     }
 

package/scripts/release-tarball-smoke.cjs

@@ -47,16 +47,23 @@ const os = require('os');
 const path = require('path');
 const { PACKAGE_NAME } = require('../gsd-core/bin/lib/package-identity.cjs');
 const { ExitError, runMain } = require('./lib/cli-exit.cjs');
-// 120 s proved too tight on Windows GitHub-hosted runners: cold-cache
-// `npm install -g` with a 1499-file tarball took ~120 s exactly, causing
-// spawnSync to fire SIGTERM and return { status: null, stdout: '', stderr: '' }
-// (Node docs: status is null when subprocess terminated due to a signal).
-// The INSTALL_FAILED branch checks `status !== 0`, which null satisfies, so the
-// test saw empty stdout/stderr and a spurious INSTALL_FAILED. Windows runners
-// are slower than Linux/macOS for filesystem-heavy operations (
-// https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories
-// ). Raise to 600 s (the same ceiling the before() helper uses for pack+install).
-const CHILD_TIMEOUT_MS = process.platform === 'win32' ? 600_000 : 120_000;
+// 120 s proved too tight for cold-cache `npm install -g` of a 1499-file tarball:
+// spawnSync fires SIGTERM at the deadline and returns { status: null, stdout: '',
+// stderr: '' } (Node docs: status is null when a subprocess is terminated by a
+// signal). The INSTALL_FAILED branch checks `status !== 0`, which null satisfies,
+// so the test sees empty stdout/stderr and a spurious INSTALL_FAILED (surfaced as
+// `installError: spawnSync npm ETIMEDOUT`).
+//
+// First observed on Windows GitHub-hosted runners, which are slower for
+// filesystem-heavy work
+// (https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners/about-github-hosted-runners#standard-github-hosted-runners-for-public-repositories),
+// then again on a slow Linux bench (cartographer: cold disk, constrained CPU) —
+// the same failure the before() helper's SLOW_HOST_TIMEOUT already guards for
+// pack+install. The slow-host reality is not platform-specific, so the ceiling is
+// now uniform 600 s across all platforms AND shared with before() via this
+// exported constant, so the two surfaces cannot diverge again. 600 s stays well
+// clear of a real cold install (3–6 min) without masking a genuine hang.
+const CHILD_TIMEOUT_MS = 600_000;
 const QUIET_NPM_ENV = Object.freeze({
   npm_config_loglevel: 'error',
   npm_config_update_notifier: 'false',
@@ -628,7 +635,7 @@ function cleanup(...dirs) {
 // Exports
 // ---------------------------------------------------------------------------
 
-module.exports = { SMOKE, runSmoke, binInvocation };
+module.exports = { SMOKE, runSmoke, binInvocation, CHILD_TIMEOUT_MS };
 
 if (require.main === module) {
   runMain(cliMain);