jobtrack 1.0.10 → 1.0.11

package/README.md

@@ -10,13 +10,22 @@ road with the same company. Single user, runs on your machine, data in a local S
 
 ## Install
 
+**On Windows**, prefer the installer:
+[**JobTrack-Setup**](https://github.com/CuplexUser/JobTrack/releases/latest). It needs no admin
+rights and no Node.js, adds a native tray icon and a settings dialog, and starts silently at
+sign-in rather than opening a console window.
+
+Everywhere else — and for development on Windows too:
+
 ```bash
 npm install -g jobtrack
 jobtrack
 ```
 
-Requires **Node.js 24+** already installed on the machine — this runs the app's TypeScript
-sources via `tsx` rather than shipping a compiled, dependency-free binary.
+That route requires **Node.js 24+** already installed on the machine, since it runs the app's
+TypeScript sources via `tsx` rather than shipping a compiled, dependency-free binary. Both routes
+use the same `%APPDATA%\jobtrack` data directory, so they share one database — install only one of
+them at a time, or the two will collide on port 3001.
 
 ## What you get
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jobtrack",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "type": "module",
   "license": "MIT",
   "description": "Runs the JobTrack API + web UI as one background process with a Windows tray icon",
@@ -10,6 +10,9 @@
     "directory": "apps/tray"
   },
   "homepage": "https://github.com/CuplexUser/JobTrack#readme",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "main": "./src/cli.ts",
   "bin": {
     "jobtrack": "./bin/jobtrack.js"

package/src/cli.ts

@@ -4,19 +4,55 @@
  * 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.
+ *
+ * The Windows installer (see `windows/`) is the one other caller: it draws its own native tray
+ * and supervises this process, so it passes `--no-tray` and `--home`, reads the JOBTRACK_READY
+ * line below off stdout, and asks for a clean stop by writing `quit` to stdin. None of that
+ * changes what plain `jobtrack` does.
  */
+import { resolve } from 'node:path';
 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';
 import { APP_VERSION } from './version.js';
 
+const argv = process.argv.slice(2);
+
+function flagValue(name: string): string | undefined {
+  const index = argv.indexOf(name);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+// Before startServer(), and that ordering is the whole point: `resolveAppDataDir()` in
+// apps/api/src/config.ts reads process.env when it's called, and everything under the data
+// directory — the database, the model cache, .env itself — hangs off what it returns.
+//
+// A flag rather than an inherited JOBTRACK_HOME because bin/jobtrack.js documents that handing
+// a reconstructed environment to a Node child breaks tsx's loader; a supervisor that never has
+// to set an environment variable can't trip over that at all.
+const home = flagValue('--home');
+if (home) process.env.JOBTRACK_HOME = resolve(home);
+
+const noTray = argv.includes('--no-tray') || process.env.JOBTRACK_NO_TRAY === '1';
+
 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 v${APP_VERSION} running at ${url} (driver: ${config.driver})`);
 
+// The same facts again, in one parseable line, so a supervisor knows the server is up and on
+// which address without scraping prose or guessing at a port it may have only set in .env.
+console.log(
+  `JOBTRACK_READY ${JSON.stringify({
+    url,
+    host: config.host,
+    port: config.port,
+    version: APP_VERSION,
+    driver: config.driver,
+  })}`,
+);
+
 let shuttingDown = false;
 async function shutdown(): Promise<void> {
   if (shuttingDown) return;
@@ -31,7 +67,36 @@ for (const signal of ['SIGINT', 'SIGTERM'] as const) {
   process.once(signal, () => void shutdown());
 }
 
-if (process.platform === 'win32') {
+/**
+ * Line-oriented commands from a supervising process. Windows has no dependable way to send a
+ * running process anything like SIGTERM from outside, so stdin is how the installer's host asks
+ * for the orderly shutdown above — closing SQLite properly — before it resorts to killing the
+ * job object.
+ */
+function listenForSupervisorCommands(): void {
+  process.stdin.setEncoding('utf8');
+  let buffered = '';
+  process.stdin.on('data', (chunk: string) => {
+    buffered += chunk;
+    let newline: number;
+    while ((newline = buffered.indexOf('\n')) !== -1) {
+      const line = buffered.slice(0, newline).trim();
+      buffered = buffered.slice(newline + 1);
+      if (line === 'quit') void shutdown();
+    }
+  });
+  // The supervisor is gone; there is nobody left to serve.
+  process.stdin.on('end', () => void shutdown());
+}
+
+if (noTray) {
+  listenForSupervisorCommands();
+} else if (process.platform === 'win32') {
+  // Imported here rather than at the top so that `systray` — 35 MB of Go tray binaries for
+  // three platforms — is only ever loaded when a tray is actually going to be drawn. That is
+  // what lets the Windows installer's payload delete the package outright: its native host
+  // draws the tray itself and always passes --no-tray.
+  const { createTray } = await import('./tray.js');
   const tray = createTray({
     autostartEnabled: isAutostartEnabled(),
     onOpen: () => openUrl(url),

package/src/server.ts

@@ -17,6 +17,12 @@ import { TransformersEmbedder } from '@jobtrack/api/search/transformers-embedder
 import { resolveWebDist } from './assets.js';
 import { APP_PACKAGE } from './version.js';
 
+/**
+ * Exit code for "the port is taken". Distinct from a generic crash so a supervisor can tell a
+ * misconfiguration it should surface to the user from a fault it should just retry.
+ */
+export const EXIT_PORT_IN_USE = 3;
+
 export interface RunningServer {
   app: FastifyInstance;
   config: Config;
@@ -68,7 +74,25 @@ export async function startServer(): Promise<RunningServer> {
   }
 
   await search.start();
-  await app.listen({ host: config.host, port: config.port });
+
+  try {
+    await app.listen({ host: config.host, port: config.port });
+  } catch (error) {
+    // Overwhelmingly this is a second JobTrack — autostart plus a manual launch. Left alone it
+    // surfaces as an unhandled rejection and a stack trace; a supervisor (and a person) can do
+    // something useful with a named cause and a distinct exit code.
+    if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') throw error;
+    console.error(
+      `JOBTRACK_ERROR ${JSON.stringify({ code: 'EADDRINUSE', host: config.host, port: config.port })}`,
+    );
+    console.error(
+      `Port ${config.port} is already in use — JobTrack may already be running. Stop it, or set PORT in .env to something else.`,
+    );
+    search.stop();
+    await app.close();
+    await repos.close();
+    process.exit(EXIT_PORT_IN_USE);
+  }
 
   return { app, config, repos, search };
 }