@happier-dev/stack 0.1.0-preview.96.1 → 0.2.0-preview.1775370152.55749

package/README.md

@@ -18,10 +18,11 @@ If you want to **develop Happier** (worktrees, multiple stacks, upstream PR work
 ### Quickstart
 
 ```bash
-curl -fsSL https://happier.dev/self-host | bash
+curl -fsSL https://happier.dev/install | bash
+happier relay host install
 ```
 
-Direct hstack flow:
+Legacy hstack wrapper (optional):
 
 ```bash
 hstack self-host install
@@ -102,7 +103,7 @@ If you want to **develop Happier** (worktrees, multiple stacks, upstream PR work
 ### Setup (guided)
 
 ```bash
-npx --yes -p @happier-dev/stack hstack setup --profile=dev
+npx --yes -p @happier-dev/stack hstack setup-from-source --profile=dev
 ```
 
 During setup, you’ll be guided through:
@@ -127,12 +128,12 @@ hstack stack wt dev -- use dev
 You can also set it non-interactively:
 
 ```bash
-npx --yes -p @happier-dev/stack hstack setup --profile=dev --workspace-dir=~/Documents/Development/happier
+npx --yes -p @happier-dev/stack hstack setup-from-source --profile=dev --workspace-dir=~/Documents/Development/happier
 ```
 
 ### Why this exists
 
-- **Automated setup**: `hstack setup` + `hstack start` gets the whole stack up and running.
+- **Automated setup (from source)**: `hstack setup-from-source` + `hstack start` gets the whole stack up and running.
 - **No hosted dependency**: run the full stack on your own computer.
 - **Lower latency**: localhost/LAN is typically much faster than remote hosted servers.
 - **Custom forks**: easily use forks while still contributing upstream to `happier-dev/happier`.
@@ -180,7 +181,7 @@ More details + automation: `[docs/remote-access.md](docs/remote-access.md)`.
 
 - **Scripts**: `scripts/*.mjs` (bootstrap/dev/start/build/stacks/worktrees/service/tailscale/mobile)
 - **Stable checkout**: `<workspace>/main` (the monorepo clone; treated as read-only)
-- **Dev checkout**: `<workspace>/dev` (created by `hstack setup --profile=dev`)
+- **Dev checkout**: `<workspace>/dev` (created by `hstack setup-from-source --profile=dev`)
 - **Worktrees**:
   - PRs: `<workspace>/pr/...`
   - locals: `<workspace>/local/<owner>/...`
@@ -266,7 +267,9 @@ Optional: enable Expo dev-client for mobile reviewers (works with both default `
 npx --yes -p @happier-dev/stack hstack tools setup-pr --repo=123 --dev --mobile
 ```
 
-Optional: run it in a self-contained sandbox folder (auto-cleaned):
+Optional: run it in a sandbox folder (auto-cleaned).
+
+Note: `review-pr` uses a persistent sandbox workspace cache by default to speed up repeat runs (default: `~/.happier-stack/cache/sandbox/workspace`). Add `--no-workspace-cache` for a fully self-contained sandbox, or `--workspace-cache-dir=...` to customize the location.
 
 ```bash
 SANDBOX="$(mktemp -d /tmp/hstack-review-pr.XXXXXX)"
@@ -381,7 +384,8 @@ Details: `[docs/tauri.md](docs/tauri.md)`.
 ### Commands (high-signal)
 
 - **Setup**:
-  - `hstack setup` (guided; selfhost or dev)
+  - `hstack setup-from-source` (guided; selfhost or dev)
+  - (deprecated alias) `hstack setup`
   - (advanced) `hstack init` (plumbing: shims/runtime/pointer env)
   - (advanced) `hstack bootstrap --interactive` (workspace bootstrap wizard)
 - **Run**:
@@ -448,7 +452,7 @@ Notes:
 
 ### Breaking changes (vs “Happy Stacks”)
 
-- No compatibility/migration for previous installs: uninstall old setups and run `hstack setup` again.
+- No compatibility/migration for previous installs: uninstall old setups and run `hstack setup-from-source` again.
 - Env prefix is now `HAPPIER_STACK_*` (no legacy aliases like `HAPPY_STACKS_*` / `HAPPY_LOCAL_*`).
 - Workspace/worktrees are monorepo-first (default workspace: `~/.happier-stack/workspace`, with `main/`, `dev/`, `pr/`, `local/`, `tmp/`).
 - Yarn-only (no pnpm support).

package/bin/happier.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import '../scripts/happier.mjs';

package/bin/hstack.mjs

@@ -5,13 +5,15 @@ import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { commandHelpArgs, renderhstackRootHelp, resolvehstackCommand } from '../scripts/utils/cli/cli_registry.mjs';
 import { expandHome, getCanonicalHomeEnvPathFromEnv } from '../scripts/utils/paths/canonical_home.mjs';
-import { resolveStackEnvPath } from '../scripts/utils/paths/paths.mjs';
+import { coerceHappyMonorepoRootFromPath, resolveStackEnvPath } from '../scripts/utils/paths/paths.mjs';
 import { SANDBOX_PRESERVE_KEYS, scrubHappierStackEnv } from '../scripts/utils/env/scrub_env.mjs';
 import { maybeAutoUpdateNotice as maybeAutoUpdateNoticeShared } from '../scripts/utils/update/auto_update_notice.mjs';
+import { resolveBundledWorkspaceSyncModulePath } from '../scripts/runtime/resolveBundledWorkspaceSyncModulePath.mjs';
+import { readBundledWorkspaceSyncConfig } from '../scripts/runtime/readBundledWorkspaceSyncConfig.mjs';
 
 function getCliRootDir() {
   return dirname(dirname(fileURLToPath(import.meta.url)));
@@ -157,7 +159,14 @@ function applySandboxDirIfRequested(argv) {
   // Keep all state under one folder that can be deleted to reset completely.
   const canonicalHomeDir = join(sandboxDir, 'canonical');
   const homeDir = join(sandboxDir, 'home');
-  const workspaceDir = join(sandboxDir, 'workspace');
+  const workspaceOverrideRaw = (process.env.HAPPIER_STACK_SANDBOX_WORKSPACE_DIR ?? '').trim();
+  const workspaceOverrideExpanded = workspaceOverrideRaw ? expandHome(workspaceOverrideRaw) : '';
+  const workspaceOverride = workspaceOverrideExpanded
+    ? isAbsolute(workspaceOverrideExpanded)
+      ? workspaceOverrideExpanded
+      : resolve(sandboxDir, workspaceOverrideExpanded)
+    : '';
+  const workspaceDir = workspaceOverride || join(sandboxDir, 'workspace');
   const runtimeDir = join(sandboxDir, 'runtime');
   const storageDir = join(sandboxDir, 'storage');
 
@@ -193,17 +202,44 @@ function applySandboxDirIfRequested(argv) {
 
   process.env.HAPPIER_STACK_HOME_DIR = homeDir;
 
-  process.env.HAPPIER_STACK_WORKSPACE_DIR = workspaceDir;
+    process.env.HAPPIER_STACK_WORKSPACE_DIR = workspaceDir;
 
-  process.env.HAPPIER_STACK_RUNTIME_DIR = runtimeDir;
+    process.env.HAPPIER_STACK_RUNTIME_DIR = runtimeDir;
 
-  process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
+    process.env.HAPPIER_STACK_STORAGE_DIR = storageDir;
 
-  // Sandbox default: disallow global side effects unless explicitly opted in.
-  // This keeps sandbox runs fast, deterministic, and isolated.
-  if (!allowGlobal) {
-    // Network-y UX (background update checks) are not useful in a temporary sandbox.
-    process.env.HAPPIER_STACK_UPDATE_CHECK = '0';
+    // When sandboxing with a shared (non-temporary) workspace, keep package-manager caches stable
+    // across runs. This makes `yarn install` much faster and avoids re-downloading toolchains.
+    const pmCacheBaseRaw = (process.env.HAPPIER_STACK_PM_CACHE_BASE_DIR ?? '').trim();
+    const sandboxAbs = resolve(sandboxDir);
+    const wsAbs = resolve(workspaceDir);
+    const isSharedWorkspace = wsAbs !== sandboxAbs && !wsAbs.startsWith(sandboxAbs + '/');
+    if (!pmCacheBaseRaw && isSharedWorkspace) {
+      const base = basename(wsAbs) === 'workspace'
+        ? join(dirname(wsAbs), 'pm')
+        : join(wsAbs, '.hstack-cache', 'pm');
+      process.env.HAPPIER_STACK_PM_CACHE_BASE_DIR = base;
+    }
+
+    // When sandboxing with a shared workspace, keep Expo/Metro transform caches stable across runs.
+    // This dramatically speeds up repeated `expo start` for review-pr flows.
+    const expoTmpBaseRaw = (process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_BASE_DIR ?? '').trim();
+    if (!expoTmpBaseRaw && isSharedWorkspace) {
+      const base = basename(wsAbs) === 'workspace'
+        ? join(dirname(wsAbs), 'expo')
+        : join(wsAbs, '.hstack-cache', 'expo');
+      process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_BASE_DIR = base;
+    }
+    const expoTmpKeyRaw = (process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_KEY ?? '').trim();
+    if (!expoTmpKeyRaw && isSharedWorkspace) {
+      process.env.HAPPIER_STACK_EXPO_SHARED_TMPDIR_KEY = wsAbs;
+    }
+
+    // Sandbox default: disallow global side effects unless explicitly opted in.
+    // This keeps sandbox runs fast, deterministic, and isolated.
+    if (!allowGlobal) {
+      // Network-y UX (background update checks) are not useful in a temporary sandbox.
+      process.env.HAPPIER_STACK_UPDATE_CHECK = '0';
     process.env.HAPPIER_STACK_UPDATE_CHECK_INTERVAL_MS = '0';
     process.env.HAPPIER_STACK_UPDATE_NOTIFY_INTERVAL_MS = '0';
 
@@ -226,6 +262,30 @@ function maybeAutoUpdateNotice(cliRootDir, cmd) {
   });
 }
 
+async function maybeRefreshLocalBundledWorkspacePackages(cliRootDir) {
+  const cliRoot = String(cliRootDir ?? '').trim();
+  if (!cliRoot) return;
+  const disabled = String(process.env.HAPPIER_STACK_SYNC_BUNDLED_WORKSPACES ?? '').trim().toLowerCase();
+  if (disabled === '0' || disabled === 'false' || disabled === 'no') return;
+
+  const repoRoot = coerceHappyMonorepoRootFromPath(cliRoot);
+  if (!repoRoot) return;
+
+  const syncModulePath = resolveBundledWorkspaceSyncModulePath(cliRoot);
+  if (!syncModulePath) return;
+
+  const syncConfig = readBundledWorkspaceSyncConfig(cliRoot);
+  if (!syncConfig) return;
+
+  const { syncBundledWorkspacePackages } = await import(pathToFileURL(syncModulePath).href);
+
+  syncBundledWorkspacePackages({
+    repoRoot,
+    packages: syncConfig.packages,
+    hostApps: syncConfig.hostApps,
+  });
+}
+
 function usage() {
   return renderhstackRootHelp();
 }
@@ -244,7 +304,22 @@ function runNodeScript(cliRootDir, scriptRelPath, args) {
   process.exit(res.status ?? 1);
 }
 
-function main() {
+function hasJsonFlag(args) {
+  const argv = Array.isArray(args) ? args : [];
+  return argv.some((a) => a === '--json' || String(a).startsWith('--json='));
+}
+
+function maybeWarnDeprecatedSetup(cmd, rest) {
+  if (cmd !== 'setup') return;
+  if (hasJsonFlag(rest)) return;
+  // Keep this on stderr so stdout remains script-friendly (especially when piping output).
+  console.error('[hstack] DEPRECATED: `hstack setup` is deprecated and will be removed in a future release.');
+  console.error('[hstack] Use `hstack setup-from-source` for from-source setup (workspace + deps).');
+  console.error('[hstack] For managed self-hosting (service + rollback), use `hstack self-host install`.');
+  console.error('');
+}
+
+async function main() {
   const cliRootDir = getCliRootDir();
   const initialArgv = process.argv.slice(2);
   const argv0 = applyVerbosityIfRequested(initialArgv);
@@ -258,6 +333,7 @@ function main() {
   }
 
   maybeReexecToCliRoot(cliRootDir);
+  await maybeRefreshLocalBundledWorkspacePackages(cliRootDir);
 
   // If the user passed only flags (common via `npx --yes -p @happier-dev/stack hstack --help`),
   // treat it as root help rather than `help --help` (which would look like
@@ -335,6 +411,8 @@ function main() {
     process.exit(1);
   }
 
+  maybeWarnDeprecatedSetup(cmd, rest);
+
   if (resolved.kind === 'external') {
     const args = resolved.external?.argsFromRest ? resolved.external.argsFromRest(rest) : rest;
     const res = spawnSync(resolved.external.cmd, args, { stdio: 'inherit', env: process.env });
@@ -345,4 +423,8 @@ function main() {
   return runNodeScript(cliRootDir, resolved.scriptRelPath, args);
 }
 
-main();
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(message);
+  process.exit(1);
+});

package/docs/happy-development.md

@@ -6,13 +6,13 @@ Key principles:
 
 - Use **repo worktrees** under `<workspace>/{pr,local,tmp}/...`
 - Keep `<workspace>/main` as the stable checkout (treat it as read-only)
-- Use `<workspace>/dev` as the default dev checkout (created by `hstack setup --profile=dev`)
+- Use `<workspace>/dev` as the default dev checkout (created by `hstack setup-from-source --profile=dev`)
 - Run feature work in isolated **stacks** (ports + dirs + env file)
 
 Quickstart (dev profile):
 
 ```bash
-npx --yes -p @happier-dev/stack hstack setup --profile=dev
+npx --yes -p @happier-dev/stack hstack setup-from-source --profile=dev
 ```
 
 Common flows:

package/docs/isolated-linux-vm.md

@@ -12,34 +12,42 @@ This avoids Docker/container UX issues (browser opening, Expo networking, file w
 brew install lima
 ```
 
-### 1b) Automated E2E smoke test (optional)
+### 1b) Automated smoke test (optional)
 
-On your macOS host (this repo):
+On your macOS host (this repo, from `apps/stack/`):
 
 ```bash
-./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e
+./scripts/provision/macos-lima-hstack-smoke.sh happy-e2e
 ```
 
 What it validates (best-effort):
-- `hstack setup --profile=selfhost` in a fully isolated sandbox (no auth / tailscale / autostart / menubar)
+- `hstack setup-from-source --profile=selfhost` in a fully isolated sandbox (no auth / tailscale / autostart / menubar)
 - server health endpoint (`/health`)
 - UI is served by server-light (`/` returns HTML)
 - monorepo worktree creation (`hstack wt new ...`)
 
+If you want repeated runs with per-iteration logs and JSON metadata, use:
+
+```bash
+HSTACK_REPEAT_COUNT=5 ./scripts/provision/macos-lima-hstack-repeat-validation.sh happy-e2e
+```
+
+The report tree is written under `output/lima-validation-<timestamp>-<vm>/` by default.
+
 Notes:
 - This runs inside the VM (Linux) and uses `npx` by default.
-- You can pin the version under test: `HSTACK_VERSION=0.6.14 ./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e`.
+- You can pin the version under test: `HSTACK_VERSION=0.6.14 ./scripts/provision/macos-lima-hstack-smoke.sh happy-e2e`.
 - If you’re testing a fork, you can point the runner at your fork’s raw scripts:
-  `HSTACK_RAW_BASE=https://raw.githubusercontent.com/<owner>/<repo>/<ref>/apps/stack ./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e`.
+  `HSTACK_RAW_BASE=https://raw.githubusercontent.com/<owner>/<repo>/<ref>/apps/stack ./scripts/provision/macos-lima-hstack-smoke.sh happy-e2e`.
 - If you’re testing unpublished local changes, copy a packed tarball into the VM and run:
-  `HSTACK_TGZ=./happier-dev-stack-*.tgz /tmp/linux-ubuntu-e2e.sh`.
+  `HSTACK_TGZ=./happier-dev-stack-*.tgz /tmp/linux-ubuntu-hstack-smoke.sh`.
 
 ### 2) Create + configure a VM (recommended script)
 
-On your macOS host (this repo):
+On your macOS host (this repo, from `apps/stack/`):
 
 ```bash
-./scripts/provision/macos-lima-happy-vm.sh happy-test
+./scripts/provision/macos-lima-vm.sh happy-test
 ```
 
 This creates the VM if needed and configures **localhost port forwarding** for the port ranges used by our VM defaults.
@@ -49,7 +57,7 @@ It also sets a higher default VM memory size (to avoid Expo/Metro getting OOM-ki
 Override if needed:
 
 ```bash
-LIMA_MEMORY=12GiB ./scripts/provision/macos-lima-happy-vm.sh happy-test
+LIMA_MEMORY=12GiB ./scripts/provision/macos-lima-vm.sh happy-test
 ```
 
 Port ranges note:
@@ -131,9 +139,9 @@ limactl shell happy-pr
 Inside the VM:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/scripts/provision/linux-ubuntu-review-pr.sh -o /tmp/linux-ubuntu-review-pr.sh \
-  && chmod +x /tmp/linux-ubuntu-review-pr.sh \
-  && /tmp/linux-ubuntu-review-pr.sh
+curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/scripts/provision/linux-ubuntu-provision.sh -o /tmp/linux-ubuntu-provision.sh \
+  && chmod +x /tmp/linux-ubuntu-provision.sh \
+  && /tmp/linux-ubuntu-provision.sh --profile=happier
 ```
 
 ### 3b) (Optional) Run the hstack dev setup wizard
@@ -141,7 +149,7 @@ curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack
 If your goal is to **work on changes** (not just review a PR), you can run the dev profile:
 
 ```bash
-npx --yes -p @happier-dev/stack@latest hstack setup --profile=dev --bind=loopback
+npx --yes -p @happier-dev/stack@latest hstack setup-from-source --profile=dev --bind=loopback
 ```
 
 Notes:
@@ -233,7 +241,7 @@ Why these paths:
 - `~/.happier`: stack storage root (`~/.happier/stacks/<name>/...` env/state/data).
 - `~/.happy`: legacy pre-monorepo location that older migrations/import tooling may still reference.
 
-If you used `hstack setup --profile=dev` and picked a custom workspace directory (outside `~/.happier-stack/workspace`), delete that directory too.
+If you used `hstack setup-from-source --profile=dev` and picked a custom workspace directory (outside `~/.happier-stack/workspace`), delete that directory too.
 
 ---
 

package/docs/mobile-ios.md

@@ -21,7 +21,7 @@ see the “Using Happier from your phone” section in the main README.
 
 ## Shared dev-client app (install once)
 
-If you ran `hstack setup --profile=dev`, the setup wizard can optionally offer to install the dev-client for you.
+If you ran `hstack setup-from-source --profile=dev`, the setup wizard can optionally offer to install the dev-client for you.
 
 Install the dedicated hstack dev-client app on your iPhone (USB).
 
@@ -145,6 +145,8 @@ HAPPIER_STACK_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" hstack mobile
 
 Note: changing `HAPPIER_STACK_SERVER_URL` requires rebuilding/reinstalling the app you care about.
 
+Tip: mobile builds prefer `HAPPIER_PUBLIC_SERVER_URL` when it is set for the stack, and fall back to `HAPPIER_STACK_SERVER_URL`. Use `HAPPIER_PUBLIC_SERVER_URL` for the canonical/share URL your phone can reach, and reserve `HAPPIER_STACK_SERVER_URL` for stack-specific overrides when needed.
+
 Important:
 
 - For **non-main stacks**, `HAPPIER_STACK_SERVER_URL` is only respected if it’s set **in that stack’s env file**

package/docs/paths-and-env.md

@@ -32,7 +32,7 @@ hstack where
   - This is the **storage workspace for the Happier monorepo checkout + worktrees** used by hstack.
   - It typically contains:
     - `<workspace>/main` (stable monorepo checkout)
-    - `<workspace>/dev` (dev monorepo checkout; created by `hstack setup --profile=dev`)
+    - `<workspace>/dev` (dev monorepo checkout; created by `hstack setup-from-source --profile=dev`)
     - `<workspace>/pr/...` (PR worktrees)
     - `<workspace>/local/<owner>/...` (local worktrees)
     - `<workspace>/tmp/<owner>/...` (temporary worktrees)

package/docs/remote-access.md

@@ -23,7 +23,9 @@ Tip: on iOS, you can “Add to Home Screen” from Safari to use it like an app.
 
 ## Automation
 
-If Serve is already configured, `hstack start` will automatically prefer the `https://*.ts.net` URL for “public” links unless you explicitly set `HAPPIER_STACK_SERVER_URL`.
+If Serve is already configured, `hstack start` will automatically prefer the `https://*.ts.net` URL for canonical/share links unless you explicitly set `HAPPIER_STACK_SERVER_URL`.
+
+Tip: for self-hosted servers, also set `HAPPIER_PUBLIC_SERVER_URL` (usually to the same `https://*.ts.net` URL). That value is advertised by the server via `GET /v1/features` and is what clients embed in QR/deep links.
 
 You can also ask hstack to enable Serve automatically at boot:
 
@@ -33,7 +35,8 @@ HAPPIER_STACK_TAILSCALE_SERVE=1 hstack start
 
 Useful knobs:
 - `HAPPIER_STACK_TAILSCALE_WAIT_MS`
-- `HAPPIER_STACK_TAILSCALE_BIN`
+- `HAPPIER_TAILSCALE_BIN` (preferred unified override)
+- `HAPPIER_STACK_TAILSCALE_BIN` (legacy stack-specific alias)
 
 ## Using the native Happier mobile app (optional)
 

package/docs/server-flavors.md

@@ -9,7 +9,7 @@ Both flavors use the **same server codebase** (the monorepo server package, typi
 ### `happier-server-light` (recommended default)
 
 - **No Docker required**
-- Uses **embedded Postgres via PGlite** (“PG_Light”) stored under the stack directory (per-stack isolation)
+- Uses **SQLite by default** (stack-local file), with optional embedded Postgres via PGlite
 - Stores local public files under the stack directory
 - Best choice for a stable “main” stack and quick local installs
 
@@ -18,6 +18,7 @@ Light stacks are isolated by default:
 ```
 ~/.happier/stacks/<stack>/server-light/files
 ~/.happier/stacks/<stack>/server-light/pglite
+~/.happier/stacks/<stack>/server-light/happier-server-light.sqlite
 ```
 
 Key env vars (stored in the stack env file):
@@ -65,10 +66,10 @@ For a “one URL” UX (especially with Tailscale), hstack starts a lightweight
 
 This means `hstack start --server=happier-server` can still work end-to-end without requiring AWS S3 or a separate nginx setup.
 
-## Migrating between flavors (PG_Light ⇢ Postgres)
+## Migrating between flavors (light ⇢ full)
 
 hstack includes an **experimental** migration helper that can copy core chat data from a
-`happier-server-light` stack (embedded PGlite) into a `happier-server` stack (Docker Postgres):
+`happier-server-light` stack into a `happier-server` stack (Docker Postgres):
 
 ```bash
 hstack migrate light-to-server --from-stack=main --to-stack=full1
@@ -90,7 +91,7 @@ Notes:
 - **`hstack dev`** is for rapid iteration:
   - for `happier-server`: hstack runs `prisma migrate deploy` by default (configurable via `HAPPIER_STACK_PRISMA_MIGRATE`).
   - for `happier-server-light`:
-    - hstack runs the server package’s `migrate:light:deploy` script, which applies `prisma migrate deploy` against the **embedded PGlite DB** using the standard Postgres schema (`prisma/schema.prisma`).
+    - hstack runs the server package’s `migrate:light:deploy` script, which applies provider-specific light migrations (SQLite by default, or PGlite when configured).
 
 Important: for a given run (`hstack start` / `hstack dev`) you choose **one** flavor.
 
@@ -143,5 +144,4 @@ There are two separate concepts:
 
 ## SQLite note
 
-SQLite is **not** used by `happier-server-light` today (it is PG_Light via embedded PGlite). SQLite may be reintroduced later as an additional light flavor, but it is not part of the current default stack.
-
+SQLite is the default DB for `happier-server-light`. You can opt into embedded Postgres (PGlite) by setting `HAPPIER_DB_PROVIDER=pglite` in the stack env.

package/docs/stacks.md

@@ -174,7 +174,8 @@ These commands run with the stack env file applied:
 
 Global/non-stack commands:
 
-- `hstack setup` (recommended; installs shims/runtime and bootstraps the monorepo)
+- `hstack setup-from-source` (recommended; installs shims/runtime and bootstraps the monorepo)
+  - Deprecated alias: `hstack setup`
 - (advanced) `hstack init` (plumbing: shims/runtime/pointer env)
 - (advanced) `hstack bootstrap` (clone/install monorepo + deps)
 

package/docs/tauri.md

@@ -58,3 +58,4 @@ Requirements:
 - `HAPPIER_STACK_TAURI_DEBUG=0` (build release-like without devtools)
 - `HAPPIER_STACK_TAURI_SERVER_URL` (force the embedded API URL)
 - `HAPPIER_STACK_TAURI_PREFER_TAILSCALE=0` (disable Tailscale detection; always embed `127.0.0.1`)
+- `HAPPIER_STACK_TAURI_CREATE_UPDATER_ARTIFACTS=1` (force generating updater artifacts; requires `TAURI_SIGNING_PRIVATE_KEY` — otherwise it defaults to off)

package/docs/worktrees-and-forks.md

@@ -22,7 +22,7 @@ hstack is **monorepo-only**: UI/CLI/server all live in the same Happier git repo
 Default paths (see `hstack where` for your actual values):
 
 - Stable checkout: `<workspace>/main`
-- Dev checkout: `<workspace>/dev` (created by `hstack setup --profile=dev`)
+- Dev checkout: `<workspace>/dev` (created by `hstack setup-from-source --profile=dev`)
 - Worktrees:
   - PRs: `<workspace>/pr/...`
   - locals: `<workspace>/local/<owner>/...`

package/extras/swiftbar/hstack.5s.sh

@@ -96,10 +96,11 @@ source "$LIB_DIR/render.sh"
 # Menu
 # ============================================================================
 
+PRIMARY_STACK_RAW="${HAPPIER_STACK_SWIFTBAR_PRIMARY_STACK:-${HAPPIER_STACK_STACK:-main}}"
+PRIMARY_STACK="${PRIMARY_STACK_RAW:-main}"
+
 hstack_BIN="$(resolve_hstack_bin)"
 hstack_TERM="$hstack_ROOT_DIR/extras/swiftbar/hstack-term.sh"
-MAIN_PORT="$(resolve_main_port)"
-MAIN_SERVER_COMPONENT="$(resolve_main_server_component)"
 TAILSCALE_URL="$(get_tailscale_url)"
 if swiftbar_is_sandboxed; then
   # Never probe Tailscale (global machine state) when sandboxing.
@@ -111,15 +112,26 @@ MENUBAR_MODE="$(resolve_menubar_mode)"
 ensure_launchctl_cache
 
 if [[ -z "$MAIN_ENV_FILE" ]]; then
-  MAIN_ENV_FILE="$(resolve_stack_env_file main)"
+  MAIN_ENV_FILE="$(resolve_stack_env_file "$PRIMARY_STACK")"
+fi
+if [[ -z "${HAPPIER_STACK_ENV_FILE:-}" ]] && [[ -n "$MAIN_ENV_FILE" ]]; then
+  export HAPPIER_STACK_ENV_FILE="$MAIN_ENV_FILE"
+fi
+MAIN_SERVER_COMPONENT="$(resolve_main_server_component)"
+if [[ "$PRIMARY_STACK" == "main" ]]; then
+  MAIN_PORT="$(resolve_main_port)"
+else
+  MAIN_PORT="$(resolve_stack_server_port "$PRIMARY_STACK" "$MAIN_ENV_FILE")"
 fi
-HAPPIER_HOME_DIR="$(resolve_stack_base_dir main "$MAIN_ENV_FILE")"
-CLI_HOME_DIR="$(resolve_stack_cli_home_dir main "$MAIN_ENV_FILE")"
+
+HAPPIER_HOME_DIR="$(resolve_stack_base_dir "$PRIMARY_STACK" "$MAIN_ENV_FILE")"
+CLI_HOME_DIR="$(resolve_stack_cli_home_dir "$PRIMARY_STACK" "$MAIN_ENV_FILE")"
 LOGS_DIR="$HAPPIER_HOME_DIR/logs"
-MAIN_LABEL="$(resolve_stack_label main)"
+MAIN_LABEL="$(resolve_stack_label "$PRIMARY_STACK")"
 
 MAIN_COLLECT="$(collect_stack_status "$MAIN_PORT" "$CLI_HOME_DIR" "$MAIN_LABEL" "$HAPPIER_HOME_DIR")"
 IFS=$'\t' read -r MAIN_LEVEL MAIN_SERVER_STATUS MAIN_SERVER_PID MAIN_SERVER_METRICS MAIN_DAEMON_STATUS MAIN_DAEMON_PID MAIN_DAEMON_METRICS MAIN_DAEMON_UPTIME MAIN_LAST_HEARTBEAT MAIN_LAUNCHAGENT_STATUS MAIN_AUTOSTART_PID MAIN_AUTOSTART_METRICS <<<"$MAIN_COLLECT"
+MAIN_DAEMON_STATE_FILE="$(resolve_preferred_daemon_state_pair "$CLI_HOME_DIR" | cut -d'|' -f1)"
 for v in MAIN_SERVER_PID MAIN_SERVER_METRICS MAIN_DAEMON_PID MAIN_DAEMON_METRICS MAIN_DAEMON_UPTIME MAIN_LAST_HEARTBEAT MAIN_AUTOSTART_PID MAIN_AUTOSTART_METRICS; do
   if [[ "${!v}" == "-" ]]; then
     printf -v "$v" '%s' ""
@@ -160,14 +172,25 @@ fi
 echo "---"
 
 # Main stack (inline)
-echo "Main stack"
+if [[ "$PRIMARY_STACK" == "main" ]]; then
+  # If the main env file points at a named stack (common in wrapper installs),
+  # render the concrete stack name to avoid ambiguity.
+  DECLARED_MAIN_STACK_NAME="$(dotenv_get "$MAIN_ENV_FILE" "HAPPIER_STACK_STACK")"
+  if [[ -n "$DECLARED_MAIN_STACK_NAME" && "$DECLARED_MAIN_STACK_NAME" != "main" ]]; then
+    echo "Stack: $DECLARED_MAIN_STACK_NAME"
+  else
+    echo "Main stack"
+  fi
+else
+  echo "Stack: $PRIMARY_STACK"
+fi
 echo "---"
 export MAIN_LEVEL="$MAIN_LEVEL"
-render_stack_info "" "main" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$HAPPIER_HOME_DIR" "$CLI_HOME_DIR" "$MAIN_LABEL" "$MAIN_ENV_FILE" "$TAILSCALE_URL" "$MAIN_SERVER_METRICS" "$MAIN_DAEMON_METRICS" "$MAIN_AUTOSTART_METRICS"
-render_component_server "" "main" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$MAIN_SERVER_STATUS" "$MAIN_SERVER_PID" "$MAIN_SERVER_METRICS" "$TAILSCALE_URL" "$MAIN_LABEL"
-render_component_daemon "" "$MAIN_DAEMON_STATUS" "$MAIN_DAEMON_PID" "$MAIN_DAEMON_METRICS" "$MAIN_DAEMON_UPTIME" "$MAIN_LAST_HEARTBEAT" "$CLI_HOME_DIR/daemon.state.json" "main"
-render_component_autostart "" "main" "$MAIN_LABEL" "$MAIN_LAUNCHAGENT_STATUS" "$MAIN_AUTOSTART_PID" "$MAIN_AUTOSTART_METRICS" "$LOGS_DIR"
-render_component_tailscale "" "main" "$TAILSCALE_URL"
+render_stack_info "" "$PRIMARY_STACK" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$HAPPIER_HOME_DIR" "$CLI_HOME_DIR" "$MAIN_LABEL" "$MAIN_ENV_FILE" "$TAILSCALE_URL" "$MAIN_SERVER_METRICS" "$MAIN_DAEMON_METRICS" "$MAIN_AUTOSTART_METRICS"
+render_component_server "" "$PRIMARY_STACK" "$MAIN_PORT" "$MAIN_SERVER_COMPONENT" "$MAIN_SERVER_STATUS" "$MAIN_SERVER_PID" "$MAIN_SERVER_METRICS" "$TAILSCALE_URL" "$MAIN_LABEL"
+render_component_daemon "" "$MAIN_DAEMON_STATUS" "$MAIN_DAEMON_PID" "$MAIN_DAEMON_METRICS" "$MAIN_DAEMON_UPTIME" "$MAIN_LAST_HEARTBEAT" "$MAIN_DAEMON_STATE_FILE" "$PRIMARY_STACK"
+render_component_autostart "" "$PRIMARY_STACK" "$MAIN_LABEL" "$MAIN_LAUNCHAGENT_STATUS" "$MAIN_AUTOSTART_PID" "$MAIN_AUTOSTART_METRICS" "$LOGS_DIR"
+render_component_tailscale "" "$PRIMARY_STACK" "$TAILSCALE_URL"
 
 echo "---"
 if [[ "$MENUBAR_MODE" == "selfhost" ]]; then
@@ -229,6 +252,7 @@ else
 
       COLLECT="$(collect_stack_status "$port" "$cli_home_dir" "$label" "$base_dir")"
       IFS=$'\t' read -r LEVEL SERVER_STATUS SERVER_PID SERVER_METRICS DAEMON_STATUS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT LAUNCHAGENT_STATUS AUTOSTART_PID AUTOSTART_METRICS <<<"$COLLECT"
+      DAEMON_STATE_FILE="$(resolve_preferred_daemon_state_pair "$cli_home_dir" | cut -d'|' -f1)"
       for v in SERVER_PID SERVER_METRICS DAEMON_PID DAEMON_METRICS DAEMON_UPTIME LAST_HEARTBEAT AUTOSTART_PID AUTOSTART_METRICS; do
         if [[ "${!v}" == "-" ]]; then
           printf -v "$v" '%s' ""
@@ -239,7 +263,7 @@ else
       export STACK_LEVEL="$LEVEL"
       render_stack_info "${STACKS_PREFIX}--" "$s" "$port" "$server_component" "$base_dir" "$cli_home_dir" "$label" "$env_file" "" "$SERVER_METRICS" "$DAEMON_METRICS" "$AUTOSTART_METRICS"
       render_component_server "${STACKS_PREFIX}--" "$s" "$port" "$server_component" "$SERVER_STATUS" "$SERVER_PID" "$SERVER_METRICS" "" "$label"
-      render_component_daemon "${STACKS_PREFIX}--" "$DAEMON_STATUS" "$DAEMON_PID" "$DAEMON_METRICS" "$DAEMON_UPTIME" "$LAST_HEARTBEAT" "$cli_home_dir/daemon.state.json" "$s"
+      render_component_daemon "${STACKS_PREFIX}--" "$DAEMON_STATUS" "$DAEMON_PID" "$DAEMON_METRICS" "$DAEMON_UPTIME" "$LAST_HEARTBEAT" "$DAEMON_STATE_FILE" "$s"
       render_component_autostart "${STACKS_PREFIX}--" "$s" "$label" "$LAUNCHAGENT_STATUS" "$AUTOSTART_PID" "$AUTOSTART_METRICS" "$base_dir/logs"
       render_component_tailscale "${STACKS_PREFIX}--" "$s" ""
       render_components_menu "${STACKS_PREFIX}--" "stack" "$s" "$env_file"
@@ -249,7 +273,7 @@ else
   fi
 
   echo "---"
-  render_components_menu "" "main" "main" "$MAIN_ENV_FILE"
+  render_components_menu "" "main" "$PRIMARY_STACK" "$MAIN_ENV_FILE"
 
   echo "Worktrees | sfimage=arrow.triangle.branch"
   if [[ -z "$hstack_BIN" ]]; then

package/extras/swiftbar/install.sh

@@ -169,6 +169,8 @@ if [[ "$SHOULD_INSTALL" == "1" ]]; then
         WORKSPACE_DIR_VAL="${HAPPIER_STACK_WORKSPACE_DIR:-}"
         RUNTIME_DIR_VAL="${HAPPIER_STACK_RUNTIME_DIR:-}"
         STORAGE_DIR_VAL="${HAPPIER_STACK_STORAGE_DIR:-}"
+        PRIMARY_STACK_VAL="${HAPPIER_STACK_SWIFTBAR_PRIMARY_STACK:-${HAPPIER_STACK_STACK:-}}"
+        PRIMARY_ENV_FILE_VAL="${HAPPIER_STACK_SWIFTBAR_PRIMARY_ENV_FILE:-${HAPPIER_STACK_ENV_FILE:-}}"
 
         if [[ -n "$SANDBOX_DIR_VAL" ]]; then
           [[ -z "$WORKSPACE_DIR_VAL" ]] && WORKSPACE_DIR_VAL="${SANDBOX_DIR_VAL%/}/workspace"
@@ -181,6 +183,8 @@ if [[ "$SHOULD_INSTALL" == "1" ]]; then
         WORKSPACE_DIR_ESC="$(escape_single_quotes "$WORKSPACE_DIR_VAL")"
         RUNTIME_DIR_ESC="$(escape_single_quotes "$RUNTIME_DIR_VAL")"
         STORAGE_DIR_ESC="$(escape_single_quotes "$STORAGE_DIR_VAL")"
+        PRIMARY_STACK_ESC="$(escape_single_quotes "$PRIMARY_STACK_VAL")"
+        PRIMARY_ENV_FILE_ESC="$(escape_single_quotes "$PRIMARY_ENV_FILE_VAL")"
         SRC_ESC="$(escape_single_quotes "$PLUGIN_SOURCE")"
         BASENAME_ESC="$(escape_single_quotes "$PLUGIN_BASENAME")"
 
@@ -190,6 +194,14 @@ set -euo pipefail
 export HAPPIER_STACK_HOME_DIR='$HOME_DIR_ESC'
 export HAPPIER_STACK_CANONICAL_HOME_DIR='$CANONICAL_DIR_ESC'
 export HAPPIER_STACK_SWIFTBAR_PLUGIN_BASENAME='$BASENAME_ESC'
+if [[ -n '$PRIMARY_STACK_ESC' ]]; then
+  export HAPPIER_STACK_SWIFTBAR_PRIMARY_STACK='$PRIMARY_STACK_ESC'
+  export HAPPIER_STACK_STACK='$PRIMARY_STACK_ESC'
+fi
+if [[ -n '$PRIMARY_ENV_FILE_ESC' ]]; then
+  export HAPPIER_STACK_SWIFTBAR_PRIMARY_ENV_FILE='$PRIMARY_ENV_FILE_ESC'
+  export HAPPIER_STACK_ENV_FILE='$PRIMARY_ENV_FILE_ESC'
+fi
 if [[ -n '$SANDBOX_DIR_ESC' ]]; then
   export HAPPIER_STACK_SANDBOX_DIR='$SANDBOX_DIR_ESC'
 fi