Compile the server into dist/, so 'jevloop serve' works from the package

serve was the one subcommand that did not work from an installed package:
it ran the TypeScript at the package root, and Node refuses to strip types
under node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING -- the trap
docs/CODE-STYLE.md 8.8 already records). It printed a clone command
instead, which is honest but is not a harness.

server.ts moves into src/ so tsc emits dist/server.js beside dist/cli.js:

- ROOT is no longer 'the directory this file is in'. web/ and DECISION.md
  live at the package root and belong to neither src/ nor dist/, so ROOT
  is now the nearest directory above us that has a package.json. Both
  locations resolve to the package root; before, a compiled copy would
  have looked for dist/web.
- Two imports (backends, env) were direct L6 -> L6, which section 11
  forbids. They go through the facade now, the way cli.ts already does.
- serve() prefers dist/server.js and falls back to src/server.ts, so the
  installed package and a clone both work.

Verified by packing and installing into an empty directory: npx jevloop
serve starts from node_modules, GET / and GET /app.js return 200, and
GET /api/spec returns the English headline. run and spec were already
working from the package.

server.ts is over the 300-line rule and says why it cannot be split in its
module JSDoc -- the route table is one thing and the halves that would
grow (sessions, workspaces, directory browsing) are already their own
files. That is the shape the rule asks for; the baseline stays empty.

Also adds an npm run serve script for working from a clone, drops
server.ts from package.json files (dist carries it now) and from ROOTS in
check.ts (src/** covers it), and registers server at L6.

Author: Xubqpanda

package.json

@@ -11,6 +11,7 @@
     "build": "tsc -p tsconfig.build.json",
     "prepare": "npm run build",
     "demo": "node --experimental-strip-types examples/demo.ts",
+    "serve": "node --experimental-strip-types src/server.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --experimental-strip-types --test \"tests/*.test.ts\"",
     "check": "node --experimental-strip-types scripts/check.ts",
@@ -40,7 +41,6 @@
   "files": [
     "dist",
     "src",
-    "server.ts",
     "web",
     "README.md",
     "LICENSE",

scripts/check.ts

@@ -47,7 +47,7 @@ interface Violation {
   detail: string
 }
 
-const ROOTS = ['src/**/*.ts', 'examples/**/*.ts', 'tests/**/*.ts', 'scripts/**/*.ts', 'bench/**/*.ts', 'server.ts']
+const ROOTS = ['src/**/*.ts', 'examples/**/*.ts', 'tests/**/*.ts', 'scripts/**/*.ts', 'bench/**/*.ts']
 
 /**
  * `dir` 下的全部 TS 文件，**含子目录**。
@@ -299,8 +299,12 @@ const LAYER: Record<string, number> = {
   backends: 6,
   env: 6,
   // 命令行入口。它组合判定、生成、工具三条缝并把它们接到 argv 上，
-  // 所以和 `backends` 同层。`server.ts` 是同一类东西，但它在包根、不在 `src/`。
+  // 所以和 `backends` 同层。
   cli: 6,
+  // 开发服务器。它组合的和 `cli` 是同一批东西，只是接到 HTTP 上而不是 argv 上。
+  // 放在 `src/` 里（而不是包根）是为了让它进 `dist/` —— 见 `cli.ts` 的 `serve`：
+  // Node 拒绝给 `node_modules` 下的文件剥离类型，所以包根那份 TS 装出来跑不了。
+  server: 6,
 }
 
 /** 层号 → 一句话，报错时要说清两边各是什么 */

src/cli.ts

@@ -22,7 +22,7 @@
 
 import { spawn } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
-import { dirname, join, resolve, sep } from 'node:path'
+import { dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import { USAGE, parseArgv } from './cli-args.ts'
@@ -127,36 +127,35 @@ async function runTask(task: string, options: Map<string, string>): Promise<numb
 /**
  * 起界面。
  *
- * `server.ts` 留在包根、不编译进 `dist/`：它用 `import.meta.url` 定位 `web/`
- * 和 `DECISION.md`，编译到 `dist/server.js` 之后这两个路径会一起指错。
+ * 两条路，取决于这个 `cli.js` 是从哪跑起来的：
  *
- * ⚠️ **代价：从 npm 装出来时它跑不了。** Node 拒绝给 `node_modules` 下的文件
- * 剥离类型（`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`，§8.8 记的就是这条）。
- * 所以这里检测到包在 `node_modules` 下就直接给出指引 —— 把 Node 的栈丢给用户
- * 等于让人自己猜，而这一条猜不出来。
+ * - **装出来的包**：`dist/cli.js` 旁边就是 `dist/server.js`（`tsc` 一起编的），
+ *   直接跑它。这条是 npm 路径，也是 `serve` 从包装出来能跑的原因。
+ * - **clone**：`src/cli.ts` 旁边是 `src/server.ts`，按类型剥离跑。
+ *
+ * 两者都能跑，是因为 `server.ts` 的 `ROOT` 是**往上找 `package.json`**，
+ * 不是「本文件所在目录」—— 从 `src/` 跑和从 `dist/` 跑都指回包根，
+ * 而 `web/` 和 `DECISION.md` 都在那儿。
  */
 function serve(options: Map<string, string>): Promise<number> {
-  const serverPath = join(PKG_ROOT, 'server.ts')
-  if (!existsSync(serverPath)) {
-    console.error(`✗ ${serverPath} is missing — this package was published without server.ts`)
+  const here = dirname(fileURLToPath(import.meta.url))
+  const compiled = join(here, 'server.js')
+  const source = join(here, 'server.ts')
+
+  let script: string
+  let stripTypes = false
+  if (existsSync(compiled)) {
+    script = compiled
+  } else if (existsSync(source)) {
+    script = source
+    // 类型剥离 v22.6 引入、v22.18 才默认开启。低版本必须显式带这个标志。
+    const [major = 0, minor = 0] = process.versions.node.split('.').map(Number)
+    stripTypes = major < 22 || (major === 22 && minor < 18)
+  } else {
+    console.error(`✗ neither ${compiled} nor ${source} exists — this package is incomplete`)
     return Promise.resolve(1)
   }
 
-  if (PKG_ROOT.includes(`${sep}node_modules${sep}`)) {
-    console.error('✗ `jevloop serve` needs a clone, not an installed package.')
-    console.error('  Node cannot strip types for files under node_modules, and server.ts is TypeScript.')
-    console.error('')
-    console.error('    git clone https://github.com/zjunlp/JevLoop && cd JevLoop')
-    console.error('    node --experimental-strip-types server.ts')
-    console.error('')
-    console.error('  `jevloop run` and `jevloop spec` work from the installed package.')
-    return Promise.resolve(1)
-  }
-
-  // 类型剥离 v22.6 引入、v22.18 才默认开启。低版本必须显式带这个标志。
-  const [major = 0, minor = 0] = process.versions.node.split('.').map(Number)
-  const needsFlag = major < 22 || (major === 22 && minor < 18)
-
   const env = { ...process.env }
   const cwd = options.get('cwd')
   if (cwd) env.CWD_ROOT = resolve(cwd)
@@ -165,14 +164,14 @@ function serve(options: Map<string, string>): Promise<number> {
   const host = options.get('host')
   if (host) env.HOST = host
 
-  const child = spawn(process.execPath, [...(needsFlag ? ['--experimental-strip-types'] : []), serverPath], {
+  const child = spawn(process.execPath, [...(stripTypes ? ['--experimental-strip-types'] : []), script], {
     stdio: 'inherit',
     env,
   })
   return new Promise((done) => {
     child.on('exit', (code) => done(code ?? 1))
     child.on('error', (err) => {
-      console.error(`✗ could not start server.ts: ${err.message}`)
+      console.error(`✗ could not start the server: ${err.message}`)
       done(1)
     })
   })

server.ts src/server.tsserver.ts renamed to src/server.ts

@@ -2,8 +2,9 @@
 /**
  * JevLoop · 开发服务器
  *
- *   node --experimental-strip-types server.ts
- *   CWD_ROOT=/path/to/project node --experimental-strip-types server.ts
+ *   npx jevloop serve                                       # 从包装出来的版本
+ *   node --experimental-strip-types src/server.ts           # 从 clone
+ *   CWD_ROOT=/path/to/project node --experimental-strip-types src/server.ts
  *
  * 把 agent loop 的事件流通过 SSE 推给浏览器，同时托管 web/ 下的界面。
  * 只用 Node 标准库 —— 没有 express，没有构建步骤。
@@ -17,34 +18,69 @@
  * 双向通信在这个界面里没有任何用途。
  *
  * 会话落盘在 `JEVLOOP_HOME/sessions/`（默认 `~/.jevloop/`），规则见
- * `src/session-store.ts`。**盘上全留，只在读给 agent 用时截到 `MAX_TURNS` 轮** ——
+ * `session-store.ts`。**盘上全留，只在读给 agent 用时截到 `MAX_TURNS` 轮** ——
  * 以前是内存里的一个 Map，重启就没了，而且界面上看不出来。
  *
+ * ── 为什么不能再拆 ────────────────────────────────────────────
+ *
+ * `docs/CODE-STYLE.md` §12 问的是能不能用一句话说完它负责什么。这里能：
+ * **这个文件是开发服务器** —— 收请求、把事件流推给浏览器、托管 `web/`。
+ * 路由按端点分节，每节都只是「解析请求 → 调内核 → 写响应」，而它们共享同一份
+ * 状态（会话、工作区、正在跑的 run）；拆成 `server-routes.ts` 之类只会让
+ * 「一共有哪些端点」从一眼可见变成要翻三个文件。
+ *
+ * 真的会长的那半已经在别处：会话存储、工作区登记、目录浏览各自成文件
+ * （`session-store.ts` / `workspace.ts` / `dir-browse.ts`），本文件只做接线。
+ *
+ * ⚠️ **本文件在 `src/` 里，但它读的文件在包根。** `web/` 和 `DECISION.md`
+ * 既不编译也不属于 `src/`，所以 `ROOT` 不是「本文件所在目录」，而是
+ * **往上找到的第一个有 `package.json` 的目录** —— 从 `src/` 跑和从 `dist/` 跑
+ * 都指回包根。写成前者的话，编译之后 `web/` 会指到 `dist/web`。
+ *
  * @module JevLoop/server
  */
 
 import { createServer, type IncomingMessage, type ServerResponse } from 'node:http'
 import { mkdir, readFile, stat, writeFile } from 'node:fs/promises'
-import { realpathSync } from 'node:fs'
-import { basename, extname, isAbsolute, join, normalize, relative } from 'node:path'
+import { realpathSync, existsSync } from 'node:fs'
+import { basename, dirname, extname, isAbsolute, join, normalize, relative } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { homedir } from 'node:os'
 
-import { Decider } from './src/decide.ts'
-import { Meter } from './src/meter.ts'
-import { runAgent } from './src/agent.ts'
-import { resolveProvider, resolveGenerator } from './src/backends.ts'
-import { loadEnv } from './src/env.ts'
-import { parseDecisionDoc, summarize, headline, isGate } from './src/decisiondoc.ts'
-import { compilePredicate } from './src/decision-compile.ts'
-import type { AgentEvent } from './src/events.ts'
-import { SessionStore, assertSessionId } from './src/session-store.ts'
-import { migrateLegacyLayout } from './src/session-migrate.ts'
-import { createDir, listDirs } from './src/dir-browse.ts'
-import { WorkspaceStore } from './src/workspace.ts'
-import { WorkspaceError, type WorkspaceErrorCode } from './src/vocab-workspace.ts'
-
-const ROOT = fileURLToPath(new URL('.', import.meta.url))
+import { Decider } from './decide.ts'
+import { Meter } from './meter.ts'
+import { runAgent } from './agent.ts'
+import { parseDecisionDoc, summarize, headline, isGate } from './decisiondoc.ts'
+import { compilePredicate } from './decision-compile.ts'
+import type { AgentEvent } from './events.ts'
+import { SessionStore, assertSessionId } from './session-store.ts'
+import { migrateLegacyLayout } from './session-migrate.ts'
+import { createDir, listDirs } from './dir-browse.ts'
+import { WorkspaceStore } from './workspace.ts'
+import { WorkspaceError, type WorkspaceErrorCode } from './vocab-workspace.ts'
+// `backends` 和 `env` 都是 L6，和本文件同层 —— §11 只允许 L0 内部互相指涉、
+// 以及 L2 指向定义角，同层直接 import 是违规的。走门面（`index.ts` 不受层约束），
+// 这也是 `cli.ts` 的写法。
+import { resolveGenerator, resolveProvider, loadEnv } from './index.ts'
+
+/**
+ * 包根目录：从本文件往上找到的第一个带 `package.json` 的目录。
+ *
+ * **不能写成「本文件所在目录」** —— `web/` 和 `DECISION.md` 在包根，
+ * 而本文件从 `src/server.ts` 跑时所在的是 `src/`、编译后是 `dist/`，
+ * 两者都指不到包根。往上找 `package.json` 对两种位置都成立。
+ */
+function findRoot(from: string): string {
+  let dir = from
+  for (;;) {
+    if (existsSync(join(dir, 'package.json'))) return dir
+    const up = dirname(dir)
+    if (up === dir) throw new Error(`no package.json above ${from} — is this file installed correctly?`)
+    dir = up
+  }
+}
+
+const ROOT = findRoot(dirname(fileURLToPath(import.meta.url)))
 const WEB_DIR = join(ROOT, 'web')
 const DECISION_MD = join(ROOT, 'DECISION.md')
 const PORT = Number(process.env.PORT ?? 7799)

tsconfig.json

@@ -19,5 +19,5 @@
     "skipLibCheck": true,
     "forceConsistentCasingInFileNames": true
   },
-  "include": ["src/**/*.ts", "examples/**/*.ts", "bin/**/*.ts", "tests/**/*.ts", "bench/**/*.ts", "scripts/**/*.ts", "server.ts"]
+  "include": ["src/**/*.ts", "examples/**/*.ts", "bin/**/*.ts", "tests/**/*.ts", "bench/**/*.ts", "scripts/**/*.ts"]
 }