Improvements for v1.0.0-rc.1

.github/workflows/ci.yml

@@ -0,0 +1,48 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  build-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test
+
+      - name: Validate (if compose config exists)
+        shell: bash
+        run: |
+          if [[ -f "compose/umbraco-compose.yaml" ]]; then
+            node dist/index.js validate --dir ./compose --strict
+          else
+            echo "Skipping validate: compose/umbraco-compose.yaml not found"
+          fi
+
+      - name: Plan (if compose config exists)
+        shell: bash
+        run: |
+          if [[ -f "compose/umbraco-compose.yaml" ]]; then
+            node dist/index.js plan --dir ./compose
+          else
+            echo "Skipping plan: compose/umbraco-compose.yaml not found"
+          fi

.github/workflows/deploy.yml

@@ -0,0 +1,63 @@
+name: Deploy
+
+on:
+  workflow_dispatch:
+    inputs:
+      compose_dir:
+        description: "Compose root directory"
+        required: true
+        default: "./compose"
+      environment_alias:
+        description: "Environment alias to apply (e.g. dev, prod)"
+        required: true
+        default: "dev"
+
+concurrency:
+  group: deploy-${{ github.ref }}-${{ inputs.environment_alias }}
+  cancel-in-progress: false
+
+jobs:
+  apply:
+    runs-on: ubuntu-latest
+    environment: ${{ inputs.environment_alias }}
+
+    steps:
+      - name: Require main branch
+        if: github.ref != 'refs/heads/main'
+        run: |
+          echo "Deploy workflow may only run from main. Current ref: $GITHUB_REF"
+          exit 1
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: .nvmrc
+          cache: npm
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Validate
+        run: node dist/index.js validate --dir "${{ inputs.compose_dir }}" --strict
+
+      - name: Plan
+        run: node dist/index.js plan --dir "${{ inputs.compose_dir }}" --env "${{ inputs.environment_alias }}"
+        env:
+          COMPOSE_MGMT_CLIENT_ID: ${{ secrets.COMPOSE_MGMT_CLIENT_ID }}
+          COMPOSE_MGMT_CLIENT_SECRET: ${{ secrets.COMPOSE_MGMT_CLIENT_SECRET }}
+          COMPOSE_MGMT_SCOPE: ${{ secrets.COMPOSE_MGMT_SCOPE }}
+          COMPOSE_MGMT_AUDIENCE: ${{ secrets.COMPOSE_MGMT_AUDIENCE }}
+
+      - name: Apply
+        run: node dist/index.js apply --dir "${{ inputs.compose_dir }}" --env "${{ inputs.environment_alias }}"
+        env:
+          COMPOSE_MGMT_CLIENT_ID: ${{ secrets.COMPOSE_MGMT_CLIENT_ID }}
+          COMPOSE_MGMT_CLIENT_SECRET: ${{ secrets.COMPOSE_MGMT_CLIENT_SECRET }}
+          COMPOSE_MGMT_SCOPE: ${{ secrets.COMPOSE_MGMT_SCOPE }}
+          COMPOSE_MGMT_AUDIENCE: ${{ secrets.COMPOSE_MGMT_AUDIENCE }}

.gitignore

@@ -138,4 +138,10 @@ dist
 # Vite files
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
-.vite/
+.vite/
+
+# Test build artifacts (keep only .ts test sources)
+test/**/*.js
+test/**/*.d.ts
+test/**/*.js.map
+test/**/*.d.ts.map

.nvmrc

@@ -0,0 +1 @@
+v24.13.1

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+## [1.0.0-rc.1] - 2026-02-13
+
+### Added
+- Core command set stabilized for IaC-style workflows:
+  - `init`, `generate`, `validate`, `clone`, `pull`, `status`, `plan`, `apply`, `env rename`
+- Broad automated test coverage for:
+  - command behavior and exit-code semantics
+  - multi-environment plan/apply flows
+  - rename safety and alias routing
+  - apply/pull API contract-map checks
+  - OpenAPI-shape assertions for key apply endpoints/payloads
+- CI and deploy GitHub Actions workflows with guarded apply behavior.
+- Operational docs:
+  - `docs/commands.md`
+  - `docs/testing.md`
+  - `docs/ci.md`
+  - `docs/workflow.md`
+  - `docs/release-v1-checklist.md`
+
+### Changed
+- Environment identity model hardened with `compose.state.json` (`id`, `alias`, `remoteAlias`) to support safe rename convergence.
+- `plan` and `pull` use `remoteAlias` routing when a rename is pending.
+- `apply` performs environment rename first, then applies nested resources through the new alias.
+- Apply operation output now includes explicit environment context and per-environment/final summaries.
+- Non-environment rename inference expanded and guarded:
+  - unique one-to-one signature matches infer rename
+  - ambiguous matches fall back to create/delete with explicit context
+- Apply convergence expanded across managed entities, including create/update/delete and rename paths where supported.
+
+### Fixed
+- Prevented lock/state writes when apply emits warnings.
+- Improved warning/plan messaging around rename and missing nested resources.
+- Tightened TypeScript compatibility under strict checks (`exactOptionalPropertyTypes`, indexed access, env config narrowing).
+- Resolved test harness response-shape issues around `204` delete cases.
+
+## [Unreleased]
+- Final `1.0.0` version bump and release tagging.

docs/ci.md

@@ -0,0 +1,61 @@
+# CI/CD Setup
+
+## Workflows
+- CI workflow: `.github/workflows/ci.yml`
+  - runs on PRs and pushes to `main`
+  - executes build + tests
+  - runs validate/plan when `compose/umbraco-compose.yaml` exists
+
+- Deploy workflow: `.github/workflows/deploy.yml`
+  - manual trigger only (`workflow_dispatch`)
+  - main-branch-only guard
+  - runs validate -> plan -> apply for the selected environment alias
+
+## Are Workflow Files Auto-Created?
+Short answer: no, not automatically by GitHub.
+
+How they appear in a repo:
+- they must exist as committed files under `.github/workflows/`
+- they can be copied from this project, a template repository, or scaffolding logic in your own tooling
+
+Current behavior in this CLI:
+- `compose init` does not scaffold workflow files today
+- users should copy/add `ci.yml` and `deploy.yml` (or use a repo template) when setting up a new canonical repo
+
+## Required Repository Secrets
+Configure these in repository settings:
+- `COMPOSE_MGMT_CLIENT_ID`
+- `COMPOSE_MGMT_CLIENT_SECRET`
+
+Optional:
+- `COMPOSE_MGMT_SCOPE`
+- `COMPOSE_MGMT_AUDIENCE`
+
+## GitHub Environment Protection
+Create GitHub Environments that match deploy aliases (for example `dev`, `prod`) and enable:
+- required reviewers
+- optional wait timer
+- environment-scoped secrets if needed
+
+The deploy workflow binds `environment: ${{ inputs.environment_alias }}`, so protections apply automatically when names match.
+
+## Recommended Branch Protection
+For `main`:
+- require PR review approvals
+- require status checks to pass:
+  - CI / build-test
+- restrict direct pushes
+
+## Running Deploy
+1. Open GitHub Actions -> `Deploy`.
+2. Click `Run workflow`.
+3. Choose `main` branch.
+4. Set:
+   - `compose_dir` (usually `./compose`)
+   - `environment_alias` (for example `dev` or `prod`)
+5. Confirm environment approval prompt if configured.
+
+## Operational Notes
+- Deploy concurrency is keyed by branch + environment alias to avoid overlapping applies for the same target.
+- Keep plan output from deploy runs for audit trail and incident review.
+- Treat non-zero exits as failed deployment attempts; do not auto-retry without reviewing warnings/errors.