elva-cli 1.1.0rc2__tar.gz → 1.2.0__tar.gz

elva_cli-1.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,27 @@
+name: Bug report
+description: Report a reproducible CLI problem
+body:
+  - type: input
+    id: version
+    attributes:
+      label: CLI version and installation method
+    validations:
+      required: true
+  - type: input
+    id: environment
+    attributes:
+      label: OS, shell and Python version
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Synthetic reproduction
+      description: Include commands and redacted errors. Do not include tokens, verification codes or customer data.
+    validations:
+      required: true
+  - type: textarea
+    id: result
+    attributes:
+      label: Expected and actual results
+      description: Include exit code and JSON status when available.
+    validations:
+      required: true

elva_cli-1.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Private security reporting
+    url: https://github.com/Theneo-Inc/theneo-elva-cli/blob/main/SECURITY.md
+    about: Read the private reporting instructions before disclosing a vulnerability.

elva_cli-1.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,19 @@
+name: Feature request
+description: Describe a developer or agent workflow need
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Workflow and problem
+    validations:
+      required: true
+  - type: textarea
+    id: outcome
+    attributes:
+      label: Desired outcome
+    validations:
+      required: true
+  - type: textarea
+    id: constraints
+    attributes:
+      label: Constraints and current workaround

elva_cli-1.2.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Change
+
+Describe the user-visible problem and resulting behavior.
+
+## Validation
+
+State checks run and gaps. Distinguish fixtures, real services, packaged CLI and
+native-agent validation.
+
+## Compatibility and docs
+
+For public behavior changes, note help/docs, JSON/exit codes, backend requirements,
+and changes to source uploads, credentials, drafts or publication. Omit inapplicable
+sections. Do not include secrets or customer data.

elva_cli-1.2.0/.github/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  wheel-and-minimum-typer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.11"
+      - run: uv build
+      - run: |
+          uv venv /tmp/wheel
+          uv pip install --python /tmp/wheel/bin/python dist/*.whl typer==0.27.1
+          /tmp/wheel/bin/python scripts/smoke_wheel.py
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --extra dev
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run mypy
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: ${{ matrix.python }}
+      - run: uv sync --extra dev
+      - run: uv run pytest

elva_cli-1.2.0/.github/workflows/installer.yml

@@ -0,0 +1,76 @@
+name: installer
+
+on:
+  push:
+    branches: [main]
+    paths: ["install/**", ".github/workflows/installer.yml"]
+  pull_request:
+    paths: ["install/**", ".github/workflows/installer.yml"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: installer-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install --global firebase-tools@15.32.1
+      - name: Prepare installer
+        run: |
+          sh -n install/install.sh
+          mkdir -p install/public
+          cp install/install.sh install/public/install.sh
+      - name: Test hosting
+        run: >-
+          firebase emulators:exec
+          --project demo-elva-cli-install
+          --config install/firebase.json
+          --only hosting
+          "sh install/test-hosting.sh"
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: check
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: installer
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm install --global firebase-tools@15.32.1
+      - name: Prepare installer
+        run: |
+          mkdir -p install/public
+          cp install/install.sh install/public/install.sh
+      - uses: google-github-actions/auth@v3
+        with:
+          workload_identity_provider: ${{ vars.ELVA_INSTALLER_WIF_PROVIDER }}
+          service_account: ${{ vars.ELVA_INSTALLER_DEPLOY_SA }}
+      - name: Deploy installer
+        run: >-
+          firebase deploy
+          --project elva-marketing-prod
+          --config install/firebase.json
+          --only hosting
+          --non-interactive
+      - name: Verify published script
+        run: |
+          curl --fail --silent --show-error --retry 5 --retry-all-errors \
+            'https://elva-cli-install.web.app/?revision=${{ github.sha }}' \
+            -o /tmp/published-install.sh
+          cmp install/install.sh /tmp/published-install.sh

elva_cli-1.2.0/.github/workflows/release.yml

@@ -0,0 +1,160 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+
+      - run: uv build
+
+      - name: Reject unpublishable versions
+        run: |
+          version=$(ls dist/*.whl | head -1 | sed -E 's/.*elva_cli-(.+)-py3.*/\1/')
+          echo "built version: $version"
+          case "$version" in
+            *+*) echo "::error::'$version' has a PEP 440 local segment; PyPI will reject it. Build from an exact tag." ; exit 1 ;;
+            *dev*) echo "::error::'$version' is a dev version; the tag is missing or HEAD is past it." ; exit 1 ;;
+          esac
+
+      - run: uvx twine check dist/*
+
+      - name: Smoke test the wheel in a clean environment
+        run: |
+          python3 -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          /tmp/smoke/bin/python scripts/smoke_wheel.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  binaries:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { runner: ubuntu-latest,    asset: elva-linux-x86_64 }
+          - { runner: ubuntu-24.04-arm, asset: elva-linux-aarch64 }
+          - { runner: macos-15-intel,   asset: elva-darwin-x86_64 }
+          - { runner: macos-latest,     asset: elva-darwin-arm64 }
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - name: Build ${{ matrix.asset }}
+        env:
+          PYAPP_EXEC_SPEC: elva_cli.main:main
+          PYAPP_PYTHON_VERSION: "3.12"
+          PYAPP_DISTRIBUTION_EMBED: "1"
+        run: |
+          export PYAPP_PROJECT_PATH="$PWD/$(ls dist/*.whl | head -1)"
+          echo "embedding $PYAPP_PROJECT_PATH"
+          cargo install pyapp --force --locked --root out
+          mv out/bin/pyapp "${{ matrix.asset }}"
+          chmod +x "${{ matrix.asset }}"
+
+      - name: It runs, and reports the version we built
+        run: |
+          set +e
+          got="$(./${{ matrix.asset }} --version 2>&1)"
+          rc=$?
+          set -e
+          echo "$got"
+          if [ $rc -ne 0 ]; then
+            echo "::error::${{ matrix.asset }} exited $rc"
+            exit 1
+          fi
+          version="$(ls dist/*.whl | head -1 | sed -E 's/.*elva_cli-(.+)-py3.*/\1/')"
+          case "$got" in
+            "elva $version "*) ;;
+            *) echo "::error::expected version $version, got: $got"; exit 1 ;;
+          esac
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.asset }}
+          path: ${{ matrix.asset }}
+
+  publish-binaries:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: elva-*
+          path: bin/
+          merge-multiple: true
+
+      - name: Checksums
+        working-directory: bin
+        run: |
+          chmod +x elva-*
+          sha256sum elva-* > SHA256SUMS
+          cat SHA256SUMS
+
+      - name: Upload to the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          case "$GITHUB_REF_NAME" in
+            *-*) prerelease="--prerelease" ;;
+            *)   prerelease="" ;;
+          esac
+          gh release view "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 \
+            || gh release create "$GITHUB_REF_NAME" --repo "$GITHUB_REPOSITORY" \
+                 --title "$GITHUB_REF_NAME" --generate-notes $prerelease
+          gh release upload "$GITHUB_REF_NAME" bin/* --repo "$GITHUB_REPOSITORY" --clobber

{elva_cli-1.1.0rc2 → elva_cli-1.2.0}/.gitignore

@@ -221,3 +221,9 @@ __marimo__/
 .venv/
 src/elva_cli/_version.py
 .ruff_cache/
+
+/install/public/
+/install/.firebase/
+firebase-debug.log*
+ui-debug.log*
+gha-creds-*.json

elva_cli-1.2.0/AGENTS.md

@@ -0,0 +1,23 @@
+# Working on Elva CLI
+
+This file guides changes to the CLI source. Agents consuming Elva should use the
+[canonical skill](src/elva_cli/assets/elva-mcp/SKILL.md), installed by `elva agent setup`,
+and the [agent interface](docs/agent-interface.md).
+
+## Preserve behavior
+
+Keep terminal I/O at the command/UI boundary and expensive imports lazy. Every
+interactive input needs an unattended equivalent. Preserve stable JSON fields,
+exit codes, retry IDs, and draft/publication separation. The existing-agent path
+sends generated API artifacts; never silently switch it to source upload or Elva AI.
+Use synthetic data and isolated profiles. Real services, email and publication
+must stay within the user's authorized scope. Do not commit secrets or private data.
+
+## Validate and document
+
+Follow [CONTRIBUTING.md](CONTRIBUTING.md). Run relevant tests; complete checks are
+`ruff check .`, `ruff format --check .`, `mypy`, and `pytest`. Check changed examples
+and links. Align `uv.lock` after dependency changes. Update help, guides and changelog
+for public behavior changes. Keep the bundled skill canonical and include required
+assets in distributions. Do not edit generated `_version.py`. Report actual checks
+and distinguish fixtures from production, runtime and native-agent validation.

elva_cli-1.2.0/CHANGELOG.md

@@ -0,0 +1,105 @@
+# Changelog
+
+## Unreleased
+
+### Repository documentation
+- Add an agent-first quickstart, shareable skill link, recovery/privacy guides,
+  contributor instructions, offline example and issue/PR templates.
+- Restore features onto current main, retaining standalone installer support.
+
+### Email-only CLI onboarding
+
+- Add `auth signup` / `auth register` with email-only verification, automatic account
+  and default workspace setup, `auth verify --code-stdin`, and `auth resume`.
+- Preserve a generated API artifact locally with `--continue-artifact`; return its
+  next command after login without source upload or another signup form.
+- Bind signup proof and newly saved credentials to their API origin, recover lost
+  responses, keep codes out of arguments/output, and acknowledge durable storage.
+- Teach the bundled agent skill to complete onboarding with authorized email access.
+
+
+### Existing-agent API artifacts
+
+- Add `agent setup`, `agent schema`, `agent validate`, and `agent create`.
+- Bundle discoverable Claude Code/Codex instructions for generating an API definition locally.
+- Import only sanitized API artifacts; create resumable collection/contract/MCP drafts without Elva AI or GitHub.
+- Require the matching artifact-plan backend before release.
+
+### Prompt from a local checkout
+- Add root `--prompt` to scan raw source with Elva AI, generate OpenAPI collections,
+  select customer endpoints/fields, and create a reviewed draft contract and MCP.
+- No GitHub connection or manually authored specification is required.
+- Add audience/API URL follow-ups, bounded filtered uploads, independent ignore
+  rules, secret redaction, auth options, `--plan-only` and `--resume` recovery.
+- Preserve source collections on planning retries and keep draft publication governed.
+
+### Workspace defaults, API insights and contracts
+- Select the default Elva workspace automatically when no selection is configured,
+  including accounts with several workspaces. Mark that default in `workspace list`.
+- Add `insights checks`, `insights review`, and `insights show`, with JSON output
+  and an optional overall-score gate for CI.
+- Add `contract list/show/create/update/sync/approve/reject/publish/delete`.
+  Creation is draft-only; publication is explicit and reports partial results.
+- Support PAT workspace discovery and scoped collection/contract reads and
+  lifecycle actions with the matching backend, preserving membership and roles.
+
+### GitHub repository sync
+- Add `repo list`, `repo connect`, `repo sync`, and `repo status` using Elva's
+  existing linked GitHub account and scan pipeline.
+- Support remote branch selection, explicit AI extraction, workspace scoping,
+  resumable bounded waits, JSON results, and collection change summaries.
+- Preserve reconnect settings, refuse unscoped backends before mutations, and
+  report partial connection, failed scans and skipped collection sync accurately.
+- Require the matching workspace-scoped repository backend before CLI rollout.
+
+### CLI validation fixes
+- Support Windows source snapshots without POSIX-only open flags, retaining regular-file
+  and file-identity checks, and read installed skills consistently as UTF-8 on repeat setup.
+- Isolate interactive tests from all CI provider flags and make newline, permission and
+  oversized-input test cases portable across the supported OS/Python matrix.
+- Return complete MCP endpoints, including the workspace component, consistently
+  from create, show, and publish; drafts have no connection URL.
+- Preserve Ctrl-C exit status 130, honor `timeout` / `ELVA_TIMEOUT` in every HTTP
+  transport, and reject non-finite timeouts before changing config files.
+- Report denied access as `ELVA_FORBIDDEN` (exit 3) without deleting credentials.
+- Require Typer 0.27.1 or newer, matching the vendored Click API the CLI uses.
+- Correct the endpoints-to-MCP pipeline and distinguish source docs from PyPI 0.5.0.
+- Isolate test profiles on macOS as well as Linux/Windows; smoke-test wheel commands.
+
+
+### Added
+- **Identify as a first-class refresh client (ELVA-200).** Every request now
+  sends `X-Elva-Client: cli` and a `User-Agent: elva-cli/<version>`. The refresh
+  and CLI-login exchanges carry the marker so the backend routes them on the
+  body-token path and, once its compatibility flag is turned off, does not
+  reject the CLI as an unmarked client.
+- **Refresh-and-retry on 401.** An idempotent request (GET/HEAD) that returns
+  401 on a token that looked valid now forces one refresh and retries once.
+  Non-idempotent requests (the spec upload) are never auto-replayed.
+- **Backoff on transient refresh failures.** A refresh that hits 429/5xx or a
+  network error is retried with backoff (1s/2s/4s) before surfacing as a
+  transient `ApiError` (exit 5); it never forces a re-login.
+
+### Changed
+- Refresh continues to happen proactively ~60s before the access token expires
+  and to persist the rotated token atomically (temp file + rename, 0600) before
+  the response is used — unchanged, but now covered by explicit tests.
+- **`elva import spec --url` now fetches through Elva and uploads like a file.**
+  The URL is fetched via Elva's `fetch-file` proxy (the same path the web app
+  uses, so a spec host only Elva can reach still works), a JSON spec is stored
+  as YAML to match a web-app import instead of one minified line, and `--name`
+  now defaults from the fetched spec's `info.title`. `--dry-run --url` reports
+  the real title/version/endpoint count/size, and a spec URL that 404s or times
+  out is now a usage error (exit 2) rather than a late server rejection. Local
+  `.json` files are converted to YAML on import for the same consistency.
+
+### Compatibility
+This version works with **both** the flagged and the unflagged backend:
+- While the backend keeps `AUTH_ALLOW_BODY_REFRESH_TOKEN` on, unmarked body
+  refreshes still work, so **older CLI versions keep working** too.
+- Once the backend turns that flag off (this CLI version being the minimum
+  supported), the server rejects unmarked and legacy ("family-less") refresh
+  tokens with `401 REFRESH_TOKEN_LEGACY`. This CLI maps that to
+  *"Your session has expired. Run `elva auth login` to sign in again."*
+  (exit code 3). **Older CLI versions stop working at that point** and users
+  must upgrade and re-login once.

elva_cli-1.2.0/CLAUDE.md

@@ -0,0 +1,6 @@
+# Elva CLI development
+
+Follow [AGENTS.md](AGENTS.md) when changing this repository. To create an MCP from
+another API repository, use the [Elva skill](src/elva_cli/assets/elva-mcp/SKILL.md)
+and [agent interface](docs/agent-interface.md). This file does not install that skill
+into another project; use `elva agent setup`.

elva_cli-1.2.0/CONTRIBUTING.md

@@ -0,0 +1,79 @@
+# Contributing to Elva CLI
+
+Use GitHub issues for reproducible bugs and feature requests. Report vulnerabilities
+privately using [SECURITY.md](SECURITY.md).
+
+## Setup
+
+Use Python 3.11 or newer. Clone the repository and check out the intended branch:
+
+```bash
+git clone https://github.com/Theneo-Inc/theneo-elva-cli.git
+cd theneo-elva-cli
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[dev]"
+elva --version
+elva --help
+```
+
+In PowerShell, use `py -m venv .venv` and `.venv\Scripts\Activate.ps1`.
+Alternatively, run `uv sync --locked --extra dev` and `uv run elva --help`.
+When changing dependencies, run `uv lock`, review its diff and commit `uv.lock`
+with `pyproject.toml`. Verify freshness with `uv lock --check`.
+
+## Checks
+
+Run focused tests while editing, then the complete checks before merging:
+
+```bash
+ruff check .
+ruff format --check .
+mypy
+pytest
+```
+
+Plain `mypy` checks source and tests; `mypy src` does not match CI. CI also defines
+Linux/macOS/Windows coverage for Python 3.11–3.13 and a clean-wheel/minimum-Typer
+check. Record actual results; a configured matrix is not evidence that it passed.
+
+Tests use synthetic data and isolated CLI profiles. Preserve that isolation.
+Use real services, email, source upload or publication only in the user's authorized
+scope and environment. Never include tokens or customer data in fixtures.
+
+## Architecture
+
+- `commands/`: Typer options and command orchestration.
+- `core/services/`: service calls and typed results.
+- `core/api/`: HTTP transport and API target resolution.
+- `core/spec/`: API format detection and normalization.
+- `core/agent_*.py`: artifact validation and skill installation.
+- `auth/`: credentials, browser/email sessions and refresh.
+- `settings/`: profiles, configuration and precedence.
+- `ui/`: terminal output and prompts.
+- `assets/elva-mcp/`: canonical installed skill.
+
+These paths are under `src/elva_cli/`. Keep terminal I/O at the command/UI boundary
+and expensive imports lazy. Every interactive input needs an unattended equivalent.
+Preserve exit codes, JSON contracts, retry IDs and the distinction between drafts
+and publication. Keep Python and backend artifact schemas aligned.
+
+## Documentation and PRs
+
+Keep the README focused on onboarding and detailed commands in `docs/`. Update help,
+the relevant guide and changelog for public behavior changes. Maintain one canonical
+skill in `src/elva_cli/assets/elva-mcp/`.
+
+Validate examples offline and check relative links:
+
+```bash
+elva --json agent validate --from examples/customer-orders/artifact.json
+```
+
+The example is synthetic. Local validation, resource creation, publication, live
+runtime access and native agent discovery are separate checks.
+
+PRs should describe the problem, resulting behavior, validation and any backend
+compatibility requirements. Do not edit generated `src/elva_cli/_version.py`.
+See [AGENTS.md](AGENTS.md), [RELEASING.md](RELEASING.md) and
+[repository readiness](docs/repository-readiness.md).