@jenga-ai/agent 1.2.4 → 2.0.0

package/skills/publish/adapters/npm.md

@@ -109,6 +109,24 @@ A successful run produces:
 - A local (and optionally pushed) git tag `v<version>` matching the published `version`
 - A history row appended to `project/logs/publish-history.json`
 
+## Staged Publishing
+
+Before a live `deploy`, this target type also supports **staged publishing**
+via `/publish stage` — npm's own pre-publish staging area, which lets a
+release be smoke-tested from the exact tarball that would ship before it
+becomes visible on the registry. See `skills/publish/SKILL.md`'s
+`### /publish stage` section for the full command reference; summary here:
+
+- `bash skills/publish/scripts/npm_stage_pipeline.sh <target> <path-to-publish.json> [--dry-run] [--non-interactive] [--otp <otp>]` runs validate → gates → pack → stage → capture → ledger and writes a `staged` ledger entry.
+- `bash skills/publish/scripts/npm_stage_inspect.sh test <stage-id>` installs the staged tarball into an isolated scratch directory and smoke-tests it, writing a `stage_tested` ledger entry.
+- `bash skills/publish/scripts/npm_stage_inspect.sh approve <stage-id>` requires an npm 2FA one-time password and refuses without a passing `test` on record unless `--force <reason>` is given.
+- `bash skills/publish/scripts/npm_stage_inspect.sh reject <stage-id>` discards the staged version.
+
+Same registry-existence precondition as a normal `npm` publish: staged
+publishing only applies to a package that has already had at least one
+non-staged publish (`validate_npm_stage_env.sh` checks this up front, exit
+`4` if not).
+
 ## Post-deploy manual steps
 
 After a successful publish, the deploy flow must print:

package/skills/publish/assets/ci-contract.md

@@ -71,6 +71,33 @@ These inputs remain optional in non-interactive mode:
 | `3` | Deploy failure | Used by the iOS adapter pipeline for build/export/upload failures |
 | `4` | Config or environment invalid | Implemented by validation scripts |
 
+## Staged publishing (`/publish stage`) — exit codes and ledger states
+
+`/publish stage` (npm/npm-ci only) has its own exit-code contract, separate
+from the deploy contract above:
+
+| Code | Meaning |
+|---|---|
+| `0` | Success (staged, or `--dry-run`/`--help` completed cleanly) |
+| `1` | User declined the pack confirmation prompt (or no tty was available) — `npm_stage_pipeline.sh` only |
+| `2` | A mandatory pre-deploy gate failed; nothing was staged — `npm_stage_pipeline.sh` only |
+| `3` | The underlying `npm stage <sub>` command failed, the tarball install failed, or the smoke test failed (`npm_stage_inspect.sh`); or `npm stage publish`/stage-id capture failed (`npm_stage_pipeline.sh`) |
+| `4` | Config/environment validation failure (`validate_npm_stage_env.sh`, or bad args), or (`npm_stage_inspect.sh` only) a usage error, an unknown sub-command, or the `approve` test interlock refusing without a passing test on record and no `--force <reason>` |
+
+`test` (via `npm_stage_inspect.sh`) surfaces a smoke-test failure as a
+non-zero exit — code `3` — distinct from a usage error (`4`).
+
+The publish ledger (`project/logs/publish-history.json`) gains four new
+`platform_state` values alongside the existing `uploaded`/`partial`/
+`dry-run`/`failed`:
+
+| `platform_state` | Written by | Meaning |
+|---|---|---|
+| `staged` | `npm_stage_pipeline.sh` | Version staged to npm's staged-publishing area; not yet visible on the registry |
+| `stage_tested` | `npm_stage_inspect.sh test` | The staged tarball was installed in isolation and smoke-tested; ledger row records `pass`/`fail` |
+| `approved` | `npm_stage_inspect.sh approve` | The staged version was approved (2FA-gated) and is now published |
+| `rejected` | `npm_stage_inspect.sh reject` | The staged version was discarded and will never be published |
+
 ## Precedence rules
 
 1. Command-line flags win over environment variables.

package/skills/publish/assets/publish.example.json

@@ -80,6 +80,33 @@
         "provider_short_name": "exampleco"
       },
       "notes": "Production upload example using App Store export mode."
+    },
+    {
+      "name": "npm-ci-example",
+      "type": "npm-ci",
+      "platform": "npm-ci-oidc",
+      "github_repo": "exampleco/example-package",
+      "workflow_path": ".github/workflows/npm-publish.yml",
+      "checks": {
+        "pre": [
+          "lint",
+          "type-check"
+        ],
+        "post": [
+          "smoke-test"
+        ]
+      },
+      "npm": {
+        "package_name": "@exampleco/example-package",
+        "access": "public",
+        "registry": "https://registry.npmjs.org",
+        "dist_tag": "latest",
+        "stage": {
+          "smoke_cmd": "npm run smoke-test",
+          "require_test_before_approve": true
+        }
+      },
+      "notes": "Scaffold example only. Demonstrates the optional npm.stage block used by '/publish stage'. Replace package_name and github_repo with your real values."
     }
   ]
 }

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

@@ -237,6 +237,26 @@
           "minLength": 1,
           "pattern": "^[a-z0-9][a-z0-9._-]*$",
           "default": "latest"
+        },
+        "stage": {
+          "$ref": "#/definitions/npmStageSettings"
+        }
+      }
+    },
+    "npmStageSettings": {
+      "description": "Optional settings for `/publish stage` on an npm or npm-ci target. Absent entirely on targets that don't use staged publishing.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "smoke_cmd": {
+          "description": "Command that `stage test` runs against the installed staged tarball. When absent, `stage test` falls back to a documented default.",
+          "type": "string",
+          "minLength": 1
+        },
+        "require_test_before_approve": {
+          "description": "When true, `stage approve` refuses without a recorded successful test for that stage id. Defaults to true.",
+          "type": "boolean",
+          "default": true
         }
       }
     },

package/skills/publish/scripts/npm_ci_pipeline.sh

@@ -160,13 +160,23 @@ WORKFLOW_YAML="$(cat <<EOF
 name: "Publish — ${PACKAGE_NAME}"
 on:
   workflow_dispatch:
+    inputs:
+      mode:
+        description: "publish (default) or stage — dispatched by npm_stage_pipeline.sh with mode=stage for /publish stage"
+        required: false
+        default: publish
+        type: choice
+        options:
+          - publish
+          - stage
 
 permissions:
   id-token: write
-  contents: read
+  contents: write
 
 jobs:
   publish:
+    if: \${{ github.event.inputs.mode == 'publish' || github.event.inputs.mode == '' }}
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -183,6 +193,45 @@ jobs:
 
       - name: Publish to npm
         run: npm publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
+
+      - name: Tag prod release and remove stage tag
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag "v\${VERSION}"
+          git push origin "v\${VERSION}"
+          git tag -d "v\${VERSION}-stage" 2>/dev/null || true
+          git push origin ":refs/tags/v\${VERSION}-stage" 2>/dev/null || true
+
+  stage:
+    if: \${{ github.event.inputs.mode == 'stage' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Stage to npm
+        run: npm stage publish --provenance --access ${NPM_ACCESS} --tag ${DIST_TAG}
+
+      - name: Tag stage release
+        if: success()
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          VERSION="\$(node -p "require('./package.json').version")"
+          git tag -f "v\${VERSION}-stage"
+          git push origin "v\${VERSION}-stage" --force
 EOF
 )"