crewx 0.9.0-rc.14 → 0.9.0-rc.141

package/bin/cli-commands.js

@@ -14,16 +14,18 @@ export const CLI_SUBCOMMANDS = new Set([
 
   // Agent / Task
   'agent',
-  'ps', 'kill', 'result', 'log', 'restart',
+  'ps', 'stop', 'kill', 'result', 'log', 'restart',
 
   // Diagnostics / Init / DB
   'doctor', 'init',
   'db',
   'help',
+  'shortcut',
+  'publish',
 
   // Built-in tools
   'memory', 'search', 'doc', 'wbs', 'cron', 'workflow', 'skill', 'dreaming',
-  'wi', 'chromex',
+  'wi', 'chromex', 'notify', 'app',
 
   // Hook platform
   'hook', 'hook-dispatch',

package/bin/crewx-lib.js

@@ -1,12 +1,104 @@
 /**
  * crewx launcher library — testable pure-logic functions extracted from crewx.js.
  */
-import { mkdirSync } from 'fs';
+import { lstatSync, mkdirSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
+import { getCrewxHome } from '@crewx/sdk';
 import { CLI_SUBCOMMANDS } from './cli-commands.js';
 import { buildHintMessage } from './launcher-flags.js';
 
+const PAIRING_CREDENTIAL_MODE = 0o600;
+const PAIRING_CREDENTIAL_NAME = 'pairing.token';
+const DEFAULT_PAIRING_ENDPOINT = 'http://localhost:8150';
+// Mirrors the WI-028 packages/built-in/shared/crewx-api-credential contract.
+const PAIRING_CREDENTIAL_PATTERN = /^crewxrt_pairing_[0-9a-f]{64}$/;
+
+
+function currentUid() {
+  return process.platform === 'win32' || typeof process.getuid !== 'function'
+    ? undefined
+    : process.getuid();
+}
+
+/**
+ * Return the canonical runtime credential path used by the local server.
+ * The path is intentionally resolved through the SDK's shared home helper.
+ *
+ * @returns {string}
+ */
+export function pairingCredentialPath() {
+  return join(getCrewxHome(), 'auth', 'runtime', PAIRING_CREDENTIAL_NAME);
+}
+
+/**
+ * Read the purpose-scoped pairing credential with the WI-028 file contract.
+ * Missing, unreadable, or insecure files throw before any HTTP request can be
+ * made. Error messages never include the credential value.
+ *
+ * @returns {string}
+ */
+export function readPairingCredential() {
+  const filePath = pairingCredentialPath();
+  let fileStat;
+  try {
+    fileStat = lstatSync(filePath);
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      throw new Error('Pairing runtime credential is missing; start the CrewX server once to create pairing.token.');
+    }
+    throw new Error('Pairing runtime credential is not readable.');
+  }
+
+  if (!fileStat.isFile()) {
+    throw new Error('Pairing runtime credential is not a regular file.');
+  }
+  if (process.platform !== 'win32' && (fileStat.mode & 0o777) !== PAIRING_CREDENTIAL_MODE) {
+    throw new Error('Pairing runtime credential permissions are invalid; expected mode 0600.');
+  }
+  const uid = currentUid();
+  if (uid !== undefined && fileStat.uid !== uid) {
+    throw new Error('Pairing runtime credential must be owned by the current user.');
+  }
+
+  let credential;
+  try {
+    credential = readFileSync(filePath, 'utf8');
+  } catch {
+    throw new Error('Pairing runtime credential is not readable.');
+  }
+  if (!PAIRING_CREDENTIAL_PATTERN.test(credential)) {
+    throw new Error('Pairing runtime credential has an invalid format.');
+  }
+  return credential;
+}
+
+/**
+ * Resolve the server endpoint for `crewx pair`.
+ * Explicit --port wins over CREWX_ENDPOINT, which wins over the local default.
+ *
+ * @param {{ port?: number, env?: NodeJS.ProcessEnv }} options
+ * @returns {string}
+ */
+export function resolvePairEndpoint({ port, env = process.env } = {}) {
+  const rawEndpoint = port === undefined
+    ? (env.CREWX_ENDPOINT?.trim() || DEFAULT_PAIRING_ENDPOINT)
+    : `http://localhost:${port}`;
+  let endpoint;
+  try {
+    endpoint = new URL(rawEndpoint);
+  } catch {
+    throw new Error('Invalid CrewX endpoint. Use an http:// or https:// URL.');
+  }
+  if (endpoint.protocol !== 'http:' && endpoint.protocol !== 'https:') {
+    throw new Error('Invalid CrewX endpoint. Use an http:// or https:// URL.');
+  }
+  if (endpoint.username || endpoint.password || endpoint.search || endpoint.hash) {
+    throw new Error('Invalid CrewX endpoint. Do not include credentials, query, or fragment data.');
+  }
+  return endpoint.toString().replace(/\/$/, '');
+}
+
 
 /**
  * Parse --port option from extra CLI args.
@@ -32,9 +124,10 @@ export function parseWebPort(extraArgs) {
  *   1. --help/-h, --version/-v → CLI (global options handled by CLI engine)
  *   2. Known CLI subcommand    → CLI
  *   3. 'serve' verb            → serve
- *   4. 'electron' verb         → electron
- *   5. No arguments            → web-default (browser auto-open)
- *   6. Unknown first argument  → error with hint
+ *   4. 'pair' verb             → pair
+ *   5. 'electron' verb         → electron
+ *   6. No arguments            → web-default (browser auto-open)
+ *   7. Unknown first argument  → error with hint
  *
  * @param {string[]} args - process.argv.slice(2)
  * @returns {{ route: string, routeArgs: string[], error?: string }}
@@ -60,12 +153,17 @@ export function resolveRoute(args) {
     return { route: 'serve', routeArgs: args.slice(1) };
   }
 
-  // 4. New verb: electron
+  // 4. Local browser pairing code requester
+  if (firstArg === 'pair') {
+    return { route: 'pair', routeArgs: args.slice(1) };
+  }
+
+  // 5. New verb: electron
   if (firstArg === 'electron') {
     return { route: 'electron', routeArgs: args.slice(1) };
   }
 
-  // 5. No arguments → web default
+  // 6. No arguments → web default
   if (firstArg === undefined) {
     return { route: 'web-default', routeArgs: [] };
   }

package/bin/crewx-ui.js

@@ -53,12 +53,6 @@ if (isElectron || isOverlay) {
     ? join(__dirname, '..', 'dist-electron', 'overlay.js')
     : join(__dirname, '..', 'dist-electron', 'main.js');
 
-  if (process.env.ELECTRON_RUN_AS_NODE) {
-    console.warn(
-      '[crewx-ui] Ignoring ELECTRON_RUN_AS_NODE for Electron UI launch (it forces Electron into Node mode).',
-    );
-  }
-
   const child = spawn(String(electronPath), [entryFile], {
     stdio: 'inherit',
     env: getElectronSpawnEnv(),

package/bin/crewx.js

@@ -10,6 +10,8 @@
  *              [--https]               → Enable HTTPS with auto-generated certificate
  *              [--trust]               → Install CA to system trust store (requires --https)
  *              [--no-open]             → Do not open browser
+ *   crewx pair [--port N]              → Request a one-time browser pairing link
+ *              [--open]                → Open the pairing link in a browser
  *   crewx electron [--overlay]         → Electron desktop or overlay window
  *   crewx --version                    → CLI version output
  *   crewx --help                       → CLI help output
@@ -22,7 +24,13 @@ import { dirname, join } from 'path';
 import { homedir, tmpdir } from 'os';
 import { createRequire } from 'module';
 import { defineCommand, runCommand, renderUsage } from 'citty';
-import { setupSignalForwarding, resolveRoute, ensureCrewxDirs } from './crewx-lib.js';
+import {
+  setupSignalForwarding,
+  resolveRoute,
+  ensureCrewxDirs,
+  readPairingCredential,
+  resolvePairEndpoint,
+} from './crewx-lib.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -47,12 +55,6 @@ function launchElectron(entryFile, routeArgs = []) {
     return false; // Electron not installed
   }
 
-  if (process.env.ELECTRON_RUN_AS_NODE) {
-    console.warn(
-      '[crewx] Ignoring ELECTRON_RUN_AS_NODE for Electron UI launch (it forces Electron into Node mode).',
-    );
-  }
-
   const child = spawn(String(electronPath), [entryFile, ...routeArgs], {
     stdio: 'inherit',
     env: getElectronSpawnEnv(),
@@ -132,7 +134,7 @@ function launchWeb({ port, token, tokenFile, open: openFlag, https, trust } = {}
     );
   }
 
-  const child = spawn(process.execPath, [serverScript], {
+  const child = spawn(process.execPath, ['--disable-sigusr1', serverScript], {
     stdio: 'inherit',
     env,
   });
@@ -146,6 +148,111 @@ function launchWeb({ port, token, tokenFile, open: openFlag, https, trust } = {}
   });
 }
 
+function parsePairPort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.error('❌ Invalid port number. Use 1-65535.');
+    process.exit(1);
+  }
+  return port;
+}
+
+function isPairingUrl(value) {
+  if (typeof value !== 'string' || value.length === 0) return false;
+  try {
+    const url = new URL(value);
+    return (url.protocol === 'http:' || url.protocol === 'https:')
+      && url.search === ''
+      && /^#pair=.{1,}$/.test(url.hash);
+  } catch {
+    return false;
+  }
+}
+
+async function requestPairingLink(endpoint, credential) {
+  let response;
+  try {
+    response = await fetch(`${endpoint}/api/v1/auth/local/code`, {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${credential}`,
+      },
+    });
+  } catch {
+    throw new Error(`Could not reach the CrewX server at ${endpoint}.`);
+  }
+  if (!response.ok) {
+    throw new Error(`Pairing code request failed (HTTP ${response.status}).`);
+  }
+
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error('Pairing code response was not valid JSON.');
+  }
+  if (!isPairingUrl(payload?.url)) {
+    throw new Error('Pairing code response did not contain a valid pairing URL.');
+  }
+  return payload.url;
+}
+
+const pairCommand = defineCommand({
+  meta: { name: 'pair', description: 'Request a one-time local browser pairing link' },
+  args: {
+    port: { type: 'string', description: 'Port of the CrewX web server' },
+    open: { type: 'boolean', description: 'Open the pairing link in a browser', default: false },
+    help: { type: 'boolean', alias: 'h', description: 'Show this help' },
+  },
+  async run({ args }) {
+    if (args.help) {
+      const usage = await renderUsage(pairCommand);
+      process.stdout.write(usage + '\n');
+      process.exit(0);
+    }
+
+    const knownArgs = new Set(['_', 'port', 'open', 'help', 'h']);
+    for (const key of Object.keys(args)) {
+      if (!knownArgs.has(key)) {
+        console.error(`❌ Unknown option for "crewx pair": --${key}`);
+        console.error('   Run `crewx pair --help` for usage.');
+        process.exit(2);
+      }
+    }
+
+    const port = args.port === undefined ? undefined : parsePairPort(args.port);
+    let endpoint;
+    let credential;
+    try {
+      endpoint = resolvePairEndpoint({ port });
+      credential = readPairingCredential();
+    } catch (error) {
+      console.error(`❌ ${error instanceof Error ? error.message : 'Unable to read pairing credential.'}`);
+      process.exit(1);
+    }
+
+    let pairingUrl;
+    try {
+      pairingUrl = await requestPairingLink(endpoint, credential);
+    } catch (error) {
+      console.error(`❌ ${error instanceof Error ? error.message : 'Unable to request pairing link.'}`);
+      process.exit(1);
+    }
+
+    process.stdout.write(`${pairingUrl}\n`);
+    if (args.open) {
+      try {
+        const open = (await import('open')).default;
+        await open(pairingUrl);
+      } catch {
+        console.error('❌ Could not open the pairing link automatically.');
+        process.exit(1);
+      }
+    }
+  },
+});
+
 const serveCommand = defineCommand({
   meta: { name: 'serve', description: 'Launch CrewX web server' },
   args: {
@@ -215,6 +322,8 @@ const { route, routeArgs, error } = resolveRoute(args);
 
 if (route === 'serve') {
   runCommand(serveCommand, { rawArgs: routeArgs });
+} else if (route === 'pair') {
+  runCommand(pairCommand, { rawArgs: routeArgs });
 } else if (route === 'electron') {
   // Electron: desktop (default) or overlay (--overlay flag)
   const isOverlay = routeArgs.includes('--overlay');

package/crewx-host.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// Entry point that server.js spawns for `crewx serve`.
+// It keeps `dist-server/main.js` out of this process's command line, so a
+// pattern stop aimed at development servers (`pkill -f "dist-server/main.js"`)
+// does not also stop an installed server such as the RC.
+require('./dist-server/main.js');