From 2a45addd28fda718d8fba7c15866a0f52bc0d8bc Mon Sep 17 00:00:00 2001 From: hyochan Date: Fri, 8 May 2026 22:43:13 +0900 Subject: [PATCH 1/4] docs(gv): add cloud workspace policy Document the safe TabTabTab gv operating boundaries for OpenIAP, including skip-env onboarding, selected-repo GitHub access, read-only Docker smoke checks, and excluded signing/release workflows. Also suppress known audit-docs false positives for top-level scalar/list API parameters so the docs consistency audit stays actionable. --- CLAUDE.md | 3 + knowledge/internal/08-gv-cloud-workspaces.md | 191 +++++++++++++++++++ scripts/audit-docs.ts | 7 + 3 files changed, 201 insertions(+) create mode 100644 knowledge/internal/08-gv-cloud-workspaces.md diff --git a/CLAUDE.md b/CLAUDE.md index f50bc2d61..679199fc8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -15,6 +15,7 @@ This document provides an overview for AI agents working across the OpenIAP mono | Docs Patterns | [`knowledge/internal/05-docs-patterns.md`](knowledge/internal/05-docs-patterns.md) | | Git & Deployment | [`knowledge/internal/06-git-deployment.md`](knowledge/internal/06-git-deployment.md) | | Docs Consistency / SSOT | [`knowledge/internal/07-docs-consistency.md`](knowledge/internal/07-docs-consistency.md) (run `bun audit:docs` before pushing API/Type doc edits) | +| GV Cloud Workspaces | [`knowledge/internal/08-gv-cloud-workspaces.md`](knowledge/internal/08-gv-cloud-workspaces.md) | ## Monorepo Structure @@ -189,3 +190,5 @@ All comprehensive rules are documented in [`knowledge/internal/`](knowledge/inte 4. **04-platform-packages.md** - Apple/Google/GQL/Docs package workflows 5. **05-docs-patterns.md** - React modal patterns, component organization 6. **06-git-deployment.md** - Commit format, deployment workflows +7. **07-docs-consistency.md** - Docs/API/type consistency audits +8. **08-gv-cloud-workspaces.md** - Safe TabTabTab `gv` cloud workspace policy diff --git a/knowledge/internal/08-gv-cloud-workspaces.md b/knowledge/internal/08-gv-cloud-workspaces.md new file mode 100644 index 000000000..03080b991 --- /dev/null +++ b/knowledge/internal/08-gv-cloud-workspaces.md @@ -0,0 +1,191 @@ +# GV Cloud Workspace Policy + +> **Priority: MANDATORY** +> Follow this policy when using TabTabTab `gv` cloud environments with OpenIAP. + +`gv` can be useful for OpenIAP as a safe remote maintenance runner, not as a +release, signing, or production-credential environment. Treat every GV +workspace as an external cloud workspace with GitHub access and no local secret +trust by default. + +## Safe role for OpenIAP + +Use GV for secret-free OSS maintenance work: + +- Documentation edits, release notes, docs typecheck, and docs consistency + audits. +- `packages/gql` tests and schema/codegen review work that does not require + private credentials. +- `packages/kit` typecheck and unit tests that run without production env vars. +- PR review response work on isolated branches/worktrees. +- Long-running lint/test/build smoke checks that should survive local laptop + sleep or high local resource use. + +Do not treat GV as the source of truth for full OpenIAP release validation. +Native Apple signing, Play/App Store production credentials, package publishing, +and deployment stay in the existing local or CI release systems. + +## Required boundaries + +Always keep these boundaries unless the repository owner explicitly changes this +policy: + +- Onboard the repo with env capture disabled: + + ```bash + gv repo add . --skip-env + ``` + +- First test of any new GV version or environment should be: + + ```bash + gv repo add . --dry-run --skip-env + ``` + +- GitHub App access must be limited to the selected `hyodotdev/openiap` + repository. Do not grant all-repository access. +- Do not enable OpenAI/Codex auth mirroring for OpenIAP by default. +- Do not enable local profile, CLI, shell, editor, or credential mirroring by + default. +- Do not add production, payment, signing, release, or deployment secrets to GV. +- If credentials are ever needed for a GV experiment, use sandbox/test-only + credentials with explicit owner approval. + +## Forbidden commands and actions + +Never run or recommend these for OpenIAP GV work: + +```bash +gv repo add . --yes +gv repo env list --reveal +gv env info --reveal +gv env info --qr +``` + +Also do not upload, reveal, or sync: + +- `.env`, `.env.local`, `.env.*` +- App Store Connect `.p8` keys +- Google service-account JSON files +- signing keys, provisioning profiles, certificates, keystores, and JKS files +- npm, NuGet, Maven Central, CocoaPods, Fly, Convex, App Store, Google Play, or + payment provider credentials + +One-time GV login URLs and workspace URLs should be treated as sensitive access +links. Do not paste them into issues, PRs, public docs, or long-lived logs. + +## Known GV baseline for this repo + +Validated on 2026-05-08 with a GV `agent-sandbox` environment: + +- Repo onboarding with `--skip-env` completed. +- `gv repo env list --repo openiap --json` returned an empty env var list. +- OpenAI auth status was disabled. +- GitHub access was enabled only after selected-repository approval. +- Cloud clone was clean on `main` from + `https://github.com/hyodotdev/openiap.git`. +- The default environment had `node`, `npm`, `corepack`, `python3`, `git`, and + `docker`. +- The default environment did not have `bun`, `yarn`, `java`, `swift`, + `flutter`, or `dotnet`. +- No `.devcontainer/devcontainer.json` existed in the repo at validation time. + +Because Bun is not available in the default GV environment, the safe current +pattern is to run Bun checks inside Docker containers with the workspace mounted +read-only. + +## Safe verification pattern + +Prefer an ephemeral Docker container with a read-only repo mount and an internal +copy: + +```bash +gv ssh --env agent-sandbox -- \ + 'docker run --rm \ + -v /home/hyo/workspace/openiap:/src:ro \ + -w /work \ + oven/bun:1.3.13 \ + bash -lc "cp -a /src/. /work && bun install --frozen-lockfile && bun run audit:docs"' +``` + +Why this pattern: + +- `:ro` prevents the container from writing to the GV checkout. +- `/work` is a temporary container copy, so `node_modules`, build output, and + generated files disappear when the container exits. +- It avoids syncing local env files or local uncommitted changes. + +After any GV run, verify both workspace cleanliness and env state: + +```bash +gv ssh --env agent-sandbox -- \ + 'cd ~/workspace/openiap && git status --short --branch' + +gv repo env list --repo openiap --json +``` + +## Verified safe smoke checks + +These checks have run successfully in the GV/Docker read-only pattern: + +```bash +# GQL tests +cd packages/gql && bun run test + +# Docs typecheck +cd packages/docs && bun run typecheck + +# Kit typecheck and tests +cd packages/kit && bun run typecheck && bun run test + +# Docs consistency audit +bun run audit:docs +``` + +Use these as the first GV regression suite for docs, GQL, and IAPKit +maintenance work. + +## Out of scope for GV until explicitly proven + +Do not use GV as the default runner for: + +- `packages/apple` SwiftPM/Xcode signing or release workflows. +- iOS/macOS Godot, Expo, React Native, KMP, Flutter, or MAUI device builds. +- Android/KMP release publishing that needs Maven Central signing credentials. +- Flutter pub.dev, npm, NuGet, CocoaPods trunk, GitHub release, or deployment + publishing. +- Fly/Convex production deploys. +- Any flow that requires production IAP, payment, App Store Connect, Google + Play, or signing credentials. + +Linux-friendly Android/KMP checks may become reasonable after the repository has +a minimal GV/devcontainer setup with Java installed, but production credentials +still remain out of scope. + +## Branch and PR workflow + +Use GV for isolated work, not direct `main` edits: + +1. Start from the clean cloud clone. +2. Create a branch such as `codex/docs-gv-audit` or `codex/kit-gv-smoke`. +3. Run only secret-free checks. +4. Review `git diff` and `git status`. +5. Push only intentional source changes. +6. Open a PR for normal CI review. + +Do not push release, signing, or deployment changes from GV without explicit +owner approval. + +## Future improvement + +If GV becomes part of regular maintenance, add a minimal devcontainer or setup +script for the Linux-friendly subset: + +- Bun pinned to the root `packageManager`. +- Node/Corepack. +- Java for Gradle checks. +- Optional Android command-line tooling if needed. + +Do not add Swift, Xcode, Flutter, .NET, signing tools, or production secret +setup to the first GV devcontainer. Keep the first iteration small and focused +on docs, GQL, kit, and non-release Android/KMP smoke checks. diff --git a/scripts/audit-docs.ts b/scripts/audit-docs.ts index d391541dc..e3366baa4 100644 --- a/scripts/audit-docs.ts +++ b/scripts/audit-docs.ts @@ -380,6 +380,13 @@ async function main() { 'purchase', 'product', 'subscription', + // Top-level scalar/list function parameters. These legitimately appear + // in API parameter lists but are not generated object fields. + 'program', + 'subscriptionIds', + 'tokenType', + 'groupId', + 'noticeType', 'continued', 'reconnect', 'cancel', From bc99e8e2d64add7c4e00dc3eb659283a08a2f638 Mon Sep 17 00:00:00 2001 From: hyochan Date: Fri, 8 May 2026 23:37:42 +0900 Subject: [PATCH 2/4] docs(gv): make workspace path portable --- knowledge/internal/08-gv-cloud-workspaces.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/knowledge/internal/08-gv-cloud-workspaces.md b/knowledge/internal/08-gv-cloud-workspaces.md index 03080b991..a1393b845 100644 --- a/knowledge/internal/08-gv-cloud-workspaces.md +++ b/knowledge/internal/08-gv-cloud-workspaces.md @@ -101,8 +101,11 @@ copy: ```bash gv ssh --env agent-sandbox -- \ - 'docker run --rm \ - -v /home/hyo/workspace/openiap:/src:ro \ + 'set -eu + OPENIAP_PATH="${OPENIAP_PATH:-$HOME/workspace/openiap}" + test -d "$OPENIAP_PATH" + docker run --rm \ + -v "$OPENIAP_PATH:/src:ro" \ -w /work \ oven/bun:1.3.13 \ bash -lc "cp -a /src/. /work && bun install --frozen-lockfile && bun run audit:docs"' From 15997f6b3ab07392d06059c9688c8dea58ab5d9c Mon Sep 17 00:00:00 2001 From: hyochan Date: Sat, 9 May 2026 00:00:46 +0900 Subject: [PATCH 3/4] docs(gv): document daily usage flow --- knowledge/internal/08-gv-cloud-workspaces.md | 40 ++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/knowledge/internal/08-gv-cloud-workspaces.md b/knowledge/internal/08-gv-cloud-workspaces.md index a1393b845..88856a76a 100644 --- a/knowledge/internal/08-gv-cloud-workspaces.md +++ b/knowledge/internal/08-gv-cloud-workspaces.md @@ -94,6 +94,46 @@ Because Bun is not available in the default GV environment, the safe current pattern is to run Bun checks inside Docker containers with the workspace mounted read-only. +## Day-to-day usage + +Use GV by opening an agent or editor attached to the cloud environment, then +give the task prompt there. The prompt is not a shell command. + +```bash +gv env use agent-sandbox + +# Open a cloud-attached agent/editor. +gv open opencode --env agent-sandbox +gv open codex --env agent-sandbox +``` + +Use `gv ssh` for direct terminal checks in the cloud workspace: + +```bash +gv ssh --env agent-sandbox +cd ~/workspace/openiap +git status --short --branch +``` + +For investigation-only work, make the boundary explicit: + +```text +Investigate issue 104 and the GQL -> SDK sync flow. +List the affected packages and propose a fix plan. +Do not change code, commit, push, create PRs, read env files, or run deploy, +release, signing, publish, or credential-related commands. +``` + +For maintenance work that may edit code, require an isolated branch and scoped +verification: + +```text +Create a branch named codex/. +Make the smallest safe change for the requested docs/GQL/kit issue. +Do not touch env, signing, release, deploy, or publish files. +Run only the relevant secret-free checks, then summarize the diff and results. +``` + ## Safe verification pattern Prefer an ephemeral Docker container with a read-only repo mount and an internal From 30a309c387ee011223850a37deb71f0cf71e1b89 Mon Sep 17 00:00:00 2001 From: hyochan Date: Sat, 9 May 2026 00:05:18 +0900 Subject: [PATCH 4/4] docs(gv): clarify smoke check context --- knowledge/internal/08-gv-cloud-workspaces.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/knowledge/internal/08-gv-cloud-workspaces.md b/knowledge/internal/08-gv-cloud-workspaces.md index 88856a76a..af62aeed3 100644 --- a/knowledge/internal/08-gv-cloud-workspaces.md +++ b/knowledge/internal/08-gv-cloud-workspaces.md @@ -169,7 +169,10 @@ gv repo env list --repo openiap --json ## Verified safe smoke checks -These checks have run successfully in the GV/Docker read-only pattern: +These checks have run successfully inside the Docker `/work` copy in the +GV read-only pattern, not directly in the default GV host shell. Bun is not +available in the default GV environment unless a future setup script installs +it. ```bash # GQL tests