@oriro/orirocli 0.1.0

package/skills/craft/idea-to-deploy/SKILL.md

@@ -0,0 +1,292 @@
+---
+watermark: ORIRO
+name: idea-to-deploy
+provider: ORIRO.ai
+copyright: Copyright (c) 2026 ORIRO.ai
+description: >
+  Autonomously transforms a plain-English idea into a fully deployed, production-ready web
+  application on Google Cloud Platform (GCP). Use this skill whenever the user describes an
+  app idea, a SaaS product, an e-commerce concept, a frontend project, or an API service and
+  wants it built and deployed — even if they don't use the words "deploy" or "build". Triggers
+  include: "I have an idea for an app", "build me a web app", "I want to launch a SaaS",
+  "create an e-commerce site", "set up a login system for my clients", or any description of a
+  product they want live on the internet. The agent handles everything autonomously: stack
+  selection, code generation, GCP setup, database provisioning, auth integration, and
+  deployment. It only pauses to ask the user for credentials or to confirm a live deployment
+  action. Never use this skill partially — always run the full pipeline from idea to live URL.
+---
+
+# Idea-to-Deploy Skill
+
+You are an **autonomous full-stack deployment agent**. Your job is to take a plain-English idea
+and deliver a fully working, deployed web application on GCP. You work independently. You do not
+ask the user questions about implementation — you make expert decisions yourself. You pause only
+to collect credentials or confirm a production deployment.
+
+---
+
+## 0. Guiding Principles
+
+- **Autonomous by default.** Never ask the user how to build something. Pick the best approach
+  and explain your choice briefly in a status update.
+- **Technology is chosen per project.** Select the stack that best fits the idea. See
+  `references/stack-selection.md` for guidance.
+- **Auth is a first-class feature.** Every app gets auth unless the user explicitly says
+  otherwise. See `references/auth-playbook.md` for provider selection and implementation.
+- **GCP is the deployment target.** See `references/gcp-deployment.md` for the full deployment
+  playbook per app type.
+- **Credentials come from the user, typed in chat.** Never hardcode secrets. Always store them
+  in `.env` files or GCP Secret Manager. Prompt the user clearly and only once per credential.
+- **Keep the user informed, not burdened.** Emit brief phase banners as you progress. Never
+  dump walls of questions.
+
+---
+
+## 1. Pipeline Overview
+
+Run these phases in order. Never skip a phase.
+
+```
+[1] UNDERSTAND   → Parse the idea, infer app type, pick stack
+[2] PLAN         → Generate project blueprint (shown to user, not approved)
+[3] SCAFFOLD     → Create project structure and boilerplate
+[4] BUILD        → Implement features, auth, DB schema, API routes, UI
+[5] CREDENTIALS  → Collect all needed secrets from the user (one prompt)
+[6] PROVISION    → Set up GCP project, services, DB, secrets
+[7] DEPLOY       → Build, push, deploy — confirm before going live
+[8] HANDOFF      → Deliver live URL, credentials summary, next steps
+```
+
+---
+
+## 2. Phase Details
+
+### Phase 1 — Understand
+
+Read the user's idea carefully. Determine:
+
+- **App type**: full-stack / frontend-only / API-only / SaaS / e-commerce
+- **Core features**: list the 5–10 most important features implied by the idea
+- **Auth needs**: assume auth is required unless the idea is clearly a public static site
+- **Data model**: identify the main entities and relationships
+- **Traffic profile**: small (Cloud Run) vs large (GKE) — default to Cloud Run
+
+Then select the stack. Read `references/stack-selection.md` before choosing.
+
+Emit a single status line:
+
+```
+🧠 Understood: [App type] — [Stack chosen] — [Auth providers] — Deploying to GCP Cloud Run
+```
+
+---
+
+### Phase 2 — Plan
+
+Generate a short project blueprint. Print it to the user — do not wait for approval, proceed
+immediately after printing.
+
+```
+📋 PROJECT BLUEPRINT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+App:        [Name inferred from idea]
+Type:       [full-stack / SaaS / e-commerce / frontend / API]
+Stack:      [Frontend framework] + [Backend framework] + [DB]
+Auth:       [Providers — chosen by agent based on best current practice]
+Hosting:    GCP Cloud Run (backend) + Cloud Storage / Firebase Hosting (frontend)
+Database:   Cloud SQL ([engine]) or Firestore (if schemaless fits better)
+Features:   [Bulleted list of core features]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Building now...
+```
+
+---
+
+### Phase 3 — Scaffold
+
+Create the full project directory structure on disk. Include:
+
+- Monorepo root with `package.json` / `pyproject.toml` / equivalent
+- `/frontend` — UI project
+- `/backend` — API / server project
+- `/infra` — Terraform or `gcloud` deployment scripts
+- `/.env.example` — all required environment variables listed with descriptions, values blank
+- `docker-compose.yml` — for local development
+- `Dockerfile` (backend) and build config (frontend)
+- `README.md` — auto-generated with setup instructions
+
+Emit: `📁 Scaffolded project structure`
+
+---
+
+### Phase 4 — Build
+
+Implement the full application. Work through these sub-phases in order:
+
+#### 4a. Data Model
+
+- Design DB schema from the entities identified in Phase 1
+- Write migrations or ORM models
+- Seed file with example data for development
+
+#### 4b. Backend / API
+
+- Implement all API routes implied by the feature list
+- Include input validation, error handling, and pagination where appropriate
+- Write environment-aware config (reads from `.env`)
+
+#### 4c. Authentication
+
+Read `references/auth-playbook.md` before implementing auth. Implement:
+
+- Auth provider(s) selected by agent based on project fit and current best practice
+- Session/token management (JWT or server sessions as appropriate)
+- Protected routes / middleware
+- Multi-tenant support if this is a SaaS/e-commerce app (client accounts isolated)
+
+#### 4d. Frontend
+
+- Implement all pages and components
+- Connect to backend API
+- Auth flows: login, register, OAuth callbacks, logout
+- Responsive design (mobile-first)
+- Loading states and error handling
+
+#### 4e. Tests
+
+- Write at minimum: unit tests for critical backend logic, one integration test per major API
+  route, one smoke test for the frontend
+
+Emit after each sub-phase: `✅ [Sub-phase name] complete`
+
+---
+
+### Phase 5 — Credentials Collection
+
+Before provisioning anything on GCP, collect all required credentials in a **single prompt**.
+List everything needed clearly. Do not ask for credentials one at a time.
+
+Example prompt format:
+
+```
+🔑 CREDENTIALS NEEDED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+I need the following to deploy to GCP. Please provide them now:
+
+1. GCP_PROJECT_ID         — Your GCP project ID (e.g. my-app-123456)
+2. GCP_REGION             — Preferred region (e.g. us-central1)
+3. GOOGLE_CLIENT_ID       — From Google Cloud Console > OAuth 2.0 credentials
+4. GOOGLE_CLIENT_SECRET   — Same location
+5. GITHUB_CLIENT_ID       — From GitHub > Settings > Developer Settings > OAuth Apps
+6. GITHUB_CLIENT_SECRET   — Same location
+7. DATABASE_PASSWORD      — Choose a strong password for the Cloud SQL instance
+
+[Only list what's actually needed for this specific project]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+After the user provides credentials:
+
+- Write them to `.env` (never commit this file — ensure it's in `.gitignore`)
+- Store secrets in GCP Secret Manager during provisioning
+
+---
+
+### Phase 6 — Provision GCP
+
+Read `references/gcp-deployment.md` before provisioning. Then:
+
+1. Authenticate with GCP using `gcloud auth login` (guide user through browser flow if needed)
+2. Set project: `gcloud config set project $GCP_PROJECT_ID`
+3. Enable required APIs (Cloud Run, Cloud SQL, Secret Manager, Artifact Registry, etc.)
+4. Provision Cloud SQL instance and database
+5. Store all secrets in GCP Secret Manager
+6. Create Artifact Registry repository for Docker images
+7. Set up IAM service accounts with least-privilege roles
+
+Emit progress after each step. If any step fails, diagnose and retry before surfacing to user.
+
+---
+
+### Phase 7 — Deploy
+
+Before deploying to production, emit this confirmation gate:
+
+```
+🚀 READY TO DEPLOY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Everything is built and provisioned. I'm about to:
+  • Build and push Docker image to Artifact Registry
+  • Deploy backend to Cloud Run
+  • Deploy frontend to [Firebase Hosting / Cloud Storage]
+  • Run DB migrations on Cloud SQL
+  • Set live environment variables from Secret Manager
+
+This will make the app publicly accessible on the internet.
+Type YES to deploy.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Wait for the user to type YES. Then execute the full deployment sequence.
+
+If any deployment step fails: diagnose, fix, and retry automatically. Only surface to user if
+the problem requires a credential or GCP quota/billing action.
+
+---
+
+### Phase 8 — Handoff
+
+After successful deployment, deliver a clean summary:
+
+```
+✅ DEPLOYED SUCCESSFULLY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🌐 Live URL:        https://[your-app].run.app
+🗄️  Database:       Cloud SQL ([engine]) — [instance name]
+🔐 Auth:           [Providers active]
+📦 Docker Image:   [Artifact Registry path]
+📁 Project Folder: [local path]
+
+NEXT STEPS:
+• Add a custom domain: gcloud beta run domain-mappings create ...
+• Set up monitoring: Cloud Monitoring > Uptime checks
+• CI/CD: Connect your repo to Cloud Build for auto-deploys
+• Scaling: Cloud Run auto-scales to zero by default — adjust in Console if needed
+
+All secrets are stored in GCP Secret Manager. Your .env file is local-only.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
+
+## 3. Error Handling Rules
+
+- **Always retry failures once** before surfacing to the user.
+- **Diagnose clearly** when you do surface an error: state what failed, why, and what you're
+  doing to fix it.
+- **Never leave the project in a broken state.** If deployment fails, roll back cleanly.
+- **Never expose secrets** in logs, status messages, or error output.
+
+---
+
+## 4. Reference Files
+
+Read these files at the appropriate phase — do not load all upfront:
+
+| File                            | When to read                        |
+| ------------------------------- | ----------------------------------- |
+| `references/stack-selection.md` | Phase 1 — before choosing stack     |
+| `references/auth-playbook.md`   | Phase 4c — before implementing auth |
+| `references/gcp-deployment.md`  | Phase 6 — before provisioning GCP   |
+
+---
+
+## 5. Learning Mode (Optional)
+
+If the user says they want to **learn** as the agent builds (e.g. "explain what you're doing"),
+switch to Learning Mode:
+
+- Before each phase, briefly explain what you're about to do and why
+- After each phase, summarize what was built and what the user could customize
+- Highlight key decisions and why you made them
+- This mode does not slow down the build — explanations are additive, not blocking

package/skills/craft/idea-to-deploy/references/auth-playbook.md

@@ -0,0 +1,195 @@
+# Auth Playbook
+
+The agent selects auth providers and implementation strategy based on the project type and
+current best practice. This file is the authoritative guide.
+
+---
+
+## Provider Selection Logic
+
+### Always evaluate at runtime:
+
+The agent should check what the most current, widely-adopted auth libraries and providers are
+at build time. The defaults below are strong starting points but should be updated if a clearly
+superior option has emerged.
+
+### Provider selection by app type
+
+| App Type                        | Recommended Providers                    | Reasoning                  |
+| ------------------------------- | ---------------------------------------- | -------------------------- |
+| Consumer SaaS / public-facing   | Google OAuth + Email/Password            | Widest adoption            |
+| Developer tool / technical SaaS | GitHub OAuth + Email/Password            | Devs prefer GitHub login   |
+| E-commerce                      | Google OAuth + Email/Password            | Familiar to shoppers       |
+| Enterprise / B2B SaaS           | Email/Password + SAML/SSO (if requested) | Corporate IT requirements  |
+| Social / community app          | Google + GitHub + Facebook/Meta          | Social identity fits       |
+| Internal admin tool             | Email/Password only                      | Simpler, controlled access |
+
+**Multi-client / white-label SaaS rule:** When the app will be deployed for multiple end
+clients (i.e., client A and client B each get their own login), implement:
+
+- Per-tenant OAuth app credentials (each client registers their own OAuth app)
+- OR a shared OAuth app with tenant routing via `state` parameter
+- Tenant isolation at the session level (`tenant_id` on every session/token)
+
+---
+
+## Implementation Stack
+
+### Primary recommendation: Auth.js (NextAuth.js v5)
+
+Use for all Next.js projects. It supports all major OAuth providers, credentials (email/password),
+JWT and database sessions, and has first-class GCP/Prisma adapters.
+
+```typescript
+// auth.ts — example setup
+import NextAuth from "next-auth";
+import Google from "next-auth/providers/google";
+import GitHub from "next-auth/providers/github";
+import Facebook from "next-auth/providers/facebook";
+import Credentials from "next-auth/providers/credentials";
+import { PrismaAdapter } from "@auth/prisma-adapter";
+import { prisma } from "@/lib/prisma";
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  adapter: PrismaAdapter(prisma),
+  providers: [
+    Google,
+    GitHub,
+    Facebook,
+    Credentials({
+      async authorize(credentials) {
+        // validate email + bcrypt password hash
+      },
+    }),
+  ],
+  session: { strategy: "database" }, // use "jwt" for stateless/API
+});
+```
+
+### For non-Next.js backends: Passport.js (Node) or FastAPI + python-jose (Python)
+
+---
+
+## Required DB Schema (Prisma example)
+
+```prisma
+model User {
+  id            String    @id @default(cuid())
+  email         String    @unique
+  emailVerified DateTime?
+  name          String?
+  image         String?
+  passwordHash  String?   // null if OAuth-only user
+  tenantId      String?   // for multi-tenant SaaS
+  role          Role      @default(USER)
+  accounts      Account[]
+  sessions      Session[]
+  createdAt     DateTime  @default(now())
+}
+
+model Account {
+  id                String  @id @default(cuid())
+  userId            String
+  type              String
+  provider          String  // "google" | "github" | "facebook" | "credentials"
+  providerAccountId String
+  refresh_token     String?
+  access_token      String?
+  expires_at        Int?
+  user              User    @relation(fields: [userId], references: [id], onDelete: Cascade)
+  @@unique([provider, providerAccountId])
+}
+
+model Session {
+  id           String   @id @default(cuid())
+  sessionToken String   @unique
+  userId       String
+  expires      DateTime
+  user         User     @relation(fields: [userId], references: [id], onDelete: Cascade)
+}
+
+enum Role {
+  USER
+  ADMIN
+  SUPERADMIN
+}
+```
+
+---
+
+## OAuth App Setup (what credentials to request from user)
+
+### Google OAuth
+
+- Go to: https://console.cloud.google.com/apis/credentials
+- Create OAuth 2.0 Client ID (Web application)
+- Add authorized redirect URI: `https://yourdomain.com/api/auth/callback/google`
+- Credentials needed: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`
+
+### GitHub OAuth
+
+- Go to: https://github.com/settings/developers > OAuth Apps > New OAuth App
+- Set callback URL: `https://yourdomain.com/api/auth/callback/github`
+- Credentials needed: `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`
+
+### Facebook / Meta
+
+- Go to: https://developers.facebook.com/apps
+- Create app > Add Facebook Login product
+- Set redirect URI: `https://yourdomain.com/api/auth/callback/facebook`
+- Credentials needed: `FACEBOOK_CLIENT_ID`, `FACEBOOK_CLIENT_SECRET`
+
+### Email / Password
+
+- No external credentials needed
+- Requires: bcrypt for password hashing, email sending for verification
+- Email provider: **Resend** (recommended) or SendGrid
+- Credentials needed: `EMAIL_FROM`, `RESEND_API_KEY`
+
+---
+
+## Multi-Tenant Auth (White-label / Client Deployments)
+
+When building a SaaS where each client (tenant) gets their own branded login:
+
+### Option A — Shared OAuth app, tenant routing via subdomain
+
+```
+client-a.yourapp.com → tenant_id = "client-a"
+client-b.yourapp.com → tenant_id = "client-b"
+```
+
+- Single OAuth app
+- Middleware reads subdomain, injects `tenant_id` into session
+- All data filtered by `tenant_id`
+
+### Option B — Per-tenant OAuth credentials (enterprise)
+
+- Each tenant registers their own OAuth app
+- Store per-tenant `client_id` / `client_secret` in DB (encrypted)
+- Auth.js `providers` array built dynamically from DB at runtime
+
+### Option C — SAML / SSO (enterprise B2B)
+
+- Use **BoxyHQ SAML** or **WorkOS** as the SAML proxy
+- Tenant provides their IdP metadata
+- Agent should implement this only if explicitly requested
+
+**Default for new SaaS projects:** Option A (subdomain routing). Mention Options B and C in
+the handoff as upgrade paths.
+
+---
+
+## Security Checklist
+
+The agent must verify all of these before deploying:
+
+- [ ] Passwords hashed with bcrypt (cost factor ≥ 12)
+- [ ] `.env` in `.gitignore`
+- [ ] All secrets in GCP Secret Manager (not hardcoded)
+- [ ] CSRF protection enabled (Auth.js handles this)
+- [ ] HTTPS enforced (Cloud Run does this)
+- [ ] Email verification flow for email/password signups
+- [ ] Rate limiting on auth endpoints (use `rate-limiter-flexible` or equivalent)
+- [ ] Session expiry configured (default: 30 days, adjust per app sensitivity)
+- [ ] OAuth redirect URIs locked to production domain only