trackly-cli 0.2.1 → 0.2.3

package/bin/trackly

@@ -466,13 +466,30 @@ async function cmdStats() {
 }
 
 const ACTION_TO_COMMAND = { applied: 'apply', saved: 'save', dismissed: 'dismiss' };
+
+// CLI surface accepts applied|saved|dismissed (legacy human-friendly terms).
+// Backend `/api/jobscout/tracker/jobs/:id/stage` expects stage values:
+//   applied → applied, saved → backlog, dismissed → discarded
+// The old `/api/jobscout-tracker/status` endpoint was removed; the new stage
+// endpoint is what production actually serves (and what hosted MCP uses).
+const ACTION_TO_STAGE = { applied: 'applied', saved: 'backlog', dismissed: 'discarded' };
+
 async function cmdUpdateStatus(id, action) {
   const jobId = parseJobId(id);
   if (jobId === null) failNow(`Job ID must be a positive integer. Usage: trackly ${ACTION_TO_COMMAND[action] || action} <id>`);
   if (!hasAuth()) failNow(AUTH_HELP_TEXT);
 
+  // action is already validated by the command dispatcher (apply/save/dismiss subcommands
+  // pass literal strings). No `|| action` fallback — if ACTION_TO_STAGE is ever widened
+  // without updating the dispatcher (or vice versa), fail loud rather than silently POST
+  // an unintended stage value (e.g., posting stage='snoozed' when backend only knows the
+  // stage column's allowlist). Mirrors the defensive throw in mcp/server.js.
+  const stage = ACTION_TO_STAGE[action];
+  if (!stage) {
+    failNow(`Internal error: unknown action "${action}" — expected applied|saved|dismissed.`);
+  }
   try {
-    const result = await apiRequest('POST', '/api/jobscout-tracker/status', { jobId, action });
+    const result = await apiRequest('POST', `/api/jobscout/tracker/jobs/${jobId}/stage`, { stage });
     if (isJSON()) return printJson(result);
     console.log(color('green', `Job ${jobId} marked as ${STATUS_LABELS[action]}.`));
   } catch (e) {
@@ -767,7 +784,7 @@ ${color('bold', 'Filter values:')}
   --remote         Flag (no value). Filters for remote jobs (equivalent to usStates=REMOTE).
   --status         new, applying, applied_confirmed, check_later, not_interested, all
                    (filters by YOUR application pipeline state)
-  --sort           newest, oldest, company
+  --sort           newest (default), match (highest match score first, requires resume)
 
 ${color('bold', 'MCP Setup:')}
   Claude Code: claude mcp add --scope user trackly -- trackly mcp
@@ -790,6 +807,29 @@ async function main() {
 
   if (args.command !== 'config' && args['api-key']) {
     process.env.TRACKLY_API_KEY = String(args['api-key']);
+    // Warn once per invocation: --api-key on the command line is visible in `ps auxww` to
+    // any local user AND lands in shell history (~/.zsh_history, ~/.bash_history). This
+    // warning is a nudge, not a block — scripted pipelines can suppress via TRACKLY_NO_WARN=1.
+    // Printed to stderr (not stdout) so `--json` consumers parsing stdout are unaffected.
+    if (process.env.TRACKLY_NO_WARN !== '1') {
+      process.stderr.write(
+        '\x1b[33mWarning:\x1b[0m --api-key on the command line is visible in `ps` and shell history.\n' +
+        '  Prefer: TRACKLY_API_KEY=trk_... trackly ... (env var)\n' +
+        '       or: trackly config --api-key trk_... (persisted to ~/.trackly/config.json, mode 0600)\n' +
+        '  Silence this warning: TRACKLY_NO_WARN=1\n'
+      );
+    }
+    // Scrub the flag value from argv so subsequent inspection (diagnostics, crash reporters,
+    // child processes that inherit argv) cannot recover the secret. The `ps` vector is
+    // already lost the moment the process started — this only protects against in-process
+    // leaks (e.g. an MCP tool accidentally logging process.argv).
+    for (let i = 0; i < process.argv.length; i++) {
+      if (process.argv[i] === '--api-key' && i + 1 < process.argv.length) {
+        process.argv[i + 1] = '***';
+      } else if (process.argv[i].startsWith('--api-key=')) {
+        process.argv[i] = '--api-key=***';
+      }
+    }
   }
 
   if (args.command !== 'config' && args['base-url']) {

package/docs/trackly-tools.md

@@ -75,7 +75,7 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
   - `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.
   - `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`, `oldest`, `company`.
+  - `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.
   - `keywords`, `companyId`, `limit`, `offset`.
 - **trackly_get_job** — Get full job details by ID
 - **trackly_search_companies** — Semantic company search

package/lib/client.js

@@ -54,7 +54,20 @@ function ensureConfigDir() {
 function saveConfig(config) {
   ensureConfigDir();
   const { file } = getConfigPaths();
-  fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 });
+  // Atomic write: stage to a sibling temp file (same dir → same filesystem → rename is atomic
+  // on POSIX) then rename into place. Without this, a crash or SIGKILL mid-write can leave
+  // a zero-byte or partial config.json, and the next CLI invocation silently loses all auth.
+  // Temp file is created mode 0600 so tokens are never world-readable, even briefly.
+  const tmp = `${file}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(tmp, 0o600); } catch (e) {}
+  try {
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    // Best-effort cleanup of the temp file if rename fails; re-raise the original error.
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw e;
+  }
   try { fs.chmodSync(file, 0o600); } catch (e) {}
 }
 
@@ -63,6 +76,28 @@ function clearConfig() {
   try { fs.unlinkSync(file); } catch (e) {}
 }
 
+// Surgical alternative to clearConfig() for the refresh-failure path. Deletes ONLY the
+// OAuth credentials (token + refreshToken) while preserving everything else on disk
+// (baseUrl, apiKey, timeout overrides, future keys). A refresh token being invalidated
+// is not a reason to reset the user's `trackly config --base-url` choice — use this
+// instead of clearConfig() when the only thing known to be dead is the session pair.
+// Bug caught by Cursor Bugbot on PR #20: clearConfig() in refresh failure paths
+// silently wiped baseUrl alongside the dead tokens.
+function clearOAuthTokens() {
+  const config = loadConfig();
+  delete config.token;
+  delete config.refreshToken;
+  // If nothing else is persisted (e.g. user only ever logged in via OAuth and never set
+  // a custom baseUrl), unlink the file so getConfigPaths().file doesn't linger as an
+  // empty {} on disk. Otherwise preserve the remaining keys.
+  if (Object.keys(config).length === 0) {
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (e) {}
+    return;
+  }
+  saveConfig(config);
+}
+
 function getBaseUrl() {
   return process.env.TRACKLY_BASE_URL || loadConfig().baseUrl || DEFAULT_BASE_URL;
 }
@@ -169,7 +204,25 @@ async function refreshAccessToken() {
       saveConfig(config);
       return result.token;
     }
-  } catch (e) {}
+    // Backend responded 2xx but didn't return a token (e.g. { success: false, code: 'invalid_grant' }).
+    // Treat as an invalidated session and purge ONLY the OAuth pair so we don't retry on
+    // every subsequent 401. Without this, a backend that signals failure via JSON instead of
+    // a 4xx status would leave the user stuck in a doomed-refresh loop forever.
+    // Use clearOAuthTokens() — NOT clearConfig() — so the user's baseUrl, apiKey, and any
+    // other persisted settings survive a token expiry. (Bug caught by Cursor Bugbot on
+    // PR #20 post-review: the earlier clearConfig() call silently wiped baseUrl too.)
+    try { clearOAuthTokens(); } catch (_) {}
+  } catch (e) {
+    // A 401/invalid_grant on refresh means the token is permanently dead (rotation, manual
+    // revocation, or session expired). Keeping it on disk makes every subsequent request
+    // trigger another doomed refresh attempt — the user looks perpetually broken until they
+    // `trackly logout`. Network errors (ECONNREFUSED, DNS) are transient and should NOT
+    // purge the token. Surgical OAuth-only clear preserves baseUrl + apiKey + timeout overrides.
+    const status = e && typeof e.status === 'number' ? e.status : null;
+    if (status === 400 || status === 401 || status === 403) {
+      try { clearOAuthTokens(); } catch (_) {}
+    }
+  }
   return null;
 }
 
@@ -227,7 +280,12 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
         }
 
         if (res.statusCode >= 400) {
-          reject({ status: res.statusCode, ...json });
+          // Spread `json` FIRST so the HTTP statusCode always wins. A backend that returns
+          // `{"status": "error"}` in the body would otherwise clobber the numeric status with
+          // a string, breaking downstream branches like `typeof e.status === 'number'` in
+          // refreshAccessToken — which would silently skip the 400/401/403 token-clear and
+          // leave dead refresh tokens on disk. (Cursor Bugbot finding #5 on PR #20.)
+          reject({ ...json, status: res.statusCode });
         } else {
           resolve(json);
         }
@@ -250,18 +308,21 @@ module.exports = {
   TracklyConfigError,
   apiRequest,
   clearConfig,
+  clearOAuthTokens,
   ensureSecureUrl,
   getApiKey,
   getAuthHeader,
   getAuthMethod,
   getBaseUrl,
   getConfigPaths,
+  getRefreshToken,
   getRequestHeaders,
   getRequestTimeoutMs,
   getToken,
   hasAuth,
   loadConfig,
   normalizeEndpoint,
+  refreshAccessToken,
   saveConfig,
   CONFIG_DIR: DEFAULT_CONFIG_DIR,
   CONFIG_FILE: path.join(DEFAULT_CONFIG_DIR, 'config.json'),

package/mcp/server.js

@@ -36,6 +36,16 @@ const STATUS_VALUES = ['new', 'applying', 'applied_confirmed', 'check_later', 'n
 // `jobModality` enum matches `jobscout.ts:2870-2875`. Employment type, NOT work-location.
 const JOB_MODALITIES = ['full_time', 'internship', 'all'];
 
+// `sort` enum matches backend handler at `jobscout.ts:3053` — NOT the pre-fix
+// `newest|oldest|company` (backend rejects oldest/company with HTTP 400).
+const SORT_VALUES = ['newest', 'match'];
+
+// Maps the user-facing trackly_update_status action to the backend's tracker
+// stage column. Backend `/api/jobscout/tracker/jobs/:id/stage` expects the
+// stage value, NOT the legacy action name. Hoisted to module scope so it's not
+// rebuilt on every tool invocation.
+const ACTION_TO_STAGE = { applied: 'applied', saved: 'backlog', dismissed: 'discarded' };
+
 function createErrorResult(error, fallbackMessage, extra = {}) {
   const payload = {
     error: error?.error || error?.message || fallbackMessage,
@@ -111,7 +121,7 @@ function createServer() {
       status: z.enum(STATUS_VALUES).optional().describe(
         'Filter by YOUR application pipeline state. Not a generic job-posting status. Values: ' + STATUS_VALUES.join(', ')
       ),
-      sort: z.enum(['newest', 'oldest', 'company']).optional().describe('Sort order: newest, oldest, company'),
+      sort: z.enum(SORT_VALUES).optional().describe('Sort order: newest (default) or match (highest match score first; requires resume). Backend rejects legacy oldest/company with HTTP 400.'),
       limit: z.number().max(50).optional().describe('Max results (default 20, max 50)'),
       offset: z.number().min(0).optional().describe('Pagination offset'),
       keywords: z.string().max(500).optional().describe('Keyword search in title, company, or description'),
@@ -194,7 +204,16 @@ function createServer() {
       action: z.enum(['applied', 'saved', 'dismissed']).describe('Status action'),
     },
     wrapTool(async ({ id, action }) => {
-      return apiRequest('POST', '/api/jobscout-tracker/status', { jobId: id, action }, false, false, MCP_USER_AGENT);
+      // Backend expects the stage name, not the human-friendly action name.
+      // ACTION_TO_STAGE is defined at module scope (mirrors the same map in bin/trackly).
+      const stage = ACTION_TO_STAGE[action];
+      if (!stage) {
+        // Defensive: the z.enum above already rejects values outside applied|saved|dismissed,
+        // but if the enum is ever widened the mapping must be updated in lockstep — fail loud
+        // rather than silently sending an unintended stage.
+        throw new Error(`trackly_update_status: unknown action "${action}" — expected applied|saved|dismissed`);
+      }
+      return apiRequest('POST', `/api/jobscout/tracker/jobs/${id}/stage`, { stage }, false, false, MCP_USER_AGENT);
     }, 'Failed to update job status')
   );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "mcpName": "io.github.kevinastuhuaman/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.1",
+  "version": "0.2.3",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.2.1",
+      "version": "0.2.3",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {