PerspectPerspectDocs
Go to Admin
View as Markdown

Building and Deploying Site Apps

Perspect's app platform lets you build and deploy a React Router v7 site directly from a Claude conversation — or from any MCP-connected agent. The sandbox holds your site's source code; the release gate ensures no code reaches production without a security review.

This guide covers the full loop: scaffold → edit → typecheck → review → deploy.

How the workspace works

Every Perspect site has an isolated sandbox. When you call app_init, the platform materializes your site's current source into that sandbox at /workspace. You edit there, build there, and when everything is clean you hand off to the release gate. Think of it as a live coding environment that lives next to your site rather than on your laptop.

CMS tools (page_*, product_*, category_*, media_*) are independent — they write directly to the platform's content layer and don't need app_init.

1. Initialize the workspace

app_init

No arguments needed. The site name comes from your MCP session. The tool fetches the current source from the platform's R2 checkpoint and unpacks it into /workspace.

Call app_init once at the start of a session. If the workspace already exists and is fresh, it returns immediately.

2. Explore and scaffold

Once initialized, you can list files, read source, and search:

app_list_files                         # top-level overview
app_list_files { "path": "app/routes" } # drill into a directory
app_read_file { "path": "app/routes.ts" }
app_search { "pattern": "getPerspectAb" }

For common patterns, the scaffold tool generates ready-wired routes:

app_scaffold_feature { "feature": "blog" }
app_scaffold_feature { "feature": "newsletter" }
app_scaffold_feature { "feature": "page" }

Scaffold writes route files, registers them in app/routes.ts, and ensures the shared SDK client/cache wiring is present. It won't overwrite existing files unless you pass "overwrite": true.

3. Edit source

Two tools cover source edits:

app_edit_file — surgical replacement, like a diff. Pass the path, the exact old_string to find, and the new_string to replace it with. Fails loudly if old_string doesn't match uniquely.

{
  "path": "app/routes/blog._index.tsx",
  "old_string": "limit: 10",
  "new_string": "limit: 20"
}

app_write_file — full file rewrite. Use this when creating new files or when the change is large enough that surgical replacement would be fragile.

{
  "path": "app/components/HeroBanner.tsx",
  "content": "export function HeroBanner() { ... }"
}

Delete files with app_delete_file. The tool confirms the path exists before removing it.

4. Validate before deploying

Run checks after each coherent change set — not after every single edit.

Fast check — route registration, SDK misuse scan. No TypeScript compilation. Catches structural issues quickly.

app_check { "mode": "fast" }

Release check — everything in fast, plus React Router typegen, local TypeScript compilation, and a diff summary against the current source checkpoint. Run this before requesting a security review.

app_check { "mode": "release" }

Typecheck alone — if you just want tsc output without the full check suite:

app_typecheck

Workspace diff — shows exactly what changed from the checkpoint. Use this to confirm the set of changes before handing off to the security reviewer.

app_workspace_diff

5. Deploy via the release gate

Every deploy goes through a two-step gate: Security Auditor review, then Release Manager deploy. Neither can be bypassed.

Step 1 — Security Auditor: record a review

The Security Auditor reviews the current workspace source and records a verdict.

{
  "tool": "release_record_security_review",
  "deploy_intent_type": "app_code_deploy",
  "max_severity": "none",
  "summary": "No external inputs, no secret access beyond existing PERSPECT_* bindings. New blog route reads public content API.",
  "blocking_findings": [],
  "deploy_requested": true
}
  • deploy_intent_type must be "app_code_deploy" for source deploys.
  • max_severity reflects the highest severity finding. none, info, and low approve; medium, high, or critical reject.
  • blocking_findings should be empty for a clean review. Any item here records a rejection unless it's a database destructive action with explicit user risk acceptance.
  • deploy_requested must be true — release tools refuse to run without an explicit user deploy request.

A review is tied to the exact source hash at review time. If you edit files after recording the review, the hash changes and the approval expires.

Step 2 — Release Manager: deploy

Once a review is approved, the Release Manager calls release_deploy:

{
  "tool": "release_deploy",
  "deploy_intent_type": "app_code_deploy",
  "deploy_requested": true
}

The tool recomputes the source hash and refuses if it doesn't match the approved review. On success, a build is queued.

Checking the build

Poll app_build_status after deploying. Wait 30–60 seconds between checks — the server throttles rapid polls while a build is running.

{
  "tool": "app_build_status",
  "build_id": "build_abc123"
}

Pass the build_id from the release_deploy response when available. Statuses: pending, deploying, deployed, failed.

6. Other tools

app_exec — run arbitrary shell commands in the sandbox. Use only for tasks not covered by dedicated tools: installing or verifying packages, running package scripts, diagnostics. Don't use it to read or write files — use the dedicated file tools instead.

app_git_status — check git integration status (read-only). Returns repo URL, branch, and last synced commit.

app_cancel_build — cancel a queued or in-progress build. Pass build_id from release_deploy.

Deployment pattern summary

app_init
→ app_scaffold_feature / app_edit_file / app_write_file
→ app_check { "mode": "release" }
→ release_record_security_review  (Security Auditor role)
→ release_deploy                  (Release Manager role)
→ app_build_status (poll until deployed)

What agents can and can't do

Agents can read, write, and build source. They cannot:

  • Deploy without a matching security review
  • Bypass the deploy_requested guard on release tools
  • Unbind or delete databases from the admin side (those are manual admin actions)

This means you can safely give an agent broad app-edit permissions without risk of silent production deploys.

Where to go next

  • Database and Migrations — provisioning D1 databases and running migrations through the release gate.
  • A/B Experiments — the experiment lifecycle from flag creation to results.
  • TypeScript SDK — the full client API your routes use to read content, products, and more.