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

package/host/transport.js

@@ -0,0 +1,316 @@
+/**
+ * The Device X browser API: same-origin JSON routes on the DSH Web server,
+ * each behind the shipped Connection trust fence (the page's signed session
+ * cookie authenticates the caller; foreign origins are rejected by the
+ * Host/Origin fence). Route handlers never shell out themselves — they call
+ * the shared operation surface, exactly like the agent tools.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/transport
+ */
+
+/** URL prefix owned by this plugin. */
+const API_PREFIX = '/devicex/api';
+
+/** Action request bodies are tiny JSON objects; anything larger is hostile. */
+const MAX_BODY_BYTES = 256 * 1024;
+
+/** Reject malformed or unknown section names before they reach collection. */
+function isSection(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+/** JSON response, always uncached: device facts are live facts. */
+function sendJson(res, status, payload) {
+  res.statusCode = status;
+  res.setHeader('content-type', 'application/json; charset=utf-8');
+  res.setHeader('cache-control', 'no-store');
+  res.end(JSON.stringify(payload));
+}
+
+/** 405 with the route's one supported method. */
+function sendMethodNotAllowed(res, allow) {
+  res.statusCode = 405;
+  res.setHeader('allow', allow);
+  res.end();
+}
+
+/** Collect a bounded request body as UTF-8 text; null past the ceiling. */
+async function readBoundedBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.byteLength;
+    if (size > MAX_BODY_BYTES) {
+      req.resume();
+      return null;
+    }
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks, size).toString('utf8');
+}
+
+/** Apply the connection trust fence; true when the request was rejected. */
+function rejected(ctx, req, res) {
+  const rejection = ctx.connection.requestRejection(req);
+  if (rejection === undefined) return false;
+  res.statusCode = rejection;
+  res.end();
+  return true;
+}
+
+/** Parse the request URL against a placeholder origin (only path/query matter). */
+function requestUrl(req) {
+  try {
+    return new URL(String(req.url), 'http://localhost');
+  } catch {
+    return new URL('http://localhost/');
+  }
+}
+
+/** Answer a GET/HEAD route, containing any handler failure as a 500. */
+function guarded(handler) {
+  return async (req, res) => {
+    try {
+      await handler(req, res);
+    } catch (error) {
+      if (!res.headersSent) {
+        sendJson(res, 500, {
+          ok: false,
+          error: {
+            code: 'internal',
+            message: error instanceof Error ? error.message : String(error),
+          },
+        });
+      } else {
+        res.destroy();
+      }
+    }
+  };
+}
+
+/**
+ * Register every Device X route as one disposable effect.
+ * @param {import('../../types/contracts.js').PluginContext} ctx - the plugin context carrying `webServer` and `connection`.
+ * @param {import('../../types/contracts.js').PluginOperations} operations - the shared operation surface.
+ * @returns the disposer removing every route.
+ */
+export function registerRoutes(ctx, operations) {
+  const disposers = [];
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/metrics`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'GET') return sendMethodNotAllowed(res, 'GET');
+      const metrics = await operations.collectMetrics();
+      sendJson(res, 200, { ok: true, metrics });
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/inventory`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'GET') return sendMethodNotAllowed(res, 'GET');
+      const url = requestUrl(req);
+      const section = url.searchParams.get('section');
+      const fresh = url.searchParams.get('fresh') === '1';
+      if (section !== null && section !== '') {
+        if (!isSection(section) || !operations.SECTIONS.includes(section)) {
+          sendJson(res, 400, {
+            ok: false,
+            error: { code: 'unknown-section', message: `unknown section: ${section}` },
+          });
+          return;
+        }
+        const data = await operations.collectSection(section, { fresh });
+        sendJson(res, 200, { ok: true, section, data });
+        return;
+      }
+      const data = await operations.collectInventory({ fresh });
+      sendJson(res, 200, { ok: true, section: null, data });
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/actions`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'GET') return sendMethodNotAllowed(res, 'GET');
+      sendJson(res, 200, {
+        ok: true,
+        platform: operations.PLATFORM,
+        sections: operations.SECTIONS,
+        actions: operations.actionCatalog(),
+        history: operations.actionHistory(),
+      });
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/action`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'POST') return sendMethodNotAllowed(res, 'POST');
+      const contentType = String(req.headers['content-type'] ?? '')
+        .split(';', 1)[0]
+        .trim()
+        .toLowerCase();
+      if (contentType !== 'application/json') {
+        sendJson(res, 415, {
+          ok: false,
+          error: { code: 'unsupported-media-type', message: 'content-type must be application/json' },
+        });
+        return;
+      }
+      let text;
+      try {
+        text = await readBoundedBody(req);
+      } catch {
+        sendJson(res, 400, {
+          ok: false,
+          error: { code: 'bad-request', message: 'request body unreadable' },
+        });
+        return;
+      }
+      if (text === null) {
+        sendJson(res, 413, {
+          ok: false,
+          error: { code: 'payload-too-large', message: 'request body is too large' },
+        });
+        return;
+      }
+      let body;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = undefined;
+      }
+      if (typeof body !== 'object' || body === null || typeof body.action !== 'string') {
+        sendJson(res, 400, {
+          ok: false,
+          error: {
+            code: 'bad-request',
+            message: 'body must be a JSON object with a string "action" and optional object "params"',
+          },
+        });
+        return;
+      }
+      const params = typeof body.params === 'object' && body.params !== null ? body.params : {};
+      const result = await operations.runAction(body.action, params);
+      sendJson(res, 200, result);
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/cleanup`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'GET') return sendMethodNotAllowed(res, 'GET');
+      const url = requestUrl(req);
+      const fresh = url.searchParams.get('fresh') === '1';
+      const cleanup = await operations.scanCleanup({ fresh });
+      sendJson(res, 200, { ok: true, cleanup });
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/footprint`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'GET') return sendMethodNotAllowed(res, 'GET');
+      const url = requestUrl(req);
+      const appPath = url.searchParams.get('path');
+      const fresh = url.searchParams.get('fresh') === '1';
+      if (appPath === null || appPath.trim() === '') {
+        sendJson(res, 400, {
+          ok: false,
+          error: { code: 'missing-path', message: 'query parameter "path" is required' },
+        });
+        return;
+      }
+      // Read-only: no action-history entry, no filesystem writes.
+      const footprint = await operations.scanFootprint({ path: appPath, fresh });
+      sendJson(res, 200, { ok: true, footprint });
+    }),
+  }));
+
+  disposers.push(ctx.webServer.register({
+    kind: 'exact',
+    path: `${API_PREFIX}/benchmark`,
+    handler: guarded(async (req, res) => {
+      if (rejected(ctx, req, res)) return;
+      if (req.method !== 'POST') return sendMethodNotAllowed(res, 'POST');
+      const contentType = String(req.headers['content-type'] ?? '')
+        .split(';', 1)[0]
+        .trim()
+        .toLowerCase();
+      if (contentType !== 'application/json') {
+        sendJson(res, 415, {
+          ok: false,
+          error: { code: 'unsupported-media-type', message: 'content-type must be application/json' },
+        });
+        return;
+      }
+      let text;
+      try {
+        text = await readBoundedBody(req);
+      } catch {
+        sendJson(res, 400, {
+          ok: false,
+          error: { code: 'bad-request', message: 'request body unreadable' },
+        });
+        return;
+      }
+      if (text === null) {
+        sendJson(res, 413, {
+          ok: false,
+          error: { code: 'payload-too-large', message: 'request body is too large' },
+        });
+        return;
+      }
+      /** @type {any} */
+      let body = {};
+      if (text.trim() !== '') {
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = undefined;
+        }
+      }
+      if (typeof body !== 'object' || body === null) {
+        sendJson(res, 400, {
+          ok: false,
+          error: { code: 'bad-request', message: 'body must be a JSON object' },
+        });
+        return;
+      }
+      const tests = body.tests;
+      if (tests !== undefined && (!Array.isArray(tests) || tests.some((id) => typeof id !== 'string'))) {
+        sendJson(res, 400, {
+          ok: false,
+          error: { code: 'bad-request', message: '"tests" must be an array of test ids' },
+        });
+        return;
+      }
+      const benchmark = await operations.runBenchmark({ tests, repeat: body.repeat === true });
+      sendJson(res, 200, benchmark);
+    }),
+  }));
+
+  return () => {
+    for (const dispose of disposers.splice(0).reverse()) {
+      try {
+        dispose();
+      } catch {
+        // A route disposer that already ran must not block the rest.
+      }
+    }
+  };
+}

package/host/uninstall.js

@@ -0,0 +1,244 @@
+/**
+ * Device X — uninstall pipeline.
+ *
+ * One shared state machine so both platforms behave identically and the
+ * ordering rule is enforced in exactly one place:
+ *
+ *     scan -> [user confirms] -> uninstall -> VERIFY -> trash app -> re-scan -> trash leftovers
+ *
+ * Two invariants matter more than the happy path:
+ *
+ *  1. **Verification gates everything.** A vendor uninstaller exiting 0 is not
+ *     evidence that the app is gone (MSI returns 0/3010/1641, vendor scripts
+ *     lie). If the app is still installed afterwards, the run aborts and
+ *     *nothing* is deleted — the failure path has zero side effects.
+ *  2. **A missing uninstaller is not a failure.** Only 2 of 79 measured apps
+ *     ship one; treating "none" as failure would disable the feature almost
+ *     everywhere. So `hasUninstaller: false` skips straight to trashing the app.
+ *
+ * The pipeline never invents paths. Leftover items come from a scan token
+ * resolved by `footprint.resolveScanItems`, and the platform adapter performs
+ * the actual moves.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/uninstall
+ */
+
+/**
+ * @typedef {object} UninstallSteps
+ * @property {(appPath: string) => Promise<{ok: boolean, message: string, code?: string}>} uninstallApp
+ *   run the vendor uninstaller; `ok: false` aborts the pipeline
+ * @property {(appPath: string) => Promise<boolean>} isStillInstalled
+ *   objective post-condition check (path gone / registry key gone)
+ * @property {(appPath: string) => Promise<{ok: boolean, message: string, destination?: string, code?: string}>} trashApp
+ * @property {(absolutePath: string) => Promise<{ok: boolean, message: string, code?: string}>} trashPath
+ *   move one leftover to the trash
+ * @property {(appPath: string) => Promise<object>} rescan
+ *   re-run the footprint scan after the app is gone
+ */
+
+/** Pipeline outcomes, in the order they can occur. */
+export const PHASES = Object.freeze([
+  'uninstall',
+  'verify',
+  'trash-app',
+  'rescan',
+  'trash-leftovers',
+  'done',
+]);
+
+/**
+ * Format bytes for a user-facing message.
+ * @param {unknown} value
+ * @returns {string}
+ */
+function humanBytes(value) {
+  const bytes = Number(value);
+  if (!Number.isFinite(bytes) || bytes <= 0) return '0 B';
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let index = 0;
+  let current = bytes;
+  while (current >= 1024 && index < units.length - 1) {
+    current /= 1024;
+    index += 1;
+  }
+  return `${current.toFixed(index === 0 ? 0 : 1)} ${units[index]}`;
+}
+
+/**
+ * Run the uninstall pipeline.
+ *
+ * @param {object} request
+ * @param {string} request.appPath resolved application path / install location
+ * @param {boolean} request.hasUninstaller whether the app ships its own uninstaller
+ * @param {boolean} [request.cleanupApp] move the app itself to the trash when
+ *   there is no uninstaller (or after it ran); default true
+ * @param {Array<{id: string, path: string}>} [request.items] leftovers chosen by
+ *   the user; already resolved through the scan token
+ * @param {number} [request.leftoverBytes] bytes those leftovers occupy, used
+ *   only for the user-facing message
+ * @param {UninstallSteps} steps platform adapter
+ * @returns {Promise<object>} a JSON-safe report
+ */
+export async function runUninstallPipeline(request, steps) {
+  const startedAt = Date.now();
+  const appPath = typeof request?.appPath === 'string' ? request.appPath : '';
+  /** @type {string[]} */
+  const errors = [];
+
+  /** @type {object} */
+  const report = {
+    ok: false,
+    aborted: false,
+    phase: 'uninstall',
+    appPath,
+    uninstaller: {
+      ran: false,
+      ok: false,
+      message: '',
+    },
+    verified: false,
+    appTrashed: false,
+    appTrashPath: null,
+    leftoversRequested: Array.isArray(request?.items) ? request.items.length : 0,
+    leftoversRemoved: 0,
+    leftoversFailed: 0,
+    leftoverBytes: 0,
+    leftoverResults: [],
+    errors,
+    durationMs: 0,
+  };
+
+  const finish = (phase, ok, message) => {
+    report.phase = phase;
+    report.ok = ok;
+    report.message = message;
+    report.durationMs = Date.now() - startedAt;
+    return report;
+  };
+
+  const abort = (phase, message) => {
+    report.phase = phase;
+    report.aborted = true;
+    report.ok = false;
+    report.message = message;
+    report.durationMs = Date.now() - startedAt;
+    return report;
+  };
+
+  if (appPath === '') return abort('uninstall', 'No application path was supplied.');
+
+  // ---- 1. vendor uninstaller (only when one exists) ----------------------
+  if (request.hasUninstaller === true) {
+    report.phase = 'uninstall';
+    const result = await steps.uninstallApp(appPath);
+    report.uninstaller.ran = true;
+    report.uninstaller.ok = result?.ok === true;
+    report.uninstaller.message = typeof result?.message === 'string' ? result.message : '';
+    if (report.uninstaller.ok !== true) {
+      // Invariant 2: the failure path changes nothing on disk.
+      return abort(
+        'uninstall',
+        `The application's own uninstaller did not complete, so nothing was removed. ${report.uninstaller.message}`.trim(),
+      );
+    }
+  }
+
+  // ---- 2. verify the app is actually gone --------------------------------
+  // Verification only makes sense as a gate after something claimed to remove
+  // the app. When there is no vendor uninstaller the app is obviously still
+  // installed - that is the expected state, and step 3 removes it - so asking
+  // and then aborting would make the feature unusable for 77 of 79 apps.
+  report.phase = 'verify';
+  if (request.hasUninstaller === true) {
+    let stillInstalled;
+    try {
+      stillInstalled = await steps.isStillInstalled(appPath);
+    } catch (error) {
+      errors.push(`verification failed: ${error instanceof Error ? error.message : String(error)}`);
+      return abort('verify', 'Could not verify whether the application was removed, so nothing was deleted.');
+    }
+    if (stillInstalled === true) {
+      return abort(
+        'verify',
+        'The application is still installed after its uninstaller finished, so nothing was deleted.',
+      );
+    }
+  }
+  report.verified = true;
+
+  // ---- 3. move the app itself to the trash ------------------------------
+  // After a successful vendor uninstall the bundle is usually already gone;
+  // only attempt the move when something is still there.
+  if (request.cleanupApp !== false) {
+    report.phase = 'trash-app';
+    let appStillThere = false;
+    try {
+      appStillThere = await steps.isStillInstalled(appPath);
+    } catch {
+      appStillThere = false;
+    }
+    if (appStillThere) {
+      const moved = await steps.trashApp(appPath);
+      report.appTrashed = moved?.ok === true;
+      report.appTrashPath = typeof moved?.destination === 'string' ? moved.destination : null;
+      if (moved?.ok !== true) {
+        return abort(
+          'trash-app',
+          `Could not move the application to the Trash, so no leftovers were touched. ${
+            typeof moved?.message === 'string' ? moved.message : ''
+          }`.trim(),
+        );
+      }
+    }
+  }
+
+  // ---- 4. re-scan, because the uninstaller may have cleaned some data ----
+  report.phase = 'rescan';
+  if (Array.isArray(request?.items) && request.items.length > 0) {
+    try {
+      const after = await steps.rescan(appPath);
+      report.rescan = {
+        items: Array.isArray(after?.items) ? after.items.length : 0,
+        totalBytes: Number(after?.totalBytes) || 0,
+        errors: Array.isArray(after?.errors) ? after.errors.slice(0, 5) : [],
+      };
+    } catch (error) {
+      errors.push(`re-scan failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  // ---- 5. move the chosen leftovers to the trash ------------------------
+  if (Array.isArray(request?.items) && request.items.length > 0) {
+    report.phase = 'trash-leftovers';
+    for (const item of request.items) {
+      const path = typeof item?.path === 'string' ? item.path : '';
+      if (path === '') continue;
+      const outcome = await steps.trashPath(path);
+      const ok = outcome?.ok === true;
+      if (ok) report.leftoversRemoved += 1;
+      else report.leftoversFailed += 1;
+      report.leftoverResults.push({
+        id: typeof item?.id === 'string' ? item.id : '',
+        path,
+        ok,
+        message: typeof outcome?.message === 'string' ? outcome.message : '',
+      });
+    }
+    report.leftoverBytes = Number(request.leftoverBytes) || 0;
+  }
+
+  const leftoverPart =
+    report.leftoversRequested === 0
+      ? 'No leftover directories were selected.'
+      : report.leftoversFailed === 0
+        ? `Moved ${report.leftoversRemoved} leftover location(s) to the Trash (${humanBytes(report.leftoverBytes)}).`
+        : `Moved ${report.leftoversRemoved} of ${report.leftoversRequested} leftover location(s) to the Trash; ${report.leftoversFailed} could not be moved.`;
+
+  // Trash is not freed space; say so rather than implying the disk grew.
+  const spaceHint =
+    report.leftoverBytes > 0
+      ? ` Empty the Trash to actually free ${humanBytes(report.leftoverBytes)}.`
+      : '';
+
+  return finish('done', report.leftoversFailed === 0, `${leftoverPart}${spaceHint}`.trim());
+}