@mseep/open-computer-use 1.0.0

package/.github/workflows/docs-lint.yml

@@ -0,0 +1,151 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Documentation linters for `docs/architecture/` and top-level README/CLAUDE.md.
+#
+# Enforces the rules in CLAUDE.md "Documentation discipline":
+#   - YAML front-matter (status / last-reviewed / owner / applies-to) on every
+#     file under docs/architecture/.
+#   - markdownlint base style.
+#   - vale banned vocabulary, banned phrases, marketing-tone warnings.
+#   - lychee broken-link check (forward references to non-existent docs fail).
+#   - wc-budget caps: ADR ≤ 200, component ≤ 600, MANIFESTO ≤ 400.
+#   - AI-slop detector: TOC in short docs, reflexive Conclusion sections,
+#     stub headings.
+#   - ASCII-diagram detector: Mermaid required in docs/architecture/.
+
+name: docs-lint
+
+on:
+  pull_request:
+    paths:
+      - "docs/architecture/**"
+      - "CLAUDE.md"
+      - "README.md"
+      - "CONTRIBUTING.md"
+      - ".markdownlint.yaml"
+      - ".vale.ini"
+      - ".vale/**"
+      - "lychee.toml"
+      - "scripts/docs-lint/**"
+      - ".github/workflows/docs-lint.yml"
+  push:
+    branches:
+      - next/v1
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  self-test:
+    name: linter self-test (fixtures)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Run linter self-tests
+        run: bash scripts/docs-lint/test-linters.sh
+
+  front-matter:
+    name: front-matter validator
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Validate
+        run: bash scripts/docs-lint/front-matter-validator.sh
+
+  wc-budget:
+    name: line-count budget
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check
+        run: bash scripts/docs-lint/wc-budget.sh
+
+  ai-slop:
+    name: AI-slop detector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check
+        env:
+          LEXICON_DENYLIST: ${{ secrets.LEXICON_DENYLIST }}
+        run: bash scripts/docs-lint/ai-slop-detector.sh
+
+  tree-whitelist:
+    name: architecture-tree whitelist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check
+        run: bash scripts/docs-lint/architecture-tree-whitelist.sh
+
+  ascii-diagram:
+    name: ASCII diagram detector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Check
+        run: bash scripts/docs-lint/ascii-diagram-detector.sh
+
+  markdownlint:
+    name: markdownlint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run markdownlint
+        uses: DavidAnson/markdownlint-cli2-action@v18
+        with:
+          # Scope to architecture docs only. Top-level CLAUDE.md, README.md,
+          # and CONTRIBUTING.md are governed by "global rules" and were
+          # authored before this lint stack — bringing them into compliance
+          # is a separate cleanup task.
+          globs: "docs/architecture/**/*.md"
+          config: ".markdownlint.yaml"
+
+  vale:
+    name: vale prose linter
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run vale
+        uses: errata-ai/vale-action@v2.1.1
+        with:
+          version: 3.9.1
+          files: docs/architecture
+          fail_on_error: true
+
+  lychee:
+    name: lychee link checker
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          # We only care about *internal* / forward-reference link integrity.
+          # `--offline` skips all HTTP checks — external URLs (rate-limit
+          # surfaces) never block this gate. Inputs are positional.
+          args: >-
+            --config lychee.toml
+            --no-progress
+            --offline
+            'docs/architecture/**/*.md'
+          fail: true
+          failIfEmpty: false

package/.github/workflows/helm.yml

@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Lints the Helm chart on every PR / push to main, and publishes versioned
+# tarballs to a "gh-pages" Helm repo on release tags. Users can then:
+#
+#   helm repo add open-computer-use https://wide-moat.github.io/open-computer-use
+#   helm repo update
+#   helm install ocu open-computer-use/computer-use-server
+#
+# Chart version (helm/computer-use-server/Chart.yaml `version:`) must be bumped
+# for chart-releaser to publish. `appVersion:` tracks the repo version.
+
+name: Helm chart
+
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+    paths:
+      - 'helm/**'
+      - 'examples/helm/**'
+      - '.github/workflows/helm.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'helm/**'
+      - 'examples/helm/**'
+      - '.github/workflows/helm.yml'
+
+jobs:
+  lint:
+    name: helm lint + template
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: azure/setup-helm@v4
+        with:
+          version: v3.16.4   # Helm 3 LTS — chart-releaser-action does not yet ship a Helm 4 image
+                            # and Helm 3 lints/templates the chart identically for our purposes.
+
+      - name: helm lint (rejects missing required values)
+        run: |
+          set -e
+          # Should fail — schema requires either secrets.mcpApiKey or secrets.existingSecret.
+          if helm lint helm/computer-use-server 2>/dev/null; then
+            echo "BUG: helm lint should have failed with empty secrets" >&2
+            exit 1
+          fi
+          # Should pass with all required keys set
+          helm lint helm/computer-use-server \
+            --set secrets.mcpApiKey=test \
+            --set orchestrator.env.PUBLIC_BASE_URL=https://x.example.com
+          # Examples must lint cleanly
+          helm lint helm/computer-use-server -f examples/helm/standalone/values.yaml
+          helm lint helm/computer-use-server -f examples/helm/with-open-webui/values-computer-use.yaml
+
+      - name: helm template (default Kata path + runc fallback)
+        run: |
+          set -e
+          # Default — Kata is the supported runtime; chart defaults render it.
+          helm template ocu helm/computer-use-server \
+            -f examples/helm/standalone/values.yaml \
+            > /tmp/render-default.yaml
+          grep -q "runtimeClassName: kata-qemu" /tmp/render-default.yaml
+          grep -q "privileged: true" /tmp/render-default.yaml
+          grep -q "name: orchestrator" /tmp/render-default.yaml
+          grep -q "name: dind" /tmp/render-default.yaml
+          grep -q "name: cleanup" /tmp/render-default.yaml
+          # The Kata machinery must be present by default.
+          grep -q "dind-entrypoint.sh" /tmp/render-default.yaml
+          grep -q "volumeMode: Block" /tmp/render-default.yaml
+          grep -q "devicePath: /dev/var-lib-docker" /tmp/render-default.yaml
+          grep -q "storage-driver=fuse-overlayfs" /tmp/render-default.yaml
+          # Unsupported runc fallback — explicit opt-out of every Kata knob.
+          helm template ocu helm/computer-use-server \
+            --set secrets.mcpApiKey=t \
+            --set orchestrator.env.PUBLIC_BASE_URL=https://x \
+            --set orchestrator.runtimeClassName="" \
+            --set dind.privileged=null \
+            --set dind.kataInit.enabled=false \
+            --set dind.storageDriver=overlay2 \
+            --set persistence.varLibDocker.persistentVolume.enabled=false \
+            > /tmp/render-runc.yaml
+          grep -q "privileged: true" /tmp/render-runc.yaml
+          ! grep -q "runtimeClassName:" /tmp/render-runc.yaml
+          ! grep -q "dind-entrypoint.sh" /tmp/render-runc.yaml
+          ! grep -q "volumeMode: Block" /tmp/render-runc.yaml
+
+      - name: Install kubeconform and validate manifests against k8s schemas
+        env:
+          KUBECONFORM_VERSION: v0.6.7
+        run: |
+          curl -sSL "https://github.com/yannh/kubeconform/releases/download/${KUBECONFORM_VERSION}/kubeconform-linux-amd64.tar.gz" \
+            | sudo tar -xz -C /usr/local/bin kubeconform
+          kubeconform -strict -summary -kubernetes-version 1.30.0 /tmp/render-default.yaml
+          kubeconform -strict -summary -kubernetes-version 1.30.0 /tmp/render-runc.yaml
+
+  release:
+    name: Publish chart to gh-pages
+    needs: lint
+    runs-on: ubuntu-latest
+    # Only on stable release tags. SemVer pre-release suffixes (`-rc.N`,
+    # `-alpha.N`, `-beta.N`) are routed to OCI publish via release-chart.yml
+    # — they must NOT land on gh-pages, otherwise stable users running
+    # `helm repo update && helm install` would resolve them.
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && !contains(github.ref_name, '-')
+    permissions:
+      contents: write
+      pages: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0  # chart-releaser needs full history to detect tag bumps
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - uses: azure/setup-helm@v4
+        with:
+          version: v3.16.4
+
+      - uses: helm/chart-releaser-action@v1.7.0
+        with:
+          charts_dir: helm
+          mark_as_latest: true
+        env:
+          CR_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/.github/workflows/identity-lint.yml

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Identity gate. Runs on every PR and every push to the long-lived branches.
+# The project commits and authors under developer@widemoat.ai; a personal
+# address must not appear in tracked file content. The exact banned address is
+# defined in scripts/docs-lint/identity-email-detector.sh. Commit *metadata* is
+# enforced locally by the pre-push hook (scripts/githooks/pre-push); this is
+# the CI backstop for file content.
+
+name: identity-lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - next/v1
+
+permissions:
+  contents: read
+
+jobs:
+  identity-email:
+    name: identity-email detector
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check tracked content for the banned personal address
+        run: bash scripts/docs-lint/identity-email-detector.sh

package/.github/workflows/release-chart.yml

@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: FSL-1.1-Apache-2.0
+# Copyright (c) 2025 Open Computer Use Contributors
+#
+# Publishes the Helm chart as an OCI artifact in ghcr.io alongside the four
+# Docker images on every `v*` git tag. Pre-release tags (`v*-rc.*`, `v*-alpha.*`,
+# `v*-beta.*`) are pushed to the same OCI repo with their SemVer pre-release
+# suffix preserved — Helm itself excludes pre-releases from stable
+# `helm install` resolution unless --devel / explicit --version is passed, so
+# this does not contaminate users running plain `helm repo update && helm
+# install`.
+#
+# This complements (does not replace) helm.yml's chart-releaser-action, which
+# only publishes when Chart.yaml.version bumps and targets gh-pages. RCs are
+# distributed via OCI because they live alongside the image tags and the
+# tag-driven flow doesn't require Chart.yaml commits.
+#
+# Operator install for an RC:
+#   helm install ocu-rc oci://ghcr.io/wide-moat/charts/computer-use-server \
+#     --version 0.1.0-rc.1 \
+#     -f my-values.yaml \
+#     --set image.tag=0.9.2.5-rc.1 \
+#     --set workspaceImage.tag=0.9.2.5-rc.1 \
+#     --set cleanup.image.tag=0.9.2.5-rc.1
+
+name: Release Helm Chart (OCI)
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Chart version to publish (SemVer, e.g. 0.1.0-rc.1)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  CHART_PATH: helm/computer-use-server
+  OCI_REPO: oci://ghcr.io/${{ github.repository_owner }}/charts
+
+jobs:
+  publish:
+    name: Package and push chart to OCI
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: azure/setup-helm@v4
+        with:
+          version: v3.16.4
+
+      - name: Resolve chart version + app version
+        id: ver
+        run: |
+          # Two distinct versions per Helm spec:
+          # - app_version: free-form, matches our project's 4-segment scheme
+          #   (e.g. 0.9.2.5-rc.1) and the docker image tags. This is what
+          #   appears in `helm list` and `appVersion:` in Chart.yaml.
+          # - chart_version: strict SemVer (3 segments + optional pre-release).
+          #   This is what `helm install --version` resolves against.
+          #
+          # Mapping rule: keep the chart at 0.X.Y matching what's already in
+          # Chart.yaml, and carry the pre-release suffix from the tag onto
+          # both versions. So tag v0.9.2.5-rc.1 → chart_version
+          # 0.1.1-rc.1 (next chart patch) only when the suffix has changed
+          # relative to the committed chart version. For RC publishing we
+          # take a shortcut: derive chart_version by stripping the leading
+          # 4th segment from the tag and re-attaching the suffix.
+
+          if [ -n "${{ inputs.version }}" ]; then
+            # Normalize dispatch input — strip an optional leading `v` so users
+            # can paste either `v0.9.2.5-rc.1` or `0.9.2.5-rc.1`.
+            tag_v="${{ inputs.version }}"
+            tag_v="${tag_v#v}"
+          elif [ "${{ github.ref_type }}" = "tag" ]; then
+            tag_v="${GITHUB_REF_NAME#v}"
+          else
+            echo "No version source: not a tag push and no dispatch input." >&2
+            exit 1
+          fi
+
+          # Split tag into base (4-segment) and suffix (-rc.1 etc.)
+          base="${tag_v%%-*}"  # 0.9.2.5
+          suffix=""
+          case "$tag_v" in
+            *-*) suffix="-${tag_v#*-}" ;;  # -rc.1
+          esac
+
+          # Count dots — Helm chart version must be 3 segments.
+          # `wc -c` pads with spaces on BSD-coreutils; strip them.
+          segs=$(echo -n "$base" | tr -cd '.' | wc -c | tr -d ' ')
+          if [ "$segs" = "3" ]; then
+            # 0.9.2.5 → drop the 4th to get 0.9.2 for chart
+            chart_base=$(echo "$base" | cut -d. -f1-3)
+          elif [ "$segs" = "2" ]; then
+            chart_base="$base"
+          else
+            echo "Unsupported version shape: $tag_v" >&2
+            exit 1
+          fi
+          chart_v="${chart_base}${suffix}"
+
+          echo "app_version=$tag_v" >> "$GITHUB_OUTPUT"
+          echo "chart_version=$chart_v" >> "$GITHUB_OUTPUT"
+          if [ -n "$suffix" ]; then
+            echo "prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+          echo "Resolved: app_version=$tag_v chart_version=$chart_v prerelease=${suffix:+true}${suffix:-false}"
+
+      - name: Stamp Chart.yaml version + appVersion (in-CI, not committed)
+        run: |
+          sed -i "s/^version:.*/version: ${{ steps.ver.outputs.chart_version }}/" \
+            "${{ env.CHART_PATH }}/Chart.yaml"
+          sed -i "s/^appVersion:.*/appVersion: \"${{ steps.ver.outputs.app_version }}\"/" \
+            "${{ env.CHART_PATH }}/Chart.yaml"
+          echo "--- Chart.yaml after stamp ---"
+          grep -E '^(version|appVersion):' "${{ env.CHART_PATH }}/Chart.yaml"
+
+      - name: helm lint (sanity)
+        run: |
+          # Lint with a placeholder API key — schema requires either mcpApiKey
+          # or existingSecret to be non-empty; we're not publishing values.yaml
+          # so this is purely a schema-level check.
+          helm lint "${{ env.CHART_PATH }}" \
+            --set secrets.mcpApiKey=lint-only \
+            --set orchestrator.env.PUBLIC_BASE_URL=https://lint.example.com
+
+      - name: helm package
+        run: |
+          mkdir -p /tmp/chart-out
+          helm package "${{ env.CHART_PATH }}" -d /tmp/chart-out
+          ls -la /tmp/chart-out
+
+      - name: Log in to GHCR
+        run: |
+          echo "${{ secrets.GITHUB_TOKEN }}" \
+            | helm registry login ghcr.io -u "${{ github.actor }}" --password-stdin
+
+      - name: helm push to OCI
+        run: |
+          chart_tgz=$(ls /tmp/chart-out/computer-use-server-*.tgz | head -n1)
+          # OCI_REPO lower-cases the owner — ghcr requires lowercase namespace.
+          repo="$(echo "${{ env.OCI_REPO }}" | tr '[:upper:]' '[:lower:]')"
+          helm push "$chart_tgz" "$repo"
+
+      - name: Summary
+        run: |
+          repo="$(echo "${{ env.OCI_REPO }}" | tr '[:upper:]' '[:lower:]')"
+          cat >> "$GITHUB_STEP_SUMMARY" <<EOF
+          ## Helm chart published
+
+          - **Chart:** \`computer-use-server\`
+          - **Chart version:** \`${{ steps.ver.outputs.chart_version }}\` (SemVer, drives \`helm install --version\`)
+          - **App version (Docker tag):** \`${{ steps.ver.outputs.app_version }}\`
+          - **Pre-release:** \`${{ steps.ver.outputs.prerelease }}\`
+          - **OCI URL:** \`${repo}/computer-use-server:${{ steps.ver.outputs.chart_version }}\`
+
+          ### Install command
+
+          \`\`\`bash
+          helm install ocu ${repo}/computer-use-server \\
+            --version ${{ steps.ver.outputs.chart_version }} \\
+            -f my-values.yaml \\
+            --set image.tag=${{ steps.ver.outputs.app_version }} \\
+            --set workspaceImage.tag=${{ steps.ver.outputs.app_version }} \\
+            --set cleanup.image.tag=${{ steps.ver.outputs.app_version }}
+          \`\`\`
+
+          > Note: the Docker images are pushed by \`.github/workflows/build.yml\`
+          > in parallel — wait for that workflow to finish before running \`helm install\`.
+          EOF

package/.github/workflows/release.yml

@@ -0,0 +1,95 @@
+name: Release
+
+on:
+  push:
+    tags: ['v*']
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - name: Generate changelog
+        id: changelog
+        run: |
+          PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
+          if [ -z "$PREV_TAG" ]; then
+            CHANGES=$(git log --oneline --no-merges)
+          else
+            CHANGES=$(git log --oneline --no-merges ${PREV_TAG}..HEAD)
+          fi
+          echo "changes<<EOF" >> $GITHUB_OUTPUT
+          echo "$CHANGES" >> $GITHUB_OUTPUT
+          echo "EOF" >> $GITHUB_OUTPUT
+
+      - name: Detect pre-release tag
+        id: prerelease
+        run: |
+          # Strip leading v; if what's left contains a SemVer pre-release suffix
+          # (`-rc.1`, `-alpha.2`, `-beta.0`, `-dev.X`), mark the GitHub Release
+          # as a pre-release so the "Latest release" badge keeps pointing at
+          # the most recent stable version.
+          # Accept both 3-segment SemVer (`1.2.3-rc.1`) and the project's
+          # 4-segment app-version scheme (`0.8.12.3-rc.1`). Any pre-release
+          # suffix flips the release to "pre-release" in GitHub so the
+          # "Latest" badge keeps tracking stable.
+          v="${GITHUB_REF_NAME#v}"
+          if echo "$v" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+(\.[0-9]+)?-[A-Za-z0-9.]+$'; then
+            echo "is_prerelease=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_prerelease=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          prerelease: ${{ steps.prerelease.outputs.is_prerelease == 'true' }}
+          body: |
+            ## Docker Images
+
+            ```bash
+            docker pull ghcr.io/${{ github.repository }}:${{ github.ref_name }}
+            docker pull ghcr.io/${{ github.repository }}-server:${{ github.ref_name }}
+            docker pull ghcr.io/${{ github.repository }}-cleanup:${{ github.ref_name }}
+            docker pull ghcr.io/${{ github.repository }}-webui:${{ github.ref_name }}
+            ```
+
+            ## Helm chart (Kubernetes)
+
+            ```bash
+            # Image tags follow the 4-segment app version (e.g. 0.8.12.3);
+            # Helm chart versions are 3-segment SemVer, so strip the 4th
+            # segment (and any pre-release suffix) for --version.
+            VERSION="${{ github.ref_name }}"; VERSION="${VERSION#v}"
+            CHART_VERSION="$(echo "$VERSION" | sed -E 's/^([0-9]+\.[0-9]+\.[0-9]+)(\.[0-9]+)?(-.*)?$/\1\3/')"
+            helm install ocu oci://ghcr.io/${{ github.repository_owner }}/charts/computer-use-server \
+              --version "$CHART_VERSION" \
+              -f my-values.yaml \
+              --set image.tag="$VERSION" \
+              --set workspaceImage.tag="$VERSION" \
+              --set cleanup.image.tag="$VERSION"
+            ```
+
+            See [`helm/computer-use-server/README.md`](https://github.com/${{ github.repository }}/blob/${{ github.ref_name }}/helm/computer-use-server/README.md) for prerequisites (Kata Containers) and full values reference.
+
+            ## Quick Start (Docker Compose)
+
+            ```bash
+            git clone https://github.com/${{ github.repository }}.git
+            cd open-computer-use
+            git checkout ${{ github.ref_name }}
+            cp .env.example .env
+            # Edit .env with your API key
+            docker compose up
+            ```
+
+            ## Changes
+            ${{ steps.changelog.outputs.changes }}