dsh-contextos-devops 0.0.0-stage → 1.48.32

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-contextos-devops
+      name: 'dsh-contextos-devops'

package/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="cdx" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#2f7cf6"/>
+      <stop offset="1" stop-color="#12b8a6"/>
+    </linearGradient>
+  </defs>
+  <rect x="3" y="3" width="58" height="58" rx="14" fill="#0f172a"/>
+  <path d="M32 13 15 22v20l17 9 17-9V22L32 13Z" fill="none" stroke="url(#cdx)" stroke-width="3" stroke-linejoin="round"/>
+  <path d="M32 32 15 22M32 32l17-10M32 32v19" stroke="url(#cdx)" stroke-width="2" opacity=".7"/>
+  <circle cx="32" cy="32" r="4.5" fill="url(#cdx)"/>
+  <circle cx="15" cy="22" r="3" fill="#12b8a6"/>
+  <circle cx="49" cy="22" r="3" fill="#2f7cf6"/>
+  <circle cx="32" cy="51" r="3" fill="#7dd3fc"/>
+</svg>

package/index.js

@@ -0,0 +1,345 @@
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { ctxRoot } from './lib/base/env.js';
+import { listNodes } from './lib/base/registry.js';
+import { writeData, readData } from './lib/core/data.js';
+import { createApp } from './lib/core/apps.js';
+import { ensureUser } from './lib/core/users.js';
+import { setLlm } from './lib/core/copilot.js';
+import { deployNode, startNode, stopNode, openNode, openSpace, openTerminalAt, nodeTerminal, spaceTerminal, runPipeline } from './lib/core/nodes.js';
+import { migrateStateOnce } from './lib/base/state.js';
+import { makeStatic } from './lib/misc/static.js';
+import { terminalUpgrade } from './lib/core/terminal2.js';
+import { startSpace, stopSpace, listSpaces, createSpace } from './lib/core/spaces.js';
+import { HTTP_DEBUG, http } from './lib/base/http.js';
+import { OPS } from './lib/core/ops.js';
+
+/**
+ * ContextOS DevOps core.
+ *
+ * Every mutation goes through ContextOS' own HTTP API (SPEC-CICD.md §0.2,
+ * USER-API.md §7/§8) or through the documented node bootstrap
+ * (`bin/ice.bin serve start`, SPEC-CICD.md §2). No shell wrapping, no private
+ * storage formats; node directories stay siblings of the main checkout.
+ */
+
+
+/** 插件用到的数据文件（JSON）清单。 */
+/** 读取插件数据文件内容（仅限 state 目录内、单文件 512KB 以内）。 */
+/** 把旧版状态目录迁移到新目录（一次性）。 */
+const ROUTE = '/dsh-contextos-devops/api';
+
+const text = (value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }];
+const output = {
+  schema: { type: 'object', properties: {}, additionalProperties: true },
+  render: (_args, value) => text(value),
+};
+
+const tools = [
+  {
+    name: 'contextos_deploy_node',
+    description:
+      'Deploy a local ContextOS service node. mode=copy (default, copy a local bin/ice.bin), mode=download (fetch ice.<os>.<arch> from a /publish source), mode=source (git clone + source etc/miss.sh build). Then bin/ice.bin forever start port <p>, and verify /c/runtime + /v/index.css.',
+    parameters: {
+      type: 'object',
+      properties: {
+        port: { type: 'number', description: 'TCP port for the new node (default 9188).' },
+        name: { type: 'string', description: 'Optional label for the node registry.' },
+        mode: { type: 'string', description: "Deploy mode: 'copy' | 'download' | 'source' (default copy)." },
+        parent: { type: 'string', description: "Parent node URL for download source and 'dev <parent>' launch." },
+        repo: { type: 'string', description: 'Git repo URL for source mode.' },
+        sourceBin: { type: 'string', description: 'Local bin/ice.bin path for copy mode.' },
+      },
+    },
+    async execute(args) {
+      return deployNode({
+        port: args?.port ?? 9188,
+        name: args?.name ?? '',
+        mode: args?.mode ?? 'copy',
+        parent: args?.parent ?? '',
+        repo: args?.repo ?? '',
+        sourceBin: args?.sourceBin ?? '',
+      });
+    },
+  },
+  {
+    name: 'contextos_list_nodes',
+    description: 'List ContextOS nodes managed by this plugin with live health (process/HTTP/static assets) and their version.',
+    parameters: { type: 'object', properties: {} },
+    async execute() {
+      return { ctxRoot: ctxRoot(), nodes: await listNodes() };
+    },
+  },
+  {
+    name: 'contextos_stop_node',
+    description: 'Stop a ContextOS node managed by this plugin by its own var/log/ice.pid; never kills other processes.',
+    parameters: {
+      type: 'object',
+      properties: { port: { type: 'number', description: 'Port of the managed node.' } },
+      required: ['port'],
+    },
+    async execute(args) {
+      return stopNode({ port: args.port });
+    },
+  },
+  {
+    name: 'contextos_start_node',
+    description: "Start a stopped ContextOS node: ./bin/ice.bin forever start port <p> in its directory, then wait for /c/runtime.",
+    parameters: { type: 'object', properties: { port: { type: 'number', description: 'Node port.' } }, required: ['port'] },
+    async execute(args) { return startNode({ port: args.port }); },
+  },
+  {
+    name: 'contextos_open_node',
+    description: "Open a node's home page (http://localhost:<port>/) in the system browser.",
+    parameters: { type: 'object', properties: { port: { type: 'number', description: 'Node port.' } }, required: ['port'] },
+    async execute(args) { return openNode({ port: args.port }); },
+  },
+  {
+    name: 'contextos_node_terminal',
+    description: "Open a macOS Terminal window at the node's directory.",
+    parameters: { type: 'object', properties: { port: { type: 'number', description: 'Node port.' } }, required: ['port'] },
+    async execute(args) { return nodeTerminal({ port: args.port }); },
+  },
+  {
+    name: 'contextos_space_start',
+    description: 'Start a project space: POST /c/dream/action/start?name=<space>.',
+    parameters: { type: 'object', properties: { node: { type: 'number' }, space: { type: 'string' } }, required: ['node', 'space'] },
+    async execute(args) { return startSpace({ node: args.node, space: args.space }); },
+  },
+  {
+    name: 'contextos_space_stop',
+    description: 'Stop a project space: POST /c/dream/action/stop?name=<space>.',
+    parameters: { type: 'object', properties: { node: { type: 'number' }, space: { type: 'string' } }, required: ['node', 'space'] },
+    async execute(args) { return stopSpace({ node: args.node, space: args.space }); },
+  },
+  {
+    name: 'contextos_space_open',
+    description: "Open a project space's home page (http://localhost:<node>/s/<space>/) in the system browser.",
+    parameters: { type: 'object', properties: { node: { type: 'number' }, space: { type: 'string' } }, required: ['node', 'space'] },
+    async execute(args) { return openSpace({ node: args.node, space: args.space }); },
+  },
+  {
+    name: 'contextos_space_terminal',
+    description: "Open a macOS Terminal window at the space's directory (<node>/usr/local/work/<space>).",
+    parameters: { type: 'object', properties: { node: { type: 'number' }, space: { type: 'string' } }, required: ['node', 'space'] },
+    async execute(args) { return spaceTerminal({ node: args.node, space: args.space }); },
+  },
+  {
+    name: 'contextos_list_spaces',
+    description: 'List project spaces on a node (GET /c/dream): full dated name, status, module, version.',
+    parameters: {
+      type: 'object',
+      properties: { node: { type: 'number', description: 'Node port.' } },
+      required: ['node'],
+    },
+    async execute(args) {
+      return { node: args.node, spaces: await listSpaces({ node: args.node }) };
+    },
+  },
+  {
+    name: 'contextos_create_space',
+    description:
+      'Create a project space with PUT /c/dream/action/create, wait for the dated name to appear in /c/dream, and wait until the space serves /c/runtime.',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: { type: 'number', description: 'Node port.' },
+        name: { type: 'string', description: 'Short space name, [a-zA-Z0-9_-]+.' },
+      },
+      required: ['node', 'name'],
+    },
+    async execute(args) {
+      return createSpace({ node: args.node, name: args.name });
+    },
+  },
+  {
+    name: 'contextos_create_app',
+    description:
+      'Create a real ContextOS app inside a space: git init, vimer module scaffold (Hash), save a CRUD command, compile, and verify the command answers. Returns the command path used for data.',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: { type: 'number', description: 'Node port.' },
+        space: { type: 'string', description: 'Full dated space name (see contextos_list_spaces).' },
+        name: { type: 'string', description: 'App name, [a-zA-Z][a-zA-Z0-9_]*.' },
+        zone: { type: 'string', description: 'Module zone / package directory (default devops).' },
+        help: { type: 'string', description: 'Command help text.' },
+      },
+      required: ['node', 'space', 'name'],
+    },
+    async execute(args) {
+      return createApp({
+        node: args.node,
+        space: args.space,
+        name: args.name,
+        zone: args.zone ?? 'devops',
+        help: args.help ?? '',
+      });
+    },
+  },
+  {
+    name: 'contextos_write_data',
+    description:
+      'Write one record through a ContextOS app command with PUT /action/create. Field values must not contain "/" (the URL path separator). Reads the table back and returns the rows.',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: { type: 'number', description: 'Node port.' },
+        space: { type: 'string', description: 'Full dated space name.' },
+        command: { type: 'string', description: 'Command name, e.g. web.chat.devops.note.' },
+        fields: { type: 'object', description: 'Field/value pairs, for example {title, content, user_uid}.' },
+      },
+      required: ['node', 'space', 'command', 'fields'],
+    },
+    async execute(args) {
+      return writeData({ node: args.node, space: args.space, command: args.command, fields: args.fields ?? {} });
+    },
+  },
+  {
+    name: 'contextos_read_data',
+    description: 'List records of a ContextOS app command (GET /s/<space>/c/<command>) and return the parsed table plus the row count.',
+    parameters: {
+      type: 'object',
+      properties: {
+        node: { type: 'number', description: 'Node port.' },
+        space: { type: 'string', description: 'Full dated space name.' },
+        command: { type: 'string', description: 'Command name.' },
+      },
+      required: ['node', 'space', 'command'],
+    },
+    async execute(args) {
+      return readData({ node: args.node, space: args.space, command: args.command });
+    },
+  },
+  {
+    name: 'contextos_pipeline',
+    description:
+      'Run the end-to-end CI/CD loop: deploy node -> create space -> create app -> write a record -> read it back. Returns each step with status and elapsed time.',
+    parameters: {
+      type: 'object',
+      properties: {
+        port: { type: 'number', description: 'Node port (default 9188).' },
+        space: { type: 'string', description: 'Short space name (default devops_demo; no "-").' },
+        app: { type: 'string', description: 'App name (default note).' },
+      },
+    },
+    async execute(args) {
+      return runPipeline({ port: args?.port ?? 9188, space: args?.space ?? 'devops_demo', app: args?.app ?? 'note' });
+    },
+  },
+];
+
+async function readBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > 2 * 1024 * 1024) throw new Error('request body too large');
+    chunks.push(chunk);
+  }
+  if (!chunks.length) return {};
+  return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+
+function send(res, status, payload) {
+  const calls = HTTP_DEBUG.getStore();
+  if (calls && calls.length) payload = { ...payload, debug: calls.slice(-80) };
+  const logId = crypto.randomUUID();
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store', 'log-id': logId });
+  res.end(body);
+}
+
+const bodyUid = (body, name) => body[`${name}_uid`] || body[`${name}UID`] || body[`${name}Id`] || '';
+
+async function route(req, res) {
+  try {
+    await migrateStateOnce();
+    const incoming = Object.fromEntries(new URL(req.url || '/', 'http://x').searchParams.entries());
+    const body = { ...incoming, ...(await readBody(req)) };
+    const op = String(body.op || 'health');
+    const node = Number(body.node);
+
+    // origin 需要连接本机端口，拿不到就退回 Host 头：只有这一条留在路由层。
+    if (op === 'origin') {
+      let host = '';
+      try { const a = server && server.address && server.address(); if (a && a.port) host = `${!a.address || a.address === '::' || a.address === '::1' ? '127.0.0.1' : a.address}:${a.port}`; } catch {}
+      if (!host) { try { host = String(req.headers.host || ''); } catch {} }
+      return send(res, 200, { ok: true, data: { host } });
+    }
+
+    const entry = OPS[op];
+    if (!entry) return send(res, 404, { ok: false, error: `unknown op ${op}` });
+    // 节点已启动的操作先确保 DSH Copilot 用户存在（15s 超时，失败不阻断）。
+    if (node && !entry.noUser) await ensureUser(node).catch(() => {});
+    return send(res, 200, { ok: true, data: await entry.run(body, { node, req }) });
+  } catch (error) {
+    return send(res, 200, { ok: false, error: String(error?.message || error), steps: error?.steps });
+  }
+}
+
+// webServer must be ready before apply, otherwise the plugin registers its
+// tools but silently loses the HTTP route the Web page calls.
+export const inject = ['tools', 'webServer', 'llm'];
+
+export function apply(ctx) {
+  setLlm(ctx.llm || (ctx.get && ctx.get('llm')) || null);
+  for (const tool of tools) {
+    ctx.effect(() =>
+      ctx.tools.register({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        output,
+        execute: tool.execute,
+        isConcurrencySafe: () => false,
+      }),
+    );
+  }
+
+  const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+  const monacoRoot = process.env.CTX_MONACO_DIR || path.join(ctxRoot(), 'usr', 'macos-app', 'Resources', 'monaco');
+  const xtermRoot = path.join(pluginDir, 'vendor', 'xterm');
+  const threeRoot = path.join(pluginDir, 'vendor', 'three');
+  const leafletRoot = path.join(pluginDir, 'vendor', 'leaflet');
+  const assetsRoot = path.join(pluginDir, 'assets');
+
+  const server = ctx.webServer || ctx.get('webServer');
+  if (server) {
+    ctx.effect(() => server.registerUpgrade({ path: '/dsh-contextos-devops/terminal', handler: terminalUpgrade }));
+    ctx.effect(() =>
+      server.register({
+        kind: 'exact',
+        path: ROUTE,
+        handler: (req, res) => {
+          HTTP_DEBUG.run([], () => {
+            route(req, res).catch((error) => send(res, 200, { ok: false, error: String(error?.message || error) }));
+          });
+        },
+      }),
+    );
+    ctx.effect(() => server.register({ kind: 'prefix', path: '/dsh-contextos-devops/monaco', handler: makeStatic('/dsh-contextos-devops/monaco', monacoRoot) }));
+    ctx.effect(() => server.register({ kind: 'prefix', path: '/dsh-contextos-devops/xterm', handler: makeStatic('/dsh-contextos-devops/xterm', xtermRoot) }));
+    ctx.effect(() => server.register({ kind: 'prefix', path: '/dsh-contextos-devops/three', handler: makeStatic('/dsh-contextos-devops/three', threeRoot) }));
+    ctx.effect(() => server.register({ kind: 'prefix', path: '/dsh-contextos-devops/leaflet', handler: makeStatic('/dsh-contextos-devops/leaflet', leafletRoot) }));
+    ctx.effect(() => server.register({ kind: 'prefix', path: '/dsh-contextos-devops/assets', handler: makeStatic('/dsh-contextos-devops/assets', assetsRoot) }));
+  }
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/lib/base/env.js

@@ -0,0 +1,22 @@
+// 路径与环境：所有目录推导只在这里，业务代码不拼 HOME。
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export const HOME = () => os.homedir();
+
+export function ctxRoot() {
+  return process.env.CTX_ROOT || path.join(os.homedir(), 'ContextOS');
+}
+
+export function stateDir() {
+  if (process.env.CTX_DEVOPS_STATE) return process.env.CTX_DEVOPS_STATE;
+  const home = process.env.DSH_HOME || path.join(os.homedir(), '.dsh');
+  const dir = path.join(home, 'dsh-contextos-devops');
+  const legacy = path.join(home, 'contextos-devops-dsh');
+  // 改名一次性迁移：旧目录里的节点缓存/会话/请求日志不能随插件改名丢掉
+  try {
+    if (!fs.existsSync(dir) && fs.existsSync(legacy)) fs.renameSync(legacy, dir);
+  } catch {}
+  return dir;
+}

package/lib/base/field.js

@@ -0,0 +1,25 @@
+// 基础功能：字段 → ContextOS 路径段（key/value/key/value）。
+import { encode } from './http.js';
+
+export function fieldSegments(fields) {
+  const out = [];
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(key)) throw new Error(`bad field name: ${key}`);
+    if (value === undefined || value === null || String(value) === '') continue;
+    if (String(value).includes('/')) throw new Error(`field ${key}: ContextOS splits URL paths on "/", use a full-width ／ instead`);
+    out.push(`${encode(key)}/${encode(value)}`);
+  }
+  return out.join('/');
+}
+
+// 修改类请求：只有表单字段进路径；*_uid 结尾的进查询参数
+export function splitFields(fields) {
+  const path = {};
+  const query = {};
+  for (const [key, value] of Object.entries(fields || {})) {
+    if (value === undefined || value === null || String(value) === '') continue;
+    if (/_uid$/.test(key)) query[key] = String(value);
+    else path[key] = value;
+  }
+  return { path, query };
+}

package/lib/base/http.js

@@ -0,0 +1,140 @@
+// 对 ContextOS 节点的 HTTP 访问：统一注入 user.uid、记录调试请求、探活与端口探测。
+import net from 'node:net';
+import { AsyncLocalStorage } from 'node:async_hooks';
+
+export const USER_CACHE = new Map();
+export const HTTP_DEBUG = new AsyncLocalStorage();
+
+export function baseUrl(port) {
+  return `http://127.0.0.1:${port}`;
+}
+
+export function encode(v) {
+  return encodeURIComponent(String(v));
+}
+
+/** ContextOS answers with plain text tables or a JSON status envelope. */
+export function envelopeRows(text) {
+  try {
+    const env = JSON.parse(text);
+    const columns = Array.isArray(env.append) ? env.append : [];
+    const height = columns.length && Array.isArray(env[columns[0]]) ? env[columns[0]].length : 0;
+    return { columns, rows: Array.from({ length: height }, (_, i) => Object.fromEntries(columns.map((c) => [c, Array.isArray(env[c]) ? env[c][i] : '']))) };
+  } catch {
+    return { columns: [], rows: [] };
+  }
+}
+
+/** 返回数据只有两种形态：列表（append + 列数组）与详情（option 单条记录）。 */
+export function envelopeShape(text) {
+  let env;
+  try { env = JSON.parse(text); } catch { return { kind: 'text', raw: String(text || '') }; }
+  if (!env || typeof env !== 'object' || Array.isArray(env)) return { kind: 'text', raw: String(text || '') };
+  const columns = Array.isArray(env.append) ? env.append : [];
+  if (columns.length) {
+    const height = Array.isArray(env[columns[0]]) ? env[columns[0]].length : 0;
+    const rows = Array.from({ length: height }, (_, i) => Object.fromEntries(columns.map((c) => [c, Array.isArray(env[c]) ? env[c][i] : ''])));
+    return { kind: 'list', columns, rows, env };
+  }
+  if (env.option && typeof env.option === 'object' && !Array.isArray(env.option) && Object.keys(env.option).length) {
+    return { kind: 'detail', fields: env.option, env };
+  }
+  if (Array.isArray(env.detail) && env.detail.length) {
+    const fields = {};
+    for (const k of env.detail) fields[k] = env.option?.[k] ?? env[k] ?? '';
+    return { kind: 'detail', fields, env };
+  }
+  return { kind: 'empty', env };
+}
+
+export async function http(port, pathname, { method = 'GET', timeout = 15000, headers = {}, auth = true, redirect = 'follow', token = '', sessid = '', cookie = '' } = {}) {
+  // cookie：平台级会话的完整值 space <pod> <command> check <sessid>
+  if (cookie) headers = { ...headers, Cookie: `sessid=${cookie}` };
+  // 远程 / 容器节点：身份来自 token 或 sessid（由 /c/web.token/create 或 /c/aaa.sess/create 取得）
+  if (sessid) pathname += (pathname.includes('?') ? '&' : '?') + 'sessid=' + encode(sessid);
+  else if (token) pathname += (pathname.includes('?') ? '&' : '?') + 'token=' + encode(token);
+  const cached = USER_CACHE.get(Number(port));
+  // 本机访问免登录、全 root，可以任意指定 user.uid；但那只对「应用级」命令有意义
+  // （/s/<pod>/c/web.team.<mod>.portal 及其子命令）。系统级命令不认它，别往日志里塞。
+  const appLevel = /^\/s\/[^/]+\/c\/web\.team\./.test(pathname);
+  if (auth && appLevel && cached?.uid && !/(?:\?|&)(?:user\.uid|sessid)=/.test(pathname)) {
+    pathname += (pathname.includes('?') ? '&' : '?') + 'user.uid=' + encode(cached.uid);
+  }
+  const fullUrl = baseUrl(port) + pathname;
+  const requestHeaders = { accept: 'text/plain, application/json', ...headers };
+  const started = Date.now();
+  const res = await fetch(fullUrl, {
+    method,
+    signal: AbortSignal.timeout(timeout),
+    headers: requestHeaders,
+    redirect,
+  });
+  const text = await res.text();
+  const responseHeaders = Object.fromEntries(res.headers.entries());
+  const logId = responseHeaders['log-id'] || responseHeaders['x-log-id'] || '';
+  const entry = { method, url: fullUrl, requestHeaders, responseHeaders, status: res.status, size: Buffer.byteLength(text), ms: Date.now() - started, logId, body: text.slice(0, 200000) };
+  if (!/\/c\/version(?:\?|$)/.test(fullUrl) && !/\/v\/index\.css/.test(fullUrl)) HTTP_DEBUG.getStore()?.push(entry);
+  return { status: res.status, size: entry.size, text, headers: responseHeaders, logId, ms: entry.ms, requestHeaders };
+}
+
+/** 文件上传：系统级命令统一走 <cmd>/action/upload（multipart/form-data）。 */
+export async function upload(port, pathname, { name = 'file', filename = 'upload.bin', data, fields = {}, timeout = 60000 } = {}) {
+  const form = new FormData();
+  for (const [k, v] of Object.entries(fields || {})) form.append(k, String(v));
+  const bytes = typeof data === 'string' ? Buffer.from(data) : data;
+  form.append(name, new Blob([bytes]), filename);
+  const started = Date.now();
+  const res = await fetch(baseUrl(port) + pathname, { method: 'POST', body: form, signal: AbortSignal.timeout(timeout) });
+  const text = await res.text();
+  const responseHeaders = Object.fromEntries(res.headers.entries());
+  const entry = { method: 'POST', url: baseUrl(port) + pathname, requestHeaders: {}, responseHeaders, status: res.status, size: Buffer.byteLength(text), ms: Date.now() - started, logId: responseHeaders['log-id'] || '', body: text.slice(0, 200000) };
+  HTTP_DEBUG.getStore()?.push(entry);
+  return { status: res.status, size: entry.size, text, headers: responseHeaders, ms: entry.ms };
+}
+
+/** Iron law 4: status + length + a known field, never status alone. */
+/** 运行时信息：/c/runtime 一次拿到版本、编译时间、程序大小 */
+export function parseRuntime(text) {
+  try {
+    const d = JSON.parse(text);
+    const boot = d.boot || {};
+    const make = d.make || {};
+    const hash = String(make.hash || '');
+    const ver = [make.version, make.forword, hash.slice(0, 6)].filter(Boolean).join('-');
+    return {
+      ok: !!(boot && make && (boot.bin || boot.pathname)),
+      boot, make,
+      version: ver,                       // v3.2.5-2458-d3a68b
+      builtAt: String(make.time || boot.time || ''),
+      sizeText: String(boot.size || ''),
+      hash, node: d.node || {}, host: d.host || {},
+    };
+  } catch { return { ok: false }; }
+}
+
+export async function probe(port, timeout = 3000) {
+  try {
+    const v = await http(port, '/c/runtime', { timeout });
+    const rt = parseRuntime(v.text);
+    const css = await http(port, '/v/index.css', { timeout });
+    return {
+      live: v.status === 200 && rt.ok && css.size > 10000,
+      port,
+      runtime: rt,
+      version: rt.version || '',
+      builtAt: rt.builtAt || '',
+      cssBytes: css.size,
+    };
+  } catch (error) {
+    return { live: false, port, error: String(error?.message || error) };
+  }
+}
+
+export async function portFree(port) {
+  return new Promise((resolve) => {
+    const s = net.createServer();
+    s.once('error', () => resolve(false));
+    s.once('listening', () => s.close(() => resolve(true)));
+    s.listen(port, '127.0.0.1');
+  });
+}

package/lib/base/platform.js

@@ -0,0 +1,33 @@
+// 基础功能逻辑：OS 差异（可 import misc）。base 不 import core。
+import { isWin, spawnDetached } from '../misc/shell.js';
+
+export const isMac = process.platform === 'darwin';
+export { isWin };
+export const isLinux = process.platform === 'linux';
+export const osName = isMac ? 'darwin' : isWin ? 'windows' : 'linux';
+export const archName = process.arch === 'arm64' ? 'arm64' : process.arch === 'ia32' ? '386' : 'amd64';
+export const platformTriple = () => `${osName}.${archName}`;
+
+/** sqlite 可执行文件：Windows 走 PATH，macOS/Linux 用常见绝对路径并回退 PATH。 */
+export function sqliteBin() {
+  if (isWin) return 'sqlite3.exe';
+  if (isMac) return '/usr/bin/sqlite3';
+  return 'sqlite3';
+}
+
+/** 用系统浏览器打开 URL。 */
+export function openBrowser(url) {
+  if (isMac) return spawnDetached('open', [url]);
+  if (isWin) return spawnDetached('cmd.exe', ['/c', 'start', '', url]);
+  return spawnDetached('xdg-open', [url]);
+}
+
+/** 在指定目录打开系统终端。 */
+export function openTerminalAt(dir) {
+  if (isMac) return spawnDetached('open', ['-a', 'Terminal', dir]);
+  if (isWin) return spawnDetached('cmd.exe', ['/c', 'start', 'cmd', '/k', `cd /d "${dir}"`]);
+  return spawnDetached('x-terminal-emulator', ['-e', 'bash', '-c', `cd "${dir}" && exec bash`]);
+}
+
+/** 内嵌 PTY 是否可用（Windows 无 pty.fork，需要 ConPTY 后端）。 */
+export const ptySupported = !isWin;