Align with API and update documentation (#261)

Bumps [typescript](https://github.com/Microsoft/TypeScript) from 5.1.6 to 5.2.2.
- [Release notes](https://github.com/Microsoft/TypeScript/releases)
- [Commits](https://github.com/Microsoft/TypeScript/compare/v5.1.6...v5.2.2)

---
updated-dependencies:
- dependency-name: typescript
  dependency-type: direct:development
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.github/workflows/main.yml

@@ -10,7 +10,7 @@ jobs:
   pre-commit-and-test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Get yarn cache directory path
         id: yarn-cache-dir-path
         run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
@@ -19,7 +19,7 @@ jobs:
         with:
           path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
           key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
-      - uses: actions/setup-node@v3
+      - uses: actions/setup-node@v4
         with:
           node-version: '18.17.1'
           cache: 'yarn'

README.md

@@ -13,7 +13,6 @@ It is a GitHub Action that publishes a Speckle Automate Function definition to S
 > This is a low level building block action.
 > As a Speckle Automate Function developer you probably want to use our [composite action](https://github.com/specklesystems/speckle-automate-github-composite-action)
 
-
 ### Inputs
 
 #### `speckle_automate_url`
@@ -32,19 +31,21 @@ If you believe your token has been compromised, please revoke it immediately on
 
 Please note that this is not a Speckle Account token, but a **Speckle Automate API** token. You can create one by logging into the [Speckle Automate Server](https://automate.speckle.dev) and going to the [API Tokens](https://automate.speckle.dev/tokens) page.
 
-#### `speckle_function_path`
-
-The path to the Speckle Automate Function to publish. This path is relative to the root of the repository. If you provide a path to a directory, your Speckle Automate Function must be in a file named `specklefunction.yaml` within that directory.
-
 #### `speckle_function_id`
 
-*Optional.* If you have already registered a Speckle Function, you can use the ID of that Speckle Function to ensure that any changes are associated with it.
-If you do not provide a Function Id, we will attempt to determine the Function ID based on the GitHub server, GitHub repository, Reference (branch), and the Speckle Function Path.
-
-Providing a Speckle Function ID allows you to change one of those values, and update the original Function instead of creating a new one.
+Associates this new version with the given ID of a Speckle Function.
 
 Your Speckle Token must have write permissions for the Speckle Function with this ID, otherwise the publish will fail.
 
+#### `speckle_function_release_tag`
+
+The release tag for this version of the Speckle Function. This is intended to provide a more human understandable name for this version, and we recommend using the [Semver](https://semver.org) naming conventions. The name must conform to the following:
+
+- A minimum of 1 character is required.
+- A maximum of 128 characters are permitted.
+- The first character must be alphanumeric (of lower or upper case) or an underscor.
+- Subsequent characters, if any, must be either alphanumeric (lower or upper case), underscore, hyphen, or a period.
+
 #### `speckle_function_recommended_cpu_m`
 
 *Optional.*  The recommended maximum CPU in millicores for the function. If the Function exceeds this limit, it will be throttled to run within the limit.
@@ -79,9 +80,9 @@ with:
   # speckle_automate_url is optional and defaults to https://automate.speckle.dev
   # The speckle_token is a secret and must be stored in GitHub as an encrypted secret
   # https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
-  speckle_token: ${{ secrets.SPECKLE_TOKEN }}
-  # speckle_function_path is optional and defaults to ./specklefunction.yaml
-  # speckle_function_id is optional and will be auto-generated if not provided
+  speckle_token: "${{ secrets.SPECKLE_TOKEN }}"
+  speckle_function_id: "abcdefghij"
+  speckle_function_release_tag: "1.0.0"
 ```
 
 #### Publish a function to a self-hosted server
@@ -93,8 +94,8 @@ with:
   speckle_automate_url: https://example.org
   # https://docs.github.com/en/actions/security-guides/encrypted-secrets#using-encrypted-secrets-in-a-workflow
   speckle_token: ${{ secrets.SPECKLE_TOKEN }}
-  # speckle_function_path is optional and defaults to ./specklefunction.yaml
-  # speckle_function_id is optional and will be auto-generated if not provided
+  speckle_function_id: "abcdefghij"
+  speckle_function_release_tag: "1.0.0"
 ```
 
 ### Example usage within an entire GitHub Actions Workflow
@@ -125,12 +126,6 @@ jobs:
         # but Speckle Automate does
         name: Checkout
         uses: actions/checkout@v3
-      -
-        id: speckle
-        name: Register Speckle Function
-        uses: actions/speckle-automate-github-action@0.1.0
-        with:
-          speckle_token: ${{ secrets.SPECKLE_TOKEN }}
       -
         name: Set up QEMU
         uses: docker/setup-qemu-action@v2
@@ -155,7 +150,17 @@ jobs:
           # ## platforms must match the platforms that you have registered with Speckle Automate, which also defaults to linux/amd64.
           # platforms: linux/amd64
           push: true
-          tags: ${{ steps.speckle.outputs.image_name }}
+          # The name of the image to build and push.
+          # This must be the automate url host, followed by the function id, followed by the release tag.
+          tags: automate.speckle.dev/abcdefghij:1.0.0
+      -
+        id: speckle
+        name: Register Speckle Function
+        uses: actions/speckle-automate-github-action@0.1.0
+        with:
+          speckle_token: ${{ secrets.SPECKLE_TOKEN }}
+          speckle_function_id: "abcdefghij"
+          speckle_function_release_tag: "1.0.0"
 ```
 
 ## Developing & Debugging

dist/action/index.js

@@ -554,7 +554,7 @@ class OidcClient {
                 .catch(error => {
                 throw new Error(`Failed to get ID Token. \n 
         Error Code : ${error.statusCode}\n 
-        Error Message: ${error.result.message}`);
+        Error Message: ${error.message}`);
             });
             const id_token = (_a = res.result) === null || _a === void 0 ? void 0 : _a.value;
             if (!id_token) {
@@ -14093,9 +14093,10 @@ const InputVariablesSchema = z.object({
     speckleAutomateUrl: z.string().url().min(1),
     speckleToken: z.string().min(1),
     speckleFunctionId: z.string().min(1),
-    speckleFunctionInputSchema: z.record(z.string().nonempty(), z.unknown()).nullable(),
-    speckleFunctionCommand: z.string().min(1).array(),
-    speckleFunctionReleaseTag: z.string().max(10).min(1),
+    speckleFunctionInputSchema: z.record(z.string().min(1), z.unknown()).nullable(),
+    speckleFunctionCommand: z.array(z.string().min(1)),
+    speckleFunctionReleaseTag: z.string()
+        .regex(new RegExp('^[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}$'), 'A maximum of 128 characters are permitted. The first character must be alphanumeric (of lower or upper case) or an underscore, the subsequent characters may be alphanumeric (or lower or upper case), underscore, hyphen, or period.'),
     speckleFunctionRecommendedCPUm: z.number()
         .int()
         .finite()
@@ -14133,8 +14134,8 @@ const parseInputs = () => {
         }),
         speckleFunctionRecommendedCPUm: parseInt(core.getInput('speckle_function_recommended_cpu_m', {
             required: false
-        })),
-        speckleFunctionRecommendedMemoryMi: parseInt(core.getInput('speckle_function_recommended_memory_mi', { required: false }))
+        })) || undefined,
+        speckleFunctionRecommendedMemoryMi: parseInt(core.getInput('speckle_function_recommended_memory_mi', { required: false })) || undefined
     };
     const inputParseResult = InputVariablesSchema.safeParse(rawInputs);
     if (inputParseResult.success)

package.json

@@ -23,32 +23,32 @@
     "node": "^16.19.1"
   },
   "dependencies": {
-    "@actions/core": "^1.10.0",
+    "@actions/core": "^1.10.1",
     "@lifeomic/attempt": "^3.0.3",
     "node-fetch": "^3.3.2",
     "zod": "^3.22.3"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.5",
-    "@types/node": "^18.17.4",
-    "@typescript-eslint/eslint-plugin": "^6.3.0",
-    "@typescript-eslint/parser": "^6.3.0",
+    "@types/node": "^18.18.8",
+    "@typescript-eslint/eslint-plugin": "^6.10.0",
+    "@typescript-eslint/parser": "^6.10.0",
     "@vercel/ncc": "^0.36.1",
-    "@vitest/coverage-istanbul": "^0.34.1",
-    "eslint": "^8.46.0",
-    "eslint-import-resolver-typescript": "^3.5.5",
+    "@vitest/coverage-istanbul": "^0.34.6",
+    "eslint": "^8.53.0",
+    "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-eslint-comments": "^3.2.0",
     "eslint-plugin-filenames": "latest",
-    "eslint-plugin-github": "^4.9.2",
+    "eslint-plugin-github": "^4.10.1",
     "eslint-plugin-i18n-text": "^1.0.1",
-    "eslint-plugin-import": "^2.28.0",
+    "eslint-plugin-import": "^2.29.0",
     "eslint-plugin-no-only-tests": "^3.1.0",
-    "eslint-plugin-prettier": "^5.0.0",
-    "eslint-plugin-vitest": "^0.2.8",
-    "msw": "^1.3.2",
-    "prettier": "^3.0.1",
-    "typescript": "^5.1.6",
-    "vite": "^4.4.9",
-    "vitest": "^0.34.1"
+    "eslint-plugin-prettier": "^5.0.1",
+    "eslint-plugin-vitest": "^0.3.9",
+    "msw": "^2.0.5",
+    "prettier": "^3.0.3",
+    "typescript": "^5.2.2",
+    "vite": "^4.5.0",
+    "vitest": "^0.34.6"
   }
 }

src/main.ts

@@ -9,9 +9,14 @@ const InputVariablesSchema = z.object({
   speckleAutomateUrl: z.string().url().min(1),
   speckleToken: z.string().min(1),
   speckleFunctionId: z.string().min(1),
-  speckleFunctionInputSchema: z.record(z.string().nonempty(), z.unknown()).nullable(),
-  speckleFunctionCommand: z.string().min(1).array(),
-  speckleFunctionReleaseTag: z.string().max(10).min(1),
+  speckleFunctionInputSchema: z.record(z.string().min(1), z.unknown()).nullable(),
+  speckleFunctionCommand: z.array(z.string().min(1)),
+  speckleFunctionReleaseTag: z
+    .string()
+    .regex(
+      new RegExp('^[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}$'),
+      'A maximum of 128 characters are permitted. The first character must be alphanumeric (of lower or upper case) or an underscore, the subsequent characters may be alphanumeric (or lower or upper case), underscore, hyphen, or period.'
+    ),
   speckleFunctionRecommendedCPUm: z
     .number()
     .int()
@@ -55,14 +60,16 @@ const parseInputs = (): InputVariables => {
     speckleFunctionReleaseTag: core.getInput('speckle_function_release_tag', {
       required: true
     }),
-    speckleFunctionRecommendedCPUm: parseInt(
-      core.getInput('speckle_function_recommended_cpu_m', {
-        required: false
-      })
-    ),
-    speckleFunctionRecommendedMemoryMi: parseInt(
-      core.getInput('speckle_function_recommended_memory_mi', { required: false })
-    )
+    speckleFunctionRecommendedCPUm:
+      parseInt(
+        core.getInput('speckle_function_recommended_cpu_m', {
+          required: false
+        })
+      ) || undefined,
+    speckleFunctionRecommendedMemoryMi:
+      parseInt(
+        core.getInput('speckle_function_recommended_memory_mi', { required: false })
+      ) || undefined
   }
   const inputParseResult = InputVariablesSchema.safeParse(rawInputs)
   if (inputParseResult.success) return inputParseResult.data

tests/main.spec.ts

@@ -13,7 +13,7 @@ import { mkdtempSync, writeFileSync, rmdirSync, rmSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { setupServer } from 'msw/node'
-import { rest } from 'msw'
+import { http, HttpResponse } from 'msw'
 import { z } from 'zod'
 
 describe('Register new version', () => {
@@ -22,30 +22,37 @@ describe('Register new version', () => {
   let count500Errors = 0
 
   const server = setupServer(
-    rest.post(
+    http.post(
       'http://myfakeautomate.speckle.internal/api/v1/functions/fake_function_id/versions',
-      async (req, res, ctx) => {
-        const parseResult = FunctionVersionRequestSchema.safeParse(await req.json())
+      async ({ request }) => {
+        const parseResult = FunctionVersionRequestSchema.safeParse(await request.json())
         expect(parseResult.success).to.be.true
         countHappyPath++
-        return res(ctx.status(201), ctx.json({ versionId: 'fake_version_id' }))
+        return new HttpResponse(JSON.stringify({ versionId: 'fake_version_id' }), {
+          status: 201,
+          headers: {
+            'Content-Type': 'application/json'
+          }
+        })
       }
     ),
-    rest.post(
+    http.post(
       'http://myfakeautomate.speckle.internal/api/v1/functions/network_error/versions',
-      async (req, res, ctx) => {
-        const parseResult = FunctionVersionRequestSchema.safeParse(await req.json())
+      async ({ request }) => {
+        const parseResult = FunctionVersionRequestSchema.safeParse(await request.json())
         expect(parseResult.success).to.be.true
-        return res.networkError('Failed to connect to server')
+        return HttpResponse.error() // simulates a network error
       }
     ),
-    rest.post(
+    http.post(
       'http://myfakeautomate.speckle.internal/api/v1/functions/500_response/versions',
-      async (req, res, ctx) => {
-        const parseResult = FunctionVersionRequestSchema.safeParse(await req.json())
+      async ({ request }) => {
+        const parseResult = FunctionVersionRequestSchema.safeParse(await request.json())
         expect(parseResult.success).to.be.true
         count500Errors++
-        return res(ctx.status(500))
+        return new HttpResponse(null, {
+          status: 500
+        })
       }
     )
   )
@@ -155,8 +162,56 @@ const FunctionVersionRequestSchema = z.object({
     .trim()
     .min(6)
     .transform((arg: string) => arg.substring(0, 10)),
-  versionTag: z.string(),
-  inputSchema: z.record(z.string(), z.unknown()).nullable(),
+  versionTag: z
+    .string()
+    .regex(
+      new RegExp('^[a-zA-Z0-9_][a-zA-Z0-9._-]{0,127}$'),
+      'A maximum of 128 characters are permitted. The first character must be alphanumeric (of lower or upper case) or an underscore, the subsequent characters may be alphanumeric (or lower or upper case), underscore, hyphen, or period.'
+    ), // regex as per OCI distribution spec https://github.com/opencontainers/distribution-spec/blob/main/spec.md#pulling-manifests
+  inputSchema: z.record(z.string(), z.unknown()).nullable(), // TODO:  we need to validate the jsonschema somehow
   command: z.array(z.string().nonempty()),
-  annotations: z.object({}).optional()
+  annotations: z
+    .object({
+      'speckle.systems/v1alpha1/publishing/status': z
+        .enum(['publish', 'draft', 'archive'], {
+          description:
+            'Whether this Function is published (and should appear in the library), a draft, or archived.'
+        })
+        .default('draft'),
+      'speckle.systems/v1alpha1/author': z
+        .string({
+          description:
+            'The name of the authoring organization or individual of this Function.'
+        })
+        .optional(),
+      'speckle.systems/v1alpha1/license': z
+        .enum(['MIT', 'BSD', 'Apache-2.0', 'MPL', 'CC0', 'Unlicense'], {
+          description:
+            'The license under under which this Function is made available. This must match the license in the source code repository.'
+        })
+        .optional(), //TODO match the specification for license names
+      'speckle.systems/v1alpha1/website': z
+        .string({
+          description: 'The marketing website for this Function or its authors.'
+        })
+        .url()
+        .optional(),
+      'speckle.systems/v1alpha1/documentation': z
+        .string({
+          description:
+            'The documentation website for this function. For example, this could be a url to the README in the source code repository.'
+        })
+        .url()
+        .optional(),
+      'speckle.systems/v1alpha1/keywords': z
+        .string({
+          description:
+            'Comma separated list of keywords used for categorizing this function.'
+        })
+        .optional(),
+      'speckle.systems/v1alpha1/description': z.string().optional()
+    })
+    .optional(),
+  recommendedCPUm: z.number().gte(100).lte(16000).finite().optional().default(1000),
+  recommendedMemoryMi: z.number().gte(1).lte(8000).finite().optional().default(100)
 })