Sokosumi Monorepo

Sokosumi is a marketplace platform. This monorepo is the web app, the Core API, native Apple apps, the developer CLI, and shared packages.

Project Structure

sokosumi/
├── apps/
│   ├── web/         # Next.js 16 web app (TypeScript, Tailwind, Shadcn UI)
│   ├── core/        # Hono API — owns all Postgres/Prisma access
│   ├── cmo/         # Next.js 16 CMO app at app.cmo.xyz (Sign in with Sokosumi; no database)
│   ├── apple/       # Native macOS + iOS — Xcode (outside turbo and Biome)
│   └── cli/         # Developer CLI — Ink TUI and headless commands (SPEC + VISION)
├── packages/
│   ├── database/    # @sokosumi/database — Prisma schema, client, helpers
│   ├── core-client/ # @sokosumi/core-client — generated TypeScript client for Core's /v1 API
│   ├── masumi/      # @sokosumi/masumi — protocol clients, hash, schemas
│   ├── utils/       # @sokosumi/utils — client-safe helpers
│   ├── net/         # @sokosumi/net — SSRF-safe fetch and outbound webhook transport
│   ├── email/       # @sokosumi/email — renderers and locales
│   ├── ai-provider/ # @sokosumi/ai-provider — Sokosumi AI SDK provider
│   └── soko-bot/    # @sokosumi/soko-bot — Soko Bot contracts (loop runs in per-bot Vercel Sandboxes; Core is the control plane)
├── docs/            # Agent, domain, coworker, and design docs
├── scripts/         # local-env, cloud-agent-db, CI helpers
├── skills/          # First-party agent skill sources
├── biome.jsonc      # Root Biome configuration
├── turbo.json       # Turborepo task graph
├── package.json     # Monorepo root config
└── pnpm-workspace.yaml

• apps/web/: User-facing web application (Next.js 16, React 19.3, Tailwind CSS, Shadcn UI, next-intl). Reaches data only through the Core API — it does not use Prisma.
• apps/core/: Hono API on Node.js. All database reads and writes live here.
• apps/cmo/: CMO at app.cmo.xyz (Next.js 16). A separate product that signs in with Sokosumi through Core's OAuth provider; it has no database.

Getting Started

Prerequisites

• Node.js 24.x
• pnpm 12 (monorepo package manager; pin is packageManager in the root package.json)

Clone and Install

git clone https://github.com/masumi-network/sokosumi.git
cd sokosumi
pnpm install

Setup Environment

pnpm env:bootstrap

Copies apps/web/.env.example and apps/core/.env.example to .env when missing, replaces Zod-breaking placeholders, and comments production BETTER_AUTH_COOKIE_DOMAIN in .env (portless injects sokosumi.localhost at runtime). Grok copies (.git/grok-worktree-source) and linked git worktrees reuse the primary checkout .env so BETTER_AUTH_SECRET / DATABASE_URL match — unless the worktree already has a unique secret.

One-time on a machine, start the portless HTTPS proxy (port 443, may prompt for sudo) and trust the local CA if portless doctor says it is untrusted:

pnpm exec portless trust    # once, if CA is not trusted
pnpm portless:proxy         # HTTPS on 443

Development

Named local URLs (worktree-safe). Linked worktrees get a branch prefix (https://<branch>.web.sokosumi.localhost):

pnpm portless:dev     # web + core
pnpm portless:web     # web only (still prints and injects both named URLs)
pnpm portless:core    # core only
pnpm portless:cmo     # CMO only

• Web: https://web.sokosumi.localhost (pnpm portless:url web)
• Core: https://core.sokosumi.localhost (pnpm portless:url core) — OpenAPI at /v1/openapi.json
• CMO: https://cmo.sokosumi.localhost (pnpm portless:url cmo)

Grok/Cursor copies under .grok/worktrees/ are not git worktrees, so portless cannot prefix the branch. pnpm portless:dev prefixes the directory basename (https://3877.web.sokosumi.localhost) and uses --force so a leftover process cannot keep Core from starting. Restarting kills the previous process for that name. Linked git worktree add checkouts (including .worktrees/) keep Portless's branch prefix only — do not stack a second basename. Always print URLs with pnpm portless:url web / core (bare portless get web.sokosumi skips the Grok basename).

portless:web and portless:core still wire WEB_APP_BASE_URL / BETTER_AUTH_URL / CORE_APP_BASE_URL from those named URLs; portless:cmo passes none of them. Start the other named host separately; classic :3000 / :8787 is not in play.

Classic single-checkout ports still work:

pnpm web:dev    # http://localhost:3000
pnpm core:dev   # http://localhost:8787

Agents should use verify-sokosumi launch (see AGENTS.md) so .env, the 443 proxy, and named URLs stay in sync.

Other available scripts:

• pnpm build — TypeScript build
• pnpm check — Biome check
• pnpm typecheck — workspace typecheck
• pnpm format — Write Biome formatting (not the gate)

The husky hook runs pnpm precommit (pnpm check && pnpm typecheck). CI gates the same pair as Biome and Typecheck.

Testing

• The monorepo uses Vitest for unit tests.
• Name tests *.test.ts(x) and place them next to the source they cover (foo.test.ts beside foo.ts). Use __tests__/ only when a test does not map 1:1 to a single source file.
• Run all workspace tests from the repo root with pnpm test.
• Run a single workspace with pnpm --filter web test, pnpm --filter core test, or pnpm --filter @sokosumi/<package> test.

Deployment

• Production: A push to main production-deploys web and core on both mainnet and preprod, and CMO on mainnet, through Vercel Git (git.deploymentEnabled allows main only). Each project skips a push that changed neither its app nor a workspace package it depends on: ignoreCommand runs scripts/ci/vercel-ignore.mjs, which asks turbo query affected. Keep the Vercel project setting "Skip deployments when there are no changes to the root directory or its dependencies" off; it adds a Skipped row per project to every PR's Vercel comment. There is no GitHub Actions or GitHub Release production path.
• Production redeploys: The ignore step always builds the last successfully deployed commit. To force a build of an older or previously canceled production deployment, uncheck Use project's Ignore Build Step in Vercel's Redeploy dialog; the SHA comparison cannot distinguish that redeploy from its original push.
• Preview: Only a comment from someone with repository write access on an open PR can deploy. On a PR from a fork, the comment must also name the full 40-character head commit SHA (/deploy preprod <sha>): the commenter approves that reviewed commit, which then builds with preview secrets and a Neon copy of production data. A different or missing SHA is refused, and later pushes to the fork never deploy or renew on their own. Vercel does not comment on a fork PR, so after a successful deploy the workflow posts each project's branch-alias URL, state, and approved SHA in one comment, edited in place on later deploys. /deploy shows help; /deploy mainnet, /deploy preprod, and /deploy all select networks. Mainnet also deploys CMO, which has no preprod project and signs in against the PR's mainnet Core preview. Opening, updating, or reopening a PR creates nothing. Commands must start the first line. Docs-only changes are skipped.
• Preview database: Actions creates or reuses preview/gh-<repo-id>-pr-<number> in each selected network's Neon project, branching from its default production branch. It writes pooled DATABASE_URL and direct DATABASE_URL_UNPOOLED as encrypted, Git-branch-scoped Preview variables on Core only. Both build and runtime receive them. Redeployment preserves preview data and renews its 24-hour expiry. Each new commit to the PR also renews existing preview databases for 24 hours, without deploying or creating databases. Fork PRs get neither renewal nor a variable scoped to their fork branch. Vercel refused variables scoped to , so each approved points here at the approved SHA, and the preview builds and scopes its variables to that branch. GitHub starts no workflow run for that push ( writes it), and later fork pushes never move it. A fork PR that changes a Vercel config file () gets no preview: Vercel reads it from that branch. is reserved; refuses a same-repo PR from it. Their database expires 24 hours after the last approved . Expiry deletes preview-only data; recreates an expired database from its parent.

Contributing

• We use GitHub Flow for branching and pull requests.
• Follow Conventional Commits for commit messages and PR titles.
• See code style and contribution guidelines in the respective package folders.

License

This project is licensed under the MIT License