@northtek/overstory 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,15 @@
 # OVERSTORY
 
+[![CI](https://github.com/NORTHTEKDevs/overstory/actions/workflows/ci.yml/badge.svg)](https://github.com/NORTHTEKDevs/overstory/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@northtek/overstory)](https://www.npmjs.com/package/@northtek/overstory)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![overstory](https://overstory-virid.vercel.app/badge/gh/NORTHTEKDevs/overstory.svg)](https://overstory-virid.vercel.app/gh/NORTHTEKDevs/overstory)
+
 **A knowledge tree of your codebase where every claim carries a receipt.**
 
+> The last badge is this repository's own claims, re-verified against this repository's
+> current code every time you load it. If it drops below 100%, the docs drifted.
+
 > **30 seconds, no jargon:** AI tools sound exactly as confident when they're wrong as when
 > they're right. OVERSTORY reads your codebase, writes it up as short statements, and then
 > **checks every statement against the actual code** — click any one to see the exact lines
@@ -80,7 +88,7 @@ There's an experimental zero-storage registry that can show verified trees of pu
 repos and re-check published trees against the live code (the registry stores nothing —
 your repo is the database). It's in quiet preview and not the point of v1: the product is
 the local tool. `overstory publish` targets it if you want to try it; details in
-docs/plans/2026-07-21-registry-design.md.
+[docs/registry-design.md](docs/registry-design.md).
 
 ## MCP: notarize your agent's answers
 

package/dist/cli/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { writeFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { buildTree, verifyExisting } from '../build/builder.js';
 import { loadCorpus } from '../core/corpus.js';
 import { loadTree, treePath } from '../core/store.js';
@@ -34,7 +35,26 @@ Options:
   --out <file>              Output path for site
   --port <n>                Port for serve (default 7433)
   --json                    Machine-readable output
+  --version, -v             Print the installed version
+  --help, -h                Show this help
 `;
+/** Read the version from the shipped package.json. Resolved relative to this module so it
+ * is correct whether running from dist/ or from source. */
+const packageVersion = () => {
+    for (const up of ['../../package.json', '../../../package.json']) {
+        try {
+            const path = fileURLToPath(new URL(up, import.meta.url));
+            const parsed = JSON.parse(readFileSync(path, 'utf8'));
+            if (parsed !== null && typeof parsed === 'object' && 'version' in parsed) {
+                return String(parsed.version);
+            }
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return 'unknown';
+};
 /** A mis-typed numeric flag must error, never silently disable the cap it configures. */
 const numFlag = (raw, flag) => {
     const n = Number(raw);
@@ -66,6 +86,8 @@ const parseArgs = (argv) => {
             flags.port = numFlag(argv[++i], '--port');
         else if (a === '--help' || a === '-h')
             positional.push('help');
+        else if (a === '--version' || a === '-v')
+            positional.unshift('version');
         else
             positional.push(a);
     }
@@ -80,6 +102,10 @@ const main = async () => {
     const { cmd, positional, flags } = parseArgs(process.argv.slice(2));
     const rootArg = positional[cmd === 'ask' ? 1 : 0];
     const root = resolve(rootArg ?? '.');
+    if (cmd === 'version') {
+        process.stdout.write(`${packageVersion()}\n`);
+        return 0;
+    }
     if (cmd === 'help') {
         process.stdout.write(HELP);
         return 0;

package/dist/registry/github.d.ts

@@ -8,6 +8,10 @@ export interface GithubSnapshot {
 export interface FetchOptions {
     ref?: string;
     maxTarballBytes?: number;
+    /** Ceiling on the DECOMPRESSED tarball. A compressed-size cap alone does not bound
+     * memory: gzip ratios above 1000:1 are trivial to construct, so a repo well under the
+     * compressed cap can still expand to gigabytes. */
+    maxUncompressedBytes?: number;
     maxFiles?: number;
     maxFileBytes?: number;
     fetchImpl?: typeof fetch;
@@ -20,6 +24,9 @@ interface TarEntry {
 /** Minimal ustar reader — enough for GitHub codeload tarballs. Handles pax extended
  * headers ('x' path overrides) and skips the pax_global_header ('g'). */
 export declare const readTar: (tar: Buffer) => TarEntry[];
+/** Decompress with a hard output ceiling so a gzip bomb fails fast and loudly instead of
+ * exhausting the function's memory. */
+export declare const gunzipUnderCap: (tarball: Buffer, maxOutputLength: number) => Buffer;
 /** Turn a GitHub codeload tarball into an in-memory corpus. The tarball's root directory
  * is `{repo}-{sha}/` — the sha comes free, no API call needed. */
 export declare const snapshotFromTarball: (tarball: Buffer, ref: string, opts?: FetchOptions) => GithubSnapshot;

package/dist/registry/github.js

@@ -48,12 +48,58 @@ export const readTar = (tar) => {
     return entries;
 };
 const looksBinary = (buf) => buf.subarray(0, 8000).includes(0);
+/** Decompress with a hard output ceiling so a gzip bomb fails fast and loudly instead of
+ * exhausting the function's memory. */
+export const gunzipUnderCap = (tarball, maxOutputLength) => {
+    try {
+        return gunzipSync(tarball, { maxOutputLength });
+    }
+    catch (err) {
+        const code = err?.code;
+        const message = err instanceof Error ? err.message : String(err);
+        if (code === 'ERR_BUFFER_TOO_LARGE' || /larger than|maxOutputLength/iu.test(message)) {
+            throw new Error(`repo expands past the registry's ${Math.round(maxOutputLength / 1e6)}MB uncompressed cap`);
+        }
+        throw err;
+    }
+};
+/** Read a response body against a running byte ceiling, cancelling the transfer the moment
+ * it is exceeded. Buffering the whole body and checking `.length` afterwards would let a
+ * hostile repo exhaust memory before the check ever ran. */
+const readUnderCap = async (res, cap) => {
+    if (!res.body) {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > cap)
+            throw new Error(tarballTooLarge(cap));
+        return buf;
+    }
+    const reader = res.body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.byteLength;
+        if (total > cap) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error(tarballTooLarge(cap));
+        }
+        chunks.push(Buffer.from(value));
+    }
+    return Buffer.concat(chunks);
+};
+const tarballTooLarge = (cap) => `repo too large for the registry (tarball exceeds the ${Math.round(cap / 1e6)}MB cap)`;
+/** GitHub owners are <=39 chars and repos <=100; neither may contain a path segment or a
+ * traversal sequence. Validated before the URL is built, not after. */
+const validSegment = (segment) => /^[\w.-]{1,100}$/u.test(segment) && !segment.includes('..') && segment !== '.';
 /** Turn a GitHub codeload tarball into an in-memory corpus. The tarball's root directory
  * is `{repo}-{sha}/` — the sha comes free, no API call needed. */
 export const snapshotFromTarball = (tarball, ref, opts = {}) => {
     const maxFiles = opts.maxFiles ?? 5_000;
     const maxFileBytes = opts.maxFileBytes ?? 1_000_000;
-    const entries = readTar(gunzipSync(tarball));
+    const maxUncompressedBytes = opts.maxUncompressedBytes ?? 400_000_000;
+    const entries = readTar(gunzipUnderCap(tarball, maxUncompressedBytes));
     if (entries.length === 0)
         throw new Error('empty tarball');
     const rootDir = entries[0].name.split('/')[0];
@@ -90,7 +136,7 @@ export const snapshotFromTarball = (tarball, ref, opts = {}) => {
 };
 /** Fetch a public GitHub repo snapshot via codeload — no git, no API token, one request. */
 export const fetchGithubSnapshot = async (owner, repo, opts = {}) => {
-    if (!/^[\w.-]+$/u.test(owner) || !/^[\w.-]+$/u.test(repo))
+    if (!validSegment(owner) || !validSegment(repo))
         throw new Error('invalid owner/repo');
     const ref = opts.ref ?? 'HEAD';
     if (!/^[\w][\w./-]*$/u.test(ref) || ref.includes('..'))
@@ -105,9 +151,6 @@ export const fetchGithubSnapshot = async (owner, repo, opts = {}) => {
         throw new Error(`GitHub repo not found (or private): ${owner}/${repo}@${ref}`);
     if (!res.ok)
         throw new Error(`GitHub tarball fetch failed: HTTP ${res.status}`);
-    const buf = Buffer.from(await res.arrayBuffer());
-    if (buf.length > maxTarballBytes) {
-        throw new Error(`repo too large for the registry (${Math.round(buf.length / 1e6)}MB tarball; cap ${Math.round(maxTarballBytes / 1e6)}MB)`);
-    }
+    const buf = await readUnderCap(res, maxTarballBytes);
     return snapshotFromTarball(buf, ref, opts);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@northtek/overstory",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Turn any repo or docs folder into a living knowledge tree where every claim carries a verifiable receipt. Local-first: your code never leaves your machine.",
   "license": "Apache-2.0",
   "type": "module",