trackly-cli 0.3.2 → 0.4.1

package/README.md

@@ -151,6 +151,7 @@ Then use natural language in any of these clients:
 | trackly_get_job_brief | Get network brief for a job (company signal, top contact, actions) |
 | trackly_contacts_at_company | Search contacts at a specific company |
 | trackly_get_company_workspace | Full company workspace (jobs, contacts, hiring managers, campaigns) |
+| trackly_request_company | Request a company be added to Trackly (rate-limited to 5 pending) |
 
 ## Authentication
 
@@ -210,7 +211,7 @@ trackly config --base-url http://127.0.0.1:3000  # Point at a different backend
 | Job search + filters | Yes | Yes | Yes |
 | Apply/save/dismiss | Yes | Yes | Yes |
 | AI-powered search | Yes (trackly ask) | Yes | Yes |
-| MCP integration | Yes (10 tools) | -- | -- |
+| MCP integration | Yes (11 tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -224,7 +225,7 @@ Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly l
 
 **What MCP servers exist for job searching?**
 
-trackly-cli includes a built-in MCP server with 10 tools for job search, company lookup, and application tracking. Run `trackly mcp` or add it to Claude Code with `claude mcp add --scope user trackly -- trackly mcp`. It connects to a live database of 128,000+ jobs across 1,900+ companies.
+trackly-cli includes a built-in MCP server with 11 tools for job search, company lookup, and application tracking. Run `trackly mcp` or add it to Claude Code with `claude mcp add --scope user trackly -- trackly mcp`. It connects to a live database of 128,000+ jobs across 1,900+ companies.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -23,6 +23,7 @@ const BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'version', 'v', 'clear-api-k
 const VALUE_FLAGS = new Set([
   'api-key',
   'base-url',
+  'company',
   'function',
   'job-type',
   'keywords',
@@ -36,6 +37,42 @@ const VALUE_FLAGS = new Set([
   'status',
   'url',
 ]);
+
+// Flags accepted on ANY command. `api-key`/`base-url` are global overrides consumed
+// in main() before dispatch; help/version are handled by early-returns.
+const UNIVERSAL_FLAGS = new Set(['json', 'help', 'h', 'version', 'v', 'api-key', 'base-url']);
+
+// Per-command allow-lists — each set is the flags that command's handler actually
+// reads. Keyed at the command level (the union across a command's subcommands) so a
+// valid filtered detail call like `jobs 123 --region us` is never falsely rejected,
+// while typos (`--regoin`) and wrong-command flags (`jobs --url`, `jobs --search`)
+// still are. `jobs` includes the deprecated `location`/`modality` so they reach the
+// richer DEPRECATED_JOB_FLAGS migration message in cmdJobs rather than a generic error.
+// Commands NOT listed here (e.g. `mcp`, or an unknown command) skip flag validation —
+// the dispatcher reports unknown commands itself.
+const COMMAND_FLAGS = {
+  login: [],
+  logout: [],
+  whoami: [],
+  jobs: ['function', 'company', 'region', 'job-type', 'remote', 'status', 'sort', 'limit', 'offset', 'keywords', 'location', 'modality'],
+  job: [],
+  companies: ['limit', 'offset'],
+  search: [],
+  stats: [],
+  status: [],
+  apply: [],
+  save: [],
+  dismiss: [],
+  ask: [],
+  contacts: ['search', 'limit', 'offset'],
+  referral: [],
+  brief: [],
+  'company-brief': ['refresh'],
+  'company-workspace': [],
+  'request-company': ['url', 'notes'],
+  'api-key': ['name'],
+  config: ['api-key', 'base-url', 'clear-api-key', 'clear-base-url'],
+};
 const AUTH_HELP_TEXT = `Not authenticated.
   Option 1: trackly login                        (Google OAuth)
   Option 2: trackly config --api-key trk_xxx     (get key at usetrackly.app)
@@ -106,6 +143,59 @@ function parseArgs(args) {
   return result;
 }
 
+// Tiny Levenshtein (no dep) for "did you mean" flag suggestions.
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => new Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1)
+      );
+    }
+  }
+  return dp[m][n];
+}
+
+function nearestFlag(key, allowed) {
+  let best = null;
+  let bestDistance = Infinity;
+  for (const flag of allowed) {
+    const d = levenshtein(key, flag);
+    if (d < bestDistance) {
+      bestDistance = d;
+      best = flag;
+    }
+  }
+  return bestDistance <= 2 ? best : null;
+}
+
+// Reject flags that the resolved command doesn't accept. Catches typos
+// (`--regoin`) and wrong-command flags (`jobs --url`) that parseArgs would
+// otherwise capture and the handler would silently ignore — returning, e.g., an
+// unfiltered job feed that looks filtered. Unknown commands (and `mcp`) skip this;
+// the dispatcher reports unknown commands itself.
+function validateFlags(args) {
+  const cmd = args.command;
+  if (!cmd || !Object.prototype.hasOwnProperty.call(COMMAND_FLAGS, cmd)) return;
+  const allowed = new Set([...UNIVERSAL_FLAGS, ...COMMAND_FLAGS[cmd]]);
+  for (const key of Object.keys(args)) {
+    if (key === '_' || key === 'command') continue;
+    if (allowed.has(key)) continue;
+    // Strip non-printable chars so a crafted `--$'\x1b[…'` flag can't inject
+    // terminal escape sequences into the error message.
+    const safe = String(key).replace(/[^\x20-\x7e]/g, '');
+    const suggestion = nearestFlag(key, allowed);
+    const hint = suggestion ? ` Did you mean --${suggestion}?` : '';
+    failNow(`Unknown option --${safe} for 'trackly ${cmd}'.${hint} Run \`trackly --help\` for valid options.`);
+  }
+}
+
 function failNow(message, exitCode = 1) {
   outputError(message);
   process.exit(exitCode);
@@ -205,13 +295,16 @@ async function cmdLogin() {
 
   console.log(color('cyan', 'Opening browser for Google login...'));
 
-  function tryLogin(port) {
+  let activeServer = null;
+
+  function tryLogin() {
     return new Promise((resolve, reject) => {
       let settled = false;
       let timeoutId = null;
 
       const server = http.createServer((req, res) => {
-        const url = new URL(req.url, `http://localhost:${port}`);
+        // Base is only used to parse req.url's path + query; the port is irrelevant.
+        const url = new URL(req.url, 'http://127.0.0.1');
         if (url.pathname === '/callback') {
           const returnedState = url.searchParams.get('state');
           if (returnedState !== state) {
@@ -297,15 +390,20 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
         }
       };
 
+      activeServer = server;
+
       server.on('error', (err) => {
-        if (err.code === 'EADDRINUSE') {
-          reject(err);
-        } else {
-          settle(err);
-        }
+        settle(err);
       });
 
-      server.listen(port, '127.0.0.1', () => {
+      // Port 0 → OS-assigned ephemeral port, always free (no fixed-range collision,
+      // so no retry loop needed). Verify it lands in the backend's accepted range.
+      server.listen(0, '127.0.0.1', () => {
+        const port = server.address().port;
+        if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+          settle(new Error(`OS assigned an out-of-range callback port (${port}); expected 1024-65535.`));
+          return;
+        }
         console.log(color('dim', `Callback server on port ${port}`));
         const loginUrl = `${baseUrl}/auth/google/cli?port=${port}&state=${state}`;
         if (!openExternalUrl(loginUrl)) {
@@ -319,18 +417,20 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
     });
   }
 
-  const MAX_PORT_RETRIES = 3;
-  for (let attempt = 0; attempt < MAX_PORT_RETRIES; attempt++) {
-    const port = 19847 + Math.floor(Math.random() * 1000);
-    try {
-      return await tryLogin(port);
-    } catch (err) {
-      if (err.code === 'EADDRINUSE' && attempt < MAX_PORT_RETRIES - 1) {
-        console.log(color('dim', `Port ${port} in use, trying another...`));
-        continue;
-      }
-      throw err;
+  // One SIGINT handler for the whole login (not per-attempt): close the active
+  // callback server and exit cleanly on Ctrl-C, then always remove the handler so
+  // it can't leak. (No EADDRINUSE retry path now, so no handler-leak edge case.)
+  const onSigint = () => {
+    if (activeServer) {
+      try { activeServer.close(); } catch (_) {}
     }
+    process.exit(130);
+  };
+  process.on('SIGINT', onSigint);
+  try {
+    await tryLogin();
+  } finally {
+    process.removeListener('SIGINT', onSigint);
   }
 }
 
@@ -711,6 +811,15 @@ async function cmdConfig(args) {
   if (args['api-key'] === null) failNow('API key value required. Usage: trackly config --api-key <key>');
   if (args['base-url'] === null) failNow('Base URL value required. Usage: trackly config --base-url <url>');
 
+  // Reject contradictory set+clear in the same invocation rather than silently
+  // letting last-write-win produce surprising results.
+  if (args['api-key'] !== undefined && args['clear-api-key']) {
+    failNow('Cannot use --api-key and --clear-api-key together.');
+  }
+  if (args['base-url'] !== undefined && args['clear-base-url']) {
+    failNow('Cannot use --base-url and --clear-base-url together.');
+  }
+
   const config = loadConfig();
   let updated = false;
 
@@ -747,7 +856,11 @@ async function cmdConfig(args) {
   }
 
   if (args['base-url'] !== undefined) {
-    config.baseUrl = normalizeBaseUrlValue(args['base-url']);
+    try {
+      config.baseUrl = normalizeBaseUrlValue(args['base-url']);
+    } catch (e) {
+      failNow('Invalid base URL: ' + e.message);
+    }
     updated = true;
     console.log(color('green', `Base URL set to ${config.baseUrl}.`));
   }
@@ -882,7 +995,11 @@ async function main() {
   }
 
   if (args.command !== 'config' && args['base-url']) {
-    process.env.TRACKLY_BASE_URL = normalizeBaseUrlValue(args['base-url']);
+    try {
+      process.env.TRACKLY_BASE_URL = normalizeBaseUrlValue(args['base-url']);
+    } catch (e) {
+      failNow('Invalid base URL: ' + e.message);
+    }
   }
 
   if (args.version || args.v || args.command === 'version') {
@@ -895,6 +1012,10 @@ async function main() {
     process.exit(0);
   }
 
+  // Reject unknown / wrong-command flags AFTER the help+version early-returns
+  // (so `trackly --help --weird` still shows help instead of erroring).
+  validateFlags(args);
+
   switch (args.command) {
     case 'login':
       await cmdLogin();
@@ -993,9 +1114,13 @@ if (require.main === module) {
 }
 
 module.exports = {
+  COMMAND_FLAGS,
+  UNIVERSAL_FLAGS,
   getPublicConfig,
   hasJobListFilters,
+  levenshtein,
   main,
+  nearestFlag,
   normalizeBaseUrlValue,
   openExternalUrl,
   parseArgs,

package/docs/trackly-tools.md

@@ -72,7 +72,7 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
   - `locationFilter`: pass ONE of
     - a single scalar: `us`, `non_us`, `all`, or a region tag (`europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`), OR
     - an array of region tags for multi-region (e.g. `["europe", "canada"]`). The array form excludes `us` — combining `us` with other tags in an array causes the backend to silently drop the others. To get "not US" use the scalar `non_us` alone.
-  - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work-location style. For remote/hybrid/onsite filtering, use the `remote` boolean or `locationFilter: "remote"`; hybrid and onsite are not exposed as filters.
+  - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work-location style. For remote filtering, use the `remote` boolean or `locationFilter: "remote"`. Hybrid and onsite are not exposed as filters.
   - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`.
   - `status`: your application pipeline state. Values: `new`, `applying`, `applied_confirmed`, `check_later`, `not_interested`, `all`.
   - `sort`: `newest` (default) or `match` (highest match score first; requires a resume on file). Backend rejects the deprecated values `oldest` and `company` with HTTP 400.
@@ -86,6 +86,7 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 - **trackly_get_job_brief** — Get network brief for a job (company signal, top contact, actions)
 - **trackly_contacts_at_company** — Search contacts at a specific company
 - **trackly_get_company_workspace** — Get full company workspace (jobs, contacts, hiring managers, campaigns)
+- **trackly_request_company** — Request that a company be added to Trackly's tracked companies. Rate-limited to 5 pending requests per user. Parameters: `companyName` (required), `companyUrl` (optional), `notes` (optional).
 
 ### Example Prompts
 

package/lib/client.js

@@ -29,17 +29,28 @@ function getConfigPaths() {
 
 function loadConfig() {
   const { file } = getConfigPaths();
+  // Read the file directly rather than gating on fs.existsSync(): existsSync can
+  // mask a permission error (and races the read). Distinguish "no config yet"
+  // (ENOENT → {}) from "config exists but unreadable" (EACCES/EPERM → a clear,
+  // actionable error) from "config is corrupt JSON".
+  let raw;
   try {
-    if (fs.existsSync(file)) {
-      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return {};
+    if (error && (error.code === 'EACCES' || error.code === 'EPERM')) {
+      throw new TracklyConfigError(`Trackly config is not readable (${file}). Check file permissions.`);
     }
+    throw error;
+  }
+  try {
+    return JSON.parse(raw);
   } catch (error) {
     if (error instanceof SyntaxError) {
       throw new TracklyConfigError(`Trackly config is invalid JSON. Fix or delete ${file}.`);
     }
     throw error;
   }
-  return {};
 }
 
 function ensureConfigDir() {
@@ -190,7 +201,28 @@ function getRequestHeaders(skipAuth = false, userAgent = null) {
   return headers;
 }
 
-async function refreshAccessToken() {
+// Single-flight wrapper around the refresh logic. Coalesces concurrent refreshes
+// WITHIN THIS PROCESS so simultaneous 401s (e.g. parallel MCP tool calls in the
+// long-lived stdio server) don't each fire `POST /api/auth/refresh`. The backend
+// rotates the refresh token on use, so a second in-flight refresh would send a
+// now-stale token → 4xx → clearOAuthTokens() → the user is silently logged out
+// mid-session even though the first refresh succeeded. All concurrent callers
+// await the same promise, then each retries reading the freshly-saved token.
+//
+// Scope: this does NOT coordinate across multiple `trackly` processes sharing
+// ~/.trackly/config.json. That is acceptable — saveConfig() is atomic (renameSync)
+// and concurrent multi-process refresh is rare; a cross-process file lock is a
+// possible future addition, not in scope here.
+let _refreshInFlight = null;
+function refreshAccessToken() {
+  if (_refreshInFlight) return _refreshInFlight;
+  // _doRefresh resolves to a token-or-null and never rejects, so the cached
+  // promise can be safely shared and the finally() latch always clears.
+  _refreshInFlight = _doRefresh().finally(() => { _refreshInFlight = null; });
+  return _refreshInFlight;
+}
+
+async function _doRefresh() {
   const rt = getRefreshToken();
   if (!rt) return null;
 
@@ -291,7 +323,25 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
         if (aborted) return; // req.destroy already rejected via 'error' handler
 
         let json;
-        try { json = body ? JSON.parse(body) : {}; } catch { json = { raw: body }; }
+        try {
+          json = body ? JSON.parse(body) : {};
+        } catch {
+          // Non-JSON body (HTML error page, plaintext, proxy notice, …). Keep the
+          // raw body for debugging but always attach a usable `message` so the
+          // downstream `e.error || e.message || fallback` chain has real context.
+          json = { raw: body, message: 'Received a non-JSON response from the Trackly API.' };
+        }
+
+        // The Trackly API is a same-origin JSON API that should never redirect on
+        // the paths the CLI/MCP call. node:http does not auto-follow 3xx, so a
+        // redirect would otherwise resolve as "success" with the redirect headers
+        // as bogus data. Treat it as an error with a clear, actionable message.
+        if (res.statusCode >= 300 && res.statusCode < 400) {
+          return reject({
+            status: res.statusCode,
+            message: `Unexpected redirect (HTTP ${res.statusCode}) from the Trackly API.`,
+          });
+        }
 
         if (res.statusCode === 401 && !skipAuth && authMethod === 'token' && !_isRetry) {
           // Try token refresh (once only)

package/lib/formatters.js

@@ -6,7 +6,19 @@ const c = {
   magenta: '\x1b[35m', cyan: '\x1b[36m', red: '\x1b[31m',
 };
 
-function color(name, text) {
+// Decide whether to emit ANSI color for a given output stream.
+// Precedence (no-color.org + the common FORCE_COLOR convention):
+//   NO_COLOR present and non-empty → never color
+//   FORCE_COLOR set and not "0"/"false" → always color
+//   otherwise → only when the stream is a TTY
+function shouldColor(stream = process.stdout) {
+  if ('NO_COLOR' in process.env && process.env.NO_COLOR !== '') return false;
+  if (process.env.FORCE_COLOR && !['0', 'false'].includes(process.env.FORCE_COLOR)) return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+function color(name, text, stream = process.stdout) {
+  if (!shouldColor(stream)) return String(text);
   return `${c[name] || ''}${text}${c.reset}`;
 }
 
@@ -314,7 +326,8 @@ function padRight(str, len) {
 }
 
 function outputError(msg) {
-  console.error(color('red', `Error: ${msg}`));
+  // Errors go to stderr, so gate their color on stderr's TTY-ness, not stdout's.
+  console.error(color('red', `Error: ${msg}`, process.stderr));
 }
 
-module.exports = { color, isJSON, outputJobs, outputCompanies, outputStats, outputContacts, outputReferralCampaign, outputNetworkBrief, outputCompanyBrief, outputCompanyWorkspace, outputError };
+module.exports = { color, shouldColor, isJSON, outputJobs, outputCompanies, outputStats, outputContacts, outputReferralCampaign, outputNetworkBrief, outputCompanyBrief, outputCompanyWorkspace, outputError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "AI job search CLI + hosted MCP server with OAuth. 128K+ jobs, 1,900+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {

package/server.json

@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.3.2",
+  "version": "0.4.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.3.2",
+      "version": "0.4.1",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {