codebase-onboarder 0.5.0 → 0.7.0

package/server/searchIndex.js

@@ -17,52 +17,44 @@
 // directory, re-reading every file, parsing its tokens — is gone. The
 // per-request cost is one Map lookup plus the scoring pass over matching
 // documents, which is bounded by the index size, not the repo size.
-
 const DEFAULTS = {
-  // Aggregate content size. Files beyond this are not indexed, only counted.
-  // 200 MB is enough to index the source of a large monorepo comfortably;
-  // past that the search would be matching against vendor copies and
-  // generated code more often than against code people wrote.
-  maxTotalBytes: 200 * 1024 * 1024,
-  // Per-file ceiling. Files larger than this are skipped (the scanner has
-  // its own ceiling for the same reason).
-  maxFileBytes: 1024 * 1024,
-  // Reads in flight at once. Same shape as `scan.js`'s read-ahead — a file
-  // is held in memory whole before the next one starts.
-  width: 8,
+    // Aggregate content size. Files beyond this are not indexed, only counted.
+    // 200 MB is enough to index the source of a large monorepo comfortably;
+    // past that the search would be matching against vendor copies and
+    // generated code more often than against code people wrote.
+    maxTotalBytes: 200 * 1024 * 1024,
+    // Per-file ceiling. Files larger than this are skipped (the scanner has
+    // its own ceiling for the same reason).
+    maxFileBytes: 1024 * 1024,
+    // Reads in flight at once. Same shape as `scan.js`'s read-ahead — a file
+    // is held in memory whole before the next one starts.
+    width: 8,
 };
-
 const BINARY_HEAD_BYTES = 1000;
-
 function looksBinary(content) {
-  // NUL in the first KB is a reliable, cheap heuristic for "this is not
-  // text the search would help with". The first KB also covers the BOM and
-  // the shebang without missing the start of the file.
-  return content.slice(0, BINARY_HEAD_BYTES).includes('\0');
+    // NUL in the first KB is a reliable, cheap heuristic for "this is not
+    // text the search would help with". The first KB also covers the BOM and
+    // the shebang without missing the start of the file.
+    return content.slice(0, BINARY_HEAD_BYTES).includes('\0');
 }
-
 // Read each path's text up to width at a time. Failures are skipped, the
 // same way `scan.js:readAhead` handles them: one unreadable file should not
 // end an index build, and the caller counts it in `skipped.readFailed`.
 async function* readAhead(source, paths, width) {
-  const inFlight = [];
-  let next = 0;
-  const read = (p) =>
-    Promise.resolve()
-      .then(() => source.read(p))
-      .then(
-        (text) => ({ path: p, text, failed: false }),
-        () => ({ path: p, text: '', failed: true }),
-      );
-
-  while (next < paths.length && inFlight.length < width) inFlight.push(read(paths[next++]));
-  while (inFlight.length) {
-    const settled = inFlight.shift();
-    if (next < paths.length) inFlight.push(read(paths[next++]));
-    yield await settled;
-  }
+    const inFlight = [];
+    let next = 0;
+    const read = (p) => Promise.resolve()
+        .then(() => source.read(p))
+        .then((text) => ({ path: p, text, failed: false }), () => ({ path: p, text: '', failed: true }));
+    while (next < paths.length && inFlight.length < width)
+        inFlight.push(read(paths[next++]));
+    while (inFlight.length) {
+        const settled = inFlight.shift();
+        if (next < paths.length)
+            inFlight.push(read(paths[next++]));
+        yield await settled;
+    }
 }
-
 // Build the search index from the file list the scanner already produced.
 // The scanner has read these files once for parsing; indexing reads them a
 // second time for tokenizing, which is the cheapest place to do it — a
@@ -71,48 +63,59 @@ async function* readAhead(source, paths, width) {
 // smallest change that closes the audit's three real concerns (first-search
 // latency, no aggregate cap, no concurrency).
 export async function buildSearchIndex(source, codeFiles, options = {}) {
-  const opts = { ...DEFAULTS, ...options };
-  const index = new Map();
-  const docCounts = new Map();
-  let totalDocs = 0;
-  let totalBytes = 0;
-
-  // Files the indexer cannot or will not index, broken down by reason. The
-  // shape matches `scan.js:skips` so a future UI surface can render one
-  // unified "what was left out" panel without translation.
-  const skipped = {
-    tooLarge: 0,    // one file over maxFileBytes
-    overCap: 0,     // a later file pushed the aggregate over maxTotalBytes
-    readFailed: 0,  // the file would not read
-    binary: 0,      // NUL in the first KB
-    noTokens: 0,    // the file read, but tokenizing produced nothing useful
-  };
-
-  for await (const { path, text, failed } of readAhead(source, codeFiles, opts.width)) {
-    if (failed) { skipped.readFailed++; continue; }
-
-    if (text.length > opts.maxFileBytes) { skipped.tooLarge++; continue; }
-    if (totalBytes + text.length > opts.maxTotalBytes) { skipped.overCap++; continue; }
-    if (looksBinary(text)) { skipped.binary++; continue; }
-
-    const tokens = text.toLowerCase().split(/\W+/).filter((t) => t.length > 1);
-    if (!tokens.length) { skipped.noTokens++; continue; }
-
-    const tf = new Map();
-    for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);
-    for (const t of tf.keys()) docCounts.set(t, (docCounts.get(t) || 0) + 1);
-
-    index.set(path, { tf, content: text, tokenCount: tokens.length });
-    totalDocs++;
-    totalBytes += text.length;
-  }
-
-  return {
-    index,
-    docCounts,
-    totalDocs,
-    totalBytes,
-    skipped,
-    cap: { maxFileBytes: opts.maxFileBytes, maxTotalBytes: opts.maxTotalBytes },
-  };
+    const opts = { ...DEFAULTS, ...options };
+    const index = new Map();
+    const docCounts = new Map();
+    let totalDocs = 0;
+    let totalBytes = 0;
+    // Files the indexer cannot or will not index, broken down by reason. The
+    // shape matches `scan.js:skips` so a future UI surface can render one
+    // unified "what was left out" panel without translation.
+    const skipped = {
+        tooLarge: 0, // one file over maxFileBytes
+        overCap: 0, // a later file pushed the aggregate over maxTotalBytes
+        readFailed: 0, // the file would not read
+        binary: 0, // NUL in the first KB
+        noTokens: 0, // the file read, but tokenizing produced nothing useful
+    };
+    for await (const { path, text, failed } of readAhead(source, codeFiles, opts.width)) {
+        if (failed) {
+            skipped.readFailed++;
+            continue;
+        }
+        if (text.length > opts.maxFileBytes) {
+            skipped.tooLarge++;
+            continue;
+        }
+        if (totalBytes + text.length > opts.maxTotalBytes) {
+            skipped.overCap++;
+            continue;
+        }
+        if (looksBinary(text)) {
+            skipped.binary++;
+            continue;
+        }
+        const tokens = text.toLowerCase().split(/\W+/).filter((t) => t.length > 1);
+        if (!tokens.length) {
+            skipped.noTokens++;
+            continue;
+        }
+        const tf = new Map();
+        for (const t of tokens)
+            tf.set(t, (tf.get(t) || 0) + 1);
+        for (const t of tf.keys())
+            docCounts.set(t, (docCounts.get(t) || 0) + 1);
+        index.set(path, { tf, content: text, tokenCount: tokens.length });
+        totalDocs++;
+        totalBytes += text.length;
+    }
+    return {
+        index,
+        docCounts,
+        totalDocs,
+        totalBytes,
+        skipped,
+        cap: { maxFileBytes: opts.maxFileBytes, maxTotalBytes: opts.maxTotalBytes },
+    };
 }
+//# sourceMappingURL=searchIndex.js.map

package/server/searchIndex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchIndex.js","sourceRoot":"","sources":["../src/server/searchIndex.ts"],"names":[],"mappings":"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","sourcesContent":["// The search index lives with the scan, not behind a request. Building it\n// here means:\n//\n//   * The first /api/search call is fast. The user is searching — make it feel\n//     that way; the work that would have been a request-blocking second walk\n//     is already done.\n//   * The index reads exactly the files the scanner did. The caller hands us\n//     `scan.files`, the list of paths the scanner accepted; we never walk\n//     the tree ourselves, so the index can never disagree with the scan\n//     about which files exist.\n//   * The index has a hard cap. A repo with a single 200 MB SQL dump used to\n//     hold its full content in the process for the lifetime of the session;\n//     now it stops indexing at the cap and records what it skipped, so a\n//     future \"why doesn't my file show up?\" question has a real answer.\n//\n// The on-disk cost of the work the old /api/search did — re-listing every\n// directory, re-reading every file, parsing its tokens — is gone. The\n// per-request cost is one Map lookup plus the scoring pass over matching\n// documents, which is bounded by the index size, not the repo size.\n\nconst DEFAULTS = {\n  // Aggregate content size. Files beyond this are not indexed, only counted.\n  // 200 MB is enough to index the source of a large monorepo comfortably;\n  // past that the search would be matching against vendor copies and\n  // generated code more often than against code people wrote.\n  maxTotalBytes: 200 * 1024 * 1024,\n  // Per-file ceiling. Files larger than this are skipped (the scanner has\n  // its own ceiling for the same reason).\n  maxFileBytes: 1024 * 1024,\n  // Reads in flight at once. Same shape as `scan.js`'s read-ahead — a file\n  // is held in memory whole before the next one starts.\n  width: 8,\n};\n\nconst BINARY_HEAD_BYTES = 1000;\n\nfunction looksBinary(content) {\n  // NUL in the first KB is a reliable, cheap heuristic for \"this is not\n  // text the search would help with\". The first KB also covers the BOM and\n  // the shebang without missing the start of the file.\n  return content.slice(0, BINARY_HEAD_BYTES).includes('\\0');\n}\n\n// Read each path's text up to width at a time. Failures are skipped, the\n// same way `scan.js:readAhead` handles them: one unreadable file should not\n// end an index build, and the caller counts it in `skipped.readFailed`.\nasync function* readAhead(source, paths, width) {\n  const inFlight = [];\n  let next = 0;\n  const read = (p) =>\n    Promise.resolve()\n      .then(() => source.read(p))\n      .then(\n        (text) => ({ path: p, text, failed: false }),\n        () => ({ path: p, text: '', failed: true }),\n      );\n\n  while (next < paths.length && inFlight.length < width) inFlight.push(read(paths[next++]));\n  while (inFlight.length) {\n    const settled = inFlight.shift();\n    if (next < paths.length) inFlight.push(read(paths[next++]));\n    yield await settled;\n  }\n}\n\n// Build the search index from the file list the scanner already produced.\n// The scanner has read these files once for parsing; indexing reads them a\n// second time for tokenizing, which is the cheapest place to do it — a\n// refactor that streamed text from the scanner into both consumers would\n// save one disk pass at the cost of a much larger refactor. This is the\n// smallest change that closes the audit's three real concerns (first-search\n// latency, no aggregate cap, no concurrency).\nexport async function buildSearchIndex(source, codeFiles, options: Record<string, any> = {}) {\n  const opts = { ...DEFAULTS, ...options };\n  const index = new Map();\n  const docCounts = new Map();\n  let totalDocs = 0;\n  let totalBytes = 0;\n\n  // Files the indexer cannot or will not index, broken down by reason. The\n  // shape matches `scan.js:skips` so a future UI surface can render one\n  // unified \"what was left out\" panel without translation.\n  const skipped = {\n    tooLarge: 0,    // one file over maxFileBytes\n    overCap: 0,     // a later file pushed the aggregate over maxTotalBytes\n    readFailed: 0,  // the file would not read\n    binary: 0,      // NUL in the first KB\n    noTokens: 0,    // the file read, but tokenizing produced nothing useful\n  };\n\n  for await (const { path, text, failed } of readAhead(source, codeFiles, opts.width)) {\n    if (failed) { skipped.readFailed++; continue; }\n\n    if (text.length > opts.maxFileBytes) { skipped.tooLarge++; continue; }\n    if (totalBytes + text.length > opts.maxTotalBytes) { skipped.overCap++; continue; }\n    if (looksBinary(text)) { skipped.binary++; continue; }\n\n    const tokens = text.toLowerCase().split(/\\W+/).filter((t) => t.length > 1);\n    if (!tokens.length) { skipped.noTokens++; continue; }\n\n    const tf = new Map();\n    for (const t of tokens) tf.set(t, (tf.get(t) || 0) + 1);\n    for (const t of tf.keys()) docCounts.set(t, (docCounts.get(t) || 0) + 1);\n\n    index.set(path, { tf, content: text, tokenCount: tokens.length });\n    totalDocs++;\n    totalBytes += text.length;\n  }\n\n  return {\n    index,\n    docCounts,\n    totalDocs,\n    totalBytes,\n    skipped,\n    cap: { maxFileBytes: opts.maxFileBytes, maxTotalBytes: opts.maxTotalBytes },\n  };\n}\n"]}

package/server/sessions.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_SESSIONS = 12;
+export declare function openSession({ root, cloneDir, searchIndex }: {
+    cloneDir?: any;
+    root: any;
+    searchIndex?: any;
+}): string;
+export declare function getSession(scanId: any): any;
+export declare function isCloneId(id: any): boolean;
+export declare function closeClone(cloneId: any): Promise<boolean>;
+export declare function removalsSettled(): Promise<void>;
+export declare function sweepClonesSync(): void;
+export declare function installExitCleanup(proc?: NodeJS.Process): void;
+export declare function _resetSessions(): void;
+export declare function _sessionCount(): number;

package/server/sessions.js

@@ -17,18 +17,14 @@
 //   * It leaked clones on exit. A clone lives in the OS temp dir until someone
 //     removes it, and only an explicit `DELETE /api/scan/:id` did. Ctrl-C left
 //     every clone of the session behind — hundreds of megabytes, silently.
-
 import crypto from 'node:crypto';
 import path from 'node:path';
 import { realpathSync } from 'node:fs';
-
 import { isCloneDir, removeClone, removeCloneSync } from './gitClone.js';
-
 // Twelve repos is far more than anyone holds open at once, and each entry is a
 // couple of strings — the cap is about not serving from a root the person has
 // forgotten scanning, not about memory.
 export const MAX_SESSIONS = 12;
-
 // scanId -> { root, cloneDir, at, searchIndex? }. Insertion-ordered, which is
 // what makes "oldest first" a `keys().next()` rather than a sort.
 //
@@ -39,14 +35,12 @@ export const MAX_SESSIONS = 12;
 // the same repo would rebuild it; the cost of one scan's worth of work is
 // far below the cost of re-fetching the repo.
 const sessions = new Map();
-
 export function openSession({ root, cloneDir = null, searchIndex = null }) {
-  const scanId = crypto.randomBytes(8).toString('hex');
-  sessions.set(scanId, { root: canonicalRoot(root), cloneDir, at: Date.now(), searchIndex });
-  evictBeyondCap();
-  return scanId;
+    const scanId = crypto.randomBytes(8).toString('hex');
+    sessions.set(scanId, { root: canonicalRoot(root), cloneDir, at: Date.now(), searchIndex });
+    evictBeyondCap();
+    return scanId;
 }
-
 // Resolve symlinks once, so the root every consumer sees is the real one. On
 // macOS `/tmp` is a symlink to `/private/tmp`, and an analyzer run against the
 // alias reports paths rooted at the target — without this, `/api/tools/run`
@@ -54,110 +48,108 @@ export function openSession({ root, cloneDir = null, searchIndex = null }) {
 // scanned through a symlinked path. Failing to resolve (a path that is gone)
 // is not fatal: the original is used and the scan's own error path reports it.
 function canonicalRoot(root) {
-  if (typeof root !== 'string' || !root) return root;
-  try {
-    return realpathSync(root);
-  } catch {
-    return root;
-  }
+    if (typeof root !== 'string' || !root)
+        return root;
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return root;
+    }
 }
-
 // Reading from a scan keeps it alive. Without the touch, opening files in the
 // first repo you scanned is what evicts it — you would lose the one you are
 // actually using and keep eleven you are not.
 export function getSession(scanId) {
-  if (!scanId) return null;
-  const session = sessions.get(scanId);
-  if (!session) return null;
-  session.at = Date.now();
-  sessions.delete(scanId);
-  sessions.set(scanId, session);
-  return session;
+    if (!scanId)
+        return null;
+    const session = sessions.get(scanId);
+    if (!session)
+        return null;
+    session.at = Date.now();
+    sessions.delete(scanId);
+    sessions.set(scanId, session);
+    return session;
 }
-
 // Clone ids are the 12 hex characters `gitClone` puts after `onboarder-`. The
 // match is on the exact directory name: `endsWith(cloneId)` treated an empty id
 // as a match against every clone, so `DELETE /api/scan/` used to delete
 // whichever clone the map happened to yield first.
 export function isCloneId(id) {
-  return /^[0-9a-f]{12}$/.test(id || '');
+    return /^[0-9a-f]{12}$/.test(id || '');
 }
-
 // Removes the clone with this id and forgets every scan pointing at it. Returns
 // whether anything was there — a repeat DELETE is not an error; the page sends
 // one on unload and may well be the second to arrive.
 export async function closeClone(cloneId) {
-  const dirName = 'onboarder-' + cloneId;
-  let found = null;
-  for (const [scanId, session] of sessions) {
-    if (session.cloneDir && path.basename(session.cloneDir) === dirName) {
-      found = session.cloneDir;
-      sessions.delete(scanId);
+    const dirName = 'onboarder-' + cloneId;
+    let found = null;
+    for (const [scanId, session] of sessions) {
+        if (session.cloneDir && path.basename(session.cloneDir) === dirName) {
+            found = session.cloneDir;
+            sessions.delete(scanId);
+        }
     }
-  }
-  if (found) await removeClone(found);
-  return Boolean(found);
+    if (found)
+        await removeClone(found);
+    return Boolean(found);
 }
-
 function evictBeyondCap() {
-  while (sessions.size > MAX_SESSIONS) {
-    const [scanId, session] = sessions.entries().next().value;
-    sessions.delete(scanId);
-    if (session.cloneDir && !stillReferenced(session.cloneDir)) sweep(session.cloneDir);
-  }
+    while (sessions.size > MAX_SESSIONS) {
+        const [scanId, session] = sessions.entries().next().value;
+        sessions.delete(scanId);
+        if (session.cloneDir && !stillReferenced(session.cloneDir))
+            sweep(session.cloneDir);
+    }
 }
-
 // Eviction happens inside a scan request, and the person is waiting on the scan,
 // not on a directory being swept — so the removal is started and not awaited. The
 // promises are chained rather than dropped so that a caller who does need to know
 // when the disk is quiet can wait for it; the only one that does is a test.
 let removals = Promise.resolve();
-
 function sweep(dir) {
-  removals = removals.then(() => removeClone(dir));
+    removals = removals.then(() => removeClone(dir));
 }
-
 export function removalsSettled() {
-  return removals;
+    return removals;
 }
-
 // Two sessions can name the same clone — scan a git URL, then scan the temp path
 // it landed in. Do not delete a directory another live session still reads from.
 function stillReferenced(dir) {
-  for (const session of sessions.values()) if (session.cloneDir === dir) return true;
-  return false;
+    for (const session of sessions.values())
+        if (session.cloneDir === dir)
+            return true;
+    return false;
 }
-
 // Synchronous on purpose: this is what an exit handler can finish.
 export function sweepClonesSync() {
-  for (const [scanId, session] of sessions) {
-    sessions.delete(scanId);
-    if (isCloneDir(session.cloneDir)) removeCloneSync(session.cloneDir);
-  }
+    for (const [scanId, session] of sessions) {
+        sessions.delete(scanId);
+        if (isCloneDir(session.cloneDir))
+            removeCloneSync(session.cloneDir);
+    }
 }
-
 // Called from the `node server/index.js` path only, never on import. The tests
 // drive the real router in-process, and a module that added signal handlers just
 // by being imported would take Ctrl-C away from the test runner.
 export function installExitCleanup(proc = process) {
-  proc.on('exit', sweepClonesSync);
-  // A signal does not run `exit` handlers on its own — the process dies where it
-  // stands. Sweeping in the signal handler and then exiting is what gets the
-  // clones removed.
-  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
-    proc.on(signal, () => {
-      sweepClonesSync();
-      proc.exit(0);
-    });
-  }
+    proc.on('exit', sweepClonesSync);
+    // A signal does not run `exit` handlers on its own — the process dies where it
+    // stands. Sweeping in the signal handler and then exiting is what gets the
+    // clones removed.
+    for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {
+        proc.on(signal, () => {
+            sweepClonesSync();
+            proc.exit(0);
+        });
+    }
 }
-
 // Tests only. The store is module state, so a test that opens sessions would
 // otherwise leak them into the next one.
 export function _resetSessions() {
-  sessions.clear();
+    sessions.clear();
 }
-
 export function _sessionCount() {
-  return sessions.size;
+    return sessions.size;
 }
+//# sourceMappingURL=sessions.js.map

package/server/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../src/server/sessions.ts"],"names":[],"mappings":"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","sourcesContent":["// What the server remembers between requests: which directory each scan came\n// from. `/api/file` needs it — the browser asks for `server/paths.js` and the\n// server has to know which root that is relative to — and the git-URL flow needs\n// it to find a clone again when the page says it is done with one.\n//\n// A scan id is the capability. Handing the browser a path and trusting it back\n// would make `/api/file` a \"read any file on this machine\" endpoint; handing it\n// an opaque id means the only readable roots are ones the person chose to scan\n// during this run.\n//\n// Two things the inline Map this replaces got wrong:\n//\n//   * It never forgot. Every scan added an entry and nothing removed one, so an\n//     afternoon of scanning left a growing list of roots still being served\n//     from. A cap with oldest-out eviction bounds it, and evicting a cloned repo\n//     deletes the clone with it.\n//   * It leaked clones on exit. A clone lives in the OS temp dir until someone\n//     removes it, and only an explicit `DELETE /api/scan/:id` did. Ctrl-C left\n//     every clone of the session behind — hundreds of megabytes, silently.\n\nimport crypto from 'node:crypto';\nimport path from 'node:path';\nimport { realpathSync } from 'node:fs';\n\nimport { isCloneDir, removeClone, removeCloneSync } from './gitClone.js';\n\n// Twelve repos is far more than anyone holds open at once, and each entry is a\n// couple of strings — the cap is about not serving from a root the person has\n// forgotten scanning, not about memory.\nexport const MAX_SESSIONS = 12;\n\n// scanId -> { root, cloneDir, at, searchIndex? }. Insertion-ordered, which is\n// what makes \"oldest first\" a `keys().next()` rather than a sort.\n//\n// `searchIndex`, when present, is the TF-IDF index built at scan time\n// (`searchIndex.js`). It is held on the session for the same reason `root`\n// is — `/api/search` is a request that has to be answered against this\n// particular scan — and is dropped when the session is evicted. Reopening\n// the same repo would rebuild it; the cost of one scan's worth of work is\n// far below the cost of re-fetching the repo.\nconst sessions = new Map();\n\nexport function openSession({ root, cloneDir = null, searchIndex = null }) {\n  const scanId = crypto.randomBytes(8).toString('hex');\n  sessions.set(scanId, { root: canonicalRoot(root), cloneDir, at: Date.now(), searchIndex });\n  evictBeyondCap();\n  return scanId;\n}\n\n// Resolve symlinks once, so the root every consumer sees is the real one. On\n// macOS `/tmp` is a symlink to `/private/tmp`, and an analyzer run against the\n// alias reports paths rooted at the target — without this, `/api/tools/run`\n// findings and `/api/file` lookups would silently miss every file in a repo\n// scanned through a symlinked path. Failing to resolve (a path that is gone)\n// is not fatal: the original is used and the scan's own error path reports it.\nfunction canonicalRoot(root) {\n  if (typeof root !== 'string' || !root) return root;\n  try {\n    return realpathSync(root);\n  } catch {\n    return root;\n  }\n}\n\n// Reading from a scan keeps it alive. Without the touch, opening files in the\n// first repo you scanned is what evicts it — you would lose the one you are\n// actually using and keep eleven you are not.\nexport function getSession(scanId) {\n  if (!scanId) return null;\n  const session = sessions.get(scanId);\n  if (!session) return null;\n  session.at = Date.now();\n  sessions.delete(scanId);\n  sessions.set(scanId, session);\n  return session;\n}\n\n// Clone ids are the 12 hex characters `gitClone` puts after `onboarder-`. The\n// match is on the exact directory name: `endsWith(cloneId)` treated an empty id\n// as a match against every clone, so `DELETE /api/scan/` used to delete\n// whichever clone the map happened to yield first.\nexport function isCloneId(id) {\n  return /^[0-9a-f]{12}$/.test(id || '');\n}\n\n// Removes the clone with this id and forgets every scan pointing at it. Returns\n// whether anything was there — a repeat DELETE is not an error; the page sends\n// one on unload and may well be the second to arrive.\nexport async function closeClone(cloneId) {\n  const dirName = 'onboarder-' + cloneId;\n  let found = null;\n  for (const [scanId, session] of sessions) {\n    if (session.cloneDir && path.basename(session.cloneDir) === dirName) {\n      found = session.cloneDir;\n      sessions.delete(scanId);\n    }\n  }\n  if (found) await removeClone(found);\n  return Boolean(found);\n}\n\nfunction evictBeyondCap() {\n  while (sessions.size > MAX_SESSIONS) {\n    const [scanId, session] = sessions.entries().next().value;\n    sessions.delete(scanId);\n    if (session.cloneDir && !stillReferenced(session.cloneDir)) sweep(session.cloneDir);\n  }\n}\n\n// Eviction happens inside a scan request, and the person is waiting on the scan,\n// not on a directory being swept — so the removal is started and not awaited. The\n// promises are chained rather than dropped so that a caller who does need to know\n// when the disk is quiet can wait for it; the only one that does is a test.\nlet removals = Promise.resolve();\n\nfunction sweep(dir) {\n  removals = removals.then(() => removeClone(dir));\n}\n\nexport function removalsSettled() {\n  return removals;\n}\n\n// Two sessions can name the same clone — scan a git URL, then scan the temp path\n// it landed in. Do not delete a directory another live session still reads from.\nfunction stillReferenced(dir) {\n  for (const session of sessions.values()) if (session.cloneDir === dir) return true;\n  return false;\n}\n\n// Synchronous on purpose: this is what an exit handler can finish.\nexport function sweepClonesSync() {\n  for (const [scanId, session] of sessions) {\n    sessions.delete(scanId);\n    if (isCloneDir(session.cloneDir)) removeCloneSync(session.cloneDir);\n  }\n}\n\n// Called from the `node server/index.js` path only, never on import. The tests\n// drive the real router in-process, and a module that added signal handlers just\n// by being imported would take Ctrl-C away from the test runner.\nexport function installExitCleanup(proc = process) {\n  proc.on('exit', sweepClonesSync);\n  // A signal does not run `exit` handlers on its own — the process dies where it\n  // stands. Sweeping in the signal handler and then exiting is what gets the\n  // clones removed.\n  for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) {\n    proc.on(signal, () => {\n      sweepClonesSync();\n      proc.exit(0);\n    });\n  }\n}\n\n// Tests only. The store is module state, so a test that opens sessions would\n// otherwise leak them into the next one.\nexport function _resetSessions() {\n  sessions.clear();\n}\n\nexport function _sessionCount() {\n  return sessions.size;\n}\n"]}

package/server/startup.d.ts

@@ -0,0 +1,118 @@
+export declare const LABEL = "com.onboarder.server";
+export declare const UNIT = "onboarder.service";
+export declare function cliEntry(): string;
+export declare function startupCommand(configFile?: string, { node, entry }?: Record<string, any>): any[];
+export declare function renderLaunchAgent({ configFile, log, ...options }?: Record<string, any>): string;
+export declare function renderSystemdUnit({ configFile, log, ...options }?: Record<string, any>): string;
+export declare function renderWindowsStartup({ configFile, log, ...options }?: Record<string, any>): string;
+export declare function startupTarget({ platform, home, env }?: Record<string, any>): {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderLaunchAgent;
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+    daemonReload?: undefined;
+} | {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderSystemdUnit;
+    daemonReload: string[];
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+};
+export declare function startupInstalled(target?: {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderLaunchAgent;
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+    daemonReload?: undefined;
+} | {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderSystemdUnit;
+    daemonReload: string[];
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+}): Promise<boolean>;
+export declare function startupStatus(target?: {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderLaunchAgent;
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+    daemonReload?: undefined;
+} | {
+    kind: string;
+    platform: any;
+    label: string;
+    path: string;
+    render: typeof renderSystemdUnit;
+    daemonReload: string[];
+    load: string[];
+    unload: string[];
+    status: string[];
+    hint: string;
+}, { run }?: Record<string, any>): Promise<{
+    kind: string;
+    supported: boolean;
+    label: string;
+    path: string;
+    installed: boolean;
+    active: any;
+    detail: string;
+    hint: string;
+}>;
+export declare function installStartup({ configFile, log, target, run }?: Record<string, any>): Promise<{
+    path?: undefined;
+    ok: boolean;
+    reason: string;
+    loaded?: undefined;
+    output?: undefined;
+    error?: undefined;
+} | {
+    reason?: undefined;
+    ok: boolean;
+    path: any;
+    loaded: boolean;
+    output: string;
+    error?: undefined;
+} | {
+    reason?: undefined;
+    loaded?: undefined;
+    ok: boolean;
+    path: any;
+    output: any;
+    error: any;
+}>;
+export declare function removeStartup({ target, run }?: Record<string, any>): Promise<{
+    path?: undefined;
+    output?: undefined;
+    ok: boolean;
+    reason: string;
+} | {
+    reason?: undefined;
+    ok: boolean;
+    path: any;
+    output: string;
+}>;