cdt-release 0.4.0__tar.gz

cdt_release-0.4.0/.agents/rules/cdt-release.md

@@ -0,0 +1,41 @@
+# CDT Release Agent Rules
+
+Use these hard rules whenever an agent runs or prepares to run `cdt run`.
+
+## Required pre-run checks
+
+1. Load `skills/cdt-release/SKILL.md`.
+2. Confirm `cdt.yaml` exists in the target project.
+3. Run `cdt pipeline list` and `cdt pipeline inspect <pipeline>` before `cdt run`.
+4. Verify the inspected steps match the user's intent and are not production-like unless production was explicitly requested and confirmed.
+5. Announce the command and log path before execution.
+
+## Production safety
+
+Never run production-like pipelines without exact human confirmation. This includes pipelines named or behaving like `prod`, `ios-prod`, `android-prod`, `release`, `deploy`, `production`, public publishing, production uploads, git pushes, or production infrastructure changes.
+
+Acceptable confirmation format:
+
+```text
+Подтверждаю production release: cdt run <pipeline>
+```
+
+Ambiguous replies such as `ok`, `да`, `go`, or `continue` are not enough for production.
+
+## Logging and observability
+
+- Use the isolated `.cdt/runs/<run-id>/output.log` created by detached execution.
+- Prefer `cdt agent-release start <pipeline> --json` and `cdt agent-release status --run <run-id> --wait --json` for long releases.
+- Do not paste full logs into chat.
+- Do not read `tail`/`grep` from the release log during healthy long-running releases; use compact agent-release status output instead.
+- Do not post repetitive progress narration such as "still waiting" while a release is healthy.
+- On failure, show only the relevant error or the last 40-80 log lines.
+- Summaries must include: `status`, `pipeline`, `artifacts`, `log`, `working_tree`, and `next_actions`.
+- A separate JSON report is optional; create one only when useful beyond the built-in run status.
+
+## Forbidden actions
+
+- Do not run `cdt run <production-like-pipeline>` without exact confirmation.
+- Use `--dry-run` only for planning. Pass `--confirm <pipeline>` only after exact production approval.
+- Do not immediately retry after `pubspec.yaml` or version files changed.
+- Do not assume a pipeline covers Android/iOS from its name alone; inspect it.

cdt_release-0.4.0/AGENTS.md

@@ -0,0 +1,88 @@
+# Instructions for AI agents working with CDT
+
+## Commands
+
+```bash
+pytest
+pytest --cov=cdt --cov-report=term
+ruff check .
+python -m build
+```
+
+Use `python -m build` before packaging or release changes to verify package metadata and included files. For release notes, check or update `CHANGELOG.md`.
+
+Use focused tests while editing, for example:
+
+```bash
+pytest tests/test_skills.py
+```
+
+## Branch naming
+
+When creating branches, use short intent-based names:
+
+- `feature/<short-kebab-feature>`
+- `fix/<short-kebab-bug>`
+- `docs/<short-kebab-topic>`
+- `chore/<short-kebab-task>`
+
+Rules:
+
+- use at most 3-4 meaningful words after the prefix;
+- do not include dates;
+- do not copy full plan titles;
+- avoid implementation details unless they are the user-facing feature name;
+- branch from latest `main`;
+- keep one PR focused on one coherent feature, fix, or docs task.
+
+Before pushing, check:
+
+```bash
+git branch --show-current
+git merge-base --is-ancestor origin/main HEAD
+git diff --name-only origin/main...HEAD
+```
+
+Good examples: `feature/agent-release`, `feature/run-status-file`, `fix/release-worker-exit`.
+Bad examples: `feature/agent-release-token-efficient-cicd`, `feature/2026-07-07-token-efficient-cdt-releases-cicd-robustness`.
+
+## PR merge cleanup
+
+Delete feature/fix/docs/chore branches after merging PRs unless the user explicitly asks to keep them.
+
+Preferred GitHub CLI merge command:
+
+```bash
+gh pr merge <PR> --merge --delete-branch
+```
+
+After merging, prune local refs and remove the local topic branch if it remains:
+
+```bash
+git fetch --prune
+git branch -d <branch>
+```
+
+The GitHub repository setting `delete_branch_on_merge` should stay enabled so web UI merges also delete merged head branches.
+
+## Agent skills
+
+When asked to send, publish, upload, or run a release through CDT, load:
+
+```text
+skills/cdt-release/SKILL.md
+```
+
+This includes requests such as `cdt run test`, TestFlight/AppTester/Firebase uploads, Pachca notifications, and Russian requests like "отправь тестовый релиз" or "залей тестовую сборку".
+
+## Release safety rules
+
+Follow `.agents/rules/cdt-release.md` for every `cdt run` prepared or executed by an agent.
+
+Hard requirements:
+
+- inspect `cdt.yaml` before running a pipeline;
+- run `cdt pipeline list` and `cdt pipeline inspect <pipeline>` as preflight;
+- use the isolated `.cdt/runs/<run-id>/output.log` created by detached execution;
+- never run production-like pipelines without exact human confirmation;
+- provide a concise structured summary after the run.

cdt_release-0.4.0/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## Unreleased
+
+- Nothing yet.
+
+## v0.4.0 - 2026-07-21
+
+- Renamed the Python distribution to `cdt-release` while preserving the `cdt` command, and added PyPI trusted publishing to the release workflow. Existing pipx users must migrate once with `pipx uninstall cdt && pipx install cdt-release`; project `cdt.yaml` files do not require migration.
+- Added isolated `.cdt/runs/<run-id>/` records with atomic manifests, statuses, exit codes, logs, latest-pipeline pointers, and concurrent-run safety.
+- Added `cdt history`, `cdt status`, and `cdt logs` while preserving direct `cdt run <pipeline>` as the primary human workflow.
+- Added run-ID based detached commands: `cdt agent-release status --run <run-id>` and `stop --run <run-id>`.
+- Added explicit pipeline `risk: production` and exact `--confirm <pipeline>` enforcement for interactive and detached execution.
+- Added Flutter/mobile project detection and reviewable test pipeline generation through `cdt init`.
+- Added a bundled `cdt.yaml` JSON Schema and `cdt schema` command for editor integration.
+- Updated Agent Skill guidance to use compact run status rather than parsing healthy logs.
+- Added security and contribution policies, refreshed installation and pipeline documentation, and documented separate human and agent workflows.
+- Consolidated duplicate CI workflows, added Python 3.13 coverage, expanded wheel smoke checks, and raised total test coverage from 81% to 84%.
+
+## v0.3.6 - 2026-07-18
+
+- Added sequential branches inside parallel pipeline groups, enabling prod flows such as iOS alongside Android AAB followed immediately by APK.
+- Added `notify.prod_user_agent` as a registered YAML built-in and included it in the example prod pipeline before `notify.success`.
+- Added nested step IDs and child-step resume support for sequential parallel branches.
+- Fixed `cdt run --skip-completed` incorrectly treating duplicate step names, including anonymous parallel groups, as the same step.
+- Changed pipeline status step fields to store stable step ids instead of step names. Older name-based resume files are rejected because duplicate step names are ambiguous; recreate them or map completed work to ids from `cdt pipeline inspect <pipeline>` / `cdt pipeline plan <pipeline>`.
+- Changed resume input handling: `--resume-status-file` is required for `--resume-from` and `--skip-completed`; `--status-file` only writes the current run status.
+
+## v0.3.5 - 2026-07-07
+
+- Added `cdt run --resume-from` and `--skip-completed` to resume long pipeline runs from status JSON.
+- Added child-level parallel runtime status fields: `running_steps`, `parallel_completed`, and `parallel_failed`.
+- Added `cdt pipeline validate --strict` to fail on planner warnings during safer CI preflight.
+- Added metadata-driven `requires_env` and `cdt pipeline preflight <pipeline>` for selected-pipeline tool/env checks.
+
+## v0.3.4 - 2026-07-07
+
+- Added `cdt agent-release start/status/stop` for token-efficient long-running release automation.
+- Added `cdt run --status-file` for machine-readable pipeline status.
+- Hardened CI/CD checks with clean `dist` builds, quiet pytest, and tag smoke retry regressions.
+
+## v0.3.3 - 2026-07-07
+
+- Automated release pipeline via GitHub Actions.
+- Hardened the release helper with explicit push mode, safer changelog formatting, clean builds, and pre-push rebase.
+- Added PR build, twine, and wheel smoke checks.
+- Added `cdt self-update --check`, `--json`, explicit `--manager`, rate-limit errors, and `uv` support.
+- Added `cdt doctor` and a getting-started guide.
+- Improved pipeline YAML, unknown-step, and failed-step error messages.
+
+## v0.3.2 - 2026-07-07
+
+- Fixed README install examples to point to the latest release tag.
+- Hardened repository URL parsing in `cdt self-update`.
+- Clarified `cdt self-update` installation-method limitations.
+- Added coverage execution to the documented local command set and CI.
+
+## v0.3.1 - 2026-07-07
+
+- Added `cdt self-update` command to update the CLI to the latest GitHub release via `pipx`.
+- Added `cdt self-update --dry-run` to preview the available release tag and update command without executing it.
+- Moved planning documents from `plans/` to `docs/plans/`.
+
+## v0.3.0 - 2026-07-06
+
+- Added step metadata for built-in and plugin pipeline steps.
+- Added `cdt pipeline plan <pipeline>` with JSON output and static risk classification.
+- Added `cdt run <pipeline> --dry-run` as a non-executing planning preflight.
+- Extended `cdt.sdk.step` decorator to accept `StepMetadata` and keyword metadata arguments.
+- Refined artifact/result metadata contract: `StepMetadata` now uses structured
+  `ResultRequirement` and `ResultProduction` objects instead of flat
+  `requires_artifacts` / `produces` strings.
+- `cdt pipeline plan --json` now exposes grouped `artifact_flow.requires` entries with
+  `types`, `mode` (`all` or `any`), and `names` inferred from static YAML options.
+- Breaking: SDK/plugin authors must migrate from `requires_artifacts` and flat string
+  `produces` metadata to `ResultRequirement` / `ResultProduction`; CI/tools parsing
+  `cdt pipeline plan --json` metadata must handle the structured metadata shape.
+
+## v0.2.1 - 2026-07-06
+
+- Improved the `cdt-release` Agent Skill with explicit production confirmation, structured summaries, and observability guidance.
+- Added repository-level `AGENTS.md` instructions for AI agents.
+- Added `.agents/rules/cdt-release.md` with hard release safety rules.
+- Updated AI agent documentation and package manifest entries for agent skills/rules.
+- Replaced Hermes-specific setup text with generic Agent Skills guidance.
+
+## v0.2.0 - 2026-07-06
+
+- Added the `cdt-release` Agent Skill for safer AI-assisted CDT test releases.
+- Removed `cdt migrate legacy` after all known projects were migrated.
+- Switched release automation to YAML-only `cdt.yaml` pipelines.
+- Removed legacy direct commands in favor of `cdt run <pipeline>`.
+- Added `cdt migrate legacy` with dry-run, merge, backup, and force behavior.
+- Added/updated built-ins: Flutter build-number increment, Android APK/AAB, iOS IPA, TestFlight upload, artifact copy, success notify, and Python hook steps.
+- Build steps now use `profile` instead of `env`, do not run `flutter pub get`, and do not increment versions implicitly.
+- Added artifact duplicate/missing checks, parallel error aggregation, JSON `schema_version`, and unknown-step suggestions.
+
+## v0.1.0 - 2026-07-03
+
+- Initial public release of CDT.
+- Includes Flutter release flows, App Store/TestFlight upload helpers, Firebase upload/deploy helpers, notifications, and trusted project-local YAML pipelines.
+- Adds plugin steps through `cdt.yaml` and the `cdt.sdk.step` decorator.

cdt_release-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to CDT
+
+## Setup
+
+```bash
+git clone https://github.com/Sergionius/cdt.git
+cd cdt
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+```
+
+## Checks
+
+Run before opening a pull request:
+
+```bash
+.venv/bin/ruff check .
+.venv/bin/pytest -q
+.venv/bin/pytest --cov=cdt --cov-report=term
+.venv/bin/python -m build
+.venv/bin/twine check dist/*
+```
+
+Changes to the CLI should include tests for both readable human output and structured JSON where applicable. Release execution changes should cover failure, interruption, status persistence, and production confirmation.
+
+## Design expectations
+
+- Keep `cdt run <pipeline>` simple for direct human use.
+- Keep agent interfaces structured and low-noise.
+- Preserve explicit, reviewable `cdt.yaml` behavior.
+- Do not add network services or persistent infrastructure without a demonstrated requirement.
+- Never include credentials, signing material, or real application artifacts in fixtures.
+- Update README, relevant docs, examples, JSON Schema, and changelog together.
+
+## Pull requests
+
+Use a short intent-based branch name such as `feature/run-history` or `fix/stale-run-status`. Keep each pull request focused and describe behavior changes, safety implications, tests, and compatibility considerations.
+
+Report security vulnerabilities privately as described in [SECURITY.md](SECURITY.md).

cdt_release-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Malkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cdt_release-0.4.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md LICENSE CHANGELOG.md AGENTS.md CONTRIBUTING.md SECURITY.md
+include examples/cdt.yaml
+recursive-include .agents *.md
+recursive-include docs *.md
+recursive-include examples/cdt_steps *.py
+recursive-include skills *.md

cdt_release-0.4.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: cdt-release
+Version: 0.4.0
+Summary: Agent-first release automation CLI for mobile, web, and custom deployments
+License-Expression: MIT
+Project-URL: Repository, https://github.com/Sergionius/cdt
+Project-URL: Documentation, https://github.com/Sergionius/cdt/tree/main/docs
+Project-URL: Changelog, https://github.com/Sergionius/cdt/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Sergionius/cdt/issues
+Keywords: ai,release,deploy,cli,pipeline,automation,mobile,web,ios,android,flutter,testing,devops
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer>=0.12
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: pyjwt[crypto]>=2.10.1
+Requires-Dist: rich>=13.0.0
+Requires-Dist: PyYAML>=6.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# <img src="site/assets/logo.png" alt="" width="28">&nbsp;CDT &nbsp;[![CI](https://github.com/Sergionius/cdt/actions/workflows/ci.yml/badge.svg)](https://github.com/Sergionius/cdt/actions/workflows/ci.yml)
+
+CDT is an agent-first release automation CLI built around project-local YAML pipelines, safe preflight checks, and reusable steps for mobile, web, and custom deployments. Direct human operation remains a first-class workflow.
+
+CDT includes built-in steps for Flutter, native iOS/Xcode, Android, web, Firebase/AppTester, TestFlight, Python hooks, and custom steps via its SDK.
+
+## Installation
+
+CDT is published as the `cdt-release` Python distribution and installs the `cdt` command. `pipx` is the recommended installation method:
+
+```bash
+pipx install cdt-release
+```
+
+A specific GitHub release can also be installed directly:
+
+```bash
+pipx install "git+https://github.com/Sergionius/cdt.git@v0.4.0"
+```
+
+Upgrade or reinstall:
+
+```bash
+cdt self-update --check
+cdt self-update --manager pipx
+cdt self-update --dry-run  # preview the release tag and command without running it
+```
+
+Or manually:
+
+```bash
+pipx uninstall cdt-release
+pipx install cdt-release
+```
+
+For local development:
+
+```bash
+git clone https://github.com/Sergionius/cdt.git
+cd cdt
+python -m pip install -e '.[dev]'
+# or reinstall the local checkout as a pipx CLI:
+scripts/reinstall.sh
+```
+
+`pip install cdt-release` also works, but `pipx` keeps the CLI isolated from project Python environments.
+
+The distribution is named `cdt-release` because the `cdt` project name on PyPI belongs to another project. The installed command remains `cdt`.
+
+### Upgrading from CDT 0.3.x
+
+CDT 0.3.x installed from GitHub used the distribution name `cdt`. Migrate the pipx environment once:
+
+```bash
+pipx uninstall cdt
+pipx install cdt-release
+```
+
+Project configuration does not require migration: `cdt.yaml` version 1 remains supported, and pipeline `risk` defaults to `standard` when omitted. Existing pipeline-named agent-release status files remain readable for compatibility; new runs use `.cdt/runs/<run-id>/`.
+
+## Commands
+
+```bash
+cdt --version
+cdt init
+cdt run <pipeline>
+cdt run <pipeline> --dry-run
+cdt history
+cdt status <run-id>
+cdt logs <run-id>
+cdt pipeline list
+cdt pipeline inspect <pipeline> --json
+cdt pipeline plan <pipeline> --json
+cdt pipeline validate [pipeline]
+cdt pipeline steps
+cdt schema --output cdt.schema.json
+cdt doctor
+cdt self-update --check
+cdt self-update --manager pipx
+cdt self-update --json --check
+```
+
+Static planning commands (`cdt pipeline plan <pipeline>` and `cdt run <pipeline> --dry-run`) show the step tree, risk, warnings, and artifact flow without executing steps.
+
+Every real run is recorded under `.cdt/runs/<run-id>/` with an atomic status file, manifest, exit code, and log location. Human operators can continue to use `cdt run test` directly; run IDs are only needed for later inspection with `cdt history`, `cdt status`, or `cdt logs`. See [Run records](docs/runs.md) for lifecycle, concurrency, retention, and recovery.
+
+Resume status migration note: current CDT status files store stable step ids (`0`, `1`, `1/0`, `1/0/1`) instead of step names. Older name-based status files are rejected because duplicate names such as anonymous `parallel` groups are ambiguous. Recreate the status file by rerunning without `--skip-completed`, or use `cdt pipeline inspect <pipeline>` / `cdt pipeline plan <pipeline>` to map completed work to step ids manually.
+
+`cdt self-update` updates the installed CLI to the latest GitHub release. It supports `--manager pipx`, `--manager pip`, and `--manager uv`; editable/local installs should be updated manually. Use `cdt self-update --check` to check without changing files, `--json` for machine-readable output, and `--dry-run` to see the release tag and update command without running it. The command requires outbound HTTPS access to `api.github.com`.
+
+For a quick first run, use `cdt init` in a Flutter project and see [Getting started in 5 minutes](docs/getting-started.md). `cdt init` creates a reviewable test pipeline; it never adds uploads, credentials, or production steps automatically.
+
+## Minimal `cdt.yaml`
+
+```yaml
+version: 1
+
+pipelines:
+  prod:
+    risk: production
+    steps:
+      - flutter.increment_build_number
+      - flutter.pub_get
+      - parallel:
+          steps:
+            - sequence:
+                steps:
+                  - ios.flutter_build_ipa:
+                      profile: prod
+                      flavor: prod
+                      artifact: ios_ipa
+                  - appstore.upload_testflight:
+                      artifact: ios_ipa
+                      changelog: prod build
+            - sequence:
+                steps:
+                  - android.build_aab:
+                      profile: prod
+                      flavor: prod
+                      artifact: android_aab
+                  - android.build_apk:
+                      profile: prod
+                      flavor: prod
+                      artifact: android_apk
+      - notify.prod_user_agent
+      - notify.success
+```
+
+See `examples/cdt.yaml` and `docs/pipelines.md` for a fuller prod pipeline, plugins, artifacts, and hooks.
+
+## Release notes
+
+See [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+
+## Releasing
+
+After updating versions and the changelog, push a `v*` tag (for example `v0.4.0`). GitHub Actions runs lint, tests, build, and `twine check`, publishes `cdt-release` to PyPI through trusted publishing, creates a GitHub Release, and attaches the wheel and source archive from `dist/`. Use `python scripts/release.py <version>` to prepare the release commit and annotated tag locally. Use `python scripts/release.py <version> --push` only after explicit confirmation to rebase, push the commit, and push the tag.
+
+## Agent-friendly automation
+
+CDT is agent-first, not agent-only. Humans keep the direct `cdt run <pipeline>` workflow, while automation clients can use JSON planning and detached execution without parsing full build logs.
+
+CDT ships an Agent Skill at `skills/cdt-release/SKILL.md`. It makes agents inspect `cdt.yaml`, avoid production pipelines without exact confirmation, use isolated run IDs, wait on compact status JSON, and return concise structured summaries.
+
+Repository-level guidance lives in `AGENTS.md`; hard release safety rules live in `.agents/rules/cdt-release.md`. Agent Skills compatible clients can copy or link `skills/cdt-release/` according to their installation mechanism. See `docs/ai-agents.md` for setup and the stable automation contract.
+
+## Built-in steps
+
+Use `cdt pipeline steps` for the complete list. Common built-ins:
+
+- `flutter.increment_build_number`
+- `flutter.pub_get`
+- `ios.flutter_build_ipa`
+- `android.build_aab`
+- `android.build_apk`
+- `appstore.upload_testflight`
+- `artifact.copy_to_downloads`
+- `hook.python_script`
+- `notify.prod_user_agent`
+- `notify.success`
+
+Build steps use `profile` for CDT presets (`profile: prod` adds `--dart-define=ENV=prod`). Flutter `flavor` is separate. Build steps do not run `flutter pub get` or increment versions implicitly.
+
+## Python hooks
+
+```yaml
+- hook.python_script:
+    script: cdt/hooks/fetch_offline_data.py
+    env:
+      OFFLINE_API_URL: ${OFFLINE_API_URL}
+    outputs:
+      - assets/offline_data.json
+```
+
+Hooks run from the project root as `python3 <script>` and must stay inside the project root.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development checks and pull request guidance. Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). CDT is available under the [MIT License](LICENSE).