@guanjinke/artifact-client 1.3.0 → 1.4.0

package/dist/environment/plan.js

@@ -0,0 +1,131 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateTarget = validateTarget;
+exports.validateEnvironmentOptions = validateEnvironmentOptions;
+exports.buildEnvironmentPlan = buildEnvironmentPlan;
+const fs = __importStar(require("fs/promises"));
+const path = __importStar(require("path"));
+const catalog_1 = require("./catalog");
+const archive_1 = require("./archive");
+async function validateTarget(root) {
+    const absolute = path.resolve(root);
+    const relative = absolute.slice(path.parse(absolute).root.length).split(path.sep).join('/');
+    if (relative)
+        (0, archive_1.validateArchivePath)(relative);
+    const protectedRoots = [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.SystemRoot, process.env.WINDIR, process.env.USERPROFILE, process.env.HOME].filter((p) => !!p).map(p => path.resolve(p).toLowerCase());
+    const normalized = absolute.toLowerCase();
+    if (absolute === path.parse(absolute).root || protectedRoots.some(p => normalized === p || ((p.includes('program files') || p.includes('windows')) && normalized.startsWith(p + path.sep)))) {
+        throw new Error('Environment root is a protected directory.');
+    }
+    // Reject links in all existing ancestors, not only the final directory.
+    for (let current = absolute;; current = path.dirname(current)) {
+        try {
+            const stat = await fs.lstat(current);
+            if (stat.isSymbolicLink() || !stat.isDirectory())
+                throw new Error('Environment root or ancestor is not a regular directory.');
+            if (current === absolute && (await fs.readdir(current)).length)
+                throw new Error('Environment root must be absent or empty.');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (current === path.dirname(current))
+            break;
+    }
+}
+async function validateEnvironmentOptions(options) {
+    if (!options.root || !options.major || !/^(9\.1(?:-[A-Za-z0-9][A-Za-z0-9._-]*)?|dev)$/.test(options.major))
+        throw new Error('Supported product majors: 9.1, 9.1-* and dev (artifact-derived V91/V100).');
+    const edition = options.edition ?? 'cn';
+    const profile = options.profile ?? 'embedded';
+    const port = options.port ?? 51980;
+    if (!['cn', 'en'].includes(edition))
+        throw new Error('Edition must be cn or en.');
+    if (profile !== 'embedded')
+        throw new Error('Only the embedded profile is supported.');
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        throw new Error('Port must be an integer between 1 and 65535.');
+    const requestedModules = [...new Set((options.modules ?? []).flatMap(m => m.split(',')).map(m => m.trim()).filter(Boolean))];
+    const modules = requestedModules.filter(m => !['server', 'account', 'dataset', 'analysis', 'cot-worker', 'common', 'monitoring'].includes(m)).sort();
+    if (modules.some(m => !['dashboard', 'reporting', 'sheets', 'documents'].includes(m)))
+        throw new Error('Select optional modules: dashboard, reporting, sheets, documents. Wyn core server, account, dataset, analysis model and cot worker are always included.');
+    if (edition !== 'en' && modules.some(m => ['sheets', 'documents'].includes(m)))
+        throw new Error('Sheets and documents require EN edition.');
+    if (modules.includes('documents'))
+        throw new Error('Documents embedded execution is not supported: CollaborationService dependency is unverified.');
+    await validateTarget(options.root);
+    return { ...options, root: path.resolve(options.root), edition, profile, port, modules: modules };
+}
+async function buildEnvironmentPlan(options, client, onProgress) {
+    onProgress?.('Validating environment options and target directory');
+    const normalized = await validateEnvironmentOptions(options);
+    const autoAddedModules = ['server', 'monitoring', 'common', 'analysis'];
+    const artifacts = [];
+    const modules = [...autoAddedModules, ...normalized.modules];
+    for (const [index, module] of modules.entries()) {
+        const entry = catalog_1.catalog[module];
+        onProgress?.(`[${index + 1}/${modules.length}] Resolving ${entry.plugin}/${normalized.major}`);
+        let version;
+        let files;
+        try {
+            version = (await client.getLatestVersion(entry.plugin, normalized.major)).version;
+            if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(version))
+                throw new Error('Invalid resolved version');
+            files = await client.listArtifacts(entry.plugin, version);
+        }
+        catch {
+            throw new Error(`Unable to resolve artifacts for ${entry.plugin}/${normalized.major}.`);
+        }
+        const name = entry.filename(version, normalized.edition);
+        const candidates = files.filter(f => f.name === name);
+        if (candidates.length !== 1)
+            throw new Error(`${entry.plugin}/${version}: expected exactly one ${name}, found ${candidates.length}.`);
+        // Remote paths must remain credential-free relative object names.
+        const remotePath = candidates[0].path;
+        if (!remotePath || /[?:\\\x00-\x1f]/.test(remotePath) || remotePath.startsWith('/') || remotePath.split('/').includes('..'))
+            throw new Error(`${entry.plugin}/${version}: invalid artifact path.`);
+        onProgress?.(`[${index + 1}/${modules.length}] Selected ${entry.plugin}/${version}/${name}`);
+        artifacts.push({ module, plugin: entry.plugin, version, name, path: remotePath, mappings: entry.mappings.map(m => ({ ...m, assemblies: [...m.assemblies] })) });
+    }
+    return {
+        root: normalized.root, major: normalized.major, schema: 'pending', edition: normalized.edition, profile: normalized.profile, port: normalized.port,
+        selectedModules: normalized.modules, autoAddedModules, artifacts,
+        warnings: ['No services are registered or started.', 'Wyn core server, account, dataset, analysis model and cot worker are always included.', 'License, sample data, bootstrap data and optional language/styles-cache archives are not provisioned.'],
+        requirements: ['Windows for execution.', '.NET runtime requirements are discovered from downloaded runtimeconfig files.', 'A valid license and database initialization may be required before startup.'],
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/environment/plan.js.map

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

package/dist/environment/process.d.ts

@@ -0,0 +1,94 @@
+import { ProcessIdentity, RunMode } from './registry';
+export declare class PendingProcessError extends Error {
+    readonly identity: ProcessIdentity;
+    constructor(message: string, identity: ProcessIdentity);
+}
+export type Inspection = {
+    status: 'live';
+    identity: ProcessIdentity;
+} | {
+    status: 'absent';
+} | {
+    status: 'unknown';
+    reason?: 'query' | 'ambiguous';
+};
+export interface StartedProcess {
+    identity: ProcessIdentity;
+    /**
+     * Resolves when the direct child spawned by this backend exits. Absent for an
+     * independent background launch, which no longer has a parent process handle.
+     */
+    exited?: Promise<void>;
+    exitCode?: () => number | null;
+    unref(): void;
+}
+export interface ProcessBackend {
+    inspect(pid: number): Promise<Inspection>;
+    find(command: string): Promise<Inspection[]>;
+    start(dll: string, mode: RunMode, stdout: string, stderr: string): Promise<StartedProcess>;
+    stop(identity: ProcessIdentity): Promise<void>;
+}
+export declare function sameProcess(a: ProcessIdentity, b: ProcessIdentity): boolean;
+export declare const monitorCommand: (dll: string) => string;
+/** Split a raw Windows command line into tokens, tolerating extra/trailing spaces. */
+export declare function commandTokens(command: string): string[] | undefined;
+/**
+ * Best-effort list of running processes whose command line references a directory.
+ * Used to explain why a directory could not be removed (for example an editor or
+ * terminal that has it open). Never throws; returns an empty list when unknown.
+ */
+export declare function describePathHolders(root: string): Promise<string[]>;
+export declare function isMonitor(identity: ProcessIdentity, dll: string): boolean;
+/**
+ * True when the identity is a `dotnet <assembly> --RunAsMonitor` invocation.
+ * Token based so the extra spaces cmd.exe introduces around arguments do not matter.
+ */
+export declare function isMonitorProcess(identity: ProcessIdentity): boolean;
+export declare function checkPort(port: number): Promise<void>;
+export declare class WindowsProcessBackend implements ProcessBackend {
+    private readonly identityTimeoutMs;
+    /**
+     * @param identityTimeoutMs how long to wait for the OS to expose the started
+     * process before giving up. Injectable so tests do not wait for the default.
+     */
+    constructor(identityTimeoutMs?: number);
+    private query;
+    inspect(pid: number): Promise<Inspection>;
+    find(command: string): Promise<Inspection[]>;
+    start(dll: string, mode: RunMode, stdout: string, stderr: string): Promise<StartedProcess>;
+    /**
+     * Foreground: a direct child with inherited stdio, so the terminal console and
+     * Ctrl+C reach the monitor and its output stays visible.
+     */
+    private startForeground;
+    /**
+     * Background: start the monitor in its own hidden console.
+     *
+     * Two Windows constraints force this: Node's `detached: true` (DETACHED_PROCESS)
+     * leaves the child without any console, and Wyn.Server assigns `Console.Title` at
+     * the top of Main, which throws IOException without one; while a non-detached child
+     * does not survive the process that spawned it. `Start-Process -WindowStyle Hidden`
+     * gives `cmd.exe` a console that has no visible window, and cmd appends the monitor's
+     * output to the log files and stays alive with it, so the monitor is independent of
+     * this CLI. Its identity is then confirmed by exact command-line discovery.
+     */
+    private startBackground;
+    /**
+     * Start `dotnet <dll> --RunAsMonitor` in a hidden console through cmd.exe and
+     * return the PID of that console host. Redirection stays with cmd because
+     * Windows PowerShell 5.1 blocks in `Start-Process` when it redirects output.
+     */
+    private launchHiddenConsole;
+    /** Terminate exact-identity leftovers of this environment and report how many remain. */
+    private cleanupCandidates;
+    /** Explain a failed launch with the monitor's own log output. */
+    private describeLaunchFailure;
+    /** Bounded tail of a log file, used to explain why a monitor exited immediately. */
+    private lastOutput;
+    /** Wait for a promise without leaving a pending timer behind. */
+    private settle;
+    private descendants;
+    private stopFresh;
+    stop(identity: ProcessIdentity): Promise<void>;
+}
+//# sourceMappingURL=process.d.ts.map

package/dist/environment/process.d.ts.map

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

package/dist/environment/process.js

@@ -0,0 +1,381 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WindowsProcessBackend = exports.monitorCommand = exports.PendingProcessError = void 0;
+exports.sameProcess = sameProcess;
+exports.commandTokens = commandTokens;
+exports.describePathHolders = describePathHolders;
+exports.isMonitor = isMonitor;
+exports.isMonitorProcess = isMonitorProcess;
+exports.checkPort = checkPort;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const net = __importStar(require("net"));
+const os_1 = require("os");
+const util_1 = require("util");
+const exec = (0, util_1.promisify)(child_process_1.execFile);
+class PendingProcessError extends Error {
+    identity;
+    constructor(message, identity) {
+        super(message);
+        this.identity = identity;
+    }
+}
+exports.PendingProcessError = PendingProcessError;
+function sameProcess(a, b) { return a.pid === b.pid && a.createdAt === b.createdAt && a.command === b.command && a.executable.toLowerCase() === b.executable.toLowerCase(); }
+const monitorCommand = (dll) => `dotnet "${dll}" --RunAsMonitor`;
+exports.monitorCommand = monitorCommand;
+/** Split a raw Windows command line into tokens, tolerating extra/trailing spaces. */
+function commandTokens(command) {
+    return command.match(/(?:[^\s"]+|"[^"]*")+/g)?.map(token => token.replace(/^"|"$/g, ''));
+}
+/**
+ * Best-effort list of running processes whose command line references a directory.
+ * Used to explain why a directory could not be removed (for example an editor or
+ * terminal that has it open). Never throws; returns an empty list when unknown.
+ */
+async function describePathHolders(root) {
+    if (process.platform !== 'win32')
+        return [];
+    // The needle travels through the environment so this helper's own PowerShell
+    // command line never matches itself.
+    const script = `$ErrorActionPreference='Stop'; $needle=$env:AFM_PATH_HOLDERS_NEEDLE; ConvertTo-Json -Compress -InputObject @(Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -and $_.ProcessId -ne ${process.pid} -and $_.CommandLine.ToLower().Contains($needle) } | ForEach-Object { @{pid=[int]$_.ProcessId; name=$_.Name} })`;
+    try {
+        const { stdout } = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { timeout: 5000, maxBuffer: 1024 * 1024, env: { ...process.env, AFM_PATH_HOLDERS_NEEDLE: root.toLowerCase() } });
+        const parsed = JSON.parse(stdout);
+        const values = Array.isArray(parsed) ? parsed : parsed ? [parsed] : [];
+        return values.filter(value => value && Number.isInteger(value.pid)).map(value => `${value.name} (pid ${value.pid})`);
+    }
+    catch {
+        return [];
+    }
+}
+function isMonitor(identity, dll) {
+    const tokens = commandTokens(identity.command);
+    return isMonitorProcess(identity) && !!tokens && path.isAbsolute(tokens[1]) && path.resolve(tokens[1]).toLowerCase() === path.resolve(dll).toLowerCase();
+}
+/**
+ * True when the identity is a `dotnet <assembly> --RunAsMonitor` invocation.
+ * Token based so the extra spaces cmd.exe introduces around arguments do not matter.
+ */
+function isMonitorProcess(identity) {
+    const tokens = commandTokens(identity.command);
+    return path.win32.basename(identity.executable).toLowerCase() === 'dotnet.exe' && !!tokens && tokens.length === 3 && path.basename(tokens[0]).toLowerCase().replace(/\.exe$/, '') === 'dotnet' && tokens[2] === '--RunAsMonitor';
+}
+async function checkPort(port) {
+    const addresses = Object.values((0, os_1.networkInterfaces)()).flatMap(entries => entries ?? []).filter(entry => entry.family === 'IPv4' || entry.family === 'IPv6' && !entry.address.toLowerCase().startsWith('fe80:')).map(entry => entry.address);
+    for (const host of new Set(['127.0.0.1', '0.0.0.0', '::1', '::', ...addresses]))
+        await new Promise((resolve, reject) => {
+            const server = net.createServer();
+            server.once('error', (error) => { if (host.startsWith('::') && ['EAFNOSUPPORT', 'EADDRNOTAVAIL', 'EPROTONOSUPPORT'].includes(error.code ?? ''))
+                resolve();
+            else
+                reject(new Error(`Port ${port} is unavailable (${error.code}); choose an alternate --port.`)); });
+            server.listen({ port, host, ipv6Only: host === '::', exclusive: true }, () => server.close(error => error ? reject(error) : resolve()));
+        });
+}
+// Fixed CIM scripts; only validated integer PIDs are interpolated, never paths or user arguments.
+class WindowsProcessBackend {
+    identityTimeoutMs;
+    /**
+     * @param identityTimeoutMs how long to wait for the OS to expose the started
+     * process before giving up. Injectable so tests do not wait for the default.
+     */
+    constructor(identityTimeoutMs = 10000) {
+        this.identityTimeoutMs = identityTimeoutMs;
+    }
+    async query(pid, timeout = 10000) {
+        if (process.platform !== 'win32')
+            return [{ status: 'unknown', reason: 'query' }];
+        if (pid !== undefined && (!Number.isInteger(pid) || pid <= 0))
+            return [{ status: 'unknown', reason: 'query' }];
+        const script = `$ErrorActionPreference='Stop'; $p=@(Get-CimInstance Win32_Process${pid === undefined ? ' -Filter "Name = \'dotnet.exe\'"' : ` -Filter "ProcessId = ${pid}"`}); ConvertTo-Json -Compress -InputObject @($p | ForEach-Object { @{pid=[int]$_.ProcessId; createdAt=$_.CreationDate.ToUniversalTime().ToString('o'); executable=$_.ExecutablePath; command=$_.CommandLine} })`;
+        try {
+            const { stdout } = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { timeout, maxBuffer: 8 * 1024 * 1024 });
+            const values = JSON.parse(stdout);
+            if (!Array.isArray(values))
+                return [{ status: 'unknown', reason: 'query' }];
+            return values.map(identity => identity.command && identity.executable && identity.createdAt ? { status: 'live', identity } : { status: 'unknown', reason: 'query' });
+        }
+        catch {
+            return [{ status: 'unknown', reason: 'query' }];
+        }
+    }
+    async inspect(pid) { return (await this.query(pid))[0] ?? { status: 'absent' }; }
+    async find(command) {
+        const dll = command.slice(8, -16);
+        const result = [];
+        for (const item of await this.query()) {
+            if (item.status === 'unknown') {
+                result.push(item);
+                continue;
+            }
+            if (item.status !== 'live')
+                continue;
+            const tokens = commandTokens(item.identity.command);
+            if (!tokens || tokens.length < 2 || path.win32.basename(item.identity.executable).toLowerCase() !== 'dotnet.exe')
+                continue;
+            // A relative same-name launch cannot be attributed to an environment, but it is
+            // also never one of ours: environments are always started with an absolute path.
+            if (!path.isAbsolute(tokens[1])) {
+                if (path.win32.basename(tokens[1]).toLowerCase() === path.win32.basename(dll).toLowerCase())
+                    result.push({ status: 'unknown', reason: 'ambiguous' });
+            }
+            else if (path.resolve(tokens[1]).toLowerCase() === path.resolve(dll).toLowerCase())
+                result.push(item);
+        }
+        return result;
+    }
+    async start(dll, mode, stdout, stderr) {
+        if (process.platform !== 'win32')
+            throw new Error('Runtime management is Windows-only.');
+        return mode === 'foreground' ? this.startForeground(dll, stderr) : this.startBackground(dll, stdout, stderr);
+    }
+    /**
+     * Foreground: a direct child with inherited stdio, so the terminal console and
+     * Ctrl+C reach the monitor and its output stays visible.
+     */
+    async startForeground(dll, stderr) {
+        const child = (0, child_process_1.spawn)('dotnet', [dll, '--RunAsMonitor'], { cwd: path.dirname(dll), shell: false, detached: false, stdio: 'inherit' });
+        const exited = new Promise(resolve => { child.once('exit', () => resolve()); child.once('error', () => resolve()); });
+        await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', reject); });
+        const pid = child.pid;
+        let inspected = { status: 'absent' };
+        const deadline = Date.now() + this.identityTimeoutMs;
+        while (child.exitCode === null && child.signalCode === null && Date.now() < deadline) {
+            inspected = (await this.query(pid, Math.max(1, Math.min(5000, deadline - Date.now()))))[0] ?? { status: 'absent' };
+            if (inspected.status === 'live')
+                break;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        const identity = inspected.status === 'live' ? inspected.identity : undefined;
+        if (identity && !isMonitor(identity, dll)) {
+            // A live process with the expected PID whose command line is not the exact
+            // monitor invocation: terminate it through its own identity, or hand the
+            // verified identity back so the caller can persist a recoverable record.
+            try {
+                await this.stopFresh(identity);
+            }
+            catch {
+                child.unref();
+                throw new PendingProcessError('Launch cleanup uncertain. Registry recovery required.', identity);
+            }
+            throw new Error('Cannot establish exact monitor identity; launch cancelled.');
+        }
+        if (!identity) {
+            const exitedEarly = child.exitCode !== null || child.signalCode !== null;
+            if (!exitedEarly) {
+                try {
+                    child.kill();
+                }
+                catch { /* already gone */ }
+                await this.settle(exited, 3000);
+            }
+            const detail = `Monitor ${exitedEarly ? `exited before its identity could be verified (exit code ${child.exitCode ?? 'null'}, signal ${child.signalCode ?? 'none'})` : `identity could not be verified within ${this.identityTimeoutMs}ms and the process was terminated`}`;
+            throw new Error(this.describeLaunchFailure(detail, dll, stderr));
+        }
+        if (child.exitCode !== null || child.signalCode !== null)
+            throw new Error('Monitor exited during launch.');
+        return { identity, exited, exitCode: () => child.exitCode, unref: () => child.unref() };
+    }
+    /**
+     * Background: start the monitor in its own hidden console.
+     *
+     * Two Windows constraints force this: Node's `detached: true` (DETACHED_PROCESS)
+     * leaves the child without any console, and Wyn.Server assigns `Console.Title` at
+     * the top of Main, which throws IOException without one; while a non-detached child
+     * does not survive the process that spawned it. `Start-Process -WindowStyle Hidden`
+     * gives `cmd.exe` a console that has no visible window, and cmd appends the monitor's
+     * output to the log files and stays alive with it, so the monitor is independent of
+     * this CLI. Its identity is then confirmed by exact command-line discovery.
+     */
+    async startBackground(dll, stdout, stderr) {
+        const hostPid = await this.launchHiddenConsole(dll, stdout, stderr);
+        let identity;
+        let hostAlive = true;
+        const deadline = Date.now() + this.identityTimeoutMs;
+        while (Date.now() < deadline) {
+            const live = (await this.find((0, exports.monitorCommand)(dll))).filter((candidate) => candidate.status === 'live' && isMonitor(candidate.identity, dll));
+            if (live.length === 1) {
+                identity = live[0].identity;
+                break;
+            }
+            if (live.length > 1)
+                throw new Error(`More than one monitor matches ${dll}; refusing to record an ambiguous identity.`);
+            // The hidden-console host only exits after its monitor exits.
+            hostAlive = (await this.inspect(hostPid)).status === 'live';
+            if (!hostAlive)
+                break;
+            await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        if (!identity) {
+            const remaining = await this.cleanupCandidates(dll);
+            const detail = `Monitor identity could not be verified within ${this.identityTimeoutMs}ms (hidden-console host pid ${hostPid} is ${hostAlive ? 'still running' : 'gone'})${remaining ? `; ${remaining} process(es) still reference ${dll} and require manual inspection` : ''}`;
+            throw new Error(this.describeLaunchFailure(detail, dll, stderr));
+        }
+        return { identity, unref: () => { } };
+    }
+    /**
+     * Start `dotnet <dll> --RunAsMonitor` in a hidden console through cmd.exe and
+     * return the PID of that console host. Redirection stays with cmd because
+     * Windows PowerShell 5.1 blocks in `Start-Process` when it redirects output.
+     */
+    launchHiddenConsole(dll, stdout, stderr) {
+        const quote = (value) => `'${value.replace(/'/g, "''")}'`;
+        const argument = `/c dotnet "${dll}" --RunAsMonitor 1>>"${stdout}" 2>>"${stderr}"`;
+        const script = [
+            "$ErrorActionPreference='Stop'",
+            `$p = Start-Process -FilePath 'cmd.exe' -ArgumentList ${quote(argument)} -WorkingDirectory ${quote(path.dirname(dll))} -WindowStyle Hidden -PassThru`,
+            '$p.Id',
+        ].join('; ');
+        return new Promise((resolve, reject) => {
+            // Not detached: Node cannot read the launcher's stdout when it is detached on
+            // Windows. The launcher only creates the hidden-console host and exits.
+            const launcher = (0, child_process_1.spawn)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { detached: false, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+            let output = '';
+            let failure = '';
+            launcher.stdout?.on('data', chunk => { output += String(chunk); });
+            launcher.stderr?.on('data', chunk => { failure += String(chunk); });
+            launcher.once('error', reject);
+            launcher.once('close', code => {
+                const pid = Number(output.trim());
+                if (code === 0 && Number.isInteger(pid) && pid > 0)
+                    resolve(pid);
+                else
+                    reject(new Error(`Cannot start the hidden-console monitor (launcher exit ${code}): ${failure.trim() || 'no launcher output'}`));
+            });
+        });
+    }
+    /** Terminate exact-identity leftovers of this environment and report how many remain. */
+    async cleanupCandidates(dll) {
+        const candidates = await this.find((0, exports.monitorCommand)(dll)).catch(() => [{ status: 'unknown' }]);
+        for (const candidate of candidates)
+            if (candidate.status === 'live')
+                await this.stopFresh(candidate.identity).catch(() => undefined);
+        return (await this.find((0, exports.monitorCommand)(dll)).catch(() => [{ status: 'unknown' }])).filter(item => item.status !== 'absent').length;
+    }
+    /** Explain a failed launch with the monitor's own log output. */
+    describeLaunchFailure(detail, dll, stderr) {
+        const tail = this.lastOutput(stderr);
+        const consoleHint = /ConsolePal\.set_Title|Console\.Title|Invalid handle|句柄/i.test(tail)
+            ? ' Wyn.Server cannot run without an attached console because it assigns Console.Title at the start of Main; guard that call in Wyn.Server or start with --foreground.'
+            : '';
+        return `${detail}. ${tail}${consoleHint}`;
+    }
+    /** Bounded tail of a log file, used to explain why a monitor exited immediately. */
+    lastOutput(file, limit = 2000) {
+        try {
+            const tail = fs.readFileSync(file, 'utf8').slice(-limit).trim();
+            return tail ? `Last output from ${file}:\n${tail}` : `${file} is empty.`;
+        }
+        catch {
+            return `${file} is empty or unreadable.`;
+        }
+    }
+    /** Wait for a promise without leaving a pending timer behind. */
+    settle(promise, ms) {
+        return new Promise(resolve => {
+            const timer = setTimeout(resolve, ms);
+            timer.unref?.();
+            void promise.then(() => { clearTimeout(timer); resolve(); });
+        });
+    }
+    async descendants(parent, deadline) {
+        const result = [];
+        const visit = async (ancestor) => {
+            if (Date.now() >= deadline)
+                throw new Error('Timed out inspecting monitor process tree.');
+            if (result.length > 512)
+                throw new Error('Monitor process tree exceeds safety limit.');
+            const script = `$ErrorActionPreference='Stop'; ConvertTo-Json -Compress -InputObject @(Get-CimInstance Win32_Process -Filter "ParentProcessId = ${ancestor.pid}" | ForEach-Object { @{pid=[int]$_.ProcessId; createdAt=$_.CreationDate.ToUniversalTime().ToString('o'); executable=$_.ExecutablePath; command=$_.CommandLine} })`;
+            const raw = await exec('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { timeout: Math.max(1, Math.min(10000, deadline - Date.now())) });
+            const children = JSON.parse(raw.stdout);
+            if (!Array.isArray(children))
+                throw new Error('Unknown monitor process tree.');
+            for (const child of children) {
+                if (!child.createdAt || !child.command || !child.executable || !Number.isInteger(child.pid))
+                    throw new Error('Unknown child process identity.');
+                // ParentProcessId can refer to an older process with a reused PID.
+                if (!Number.isFinite(Date.parse(child.createdAt)) || !Number.isFinite(Date.parse(ancestor.createdAt)) || Date.parse(child.createdAt) < Date.parse(ancestor.createdAt))
+                    throw new Error('Child ancestry uncertain or parent PID reused; refusing tree kill.');
+                if (result.some(entry => entry.pid === child.pid))
+                    throw new Error('Cyclic process tree.');
+                result.push(child);
+                await visit(child);
+            }
+        };
+        await visit(parent);
+        return result;
+    }
+    async stopFresh(identity) {
+        const deadline = Date.now() + 15000;
+        const inspect = async (pid) => { if (Date.now() >= deadline)
+            throw new Error('Timed out stopping monitor tree.'); return (await this.query(pid, Math.max(1, Math.min(10000, deadline - Date.now()))))[0] ?? { status: 'absent' }; };
+        const current = await inspect(identity.pid);
+        if (current.status !== 'live' || !sameProcess(current.identity, identity))
+            throw new Error('Process identity uncertain or changed; refusing kill.');
+        const descendants = await this.descendants(identity, deadline);
+        const immediate = await inspect(identity.pid);
+        if (immediate.status !== 'live' || !sameProcess(immediate.identity, identity))
+            throw new Error('Process identity changed before kill.');
+        if (Date.now() >= deadline)
+            throw new Error('Timed out before monitor tree termination.');
+        await exec('taskkill.exe', ['/PID', String(identity.pid), '/T', '/F'], { timeout: Math.max(1, Math.min(10000, deadline - Date.now())) });
+        for (let attempt = 0; attempt < 30; attempt++) {
+            let live = false;
+            for (const entry of [identity, ...descendants]) {
+                if (Date.now() >= deadline)
+                    throw new Error('Timed out confirming monitor tree exit.');
+                const state = await inspect(entry.pid);
+                if (state.status === 'unknown')
+                    throw new Error('Unable to confirm process tree exit.');
+                if (state.status === 'live' && sameProcess(state.identity, entry))
+                    live = true;
+            }
+            if (!live)
+                return;
+            await new Promise(resolve => setTimeout(resolve, 100));
+        }
+        throw new Error('Timed out waiting for monitor tree exit.');
+    }
+    async stop(identity) {
+        if (!isMonitorProcess(identity))
+            throw new Error('Not a verified dotnet monitor.');
+        await this.stopFresh(identity);
+    }
+}
+exports.WindowsProcessBackend = WindowsProcessBackend;
+//# sourceMappingURL=process.js.map