@vibes.diy/api-queue 0.0.0-smoke-70d942c5-1774564519

package/LICENSE.md

@@ -0,0 +1,232 @@
+The contents of this repository are Copyright (c) corresponding authors and
+contributors, licensed under the `Permissive License Stack` meaning either of:
+
+- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
+  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
+
+- MIT Software License: https://opensource.org/licenses/MIT
+  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
+
+You may not use the contents of this repository except in compliance
+with one of the listed Licenses. For an extended clarification of the
+intent behind the choice of Licensing please refer to
+https://protocol.ai/blog/announcing-the-permissive-license-stack/
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the terms listed in this notice is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See each License for the specific language
+governing permissions and limitations under that License.
+
+<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+
+`SPDX-License-Identifier: Apache-2.0 OR MIT`
+
+Verbatim copies of both licenses are included below:
+
+<details><summary>Apache-2.0 Software License</summary>
+
+```
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+```
+
+</details>
+
+<details><summary>MIT Software License</summary>
+
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
+
+</details>

package/README.md

@@ -0,0 +1,539 @@
+# vibes.diy API
+
+WebSocket-based API for vibes.diy chat persistence and app deployment. Supports both HTTP POST and WebSocket connections using the same handler via the Evento event-driven framework.
+
+## Package Structure
+
+```
+api/
+├── types/              @vibes.diy/api-types    SHARED (client + server)
+│   ├── msg-types.ts    Request/response types, VibeFile, MsgBase envelope, arktype schemas
+│   ├── types.ts        FileSystemItem with transform support
+│   └── vibes-diy-serv-ctx.ts  Server context for wrapper/iframe rendering
+│
+├── pkg/                @vibes.diy/api-pkg      SHARED (client + server)
+│   ├── api.ts          VibesDiyApiIface interface (3 methods)
+│   ├── encoder.ts      Evento encoders: ReqRes, W3CWebSocket, Combined
+│   ├── index.ts        Re-exports
+│   └── react/          React components (client only in practice)
+│
+├── impl/               @vibes.diy/api-impl     CLIENT
+│   └── index.ts        VibeDiyApi class (WebSocket client, WIP - no reconnection)
+│
+├── svc/                @vibes.diy/api-svc      SERVER (Cloudflare Workers)
+│   ├── cf-serve.ts     Cloudflare Worker entry point (HTTP + WebSocket)
+│   ├── create-handler.ts   Evento pipeline setup with all handlers
+│   ├── check-auth.ts   Auth middleware (clerk, device-id verification)
+│   ├── unwrap-msg-base.ts  MsgBase envelope unwrapping for validation
+│   ├── api.ts          VibesApiSQLCtx type + VibesFPApiParameters
+│   ├── entry-point-utils.ts  URL construction for deployed apps
+│   │
+│   ├── public/         Public API handlers (Evento handlers)
+│   │   ├── ensure-app-slug-item.ts  App deployment with CID-based storage
+│   │   ├── ensure-chat-context.ts   Chat session creation/retrieval
+│   │   ├── append-chat-section.ts   Message persistence with seq numbers
+│   │   └── serv-entry-point.ts      Serves deployed app HTML
+│   │
+│   ├── intern/         Internal helpers
+│   │   ├── ensure-slug-binding.ts   User/app slug management (random-words)
+│   │   ├── ensure-storage.ts        CID calculation (SHA-256 + base58btc)
+│   │   ├── import-map.ts            ESM import map generation (esm.sh)
+│   │   ├── render-vibes.tsx         HTML rendering with import map injection
+│   │   └── write-apps.ts            App record creation with transforms (sucrase, acorn)
+│   │
+│   └── sql/
+│       └── vibes-diy-api-schema.ts  Drizzle schema (D1)
+│
+└── tests/              @vibes.diy/api-test
+    └── api.test.ts
+```
+
+## Package Summary
+
+| Package                | Runs On | Purpose                                 |
+| ---------------------- | ------- | --------------------------------------- |
+| `@vibes.diy/api-types` | Both    | arktype schemas, request/response types |
+| `@vibes.diy/api-pkg`   | Both    | Interface + encoders (shared contract)  |
+| `@vibes.diy/api-impl`  | Client  | `VibeDiyApi` WebSocket client class     |
+| `@vibes.diy/api-svc`   | Server  | Cloudflare Worker handlers, D1/Drizzle  |
+
+## Architecture
+
+### Message Envelope
+
+All requests are wrapped in a `MsgBase` envelope:
+
+```typescript
+interface MsgBase {
+  tid: string; // Transaction ID for request/response correlation
+  src: string; // Source identifier
+  dst: string; // Destination identifier
+  ttl: number; // Time-to-live
+  payload: unknown; // The actual request/response
+}
+```
+
+### Evento Pipeline
+
+The server uses Evento (from `@adviser/cement`) for request routing. Handlers are registered in order:
+
+1. **CORS preflight** - Handles OPTIONS requests
+2. **servEntryPoint** - Serves deployed app HTML (hostname routing: `{appSlug}--{userSlug}.{host}/~{fsId}~/`)
+3. **Request logging** - Logs incoming POST/PUT requests, rejects other methods with 503
+4. **ensureAppSlugItem** - App deployment handler
+5. **ensureChatContext** - Chat session handler
+6. **appendChatSection** - Message persistence handler
+7. **Not-found handler** - Returns 501 for unmatched requests (semantically "Not Implemented")
+8. **Error handler** - Catches and formats errors as 500
+
+Each handler has `validate` (arktype schema check) and `handle` (business logic) phases. Some handlers also have a `post` phase for cleanup/logging.
+
+## Data Flow
+
+```
+Client (browser)                      Server (CF Worker)
+─────────────────                     ──────────────────
+VibeDiyApi.ensureAppSlug()        →   cf-serve.ts
+        ↓                                   ↓
+   WebSocket.send(MsgBox<Req>)    →   WebSocketPair upgrade
+                                            ↓
+                                      CombinedEventoEnDecoder.encode()
+                                            ↓
+                                      Evento.trigger() with handlers
+                                            ↓
+                                      unwrapMsgBase() → extract payload
+                                            ↓
+                                      checkAuth() → verify token
+                                            ↓
+                                      handler.handle() → business logic
+                                            ↓
+                                      D1 queries (Drizzle ORM)
+                                            ↓
+   MsgBox<Res>                    ←   SendResponseProvider.send()
+```
+
+## API Methods
+
+### `ensureAppSlug()`
+
+Deploy an app with a filesystem. Process:
+
+1. Verify auth token (clerk/device-id)
+2. Create or retrieve user slug binding
+3. Create or retrieve app slug binding
+4. Calculate CIDs for all file contents
+5. Store assets in D1 `Assets` table
+6. Apply transforms (jsx-to-js, import map generation)
+7. Create `Apps` record with filesystem manifest
+8. Return `entryPointUrl` for iframe loading
+
+### `ensureChatContext()`
+
+Create or retrieve a chat session:
+
+1. If `contextId` provided, verify it exists and belongs to user
+2. Otherwise, generate new contextId (12-char ID)
+3. Insert into `ChatContexts` table
+4. Return `contextId`
+
+### `appendChatSection()`
+
+Add messages to a chat context:
+
+1. Verify context exists and belongs to user
+2. Get max `seq` for context, increment
+3. Insert into `ChatSections` with `origin` ('user' or 'llm')
+4. Blocks use `BlockMsgs | PromptMsg` types from `@vibes.diy/call-ai-v2`
+5. Return `seq` number
+
+## CI/CD
+
+The API is bundled into the main vibes.diy Cloudflare Worker (not a separate deployment).
+
+### Workflow
+
+`.github/workflows/vibes-diy-deploy.yaml`
+
+**Triggers:**
+
+- Push to `vibes.diy/**/*` paths
+- Tags: `vibes-diy@*`
+- Manual dispatch
+
+### Environments
+
+| Trigger                 | Environment | Domain                   |
+| ----------------------- | ----------- | ------------------------ |
+| Tag `vibes-diy@s*`      | staging     | `*.dev-v2.vibesdiy.net`  |
+| Tag `vibes-diy@p*`      | production  | `*.prod-v2.vibesdiy.net` |
+| Path push or other tags | dev         | `*.dev-v2.vibesdiy.net`  |
+
+### Deploy Steps
+
+Deployment is handled by the GitHub Action (`vibes.diy/actions/deploy`). The action runs:
+
+```bash
+pnpm run build              # Build React app + bundle worker
+pnpm run drizzle:d1-remote  # Run D1 migrations
+core-cli writeEnv | wrangler secret bulk  # Push secrets
+pnpm run deploy:${ENV}      # wrangler deploy
+```
+
+Do not run these manually - push a tag or merge to trigger the workflow.
+
+### Infrastructure
+
+| Resource      | Binding  | Purpose                       |
+| ------------- | -------- | ----------------------------- |
+| D1 Database   | `DB`     | Chat contexts, sections, apps |
+| Static Assets | `ASSETS` | React app build               |
+
+### Server Context (VibesApiSQLCtx)
+
+All handlers receive a shared context via `ctx.ctx.getOrThrow<VibesApiSQLCtx>("vibesApiCtx")`:
+
+```typescript
+interface VibesApiSQLCtx {
+  sthis: SuperThis; // Fireproof utilities (logger, nextId, env)
+  db: VibesSqlite; // Drizzle DB instance
+  tokenApi: Record<string, FPApiToken>; // Auth verifiers by type
+  deviceCA: DeviceIdCAIf; // Device ID certificate authority
+  logger: Logger; // Structured logger
+  params: VibesFPApiParameters; // Service configuration
+  cache: CfCacheIf; // Cloudflare cache API
+  fetchPkgVersion(pkg): Promise<string | undefined>; // npm registry lookup
+  waitUntil<T>(promise): void; // CF worker lifecycle
+  ensureStorage(...items): Promise<Result<StorageResult[]>>; // Asset storage
+}
+```
+
+### D1 Schema
+
+Defined in `svc/sql/vibes-diy-api-schema.ts` using Drizzle ORM.
+
+**Assets** - Binary content storage (could move to R2)
+| Column | Type | Description |
+|--------|------|-------------|
+| `assetId` | text PK | CID of content |
+| `content` | blob | Actual content |
+| `created` | text | ISO timestamp |
+
+**UserSlugBindings** - Maps users to their human-friendly slugs
+| Column | Type | Description |
+|--------|------|-------------|
+| `userId` | text | User identifier |
+| `userSlug` | text | Human-friendly user slug (unique) |
+| `created` | text | ISO timestamp |
+
+Primary key: `(userSlug, userId)`. Unique index on `userSlug`.
+
+**AppSlugBindings** - Maps apps to slugs within a user's namespace
+| Column | Type | Description |
+|--------|------|-------------|
+| `userSlug` | text FK | References UserSlugBindings.userSlug |
+| `appSlug` | text | Human-friendly app slug |
+| `created` | text | ISO timestamp |
+
+Primary key: `(appSlug, userSlug)`.
+
+**Apps** - Deployed app versions with filesystem and environment
+| Column | Type | Description |
+|--------|------|-------------|
+| `appSlug` | text | App identifier |
+| `userId` | text | Owner |
+| `userSlug` | text | Owner's slug |
+| `releaseSeq` | int | Incremented on each deployment |
+| `fsId` | text | CID of filesystem manifest |
+| `env` | json | Environment variables (VibesEnv) |
+| `fileSystem` | json | Array of FileSystemItem with transforms |
+| `mode` | text | 'production' or 'dev' |
+| `created` | text | ISO timestamp |
+
+Primary key: `(appSlug, userId, releaseSeq)`. Indexes on `fsId` and `created`.
+
+**ChatContexts** - Chat session containers
+| Column | Type | Description |
+|--------|------|-------------|
+| `contextId` | text PK | UUID v4 |
+| `userId` | text | Owner |
+| `created` | text | ISO timestamp |
+
+**ChatSections** - Individual messages/blocks within a chat
+| Column | Type | Description |
+|--------|------|-------------|
+| `contextId` | text FK | References ChatContexts.contextId |
+| `seq` | int | Section sequence number (0-indexed, auto-incremented) |
+| `origin` | text | 'user' or 'llm' |
+| `blocks` | json | Array of BlockMsgs or PromptMsg from call-ai-v2 |
+| `created` | text | ISO timestamp |
+
+Primary key: `(seq, contextId)`.
+
+### Environment Variables
+
+**Required:**
+| Variable | Purpose |
+|----------|---------|
+| `CLOUD_SESSION_TOKEN_PUBLIC` | Public key for cloud session tokens |
+| `CLERK_PUBLISHABLE_KEY` | Clerk auth verification |
+| `DEVICE_ID_CA_PRIV_KEY` | Device ID certificate authority private key |
+| `DEVICE_ID_CA_CERT` | Device ID certificate authority cert |
+| `FP_VERSION` | Fireproof version for import maps |
+| `VIBES_SVC_HOSTNAME_BASE` | Base hostname for deployed apps (e.g., `vibes.app`) |
+
+**Optional (with defaults):**
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `VIBES_SVC_PROTOCOL` | `https` | Protocol for deployed apps |
+| `MAX_APP_SLUG_PER_USER_ID` | `10` | Max app slugs per user |
+| `MAX_USER_SLUG_PER_USER_ID` | `10` | Max user slugs per user |
+| `MAX_APPS_PER_USER_ID` | `50` | Max app deployments per user |
+
+## Message Types
+
+### VibeFile (for deployment)
+
+Six variants for different content types:
+
+| Type                | Content                              | Use Case                       |
+| ------------------- | ------------------------------------ | ------------------------------ |
+| `code-block`        | Inline string, `lang: 'jsx' \| 'js'` | JSX/JS source code             |
+| `code-ref`          | `refId` reference                    | Code stored elsewhere          |
+| `str-asset-block`   | Inline string                        | CSS, JSON, text files          |
+| `str-asset-ref`     | `refId` reference                    | String assets stored elsewhere |
+| `uint8-asset-block` | `Uint8Array`                         | Images, fonts, binaries        |
+| `uint8-asset-ref`   | `refId` reference                    | Binary assets stored elsewhere |
+
+All file types share base properties:
+
+```typescript
+{
+  filename: string;    // Must start with /, no //, /../, /./
+  entryPoint?: boolean; // Last one wins, marks app entry
+  mimetype?: string;   // Derived from filename if not set
+}
+```
+
+### FileSystemItem (stored result)
+
+After processing, files become `FileSystemItem`:
+
+```typescript
+{
+  fileName: string;
+  mimeType: string;
+  assetId: string;     // CID of content
+  assetURI: string;    // sql://Assets.assetId, s3://..., r2://...
+  entryPoint?: boolean;
+  size: number;
+  transform?: {
+    type: 'jsx-to-js' | 'imports' | 'import-map' | 'transformed';
+    // ... transform-specific fields
+  }
+}
+```
+
+### Auth Types
+
+```typescript
+type DashAuthType = {
+  type: "clerk" | "device-id";
+  token: string;
+};
+```
+
+Auth is verified via `tokenApi` which supports:
+
+- **clerk** - Clerk JWT verification using `CLERK_PUB_JWT_KEY` / `CLERK_PUB_JWT_URL` env vars
+- **device-id** - Device certificate verification using `DEVICE_ID_CA_*` keys
+
+## Client Usage
+
+> [!WARNING]
+> The client (`@vibes.diy/api-impl`) is currently a work-in-progress. While it can send requests over WebSocket, the response correlation logic (matching server responses to requests via `tid`) is not yet fully implemented. It is currently primarily used for testing with direct handler calls.
+
+The client is currently used in tests. The main vibes.diy app doesn't use it yet - integration is in progress.
+
+### Creating a Client
+
+```typescript
+import { VibeDiyApi } from "@vibes.diy/api-impl";
+import { Result } from "@adviser/cement";
+
+const api = new VibeDiyApi({
+  apiUrl: "wss://api.vibes.diy/v1/ws", // Default if omitted
+  getToken: async () => {
+    // Return auth token (Clerk or device-id)
+    return Result.Ok({ type: "clerk", token: clerkToken });
+  },
+  timeoutMs: 10000, // Default: 10s request timeout
+});
+```
+
+The client uses `KeyedResolvOnce` for connection pooling - multiple `VibeDiyApi` instances with the same `apiUrl` share a WebSocket connection. (See `impl/index.ts` for custom message routing options via the `msg` config.)
+
+### Deploying an App
+
+```typescript
+const res = await api.ensureAppSlug({
+  mode: "dev", // 'dev' or 'production'
+  appSlug: "my-app", // optional, server generates 3-word slug
+  userSlug: "my-user", // optional, server generates 3-word slug
+  env: { API_KEY: "..." }, // optional, passed to app runtime
+  fileSystem: [
+    {
+      type: "code-block",
+      lang: "jsx",
+      filename: "/App.jsx", // Must start with /, becomes entry point
+      entryPoint: true,
+      content: "export default function App() { return <div>Hello</div>; }",
+    },
+  ],
+});
+
+if (res.isOk()) {
+  const { entryPointUrl, fsId, userSlug, appSlug, fileSystem } = res.Ok();
+  // entryPointUrl -> https://{appSlug}--{userSlug}.{hostnameBase}/~{fsId}~/
+  // e.g. https://my-app--my-user.vibes.app/~zABC123~/
+  // fsId -> CID of filesystem manifest
+  // fileSystem -> Array<FileSystemItem> with assetIds and transforms
+}
+```
+
+**Response includes:**
+
+- `entryPointUrl` - URL to load in iframe (constructed from `VIBES_SVC_*` config)
+- `wrapperUrl` - URL for wrapper page with auth handoff
+- `fsId` - CID of the filesystem manifest
+- `fileSystem` - Processed `FileSystemItem[]` with CIDs and transforms applied
+
+### Chat Context Management
+
+```typescript
+// Create a new chat context (server generates contextId)
+const ctx = await api.ensureChatContext({});
+
+// Or retrieve/create with a specific contextId
+const ctx = await api.ensureChatContext({ contextId: "my-context-id" });
+
+if (ctx.isOk()) {
+  const { contextId } = ctx.Ok();
+
+  // Append a user message
+  const userRes = await api.appendChatSection({
+    contextId,
+    origin: "user", // 'user' | 'llm'
+    blocks: [
+      // BlockMsgs or PromptMsg from @vibes.diy/call-ai-v2
+      {
+        type: "prompt.txt",
+        streamId: "stream-1",
+        request: { model: "gpt-4", messages: [{ role: "user", content: "Hello" }] },
+        timestamp: new Date(),
+      },
+    ],
+  });
+  // userRes.Ok().seq -> 0 (first section)
+
+  // Append LLM response
+  const llmRes = await api.appendChatSection({
+    contextId,
+    origin: "llm",
+    blocks: sectionBlocks, // BlockMsgs from call-ai sections stream
+  });
+  // llmRes.Ok().seq -> 1 (second section)
+}
+```
+
+**Note:** Context ownership is enforced - you can only append to contexts created by your userId.
+
+### Testing
+
+Tests use a local handler directly rather than WebSocket. See `api/tests/api.test.ts` for the full setup including:
+
+- Creating a local D1/libsql database
+- Setting up test device-id auth
+- Calling the handler directly
+
+Note: The test passes an ad-hoc `fetch` property via TypeScript structural typing, but this isn't part of the official `VibeDiyApiParam` interface. A proper `fetch` override may be added in the future.
+
+## Running Tests
+
+```bash
+cd vibes.diy/api/tests
+pnpm test
+```
+
+## Implementation Details
+
+### URL Structure
+
+Deployed apps are served via hostname-based routing:
+
+```
+https://{appSlug}--{userSlug}.{hostnameBase}/~{fsId}~/
+       └────────────────────┘ └──────────┘  └──────┘
+              hostname          base domain   version path
+```
+
+Example: `https://my-app--fuzzy-purple-elephant.vibes.app/~z4PhNX7vuL~/`
+
+The `extractHostToBindings()` function parses:
+
+- Hostname pattern: `{appSlug}--{userSlug}.{rest}`
+- Path pattern: `/~{fsId}~/` (fsId starts with `z`, 8+ chars)
+- If no fsId in path, serves latest production release
+
+### Slug Generation
+
+When `appSlug` or `userSlug` are not provided, the server generates 3-word slugs using the `random-words` package:
+
+```typescript
+generate({ exactly: 1, wordsPerString: 3, separator: "-" });
+// → "fuzzy-purple-elephant"
+```
+
+Up to 5 attempts are made to find a unique slug before failing.
+
+### Transform Pipeline
+
+The `write-apps.ts` module applies transforms to uploaded files:
+
+1. **JSX → JS** (`sucrase` with automatic JSX runtime)
+   - Input: `code-block` with `lang: "jsx"`
+   - Output: `/~~transformed~~/{cid}` with `transform: { type: "transformed", action: "jsx-to-js" }`
+
+2. **Import Extraction** (`acorn` parser)
+   - Parses all JS files for `import`/`export` statements
+   - Extracts bare specifiers (e.g., `react`, `@fireproof/core`)
+
+3. **Import Map Generation**
+   - Unknown packages → npm registry lookup for version → `esm.sh` URL
+   - Predefined mappings for React 19.2.1, Fireproof, Clerk, etc.
+   - Output: `/~~calculated~~/import-map.json` with `transform: { type: "import-map" }`
+
+### fsId Calculation
+
+The `fsId` is a deterministic CID computed from:
+
+```typescript
+hash(sortedFilenames + mimetypes + contentCIDs + sortedEnvJSON);
+```
+
+Same files + same env = same fsId (enables deduplication).
+
+### Asset Caching
+
+`serv-entry-point.ts` uses two-tier Cloudflare caching:
+
+1. **Global cache** by CID: `assetCacheUrl/{assetId}`
+2. **Path cache** by request URL
+
+On cache miss: D1 query → populate both caches via `waitUntil()`.
+
+### App Eviction
+
+When a user exceeds `MAX_APPS_PER_USER_ID`:
+
+- Oldest `dev` mode apps are evicted first (10% of total + 1)
+- `production` apps are preserved

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vibes.diy/api-queue",
+  "version": "0.0.0-smoke-70d942c5-1774564519",
+  "type": "module",
+  "scripts": {
+    "build": "core-cli tsc && wrangler build",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "deploy:dev": "wrangler deploy --env dev",
+    "deploy:prod": "wrangler deploy --env prod"
+  },
+  "dependencies": {
+    "@adviser/cement": "~0.5.34",
+    "@cloudflare/puppeteer": "~1.0.6",
+    "@fireproof/core-runtime": "~0.24.13",
+    "@vibes.diy/api-svc": "0.0.0-smoke-70d942c5-1774564519",
+    "@vibes.diy/api-types": "0.0.0-smoke-70d942c5-1774564519",
+    "arktype": "~2.2.0",
+    "drizzle-orm": "~0.45.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VibesDIY/vibes.diy.git"
+  }
+}

package/screen-shotter.d.ts

@@ -0,0 +1,3 @@
+import { CFEnv, EvtNewFsId } from "@vibes.diy/api-types";
+export declare function takeScreenshot(event: EvtNewFsId, env: CFEnv): Promise<Uint8Array>;
+export declare function processScreenShotEvent(message: unknown, env: CFEnv): Promise<void>;

package/screen-shotter.js

@@ -0,0 +1,70 @@
+import puppeteer from "@cloudflare/puppeteer";
+import { isEvtNewFsId, isMsgBase, msgBase } from "@vibes.diy/api-types";
+import { R2ToS3Api, storeScreenshot } from "@vibes.diy/api-svc";
+import { cfDrizzle } from "@vibes.diy/api-svc/cf-serve.js";
+import { createVibesApiTables } from "@vibes.diy/api-svc/sql/tables.js";
+import { type } from "arktype";
+import { ensureSuperThis } from "@fireproof/core-runtime";
+import { LoggerImpl } from "@adviser/cement";
+export async function takeScreenshot(event, env) {
+    console.log(`Taking screenshot for ${event.vibeUrl} (fsId: ${event.fsId})`);
+    const browser = await puppeteer.launch(env.BROWSER);
+    try {
+        const page = await browser.newPage();
+        await page.setViewport({
+            width: 1280,
+            height: 720,
+            deviceScaleFactor: 1,
+        });
+        await page.goto(event.vibeUrl, {
+            waitUntil: "networkidle0",
+            timeout: 30000,
+        });
+        const screenshot = await page.screenshot({
+            type: "jpeg",
+            quality: 85,
+            fullPage: false,
+        });
+        return screenshot;
+    }
+    finally {
+        await browser.close();
+    }
+}
+export async function processScreenShotEvent(message, env) {
+    if (!isMsgBase(message)) {
+        const x = msgBase(message);
+        if (x instanceof type.errors) {
+            console.error("Received message that is not MsgBase but matches MsgBase structure:", x.summary, message);
+        }
+        else {
+            console.error("Received message that is not MsgBase:", message);
+        }
+        return;
+    }
+    const payload = message.payload;
+    if (isEvtNewFsId(payload)) {
+        console.log("Processing ScreenShotEvent:", {
+            shotUrl: payload.vibeUrl,
+            fsId: payload.fsId,
+        });
+        const screenshot = await takeScreenshot(payload, env);
+        const screenshotData = new Uint8Array(screenshot);
+        console.log(`Screenshot taken for ${payload.fsId}: ${screenshotData.byteLength} bytes`);
+        const { db } = await cfDrizzle(env);
+        const sthis = ensureSuperThis({ logger: new LoggerImpl() });
+        const tables = createVibesApiTables(env.DB_FLAVOUR ?? "sqlite");
+        const result = await storeScreenshot({
+            sql: { dbFlavour: env.DB_FLAVOUR ?? "sqlite", db, tables },
+            s3Api: new R2ToS3Api(env.FS_IDS_BUCKET, sthis),
+        }, payload.fsId, screenshotData);
+        if (result.isErr()) {
+            console.error(`Failed to store screenshot: ${result.Err()}`);
+            return;
+        }
+        console.log(`Screenshot stored with assetId: ${result.Ok().assetUrl}`);
+        return;
+    }
+    console.error("Received message with unrecognized payload:", payload);
+}
+//# sourceMappingURL=screen-shotter.js.map

package/screen-shotter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen-shotter.js","sourceRoot":"","sources":["../jsr/screen-shotter.ts"],"names":[],"mappings":"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"}

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": [
+    "/Users/menabe/Software/fproof/vibes.diy-main/tsconfig.dist.json"
+  ],
+  "compilerOptions": {
+    "outDir": "../npm/",
+    "sourceMap": true,
+    "noEmit": false
+  },
+  "include": [
+    "**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    ".git",
+    ".vscode"
+  ]
+}

package/worker.d.ts

@@ -0,0 +1,6 @@
+import { MessageBatch } from "@cloudflare/workers-types";
+import { CFEnv } from "@vibes.diy/api-types";
+declare const _default: {
+    queue(batch: MessageBatch, env: CFEnv): Promise<void>;
+};
+export default _default;

package/worker.js

@@ -0,0 +1,22 @@
+import { processScreenShotEvent } from "./screen-shotter.js";
+export default {
+    async queue(batch, env) {
+        for (const message of batch.messages) {
+            try {
+                console.log("Queue message received:", message.id, typeof message.body);
+                let body = message.body;
+                if (typeof message.body === "string") {
+                    body = JSON.parse(message.body);
+                    console.log("Message body:", body);
+                }
+                await processScreenShotEvent(body, env);
+                message.ack();
+            }
+            catch (error) {
+                console.error("Failed to process queue message:", error);
+                message.retry();
+            }
+        }
+    },
+};
+//# sourceMappingURL=worker.js.map

package/worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.js","sourceRoot":"","sources":["../jsr/worker.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,eAAe;IACb,KAAK,CAAC,KAAK,CAAC,KAAmB,EAAE,GAAU;QACzC,KAAK,MAAM,OAAO,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;YACrC,IAAI,CAAC;gBACH,OAAO,CAAC,GAAG,CAAC,yBAAyB,EAAE,OAAO,CAAC,EAAE,EAAE,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;gBACxE,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;gBACxB,IAAI,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACrC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAc,CAAC,CAAC;oBAC1C,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,CAAC,CAAC;gBACrC,CAAC;gBACD,MAAM,sBAAsB,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBACxC,OAAO,CAAC,GAAG,EAAE,CAAC;YAChB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,KAAK,CAAC,CAAC;gBACzD,OAAO,CAAC,KAAK,EAAE,CAAC;YAClB,CAAC;QACH,CAAC;IACH,CAAC;CAC+B,CAAC"}

package/wrangler.toml

@@ -0,0 +1,61 @@
+name = "vibes-diy-v2-queue-consumer"
+main = "./worker.ts"
+compatibility_date = "2025-02-24"
+compatibility_flags = ["nodejs_compat"]
+
+[browser]
+binding = "BROWSER"
+
+[[d1_databases]]
+binding = "DB"
+database_name = "dev-vibes-diy-v2"
+database_id = "105530de-9900-435b-92f4-15347af604f6"
+
+[[r2_buckets]]
+binding = "FS_IDS_BUCKET"
+bucket_name = "vibes-diy-fs-ids"
+
+[[queues.consumers]]
+queue = "vibes-service"
+max_batch_size = 10
+max_batch_timeout = 30
+
+[env.dev]
+name = "vibes-diy-v2-queue-consumer-dev"
+
+[env.dev.browser]
+binding = "BROWSER"
+
+[[env.dev.d1_databases]]
+binding = "DB"
+database_name = "dev-vibes-diy-v2"
+database_id = "105530de-9900-435b-92f4-15347af604f6"
+
+[[env.dev.r2_buckets]]
+binding = "FS_IDS_BUCKET"
+bucket_name = "vibes-diy-fs-ids"
+
+[[env.dev.queues.consumers]]
+queue = "vibes-service-dev"
+max_batch_size = 10
+max_batch_timeout = 30
+
+[env.prod]
+name = "vibes-diy-v2-queue-consumer-prod"
+
+[env.prod.browser]
+binding = "BROWSER"
+
+[[env.prod.d1_databases]]
+binding = "DB"
+database_name = "prod-vibes-diy-v2"
+database_id = "0f783eae-91cf-49c4-a706-6e4d2498cb4a"
+
+[[env.prod.r2_buckets]]
+binding = "FS_IDS_BUCKET"
+bucket_name = "vibes-diy-fs-ids"
+
+[[env.prod.queues.consumers]]
+queue = "vibes-service-prod"
+max_batch_size = 10
+max_batch_timeout = 30