Initial commit: Mixly HF Space deploy config

Modelled on Host-Tierly. Adapted after verifying against Mixly's
actual source (scripts/restore-db.mjs, src/lib/backup.ts, src/lib/s3.ts,
src/instrumentation.ts, src/lib/env.ts, shopify.app.toml):
- DB path /data/mixly.db, bucket Mixly-storage, snapshot prefix mixly-
- Space solora-hq/Mixly, GitHub source phamdung2209/Mixly
- Kept Prisma Studio proxy (Mixly has src/lib/ops/studio-proxy.ts)
- Dropped Crisp build secret (no Crisp integration in Mixly)
- Dropped --config=production (only a default shopify.app.toml exists)
- Scopes/API version taken from Mixly's own shopify.app.toml

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

DEPLOY.md

@@ -0,0 +1,155 @@
+# Mixly on Hugging Face Spaces — deploy & operations
+
+The Space (`solora-hq/Mixly`) is a **Docker** host. Its `Dockerfile` clones the
+**private** GitHub repo `phamdung2209/Mixly` at build time and runs the Next.js app.
+
+Public URL: `https://solora-hq-mixly.hf.space`
+
+> ⚠️ **Data isolation.** `solora-hq` also hosts **Tierly**, which is LIVE with real
+> merchant data. Mixly's `DATABASE_URL`, `S3_BUCKET`, and Space name are a
+> completely separate set of identifiers from Tierly's — never copy a value from
+> Tierly's `DEPLOY.md` here. Concretely: DB path is `/data/mixly.db` (not
+> `tierly.db`), bucket is `Mixly-storage` (not `Tierly-storage`), Space is
+> `solora-hq/Mixly` (not `solora-hq/Tierly`). Pointing Mixly at any of Tierly's
+> identifiers risks corrupting or leaking live merchant data.
+
+---
+
+## 0. First-time setup (do this once — the Space doesn't exist yet)
+
+1. **Create the Space**: https://huggingface.co/new-space → Owner `solora-hq`,
+   Space name `Mixly`, **SDK: Docker**, visibility your choice, no template.
+2. **Add the remote and push this repo**:
+   ```
+   git remote add origin https://huggingface.co/spaces/solora-hq/Mixly
+   git push -u origin main
+   ```
+   The first build will fail (or crash-loop) until the secrets in §2 are set —
+   that's expected, HF just needs a repo to attach the build to.
+3. **Create the S3 storage bucket**: HF → your `solora-hq` org → **Storage** →
+   **New bucket** → name it exactly `Mixly-storage` (bare name, no slashes). Double
+   check it is not `Tierly-storage`.
+4. **Set every secret in §2 below** (Space → Settings → Variables and secrets),
+   then Space → Settings → **Factory rebuild**.
+
+---
+
+## 1. GitHub token (required — the repo is private)
+
+Cloning a private repo inside the Docker build needs a token. Create a
+**fine-grained Personal Access Token**, scoped to just this repo, read-only:
+
+1. GitHub → **Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new**.
+2. **Resource owner**: `phamdung2209`. **Repository access**: *Only select repositories* → `Mixly`.
+3. **Permissions → Repository → Contents: Read-only** (that's all it needs).
+4. Expiration: 90 days (rotate on expiry). Generate → copy the `github_pat_…`.
+
+Then add it to the Space as a **build secret**:
+- Space → **Settings → Variables and secrets → New secret**
+- Name: `GITHUB_TOKEN` · Value: the `github_pat_…`
+
+> The Dockerfile reads it via `--mount=type=secret,id=GITHUB_TOKEN`, so it is
+> **never baked into an image layer**.
+
+---
+
+## 2. Space secrets (runtime) — Settings → Variables and secrets
+
+🔒 Paste values in the HF UI, never into code/git. **Secrets** (hidden) vs
+**Variables** (visible) — put all credentials as *Secrets*.
+
+### Required
+| Name | Value / where from |
+|---|---|
+| `GITHUB_TOKEN` | build secret from §1 |
+| `SHOPIFY_API_KEY` | Partner Dashboard → Mixly → API credentials |
+| `SHOPIFY_API_SECRET` | ″ (secret) |
+| `NEXT_PUBLIC_SHOPIFY_API_KEY` | **same value as** `SHOPIFY_API_KEY` |
+| `SHOPIFY_SCOPES` | `read_orders,read_products,write_discounts` (match `shopify.app.toml`) |
+| `SHOPIFY_APP_URL` | `https://solora-hq-mixly.hf.space` |
+| `SHOPIFY_API_VERSION` | `2026-07` |
+| `DATABASE_URL` | `file:/data/mixly.db` (persistent mount — see §3) |
+| `SESSION_ENCRYPTION_KEY` | `openssl rand -hex 32`. **Set once, never change** (rotating it forces every store to re-auth). |
+
+### Ops Console + DB access (`/ops`, `/ops/studio`)
+| Name | Value |
+|---|---|
+| `OPS_ALLOWLIST` | comma-separated emails allowed into `/ops` |
+| `AUTH_SECRET` | `npx auth secret`. Keep stable (else your `/ops` sessions drop). |
+| `AUTH_GOOGLE_ID` | Google Cloud Console → OAuth client ID |
+| `AUTH_GOOGLE_SECRET` | ″ (redirect URI: `https://solora-hq-mixly.hf.space/api/auth/callback/google`) |
+
+### DB backup (§4) — HF Storage Bucket via S3 API
+| Name | Value |
+|---|---|
+| `S3_ENDPOINT` | `https://s3.hf.co/solora-hq` (gateway scoped to the namespace) |
+| `S3_BUCKET` | `Mixly-storage` (bare bucket name — **not** `Tierly-storage`) |
+| `S3_ACCESS_KEY_ID` | `HFAK…` — HF **Access Tokens** → token (Write) → dropdown → **Generate S3 credentials** |
+| `S3_SECRET_ACCESS_KEY` | ″ (shown once) |
+| `HF_TOKEN` | HF bearer token — used to rebuild/restart the Space from `/ops/backup` after a DB restore (§4), and by `scripts/sync-env.mjs` (§5), NOT the S3 creds |
+
+### Optional (features degrade gracefully when unset)
+`SENTRY_DSN`, `HF_SPACE_ID` (defaults to `solora-hq/Mixly` in code — only set if
+the Space is ever renamed), `GITHUB_REPO` (overrides the clone source; the
+Dockerfile's `ARG GITHUB_REPO` build arg already defaults to the right repo).
+
+Mixly has **no** Crisp chat, QStash, or email (Resend) integration — unlike
+Tierly, none of `NEXT_PUBLIC_CRISP_WEBSITE_ID`, `QSTASH_*`, `RESEND_API_KEY`,
+`EMAIL_FROM`, or `CRON_SECRET` apply here; don't set them.
+
+---
+
+## 3. Persistent storage
+
+Space → **Settings → Persistent storage** → enable (Small is plenty). It mounts
+at `/data`, which is where `DATABASE_URL=file:/data/mixly.db` points. Without it,
+`/data` resets on every rebuild — which is exactly why §4 exists.
+
+> Do **not** mount the Storage Bucket as a data volume. Backup talks to it over the
+> S3 API (§4); a bucket *mount* is a schedule-time dependency and, if HF can't attach
+> it, the Space fails with "Scheduling failure: unable to schedule".
+
+---
+
+## 4. Database backup / restore (HF Storage Bucket, S3 API)
+
+The app backs the SQLite DB up to a **Storage Bucket over the S3 API** and restores
+it on boot if `/data` is empty — so data survives a rebuild even on the free tier.
+Network-only (no mount), so it never blocks Space scheduling.
+
+- **What's backed up:** only the SQLite DB file (`/data/mixly.db`). It holds
+  everything stateful: Shopify sessions (tokens encrypted at rest), bundle offers,
+  bundle configs, shop profiles, settings. Migrations live in git; nothing else
+  needs backing up.
+- **The one thing that is NOT in the bucket:** `SESSION_ENCRYPTION_KEY`. It lives
+  only in Space secrets. Keep it — a restored DB with a lost/rotated key can't
+  decrypt stored Shopify tokens (the app then just re-exchanges them, no data loss,
+  but avoid churn).
+- **Bucket:** `solora-hq/Mixly-storage`. Objects: `latest.db` (overwritten in place —
+  no history growth) + `snapshots/mixly-YYYY-MM-DD.db` (daily, pruned after 30 days).
+- **Schedule:** in-process — an initial backup ~1 min after boot, then hourly, plus a
+  debounced write after each DB change and a final flush on SIGTERM (see
+  `src/lib/backup.ts` + `src/lib/s3.ts`, started from `src/instrumentation.ts`).
+- **Operator-driven backup/restore:** unlike a plain snapshot loop, Mixly ships an
+  `/ops/backup` panel (Google-authenticated, see §2) that can trigger an immediate
+  backup, upload a snapshot to restore from, and inspect it (table/row checks)
+  before committing. Restoring requires typing `overwrite` to confirm, snapshots
+  the *current* DB as a `pre-restore-…db` rollback key first, then calls
+  `restartSpace()` (needs `HF_TOKEN`) to restart the Space onto the restored file.
+
+---
+
+## 5. Deploy / rebuild
+
+- **Redeploy the web app:** push to GitHub `main`, then in the Space use
+  **Settings → Factory rebuild** (re-clones latest `main`).
+- **Push local env vars as Space secrets:** `HF_TOKEN=… node scripts/sync-env.mjs
+  [.env.production.local] [solora-hq/Mixly]` (both args optional, those are the
+  defaults) — reads `KEY=value` lines and pushes each as a secret via the HF API.
+  Changes apply on the next rebuild/restart.
+- **Deploy the Shopify Function / extensions:** that is a *separate* target, run from
+  your machine (needs the Shopify CLI + Partner auth) — `npm run app:deploy`. The
+  container also runs this non-fatally during a Space build (see Dockerfile), gated
+  on the `SHOPIFY_CLI_PARTNERS_TOKEN` build secret.
+
+> After changing scopes or the app URL, re-open the app in the store to re-consent.

Dockerfile

@@ -0,0 +1,96 @@
+# syntax=docker/dockerfile:1
+#
+# Hugging Face Space (Docker SDK) for Mixly.
+#
+# The app source lives in the PRIVATE GitHub repo, not in this Space repo — this
+# Dockerfile clones it at build time using the GITHUB_TOKEN *build secret*, builds
+# the Next.js app, then runs it. Keeping the Space tiny means a rebuild always
+# pulls the latest `main` from GitHub.
+#
+# The SQLite DB lives on the /data mount. On boot it is restored from the HF Storage
+# Bucket (S3 API) if /data is empty, so data survives even without paid Persistent
+# Storage (see scripts/restore-db.mjs).
+
+# ---- builder ----
+FROM node:24-slim AS builder
+WORKDIR /app
+RUN apt-get update && apt-get install -y --no-install-recommends git ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Which repo/branch to deploy. Override GITHUB_REF (Space variable) to pin a release.
+ARG GITHUB_REPO=github.com/phamdung2209/Mixly.git
+ARG GITHUB_REF=main
+
+# Clone with the token mounted as a build secret — it is never written into an
+# image layer. Add GITHUB_TOKEN in Space → Settings → Secrets.
+RUN --mount=type=secret,id=GITHUB_TOKEN,required=true \
+    git clone --depth 1 --branch "${GITHUB_REF}" \
+      "https://x-access-token:$(cat /run/secrets/GITHUB_TOKEN)@${GITHUB_REPO}" .
+
+ENV NEXT_TELEMETRY_DISABLED=1
+# Placeholder values ONLY so env validation passes during `next build` (some server
+# modules read env at import). The app reads the REAL values from HF secrets at
+# runtime; none of these are NEXT_PUBLIC, so nothing is baked into the output.
+ENV SHOPIFY_API_KEY=build SHOPIFY_API_SECRET=build SHOPIFY_SCOPES=read_products \
+    SHOPIFY_APP_URL=https://build.invalid SHOPIFY_API_VERSION=2026-07 DATABASE_URL=file:/tmp/build.db
+# NEXT_PUBLIC_* is inlined into the client bundle at BUILD time, so it must exist
+# during `npm run build` — a runtime secret is too late. The Shopify API key is
+# public (it ships in the browser), so mounting the secret just for the build is safe.
+RUN --mount=type=secret,id=NEXT_PUBLIC_SHOPIFY_API_KEY \
+    export NEXT_PUBLIC_SHOPIFY_API_KEY="$(cat /run/secrets/NEXT_PUBLIC_SHOPIFY_API_KEY 2>/dev/null)" && \
+    npm ci && npx prisma generate && npm run build && mkdir -p public
+
+# Deploy the Shopify Function + app config as part of the Space build, so ONE rebuild
+# ships the web app AND the extensions together. Only runs on a real rebuild (not on
+# restart/wake), so no version churn. NON-FATAL: a Shopify hiccup never breaks the web
+# deploy. Needs the SHOPIFY_CLI_PARTNERS_TOKEN Space secret (else it just skips).
+RUN --mount=type=secret,id=SHOPIFY_CLI_PARTNERS_TOKEN \
+    if [ -s /run/secrets/SHOPIFY_CLI_PARTNERS_TOKEN ]; then \
+      export SHOPIFY_CLI_PARTNERS_TOKEN="$(cat /run/secrets/SHOPIFY_CLI_PARTNERS_TOKEN)" CI=true; \
+      for d in extensions/*/; do [ -f "${d}package.json" ] && (cd "$d" && npm install --no-audit --no-fund || true); done; \
+      npx shopify app deploy --allow-updates || echo "WARN: shopify app deploy failed (non-fatal)"; \
+    else echo "SHOPIFY_CLI_PARTNERS_TOKEN not set — skipping Shopify deploy"; fi
+
+# ---- runner ----
+FROM node:24-slim AS runner
+WORKDIR /app
+ENV NODE_ENV=production NEXT_TELEMETRY_DISABLED=1 PORT=3000 HOSTNAME=0.0.0.0
+
+# tini as PID 1: forwards SIGTERM to the app and reaps zombies. Without it (e.g.
+# `npm start` as PID 1) npm swallows SIGTERM and never forwards it to the Node
+# server, so the shutdown DB backup (src/lib/backup.ts) never runs on a rebuild.
+RUN apt-get update && apt-get install -y --no-install-recommends tini \
+    && rm -rf /var/lib/apt/lists/*
+
+# node:24-slim already ships a `node` user at UID 1000 (which HF mounts /data for) —
+# reuse it; creating a second UID-1000 user fails with "UID 1000 is not unique".
+COPY --from=builder --chown=node /app/node_modules ./node_modules
+COPY --from=builder --chown=node /app/.next ./.next
+COPY --from=builder --chown=node /app/public ./public
+COPY --from=builder --chown=node /app/package.json ./package.json
+COPY --from=builder --chown=node /app/next.config.ts ./next.config.ts
+COPY --from=builder --chown=node /app/prisma ./prisma
+COPY --from=builder --chown=node /app/prisma.config.ts ./prisma.config.ts
+COPY --from=builder --chown=node /app/scripts ./scripts
+
+# Make /data writable with OR without Persistent Storage. If enabled, HF mounts
+# /data (uid 1000) over this. If not, this ephemeral dir is used and data still
+# survives rebuilds via the S3 bucket restore on boot (scripts/restore-db.mjs).
+RUN mkdir -p /data && chown node:node /data
+USER node
+
+EXPOSE 3000
+# 1) restore the DB from the HF Storage Bucket (S3) if /data is empty, 2) apply migrations,
+# 3) start. Restore MUST run before migrate — migrate would otherwise create an
+# empty DB and the restore would think data already exists.
+# `exec next` (NOT `npm start`) so the Node server itself becomes the process that
+# receives SIGTERM on rebuild/sleep — that's what triggers the final DB backup
+# (src/lib/backup.ts). npm would fork the server as a child and swallow the signal.
+# tini (ENTRYPOINT) forwards the signal and reaps zombies.
+ENTRYPOINT ["tini", "--"]
+# Prisma Studio runs in the background on port 5555. NOTE: prisma studio v7 binds
+# 0.0.0.0 (no hostname flag) — it is NOT localhost-only. It stays private because HF
+# routes ONLY port 3000 as ingress and network-isolates the container; the DB is
+# reached via the operator + same-origin gated route handlers (src/lib/ops/studio-proxy)
+# at /ops/studio. Do NOT reuse this where 5555 is published (e.g. docker -p 5555:5555).
+CMD ["sh", "-c", "node scripts/restore-db.mjs && node_modules/.bin/prisma migrate deploy && (node_modules/.bin/prisma studio --port 5555 --browser none &) && exec node_modules/.bin/next start"]

README.md

@@ -0,0 +1,22 @@
+---
+title: Mixly
+emoji: 📦
+colorFrom: purple
+colorTo: green
+sdk: docker
+app_port: 3000
+pinned: false
+license: mit
+short_description: Product bundles that discount what's already in the cart. No new SKUs, no inventory drift.
+---
+
+# Mixly — Hugging Face Space
+
+Docker host for the [Mixly](https://github.com/phamdung2209/Mixly) Shopify app.
+This Space repo holds only the `Dockerfile`; it clones the app source from the
+private GitHub repo at build time.
+
+**Deploy / operations guide → [`DEPLOY.md`](./DEPLOY.md)** (GitHub token, secrets,
+persistent storage, DB backup/restore, rebuilds).
+
+Config reference: https://huggingface.co/docs/hub/spaces-config-reference