@hcu-lab.me/mcp-device 1.0.10 → 1.0.12

package/dist/platform/plugin-policy.d.ts

@@ -0,0 +1,3 @@
+export type DevicePluginPolicy = 'bundled' | 'core-first';
+/** Legacy option compatibility only. Core never bundles optional plugins. */
+export declare function resolveDevicePluginPolicy(argv?: readonly string[], env?: NodeJS.ProcessEnv): DevicePluginPolicy | undefined;

package/dist/platform/plugin-policy.js

@@ -0,0 +1,29 @@
+const POLICY_ERROR = '--plugin-policy must be bundled or core-first';
+function parsePolicy(value, source) {
+    if (value === undefined || (source === 'env' && value === ''))
+        return undefined;
+    if (value === 'bundled' || value === 'core-first')
+        return value;
+    throw new Error(POLICY_ERROR);
+}
+/** Legacy option compatibility only. Core never bundles optional plugins. */
+export function resolveDevicePluginPolicy(argv = process.argv, env = process.env) {
+    let cliValue;
+    let cliSpecified = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        if (argument === '--plugin-policy') {
+            cliSpecified = true;
+            const next = argv[index + 1];
+            if (!next || next.startsWith('--'))
+                throw new Error(POLICY_ERROR);
+            cliValue = next;
+            index += 1;
+        }
+        else if (argument.startsWith('--plugin-policy=')) {
+            cliSpecified = true;
+            cliValue = argument.slice('--plugin-policy='.length);
+        }
+    }
+    return cliSpecified ? parsePolicy(cliValue, 'cli') : parsePolicy(env.MCP_DEVICE_PLUGIN_POLICY, 'env');
+}

package/dist/platform/plugin-services.d.ts

@@ -0,0 +1,14 @@
+import { type CapabilityRequirement } from './plugin-contract.js';
+/** Services are scoped to one lifecycle or invocation request, never a process-global caller. */
+export interface PluginServices {
+    invoke(name: string, input: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+export interface DependencyCallOptions {
+    version: string;
+    signal: AbortSignal;
+    compose: false;
+}
+export type DependencyInvoker = (name: string, input: unknown, options: DependencyCallOptions) => Promise<unknown>;
+export declare function createPluginServices(requirements: readonly CapabilityRequirement[], invokeProvider: DependencyInvoker, parentSignal: AbortSignal): PluginServices;

package/dist/platform/plugin-services.js

@@ -0,0 +1,32 @@
+import { CapabilityError } from './plugin-contract.js';
+export function createPluginServices(requirements, invokeProvider, parentSignal) {
+    const declared = new Map(requirements.map(requirement => [requirement.name, requirement.version]));
+    return Object.freeze({
+        async invoke(name, input, options = {}) {
+            const version = declared.get(name);
+            if (!version)
+                throw new CapabilityError('CAPABILITY_DEPENDENCY_UNDECLARED', 'Plugin did not declare the required capability');
+            const signal = options.signal ? AbortSignal.any([parentSignal, options.signal]) : parentSignal;
+            if (signal.aborted)
+                throw new CapabilityError('CANCELLED', 'Dependency call scope ended or was cancelled');
+            let abort;
+            try {
+                return await Promise.race([
+                    Promise.resolve().then(() => {
+                        if (signal.aborted)
+                            throw new CapabilityError('CANCELLED', 'Dependency call cancelled before dispatch');
+                        return invokeProvider(name, input, { version, signal, compose: false });
+                    }),
+                    new Promise((_, reject) => {
+                        abort = () => reject(new CapabilityError('CANCELLED', 'Dependency call cancelled'));
+                        signal.addEventListener('abort', abort, { once: true });
+                    })
+                ]);
+            }
+            finally {
+                if (abort)
+                    signal.removeEventListener('abort', abort);
+            }
+        }
+    });
+}

package/dist/platform/process-identity.d.ts

@@ -0,0 +1,9 @@
+export interface ProcessNamespace {
+    platform: string;
+    hostname: string;
+    bootId?: string;
+    pidNamespace?: string;
+}
+export declare function processNamespace(): Promise<ProcessNamespace | null>;
+export declare function sameProcessNamespace(recorded: ProcessNamespace | undefined): Promise<boolean>;
+export declare function processBirth(pid: number): Promise<string | null>;

package/dist/platform/process-identity.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+let ownBirth;
+let ownNamespace;
+export async function processNamespace() {
+    ownNamespace ?? (ownNamespace = (async () => {
+        try {
+            const common = { platform: process.platform, hostname: os.hostname() };
+            if (process.platform === 'linux') {
+                const [boot, pidNamespace] = await Promise.all([
+                    fs.readFile('/proc/sys/kernel/random/boot_id', 'utf8'),
+                    fs.readlink('/proc/self/ns/pid')
+                ]);
+                if (!/^[a-f0-9-]{36}$/i.test(boot.trim()) || !/^pid:\[\d+\]$/.test(pidNamespace))
+                    return null;
+                return { ...common, bootId: boot.trim(), pidNamespace };
+            }
+            return common;
+        }
+        catch {
+            return null;
+        }
+    })());
+    return ownNamespace;
+}
+export async function sameProcessNamespace(recorded) {
+    const current = await processNamespace();
+    return !!current && !!recorded && current.platform === recorded.platform && current.hostname === recorded.hostname
+        && current.bootId === recorded.bootId && current.pidNamespace === recorded.pidNamespace;
+}
+export async function processBirth(pid) {
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return null;
+    if (pid === process.pid) {
+        ownBirth ?? (ownBirth = observe(pid));
+        return ownBirth;
+    }
+    return observe(pid);
+}
+async function observe(pid) {
+    try {
+        if (process.platform === 'linux') {
+            const [stat, boot] = await Promise.all([
+                fs.readFile(`/proc/${pid}/stat`, 'utf8'),
+                fs.readFile('/proc/sys/kernel/random/boot_id', 'utf8')
+            ]);
+            const end = stat.lastIndexOf(')'), fields = stat.slice(end + 2).trim().split(/\s+/), start = fields[19];
+            if (end < 0 || !/^\d+$/.test(start ?? '') || !/^[a-f0-9-]{36}$/i.test(boot.trim()))
+                return null;
+            return 'linux:' + boot.trim() + ':' + start;
+        }
+        if (process.platform === 'win32') {
+            const powershell = path.join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+            const command = `[Console]::Write((Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToFileTimeUtc().ToString([Globalization.CultureInfo]::InvariantCulture))`;
+            const { stdout } = await exec(powershell, ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], {
+                encoding: 'utf8', windowsHide: true, timeout: 3000, maxBuffer: 4096
+            });
+            const ticks = stdout.trim();
+            return /^\d{10,}$/.test(ticks) ? 'win32:' + ticks : null;
+        }
+    }
+    catch { /* unknown identity never authorizes takeover */ }
+    return null;
+}

package/dist/platform/runtime-lease.d.ts

@@ -0,0 +1,4 @@
+/** No listener is created and no prior runtime is stopped by taking this lease. */
+export declare function acquireServerLease(stateRoot: string, options?: {
+    allowDeviceOwnerPid?: number;
+}): Promise<() => Promise<void>>;

package/dist/platform/runtime-lease.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { CapabilityError } from './plugin-contract.js';
+import { probeRuntimeOwner } from '../device/runtime-owner.js';
+import { coordinationObservation, coordinationOwnerAbandoned, createCoordinationLock, releaseCoordinationLock, repairCoordinationLock } from './coordination-lock.js';
+/** No listener is created and no prior runtime is stopped by taking this lease. */
+export async function acquireServerLease(stateRoot, options = {}) {
+    stateRoot = path.resolve(stateRoot);
+    await fs.mkdir(stateRoot, { recursive: true });
+    const filename = path.join(stateRoot, 'server-runtime.lock');
+    for (let attempt = 0; attempt < 3; attempt++) {
+        try {
+            const lock = await createCoordinationLock(filename);
+            const release = () => releaseCoordinationLock(lock, filename);
+            try {
+                // Device-only v11 uses a named pipe / Unix socket. Holding the common
+                // lease first also serializes new Device, server and maintenance starts.
+                const owner = await probeRuntimeOwner({ root: stateRoot, identity: path.join(stateRoot, 'gateway-identity.json'), config: path.join(stateRoot, 'gateway-config.json'), status: path.join(stateRoot, 'gateway-status.json'), runtime: path.join(stateRoot, 'runtime'), update: path.join(stateRoot, 'update') });
+                if (owner && !(options.allowDeviceOwnerPid === process.pid && owner.pid === process.pid))
+                    throw new CapabilityError('RUNTIME_ALREADY_RUNNING', `This state directory has an active Device runtime in PID ${owner.pid}`);
+                if (!owner) {
+                    try {
+                        await fs.access(path.join(stateRoot, 'runtime-control.json'));
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT')
+                            return release;
+                        throw error;
+                    }
+                    throw new CapabilityError('DEVICE_RUNTIME_STOP_NOT_PROVEN', 'Device runtime control exists but does not respond; inspect the stopped runtime before recovering it');
+                }
+                return release;
+            }
+            catch (error) {
+                await release();
+                throw error;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            const previous = await coordinationObservation(filename);
+            if (!previous)
+                continue;
+            if (!previous.body)
+                throw new CapabilityError('RUNTIME_LOCK_INVALID', 'Runtime lease does not identify a valid process and token; inspect the stopped runtime before recovering it');
+            if (await coordinationOwnerAbandoned(previous.body)) {
+                await repairCoordinationLock(filename, {
+                    codes: { busy: 'RUNTIME_RECOVERY_BUSY', active: 'RUNTIME_ALREADY_RUNNING', recoveryRequired: 'RUNTIME_RECOVERY_BUSY' },
+                    messagePrefix: 'Runtime lease', retainAbandoned: false
+                });
+                continue;
+            }
+            throw new CapabilityError('RUNTIME_ALREADY_RUNNING', `This state directory is already owned by PID ${previous.body.pid}`);
+        }
+    }
+    throw new CapabilityError('RUNTIME_ALREADY_RUNNING', 'Another process acquired this runtime state');
+}

package/dist/platform/runtime-root.d.ts

@@ -0,0 +1,9 @@
+export interface RuntimeRootInspection {
+    root: string;
+    activeLease: boolean;
+    palaceRegistry: boolean;
+    leaseInspectable: boolean;
+    leaseVerification: 'pid-namespace';
+}
+export declare function inspectRuntimeRoot(root: string): Promise<RuntimeRootInspection>;
+export declare function resolveRuntimeRoot(explicit?: string): Promise<string>;

package/dist/platform/runtime-root.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { CapabilityError } from './plugin-contract.js';
+import { sameProcessNamespace } from './process-identity.js';
+async function activeLease(root) {
+    const file = path.join(root, 'server-runtime.lock');
+    let body;
+    try {
+        body = JSON.parse(await fs.readFile(file, 'utf8'));
+    }
+    catch (error) {
+        return { active: false, inspectable: error.code === 'ENOENT' };
+    }
+    const pid = Number(body.pid);
+    if (!Number.isSafeInteger(pid) || pid < 1)
+        return { active: false, inspectable: false };
+    try {
+        process.kill(pid, 0);
+    }
+    catch (error) {
+        return error.code === 'ESRCH' ? { active: false, inspectable: true } : { active: false, inspectable: false };
+    }
+    if (!await sameProcessNamespace(body.namespace))
+        return { active: false, inspectable: false };
+    // Observation only: a reused PID can conservatively appear active. Never
+    // use this result to authorize lock recovery, takeover or mutation.
+    return { active: true, inspectable: true };
+}
+async function palaceRegistry(root) {
+    try {
+        return Boolean(JSON.parse(await fs.readFile(path.join(root, 'plugins', 'registry.json'), 'utf8'))?.plugins?.palace);
+    }
+    catch {
+        return false;
+    }
+}
+export async function inspectRuntimeRoot(root) {
+    root = path.resolve(root);
+    const [lease, registry] = await Promise.all([activeLease(root), palaceRegistry(root)]);
+    return { root, activeLease: lease.active, palaceRegistry: registry, leaseInspectable: lease.inspectable, leaseVerification: 'pid-namespace' };
+}
+export async function resolveRuntimeRoot(explicit) {
+    if (explicit)
+        return path.resolve(explicit);
+    if (process.env.MCP_DEVICE_CONFIG_DIR)
+        return path.resolve(process.env.MCP_DEVICE_CONFIG_DIR);
+    const device = path.resolve(os.homedir(), '.mcp-device'), server = path.join(device, 'server');
+    const rows = await Promise.all([inspectRuntimeRoot(server), inspectRuntimeRoot(device)]);
+    const active = rows.filter(row => row.activeLease);
+    if (active.length === 1)
+        return active[0].root;
+    if (active.length > 1)
+        throw new CapabilityError('RUNTIME_AMBIGUOUS', `Multiple MCP Device runtimes are active: ${active.map(x => x.root).join(', ')}. Pass --runtime-dir explicitly.`);
+    const registered = rows.filter(row => row.palaceRegistry);
+    if (registered.length === 1)
+        return registered[0].root;
+    if (registered.length > 1)
+        throw new CapabilityError('RUNTIME_AMBIGUOUS', `Multiple MCP Device runtimes contain Palace: ${registered.map(x => x.root).join(', ')}. Pass --runtime-dir explicitly.`);
+    return server;
+}

package/dist/platform/state-backup.d.ts

@@ -0,0 +1,92 @@
+export interface StateFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+    mode: number;
+}
+interface Inventory {
+    files: StateFile[];
+    directories: string[];
+    totalBytes: number;
+    sourceDigest: string;
+}
+export interface StateBackupPlan extends Inventory {
+    schemaVersion: 1;
+    kind: 'mcp-device-state-backup-plan';
+    sourceRoot: string;
+    backupRoot: string;
+    dryRun: true;
+    excluded: string[];
+}
+export interface StateBackupManifest extends Inventory {
+    schemaVersion: 1;
+    kind: 'mcp-device-state-backup';
+    createdAt: string;
+    sourceRoot: string;
+    excluded: string[];
+    manifestHash: string;
+}
+export interface LegacyMigrationPlan {
+    schemaVersion: 1;
+    kind: 'mcp-device-legacy-migration-plan';
+    dryRun: boolean;
+    deviceRoot: string;
+    gatewayRoot: string;
+    backupRoot: string;
+    targetRoot: string;
+    device: Inventory;
+    gateway: Inventory;
+    mappings: Array<{
+        source: 'device' | 'gateway';
+        path: string;
+        targetPath: string;
+    }>;
+    planHash: string;
+}
+export declare function planStateBackup(options: {
+    sourceRoot: string;
+    backupRoot: string;
+}): Promise<StateBackupPlan>;
+export declare function createStateBackup(options: {
+    sourceRoot: string;
+    backupRoot: string;
+}): Promise<{
+    backupRoot: string;
+    manifest: StateBackupManifest;
+}>;
+export declare function verifyStateBackup(options: {
+    backupRoot: string;
+}): Promise<{
+    valid: true;
+    backupRoot: string;
+    manifest: StateBackupManifest;
+}>;
+export declare function restoreStateBackup(options: {
+    backupRoot: string;
+    targetRoot: string;
+}): Promise<{
+    targetRoot: string;
+    files: number;
+    bytes: number;
+    sourceDigest: string;
+}>;
+export declare function planLegacyMigration(options: {
+    deviceRoot: string;
+    gatewayRoot: string;
+    targetRoot: string;
+    backupRoot: string;
+    dryRun?: boolean;
+}): Promise<LegacyMigrationPlan>;
+export declare function applyLegacyMigration(options: {
+    plan: LegacyMigrationPlan;
+}): Promise<{
+    targetRoot: string;
+    backupRoot: string;
+    files: number;
+    sourceDigest: string;
+    rollback: {
+        deviceBackup: string;
+        gatewayBackup: string;
+    };
+}>;
+export {};