@revos/cli 0.2.3 → 0.3.0

package/dist/templates/README.md

@@ -1,23 +1,92 @@
 # <%=projectName%>
 
-RevOS data engineering project for **<%=orgName%>** organization.
+RevOS data engineering project for **<%=orgName%>**.
+
+This project is designed to be opened in a Dev Container. All tooling — Python, Node, dbt, the Google Cloud CLI, the RevOS CLI, GitHub CLI, and Claude Code — comes pre-installed. The container is the supported development environment; you should rarely need to install anything on your host.
 
 ## Getting started
 
-1. Open this folder in VS Code and click **Reopen in Container** — the Dev Container installs all tools automatically.
-2. Inside the container, verify your setup:
+1. **Open in VS Code** and click **Reopen in Container** when prompted. First open builds the image (~1–2 min); subsequent opens are instant.
+
+2. **One-time setup inside the container.** Open a terminal and run these two commands once:
+
+   ```bash
+   revos auth login    # OAuth flow — browser opens automatically
+   revos init          # provisions the BigQuery service account key
+   ```
+
+   `revos init` detects it's running inside an existing project, skips the org prompt and scaffolding, and just fills in the missing GCP key.
+
+   **You won't need to repeat this.** Credentials persist in per-project Docker volumes, so every future `Rebuild Container`, restart, or VS Code reopen lands in a fully-authenticated state — the container will print `REVOS DEV CONTAINER — READY` on every start.
+
+3. **Verify everything is wired up.** Either look at the banner the container prints on every start (`REVOS DEV CONTAINER — READY` with your auth + GCP details), or run:
+
    ```bash
-   dbt --version
-   bq version
+   bq ls $REVOS_BQ_DATASET     # list tables in your BigQuery dataset
+   dbt debug                   # confirm dbt connection
+   revos status                # list local Connections/Cubes vs. the API
    ```
 
-## Project structure
+## Project layout
 
 ```
-dbt/models/
-  bronze/   # raw ingested data
-  silver/   # cleaned & conformed
-  gold/     # business-ready marts
-semantic/
-  cubes/    # Cube.dev cube definitions
+.
+├── revos.yaml                # binds this project to your RevOS org (do not edit)
+├── connections/              # sync pipelines (RevOS-managed; one YAML per Connection)
+├── cubes/                    # Cube.dev semantic model definitions (one YAML per Cube)
+├── dbt/
+│   ├── dbt_project.yml
+│   ├── profiles.yml          # pre-configured for BigQuery via $GOOGLE_APPLICATION_CREDENTIALS
+│   └── models/
+│       ├── bronze/           # raw ingested data — declared as dbt sources in schema.yml
+│       ├── silver/           # cleaned & conformed
+│       └── gold/             # business-ready marts
+├── .claude/                  # AI companion config + pre-installed skills
+├── .devcontainer/            # Dev Container definition
+├── AGENTS.md                 # context for AI coding agents
+└── CLAUDE.md                 # imports AGENTS.md
 ```
+
+## Common workflows
+
+| Task                                          | Command                              |
+| --------------------------------------------- | ------------------------------------ |
+| List data sources available on RevOS          | `revos sources list`                 |
+| Add a new data source (opens RevOS UI)        | `revos sources create`               |
+| Pull current Connections & Cubes from the API | `revos pull`                         |
+| Push local YAML changes back to the API       | `revos apply`                        |
+| Preview drift before applying                 | `revos diff`                         |
+| Run all dbt models                            | `dbt run`                            |
+| Run dbt tests                                 | `dbt test`                           |
+| Inspect a BigQuery table                      | `bq head -n 5 $REVOS_BQ_DATASET.<t>` |
+| Show all `revos` commands                     | `revos --help`                       |
+
+## Working with Claude Code
+
+This project ships pre-installed Claude skills under `.claude/skills/` for the common tasks:
+
+- **`explore-lakehouse`** — survey your BigQuery datasets and tables.
+- **`create-connections`** — author a Connection YAML from a Source's available streams.
+- **`create-cubes`** — build Cube.dev semantic models from gold-layer tables.
+- **`create-dbt-transformations`** — write bronze→silver→gold dbt models.
+- **`load-sample-data`** — seed BigQuery with example data when the warehouse is empty.
+- **`visualize-semantic-model`** — render the cube graph as an image.
+
+Inside the container, ask Claude things like _"create a Connection for our Stripe source"_ or _"build a silver model for the orders table"_ and it will use the matching skill.
+
+## Troubleshooting
+
+- **Container shows `SETUP REQUIRED` banner.** Run `revos auth login` and `revos init` in the container terminal.
+- **`bq` or `dbt` fails with auth errors.** Container's gcloud is not activated. Rebuild the container, or run `bash .devcontainer/post-start.sh` to re-activate.
+- **Start from a clean slate.** Wipe the per-project Docker volumes from your host:
+  ```bash
+  docker volume rm revos-<%=projectSlug%>-credentials \
+                  revos-<%=projectSlug%>-gcloud \
+                  revos-<%=projectSlug%>-claude
+  ```
+  Then `Rebuild Container` and rerun step 2.
+
+## Further reading
+
+- RevOS CLI reference: <https://cli.revos.dev>
+- This project's AI guidance: [`AGENTS.md`](./AGENTS.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revos/cli",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "RevOS CLI for managing RevOS platform resources",
   "license": "MIT",
   "type": "module",

package/dist/templates/.devcontainer/setup.sh

@@ -1,35 +0,0 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-# Copy mounted GCP service account key to vscode user's home
-if [ -f /tmp/.revos-gsa-creds.json ]; then
-  mkdir -p "$HOME/.revos"
-  cp /tmp/.revos-gsa-creds.json "$HOME/.revos/gsa-creds.json"
-  chmod 600 "$HOME/.revos/gsa-creds.json"
-fi
-
-# Copy mounted RevOS CLI credentials so revos commands work without re-login
-if [ -f /tmp/.revos-credentials.json ]; then
-  mkdir -p "$HOME/.revos"
-  cp /tmp/.revos-credentials.json "$HOME/.revos/credentials.json"
-  chmod 600 "$HOME/.revos/credentials.json"
-fi
-
-# Configure gcloud with service account and project
-GCP_KEY="$HOME/.revos/gsa-creds.json"
-if [ -f "$GCP_KEY" ]; then
-  gcloud auth activate-service-account --key-file="$GCP_KEY"
-fi
-if [ -n "${GOOGLE_CLOUD_PROJECT:-}" ]; then
-  gcloud config set project "$GOOGLE_CLOUD_PROJECT"
-fi
-
-# Fix Claude Code credentials permissions (volume is created as root)
-sudo chown -R vscode:vscode /home/vscode/.claude 2>/dev/null || true
-
-# Install RevOS CLI
-npm install -g @revos/cli
-
-# Symlink dbt profiles so `dbt run` works without --profiles-dir
-mkdir -p "$HOME/.dbt"
-ln -sf "$(pwd)/dbt/profiles.yml" "$HOME/.dbt/profiles.yml"