@jenga-ai/agent 1.0.0

package/skills/publish/scripts/validate_config.sh

@@ -0,0 +1,163 @@
+#!/usr/bin/env bash
+set -u
+
+CONFIG_PATH="${1:-}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCHEMA_PATH="${SCRIPT_DIR}/../schemas/publish.schema.json"
+EXIT_CONFIG_INVALID=4
+
+fail() {
+  printf 'publish config validation failed: %s\n' "$1" >&2
+  exit "$EXIT_CONFIG_INVALID"
+}
+
+[[ -n "$CONFIG_PATH" ]] || fail "missing config path argument"
+[[ -f "$CONFIG_PATH" ]] || fail "config file not found at '$CONFIG_PATH'"
+[[ -f "$SCHEMA_PATH" ]] || fail "schema file not found at '$SCHEMA_PATH'"
+command -v jq >/dev/null 2>&1 || fail "jq is required"
+
+jq -e . "$SCHEMA_PATH" >/dev/null 2>&1 || fail "schema file is not valid JSON"
+jq -e . "$CONFIG_PATH" >/dev/null 2>&1 || fail "config file is not valid JSON"
+
+# shellcheck disable=SC2154  # $t, $cfg, $schema are jq variables inside the single-quoted program below, not shell variables.
+ERRORS="$(
+  jq -rn \
+    --slurpfile cfg "$CONFIG_PATH" \
+    --slurpfile schema "$SCHEMA_PATH" '
+    ($cfg[0]) as $cfg
+    | ($schema[0]) as $schema
+    | def env_ref: type == "string" and test("^\\$\\{?[A-Z][A-Z0-9_]*\\}?$");
+      def non_empty_string: type == "string" and length > 0;
+      def string_gate_name: type == "string" and test("^[a-z0-9][a-z0-9-]*$");
+      def gate_entry_valid:
+        (string_gate_name)
+        or (
+          type == "object"
+          and (
+            (.name? | string_gate_name)
+            or (.gate? | string_gate_name)
+            or (.type? | string_gate_name)
+          )
+        );
+      def gate_list_valid:
+        type == "array" and all(.[]?; gate_entry_valid);
+      def checks_valid:
+        type == "object"
+        and ((.pre? == null) or (.pre | gate_list_valid))
+        and ((.post? == null) or (.post | gate_list_valid));
+      def secrets_valid:
+        type == "object"
+        and (.app_store_connect_api_key_id? | env_ref)
+        and (.app_store_connect_issuer_id? | env_ref)
+        and (.app_store_connect_private_key_path? | env_ref)
+        and (.code_sign_identity? | env_ref)
+        and (.provisioning_profile_uuid? | env_ref);
+      def ios_valid:
+        type == "object"
+        and (.scheme? | non_empty_string)
+        and (.configuration? | non_empty_string)
+        and (.archive_path? | non_empty_string)
+        and (.export_path? | non_empty_string)
+        and (((.export_method? // "") == "ad-hoc") or ((.export_method? // "") == "app-store"))
+        and (.bundle_id? | non_empty_string)
+        and (.team_id? | type == "string" and test("^[A-Z0-9]{6,}$"))
+        and (.app_store_app_id? | type == "string" and test("^[0-9]+$"))
+        and (((.project_path? // empty) | non_empty_string) or ((.workspace_path? // empty) | non_empty_string));
+      def npm_secrets_valid:
+        type == "object"
+        and (
+          (((.NPM_TOKEN? // null) != null) and (.NPM_TOKEN | env_ref))
+          or (((.NODE_AUTH_TOKEN? // null) != null) and (.NODE_AUTH_TOKEN | env_ref))
+        );
+      def npm_valid:
+        type == "object"
+        and (.package_name? | non_empty_string)
+        and (.package_name | test("^(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"))
+        and ((.package_name | length) <= 214)
+        and (((.access? // "") == "public") or ((.access? // "") == "restricted"))
+        and (((.registry? // null) == null) or (.registry | non_empty_string))
+        and (((.dist_tag? // null) == null) or (((.dist_tag | type) == "string") and (.dist_tag | test("^[a-z0-9][a-z0-9._-]*$"))));
+      def npm_ci_valid:
+        type == "object"
+        and (.package_name? | non_empty_string)
+        and (.package_name | test("^(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"))
+        and ((.package_name | length) <= 214)
+        and (((.access? // "") == "public") or ((.access? // "") == "restricted"))
+        and (((.registry? // null) == null) or (.registry | non_empty_string))
+        and (((.dist_tag? // null) == null) or (((.dist_tag | type) == "string") and (.dist_tag | test("^[a-z0-9][a-z0-9._-]*$"))));
+      def ios_target_valid:
+        type == "object"
+        and (.name? | type == "string" and test("^[a-z0-9][a-z0-9-]*$"))
+        and (.type? == "mobile-ios")
+        and (.platform? == "ios-app-store")
+        and (.checks? | checks_valid)
+        and (.secrets? | secrets_valid)
+        and (.ios? | ios_valid);
+      def npm_target_valid:
+        type == "object"
+        and (.name? | type == "string" and test("^[a-z0-9][a-z0-9-]*$"))
+        and (.type? == "npm")
+        and (((.platform? // "") == "npm-registry") or ((.platform? // "") == "github-packages"))
+        and (.checks? | checks_valid)
+        and (.secrets? | npm_secrets_valid)
+        and (.npm? | npm_valid)
+        and ((.ios? // null) == null);
+      def npm_ci_target_valid:
+        type == "object"
+        and (.name? | type == "string" and test("^[a-z0-9][a-z0-9-]*$"))
+        and (.type? == "npm-ci")
+        and ((.github_repo? // "") | non_empty_string)
+        and (.npm? | npm_ci_valid)
+        and ((.ios? // null) == null);
+      def target_valid: ios_target_valid or npm_target_valid or npm_ci_target_valid;
+      def target_label: (.name? // "<unnamed>");
+      def npm_diagnostics:
+        . as $t
+        | [
+            (if (($t.npm? | type) != "object") then ("target \"" + ($t | target_label) + "\": npm block is required for npm targets") else empty end),
+            (if ((($t.npm?.package_name? // "") | non_empty_string) | not) then ("target \"" + ($t | target_label) + "\": npm.package_name is required and must be a non-empty string") else empty end),
+            (if ((($t.npm?.package_name? // "") | type) == "string" and (($t.npm.package_name | length) > 0) and ((($t.npm.package_name | test("^(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"))) | not)) then ("target \"" + ($t | target_label) + "\": npm.package_name must match npm naming rules") else empty end),
+            (if (((($t.npm?.access? // "") == "public") or (($t.npm?.access? // "") == "restricted")) | not) then ("target \"" + ($t | target_label) + "\": npm.access must be \"public\" or \"restricted\"") else empty end),
+            (if (($t.ios? // null) != null) then ("target \"" + ($t | target_label) + "\": ios block is not allowed on npm targets") else empty end),
+            (if (((($t.platform? // "") == "npm-registry") or (($t.platform? // "") == "github-packages")) | not) then ("target \"" + ($t | target_label) + "\": platform must be \"npm-registry\" or \"github-packages\" for npm targets") else empty end),
+            (if (($t.secrets? | npm_secrets_valid) | not) then ("target \"" + ($t | target_label) + "\": secrets must contain NPM_TOKEN or NODE_AUTH_TOKEN as an environment reference") else empty end)
+          ] | .[];
+      def npm_ci_diagnostics:
+        . as $t
+        | [
+            (if (($t.github_repo? // "") | non_empty_string) then empty else ("target \"" + ($t | target_label) + "\": github_repo is required and must be a non-empty string") end),
+            (if (($t.npm? | type) != "object") then ("target \"" + ($t | target_label) + "\": npm block is required for npm-ci targets") else empty end),
+            (if ((($t.npm?.package_name? // "") | non_empty_string) | not) then ("target \"" + ($t | target_label) + "\": npm.package_name is required and must be a non-empty string") else empty end),
+            (if ((($t.npm?.package_name? // "") | type) == "string" and (($t.npm.package_name | length) > 0) and ((($t.npm.package_name | test("^(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"))) | not)) then ("target \"" + ($t | target_label) + "\": npm.package_name must match npm naming rules") else empty end),
+            (if (((($t.npm?.access? // "") == "public") or (($t.npm?.access? // "") == "restricted")) | not) then ("target \"" + ($t | target_label) + "\": npm.access must be \"public\" or \"restricted\"") else empty end),
+            (if (($t.ios? // null) != null) then ("target \"" + ($t | target_label) + "\": ios block is not allowed on npm-ci targets") else empty end)
+          ] | .[];
+      def per_target_errors:
+        . as $t
+        | if target_valid then empty
+          elif ($t.type? == "npm") then ($t | npm_diagnostics)
+          elif ($t.type? == "npm-ci") then ($t | npm_ci_diagnostics)
+          elif ($t.type? == "mobile-ios") then ("invalid target: " + ($t | target_label))
+          else ("target \"" + ($t | target_label) + "\": type must be \"mobile-ios\", \"npm\", or \"npm-ci\"") end;
+      [
+        (if (($schema["$schema"] // "") | contains("draft-07")) then empty else "schema must declare draft-07" end),
+        (if (($cfg | type) == "object") then empty else "root config must be an object" end),
+        (if (($cfg.version? // null) == 1) then empty else "version must be 1" end),
+        (if (($cfg.defaults? | type) == "object") then empty else "defaults must be an object" end),
+        (if (($cfg.defaults.history_file? // "") | non_empty_string) then empty else "defaults.history_file must be a non-empty string" end),
+        (if (($cfg.defaults.mandatory_checks? | type) == "array" and (($cfg.defaults.mandatory_checks | length) > 0) and all($cfg.defaults.mandatory_checks[]; string_gate_name)) then empty else "defaults.mandatory_checks must be a non-empty array of gate names" end),
+        (if (($cfg.defaults.optional_checks? == null) or (($cfg.defaults.optional_checks | type) == "array" and all($cfg.defaults.optional_checks[]; string_gate_name))) then empty else "defaults.optional_checks must be an array of gate names when provided" end),
+        (if (($cfg.targets? | type) == "array" and (($cfg.targets | length) > 0)) then empty else "targets must be a non-empty array" end),
+        (if (($cfg.targets? | type) == "array") then ([$cfg.targets[] | per_target_errors] | .[]) else empty end)
+      ] | map(select(. != null and . != "")) | .[]
+  ' 2>/dev/null || true
+)"
+
+if [[ -n "$ERRORS" ]]; then
+  while IFS= read -r line; do
+    [[ -n "$line" ]] && printf 'publish config validation failed: %s\n' "$line" >&2
+  done <<< "$ERRORS"
+  exit "$EXIT_CONFIG_INVALID"
+fi
+
+exit 0

package/skills/publish/scripts/validate_droplet_env.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+set -u
+
+EXIT_ENV_INVALID=4
+
+# Usage: validate_droplet_env.sh <publish_json_path> <target_name>
+
+CONFIG_PATH="${1:-}"
+TARGET_NAME="${2:-}"
+
+fail() {
+  printf 'droplet env validation failed: %s\n' "$1" >&2
+  exit "$EXIT_ENV_INVALID"
+}
+
+[[ -n "$CONFIG_PATH" ]] || fail "missing publish.json path argument"
+[[ -f "$CONFIG_PATH" ]] || fail "publish config not found at '$CONFIG_PATH'"
+command -v jq >/dev/null 2>&1 || fail "jq is required but not found on PATH"
+[[ -n "$TARGET_NAME" ]] || fail "missing target name argument"
+
+# Extract the droplet target block
+TARGET_JSON="$(jq -c --arg t "$TARGET_NAME" \
+  '.targets[]? | select(.name == $t and .type == "droplet")' \
+  "$CONFIG_PATH")"
+[[ -n "$TARGET_JSON" ]] || fail "target '$TARGET_NAME' was not found or is not type 'droplet' in '$CONFIG_PATH'"
+
+check_field() {
+  local label="$1"
+  local value
+  value="$(printf '%s' "$TARGET_JSON" | jq -r "$2 // empty" 2>/dev/null || true)"
+  if [[ -z "$value" ]]; then
+    fail "missing required field '$label'"
+  fi
+}
+
+check_field "host"              '.droplet.host'
+check_field "ssh_user"          '.droplet.ssh_user'
+check_field "deploy_path"       '.droplet.deploy_path'
+check_field "github_repo"       '.droplet.github_repo'
+check_field "deploy_branch"     '.droplet.deploy_branch'
+check_field "start_cmd"         '.droplet.start_cmd'
+check_field "ssh_key_secret"    '.secrets.ssh_key_secret'
+check_field "known_hosts_secret" '.secrets.known_hosts_secret'
+
+exit 0

package/skills/publish/scripts/validate_ios_env.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -u
+
+CONFIG_PATH="${1:-}"
+TARGET_NAME="${2:-}"
+EXIT_ENV_INVALID=4
+
+fail() {
+  printf 'iOS env validation failed: %s\n' "$1" >&2
+  exit "$EXIT_ENV_INVALID"
+}
+
+[[ -n "$CONFIG_PATH" ]] || fail "missing publish.json path argument"
+[[ -f "$CONFIG_PATH" ]] || fail "publish config not found at '$CONFIG_PATH'"
+command -v jq >/dev/null 2>&1 || fail "jq is required"
+
+if [[ -n "$TARGET_NAME" ]]; then
+  jq -e --arg target "$TARGET_NAME" '.targets[]? | select(.name == $target and .type == "mobile-ios")' "$CONFIG_PATH" >/dev/null 2>&1 || \
+    fail "target '$TARGET_NAME' was not found or is not mobile-ios"
+fi
+
+REQUIRED_VARS=()
+while IFS= read -r var_name; do
+  [[ -n "$var_name" ]] && REQUIRED_VARS+=("$var_name")
+done < <(
+  jq -r --arg target "$TARGET_NAME" '
+    [
+      .targets[]?
+      | select(.type == "mobile-ios")
+      | if $target == "" then . else select(.name == $target) end
+      | [
+          .secrets.app_store_connect_api_key_id?,
+          .secrets.app_store_connect_issuer_id?,
+          .secrets.app_store_connect_private_key_path?,
+          .secrets.code_sign_identity?,
+          .secrets.provisioning_profile_uuid?
+        ][]
+      | select(type == "string" and length > 0)
+      | sub("^\\$\\{"; "")
+      | sub("^\\$"; "")
+      | sub("\\}$"; "")
+    ]
+    | unique
+    | .[]
+  ' "$CONFIG_PATH"
+)
+
+if [[ ${#REQUIRED_VARS[@]} -eq 0 ]]; then
+  if [[ -n "$TARGET_NAME" ]]; then
+    fail "no mobile-ios env-var references were found for target '$TARGET_NAME'"
+  fi
+  fail "no mobile-ios env-var references were found in '$CONFIG_PATH'"
+fi
+
+MISSING_VARS=()
+for var_name in "${REQUIRED_VARS[@]}"; do
+  value="$(printenv "$var_name" 2>/dev/null || true)"
+  if [[ -z "$value" ]]; then
+    MISSING_VARS+=("$var_name")
+  fi
+done
+
+if [[ ${#MISSING_VARS[@]} -gt 0 ]]; then
+  printf 'Missing required iOS environment variables: %s\n' "${MISSING_VARS[*]}" >&2
+  exit "$EXIT_ENV_INVALID"
+fi
+
+exit 0

package/skills/publish/scripts/validate_npm_ci_env.sh

@@ -0,0 +1,71 @@
+#!/usr/bin/env bash
+set -u
+
+EXIT_ENV_INVALID=4
+
+# Usage: validate_npm_ci_env.sh <publish_json_path> <target_name>
+
+CONFIG_PATH="${1:-}"
+TARGET_NAME="${2:-}"
+
+fail() {
+  printf '[validate] ERROR: %s\n' "$1" >&2
+  exit "$EXIT_ENV_INVALID"
+}
+
+# ── runtime dependency checks ──────────────────────────────────────────────────
+
+command -v gh >/dev/null 2>&1 || fail "gh CLI is required but not found on PATH. Install it from https://cli.github.com/ and re-run."
+
+gh auth status >/dev/null 2>&1 || fail "gh CLI is not authenticated. Run 'gh auth login' and re-run."
+
+command -v jq >/dev/null 2>&1 || fail "jq is required but not found on PATH. Install it from https://stedolan.github.io/jq/ and re-run."
+
+# ── config argument checks ─────────────────────────────────────────────────────
+
+[[ -n "$CONFIG_PATH" ]] || fail "missing publish.json path argument"
+[[ -f "$CONFIG_PATH" ]] || fail "publish config not found at '$CONFIG_PATH'"
+[[ -n "$TARGET_NAME" ]] || fail "missing target name argument"
+
+# ── extract the npm-ci target block ───────────────────────────────────────────
+
+TARGET_JSON="$(jq -c --arg t "$TARGET_NAME" \
+  '.targets[]? | select(.name == $t and .type == "npm-ci")' \
+  "$CONFIG_PATH")"
+[[ -n "$TARGET_JSON" ]] || fail "target '$TARGET_NAME' was not found or is not type 'npm-ci' in '$CONFIG_PATH'"
+
+# ── field validators ───────────────────────────────────────────────────────────
+
+check_field() {
+  local label="$1"
+  local value
+  value="$(printf '%s' "$TARGET_JSON" | jq -r "$2 // empty" 2>/dev/null || true)"
+  if [[ -z "$value" ]]; then
+    fail "missing required field '$label'"
+  fi
+}
+
+# github_repo — required at the target level (not nested under .npm)
+check_field "github_repo" '.github_repo'
+
+# Verify github_repo contains exactly one '/'
+GITHUB_REPO="$(printf '%s' "$TARGET_JSON" | jq -r '.github_repo // empty' 2>/dev/null || true)"
+SLASH_COUNT="${GITHUB_REPO//[!\/]}"
+if [[ ${#SLASH_COUNT} -ne 1 ]]; then
+  fail "field 'github_repo' must be in 'owner/name' format (contains exactly one '/'), got: '$GITHUB_REPO'"
+fi
+
+# npm.package_name — required
+check_field "npm.package_name" '.npm.package_name'
+
+# npm.access — required; must be 'public' or 'restricted'
+check_field "npm.access" '.npm.access'
+NPM_ACCESS="$(printf '%s' "$TARGET_JSON" | jq -r '.npm.access // empty' 2>/dev/null || true)"
+if [[ "$NPM_ACCESS" != "public" && "$NPM_ACCESS" != "restricted" ]]; then
+  fail "field 'npm.access' must be 'public' or 'restricted', got: '$NPM_ACCESS'"
+fi
+
+# ── all checks passed ──────────────────────────────────────────────────────────
+
+printf '[validate] environment OK\n'
+exit 0

package/skills/publish/scripts/validate_npm_env.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+set -u
+
+EXIT_ENV_INVALID=4
+
+fail() {
+  printf 'npm env validation failed: %s\n' "$1" >&2
+  exit "$EXIT_ENV_INVALID"
+}
+
+if ! command -v npm >/dev/null 2>&1; then
+  fail "'npm' was not found on PATH. Install Node.js (which provides npm) from https://nodejs.org/ or via your package manager, then re-run."
+fi
+
+NPM_TOKEN_VALUE="$(printenv NPM_TOKEN 2>/dev/null || true)"
+NODE_AUTH_TOKEN_VALUE="$(printenv NODE_AUTH_TOKEN 2>/dev/null || true)"
+
+if [[ -z "$NPM_TOKEN_VALUE" && -z "$NODE_AUTH_TOKEN_VALUE" ]]; then
+  fail "no npm auth token found. Set NPM_TOKEN (or NODE_AUTH_TOKEN) in the environment before publishing, e.g. 'export NPM_TOKEN=<your-npm-automation-token>'. Generate a token at https://www.npmjs.com/settings/<user>/tokens."
+fi
+
+exit 0

package/skills/publish/scripts/write_ledger_entry.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/publish_common.sh"
+
+usage() {
+  cat <<'USAGE'
+Usage: write_ledger_entry.sh <target> <adapter> <platform_state> <notes_path> [--yes] [--dry-run] [--version <vX.Y.Z>] [--config <path>]
+USAGE
+}
+
+[[ $# -ge 4 ]] || { usage >&2; exit 1; }
+TARGET_NAME="$1"
+ADAPTER_NAME="$2"
+PLATFORM_STATE="$3"
+NOTES_PATH_RAW="$4"
+shift 4
+
+AUTO_ACCEPT=0
+DRY_RUN=0
+SELECTED_VERSION=''
+CONFIG_PATH="${PUBLISH_CONFIG:-}"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --yes)
+      AUTO_ACCEPT=1
+      shift
+      ;;
+    --dry-run)
+      DRY_RUN=1
+      shift
+      ;;
+    --version)
+      [[ $# -ge 2 ]] || { usage >&2; exit 1; }
+      SELECTED_VERSION="$2"
+      shift 2
+      ;;
+    --config)
+      [[ $# -ge 2 ]] || { usage >&2; exit 1; }
+      CONFIG_PATH="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      usage >&2
+      exit 1
+      ;;
+  esac
+done
+
+[[ -n "$TARGET_NAME" && -n "$ADAPTER_NAME" && -n "$PLATFORM_STATE" ]] || { usage >&2; exit 1; }
+command -v jq >/dev/null 2>&1 || { echo 'jq is required.' >&2; exit 1; }
+
+HISTORY_FILE="$(publish_resolve_history_file "$CONFIG_PATH")"
+publish_ensure_history_file "$HISTORY_FILE"
+
+if [[ -n "$SELECTED_VERSION" ]]; then
+  VERSION="$SELECTED_VERSION"
+else
+  SUGGEST_CMD=(bash "$SCRIPT_DIR/suggest_semver_bump.sh")
+  if (( AUTO_ACCEPT )); then
+    SUGGEST_CMD+=(--yes)
+  fi
+  if [[ -n "$CONFIG_PATH" ]]; then
+    SUGGEST_CMD+=("$CONFIG_PATH")
+  fi
+  VERSION_OUTPUT="$("${SUGGEST_CMD[@]}")"
+  printf '%s\n' "$VERSION_OUTPUT"
+  VERSION="$(printf '%s\n' "$VERSION_OUTPUT" | tail -n 1 | tr -d '\r')"
+fi
+VERSION="$(publish_normalize_version "$VERSION")" || {
+  echo "Unable to resolve a valid version from suggest_semver_bump.sh output." >&2
+  exit 1
+}
+
+GIT_TAG="$VERSION"
+if (( DRY_RUN )); then
+  printf '[DRY RUN] Would create tag %s\n' "$GIT_TAG"
+elif git rev-parse "$GIT_TAG" >/dev/null 2>&1; then
+  printf '⚠️  Git tag %s already exists — skipping tag creation\n' "$GIT_TAG" >&2
+else
+  git tag -a "$GIT_TAG" -m "Release $GIT_TAG — deployed to $TARGET_NAME"
+fi
+
+TIMESTAMP="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+RELEASED_BY="$(publish_current_actor)"
+COMMIT_SHA="$(git rev-parse HEAD)"
+ENTRY_ID="$(uuidgen | tr '[:upper:]' '[:lower:]')"
+
+if [[ -z "$NOTES_PATH_RAW" || "$NOTES_PATH_RAW" == 'null' ]]; then
+  NOTES_JSON='null'
+else
+  NOTES_JSON="$(jq -Rn --arg path "$NOTES_PATH_RAW" '$path')"
+fi
+
+ENTRY_JSON="$(jq -cn \
+  --arg id "$ENTRY_ID" \
+  --arg version "$VERSION" \
+  --arg target "$TARGET_NAME" \
+  --arg adapter "$ADAPTER_NAME" \
+  --arg timestamp "$TIMESTAMP" \
+  --arg released_by "$RELEASED_BY" \
+  --arg platform_state "$PLATFORM_STATE" \
+  --arg git_tag "$GIT_TAG" \
+  --arg commit_sha "$COMMIT_SHA" \
+  --argjson release_notes_path "$NOTES_JSON" \
+  '{
+    id: $id,
+    version: $version,
+    target: $target,
+    adapter: $adapter,
+    timestamp: $timestamp,
+    released_by: $released_by,
+    release_notes_path: $release_notes_path,
+    platform_state: $platform_state,
+    git_tag: $git_tag,
+    commit_sha: $commit_sha
+  }')"
+
+publish_append_history_entry "$HISTORY_FILE" "$ENTRY_JSON"
+printf '🧾 Publish ledger entry appended for %s\n' "$VERSION"