@jenga-ai/agent 1.0.0

package/skills/publish/wizards/droplet.md

@@ -0,0 +1,275 @@
+# Droplet setup wizard
+
+Use this template to collect the values required for a `droplet` publish target.
+Each section maps directly to a field in `publish.json`. The adapter is generic —
+it works with any SSH-reachable Linux host, not just DigitalOcean droplets.
+
+Before running the prompts, check whether `publish.json` already contains a target
+whose `type` is `droplet`. If one exists, ask the user whether to **overwrite**
+the existing target or **update** individual fields — do not silently replace it.
+
+After collecting answers, write the target block to `publish.json` (create the
+file from the base scaffold if it does not exist), validate the config, and write
+`project/instructions/E22_S07_INSTRUCTIONS.md` listing the required GitHub secrets.
+See the "Post-collection actions" section at the bottom for the full write sequence.
+
+---
+
+## Question: host
+
+Maps to: `targets[].droplet.host`
+
+Enter the IP address or fully qualified domain name (FQDN) of the target host.
+This is the address GitHub Actions will SSH into when deploying.
+
+## Expected format:
+
+A valid IPv4 address or hostname (e.g. `192.168.1.10`, `deploy.example.com`).
+
+---
+
+## Question: ssh_user
+
+Maps to: `targets[].droplet.ssh_user`
+
+Enter the SSH username used to connect to the target host. This user must have
+read/write access to the `deploy_path` directory and permission to execute
+`build_cmd` and `start_cmd`.
+
+## Expected format:
+
+A valid Unix username (e.g. `deploy`, `ubuntu`, `root`).
+
+---
+
+## Question: ssh_port
+
+Maps to: `targets[].droplet.ssh_port`
+
+Enter the SSH port on the target host. Press Enter to accept the default (22).
+
+## Expected format:
+
+An integer between 1 and 65535. Press Enter to accept the default (`22`).
+
+---
+
+## Question: deploy_path
+
+Maps to: `targets[].droplet.deploy_path`
+
+Enter the absolute path on the remote host where the repository is checked out.
+This directory must already exist and contain a valid git working tree before the
+first deploy (see First-run bootstrap in post-setup manual steps).
+
+## Expected format:
+
+An absolute Unix path (e.g. `/var/www/myapp`, `/home/deploy/myapp`).
+
+---
+
+## Question: github_repo
+
+Maps to: `targets[].droplet.github_repo`
+
+Enter the GitHub repository that hosts this project, in `owner/name` format.
+The adapter uses this value with `gh workflow run` to trigger the generated
+workflow.
+
+## Expected format:
+
+`owner/name` (e.g. `acme-corp/my-app`). Must match the pattern
+`^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$`.
+
+---
+
+## Question: deploy_branch
+
+Maps to: `targets[].droplet.deploy_branch`
+
+Enter the git branch to pull on the remote host during deploy. The generated
+GitHub Actions workflow will run `git pull origin <deploy_branch>` on the host.
+
+## Expected format:
+
+A git branch name (e.g. `main`, `production`). Press Enter to accept the
+default (`main`).
+
+---
+
+## Question: build_cmd
+
+Maps to: `targets[].droplet.build_cmd`
+
+Enter the build command to run on the remote host after pulling (e.g.
+`npm run build`, `make build`, `pip install -r requirements.txt`). Leave blank
+to skip the build step — the `build_cmd` field is optional.
+
+## Expected format:
+
+Any valid shell command string, or press Enter to skip.
+
+---
+
+## Question: start_cmd
+
+Maps to: `targets[].droplet.start_cmd`
+
+Enter the command to (re)start the service on the remote host after deploy.
+The adapter makes no assumptions about your runtime — supply whatever command
+your deployment uses. This field is required.
+
+## Expected format:
+
+A valid shell command (e.g. `pm2 reload ecosystem.config.js`,
+`sudo systemctl restart myapp`, `./scripts/restart.sh`).
+
+---
+
+## Question: ssh_key_secret
+
+Maps to: `targets[].secrets.ssh_key_secret`
+
+Enter the **name** of the GitHub Actions secret that holds the SSH private key
+used to authenticate with the target host. Do not enter the key value itself —
+only the secret name. The adapter reads this name and injects
+`${{ secrets.<ssh_key_secret> }}` into the generated workflow.
+
+## Expected format:
+
+A GitHub Actions secret name (e.g. `DROPLET_SSH_KEY`). Uppercase, underscores
+allowed.
+
+---
+
+## Question: known_hosts_secret
+
+Maps to: `targets[].secrets.known_hosts_secret`
+
+Enter the **name** of the GitHub Actions secret that holds the known_hosts
+entry for the target host. This prevents MITM attacks during the SSH connection
+from GitHub Actions. Generate the value with `ssh-keyscan <host>`.
+
+## Expected format:
+
+A GitHub Actions secret name (e.g. `DROPLET_KNOWN_HOSTS`).
+
+---
+
+## Secrets Guide
+
+The following secrets must be added to the GitHub repository before the first
+deploy. Navigate to **Settings → Secrets and variables → Actions → New
+repository secret** in the GitHub UI, or use the `gh` CLI as shown below.
+
+| Secret name           | What it holds                                                    |
+|-----------------------|------------------------------------------------------------------|
+| `DROPLET_SSH_KEY`     | Contents of the SSH private key file (e.g. `~/.ssh/id_deploy`)  |
+| `DROPLET_SSH_HOST`    | IP address or FQDN of the target host                            |
+| `DROPLET_SSH_USER`    | SSH username on the target host                                  |
+| `DROPLET_SSH_PORT`    | SSH port (typically `22`)                                        |
+| `DROPLET_KNOWN_HOSTS` | Output of `ssh-keyscan <host>` for the target host               |
+
+### How to add secrets via `gh` CLI
+
+```bash
+# Private key — reads from file
+gh secret set DROPLET_SSH_KEY < ~/.ssh/id_deploy
+
+# Host and connection details
+gh secret set DROPLET_SSH_HOST --body "your.host.ip.or.fqdn"
+gh secret set DROPLET_SSH_USER --body "your-ssh-user"
+gh secret set DROPLET_SSH_PORT --body "22"
+
+# Known hosts — generate with ssh-keyscan
+ssh-keyscan your.host.ip.or.fqdn | gh secret set DROPLET_KNOWN_HOSTS
+```
+
+### Via GitHub UI
+
+1. Go to your repository on GitHub.
+2. Navigate to **Settings** → **Secrets and variables** → **Actions**.
+3. Click **New repository secret** for each of the five secrets listed above.
+4. Paste the value and save.
+
+---
+
+## Post-setup manual steps
+
+After the wizard completes, the following steps must be performed manually:
+
+1. **Add the listed secrets to the GitHub repo before the first deploy.**
+   The workflow will fail immediately if any of the five secrets above are
+   missing. Verify them at Settings → Secrets and variables → Actions.
+
+2. **Bootstrap the deploy path on the host before the first deploy.**
+   The adapter assumes the deploy path already contains a git working tree.
+   SSH into the host and run:
+   ```bash
+   git clone <your-repo-url> <deploy_path>
+   cd <deploy_path>
+   # Install any runtime dependencies (e.g. npm install, pip install)
+   ```
+
+3. **Push a commit to the deploy branch to trigger the first deploy.**
+   After running `/publish deploy --target <name>`, the generated workflow will
+   be committed and can be triggered via `gh workflow run` or by pushing to the
+   configured deploy branch.
+
+---
+
+## Post-collection actions
+
+Once all answers have been collected, perform the following steps in order:
+
+1. **Load or scaffold `publish.json`.** If the file does not exist at the
+   project root, create it from the base scaffold with `version: 1`,
+   populated `defaults`, and an empty `targets` array. If it does exist,
+   parse and preserve every unrelated field.
+
+2. **Check for an existing droplet target.** Scan `targets[]` for any entry
+   with `"type": "droplet"`. If one exists, ask the user:
+   - **overwrite** — replace the entire target block with the wizard output
+   - **update** — merge the wizard answers into the existing target
+     field-by-field, keeping any user-added fields (e.g. custom `checks`)
+   If none exists, append a new target block.
+
+3. **Write the target block.** Emit it in the exact shape below (omit
+   `build_cmd` if the user left it blank):
+
+   ```json
+   {
+     "name": "my-droplet",
+     "type": "droplet",
+     "platform": "droplet-ssh",
+     "checks": { "pre": ["build", "test"], "post": [] },
+     "secrets": {
+       "ssh_key_secret": "DROPLET_SSH_KEY",
+       "known_hosts_secret": "DROPLET_KNOWN_HOSTS"
+     },
+     "droplet": {
+       "host": "<answer>",
+       "ssh_user": "<answer>",
+       "ssh_port": 22,
+       "deploy_path": "<answer>",
+       "github_repo": "<answer>",
+       "deploy_branch": "<answer>",
+       "build_cmd": "<answer or omit if blank>",
+       "start_cmd": "<answer>"
+     }
+   }
+   ```
+
+4. **Validate against the schema.** Run
+   `bash skills/publish/scripts/validate_config.sh <path-to-publish.json>`
+   before saving. If validation fails, report the error and abort — do not
+   write a broken `publish.json`.
+
+5. **Write the instructions file.** Create
+   `project/instructions/E22_S07_INSTRUCTIONS.md` listing the five required
+   GitHub secrets and how to add them. Create the `project/instructions/`
+   directory if it does not exist.
+
+6. **Report to the user.** Print a short summary listing (a) the target block
+   written, (b) the path to the instructions file, and (c) the five GitHub
+   secrets that must be configured before the first deploy.

package/skills/publish/wizards/mobile-ios.md

@@ -0,0 +1,157 @@
+# mobile-ios setup wizard
+
+Use this template to collect the values required for a `mobile-ios` publish target.
+Each section maps directly to a field in `publish.json`.
+
+## Question: bundle_id
+
+Maps to: `targets[].ios.bundle_id`
+
+Enter the iOS bundle identifier for the app you want to publish.
+This should match the bundle identifier configured in Xcode and Apple Developer.
+
+## Expected format:
+
+Reverse-DNS identifier such as `com.example.myapp`.
+
+## Question: team_id
+
+Maps to: `targets[].ios.team_id`
+
+Enter the Apple Developer Team ID that owns the signing assets for this app.
+
+## Expected format:
+
+Uppercase alphanumeric team identifier such as `ABCDE12345`.
+
+## Question: scheme
+
+Maps to: `targets[].ios.scheme`
+
+Enter the Xcode scheme that should be built for publish flows.
+
+## Expected format:
+
+A non-empty scheme name such as `MyApp` or `MyAppRelease`.
+
+## Question: configuration
+
+Maps to: `targets[].ios.configuration`
+
+Enter the Xcode build configuration for the publish flow.
+
+## Expected format:
+
+Usually `Release`. Press Enter to accept the default.
+
+## Question: archive_path
+
+Maps to: `targets[].ios.archive_path`
+
+Enter the repo-relative path where the Xcode archive should be written.
+
+## Expected format:
+
+A non-empty path such as `build/ios/staging/MyApp.xcarchive`.
+
+## Question: export_path
+
+Maps to: `targets[].ios.export_path`
+
+Enter the repo-relative path where exported build artifacts should be written.
+
+## Expected format:
+
+A non-empty path such as `build/ios/staging/export`.
+
+## Question: export_method
+
+Maps to: `targets[].ios.export_method`
+
+Choose the export method used for packaging the archive.
+
+## Expected format:
+
+One of: `ad-hoc`, `app-store`.
+
+## Question: app_store_app_id
+
+Maps to: `targets[].ios.app_store_app_id`
+
+Enter the numeric App Store Connect app identifier for this target.
+
+## Expected format:
+
+Digits only such as `1234567890`.
+
+## Question: project_or_workspace_path
+
+Maps to: `targets[].ios.project_path` or `targets[].ios.workspace_path`
+
+Enter the repo-relative Xcode project or workspace path used for builds.
+
+## Expected format:
+
+A path ending in `.xcodeproj` or `.xcworkspace`.
+
+## Question: provider_short_name
+
+Maps to: `targets[].ios.provider_short_name`
+
+Optionally enter the App Store Connect provider short name used by some upload flows.
+Leave blank if not needed.
+
+## Expected format:
+
+Optional short string such as `exampleco`.
+
+## Question: api_key_id_env_var
+
+Maps to: `targets[].secrets.app_store_connect_api_key_id`
+
+Enter the environment-variable name that will supply the App Store Connect API key identifier.
+See `skills/publish/assets/secrets-guide.md` before answering.
+
+## Expected format:
+
+Uppercase environment-variable name such as `APP_STORE_CONNECT_API_KEY_ID`.
+
+## Question: issuer_id_env_var
+
+Maps to: `targets[].secrets.app_store_connect_issuer_id`
+
+Enter the environment-variable name that will supply the App Store Connect issuer identifier.
+
+## Expected format:
+
+Uppercase environment-variable name such as `APP_STORE_CONNECT_ISSUER_ID`.
+
+## Question: private_key_path_env_var
+
+Maps to: `targets[].secrets.app_store_connect_private_key_path`
+
+Enter the environment-variable name that will supply the filesystem path to the App Store Connect private key.
+
+## Expected format:
+
+Uppercase environment-variable name such as `APP_STORE_CONNECT_PRIVATE_KEY_PATH`.
+
+## Question: code_sign_identity_env_var
+
+Maps to: `targets[].secrets.code_sign_identity`
+
+Enter the environment-variable name that will supply the iOS code-sign identity.
+
+## Expected format:
+
+Uppercase environment-variable name such as `CODE_SIGN_IDENTITY`.
+
+## Question: provisioning_profile_uuid_env_var
+
+Maps to: `targets[].secrets.provisioning_profile_uuid`
+
+Enter the environment-variable name that will supply the provisioning profile UUID reference.
+
+## Expected format:
+
+Uppercase environment-variable name such as `PROVISIONING_PROFILE_UUID`.

package/skills/publish/wizards/npm-ci.md

@@ -0,0 +1,240 @@
+# npm-ci setup wizard
+
+Use this template to collect the values required for an `npm-ci` publish target.
+Each section maps directly to a field in `publish.json`. Unlike the `npm` target
+type, `npm-ci` publishes via GitHub Actions OIDC (Trusted Publishers) — no
+`NPM_TOKEN` is stored anywhere. All authorisation is handled through the
+npmjs.com Trusted Publisher link between the package and the GitHub repository.
+
+Before running the prompts, load the project's `package.json` (if present) so
+`name` can be offered as the default for `package_name`. If `publish.json`
+already contains a target whose `type` is `npm-ci`, ask the user whether to
+**overwrite** the existing target or **update** individual fields — do not
+silently replace it.
+
+After collecting answers, write the target block to `publish.json` (create the
+file from the base scaffold if it does not exist). No instructions file is
+generated for this target type — there is no secret to configure. See the
+"Post-collection actions" section at the bottom for the full write sequence.
+
+## Prerequisites
+
+Before running this wizard, confirm that all of the following are in place:
+
+- **`gh` CLI installed and authenticated**: run `gh auth status` to verify.
+  If not authenticated, run `gh auth login` first.
+- **GitHub Actions enabled** on the target repository. Actions must be enabled
+  under the repository's Settings → Actions → General page.
+- **The package must already exist on npmjs.com**, or be publishable under
+  your npm account. A brand-new package name is created on the first successful
+  publish if your account has permission to publish under that name or scope.
+
+## One-time npmjs.com Trusted Publisher setup
+
+Complete these steps manually in a browser **before** running `/publish deploy`
+against this target for the first time. The adapter cannot establish this link
+automatically — it is a one-time browser-based setup on the npmjs.com website.
+
+1. Sign in to https://www.npmjs.com with the account that owns (or is a
+   maintainer of) the package.
+2. Navigate to your package page. If the package does not exist yet, create it
+   first (publish a placeholder version locally before configuring Trusted
+   Publishers, or ensure your account has permission to publish under the
+   chosen name or scope on first push).
+3. Go to **Settings** → **Publishing** → **Trusted Publishers**.
+4. Click **Add publisher**.
+5. Select **GitHub Actions** as the publisher type.
+6. Enter the following values:
+   - **Owner/repository**: your GitHub `owner/repo`
+     (e.g. `acme-org/my-package`)
+   - **Workflow file path**: the path to the workflow file that will publish
+     (e.g. `.github/workflows/npm-publish.yml`)
+7. Click **Save**.
+
+**Important trade-off**: once Trusted Publishers is configured on a package,
+npmjs.com will **only** accept publishes originating from the linked workflow.
+Local `npm publish` commands authenticated with an `NPM_TOKEN` will be rejected
+for that package. If you need to publish locally in an emergency, you must
+remove or disable the Trusted Publisher link on npmjs.com before using a token.
+Plan accordingly before enabling this feature on a production package.
+
+## Question: package_name
+
+Maps to: `targets[].npm.package_name`
+
+Enter the npm package name as it should appear in the registry.
+If a `package.json` exists at the project root, offer its `name` field as the
+default. Supports scoped names such as `@scope/name`.
+
+## Expected format:
+
+Lowercase, url-safe name matching `^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$`
+(e.g. `jenga-agent`, `@my-org/utils`). Max 214 characters.
+
+## Question: access
+
+Maps to: `targets[].npm.access`
+
+Choose the registry access level for this package.
+`public` publishes an openly-installable package. `restricted` publishes a
+private package (requires a paid npm plan or a private registry such as
+GitHub Packages).
+
+## Expected format:
+
+One of: `public`, `restricted`. Press Enter to accept the default (`public`).
+
+## Question: dist_tag
+
+Maps to: `targets[].npm.dist_tag`
+
+Enter the npm dist-tag applied to this publish. `latest` is the default
+install tag; use tags like `next` or `beta` for pre-releases so that
+`npm install <pkg>` continues to resolve to the current stable version.
+
+## Expected format:
+
+Lowercase tag matching `^[a-z0-9][a-z0-9._-]*$` (e.g. `latest`, `next`,
+`beta`). Press Enter to accept the default (`latest`).
+
+## Question: registry
+
+Maps to: `targets[].npm.registry`
+
+Enter the registry URL to publish to.
+For the public npm registry, accept the default. For GitHub Packages, use
+`https://npm.pkg.github.com`. For a private/internal registry, use the URL
+provided by your registry operator.
+
+## Expected format:
+
+An absolute `https://` URL (e.g. `https://registry.npmjs.org`,
+`https://npm.pkg.github.com`). Press Enter to accept the default
+(`https://registry.npmjs.org`).
+
+## Question: github_repo
+
+Maps to: `targets[].github_repo`
+
+Enter the GitHub repository that will run the publish workflow. This value is
+used by the adapter to generate and trigger the GitHub Actions workflow via
+`gh workflow run`. It must match the repository where the Trusted Publisher
+link was established on npmjs.com.
+
+## Expected format:
+
+`owner/name` format matching `^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$`
+(e.g. `acme-org/my-package`). This field is required — there is no default.
+
+## Question: workflow_path
+
+Maps to: `targets[].workflow_path`
+
+Enter the path to the GitHub Actions workflow file the adapter will generate
+and trigger. This must match the workflow file path entered in the npmjs.com
+Trusted Publisher configuration above. If the file already exists in the
+repository, the adapter will overwrite it only if its content has changed.
+
+## Expected format:
+
+A relative path starting with `.github/workflows/` and ending in `.yml` or
+`.yaml` (e.g. `.github/workflows/npm-publish.yml`). Press Enter to accept the
+default (`.github/workflows/npm-publish.yml`).
+
+## publish.json snippet
+
+A complete, valid example target block for the `npm-ci` type. Note that there
+is no `secrets` block — this adapter uses OIDC and requires no stored tokens:
+
+```json
+{
+  "name": "npm-ci-my-package",
+  "type": "npm-ci",
+  "platform": "npm-registry",
+  "github_repo": "acme-org/my-package",
+  "workflow_path": ".github/workflows/npm-publish.yml",
+  "checks": {
+    "pre": ["lint", "type-check"],
+    "post": ["smoke-test"]
+  },
+  "npm": {
+    "package_name": "my-package",
+    "access": "public",
+    "registry": "https://registry.npmjs.org",
+    "dist_tag": "latest"
+  }
+}
+```
+
+## Post-collection actions
+
+Once all six answers have been collected, perform the following steps in order:
+
+1. **Load or scaffold `publish.json`.** If the file does not exist at the
+   project root, create it from the base scaffold with `version: 1`,
+   populated `defaults`, and an empty `targets` array. If it does exist,
+   parse and preserve every unrelated field.
+2. **Check for an existing `npm-ci` target.** Scan `targets[]` for any entry
+   with `"type": "npm-ci"`. If one exists, ask the user:
+   - **overwrite** — replace the entire target block with the wizard output
+   - **update** — merge the wizard answers into the existing target
+     field-by-field, keeping any user-added fields (e.g. custom `checks`
+     or `notes`) intact.
+   If none exists, append a new target block.
+3. **Write the target block.** Emit it in the exact shape shown in the
+   "publish.json snippet" section above — no `secrets` block:
+
+   ```json
+   {
+     "name": "npm-ci-<package-slug>",
+     "type": "npm-ci",
+     "platform": "npm-registry",
+     "github_repo": "<answer>",
+     "workflow_path": "<answer>",
+     "checks": {
+       "pre": ["lint", "type-check"],
+       "post": ["smoke-test"]
+     },
+     "npm": {
+       "package_name": "<answer>",
+       "access": "<answer>",
+       "registry": "<answer>",
+       "dist_tag": "<answer>"
+     }
+   }
+   ```
+
+   Notes on shape:
+   - `name` is derived from the package name (slugified, lowercased, prefixed
+     with `npm-ci-`). If a collision exists, suffix with `-2`, `-3`, etc.
+   - `platform` is `npm-registry` for `https://registry.npmjs.org`. If the
+     user supplied `https://npm.pkg.github.com`, set `platform` to
+     `github-packages` instead.
+   - Do not include a `secrets` block — this adapter uses OIDC and no token
+     is required.
+4. **Validate against the schema.** Run
+   `skills/publish/scripts/validate_config.sh` before saving. If validation
+   fails, report the error and abort — do not write a broken `publish.json`.
+5. **Report to the user.** Print a short summary confirming (a) the target
+   block written, (b) the `github_repo` value, and (c) the `workflow_path`
+   value. Remind the user to complete the one-time npmjs.com Trusted Publisher
+   setup (described above) before running `/publish deploy` for the first time.
+6. **No instructions file is needed.** Unlike the `npm` target type, `npm-ci`
+   has no secret to configure. The OIDC trust is established entirely through
+   the npmjs.com Trusted Publisher link and the GitHub Actions workflow — both
+   of which are documented in this wizard.
+
+## Post-setup verification
+
+After completing the wizard and the one-time Trusted Publisher setup:
+
+1. Run `/publish deploy --target <name> --dry-run` to confirm the workflow YAML
+   is generated correctly. The adapter will print the rendered workflow YAML to
+   stdout without writing any file or triggering a run.
+2. Review the printed YAML to ensure it matches the expected `npm-publish.yml`
+   structure: verify that `permissions.id-token: write` is present and that the
+   publish step runs `npm publish --provenance`.
+3. Run `/publish deploy --target <name>` (without `--dry-run`) to trigger the
+   first CI publish. The adapter will commit the workflow file to the repository
+   and trigger a GitHub Actions run. Open the printed run URL to monitor the
+   job in GitHub Actions.