feat: add optional visibility to metadata entries (#34)

Exposes ic-wasm's metadata visibility to users, per metadata entry.

Author: raymondk

recipes/asset-canister/README.md

@@ -28,7 +28,7 @@ canisters:
 | version | string | No | SDK version tag to download the asset canister from (e.g., `0.30.2`) | latest |
 | dir | string | Yes | Directory containing frontend assets to synchronize to the canister | - |
 | build | array | No | Shell commands to build the frontend assets before deployment (e.g., `npm run build`) | [] |
-| metadata | array | No | Array of key-value pairs for custom metadata to inject into the WASM | [] |
+| metadata | array | No | Custom wasm metadata entries. Each takes `name`, `value`, and an optional `visibility` of `public` or `private` (omitted means private) | [] |
 
 ## Prerequisites
 
@@ -69,6 +69,9 @@ canisters:
             value: "react"
           - name: "frontend:version"
             value: "1.0.0"
+          - name: "build:commit"
+            value: "a1b2c3d"
+            visibility: public
 ```
 
 ## Build Process

recipes/asset-canister/recipe.hbs

@@ -2,7 +2,7 @@
 {{! `version: string` Optional, The version of the asset canister to use. Defaults to the master branch}}
 {{! `dir: string` Required, the directory of assets to synchronize }}
 {{! `build: [string]` Optional, array of commands to build the frontend assets before deployment }}
-{{! `metadata: [name: string, value: string]`: An array of name/value pairs that get injected into the wasm metadata section }}
+{{! `metadata: [{name: string, value: string, visibility: string}]`: An array of entries that get injected into the wasm metadata section. `visibility` is optional, `public` or `private`; omitted means private, ic-wasm's default }}
 
 build:
 
@@ -34,7 +34,7 @@ build:
     - type: script
       commands:
         {{#each metadata}}
-        - sh -c 'ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}" --keep-name-section'
+        - sh -c 'ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}"{{#if visibility}} -v {{ visibility }}{{/if}} --keep-name-section'
         {{/each}}
     {{/if}}
 

recipes/motoko/README.md

@@ -33,7 +33,7 @@ Compiler flags, per-canister args, and the Candid file are all configured in `mo
 
 | Parameter | Type    | Required | Description                                  | Default |
 |-----------|---------|----------|----------------------------------------------|---------|
-| metadata  | array   | No       | Array of key-value pairs for custom metadata | []      |
+| metadata  | array   | No       | Custom wasm metadata entries. Each takes `name`, `value`, and an optional `visibility` of `public` or `private` (omitted means private) | []      |
 | shrink    | boolean | No       | Remove unused functions and debug info to reduce file size | false   |
 | compress  | boolean | No       | Gzip compress the WASM file                  | false   |
 
@@ -83,6 +83,9 @@ canisters:
         metadata:
           - name: "canister:type"
             value: "backend"
+          - name: "build:commit"
+            value: "a1b2c3d"
+            visibility: public
 ```
 
 ```toml

recipes/motoko/recipe.hbs

@@ -1,7 +1,7 @@
 {{! A recipe for building a Motoko canister using `mops build` }}
 {{! `shrink: boolean` Optimizes the wasm with ic-wasm }}
 {{! `compress: boolean` determines whether the wasm should be gzipped }}
-{{! `metadata: [name: string, value: string]`: An array of name/value pairs that get injected into the wasm metadata section }}
+{{! `metadata: [{name: string, value: string, visibility: string}]`: An array of entries that get injected into the wasm metadata section. `visibility` is optional, `public` or `private`; omitted means private, ic-wasm's default }}
 
 build:
   steps:
@@ -28,7 +28,7 @@ build:
         - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "template:type" -d "motoko" --keep-name-section
         {{#if metadata}}
         {{#each metadata}}
-        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}" --keep-name-section
+        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}"{{#if visibility}} -v {{ visibility }}{{/if}} --keep-name-section
         {{/each}}
         {{/if}}
 

recipes/prebuilt/README.md

@@ -31,7 +31,7 @@ canisters:
 | sha256 | string | No | SHA256 hash for integrity verification. Generate with `sha256sum <file>.wasm` | - |
 | shrink | boolean | No | Remove unused functions and debug info to reduce file size | false |
 | compress | boolean | No | Gzip compress the WASM file | false |
-| metadata | array | No | Array of key-value pairs for custom metadata to inject into the WASM | [] |
+| metadata | array | No | Custom wasm metadata entries. Each takes `name`, `value`, and an optional `visibility` of `public` or `private` (omitted means private) | [] |
 
 ## Prerequisites
 
@@ -73,6 +73,9 @@ canisters:
             value: "2.1.0"
           - name: "build:environment"
             value: "production"
+          - name: "build:commit"
+            value: "a1b2c3d"
+            visibility: public
           - name: "build:timestamp"
             value: "2024-01-01T00:00:00Z"
 ```

recipes/prebuilt/recipe.hbs

@@ -3,7 +3,7 @@
 {{! `sha256: string` Optional, the hash of the wasm to deploy}}
 {{! `shrink: boolean` Optimizes the wasm with ic-wasm }}
 {{! `compress: boolean` determines whether the wasm should be gzipped }}
-{{! `metadata: [name: string, value: string]`: An array of name/value pairs that get injected into the wasm metadata section }}
+{{! `metadata: [{name: string, value: string, visibility: string}]`: An array of entries that get injected into the wasm metadata section. `visibility` is optional, `public` or `private`; omitted means private, ic-wasm's default }}
 
 build:
 
@@ -32,7 +32,7 @@ build:
     - type: script
       commands:
         {{#each metadata}}
-        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}" --keep-name-section
+        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}"{{#if visibility}} -v {{ visibility }}{{/if}} --keep-name-section
         {{/each}}
     {{/if}}
 

recipes/rust/README.md

@@ -26,7 +26,7 @@ By convention the canister `name` in `icp.yaml` should match the `[package] name
 | package   | string  | No       | Cargo package name to build. Defaults to the canister name in `icp.yaml` | (canister name) |
 | locked    | boolean | No       | Use exact dependency versions from `Cargo.lock` (passes `--locked` to Cargo) | false                     |
 | candid    | string  | No       | Path to a custom Candid interface file. If not provided, the interface is auto-extracted from the WASM using `candid-extractor` | (auto-extracted) |
-| metadata  | array   | No       | Array of key-value pairs for custom metadata | []                        |
+| metadata  | array   | No       | Custom wasm metadata entries. Each takes `name`, `value`, and an optional `visibility` of `public` or `private` (omitted means private) | []                        |
 | shrink    | boolean | No       | Remove unused functions and debug info to reduce file size | false                     |
 | compress  | boolean | No       | Gzip compress the WASM file                  | false                     |
 
@@ -75,6 +75,9 @@ canisters:
             value: "1.0.0"
           - name: "build:profile"
             value: "release"
+          - name: "build:commit"
+            value: "a1b2c3d"
+            visibility: public
 ```
 
 ### Workspace Example

recipes/rust/recipe.hbs

@@ -4,7 +4,7 @@
 {{! `candid: string` The path to the Candid interface file }}
 {{! `shrink: boolean` Optimizes the wasm with ic-wasm }}
 {{! `compress: boolean` determines whether the wasm should be gzipped }}
-{{! `metadata: [name: string, value: string]`: An array of name/value pairs that get injected into the wasm metadata section }}
+{{! `metadata: [{name: string, value: string, visibility: string}]`: An array of entries that get injected into the wasm metadata section. `visibility` is optional, `public` or `private`; omitted means private, ic-wasm's default }}
 
 build:
   steps:
@@ -36,7 +36,7 @@ build:
         {{/if}}
         {{#if metadata}}
         {{#each metadata}}
-        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}" --keep-name-section
+        - ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "${ICP_WASM_OUTPUT_PATH}" metadata "{{ name }}" -d "{{ value }}"{{#if visibility}} -v {{ visibility }}{{/if}} --keep-name-section
         {{/each}}
         {{/if}}
 

recipes/static-site/README.md

@@ -26,7 +26,7 @@ canisters:
 | dir | string | Yes | The single directory of built assets to synchronize to the canister | - |
 | build | array | No | Shell commands run before sync to produce the asset directory (e.g. `npm run build`) | [] |
 | presync | array | No | Shell commands run at sync time (after the canister exists), with the deployed canister IDs in the environment — see [Pre-sync environment](#pre-sync-environment) | [] |
-| metadata | array | No | Name/value pairs injected into the canister wasm via `ic-wasm` | [] |
+| metadata | array | No | Entries injected into the canister wasm via `ic-wasm`. Each takes `name`, `value`, and an optional `visibility` of `public` or `private` (omitted means private) | [] |
 
 > The sync plugin owns the canister's full URL space and accepts **exactly one** asset directory, so `dir` is a single string rather than a list.
 
@@ -66,6 +66,9 @@ canisters:
         metadata:
           - name: "frontend:framework"
             value: "react"
+          - name: "build:commit"
+            value: "a1b2c3d"
+            visibility: public
 ```
 
 ### With a pre-sync build that needs canister IDs

recipes/static-site/recipe.hbs

@@ -2,7 +2,7 @@
 {{! `dir: string` Required. The single directory of built assets to synchronize. }}
 {{! `build: [string]` Optional. Commands run before sync to produce the asset directory. }}
 {{! `presync: [string]` Optional. Commands run at sync time (after the canister exists), before assets upload, with the deployed canister IDs in the environment: ICP_CLI_CID, ICP_CLI_CID_<NAME>, ICP_CLI_NETWORK, ICP_CLI_ENVIRONMENT. }}
-{{! `metadata: [{name, value}]` Optional. Pairs injected into the canister wasm via ic-wasm. }}
+{{! `metadata: [{name, value, visibility}]` Optional. Entries injected into the canister wasm via ic-wasm. `visibility` is optional, `public` or `private`; omitted means private, ic-wasm's default. }}
 
 build:
   steps:
@@ -25,7 +25,7 @@ build:
     - type: script
       commands:
         {{#each metadata}}
-        - sh -c 'ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "$ICP_WASM_OUTPUT_PATH" metadata "{{ name }}" -d "{{ value }}" --keep-name-section'
+        - sh -c 'ic-wasm "$ICP_WASM_OUTPUT_PATH" -o "$ICP_WASM_OUTPUT_PATH" metadata "{{ name }}" -d "{{ value }}"{{#if visibility}} -v {{ visibility }}{{/if}} --keep-name-section'
         {{/each}}
     {{/if}}