dominds 1.4.2 → 1.5.2

package/README.md

@@ -107,6 +107,30 @@ Notes:
 - `npx dominds` does **not** necessarily mean “always latest”: if your project already has `dominds` installed, or your npm cache already contains an older version, `npx` may reuse that.
 - If you want “resolve whatever `latest` points to”, use `dominds@latest` explicitly. It may still reuse the cached copy of that same version (expected).
 
+### Installing Dominds apps
+
+Installing the `dominds` CLI itself and installing a **Dominds app** into your current rtws are two different operations:
+
+- `npm install -g dominds` / `pnpm add -g dominds`: install the Dominds CLI.
+- `npx -y dominds@latest`: run the Dominds CLI without a global install.
+- `dominds install <app>`: add a Dominds app into the current rtws capability graph.
+
+Examples:
+
+```bash
+# Install a published app into the current rtws
+dominds install @longrun-ai/web-dev --enable
+
+# Install a local app under development into the current rtws
+dominds install ./dominds-apps/web-dev --local --enable
+```
+
+Important distinctions:
+
+- `npm install` / `pnpm add` only download packages; they do **not** register an app into `.minds/app.yaml` for the current rtws.
+- `npx` is used by the kernel/CLI as a package-execution backend. For app installation, the kernel may execute `npx -y <pkg> --dominds-app` under the hood.
+- `--dominds-app` is a low-level app handshake flag between the kernel/CLI and the app package. It is not the normal end-user interface.
+
 For development and any sort of open source contribution, use the in-tree dev wrapper rtws:
 
 https://github.com/longrun-ai/dominds-feat-dev

package/README.zh.md

@@ -62,6 +62,30 @@ npx -y dominds@latest
 - 仅写 `npx dominds` **不一定**会自动跑“最新版”：如果你本地项目已安装了 `dominds`，或 npm cache 已存在旧版本，`npx` 可能会直接复用已有版本。
 - 想要“每次都按 latest 标签解析版本”，请显式写 `dominds@latest`；它仍可能复用 cache 中已下载的同版本（属于正常行为）。
 
+### 安装 Dominds app
+
+安装 `dominds` CLI 本体，和把一个 **Dominds app** 装进当前 rtws，是两件不同的事：
+
+- `npm install -g dominds` / `pnpm add -g dominds`：安装 Dominds CLI。
+- `npx -y dominds@latest`：无需全局安装，直接运行 Dominds CLI。
+- `dominds install <app>`：把一个 Dominds app 纳入当前 rtws 的能力图。
+
+示例：
+
+```bash
+# 安装已发布 app 到当前 rtws
+dominds install @longrun-ai/web-dev --enable
+
+# 安装本地开发中的 app 到当前 rtws
+dominds install ./dominds-apps/web-dev --local --enable
+```
+
+几个关键区别：
+
+- `npm install` / `pnpm add` 只负责下载包；它们**不会**自动把 app 登记到当前 rtws 的 `.minds/app.yaml`。
+- `npx` 在这里主要是 Kernel/CLI 的包执行后端。安装 app 时，Kernel 可能会在底层执行 `npx -y <pkg> --dominds-app` 来做握手。
+- `--dominds-app` 是 Kernel/CLI 与 app 包之间的底层握手参数，不是普通用户的常规操作入口。
+
 ### 开发与贡献（树内工作流 / in-tree 工作流）
 
 若你计划为 Dominds 开源项目贡献代码，建议使用树内包装器（in-tree wrapper）运行时工作区（rtws）：

package/dist/apps/app-json.js

@@ -90,9 +90,27 @@ function parseDialogRunControlJson(v, at) {
         },
     };
 }
-function parseDomindsAppInstallJson(v) {
+function parseReminderOwnerJson(v, at) {
     if (!isRecord(v))
-        return { ok: false, errorText: 'Invalid app --json output: expected object' };
+        return { ok: false, errorText: `Invalid ${at}: expected object` };
+    const ref = asString(v['ref']);
+    if (!ref || ref.trim() === '')
+        return { ok: false, errorText: `Invalid ${at}.ref: required` };
+    const managedByTool = asString(v['managedByTool']) ?? undefined;
+    const updateExample = asString(v['updateExample']) ?? undefined;
+    return {
+        ok: true,
+        owner: {
+            ref,
+            managedByTool,
+            updateExample,
+        },
+    };
+}
+function parseDomindsAppInstallJson(v) {
+    if (!isRecord(v)) {
+        return { ok: false, errorText: 'Invalid app --dominds-app output: expected object' };
+    }
     const schemaVersion = v['schemaVersion'];
     if (schemaVersion !== 1) {
         return { ok: false, errorText: `Unsupported app json schemaVersion: ${String(schemaVersion)}` };
@@ -189,7 +207,24 @@ function parseDomindsAppInstallJson(v) {
                 dialogRunControls.push(parsed.control);
             }
         }
-        contributes = { teammatesYamlRelPath, toolsets, dialogRunControls };
+        const reminderOwnersRaw = contributesRaw['reminderOwners'];
+        let reminderOwners;
+        if (reminderOwnersRaw !== undefined) {
+            if (!Array.isArray(reminderOwnersRaw)) {
+                return {
+                    ok: false,
+                    errorText: 'Invalid app json: contributes.reminderOwners must be an array',
+                };
+            }
+            reminderOwners = [];
+            for (let i = 0; i < reminderOwnersRaw.length; i += 1) {
+                const parsed = parseReminderOwnerJson(reminderOwnersRaw[i], `contributes.reminderOwners[${i}]`);
+                if (!parsed.ok)
+                    return parsed;
+                reminderOwners.push(parsed.owner);
+            }
+        }
+        contributes = { teammatesYamlRelPath, toolsets, dialogRunControls, reminderOwners };
     }
     return {
         ok: true,

package/dist/apps/dialog-run-controls.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.clearAppDialogRunControlsRegistry = clearAppDialogRunControlsRegistry;
 exports.registerAppDialogRunControl = registerAppDialogRunControl;
+exports.unregisterAppDialogRunControl = unregisterAppDialogRunControl;
 exports.getAppDialogRunControlMeta = getAppDialogRunControlMeta;
 exports.listAppDialogRunControls = listAppDialogRunControls;
 const runControlRegistry = new Map();
@@ -22,6 +23,9 @@ function registerAppDialogRunControl(params) {
         descriptionI18n: params.descriptionI18n,
     });
 }
+function unregisterAppDialogRunControl(id) {
+    runControlRegistry.delete(id);
+}
 function getAppDialogRunControlMeta(id) {
     const found = runControlRegistry.get(id);
     return found ?? null;

package/dist/apps/enabled-apps.js

@@ -62,9 +62,15 @@ function getResolutionHint(params) {
         `Default local root is 'dominds-apps' (rtws-relative) and expects local apps at '<root>/<appId>/'.`);
 }
 async function resolveLocalAppPackageRootAbs(params) {
+    const candidates = new Set();
+    if (params.previousResolutionEntry?.source.kind === 'local') {
+        candidates.add(params.previousResolutionEntry.source.pathAbs);
+    }
     for (const root of params.localRoots) {
         const rootAbs = node_path_1.default.isAbsolute(root) ? root : node_path_1.default.resolve(params.rtwsRootAbs, root);
-        const candidateAbs = node_path_1.default.resolve(rootAbs, params.appId);
+        candidates.add(node_path_1.default.resolve(rootAbs, params.appId));
+    }
+    for (const candidateAbs of candidates) {
         if (await dirExists(candidateAbs))
             return candidateAbs;
     }
@@ -101,6 +107,7 @@ async function probeAppByStrategy(params) {
                 rtwsRootAbs: params.rtwsRootAbs,
                 appId: params.appId,
                 localRoots: params.strategy.localRoots,
+                previousResolutionEntry: params.previousResolutionEntry,
             });
             if (!packageRootAbs)
                 continue;

package/dist/apps/installed-file.js

@@ -0,0 +1,207 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALLED_APPS_REL_PATH = void 0;
+exports.loadInstalledAppsFile = loadInstalledAppsFile;
+exports.writeInstalledAppsFile = writeInstalledAppsFile;
+exports.upsertInstalledApp = upsertInstalledApp;
+exports.removeInstalledApp = removeInstalledApp;
+exports.setAppEnabled = setAppEnabled;
+exports.setAppRuntimePort = setAppRuntimePort;
+exports.findInstalledApp = findInstalledApp;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const yaml_1 = __importDefault(require("yaml"));
+const time_1 = require("../shared/utils/time");
+exports.INSTALLED_APPS_REL_PATH = path_1.default.join('.apps', 'installed.yaml');
+function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function asString(v) {
+    return typeof v === 'string' ? v : null;
+}
+function asBool(v) {
+    return typeof v === 'boolean' ? v : null;
+}
+function asNullableNumber(v) {
+    if (v === null)
+        return null;
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    return null;
+}
+function parseSource(v, at) {
+    if (!isRecord(v))
+        return { ok: false, errorText: `Invalid ${at}: expected object` };
+    const kind = asString(v['kind']);
+    if (kind !== 'npx' && kind !== 'local') {
+        return { ok: false, errorText: `Invalid ${at}.kind: expected 'npx'|'local'` };
+    }
+    if (kind === 'npx') {
+        const spec = asString(v['spec']);
+        if (!spec || spec.trim() === '')
+            return { ok: false, errorText: `Invalid ${at}.spec: required` };
+        return { ok: true, source: { kind, spec } };
+    }
+    const pathAbs = asString(v['pathAbs']);
+    if (!pathAbs || pathAbs.trim() === '')
+        return { ok: false, errorText: `Invalid ${at}.pathAbs: required` };
+    return { ok: true, source: { kind, pathAbs } };
+}
+function parseRuntime(v, at) {
+    if (!isRecord(v))
+        return { ok: false, errorText: `Invalid ${at}: expected object` };
+    const portRaw = v['port'];
+    const port = asNullableNumber(portRaw);
+    if (port === null) {
+        if (portRaw !== null) {
+            return { ok: false, errorText: `Invalid ${at}.port: expected number|null` };
+        }
+        return { ok: true, runtime: { port: null } };
+    }
+    if (port < 0 || !Number.isInteger(port))
+        return { ok: false, errorText: `Invalid ${at}.port: expected non-negative integer|null` };
+    return { ok: true, runtime: { port: port } };
+}
+function parseEntry(v, at) {
+    if (!isRecord(v))
+        return { ok: false, errorText: `Invalid ${at}: expected object` };
+    const id = asString(v['id']);
+    if (!id || id.trim() === '')
+        return { ok: false, errorText: `Invalid ${at}.id: required` };
+    const enabled = asBool(v['enabled']);
+    if (enabled === null)
+        return { ok: false, errorText: `Invalid ${at}.enabled: boolean required` };
+    const installedAt = asString(v['installedAt']);
+    const updatedAt = asString(v['updatedAt']);
+    if (!installedAt || installedAt.trim() === '')
+        return { ok: false, errorText: `Invalid ${at}.installedAt: required` };
+    if (!updatedAt || updatedAt.trim() === '')
+        return { ok: false, errorText: `Invalid ${at}.updatedAt: required` };
+    const sourceParsed = parseSource(v['source'], `${at}.source`);
+    if (!sourceParsed.ok)
+        return sourceParsed;
+    const runtimeParsed = parseRuntime(v['runtime'] ?? { port: null }, `${at}.runtime`);
+    if (!runtimeParsed.ok)
+        return runtimeParsed;
+    // installJson is validated by install/update command on write. On read we keep permissive:
+    // kernel will fail fast later if it needs a missing field.
+    const installJson = v['installJson'];
+    if (!isRecord(installJson))
+        return { ok: false, errorText: `Invalid ${at}.installJson: expected object` };
+    return {
+        ok: true,
+        entry: {
+            id,
+            enabled,
+            source: sourceParsed.source,
+            runtime: runtimeParsed.runtime,
+            installJson: installJson,
+            installedAt,
+            updatedAt,
+        },
+    };
+}
+async function loadInstalledAppsFile(params) {
+    const filePathAbs = path_1.default.resolve(params.rtwsRootAbs, exports.INSTALLED_APPS_REL_PATH);
+    let raw;
+    try {
+        raw = await promises_1.default.readFile(filePathAbs, 'utf-8');
+    }
+    catch (err) {
+        const isEnoent = typeof err === 'object' &&
+            err !== null &&
+            'code' in err &&
+            err.code === 'ENOENT';
+        if (isEnoent) {
+            return { kind: 'ok', filePathAbs, file: { schemaVersion: 1, apps: [] } };
+        }
+        return {
+            kind: 'error',
+            filePathAbs,
+            errorText: err instanceof Error ? err.message : String(err),
+        };
+    }
+    let parsed;
+    try {
+        parsed = yaml_1.default.parse(raw);
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            filePathAbs,
+            errorText: `Failed to parse YAML: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!isRecord(parsed)) {
+        return { kind: 'error', filePathAbs, errorText: 'Invalid installed.yaml: expected object' };
+    }
+    const schemaVersion = parsed['schemaVersion'];
+    if (schemaVersion !== 1) {
+        return {
+            kind: 'error',
+            filePathAbs,
+            errorText: `Unsupported schemaVersion: ${String(schemaVersion)}`,
+        };
+    }
+    const appsRaw = parsed['apps'];
+    if (!Array.isArray(appsRaw)) {
+        return {
+            kind: 'error',
+            filePathAbs,
+            errorText: 'Invalid installed.yaml: apps must be an array',
+        };
+    }
+    const apps = [];
+    for (let i = 0; i < appsRaw.length; i += 1) {
+        const e = parseEntry(appsRaw[i], `apps[${i}]`);
+        if (!e.ok)
+            return { kind: 'error', filePathAbs, errorText: e.errorText };
+        apps.push(e.entry);
+    }
+    return { kind: 'ok', filePathAbs, file: { schemaVersion: 1, apps } };
+}
+async function writeInstalledAppsFile(params) {
+    const dirAbs = path_1.default.resolve(params.rtwsRootAbs, '.apps');
+    await promises_1.default.mkdir(dirAbs, { recursive: true });
+    const filePathAbs = path_1.default.resolve(params.rtwsRootAbs, exports.INSTALLED_APPS_REL_PATH);
+    const yamlText = yaml_1.default.stringify(params.file);
+    await promises_1.default.writeFile(filePathAbs, yamlText, 'utf-8');
+}
+function upsertInstalledApp(params) {
+    const apps = [...params.existing.apps];
+    const idx = apps.findIndex((a) => a.id === params.next.id);
+    if (idx >= 0) {
+        apps[idx] = params.next;
+    }
+    else {
+        apps.push(params.next);
+    }
+    return { schemaVersion: 1, apps };
+}
+function removeInstalledApp(params) {
+    return { schemaVersion: 1, apps: params.existing.apps.filter((a) => a.id !== params.appId) };
+}
+function setAppEnabled(params) {
+    const now = (0, time_1.formatUnifiedTimestamp)(new Date());
+    const apps = params.existing.apps.map((a) => a.id === params.appId ? { ...a, enabled: params.enabled, updatedAt: now } : a);
+    return { schemaVersion: 1, apps };
+}
+function setAppRuntimePort(params) {
+    const existingApp = findInstalledApp(params.existing, params.appId);
+    if (!existingApp)
+        return params.existing;
+    if (existingApp.runtime.port === params.port)
+        return params.existing;
+    const now = (0, time_1.formatUnifiedTimestamp)(new Date());
+    const apps = params.existing.apps.map((a) => a.id === params.appId
+        ? { ...a, runtime: { ...a.runtime, port: params.port }, updatedAt: now }
+        : a);
+    return { schemaVersion: 1, apps };
+}
+function findInstalledApp(file, appId) {
+    const found = file.apps.find((a) => a.id === appId);
+    return found ?? null;
+}

package/dist/apps/run-app-json.js

@@ -61,26 +61,26 @@ function parseAppJsonFromStdout(stdout, where) {
     return res.json;
 }
 async function runDomindsAppJsonViaNpx(params) {
-    const { stdout, stderr } = await execFileAsync('npx', ['-y', params.spec, '--json'], {
+    const { stdout, stderr } = await execFileAsync('npx', ['-y', params.spec, '--dominds-app'], {
         cwd: params.cwdAbs,
         env: process.env,
         maxBuffer: 10 * 1024 * 1024,
     });
     if (stderr.trim() !== '') {
         // Loud: stderr indicates non-JSON noise that would break parsing determinism.
-        throw new Error(`App printed to stderr during --json handshake (spec=${params.spec}):\n${stderr}`);
+        throw new Error(`App printed to stderr during --dominds-app handshake (spec=${params.spec}):\n${stderr}`);
     }
-    return parseAppJsonFromStdout(stdout, `npx ${params.spec} --json`);
+    return parseAppJsonFromStdout(stdout, `npx ${params.spec} --dominds-app`);
 }
 async function runDomindsAppJsonViaLocalPackage(params) {
     const scriptAbs = await resolveLocalBinScriptAbs(params.packageRootAbs);
-    const { stdout, stderr } = await execFileAsync(process.execPath, [scriptAbs, '--json'], {
+    const { stdout, stderr } = await execFileAsync(process.execPath, [scriptAbs, '--dominds-app'], {
         cwd: params.packageRootAbs,
         env: process.env,
         maxBuffer: 10 * 1024 * 1024,
     });
     if (stderr.trim() !== '') {
-        throw new Error(`Local app printed to stderr during --json handshake (path=${params.packageRootAbs}):\n${stderr}`);
+        throw new Error(`Local app printed to stderr during --dominds-app handshake (path=${params.packageRootAbs}):\n${stderr}`);
     }
-    return parseAppJsonFromStdout(stdout, `local ${params.packageRootAbs} --json`);
+    return parseAppJsonFromStdout(stdout, `local ${params.packageRootAbs} --dominds-app`);
 }

package/dist/apps/runtime-port.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveStableAppRuntimePort = resolveStableAppRuntimePort;
+const node_net_1 = __importDefault(require("node:net"));
+const STABLE_PORT_RANGE_START = 43000;
+const STABLE_PORT_RANGE_END = 49999;
+const PORT_MAX = 65535;
+function isPositivePort(value) {
+    return (typeof value === 'number' &&
+        Number.isInteger(value) &&
+        value > 0 &&
+        value <= PORT_MAX &&
+        Number.isFinite(value));
+}
+function hashAppId(appId) {
+    // FNV-1a 32-bit hash for deterministic port probing order.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < appId.length; i += 1) {
+        hash ^= appId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+function collectReservedPorts(existingApps, appId) {
+    const reserved = new Set();
+    for (const app of existingApps) {
+        if (app.id === appId)
+            continue;
+        if (isPositivePort(app.runtime.port)) {
+            reserved.add(app.runtime.port);
+        }
+    }
+    return reserved;
+}
+async function canBindPort(port) {
+    return await new Promise((resolve) => {
+        const server = node_net_1.default.createServer();
+        server.unref();
+        const finish = (ok) => {
+            server.removeAllListeners('error');
+            server.removeAllListeners('listening');
+            resolve(ok);
+        };
+        server.once('error', () => {
+            finish(false);
+        });
+        server.once('listening', () => {
+            server.close(() => finish(true));
+        });
+        server.listen({ host: '127.0.0.1', port, exclusive: true });
+    });
+}
+async function pickDeterministicAvailablePort(params) {
+    const rangeSize = STABLE_PORT_RANGE_END - STABLE_PORT_RANGE_START + 1;
+    if (rangeSize <= 0) {
+        throw new Error('Invalid stable app runtime port range configuration');
+    }
+    const baseHash = hashAppId(params.appId);
+    for (let i = 0; i < rangeSize; i += 1) {
+        const candidate = STABLE_PORT_RANGE_START + ((baseHash + i) % rangeSize);
+        if (params.reservedPorts.has(candidate))
+            continue;
+        if (await canBindPort(candidate))
+            return candidate;
+    }
+    throw new Error(`Failed to allocate stable runtime port for app '${params.appId}': no bindable port in ${STABLE_PORT_RANGE_START}-${STABLE_PORT_RANGE_END}`);
+}
+async function resolveStableAppRuntimePort(params) {
+    if (!params.installJson.frontend)
+        return null;
+    const reservedPorts = collectReservedPorts(params.existingApps, params.appId);
+    if (isPositivePort(params.existingRuntimePort)) {
+        if (reservedPorts.has(params.existingRuntimePort)) {
+            throw new Error(`Invalid installed apps state: runtime port ${params.existingRuntimePort} for '${params.appId}' collides with another installed app`);
+        }
+        return params.existingRuntimePort;
+    }
+    const defaultPort = params.installJson.frontend.defaultPort;
+    if (isPositivePort(defaultPort) &&
+        !reservedPorts.has(defaultPort) &&
+        (await canBindPort(defaultPort))) {
+        return defaultPort;
+    }
+    return await pickDeterministicAvailablePort({
+        appId: params.appId,
+        reservedPorts,
+    });
+}