siteplane 0.1.67 → 0.2.0-next.0

package/README.md

@@ -1,151 +1,55 @@
 # siteplane
 
-**Image-policy preparation:** When the scan includes image fields, `withSiteplane` prepares
-Next Image and existing Next-config CSP headers for Siteplane's image route and your website's
-`/siteplane-assets/` path. Existing image sources stay in place. Local builds require the same public HTTPS
-`SITEPLANE_SITE_ORIGIN` supplied by `setup deploy`. The wrapper adds only those exact patterns: existing
-sources, custom loaders and redirect settings remain unchanged. Preflight still flags custom loaders and CSP
-in middleware, proxy or app source for explicit delivery checks. Keep existing policies and verify Siteplane
-images through the website's actual renderer. This preparation does not authorize hosting.
-
-Public Siteplane CLI for connected-site setup, field synchronization, Analytics
-instrumentation and Booking integration.
-
-## Controlled guest review
-
-After a controlled accountless setup reaches `ready_for_review`, run `siteplane setup review`
-in the same website repository. Its protected local installation key opens access to that project's
-saved review without creating another site or deployment. Give the one-time link to the user;
-they choose **Open review** in their own browser. Do not consume the link on their behalf.
-Issue a fresh link only when needed. The URL fragment is a short-lived credential, so do not
-write it to source, documentation, analytics or shared logs. Guest review can organize and finish
-the setup; activation and account ownership require the later claim step. This entry remains
-controlled by the existing beta and launch gates.
-
-### Controlled claim confirmation
-
-When the signed-in review supplies a claim code, run `siteplane setup claim inspect --code <code>`
-in the original repository. Show the returned account, workspace and website to the user. After
-they explicitly approve that concrete request, run `siteplane setup claim confirm --code <code>
---request <requestId>`. Inspection never confirms automatically. A code alone cannot claim a website;
-the command also requires the original local installation key.
-
-Confirmation saves the receipt in the ignored local credentials file before acknowledging it to
-the server. If the response is lost, retry the same code and request. Keep the existing project,
-connection and deployment. Claim revokes guest access and preserves only the still-open setup rights;
-it does not activate modules or reopen a finished setup. The browser Auth/claim flow is still under
-development, and the general accountless entry remains closed.
-
-## Initial setup
-
-Copy the setup prompt in Siteplane, then run its exact one-time command in the
-website repository:
+Siteplane for Next.js websites (App Router, Next 15 and 16): content you can edit in Siteplane with the current
+content as fallback in your code, a Draft Mode preview for the editor, Booking and the `siteplane` CLI.
 
-```bash
-npx -y siteplane@<exact-version> setup preflight
-npx -y siteplane@<exact-version> init --setup-token <one-time-setup-grant>
-npx siteplane setup context
-```
+## Connect a website
 
-`init` exchanges the short-lived grant for the run-bound Project Connection and
-stores it only in the ignored `.siteplane/credentials.json`. No browser approval
-is required. The same connection resumes the open setup and review corrections
-until the owner completes or revokes the setup.
-
-`setup context` returns the single `siteplane.setup-task.v2` task: exact packages, current run,
-authorized modules/scopes, separate unchanged user instructions, environment provenance and one next action.
-An initial instruction such as `Only prices` does not start a correction workflow. The agent integrates
-Siteplane's existing CMS editing layer, preserving the website; it does not build a separate CMS.
-
-Report observed work with `siteplane setup activity --phase inspecting` (also integrating, deploying,
-verifying or repairing). Reports are limited to one per 30 seconds; context polling is not activity.
-Optional Analytics preparation uses this same connection with explicit authorization. It grants no
-activation, import, reporting, booking or publishing rights. Standalone bootstrap cannot replace an open task.
-
-`setup prepare` installs the task's exact packages and creates the narrow official runtime integration.
-The agent chooses and instruments content, then persists a separate, bounded summary:
-
-For a direct field ID, put `siteplane.attrs(fieldId, { routeKey })` on the visible
-element using the same canonical route pattern as its value call. The value call
-does not attach DOM metadata. Missing or mismatched DOM routes block apply and
-the Next build; dynamic pages use their pattern, such as `/services/[slug]`.
-Direct attrs defaults to `fieldType: "text"`; for longText, link and image,
-pass the matching `fieldType` explicitly. The value call does not infer it for attrs.
-`setup apply` reports `field_scan.attrs_field_type_mismatch` before any contract write.
-This type diagnostic remains a scanner warning for normal website builds.
+Run this in the website's folder, or tell your coding agent "Install Siteplane":
 
 ```bash
-siteplane setup apply --definition editor-definition.json --selection-summary-file selection.txt
-siteplane setup deploy --wait
+npx siteplane@next init
 ```
 
-Commit only intended source before deploy. The CLI securely transfers its Production environment, adopts or
-starts one matching deployment and verifies the actual build and signed runtime. Unchanged resume creates no
-new deployment. If the linked project has multiple verified, non-redirecting Production domains, select the
-canonical one on the first run with `siteplane setup deploy --wait --production-origin <https-origin>`. The CLI
-rejects foreign, redirect, branch and unverified domains, stores the binding and reuses it on resume. A saved
-15-minute provider deadline and operation identity prevent blind retries after response
-loss. If that deadline expires after the deploy was requested, rerun the same command: each invocation gets a
-bounded 120-second readback of that same operation. A ready result is adopted; a still-running or unreachable
-provider remains resumable and never authorizes a second deploy. Uploads use committed source in a temporary
-checkout; local credentials are never copied into it.
-
-For a lost connection, the owner chooses **Replace local connection** in the same open setup. Its new grant
-preserves the Site, Run, runtime key, revalidation generation, selected fields and provider admin-session secret.
-Completed setup credentials remain closed. Known package/workspace/provider conflicts are diagnosed before
-writes; support ranges do not trigger automatic framework or package-manager upgrades.
-
-## Accountless start
+Version 0.2 is on the `next` tag until it becomes `latest`.
 
-Use `setup start` for an explicit user request to integrate a website before creating an account.
-Save the user's exact editing instructions in a text file and pass `--instructions-file`; inline
-`--instructions` is not supported. Omit the file only when the user asks the agent to choose.
+`init` opens the approval page in the browser. There you sign up or sign in, create the website in Siteplane or pick
+an existing one, and click Connect. If you created the website in Siteplane first, its prompt names the site:
+`npx siteplane@<version> init --site <site ID>`.
 
-Before starting, add `.siteplane/credentials.json` to the repository’s `.gitignore`. Start rejects tracked or
-unprotected credentials before any provisioning request.
-
-```bash
-npx -y siteplane@0.1.61 setup start --modules editing --instructions-file instructions.txt
-npx -y siteplane@0.1.61 setup context
-```
+`init` then writes `siteplane.config.json`, installs this package, wraps `next.config` in `withSiteplane`, adds the
+route `app/api/siteplane/[...siteplane]/route.ts` and `<SiteplaneBridge />`, and prints the task for the agent.
+Siteplane needs no environment variables or secrets in your project.
 
-Start performs read-only preflight and saves the installation key and original request privately before the
-first provisioning call. Select `editing,analytics` only when explicitly requested. Retry in the same directory
-with the same request after interruption; configuration without credentials produces a diagnosis, never a silent
-replacement project. The returned task carries the provisional assignment and deadline. After verification,
-`setup review` opens the saved guest review. The user can create an account or sign in from that review;
-inspect and confirm only their concrete claim request in this repository. Claim preserves the review and
-returns it to the owner's account; it does not activate editing or analytics.
+## Field API
 
-## Approved fields
+```tsx
+import { siteplane } from "siteplane";
 
-Run the exact command from Siteplane's compact apply prompt. It authenticates
-with the local Project Connection and reads the approved snapshot without asking
-the user to paste its JSON:
+const title = await siteplane.text("home.hero.title", "Fresh rolls since 1920");
 
-```bash
-siteplane setup fields apply-context --plan-id <plan-id> --snapshot-hash <sha256>
-siteplane setup fields apply-context --plan-id <plan-id> --snapshot-hash <sha256> --route / --offset 0
+<h1 {...siteplane.attrs("home.hero.title")}>{title}</h1>;
 ```
 
-The first call returns route counts. Route calls return at most 25 approved fields
-and a `nextOffset`; continue until it is `null`.
+Types: `text`, `longText`, `link` (`{ href, label }`) and `image` (`{ src, alt }`). Values load once per request and
+are cached for 60 seconds; without Siteplane the fallbacks render.
 
-## Analytics
+## Commands
 
 ```bash
-siteplane analytics init --agent-client codex
-siteplane analytics check
-siteplane analytics sync
-siteplane analytics test --page-url https://example.com
-siteplane analytics import --file provider-export.json
+npx siteplane task                    # the task for the agent
+npx siteplane check                   # checks the fields in the code
+npx siteplane sync                    # checks and reports the fields to Siteplane
+npx siteplane status --url <address>  # checks a deployed address
 ```
 
-Analytics commands reuse `siteplane.config.json` and the untracked
-`.siteplane/credentials.json` Project Connection. Provider import apply requires
-`--apply --confirm-hash <hash> --yes` and an active owner-approved grant.
+Optional display names for new fields go into `siteplane.labels.json` (`{ "home.hero.title": "Hero headline" }`).
+
+A website with `basePath` in `next.config` needs no extra setup. Check it with the base path in the address
+(`npx siteplane status --url https://www.example.com/docs`); Siteplane saves that address as the website URL and
+reaches the website below it.
 
-## Booking without Editor setup
+## Booking
 
 ```ts
 import { withSiteplane } from "siteplane/next";
@@ -153,7 +57,16 @@ export default withSiteplane(nextConfig, { booking: { site: "<immutable-site-id>
 ```
 
 The wrapper adds `/booking/:path*` as a `beforeFiles` rewrite to Siteplane and preserves existing rewrite sections.
-Without `siteplane.config.json`, it skips Editor scanning, headers and build proof. Use `<a href="/booking">`
-instead of `next/link`; exclude this path from customer middleware. Configure the public booking address in
-Siteplane and permit Siteplane/Stripe assets and connections in the customer CSP. `siteplane booking check`
-verifies the Site ID in `next.config.*`. The public API uses Site ID plus allowed Origin; no raw Booking key is needed.
+Use `<a href="/booking">` instead of `next/link`; exclude this path from customer middleware.
+
+```bash
+npx siteplane booking init
+npx siteplane booking check
+npx siteplane booking sync
+npx siteplane booking test
+```
+
+`booking sync` and `booking test` read the Site ID from `siteplane.booking.json` and connect through the same browser
+approval. The agent connection is stored in the user config directory (`$SITEPLANE_CONFIG_DIR`,
+`$XDG_CONFIG_HOME/siteplane`, `%APPDATA%\siteplane` or `~/.config/siteplane`), never in the project; `--no-browser`
+skips opening the browser.