@jenga-ai/agent 1.0.0

package/skills/publish/assets/secrets-guide.md

@@ -0,0 +1,104 @@
+# Publish secrets guide
+
+## Never do this
+
+Never commit secrets, tokens, certificates, API keys, or `.env` files into git.
+Use gitignored local files or secret stores instead.
+
+```gitignore
+.env
+.env.*
+*.local
+```
+
+If a value is sensitive, keep the real value outside the repository and store only its environment-variable name in `publish.json`.
+
+## Local development
+
+For local-only setup, keep secrets in a gitignored `.env` file or shell profile and load them before running `/publish`.
+If you already use `direnv`, prefer a gitignored `.envrc` or sourced env file so the variables are loaded automatically when you enter the project.
+
+Example:
+
+```bash
+export APP_STORE_CONNECT_API_KEY_ID=ABC123XYZ
+export IOS_PROVISIONING_PROFILE_UUID=11111111-2222-3333-4444-555555555555
+```
+
+## macOS Keychain
+
+Use the macOS Keychain when you do not want long-lived secret values sitting in plain text files.
+Store a secret:
+
+```bash
+security add-generic-password -a "$USER" -s publish.app-store-connect.api-key-id -w '<value>'
+```
+
+Read it later into an environment variable:
+
+```bash
+export APP_STORE_CONNECT_API_KEY_ID="$(security find-generic-password -a "$USER" -s publish.app-store-connect.api-key-id -w)"
+```
+
+You can repeat the same pattern for provisioning-profile references or other deploy credentials.
+
+## GitHub Actions / CI secrets
+
+Store shared secrets in repository or organization secrets, then map them to job-level environment variables.
+Reference them in workflow files with `${{ secrets.NAME }}`.
+
+Example:
+
+```yaml
+env:
+  APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
+  IOS_PROVISIONING_PROFILE_UUID: ${{ secrets.IOS_PROVISIONING_PROFILE_UUID }}
+```
+
+Use repository secrets for project-specific values and organization secrets for centrally managed credentials that multiple repositories share.
+
+## Droplet (GitHub Actions → SSH)
+
+The `droplet` adapter reads all SSH credentials from GitHub Actions secrets at workflow runtime. Your `publish.json` stores only the *names* of the secrets — never the values.
+
+### Required secrets
+
+| Secret name | Value |
+|---|---|
+| `DROPLET_SSH_HOST` | IP address or FQDN of your target host |
+| `DROPLET_SSH_USER` | SSH login username (e.g. `ubuntu`, `deploy`) |
+| `DROPLET_SSH_PORT` | SSH port number (usually `22`) |
+| `DROPLET_SSH_KEY` | Contents of the private key used to SSH into the host |
+| `DROPLET_KNOWN_HOSTS` | Output of `ssh-keyscan -H <host>` |
+
+### How to add secrets
+
+Via the `gh` CLI (recommended):
+
+```bash
+gh secret set DROPLET_SSH_HOST --body "1.2.3.4" --repo owner/myrepo
+gh secret set DROPLET_SSH_USER --body "deploy" --repo owner/myrepo
+gh secret set DROPLET_SSH_PORT --body "22" --repo owner/myrepo
+gh secret set DROPLET_SSH_KEY < ~/.ssh/id_deploy --repo owner/myrepo
+ssh-keyscan -H 1.2.3.4 | gh secret set DROPLET_KNOWN_HOSTS --repo owner/myrepo
+```
+
+Via the GitHub UI: **Repository → Settings → Secrets and variables → Actions → New repository secret**.
+
+### Generating the SSH key pair
+
+If you don't have a dedicated deploy key:
+
+```bash
+ssh-keygen -t ed25519 -C "deploy@myrepo" -f ~/.ssh/id_deploy -N ""
+# Add the public key to the host's authorized_keys:
+ssh-copy-id -i ~/.ssh/id_deploy.pub deploy@1.2.3.4
+# Then add the private key to GitHub secrets (see above)
+```
+
+Never commit the private key to the repository.
+
+## General rule
+
+Secrets in `publish.json` are always environment-variable references such as `APP_STORE_CONNECT_API_KEY_ID`.
+Do not put literal secret values in `publish.json`, shell scripts, commit messages, or logs.

package/skills/publish/schemas/fixtures/npm-ci-minimal.json

@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": ["build-ok"]
+  },
+  "targets": [
+    {
+      "name": "my-pkg",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "checks": {},
+      "npm": { "package_name": "my-pkg", "access": "public" },
+      "github_repo": "owner/my-pkg"
+    }
+  ]
+}

package/skills/publish/schemas/fixtures/npm-ci-with-empty-secrets.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": ["build-ok"]
+  },
+  "targets": [
+    {
+      "name": "my-pkg",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "checks": {},
+      "secrets": {},
+      "npm": { "package_name": "my-pkg", "access": "public" },
+      "github_repo": "owner/my-pkg"
+    }
+  ]
+}

package/skills/publish/schemas/fixtures/npm-ci-with-workflow-path.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "defaults": {
+    "history_file": "project/logs/publish-history.json",
+    "mandatory_checks": ["build-ok"]
+  },
+  "targets": [
+    {
+      "name": "my-pkg",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "checks": {},
+      "npm": { "package_name": "my-pkg", "access": "public" },
+      "github_repo": "owner/my-pkg",
+      "workflow_path": ".github/workflows/release.yml"
+    }
+  ]
+}

package/skills/publish/schemas/publish.schema.json

@@ -0,0 +1,428 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://jenga.local/skills/publish/schemas/publish.schema.json",
+  "title": "Publish Skill Configuration",
+  "description": "Schema for project/configs/publish.json used by the /publish skill.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "defaults",
+    "targets"
+  ],
+  "properties": {
+    "version": {
+      "type": "integer",
+      "enum": [1]
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "history_file",
+        "mandatory_checks"
+      ],
+      "properties": {
+        "history_file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mandatory_checks": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/checkName"
+          }
+        },
+        "optional_checks": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "$ref": "#/definitions/checkName"
+          }
+        }
+      }
+    },
+    "targets": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/definitions/target"
+      }
+    }
+  },
+  "definitions": {
+    "checkName": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "envVarRef": {
+      "type": "string",
+      "pattern": "^\\$\\{?[A-Z][A-Z0-9_]*\\}?$"
+    },
+    "gateEntry": {
+      "oneOf": [
+        {
+          "$ref": "#/definitions/checkName"
+        },
+        {
+          "type": "object",
+          "additionalProperties": true,
+          "properties": {
+            "name": { "$ref": "#/definitions/checkName" },
+            "gate": { "$ref": "#/definitions/checkName" },
+            "type": { "$ref": "#/definitions/checkName" }
+          },
+          "anyOf": [
+            { "required": ["name"] },
+            { "required": ["gate"] },
+            { "required": ["type"] }
+          ]
+        }
+      ]
+    },
+    "gateList": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/gateEntry"
+      }
+    },
+    "checksObject": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pre": {
+          "$ref": "#/definitions/gateList"
+        },
+        "post": {
+          "$ref": "#/definitions/gateList"
+        }
+      }
+    },
+    "iosSecretMap": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "app_store_connect_api_key_id",
+        "app_store_connect_issuer_id",
+        "app_store_connect_private_key_path",
+        "code_sign_identity",
+        "provisioning_profile_uuid"
+      ],
+      "properties": {
+        "app_store_connect_api_key_id": { "$ref": "#/definitions/envVarRef" },
+        "app_store_connect_issuer_id": { "$ref": "#/definitions/envVarRef" },
+        "app_store_connect_private_key_path": { "$ref": "#/definitions/envVarRef" },
+        "code_sign_identity": { "$ref": "#/definitions/envVarRef" },
+        "provisioning_profile_uuid": { "$ref": "#/definitions/envVarRef" }
+      }
+    },
+    "npmSecretMap": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "NPM_TOKEN": { "$ref": "#/definitions/envVarRef" },
+        "NODE_AUTH_TOKEN": { "$ref": "#/definitions/envVarRef" }
+      },
+      "anyOf": [
+        { "required": ["NPM_TOKEN"] },
+        { "required": ["NODE_AUTH_TOKEN"] }
+      ]
+    },
+    "iosSettings": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scheme",
+        "configuration",
+        "archive_path",
+        "export_path",
+        "export_method",
+        "bundle_id",
+        "team_id",
+        "app_store_app_id"
+      ],
+      "properties": {
+        "project_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "workspace_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "scheme": {
+          "type": "string",
+          "minLength": 1
+        },
+        "configuration": {
+          "type": "string",
+          "minLength": 1
+        },
+        "archive_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "export_path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "export_method": {
+          "type": "string",
+          "enum": ["ad-hoc", "app-store"]
+        },
+        "bundle_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "team_id": {
+          "type": "string",
+          "pattern": "^[A-Z0-9]{6,}$"
+        },
+        "app_store_app_id": {
+          "type": "string",
+          "pattern": "^[0-9]+$"
+        },
+        "provider_short_name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "destination": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sdk": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "oneOf": [
+        { "required": ["project_path"] },
+        { "required": ["workspace_path"] }
+      ]
+    },
+    "npmSettings": {
+      "description": "Settings for an npm publish target. `package_name` and `access` are required; `registry` and `dist_tag` are optional with documented defaults.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "package_name",
+        "access"
+      ],
+      "properties": {
+        "package_name": {
+          "description": "The npm package name as it will appear in the registry. Supports scoped (`@scope/name`) and unscoped names. Must be lowercase, url-safe, and follow npm naming rules.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 214,
+          "pattern": "^(?:@[a-z0-9][a-z0-9._-]*\\/)?[a-z0-9][a-z0-9._-]*$"
+        },
+        "access": {
+          "description": "Registry access level. `public` publishes an openly-installable package; `restricted` publishes a private package (paid npm/GitHub Packages).",
+          "type": "string",
+          "enum": ["public", "restricted"]
+        },
+        "registry": {
+          "description": "Registry URL to publish to. Defaults to the public npm registry when omitted by the pipeline.",
+          "type": "string",
+          "format": "uri",
+          "minLength": 1,
+          "default": "https://registry.npmjs.org"
+        },
+        "dist_tag": {
+          "description": "npm dist-tag applied to this publish (e.g. `latest`, `next`, `beta`). Defaults to `latest` when omitted by the pipeline.",
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "default": "latest"
+        }
+      }
+    },
+    "dropletSecretMap": {
+      "description": "Secret name references for a droplet SSH target. Values are GitHub Actions secret names, not the secret values themselves.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "ssh_key_secret",
+        "known_hosts_secret"
+      ],
+      "properties": {
+        "ssh_key_secret": {
+          "description": "Name of the GitHub Actions secret that holds the SSH private key (e.g. DROPLET_SSH_KEY).",
+          "type": "string",
+          "minLength": 1
+        },
+        "known_hosts_secret": {
+          "description": "Name of the GitHub Actions secret that holds the known_hosts entry for the target host (e.g. DROPLET_KNOWN_HOSTS).",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "dropletSettings": {
+      "description": "Settings for a droplet (or any SSH-reachable Linux host) deploy target. Deployment is orchestrated via a generated GitHub Actions workflow that SSHes into the host.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "host",
+        "ssh_user",
+        "deploy_path",
+        "github_repo",
+        "deploy_branch",
+        "start_cmd"
+      ],
+      "properties": {
+        "host": {
+          "description": "IP address or FQDN of the target host.",
+          "type": "string",
+          "minLength": 1
+        },
+        "ssh_user": {
+          "description": "SSH username used to connect to the target host.",
+          "type": "string",
+          "minLength": 1
+        },
+        "ssh_port": {
+          "description": "SSH port on the target host. Defaults to 22 when omitted.",
+          "type": "integer",
+          "default": 22
+        },
+        "deploy_path": {
+          "description": "Absolute path on the remote host where the repository is checked out.",
+          "type": "string",
+          "minLength": 1
+        },
+        "github_repo": {
+          "description": "GitHub repository in owner/name format. Used to trigger the workflow via gh CLI.",
+          "type": "string",
+          "pattern": "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$"
+        },
+        "deploy_branch": {
+          "description": "Git branch to pull and deploy on the remote host.",
+          "type": "string",
+          "minLength": 1
+        },
+        "build_cmd": {
+          "description": "Optional build command to run on the remote host after pulling (e.g. npm run build). Omit or leave empty to skip the build step.",
+          "type": "string",
+          "minLength": 1
+        },
+        "start_cmd": {
+          "description": "Command to (re)start the service on the remote host after deploy (e.g. pm2 reload ecosystem.config.js, sudo systemctl restart myapp).",
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "target": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "type",
+        "platform",
+        "checks"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9-]*$"
+        },
+        "type": {
+          "type": "string",
+          "enum": ["mobile-ios", "npm", "droplet", "npm-ci"]
+        },
+        "platform": {
+          "type": "string",
+          "enum": ["ios-app-store", "npm-registry", "github-packages", "droplet-ssh", "npm-ci-oidc"]
+        },
+        "checks": {
+          "$ref": "#/definitions/checksObject"
+        },
+        "secrets": {
+          "type": "object"
+        },
+        "ios": {
+          "$ref": "#/definitions/iosSettings"
+        },
+        "npm": {
+          "$ref": "#/definitions/npmSettings"
+        },
+        "droplet": {
+          "$ref": "#/definitions/dropletSettings"
+        },
+        "github_repo": {
+          "description": "GitHub repository in owner/name format. Required for npm-ci targets; used to identify the repository that hosts the trusted-publisher workflow.",
+          "type": "string",
+          "pattern": "^[^/]+/[^/]+$"
+        },
+        "workflow_path": {
+          "description": "Path within the repository to the GitHub Actions workflow file that publishes to npm. Defaults to .github/workflows/npm-publish.yml.",
+          "type": "string",
+          "minLength": 1,
+          "default": ".github/workflows/npm-publish.yml"
+        },
+        "notes": {
+          "type": "string"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "type": { "const": "mobile-ios" } },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["ios", "secrets"],
+            "not": { "required": ["npm"] },
+            "properties": {
+              "platform": { "const": "ios-app-store" },
+              "secrets": { "$ref": "#/definitions/iosSecretMap" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "npm" } },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["npm", "secrets"],
+            "not": { "required": ["ios"] },
+            "properties": {
+              "platform": { "enum": ["npm-registry", "github-packages"] },
+              "secrets": { "$ref": "#/definitions/npmSecretMap" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "droplet" } },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["droplet", "secrets"],
+            "properties": {
+              "platform": { "const": "droplet-ssh" },
+              "secrets": { "$ref": "#/definitions/dropletSecretMap" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": { "type": { "const": "npm-ci" } },
+            "required": ["type"]
+          },
+          "then": {
+            "required": ["npm", "github_repo"],
+            "properties": {
+              "platform": { "const": "npm-ci-oidc" }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/skills/publish/scripts/check_target_config.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -u
+
+TARGET_NAME="${1:-}"
+CONFIG_PATH="${2:-}"
+EXIT_CONFIG_INVALID=4
+
+fail() {
+  printf 'target config check failed: %s\n' "$1" >&2
+  exit "$EXIT_CONFIG_INVALID"
+}
+
+[[ -n "$TARGET_NAME" ]] || fail "missing target name argument"
+[[ -n "$CONFIG_PATH" ]] || fail "missing publish.json path argument"
+[[ -f "$CONFIG_PATH" ]] || fail "publish.json not found at '$CONFIG_PATH'"
+command -v jq >/dev/null 2>&1 || fail "jq is required"
+jq -e . "$CONFIG_PATH" >/dev/null 2>&1 || fail "publish.json is not valid JSON"
+
+TARGET_JSON="$(jq -c --arg name "$TARGET_NAME" '.targets[]? | select(.name == $name)' "$CONFIG_PATH")"
+[[ -n "$TARGET_JSON" ]] || fail "target '$TARGET_NAME' was not found in '$CONFIG_PATH'"
+
+TARGET_TYPE="$(printf '%s\n' "$TARGET_JSON" | jq -r '.type // empty')"
+[[ -n "$TARGET_TYPE" ]] || fail "target '$TARGET_NAME' is missing a type"
+
+case "$TARGET_TYPE" in
+  mobile-ios)
+    MISSING="$(printf '%s\n' "$TARGET_JSON" | jq -r '
+      def non_empty($value):
+        ($value | type) == "string" and (($value | length) > 0);
+      def env_ref($value):
+        ($value | type) == "string" and ($value | test("^\\$\\{?[A-Z][A-Z0-9_]*\\}?$"));
+      def missing_string($path; $value):
+        if non_empty($value // "") then empty else $path end;
+      def missing_env_ref($path; $value):
+        if env_ref($value // "") then empty else $path end;
+      [
+        (if .platform == "ios-app-store" then empty else "platform" end),
+        (if (.checks | type) == "object" then empty else "checks" end),
+        (if (.checks.pre | type) == "array" then empty else "checks.pre" end),
+        (if (.checks.post | type) == "array" then empty else "checks.post" end),
+        (missing_env_ref("secrets.app_store_connect_api_key_id"; .secrets.app_store_connect_api_key_id)),
+        (missing_env_ref("secrets.app_store_connect_issuer_id"; .secrets.app_store_connect_issuer_id)),
+        (missing_env_ref("secrets.app_store_connect_private_key_path"; .secrets.app_store_connect_private_key_path)),
+        (missing_env_ref("secrets.code_sign_identity"; .secrets.code_sign_identity)),
+        (missing_env_ref("secrets.provisioning_profile_uuid"; .secrets.provisioning_profile_uuid)),
+        (missing_string("ios.scheme"; .ios.scheme)),
+        (missing_string("ios.configuration"; .ios.configuration)),
+        (missing_string("ios.archive_path"; .ios.archive_path)),
+        (missing_string("ios.export_path"; .ios.export_path)),
+        (if (.ios.export_method == "ad-hoc" or .ios.export_method == "app-store") then empty else "ios.export_method" end),
+        (missing_string("ios.bundle_id"; .ios.bundle_id)),
+        (if ((.ios.team_id // "") | type) == "string" and ((.ios.team_id // "") | test("^[A-Z0-9]{6,}$")) then empty else "ios.team_id" end),
+        (if ((.ios.app_store_app_id // "") | type) == "string" and ((.ios.app_store_app_id // "") | test("^[0-9]+$")) then empty else "ios.app_store_app_id" end),
+        (if ((.ios.project_path // "") | length) > 0 or ((.ios.workspace_path // "") | length) > 0 then empty else "ios.project_path|ios.workspace_path" end)
+      ]
+      | map(select(. != null and . != ""))
+      | .[]
+    ' 2>/dev/null || true)"
+    ;;
+  npm-ci)
+    MISSING="$(printf '%s\n' "$TARGET_JSON" | jq -r '
+      def non_empty($value):
+        ($value | type) == "string" and (($value | length) > 0);
+      def missing_string($path; $value):
+        if non_empty($value // "") then empty else $path end;
+      [
+        (missing_string("github_repo"; .github_repo)),
+        (if (.npm | type) == "object" then empty else "npm" end),
+        (missing_string("npm.package_name"; .npm.package_name)),
+        (if ((.npm.access? // "") == "public" or (.npm.access? // "") == "restricted") then empty else "npm.access" end)
+      ]
+      | map(select(. != null and . != ""))
+      | .[]
+    ' 2>/dev/null || true)"
+    ;;
+  *)
+    fail "unsupported target type '$TARGET_TYPE' for target '$TARGET_NAME'"
+    ;;
+esac
+
+if [[ -n "$MISSING" ]]; then
+  MESSAGE=""
+  while IFS= read -r item; do
+    [[ -n "$item" ]] || continue
+    if [[ -z "$MESSAGE" ]]; then
+      MESSAGE="$item"
+    else
+      MESSAGE="$MESSAGE, $item"
+    fi
+  done <<EOF_MISSING
+$MISSING
+EOF_MISSING
+  fail "target '$TARGET_NAME' is incomplete. Missing or invalid: $MESSAGE"
+fi
+
+exit 0