nc-agent 0.1.2 → 0.1.4

package/README.md

@@ -0,0 +1,16 @@
+# nc-agent
+
+Node Command device pairing and agent installer.
+
+## Usage
+
+```bash
+# Interactive RFC 8628 pairing (8-character code displayed in terminal)
+npx nc-agent
+
+# Direct pairing with host ID and enrollment token
+npx nc-agent <host_id> <enrollment_token>
+
+# Uninstall the agent from the canonical system directory
+npx nc-agent uninstall
+```

package/bin/nc.mjs

@@ -15,6 +15,7 @@ import {
   findRemovalTargets,
   getNcRootForMode,
   installerEnvForMode,
+  isElevated,
   modeWarningFor,
   runUninstallerScript,
   uninstallFailureSuggestion,
@@ -324,21 +325,24 @@ export async function downloadToFile(targetUrl, destinationPath, extraHeaders =
 }
 
 /**
- * Determines the installation root (NC_ROOT) dynamically based on OS:
- * - Windows: %LOCALAPPDATA%\nc
+ * Determines the canonical installation root (NC_ROOT) dynamically based on
+ * OS:
+ * - Windows: %ProgramData%\NC (the machine-wide root; user-space
+ *   %LOCALAPPDATA%\nc is never a default — see getNcRootForMode('user'))
  * - macOS: ~/Library/Application Support/nc
  * - Linux (root): /opt/nc
  * - Linux (non-root): ~/.local/share/nc
+ * An explicit NC_ROOT always wins. Probes are injectable for deterministic
+ * tests.
+ * @param {{ platform?: string, env?: NodeJS.ProcessEnv }} [options]
  * @returns {string}
  */
-export function getNcRoot() {
-  if (process.env.NC_ROOT) {
-    return process.env.NC_ROOT;
+export function getNcRoot({ platform = os.platform(), env = process.env } = {}) {
+  if (env.NC_ROOT) {
+    return env.NC_ROOT;
   }
-  const platform = os.platform();
   if (platform === 'win32') {
-    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
-    return path.join(localAppData, 'nc');
+    return path.join(env.ProgramData || 'C:\\ProgramData', 'NC');
   }
   if (platform === 'darwin') {
     return path.join(os.homedir(), 'Library', 'Application Support', 'nc');
@@ -1375,6 +1379,7 @@ function printCliHelp() {
       'Usage:',
       '  nodecommand                          pair this machine via the browser device flow',
       '  nodecommand setup [host_id token]    install the agent (auto system/user mode; no args = browser device flow)',
+      '  nodecommand uninstall [--yes]        remove the agent from the canonical root (alias: remove)',
       '  nodecommand remove [--yes]           uninstall the agent (asks for confirmation unless --yes)',
       '  nodecommand --diagnostics            preview a redacted diagnostics bundle (dry-run, writes nothing)',
       '  nodecommand --diagnostics --apply    write the diagnostics bundle (.tar.gz) for a support ticket',
@@ -1406,6 +1411,10 @@ async function main() {
     await runSetup(subArgs);
     return;
   }
+  if (subcommand === 'uninstall') {
+    await runUninstall(subArgs);
+    return;
+  }
   if (subcommand === 'remove') {
     await runRemove(subArgs);
     return;
@@ -1525,11 +1534,53 @@ function printSetupSuccess({ hostId, serverUrl, installMode = undefined, resumed
   console.log('status: agent credentials verified online');
 }
 
+/**
+ * Guidance printed when Windows UAC elevation for a system-wide install is
+ * unavailable (headless shell) or was declined by the operator.
+ */
+const WINDOWS_ELEVATION_INSTALL_DECLINED =
+  'Elevation unavailable or declined. Please run as Administrator in an elevated shell for a system-wide install at C:\\ProgramData\\NC.';
+
+/**
+ * Guidance printed when Windows UAC elevation for uninstallation is
+ * unavailable (headless shell) or was declined by the operator.
+ */
+const WINDOWS_ELEVATION_UNINSTALL_DECLINED =
+  'Elevation unavailable or declined. Please run as Administrator in an elevated shell to uninstall the agent from C:\\ProgramData\\NC.';
+
+/**
+ * Re-runs the current CLI invocation elevated through the Windows UAC prompt
+ * (`Start-Process -Verb RunAs -Wait`; stdio stays inherited so the elevated
+ * console is visible) and returns the spawnSync result. Never throws: a
+ * missing powershell or a declined prompt resolves to null/non-zero.
+ */
+function requestWindowsElevation() {
+  const args = [...process.argv.slice(1)];
+  try {
+    return child_process.spawnSync(
+      'powershell',
+      [
+        '-NoProfile',
+        '-Command',
+        `Start-Process -FilePath "${process.execPath}" -ArgumentList ${args
+          .map((a) => `"${String(a).replace(/"/g, '`"')}"`)
+          .join(',')} -Verb RunAs -Wait`
+      ],
+      { stdio: 'inherit' }
+    );
+  } catch {
+    return null;
+  }
+}
+
 /**
  * `nodecommand setup [host_id enrollment_token]`.
  *
- * Mode is automatic (never prompted): elevated processes install system-wide,
- * everything else installs per-user with a single-line capability notice.
+ * Mode is automatic (never prompted): elevated processes install machine-wide.
+ * POSIX: a non-root admin requests sudo; a refusal falls back to a per-user
+ * install with a single-line capability notice. Windows: a standard shell
+ * requests UAC elevation instead and hard-stops (exit 1) when elevation is
+ * unavailable or declined — never a silent %LOCALAPPDATA% degradation.
  * Without arguments a fresh enrollment is requested via the browser device
  * flow; with `host_id` + `token` (dashboard flow) the supplied enrollment is
  * redeemed directly. Enrollment always goes through POST /api/enroll with the
@@ -1563,10 +1614,21 @@ export async function runSetup(args = []) {
   }
   let installMode = decideInstallMode();
   // A non-root admin must not silently fall back to a per-user install: the
-  // install root, service scope and privileged helper all differ. Request sudo
-  // (the password prompt IS the admin request) and re-run elevated so the
-  // install lands machine-wide at the canonical system root.
+  // install root, service scope and privileged helper all differ. POSIX
+  // requests sudo and re-runs elevated; Windows requests UAC (Start-Process
+  // -Verb RunAs) so the install lands machine-wide at the canonical system
+  // root. A refused or unavailable Windows elevation is a hard stop: the CLI
+  // never silently degrades a system install into %LOCALAPPDATA%.
   if (installMode === 'user' && canElevate() && !process.env.NC_ELEVATED) {
+    if (os.platform() === 'win32') {
+      if (process.stdin.isTTY) {
+        console.log('Admin rights required for a system-wide install. Requesting UAC elevation…');
+        const elevated = requestWindowsElevation();
+        if (elevated && elevated.status === 0) process.exit(0);
+      }
+      console.error(WINDOWS_ELEVATION_INSTALL_DECLINED);
+      process.exit(1);
+    }
     console.log('Admin rights required for a system-wide install. Requesting sudo…');
     const elevated = child_process.spawnSync(
       'sudo',
@@ -1636,30 +1698,47 @@ export function confirmPrompt(question, openInterface = null) {
 }
 
 /**
- * `nodecommand remove [--yes]`. Idempotent: no install found means success
- * (exit 0). Otherwise the uninstaller living inside each installed tree is
- * executed (never a downloaded copy) and its exit status is reported.
+ * Shared engine for `remove`/`uninstall`: idempotent (no install found means
+ * success, exit 0); otherwise the uninstaller living inside each installed
+ * tree is executed (never a downloaded copy) and its exit status is reported.
+ * Target discovery is centered on the canonical root (candidateInstallRoots
+ * lists it first) and treats an unreadable system tree as installed, so a
+ * non-root shell routes it to the elevated uninstaller instead of reporting
+ * "nothing to remove".
  * @param {string[]} args
+ * @param {{ command: string, emptyMessage: string, elevateOnWindows?: boolean, completionMessage: string }} options
  */
-export async function runRemove(args = []) {
+async function runRemoval(args, { command, emptyMessage, elevateOnWindows = false, completionMessage }) {
   if (args.includes('--help') || args.includes('-h') || args.includes('help')) {
     printCliHelp();
     return;
   }
-  assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], 'remove');
+  assertKnownFlags(args, ['--yes', '-y', '--help', '-h'], command);
   const stray = args.filter((a) => !a.startsWith('-') && a !== 'help');
   if (stray.length > 0) {
-    console.error(`error: [UNKNOWN_ARGUMENT] \`remove\` takes no positional arguments (got: ${stray.join(', ')}).`);
-    console.error('suggested_action: Run `nodecommand remove --yes` (or plain `nodecommand remove` to be asked).');
+    console.error(`error: [UNKNOWN_ARGUMENT] \`${command}\` takes no positional arguments (got: ${stray.join(', ')}).`);
+    console.error(`suggested_action: Run \`nodecommand ${command} --yes\` (or plain \`nodecommand ${command}\` to be asked).`);
     process.exit(1);
   }
   const yes = args.includes('--yes') || args.includes('-y');
   const { install, unreadable } = findRemovalTargets();
   const targets = [...install, ...unreadable];
   if (targets.length === 0) {
-    console.log('No Node Command installation found (nothing to remove).');
+    console.log(emptyMessage);
     return;
   }
+  // Windows: a machine-wide tree at C:\ProgramData\NC cannot be removed from
+  // a standard shell — request UAC (Start-Process -Verb RunAs) and re-run this
+  // same command elevated. Declined or headless elevation is a hard stop.
+  if (elevateOnWindows && os.platform() === 'win32' && !isElevated()) {
+    if (process.stdin.isTTY) {
+      console.log('Admin rights required to remove the system-wide agent. Requesting UAC elevation…');
+      const elevated = requestWindowsElevation();
+      if (elevated && elevated.status === 0) process.exit(0);
+    }
+    console.error(WINDOWS_ELEVATION_UNINSTALL_DECLINED);
+    process.exit(1);
+  }
   console.log(`Found Node Command installation(s): ${targets.join(', ')}`);
   if (unreadable.length > 0) {
     console.log(
@@ -1668,11 +1747,11 @@ export async function runRemove(args = []) {
   }
   if (!yes) {
     if (!process.stdin.isTTY) {
-      console.error('error: [CONFIRMATION_REQUIRED] remove needs confirmation in non-interactive shells.');
-      console.error('suggested_action: Re-run as `nodecommand remove --yes`.');
+      console.error(`error: [CONFIRMATION_REQUIRED] ${command} needs confirmation in non-interactive shells.`);
+      console.error(`suggested_action: Re-run as \`nodecommand ${command} --yes\`.`);
       process.exit(1);
     }
-    const confirmed = await confirmPrompt(`Remove ${targets.length === 1 ? 'this installation' : 'these installations'}? [y/N] `);
+    const confirmed = await confirmPrompt(`${command === 'uninstall' ? 'Uninstall' : 'Remove'} ${targets.length === 1 ? 'this installation' : 'these installations'}? [y/N] `);
     if (!confirmed) {
       console.log('Aborted (nothing removed).');
       return;
@@ -1713,7 +1792,40 @@ export async function runRemove(args = []) {
     }
   }
   if (failed > 0) process.exit(1);
-  console.log('Remove complete.');
+  console.log(completionMessage);
+}
+
+/**
+ * `nodecommand remove [--yes]` — legacy name for the canonical uninstall.
+ * @param {string[]} args
+ */
+export async function runRemove(args = []) {
+  return runRemoval(args, {
+    command: 'remove',
+    emptyMessage: 'No Node Command installation found (nothing to remove).',
+    completionMessage: 'Remove complete.'
+  });
+}
+
+/**
+ * `nodecommand uninstall [--yes]` (alias: `remove`). Resolves the canonical
+ * install root (`getNcRoot()`), verifies an agent tree actually lives there
+ * (readable markers, or an unreadable system tree that requires elevation),
+ * and invokes the in-tree platform uninstaller:
+ * - Windows: `powershell -NoProfile -ExecutionPolicy Bypass -File <root>\uninstall.ps1`
+ *   after requesting UAC (`Start-Process -Verb RunAs`) when not elevated
+ * - POSIX: `sudo <root>/uninstall.sh`, run directly when already root
+ * When no agent is installed the command reports the canonical root and
+ * exits cleanly.
+ * @param {string[]} args
+ */
+export async function runUninstall(args = []) {
+  return runRemoval(args, {
+    command: 'uninstall',
+    emptyMessage: `No active NC agent installation found at ${getNcRoot()}.`,
+    elevateOnWindows: true,
+    completionMessage: 'Uninstall complete.'
+  });
 }
 
 /**

package/lib/setup.mjs

@@ -74,17 +74,19 @@ export function decideInstallMode(options = {}) {
 
 /**
  * True when the current user CAN elevate to a machine-wide install even when
- * the process is not root yet: POSIX admin groups (sudo/admin/wheel) or an
- * already-elevated process. Used so a non-root admin is asked for sudo instead
- * of silently degrading to a per-user install (different root, service scope
- * and no privileged helper).
+ * the process is not root yet: an already-elevated process, a Windows
+ * standard shell (UAC `Start-Process -Verb RunAs` is always available), or
+ * POSIX admin groups (sudo/admin/wheel). Used so a non-root admin is asked
+ * for elevation instead of silently degrading to a per-user install
+ * (different root, service scope and no privileged helper).
  * @param {{ platform?: string, getuid?: (() => number)|null, isAdmin?: boolean|null, runAdminCheck?: (() => boolean)|null }} [options]
  */
 export function canElevate(options = {}) {
   if (isElevated(options)) return true;
   const platform = options.platform || os.platform();
-  // Windows: isElevated already answers "is administrator".
-  if (platform === 'win32') return false;
+  // Windows: a non-elevated process can still relaunch itself through the
+  // UAC prompt, so elevation is available even when not administrator.
+  if (platform === 'win32') return true;
   try {
     const r = child_process.spawnSync('id', ['-nG'], { encoding: 'utf8' });
     const groups = r && typeof r.stdout === 'string' ? r.stdout : '';

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "nc-agent",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Node Command device pairing and agent installer. Run npx nc-agent to pair this machine with your Node Command workspace.",
   "type": "module",
   "license": "Apache-2.0",
-  "engines": { "node": ">=22.5.0" },
-  "bin": { "nc-agent": "./bin/nc.mjs" },
-  "files": ["bin/", "lib/"]
+  "bin": {
+    "nc-agent": "./bin/nc.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ]
 }