idlewatch 0.1.3 → 0.1.5

package/README.md

@@ -17,7 +17,7 @@ npx idlewatch quickstart
 npx idlewatch --dry-run
 ```
 
-`quickstart` runs a first-run setup wizard that writes a local env file and (for production mode) stores a locked-down copy of the service-account key under `~/.idlewatch/`. On hosts with Rust/Cargo available, quickstart launches a ratatui-powered onboarding flow first; otherwise it falls back to the text wizard.
+`quickstart` is the happy path: create an API key on idlewatch.com/api, run the wizard, pick a device name + metrics, and IdleWatch saves local config before sending a first sample. It prefers a bundled TUI binary when available, otherwise falls back to a local Cargo build only on developer machines that already have Cargo installed. Use `idlewatch quickstart --no-tui` to skip the TUI and stay on the plain text setup path.
 
 ## CLI options
 
@@ -49,26 +49,30 @@ Use `gpuSource` + `gpuConfidence` in dashboards to decide whether to trust value
 - `low`: constrained probe path
 - `none`: no usable sample for that sample window
 
-## Firebase wiring
+## Quickstart
 
-### Recommended: guided enrollment (external users)
+### Recommended: guided enrollment
 
 ```bash
 npx idlewatch quickstart
 ```
 
-The wizard supports:
-- **Production mode**: prompts for project id + service-account JSON file path, validates it, copies credentials to a local secure path (0600), and writes `FIREBASE_SERVICE_ACCOUNT_FILE=...`.
-- **Emulator mode**: writes `FIREBASE_PROJECT_ID` + `FIRESTORE_EMULATOR_HOST` only.
-- **Local-only mode**: writes no Firebase credentials.
+The wizard keeps setup small:
+- asks for a **device name**
+- asks for your **API key** from `idlewatch.com/api`
+- lets you choose which **metrics** to collect
+- saves local config to `~/.idlewatch/idlewatch.env`
+- sends a first sample so the device can link right away
 
-Then run a one-shot publish check:
+The saved config is auto-loaded on later runs, so you should not need to manually source the env file in normal use.
+
+Then run a one-shot publish check any time with:
 
 ```bash
 idlewatch --once
 ```
 
-The saved config is auto-loaded from `~/.idlewatch/idlewatch.env`, so you should not need to manually source the env file in normal use.
+## Advanced Firebase wiring
 
 ### Manual wiring
 

package/bin/idlewatch-agent.js

@@ -18,7 +18,7 @@ import { enrichWithOpenClawFleetTelemetry } from '../src/telemetry-mapping.js'
 import pkg from '../package.json' with { type: 'json' }
 
 function printHelp() {
-  console.log(`idlewatch\n\nUsage:\n  idlewatch [quickstart|configure|dashboard|run] [--dry-run] [--once] [--help]\n\nOptions:\n  quickstart  Run first-run setup TUI and save local IdleWatch config\n  configure   Alias for quickstart; reopen setup to change device name, API key, or metrics\n  dashboard   Launch local dashboard from local IdleWatch logs\n  run         Start the background collector using saved local config\n  --dry-run   Collect and print one telemetry sample, then exit without cloud/Firebase writes\n  --once      Collect and publish one telemetry sample, then exit\n  --help      Show this help message\n\nEnvironment:\n  IDLEWATCH_HOST                     Optional custom host label (default: hostname)\n  IDLEWATCH_INTERVAL_MS              Sampling interval in ms (default: 10000)\n  IDLEWATCH_LOCAL_LOG_PATH           Optional NDJSON file path for local sample durability\n  IDLEWATCH_DASHBOARD_PORT           Local dashboard HTTP port (default: 4373)\n  IDLEWATCH_OPENCLAW_USAGE           OpenClaw usage lookup mode: auto|off (default: auto)\n  IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS OpenClaw command timeout per probe in ms (default: 2500)\n  IDLEWATCH_OPENCLAW_PROBE_RETRIES   Extra OpenClaw probe sweep retries after first pass (default: 1)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES   Max per-command OpenClaw probe output capture in bytes before truncation (default: 2097152 / 2MB)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES_HARD_CAP  Hard cap for auto-retry output capture escalation (default: 16777216 / 16MB)\n  IDLEWATCH_USAGE_STALE_MS           Mark OpenClaw usage stale beyond this age in ms (default: max(interval*3,60000))\n  IDLEWATCH_USAGE_NEAR_STALE_MS      Mark OpenClaw usage as aging beyond this age in ms (default: floor((stale+grace)*0.85))\n  IDLEWATCH_USAGE_STALE_GRACE_MS     Extra grace window before status becomes stale (default: min(interval,10000))\n  IDLEWATCH_USAGE_REFRESH_REPROBES   Forced uncached reprobes when usage crosses stale threshold (default: 1)\n  IDLEWATCH_USAGE_REFRESH_DELAY_MS   Delay between forced stale-threshold reprobes in ms (default: 250)\n  IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE Trigger refresh when usage is near-stale: 1|0 (default: 1)\n  IDLEWATCH_USAGE_IDLE_AFTER_MS      Downgrade stale usage alerts to idle notice beyond this age in ms (default: 21600000)\n  IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS  Reuse last successful usage snapshot after probe failures up to this age in ms\n  IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH Persist/reuse last successful usage snapshot across restarts (default: ~/.idlewatch/cache/<host>-openclaw-last-good.json)\n  IDLEWATCH_REQUIRE_FIREBASE_WRITES  Require Firebase publish path in --once mode: 1|0 (default: 0)\n  FIREBASE_PROJECT_ID                Firebase project id\n  FIREBASE_SERVICE_ACCOUNT_FILE      Path to service account JSON file (preferred for production)\n  FIREBASE_SERVICE_ACCOUNT_JSON      Raw JSON service account (supported, less secure than file path)\n  FIREBASE_SERVICE_ACCOUNT_B64       Base64-encoded JSON service account (legacy)\n  FIRESTORE_EMULATOR_HOST            Optional Firestore emulator host; allows local writes without service-account creds\n  IDLEWATCH_CLOUD_INGEST_URL         Optional cloud ingest endpoint (e.g. https://idlewatch.com/api/ingest)\n  IDLEWATCH_CLOUD_API_KEY            Cloud API key from dashboard for device linking\n  IDLEWATCH_REQUIRE_CLOUD_WRITES     Require cloud publish path in --once mode: 1|0 (default: 0)\n`)
+  console.log(`idlewatch\n\nUsage:\n  idlewatch [quickstart|configure|dashboard|run] [--dry-run] [--once] [--help]\n\nOptions:\n  quickstart  Run first-run setup and save local IdleWatch config\n  configure   Alias for quickstart; reopen setup to change device name, API key, or metrics\n  dashboard   Launch local dashboard from local IdleWatch logs\n  run         Start the background collector using saved local config\n  --no-tui    Skip the Rust TUI and use plain text setup without installing Cargo\n  --dry-run   Collect and print one telemetry sample, then exit without remote writes\n  --once      Collect and publish one telemetry sample, then exit\n  --help      Show this help message\n\nQuickstart:\n  1. Create an API key on idlewatch.com/api\n  2. Run: idlewatch quickstart\n  3. Pick a device name and metrics\n  4. IdleWatch saves your local config and sends a first sample\n\nEnvironment:\n  IDLEWATCH_HOST                     Optional custom host label (default: hostname)\n  IDLEWATCH_INTERVAL_MS              Sampling interval in ms (default: 10000)\n  IDLEWATCH_LOCAL_LOG_PATH           Optional NDJSON file path for local sample durability\n  IDLEWATCH_DASHBOARD_PORT           Local dashboard HTTP port (default: 4373)\n  IDLEWATCH_OPENCLAW_USAGE           OpenClaw usage lookup mode: auto|off (default: auto)\n  IDLEWATCH_OPENCLAW_PROBE_TIMEOUT_MS OpenClaw command timeout per probe in ms (default: 2500)\n  IDLEWATCH_OPENCLAW_PROBE_RETRIES   Extra OpenClaw probe sweep retries after first pass (default: 1)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES   Max per-command OpenClaw probe output capture in bytes before truncation (default: 2097152 / 2MB)\n  IDLEWATCH_OPENCLAW_MAX_OUTPUT_BYTES_HARD_CAP  Hard cap for auto-retry output capture escalation (default: 16777216 / 16MB)\n  IDLEWATCH_USAGE_STALE_MS           Mark OpenClaw usage stale beyond this age in ms (default: max(interval*3,60000))\n  IDLEWATCH_USAGE_NEAR_STALE_MS      Mark OpenClaw usage as aging beyond this age in ms (default: floor((stale+grace)*0.85))\n  IDLEWATCH_USAGE_STALE_GRACE_MS     Extra grace window before status becomes stale (default: min(interval,10000))\n  IDLEWATCH_USAGE_REFRESH_REPROBES   Forced uncached reprobes when usage crosses stale threshold (default: 1)\n  IDLEWATCH_USAGE_REFRESH_DELAY_MS   Delay between forced stale-threshold reprobes in ms (default: 250)\n  IDLEWATCH_USAGE_REFRESH_ON_NEAR_STALE Trigger refresh when usage is near-stale: 1|0 (default: 1)\n  IDLEWATCH_USAGE_IDLE_AFTER_MS      Downgrade stale usage alerts to idle notice beyond this age in ms (default: 21600000)\n  IDLEWATCH_OPENCLAW_LAST_GOOD_MAX_AGE_MS  Reuse last successful usage snapshot after probe failures up to this age in ms\n  IDLEWATCH_OPENCLAW_LAST_GOOD_CACHE_PATH Persist/reuse last successful usage snapshot across restarts (default: ~/.idlewatch/cache/<host>-openclaw-last-good.json)\n  IDLEWATCH_CLOUD_INGEST_URL         Optional cloud ingest endpoint (e.g. https://idlewatch.com/api/ingest)\n  IDLEWATCH_CLOUD_API_KEY            Cloud API key from idlewatch.com/api for device linking\n  IDLEWATCH_REQUIRE_CLOUD_WRITES     Require cloud publish path in --once mode: 1|0 (default: 0)\n\nAdvanced Firebase / emulator mode:\n  IDLEWATCH_REQUIRE_FIREBASE_WRITES  Require Firebase publish path in --once mode: 1|0 (default: 0)\n  FIREBASE_PROJECT_ID                Firebase project id\n  FIREBASE_SERVICE_ACCOUNT_FILE      Path to service account JSON file (preferred for production)\n  FIREBASE_SERVICE_ACCOUNT_JSON      Raw JSON service account (supported, less secure than file path)\n  FIREBASE_SERVICE_ACCOUNT_B64       Base64-encoded JSON service account (legacy)\n  FIRESTORE_EMULATOR_HOST            Optional Firestore emulator host; allows local writes without service-account creds\n`)
 }
 
 const require = createRequire(import.meta.url)
@@ -372,7 +372,7 @@ if (dashboardRequested) {
 
 if (quickstartRequested) {
   try {
-    const result = await runEnrollmentWizard()
+    const result = await runEnrollmentWizard({ noTui: args.has('--no-tui') })
 
     const enrolledEnv = parseEnvFileToObject(result.outputEnvFile)
     const onceRun = spawnSync(process.execPath, [process.argv[1], '--once'], {
@@ -626,7 +626,7 @@ if (firebaseConfigError) {
 
 if (!appReady && !(CLOUD_INGEST_URL && CLOUD_API_KEY)) {
   console.error(
-    'Firebase is not configured. Running without Firebase writes. Set FIREBASE_PROJECT_ID + FIREBASE_SERVICE_ACCOUNT_FILE (preferred, or FIREBASE_SERVICE_ACCOUNT_JSON / FIREBASE_SERVICE_ACCOUNT_B64), use FIREBASE_PROJECT_ID + FIRESTORE_EMULATOR_HOST for emulator writes, or configure cloud ingest via idlewatch setup.'
+    'Firebase is not configured. Running without Firebase writes. Set FIREBASE_PROJECT_ID + FIREBASE_SERVICE_ACCOUNT_FILE (preferred, or FIREBASE_SERVICE_ACCOUNT_JSON / FIREBASE_SERVICE_ACCOUNT_B64), use FIREBASE_PROJECT_ID + FIRESTORE_EMULATOR_HOST for emulator writes, or run idlewatch quickstart to link cloud ingest.'
   )
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idlewatch",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Host telemetry collector for IdleWatch",
   "type": "module",
   "files": [
@@ -9,6 +9,7 @@
     "scripts",
     "skill",
     "tui/src",
+    "tui/bin",
     "tui/Cargo.toml",
     "tui/Cargo.lock",
     "README.md",

package/src/enrollment.js

@@ -94,12 +94,53 @@ function sanitizeDeviceId(raw, fallback = os.hostname()) {
   return sanitized || normalizeDeviceName(fallback).replace(/[^a-zA-Z0-9_.-]/g, '_')
 }
 
+function cargoAvailable() {
+  const cargoProbe = spawnSync('cargo', ['--version'], { stdio: 'ignore' })
+  return cargoProbe.status === 0
+}
+
+function bundledTuiBinaryPath() {
+  const platform = process.platform
+  const arch = process.arch
+  const ext = platform === 'win32' ? '.exe' : ''
+  return path.join(PACKAGE_ROOT, 'tui', 'bin', `${platform}-${arch}`, `idlewatch-setup${ext}`)
+}
+
+function tryBundledRustTui({ configDir, outputEnvFile }) {
+  const binPath = bundledTuiBinaryPath()
+  if (!fs.existsSync(binPath)) return { ok: false, reason: 'bundled-binary-missing', binPath }
+
+  try {
+    fs.chmodSync(binPath, 0o755)
+  } catch {
+    // best effort
+  }
+
+  const run = spawnSync(binPath, [], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      IDLEWATCH_ENROLL_CONFIG_DIR: configDir,
+      IDLEWATCH_ENROLL_OUTPUT_ENV_FILE: outputEnvFile
+    }
+  })
+
+  if (run.status === 0) return { ok: true, binPath }
+  return { ok: false, reason: `bundled-binary-failed:${run.status ?? 'unknown'}`, binPath }
+}
+
 function tryRustTui({ configDir, outputEnvFile }) {
   const disabled = process.env.IDLEWATCH_DISABLE_RUST_TUI === '1'
   if (disabled) return { ok: false, reason: 'disabled' }
 
-  const cargoProbe = spawnSync('cargo', ['--version'], { stdio: 'ignore' })
-  if (cargoProbe.status !== 0) return { ok: false, reason: 'cargo-missing' }
+  const bundled = tryBundledRustTui({ configDir, outputEnvFile })
+  if (bundled.ok) return bundled
+
+  if (!cargoAvailable()) {
+    return bundled.reason === 'bundled-binary-missing'
+      ? { ok: false, reason: 'bundled-binary-missing-and-cargo-missing', binPath: bundled.binPath }
+      : { ok: false, reason: 'cargo-missing' }
+  }
 
   const manifestPath = path.join(PACKAGE_ROOT, 'tui', 'Cargo.toml')
   if (!fs.existsSync(manifestPath)) return { ok: false, reason: 'manifest-missing', manifestPath }
@@ -126,6 +167,7 @@ function promptModeText() {
 
 export async function runEnrollmentWizard(options = {}) {
   const nonInteractive = options.nonInteractive || process.env.IDLEWATCH_ENROLL_NON_INTERACTIVE === '1'
+  const noTui = options.noTui || process.env.IDLEWATCH_NO_TUI === '1'
   const configDir = path.resolve(options.configDir || process.env.IDLEWATCH_ENROLL_CONFIG_DIR || defaultConfigDir())
   const outputEnvFile = path.resolve(options.outputEnvFile || process.env.IDLEWATCH_ENROLL_OUTPUT_ENV_FILE || path.join(configDir, 'idlewatch.env'))
 
@@ -140,7 +182,7 @@ export async function runEnrollmentWizard(options = {}) {
     availableMonitorTargets
   )
 
-  if (!nonInteractive) {
+  if (!nonInteractive && !noTui) {
     const tuiResult = tryRustTui({ configDir, outputEnvFile })
     if (tuiResult.ok) {
       return {
@@ -150,7 +192,9 @@ export async function runEnrollmentWizard(options = {}) {
       }
     }
 
-    if (!['disabled', 'cargo-missing'].includes(tuiResult.reason || '')) {
+    if (tuiResult.reason === 'bundled-binary-missing-and-cargo-missing') {
+      console.warn('IdleWatch TUI is not bundled for this platform and Cargo is not installed. Falling back to text setup. Use --no-tui to skip this check.')
+    } else if (!['disabled', 'cargo-missing', 'bundled-binary-missing'].includes(tuiResult.reason || '')) {
       console.warn(`IdleWatch TUI unavailable (${tuiResult.reason || 'unknown'}). Falling back to text setup.`)
     }
   }