Merge pull request #4 from hashgraph-online/feat/safe-skill-package-discovery

kantorcodes · web-flow · commit 6b370483d5cc · 2026-03-09T13:39:08.000-04:00
feat: guard production skill version publishes
diff --git a/README.md b/README.md
@@ -311,7 +311,8 @@ This action exists to make that publish step deterministic and automated in CI.
 | `api-base-url` | No | `https://hol.org/registry/api/v1` | Broker base URL (`.../registry` or `.../registry/api/v1`). |
 | `account-id` | No | - | Optional Hedera account ID for publish authorization edge cases. |
 | `name` | No | - | Optional skill name override for `skill.json`. |
-| `version` | No | - | Optional version override for `skill.json`. |
+| `version` | No | - | Optional version override for `skill.json`. Non-stable overrides are blocked on production by default. |
+| `allow-nonstable-production-version` | No | `false` | Explicitly permits publishing a non-stable custom version to the production registry. |
 | `stamp-repo-commit` | No | `true` | Stamp `repo` and `commit` metadata into payload. |
 | `poll-timeout-ms` | No | `720000` | Max time to wait for publish job completion. |
 | `poll-interval-ms` | No | `4000` | Interval between publish job status polls. |
diff --git a/action.yml b/action.yml
@@ -24,6 +24,10 @@ inputs:
   version:
     description: "Optional version override for skill.json"
     required: false
+  allow-nonstable-production-version:
+    description: "When true, permits publishing a non-stable custom version to the production registry"
+    required: false
+    default: "false"
   stamp-repo-commit:
     description: "When true, writes repo and commit fields into the publish payload"
     required: false
@@ -173,6 +177,7 @@ runs:
         INPUT_SKILL_DIR: ${{ inputs.skill-dir }}
         INPUT_NAME: ${{ inputs.name }}
         INPUT_VERSION: ${{ inputs.version }}
+        INPUT_ALLOW_NONSTABLE_PRODUCTION_VERSION: ${{ inputs.allow-nonstable-production-version }}
         INPUT_STAMP_REPO_COMMIT: ${{ inputs.stamp-repo-commit }}
         INPUT_POLL_TIMEOUT_MS: ${{ inputs.poll-timeout-ms }}
         INPUT_POLL_INTERVAL_MS: ${{ inputs.poll-interval-ms }}
diff --git a/bin/lib/repo-commands.mjs b/bin/lib/repo-commands.mjs
@@ -140,6 +140,13 @@ function buildManualWorkflow(skillDir, annotate) {
 on:
   workflow_dispatch:
     inputs:
+      publish_target:
+        type: choice
+        required: true
+        default: staging
+        options:
+          - staging
+          - production
       version:
         type: string
         required: false
@@ -153,9 +160,19 @@ jobs:
       issues: write
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve broker API URL
+        id: target
+        shell: bash
+        run: |
+          if [[ "\${{ inputs.publish_target }}" == "staging" ]]; then
+            echo "api_base_url=https://registry-staging.hol.org/registry/api/v1" >> "$GITHUB_OUTPUT"
+          else
+            echo "api_base_url=https://hol.org/registry/api/v1" >> "$GITHUB_OUTPUT"
+          fi
       - name: Publish skill package
         uses: hashgraph-online/skill-publish@v1
         with:
+          api-base-url: \${{ steps.target.outputs.api_base_url }}
           api-key: \${{ secrets.RB_API_KEY }}
           skill-dir: ${skillDir}
           version: \${{ inputs.version }}
diff --git a/entrypoint.mjs b/entrypoint.mjs
@@ -9,12 +9,49 @@ const stderr = (message) => process.stderr.write(`${message}\n`);
 const printJson = (value) => process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 
 class ActionError extends Error {
-  constructor(message) {
+  constructor(message, options = {}) {
     super(message);
     this.name = 'ActionError';
+    this.statusCode =
+      typeof options.statusCode === 'number' && Number.isFinite(options.statusCode)
+        ? options.statusCode
+        : undefined;
+    this.code =
+      typeof options.code === 'string' && options.code.trim().length > 0
+        ? options.code.trim().toUpperCase()
+        : undefined;
   }
 }
 
+const RETRYABLE_STATUS_CODES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const RETRYABLE_ERROR_CODES = new Set([
+  'ECONNABORTED',
+  'ECONNRESET',
+  'ECONNREFUSED',
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ETIMEDOUT',
+  'ERR_NETWORK',
+  'UND_ERR_CONNECT_TIMEOUT',
+  'UND_ERR_CONNECT_ERROR',
+]);
+const RETRYABLE_ERROR_MARKERS = [
+  'gateway time-out',
+  'gateway timeout',
+  'timed out',
+  'timeout',
+  'service unavailable',
+  'temporarily unavailable',
+  'too many requests',
+  'rate limit',
+  'network error',
+  'fetch failed',
+  'connection reset',
+];
+const INTEGER_VERSION_PATTERN = /^\d+$/;
+const SEMVER_VERSION_PATTERN = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?$/;
+const SEMVER_PRERELEASE_PATTERN = /^\d+\.\d+\.\d+-[0-9A-Za-z.-]+(?:\+[0-9A-Za-z.-]+)?$/;
+
 const getEnv = (name, fallback = '') => {
   const value = process.env[name];
   return typeof value === 'string' ? value : fallback;
@@ -33,6 +70,30 @@ const parseNumber = (value, fallback) => {
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 };
 
+const isStableRegistryVersion = (value) => {
+  const normalized = String(value ?? '').trim();
+  if (!normalized) {
+    return false;
+  }
+  if (INTEGER_VERSION_PATTERN.test(normalized)) {
+    return true;
+  }
+  if (SEMVER_PRERELEASE_PATTERN.test(normalized)) {
+    return false;
+  }
+  return SEMVER_VERSION_PATTERN.test(normalized);
+};
+
+const isProductionRegistryBase = (value) => {
+  try {
+    const url = new URL(String(value ?? '').trim());
+    const hostname = url.hostname.toLowerCase();
+    return hostname === 'hol.org' || hostname === 'registry.hashgraphonline.com';
+  } catch {
+    return false;
+  }
+};
+
 const guessMimeType = (filePath) => {
   const lower = filePath.toLowerCase();
   if (lower.endsWith('.md') || lower.endsWith('.markdown')) {
@@ -110,6 +171,44 @@ const summarizeErrorBody = async (response) => {
   }
 };
 
+const sleep = (delayMs) =>
+  new Promise((resolve) => {
+    setTimeout(resolve, delayMs);
+  });
+
+const extractErrorCode = (error) => {
+  if (!error || typeof error !== 'object') {
+    return '';
+  }
+  if (typeof error.code === 'string') {
+    return error.code.trim().toUpperCase();
+  }
+  if (error.cause && typeof error.cause === 'object' && typeof error.cause.code === 'string') {
+    return error.cause.code.trim().toUpperCase();
+  }
+  return '';
+};
+
+const isRetryableRequestError = (error) => {
+  if (error instanceof ActionError && typeof error.statusCode === 'number') {
+    if (RETRYABLE_STATUS_CODES.has(error.statusCode)) {
+      return true;
+    }
+    if (error.statusCode >= 400 && error.statusCode < 500) {
+      return false;
+    }
+  }
+
+  const code = extractErrorCode(error);
+  if (code && RETRYABLE_ERROR_CODES.has(code)) {
+    return true;
+  }
+
+  const message =
+    error instanceof Error ? error.message.toLowerCase() : String(error ?? '').toLowerCase();
+  return RETRYABLE_ERROR_MARKERS.some((marker) => message.includes(marker));
+};
+
 const requestJson = async (params) => {
   const {
     method,
@@ -118,34 +217,69 @@ const requestJson = async (params) => {
     body,
     signal,
   } = params;
-  const response = await fetch(url, {
-    method,
-    headers: {
-      'content-type': 'application/json',
-      'x-api-key': apiKey,
-    },
-    ...(body ? { body: JSON.stringify(body) } : {}),
-    signal,
-  });
+  let response;
+  try {
+    response = await fetch(url, {
+      method,
+      headers: {
+        'content-type': 'application/json',
+        'x-api-key': apiKey,
+      },
+      ...(body ? { body: JSON.stringify(body) } : {}),
+      signal,
+    });
+  } catch (error) {
+    throw new ActionError(
+      `${method} ${url} failed: ${error instanceof Error ? error.message : String(error)}`,
+      {
+        code: extractErrorCode(error),
+      },
+    );
+  }
   if (!response.ok) {
     const bodySummary = await summarizeErrorBody(response);
     throw new ActionError(
       `${method} ${url} failed with ${response.status}${bodySummary ? `: ${bodySummary}` : ''}`,
+      {
+        statusCode: response.status,
+      },
     );
   }
   return response.json();
 };
 
+const requestJsonWithRetry = async (params) => {
+  const attempts = Number.isFinite(params.attempts) && params.attempts > 0 ? Math.floor(params.attempts) : 1;
+  let lastError = null;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    try {
+      return await requestJson(params);
+    } catch (error) {
+      lastError = error;
+      if (attempt >= attempts || !isRetryableRequestError(error)) {
+        throw error;
+      }
+      const delayMs = Math.min(10_000, 1_000 * attempt);
+      stderr(
+        `Transient request failure on ${params.method} ${params.url}; retrying in ${delayMs}ms (retry ${attempt}/${attempts - 1}).`,
+      );
+      await sleep(delayMs);
+    }
+  }
+  throw lastError instanceof Error ? lastError : new ActionError('Request failed');
+};
+
 const findExistingSkillVersion = async (params) => {
   const { apiBaseUrl, apiKey, name, version } = params;
-  const response = await requestJson({
+  const response = await requestJsonWithRetry({
     method: 'GET',
     url: buildApiUrl(apiBaseUrl, '/skills', {
       name,
       version,
       limit: 20,
     }),
     apiKey,
+    attempts: 3,
   });
 
   const items = Array.isArray(response?.items) ? response.items : [];
@@ -396,6 +530,10 @@ const run = async () => {
   const skillDirInput = getEnv('INPUT_SKILL_DIR');
   const overrideName = getEnv('INPUT_NAME');
   const overrideVersion = getEnv('INPUT_VERSION');
+  const allowNonstableProductionVersion = toBoolean(
+    getEnv('INPUT_ALLOW_NONSTABLE_PRODUCTION_VERSION'),
+    false,
+  );
   const stampRepoCommit = toBoolean(getEnv('INPUT_STAMP_REPO_COMMIT'), true);
   const pollTimeoutMs = parseNumber(getEnv('INPUT_POLL_TIMEOUT_MS'), 720000);
   const pollIntervalMs = parseNumber(getEnv('INPUT_POLL_INTERVAL_MS'), 4000);
@@ -494,6 +632,21 @@ const run = async () => {
   if (!skillDescription) {
     throw new ActionError('skill.json must include description.');
   }
+  const nonstableVersion = !isStableRegistryVersion(skillVersion);
+  if (
+    nonstableVersion &&
+    isProductionRegistryBase(apiBaseUrl) &&
+    !allowNonstableProductionVersion
+  ) {
+    throw new ActionError(
+      `Refusing to publish ${skillName}@${skillVersion} to the production registry because it is not a stable release version. Use staging instead, or set allow-nonstable-production-version=true if this is intentional.`,
+    );
+  }
+  if (nonstableVersion) {
+    stderr(
+      `Publishing ${skillName}@${skillVersion} as a custom prerelease version. The registry will not use this release as the public stable default unless it is explicitly recommended.`,
+    );
+  }
 
   if (mode === 'publish') {
     const existingVersion = await findExistingSkillVersion({
@@ -576,10 +729,11 @@ const run = async () => {
   let maxTotalSizeBytes = 0;
   let allowedMimeTypes = null;
   if (mode === 'publish' || mode === 'quote') {
-    const config = await requestJson({
+    const config = await requestJsonWithRetry({
       method: 'GET',
       url: buildApiUrl(apiBaseUrl, '/skills/config'),
       apiKey,
+      attempts: 3,
     });
     maxFiles = Number(config?.maxFiles ?? 0);
     maxTotalSizeBytes = Number(config?.maxTotalSizeBytes ?? 0);
@@ -662,14 +816,15 @@ const run = async () => {
     return;
   }
 
-  const quote = await requestJson({
+  const quote = await requestJsonWithRetry({
     method: 'POST',
     url: buildApiUrl(apiBaseUrl, '/skills/quote'),
     apiKey,
     body: {
       files,
       ...(accountId ? { accountId } : {}),
     },
+    attempts: 3,
   });
 
   const quoteId = String(quote?.quoteId ?? '').trim();
@@ -741,10 +896,11 @@ const run = async () => {
   let lastStatus = '';
   let completedJob = null;
   while (Date.now() - startedAt < pollTimeoutMs) {
-    const job = await requestJson({
+    const job = await requestJsonWithRetry({
       method: 'GET',
       url: buildApiUrl(apiBaseUrl, `/skills/jobs/${encodeURIComponent(jobId)}`, accountId ? { accountId } : null),
       apiKey,
+      attempts: 3,
     });
     const status = String(job?.status ?? '').trim();
     if (status && status !== lastStatus) {
diff --git a/examples/workflows/publish-manual.yml b/examples/workflows/publish-manual.yml
@@ -7,6 +7,13 @@ on:
         type: string
         required: true
         default: skills/my-skill
+      publish_target:
+        type: choice
+        required: true
+        default: staging
+        options:
+          - staging
+          - production
       version:
         type: string
         required: false
@@ -25,9 +32,19 @@ jobs:
       contents: read
     steps:
       - uses: actions/checkout@v4
+      - name: Resolve broker API URL
+        id: target
+        shell: bash
+        run: |
+          if [[ "${{ inputs.publish_target }}" == "staging" ]]; then
+            echo "api_base_url=https://registry-staging.hol.org/registry/api/v1" >> "$GITHUB_OUTPUT"
+          else
+            echo "api_base_url=https://hol.org/registry/api/v1" >> "$GITHUB_OUTPUT"
+          fi
       - name: Publish skill package
         uses: hashgraph-online/skill-publish@v1
         with:
+          api-base-url: ${{ steps.target.outputs.api_base_url }}
           api-key: ${{ secrets.RB_API_KEY }}
           skill-dir: ${{ inputs.skill_dir }}
           version: ${{ inputs.version }}
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "skill-publish",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Publish trustless, immutable, on-chain skill releases via the HOL Registry Broker.",
   "type": "module",
   "homepage": "https://hol.org/registry/skills/publish",

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "skill-publish",`
`3`		`- "version": "1.0.3",`
	`3`	`+ "version": "1.0.4",`
`4`	`4`	`"description": "Publish trustless, immutable, on-chain skill releases via the HOL Registry Broker.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"homepage": "https://hol.org/registry/skills/publish",`