Test PR

.eslintignore

@@ -1,2 +1,3 @@
 packages/**/node_modules
+packages/**/dist
 packages/zcli-connectors/src/templates

.github/CONTRIBUTING.md

@@ -35,10 +35,10 @@ your PR is merged.
 
 ## Development Workflow
 
-Before you start, be sure [yarn](https://yarnpkg.com/en/) is installed
-on your system. After you clone this repo, run `yarn` to install
-dependencies needed for development. After installation, the following
-commands are available:
+Before you start, be sure [Node.js](https://nodejs.org/) v20.17.0 or higher is installed
+on your system. The project uses Yarn Berry (v4) which is managed via Corepack (included with Node.js).
+After you clone this repo, run `yarn` to install dependencies needed for development.
+After installation, the following commands are available:
 
 - `yarn dev` to run zcli
 - `yarn lint` to lint your typescript code using standardjs eslint config

.github/workflows/release.yml

@@ -0,0 +1,56 @@
+name: Release to npm
+
+# ⚠️ SAFETY MODE: This workflow is configured with --dry-run by default
+# ⚠️ No packages will actually be published until you remove the --dry-run flag
+# ⚠️ See line ~46 in the 'publish' job
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'lerna.json'
+      - 'packages/*/package.json'
+
+jobs:
+  check-release:
+    name: Check if release commit
+    runs-on: ubuntu-latest
+    outputs:
+      should-publish: ${{ steps.check.outputs.should-publish }}
+      version: ${{ steps.check.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Check if this is a release commit
+        id: check
+        run: |
+          COMMIT_MSG=$(git log -1 --pretty=%B)
+          if echo "$COMMIT_MSG" | grep -q "chore(release): publish"; then
+            echo "should-publish=true" >> $GITHUB_OUTPUT
+            VERSION=$(jq -r '.version' lerna.json)
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "✅ Release commit detected: $VERSION"
+          else
+            echo "should-publish=false" >> $GITHUB_OUTPUT
+            echo "ℹ️ Not a release commit, skipping publish"
+          fi
+
+  publish:
+    name: Publish packages to npm
+    needs: check-release
+    if: needs.check-release.outputs.should-publish == 'true'
+    # TODO: Update this path to your actual company reusable workflow location
+    # Example: zendesk/shared-workflows/.github/workflows/npm-publish.yml@main
+    uses: zendesk/REPLACE_WITH_ACTUAL_PATH/.github/workflows/npm-publish.yml@main
+    with:
+      node_version: '20.17.0'
+      # This command will be executed as: yarn workspaces foreach ... npm publish --otp $totp
+      # ⚠️ IMPORTANT: Remove --dry-run flag when ready for production publishing!
+      command: 'workspaces foreach --no-private --topological npm publish --dry-run --tolerate-republish'
+      commit: false
+    secrets:
+      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      NPM_TOTP_DEVICE: ${{ secrets.NPM_TOTP_DEVICE }}

.github/workflows/test.yml

@@ -18,24 +18,19 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: zendesk/checkout@v3
+      - name: Enable Corepack
+        run: corepack enable || true
       - name: Use Node.js
         uses: zendesk/setup-node@v4
         with:
           node-version: "${{ matrix.node-version }}"
-          cache: "yarn"
       - uses: zendesk/cache@v3
         with:
-          path: |
-            ./node_modules/
-            ./packages/zcli/node_modules/
-            ./packages/zcli-core/node_modules/
-            ./packages/zcli-apps/node_modules/
-            ./packages/zcli-themes/node_modules/
-          key: node-modules-${{ runner.os }}-${{ hashFiles('**/package.json') }}-${{ hashFiles('yarn.lock') }}
+          path: .yarn/cache
+          key: yarn-berry-${{ runner.os }}-${{ hashFiles('yarn.lock', '.yarnrc.yml') }}
           restore-keys: |
-            node-modules-${{ runner.os }}-${{ hashFiles('**/package.json') }}-
-            node-modules-${{ runner.os }}-
-      - run: yarn install
+            yarn-berry-${{ runner.os }}-
+      - run: yarn install --immutable
       - run: yarn lint
       - run: yarn test
       - run: yarn test:functional

.gitignore

@@ -7,3 +7,9 @@ packages/zcli-apps/tests/functional/mocks/*/tmp
 packages/**/dist
 .DS_Store
 .idea
+
+# Yarn Berry
+.yarn/*
+!.yarn/releases
+IMPLEMENTATION_GUIDE.md
+.tool-versions

.mocharc.json

@@ -10,5 +10,8 @@
     "watch-ignore": ["lib/vendor"],
     "require": ["ts-node/register"],
     "recursive": true,
-    "ignore": ["packages/zcli-connectors/src/templates/**"]
+    "ignore": [
+        "packages/zcli-connectors/src/templates/**",
+        "packages/zcli-connectors/src/**/*.test.ts"
+    ]
 }

.yarnrc.yml

@@ -0,0 +1,9 @@
+nodeLinker: node-modules
+
+enableGlobalCache: false
+
+supportedArchitectures:
+  os: ["linux", "darwin", "win32"]
+  cpu: ["x64", "arm64"]
+
+yarnPath: .yarn/releases/yarn-4.5.3.cjs

AUTOMATED_RELEASE_CHECKLIST.md

@@ -0,0 +1,175 @@
+# Automated Release Setup Checklist
+
+This checklist tracks the setup of the automated release process for ZCLI.
+
+## ✅ Completed Steps
+
+- [x] Migrate to Yarn Berry v4.5.3
+- [x] Add `build` script to root package.json
+- [x] Create `scripts/create-release-pr.sh`
+- [x] Create `.github/workflows/release.yml`
+- [x] Update `scripts/release.sh` with deprecation notice
+- [x] Create release process documentation
+
+## 🔧 TODO: Configuration Required
+
+### 1. Update Workflow Path (Required)
+
+**File:** `.github/workflows/release.yml`
+
+**Action:** Replace the placeholder with your actual company workflow path
+
+```yaml
+# Current (line ~40):
+uses: zendesk/REPLACE_WITH_ACTUAL_PATH/.github/workflows/npm-publish.yml@main
+
+# Replace with actual path (ask platform team):
+uses: zendesk/shared-workflows/.github/workflows/npm-publish.yml@main
+```
+
+**Who to ask:** Platform/DevOps team for the reusable workflow location
+
+---
+
+### 2. Configure GitHub Secrets (Required)
+
+**Location:** Repository Settings → Secrets and variables → Actions
+
+**Secrets to add:**
+
+#### `NPM_TOKEN`
+- **What:** npm authentication token
+- **How to get:**
+  1. Log into npm: https://www.npmjs.com/
+  2. Go to: Settings → Access Tokens
+  3. Generate New Token → Automation
+  4. Copy token (starts with `npm_`)
+  5. Add to GitHub secrets
+
+#### `NPM_TOTP_DEVICE`
+- **What:** TOTP secret for npm 2FA (base32 encoded)
+- **How to get:**
+  1. Go to npm 2FA settings
+  2. Disable 2FA (if enabled)
+  3. Re-enable 2FA
+  4. Click "Can't scan? Enter this code manually"
+  5. Copy the base32 secret (e.g., `JBSWY3DPEHPK3PXP`)
+  6. Add to GitHub secrets
+  7. Update your authenticator app with the new secret
+
+**Status:** ⬜ Not configured yet
+
+---
+
+### 3. Test with Dry Run (Recommended)
+
+The workflow is configured with `--dry-run` flag by default for safety.
+
+**Status:** ✅ Already configured (dry-run is the default)
+
+#### Step 3a: Create test release
+
+```bash
+# Create test commit with conventional commit message
+git checkout -b test-release-workflow
+echo "# Test" >> README.md
+git add README.md
+git commit -m "feat: test automated release workflow"
+git push origin test-release-workflow
+
+# Merge to master (or create PR and merge)
+# Then run:
+./scripts/create-release-pr.sh
+```
+
+#### Step 3b: Merge and verify
+
+1. Merge the release PR
+2. Go to Actions tab: https://github.com/zendesk/zcli/actions
+3. Watch "Release to npm" workflow run
+4. Verify it completes without errors
+5. Confirm nothing was published to npm (dry-run mode)
+
+**Status:** ⬜ Not tested yet
+
+---
+
+### 4. Enable Production Publishing (Required)
+
+After successful dry-run test, enable real publishing:
+
+**File:** `.github/workflows/release.yml`
+
+**Remove the `--dry-run` flag:**
+```yaml
+# Change from:
+command: 'workspaces foreach --no-private --topological npm publish --dry-run --tolerate-republish'
+
+# To:
+command: 'workspaces foreach --no-private --topological npm publish --tolerate-republish'
+#                                                        ^^^^^^^^^^^ Remove this
+```
+
+**Status:** ⬜ Still in dry-run mode
+
+---
+
+### 5. Update Team Documentation (Optional)
+
+- [ ] Update internal wiki/confluence with new process
+- [ ] Notify team about the new release workflow
+- [ ] Add link to [docs/RELEASING.md](./docs/RELEASING.md) in onboarding docs
+
+---
+
+## 📚 Documentation
+
+| Document | Purpose |
+|----------|---------|
+| [docs/SETUP_RELEASE_WORKFLOW.md](./docs/SETUP_RELEASE_WORKFLOW.md) | Detailed setup instructions |
+| [docs/RELEASING.md](./docs/RELEASING.md) | How to create releases |
+| [scripts/create-release-pr.sh](./scripts/create-release-pr.sh) | Release PR creation script |
+| [.github/workflows/release.yml](./.github/workflows/release.yml) | GitHub Actions workflow |
+
+---
+
+## 🚀 Quick Start (After Setup)
+
+Once everything above is configured:
+
+```bash
+# 1. Run the release script
+./scripts/create-release-pr.sh
+
+# 2. Open the PR URL provided
+
+# 3. Review and merge
+
+# 4. Automated publishing happens!
+```
+
+---
+
+## ❓ Getting Help
+
+**Questions about:**
+- Reusable workflow path → Ask platform/DevOps team
+- npm credentials → Ask maintainer with npm access
+- Process/bugs → Open issue in this repo
+
+**Common issues:** See [Troubleshooting section](./docs/SETUP_RELEASE_WORKFLOW.md#troubleshooting) in setup docs
+
+---
+
+## ✅ Ready to Go Live?
+
+Check that all items above are completed:
+
+- [ ] Workflow path updated
+- [ ] GitHub secrets configured
+- [ ] Dry-run test passed
+- [ ] Team notified
+
+Once all checked, you're ready to create your first automated release! 🎉
+
+⚠️ **Remember:** The workflow is in dry-run mode by default. After testing, don't forget to remove the `--dry-run` flag to enable real publishing!