dominds 1.25.18 → 1.26.0

package/dist/docs/cli-usage.md

@@ -4,7 +4,7 @@ Chinese version: [中文版](./cli-usage.zh.md)
 
 The `dominds` CLI provides a unified entry point, but the **primary interaction experience is the Web UI** (the default `dominds` command). This guide focuses on the Web UI workflow.
 
-> Note: In this document, **rtws (runtime workspace)** refers to the runtime root directory Dominds uses (by default `process.cwd()`, switchable via `-C <dir>`).
+> Note: In this document, **rtws (runtime workspace)** refers to the runtime root directory Dominds uses (by default `process.cwd()`, switchable via `-C <abs-dir>`; `-C` only accepts absolute paths).
 
 > Note: `dominds tui` / `dominds run` are currently reserved subcommand names and do not have a stable implementation yet. As a result, this guide does not document TUI options or detailed usage.
 
@@ -18,6 +18,7 @@ The `dominds` CLI provides a unified entry point, but the **primary interaction
     - [Web UI Interface](#web-ui-interface)
     - [Text User Interface (TUI) (Not Implemented Yet)](#text-user-interface-tui-not-implemented-yet)
     - [Minds Reader](#minds-reader)
+    - [Certificate Tools](#certificate-tools)
     - [rtws Creation](#rtws-creation)
   - [Usage Examples](#usage-examples)
   - [Dialog Storage](#dialog-storage)
@@ -32,6 +33,7 @@ The `dominds` package provides a unified CLI with subcommands:
 | `dominds` or `dominds webui`      | Start Web UI (default, recommended)                           | Web UI         |
 | `dominds tui` or `dominds run`    | Terminal UI (planned; no stable implementation at the moment) | N/A            |
 | `dominds read`                    | Read and inspect rtws/team minds configuration                | CLI            |
+| `dominds cert`                    | Create and inspect local WebUI HTTPS certificates             | CLI            |
 | `dominds create` or `dominds new` | Create a new rtws (runtime workspace) from a template         | CLI            |
 | `dominds help`                    | Show help message                                             | CLI            |
 | `dominds --version`               | Show version information                                      | CLI            |
@@ -49,11 +51,16 @@ dominds webui [options]
 
 # Common: choose port / rtws
 dominds webui -p 8080
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # Minds reader: inspect team configuration
 dominds read [options] [member-id]
 
+# Certificate tools: create/inspect local HTTPS certificates
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+
 # rtws creation: scaffold a new runtime workspace
 dominds create <template> [directory]
 dominds new <template> [directory]  # alias for create
@@ -83,7 +90,7 @@ Start the web-based user interface for the current rtws. This provides a graphic
 
 - `-p, --port <port>` - Port to listen on; a bare port binds strictly, suffix `+` tries higher ports, and suffix `-` tries lower ports (omitting `--port` is equivalent to `5666-`)
 - `-h, --host <host>` - Host to bind to (default: localhost)
-- `-C, --cwd <dir>` - Change to rtws directory before starting
+- `-C, --cwd <abs-dir>` - Change to rtws directory before starting; absolute paths only
 - `--help` - Show help message
 
 **Examples:**
@@ -92,7 +99,7 @@ Start the web-based user interface for the current rtws. This provides a graphic
 dominds
 dominds webui -p 8080
 dominds webui -p 8080+
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 ```
 
 **Common use cases:**
@@ -122,7 +129,7 @@ Read and inspect agent prompts/configuration for the rtws. This is commonly used
 
 **Options:**
 
-- `-C, --cwd <dir>` - Change to rtws directory before reading
+- `-C, --cwd <abs-dir>` - Change to rtws directory before reading; absolute paths only
 - `--only-prompt` - Show only system prompts
 - `--only-mem` - Show only memory
 - `--help` - Show help message
@@ -132,11 +139,40 @@ Read and inspect agent prompts/configuration for the rtws. This is commonly used
 ```bash
 dominds read
 dominds read developer
-dominds read -C ./my-rtws
+dominds read -C /path/to/my-rtws
 dominds read --only-prompt
 dominds read --only-mem
 ```
 
+### Certificate Tools
+
+```bash
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+```
+
+Create or inspect local HTTPS certificates for the Dominds WebUI. Certificates live in `~/.dominds/certs/` and match DNS/IP hostnames, not ports; one certificate covers every WebUI port on that host.
+
+**Options:**
+
+- `--host <host>` - Certificate SAN hostname or IP; repeatable for certificate creation; defaults to one or more detected non-loopback LAN hosts
+- `--days <days>` - Certificate validity in days (default: 3650, or 10 years)
+- `--force` - Overwrite existing generated files
+- `--port <port>` - Port used when formatting `status --origin`
+- `--origin` - Print only the effective origin; HTTPS when a cert matches, HTTP otherwise
+
+**Examples:**
+
+```bash
+dominds cert create
+dominds cert create --host 192.168.1.10 --host my-host.local
+dominds cert status --host 0.0.0.0
+dominds cert status --host 0.0.0.0 --port 5666 --origin
+```
+
+`localhost`, `loopback`, `127.0.0.0/8`, `::1`, `0.0.0.0`, and `::` are not certificate hosts. `0.0.0.0` / `::` only mean bind-all; certificate matching uses detected non-loopback LAN hosts.
+
 ### rtws Creation
 
 ```bash
@@ -190,7 +226,7 @@ dominds
 dominds webui -p 8080
 
 # 3) Start in a specific rtws
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # 4) Inspect current team/rtws configuration
 dominds read

package/dist/docs/cli-usage.zh.md

@@ -4,7 +4,7 @@
 
 `dominds` 提供统一的命令行入口，但**主要交互界面是 Web UI**（默认命令 `dominds`）。本文档以 Web UI 工作流为主。
 
-> 注：本文统一使用 **rtws（运行时工作区）** 表示 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <dir>` 切换）。
+> 注：本文统一使用 **rtws（运行时工作区）** 表示 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <abs-dir>` 切换；`-C` 只接受绝对路径）。
 
 > 说明：`dominds tui` / `dominds run` 相关功能目前尚未提供稳定实现（子命令名保留用于未来规划），因此本指南不再展开 TUI 的命令选项与用法细节。
 
@@ -18,6 +18,7 @@
     - [Web UI 界面](#web-ui-界面)
     - [文本用户界面 (TUI)（尚未实现）](#文本用户界面-tui尚未实现)
     - [Minds 阅读器](#minds-阅读器)
+    - [证书工具](#证书工具)
     - [rtws 创建](#rtws-创建)
   - [使用示例](#使用示例)
   - [对话存储](#对话存储)
@@ -32,6 +33,7 @@
 | `dominds` 或 `dominds webui`      | 启动 Web UI（默认、推荐）                | Web UI   |
 | `dominds tui` 或 `dominds run`    | 终端界面（规划中；当前版本暂不提供稳定） | N/A      |
 | `dominds read`                    | 读取/分析团队 minds 配置                 | CLI      |
+| `dominds cert`                    | 创建/检查本机 WebUI HTTPS 证书           | CLI      |
 | `dominds create` 或 `dominds new` | 从模板创建新 rtws（运行时工作区）        | CLI      |
 | `dominds help`                    | 显示帮助消息                             | CLI      |
 | `dominds --version`               | 显示版本信息                             | CLI      |
@@ -49,11 +51,16 @@ dominds webui [options]
 
 # 常用：指定端口 / rtws
 dominds webui -p 8080
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # Minds 阅读器：分析团队配置
 dominds read [options] [member-id]
 
+# 证书工具：创建/检查本机 HTTPS 证书
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+
 # rtws 创建：搭建新项目/运行时工作区
 dominds create <template> [directory]
 dominds new <template> [directory]  # create 的别名
@@ -83,7 +90,7 @@ dominds webui [options]
 
 - `-p, --port <port>` - 监听端口；裸端口严格绑定，后缀 `+` 向更大端口自动尝试，后缀 `-` 向更小端口自动尝试（未指定时等价于 `5666-`）
 - `-h, --host <host>` - 绑定的主机（默认：localhost）
-- `-C, --cwd <dir>` - 启动前更改 rtws 目录
+- `-C, --cwd <abs-dir>` - 启动前更改 rtws 目录；只接受绝对路径
 - `--help` - 显示帮助消息
 
 **示例：**
@@ -99,7 +106,7 @@ dominds webui -p 8080
 dominds webui -p 8080+
 
 # 在特定 rtws 启动 Web UI
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 ```
 
 **常见用途：**
@@ -129,7 +136,7 @@ dominds read [options] [member-id]
 
 **选项：**
 
-- `-C, --cwd <dir>` - 读取前更改 rtws 目录
+- `-C, --cwd <abs-dir>` - 读取前更改 rtws 目录；只接受绝对路径
 - `--only-prompt` - 仅显示系统提示词
 - `--only-mem` - 仅显示内存
 - `--help` - 显示帮助消息
@@ -139,11 +146,40 @@ dominds read [options] [member-id]
 ```bash
 dominds read
 dominds read developer
-dominds read -C ./my-rtws
+dominds read -C /path/to/my-rtws
 dominds read --only-prompt
 dominds read --only-mem
 ```
 
+### 证书工具
+
+```bash
+dominds cert create [--host <host>] [--days <days>] [--force]
+dominds cert self-cert [--host <host>] [--days <days>] [--force]
+dominds cert status --host <host> [--port <port>] [--origin]
+```
+
+创建或检查 Dominds WebUI 的本机 HTTPS 证书。证书保存在 `~/.dominds/certs/`，按 DNS/IP 主机名匹配，不绑定端口；同一张证书可覆盖该主机上的所有 WebUI 端口。
+
+**选项：**
+
+- `--host <host>` - 证书 SAN 主机名或 IP；创建证书时可重复指定；未指定时使用检测到的一个或多个非 loopback LAN 主机
+- `--days <days>` - 证书有效天数（默认：3650，即 10 年）
+- `--force` - 覆盖已有的同名生成文件
+- `--port <port>` - `status --origin` 输出 URL 时使用的端口
+- `--origin` - 仅输出有效访问 origin；找到证书时输出 HTTPS，否则输出 HTTP
+
+**示例：**
+
+```bash
+dominds cert create
+dominds cert create --host 192.168.1.10 --host my-host.local
+dominds cert status --host 0.0.0.0
+dominds cert status --host 0.0.0.0 --port 5666 --origin
+```
+
+`localhost`、`loopback`、`127.0.0.0/8`、`::1`、`0.0.0.0`、`::` 不会作为 HTTPS 证书主机。`0.0.0.0` / `::` 只表示绑定所有地址，匹配证书时会使用检测到的非 loopback LAN 主机。
+
 ### rtws 创建
 
 ```bash
@@ -204,7 +240,7 @@ dominds
 dominds webui -p 8080
 
 # 3) 在特定 rtws 启动
-dominds webui -C ./my-rtws
+dominds webui -C /path/to/my-rtws
 
 # 4) 查看/核对当前团队配置
 dominds read

package/dist/docs/dialog-persistence.md

@@ -4,7 +4,7 @@ Chinese version: [中文版](./dialog-persistence.zh.md)
 
 This document describes the persistence layer and storage mechanisms for the Dominds dialog system, including file system conventions, data structures, and storage patterns.
 
-> Note: In this document, **rtws (runtime workspace)** refers to Dominds' runtime root directory (by default `process.cwd()`, switchable via `-C <dir>`).
+> Note: In this document, **rtws (runtime workspace)** refers to Dominds' runtime root directory (by default `process.cwd()`, switchable via `-C <abs-dir>`; `-C` only accepts absolute paths).
 
 ## Current Implementation Status
 

package/dist/docs/dominds-terminology.md

@@ -264,8 +264,8 @@ Example / 示例（概念）:
 
 ### rtws（运行时工作区）
 
-- EN: **rtws** (runtime workspace) is the directory Dominds treats as its runtime root (by default it is `process.cwd()`, and can be changed via `-C <dir>`). Files like `.minds/` and `.dialogs/` live under the rtws.
-- ZH: **rtws（运行时工作区）**是 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <dir>` 切换）。诸如 `.minds/`、`.dialogs/` 等运行态目录均位于 rtws 下。
+- EN: **rtws** (runtime workspace) is the directory Dominds treats as its runtime root (by default it is `process.cwd()`, and can be changed via `-C <abs-dir>`; `-C` only accepts absolute paths). Files like `.minds/` and `.dialogs/` live under the rtws.
+- ZH: **rtws（运行时工作区）**是 Dominds 运行时使用的根目录（默认等于 `process.cwd()`，可通过 `-C <abs-dir>` 切换；`-C` 只接受绝对路径）。诸如 `.minds/`、`.dialogs/` 等运行态目录均位于 rtws 下。
 
 - EN: Wording rule: when the meaning is **rtws**, prefer writing “rtws (runtime workspace)” (or just “rtws” after the first mention) rather than the ambiguous generic “workspace”.
 - ZH: 用词规则：当语义指向 **rtws** 时，优先写“rtws（运行时工作区）”（或在已定义后只写“rtws”），避免在对外提示/文档中只写“工作区”从而与其他语境的 workspace/workdir 混淆。

package/dist/server/auth.d.ts

@@ -37,7 +37,14 @@ export declare function isAuthEnabled(auth: AuthConfig): auth is Extract<AuthCon
 export declare function getHttpAuthCheck(req: IncomingMessage, auth: AuthConfig): AuthCheckResult;
 export declare function getHttpAuthCheckAllowUrlParam(req: IncomingMessage, auth: AuthConfig, requestUrl: URL): AuthCheckResult;
 export declare function getWebSocketAuthCheck(req: IncomingMessage, auth: AuthConfig): AuthCheckResult;
+export type ServerUrlScheme = 'http' | 'https';
+export declare function formatServerOrigin(params: {
+    scheme: ServerUrlScheme;
+    host: string;
+    port: number;
+}): string;
 export declare function formatAutoAuthUrl(params: {
+    scheme?: ServerUrlScheme;
     host: string;
     port: number;
     authKey: string;

package/dist/server/auth.js

@@ -53,6 +53,7 @@ exports.isAuthEnabled = isAuthEnabled;
 exports.getHttpAuthCheck = getHttpAuthCheck;
 exports.getHttpAuthCheckAllowUrlParam = getHttpAuthCheckAllowUrlParam;
 exports.getWebSocketAuthCheck = getWebSocketAuthCheck;
+exports.formatServerOrigin = formatServerOrigin;
 exports.formatAutoAuthUrl = formatAutoAuthUrl;
 const crypto = __importStar(require("crypto"));
 function computeAuthConfig(params) {
@@ -129,14 +130,24 @@ function getWebSocketAuthCheck(req, auth) {
         ? { kind: 'ok' }
         : { kind: 'unauthorized', reason: 'invalid' };
 }
+function formatServerOrigin(params) {
+    const visibleHost = normalizeHostForUrl(params.host, params.scheme);
+    return `${params.scheme}://${visibleHost}:${params.port}`;
+}
 function formatAutoAuthUrl(params) {
-    const visibleHost = normalizeHostForUrl(params.host);
-    return `http://${visibleHost}:${params.port}/?auth=${encodeURIComponent(params.authKey)}`;
+    return `${formatServerOrigin({
+        scheme: params.scheme ?? 'http',
+        host: params.host,
+        port: params.port,
+    })}/?auth=${encodeURIComponent(params.authKey)}`;
 }
-function normalizeHostForUrl(host) {
+function normalizeHostForUrl(host, scheme) {
     // Binding to 0.0.0.0/:: is common, but not a browsable "host".
-    if (host === '0.0.0.0' || host === '::')
+    // For HTTPS, preserve the certificate-matched bind host to avoid creating a hostname mismatch.
+    if (scheme === 'http' && (host === '0.0.0.0' || host === '::'))
         return 'localhost';
+    if (host.includes(':') && !host.startsWith('['))
+        return `[${host}]`;
     return host;
 }
 function generateAuthKey() {

package/dist/server/certificates.d.ts

@@ -0,0 +1,61 @@
+export declare const DEFAULT_SELF_SIGNED_CERT_DAYS = 3650;
+export type HttpsCertificateMaterial = {
+    cert: string;
+    key: string;
+    certPath: string;
+    keyPath: string;
+    matchedHost: string;
+    matchedHostPriority: number;
+    validTo: Date;
+};
+export type CertificateLookupEndpoint = Readonly<{
+    bindHost: string;
+    urlHost: string;
+}>;
+export type CertificateLookupDiagnostic = {
+    level: 'warn';
+    code: 'invalid_cert_file' | 'missing_key_file' | 'invalid_key_pair' | 'expired_or_not_yet_valid';
+    message: string;
+    certPath: string;
+    keyPath?: string;
+} | {
+    level: 'warn';
+    code: 'multiple_matching_certs';
+    message: string;
+    host: string;
+    certPaths: readonly string[];
+};
+export type CertificateLookupResult = {
+    kind: 'found';
+    certsDirAbs: string;
+    endpoint: CertificateLookupEndpoint;
+    certificate: HttpsCertificateMaterial;
+    diagnostics: readonly CertificateLookupDiagnostic[];
+} | {
+    kind: 'not_found';
+    certsDirAbs: string;
+    endpoint: CertificateLookupEndpoint;
+    diagnostics: readonly CertificateLookupDiagnostic[];
+};
+export type CreatedSelfSignedCertificate = {
+    host: string;
+    hosts: readonly string[];
+    days: number;
+    certsDirAbs: string;
+    certPath: string;
+    keyPath: string;
+    metadataPath: string;
+};
+export declare function getDefaultDomindsCertsDir(): string;
+export declare function findAutoHttpsCertificateForHost(params: {
+    host: string;
+    certsDirAbs?: string;
+    now?: Date;
+}): Promise<CertificateLookupResult>;
+export declare function createSelfSignedCertificate(params: {
+    host?: string;
+    altHosts?: readonly string[];
+    days?: number;
+    certsDirAbs?: string;
+    force?: boolean;
+}): Promise<CreatedSelfSignedCertificate>;