vb-os 0.1.0__tar.gz

vb_os-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[cli,dev]"
+      - run: ruff check vbos/ vbos_cli/
+      - run: pytest tests/ -v --tb=short
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - name: Verify no binary artifacts in sdist
+        run: |
+          tar tzf dist/*.tar.gz | grep -E '\.(so|dylib|dll|exe)$' && exit 1 || true
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

vb_os-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+*.egg
+.mypy_cache/
+.ruff_cache/

vb_os-0.1.0/LICENSE

@@ -0,0 +1,6 @@
+Copyright (c) 2024-2026 MNC Labs, Inc. All rights reserved.
+
+This software is proprietary and confidential. Unauthorized copying, modification,
+distribution, or use of this software, via any medium, is strictly prohibited.
+
+For licensing inquiries, contact: legal@vb-os.org

vb_os-0.1.0/MANIFEST.md

@@ -0,0 +1,279 @@
+# VB-OS Python SDK — Manifest
+
+## Ticket
+
+CP1-S0049 — Python SDK Core Architecture (issue #1)
+
+## Package
+
+- **PyPI name:** `vb-os`
+- **Import name:** `vbos`
+- **Version:** 0.1.0
+- **Python:** >=3.10
+- **Dependencies:** httpx >=0.27.0,<1.0.0, pydantic >=2.0.0,<3.0.0
+
+## Files
+
+### Source (`vbos/`)
+
+| File | Purpose |
+|------|---------|
+| `__init__.py` | Package init — exports all public classes + ~80 models, `__version__` |
+| `_transport.py` | Shared HTTP helpers: `handle_json_response`, `parse_error_body`, `extract_request_id`, `extract_retry_after` |
+| `exceptions.py` | Exception hierarchy: VBOSError base, 6 typed subclasses, `raise_for_status()` |
+| `models.py` | Typed Pydantic response models matching API schema (~80 models, all `extra="ignore"`) |
+| `retry.py` | Full jitter exponential backoff — `compute_delay()`, `sync_retry()`, `async_retry()` |
+| `client.py` | VBOSClient (sync) + AsyncVBOSClient (async) with 27 resource namespaces + top-level `verify()`, `verify_batch()`, `validate()`, `certify()`, `replay()` |
+
+### Resource Modules (`vbos/resources/`)
+
+| File | Sync/Async Classes | Methods |
+|------|--------------------|---------|
+| `__init__.py` | Package init | — |
+| `account.py` | SyncAccount / AsyncAccount | delete, cancel_delete, deletion_status, export, export_latest, export_status, export_download |
+| `alert_rules.py` | SyncAlertRules / AsyncAlertRules | create, list, get, update (PUT), delete |
+| `analytics.py` | SyncAnalytics / AsyncAnalytics | assertion_rate, deferral_rate, evaluations, failure_reasons, latency |
+| `audit_log.py` | SyncAuditLog / AsyncAuditLog | list, export, export_status |
+| `billing.py` | SyncBilling / AsyncBilling | usage, subscription, invoices |
+| `boundaries.py` | SyncBoundaries / AsyncBoundaries | list, create, get, update_draft, submit, versions, get_version, approve, reject, diff |
+| `certification_models.py` | SyncCertificationModels / AsyncCertificationModels | list, create, create_version |
+| `certifications.py` | SyncCertifications / AsyncCertifications | list, get, get_report, wait (polling helper) |
+| `connector_providers.py` | SyncConnectorProviders / AsyncConnectorProviders | list, schema |
+| `connectors.py` | SyncConnectors / AsyncConnectors | create, list, get, update, delete, test, gather, analytics, resources, schema, get_schedule, set_schedule, list_gathers, authorize, disconnect, reconnect, oauth_status, wait_for_authorization |
+| `deployments.py` | SyncDeployments / AsyncDeployments | list, create, active, approve, reject, promote, rollback |
+| `environments.py` | SyncEnvironments / AsyncEnvironments | list, create, get, update, deactivate, reactivate |
+| `flow_templates.py` | SyncFlowTemplates / AsyncFlowTemplates | list, get |
+| `flows.py` | SyncFlows / AsyncFlows | create, list, get, update, delete, export, import_flow, from_template, create_version, list_versions, get_version, update_version, delete_version, approve_version, deploy, suspend, dry_run, list_executions, reconstruct_execution |
+| `governed_workspaces.py` | SyncGovernedWorkspaces / AsyncGovernedWorkspaces | create, list, get, create_version, get_version, submit, approve, deploy, archive, create_instance, submit_instance, get_instance |
+| `keys.py` | SyncKeys / AsyncKeys | list, create, get, rotate, revoke, disable, enable |
+| `members.py` | SyncMembers / AsyncMembers | list, invite, set_role, remove, suspend, reactivate, revoke_invitation |
+| `named_sets.py` | SyncNamedSets / AsyncNamedSets | create, list, get, update, delete, usage |
+| `notifications.py` | SyncNotifications / AsyncNotifications | list, read, unread |
+| `org.py` | SyncOrg / AsyncOrg | get, update, get_settings, update_settings, get_ai_policy, update_ai_policy, transfer_ownership, accept_transfer, cancel_transfer, get_transfer |
+| `projects.py` | SyncProjects / AsyncProjects | list, create, get, update, archive, delete, list_members, add_member, remove_member, update_member |
+| `service_accounts.py` | SyncServiceAccounts / AsyncServiceAccounts | list, create, update, disable, enable |
+| `templates.py` | SyncTemplates / AsyncTemplates | list, get, fork |
+| `users.py` | SyncUsers / AsyncUsers | me, organizations |
+| `webhooks.py` | SyncWebhooks / AsyncWebhooks | list, create, update, delete, rotate_secret, deliveries, list_org, create_org |
+| `workspaces.py` | SyncWorkspaces / AsyncWorkspaces | list, create, get, update, archive, delete, list_members, add_member, remove_member |
+
+**Total:** 27 resource modules, 180 endpoint-backed methods + 1 polling helper (`certifications.wait`)
+
+### Tests (`tests/`)
+
+| File | Purpose | Count |
+|------|---------|-------|
+| `conftest.py` | Shared mock response fixtures (ASSERT, DEFER, error) | — |
+| `test_exceptions.py` | Exception hierarchy + `raise_for_status()` | 18 |
+| `test_models.py` | Pydantic model parsing (ASSERT, DEFER, sub-models) | 9 |
+| `test_retry.py` | Retry logic (is_retryable, compute_delay, sync/async retry) | 18 |
+| `test_client.py` | VBOSClient init + verify() happy/error paths | 15 |
+| `test_async_client.py` | AsyncVBOSClient init + verify() happy/error paths | 13 |
+| `test_async_evaluations.py` | AsyncVBOSClient evaluations replay, list, get | 6 |
+| `tests/contract/test_verify_contract.py` | SDK ↔ API contract validation (sync + async) | 10 |
+| `tests/contract/test_sdk_contracts.py` | Per-resource HTTP method/path contracts (CC-01 through CC-23) | ~73 |
+| `test_endpoint_manifest.py` | 180-row ledger: sync+async method existence, parity, signature parity | 364 |
+| `test_cross_cutting.py` | Forward compat (XC-02/03), secret leakage (XC-04), query params (XC-06), immutability (XC-07), error parity (XC-08/13), certifications.wait (XC-09/10/11), pagination cursors (XC-14) | 93 |
+| **Total** | | **~1100** |
+
+### Configuration
+
+| File | Purpose |
+|------|---------|
+| `pyproject.toml` | Package config, build, dev deps, tool configs (pytest, ruff, mypy) |
+| `README.md` | Package README with quick start |
+
+### Postman
+
+| File | Purpose |
+|------|---------|
+| `postman/vb-os-python-sdk.postman_collection.json` | Standalone SDK contract validation (runs against api.vb-os.org) |
+| `vb-os-cloud-api/postman/...` → "SDK Contract Validation (S0049)" | Cloud API Postman collection folder — self-bootstrapping auth + 6 contract tests validating SDK response schema expectations (PR #101) |
+
+## REQ Coverage
+
+| REQ | Description | Status |
+|-----|-------------|--------|
+| REQ-A1-144 | `pip install vb-os` | Complete |
+| REQ-A1-145 | SDK wraps POST /v1/verify — `verify()` method only (remaining methods deferred to CP1-E14) | Partial |
+| REQ-A1-146 | EvaluationResult fields: decision, replay_id, evaluation_id, admissibility, prohibitions, predicate_results, failure_reasons, latency_ms | Complete |
+| REQ-A1-154 | Thin transport wrapper — no business logic in SDK | Complete |
+| REQ-A1-155 | Typed Pydantic models (not raw dicts) for all API responses | Complete |
+| REQ-A1-156 | AsyncVBOSClient.verify() for async usage (async counterpart) | Complete |
+| REQ-A1-157 | Retry with backoff on 5xx/timeout, never on 4xx. Full jitter: `delay = random.uniform(0, base_delay * 2^attempt)` capped at max_delay | Complete |
+| REQ-A1-158 | Structured exceptions carry error_code, message, details, request_id — not just status codes | Complete |
+| REQ-A1-290 | Python SDK ships CP-1 | Complete |
+
+## CLI (`vbos_cli/`) — CP2-S0031
+
+| File | Purpose |
+|------|---------|
+| `vbos_cli/__init__.py` | CLI package init — `__version__ = "0.1.0"` |
+| `vbos_cli/__main__.py` | `python -m vbos_cli` support |
+| `vbos_cli/errors.py` | Error hierarchy: CLIError(exit_code), AuthenticationError, CredentialStoreError, UnsupportedInLocalModeError, SessionExpiredError, APIKeyInvalidError |
+| `vbos_cli/output.py` | print_json, print_table, print_result, print_error, stderr, print_banner (VB-OS logo on login) |
+| `vbos_cli/profiles.py` | resolve_profile (flag > VBOS_PROFILE env > "default") |
+| `vbos_cli/config.py` | TOML config at ~/.vbos/config — profile sections, atomic writes, get/set/list |
+| `vbos_cli/credentials/__init__.py` | Credential store package |
+| `vbos_cli/credentials/store.py` | CredentialStore abstraction, SessionCredential/APIKeyCredential dataclasses, resolve_credential |
+| `vbos_cli/credentials/keychain.py` | KeychainStore — OS keychain via `keyring`, validates macOS/Windows/Linux backends |
+| `vbos_cli/credentials/file.py` | FileStore — PBKDF2-HMAC-SHA256 (600k iterations) + Fernet encryption, atomic writes, 0600 permissions |
+| `vbos_cli/credentials/migration.py` | Credential store migration (read→write→verify→delete) |
+| `vbos_cli/client.py` | AuthenticatedClient — auth injection, pre-request JWT exp check, method-aware retry, token refresh |
+| `vbos_cli/cli.py` | Click group with --version, --profile, --format, --cloud/--local, CLIGroup (catches CLIError), CloudOnlyCommand |
+| `vbos_cli/commands/__init__.py` | Commands package |
+| `vbos_cli/commands/auth.py` | login (interactive + --token + --org, MFA, multi-org, TOS), logout, resend_verification |
+| `vbos_cli/commands/org.py` | switch_org command |
+| `vbos_cli/commands/config_cmd.py` | config set/get/list with credential-store migration |
+| `vbos_cli/commands/completions.py` | bash/zsh/fish completion script output |
+
+### CLI Tests (`tests/cli/`)
+
+| File | Purpose | Count |
+|------|---------|-------|
+| `test_cli.py` | Version, help, execution modes (mutual exclusion, local rejection), output format, network error handling (ConnectError, TimeoutException) | 14 |
+| `test_config.py` | Config set/get/list, profile isolation, credential absence | 7 |
+| `test_credentials.py` | Serialization, keychain validation, file encryption, atomic writes, corrupted file, migration (success/verify-fail/delete-fail/empty), resolve | 25 |
+| `test_client.py` | JWT exp extraction, expiry detection, API key bypass, session refresh, 401 handling, retry | 18 |
+| `test_profiles.py` | Profile resolution precedence | 4 |
+| `test_output.py` | JSON/table/error/stderr/banner output | 9 |
+| `test_auth.py` | Login/logout, MFA recovery, MFA max attempts, --org bypass, switch-org (direct + interactive), TOS, lockout, PENDING_DELETION, resend-verification, credential leakage, password non-echo, session→API-key replacement, enrollment vs runtime auth | 22 |
+| `test_completions.py` | Bash/zsh/fish completion output | 3 |
+| `test_integration.py` | IT-S0031-01 through IT-S0031-08 end-to-end flows | 9 |
+| **Total** | | **111** |
+
+### CLI Dependencies (pyproject.toml `[project.optional-dependencies] cli`)
+
+| Package | Purpose |
+|---------|---------|
+| click >=8.1,<9.0 | CLI framework |
+| keyring >=25.0,<26.0 | OS credential store |
+| cryptography >=44.0,<45.0 | Fernet encryption for file store |
+| tomli_w >=1.0,<2.0 | TOML writing |
+
+## CLI Full Command Surface (`vbos_cli/commands/`) — CP2-S0032
+
+### Shared Infrastructure
+
+| File | Purpose |
+|------|---------|
+| `vbos_cli/formatters.py` | Shared output formatting: `format_output` (JSON/table/quiet), `format_secret`, `format_artifact_download`, `_atomic_write` (0600 perms), `handle_api_error`, `paginate_all` (cursor loop detection), `make_client`, `resolve_project`/`resolve_environment` (config fallback), `add_output_options`/`add_pagination_options`/`add_confirm_option` decorators, `confirm_destructive` |
+| `vbos_cli/local_bridge.py` | Local binary bridge: `_find_binary` (PATH + /opt/vbos/bin fallback), `_verify_install` (A-REL-002 manifest), `_build_a_input_001` (bundle format), `_to_binary_dsl` (DSL conversion), `_parse_audit_parity`, `invoke_local` (full orchestration) |
+
+### Command Modules (23 groups, ~180+ commands)
+
+| File | Group | Commands |
+|------|-------|----------|
+| `commands/verify.py` | `verify` | Submit workload (--cloud/--local/--batch), exit 0=ASSERT/1=DEFER/2=error |
+| `commands/replay.py` | `replay` | Replay prior evaluation |
+| `commands/evaluations.py` | `evaluations` | list, get, search, export, share, replay-analysis |
+| `commands/boundaries.py` | `boundaries` | create, list, get, update, archive, compile, validate, diff, promote + `versions` subgroup (create, list, get, update, submit, approve, reject) |
+| `commands/projects.py` | `projects` | create, list, get, update, archive, delete + `members` subgroup (list, add, remove) |
+| `commands/environments.py` | `environments` | create, list, get, update, archive, unarchive |
+| `commands/keys.py` | `keys` | create (format_secret), list, get, rotate (format_secret), revoke |
+| `commands/connectors.py` | `connectors` | create, list, get, update, delete, test, gather, authorize, disconnect, reconnect, status + `providers` subgroup (list, get) |
+| `commands/webhooks.py` | `webhooks` | create, list, get, update, delete, test, rotate-secret, deliveries, retry (project/org scope via --org) |
+| `commands/flows.py` | `flows` | create, list, get, update, delete, export, import, from-template, deploy, suspend, resume, dry-run + `versions` (create, list, get, update, delete, approve) + `executions` (list, reconstruct) + `templates` (list, get) |
+| `commands/alert_rules.py` | `alert-rules` | create, list, get, update (PUT), delete |
+| `commands/deployments.py` | `deployments` | list, get, active, rollback, approve, reject |
+| `commands/templates.py` | `templates` | list, get, fork |
+| `commands/named_sets.py` | `named-sets` | list, get, create, update, delete |
+| `commands/org_mgmt.py` | `org` | get, update + `settings` subgroup (get, update) |
+| `commands/members.py` | `members` | list, invite, role, remove, suspend, reactivate |
+| `commands/workspaces.py` | `workspaces` | list, get, create, update, archive |
+| `commands/audit_log.py` | `audit-log` | list, export, export-status |
+| `commands/certify.py` | `certify` (standalone command) + `certifications` group (list, get, report, revoke) + `certification-models` group (create, list, get, update, delete) |
+| `commands/analytics.py` | `analytics` | assertion-rate |
+| `commands/governed_workspaces.py` | `governed-workspaces` | provision, list, get, deploy, evaluate, seal, teardown |
+| `commands/notifications.py` | `notifications` | list, read, unread |
+| `commands/account.py` | `account` | delete, delete-status, delete-cancel, export, export-status |
+
+### S0032 Tests (`tests/cli/`)
+
+| File | Purpose | Count |
+|------|---------|-------|
+| `test_command_registration.py` | All 25 S0032 + 6 S0031 commands registered, help works | 57 |
+| `test_formatters.py` | Atomic write (0600), format_output, format_secret, quiet extractors, pagination | 14 |
+| `test_local_bridge.py` | Binary discovery, verify-install, bundle build, DSL conversion, audit parity, decision map | 12 |
+| `test_error_handling.py` | API error exit codes (401/403/404/500), client close lifecycle | 6 |
+| `test_config_fallback.py` | Project/environment resolution from flag vs config | 3 |
+| `test_verify.py` | Verify command: ASSERT/DEFER exit codes, batch, local exclusion, idempotency | 12 |
+| `test_evaluations.py` | Evaluations group: list/get/search/export/share/replay-analysis | 21 |
+| `test_replay.py` | Replay command: basic, API error, client lifecycle | 6 |
+| `test_projects.py` | Projects group: CRUD, members, destructive confirm | 23 |
+| `test_environments.py` | Environments group: CRUD, archive/unarchive | 14 |
+| `test_keys.py` | Keys group: create/rotate (format_secret), revoke | 15 |
+| `test_boundaries.py` | Boundaries group: CRUD, compile, validate, diff, promote, versions | 34 |
+| `test_connectors.py` | Connectors group: CRUD, test, gather, providers | 20 |
+| `test_connectors_oauth.py` | Connector OAuth: sync/async authorize, disconnect, reconnect, oauth_status, wait_for_authorization, terminal states, 404, timeout, security | 18 |
+| `cli/test_connectors_oauth.py` | CLI OAuth commands: authorize (all terminal states, 503 retry, no-browser, quiet, API error), disconnect, reconnect, status, token leakage | 17 |
+| `test_webhooks.py` | Webhooks group: CRUD, rotate-secret, deliveries, retry, org scope | 22 |
+| `test_flows.py` | Flows group: CRUD, export/import, deploy, versions, executions | 33 |
+| `test_alert_rules.py` | Alert rules group: CRUD, PUT update | 17 |
+| `test_deployments.py` | Deployments group: list, get, active, rollback, approve, reject | 10 |
+| `test_templates.py` | Templates group: list, get, fork | 8 |
+| `test_named_sets.py` | Named sets group: CRUD | 7 |
+| `test_org_mgmt.py` | Org group: get, update, settings get/update | 6 |
+| `test_members.py` | Members group: list, invite, role, remove, suspend, reactivate | 10 |
+| `test_workspaces.py` | Workspaces group: CRUD, archive | 7 |
+| `test_audit_log.py` | Audit log group: list, export, export-status | 7 |
+| `test_certify.py` | Certify + certifications + certification-models | 17 |
+| `test_analytics.py` | Analytics group: assertion-rate | 4 |
+| `test_governed_workspaces.py` | Governed workspaces: provision, list, get, deploy, evaluate, seal, teardown | 9 |
+| `test_notifications.py` | Notifications group: list, read, unread | 7 |
+| `test_account.py` | Account: delete, delete-status, delete-cancel, export, export-status | 11 |
+| `test_integration_s0032.py` | IT-01 through IT-06: verify lifecycle, boundary lifecycle, project setup, file perms, exit codes, destructive confirm | 15 |
+| **Total S0032 tests** | | **432** |
+
+## Distribution — CP2-S0050
+
+### Distribution Files
+
+| File | Purpose |
+|------|---------|
+| `scripts/install.sh` | Shell installer — isolated vbos installation via pipx or dedicated venv |
+
+### Distribution Channels
+
+| Channel | Command | Dependencies |
+|---------|---------|-------------|
+| pip | `pip install "vb-os[cli]"` | PyPI publication |
+| Homebrew | `brew install VB-OS/tap/vbos` | PyPI + homebrew-tap formula generation |
+| Shell installer | `curl -fsSL https://get.vb-os.org/cli \| sh` | PyPI + get.vb-os.org hosting |
+
+### Installer Behavior
+
+- Detects OS (macOS, Linux), rejects unsupported
+- Requires Python >= 3.10
+- Fresh install: pipx if available, otherwise dedicated venv at `~/.vbos/venv`
+- Upgrade: detects existing mechanism (pipx or venv), upgrades in-place
+- Never silently migrates between installation mechanisms
+- Detects pre-existing unrelated `vbos` on PATH, warns and aborts
+- `VBOS_INSTALL_SOURCE` env var overrides package source for local testing
+- shellcheck clean
+
+### Documentation
+
+| File | Purpose |
+|------|---------|
+| `docs/cli-developer-manual.md` | Architecture, distribution, release procedures, rollback |
+| `docs/cli-operator-manual.md` | Installation methods, authentication, upgrade, troubleshooting |
+
+## Architecture
+
+- **Two-client pattern:** VBOSClient (httpx.Client) and AsyncVBOSClient (httpx.AsyncClient)
+- **27 resource namespaces:** Each resource group is a SyncX/AsyncX sub-client taking `(client, max_retries)`, using `_request` helper → `build_request → sync_retry/async_retry → handle_json_response`
+- **Transport extraction:** `_transport.py` holds shared HTTP helpers to avoid circular imports between `client.py` and `resources/*.py`
+- **1:1 endpoint mapping:** Every SDK method maps to exactly one Cloud API endpoint — no business logic
+- **Forward compatibility:** All Pydantic models use `extra="ignore"` to handle unknown fields
+- **Context manager support:** Both clients support `with` / `async with`
+- **CLI entry point:** `vbos` binary via `[project.scripts]`, Click group with 31 commands (6 S0031 + 25 S0032)
+- **Default base URL:** `https://api.vb-os.org`
+- **Default timeout:** 30.0s
+- **Default max retries:** 3
+- **User-Agent:** `vb-os-python-sdk/0.1.0` (SDK), `vbos-cli/0.1.0` (CLI)
+
+## Test Results
+
+- **1100 total tests passed** (0 failures) — 111 S0031 CLI + 432 S0032 CLI + 17 S0032 integration + ~540 SDK core (83 original + 364 manifest + 93 cross-cutting + ~73 contract) = ~1100
+- **Lint clean** (ruff — 0 errors)