@nometria-ai/nom 0.2.9 → 0.3.1

package/src/commands/rollback.js

@@ -0,0 +1,95 @@
+/**
+ * nom rollback — Roll back to a previous deployment.
+ */
+import { requireApiKey } from '../lib/auth.js';
+import { apiRequest } from '../lib/api.js';
+import { readConfig } from '../lib/config.js';
+import { createSpinner } from '../lib/spinner.js';
+import { confirm } from '../lib/prompt.js';
+
+export async function rollback(flags, positionals) {
+  const apiKey = requireApiKey();
+  const config = readConfig();
+  const appId = config.app_id;
+
+  if (!appId) {
+    console.error('\n  No app_id in nometria.json. Deploy first: nom deploy\n');
+    process.exit(1);
+  }
+
+  // Step 1: List recent deployments
+  const spinner = createSpinner('Fetching deployment history').start();
+  let deployments;
+  try {
+    const result = await apiRequest('/v1/deployments', {
+      apiKey,
+      body: { app_id: appId },
+    });
+    deployments = result.deployments || result.data?.deployments || [];
+    spinner.succeed(`Found ${deployments.length} deployment(s)`);
+  } catch (err) {
+    spinner.fail('Failed to fetch deployment history');
+    console.error(`\n  ${err.message}`);
+    console.error(`  This app may not support rollback yet.`);
+    console.error(`  Help: https://docs.nometria.com/deploy/overview\n`);
+    process.exit(1);
+  }
+
+  if (deployments.length < 2) {
+    console.log('\n  No previous deployments to roll back to.\n');
+    return;
+  }
+
+  // Step 2: Show recent deployments
+  console.log('\n  Recent deployments:\n');
+  for (let i = 0; i < Math.min(deployments.length, 10); i++) {
+    const d = deployments[i];
+    const marker = i === 0 ? ' (current)' : '';
+    const status = d.status || 'unknown';
+    const date = d.created_at ? new Date(d.created_at).toLocaleString() : '—';
+    console.log(`  ${i + 1}. ${d.id}  ${status}  ${date}${marker}`);
+  }
+  console.log();
+
+  // Step 3: Determine target
+  let targetId = positionals?.[0];
+  if (!targetId) {
+    // Default to the second deployment (previous)
+    if (deployments.length >= 2) {
+      targetId = deployments[1].id;
+    }
+  }
+
+  if (!targetId) {
+    console.error('\n  No deployment to roll back to.\n');
+    process.exit(1);
+  }
+
+  // Step 4: Confirm
+  if (!flags.yes) {
+    const ok = await confirm(`Roll back to ${targetId}?`, false);
+    if (!ok) {
+      console.log('  Cancelled.\n');
+      return;
+    }
+  }
+
+  // Step 5: Execute rollback
+  const rollbackSpinner = createSpinner('Rolling back').start();
+  try {
+    const result = await apiRequest(`/v1/deployments/${targetId}/rollback`, {
+      apiKey,
+      body: { app_id: appId },
+    });
+    rollbackSpinner.succeed('Rollback complete');
+    console.log(`\n  Rolled back to: ${targetId}`);
+    if (result.url) console.log(`  URL: ${result.url}`);
+    console.log(`  Dashboard: https://nometria.com/AppDetails?app_id=${appId}\n`);
+  } catch (err) {
+    rollbackSpinner.fail('Rollback failed');
+    console.error(`\n  ${err.message}`);
+    console.error(`  Dashboard: https://nometria.com/AppDetails?app_id=${appId}`);
+    console.error(`  Help: https://docs.nometria.com/deploy/overview\n`);
+    process.exit(1);
+  }
+}

package/src/commands/setup.js

@@ -90,6 +90,16 @@ export async function setup(flags) {
   writeContinueConfig(continueConfigPath);
   files.push('.continue/config.json');
 
+  // 10. Claude Code automation hooks
+  const hooksDir = join(dir, '.claude', 'hooks');
+  mkdirSync(hooksDir, { recursive: true });
+  writeFileSync(join(hooksDir, 'auto-deploy-on-commit.sh'), autoDeployHook(), { mode: 0o755 });
+  files.push('.claude/hooks/auto-deploy-on-commit.sh');
+  writeFileSync(join(hooksDir, 'security-gate.sh'), securityGateHook(), { mode: 0o755 });
+  files.push('.claude/hooks/security-gate.sh');
+  writeFileSync(join(hooksDir, 'cost-guardian.sh'), costGuardianHook(), { mode: 0o755 });
+  files.push('.claude/hooks/cost-guardian.sh');
+
   // Print results
   for (const f of files) {
     console.log(`    ${f}`);
@@ -105,7 +115,15 @@ export async function setup(flags) {
     /deploy            Deploy to production
     /preview           Staging preview (free, 2hr)
     /status            Check deployment status
+    /logs              View deployment logs
+    /env               Manage environment variables
+    /domain            Add custom domains
     /nometria-login    Set up authentication
+
+  Automation hooks installed:
+    auto-deploy-on-commit.sh   Auto-resync on git commit
+    security-gate.sh           Block deploys with low security score
+    cost-guardian.sh            Warn about idle running instances
 `);
 }
 
@@ -298,9 +316,14 @@ on:
     branches: [main]
   workflow_dispatch:
 
+concurrency:
+  group: nometria-deploy
+  cancel-in-progress: true
+
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
     steps:
       - uses: actions/checkout@v4
 
@@ -311,10 +334,30 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Deploy
+      - name: Run security scan
+        run: npx @nometria-ai/nom scan || echo "Scan completed with warnings"
+        env:
+          NOMETRIA_API_KEY: \${{ secrets.NOMETRIA_API_KEY }}
+
+      - name: Deploy to production
+        id: deploy
         run: npx @nometria-ai/nom deploy --yes
         env:
           NOMETRIA_API_KEY: \${{ secrets.NOMETRIA_API_KEY }}
+
+      - name: Verify deployment
+        if: success()
+        run: |
+          echo "Deployment successful"
+          npx @nometria-ai/nom status --json || true
+        env:
+          NOMETRIA_API_KEY: \${{ secrets.NOMETRIA_API_KEY }}
+
+      - name: Notify on failure
+        if: failure()
+        run: |
+          echo "::error::Deployment failed. Check logs: npx @nometria-ai/nom logs"
+          echo "Dashboard: https://nometria.com/dashboard"
 `;
 }
 
@@ -852,3 +895,104 @@ function writeContinueConfig(configPath) {
 
   writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
 }
+
+// ─── Automation Hook Templates ─────────────────────────────────────────────
+
+function autoDeployHook() {
+  return `#!/usr/bin/env bash
+# Nometria: Auto-deploy on git commit
+# Triggers resync when a git commit is made in a Nometria project.
+set -euo pipefail
+
+TOOL_INPUT="\${CLAUDE_TOOL_INPUT:-}"
+if ! echo "$TOOL_INPUT" | grep -q "git commit"; then exit 0; fi
+if [ ! -f "nometria.json" ]; then exit 0; fi
+
+APP_ID=$(grep -o '"app_id"[[:space:]]*:[[:space:]]*"[^"]*"' nometria.json 2>/dev/null | head -1 | cut -d'"' -f4)
+[ -z "$APP_ID" ] && exit 0
+
+TOKEN="\${NOMETRIA_API_KEY:-\${NOMETRIA_TOKEN:-}}"
+[ -z "$TOKEN" ] && [ -f .env ] && TOKEN=$(grep -s 'NOMETRIA_API_KEY\\|NOMETRIA_TOKEN' .env 2>/dev/null | head -1 | cut -d= -f2- | tr -d ' "'"'"'')
+[ -z "$TOKEN" ] && [ -f "$HOME/.nometria/credentials.json" ] && TOKEN=$(grep -o '"api_key"[[:space:]]*:[[:space:]]*"[^"]*"' "$HOME/.nometria/credentials.json" 2>/dev/null | head -1 | cut -d'"' -f4)
+[ -z "$TOKEN" ] && exit 0
+
+curl -sf -X POST https://app.nometria.com/resyncHosting \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -d "{\\"app_id\\": \\"$APP_ID\\"}" > /dev/null 2>&1 &
+
+echo "Nometria: resyncing $APP_ID in background..."
+`;
+}
+
+function securityGateHook() {
+  return `#!/usr/bin/env bash
+# Nometria: Security gate before deploy
+# Blocks production deploys if security score < 70.
+set -euo pipefail
+
+TOOL_NAME="\${CLAUDE_TOOL_NAME:-}"
+TOOL_INPUT="\${CLAUDE_TOOL_INPUT:-}"
+
+IS_DEPLOY=false
+[ "$TOOL_NAME" = "Skill" ] && echo "$TOOL_INPUT" | grep -q '"deploy"' && IS_DEPLOY=true
+[ "$TOOL_NAME" = "Bash" ] && echo "$TOOL_INPUT" | grep -qE "deployToAws|resyncHosting|nom deploy" && IS_DEPLOY=true
+[ "$IS_DEPLOY" != "true" ] && exit 0
+[ ! -f "nometria.json" ] && exit 0
+
+APP_ID=$(grep -o '"app_id"[[:space:]]*:[[:space:]]*"[^"]*"' nometria.json 2>/dev/null | head -1 | cut -d'"' -f4)
+MIGRATION_ID=$(grep -o '"migration_id"[[:space:]]*:[[:space:]]*"[^"]*"' nometria.json 2>/dev/null | head -1 | cut -d'"' -f4)
+[ -z "$APP_ID" ] || [ -z "$MIGRATION_ID" ] && exit 0
+
+TOKEN="\${NOMETRIA_API_KEY:-\${NOMETRIA_TOKEN:-}}"
+[ -z "$TOKEN" ] && [ -f .env ] && TOKEN=$(grep -s 'NOMETRIA_API_KEY\\|NOMETRIA_TOKEN' .env 2>/dev/null | head -1 | cut -d= -f2- | tr -d ' "'"'"'')
+[ -z "$TOKEN" ] && [ -f "$HOME/.nometria/credentials.json" ] && TOKEN=$(grep -o '"api_key"[[:space:]]*:[[:space:]]*"[^"]*"' "$HOME/.nometria/credentials.json" 2>/dev/null | head -1 | cut -d'"' -f4)
+[ -z "$TOKEN" ] && exit 0
+
+echo "Nometria: running security scan before deploy..."
+SCAN_RESULT=$(curl -sf -X POST https://app.nometria.com/runAiScan \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -d "{\\"app_id\\": \\"$APP_ID\\", \\"migration_id\\": \\"$MIGRATION_ID\\"}" 2>/dev/null || echo '{}')
+
+SCORE=$(echo "$SCAN_RESULT" | grep -o '"securityScore"[[:space:]]*:[[:space:]]*[0-9]*' | grep -o '[0-9]*$')
+
+if [ -n "$SCORE" ] && [ "$SCORE" -lt 70 ]; then
+  echo "BLOCKED: Security score $SCORE/100 (minimum: 70). Run 'nom scan' for details."
+  exit 2
+fi
+[ -n "$SCORE" ] && echo "Nometria: security score $SCORE/100 — passed."
+`;
+}
+
+function costGuardianHook() {
+  return `#!/usr/bin/env bash
+# Nometria: Cost guardian — detect idle instances on session start
+set -euo pipefail
+
+TOKEN="\${NOMETRIA_API_KEY:-\${NOMETRIA_TOKEN:-}}"
+[ -z "$TOKEN" ] && [ -f .env ] && TOKEN=$(grep -s 'NOMETRIA_API_KEY\\|NOMETRIA_TOKEN' .env 2>/dev/null | head -1 | cut -d= -f2- | tr -d ' "'"'"'')
+[ -z "$TOKEN" ] && [ -f "$HOME/.nometria/credentials.json" ] && TOKEN=$(grep -o '"api_key"[[:space:]]*:[[:space:]]*"[^"]*"' "$HOME/.nometria/credentials.json" 2>/dev/null | head -1 | cut -d'"' -f4)
+[ -z "$TOKEN" ] && exit 0
+
+MIGRATIONS=$(curl -sf -X POST https://app.nometria.com/listUserMigrations \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer $TOKEN" \\
+  -d '{}' 2>/dev/null || echo '{}')
+
+APP_IDS=$(echo "$MIGRATIONS" | grep -o '"app_id"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+[ -z "$APP_IDS" ] && exit 0
+
+RUNNING=0
+for APP_ID in $APP_IDS; do
+  STATUS=$(curl -sf -X POST https://app.nometria.com/checkAwsStatus \\
+    -H "Content-Type: application/json" \\
+    -H "Authorization: Bearer $TOKEN" \\
+    -d "{\\"app_id\\": \\"$APP_ID\\"}" 2>/dev/null || echo '{}')
+  STATE=$(echo "$STATUS" | grep -o '"instanceState"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
+  [ "$STATE" = "running" ] && RUNNING=$((RUNNING + 1)) && echo "  Running: $APP_ID"
+done
+
+[ "$RUNNING" -gt 0 ] && echo "Nometria: $RUNNING running instance(s). Stop idle ones with: nom stop <app_id>"
+`;
+}

package/src/commands/ssh.js

@@ -0,0 +1,88 @@
+/**
+ * nom ssh — Get SSH/exec access to a deployed instance.
+ * Uses AWS SSM or provides SSH instructions.
+ */
+import { requireApiKey } from '../lib/auth.js';
+import { apiRequest } from '../lib/api.js';
+import { readConfig } from '../lib/config.js';
+
+export async function ssh(flags, positionals) {
+  const apiKey = requireApiKey();
+  const config = readConfig();
+  const appId = config.app_id;
+
+  if (!appId) {
+    console.error('\n  No app_id in nometria.json. Deploy first: nom deploy');
+    console.error('  Docs: https://docs.nometria.com/cli/commands\n');
+    process.exit(1);
+  }
+
+  // Get instance details
+  const result = await apiRequest('/checkAwsStatus', {
+    apiKey,
+    body: { app_id: appId },
+  });
+
+  const data = result.data || result;
+  const state = data.instanceState;
+  const ip = data.ipAddress;
+  const instanceId = data.instanceId;
+
+  if (state !== 'running') {
+    console.error(`\n  Instance is not running (state: ${state || 'unknown'}).`);
+    console.error('  Start it first: nom start\n');
+    process.exit(1);
+  }
+
+  if (!ip && !instanceId) {
+    console.error('\n  Could not determine instance IP or ID.');
+    console.error(`  Dashboard: https://nometria.com/AppDetails?app_id=${appId}\n`);
+    process.exit(1);
+  }
+
+  // Check if user wants to run a command
+  const command = positionals.join(' ');
+
+  if (command) {
+    // nom ssh <command> — execute remote command
+    console.log(`\n  Running on ${appId} (${ip || instanceId}):\n`);
+    try {
+      const execResult = await apiRequest('/cli/exec', {
+        apiKey,
+        body: { app_id: appId, command },
+      });
+      console.log(execResult.output || execResult.stdout || '(no output)');
+      if (execResult.stderr) console.error(execResult.stderr);
+      console.log();
+    } catch (err) {
+      // Fallback: show SSH instructions
+      console.error(`  Remote exec not available: ${err.message}\n`);
+      showSshInstructions(ip, instanceId);
+    }
+  } else {
+    // nom ssh — show connection instructions
+    showSshInstructions(ip, instanceId);
+  }
+}
+
+function showSshInstructions(ip, instanceId) {
+  console.log('\n  Connect to your instance:\n');
+
+  if (ip) {
+    console.log(`  SSH:  ssh ubuntu@${ip}`);
+    console.log(`        (requires your SSH key to be configured)\n`);
+  }
+
+  if (instanceId) {
+    console.log(`  SSM:  aws ssm start-session --target ${instanceId}`);
+    console.log(`        (requires AWS CLI + Session Manager plugin)\n`);
+  }
+
+  console.log('  Common debug commands:');
+  console.log('    pm2 status                   Check running processes');
+  console.log('    pm2 logs                     View app logs');
+  console.log('    sudo nginx -t                Test nginx config');
+  console.log('    cat /home/ubuntu/deploy.log  View deploy log');
+  console.log('    df -h                        Check disk space');
+  console.log();
+}

package/src/lib/cache.js

@@ -0,0 +1,56 @@
+/**
+ * Simple file-based cache for CLI responses.
+ * Stores cached data in ~/.nometria/cache/ with TTL-based expiration.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const CACHE_DIR = join(homedir(), '.nometria', 'cache');
+const DEFAULT_TTL = 60_000; // 1 minute
+
+function ensureCacheDir() {
+  if (!existsSync(CACHE_DIR)) {
+    mkdirSync(CACHE_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Get a cached value. Returns null if expired or not found.
+ */
+export function getCached(key, ttl = DEFAULT_TTL) {
+  try {
+    const path = join(CACHE_DIR, `${key}.json`);
+    if (!existsSync(path)) return null;
+
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (Date.now() - raw.timestamp > ttl) return null;
+    return raw.data;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a value in cache.
+ */
+export function setCache(key, data) {
+  try {
+    ensureCacheDir();
+    const path = join(CACHE_DIR, `${key}.json`);
+    writeFileSync(path, JSON.stringify({ timestamp: Date.now(), data }));
+  } catch {
+    // Non-fatal — cache write failure shouldn't break CLI
+  }
+}
+
+/**
+ * Cache-aware API request wrapper.
+ * Uses cache for reads, bypasses for writes.
+ */
+export function withCache(key, ttl = DEFAULT_TTL) {
+  return {
+    get() { return getCached(key, ttl); },
+    set(data) { setCache(key, data); },
+  };
+}

package/src/lib/detect.js

@@ -74,6 +74,48 @@ export function detectFramework(dir = process.cwd()) {
     if (deps['vite']) return { framework: 'vite', build: { command: hasBuildScript ? 'npm run build' : null, output: 'dist' } };
   }
 
+  // Check for Hono
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['hono']) return { framework: 'hono', build: { command: null, output: '.' } };
+  }
+
+  // Check for Solid
+  if (existsSync(join(dir, 'solid.config.js')) || existsSync(join(dir, 'solid.config.ts'))) {
+    return { framework: 'solid', build: { command: 'npm run build', output: 'dist' } };
+  }
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['solid-js'] && deps['solid-start']) return { framework: 'solid', build: { command: 'npm run build', output: 'dist' } };
+  }
+
+  // Check for Astro
+  if (existsSync(join(dir, 'astro.config.mjs')) || existsSync(join(dir, 'astro.config.ts'))) {
+    return { framework: 'astro', build: { command: 'npm run build', output: 'dist' } };
+  }
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['astro']) return { framework: 'astro', build: { command: 'npm run build', output: 'dist' } };
+  }
+
+  // Check for SvelteKit
+  if (existsSync(join(dir, 'svelte.config.js')) || existsSync(join(dir, 'svelte.config.ts'))) {
+    return { framework: 'sveltekit', build: { command: 'npm run build', output: 'build' } };
+  }
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['@sveltejs/kit']) return { framework: 'sveltekit', build: { command: 'npm run build', output: 'build' } };
+  }
+
+  // Check for Nuxt
+  if (existsSync(join(dir, 'nuxt.config.ts')) || existsSync(join(dir, 'nuxt.config.js'))) {
+    return { framework: 'nuxt', build: { command: 'npm run build', output: '.output' } };
+  }
+  if (pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if (deps['nuxt']) return { framework: 'nuxt', build: { command: 'npm run build', output: '.output' } };
+  }
+
   // Check if it looks like a Node.js project
   if (pkg && (pkg.main || pkg.scripts?.start)) {
     return { framework: 'node', build: { command: null, output: '.' } };
@@ -85,7 +127,8 @@ export function detectFramework(dir = process.cwd()) {
     return { framework: 'python', build: { command: null, output: '.' } };
   }
 
-  return { framework: 'static', build: { command: null, output: '.' } };
+  // Flag as uncertain — let callers decide whether to prompt or default
+  return { framework: 'static', build: { command: null, output: '.' }, uncertain: true };
 }
 
 export function detectPackageManager(dir = process.cwd()) {
@@ -212,6 +255,69 @@ export function detectServices(dir = process.cwd()) {
   return result;
 }
 
+/**
+ * Detect if the project is a monorepo.
+ * Returns { isMonorepo: boolean, tool: string|null, packages: string[] }
+ */
+export function detectMonorepo(dir = process.cwd()) {
+  const result = { isMonorepo: false, tool: null, packages: [] };
+
+  // Check for monorepo config files
+  if (existsSync(join(dir, 'turbo.json'))) {
+    result.isMonorepo = true;
+    result.tool = 'turborepo';
+  } else if (existsSync(join(dir, 'nx.json'))) {
+    result.isMonorepo = true;
+    result.tool = 'nx';
+  } else if (existsSync(join(dir, 'pnpm-workspace.yaml'))) {
+    result.isMonorepo = true;
+    result.tool = 'pnpm-workspaces';
+  } else if (existsSync(join(dir, 'lerna.json'))) {
+    result.isMonorepo = true;
+    result.tool = 'lerna';
+  }
+
+  // Check package.json workspaces
+  if (!result.isMonorepo) {
+    const pkgPath = join(dir, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.workspaces) {
+          result.isMonorepo = true;
+          result.tool = 'npm-workspaces';
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  if (!result.isMonorepo) return result;
+
+  // Find deployable packages (those with package.json and a build or start script)
+  const packagesDir = existsSync(join(dir, 'packages')) ? join(dir, 'packages') :
+                      existsSync(join(dir, 'apps')) ? join(dir, 'apps') : null;
+
+  if (packagesDir) {
+    try {
+      const entries = readdirSync(packagesDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+        const pkgJson = join(packagesDir, entry.name, 'package.json');
+        if (existsSync(pkgJson)) {
+          try {
+            const pkg = JSON.parse(readFileSync(pkgJson, 'utf8'));
+            if (pkg.scripts?.build || pkg.scripts?.start || pkg.scripts?.dev) {
+              result.packages.push(entry.name);
+            }
+          } catch { /* skip */ }
+        }
+      }
+    } catch { /* skip */ }
+  }
+
+  return result;
+}
+
 export function getProjectName(dir = process.cwd()) {
   const pkgPath = join(dir, 'package.json');
   if (existsSync(pkgPath)) {

package/src/lib/telemetry.js

@@ -0,0 +1,123 @@
+/**
+ * Anonymous CLI telemetry — tracks deployment funnel to identify drop-off points.
+ *
+ * Opt-out: set NOM_TELEMETRY=0 or run `nom config telemetry false`
+ *
+ * What we track:
+ *   - Command name (deploy, init, preview, etc.)
+ *   - Framework detected
+ *   - Success/failure
+ *   - Duration
+ *
+ * What we DON'T track:
+ *   - App names, URLs, or content
+ *   - API keys or tokens
+ *   - File paths or code
+ *   - IP addresses (server-side)
+ */
+import { homedir } from 'node:os';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TELEMETRY_ENDPOINT = 'https://app.nometria.com/cli/telemetry';
+const CONFIG_PATH = join(homedir(), '.nometria', 'config.json');
+
+function isEnabled() {
+  // Env var override
+  if (process.env.NOM_TELEMETRY === '0' || process.env.NOM_TELEMETRY === 'false') return false;
+  if (process.env.DO_NOT_TRACK === '1') return false;  // Respect consented.org standard
+
+  // Config file override
+  try {
+    if (existsSync(CONFIG_PATH)) {
+      const config = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+      if (config.telemetry === false) return false;
+    }
+  } catch { /* ignore */ }
+
+  return true;
+}
+
+/**
+ * Record a CLI event. Non-blocking — fire and forget.
+ */
+export function trackEvent(event, properties = {}) {
+  if (!isEnabled()) return;
+
+  const payload = {
+    event,
+    properties: {
+      ...properties,
+      cli_version: getCliVersion(),
+      node_version: process.version,
+      platform: process.platform,
+      arch: process.arch,
+    },
+    timestamp: new Date().toISOString(),
+  };
+
+  // Fire and forget — never block the CLI
+  try {
+    fetch(TELEMETRY_ENDPOINT, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(3000),
+    }).catch(() => { /* silently ignore */ });
+  } catch { /* silently ignore */ }
+}
+
+/**
+ * Track command start. Returns a finish function to record duration.
+ */
+export function trackCommand(command, metadata = {}) {
+  const start = Date.now();
+  trackEvent('command_start', { command, ...metadata });
+
+  return {
+    success(extra = {}) {
+      trackEvent('command_success', {
+        command,
+        duration_ms: Date.now() - start,
+        ...metadata,
+        ...extra,
+      });
+    },
+    fail(error, extra = {}) {
+      trackEvent('command_fail', {
+        command,
+        duration_ms: Date.now() - start,
+        error: typeof error === 'string' ? error : error?.message || 'unknown',
+        ...metadata,
+        ...extra,
+      });
+    },
+  };
+}
+
+/**
+ * Set telemetry preference.
+ */
+export function setTelemetry(enabled) {
+  const dir = join(homedir(), '.nometria');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  let config = {};
+  try {
+    if (existsSync(CONFIG_PATH)) config = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch { /* start fresh */ }
+
+  config.telemetry = enabled;
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+function getCliVersion() {
+  try {
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(readFileSync(join(dir, '..', '..', 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}