dsh-m 0.0.3 → 0.1.1

package/lib/core/market.js

@@ -0,0 +1,198 @@
+/**
+ * 市场编排层：registry × profile × 最新版本 → 市场列表 / 已装列表 / outdated /
+ * 安装 / 卸载 / 升级。安装语义见 DESIGN.md §3（npm 精确锁定、GitHub 锁 SHA）。
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { addDshPlugin } from './dsh-cli.js';
+import { dshHome, webProfileDir } from './env.js';
+import { listInstalledPlugins, readProfileDeps, removeInstalledPlugin, } from './installed.js';
+import { setLivePluginDisabled } from './live-plugin.js';
+import { loadRegistry } from './registry.js';
+import { githubLatestTag, isNewerVersion, npmLatest } from './versions.js';
+function matchInstalledByEntry(entry, installed) {
+    return installed.find((it) => {
+        if (entry.npm && it.pkg === entry.npm)
+            return true;
+        if (entry.npm && it.name === entry.npm)
+            return true;
+        if (entry.github && it.source === 'github') {
+            const m = /^github:([^#]+)/.exec(it.spec);
+            if (m && m[1] === entry.github)
+                return true;
+        }
+        return false;
+    });
+}
+export async function listMarket(cfg = {}, opts = {}) {
+    const [loaded, installed] = await Promise.all([
+        loadRegistry(cfg, opts),
+        listInstalledPlugins(),
+    ]);
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const items = [];
+    for (const entry of loaded.registry.plugins) {
+        const inst = matchInstalledByEntry(entry, installed.items);
+        const item = {
+            ...entry,
+            installed: Boolean(inst),
+            outdated: false,
+        };
+        if (inst) {
+            item.installedPkg = inst.pkg;
+            item.installedVersion = inst.version;
+        }
+        try {
+            if (entry.source === 'npm' && entry.npm) {
+                const latest = await npmLatest(entry.npm, timeoutMs);
+                item.latestVersion = latest.version;
+                if (inst?.version && isNewerVersion(latest.version, inst.version))
+                    item.outdated = true;
+            }
+            else if (entry.github) {
+                const { tag, sha } = await githubLatestTag(entry.github, timeoutMs);
+                item.latestTag = tag;
+                item.latestSha = sha;
+                if (inst && !inst.spec.includes(sha))
+                    item.outdated = true;
+            }
+        }
+        catch (err) {
+            item.latestError = err instanceof Error ? err.message : String(err);
+        }
+        items.push(item);
+    }
+    return {
+        items,
+        registrySource: loaded.source,
+        registryFetchedAt: loaded.fetchedAt,
+        registryErrors: loaded.errors,
+    };
+}
+export async function listInstalledWithMeta(cfg = {}) {
+    const [{ items: installed, others, profileDir }, loaded] = await Promise.all([
+        listInstalledPlugins(),
+        loadRegistry(cfg),
+    ]);
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const items = [];
+    for (const it of installed) {
+        const entry = loaded.registry.plugins.find((e) => matchInstalledByEntry(e, [it]));
+        const item = { ...it, outdated: false };
+        if (entry) {
+            item.registryId = entry.id;
+            item.registryGithub = entry.github ?? null;
+            item.registryIcon = entry.icon ?? null;
+        }
+        try {
+            if (!entry && it.source === 'npm') {
+                const latest = await npmLatest(it.pkg, timeoutMs);
+                item.latestVersion = latest.version;
+                item.outdated = isNewerVersion(latest.version, it.version);
+            }
+            else if (entry?.source === 'npm' && entry.npm) {
+                const latest = await npmLatest(entry.npm, timeoutMs);
+                item.latestVersion = latest.version;
+                item.outdated = isNewerVersion(latest.version, it.version);
+            }
+            else if (it.source === 'github') {
+                const m = /^github:([^#]+)/.exec(it.spec);
+                if (m) {
+                    const { tag, sha } = await githubLatestTag(m[1], timeoutMs);
+                    item.latestTag = tag;
+                    item.outdated = !it.spec.includes(sha);
+                }
+            }
+        }
+        catch {
+            /* 查询失败不阻塞列表，outdated 维持 false */
+        }
+        items.push(item);
+    }
+    return { items, others, profileDir };
+}
+/** 从 registry 收录条目安装（npm → 精确锁定最新版；github → 锁 HEAD SHA）。 */
+export async function installFromRegistry(id, cfg = {}, opts = {}) {
+    const { registry } = await loadRegistry(cfg);
+    const entry = registry.plugins.find((e) => e.id === id);
+    if (!entry)
+        throw new Error(`registry 中没有该条目: ${id}`);
+    return installEntry(entry, cfg, opts);
+}
+export async function installEntry(entry, cfg = {}, opts = {}) {
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    if (entry.source === 'npm' && entry.npm) {
+        const version = opts.version && /^\d+\.\d+\.\d+/.test(opts.version) ? opts.version : (await npmLatest(entry.npm, timeoutMs)).version;
+        const spec = `${entry.npm}@${version}`;
+        const res = await addDshPlugin(spec);
+        // 安装后校验：落盘版本必须与意图一致（tarball 完整性由 pnpm 按 lock integrity 保证）
+        const deps = await readProfileDeps(webProfileDir());
+        const specInProfile = deps[entry.npm];
+        if (specInProfile === undefined)
+            throw new Error(`安装后未在 profile 依赖中找到 ${entry.npm}`);
+        return {
+            id: entry.id,
+            pkg: entry.npm,
+            spec,
+            version,
+            usedAllowAllBuilds: res.usedAllowAllBuilds,
+            needsRestart: true,
+            output: res.output.slice(-800),
+        };
+    }
+    if (entry.github) {
+        const { tag, sha } = await githubLatestTag(entry.github, timeoutMs);
+        const spec = `github:${entry.github}#${sha}`;
+        const res = await addDshPlugin(spec);
+        const deps = await readProfileDeps(webProfileDir());
+        const pkgKey = Object.keys(deps).find((k) => deps[k] === spec || deps[k].startsWith(`github:${entry.github}#`));
+        if (!pkgKey)
+            throw new Error(`安装后未在 profile 依赖中找到 ${entry.github}`);
+        return {
+            id: entry.id,
+            pkg: pkgKey,
+            spec,
+            sha,
+            usedAllowAllBuilds: res.usedAllowAllBuilds,
+            needsRestart: true,
+            output: res.output.slice(-800),
+        };
+    }
+    throw new Error(`条目 ${entry.id} 缺少可安装来源`);
+}
+/** 卸载：live-disable → pnpm remove → 报告疑似残留（DESIGN.md §3：删包不删数据）。 */
+export async function uninstallPlugin(pkg, _cfg = {}) {
+    const liveDisabled = await setLivePluginDisabled(pkg, true);
+    await removeInstalledPlugin(pkg);
+    return { pkg, liveDisabled, needsRestart: true, leftovers: leftoverCandidates(pkg) };
+}
+/** 升级 = 按最新重新安装（npm 拉最新精确版；github 重新锁 HEAD）。 */
+export async function upgradePlugin(pkg, cfg = {}) {
+    const { registry } = await loadRegistry(cfg);
+    const { items: installed } = await listInstalledPlugins();
+    const target = installed.find((it) => it.pkg === pkg);
+    if (!target)
+        throw new Error(`web profile 未安装该插件: ${pkg}`);
+    const entry = registry.plugins.find((e) => matchInstalledByEntry(e, [target]));
+    if (!entry)
+        throw new Error(`「${pkg}」不是经 dsh-m 收录的插件；直接升级请用 dsh plugin update 或先在 registry 收录它`);
+    const result = await installEntry(entry, cfg);
+    return { ...result, fromVersion: target.version };
+}
+/** 变更互斥：安装/卸载/升级串行执行（skillhub install-lock 同款思路）。 */
+let mutationTail = Promise.resolve();
+export function withMutationLock(task) {
+    const next = mutationTail.then(task, task);
+    mutationTail = next.catch(() => undefined);
+    return next;
+}
+/** 疑似残留路径（存在才列出）：删包不删数据，只报告。 */
+export function leftoverCandidates(pkg) {
+    const home = dshHome();
+    const candidates = [
+        join(home, `${pkg}.json`),
+        join(home, pkg),
+        join(home, `${pkg.replace(/^@[^/]+\//, '')}.json`),
+    ];
+    return candidates.filter((p) => existsSync(p));
+}

package/lib/core/progress.js

@@ -0,0 +1,113 @@
+/**
+ * pnpm `--reporter=ndjson` 进度解析器。移植自 skillhub ndjson.ts（零依赖）。
+ * stdout 每行一个 JSON 对象；人类可读的回退行由 spawn 层处理。
+ */
+export function emptyProgress() {
+    return {
+        phase: null,
+        done: 0,
+        total: null,
+        currentPackage: null,
+        downloaded: null,
+        size: null,
+        seen: false,
+        error: null,
+    };
+}
+export function createProgressTracker() {
+    const snap = emptyProgress();
+    const seenPackages = new Set();
+    function dedupe(packageId) {
+        if (typeof packageId !== 'string' || packageId === '')
+            return;
+        if (!seenPackages.has(packageId)) {
+            seenPackages.add(packageId);
+            snap.done += 1;
+        }
+    }
+    function feed(line) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof event !== 'object' || event === null)
+            return;
+        const msg = event;
+        const name = msg.name;
+        if (typeof name !== 'string')
+            return;
+        if (name === 'pnpm:stage') {
+            const stage = msg.stage;
+            if (stage === 'resolution_started')
+                snap.phase = 'resolving';
+            else if (stage === 'resolution_done')
+                snap.phase = 'downloading';
+            else if (stage === 'importing_started' || stage === 'importing_done')
+                snap.phase = 'linking';
+            snap.seen = true;
+            return;
+        }
+        if (name === 'pnpm:progress') {
+            snap.seen = true;
+            const status = msg.status;
+            if (status === 'resolved') {
+                if (snap.phase === null)
+                    snap.phase = 'resolving';
+                dedupe(msg.packageId);
+            }
+            else if (status === 'fetched' || status === 'found_in_store') {
+                snap.phase = 'downloading';
+                snap.currentPackage = typeof msg.packageId === 'string' ? msg.packageId : snap.currentPackage;
+                dedupe(msg.packageId);
+            }
+            return;
+        }
+        if (name === 'pnpm:fetching-progress') {
+            snap.seen = true;
+            snap.phase = 'downloading';
+            if (typeof msg.packageId === 'string')
+                snap.currentPackage = msg.packageId;
+            if (typeof msg.size === 'number')
+                snap.size = msg.size;
+            if (typeof msg.downloaded === 'number')
+                snap.downloaded = msg.downloaded;
+            dedupe(msg.packageId);
+            return;
+        }
+        if (name === 'pnpm:lifecycle') {
+            snap.seen = true;
+            snap.phase = 'building';
+            const wd = typeof msg.wd === 'string' ? msg.wd : '';
+            const dep = typeof msg.depPath === 'string' ? msg.depPath : '';
+            const base = wd.split(/[\\/]/).filter(Boolean).pop();
+            snap.currentPackage = base ?? (dep !== '' ? dep : snap.currentPackage);
+            return;
+        }
+        if (name === 'pnpm:stats') {
+            if (msg.added !== undefined || msg.removed !== undefined)
+                snap.phase = 'linking';
+            snap.seen = true;
+            return;
+        }
+        if (name === 'pnpm' && msg.level === 'error') {
+            const err = (msg.err ?? {});
+            const message = typeof err.message === 'string' ? err.message : '';
+            if (message !== '')
+                snap.error = message.slice(0, 400);
+        }
+    }
+    function reset() {
+        seenPackages.clear();
+        Object.assign(snap, emptyProgress());
+    }
+    return {
+        get snapshot() {
+            return { ...snap };
+        },
+        feed,
+        reset,
+    };
+}

package/lib/core/registry.js

@@ -0,0 +1,167 @@
+/**
+ * registry（DESIGN.md §2）：repo 内手工 curated 的 registry.json。
+ * 分发顺序：源覆盖 → jsDelivr @main → raw @main → TTL 缓存 → 包内快照兜底。
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { cacheDir } from './env.js';
+import { fetchJsonLimited } from './httpx.js';
+export const CATEGORIES = ['market', 'tools', 'ui', 'search', 'media', 'other'];
+const REPO = 'iasiv5/dsh-m';
+// raw 优先：jsDelivr 对 @main 有 CDN 缓存（可 stale 数小时），raw 始终反映 main 最新内容；
+// jsDelivr 降为备用线路（可通过 purge.jsdelivr.net 手动清缓存）。
+const DEFAULT_URLS = [
+    { source: 'raw', url: `https://raw.githubusercontent.com/${REPO}/main/registry.json` },
+    { source: 'jsdelivr', url: `https://cdn.jsdelivr.net/gh/${REPO}@main/registry.json` },
+];
+// ---------- 校验 ----------
+const GITHUB_RE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[A-Za-z0-9._-]+$/;
+const HTTPS_URL_RE = /^https:\/\/\S+$/i;
+export function validateRegistry(raw) {
+    const errors = [];
+    if (!raw || typeof raw !== 'object')
+        return { ok: false, errors: ['registry 根必须是对象'], registry: null };
+    const obj = raw;
+    if (obj.version !== 1)
+        errors.push('version 必须为 1');
+    if (!Array.isArray(obj.plugins))
+        return { ok: false, errors: [...errors, 'plugins 必须是数组'], registry: null };
+    const plugins = [];
+    const seen = new Set();
+    obj.plugins.forEach((item, index) => {
+        const where = `plugins[${index}]`;
+        if (!item || typeof item !== 'object') {
+            errors.push(`${where}: 必须是对象`);
+            return;
+        }
+        const e = item;
+        const id = String(e.id || '').trim();
+        if (!id || id.length > 64)
+            return errors.push(`${where}.id 无效`);
+        if (seen.has(id))
+            return errors.push(`${where}.id 重复: ${id}`);
+        seen.add(id);
+        const category = String(e.category || '');
+        if (!CATEGORIES.includes(category))
+            return errors.push(`${where}.category 无效: ${category}`);
+        const source = String(e.source || '');
+        if (source !== 'npm' && source !== 'github')
+            return errors.push(`${where}.source 无效: ${source}`);
+        const entry = {
+            id,
+            name: String(e.name || id).trim().slice(0, 100),
+            description: String(e.description || '').trim().slice(0, 500),
+            category: category,
+            tags: Array.isArray(e.tags) ? e.tags.map((t) => String(t).trim().slice(0, 30)).filter(Boolean).slice(0, 10) : [],
+            source,
+        };
+        if (source === 'npm') {
+            const npm = String(e.npm || '').trim();
+            if (!npm)
+                return errors.push(`${where}.npm 必填（source=npm）`);
+            entry.npm = npm;
+        }
+        if (source === 'github') {
+            const gh = String(e.github || '').trim();
+            if (!GITHUB_RE.test(gh))
+                return errors.push(`${where}.github 必须是 owner/repo（source=github）`);
+            entry.github = gh;
+        }
+        if (e.npm && source !== 'npm')
+            entry.npm = String(e.npm).trim();
+        if (e.github && source !== 'github' && GITHUB_RE.test(String(e.github).trim()))
+            entry.github = String(e.github).trim();
+        for (const key of ['homepage', 'icon']) {
+            const v = e[key];
+            if (v === undefined || v === null || v === '')
+                continue;
+            const s = String(v).trim();
+            if (!HTTPS_URL_RE.test(s))
+                return errors.push(`${where}.${key} 必须是 https URL`);
+            entry[key] = s;
+        }
+        plugins.push(entry);
+    });
+    return { ok: errors.length === 0, errors, registry: errors.length === 0 ? { version: 1, plugins } : null };
+}
+// ---------- 包内快照兜底 ----------
+function bundledSnapshot() {
+    const require = createRequire(import.meta.url);
+    for (const rel of ['../registry.json', '../../registry.json']) {
+        try {
+            const raw = require(rel);
+            const parsed = validateRegistry(raw);
+            if (parsed.registry)
+                return parsed.registry;
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return { version: 1, plugins: [] };
+}
+function cachePath() {
+    return join(cacheDir(), 'registry.json');
+}
+function readCache() {
+    try {
+        const raw = JSON.parse(readFileSync(cachePath(), 'utf8'));
+        if (!raw || typeof raw !== 'object' || !raw.registry || !Array.isArray(raw.registry.plugins))
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(file) {
+    try {
+        mkdirSync(cacheDir(), { recursive: true });
+        writeFileSync(cachePath(), JSON.stringify(file, null, 2));
+    }
+    catch {
+        /* 缓存写失败不致命 */
+    }
+}
+function cacheFresh(file, ttlMin) {
+    const t = Date.parse(file.fetchedAt || '');
+    if (!Number.isFinite(t))
+        return false;
+    return Date.now() - t < ttlMin * 60_000;
+}
+// ---------- 加载 ----------
+export async function loadRegistry(cfg = {}, opts = {}) {
+    const errors = [];
+    const timeoutMs = cfg.timeoutMs ?? 20_000;
+    const ttlMin = Math.max(0, cfg.cacheTtlMin ?? 60);
+    const cached = readCache();
+    if (!opts.force && cached && cacheFresh(cached, ttlMin)) {
+        return { registry: cached.registry, source: 'cache', fetchedAt: cached.fetchedAt, errors };
+    }
+    const candidates = [];
+    if (cfg.registryUrl && cfg.registryUrl.trim()) {
+        candidates.push({ source: 'override', url: cfg.registryUrl.trim() });
+    }
+    candidates.push(...DEFAULT_URLS);
+    for (const candidate of candidates) {
+        try {
+            const raw = await fetchJsonLimited(candidate.url, { timeoutMs });
+            const parsed = validateRegistry(raw);
+            if (!parsed.ok || !parsed.registry) {
+                errors.push(`${candidate.source}: registry 校验失败 — ${parsed.errors.slice(0, 3).join('; ')}`);
+                continue;
+            }
+            const fetchedAt = new Date().toISOString();
+            writeCache({ fetchedAt, source: candidate.source, registry: parsed.registry });
+            return { registry: parsed.registry, source: candidate.source, fetchedAt, errors };
+        }
+        catch (err) {
+            const he = err;
+            errors.push(`${candidate.source}: ${he?.status ? `HTTP ${he.status}` : err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (cached)
+        return { registry: cached.registry, source: 'cache', fetchedAt: cached.fetchedAt, errors };
+    return { registry: bundledSnapshot(), source: 'bundled', fetchedAt: null, errors };
+}

package/lib/core/restart.js

@@ -0,0 +1,213 @@
+/**
+ * 自重启：移植自 skillhub restart.ts（tag→OIDC 同源的 dsh-web shim 环境已验证）。
+ * 优先 systemd 单元重启（本机 = deepseek-harness.service，dsh-web.service 为转发 shim）；
+ * 无 systemd 时退回 detached helper 等端口释放后换身重拉。
+ * 安全：restart 端点必须通过 trustedRestartRequest（Origin 与 Host 同源）。
+ */
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { dshArgv, nodeExecutable } from './dsh-cli.js';
+function headerString(raw) {
+    if (raw === undefined)
+        return undefined;
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    const trimmed = String(value || '').trim();
+    return trimmed === '' ? undefined : trimmed.split(',')[0].trim();
+}
+function parseHost(raw) {
+    try {
+        const parsed = new URL(raw.includes('://') ? raw : `http://${raw}`);
+        return { hostname: parsed.hostname.toLowerCase(), port: parsed.port };
+    }
+    catch {
+        return null;
+    }
+}
+function isLoopbackHost(host) {
+    const parsed = parseHost(host);
+    if (parsed === null)
+        return false;
+    return parsed.hostname === '127.0.0.1' || parsed.hostname === 'localhost' || parsed.hostname === '::1';
+}
+function hostsMatch(originHost, candidate) {
+    const a = parseHost(originHost);
+    const b = parseHost(candidate);
+    if (a === null || b === null)
+        return false;
+    if (a.hostname !== b.hostname)
+        return false;
+    if (a.port !== '' && b.port !== '' && a.port !== b.port)
+        return false;
+    return true;
+}
+export function servingPort(request) {
+    const host = headerString(request.headers.host);
+    if (host === undefined || !isLoopbackHost(host))
+        return null;
+    const match = /:(\d{1,5})$/u.exec(host);
+    if (match === null)
+        return null;
+    const port = Number(match[1]);
+    return Number.isInteger(port) && port > 0 && port < 65536 ? port : null;
+}
+export function trustedRestartRequest(request) {
+    const origin = headerString(request.headers.origin);
+    if (origin === undefined)
+        return false;
+    let from;
+    try {
+        const parsed = new URL(origin);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return false;
+        from = parsed.host;
+    }
+    catch {
+        return false;
+    }
+    const host = headerString(request.headers.host);
+    const forwardedHost = headerString(request.headers['x-forwarded-host']);
+    const candidates = [host, forwardedHost].filter((value) => value !== undefined);
+    return candidates.some((candidate) => hostsMatch(from, candidate));
+}
+export function readProcCgroup(readFile = (path, encoding) => readFileSync(path, encoding)) {
+    try {
+        return readFile('/proc/self/cgroup', 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+export function systemdUnitName(cgroupText) {
+    for (const line of cgroupText.split(/\r?\n/u)) {
+        if (line.trim() === '')
+            continue;
+        const path = line.includes(':') ? line.slice(line.lastIndexOf(':') + 1) : line;
+        const parts = path.split('/').filter(Boolean);
+        for (let i = parts.length - 1; i >= 0; i--) {
+            const part = parts[i];
+            if (!part.endsWith('.service'))
+                continue;
+            if (/^user@\d+\.service$/u.test(part))
+                continue;
+            return part;
+        }
+    }
+    return null;
+}
+export function systemdRestartArgv(opts) {
+    const unit = systemdUnitName(opts.cgroup);
+    if (unit === null)
+        return null;
+    if (opts.cgroup.includes('/user.slice/')) {
+        return { file: 'systemctl', args: ['--user', 'restart', '--no-block', unit] };
+    }
+    if (opts.uid === 0) {
+        return { file: 'systemctl', args: ['restart', '--no-block', unit] };
+    }
+    return { file: 'sudo', args: ['-n', 'systemctl', 'restart', '--no-block', unit] };
+}
+export function restartLaunch() {
+    const launch = dshArgv();
+    return {
+        ...launch,
+        args: [...launch.args, ...process.argv.slice(2)],
+        cwd: launch.cwd ?? process.cwd(),
+    };
+}
+function respawnInvocation(launch, platform = process.platform) {
+    if (platform !== 'win32') {
+        return { file: launch.file, args: launch.args, viaShell: launch.viaShell, detached: true };
+    }
+    const quote = (part) => `'${part.replace(/'/g, "''")}'`;
+    return {
+        file: 'powershell.exe',
+        args: ['-NoProfile', '-WindowStyle', 'Hidden', '-Command',
+            [`& ${quote(launch.file)}`, ...launch.args.map(quote)].join(' ')],
+        viaShell: false,
+        detached: false,
+    };
+}
+function restartHelperSource(spawned, launch, logs, port) {
+    return [
+        "const { spawn } = require('node:child_process')",
+        "const fs = require('node:fs')",
+        "const net = require('node:net')",
+        `const file = ${JSON.stringify(spawned.file)}`,
+        `const args = ${JSON.stringify(spawned.args)}`,
+        `const cwd = ${JSON.stringify(launch.cwd)}`,
+        `const viaShell = ${JSON.stringify(spawned.viaShell)}`,
+        `const detached = ${JSON.stringify(spawned.detached)}`,
+        `const logOut = ${JSON.stringify(logs.out)}`,
+        `const logErr = ${JSON.stringify(logs.err)}`,
+        `const port = ${JSON.stringify(port)}`,
+        'const sleep = (ms) => new Promise(r => setTimeout(r, ms))',
+        "const note = (line) => { try { fs.appendFileSync(logErr, `[dsh-m] ${line}\\n`) } catch {} }",
+        'const listening = () => new Promise((resolve) => {',
+        '  const probe = net.connect({ host: "127.0.0.1", port })',
+        '  const done = (value) => { probe.destroy(); resolve(value) }',
+        '  probe.on("connect", () => done(true))',
+        '  probe.on("error", () => done(false))',
+        '  setTimeout(() => done(false), 500)',
+        '})',
+        'const main = async () => {',
+        '  if (port) {',
+        '    const until = Date.now() + 30000',
+        '    while (Date.now() < until && await listening()) await sleep(250)',
+        '    if (await listening()) note(`port ${port} was still in use after 30s; starting anyway`)',
+        '    await sleep(300)',
+        '  } else {',
+        '    await sleep(1500)',
+        '  }',
+        "  let child",
+        '  try {',
+        '    const out = fs.openSync(logOut, "a")',
+        '    const err = fs.openSync(logErr, "a")',
+        '    child = spawn(file, args, { cwd, detached, stdio: ["ignore", out, err], env: process.env, shell: viaShell })',
+        '    child.on("error", (error) => note(`could not start the replacement: ${error && error.message ? error.message : error}`))',
+        '    child.unref()',
+        '  } catch (error) {',
+        '    note(`could not start the replacement: ${error && error.message ? error.message : error}`)',
+        '    return',
+        '  }',
+        '  if (!port) { await sleep(3000); return }',
+        '  const upBy = Date.now() + 20000',
+        '  while (Date.now() < upBy && !(await listening())) await sleep(500)',
+        '  if (!(await listening())) note(`the replacement did not bind port ${port} within 20s — see the output log beside this one`)',
+        '}',
+        'main()',
+    ].join('\n');
+}
+export function scheduleRestart(port = null, deps = {}) {
+    const pid = deps.pid ?? process.pid;
+    const systemd = systemdRestartArgv({
+        cgroup: deps.cgroup ?? readProcCgroup(),
+        uid: deps.uid ?? (typeof process.getuid === 'function' ? process.getuid() : 1),
+    });
+    if (systemd !== null) {
+        ;
+        (deps.setTimeout ?? setTimeout)(() => {
+            const helper = (deps.spawn ?? spawn)(systemd.file, systemd.args, {
+                detached: true,
+                stdio: 'ignore',
+                env: process.env,
+            });
+            helper.unref();
+        }, 500);
+        return { pid, helperPid: undefined, via: 'systemd' };
+    }
+    const launch = (deps.restartLaunch ?? restartLaunch)();
+    const spawned = respawnInvocation(launch);
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const logOut = join(tmpdir(), `dshm-restart-${stamp}.out.log`);
+    const logErr = join(tmpdir(), `dshm-restart-${stamp}.err.log`);
+    const helper = (deps.spawn ?? spawn)((deps.nodeExecutable ?? nodeExecutable)(), ['-e', restartHelperSource(spawned, launch, { out: logOut, err: logErr }, port)], {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env,
+    });
+    helper.unref();
+    (deps.setTimeout ?? setTimeout)(() => (deps.kill ?? process.kill)(pid, 'SIGTERM'), 500);
+    return { pid, helperPid: helper.pid, via: 'helper' };
+}