jishushell 0.4.10 → 0.4.17

package/dist/services/app-compiler.js

@@ -0,0 +1,169 @@
+export function parseCpuToMHz(cpu) {
+    if (!cpu)
+        return 500;
+    if (cpu.endsWith("m")) {
+        const n = parseInt(cpu.slice(0, -1), 10);
+        if (isNaN(n))
+            throw new Error(`Invalid CPU format: ${cpu}`);
+        return n;
+    }
+    const n = parseFloat(cpu);
+    if (isNaN(n))
+        throw new Error(`Invalid CPU format: ${cpu}`);
+    return Math.round(n * 1000);
+}
+export function parseMemoryToMB(memory) {
+    if (!memory)
+        return 512;
+    if (memory.endsWith("Gi")) {
+        const n = parseInt(memory.slice(0, -2), 10);
+        if (isNaN(n))
+            throw new Error(`Invalid memory format: ${memory}`);
+        return n * 1024;
+    }
+    if (memory.endsWith("Mi")) {
+        const n = parseInt(memory.slice(0, -2), 10);
+        if (isNaN(n))
+            throw new Error(`Invalid memory format: ${memory}`);
+        return n;
+    }
+    if (memory.endsWith("G")) {
+        const n = parseInt(memory.slice(0, -1), 10);
+        if (isNaN(n))
+            throw new Error(`Invalid memory format: ${memory}`);
+        return n * 1024;
+    }
+    if (memory.endsWith("M")) {
+        const n = parseInt(memory.slice(0, -1), 10);
+        if (isNaN(n))
+            throw new Error(`Invalid memory format: ${memory}`);
+        return n;
+    }
+    const n = parseInt(memory, 10);
+    if (isNaN(n))
+        throw new Error(`Invalid memory format: ${memory}`);
+    return n;
+}
+/** Parse interval strings like "10s", "1m" into nanoseconds (Nomad unit) */
+function parseIntervalNs(s) {
+    if (!s)
+        return 10_000_000_000; // 10s default
+    if (s.endsWith("ms"))
+        return parseInt(s) * 1_000_000;
+    if (s.endsWith("s"))
+        return parseInt(s) * 1_000_000_000;
+    if (s.endsWith("m"))
+        return parseInt(s) * 60_000_000_000;
+    return parseInt(s) * 1_000_000_000;
+}
+/** Compile AppTask ports → Nomad network port mappings */
+export function compilePorts(ports) {
+    if (!ports || ports.length === 0)
+        return [];
+    return ports.map((p) => ({
+        Label: p.name,
+        Value: p.port,
+        To: p.port,
+    }));
+}
+/** Compile AppTask health → Nomad service check */
+export function compileHealthCheck(health, taskName) {
+    if (!health)
+        return null;
+    if (health.http) {
+        return {
+            Name: `${taskName || "service"}-health`,
+            Type: "http",
+            Path: health.http.path,
+            PortLabel: String(health.http.port),
+            Interval: parseIntervalNs(health.interval || "10s"),
+            Timeout: parseIntervalNs(health.timeout || "2s"),
+        };
+    }
+    return null;
+}
+/** Map AppTask role → Nomad lifecycle hook */
+export function compileLifecycle(role) {
+    switch (role) {
+        case "init":
+            return { Hook: "prestart", Sidecar: false };
+        case "sidecar":
+            return { Hook: "prestart", Sidecar: true };
+        case "cleanup":
+            return { Hook: "poststop", Sidecar: false };
+        default: // "service" — main task, no lifecycle hook
+            return null;
+    }
+}
+export function compileTaskRuntime(task, instanceId) {
+    return {
+        command: task.command || "/usr/bin/openclaw",
+        args: task.args || [],
+        cwd: "/",
+        user: "root",
+        env_files: [],
+        env: task.env || {},
+        image: task.image || null,
+        resources: {
+            CPU: parseCpuToMHz(task.resources?.cpu),
+            MemoryMB: parseMemoryToMB(task.resources?.memory),
+        },
+    };
+}
+/**
+ * Compile a full AppSpec into a Nomad-compatible task group structure.
+ * Returns an array of Nomad task objects (to be placed inside TaskGroups[0].Tasks).
+ */
+export function compileAppToNomadTasks(spec, instanceId) {
+    const tasks = [];
+    // Sort tasks by role precedence: init → sidecar → service → cleanup
+    const roleOrder = { init: 0, sidecar: 1, service: 2, cleanup: 3 };
+    const sorted = [...spec.tasks].sort((a, b) => (roleOrder[a.role] ?? 2) - (roleOrder[b.role] ?? 2));
+    for (const task of sorted) {
+        const compiled = {
+            Name: task.name,
+            Driver: task.runtime === "container" ? "docker" : "raw_exec",
+            Config: {},
+            Env: { ...task.env },
+            Resources: {
+                CPU: parseCpuToMHz(task.resources?.cpu),
+                MemoryMB: parseMemoryToMB(task.resources?.memory),
+            },
+        };
+        // Driver-specific config
+        if (task.runtime === "container") {
+            compiled.Config.image = task.image;
+            if (task.command)
+                compiled.Config.command = task.command;
+            if (task.args?.length)
+                compiled.Config.args = task.args;
+            // Port mappings for Docker
+            const ports = compilePorts(task.ports);
+            if (ports.length > 0) {
+                compiled.Config.ports = ports.map((p) => p.Label);
+            }
+        }
+        else {
+            // raw_exec (process runtime)
+            compiled.Config.command = task.command || "/usr/bin/openclaw";
+            if (task.args?.length)
+                compiled.Config.args = task.args;
+        }
+        // Lifecycle for non-service tasks
+        const lifecycle = compileLifecycle(task.role);
+        if (lifecycle)
+            compiled.Lifecycle = lifecycle;
+        // Health check → Nomad service block
+        const check = compileHealthCheck(task.health, task.name);
+        if (check) {
+            compiled.Services = [{
+                    Name: `${instanceId}-${task.name}`,
+                    PortLabel: check.PortLabel,
+                    Checks: [check],
+                }];
+        }
+        tasks.push(compiled);
+    }
+    return tasks;
+}
+//# sourceMappingURL=app-compiler.js.map

package/dist/services/app-compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-compiler.js","sourceRoot":"","sources":["../../src/services/app-compiler.ts"],"names":[],"mappings":"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"}

package/dist/services/app-manager.d.ts

@@ -0,0 +1,17 @@
+import type { AppManifest, AppSpec } from "../types.js";
+export declare function installApp(specYaml: string): Promise<{
+    spec: AppSpec;
+    manifest: AppManifest;
+}>;
+export declare function listApps(): Array<{
+    spec: AppSpec;
+    manifest: AppManifest;
+}>;
+export declare function getApp(id: string): {
+    spec: AppSpec;
+    manifest: AppManifest;
+} | null;
+export declare function uninstallApp(id: string): void;
+export declare function registerCapabilities(instanceId: string, spec: AppSpec, port: number): void;
+export declare function unregisterCapabilities(instanceId: string): void;
+export declare function resolveRequires(spec: AppSpec): Record<string, string>;

package/dist/services/app-manager.js

@@ -0,0 +1,168 @@
+import { createHash } from "crypto";
+import { existsSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { join } from "path";
+import { parse } from "yaml";
+import { APPS_DIR } from "../config.js";
+import { ensureDirHost } from "../utils/fs.js";
+import { safeReadJson, safeWriteJson } from "../utils/safe-json.js";
+const DOCKER_IMAGE_RE = /^[a-zA-Z0-9][a-zA-Z0-9\-_.:/@]*$/;
+const APP_ID_RE = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const REGISTRY_PATH = join(APPS_DIR, "capability-registry.json");
+function readRegistry() {
+    const reg = safeReadJson(REGISTRY_PATH, "capability-registry");
+    return reg ?? { capabilities: {} };
+}
+function writeRegistry(reg) {
+    ensureDirHost(APPS_DIR);
+    safeWriteJson(REGISTRY_PATH, reg, true);
+}
+export async function installApp(specYaml) {
+    let spec;
+    try {
+        spec = parse(specYaml);
+    }
+    catch (e) {
+        throw new Error(`YAML 解析失败: ${e.message}`);
+    }
+    if (!spec || !spec.id || !APP_ID_RE.test(spec.id)) {
+        throw new Error(`App id '${spec?.id}' 格式无效，必须符合 /^[a-z0-9][a-z0-9-]{0,62}$/`);
+    }
+    if (!Array.isArray(spec.tasks) || spec.tasks.length === 0) {
+        throw new Error("tasks 不能为空");
+    }
+    const hasService = spec.tasks.some((t) => t.role === "service");
+    if (!hasService) {
+        throw new Error("tasks 中至少需要一个 role 为 'service' 的任务");
+    }
+    for (const task of spec.tasks) {
+        if (task.runtime === "vm") {
+            throw new Error(`runtime 'vm' 暂不支持，请使用 runtime: container 或 process`);
+        }
+        if (task.runtime === "container" && !task.image) {
+            throw new Error(`container task '${task.name}' 需要指定 image 字段`);
+        }
+        if (task.runtime === "process" && !task.command) {
+            throw new Error(`process task '${task.name}' 需要指定 command 字段`);
+        }
+        if (task.image && !DOCKER_IMAGE_RE.test(task.image)) {
+            throw new Error(`task '${task.name}' 的 image '${task.image}' 格式无效`);
+        }
+    }
+    const appDir = join(APPS_DIR, spec.id);
+    const manifestPath = join(appDir, "manifest.json");
+    if (existsSync(manifestPath)) {
+        const err = new Error(`App '${spec.id}' 已安装，如需更新请先卸载`);
+        err.code = 409;
+        throw err;
+    }
+    ensureDirHost(appDir);
+    const yamlPath = join(appDir, "app-spec.yaml");
+    const yamlTmp = yamlPath + ".tmp";
+    writeFileSync(yamlTmp, specYaml, { mode: 0o644 });
+    renameSync(yamlTmp, yamlPath);
+    const manifest = {
+        id: spec.id,
+        installed_at: new Date().toISOString(),
+        spec_hash: createHash("sha256").update(specYaml).digest("hex"),
+    };
+    safeWriteJson(manifestPath, manifest, true);
+    return { spec, manifest };
+}
+export function listApps() {
+    if (!existsSync(APPS_DIR))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(APPS_DIR, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const results = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const appId = entry.name;
+        const appDir = join(APPS_DIR, appId);
+        try {
+            const yamlPath = join(appDir, "app-spec.yaml");
+            const manifestPath = join(appDir, "manifest.json");
+            if (!existsSync(yamlPath) || !existsSync(manifestPath))
+                continue;
+            const spec = parse(readFileSync(yamlPath, "utf-8"));
+            const manifest = safeReadJson(manifestPath, `app:${appId}`);
+            if (!manifest)
+                continue;
+            results.push({ spec, manifest });
+        }
+        catch (e) {
+            console.warn(`[app-manager] Skipping app '${appId}': ${e.message}`);
+        }
+    }
+    return results;
+}
+export function getApp(id) {
+    if (!APP_ID_RE.test(id))
+        return null;
+    const appDir = join(APPS_DIR, id);
+    const yamlPath = join(appDir, "app-spec.yaml");
+    const manifestPath = join(appDir, "manifest.json");
+    if (!existsSync(yamlPath) || !existsSync(manifestPath))
+        return null;
+    try {
+        const spec = parse(readFileSync(yamlPath, "utf-8"));
+        const manifest = safeReadJson(manifestPath, `app:${id}`);
+        if (!manifest)
+            return null;
+        return { spec, manifest };
+    }
+    catch {
+        return null;
+    }
+}
+export function uninstallApp(id) {
+    if (!APP_ID_RE.test(id))
+        return;
+    rmSync(join(APPS_DIR, id), { recursive: true, force: true });
+}
+export function registerCapabilities(instanceId, spec, port) {
+    if (!spec.provides || spec.provides.length === 0)
+        return;
+    const reg = readRegistry();
+    const now = new Date().toISOString();
+    for (const provide of spec.provides) {
+        reg.capabilities[provide.capability] = {
+            instanceId,
+            hostPort: port,
+            address: `127.0.0.1:${port}`,
+            registered_at: now,
+        };
+    }
+    writeRegistry(reg);
+}
+export function unregisterCapabilities(instanceId) {
+    const reg = readRegistry();
+    for (const key of Object.keys(reg.capabilities)) {
+        if (reg.capabilities[key].instanceId === instanceId) {
+            delete reg.capabilities[key];
+        }
+    }
+    writeRegistry(reg);
+}
+export function resolveRequires(spec) {
+    if (!spec.requires || spec.requires.length === 0)
+        return {};
+    const reg = readRegistry();
+    const result = {};
+    for (const req of spec.requires) {
+        const entry = reg.capabilities[req.capability];
+        if (entry) {
+            result[req.inject_as] = entry.address;
+        }
+        else if (req.required !== false) {
+            throw new Error(`Required capability '${req.capability}' is not registered`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=app-manager.js.map

package/dist/services/app-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-manager.js","sourceRoot":"","sources":["../../src/services/app-manager.ts"],"names":[],"mappings":"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"}

package/dist/services/instance-manager.d.ts

@@ -1,6 +1,30 @@
+import type { AppSpec } from "../types.js";
 type ConfigChangeListener = (instanceId: string) => void;
 export declare function onConfigChange(listener: ConfigChangeListener): () => void;
 declare function instanceDir(instanceId: string): string;
+/**
+ * Probes whether a port is currently held by any process on the host.
+ *
+ * Binds `0.0.0.0:port` — under the Linux default socket semantics, this fails
+ * with EADDRINUSE whenever another listener holds the port on `0.0.0.0`, on
+ * any specific interface (e.g. `127.0.0.1`), or via Docker's published port
+ * map. An IPv6-only listener on `::1` is not detected, but that edge case
+ * never comes up in the Nomad+Docker path this project uses.
+ */
+export declare function isPortInUse(port: number): Promise<boolean>;
+/**
+ * Result of {@link allocateGatewayPort}.
+ *
+ * `skipped` is the ordered list of ports we walked past because they were
+ * already configured on another instance, already pending for a concurrent
+ * allocation, or held by a real listener on the host. When non-empty it
+ * means the default port was taken and the caller can surface a toast to
+ * the user explaining the shift.
+ */
+export type GatewayPortAllocation = {
+    port: number;
+    skipped: number[];
+};
 export declare function getResolvedOpenclawBin(): string;
 /**
  * When jishushell runs as root (e.g. systemd service), returns the actual
@@ -40,17 +64,17 @@ export declare function isChannelPluginInstalled(instanceId: string, channelId:
 export declare function installChannelPlugin(instanceId: string, channelId: string): Promise<void>;
 export declare function listInstances(): Record<string, any>[];
 export declare function getInstance(instanceId: string): Record<string, any> | null;
-export declare function createInstance(instanceId: string, name: string, description?: string, cloneFrom?: string, openclawHome?: string, cloneOptions?: {
+export declare function createInstance(instanceId: string, name: string, description?: string, cloneFrom?: string, openclawHome?: string, appSpec?: AppSpec, cloneOptions?: {
     include_sessions?: boolean;
     include_memory?: boolean;
 }): Promise<Record<string, any>>;
 export declare function updateInstance(instanceId: string, name?: string, description?: string): Record<string, any> | null;
 /** Update instance.json metadata fields (shallow merge at top level). */
 export declare function updateInstanceMeta(instanceId: string, patch: Record<string, any>): void;
-export declare function deleteInstance(instanceId: string, purgeBackups?: boolean): {
+export declare function deleteInstance(instanceId: string, purgeBackups?: boolean): Promise<{
     ok: boolean;
     warnings?: string[];
-};
+}>;
 export declare function getConfig(instanceId: string): Record<string, any> | null;
 export declare function getStoredConfig(instanceId: string): Record<string, any> | null;
 export declare function saveConfig(instanceId: string, config: Record<string, any>): boolean;
@@ -81,7 +105,31 @@ export declare function getInstanceRuntime(instanceId: string): Record<string, a
 export declare function getRuntimeEnvFiles(instanceId: string): string[];
 export declare function getGatewayPort(instanceId: string): number;
 export declare function getGatewayHost(instanceId: string): Promise<string>;
+/**
+ * Wrap an IPv6 literal in brackets for safe URL host-component / Host-header
+ * use. Bare names ("gateway.local") and IPv4 ("127.0.0.1") contain no colon
+ * and pass through unchanged; anything with a colon is an IPv6 literal and
+ * MUST be bracketed before being concatenated with a port, otherwise
+ * `http://::1:18789/` is unparseable.
+ */
+export declare function urlHost(host: string): string;
 export declare function findInstancesSharingOpenclawHome(instanceId: string): string[];
+/**
+ * Re-pick a gateway port for an existing instance and rewrite its persisted
+ * runtime metadata (`runtime.args` and `runtime.env.OPENCLAW_GATEWAY_PORT`).
+ *
+ * Used when {@link isPortInUse} reports that the previously-assigned port has
+ * been taken by something else between create-time and start-time (e.g. a
+ * host-side openclaw started by the user, an unrelated service that grabbed
+ * the port at boot, or a Docker race on the next allocation). The Nomad job
+ * spec is rebuilt from instance metadata on every submit, so updating
+ * `instance.json` here is sufficient — no other files need patching.
+ */
+export declare function reallocateGatewayPort(instanceId: string): Promise<{
+    from: number;
+    to: number;
+    skipped: number[];
+}>;
 export declare function findInstancesSharingGatewayPort(instanceId: string): string[];
 export declare function getRuntimeEnv(instanceId: string): Record<string, string>;
 export { instanceDir as getInstanceDir };