carom-link 1.0.0

package/src/cli/commands/add.js

@@ -0,0 +1,106 @@
+import { loadConfig } from '../../config.js';
+import { getDb, createLink, findBySlug } from '../../db.js';
+import { customAlphabet } from 'nanoid';
+import { SLUG_ALPHABET, SLUG_LENGTH } from '../../constants.js';
+import { printSuccess, printError, printInfo } from '../formatters.js';
+
+const generateSlug = customAlphabet(SLUG_ALPHABET, SLUG_LENGTH);
+
+/**
+ * Register the `add` command.
+ */
+export function registerAddCommand(program) {
+  program
+    .command('add <url> [slug]')
+    .description('Create a new short link')
+    .option('--expires <duration>', 'Expiration time (e.g., 7d, 24h, 30m)')
+    .action(async (url, customSlug, options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const config = loadConfig(dataDir);
+        const db = getDb(dataDir);
+
+        // Validate URL
+        try {
+          new URL(url);
+        } catch {
+          printError('Invalid URL format. Provide a full URL like https://example.com');
+          process.exit(1);
+        }
+
+        // Generate or validate slug
+        let slug = customSlug;
+        if (slug) {
+          if (!/^[a-zA-Z0-9_-]+$/.test(slug)) {
+            printError('Slug can only contain letters, numbers, hyphens, and underscores.');
+            process.exit(1);
+          }
+          const reserved = ['api', 'dashboard', 'health'];
+          if (reserved.includes(slug.toLowerCase())) {
+            printError(`Slug "${slug}" is reserved.`);
+            process.exit(1);
+          }
+          if (findBySlug(db, slug)) {
+            printError(`Slug "${slug}" already exists.`);
+            process.exit(1);
+          }
+        } else {
+          let attempts = 0;
+          do {
+            slug = generateSlug();
+            attempts++;
+          } while (attempts < 10 && findBySlug(db, slug));
+        }
+
+        // Parse expiration
+        let expiresAt = null;
+        if (options.expires) {
+          expiresAt = parseExpiration(options.expires);
+          if (!expiresAt) {
+            printError('Invalid expiration format. Use: 7d, 24h, 30m');
+            process.exit(1);
+          }
+        }
+
+        const link = createLink(db, {
+          slug,
+          destinationUrl: url,
+          expiresAt,
+        });
+
+        const baseUrl = config.baseUrl || `http://localhost:${config.port || 3000}`;
+        const shortUrl = `${baseUrl}/${link.slug}`;
+
+        printSuccess(`Link created!`);
+        printInfo(`Short URL: ${shortUrl}`);
+        printInfo(`Slug:      ${link.slug}`);
+        printInfo(`Target:    ${url}`);
+        if (expiresAt) {
+          printInfo(`Expires:   ${expiresAt}`);
+        }
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}
+
+function parseExpiration(duration) {
+  const match = duration.match(/^(\d+)(m|h|d)$/i);
+  if (!match) return null;
+
+  const amount = parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  const now = new Date();
+
+  switch (unit) {
+    case 'm': now.setMinutes(now.getMinutes() + amount); break;
+    case 'h': now.setHours(now.getHours() + amount); break;
+    case 'd': now.setDate(now.getDate() + amount); break;
+    default: return null;
+  }
+
+  return now.toISOString();
+}

package/src/cli/commands/config.js

@@ -0,0 +1,95 @@
+import chalk from 'chalk';
+import { loadConfig, setConfigValue, resetConfig } from '../../config.js';
+import { printSuccess, printError, printInfo } from '../formatters.js';
+
+/**
+ * Register the `config` command with subcommands.
+ */
+export function registerConfigCommand(program) {
+  const config = program
+    .command('config')
+    .description('Manage carom configuration');
+
+  // config ls
+  config
+    .command('ls')
+    .description('Show current configuration')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const currentConfig = loadConfig(dataDir);
+
+        if (options.json) {
+          console.log(JSON.stringify(currentConfig, null, 2));
+          process.exit(0);
+        }
+
+        console.log('');
+        console.log(chalk.bold.cyan('  carom Configuration'));
+        console.log('');
+        printConfigObject(currentConfig, '  ');
+        console.log('');
+        printInfo(`Config file: ~/.carom/config.json`);
+        printInfo(`Use "carom config set <key> <value>" to change settings.`);
+        console.log('');
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  // config set
+  config
+    .command('set <key> <value>')
+    .description('Set a configuration value (dot-notation keys)')
+    .action(async (key, value) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        setConfigValue(key, value, dataDir);
+        printSuccess(`Set ${chalk.bold(key)} = ${chalk.bold(value)}`);
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  // config reset
+  config
+    .command('reset')
+    .description('Reset configuration to defaults')
+    .action(async () => {
+      try {
+        const dataDir = program.opts().dataDir;
+        resetConfig(dataDir);
+        printSuccess('Configuration reset to defaults.');
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}
+
+/**
+ * Pretty-print a config object with indentation.
+ */
+function printConfigObject(obj, indent = '', path = '') {
+  for (const [key, value] of Object.entries(obj)) {
+    const fullPath = path ? `${path}.${key}` : key;
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+      console.log(`${indent}${chalk.dim(key + ':')}`);
+      printConfigObject(value, indent + '  ', fullPath);
+    } else {
+      const displayValue = typeof value === 'boolean'
+        ? (value ? chalk.green('true') : chalk.red('false'))
+        : chalk.white(String(value || '(empty)'));
+      console.log(`${indent}${chalk.dim(key + ':')} ${displayValue}  ${chalk.dim(`[${fullPath}]`)}`);
+    }
+  }
+}

package/src/cli/commands/install.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { loadConfig } from '../../config.js';
+import { installService, getServiceType } from '../../service/manager.js';
+import { printSuccess, printError, printInfo, printWarning } from '../formatters.js';
+
+/**
+ * Register the `install` command.
+ */
+export function registerInstallCommand(program) {
+  program
+    .command('install')
+    .description('Install carom as a system service (auto-start on boot)')
+    .option('-p, --port <number>', 'Redirect server port', parseInt)
+    .option('--admin-port <number>', 'Admin dashboard & API port', parseInt)
+    .option('--host <address>', 'Bind address')
+    .option('--api-key <key>', 'API key')
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const config = loadConfig(dataDir);
+
+        // CLI options override config
+        if (options.port) config.port = options.port;
+        if (options.adminPort) config.adminPort = options.adminPort;
+        if (options.host) config.host = options.host;
+        if (options.apiKey) config.apiKey = options.apiKey;
+        config.dataDir = dataDir;
+
+        const serviceType = getServiceType();
+        printInfo(`Detected platform: ${serviceType}`);
+        printInfo(`Installing carom service...`);
+
+        const result = await installService(config);
+
+        printSuccess(result.message);
+        printInfo(`carom will now auto-start on boot.`);
+        printInfo(`Use ${chalk.bold('carom status')} to check the service.`);
+        printInfo(`Use ${chalk.bold('carom uninstall')} to remove.`);
+
+        if (!config.apiKey) {
+          printWarning('No API key set. The API is open to anyone. Use --api-key to secure it.');
+        }
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/list.js

@@ -0,0 +1,62 @@
+import { loadConfig } from '../../config.js';
+import { getDb, getLinks } from '../../db.js';
+import { formatTable, truncate, formatClicks, formatStatus, formatDate, printInfo } from '../formatters.js';
+
+/**
+ * Register the `ls` command.
+ */
+export function registerListCommand(program) {
+  program
+    .command('ls')
+    .description('List all links with click stats')
+    .option('--all', 'Include inactive links')
+    .option('--json', 'Output as JSON')
+    .option('--limit <number>', 'Max links to show', parseInt)
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const config = loadConfig(dataDir);
+        const db = getDb(dataDir);
+
+        const links = getLinks(db, {
+          includeInactive: options.all || false,
+          limit: options.limit || 100,
+        });
+
+        if (options.json) {
+          const baseUrl = config.baseUrl || `http://localhost:${config.port || 3000}`;
+          const output = links.map(l => ({
+            ...l,
+            shortUrl: `${baseUrl}/${l.slug}`,
+          }));
+          console.log(JSON.stringify(output, null, 2));
+          process.exit(0);
+        }
+
+        if (links.length === 0) {
+          printInfo('No links found. Create one with: carom add <url>');
+          process.exit(0);
+        }
+
+        const headers = ['ID', 'SLUG', 'DESTINATION', 'CLICKS (H/B)', 'CREATED', 'STATUS'];
+        const rows = links.map(l => [
+          l.id,
+          l.slug,
+          truncate(l.destination_url, 45),
+          formatClicks(l.human_clicks, l.bot_clicks),
+          formatDate(l.created_at),
+          formatStatus(l.active),
+        ]);
+
+        console.log('');
+        console.log(formatTable(headers, rows));
+        console.log('');
+        printInfo(`${links.length} link${links.length === 1 ? '' : 's'} total`);
+
+        process.exit(0);
+      } catch (err) {
+        console.error('Error:', err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/logs.js

@@ -0,0 +1,70 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { spawn } from 'child_process';
+import { DEFAULT_DATA_DIR, LOG_DIR } from '../../constants.js';
+import { printError, printInfo } from '../formatters.js';
+
+/**
+ * Register the `logs` command.
+ */
+export function registerLogsCommand(program) {
+  program
+    .command('logs')
+    .description('Tail the carom server logs')
+    .option('-n, --lines <number>', 'Number of lines to show', '50')
+    .option('--no-follow', 'Don\'t follow (just print last N lines)')
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir || DEFAULT_DATA_DIR;
+        const logDir = join(dataDir, LOG_DIR);
+        const stdoutLog = join(logDir, 'stdout.log');
+        const stderrLog = join(logDir, 'stderr.log');
+
+        // Find a log file that exists
+        let logFile = null;
+        if (existsSync(stdoutLog)) {
+          logFile = stdoutLog;
+        } else if (existsSync(stderrLog)) {
+          logFile = stderrLog;
+        }
+
+        if (!logFile) {
+          printError('No log files found.');
+          printInfo(`Log directory: ${logDir}`);
+          printInfo('Start the server first with: carom start');
+          process.exit(1);
+        }
+
+        printInfo(`Tailing: ${logFile}`);
+        console.log('');
+
+        const args = ['-n', options.lines];
+        if (options.follow !== false) {
+          args.push('-f');
+        }
+        args.push(logFile);
+
+        const tail = spawn('tail', args, {
+          stdio: 'inherit',
+        });
+
+        tail.on('error', (err) => {
+          printError(`Failed to tail logs: ${err.message}`);
+          process.exit(1);
+        });
+
+        tail.on('exit', (code) => {
+          process.exit(code || 0);
+        });
+
+        // Handle Ctrl+C
+        process.on('SIGINT', () => {
+          tail.kill('SIGINT');
+          process.exit(0);
+        });
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/remove.js

@@ -0,0 +1,36 @@
+import { getDb, findLinkByIdOrSlug, deactivateLink } from '../../db.js';
+import { printSuccess, printError } from '../formatters.js';
+
+/**
+ * Register the `rm` command.
+ */
+export function registerRemoveCommand(program) {
+  program
+    .command('rm <idOrSlug>')
+    .description('Deactivate a link')
+    .action(async (idOrSlug) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+
+        const link = findLinkByIdOrSlug(db, idOrSlug);
+        if (!link) {
+          printError(`Link "${idOrSlug}" not found.`);
+          process.exit(1);
+        }
+
+        if (!link.active) {
+          printError(`Link "${link.slug}" is already inactive.`);
+          process.exit(1);
+        }
+
+        deactivateLink(db, link.id);
+        printSuccess(`Link "${link.slug}" (→ ${link.destination_url}) deactivated.`);
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/rules.js

@@ -0,0 +1,168 @@
+import chalk from 'chalk';
+import { getDb, addRule, getRules, removeRule } from '../../db.js';
+import { BOT_UA_PATTERNS } from '../../cloak/patterns.js';
+import { testUserAgent } from '../../cloak/detector.js';
+import { formatTable, printSuccess, printError, printInfo, formatClassification } from '../formatters.js';
+
+/**
+ * Register the `rules` command with subcommands.
+ */
+export function registerRulesCommand(program) {
+  const rules = program
+    .command('rules')
+    .description('Manage bot detection rules');
+
+  // rules ls
+  rules
+    .command('ls')
+    .description('List all bot detection rules')
+    .option('--builtin', 'Show built-in patterns')
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+        const customRules = getRules(db);
+
+        if (options.builtin) {
+          console.log('');
+          console.log(chalk.bold.cyan('  Built-in Bot UA Patterns'));
+          console.log(chalk.dim(`  ${BOT_UA_PATTERNS.length} patterns loaded`));
+          console.log('');
+
+          // Group into columns
+          const cols = 4;
+          const rows = [];
+          for (let i = 0; i < BOT_UA_PATTERNS.length; i += cols) {
+            rows.push(
+              BOT_UA_PATTERNS.slice(i, i + cols)
+                .map(p => chalk.dim(p.padEnd(22)))
+                .join('')
+            );
+          }
+          console.log(rows.join('\n'));
+          console.log('');
+        }
+
+        console.log('');
+        console.log(chalk.bold.cyan('  Custom Rules'));
+        console.log('');
+
+        if (customRules.length === 0) {
+          printInfo('No custom rules. Add one with: carom rules add <pattern>');
+        } else {
+          const headers = ['ID', 'TYPE', 'PATTERN', 'WEIGHT', 'NOTE'];
+          const tableRows = customRules.map(r => [
+            r.id,
+            r.type,
+            r.pattern,
+            `+${r.weight}`,
+            r.note || '—',
+          ]);
+          console.log(formatTable(headers, tableRows));
+        }
+        console.log('');
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  // rules add
+  rules
+    .command('add <pattern>')
+    .description('Add a custom bot detection pattern')
+    .option('--type <type>', 'Rule type: ua_pattern, ip_range, asn', 'ua_pattern')
+    .option('--weight <number>', 'Score weight', parseInt)
+    .option('--note <text>', 'Description/note for the rule')
+    .action(async (pattern, options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+
+        const validTypes = ['ua_pattern', 'ip_range', 'asn'];
+        if (!validTypes.includes(options.type)) {
+          printError(`Invalid type "${options.type}". Must be one of: ${validTypes.join(', ')}`);
+          process.exit(1);
+        }
+
+        const rule = addRule(db, {
+          type: options.type,
+          pattern,
+          weight: options.weight || 30,
+          note: options.note || null,
+        });
+
+        printSuccess(`Rule added (ID: ${rule.id})`);
+        printInfo(`Type: ${rule.type}, Pattern: "${rule.pattern}", Weight: +${rule.weight}`);
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  // rules rm
+  rules
+    .command('rm <id>')
+    .description('Remove a custom rule')
+    .action(async (id) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+
+        const ruleId = parseInt(id, 10);
+        if (isNaN(ruleId)) {
+          printError('Rule ID must be a number.');
+          process.exit(1);
+        }
+
+        removeRule(db, ruleId);
+        printSuccess(`Rule ${ruleId} removed.`);
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+
+  // rules test
+  rules
+    .command('test <userAgent>')
+    .description('Test a user-agent string against detection rules')
+    .action(async (userAgent) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const db = getDb(dataDir);
+
+        const result = testUserAgent(userAgent, db);
+
+        console.log('');
+        console.log(chalk.bold(`  Testing: "${userAgent}"`));
+        console.log('');
+        console.log(`  Result:         ${formatClassification(result.classification)}`);
+        console.log(`  Score:          ${chalk.bold(result.score)} / 40 (threshold)`);
+        console.log('');
+
+        if (result.signals.length > 0) {
+          console.log(chalk.bold('  Signals:'));
+          for (const signal of result.signals) {
+            if (signal.name === 'note') {
+              console.log(chalk.dim(`    ℹ ${signal.detail}`));
+            } else {
+              console.log(`    ${chalk.yellow(`+${signal.weight}`)} ${signal.name}: ${signal.detail}`);
+            }
+          }
+        }
+        console.log('');
+
+        process.exit(0);
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/start.js

@@ -0,0 +1,43 @@
+import { loadConfig } from '../../config.js';
+import { getDb, getLinkCount } from '../../db.js';
+import { startServer } from '../../server/server.js';
+import { printBanner, printError } from '../formatters.js';
+
+/**
+ * Register the `start` command.
+ */
+export function registerStartCommand(program) {
+  program
+    .command('start')
+    .description('Start the carom redirect server')
+    .option('-p, --port <number>', 'Redirect server port', parseInt)
+    .option('--admin-port <number>', 'Admin dashboard & API port', parseInt)
+    .option('--host <address>', 'Bind address')
+    .option('--api-key <key>', 'API key for the REST API')
+    .action(async (options) => {
+      try {
+        const dataDir = program.opts().dataDir;
+        const config = loadConfig(dataDir);
+
+        // CLI options override config
+        if (options.port) config.port = options.port;
+        if (options.adminPort) config.adminPort = options.adminPort;
+        if (options.host) config.host = options.host;
+        if (options.apiKey) config.apiKey = options.apiKey;
+
+        // Init DB to get link count for banner
+        const db = getDb(dataDir);
+        const linkCount = getLinkCount(db);
+
+        printBanner(config, linkCount);
+
+        await startServer(config, {
+          dataDir,
+          verbose: program.opts().verbose || false,
+        });
+      } catch (err) {
+        printError(err.message);
+        process.exit(1);
+      }
+    });
+}