@spacemade/ui 0.0.1

package/README.md

@@ -0,0 +1,705 @@
+# App Studio
+
+App Studio is a reusable full-stack SaaS admin starter for building and operating custom products.
+
+By default, the admin app is intended to run under a mounted path such as `/admin`, while the root `/` can be served by a separate CMS or public website.
+
+The intended use is:
+
+- start with a real repo, not just a UI kit
+- keep a reusable core for auth, users, orgs, billing, settings, and admin
+- add your own product-specific models, pages, and workflows on top
+- ship with your own containers, pipelines, and deployment flow
+- bootstrap new products with `app.sh`, install the NPM UI/API packages, then generate app code from an editable schema
+
+This is the right shape for products such as:
+
+- an admin portal
+- a site provisioning portal
+- a multi-tenant control plane
+- a customer success or operations dashboard
+- a product that sells plans and manages installations
+
+## What App Studio Is
+
+App Studio is a repo-level starter for:
+
+- `app`: React/Next admin UI
+- `api`: backend service
+- `devops`: Docker and pipeline setup
+- `billing`: Stripe-ready product model pattern
+- `core domains`: users, orgs, projects, providers, settings, admin
+
+App Studio now supports a hybrid bootstrap model: this repo remains the source foundation, while reusable API/UI pieces can be published as NPM packages and installed into product repos.
+
+## Bootstrap With app.sh
+
+For new projects, start with a blank repo and download `app.sh` into the repo root.
+
+```bash
+curl -fsSL "$APPSTUDIO_BOOTSTRAP_URL" -o app.sh
+chmod +x app.sh
+./app.sh init --name my-product
+./app.sh edit-schema
+./app.sh install
+./app.sh generate
+```
+
+The release pipeline publishes the latest script to the `application-studio` S3 bucket by default:
+
+```bash
+curl -fsSL "https://s3.amazonaws.com/application-studio/app.sh" -o app.sh
+```
+
+The S3 release upload is configured with:
+
+```text
+APPSTUDIO_BOOTSTRAP_S3_URI=s3://application-studio/app.sh
+```
+
+The bucket or CloudFront distribution should allow public read access to that object. If the bucket still uses object ACLs, set `APPSTUDIO_BOOTSTRAP_S3_ACL=public-read`; otherwise leave it unset and use a bucket policy. The pipeline also uploads a versioned copy next to it, such as `app-0.1.0.sh`, unless `APPSTUDIO_BOOTSTRAP_S3_VERSION_URI` is set.
+
+If you already have `app.sh`, the local commands are:
+
+```bash
+./app.sh init --name my-product
+./app.sh edit-schema
+./app.sh install
+./app.sh generate
+```
+
+The intended flow is:
+
+1. `init` creates a lightweight local skeleton and `appstudio.schema.json`.
+2. You edit the schema for the product shape.
+3. `install` installs the reusable UI and API packages from NPM, or links local checkouts when configured.
+4. `generate` links local packages when available, then overlays local routes, models, pages, and module code on top.
+
+The generated repo also gets its own deployable-app scaffold:
+
+- `bitbucket-pipelines.yml` for Docker image publish and CloudFormation deploy
+- `docker-compose.yml` for local app/API development
+- `devops/docker/Dockerfile.app`
+- `devops/docker/Dockerfile.api`
+- `devops/cloudformation/app.yml`
+
+The default packages are `@spacemade/ui` and `@spacemade/api`:
+
+```bash
+./app.sh install
+```
+
+When developing the reusable packages and a product app side by side, point the app at the local checkout so imports resolve through `node_modules` exactly like the published packages:
+
+```bash
+SPACEMADE_UI_PATH=../appstudio \
+SPACEMADE_API_PATH=../appstudio/api \
+./app.sh install
+./app.sh generate
+```
+
+`./app.sh link-core ../appstudio` also works directly. With no path, it checks common sibling folders such as `../appstudio`, `../spacemade-ui`, and `../ui`.
+
+That creates:
+
+```text
+node_modules/@spacemade/ui  -> ../appstudio
+node_modules/@spacemade/api -> ../appstudio/api
+```
+
+This is the best local loop because the product app exercises the real package names and package boundaries while still picking up edits from the reusable package checkout immediately.
+
+## Repo And NPM Package
+
+Use the repo when you need:
+
+- frontend app structure
+- backend API structure
+- data model conventions
+- Docker and deployment setup
+- pipelines
+- environment contracts
+- product bootstrapping
+
+Use NPM packages for:
+
+- reusable API/UI core
+- shared UI components
+- shared types and schemas
+- Stripe and auth helpers
+- the schema-driven generator
+
+Recommended strategy:
+
+1. Keep `appstudio` as the source repo for the reusable UI, API, and generator.
+2. Publish stable pieces as `@spacemade/*` packages.
+3. Build product repos from a blank skeleton using `app.sh`.
+4. Let the generator add product-specific modules on top of the installed packages.
+
+For example:
+
+```text
+appstudio/                # starter repo
+admin-app/             # product repo built from appstudio
+
+@spacemade/ui          # reusable admin UI and generator CLI
+@spacemade/api         # reusable API service
+@spacemade/types       # shared types
+@spacemade/stripe      # Stripe helpers
+@spacemade/auth        # auth helpers
+```
+
+## Best Fit Product Example
+
+If you are building an Admin portal, `appstudio` should power:
+
+- account creation and login
+- organization and workspace management
+- user invites and roles
+- pricing and subscriptions
+- product instance creation
+- install management
+- environment and provider configuration
+- support/admin operations
+
+Then your product repo adds:
+
+- product-specific models
+- site/install lifecycle flows
+- domain mapping
+- provisioning actions
+- template selection
+- product management UI
+
+## Current Structure
+
+```text
+api/
+  lib/
+    controllers/
+    data/
+    models/
+    repositories/
+    services/
+  pages/api/
+devops/
+  docker/
+src/
+  app/
+  components/
+  config/
+  data/
+  lib/
+  types/
+docs/
+  cms-quickstart.md
+  gallery-quickstart.md
+  gpu-marketplace-quickstart.md
+  metaverse-quickstart.md
+  migration-plan.md
+  modules.md
+  nft-quickstart.md
+  simple-cms-quickstart.md
+docker-compose.yml
+bitbucket-pipelines.yml
+cmd.sh
+```
+
+## Mounted Admin App
+
+App Studio is designed to work as an admin application mounted under a subpath.
+
+Examples:
+
+- `/admin`
+- `/custom`
+
+Recommended deployment shape:
+
+- `/` serves the public CMS or website
+- `/admin` proxies to the App Studio React app
+- `/admin/api` or a sibling API hostname proxies to the App Studio API service
+
+Main setting:
+
+- `NEXT_PUBLIC_APP_BASE_PATH=/admin`
+
+This is wired through:
+
+- [`next.config.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/next.config.ts)
+- [`src/config/app.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/config/app.ts)
+- [`src/lib/app-paths.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/lib/app-paths.ts)
+- [`middleware.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/middleware.ts)
+
+## Core Architecture
+
+App Studio should own the reusable SaaS backbone.
+
+Core domains:
+
+- auth
+- users
+- orgs
+- projects
+- providers
+- pricing
+- settings
+- admin
+
+Product-specific domains should be added by the product repo.
+
+Examples:
+
+- `admin-install`
+- `admin-template`
+- `managed-site`
+- `managed-domain`
+- `managed-module`
+- `managed-theme`
+- `deployment-job`
+
+## How To Build A Custom Product On Top
+
+### 1. Start With App Studio Core
+
+Keep these areas generic:
+
+- login and session model
+- org and membership model
+- user roles and admin permissions
+- plans and billing entities
+- provider registry
+- settings pages
+- admin shell
+
+### 2. Add Your Product Domain
+
+For a notepad app, add models such as:
+
+- `Notebook`
+- `Note`
+- `NoteTag`
+- `SharedNotePermission`
+
+For an Admin portal, add models such as:
+
+- `AdminInstall`
+- `AdminTemplate`
+- `AdminDomain`
+- `ProvisionJob`
+- `ManagedEnvironment`
+- `BackupJob`
+
+### 3. Add Product Routes
+
+Examples:
+
+- `/installs`
+- `/installs/[id]`
+- `/templates`
+- `/domains`
+- `/deployments`
+
+### 4. Add Product API
+
+Examples:
+
+- `api/pages/api/installs/index.ts`
+- `api/pages/api/installs/[id].ts`
+- `api/pages/api/templates/index.ts`
+- `api/pages/api/provision/index.ts`
+
+### 5. Add Product Services
+
+Examples:
+
+- install provisioning service
+- domain connection service
+- deployment orchestration service
+- backup and restore service
+
+## Backend Pattern
+
+The API follows this structure:
+
+- `models`: domain shapes
+- `repositories`: data access
+- `services`: business logic
+- `controllers`: response assembly
+- `pages/api`: HTTP handlers
+
+Example flow:
+
+```text
+HTTP route
+  -> controller
+  -> service
+  -> repository
+  -> model/data
+```
+
+Current reusable examples live in:
+
+- [`api/lib/models`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/models)
+- [`api/lib/services`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/services)
+- [`api/lib/controllers`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/controllers)
+- [`api/pages/api`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/pages/api)
+
+## Base App Startup
+
+The reusable admin base now includes starter coverage for:
+
+- activity
+- addresses
+- forms
+- invoices
+- media
+- orgs
+- posts
+- products
+- projects
+- providers
+- purchases
+- sites
+- subscriptions
+- tags
+- tickets
+- usage
+- users
+
+For database startup in the API service:
+
+1. Configure database env vars for `api`
+2. Run `npm run migrate:up`
+3. Run `npm run seed:up`
+
+Reference files:
+
+- [`api/migrations/20260326093000-baseline.js`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/migrations/20260326093000-baseline.js)
+- [`api/seeders/20260326094500-base-app.js`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/seeders/20260326094500-base-app.js)
+- [`api/doc/migration-baseline.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/doc/migration-baseline.md)
+
+## Local Docker Dev
+
+App Studio is set up for local containerized development with bind mounts and watch-friendly polling.
+
+Main files:
+
+- [`docker-compose.yml`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docker-compose.yml)
+- [`devops/docker/Dockerfile.app`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/Dockerfile.app)
+- [`devops/docker/Dockerfile.api`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/Dockerfile.api)
+- [`devops/docker/entrypoint/app-docker-entrypoint.sh`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/entrypoint/app-docker-entrypoint.sh)
+- [`devops/docker/entrypoint/api-docker-entrypoint.sh`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/entrypoint/api-docker-entrypoint.sh)
+- [`.env`](/mnt/c/wsl/osirus-ai/submodules/appstudio/.env)
+
+Recommended local flow:
+
+1. Configure `.env`
+2. Start containers with `docker compose up --build`
+3. Open the app on `http://localhost:3000`
+4. Open the API on `http://localhost:3001`
+5. Run `npm run migrate:up` and `npm run seed:up` inside the API container when ready
+
+Dev-friendly behavior included:
+
+- bind mounts for app and API source
+- polling enabled for WSL/docker watch behavior
+- named volumes for `node_modules` and `.next` cache
+- API bind mounts for `config`, `migrations`, `seeders`, and `lib`
+- default local auth/session env values for quick access
+
+Important local envs:
+
+- `NEXT_PUBLIC_APP_BASE_PATH`
+- `WATCHPACK_POLLING_INTERVAL`
+- `API_WATCHPACK_POLLING_INTERVAL`
+- `NEXT_PUBLIC_DEFAULT_USER_ID`
+- `NEXT_PUBLIC_DEFAULT_ROLE`
+- `NEXT_PUBLIC_DEFAULT_ORG_ROLE`
+- `DEFAULT_USER_ID`
+- `DEFAULT_ROLE`
+- `DEFAULT_ORG_ROLE`
+
+## Security Layer
+
+App Studio now includes a reusable starter security layer for the admin surface.
+
+Frontend security files:
+
+- [`middleware.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/middleware.ts)
+- [`src/helpers/permissions/index.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/helpers/permissions/index.ts)
+- [`src/lib/auth.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/lib/auth.ts)
+- [`src/lib/security.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/lib/security.ts)
+
+API security files:
+
+- [`api/lib/auth/session.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/auth/session.ts)
+- [`api/lib/security/permissions.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/security/permissions.ts)
+- [`api/lib/middleware/with-auth.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/middleware/with-auth.ts)
+
+Default behavior:
+
+- `/` and `/pricing` remain public
+- core app routes require an authenticated session
+- `admin` requires admin-style access
+- API domain routes require auth and check CRUD permission by role
+
+## Agents
+
+App Studio now includes starter agent scaffolding, but agents are treated as part of the product being built, not tied to a fixed legacy app.
+
+Files:
+
+- [`src/app/agents/page.tsx`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/app/agents/page.tsx)
+- [`api/lib/models/agent.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/models/agent.ts)
+- [`api/lib/data/agents.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/lib/data/agents.ts)
+- [`api/pages/api/agents/index.ts`](/mnt/c/wsl/osirus-ai/submodules/appstudio/api/pages/api/agents/index.ts)
+
+Use agents for the current product:
+
+- support agents for the admin portal
+- publishing agents for the CMS website
+- provisioning agents for install systems
+- product-specific automation workers
+
+Starter session inputs:
+
+- frontend cookies: `appstudio_user_id`, `appstudio_role`, `appstudio_org_role`, `appstudio_active_org_id`, `appstudio_active_project_id`
+- API headers: `x-appstudio-user-id`, `x-appstudio-role`, `x-appstudio-org-role`, `x-appstudio-org-id`, `x-appstudio-project-id`
+- env fallbacks for local setup: `NEXT_PUBLIC_DEFAULT_USER_ID`, `NEXT_PUBLIC_DEFAULT_ROLE`, `NEXT_PUBLIC_DEFAULT_ORG_ROLE`, `DEFAULT_USER_ID`, `DEFAULT_ROLE`, `DEFAULT_ORG_ROLE`
+
+## Frontend Pattern
+
+The frontend should stay focused on:
+
+- dashboards
+- settings
+- admin workflows
+- product configuration
+- entity listing/detail pages
+
+The reusable shell lives in:
+
+- [`src/app/layout.tsx`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/app/layout.tsx)
+- [`src/components`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/components)
+- [`src/config`](/mnt/c/wsl/osirus-ai/submodules/appstudio/src/config)
+
+## Stripe Setup
+
+Use Stripe as part of the reusable core, not as product-only code.
+
+Stripe belongs in the platform layer because most admin products need:
+
+- products
+- plans
+- subscriptions
+- invoices
+- payment method handling
+- entitlement checks
+
+### Recommended Stripe Model
+
+Create platform entities like:
+
+- `BillingProduct`
+- `BillingPlan`
+- `Subscription`
+- `Invoice`
+- `UsageEvent`
+
+Then map product-specific entitlements on top:
+
+- `install_limit`
+- `template_limit`
+- `custom_domain_limit`
+- `backup_retention_days`
+
+### Suggested Stripe Flow
+
+1. User signs up.
+2. User creates or joins an org.
+3. User selects a plan.
+4. Stripe checkout creates a subscription.
+5. Webhook updates local subscription state.
+6. Entitlements unlock product actions.
+
+### Stripe Setup In App Studio
+
+Add these areas next:
+
+- `api/lib/models/billing-*`
+- `api/lib/services/stripe-service.ts`
+- `api/lib/controllers/stripe-controller.ts`
+- `api/pages/api/webhook/stripe.ts`
+- `src/app/pricing`
+- `src/app/settings/billing`
+
+### Example Environment Variables
+
+```env
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_PUBLISHABLE_KEY=pk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx
+```
+
+## Handling Users
+
+User handling belongs in core.
+
+Recommended platform user model:
+
+- `User`
+- `UserPassword` or auth provider identity
+- `Org`
+- `OrgMembership`
+- `UserRole`
+- `Invite`
+
+Recommended roles:
+
+- owner
+- admin
+- editor
+- viewer
+
+For an Admin portal, users should be scoped through org/workspace membership, not just global access.
+
+That gives you:
+
+- multi-tenant separation
+- team billing ownership
+- shared installations inside an org
+- support/admin escalation paths
+
+## Admin Portal Design
+
+If the goal is “buy and launch and manage product installs”, your product repo should likely include these domains:
+
+### Platform Core
+
+- users
+- orgs
+- billing
+- admin
+- providers
+- settings
+
+### Product Layer
+
+- install catalog
+- provisioning jobs
+- deployment environments
+- connected domains
+- backups
+- templates
+- themes
+- plugins/modules
+
+### Key Workflows
+
+1. Customer signs up.
+2. Customer picks a plan.
+3. Customer creates an org/workspace.
+4. Customer launches an install.
+5. System provisions the install.
+6. Customer manages domains, templates, and billing.
+7. Admin/support can inspect and intervene when needed.
+
+## Containers
+
+App Studio includes starter container files:
+
+- [`docker-compose.yml`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docker-compose.yml)
+- [`devops/docker/Dockerfile.app`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/Dockerfile.app)
+- [`devops/docker/Dockerfile.api`](/mnt/c/wsl/osirus-ai/submodules/appstudio/devops/docker/Dockerfile.api)
+
+Current local services:
+
+- `app`
+- `api`
+- `mysql`
+
+Start from:
+
+- [`.env`](/mnt/c/wsl/osirus-ai/submodules/appstudio/.env)
+
+## Commands
+
+App Studio includes a repo command wrapper modeled after the parent project:
+
+- [`cmd.sh`](/mnt/c/wsl/osirus-ai/submodules/appstudio/cmd.sh)
+
+Examples:
+
+```bash
+./cmd.sh init cms
+./cmd.sh init cms --force
+./cmd.sh init simple-cms
+./cmd.sh init gallery
+./cmd.sh init nft
+./cmd.sh init gpu
+./cmd.sh init metaverse
+./cmd.sh init all --force
+```
+
+## Pipelines
+
+Bitbucket pipeline file:
+
+- [`bitbucket-pipelines.yml`](/mnt/c/wsl/osirus-ai/submodules/appstudio/bitbucket-pipelines.yml)
+
+Current pipeline shape:
+
+- PR/package verification with `npm pack --dry-run`
+- tag-based publish for `@spacemade/ui`
+- tag-based publish for `@spacemade/api`
+- tag-based upload of `app.sh` to `s3://application-studio/app.sh`
+
+Generated product apps should own their Docker images, CloudFormation templates, and runtime deployment pipeline.
+
+## Environment Contract
+
+Example frontend/platform config:
+
+```env
+NEXT_PUBLIC_APP_NAME=App Studio
+NEXT_PUBLIC_ENABLED_MODULES=projects,orgs,providers,users,pricing,settings,admin
+```
+
+Example richer product:
+
+```env
+NEXT_PUBLIC_APP_NAME=Admin
+NEXT_PUBLIC_ENABLED_MODULES=projects,orgs,providers,users,pricing,settings,admin
+```
+
+For an Admin product, avoid turning on AI-style modules unless you actually build them.
+
+## Recommended Next Steps
+
+1. Add auth and session handling.
+2. Add org membership and invite models.
+3. Add Stripe models and webhook handling.
+4. Add install models.
+5. Add provisioning job service.
+6. Add deployment/provider adapters.
+7. Add admin pages for install lifecycle management.
+
+## Practical Recommendation
+
+Use this repo as the source for the reusable `@spacemade/ui` and `@spacemade/api` packages.
+
+Build each Admin product as a lightweight repo that installs or links both packages.
+
+Keep product-specific schema, generated overlays, routes, and custom code in the product repo.
+
+If you later discover stable cross-product modules, extract them into additional `@spacemade/*` packages.
+
+For a CMS-style install system, see:
+
+- [`docs/cms-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/cms-quickstart.md)
+- [`docs/simple-cms-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/simple-cms-quickstart.md)
+- [`docs/gallery-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/gallery-quickstart.md)
+- [`docs/nft-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/nft-quickstart.md)
+- [`docs/gpu-marketplace-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/gpu-marketplace-quickstart.md)
+- [`docs/metaverse-quickstart.md`](/mnt/c/wsl/osirus-ai/submodules/appstudio/docs/metaverse-quickstart.md)