server

作用

apps/server 是 Tutti 的项目 host service。

它负责：

• tutti launch 后的项目绑定、恢复和接管入口
• Fastify API、SSE、packaged static Web 产物服务和 server 生命周期
• SQLite store、migrations、repository 与协作真相读写
• control-plane、scheduler、procedure-engine、run-engine、workspace-ops 与 OpenAI provider 接入
• host 到 Relay 的连接与工作区加入协作

结构

• src/：server 代码根目录。
• prompts/：大模型 prompt、指令模板和 Codex 执行模板的统一保存目录。
• migrations/：本地 tutti.sqlite 的 SQL migrations。
• cli-package.mjs：生成临时 staging @xfey/tutti package artifact 的脚本。
• prepare-package-assets.mjs：把 Web build output 和内部 runtime package 复制到 staging package 所需位置。
• pack-dry-run.mjs：构建 staging package 并执行 npm pack --dry-run --json 文件列表校验。
• smoke-packed-cli.mjs：安装并验证 packed CLI tarball 的本地 smoke，包括 CLI help / version、runtime deps 和 QR dependency。

当前状态

• 已具备 Fastify host shell、后台 host manager CLI 套件、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层和 OpenAI / Codex provider 接入。
• Host server 支持在显式 webStatic.root 或 packaged web/ 存在时服务 Web 静态产物；/api/*、SSE、health 和 host-local control 不被 SPA fallback 吞掉。
• Root pack:dry-run 会先清理 build output、重新构建，再复制 apps/web/dist 到 package-local web/，生成临时 staging @xfey/tutti artifact，并校验 npm pack 文件列表包含 CLI、migrations、prompts、Web index、bundled @tutti/shared / @tutti/relay-client 以及它们的外部 runtime dependencies，同时排除源码、source map、日志、SQLite、.env、.tutti-dev 与测试产物。
• Root smoke:packed-cli 同样从干净 build output 生成 staging @xfey/tutti tarball、在临时目录安装，并验证 SQLite native binding、tutti --help / tutti launch --help / tutti --version、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 @openai/codex binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
• prompts/ 是所有模型-facing prompt、指令模板和 Codex 执行模板的统一落点；长 prompt 不内联在 TypeScript 中。
• Host Project API 只信任 Relay tunnel metadata 注入的 relay_session_context；direct loopback 缺少可信 context 时不作为浏览器工作区入口。
• 详细模块落点见 src/README.md；logger redaction、command idempotency、schema、provider 与 Codex 边界以 docs/system/ 对应 canonical 文档为准。

约定

• 默认运行在 macOS / Linux host 上。
• 项目 truth 只在 host server 与正式 repo 中，不进入 Relay。
• SQLite driver 默认使用 better-sqlite3，只有 store adapter 可以直接依赖 driver。
• 真实仓库任务的正式 adapter 使用 Codex app-server；普通结构化判断走 OpenAI SDK。两者共享同一份 OpenAI provider config。
• 所有模型-facing prompt 和长指令模板都必须放在 prompts/，不得在 TypeScript 中内联长 prompt；模板规范见 ../../docs/system/prompt-template-management.md。
• 不实现绕过 Relay 的单人工作区路径。
• packaged / production tutti launch 默认连接 https://tutti.now；TUTTI_RELAY_URL 可覆盖 Relay URL，本地开发 dev runner 默认使用 http://127.0.0.1:4370。
• host 注册使用 machine-local host_registration_secret；该 secret 明文只可写入受限权限的 machine-local secret store，不写入目标项目 repo、Git local config 项目身份、SQLite 协作真相或日志，binding.json 只保存引用。
• Relay registration 成功后只把 relay_project_ref 写回 machine-local binding；join URL 只在 host 本机终端或当前 host-local control 内存状态中展示，不写入 binding、runtime endpoint、SQLite 协作真相或日志。
• 普通 tutti launch 默认后台运行 host，CLI 完成页展示 join URL 后直接退出；tutti launch --foreground 保留前台诊断模式。Host HTTP request log 与 Control Plane / Run Pipeline runtime log 写入 TUTTI_HOME/logs/host.log，不写入目标项目 repo 或常规 CLI stdout。
• Reference 和 Skills 上传的最终写入由 Host Project API 完成；Host 只通过 Relay host-control resolve 获取短期 R2 URL 下载 staged object，不接收浏览器 base64 文件正文，也不持久化 presigned URL。
• Host Project API command 的 browser session context 只信任 Relay tunnel metadata 中的 relay_session_context；route handler 不读取浏览器身份 header，也不接受 payload 内身份字段。
• Fastify request log、debug log、SSE payload、activity event 和 run result 都必须经过 redaction，不得泄露 provider secret、host registration secret、host connection token、join token、cookie、host 绝对路径或 run workspace path。
• Repo Viewer path policy 已以可测试 helper 落地并接入 Phase 6 Viewer / Reference Files API；Phase 7 checks executor 已以 safe npm script discovery、结构化 spawn、timeout、stdout / stderr redaction 与 no-shell 执行为首批命令安全边界。
• 当前源码 package root 仍是 apps/server；对外 npm 名由 staging artifact 使用 @xfey/tutti，internal workspace dependency bundling、对应外部 runtime dependency bundling 和 packed CLI install smoke 已接通。