jobtrack 1.0.0

package/bin/jobtrack.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+// Only the installed CLI needs a real per-user data directory for the database, model cache,
+// and .env — `apps/api/src/config.ts` otherwise defaults to the monorepo's own repo root,
+// which is exactly right for `npm run tray`/`npm run dev` (run straight off src/ via tsx,
+// never through this file) and exactly wrong once this is running out of node_modules.
+if (!process.env.JOBTRACK_HOME) {
+  const base = process.platform === 'win32' && process.env.APPDATA ? process.env.APPDATA : join(homedir(), '.local', 'share');
+  process.env.JOBTRACK_HOME = join(base, 'jobtrack');
+}
+
+// The published package ships TypeScript sources rather than a compiled build (matching
+// apps/api and apps/mcp, which also run straight off `src/` via tsx). Loading tsx's ESM hook
+// in-process — via `node:module`'s `register()`, or tsx's own `tsx/esm/api` register (both
+// route through the same internal loader) — throws "tsx must be loaded with --import instead
+// of --loader" on current tsx/Node: that loader's `initialize` hook runs in a worker thread and
+// never receives its options data that way. So this spawns a child `node` with the exact
+// `--require <preflight> --import <loader>` flags the tsx CLI itself uses, resolved via tsx's
+// public `tsx`/`tsx/preflight` export paths rather than hardcoded internal file names.
+//
+// One easy-to-miss gotcha reproducing that: pass `env` to spawnSync at all (even a literal
+// `process.env`) and the *same* "must be loaded with --import" error comes back — something
+// about handing Node a reconstructed environment object, rather than truly inheriting via
+// `stdio`, breaks whatever the loader's worker thread needs. Leaving `env` unset here (true
+// inheritance) is required, not a style choice.
+const require = createRequire(import.meta.url);
+const preflight = require.resolve('tsx/preflight');
+const loader = pathToFileURL(require.resolve('tsx')).href;
+const cliEntry = fileURLToPath(new URL('../src/cli.ts', import.meta.url));
+
+const result = spawnSync(
+  process.execPath,
+  ['--require', preflight, '--import', loader, cliEntry, ...process.argv.slice(2)],
+  { stdio: 'inherit' },
+);
+
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "jobtrack",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Runs the JobTrack API + web UI as one background process with a Windows tray icon",
+  "main": "./src/cli.ts",
+  "bin": {
+    "jobtrack": "./bin/jobtrack.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor"
+  ],
+  "scripts": {
+    "dev": "tsx watch --clear-screen=false src/cli.ts",
+    "start": "tsx src/cli.ts",
+    "prepack": "node scripts/stage-assets.mjs"
+  },
+  "dependencies": {
+    "@fastify/static": "^10.1.3",
+    "@jobtrack/api": "^1.0.0",
+    "fastify": "^5.12.1",
+    "systray": "^1.0.5",
+    "tsx": "^4.23.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1"
+  }
+}

package/src/assets.ts

@@ -0,0 +1,34 @@
+/**
+ * Resolves read-only files this package needs but doesn't own the source of: the built web
+ * UI, and a template `.env.example`. Prefers a copy staged inside this package (see
+ * scripts/stage-assets.mjs, which the `prepack` script runs before `npm publish`/`npm pack`)
+ * and falls back to the sibling location in this monorepo, for local development before that
+ * staging step has ever run.
+ *
+ * Distinct from `resolveAppDataDir` in `@jobtrack/api/config`: that's where *user* data lives
+ * (the database, the model cache); this is where the package's own *shipped* assets live.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageRoot = resolve(here, '..');
+/** Only exists in a monorepo checkout — never present in a published, installed package. */
+const monorepoRoot = resolve(here, '../../..');
+
+function resolveAsset(bundledRelative: string, monorepoRelative: string): string | undefined {
+  const bundled = resolve(packageRoot, bundledRelative);
+  if (existsSync(bundled)) return bundled;
+  const monorepo = resolve(monorepoRoot, monorepoRelative);
+  if (existsSync(monorepo)) return monorepo;
+  return undefined;
+}
+
+export function resolveWebDist(): string | undefined {
+  return resolveAsset('vendor/web-dist', 'apps/web/dist');
+}
+
+export function resolveEnvExample(): string | undefined {
+  return resolveAsset('vendor/.env.example', '.env.example');
+}

package/src/autostart.ts

@@ -0,0 +1,50 @@
+/**
+ * Autostart with Windows, via the per-user Registry Run key — no admin rights needed, and it
+ * survives reinstalls since it's keyed off HKCU, not the app's install location.
+ *
+ * The registered command always points at this package's `bin/jobtrack.js`, resolved relative
+ * to this module rather than to however the current process happened to be launched (tsx watch
+ * during development must never end up as the autostart target).
+ */
+import { execFileSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(here, '../bin/jobtrack.js');
+
+const RUN_KEY = String.raw`HKCU\Software\Microsoft\Windows\CurrentVersion\Run`;
+const VALUE_NAME = 'JobTrack';
+
+function assertWindows(): void {
+  if (process.platform !== 'win32') {
+    throw new Error('Autostart is only supported on Windows.');
+  }
+}
+
+export function isAutostartEnabled(): boolean {
+  if (process.platform !== 'win32') return false;
+  try {
+    execFileSync('reg', ['query', RUN_KEY, '/v', VALUE_NAME], { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function enableAutostart(): void {
+  assertWindows();
+  const command = `"${process.execPath}" "${binPath}"`;
+  execFileSync('reg', ['add', RUN_KEY, '/v', VALUE_NAME, '/t', 'REG_SZ', '/d', command, '/f'], {
+    stdio: 'ignore',
+  });
+}
+
+export function disableAutostart(): void {
+  assertWindows();
+  try {
+    execFileSync('reg', ['delete', RUN_KEY, '/v', VALUE_NAME, '/f'], { stdio: 'ignore' });
+  } catch {
+    // Already absent — nothing to do.
+  }
+}

package/src/cli.ts

@@ -0,0 +1,44 @@
+/**
+ * Entry point for the `jobtrack` command (see bin/jobtrack.js).
+ *
+ * Starts the API + web UI as one process (server.ts) and, on Windows, shows a tray icon for
+ * opening the UI, toggling autostart, and opening .env (tray.ts). Elsewhere it just runs
+ * headless — Ctrl+C to stop — until a native tray for those platforms is worth building.
+ */
+import { startServer } from './server.js';
+import { createTray } from './tray.js';
+import { isAutostartEnabled, enableAutostart, disableAutostart } from './autostart.js';
+import { openSettingsFile } from './settings.js';
+import { openUrl } from './os.js';
+
+const { app, config, repos, search } = await startServer();
+
+const url = `http://${config.host === '0.0.0.0' ? '127.0.0.1' : config.host}:${config.port}`;
+console.log(`JobTrack running at ${url} (driver: ${config.driver})`);
+
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  search.stop();
+  await app.close();
+  await repos.close();
+  process.exit(0);
+}
+
+for (const signal of ['SIGINT', 'SIGTERM'] as const) {
+  process.once(signal, () => void shutdown());
+}
+
+if (process.platform === 'win32') {
+  const tray = createTray({
+    autostartEnabled: isAutostartEnabled(),
+    onOpen: () => openUrl(url),
+    onToggleAutostart: (enabled) => (enabled ? enableAutostart() : disableAutostart()),
+    onOpenSettings: () => openSettingsFile(),
+    onQuit: () => void shutdown(),
+  });
+  process.once('exit', () => tray.kill(false));
+} else {
+  console.log('[tray] a system tray icon is only implemented for Windows today; running headless. Press Ctrl+C to stop.');
+}

package/src/os.ts

@@ -0,0 +1,28 @@
+/**
+ * Small platform-shell helpers. The tray icon itself (see tray.ts) is Windows-only for now,
+ * but these stay cross-platform so running headless on macOS/Linux still gets a working
+ * "open the app" experience.
+ */
+import { execFile } from 'node:child_process';
+
+export function openUrl(url: string): void {
+  if (process.platform === 'win32') {
+    // The empty string is `start`'s window-title argument — required so it doesn't mistake
+    // a quoted URL for the title itself.
+    execFile('cmd', ['/c', 'start', '""', url]);
+  } else if (process.platform === 'darwin') {
+    execFile('open', [url]);
+  } else {
+    execFile('xdg-open', [url]);
+  }
+}
+
+export function openInEditor(filePath: string): void {
+  if (process.platform === 'win32') {
+    execFile('notepad.exe', [filePath]);
+  } else if (process.platform === 'darwin') {
+    execFile('open', ['-t', filePath]);
+  } else {
+    execFile('xdg-open', [filePath]);
+  }
+}

package/src/server.ts

@@ -0,0 +1,66 @@
+/**
+ * Composes the existing API app with static serving for the built web UI, so the tray manages
+ * one process instead of two. Mirrors apps/api/src/index.ts's startup sequence (config, repos,
+ * search, then listen) but adds @fastify/static + an SPA fallback on top of the same
+ * `buildApp` every other entry point (API server, tests) uses — the JSON API itself is
+ * unchanged, including its 404 behavior for `/api/*`.
+ */
+import fastifyStatic from '@fastify/static';
+import type { FastifyInstance } from 'fastify';
+import { buildApp } from '@jobtrack/api/app';
+import { loadConfig, type Config } from '@jobtrack/api/config';
+import { createRepos, type RepoBundle } from '@jobtrack/api/db/repos';
+import { SearchIndex } from '@jobtrack/api/search';
+import { DisabledEmbedder, TransformersEmbedder, type Embedder } from '@jobtrack/api/search/embedder';
+import { resolveWebDist } from './assets.js';
+
+export interface RunningServer {
+  app: FastifyInstance;
+  config: Config;
+  repos: RepoBundle;
+  search: SearchIndex;
+}
+
+export async function startServer(): Promise<RunningServer> {
+  const config = loadConfig();
+  const repos = await createRepos(config);
+
+  const embedder: Embedder = config.semanticSearchEnabled
+    ? new TransformersEmbedder({
+        model: config.embeddingModel,
+        cacheDir: config.modelCacheDir,
+        onError: (error) => {
+          console.warn('[search] semantic model unavailable, staying lexical-only:', error);
+        },
+      })
+    : new DisabledEmbedder();
+
+  const search = new SearchIndex({
+    repos,
+    embedder,
+    log: (message, error) => console.warn(`[search] ${message}`, error ?? ''),
+  });
+
+  const app = await buildApp({ repos, search, config }, { logger: true });
+
+  const webDist = resolveWebDist();
+  if (webDist) {
+    await app.register(fastifyStatic, { root: webDist });
+    // React Router routes (e.g. /applications, /companies/:id) are only real files at
+    // `/`; anything else that isn't an API call falls back to index.html so client-side
+    // routing can take over.
+    app.setNotFoundHandler((request, reply) => {
+      if (request.method === 'GET' && !request.url.startsWith('/api/')) {
+        return reply.sendFile('index.html');
+      }
+      return reply.status(404).send({ error: 'not_found', message: 'Not found' });
+    });
+  } else {
+    console.warn('[tray] no built web UI found — run "npm run build" to serve it. API-only for now.');
+  }
+
+  await search.start();
+  await app.listen({ host: config.host, port: config.port });
+
+  return { app, config, repos, search };
+}

package/src/settings.ts

@@ -0,0 +1,21 @@
+/**
+ * "Open app settings" — the tray's escape hatch to .env, which is the only place connection
+ * settings and other secrets live (see apps/api/src/config.ts). Seeded from .env.example on
+ * first use so there's always a real file to open, matching `npm install`'s quick-start step.
+ */
+import { copyFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { resolveAppDataDir } from '@jobtrack/api/config';
+import { resolveEnvExample } from './assets.js';
+import { openInEditor } from './os.js';
+
+export function openSettingsFile(): void {
+  const envPath = resolve(resolveAppDataDir(), '.env');
+  const examplePath = resolveEnvExample();
+
+  if (!existsSync(envPath) && examplePath) {
+    copyFileSync(examplePath, envPath);
+  }
+
+  openInEditor(envPath);
+}

package/src/tray.ts

@@ -0,0 +1,88 @@
+/**
+ * The Windows tray icon: open the UI, toggle autostart, open .env, quit. Built on `systray`
+ * (a thin wrapper over a portable Go tray binary), which needs no native compilation — a
+ * plain dependency install is enough, unlike node-gyp-based tray libraries.
+ */
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { resolveWebDist } from './assets.js';
+
+// `systray` is CommonJS and sets an `__esModule: true` flag on its own exports while also
+// assigning `exports.default`. Node's native ESM/CJS interop does not honor that flag the way
+// tsc/webpack do — a plain `import SysTray from 'systray'` resolves to the *whole*
+// `module.exports` object (which itself has a `.default`), one level up from the real class,
+// so `new SysTray(...)` fails with "SysTray is not a constructor". Going through `require`
+// directly sidesteps that ESM-interop ambiguity and gets the real class, as plain CommonJS
+// consumption always would.
+type SysTrayCtor = typeof import('systray').default;
+const SysTray = createRequire(import.meta.url)('systray').default as SysTrayCtor;
+
+const ITEM = { OPEN: 0, AUTOSTART: 1, SETTINGS: 2, QUIT: 3 } as const;
+
+export interface TrayHandlers {
+  autostartEnabled: boolean;
+  onOpen: () => void;
+  onToggleAutostart: (nextEnabled: boolean) => void;
+  onOpenSettings: () => void;
+  onQuit: () => void;
+}
+
+export function createTray(handlers: TrayHandlers): InstanceType<SysTrayCtor> {
+  const webDist = resolveWebDist();
+  if (!webDist) {
+    throw new Error('No built web UI found — run "npm run build" before starting the tray.');
+  }
+  const icon = readFileSync(resolve(webDist, 'favicon.ico')).toString('base64');
+
+  const systray = new SysTray({
+    menu: {
+      icon,
+      title: 'JobTrack',
+      tooltip: 'JobTrack is running',
+      items: [
+        { title: 'Open JobTrack', tooltip: 'Open the web UI', checked: false, enabled: true },
+        {
+          title: 'Autostart with Windows',
+          tooltip: 'Launch JobTrack automatically when you sign in',
+          checked: handlers.autostartEnabled,
+          enabled: true,
+        },
+        { title: 'Open App Settings', tooltip: 'Edit .env', checked: false, enabled: true },
+        { title: 'Quit', tooltip: 'Stop JobTrack', checked: false, enabled: true },
+      ],
+    },
+    debug: false,
+    // Copies the bundled Go tray binary out of node_modules before running it — needed for
+    // packaging tools (and harmless otherwise), per the systray README.
+    copyDir: true,
+  });
+
+  systray.onClick((action) => {
+    switch (action.seq_id) {
+      case ITEM.OPEN:
+        handlers.onOpen();
+        break;
+      case ITEM.AUTOSTART: {
+        const next = !action.item.checked;
+        handlers.onToggleAutostart(next);
+        systray.sendAction({
+          type: 'update-item',
+          item: { ...action.item, checked: next },
+          seq_id: action.seq_id,
+        });
+        break;
+      }
+      case ITEM.SETTINGS:
+        handlers.onOpenSettings();
+        break;
+      case ITEM.QUIT:
+        handlers.onQuit();
+        break;
+      default:
+        break;
+    }
+  });
+
+  return systray;
+}

package/src/types/systray.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal ambient types for the `systray` package (no upstream types or @types package).
+ * Covers only the surface this app actually uses — see the README at
+ * https://github.com/zaaack/node-systray for the full API.
+ */
+declare module 'systray' {
+  export interface MenuItem {
+    title: string;
+    tooltip: string;
+    checked: boolean;
+    enabled: boolean;
+  }
+
+  export interface Menu {
+    icon: string;
+    title: string;
+    tooltip: string;
+    items: MenuItem[];
+  }
+
+  export interface SysTrayConf {
+    menu: Menu;
+    debug?: boolean;
+    copyDir?: boolean;
+  }
+
+  export interface ClickAction {
+    type: 'clicked';
+    item: MenuItem;
+    seq_id: number;
+  }
+
+  export interface UpdateItemAction {
+    type: 'update-item';
+    item: MenuItem;
+    seq_id: number;
+  }
+
+  export default class SysTray {
+    constructor(conf: SysTrayConf);
+    onClick(listener: (action: ClickAction) => void): void;
+    sendAction(action: UpdateItemAction): void;
+    kill(exitNode?: boolean): void;
+  }
+}

package/vendor/.env.example

@@ -0,0 +1,29 @@
+# Copy this file to `.env` and adjust as needed. Every value below is optional — an
+# unmodified `.env` (or no `.env` at all) runs JobTrack on local SQLite at
+# http://127.0.0.1:3001. See README.md "Configuration" for the full write-up.
+
+# sqlite (default), postgres, or mysql — the driver for the implicit "default" target.
+# DB_DRIVER=sqlite
+
+# SQLite only. Path is relative to the repo root.
+# DB_FILE=data/jobtrack.db
+
+# Postgres/MySQL only. Required when DB_DRIVER is postgres or mysql.
+# DATABASE_URL=postgres://user:pass@host/db
+
+# JSON array of additional named DB targets, switchable from the Settings page without
+# editing this file again. See README.md "Switching databases".
+# DB_TARGETS=[{"name":"cloud","driver":"postgres","url":"postgres://user:pass@host/db"}]
+
+# API bind address.
+# HOST=127.0.0.1
+# PORT=3001
+
+# Set to false to skip loading the embedding model entirely and stay lexical-only search.
+# SEMANTIC_SEARCH=true
+
+# Any transformers.js feature-extraction model.
+# EMBEDDING_MODEL=Xenova/all-MiniLM-L6-v2
+
+# Where the ONNX embedding model is cached, relative to the repo root.
+# MODEL_CACHE_DIR=.models