trackly-cli 0.2.8 → 0.4.0

package/README.md

@@ -35,7 +35,7 @@ trackly jobs --function product
 
 ## At a Glance
 
-1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 10 MCP tools
+1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 11 MCP tools
 
 ## CLI Commands
 
@@ -63,6 +63,7 @@ trackly referral start 1234           # Start a referral campaign
 trackly referral status 1234          # Check referral campaign status
 trackly company-brief 243             # Get company brief (--refresh to regenerate)
 trackly company-workspace 243         # Full company workspace view
+trackly request-company "eBay"        # Request a company be added (--url, --notes optional)
 trackly api-key create                # Generate API key
 trackly api-key list                  # List API keys
 trackly config                        # Show current CLI config
@@ -150,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
 
@@ -209,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 |
 
@@ -223,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,17 +23,56 @@ 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',
   'limit',
   'name',
+  'notes',
   'offset',
   'region',
   'search',
   'sort',
   '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)
@@ -104,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);
@@ -668,6 +760,43 @@ async function cmdCompanyWorkspace(args) {
   }
 }
 
+async function cmdRequestCompany(args) {
+  // Positional arg = company name. Allow multi-word names without forcing the user
+  // to quote, e.g. `trackly request-company Built Robotics --url ...` joins the
+  // free-floating positionals into "Built Robotics". Matches `trackly ask` UX.
+  const name = (args._ || []).join(' ').trim();
+  if (!name) {
+    failNow('Company name required. Usage: trackly request-company <name> [--url <url>] [--notes <notes>]');
+  }
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
+  const url = typeof args.url === 'string' ? args.url : '';
+  const notes = typeof args.notes === 'string' ? args.notes : '';
+
+  try {
+    const result = await apiRequest('POST', '/api/jobscout/companies/request', {
+      company_name: name,
+      company_url: url,
+      notes: notes,
+      source: 'cli',
+    });
+    if (isJSON()) return printJson(result);
+    const requestId = result.requestId || result.id || '?';
+    console.log(color('green', `Requested "${name}" (#${requestId}). Trackly team will review shortly.`));
+  } catch (e) {
+    // Backend returns 429 (rate limit, max 5 pending) and 409 (duplicate pending request)
+    // with a specific `error` message. Surface that message verbatim so the user knows
+    // exactly which gate fired without having to enable --json.
+    if (e.status === 429) {
+      setErrorExit(e.error || 'Maximum 5 pending requests allowed. Please wait for existing requests to be reviewed.');
+    } else if (e.status === 409) {
+      setErrorExit(e.error || 'You already have a pending request for this company.');
+    } else {
+      setErrorExit(e.error || e.message || 'Failed to request company');
+    }
+  }
+}
+
 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>');
@@ -708,7 +837,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}.`));
   }
@@ -770,6 +903,7 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'brief <id>')}           Get network brief for a job
   ${color('cyan', 'company-brief <id>')}   Get company brief (--refresh to generate)
   ${color('cyan', 'company-workspace <id>')} Show company workspace (jobs, contacts, campaigns)
+  ${color('cyan', 'request-company <name>')} Request a company be added to Trackly (--url, --notes)
   ${color('cyan', 'api-key create')}       Generate an API key
   ${color('cyan', 'api-key list')}         List your API keys
   ${color('cyan', 'config')}               Show or update CLI config (--api-key, --base-url)
@@ -842,7 +976,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') {
@@ -855,6 +993,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();
@@ -926,6 +1068,9 @@ async function main() {
     case 'company-workspace':
       await cmdCompanyWorkspace(args);
       break;
+    case 'request-company':
+      await cmdRequestCompany(args);
+      break;
     case 'api-key':
       await cmdApiKey(args);
       break;
@@ -950,9 +1095,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/mcp/server.js

@@ -297,6 +297,24 @@ function createServer() {
     }, 'Failed to fetch company workspace')
   );
 
+  server.tool(
+    'trackly_request_company',
+    'Request that a company be added to Trackly\'s tracked companies. Use when the user asks about a company that isn\'t in trackly_search_companies / trackly_list_companies results. Rate-limited to 5 pending requests per user.',
+    {
+      companyName: z.string().min(1).max(200).describe('Company name (e.g. "eBay")'),
+      companyUrl: z.string().max(500).optional().describe('Optional careers page or homepage URL (e.g. "https://careers.ebay.com")'),
+      notes: z.string().max(1000).optional().describe('Optional context (e.g. "MBA hiring page", "specific role I want tracked")'),
+    },
+    wrapTool(async ({ companyName, companyUrl, notes }) => {
+      return apiRequest('POST', '/api/jobscout/companies/request', {
+        company_name: companyName,
+        company_url: companyUrl || '',
+        notes: notes || '',
+        source: 'mcp',
+      }, false, false, MCP_USER_AGENT);
+    }, 'Failed to request company')
+  );
+
   return server;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.2.8",
+  "version": "0.4.0",
   "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.2.8",
+  "version": "0.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.2.8",
+      "version": "0.4.0",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {