happy2 0.0.5

package/README.md

@@ -0,0 +1,82 @@
+# Happy (2)
+
+Happy (2) is a desktop work and coding app that evolves by adopting itself. This
+pnpm monorepo delivers its shared Solid UI through a web app and an Electron
+desktop app. Happy (2) is desktop-only; its UI must not assume mobile use or adapt
+for mobile viewports.
+
+## Packages
+
+- `happy2-app` contains the shared Solid component and its tests.
+- `happy2-web` imports `happy2-app` and creates a browser build.
+- `happy2-desktop` imports `happy2-app` in an Electron renderer and builds its
+  Electron main process with Vite.
+- `happy2-server` is the Fastify server and authentication-service package.
+- The root `happy2` package bundles the server and built web app into the complete
+  distributable.
+- `happy2-gym` is the isolated end-to-end testing environment. Its server harness runs
+  black-box HTTP tests against disposable in-memory server instances; see
+  [`packages/happy2-gym/README.md`](packages/happy2-gym/README.md) for usage.
+
+## Requirements
+
+- Node.js 24 or later (required by Portless)
+- pnpm 10.28 or later
+
+TypeScript is on the v7 release line throughout the workspace.
+
+## Commands
+
+```sh
+pnpm install
+pnpm dev                # Server + web app on stable Portless URLs
+pnpm dev:desktop        # Electron app connected to the server from pnpm dev
+pnpm --dir packages/happy2-gym test # Server end-to-end tests
+pnpm check              # Type-check, test, and build every package
+```
+
+`pnpm build` emits browser files to `packages/happy2-web/dist` and an Electron renderer
+plus main process to `packages/happy2-desktop/dist`. Start the latter after building
+with `pnpm --filter happy2-desktop start`.
+
+`pnpm dev` runs the server and web app through Portless with interleaved logs.
+The main checkout uses `https://happy2.localhost` and
+`https://happy2-api.localhost`; linked worktrees automatically receive unique
+branch-prefixed hostnames. The generated development TOML, database, files,
+keys, and password pepper stay under `.context/dev` in each workspace.
+
+With `pnpm dev` running, start `pnpm dev:desktop` in another terminal. It resolves
+the same workspace-specific `happy2-api` URL and passes it to the Electron
+renderer. Portless assigns the renderer an available workspace-specific port;
+set `PORT=xxxx` only when you need to choose it explicitly.
+
+Start only a local server with `pnpm dev:server`. Without a TOML file it enables
+self-service password registration and login, creates its SQLite database under
+`packages/happy2-server`, and generates durable local JWT keys plus password pepper in
+`packages/happy2-server/.env` on first start. Pass `--config path/to/happy2.toml` (or
+set `HAPPY2_CONFIG`) to override the defaults; copy the example TOML before
+production deployment. See the server package README for deployment and auth
+configuration.
+
+## Publishing
+
+Authenticate with npm once using `pnpm login`, then publish the all-in-one `happy2`
+from a clean, up-to-date `main` branch:
+
+```sh
+pnpm release 0.1.0
+```
+
+The release command also accepts semantic version bumps such as `patch`,
+`minor`, and `major`. It checks the branch, working tree, and npm
+authentication; runs the full workspace check; creates the release commit and
+tag; previews the package; pushes to `main`; and publishes it publicly. If
+publishing is interrupted after the tag is created, rerun the command with the
+exact version to resume safely.
+
+## Working convention
+
+“Sync to main” means to commit the current work, rebase it onto the latest
+`origin/main`, and push the resulting `HEAD` to `main` without force. If `main`
+advances or the push is rejected, fetch and rebase again before retrying. Never
+force-push `main`.

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "happy2",
+  "version": "0.0.5",
+  "description": "Happy (2) desktop web app and server bundle",
+  "bin": {
+    "happy2": "packages/happy2-server/bin/happy2.js"
+  },
+  "files": [
+    "packages/happy2-server/bin/happy2.js",
+    "packages/happy2-server/dist",
+    "packages/happy2-server/drizzle",
+    "packages/happy2-server/happy2.example.toml",
+    "packages/happy2-server/README.md",
+    "packages/happy2-server/Dockerfile"
+  ],
+  "type": "module",
+  "main": "./packages/happy2-server/dist/index.js",
+  "types": "./packages/happy2-server/dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./packages/happy2-server/dist/index.d.ts",
+      "default": "./packages/happy2-server/dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.0.0",
+    "pnpm": ">=10.28.1"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.3.0",
+    "@fastify/http-proxy": "^11.5.0",
+    "@fastify/multipart": "^10.1.0",
+    "@fastify/static": "^10.1.0",
+    "@libsql/client": "^0.17.4",
+    "@paralleldrive/cuid2": "^3.3.0",
+    "@slopus/rig": "^0.0.17",
+    "drizzle-orm": "^0.45.2",
+    "fastify": "^5.8.2",
+    "jose": "^6.1.3",
+    "nodemailer": "^7.0.13",
+    "sharp": "^0.35.3",
+    "smol-toml": "^1.4.2",
+    "thumbhash": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "concurrently": "^10.0.3",
+    "oxfmt": "^0.57.0",
+    "oxlint": "^1.73.0",
+    "portless": "^0.15.1",
+    "tsx": "^4.21.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "dev": "node scripts/dev.mjs",
+    "dev:web": "pnpm --filter happy2-web dev",
+    "dev:desktop": "node scripts/dev-desktop.mjs",
+    "dev:server": "pnpm --dir packages/happy2-server dev",
+    "start": "node packages/happy2-server/dist/runner.js",
+    "build": "pnpm -r --if-present build && VITE_HAPPY2_SERVER_URL='/' pnpm --filter happy2-web exec vite build --outDir ../happy2-server/dist/web --emptyOutDir false",
+    "test": "pnpm -r --if-present test",
+    "test:watch": "pnpm -r --parallel --if-present test:watch",
+    "typecheck": "tsc --project tsconfig.json && pnpm -r --if-present typecheck",
+    "format": "oxfmt --write scripts tsconfig.json && pnpm -r --if-present format",
+    "format:check": "oxfmt --check scripts tsconfig.json && pnpm -r --if-present format:check",
+    "lint": "oxlint scripts && pnpm -r --if-present lint",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test && pnpm build",
+    "release": "tsx scripts/release.ts",
+    "clean": "pnpm -r --if-present clean"
+  }
+}

package/packages/happy2-server/Dockerfile

@@ -0,0 +1,18 @@
+# Build from the repository root:
+# docker build -f packages/happy2-server/Dockerfile -t slopus/happy2 .
+FROM node:22-bookworm-slim AS build
+WORKDIR /workspace
+RUN corepack enable
+COPY package.json pnpm-lock.yaml pnpm-workspace.yaml ./
+COPY packages/happy2-server/package.json packages/happy2-server/package.json
+RUN pnpm install --frozen-lockfile
+COPY packages/happy2-server packages/happy2-server
+RUN pnpm --filter happy2-server build:server \
+  && pnpm --filter happy2-server --prod deploy /app
+
+FROM node:22-bookworm-slim
+ENV NODE_ENV=production
+WORKDIR /app
+COPY --from=build /app ./
+EXPOSE 3000
+ENTRYPOINT ["node", "dist/cli.js"]

package/packages/happy2-server/README.md

@@ -0,0 +1,418 @@
+# `happy2-server`
+
+`happy2-server` is the Fastify backend for deployments that run one service
+(`server.role = "all"`), a dedicated authentication service (`"auth"`), or an
+API-side token validator (`"api"`). All useful backend endpoints are versioned
+under `/v0`; the backend's `/` remains only a small service-status response.
+
+## Run
+
+```sh
+# Published backend package
+npx happy2-server --config ./happy2.toml
+
+# Published all-in-one web app and API on http://127.0.0.1:3000
+npx happy2
+
+# Development, with reload and no configuration file:
+pnpm dev:server
+
+# Locally built backend:
+cp packages/happy2-server/happy2.example.toml happy2.toml
+pnpm --filter happy2-server build
+pnpm --filter happy2-server start -- --config ../../happy2.toml
+
+# Locally built complete package:
+pnpm build
+pnpm start -- --config ./happy2.toml
+```
+
+The all-in-one `happy2` executable starts the API on an ephemeral loopback port, serves the
+packaged SPA on the configured public port, and streams `/v0` requests through
+an internal reverse proxy. The web app therefore uses one origin for normal
+HTTP, uploads, and server-sent events. The configured `trusted_proxy_hops`
+continues to describe only proxies outside Happy (2); the private loopback hop is
+handled internally.
+
+Without a TOML file, the package starts an `all`-role app on `127.0.0.1:3000`
+with SQLite, self-service password registration, and generated JWT/pepper
+material. Database, files, generated secrets, agent workspaces, and Rig runtime
+state live under `.happy2` in the invoking directory. Add `.happy2` to the
+project's ignore rules and preserve it as private application state. The
+package starts its bundled `@slopus/rig` executable with a private Rig home under
+`.happy2/rig` by default, containing configuration, runtime settings, session
+state, socket, and token. Set `RIG_HOME` to an absolute path to relocate it. The
+package never connects to the user's global Rig daemon. Provide
+`--config /path/to/happy2.toml` or
+`HAPPY2_CONFIG=/path/to/happy2.toml` to override the defaults.
+
+Clients can discover the selected authentication method at `GET /v0/auth/methods`.
+The response includes the server role and one `method` value: `password`,
+`magic_link`, `oidc`, `cloudflare_access`, or `null` in validation-only API mode. Password responses
+also report `signupEnabled`; OIDC responses report `oidcProvider`.
+
+## Profiles and avatar files
+
+Authentication creates an inactive account. `POST /v0/me/createProfile` (with the
+temporary bearer token) creates the product-level User profile—first name,
+optional last name, username, optional email, and optional phone—and activates
+the account. `GET /v0/me` reads the active profile and
+`POST /v0/me/updateProfile` replaces its editable state. Product routes reject
+accounts that do not yet have an active profile.
+
+`POST /v0/me/uploadAvatarFile` accepts one multipart image after profile
+creation. Its required `visibility` field is `public` or `private`. Images over
+2048px on either side or 10 MB are rejected. The server records the uploader,
+stores an unguessable CUID2-backed file record plus a JPEG file, converts the
+image to a 1024×1024 JPEG, and records a ThumbHash.
+
+`POST /v0/me/updateAvatar` takes a `fileId` and accepts only a public file the
+current user uploaded. Public files are fetched directly with
+`GET /v0/files/:fileId` plus the normal bearer header; they do not use signed
+URLs. Private files are fetched using a five-minute signed URL produced by
+`POST /v0/files/:fileId/createSignedUrl`.
+
+The server applies the bundled Drizzle SQLite migrations at startup. `file:`
+database URLs are suitable when all replicas share one local filesystem with
+SQLite locking. For independently deployed auth and API services, configure a
+shared `libsql:`/`https:` SQLite endpoint and, if needed, set its auth-token
+environment variable named by `database.auth_token_env`.
+
+Build the image from the repository root:
+
+```sh
+docker build -f packages/happy2-server/Dockerfile -t slopus/happy2 .
+docker run --rm -p 3000:3000 -v "$PWD/happy2.toml:/app/happy2.toml:ro" slopus/happy2 --config /app/happy2.toml
+```
+
+Mount a writable directory containing `happy2.toml` when using generated key
+material, because the adjacent `.env` file is the durable key store.
+
+## Authentication
+
+Choose exactly one of password, magic-link, OIDC, or Cloudflare Access in `happy2.toml`; startup
+rejects configurations that enable more than one method. Clients can learn the
+selected method from `GET /v0/auth/methods`.
+
+- Password registration is disabled unless `signup_enabled` is true. Every
+  password has its own random salt; a server-wide password pepper is also used.
+- Magic-link SMTP credentials are exclusively `EMAIL_SMTP_HOST`,
+  `EMAIL_SMTP_PORT`, `EMAIL_SMTP_USER`, and `EMAIL_SMTP_PASSWORD` environment
+  variables. The configured `redirect_url` should be the desktop app’s link
+  handler; it submits the token to `POST /v0/auth/magic-link/verify`.
+- OIDC uses discovery, PKCE, a nonce, and remote JWKS validation. Provider
+  secrets are referenced by environment-variable name in TOML.
+- Cloudflare Access validates the signed `Cf-Access-Jwt-Assertion` that Access
+  forwards after its policy permits the request. It uses the Access application
+  session rather than issuing a Happy (2) bearer token.
+
+### Cloudflare Access
+
+Cloudflare Access can provide all interactive authentication for a deployment.
+Create a **Self-hosted** HTTP application for the public Happy (2) hostname,
+attach the intended Access policy and identity providers, then configure this
+as the only enabled method:
+
+```toml
+[auth.password]
+enabled = false
+
+[auth.magic_link]
+enabled = false
+
+[auth.cloudflare_access]
+enabled = true
+team_domain = "https://your-team.cloudflareaccess.com"
+# Zero Trust → Access controls → Applications → your application →
+# Additional settings → Application Audience (AUD) Tag.
+audience = "your-access-application-aud-tag"
+```
+
+The server fetches the signing keys from the configured team domain and accepts
+only an RS256 application assertion whose issuer and audience match this
+configuration. It requires the Access JWT's `type`, `sub`, `email`, and expiry
+claims, then maps the `(team domain, sub)` identity to a Happy (2) account.
+As with the other methods, a newly authenticated account cannot use product
+routes until it has an active profile.
+
+Do not expose the origin directly. Use Cloudflare Tunnel or a network firewall
+that allows only Cloudflare to reach it; otherwise a captured valid assertion
+could be replayed directly to the origin until it expires. Happy (2) validates
+the assertion itself and deliberately does not trust identity headers or the
+`CF_Authorization` cookie. Cloudflare's browser/logout flow owns the session;
+use `https://your-happy-host/cdn-cgi/access/logout` to end it. Consequently,
+`POST /v0/auth/refresh` does not apply and `POST /v0/auth/logout` returns
+`cloudflare_access_manages_session`.
+
+The web bundle must be served from the protected hostname so browser requests,
+SSE, and the `CF_Authorization` cookie share one origin. To run the Electron
+desktop shell against that deployed bundle, start it with:
+
+```sh
+HAPPY2_SERVER_URL="https://happy.example.com" pnpm --filter happy2-desktop start
+```
+
+Electron loads the protected hostname in its own browser session, so Access
+performs its normal redirect before Happy (2) renders. Do not point the bundled
+local renderer at this hostname: that cross-origin arrangement cannot safely
+reuse Cloudflare's HttpOnly application cookie.
+
+On initial startup, external environment values win. If an auth-capable server
+has no JWT private key configured, it generates a 3072-bit RS256 key pair and
+adds base64-encoded `HAPPY2_JWT_PRIVATE_KEY_B64` and
+`HAPPY2_JWT_PUBLIC_KEY_B64` to the `.env` file beside its TOML file. It likewise
+adds `HAPPY2_PASSWORD_PEPPER` when password auth is enabled. Preserve that file
+as a secret; replacing it invalidates existing passwords and sessions. You may
+instead supply those variables through the deployment environment or mount PEM
+key files via the `jwt` config.
+
+Sessions are signed JWTs with a 30-day default lifetime and a stable `sid`.
+`POST /v0/auth/refresh` re-signs the same session ID and advances the database
+expiry. All authenticated requests check the shared SQLite session row, so a
+missing, expired, or revoked row is rejected regardless of JWT validity.
+
+## Collaboration API
+
+The API is HTTP-only. Durable reads and actions use JSON GET/POST endpoints;
+live hints, typing, presence, and WebRTC signaling use Server-Sent Events. All
+product routes require an active User profile. An `auth`-role server does not
+serve collaboration routes; `all` and `api` roles do.
+
+The main route groups are:
+
+| Area                  | Route families                                                                                                                            |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| Chats                 | `/v0/chats`, `createDirectMessage`, `createGroupDirectMessage`, `createChannel`, and channel update/archive/unarchive/delete actions      |
+| Membership and policy | chat join/leave/add/remove/set-role actions, member lists, posting policy, retention policy, topic, and owner transfer                    |
+| Messages              | history and message reads; send/edit/delete/forward actions; revision history; read receipts and unread state                             |
+| Replies and threads   | `quotedMessageId` creates an explicit reply in the main timeline; thread send/list/subscription/read actions maintain a separate timeline |
+| Message organization  | reactions, custom emoji, pins, chat and user bookmarks, scheduled messages, notifications, stars, and per-user ordering                   |
+| Discovery             | contacts, directories, files, thread inbox, calls, and fuzzy global search across visible users, channels, and messages                   |
+| Files                 | streaming and resumable uploads, upload state/cancel/complete, ranged downloads, image/video previews, deletion, and signed URLs          |
+| Presence and calls    | durable user status/DND preferences, ephemeral presence and typing, call lifecycle, and ephemeral WebRTC signaling                        |
+| Sync                  | state, paginated server/chat differences, consumer acknowledgement, compaction/reset, and SSE hints                                       |
+| Operations            | audit logs, access telemetry, bans, reports/actions, data-export jobs, backup records, retention runs, and server/user administration     |
+| Integrations          | bots, scoped API credentials, credential-authenticated posting, incoming/outgoing webhooks, slash commands, and delivery queues           |
+| Automation            | scheduled messages plus schedule, durable event, authenticated webhook, outgoing-webhook, bot-message, and moderation automations         |
+
+## AI agents
+
+`POST /v0/chats/createAgent` requires a display name and unique username. It
+creates an ordinary `User` with `kind = "agent"`, records the creating user, and
+opens a normal two-member direct message with it. There is no agent-specific
+chat kind. Creation is rejected until an administrator has built and selected a
+ready default image.
+Agents share the normal user profile, username, sender, directory, mention, and
+typing paths; only their Rig execution bindings are agent-specific. The product
+server—not the desktop or web client—creates and controls Rig sessions over its
+authenticated Unix socket. Configure `[agents]` with the socket, token, Rig
+executable, and server-owned `default_cwd`; clients cannot select filesystem
+paths.
+
+The server seeds immutable `Daycare Minimal` and `Daycare Full` definitions from
+the pinned upstream Daycare runtime Dockerfiles. Both use Ubuntu 24.04; Full adds
+the Python, Rust, and Go toolchains. Administrators use
+`GET /v0/admin/agentImages`, `GET /v0/admin/agentImages/:imageId`,
+`POST /v0/admin/agentImages/:imageId/buildImage`,
+`POST /v0/admin/agentImages/createImage`, and
+`POST /v0/admin/agentImages/:imageId/setDefaultImage` to list concise build
+summaries, inspect a definition's Dockerfile and latest build log, build a
+built-in or custom persisted Dockerfile, and select a ready default. List rows
+include a best-effort 0–100 step percentage and the last non-empty log line;
+detail responses include the Dockerfile, log, and an explicit truncation flag.
+Definitions and content-derived tags never change. Builds are leased in SQLite,
+resume after server restart, use the administrator host's active Docker context,
+and publish durable `agent-images` sync hints over the existing SSE connection.
+Docker output is persisted in 500 ms batches so progress remains live without
+turning every process chunk into a SQLite transaction. The latest attempt's log
+is capped at two million characters and retries begin a fresh log.
+
+Each agent is rooted at `default_cwd/agents/<agent-user-id>`. Direct/private
+conversations get separate `users/<human-user-id>/home` and
+`users/<human-user-id>/workspace` directories below that root, preventing one
+person's files and context from leaking into another's. The server starts one
+long-lived container with a read-only root filesystem, writable tmpfs mounts at
+`/tmp`, `/run`, `/var/tmp`, and `/var/run`, 1 GiB `/dev/shm`, init enabled, and
+only the private home and workspace mounted read-write at `/home` and
+`/workspace`. It then creates the Rig session with Rig's built-in existing
+container configuration and `/workspace` working directory. For now, only
+top-level messages in exact two-user DMs invoke Rig. Agents may be ordinary
+members of group DMs and channels—including multiple agents in one channel—but
+those conversations remain dormant until mention-based collaboration is
+implemented.
+
+The workspace file API is available to any chat that has exactly one connected
+Rig environment. It resolves the persisted `agent_rig_bindings.cwd` host path,
+which is the directory mounted into that environment at `/workspace`; it never
+creates a separate directory from the chat ID. A current chat member can read
+its file-tree snapshot from `GET /v0/chats/:chatId/workspace`. An unconnected or
+ambiguous chat returns `404`, and public-channel discovery alone never reveals
+workspace contents. Paths are canonical `@pierre/trees` input (directory paths
+end in `/`), absolute server paths are never returned, and directory symlinks
+are listed without being traversed.
+
+The first request lazily creates a process-local partial index and starts its
+recursive monitor before reading the root. Adaptive preload returns at most
+2,500 paths, 192 KiB of encoded path data, three levels, and 128 inspected
+directories. A directory with more than 400 direct children remains collapsed.
+The default-deferred basenames are `.git`, `.next`, `.pnpm`, `.turbo`, `.yarn`,
+`.cache`, `build`, `coverage`, `dist`, `node_modules`, `target`, and `vendor`.
+These entries are visible and fully accessible; the preload simply does not
+descend into them. `unloadedDirectories` identifies every visible directory
+whose children still need to be loaded.
+
+`GET /v0/chats/:chatId/workspace?directory=<canonical-directory>` pages one
+directory's direct children, including the root when `directory` is empty. The
+default page is 250 entries, callers may request up to 1,000, and an adaptive
+128 KiB path-data ceiling can end a page earlier. `nextCursor` continues the
+same directory; a filesystem change invalidates it with `409
+workspace_cursor_stale`. All entries—including hidden files and the contents of
+`.git/`—remain reachable through these pages.
+
+Directory listings use a per-workspace LRU capped at 20,000 entries. Chats
+connected to the same mounted host directory share one index and monitor. At
+most 8 partial indexes stay warm; cooling an older index releases its directory
+and Git caches but keeps its lightweight monitor active, and the next request
+warms it again. Git status initializes and refreshes in the background, so a
+cold tree response does not wait for Git. Responses expose `gitStatusPending`
+and a process-local `revision`; completion publishes the same
+`workspace.changed` SSE invalidation as a filesystem mutation. File changes are
+coalesced for 20 ms,
+invalidate only affected directory-cache branches when the watcher supplies a
+path, and cause clients to reconcile through the HTTP snapshot. Successful
+responses provide a private, revalidated `ETag`, allowing an unchanged
+reconciliation to return no body over a slow connection. All indexes and
+monitors close with the server.
+
+If the configured socket is unavailable, Happy (2) runs `rig daemon start` without
+a shell and passes the configured socket and token paths through Rig's standard
+environment variables. User turns are ordinary chat messages. The message and
+its durable `agent_turns` outbox row commit in one SQLite transaction; leased
+workers then serialize turns per agent and chat and resume them after restart.
+At startup the server enables Rig's durable global event queue when necessary.
+It consumes the queue through one resumable global SSE connection and a numeric
+cursor persisted in SQLite; it never polls the queue or opens per-session event
+streams. Agent work is broadcast through the ordinary typing-presence event,
+and persisted replies use the agent `User` as sender, update human unread
+counts, and then publish normal sync hints. Agent users never accumulate unread
+counters, receipts, or notifications. Applied Rig events are trimmed in batches
+after 1,000 updates or one day. Remote clients use the same chat and sync APIs as
+local clients and never need access to Rig itself.
+
+Rig remains the source of truth for agent secret registrations and values.
+Administrators use `GET /v0/admin/agentSecrets`,
+`POST /v0/admin/agentSecrets/createSecret`, and
+`POST /v0/admin/agentSecrets/:secretId/deleteSecret` through Happy (2); list and
+mutation responses contain only the Rig ID, description, and environment-variable
+names. Secret values are forwarded once to Rig and are never persisted in the
+Happy (2) database or returned to a client. Happy (2) stores only assignments,
+managed through the `attachToAgent`, `detachFromAgent`, `attachToChannel`, and
+`detachFromChannel` actions. An agent assignment applies to every Rig session for
+that agent; a channel assignment applies to every agent Rig session bound to that
+channel. The union is reconciled before each turn and when Happy (2) starts, while
+Rig still requires the model to select the needed bundle IDs on each shell command.
+All secret-management routes require server-admin permission and publish durable
+`agent-secrets` sync hints.
+
+Channels are `public_channel` or `private_channel`. Direct chats support both
+exact two-user DMs and membership-exact group DMs. Public channels can be
+discovered and read by every active server member, but posting requires joining.
+Private channels and DMs require current membership. Channel owners remain
+canonical through leave, removal, role changes, and account deletion. The first
+active profile is a server administrator. Administrators can change the server
+profile and retention defaults, manage user titles/roles, inspect durable
+last-access times, ban or delete users, moderate content and files, and send
+audited automated messages.
+
+`POST /v0/files/upload` streams one file to storage and returns a stable CUID2
+file ID. Large clients use `createUpload`, ordered `appendUpload` calls, and
+`completeUpload`; completion is replay-safe across a process crash. JPEG, PNG,
+WebP, GIF, MP4, and WebM signatures are recognized, metadata is probed with
+bounded work, previews/posters are tracked as derivatives, and downloads support
+byte ranges. Storage and malware scanning are provider interfaces. Quota is
+reserved while bytes are staged, rejected content is quarantined, scan results
+are durable, and periodic maintenance releases abandoned reservations and
+staging artifacts.
+
+A file is visible to its uploader, through an explicit unexpired user/chat/server
+grant, as a public profile or custom-emoji asset, or through a live message the
+requester can currently read. Forwarding creates a destination attachment grant
+without promoting the file globally. Deleting or expiring the last visible
+message reference removes that derived access. The files directory and previews
+use the same authorization query, so private-channel and DM attachments do not
+leak.
+
+Message sends accept an optional `clientMutationId`; retries by the same user in
+the same chat return the originally committed message. A send may contain text,
+attachment file IDs, `quotedMessageId`, `threadRootMessageId`, and a bounded
+self-destruction duration. Deletion and expiry leave syncable tombstones rather
+than hard-deleting message identity, remove searchable/revision plaintext, and
+recompute thread projections. `after_read` destruction uses a send-time receipt
+roster, so users who join later cannot block expiry.
+
+HTTP write actions also accept `Idempotency-Key`. Keys are isolated by the
+authenticated principal and concrete action path, conflicting payload reuse is
+rejected, and completed responses survive restart. Request limiting and realtime
+fanout use local adapter implementations; Redis-backed implementations can be
+added without making process-local state authoritative.
+
+## Sync protocol
+
+The protocol adapts Telegram's independent update sequences, state snapshots,
+and paginated differences, as described in its official
+[Working with Updates](https://core.telegram.org/api/updates),
+[`updates.getState`](https://core.telegram.org/method/updates.getState), and
+[`updates.getDifference`](https://core.telegram.org/method/updates.getDifference)
+documentation.
+
+Happy (2) has two durable cursor levels:
+
+- A database-generation ID and server-wide `sequence` identify durable objects
+  that changed for reconnect discovery.
+- Every chat has an independent `pts`. Messages, reactions, tombstones, thread
+  activity, topics, and membership-visible changes advance that chat's `pts`.
+
+Cursors are decimal strings in JSON, never JSON numbers; the current server
+rejects cursor values outside its safe-integer operating range. Every mutation
+allocates the common sequence, changes domain rows, advances affected chat
+cursors, and appends update pointers in one database transaction. Pubsub happens
+only after commit. The local pubsub implementation is intentionally replaceable
+by a Redis adapter and is allowed to drop, duplicate, reorder, or coalesce events.
+
+1. `GET /v0/sync/state` returns `{protocolVersion, generation, sequence}`. On a
+   new installation this is a baseline, not the beginning of retained history.
+2. `POST /v0/sync/getDifference` takes the last stored
+   `state: {generation, sequence}`, optional fixed `untilSequence`, and `limit`.
+   It returns changed chat summaries with
+   their latest `pts`, removed private-chat IDs, changed global areas, an
+   intermediate state, and the fixed target state. A slice is repeated with its
+   intermediate cursor and the same target until complete.
+3. For every changed chat, `POST /v0/chats/:chatId/getDifference` takes the
+   cached `state: {membershipEpoch, pts}`. It returns ordered pointers plus
+   current message projections/tombstones. A changed membership epoch or pruned
+   cursor returns a reset/too-long result; the client discards that cached chat
+   and fetches current history.
+4. The client advances its common cursor in the same local transaction that
+   stores pending target `pts` values. It advances a chat cursor only with the
+   corresponding projections/tombstones. Duplicate projections are safe.
+5. `POST /v0/sync/acknowledge` records a per-user, per-device durable consumer
+   cursor. Compaction honors active acknowledgements and retention windows. A
+   cursor older than retained history receives an explicit reset with the
+   minimum recoverable sequence rather than an incomplete difference.
+
+For a chat update with `ptsCount`, clients use the Telegram rule:
+
+```text
+localPts + ptsCount == update.pts  apply it
+localPts + ptsCount >  update.pts  ignore the duplicate
+localPts + ptsCount <  update.pts  stop and fetch the difference
+```
+
+`GET /v0/sync/events` is a deliberately lossy SSE stream. It first subscribes,
+then emits `ready` with current durable state. `sync` events only hint at a newer
+server sequence/chat `pts`; clients never advance a durable cursor from SSE.
+`typing`, `presence`, and `call.signal` are ephemeral and never enter a
+difference. Heartbeats include a fresh database state and revalidate the session,
+so another local instance's commit, a missed publish, ban, or logout is detected.
+Every reconnect runs the HTTP difference flow; `Last-Event-ID` is not a sync
+cursor.

package/packages/happy2-server/bin/happy2.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../dist/runner.js";

package/packages/happy2-server/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/packages/happy2-server/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../sources/cli.ts"],"names":[],"mappings":""}

package/packages/happy2-server/dist/cli.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { TokenService } from "./modules/auth/tokens.js";
+import { loadRuntimeConfig } from "./modules/config/runtime.js";
+import { Database } from "./modules/database.js";
+import { buildServer } from "./server.js";
+const { values } = parseArgs({
+    options: { config: { type: "string" } },
+});
+const configPath = values.config ?? process.env.HAPPY2_CONFIG;
+const { config } = await loadRuntimeConfig(configPath);
+const database = new Database(config.database.url, config.database.authTokenEnv ? process.env[config.database.authTokenEnv] : undefined);
+await database.migrate();
+const app = await buildServer(config, { database, tokens: await TokenService.create(config) });
+let cleanupPromise;
+const cleanup = () => {
+    cleanupPromise ??= (async () => {
+        try {
+            await app.close();
+        }
+        finally {
+            database.close();
+        }
+    })();
+    return cleanupPromise;
+};
+try {
+    await app.listen({ host: config.server.host, port: config.server.port });
+    const stop = () => {
+        void cleanup().catch((error) => {
+            app.log.error(error);
+            process.exitCode = 1;
+        });
+    };
+    process.once("SIGHUP", stop);
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+}
+catch (error) {
+    app.log.error(error);
+    await cleanup().catch((cleanupError) => app.log.error(cleanupError));
+    process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/packages/happy2-server/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../sources/cli.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IACzB,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;CAC1C,CAAC,CAAC;AACH,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAC9D,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,iBAAiB,CAAC,UAAU,CAAC,CAAC;AACvD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CACzB,MAAM,CAAC,QAAQ,CAAC,GAAG,EACnB,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS,CACvF,CAAC;AACF,MAAM,QAAQ,CAAC,OAAO,EAAE,CAAC;AACzB,MAAM,GAAG,GAAG,MAAM,WAAW,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AAC/F,IAAI,cAAyC,CAAC;AAC9C,MAAM,OAAO,GAAG,GAAG,EAAE;IACjB,cAAc,KAAK,CAAC,KAAK,IAAI,EAAE;QAC3B,IAAI,CAAC;YACD,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC;gBAAS,CAAC;YACP,QAAQ,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;IACL,CAAC,CAAC,EAAE,CAAC;IACL,OAAO,cAAc,CAAC;AAC1B,CAAC,CAAC;AACF,IAAI,CAAC;IACD,MAAM,GAAG,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,GAAG,EAAE;QACd,KAAK,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACpC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACrB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;AAClC,CAAC;AAAC,OAAO,KAAK,EAAE,CAAC;IACb,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACrB,MAAM,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,YAAqB,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;IAC9E,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACzB,CAAC"}