codebase-onboarder 0.5.0 → 0.7.0

package/server/gitHistory.js

@@ -5,106 +5,106 @@
 // downloaded tarball has no .git, and a plain folder may simply not be a
 // checkout. All of those come back as { available: false, reason } so the UI
 // can say why instead of showing zeros.
-
 import { spawn } from 'node:child_process';
-
 // How far back the window goes. Two thousand commits is years of work on most
 // repos and keeps the log parse bounded; `totalCommits` travels alongside so
 // truncation is stated, not silent.
 const LOG_CAP = 2000;
 const TIMEOUT_MS = 30_000;
-
 // Record separator \x1e between commits, unit separator \x1f between fields.
 // Filenames are one per line after the header. A filename containing \x1e or
 // \x1f is legal on paper and does not happen in practice — the same trade every
 // machine-readable git format makes (documented limitation, like .gitignore
 // negation in scan.js).
 const LOG_FORMAT = '%x1e%H%x1f%an%x1f%ae%x1f%aI';
-
 export async function gitLog(root) {
-  let countText;
-  try {
-    countText = await run(['-C', root, 'rev-list', '--count', 'HEAD']);
-  } catch (err) {
-    return { ok: false, reason: explain(err) };
-  }
-  const totalCommits = parseInt(countText.trim(), 10) || 0;
-  if (!totalCommits) {
-    return { ok: false, reason: 'The repository exists but has no commits yet.' };
-  }
-
-  let text;
-  try {
-    text = await run([
-      '-C', root, 'log',
-      '--max-count=' + LOG_CAP,
-      '--pretty=format:' + LOG_FORMAT,
-      '--name-only',
-      '--no-renames',
-      'HEAD',
-    ]);
-  } catch (err) {
-    return { ok: false, reason: explain(err) };
-  }
-
-  return { ok: true, text, totalCommits };
+    let countText;
+    try {
+        countText = await run(['-C', root, 'rev-list', '--count', 'HEAD']);
+    }
+    catch (err) {
+        return { ok: false, reason: explain(err) };
+    }
+    const totalCommits = parseInt(countText.trim(), 10) || 0;
+    if (!totalCommits) {
+        return { ok: false, reason: 'The repository exists but has no commits yet.' };
+    }
+    let text;
+    try {
+        text = await run([
+            '-C', root, 'log',
+            '--max-count=' + LOG_CAP,
+            '--pretty=format:' + LOG_FORMAT,
+            '--name-only',
+            '--no-renames',
+            'HEAD',
+        ]);
+    }
+    catch (err) {
+        return { ok: false, reason: explain(err) };
+    }
+    return { ok: true, text, totalCommits };
 }
-
 // Pure, so the format contract is testable without a git binary.
 export function parseGitLog(text) {
-  const commits = [];
-  for (const record of String(text).split('\x1e')) {
-    if (!record.trim()) continue;
-    const lines = record.split('\n');
-    const [hash, name, email, date] = lines[0].split('\x1f');
-    if (!hash) continue;
-    const files = [];
-    for (let i = 1; i < lines.length; i++) {
-      const f = lines[i].trim();
-      if (f) files.push(f);
+    const commits = [];
+    for (const record of String(text).split('\x1e')) {
+        if (!record.trim())
+            continue;
+        const lines = record.split('\n');
+        const [hash, name, email, date] = lines[0].split('\x1f');
+        if (!hash)
+            continue;
+        const files = [];
+        for (let i = 1; i < lines.length; i++) {
+            const f = lines[i].trim();
+            if (f)
+                files.push(f);
+        }
+        commits.push({ hash, author: { name: name || '', email: email || '' }, date: date || '', files });
     }
-    commits.push({ hash, author: { name: name || '', email: email || '' }, date: date || '', files });
-  }
-  return commits;
+    return commits;
 }
-
 function explain(err) {
-  const message = err.message || '';
-  if (err.code === 'ENOENT' || /spawn git ENOENT/.test(message)) {
-    return 'git is not installed or not on PATH, so there is no history to read.';
-  }
-  if (/not a git repository/i.test(message)) {
-    return 'No .git here — this folder is not a checkout, so there is no history to read.';
-  }
-  if (/does not have any commits yet/i.test(message)) {
-    return 'The repository exists but has no commits yet.';
-  }
-  return 'git would not say: ' + message.split('\n').pop();
+    const message = err.message || '';
+    if (err.code === 'ENOENT' || /spawn git ENOENT/.test(message)) {
+        return 'git is not installed or not on PATH, so there is no history to read.';
+    }
+    if (/not a git repository/i.test(message)) {
+        return 'No .git here — this folder is not a checkout, so there is no history to read.';
+    }
+    if (/does not have any commits yet/i.test(message)) {
+        return 'The repository exists but has no commits yet.';
+    }
+    return 'git would not say: ' + message.split('\n').pop();
 }
-
 function run(args) {
-  return new Promise((resolve, reject) => {
-    const child = spawn('git', args, { stdio: ['ignore', 'pipe', 'pipe'] });
-    let out = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => { out += chunk; });
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk;
-      if (stderr.length > 2000) stderr = stderr.slice(-2000);
-    });
-    const timer = setTimeout(() => {
-      child.kill('SIGKILL');
-      reject(new Error('git took too long and was stopped.'));
-    }, TIMEOUT_MS);
-    child.on('error', (err) => {
-      clearTimeout(timer);
-      err.message = 'Could not run git: ' + err.message;
-      reject(err);
-    });
-    child.on('close', (code) => {
-      clearTimeout(timer);
-      if (code === 0) resolve(out);
-      else reject(new Error(stderr.trim() || ('git exited ' + code)));
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+        let out = '';
+        let stderr = '';
+        child.stdout.on('data', (chunk) => { out += chunk; });
+        child.stderr.on('data', (chunk) => {
+            stderr += chunk;
+            if (stderr.length > 2000)
+                stderr = stderr.slice(-2000);
+        });
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new Error('git took too long and was stopped.'));
+        }, TIMEOUT_MS);
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            err.message = 'Could not run git: ' + err.message;
+            reject(err);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (code === 0)
+                resolve(out);
+            else
+                reject(new Error(stderr.trim() || ('git exited ' + code)));
+        });
     });
-  });
 }
+//# sourceMappingURL=gitHistory.js.map

package/server/gitHistory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitHistory.js","sourceRoot":"","sources":["../src/server/gitHistory.ts"],"names":[],"mappings":"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","sourcesContent":["// Reading git history for a scanned root. The same discipline as gitClone.js:\n// git is spawned with an argument array — never through a shell — and its\n// output is parsed, not interpreted. A root without history is an expected\n// outcome, not an error: the browser folder-pick flow never touches git, a\n// downloaded tarball has no .git, and a plain folder may simply not be a\n// checkout. All of those come back as { available: false, reason } so the UI\n// can say why instead of showing zeros.\n\nimport { spawn } from 'node:child_process';\n\n// How far back the window goes. Two thousand commits is years of work on most\n// repos and keeps the log parse bounded; `totalCommits` travels alongside so\n// truncation is stated, not silent.\nconst LOG_CAP = 2000;\nconst TIMEOUT_MS = 30_000;\n\n// Record separator \\x1e between commits, unit separator \\x1f between fields.\n// Filenames are one per line after the header. A filename containing \\x1e or\n// \\x1f is legal on paper and does not happen in practice — the same trade every\n// machine-readable git format makes (documented limitation, like .gitignore\n// negation in scan.js).\nconst LOG_FORMAT = '%x1e%H%x1f%an%x1f%ae%x1f%aI';\n\nexport async function gitLog(root) {\n  let countText;\n  try {\n    countText = await run(['-C', root, 'rev-list', '--count', 'HEAD']);\n  } catch (err) {\n    return { ok: false, reason: explain(err) };\n  }\n  const totalCommits = parseInt(countText.trim(), 10) || 0;\n  if (!totalCommits) {\n    return { ok: false, reason: 'The repository exists but has no commits yet.' };\n  }\n\n  let text;\n  try {\n    text = await run([\n      '-C', root, 'log',\n      '--max-count=' + LOG_CAP,\n      '--pretty=format:' + LOG_FORMAT,\n      '--name-only',\n      '--no-renames',\n      'HEAD',\n    ]);\n  } catch (err) {\n    return { ok: false, reason: explain(err) };\n  }\n\n  return { ok: true, text, totalCommits };\n}\n\n// Pure, so the format contract is testable without a git binary.\nexport function parseGitLog(text) {\n  const commits = [];\n  for (const record of String(text).split('\\x1e')) {\n    if (!record.trim()) continue;\n    const lines = record.split('\\n');\n    const [hash, name, email, date] = lines[0].split('\\x1f');\n    if (!hash) continue;\n    const files = [];\n    for (let i = 1; i < lines.length; i++) {\n      const f = lines[i].trim();\n      if (f) files.push(f);\n    }\n    commits.push({ hash, author: { name: name || '', email: email || '' }, date: date || '', files });\n  }\n  return commits;\n}\n\nfunction explain(err) {\n  const message = err.message || '';\n  if (err.code === 'ENOENT' || /spawn git ENOENT/.test(message)) {\n    return 'git is not installed or not on PATH, so there is no history to read.';\n  }\n  if (/not a git repository/i.test(message)) {\n    return 'No .git here — this folder is not a checkout, so there is no history to read.';\n  }\n  if (/does not have any commits yet/i.test(message)) {\n    return 'The repository exists but has no commits yet.';\n  }\n  return 'git would not say: ' + message.split('\\n').pop();\n}\n\nfunction run(args) {\n  return new Promise((resolve, reject) => {\n    const child = spawn('git', args, { stdio: ['ignore', 'pipe', 'pipe'] });\n    let out = '';\n    let stderr = '';\n    child.stdout.on('data', (chunk) => { out += chunk; });\n    child.stderr.on('data', (chunk) => {\n      stderr += chunk;\n      if (stderr.length > 2000) stderr = stderr.slice(-2000);\n    });\n    const timer = setTimeout(() => {\n      child.kill('SIGKILL');\n      reject(new Error('git took too long and was stopped.'));\n    }, TIMEOUT_MS);\n    child.on('error', (err) => {\n      clearTimeout(timer);\n      err.message = 'Could not run git: ' + err.message;\n      reject(err);\n    });\n    child.on('close', (code) => {\n      clearTimeout(timer);\n      if (code === 0) resolve(out);\n      else reject(new Error(stderr.trim() || ('git exited ' + code)));\n    });\n  });\n}\n"]}

package/server/gitRemote.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The `origin` remote of a checkout, or null with a reason.
+ *
+ * `origin` specifically, not "the first remote": origin is the one that means
+ * "where this came from". A fork's `upstream` is a different repository, and
+ * reporting that repo's stars for a fork is a confident wrong answer.
+ */
+export declare function gitRemoteOrigin(root: any): Promise<{
+    ok: boolean;
+    url?: string;
+    reason?: string;
+}>;

package/server/gitRemote.js

@@ -0,0 +1,60 @@
+// The URL a local checkout came from — `git remote get-url origin`.
+//
+// The web app never needs this: it only shows remote facts for a repo it cloned
+// itself, where it already knows the URL it was given. A terminal session is
+// usually started *inside* somebody's checkout, so `github` there has no URL to
+// work from and has to ask git. That is the one place this surface is a strict
+// improvement on the site rather than a copy of it.
+//
+// Same discipline as `gitHistory.js`: git is spawned with an argument array,
+// never through a shell, and a repo with no remote is an expected outcome rather
+// than an error — a plain folder, a tarball, and a checkout with the remote
+// removed are all normal.
+import { spawn } from 'node:child_process';
+const TIMEOUT_MS = 10_000;
+/**
+ * The `origin` remote of a checkout, or null with a reason.
+ *
+ * `origin` specifically, not "the first remote": origin is the one that means
+ * "where this came from". A fork's `upstream` is a different repository, and
+ * reporting that repo's stars for a fork is a confident wrong answer.
+ */
+export function gitRemoteOrigin(root) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn('git', ['-C', root, 'remote', 'get-url', 'origin'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+        }
+        catch (err) {
+            resolve({ ok: false, reason: 'Could not run git: ' + err.message });
+            return;
+        }
+        let out = '';
+        let stderr = '';
+        const cap = (buf, max) => (buf.length > max ? buf.slice(-max) : buf);
+        child.stdout.on('data', (c) => { out = cap(out + c, 2000); });
+        child.stderr.on('data', (c) => { stderr = cap(stderr + c, 2000); });
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            resolve({ ok: false, reason: 'git took too long to say where this came from.' });
+        }, TIMEOUT_MS);
+        // `once`, and the promise is only ever settled once, so a timeout that
+        // races a late `close` cannot resolve an already-resolved promise.
+        const settle = (value) => { clearTimeout(timer); resolve(value); };
+        child.on('error', (err) => settle({ ok: false, reason: 'Could not run git: ' + err.message }));
+        child.on('close', (code) => {
+            const url = out.trim();
+            if (code === 0 && url)
+                settle({ ok: true, url });
+            else if (/not a git repository/i.test(stderr))
+                settle({ ok: false, reason: 'This folder is not a git checkout, so it has no remote.' });
+            else if (code === 0)
+                settle({ ok: false, reason: 'This checkout has no origin remote.' });
+            else
+                settle({ ok: false, reason: 'git would not say: ' + (stderr.trim().split('\n').pop() || ('exited ' + code)) });
+        });
+    });
+}
+//# sourceMappingURL=gitRemote.js.map

package/server/gitRemote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitRemote.js","sourceRoot":"","sources":["../src/server/gitRemote.ts"],"names":[],"mappings":"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","sourcesContent":["// The URL a local checkout came from — `git remote get-url origin`.\n//\n// The web app never needs this: it only shows remote facts for a repo it cloned\n// itself, where it already knows the URL it was given. A terminal session is\n// usually started *inside* somebody's checkout, so `github` there has no URL to\n// work from and has to ask git. That is the one place this surface is a strict\n// improvement on the site rather than a copy of it.\n//\n// Same discipline as `gitHistory.js`: git is spawned with an argument array,\n// never through a shell, and a repo with no remote is an expected outcome rather\n// than an error — a plain folder, a tarball, and a checkout with the remote\n// removed are all normal.\n\nimport { spawn } from 'node:child_process';\n\nconst TIMEOUT_MS = 10_000;\n\n/**\n * The `origin` remote of a checkout, or null with a reason.\n *\n * `origin` specifically, not \"the first remote\": origin is the one that means\n * \"where this came from\". A fork's `upstream` is a different repository, and\n * reporting that repo's stars for a fork is a confident wrong answer.\n */\nexport function gitRemoteOrigin(root) {\n  return new Promise<{ ok: boolean; url?: string; reason?: string }>((resolve) => {\n    let child;\n    try {\n      child = spawn('git', ['-C', root, 'remote', 'get-url', 'origin'], {\n        stdio: ['ignore', 'pipe', 'pipe'],\n      });\n    } catch (err) {\n      resolve({ ok: false, reason: 'Could not run git: ' + err.message });\n      return;\n    }\n\n    let out = '';\n    let stderr = '';\n    const cap = (buf, max) => (buf.length > max ? buf.slice(-max) : buf);\n    child.stdout.on('data', (c) => { out = cap(out + c, 2000); });\n    child.stderr.on('data', (c) => { stderr = cap(stderr + c, 2000); });\n\n    const timer = setTimeout(() => {\n      child.kill('SIGKILL');\n      resolve({ ok: false, reason: 'git took too long to say where this came from.' });\n    }, TIMEOUT_MS);\n\n    // `once`, and the promise is only ever settled once, so a timeout that\n    // races a late `close` cannot resolve an already-resolved promise.\n    const settle = (value) => { clearTimeout(timer); resolve(value); };\n\n    child.on('error', (err) => settle({ ok: false, reason: 'Could not run git: ' + err.message }));\n    child.on('close', (code) => {\n      const url = out.trim();\n      if (code === 0 && url) settle({ ok: true, url });\n      else if (/not a git repository/i.test(stderr)) settle({ ok: false, reason: 'This folder is not a git checkout, so it has no remote.' });\n      else if (code === 0) settle({ ok: false, reason: 'This checkout has no origin remote.' });\n      else settle({ ok: false, reason: 'git would not say: ' + (stderr.trim().split('\\n').pop() || ('exited ' + code)) });\n    });\n  });\n}"]}

package/server/htmlText.d.ts

@@ -0,0 +1,4 @@
+export declare function htmlToText(html: any, limit?: number): {
+    title: string;
+    text: string;
+};

package/server/htmlText.js

@@ -8,37 +8,30 @@
 // after it there is no way to tell the title from the first paragraph. Entities
 // are decoded last, so a `<script>` written *about* HTML in the docs
 // cannot turn back into markup that the earlier passes would have removed.
-
 // Enough context for a model to summarise from without sending a whole site.
 const MAX_TEXT = 14000;
-
 const ENTITIES = {
-  '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'",
+    '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&#39;': "'",
 };
-
 // Horizontal space, newlines excluded. The non-breaking space belongs here:
 // `&nbsp;` is decoded to a plain space below, but pages carry the raw character
 // as well and it should not survive as indentation.
 const RUN_OF_SPACE = /[ \t\u00a0]+/g;
 const AROUND_NEWLINE = /[ \t\u00a0]*\n[ \t\u00a0]*/g;
-
 export function htmlToText(html, limit = MAX_TEXT) {
-  let s = String(html);
-  s = s.replace(/<script[\s\S]*?<\/script>/gi, ' ');
-  s = s.replace(/<style[\s\S]*?<\/style>/gi, ' ');
-
-  const rawTitle = (s.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [, ''])[1];
-  const title = rawTitle.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
-
-  s = s.replace(/<[^>]+>/g, ' ');
-  s = s.replace(/&nbsp;|&amp;|&lt;|&gt;|&quot;|&#39;/g, (m) => ENTITIES[m]);
-
-  // Newlines survive as paragraph breaks \u2014 a docs page read as one long line
-  // loses the structure a summary needs \u2014 but everything else collapses. Every
-  // tag became a space, so a break arrives as " \n\n\n " and the indentation of
-  // the source becomes indentation of the text; trimming around each newline is
-  // what makes the break itself clean.
-  s = s.replace(RUN_OF_SPACE, ' ').replace(AROUND_NEWLINE, '\n').replace(/\n{3,}/g, '\n\n').trim();
-
-  return { title, text: s.slice(0, limit) };
+    let s = String(html);
+    s = s.replace(/<script[\s\S]*?<\/script>/gi, ' ');
+    s = s.replace(/<style[\s\S]*?<\/style>/gi, ' ');
+    const rawTitle = (s.match(/<title[^>]*>([\s\S]*?)<\/title>/i) || [, ''])[1];
+    const title = rawTitle.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    s = s.replace(/<[^>]+>/g, ' ');
+    s = s.replace(/&nbsp;|&amp;|&lt;|&gt;|&quot;|&#39;/g, (m) => ENTITIES[m]);
+    // Newlines survive as paragraph breaks \u2014 a docs page read as one long line
+    // loses the structure a summary needs \u2014 but everything else collapses. Every
+    // tag became a space, so a break arrives as " \n\n\n " and the indentation of
+    // the source becomes indentation of the text; trimming around each newline is
+    // what makes the break itself clean.
+    s = s.replace(RUN_OF_SPACE, ' ').replace(AROUND_NEWLINE, '\n').replace(/\n{3,}/g, '\n\n').trim();
+    return { title, text: s.slice(0, limit) };
 }
+//# sourceMappingURL=htmlText.js.map

package/server/htmlText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"htmlText.js","sourceRoot":"","sources":["../src/server/htmlText.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,gFAAgF;AAChF,4DAA4D;AAC5D,EAAE;AACF,kFAAkF;AAClF,yEAAyE;AACzE,+EAA+E;AAC/E,gFAAgF;AAChF,2EAA2E;AAC3E,2EAA2E;AAE3E,6EAA6E;AAC7E,MAAM,QAAQ,GAAG,KAAK,CAAC;AAEvB,MAAM,QAAQ,GAAG;IACf,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG;CACnF,CAAC;AAEF,4EAA4E;AAC5E,gFAAgF;AAChF,oDAAoD;AACpD,MAAM,YAAY,GAAG,eAAe,CAAC;AACrC,MAAM,cAAc,GAAG,6BAA6B,CAAC;AAErD,MAAM,UAAU,UAAU,CAAC,IAAI,EAAE,KAAK,GAAG,QAAQ;IAC/C,IAAI,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IACrB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;IAClD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,2BAA2B,EAAE,GAAG,CAAC,CAAC;IAEhD,MAAM,QAAQ,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,kCAAkC,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAE5E,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,sCAAsC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE1E,gFAAgF;IAChF,kFAAkF;IAClF,8EAA8E;IAC9E,8EAA8E;IAC9E,qCAAqC;IACrC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAEjG,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;AAC5C,CAAC","sourcesContent":["// HTML to readable text, for the docs fetch. Not a parser and not trying to be:\n// the output is fed to a language model as context, so what matters is that the\n// prose survives and the markup, scripts and styles do not.\n//\n// Order is the whole trick. Script and style bodies go first — their contents are\n// text, not tags, so stripping tags first would leave a page of minified\n// JavaScript behind. The title is lifted before the general tag strip, because\n// after it there is no way to tell the title from the first paragraph. Entities\n// are decoded last, so a `&lt;script&gt;` written *about* HTML in the docs\n// cannot turn back into markup that the earlier passes would have removed.\n\n// Enough context for a model to summarise from without sending a whole site.\nconst MAX_TEXT = 14000;\n\nconst ENTITIES = {\n  '&nbsp;': ' ', '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '\"', '&#39;': \"'\",\n};\n\n// Horizontal space, newlines excluded. The non-breaking space belongs here:\n// `&nbsp;` is decoded to a plain space below, but pages carry the raw character\n// as well and it should not survive as indentation.\nconst RUN_OF_SPACE = /[ \\t\\u00a0]+/g;\nconst AROUND_NEWLINE = /[ \\t\\u00a0]*\\n[ \\t\\u00a0]*/g;\n\nexport function htmlToText(html, limit = MAX_TEXT) {\n  let s = String(html);\n  s = s.replace(/<script[\\s\\S]*?<\\/script>/gi, ' ');\n  s = s.replace(/<style[\\s\\S]*?<\\/style>/gi, ' ');\n\n  const rawTitle = (s.match(/<title[^>]*>([\\s\\S]*?)<\\/title>/i) || [, ''])[1];\n  const title = rawTitle.replace(/<[^>]+>/g, ' ').replace(/\\s+/g, ' ').trim();\n\n  s = s.replace(/<[^>]+>/g, ' ');\n  s = s.replace(/&nbsp;|&amp;|&lt;|&gt;|&quot;|&#39;/g, (m) => ENTITIES[m]);\n\n  // Newlines survive as paragraph breaks \\u2014 a docs page read as one long line\n  // loses the structure a summary needs \\u2014 but everything else collapses. Every\n  // tag became a space, so a break arrives as \" \\n\\n\\n \" and the indentation of\n  // the source becomes indentation of the text; trimming around each newline is\n  // what makes the break itself clean.\n  s = s.replace(RUN_OF_SPACE, ' ').replace(AROUND_NEWLINE, '\\n').replace(/\\n{3,}/g, '\\n\\n').trim();\n\n  return { title, text: s.slice(0, limit) };\n}\n"]}

package/server/http.d.ts

@@ -0,0 +1,5 @@
+export declare const MAX_BODY_BYTES: number;
+export declare function readBody(req: any, limit?: number): Promise<unknown>;
+export declare function sendJSON(res: any, status: any, data: any, headers?: Record<string, any>): void;
+export declare function sendError(res: any, status: any, message: any): void;
+export declare function sendText(res: any, status: any, text: any): void;

package/server/http.js

@@ -2,54 +2,51 @@
 // does. Pulled out of the router so a handler can be read on its own, and so
 // the body limit is one number in one place rather than a check repeated per
 // route and forgotten on the next one.
-
 // A scan request carries a path or a URL; an explain request carries a prompt
 // and a slice of facts. Two megabytes is far more than either needs, and the
 // point is to have a ceiling at all: a local server with no auth should not let
 // a stray fetch hold memory open.
 export const MAX_BODY_BYTES = 2 * 1024 * 1024;
-
 // Resolves to the parsed JSON body, or `{}` for an empty one — a POST with no
 // body is a valid "just the defaults" request and every caller would otherwise
 // need the same guard. Rejects on oversized or malformed input; the router turns
 // that into a 500 with the message.
 export function readBody(req, limit = MAX_BODY_BYTES) {
-  return new Promise((resolve, reject) => {
-    let size = 0;
-    const chunks = [];
-    req.on('data', (chunk) => {
-      size += chunk.length;
-      if (size > limit) {
-        reject(new Error('Request body too large.'));
-        req.destroy();
-        return;
-      }
-      chunks.push(chunk);
+    return new Promise((resolve, reject) => {
+        let size = 0;
+        const chunks = [];
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new Error('Request body too large.'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            try {
+                resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
+            }
+            catch {
+                reject(new Error('The request body was not valid JSON.'));
+            }
+        });
+        req.on('error', reject);
     });
-    req.on('end', () => {
-      try {
-        resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});
-      } catch {
-        reject(new Error('The request body was not valid JSON.'));
-      }
-    });
-    req.on('error', reject);
-  });
 }
-
 export function sendJSON(res, status, data, headers = {}) {
-  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });
-  res.end(JSON.stringify(data));
+    res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });
+    res.end(JSON.stringify(data));
 }
-
 // Every error the UI shows comes back through here, so the shape is fixed:
 // `{ error }` with a sentence a person can act on. The front end reads `.error`
 // and nothing else.
 export function sendError(res, status, message) {
-  sendJSON(res, status, { error: message });
+    sendJSON(res, status, { error: message });
 }
-
 export function sendText(res, status, text) {
-  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
-  res.end(text);
+    res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end(text);
 }
+//# sourceMappingURL=http.js.map

package/server/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/server/http.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,6EAA6E;AAC7E,6EAA6E;AAC7E,uCAAuC;AAEvC,8EAA8E;AAC9E,6EAA6E;AAC7E,gFAAgF;AAChF,kCAAkC;AAClC,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9C,8EAA8E;AAC9E,+EAA+E;AAC/E,iFAAiF;AACjF,oCAAoC;AACpC,MAAM,UAAU,QAAQ,CAAC,GAAG,EAAE,KAAK,GAAG,cAAc;IAClD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,MAAM,MAAM,GAAG,EAAE,CAAC;QAClB,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;YACvB,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;YACrB,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAC;gBAC7C,GAAG,CAAC,OAAO,EAAE,CAAC;gBACd,OAAO;YACT,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC;gBACH,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnF,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC,CAAC;YAC5D,CAAC;QACH,CAAC,CAAC,CAAC;QACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAwB,EAAE;IAC3E,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,iCAAiC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACzF,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC;AAChC,CAAC;AAED,2EAA2E;AAC3E,gFAAgF;AAChF,oBAAoB;AACpB,MAAM,UAAU,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO;IAC5C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI;IACxC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,CAAC,CAAC;IACvE,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC","sourcesContent":["// Reading a request body and writing a response — the two things every route\n// does. Pulled out of the router so a handler can be read on its own, and so\n// the body limit is one number in one place rather than a check repeated per\n// route and forgotten on the next one.\n\n// A scan request carries a path or a URL; an explain request carries a prompt\n// and a slice of facts. Two megabytes is far more than either needs, and the\n// point is to have a ceiling at all: a local server with no auth should not let\n// a stray fetch hold memory open.\nexport const MAX_BODY_BYTES = 2 * 1024 * 1024;\n\n// Resolves to the parsed JSON body, or `{}` for an empty one — a POST with no\n// body is a valid \"just the defaults\" request and every caller would otherwise\n// need the same guard. Rejects on oversized or malformed input; the router turns\n// that into a 500 with the message.\nexport function readBody(req, limit = MAX_BODY_BYTES) {\n  return new Promise((resolve, reject) => {\n    let size = 0;\n    const chunks = [];\n    req.on('data', (chunk) => {\n      size += chunk.length;\n      if (size > limit) {\n        reject(new Error('Request body too large.'));\n        req.destroy();\n        return;\n      }\n      chunks.push(chunk);\n    });\n    req.on('end', () => {\n      try {\n        resolve(chunks.length ? JSON.parse(Buffer.concat(chunks).toString('utf8')) : {});\n      } catch {\n        reject(new Error('The request body was not valid JSON.'));\n      }\n    });\n    req.on('error', reject);\n  });\n}\n\nexport function sendJSON(res, status, data, headers: Record<string, any> = {}) {\n  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', ...headers });\n  res.end(JSON.stringify(data));\n}\n\n// Every error the UI shows comes back through here, so the shape is fixed:\n// `{ error }` with a sentence a person can act on. The front end reads `.error`\n// and nothing else.\nexport function sendError(res, status, message) {\n  sendJSON(res, status, { error: message });\n}\n\nexport function sendText(res, status, text) {\n  res.writeHead(status, { 'content-type': 'text/plain; charset=utf-8' });\n  res.end(text);\n}\n"]}

package/server/httpGuards.d.ts

@@ -0,0 +1,2 @@
+export declare function rebindingReason(req: any, extraHosts?: any[]): string;
+export declare function crossOriginReason(req: any): string;

package/server/httpGuards.js

@@ -6,22 +6,18 @@
 // authenticate. Both exist to stop some *other* page the user happens to have
 // open from driving this server on their behalf. Binding to 127.0.0.1 keeps
 // the network out; it does nothing about the browser, which is already inside.
-
 import net from 'node:net';
-
 const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
-
 // "localhost:4310" -> "localhost", "[::1]:4310" -> "[::1]"
 function hostnameOf(hostHeader) {
-  const raw = String(hostHeader ?? '').trim().toLowerCase();
-  if (raw.startsWith('[')) {
-    const close = raw.indexOf(']');
-    return close === -1 ? raw : raw.slice(0, close + 1);
-  }
-  const colon = raw.lastIndexOf(':');
-  return colon === -1 ? raw : raw.slice(0, colon);
+    const raw = String(hostHeader ?? '').trim().toLowerCase();
+    if (raw.startsWith('[')) {
+        const close = raw.indexOf(']');
+        return close === -1 ? raw : raw.slice(0, close + 1);
+    }
+    const colon = raw.lastIndexOf(':');
+    return colon === -1 ? raw : raw.slice(0, colon);
 }
-
 // DNS rebinding, the attack this server's loopback bind does not cover: a page
 // on evil.com whose DNS answer flips to 127.0.0.1 reaches us anyway, and from
 // then on the browser treats evil.com as the same origin as everything we
@@ -38,25 +34,31 @@ function hostnameOf(hostHeader) {
 //
 // Returns null when the request is fine, or a short reason when it isn't.
 export function rebindingReason(req, extraHosts = []) {
-  const host = req.headers?.host;
-  if (!host) return 'The request arrived with no Host header.';
-  const name = hostnameOf(host);
-  if (LOOPBACK_HOSTS.has(name)) return null;
-  for (const extra of extraHosts) {
-    if (extra === 'ip:*' && net.isIP(name.replace(/^\[|\]$/g, '')) > 0) return null;
-    if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;
-    if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6) return null;
-    if (extra.startsWith('*.')) {
-      // "*.trycloudflare.com" matches "abc.trycloudflare.com" but not the bare
-      // suffix itself and not "evil-trycloudflare.com".
-      if (name.endsWith(extra.slice(1)) && name.length > extra.length) return null;
-    } else if (name === extra) {
-      return null;
+    const host = req.headers?.host;
+    if (!host)
+        return 'The request arrived with no Host header.';
+    const name = hostnameOf(host);
+    if (LOOPBACK_HOSTS.has(name))
+        return null;
+    for (const extra of extraHosts) {
+        if (extra === 'ip:*' && net.isIP(name.replace(/^\[|\]$/g, '')) > 0)
+            return null;
+        if (extra === 'ipv4:*' && net.isIP(name) === 4)
+            return null;
+        if (extra === 'ipv6:*' && net.isIP(name.replace(/^\[|\]$/g, '')) === 6)
+            return null;
+        if (extra.startsWith('*.')) {
+            // "*.trycloudflare.com" matches "abc.trycloudflare.com" but not the bare
+            // suffix itself and not "evil-trycloudflare.com".
+            if (name.endsWith(extra.slice(1)) && name.length > extra.length)
+                return null;
+        }
+        else if (name === extra) {
+            return null;
+        }
     }
-  }
-  return `It arrived addressed to ${name}.`;
+    return `It arrived addressed to ${name}.`;
 }
-
 // Cross-site requests: any page in the browser can POST here without being
 // able to read the answer, and "without being able to read the answer" is not
 // the same as harmless — /api/scan walks a directory the caller names, and
@@ -74,19 +76,21 @@ export function rebindingReason(req, extraHosts = []) {
 // A request carrying neither header isn't a browser at all — curl, a test, a
 // script — and there is no cross-site story for those, so they pass.
 export function crossOriginReason(req) {
-  const site = req.headers?.['sec-fetch-site'];
-  if (site && site !== 'same-origin' && site !== 'none') {
-    return `The browser reported it as ${site}.`;
-  }
-  const origin = req.headers?.origin;
-  if (origin) {
-    // The host was just vetted by the rebinding check, so the origin only has
-    // to agree with it. Both schemes are accepted: a self-hosted server behind
-    // a tunnel is reached over https while the page's fetches still arrive
-    // here addressed to the same host the tunnel forwarded.
-    const host = String(req.headers.host ?? '').trim().toLowerCase();
-    const expected = new Set(['http://' + host, 'https://' + host]);
-    if (!expected.has(String(origin).trim().toLowerCase())) return `It came from ${origin}.`;
-  }
-  return null;
+    const site = req.headers?.['sec-fetch-site'];
+    if (site && site !== 'same-origin' && site !== 'none') {
+        return `The browser reported it as ${site}.`;
+    }
+    const origin = req.headers?.origin;
+    if (origin) {
+        // The host was just vetted by the rebinding check, so the origin only has
+        // to agree with it. Both schemes are accepted: a self-hosted server behind
+        // a tunnel is reached over https while the page's fetches still arrive
+        // here addressed to the same host the tunnel forwarded.
+        const host = String(req.headers.host ?? '').trim().toLowerCase();
+        const expected = new Set(['http://' + host, 'https://' + host]);
+        if (!expected.has(String(origin).trim().toLowerCase()))
+            return `It came from ${origin}.`;
+    }
+    return null;
 }
+//# sourceMappingURL=httpGuards.js.map

package/server/httpGuards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpGuards.js","sourceRoot":"","sources":["../src/server/httpGuards.ts"],"names":[],"mappings":"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","sourcesContent":["// Two questions worth asking about a request before it is allowed to do\n// anything: did it arrive at a name that really is this machine, and did it\n// come from this app's own page?\n//\n// Neither is authentication — a single-user local tool has nobody to\n// authenticate. Both exist to stop some *other* page the user happens to have\n// open from driving this server on their behalf. Binding to 127.0.0.1 keeps\n// the network out; it does nothing about the browser, which is already inside.\n\nimport net from 'node:net';\n\nconst LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);\n\n// \"localhost:4310\" -> \"localhost\", \"[::1]:4310\" -> \"[::1]\"\nfunction hostnameOf(hostHeader) {\n  const raw = String(hostHeader ?? '').trim().toLowerCase();\n  if (raw.startsWith('[')) {\n    const close = raw.indexOf(']');\n    return close === -1 ? raw : raw.slice(0, close + 1);\n  }\n  const colon = raw.lastIndexOf(':');\n  return colon === -1 ? raw : raw.slice(0, colon);\n}\n\n// DNS rebinding, the attack this server's loopback bind does not cover: a page\n// on evil.com whose DNS answer flips to 127.0.0.1 reaches us anyway, and from\n// then on the browser treats evil.com as the same origin as everything we\n// return — so the origin check below is looking at `same-origin` and sees\n// nothing wrong. What still gives it away is the Host header, which the page\n// cannot set and which still says evil.com.\n//\n// `extraHosts` is the self-hosted escape hatch: the domain and bind address\n// from the settings file, so a server that was deliberately put on the network\n// answers to its own name and nothing else. A local server passes nothing and\n// keeps the loopback-only rule. Entries may be exact names or `*.suffix`\n// wildcards — enabled tunnels put their random upstream names here, which\n// cannot be known ahead of time.\n//\n// Returns null when the request is fine, or a short reason when it isn't.\nexport function rebindingReason(req, extraHosts = []) {\n  const host = req.headers?.host;\n  if (!host) return 'The request arrived with no Host header.';\n  const name = hostnameOf(host);\n  if (LOOPBACK_HOSTS.has(name)) return null;\n  for (const extra of extraHosts) {\n    if (extra === 'ip:*' && net.isIP(name.replace(/^\\[|\\]$/g, '')) > 0) return null;\n    if (extra === 'ipv4:*' && net.isIP(name) === 4) return null;\n    if (extra === 'ipv6:*' && net.isIP(name.replace(/^\\[|\\]$/g, '')) === 6) return null;\n    if (extra.startsWith('*.')) {\n      // \"*.trycloudflare.com\" matches \"abc.trycloudflare.com\" but not the bare\n      // suffix itself and not \"evil-trycloudflare.com\".\n      if (name.endsWith(extra.slice(1)) && name.length > extra.length) return null;\n    } else if (name === extra) {\n      return null;\n    }\n  }\n  return `It arrived addressed to ${name}.`;\n}\n\n// Cross-site requests: any page in the browser can POST here without being\n// able to read the answer, and \"without being able to read the answer\" is not\n// the same as harmless — /api/scan walks a directory the caller names, and\n// /api/explain will POST to any URL the caller names.\n//\n// Two signals, and a request only has to fail one to be refused:\n//\n//   Sec-Fetch-Site  set by the browser, unsettable by page script. `none`\n//                   means the user did it themselves — typed the URL, opened\n//                   a bookmark — which no attacking page can arrange.\n//   Origin          sent on every fetch that isn't GET/HEAD. Compared against\n//                   this server's own origin, which is `http://` plus the Host\n//                   we just confirmed is loopback.\n//\n// A request carrying neither header isn't a browser at all — curl, a test, a\n// script — and there is no cross-site story for those, so they pass.\nexport function crossOriginReason(req) {\n  const site = req.headers?.['sec-fetch-site'];\n  if (site && site !== 'same-origin' && site !== 'none') {\n    return `The browser reported it as ${site}.`;\n  }\n  const origin = req.headers?.origin;\n  if (origin) {\n    // The host was just vetted by the rebinding check, so the origin only has\n    // to agree with it. Both schemes are accepted: a self-hosted server behind\n    // a tunnel is reached over https while the page's fetches still arrive\n    // here addressed to the same host the tunnel forwarded.\n    const host = String(req.headers.host ?? '').trim().toLowerCase();\n    const expected = new Set(['http://' + host, 'https://' + host]);\n    if (!expected.has(String(origin).trim().toLowerCase())) return `It came from ${origin}.`;\n  }\n  return null;\n}\n"]}