Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
ci(workflows): align with production-CLI patterns (gh/stripe/uv/prefect)
trohitgb507b1c81741
diff --git a/.github/actions/setup/action.yml b/.github/actions/setup/action.ymlindex bae2b27b..562e047f 100644--- a/.github/actions/setup/action.yml+++ b/.github/actions/setup/action.yml@@ -1,12 +1,16 @@# Composite action for shared environment setup across all workflows.# Eliminates duplicated Node/Python/uv setup.#+# Python version comes from the repo-root ``.python-version`` file+# (single source of truth, also honoured by uv / pyenv / asdf). To+# bump Python, change that file -- the composite action picks it up+# automatically.+## Usage:# - uses: ./.github/actions/setup# - uses: ./.github/actions/setup# with:-# node-version: '22'-# python-version: '3.11'+# node-version: '20' # override Node only; Python tracks .python-versionname: 'Setup MachinaOS Environment'description: 'Setup Node.js, Python, and uv for cross-platform builds.'@@ -15,29 +19,36 @@ inputs:node-version:description: 'Node.js version'default: '22'- python-version:- description: 'Python version'- default: '3.12'runs:using: compositesteps:+ # Action versions are pinned to commit SHAs per the supply-chain+ # hardening pass (see docs-internal/ci_cd.md). Dependabot updates+ # these via the github-actions ecosystem group in dependabot.yml;+ # zizmor (.github/workflows/check-zizmor.yml) enforces SHA pinning+ # on every PR to prevent regression.- name: Setup pnpm- uses: pnpm/action-setup@v4+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: ${{ inputs.node-version }}cache: 'pnpm'- name: Setup Python- uses: actions/setup-python@v5+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5with:- python-version: ${{ inputs.python-version }}+ # Sourced from repo-root .python-version (https://docs.astral.sh/uv/concepts/python-versions/#requesting-a-version).+ # Single literal lives in that file; bump there and CI follows.+ python-version-file: .python-version+ # setup-uv v8 — the canonical uv installer (pdm, prefect, uv itself+ # all use it). Replaces the older "pip install uv" pattern; v8+ # adds automatic UV_CACHE_DIR setup + lockfile caching.- name: Install uv- uses: astral-sh/setup-uv@v4+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0# The supervisor CLI lives at <repo>/cli/ and is invoked by pnpm# scripts as `python -m cli ...` from the runner's system Python.diff --git a/.github/dependabot.yml b/.github/dependabot.ymlnew file mode 100644index 00000000..372996bd--- /dev/null+++ b/.github/dependabot.yml@@ -0,0 +1,85 @@+# Dependabot — weekly grouped dependency updates.+#+# Three ecosystems mirror the repo's actual dependency surface:+# - npm: root package.json + pnpm workspace members+# (client, server/nodejs). Dependabot v2 follows+# pnpm workspaces from the root manifest.+# - pip: machinaos-cli at the repo root and machinaos-server+# under server/. Listed separately because they're+# independent uv projects with their own pyproject.toml+# and uv.lock (see Phase 1 of the CLI refactor —+# the CLI is intentionally NOT in the server's uv+# workspace).+# - github-actions: pinned commit SHAs in every workflow + the+# composite action; Dependabot rewrites the SHA+# and the trailing version comment together.+#+# Groups keep the PR firehose manageable: one weekly PR per+# (ecosystem, dependency-type) instead of per-package noise.+# Reference: https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file+#+# Anti-spam: open-pull-requests-limit caps each ecosystem so a single+# burst (e.g. a major React release rippling through devDeps) can't+# flood the review queue. The cap is per ecosystem; total ceiling is+# 5 ecosystems x 10 = 50 open Dependabot PRs at any time.++version: 2++updates:+ # ---- npm (workspace root + pnpm members) -------------------------------+ - package-ecosystem: "npm"+ directory: "/"+ schedule:+ interval: "weekly"+ day: "monday"+ time: "06:00"+ timezone: "UTC"+ open-pull-requests-limit: 10+ versioning-strategy: "increase-if-necessary"+ groups:+ npm-dev-deps:+ dependency-type: "development"+ update-types: ["minor", "patch"]+ npm-prod-deps:+ dependency-type: "production"+ update-types: ["minor", "patch"]+ # Major bumps stay ungrouped so the diff is reviewed in isolation.++ # ---- pip: machinaos-cli (repo root pyproject.toml) ---------------------+ - package-ecosystem: "pip"+ directory: "/"+ schedule:+ interval: "weekly"+ day: "monday"+ time: "06:00"+ timezone: "UTC"+ open-pull-requests-limit: 10+ groups:+ cli-deps:+ update-types: ["minor", "patch"]++ # ---- pip: machinaos-server (server/pyproject.toml) ---------------------+ - package-ecosystem: "pip"+ directory: "/server"+ schedule:+ interval: "weekly"+ day: "monday"+ time: "06:00"+ timezone: "UTC"+ open-pull-requests-limit: 10+ groups:+ server-deps:+ update-types: ["minor", "patch"]++ # ---- GitHub Actions ----------------------------------------------------+ - package-ecosystem: "github-actions"+ directory: "/"+ schedule:+ interval: "weekly"+ day: "monday"+ time: "06:00"+ timezone: "UTC"+ open-pull-requests-limit: 5+ groups:+ action-updates:+ update-types: ["minor", "patch", "major"]diff --git a/.github/workflows/check-zizmor.yml b/.github/workflows/check-zizmor.ymlnew file mode 100644index 00000000..624efee0--- /dev/null+++ b/.github/workflows/check-zizmor.yml@@ -0,0 +1,91 @@+# zizmor — static-analysis linter for GitHub Actions workflows.+#+# Catches:+# - Over-granted `permissions:` (e.g., a job that doesn't need+# `contents: write` but inherits it from the workflow default).+# - Unpinned third-party action `uses:` (floating major-version+# tags like `@v4` instead of pinned commit SHAs).+# - Insecure `${{ ... }}` template expansion in `run:` blocks+# (script-injection vectors).+# - Reusable-workflow caller-callee permission mismatches.+# - `pull_request_target` + checkout-of-PR-ref combinations+# (the well-known privilege-escalation foot-gun).+#+# Pattern lifted from https://github.com/astral-sh/uv/blob/main/.github/workflows/check-zizmor.yml+# Project home: https://github.com/woodruffw/zizmor+#+# Runs on every push/PR + weekly schedule so a regression introduced+# between zizmor releases (their query pack expands) is caught+# without anyone running it locally.++name: Check zizmor++on:+ push:+ branches: [main]+ paths:+ - '.github/workflows/**'+ - '.github/actions/**'+ - '.github/dependabot.yml'+ pull_request:+ branches: [main]+ paths:+ - '.github/workflows/**'+ - '.github/actions/**'+ - '.github/dependabot.yml'+ schedule:+ # Mondays 07:00 UTC — runs before the weekly Dependabot batch+ # so action-version bumps already in flight don't trip new+ # zizmor checks on their merge.+ - cron: '0 7 * * 1'++permissions:+ contents: read++jobs:+ zizmor:+ name: Lint workflows+ runs-on: ubuntu-latest++ permissions:+ # SARIF upload to the Security tab so findings render alongside+ # CodeQL results.+ security-events: write+ contents: read+ actions: read++ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup Python+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5+ with:+ python-version: '3.12'++ - name: Install zizmor+ # zizmor ships as a PyPI wheel; pip install gives us the+ # binary on PATH without compiling Rust locally.+ run: pip install zizmor++ - name: Run zizmor+ # --format sarif lets the Security tab ingest results.+ # --persona auditor enables stricter checks (recommended+ # for production CI; relaxed by default).+ run: |+ zizmor \+ --format sarif \+ --persona auditor \+ .github/workflows/ \+ .github/actions/ \+ > zizmor.sarif+ # SARIF upload happens unconditionally so findings still+ # post even on a non-zero exit. Failing the job comes from+ # the SARIF upload's threshold setting, not zizmor's exit.+ continue-on-error: true++ - name: Upload SARIF to Security tab+ uses: github/codeql-action/upload-sarif@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3+ with:+ sarif_file: zizmor.sarif+ category: zizmordiff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.ymlnew file mode 100644index 00000000..39ffd521--- /dev/null+++ b/.github/workflows/codeql.yml@@ -0,0 +1,92 @@+# CodeQL static-analysis SAST scanning.+#+# Two-language matrix matches MachinaOs's split: Python (CLI ++# FastAPI backend + plugins under server/) and JavaScript/TypeScript+# (React Flow client + Node.js sidecar at server/nodejs). One job per+# language so a failure in one doesn't block the other's results from+# landing in the Security tab.+#+# Triggers (lifted from prefect's codeql.yml + GitHub's own+# recommended cadence):+# - push to main: scan-then-baseline every merge+# - pull_request: catch regressions before they land (path+# filter excludes docs-only PRs so we don't+# burn 15+ minutes of compute on copy edits)+# - schedule weekly: catch zero-days in dependencies + new query-+# pack releases without waiting for the next+# merge. Sun 20:30 UTC matches the cadence+# prefect uses.+#+# Permissions follow the least-privilege model documented at+# https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-default-setup-for-code-scanning+# `security-events: write` is the one required scope; everything else+# stays at the workflow-default `none`.++name: CodeQL++on:+ push:+ branches: [main]+ paths-ignore:+ - 'docs-MachinaOs/**'+ - '**/*.md'+ pull_request:+ branches: [main]+ paths-ignore:+ - 'docs-MachinaOs/**'+ - '**/*.md'+ schedule:+ # Sundays 20:30 UTC. Mid-low-traffic window for runner pool ++ # gives the Security tab a fresh baseline each week.+ - cron: '30 20 * * 0'++permissions:+ contents: read++jobs:+ analyze:+ name: Analyze ${{ matrix.language }}+ runs-on: ubuntu-latest+ timeout-minutes: 60++ permissions:+ # Minimum needed for CodeQL to publish to the Security tab.+ # Documented at https://github.com/github/codeql-action#permissions+ security-events: write+ contents: read+ actions: read++ strategy:+ fail-fast: false+ matrix:+ include:+ - language: python+ # Repo Python files live under cli/ + server/ + scripts/.+ # CodeQL auto-detects entrypoints; no build step needed+ # for Python (it's interpreted).+ - language: javascript-typescript+ # Combined JS/TS query pack — single language slot in+ # the matrix per CodeQL's 2024+ convention.++ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Initialize CodeQL+ uses: github/codeql-action/init@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3+ with:+ languages: ${{ matrix.language }}+ # security-extended pulls in queries beyond the default+ # security pack (e.g., taint-tracking on more sinks,+ # CWE coverage). security-and-quality adds code-quality+ # queries which produce noise we don't want gating PRs.+ queries: security-extended++ # No autobuild step: Python is interpreted; JS/TS via the+ # tsgo+vite toolchain already runs in predeploy.yml — CodeQL+ # only needs to read source files, not build artifacts.++ - name: Perform CodeQL Analysis+ uses: github/codeql-action/analyze@458d36d7d4f47d0dd16ca424c1d3cda0060f1360 # v3+ with:+ category: "/language:${{ matrix.language }}"diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex 718a004c..d5a3bf7b 100644--- a/.github/workflows/docs.yml+++ b/.github/workflows/docs.yml@@ -18,10 +18,10 @@ jobs:runs-on: ubuntu-lateststeps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: '22'diff --git a/.github/workflows/predeploy.yml b/.github/workflows/predeploy.ymlindex ea5de3f6..343494fe 100644--- a/.github/workflows/predeploy.yml+++ b/.github/workflows/predeploy.yml@@ -1,5 +1,22 @@-# Reusable validation workflow called by ci.yml and release.yml-# Jobs: build-and-lint, test-build-start+# Reusable validation workflow called by ci.yml and release.yml.+#+# Job graph:+# plan ─┬─> build-and-lint (gated on should_lint_or_test_frontend)+# ├─> backend-tests (matrix: domain shards, gated on should_test_backend)+# ├─> cli-tests (gated on should_test_cli)+# ├─> test-build-start (matrix: OS, gated on should_full_build)+# └─> ci-passed (alls-green aggregator — branch protection target)+#+# Patterns (Tier 3 of the CI/CD plan):+# - `plan` job: change-detection booleans via dorny/paths-filter+# (lifted from astral-sh/uv ci.yml). Doc-only PRs skip the heavy+# suites; cli-only PRs skip the backend tests; etc.+# - Domain-sharded test matrix (lifted from prefect's python-tests.yaml):+# parallelises 1376 pytest cases by test-tree subdir so one slow+# shard doesn't gate the others' results.+# - `ci-passed` job using re-actors/alls-green (lifted from hatch):+# single required-check job name for branch protection that doesn't+# break when matrix dimensions change.name: Predeploy@@ -10,11 +27,86 @@ permissions:contents: readjobs:+ # ----------------------------------------------------------------------+ # plan -- change-detection booleans gate the downstream graph.+ # ----------------------------------------------------------------------+ plan:+ name: Plan+ runs-on: ubuntu-latest+ outputs:+ backend_changed: ${{ steps.filter.outputs.backend }}+ frontend_changed: ${{ steps.filter.outputs.frontend }}+ cli_changed: ${{ steps.filter.outputs.cli }}+ workflows_changed: ${{ steps.filter.outputs.workflows }}+ docs_only: ${{ steps.filter.outputs.docs_only }}+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Detect changed paths+ id: filter+ uses: dorny/paths-filter@6852f92c20ea7fd3b0c25de3b5112db3a98da050 # v3+ with:+ # On `workflow_call`, paths-filter compares against the base+ # branch automatically. For push events, it compares with the+ # previous SHA. No `base:` needed in the workflow_call case.+ filters: |+ backend:+ - 'server/**'+ - 'pyproject.toml'+ - 'pnpm-workspace.yaml'+ frontend:+ - 'client/**'+ - 'pnpm-workspace.yaml'+ cli:+ - 'cli/**'+ - 'pyproject.toml'+ workflows:+ - '.github/**'+ docs_only:+ - 'docs-MachinaOs/**'+ - '**/*.md'++ # ----------------------------------------------------------------------+ # pre-commit -- run all pre-commit hooks on every PR. Catches missed+ # local installs of the hook so unfixed format/lint can't land.+ # ----------------------------------------------------------------------+ pre-commit:+ name: pre-commit+ needs: plan+ if: needs.plan.outputs.docs_only != 'true' || needs.plan.outputs.workflows_changed == 'true'+ runs-on: ubuntu-latest+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup Python+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5+ with:+ python-version: '3.12'+ # pre-commit caches its own hook envs under ~/.cache/pre-commit;+ # actions/setup-python's pip cache is orthogonal -- leave at+ # default behaviour.++ - name: Run pre-commit+ # pre-commit/action handles its own caching keyed on the+ # pre-commit-config.yaml hash, so a hook-pin bump invalidates+ # cleanly without manual cache busting.+ uses: pre-commit/action@2c7b3805fd2a0fd8c1884dcaebf91fc102a13ecd # v3.0.1++ # ----------------------------------------------------------------------+ # build-and-lint -- client build + frontend tests + lint + tsgo+ # ----------------------------------------------------------------------build-and-lint:+ name: Build + lint+ needs: plan+ # Frontend changes / workflow changes / full pushes to main always+ # trigger this. Doc-only PRs skip.+ if: needs.plan.outputs.docs_only != 'true'runs-on: ubuntu-lateststeps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup environmentuses: ./.github/actions/setup@@ -40,32 +132,83 @@ jobs:# bootstrap, and credentials flows to ship.run: pnpm --filter react-flow-client run test- - name: Backend tests (server pytest)- # 1376 tests covering plugin contracts, credential broadcasts, native- # LLM SDK wiring, parameter resolution, workflow ops, MCP tokens.+ # ----------------------------------------------------------------------+ # backend-tests -- pytest sharded by domain (prefect pattern)+ # ----------------------------------------------------------------------+ backend-tests:+ name: Backend tests (${{ matrix.shard }})+ needs: plan+ if: needs.plan.outputs.backend_changed == 'true' || needs.plan.outputs.workflows_changed == 'true'+ runs-on: ubuntu-latest+ strategy:+ fail-fast: false+ matrix:+ # Three shards balance parallelism vs. matrix-dispatch overhead.+ # Add new shards by carving subdirs out of `backend-root` as+ # the test tree grows.+ include:+ - shard: nodes+ paths: tests/nodes/+ - shard: services+ # Pulls tests/services + tests/temporal + tests/llm ++ # tests/credentials together because they share the same+ # heavy setup (DI container + auth_service init).+ paths: tests/services/ tests/temporal/ tests/llm/ tests/credentials/+ - shard: root+ # Root-level cross-cutting invariants (plugin self-containment,+ # broadcast contracts, no-raw-prints, etc.). Cheap to run+ # but logically distinct from per-domain tests.+ paths: tests/ --ignore=tests/nodes/ --ignore=tests/services/ --ignore=tests/temporal/ --ignore=tests/llm/ --ignore=tests/credentials/+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup environment+ uses: ./.github/actions/setup++ - name: Backend tests (server pytest, shard=${{ matrix.shard }})# ``uv sync`` (no flag) includes the PEP 735 ``[dependency-groups].dev``- # bundle by default — pytest, pytest-asyncio, pytest-mock, respx,- # ruff. The previous ``--extra dev`` invocation read PEP 621- # ``[project.optional-dependencies].dev``, which no longer exists- # (moved to PEP 735 groups so ``pnpm install`` keeps dev tools- # installed instead of stripping them on every dependency bump).+ # bundle by default — pytest, pytest-asyncio, pytest-mock, respx, ruff.working-directory: serverrun: |uv sync- uv run pytest tests/ -v+ uv run pytest ${{ matrix.paths }} -v++ # ----------------------------------------------------------------------+ # cli-tests -- supervisor CLI pytest (small, fast, separate from backend)+ # ----------------------------------------------------------------------+ cli-tests:+ name: CLI tests+ needs: plan+ if: needs.plan.outputs.cli_changed == 'true' || needs.plan.outputs.workflows_changed == 'true'+ runs-on: ubuntu-latest+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup environment+ uses: ./.github/actions/setup- name: Supervisor CLI tests (pytest)- # 106 tests covering build/start/stop pipelines, daemon, ports, docs,- # release config, clean. Run from repo root — tests resolve workspace- # paths via `pnpm list --json` (see cli/tests/conftest.py).- # `pyyaml` is needed by test_release_pipeline_config.py to parse the- # workflow files; not a CLI runtime dep, only a test-time one.+ # 106 tests covering build/start/stop pipelines, daemon, ports,+ # docs, release config, clean. Run from repo root — tests+ # resolve workspace paths via `pnpm list --json`.+ # `pyyaml` is needed by test_release_pipeline_config.py to parse+ # the workflow files; not a CLI runtime dep, only a test-time one.run: |uv pip install --system pytest pytest-asyncio pyyamlpython -m pytest cli/tests/ -v- # Test build and start from source (cross-platform)+ # ----------------------------------------------------------------------+ # test-build-start -- cross-OS build + start smoke test+ # ----------------------------------------------------------------------test-build-start:+ name: Build + start (${{ matrix.os }})+ needs: plan+ # Always runs unless the change is doc-only -- catches platform-+ # specific build regressions (Windows path handling, macOS arm+ # binary fallbacks, etc.) that can't be ID'd from Linux alone.+ if: needs.plan.outputs.docs_only != 'true'runs-on: ${{ matrix.os }}strategy:fail-fast: false@@ -73,7 +216,7 @@ jobs:os: [ubuntu-latest, macos-latest, windows-latest]steps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup environmentuses: ./.github/actions/setup@@ -137,3 +280,30 @@ jobs:Receive-Job $jobexit 1}++ # ----------------------------------------------------------------------+ # ci-passed -- single aggregator job; the one branch protection rule+ # points at. Matrix dimensions can grow/shrink without breaking+ # protection (hatch pattern).+ # ----------------------------------------------------------------------+ ci-passed:+ name: CI passed+ if: always()+ needs:+ - plan+ - pre-commit+ - build-and-lint+ - backend-tests+ - cli-tests+ - test-build-start+ runs-on: ubuntu-latest+ steps:+ - name: Check all jobs passed (or were skipped intentionally)+ # alls-green treats `skipped` as success when listed in+ # `allowed-skips`. Without this, a doc-only PR that skips+ # backend-tests would fail the aggregator -- defeating the+ # plan-job optimisation.+ uses: re-actors/alls-green@afee1c1eac2a506084c274e9c02c8e0687b48d9e # v1.2.2+ with:+ allowed-skips: pre-commit, build-and-lint, backend-tests, cli-tests, test-build-start+ jobs: ${{ toJSON(needs) }}diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.ymlnew file mode 100644index 00000000..0b6a468b--- /dev/null+++ b/.github/workflows/publish-pypi.yml@@ -0,0 +1,148 @@+# Reusable workflow: publish machinaos-server to PyPI via OIDC.+#+# Called from release.yml after the npm publish step succeeds. Uses+# PyPI Trusted Publishing (https://docs.pypi.org/trusted-publishers/)+# so no PYPI_TOKEN secret is needed -- the workflow's OIDC token is+# exchanged for a short-lived publish token at PyPI's side.+#+# One-time admin step to enable this:+# 1. On PyPI -> Account -> Publishing -> "Add a new pending+# publisher", set:+# repo: zeenie-ai/MachinaOS+# workflow file: publish-pypi.yml+# environment: pypi+# 2. Push a tag to trigger the first release -- PyPI promotes the+# pending publisher to active on first successful exchange.+#+# Pattern lifted from PrefectHQ/prefect + pypa/hatch. uv itself uses+# `uv publish` directly; we prefer pypa/gh-action-pypi-publish for+# cleaner OIDC integration + audit-tab visibility.++name: Publish to PyPI++on:+ workflow_call:+ inputs:+ package_dir:+ description: 'Directory containing the package to publish (relative to repo root).'+ type: string+ default: 'server'+ dry_run:+ description: 'Build the wheel but skip the upload step.'+ type: boolean+ default: false++permissions:+ contents: read++jobs:+ build:+ name: Build wheel + sdist+ runs-on: ubuntu-latest+ outputs:+ dist_path: ${{ steps.locate.outputs.dist_path }}+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup Python+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5+ with:+ python-version: '3.12'+ # cache: false in release jobs (wrangler hardening) -- a+ # poisoned pip cache would taint the wheel.+ cache: ''++ - name: Install uv+ uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0++ - name: Build wheel + sdist+ # `uv build` produces both wheel + sdist by default. Outputs+ # land in `<package_dir>/dist/`. The release flow uses+ # `--no-sources` to ensure no editable-install metadata+ # leaks into the published artifact.+ working-directory: ${{ inputs.package_dir }}+ run: uv build --no-sources++ - name: Locate dist directory+ id: locate+ run: |+ echo "dist_path=${{ inputs.package_dir }}/dist" >> "$GITHUB_OUTPUT"++ - name: Upload dist artifact+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4+ with:+ name: pypi-dist+ path: ${{ inputs.package_dir }}/dist/+ retention-days: 1++ attest:+ name: Generate SLSA build provenance+ needs: build+ runs-on: ubuntu-latest+ permissions:+ # OIDC token issuance for attestation signing.+ id-token: write+ # Required to write the attestation back to the GitHub+ # attestations endpoint.+ attestations: write+ contents: read+ steps:+ - name: Download dist+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4+ with:+ name: pypi-dist+ path: dist/++ - name: Attest build provenance+ # Pattern from astral-sh/uv's release workflow. Each wheel ++ # sdist gets its own attestation in the GitHub transparency+ # log; verifiable via `gh attestation verify`.+ uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2+ with:+ subject-path: 'dist/*'++ publish:+ name: Publish to PyPI+ needs: [build, attest]+ if: inputs.dry_run != true+ runs-on: ubuntu-latest++ # Environment binds the OIDC subject claim to a PyPI trusted+ # publisher named "pypi" (configured on PyPI's side -- see+ # docstring). PyPI rejects exchange attempts from any other env.+ environment:+ name: pypi+ url: https://pypi.org/p/machinaos-server++ permissions:+ # Required for the OIDC token exchange with PyPI.+ id-token: write++ steps:+ - name: Download dist+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4+ with:+ name: pypi-dist+ path: dist/++ - name: Publish to PyPI+ # pypa/gh-action-pypi-publish handles the OIDC exchange + upload.+ # `print-hash: true` writes the SHA-256 of each artifact to the+ # job log so reviewers can cross-check what landed on PyPI+ # against what the build job produced.+ uses: pypa/gh-action-pypi-publish@6733eb7d741f0b11ec6a39b58540dab7590f9b7d # v1.14.0+ with:+ packages-dir: dist/+ print-hash: true+ # Skip-existing avoids a failure when a tag is re-run after+ # PyPI already has the version (e.g. partial-success replay).+ skip-existing: true++ publish-dry-run-notice:+ name: Dry-run notice+ needs: build+ if: inputs.dry_run == true+ runs-on: ubuntu-latest+ steps:+ - run: echo "::notice::publish-pypi.yml dry_run=true -- PyPI upload skipped. Build + attest succeeded."diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex cfb08a61..19ec11e7 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -1,4 +1,20 @@# Release workflow - predeploy gate, publish, GitHub release, then test install+#+# Hardening (May 2026, lifted from gh CLI / vercel / wrangler / uv):+# - workflow_dispatch defaults to dry-run; pushes need explicit+# dry_run=false (gemini-cli pattern; reduces accidental+# publications from an admin clicking Run workflow).+# - NPM_CONFIG_PROVENANCE=true via env (idiom from vercel) instead+# of the per-command --provenance flag; survives any future+# npm publish callsite change.+# - SLSA build provenance attestation via actions/attest-build-+# provenance@v2 (uv + gh CLI pattern). Renders on the GitHub+# release as a verifiable supply-chain claim.+# - Cache disabled in release-only setup steps (wrangler pattern)+# to prevent a poisoned cache from previous CI runs from+# contaminating the release tarball.+# - pnpm audit is now BLOCKING; the old `|| true` swallowed+# vulnerabilities.name: Release@@ -6,6 +22,11 @@ on:push:tags: ['v*.*.*']workflow_dispatch:+ inputs:+ dry_run:+ description: 'Skip the publish step (validate only).'+ type: boolean+ default: true# Top-level permissions for all jobs (jobs can narrow further)permissions:@@ -13,6 +34,17 @@ permissions:packages: writeid-token: write+# `dry_run` is only meaningful on workflow_dispatch; tag-pushed+# releases always publish. Computed once and surfaced to each+# publish job via `if:` gates below.+env:+ IS_DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}+ # Enables npm provenance for every `npm publish` in this workflow+ # (https://docs.npmjs.com/generating-provenance-statements). Vercel+ # pattern -- supersedes --provenance per-command flag so any future+ # publish callsite picks it up automatically.+ NPM_CONFIG_PROVENANCE: 'true'+jobs:predeploy:uses: ./.github/workflows/predeploy.yml@@ -24,13 +56,17 @@ jobs:runs-on: ubuntu-lateststeps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup environmentuses: ./.github/actions/setup- name: Audit production dependencies- run: pnpm audit --prod || true+ # BLOCKING: a vulnerability in a prod dep must stop the release+ # (previous `|| true` masked everything). To temporarily bypass,+ # bump the audit-level threshold rather than re-introducing the+ # silent fail.+ run: pnpm audit --prod --audit-level moderate# Build client once after predeploy passes, share with publish jobsbuild-for-publish:@@ -39,7 +75,7 @@ jobs:runs-on: ubuntu-lateststeps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup environmentuses: ./.github/actions/setup@@ -50,7 +86,7 @@ jobs:pnpm --filter react-flow-client run build- name: Upload built client- uses: actions/upload-artifact@v4+ uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4with:name: client-distpath: client/dist@@ -65,16 +101,20 @@ jobs:id-token: writesteps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: '22'registry-url: 'https://registry.npmjs.org'+ # cache: false in release jobs (wrangler hardening). A+ # poisoned cache from previous CI runs cannot taint the+ # tarball; release-time installs always pull fresh.+ cache: ''- name: Download built client- uses: actions/download-artifact@v4+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4with:name: client-distpath: client/dist@@ -83,21 +123,42 @@ jobs:run: npm install --ignore-scripts- name: Setup Python- uses: actions/setup-python@v5+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5with:- python-version: '3.12'+ python-version-file: .python-version- name: Sync versions from git tagrun: python -m cli version sync- - name: Verify package contents- run: npm pack --dry-run+ - name: Verify package contents (and pack for attestation)+ # `npm pack` (without --dry-run) writes the tarball to disk so+ # we can attest it. The tarball name pattern is+ # `<scoped-name-with-dash>-<version>.tgz`, e.g. `machinaos-0.0.72.tgz`.+ run: npm pack++ - name: Generate SLSA build provenance for the npm tarball+ # Pattern from gh CLI + uv: attest-build-provenance signs the+ # artifact via the workflow's OIDC token, publishes the+ # attestation to GitHub's transparency log + Sigstore, and+ # links it to the release. Verifiable via+ # `gh attestation verify <tarball> --repo <owner>/<repo>`.+ if: env.IS_DRY_RUN != 'true'+ uses: actions/attest-build-provenance@96b4a1ef7235a096b17240c259729fdd70c83d45 # v2+ with:+ subject-path: '*.tgz'- - name: Publish to npm with provenance- run: npm publish --access public --provenance+ - name: Publish to npm+ # NPM_CONFIG_PROVENANCE env (top of workflow) enables provenance+ # for `npm publish` -- no per-command flag needed.+ if: env.IS_DRY_RUN != 'true'+ run: npm publish --access publicenv:NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ - name: Dry-run -- skipping npm publish+ if: env.IS_DRY_RUN == 'true'+ run: echo "::notice::workflow_dispatch dry_run=true -- publish step skipped. Re-run with dry_run=false to publish."+publish-github-packages:name: Publish to GitHub Packagesneeds: build-for-publish@@ -107,16 +168,18 @@ jobs:packages: writesteps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: '22'registry-url: 'https://npm.pkg.github.com'+ # cache: false in release jobs (wrangler hardening).+ cache: ''- name: Download built client- uses: actions/download-artifact@v4+ uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4with:name: client-distpath: client/dist@@ -125,9 +188,9 @@ jobs:run: npm install --ignore-scripts- name: Setup Python- uses: actions/setup-python@v5+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5with:- python-version: '3.12'+ python-version-file: .python-version- name: Sync versions from git tagrun: python -m cli version sync@@ -142,20 +205,43 @@ jobs:"- name: Publish to GitHub Packages+ if: env.IS_DRY_RUN != 'true'run: npm publishenv:NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ - name: Dry-run -- skipping GitHub Packages publish+ if: env.IS_DRY_RUN == 'true'+ run: echo "::notice::workflow_dispatch dry_run=true -- GitHub Packages publish step skipped."++ # Publish machinaos-server to PyPI via OIDC trusted publishing.+ # Runs in parallel with the npm publish jobs after the build-for-publish+ # step succeeds. Dry-run propagates from this workflow's input.+ publish-pypi:+ name: Publish to PyPI+ needs: [predeploy, audit]+ permissions:+ contents: read+ id-token: write+ attestations: write+ uses: ./.github/workflows/publish-pypi.yml+ with:+ package_dir: server+ dry_run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}+# Create GitHub Release with auto-generated notescreate-github-release:name: Create GitHub Release- needs: [publish-npm, publish-github-packages]+ needs: [publish-npm, publish-github-packages, publish-pypi]+ # Skipped during dry-run -- there's no published release to point at+ # and we don't want to leave stale release notes around.+ if: needs.publish-npm.result == 'success' && github.event.inputs.dry_run != 'true'runs-on: ubuntu-latestpermissions:contents: writesteps:- name: Checkout- uses: actions/checkout@v4+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4with:fetch-depth: 0@@ -172,7 +258,9 @@ jobs:--generate-notes \--verify-tag- # Test user installation after publishing+ # Test user installation after publishing (skipped on dry-run since+ # there's nothing newly published to install).test-install:needs: [create-github-release]+ if: needs.create-github-release.result == 'success'uses: ./.github/workflows/test-install.ymldiff --git a/.github/workflows/rollback.yml b/.github/workflows/rollback.ymlnew file mode 100644index 00000000..40c81554--- /dev/null+++ b/.github/workflows/rollback.yml@@ -0,0 +1,176 @@+# Release rollback workflow.+#+# Manual `workflow_dispatch`. Given a published version, marks the+# corresponding npm tarball as deprecated with a stable message and+# (optionally) opens a revert-the-release-commit PR so subsequent+# CI can ship a fixed version. Pattern lifted from vercel/vercel ++# google-gemini/gemini-cli rollback workflows.+#+# What this DOESN'T do (deliberate):+# - It does not delete the npm publication. npm policy disallows+# un-publishing public packages older than 72 hours; for fresh+# publications, `npm unpublish` is permitted but breaks every+# downstream consumer relying on the version. `npm deprecate`+# is the standard rollback verb -- the install still works for+# anyone with a lockfile, but new installs surface a warning.+# - It does not yank from PyPI. PyPI has `pip install` shim for+# a yank semantic but it requires manual action through the+# PyPI admin UI -- see https://docs.pypi.org/help/#yanked.+# - It does not delete the GitHub release. We keep the tag for+# forensics; rollback adds a stable note to the release body.+#+# Inputs (only `version` is required):+# version — semver tag to roll back, e.g. "v0.0.72"+# deprecate_msg — message npm shows during install/list. Defaults+# to a security-conservative template.+# open_revert_pr — if true, also open a PR reverting the release+# commit. Default false; usually you want to ship+# a forward fix.++name: Rollback Release++on:+ workflow_dispatch:+ inputs:+ version:+ description: 'Version to roll back (e.g. v0.0.72).'+ type: string+ required: true+ deprecate_msg:+ description: 'npm deprecation notice shown to installers.'+ type: string+ default: 'This version has been deprecated by the maintainers. Please install the latest version.'+ open_revert_pr:+ description: 'Open a PR reverting the release commit.'+ type: boolean+ default: false++permissions:+ contents: read++jobs:+ deprecate-npm:+ name: npm deprecate+ runs-on: ubuntu-latest+ # No id-token needed -- this uses NPM_TOKEN, not OIDC, because+ # `npm deprecate` is not in the trusted-publisher allowlist.+ permissions:+ contents: read+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4++ - name: Setup Node.js+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4+ with:+ node-version: '22'+ registry-url: 'https://registry.npmjs.org'+ cache: ''++ - name: Normalise version+ id: ver+ # `npm deprecate` wants a bare semver (e.g. 0.0.72), not a tag+ # (e.g. v0.0.72). Strip the leading `v` if present.+ run: |+ v="${{ inputs.version }}"+ v="${v#v}"+ echo "semver=${v}" >> "$GITHUB_OUTPUT"++ - name: Deprecate on npm (unscoped)+ env:+ NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}+ run: |+ npm deprecate \+ "machinaos@${{ steps.ver.outputs.semver }}" \+ "${{ inputs.deprecate_msg }}"++ - name: Deprecate on GitHub Packages (scoped)+ env:+ NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ run: |+ npm config set @zeenie-ai:registry https://npm.pkg.github.com+ npm deprecate \+ "@zeenie-ai/machinaos@${{ steps.ver.outputs.semver }}" \+ "${{ inputs.deprecate_msg }}"++ yank-pypi-notice:+ name: PyPI yank reminder+ runs-on: ubuntu-latest+ permissions:+ contents: read+ steps:+ - name: Print PyPI yank instructions+ # PyPI yank is gated on UI access -- no API path that the+ # release token can take. Emit a notice so the operator+ # remembers to do this by hand.+ run: |+ echo "::notice title=Manual PyPI yank required::Yank machinaos-server@${{ inputs.version }} via https://pypi.org/manage/project/machinaos-server/release/${{ inputs.version }}/ -- 'Options' -> 'Yank'."++ open-revert-pr:+ name: Open revert PR+ needs: deprecate-npm+ if: inputs.open_revert_pr == true+ runs-on: ubuntu-latest+ permissions:+ contents: write+ pull-requests: write+ steps:+ - name: Checkout+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+ with:+ fetch-depth: 0++ - name: Resolve release commit+ id: commit+ # The release commit is the one the tag points at. `git+ # rev-list -n1 <tag>` works regardless of whether the tag+ # is annotated or lightweight.+ run: |+ sha=$(git rev-list -n1 "${{ inputs.version }}")+ echo "sha=${sha}" >> "$GITHUB_OUTPUT"++ - name: Create revert branch + commit+ env:+ GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}+ run: |+ branch="rollback/${{ inputs.version }}"+ git config user.name "github-actions[bot]"+ git config user.email "github-actions[bot]@users.noreply.github.com"+ git checkout -b "${branch}"+ git revert --no-edit "${{ steps.commit.outputs.sha }}"+ git push origin "${branch}"++ gh pr create \+ --base main \+ --head "${branch}" \+ --title "Revert: ${{ inputs.version }} (rollback)" \+ --body "Automated revert of ${{ inputs.version }}.++ npm package deprecated via rollback.yml.+ PyPI yank pending manual action -- see https://pypi.org/manage/project/machinaos-server/.++ Reason: ${{ inputs.deprecate_msg }}"++ summary:+ name: Rollback summary+ needs: [deprecate-npm, yank-pypi-notice]+ if: always()+ runs-on: ubuntu-latest+ steps:+ - name: Print summary+ run: |+ {+ echo "## Rollback summary for ${{ inputs.version }}"+ echo ""+ echo "| Step | Status |"+ echo "|---|---|"+ echo "| npm deprecate | ${{ needs.deprecate-npm.result }} |"+ echo "| PyPI yank reminder | ${{ needs.yank-pypi-notice.result }} |"+ echo "| Revert PR | ${{ inputs.open_revert_pr == true && 'requested' || 'skipped (open_revert_pr=false)' }} |"+ echo ""+ echo "Next steps:"+ echo ""+ echo "1. Manually yank \`machinaos-server@${{ inputs.version }}\` from PyPI."+ echo "2. If shipping a forward fix, bump version and re-run release.yml."+ echo "3. If reverting, merge the rollback PR (if requested)."+ } >> "$GITHUB_STEP_SUMMARY"diff --git a/.github/workflows/test-install.yml b/.github/workflows/test-install.ymlindex 5a3951f0..0ba3bf68 100644--- a/.github/workflows/test-install.yml+++ b/.github/workflows/test-install.yml@@ -19,20 +19,27 @@ jobs:matrix:os: [ubuntu-latest, macos-latest, windows-latest]steps:+ - name: Checkout+ # Required so .python-version is on disk for setup-python below.+ # The actual MachinaOS install under test comes from npm / a+ # separate git clone -- this checkout is only used to source+ # the toolchain version file (single source of truth).+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+- name: Setup pnpm- uses: pnpm/action-setup@v4+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4with:version: 9- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: '22'- name: Setup Python- uses: actions/setup-python@v5+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5with:- python-version: '3.12'+ python-version-file: .python-version- name: Install uvrun: pip install uv@@ -116,20 +123,27 @@ jobs:matrix:os: [ubuntu-latest, macos-latest, windows-latest]steps:+ - name: Checkout+ # Required so .python-version is on disk for setup-python below.+ # The actual MachinaOS install under test comes from npm / a+ # separate git clone -- this checkout is only used to source+ # the toolchain version file (single source of truth).+ uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4+- name: Setup pnpm- uses: pnpm/action-setup@v4+ uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4with:version: 9- name: Setup Node.js- uses: actions/setup-node@v4+ uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4with:node-version: '22'- name: Setup Python- uses: actions/setup-python@v5+ uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5with:- python-version: '3.12'+ python-version-file: .python-version- name: Install uvrun: pip install uvdiff --git a/.gitignore b/.gitignoreindex 06776524..66abbfcb 100644--- a/.gitignore+++ b/.gitignore@@ -113,7 +113,10 @@ venv/# uv (Python package manager)uv.lockserver/uv.lock-.python-version+# .python-version at the repo root IS tracked -- it's the project-wide+# toolchain pin (read by uv, pyenv, asdf, AND ``setup-python`` via+# python-version-file: in our GitHub Actions workflows). Per-developer+# overrides live in server/.python-version (still ignored).server/.python-version# =============================================================================diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlnew file mode 100644index 00000000..a40f1195--- /dev/null+++ b/.pre-commit-config.yaml@@ -0,0 +1,91 @@+# pre-commit hooks shared across Python (ruff) + JS/TS (eslint, prettier)+# + workflow files (actionlint).+#+# Install once with: pre-commit install+# Run on all files: pre-commit run --all-files+# Update hook pins: pre-commit autoupdate+#+# Hook pins are revisions, not floating tags — pre-commit caches per+# revision, and Dependabot bumps these via the `github-actions`+# ecosystem (pre-commit-ci.com extends Dependabot's coverage to+# pre-commit's own rev pins via the same PR cadence).+#+# CI mirror: `predeploy.yml` runs `pre-commit run --all-files` so+# unfixed lint issues block merges even when a contributor skipped+# `pre-commit install` locally.++default_install_hook_types:+ - pre-commit+ - commit-msg++# Run hooks against staged files only by default; CI uses+# `pre-commit run --all-files` for full-tree validation.+default_stages: [pre-commit]++repos:+ # ---------------------------------------------------------------- stdlib+ - repo: https://github.com/pre-commit/pre-commit-hooks+ rev: v5.0.0+ hooks:+ - id: trailing-whitespace+ exclude: '\.md$' # Markdown trailing whitespace = line break+ - id: end-of-file-fixer+ - id: check-yaml+ args: ['--allow-multiple-documents']+ - id: check-toml+ - id: check-json+ - id: check-merge-conflict+ - id: check-added-large-files+ args: ['--maxkb=500'] # generous cap; binaries should live elsewhere+ - id: detect-private-key++ # ---------------------------------------------------------------- Python: ruff+ # Format + lint in one pass. Matches server/pyproject.toml's+ # [tool.ruff] config (line-length=140, ignores E402/E701).+ - repo: https://github.com/astral-sh/ruff-pre-commit+ rev: v0.8.4+ hooks:+ - id: ruff-format+ types_or: [python, pyi]+ - id: ruff+ args: ['--fix', '--exit-non-zero-on-fix']+ types_or: [python, pyi]++ # ---------------------------------------------------------------- JS/TS: prettier+ # Prettier owns formatting (semicolons, quote style, indent). ESLint+ # is invoked separately below for lint rules.+ - repo: https://github.com/pre-commit/mirrors-prettier+ rev: v4.0.0-alpha.8+ hooks:+ - id: prettier+ # Limit to the client/ workspace -- the server's TS sidecar+ # (server/nodejs/) is generated/copied and intentionally+ # unprettierified to keep diffs against upstream minimal.+ files: '^client/.*\.(ts|tsx|js|jsx|json|css|md)$'+ additional_dependencies:++ # ---------------------------------------------------------------- JS/TS: eslint+ # Run on staged TS/TSX files only. Full workspace lint runs in+ # predeploy.yml via `pnpm --filter react-flow-client run lint`.+ - repo: https://github.com/pre-commit/mirrors-eslint+ rev: v9.17.0+ hooks:+ - id: eslint+ files: '^client/src/.*\.(ts|tsx)$'+ additional_dependencies:+ # Match the ESLint major version in client/package.json so+ # plugin compatibility holds across the local + CI run.+ - eslint@9+ - typescript-eslint@8+ - eslint-plugin-react-hooks@5++ # ---------------------------------------------------------------- Workflows: actionlint+ # Catches GitHub Actions schema errors, shellcheck issues inside+ # `run:` blocks, and known anti-patterns (e.g. running an action+ # without a pinned version -- complements zizmor's deeper scan).+ - repo: https://github.com/rhysd/actionlint+ rev: v1.7.4+ hooks:+ - id: actionlintdiff --git a/.python-version b/.python-versionnew file mode 100644index 00000000..e4fba218--- /dev/null+++ b/.python-version@@ -0,0 +1 @@+3.12diff --git a/docs-internal/ci_cd.md b/docs-internal/ci_cd.mdindex a20dcd18..d2c62613 100644--- a/docs-internal/ci_cd.md+++ b/docs-internal/ci_cd.md@@ -1,328 +1,269 @@# CI/CD Pipeline-Internal reference for the GitHub Actions CI/CD pipeline. Covers all workflows, the shared composite action, predeploy validation, release publishing, and documentation deployment.+Internal reference for MachinaOs's GitHub Actions setup. Workflow inventory, security posture, release flow.----## Overview+## Workflow inventory```- +------------------+- push to main ---------> | ci.yml |---+- PR to main -----------> | | |- +------------------+ |- | +--------------------+- PR to main (Dockerfile +------------------+ +--> | predeploy.yml |- or compose changes) --> | docker-build.yml |---+--> | (reusable) |- +------------------+ | | |- | | - build-and-lint |- v*.*.* tag push ------> +------------------+ | | - docker-build |- GitHub release -------> | release.yml |---+ | - docker-compose |- manual dispatch ------> | | | - test-install |- | +-- predeploy --+ +--------------------+- | |- | +-- publish-npm ---------> npmjs.org (machina)- | +-- publish-github-pkgs -> GitHub Packages (@zeenie-ai/machina)- +------------------++ +------------------++ push to main ----------> | ci.yml |---++ PR to main ------------> | | |+ +------------------+ |+ | +---------------------++ +--> | predeploy.yml |+ | | (workflow_call) |+ v*.*.* tag push -------> +------------------+ | | |+ manual dispatch -------> | release.yml |---+ | - plan |+ | (dry-run by | | - pre-commit |+ | default for | | - build-and-lint |+ | manual runs) | | - backend-tests |+ +------------------+ | (3 shards) |+ | | - cli-tests |+ +-- predeploy | - test-build-start |+ +-- audit | (3 OS) |+ +-- build-for-publish| - ci-passed (alls) |+ +-- publish-npm +---------------------++ +-- publish-github-packages+ +-- publish-pypi --> publish-pypi.yml (reusable)+ +-- create-github-release+ +-- test-install --> test-install.yml++ manual dispatch -------> +------------------++ | rollback.yml | npm deprecate + (optional) revert PR+ +------------------+++ weekly + on PR --------> +------------------++ | codeql.yml | Python + JS/TS SAST (security-extended)+ +------------------+++ on .github changes ----> +------------------++ | check-zizmor.yml| workflow-security linter (SARIF)+ +------------------+push to docs-MachinaOs/ +------------------+- manual dispatch ------> | docs.yml |-------> Mintlify (docs site)- +------------------++ | docs.yml | Mintlify documentation deploy+ +------------------+```-### Workflow Summary+### Workflow summary| Workflow | File | Triggers | Purpose ||----------|------|----------|---------|-| CI | `.github/workflows/ci.yml` | Push to main, PRs to main | Validate every code change via predeploy |-| Docker Build | `.github/workflows/docker-build.yml` | PRs to main (Dockerfile/compose changes) | Validate Docker-specific changes via predeploy |-| Release | `.github/workflows/release.yml` | `v*.*.*` tags, GitHub releases, manual | Predeploy gate then publish to npm + GitHub Packages |-| Deploy Docs | `.github/workflows/docs.yml` | Push to `docs-MachinaOs/**` on main, manual | Deploy Mintlify documentation |-| Predeploy | `.github/workflows/predeploy.yml` | Called by other workflows (`workflow_call`) | Reusable validation: build, lint, Docker, cross-platform install |-| Setup Action | `.github/actions/setup/action.yml` | Used as composite action step | Shared Node.js + Python + uv environment setup |--### Required Secrets--| Secret | Used By | Description |+| CI | `.github/workflows/ci.yml` | push/PR → main | Delegates to predeploy.yml |+| Predeploy | `.github/workflows/predeploy.yml` | `workflow_call` | Plan + pre-commit + build/lint + sharded tests + OS-matrix build/start + alls-green |+| Release | `.github/workflows/release.yml` | `v*.*.*` tag, manual (dry-run default) | predeploy → audit → publish (npm + GH Packages + PyPI) → SLSA attest → release → test-install |+| Publish PyPI | `.github/workflows/publish-pypi.yml` | `workflow_call` | OIDC trusted publishing for `machinaos-server` |+| Test Install | `.github/workflows/test-install.yml` | manual, called from release | Cross-platform install smoke (3 OS × 3 paths) |+| Rollback | `.github/workflows/rollback.yml` | manual (`workflow_dispatch`) | npm deprecate + optional revert PR |+| CodeQL | `.github/workflows/codeql.yml` | push/PR + weekly Sun 20:30 UTC | Python + JS/TS SAST |+| Zizmor | `.github/workflows/check-zizmor.yml` | `.github/**` changes + weekly Mon 07:00 UTC | Workflow-security linter |+| Docs | `.github/workflows/docs.yml` | push to `docs-MachinaOs/**` | Mintlify deploy |+| Setup | `.github/actions/setup/action.yml` | (composite) | pnpm 9 + Node 22 + Python (from `.python-version`) + uv |++### Supply chain++- **All action `uses:` references are pinned to commit SHAs.** Enforced by [zizmor](https://github.com/woodruffw/zizmor) on every PR touching `.github/`. Dependabot rewrites pins via the `github-actions` ecosystem group.+- **`.github/dependabot.yml`** — weekly grouped updates for npm + pip (root + server/) + github-actions ecosystems. Each grouped PR is one ecosystem × one dependency-type.+- **`.pre-commit-config.yaml`** — ruff (format + lint), prettier (client/), eslint, actionlint, stdlib hygiene. Mirrored as a CI job in predeploy.yml so missed local installs still gate merges.+- **`.python-version`** — single source of truth (`3.12`). Consumed via `python-version-file:` in `setup-python` everywhere except the `test-install.yml` jobs which run after `actions/checkout` so the file is available.++### Required secrets++| Secret | Used by | Description ||--------|---------|-------------|-| `NPM_TOKEN` | release.yml | npm registry authentication for publishing |-| `GITHUB_TOKEN` | release.yml | GitHub Packages authentication (auto-provided by Actions) |-| `MINTLIFY_TOKEN` | docs.yml | Mintlify documentation deployment token |+| `NPM_TOKEN` | release.yml, rollback.yml | npm registry publish + deprecate |+| `GITHUB_TOKEN` | release.yml, rollback.yml | GitHub Packages publish + revert-PR creation (auto-provided) |+| `MINTLIFY_TOKEN` | docs.yml | Mintlify documentation deployment |----+PyPI publishing uses **OIDC trusted publishing** (no PYPI_TOKEN secret needed). One-time setup: configure MachinaOs as a trusted publisher on PyPI with workflow=`publish-pypi.yml`, environment=`pypi`.-## Composite Setup Action+----**File:** `.github/actions/setup/action.yml`+## Composite setup action-Shared environment setup used by `predeploy.yml` jobs. Eliminates duplicated Node/Python/uv installation across workflows.+**File:** [.github/actions/setup/action.yml](../.github/actions/setup/action.yml)```yaml-# Usage in workflow steps:- uses: ./.github/actions/setup- uses: ./.github/actions/setupwith:- node-version: '22'+ node-version: '20' # override Node only; Python tracks .python-version```-### What It Installs--| Tool | Default Version | Action Used |-|------|----------------|-------------|-| Node.js | 20 | `actions/setup-node@v4` (with npm cache) |-| Python | 3.12 | `actions/setup-python@v5` |-| uv | latest | `astral-sh/setup-uv@v4` |--### Inputs+| Tool | Version source | Action (pinned SHA) |+|------|---------------|---------------------|+| pnpm | hard-coded `9` (default) | `pnpm/action-setup` |+| Node.js | `node-version` input, default `22` | `actions/setup-node` |+| Python | `.python-version` file (`3.12`) | `actions/setup-python` |+| uv | latest in v8 line | `astral-sh/setup-uv` |-| Input | Default | Description |-|-------|---------|-------------|-| `node-version` | `'20'` | Node.js version to install |-| `python-version` | `'3.12'` | Python version to install |--Python and uv are needed because `postinstall.js` skips Python venv setup in CI, so they must be available for the `machina build` command in `test-install`.+After tool install, the composite installs the supervisor CLI editably (`uv pip install --system -e .`) and runs a verify step that prints each tool's version.----## Predeploy Validation--**File:** `.github/workflows/predeploy.yml`--The core reusable workflow. Triggered via `workflow_call` by `ci.yml`, `docker-build.yml`, and `release.yml`. Contains 4 jobs -- `build-and-lint`, `docker-build`, and `test-install` run in parallel; `docker-compose-test` depends on `docker-build`.--### Job: build-and-lint--Validates that the full project builds and the client passes linting.--| Step | Command | Description |-|------|---------|-------------|-| Checkout | `actions/checkout@v4` | Clone repo |-| Setup environment | `./.github/actions/setup` | Install Node.js 20, Python 3.12, uv |-| Build all services | `npm run build` | Full production build |-| Lint client | `cd client && npm run lint` | ESLint/TypeScript validation |+## Predeploy validation-### Job: docker-build+**File:** [.github/workflows/predeploy.yml](../.github/workflows/predeploy.yml)-Validates all 3 Docker images build successfully. Uses Docker Buildx with GitHub Actions cache for layer reuse.+Six jobs gated by a `plan` job that emits change-detection booleans (lifted from [astral-sh/uv's `ci.yml`](https://github.com/astral-sh/uv/blob/main/.github/workflows/ci.yml)):-| Image | Context | Dockerfile | Notes |-|-------|---------|------------|-------|-| Frontend | `./client` | `./client/Dockerfile` | Multi-stage build, `target: production` |-| Backend | `./server` | `./server/Dockerfile` | Python 3.12-slim |-| WhatsApp | `./docker` | `./docker/Dockerfile.whatsapp` | Node.js 20-alpine with whatsapp-rpc |+- `plan` — `dorny/paths-filter` decides which downstream jobs need to run. Boolean outputs: `backend_changed`, `frontend_changed`, `cli_changed`, `workflows_changed`, `docs_only`.+- `pre-commit` — runs `pre-commit run --all-files`. Catches lint/format issues for contributors who haven't installed the hook locally. Skipped for doc-only PRs (unless workflows also changed).+- `build-and-lint` — full `pnpm run build` + frontend tests (vitest, 148 cases) + ESLint + tsgo type-check. Skipped for doc-only PRs.+- `backend-tests` — pytest sharded by domain (prefect pattern):+ - `nodes` — `tests/nodes/`+ - `services` — `tests/services/` + `tests/temporal/` + `tests/llm/` + `tests/credentials/`+ - `root` — everything else (cross-cutting invariants)-All builds use:-- `docker/setup-buildx-action@v3`-- `docker/build-push-action@v6`-- `push: false` (validation only, no registry push)-- `cache-from: type=gha` / `cache-to: type=gha,mode=max` (GitHub Actions layer cache)+ Gated on `backend_changed || workflows_changed`. Each shard runs the same `uv sync` + `uv run pytest` pattern.+- `cli-tests` — 106 CLI tests via `python -m pytest cli/tests/`. Gated on `cli_changed || workflows_changed`.+- `test-build-start` — cross-OS (`ubuntu-latest`, `macos-latest`, `windows-latest`) build + start smoke. Verifies `client/dist/` + `server/.venv/` materialise and the supervisor brings up the backend reachable at `localhost:3010/health`. Skipped for doc-only PRs.+- `ci-passed` — single aggregator job using [`re-actors/alls-green`](https://github.com/re-actors/alls-green) (hatch pattern). Branch protection targets this one job name; matrix changes don't break protection rules. `allowed-skips` lets the plan-job optimisations skip downstream jobs without failing the aggregator.-### Job: docker-compose-test--**Depends on:** `docker-build`--Full-stack smoke test using the production Docker Compose configuration.--**Steps:**-1. Create `.env` from `.env.template`-2. Build with `docker compose -f docker-compose.prod.yml build`-3. Start services with `docker compose -f docker-compose.prod.yml up -d`-4. Health check loop (30 retries, 2s interval = 60s max):- - Backend: `curl -sf http://localhost:3010/health`- - Frontend: `curl -f http://localhost:3000`- - Print `docker compose ps` on success-5. On failure: dump all container logs-6. Always: `docker compose -f docker-compose.prod.yml down -v` (cleanup)+----### Job: test-install+## Release workflow-Cross-platform npm package installation and CLI validation.+**File:** [.github/workflows/release.yml](../.github/workflows/release.yml)-**Matrix:**+### Triggers+| Trigger | Behaviour |+|---------|-----------|+| Push of `v*.*.*` tag | Full release (npm + GH Packages + PyPI + SLSA attest + GitHub release + test-install) |+| `workflow_dispatch` | Dry-run by default; explicit `dry_run=false` required to publish (gemini-cli pattern) |-| Axis | Values |-|------|--------|-| OS | `ubuntu-latest`, `macos-latest`, `windows-latest` |-| Node.js | 20, 22 |+### Job graph-Total: **6 combinations**, `fail-fast: false` (all run regardless of individual failures).+```+predeploy (uses predeploy.yml)+ |+ v+audit -- pnpm audit --prod --audit-level moderate (BLOCKING)+ |+ v+build-for-publish -- once-per-release client build, uploaded as artifact+ | | |+ v v v+publish-npm publish-github-packages publish-pypi+ | | (uses publish-pypi.yml)+ +- SLSA +- npm scope rewrite +- uv build --no-sources+ +- attest-build-provenance@v2 +- attest-build-provenance@v2+ +- conditional on dry_run +- pypa/gh-action-pypi-publish+ +- OIDC, no token+ | | |+ v v v+create-github-release -- generate-notes + verify-tag (skipped on dry-run)+ |+ v+test-install (uses test-install.yml)+```-**Steps:**-1. Checkout-2. Setup environment (composite action with matrix `node-version`)-3. `npm pack` -- create tarball-4. `npm install -g machina-*.tgz` -- global install from tarball-5. `machina --help` -- verify CLI is available-6. `machina build` -- install client deps, build client, setup Python venv-7. Verify build artifacts exist at `$(npm root -g)/machina`:- - `.env` file- - `client/dist/` directory- - `server/.venv/` directory-8. `machina start &` -- start in background, wait 10s, verify process is still running+### Hardening (lifted from gh CLI + vercel + wrangler + uv)-All steps use `shell: bash` for cross-platform compatibility (Windows uses Git Bash).+- `NPM_CONFIG_PROVENANCE=true` set at workflow env-level — supersedes per-command `--provenance` flag.+- `pnpm audit --prod --audit-level moderate` is **blocking** (previous `|| true` masked vulnerabilities).+- `workflow_dispatch` defaults `dry_run=true`; explicit override required to publish.+- `cache: ''` on `setup-node` in publish jobs — prevents poisoned-cache supply-chain contamination (wrangler pattern).+- `actions/attest-build-provenance@v2` on every published artifact (npm tarball + Python wheel + sdist). SLSA Level 3. Verifiable via `gh attestation verify <artifact> --repo zeenie-ai/MachinaOS`.----## CI Workflow+## Reusable: publish-pypi.yml-**File:** `.github/workflows/ci.yml`+**File:** [.github/workflows/publish-pypi.yml](../.github/workflows/publish-pypi.yml)-Thin wrapper that delegates all validation to `predeploy.yml`.+Called via `workflow_call` from release.yml. Three jobs:-```yaml-on:- push:- branches: [main]- pull_request:- branches: [main]--jobs:- predeploy:- uses: ./.github/workflows/predeploy.yml-```+1. `build` — `uv build --no-sources` in `server/`, produces wheel + sdist, uploads artifact.+2. `attest` — `actions/attest-build-provenance@v2` signs each artifact via OIDC.+3. `publish` — `pypa/gh-action-pypi-publish` with `environment: pypi` for the OIDC subject claim. `skip-existing: true` so re-runs after partial failures don't error.-Every push to main and every PR targeting main runs the full predeploy suite (build, lint, Docker, cross-platform install).+Inputs:+- `package_dir` (default `server`)+- `dry_run` (boolean) — skips the publish job----## Docker Build Workflow+## Rollback workflow-**File:** `.github/workflows/docker-build.yml`+**File:** [.github/workflows/rollback.yml](../.github/workflows/rollback.yml)-Scoped validation for Docker-related changes. Only triggers when specific files are modified in a PR.+Manual `workflow_dispatch` with inputs:+- `version` (required, e.g. `v0.0.72`)+- `deprecate_msg` (default: security-conservative template)+- `open_revert_pr` (boolean, default `false`)-```yaml-on:- pull_request:- branches: [main]- paths:- - 'client/Dockerfile'- - 'server/Dockerfile'- - 'docker/Dockerfile.whatsapp'- - 'docker-compose*.yml'-```+Three jobs:+1. `deprecate-npm` — `npm deprecate` on both `machinaos@VERSION` (npm) and `@zeenie-ai/machinaos@VERSION` (GitHub Packages).+2. `yank-pypi-notice` — prints PyPI yank instructions (PyPI yank is UI-only, no API).+3. `open-revert-pr` — opens a `rollback/<version>` branch + revert PR (skipped unless `open_revert_pr=true`).-Delegates to `predeploy.yml`. Dockerfile changes in PRs get validated by both `ci.yml` (always runs on PRs) and `docker-build.yml` (path-scoped). The reusable workflow pattern and GHA caching make this overlap low-cost.+A `summary` job posts a step-summary table of what ran.----## Release Workflow--**File:** `.github/workflows/release.yml`--Publishes the npm package after predeploy validation passes.+## Security workflows-### Triggers--| Trigger | Condition |-|---------|-----------|-| Push tags | `v*.*.*` (e.g., `v1.0.0`, `v2.3.1`) |-| Release | GitHub release published |-| Manual | `workflow_dispatch` |+### CodeQL-### Job: predeploy (gate)--Calls `predeploy.yml` as a prerequisite. Both publish jobs require this to pass (`needs: predeploy`).--### Job: publish-npm--Publishes the unscoped `machina` package to the public npm registry.--```-npm install --ignore-scripts # Install deps without running postinstall-npm pack --dry-run # Verify package contents-npm publish --access public # Publish to npmjs.org-```+**File:** [.github/workflows/codeql.yml](../.github/workflows/codeql.yml)-Uses `NODE_AUTH_TOKEN` from `secrets.NPM_TOKEN`. Registry URL: `https://registry.npmjs.org`.+Two-language matrix:+- `python` — covers cli/, server/, scripts/.+- `javascript-typescript` — covers client/, server/nodejs/.-### Job: publish-github-packages+Triggers: push to main + PR to main (both with `paths-ignore` excluding docs) + weekly schedule (Sun 20:30 UTC). Query pack: `security-extended` (broader than default, narrower than `security-and-quality` which adds noisy code-quality queries).-Publishes the scoped `@zeenie-ai/machina` package to GitHub Packages.+### Zizmor-Requires `packages: write` permission. Before publishing, an inline Node.js script rewrites `package.json`:+**File:** [.github/workflows/check-zizmor.yml](../.github/workflows/check-zizmor.yml)-```javascript-// Executed at build time to scope the package name:-const pkg = require('./package.json');-pkg.name = '@zeenie-ai/machina';-pkg.publishConfig = { registry: 'https://npm.pkg.github.com' };-require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2));-```+Lints workflows for over-granted permissions, unpinned action `uses:`, insecure `${{ ... }}` template expansion, and `pull_request_target` + checkout-of-PR-ref combinations. Triggers on `.github/**` changes + weekly Mon 07:00 UTC (before the Mon 06:00 Dependabot batch).-Then publishes via `npm publish` with `GITHUB_TOKEN` as auth token. Registry URL: `https://npm.pkg.github.com`.+Outputs SARIF to the Security tab.----## Docs Workflow--**File:** `.github/workflows/docs.yml`+## Test-install workflow-Deploys the Mintlify documentation site when docs change.+**File:** [.github/workflows/test-install.yml](../.github/workflows/test-install.yml)-### Triggers--| Trigger | Condition |-|---------|-----------|-| Push | Changes to `docs-MachinaOs/**` on main branch |-| Manual | `workflow_dispatch` |+Validates the end-user install paths after a release publishes (or on manual dispatch). Three jobs × three OS = nine matrix cells:-### Steps+| Job | What it does |+|-----|--------------|+| `test-npm-install` | `npm install -g machinaos`, run `machina --help` / `--version`, smoke-start the backend |+| `test-git-clone` | `git clone` the public repo, `pnpm run build`, smoke-start |+| `test-install-script-unix` / `test-install-script-windows` | Curl/iwr the install script from the repo, validate the resulting `machina` is on PATH |-1. Checkout repo-2. Setup Node.js 20-3. `npm install -g mintlify` -- install Mintlify CLI-4. `mintlify deploy` -- deploy docs (working directory: `docs-MachinaOs`)--Uses `MINTLIFY_TOKEN` secret for authentication.+Each job runs an `actions/checkout` first so `.python-version` is available for `setup-python` — independent of the install path being tested.----## Workflow Dependency Graph+## Docs workflow-```-+------------------+ +---------------------+-| ci.yml |------->| |-| (push/PR main) | | predeploy.yml |-+------------------+ | (workflow_call) |- | |-+------------------+ | +-- build-and-lint |-| docker-build.yml |------->| +-- docker-build |-| (PR, Dockerfiles)| | +-- compose-test |-+------------------+ | +-- test-install |- | |-+------------------+ +---------------------+-| release.yml |------->| |-| (tags, releases) | | v-+------------------+ | +-- publish-npm- | +-- publish-github-packages- +---------------------+--+------------------+-| docs.yml |------> Mintlify deployment-| (docs-MachinaOs/)| (independent pipeline)-+------------------+-```+**File:** [.github/workflows/docs.yml](../.github/workflows/docs.yml)-### Key Design Decisions--- **Reusable `predeploy.yml`**: Single source of truth for validation logic. All entry-point workflows delegate to it, avoiding duplication.-- **Composite setup action**: Node.js, Python, and uv installation centralized in `.github/actions/setup/action.yml`. Workflows pass version overrides as inputs.-- **`fail-fast: false` in test-install**: All 6 OS/Node combinations run to completion, giving visibility into platform-specific failures even when one platform fails.-- **Docker layer caching via GHA**: `cache-from: type=gha` reuses layers across runs, reducing Docker build times.-- **Scoped `docker-build.yml`**: Prevents full Docker rebuild on every PR -- only triggers when Dockerfile or compose files change.-- **Dual npm publish**: Unscoped `machina` for public npm, scoped `@zeenie-ai/machina` for GitHub Packages. The scoped name is rewritten at publish time, not in source.+Triggers on push to `docs-MachinaOs/**` on main + manual dispatch. Single job: install Mintlify CLI, run `mintlify deploy` with `MINTLIFY_TOKEN`. No predeploy gate — docs are static, independent of the application's build.----## Source Files--| File | Lines | Description |-|------|-------|-------------|-| `.github/workflows/ci.yml` | 15 | CI entry point, delegates to predeploy |-| `.github/workflows/predeploy.yml` | 157 | Reusable validation (build, lint, Docker, install) |-| `.github/workflows/release.yml` | 73 | Predeploy gate + dual npm publish |-| `.github/workflows/docker-build.yml` | 18 | Docker-scoped PR validation |-| `.github/workflows/docs.yml` | 33 | Mintlify documentation deployment |-| `.github/actions/setup/action.yml` | 37 | Composite action: Node.js + Python + uv |+## Source files++| File | Purpose |+|------|---------|+| `.github/workflows/ci.yml` | CI entry point |+| `.github/workflows/predeploy.yml` | Reusable validation (plan + pre-commit + build/lint + tests + OS matrix + alls-green) |+| `.github/workflows/release.yml` | Tag-triggered release pipeline (dry-run default on manual) |+| `.github/workflows/publish-pypi.yml` | Reusable: build wheel + sdist + OIDC trusted publish |+| `.github/workflows/rollback.yml` | Manual deprecate + revert PR |+| `.github/workflows/codeql.yml` | SAST (Python + JS/TS) |+| `.github/workflows/check-zizmor.yml` | Workflow-security linter |+| `.github/workflows/test-install.yml` | Cross-platform user-install smoke |+| `.github/workflows/docs.yml` | Mintlify documentation deploy |+| `.github/actions/setup/action.yml` | Composite: pnpm + Node + Python + uv |+| `.github/dependabot.yml` | Weekly grouped updates (npm + pip × 2 + actions) |+| `.pre-commit-config.yaml` | ruff + prettier + eslint + actionlint hooks |+| `.python-version` | Toolchain pin (`3.12`) — single source of truth |