Pages v1: guided Cloudflare setup and complete local publishing in the Alab binary

[harshitsinghbhandari]

Outcome

Make Pages a complete single-machine static publishing tool exposed as alab pages in the shared Alab binary. A user supplies a Cloudflare account, authorizes access, and points the CLI at a directory. The CLI guides authentication, provisions its Pages project when needed, and supports publishing, updating, listing, inspecting, opening, and deleting pages.

This issue specifies Pages v1. It does not authorize implementing the review tool or moving ownership of the combined binary release into this repository.

Confirmed product decisions

• Publish ready-made HTML, CSS, JavaScript, and supporting static assets only. No framework builds, application servers, or server-side functions.
• One machine owns the local content store and page identity. Local files and metadata are authoritative.
• Preserve alab pages put <directory> behavior: first use creates a page and stable URL; later uses update that same page at that same URL.
• Create the configured Cloudflare Pages project through the CLI if it does not exist. Reuse it when it exists.
• Default URLs are https://<project>.pages.dev/<page-id>/. Users do not need a domain or DNS configuration for v1.
• Custom-domain management is deferred beyond v1. Existing explicit custom-domain configuration should not be silently overwritten.
• Cross-machine recovery, remote inventory synchronization, pull, and pull --download are explicitly out of scope. Earlier discussion of those features was withdrawn.
• Complete Pages first. Review functionality will be specified separately.

Repository and distribution ownership

agentlab-in/alab-cli is the intended integration and release repository. It pins explicit tool versions and produces the combined alab executable for each supported platform. Pages remains responsible for its own implementation and its integration deliverable.

The user-facing distribution contract belongs in alab-cli: users download only the matching Alab binary. They must not separately install Node, npm, npx, Bun, Go, Python, Wrangler, or another supporting CLI to use Pages. Automatic extraction and execution of bundled components is acceptable; downloading missing runtimes or tools at first use is not.

Pages must be compatible with that contract. Its existing invocation of npx --yes wrangler@4 cannot remain a dependency on the user's environment. Use a self-contained deployment implementation or include everything required in the packaged deliverable. Do not mandate a language rewrite just to satisfy packaging.

Tool releases are explicitly pinned, not fetched from a moving main reference. The integration can consume versioned artifacts or pinned source. Exact artifact format, supported OS/CPU matrix, internal command interface, and packaging mechanism require coordination with alab-cli; they are not already selected by this spec. Build-time tooling in CI is allowed.

Current baseline

The repository currently documents a TypeScript/Node CLI, local content storage, stable IDs in <directory>/.alab/pages.json, and full-project deployments through externally invoked Wrangler. It already exposes put, ls, open, delete, and info. The current onboarding requires manual Cloudflare project creation and configuration.

Extend and document the existing lifecycle rather than treating CRUD as entirely absent. The primary gaps are guided onboarding/provisioning and compatibility with self-contained binary distribution.

User journey and responsibilities

1. Discover the tool

• alab pages, alab pages help, and alab pages --help provide useful command discovery and a concise first-use path.
• Command-specific help explains arguments, local effects, remote effects, and failure behavior.
• Help must work without credentials, network access, or provisioning.

2. Authenticate

Provide a guided Cloudflare login flow under Pages. Exact command spelling can follow the shared CLI convention; examples may use alab pages login.

User responsibilities:

1. Create or sign into their own Cloudflare account.
2. Create and supply an API token using the guided instructions.
3. Select the intended account if necessary, or provide its identifier when discovery is unavailable.
4. Supply the directory to publish.

CLI responsibilities:

• Explain the account access and token permissions required, with a link to the appropriate Cloudflare token-creation page.
• Accept the token without echoing it, validate access, and report invalid, expired, or insufficiently scoped credentials with actionable guidance.
• Store credentials locally with appropriate filesystem protection. Never include secrets in help, logs, JSON output, page metadata, or deploy contents.
• Preserve supported environment/configuration inputs for automation. Noninteractive execution must fail clearly on missing inputs rather than hang on a prompt.
• Distinguish authentication success from project setup and publishing success.

A browser OAuth integration is not a confirmed requirement. This flow can guide API-token creation; it must not promise authorization that Cloudflare does not support.

3. Provision the project

• Explain which account/project the CLI will use and what it will create before making provisioning changes.
• Store the selected account, project identity, production branch, and derived base URL locally.
• Check the configured project and reuse it when present. Create it when missing through the authenticated Cloudflare API.
• Make repeated setup idempotent: no duplicate projects or unintended project switches.
• Handle name collisions and permission failures explicitly. Do not adopt an unrelated project merely because its name looks familiar.
• No account-wide recovery scheme, ownership-marker discovery protocol, remote inventory, custom domain, or DNS change is required for v1.
• Do not assume ownership of a populated remote project permits overwriting it with an empty or unrelated local store. Explain that case and require an explicit setup decision.

4. Publish and update

• alab pages put <directory> retains its existing create-or-update behavior and stable local ID mapping.
• Validate the static directory before upload; preserve existing index-file requirements, size/file limits, ignored files, and path confinement unless separately justified.
• Publish a complete snapshot of the local store, preserving other locally stored pages when one page changes.
• Return the production URL based on the actual project configuration. Do not hard-code the AgentLab-owned domain for new users.
• Keep production deployment selection explicit and independent of the source directory's Git branch.
• A failed deploy must not be reported as a successful live update. Explain any local changes already made and how to retry with the same identity.

5. List, inspect, open, and delete

• Preserve ls, info, and open as useful local management surfaces. Lists show locally known page IDs and derived URLs; inspection reports useful configuration/state without secrets.
• Preserve delete: remove the selected locally known page and redeploy the remaining snapshot. Do not delete the entire Cloudflare project.
• Unknown IDs produce actionable errors. Deployment failures distinguish local deletion from successful removal on the live site.
• A separate update command is unnecessary: put already owns updates. Additional aliases are not required by this spec.

Existing behavior to preserve and document

• Stable identity in .alab/pages.json and the existing local content store.
• Static pages are public. An optional password-protected root listing is not authentication for individual pages.
• Existing --json, --skip-deploy, and --dry-run behavior where supported. JSON stdout stays machine-readable; progress belongs on stderr.
• Current dry-run behavior can mutate local state while skipping deployment. Do not claim it is read-only; changes to that contract need an explicit compatibility decision.
• Existing local configurations and explicit URLs must have a documented compatibility path. Never silently reassign existing pages to a new project.

Acceptance criteria

• A first-time user can follow CLI help to authenticate, provision a project, publish static files, and receive a Cloudflare default-domain URL without manually creating the project or configuring DNS.
• Repeated setup reuses the configured project, and invalid credentials, insufficient access, and project collisions produce actionable failures.
• Publishing the same directory twice retains its page ID and URL and updates the deployed content.
• Publishing or deleting one page preserves all other locally stored pages in the assembled snapshot.
• Listing, inspection, opening, and deletion work through the documented Pages commands without leaking credentials.
• Offline help and noninteractive error handling work without credential prompts or unexpected external writes.
• Existing state/configuration and automation flags have regression coverage and accurate documentation.
• README and CLI help explain the single-machine model, default URLs, user versus CLI responsibilities, and failure/retry behavior.
• Pages provides a documented, versionable integration deliverable for alab-cli; final artifact/interface details are agreed with that repository.
• The integrated executable is verified on each declared supported platform without separately installed language runtimes or supporting CLIs. Final combined-binary validation belongs to alab-cli; Pages supplies the relevant command smoke tests.
• Repository tests and build pass. Cloudflare interactions use mocks/fixtures for routine tests; any real disposable-account integration test is separately authorized.

Verification approach

Add focused coverage for authentication/configuration, project reuse and creation, default URL derivation, upload failure handling, and preservation of existing store/ID/deletion behavior. Exercise commands with isolated temporary homes and content stores. Test dependency-free execution at the packaged binary boundary, not only through a developer's Node installation. Do not use the maintainer's real credentials or deployed project for routine tests.

Out of scope

Cross-machine state or file recovery; pull commands; remote backup infrastructure; framework builds; SSR or backend hosting; page authentication; custom-domain/DNS management in v1; review-tool functionality; implementation of the shared release system inside the Pages repository.