Feat/add pkg

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets).
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md).

.changeset/config.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.3/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "compose-documentation"
+  ]
+}

.github/pull_request_template.md

@@ -24,6 +24,8 @@ Before submitting this PR, please ensure:
 
 - [ ] **Documentation updated** - If applicable, update relevant documentation
 
+- [ ] **Changesets** — If this PR changes publishable packages (`src/`, `cli/`), [changeset-bot](https://github.com/apps/changeset-bot) will comment if a release note might be needed. You can add one when convenient or defer to maintainers.
+
 Make sure to follow the [contributing](https://compose.diamonds/docs/contribution/how-to-contribute) guidelines.
 
 ## Additional Notes

.github/workflows/publish.yml

@@ -0,0 +1,117 @@
+name: Publish
+
+on:
+  workflow_run:
+    workflows: ["Release"]
+    types:
+      - completed
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    if: ${{ github.event.workflow_run.conclusion == 'success' && github.event.workflow_run.head_branch == 'main' }}
+    runs-on: ubuntu-latest
+    environment: npm-publish
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          registry-url: https://registry.npmjs.org
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Skip if pending changesets remain
+        id: pending
+        run: |
+          set -euo pipefail
+          PENDING=""
+          for f in .changeset/*.md; do
+            [ -e "$f" ] || continue
+            case "$f" in
+              .changeset/README.md) continue ;;
+              *) PENDING="${PENDING}${f}"$'\n' ;;
+            esac
+          done
+          if [ -n "${PENDING}" ]; then
+            echo "Pending changesets still present (merge the chore(release) version bump PR first). Skipping publish."
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Re-run quality checks
+        if: steps.pending.outputs.skip != 'true'
+        run: |
+          npm run compose@ci
+          npm run check
+
+      - name: Capture existing tags
+        if: steps.pending.outputs.skip != 'true'
+        run: git tag -l | sort > /tmp/tags-before.txt
+
+      - name: Publish changed packages
+        if: steps.pending.outputs.skip != 'true'
+        run: npm run release
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"
+
+      - name: Capture new tags
+        if: steps.pending.outputs.skip != 'true'
+        run: |
+          git fetch --tags --force
+          git tag -l | sort > /tmp/tags-after.txt
+          comm -13 /tmp/tags-before.txt /tmp/tags-after.txt > /tmp/new-tags.txt
+
+      - name: Verify published versions on npm
+        if: steps.pending.outputs.skip != 'true'
+        run: |
+          set -euo pipefail
+          if [ ! -s /tmp/new-tags.txt ]; then
+            echo "No new tags after publish (nothing published or tag step skipped)."
+            exit 0
+          fi
+          while IFS= read -r tag; do
+            [ -z "$tag" ] && continue
+            echo "Verifying npm registry for tag: $tag"
+            npm view "$tag" version
+          done < /tmp/new-tags.txt
+
+      - name: Create package-scoped GitHub Releases
+        if: steps.pending.outputs.skip != 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [ ! -s /tmp/new-tags.txt ]; then
+            echo "No new tags; skipping GitHub Releases."
+            exit 0
+          fi
+          while IFS= read -r tag; do
+            [ -z "$tag" ] && continue
+            if gh release view "$tag" >/dev/null 2>&1; then
+              echo "Release already exists for $tag, skipping."
+              continue
+            fi
+            gh release create "$tag" --title "$tag" --generate-notes
+          done < /tmp/new-tags.txt

.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "src/**"
+      - "cli/**"
+      - ".changeset/**"
+      - "package.json"
+      - "package-lock.json"
+      - ".github/workflows/release.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  quality-gates:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install Foundry
+        uses: foundry-rs/foundry-toolchain@v1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Forge checks (fmt, build --sizes, test)
+        run: npm run compose@ci
+
+      - name: Run workspace checks
+        run: npm run check
+
+  version-packages:
+    runs-on: ubuntu-latest
+    needs: quality-gates
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          submodules: recursive
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24.x
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Create or update version PR
+        uses: changesets/action@v1
+        with:
+          version: npm run version-packages
+          commit: "chore(release): apply changesets and bump versions"
+          title: "chore(release): bump npm versions & changelogs"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -11,26 +11,8 @@ out/
 .env
 .gas-snapshot
 
-# Docusaurus
-# Dependencies
-docs/node_modules
+node_modules/
 
-# Production
-docs/build
-
-# Generated files
-docs/.docusaurus
-docs/.cache-loader
-
-# Misc
-docs/.DS_Store
-docs/.env
-docs/.env.local
-docs/.env.development.local
-docs/.env.test.local
-docs/.env.production.local
-
-docs/npm-debug.log*
-docs/yarn-debug.log*
-docs/yarn-error.log*
+# tmp copy of CHANGELOG.md when running changeset version
+src/CHANGELOG.md
 

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.0.1
+
+- Library package established; future entries are appended by [Changesets](https://github.com/changesets/changesets) on release.

RELEASING.md

@@ -0,0 +1,36 @@
+# Releasing Compose Packages
+
+This repository publishes 2 npm packages:
+
+- `@perfect-abstractions/compose` from `src/`
+- `@perfect-abstractions/compose-cli` from `cli/`
+
+Releases use [Changesets](https://github.com/changesets/changesets) and run in GitHub Actions.
+
+## Release model
+
+- **Branch:** `main` only for production releases.
+- **Versioning:** independent per package.
+- **Batching:** Multiple PRs can add `.changeset/*.md` files; one **version bump PR** (same PR updated) applies all pending bumps together.
+- **Publish approval:** manual via GitHub Environment `npm-publish` and secret `NPM_TOKEN`.
+- **Provenance:** `NPM_CONFIG_PROVENANCE=true` on publish (OIDC; requires `id-token: write` on the publish job).
+
+## Contributor flow
+
+1. Change code under `src/` and/or `cli/`.
+2. **[changeset-bot](https://github.com/apps/changeset-bot)** comments on the PR when a release note may be needed. You can run `npm run changeset` locally, use the bot’s **add a changeset** link on GitHub, or leave it to maintainers before release.
+3. Merge after required CI checks pass.
+
+There is **no** failing CI check for missing changesets; maintainers batch or add `.changeset/*.md` when preparing releases as needed.
+
+## First release checklist
+
+1. Confirm `src/package.json` and `cli/package.json` names and versions.
+2. Install **[changeset-bot](https://github.com/apps/changeset-bot)** on the org/repo (optional but recommended for PR reminders).
+3. Add at least one `.changeset/*.md` on `main` (feature PR or maintainer commit), then merge the generated **chore(release): bump npm versions & changelogs** PR when ready (bot branch is usually `changeset-release/main`; [changesets/action](https://github.com/changesets/action) updates that PR as new changesets land).
+4. Approve the **Publish** workflow deployment for `npm-publish`.
+5. Confirm versions on npm and tags/releases on GitHub.
+
+## Rollback
+
+Prefer a new **patch** release with a revert + changeset. Avoid unpublishing except for serious issues.

cli/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-## 0.1.0
+## 0.0.1
 
 - Initial Compose CLI foundation.
 - Added config-driven template registry with Foundry/Hardhat variants.