@cfour-hi/dsh-plugin-devicex 0.0.0-stage → 1.5.0

package/host/collector.js

@@ -0,0 +1,71 @@
+/**
+ * Device X host collectors — platform dispatcher.
+ *
+ * The data contract (`Metrics`, the six sections, `Inventory`) is identical on
+ * every supported platform; this module only picks the implementation:
+ *
+ *  - `darwin` → `collector-darwin.js` (macOS commands, the original target)
+ *  - `win32`  → `collector-win32.js` (PowerShell/CIM)
+ *
+ * `dsh.bundle.platforms` limits installation to those two hosts; the darwin
+ * branch is the safe fallback for an already-loaded tree on anything else
+ * (every command then fails into the section's `errors[]` instead of throwing).
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/collector
+ */
+import * as darwin from './collector-darwin.js';
+import * as win32 from './collector-win32.js';
+
+/** Host platform. */
+/** @type {import('../../types/contracts.js').Platform} */
+export const PLATFORM = /** @type {import('../../types/contracts.js').Platform} */ (process.platform);
+
+/** Frozen section identifiers, in UI order. */
+export const SECTIONS = ['hardware', 'system', 'software', 'network', 'security', 'processes'];
+
+/** @type {import('../../types/contracts.js').PlatformCollector} */
+const impl = process.platform === 'win32' ? win32 : darwin;
+
+/**
+ * Start slow section collection in the background.
+ * @returns {void}
+ */
+export function warmup() {
+  return impl.warmup();
+}
+
+/**
+ * One fast metrics snapshot for the 2500 ms UI poll.
+ * @returns {Promise<object>}
+ */
+export function collectMetrics() {
+  return impl.collectMetrics();
+}
+
+/**
+ * Collect one section.
+ * @param {string} section one of SECTIONS.
+ * @param {{fresh?: boolean}} [options]
+ * @returns {Promise<object>}
+ */
+export function collectSection(section, options = {}) {
+  return impl.collectSection(section, options);
+}
+
+/**
+ * Full inventory for the panel's initial load and the agent tool.
+ * @param {{sections?: string[], fresh?: boolean}} [options]
+ * @returns {Promise<object>}
+ */
+export function collectInventory(options = {}) {
+  return impl.collectInventory(options);
+}
+
+/**
+ * Drop cached section data.
+ * @param {string} [section]
+ * @returns {void}
+ */
+export function clearCache(section) {
+  return impl.clearCache(section);
+}

package/host/proc.js

@@ -0,0 +1,232 @@
+/**
+ * Shared child-process helpers for the Device X host half.
+ *
+ * Everything in the host collectors/actions goes through here so we get one
+ * place that guarantees: argv-only spawning (never a shell string), a timeout,
+ * a bounded buffer, a deterministic (C) locale for text parsing, and a small
+ * concurrency cap so a full inventory page cannot fork-bomb the machine.
+ *
+ * `run()` never throws and never rejects: every failure is reported in the
+ * resolved result object.
+ *
+ * Plain Node ESM, `node:*` imports only.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/proc
+ */
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+
+/** Default per-command wall-clock timeout. */
+const DEFAULT_TIMEOUT = 10_000;
+/** Default stdout/stderr buffer (system_profiler JSON is well below this). */
+const DEFAULT_MAX_BUFFER = 16 * 1024 * 1024;
+/** Maximum concurrently running child processes. */
+const MAX_CONCURRENT = 12;
+
+let active = 0;
+/** @type {Array<() => void>} */
+const waiters = [];
+
+function acquire() {
+  if (active < MAX_CONCURRENT) {
+    active += 1;
+    return Promise.resolve();
+  }
+  return new Promise((resolve) => waiters.push(() => resolve(undefined)));
+}
+
+function release() {
+  active -= 1;
+  const next = waiters.shift();
+  if (next) {
+    active += 1;
+    next();
+  }
+}
+
+/**
+ * @typedef {object} ExecResult
+ * @property {boolean} ok
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {number|null} code process exit code, null when killed/spawn failed
+ * @property {string|null} signal signal that terminated the child
+ * @property {boolean} timedOut
+ * @property {string|null} error
+ */
+
+/**
+ * Run one executable with an argv array.
+ *
+ * Never throws and never rejects: missing binary, non-zero exit, timeout and
+ * buffer overflow are all reported in the resolved object.
+ *
+ * @param {string} file absolute path or PATH-resolved binary name.
+ * @param {string[]} [args]
+ * @param {object} [options]
+ * @param {number} [options.timeout] milliseconds.
+ * @param {number} [options.maxBuffer] bytes.
+ * @param {NodeJS.ProcessEnv} [options.env] full environment replacement.
+ * @param {string} [options.cwd]
+ * @param {string} [options.input] bytes to write to the child's stdin, then close it.
+ * @returns {Promise<ExecResult>}
+ */
+export function run(file, args = [], options = {}) {
+  const {
+    timeout = DEFAULT_TIMEOUT,
+    maxBuffer = DEFAULT_MAX_BUFFER,
+    env,
+    cwd,
+    input,
+  } = options;
+
+  return acquire().then(
+    () =>
+      new Promise((resolve) => {
+        const childEnv = env ?? { ...process.env, LC_ALL: 'C', LANG: 'C' };
+        /** @param {ExecResult} result */
+        const finish = (result) => {
+          release();
+          resolve(result);
+        };
+        /** @param {unknown} err */
+        const failure = (err) => {
+          const error = /** @type {NodeJS.ErrnoException & {signal?: string|null}} */ (err ?? {});
+          finish({
+            ok: false,
+            stdout: '',
+            stderr: '',
+            code: typeof error.code === 'number' ? error.code : null,
+            signal: /** @type {string|null} */ (error.signal ?? null),
+            timedOut: false,
+            error: String(error.message ?? error),
+          });
+        };
+
+        let child;
+        try {
+          child = execFile(
+            file,
+            args,
+            {
+              timeout,
+              maxBuffer,
+              env: childEnv,
+              cwd,
+              encoding: 'utf8',
+              windowsHide: true,
+            },
+            (err, stdout, stderr) => {
+              if (!err) {
+                finish({
+                  ok: true,
+                  stdout: typeof stdout === 'string' ? stdout : '',
+                  stderr: typeof stderr === 'string' ? stderr : '',
+                  code: 0,
+                  signal: null,
+                  timedOut: false,
+                  error: null,
+                });
+                return;
+              }
+              const error = /** @type {NodeJS.ErrnoException & {killed?: boolean, signal?: string|null}} */ (err);
+              finish({
+                ok: false,
+                stdout: typeof stdout === 'string' ? stdout : '',
+                stderr: typeof stderr === 'string' ? stderr : '',
+                code: typeof error.code === 'number' ? error.code : null,
+                signal: /** @type {string|null} */ (error.signal ?? null),
+                timedOut:
+                  error.killed === true ||
+                  error.signal === 'SIGTERM' ||
+                  error.signal === 'SIGKILL' ||
+                  error.code === 'ETIMEDOUT',
+                error: String(error.message || error),
+              });
+            },
+          );
+        } catch (err) {
+          failure(err);
+          return;
+        }
+        // Async spawn failures are delivered through the callback; this handler
+        // only prevents an unhandled `error` event on the child object.
+        child.on('error', () => {});
+        // Optional stdin payload: used by the Windows PowerShell bridge, whose
+        // scripts routinely exceed the Windows 32,767-character command line
+        // (they are streamed to `powershell -Command -` instead of argv).
+        if (typeof input === 'string' && child.stdin !== null) {
+          child.stdin.on('error', () => {});
+          child.stdin.end(input);
+        } else if (child.stdin !== null) {
+          child.stdin.end();
+        }
+      }),
+  );
+}
+
+/**
+ * Run a command and parse its stdout as JSON. Never throws or rejects.
+ *
+ * @param {string} file
+ * @param {string[]} [args]
+ * @param {object} [options] same as {@link run}.
+ * @returns {Promise<{ok: boolean, data: any, error: string|null, raw: ExecResult}>}
+ */
+export async function runJson(file, args = [], options = {}) {
+  const raw = await run(file, args, options);
+  if (!raw.ok) {
+    return {
+      ok: false,
+      data: null,
+      error: raw.error || `${file} exited with code ${String(raw.code)}`,
+      raw,
+    };
+  }
+  try {
+    return { ok: true, data: JSON.parse(raw.stdout || 'null'), error: null, raw };
+  } catch (err) {
+    return {
+      ok: false,
+      data: null,
+      error: `Invalid JSON from ${file}: ${err instanceof Error ? err.message : String(err)}`,
+      raw,
+    };
+  }
+}
+
+/**
+ * Split command output into trimmed, non-empty lines.
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function lines(text) {
+  return String(text ?? '')
+    .split(/\r?\n/)
+    .filter((line) => line.trim() !== '');
+}
+
+/**
+ * `setTimeout` as a promise (used only for the tiny CPU delta sample).
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * First existing path from a candidate list.
+ * @param {string[]} candidates
+ * @returns {string|null}
+ */
+export function firstExisting(candidates) {
+  for (const candidate of candidates) {
+    try {
+      if (candidate && existsSync(candidate)) return candidate;
+    } catch {
+      /* keep looking */
+    }
+  }
+  return null;
+}

package/host/tool.js

@@ -0,0 +1,254 @@
+/**
+ * Agent-facing Device X tools. Both tools call the same shared operation
+ * surface as the browser API, so the model and the UI can never disagree
+ * about what an action does.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/tool
+ */
+
+/** Sections the read tool accepts, in UI order. */
+const READ_SECTIONS = [
+  'overview',
+  'hardware',
+  'system',
+  'software',
+  'network',
+  'security',
+  'processes',
+  'cleanup',
+];
+
+/** Human byte size helper shared by the tool summaries. */
+function humanBytes(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return 'n/a';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let current = value;
+  while (current >= 1024 && index < units.length - 1) {
+    current /= 1024;
+    index += 1;
+  }
+  return `${current.toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+}
+
+/** Build a compact one-line summary from the fast metrics payload. */
+function summarize(metrics) {
+  const parts = [];
+  if (typeof metrics?.hostname === 'string') parts.push(metrics.hostname);
+  if (typeof metrics?.osVersion === 'string') parts.push(metrics.osVersion);
+  if (typeof metrics?.cpu?.usagePercent === 'number') {
+    parts.push(`CPU ${metrics.cpu.usagePercent.toFixed(0)}%`);
+  }
+  if (typeof metrics?.memory?.totalBytes === 'number') {
+    const used = metrics.memory.usedBytes ?? 0;
+    parts.push(`RAM ${humanBytes(used)}/${humanBytes(metrics.memory.totalBytes)}`);
+  }
+  if (typeof metrics?.disk?.totalBytes === 'number') {
+    const used = metrics.disk.usedBytes ?? 0;
+    parts.push(`Disk ${humanBytes(used)}/${humanBytes(metrics.disk.totalBytes)}`);
+  }
+  if (metrics?.battery?.present === true) parts.push(`Battery ${metrics.battery.percent}%`);
+  if (typeof metrics?.uptimeSec === 'number') {
+    parts.push(`Uptime ${(metrics.uptimeSec / 3600).toFixed(1)}h`);
+  }
+  return parts.length > 0 ? parts.join(' · ') : 'device metrics unavailable';
+}
+
+/** Cap the JSON a tool result hands to the model. */
+function capJson(value, budget = 24000) {
+  let text;
+  try {
+    text = JSON.stringify(value, null, 2);
+  } catch {
+    return '(value could not be serialized)';
+  }
+  if (text.length <= budget) return text;
+  return `${text.slice(0, budget)}\n… (truncated; request a specific section for full data)`;
+}
+
+/**
+ * Register both tools on the plugin's context.
+ * @param {import('../../types/contracts.js').PluginContext} ctx - the plugin context carrying the `tools` service.
+ * @param {import('../../types/contracts.js').PluginOperations} operations - the shared operation surface.
+ * @returns an array of disposers removing the registrations.
+ */
+export function registerTools(ctx, operations) {
+  const actionIds = operations.actionCatalog().map((entry) => entry.id);
+
+  const info = {
+    name: 'device_info',
+    description:
+      'Read this machine\'s device facts: hardware (CPU, memory, GPU, displays, storage, battery, USB, Bluetooth, audio, cameras, drivers, temperatures), system (OS, kernel, boot, users, launch agents), software (installed applications, Homebrew/winget), network (interfaces, Wi-Fi, DNS, routes, listening ports), security (FileVault, SIP, Gatekeeper, BitLocker, Secure Boot, Defender, firewall, permissions), processes, and the cleanup scan (cache/log/trash sizes). ' +
+      'Use section="overview" (default) for a fast health summary, or one of ' +
+      READ_SECTIONS.join('/') +
+      ' for details. Set fresh=true to bypass the collector cache.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        section: {
+          type: 'string',
+          enum: READ_SECTIONS,
+          description: 'Which slice of the device to read. Defaults to overview.',
+        },
+        fresh: {
+          type: 'boolean',
+          description: 'Bypass the section cache and re-collect now.',
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          section: { type: 'string' },
+          summary: { type: 'string' },
+          data: { description: 'The section payload (JSON).' },
+        },
+        required: ['section', 'summary', 'data'],
+      },
+      render(_args, value) {
+        return [
+          { type: 'text', text: value.summary },
+          { type: 'text', text: capJson(value.data) },
+        ];
+      },
+    },
+    async execute(args) {
+      const section = typeof args.section === 'string' ? args.section : 'overview';
+      if (!READ_SECTIONS.includes(section)) {
+        throw new Error(`unknown section: ${section}`);
+      }
+      const fresh = args.fresh === true;
+      if (section === 'overview') {
+        const metrics = await operations.collectMetrics();
+        const catalog = operations.actionCatalog();
+        const data = {
+          metrics,
+          hostname: metrics?.hostname ?? null,
+          osVersion: metrics?.osVersion ?? null,
+          uptimeSec: metrics?.uptimeSec ?? null,
+          availableActions: catalog.map((entry) => entry.id),
+        };
+        return { section, summary: summarize(metrics), data };
+      }
+      if (section === 'cleanup') {
+        const cleanup = await operations.scanCleanup({ fresh });
+        const summary = `cleanup · ${(cleanup.items ?? []).length} items · ${humanBytes(cleanup.totalBytes)} reclaimable`;
+        return { section, summary, data: cleanup };
+      }
+      const data = await operations.collectSection(section, { fresh });
+      const metrics = await operations.collectMetrics();
+      return { section, summary: `${section} · ${summarize(metrics)}`, data };
+    },
+  };
+
+  const control = {
+    name: 'device_control',
+    description:
+      'Operate this machine: signal/kill processes, quit or launch applications, uninstall applications (trash or delete), manage launch agents, change host name / volume / dark mode, toggle Wi-Fi or the firewall, set DNS servers, uninstall Homebrew formulas, flush DNS, empty the trash, sleep or lock the screen, and open System Settings panes. ' +
+      'Every operation is a whitelisted action with strict parameter validation — there is no arbitrary shell execution. ' +
+      'Available actions: ' +
+      actionIds.join(', ') +
+      '. High-danger actions (uninstall, kill, host name, firewall, DNS) are irreversible: confirm with the user and state what you are about to do before calling them.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          enum: actionIds,
+          description: 'The action id to run.',
+        },
+        params: {
+          type: 'object',
+          additionalProperties: true,
+          description:
+            'Action-specific parameters (see device_info action catalog or the Device X 操作 page). Omit for actions with no parameters.',
+        },
+      },
+      required: ['action'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          message: { type: 'string' },
+          data: { description: 'Optional action payload.' },
+        },
+        required: ['ok', 'message'],
+      },
+      render(_args, value) {
+        const head = value.ok ? `OK: ${value.message}` : `FAILED: ${value.message}`;
+        return [
+          { type: 'text', text: head },
+          ...(value.data === undefined
+            ? []
+            : [{ type: 'text', text: capJson(value.data, 8000) }]),
+        ];
+      },
+    },
+    async execute(args) {
+      if (typeof args.action !== 'string' || !actionIds.includes(args.action)) {
+        throw new Error(`unknown device action: ${String(args.action)}`);
+      }
+      const params = typeof args.params === 'object' && args.params !== null ? args.params : {};
+      return operations.runAction(args.action, params);
+    },
+  };
+
+  const bench = {
+    name: 'device_benchmark',
+    description:
+      'Run the repeatable Device X benchmark on this machine: CPU (ops/s, single- and multi-thread), memory bandwidth (GB/s) and disk throughput (MB/s, temp file). Fixed work per run, bounded to a few seconds, no network. Scores are only comparable on the same machine over time — they are not an internet rating. ' +
+      'Default runs all three tests; pass tests to select a subset and repeat=true to keep the better of two runs.',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        tests: {
+          type: 'array',
+          items: { type: 'string', enum: ['cpu', 'memory', 'disk'] },
+          description: 'Subset of tests to run. Omit for all three.',
+        },
+        repeat: {
+          type: 'boolean',
+          description: 'Run each test twice and keep the better score.',
+        },
+      },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean' },
+          summary: { type: 'string' },
+          data: { description: 'The full benchmark payload (JSON).' },
+        },
+        required: ['ok', 'summary', 'data'],
+      },
+      render(_args, value) {
+        return [
+          { type: 'text', text: value.summary },
+          { type: 'text', text: capJson(value.data, 8000) },
+        ];
+      },
+    },
+    async execute(args) {
+      const tests = Array.isArray(args.tests)
+        ? args.tests.filter((id) => typeof id === 'string')
+        : [];
+      const result = await operations.runBenchmark({ tests, repeat: args.repeat === true });
+      const rows = (result.benchmark?.results ?? []).map(
+        (entry) => `${entry.id}: ${entry.score ?? 'n/a'} ${entry.unit ?? ''}`.trim(),
+      );
+      return { ok: result.ok === true, summary: rows.join(' · '), data: result.benchmark };
+    },
+  };
+
+  return [ctx.tools.register(info), ctx.tools.register(control), ctx.tools.register(bench)];
+}