pagespeed-quest 0.9.1 → 0.11.0

package/build/llm.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Directory holding the single source of knowledge served to AI agents.
+ *
+ * The Markdown files are shipped with the npm package (see the `files` field in
+ * package.json) so that `psq llm` works offline and always matches the version
+ * of the package that is installed. They are also what context7 crawls.
+ */
+export declare const LlmDocsDir: string;
+/** Version of the installed package, used by `psq --version`. */
+export declare function packageVersion(): string;
+export interface LlmDocChapter {
+    /** File name without the numeric prefix and extension, e.g. `guide` */
+    name: string;
+    /** First level-1 heading of the chapter */
+    title: string;
+    /** Markdown body, heading included */
+    content: string;
+}
+export declare function loadLlmDocs(dir?: string): Promise<LlmDocChapter[]>;
+export declare function renderLlmDocs(format?: 'markdown' | 'json', dir?: string): Promise<string>;

package/build/llm.js

@@ -0,0 +1,42 @@
+import Fs from 'fs';
+import Fsp from 'fs/promises';
+import Path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = Path.dirname(__filename);
+/**
+ * Directory holding the single source of knowledge served to AI agents.
+ *
+ * The Markdown files are shipped with the npm package (see the `files` field in
+ * package.json) so that `psq llm` works offline and always matches the version
+ * of the package that is installed. They are also what context7 crawls.
+ */
+export const LlmDocsDir = Path.resolve(__dirname, '..', 'llmdocs');
+/** Version of the installed package, used by `psq --version`. */
+export function packageVersion() {
+    const packageJsonPath = Path.resolve(__dirname, '..', 'package.json');
+    const packageJson = JSON.parse(Fs.readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version;
+}
+function titleOf(markdown, fallback) {
+    const heading = markdown.split(/\r?\n/).find((line) => line.startsWith('# '));
+    return heading ? heading.slice(2).trim() : fallback;
+}
+export async function loadLlmDocs(dir = LlmDocsDir) {
+    const entries = await Fsp.readdir(dir);
+    const files = entries.filter((name) => name.endsWith('.md')).sort();
+    const chapters = [];
+    for (const file of files) {
+        const content = await Fsp.readFile(Path.join(dir, file), 'utf8');
+        const name = Path.basename(file, '.md').replace(/^\d+-/, '');
+        chapters.push({ name, title: titleOf(content, name), content: content.trimEnd() });
+    }
+    return chapters;
+}
+export async function renderLlmDocs(format = 'markdown', dir) {
+    const chapters = await loadLlmDocs(dir);
+    if (format === 'json')
+        return `${JSON.stringify(chapters, null, 2)}\n`;
+    return `${chapters.map((chapter) => chapter.content).join('\n\n---\n\n')}\n`;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibGxtLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL2xsbS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsTUFBTSxJQUFJLENBQUE7QUFDbkIsT0FBTyxHQUFHLE1BQU0sYUFBYSxDQUFBO0FBQzdCLE9BQU8sSUFBSSxNQUFNLE1BQU0sQ0FBQTtBQUN2QixPQUFPLEVBQUUsYUFBYSxFQUFFLE1BQU0sS0FBSyxDQUFBO0FBRW5DLE1BQU0sVUFBVSxHQUFHLGFBQWEsQ0FBQyxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsQ0FBQyxDQUFBO0FBQ2pELE1BQU0sU0FBUyxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUE7QUFFMUM7Ozs7OztHQU1HO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHLElBQUksQ0FBQyxPQUFPLENBQUMsU0FBUyxFQUFFLElBQUksRUFBRSxTQUFTLENBQUMsQ0FBQTtBQUVsRSxpRUFBaUU7QUFDakUsTUFBTSxVQUFVLGNBQWM7SUFDNUIsTUFBTSxlQUFlLEdBQUcsSUFBSSxDQUFDLE9BQU8sQ0FBQyxTQUFTLEVBQUUsSUFBSSxFQUFFLGNBQWMsQ0FBQyxDQUFBO0lBQ3JFLE1BQU0sV0FBVyxHQUFHLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLFlBQVksQ0FBQyxlQUFlLEVBQUUsTUFBTSxDQUFDLENBQUMsQ0FBQTtJQUN4RSxPQUFPLFdBQVcsQ0FBQyxPQUFpQixDQUFBO0FBQ3RDLENBQUM7QUFXRCxTQUFTLE9BQU8sQ0FBQyxRQUFnQixFQUFFLFFBQWdCO0lBQ2pELE1BQU0sT0FBTyxHQUFHLFFBQVEsQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsVUFBVSxDQUFDLElBQUksQ0FBQyxDQUFDLENBQUE7SUFDN0UsT0FBTyxPQUFPLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxLQUFLLENBQUMsQ0FBQyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQTtBQUNyRCxDQUFDO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSxXQUFXLENBQUMsTUFBYyxVQUFVO0lBQ3hELE1BQU0sT0FBTyxHQUFHLE1BQU0sR0FBRyxDQUFDLE9BQU8sQ0FBQyxHQUFHLENBQUMsQ0FBQTtJQUN0QyxNQUFNLEtBQUssR0FBRyxPQUFPLENBQUMsTUFBTSxDQUFDLENBQUMsSUFBSSxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsUUFBUSxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUE7SUFFbkUsTUFBTSxRQUFRLEdBQW9CLEVBQUUsQ0FBQTtJQUNwQyxLQUFLLE1BQU0sSUFBSSxJQUFJLEtBQUssRUFBRSxDQUFDO1FBQ3pCLE1BQU0sT0FBTyxHQUFHLE1BQU0sR0FBRyxDQUFDLFFBQVEsQ0FBQyxJQUFJLENBQUMsSUFBSSxDQUFDLEdBQUcsRUFBRSxJQUFJLENBQUMsRUFBRSxNQUFNLENBQUMsQ0FBQTtRQUNoRSxNQUFNLElBQUksR0FBRyxJQUFJLENBQUMsUUFBUSxDQUFDLElBQUksRUFBRSxLQUFLLENBQUMsQ0FBQyxPQUFPLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxDQUFBO1FBQzVELFFBQVEsQ0FBQyxJQUFJLENBQUMsRUFBRSxJQUFJLEVBQUUsS0FBSyxFQUFFLE9BQU8sQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLEVBQUUsT0FBTyxFQUFFLE9BQU8sQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLENBQUE7SUFDcEYsQ0FBQztJQUVELE9BQU8sUUFBUSxDQUFBO0FBQ2pCLENBQUM7QUFFRCxNQUFNLENBQUMsS0FBSyxVQUFVLGFBQWEsQ0FBQyxTQUE4QixVQUFVLEVBQUUsR0FBWTtJQUN4RixNQUFNLFFBQVEsR0FBRyxNQUFNLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQTtJQUN2QyxJQUFJLE1BQU0sS0FBSyxNQUFNO1FBQUUsT0FBTyxHQUFHLElBQUksQ0FBQyxTQUFTLENBQUMsUUFBUSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUMsSUFBSSxDQUFBO0lBQ3RFLE9BQU8sR0FBRyxRQUFRLENBQUMsR0FBRyxDQUFDLENBQUMsT0FBTyxFQUFFLEVBQUUsQ0FBQyxPQUFPLENBQUMsT0FBTyxDQUFDLENBQUMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxJQUFJLENBQUE7QUFDOUUsQ0FBQyJ9

package/build/recording.d.ts

@@ -6,6 +6,7 @@ export interface RecordingProxyOptions {
     entryUrl?: string;
     deviceType?: DeviceType;
     port?: number;
+    excludePatterns?: string[];
 }
 export type RecordingProxyDependency = Pick<DependencyInterface, 'logger'>;
 export declare class RecordingProxy {
@@ -14,6 +15,7 @@ export declare class RecordingProxy {
     entryUrl?: string;
     deviceType?: DeviceType;
     requestedPort?: number;
+    excludePatterns?: string[];
     dependency: RecordingProxyDependency;
     constructor(options?: RecordingProxyOptions, dependency?: RecordingProxyDependency);
     start(): Promise<void>;

package/build/recording.js

@@ -1,11 +1,58 @@
-import { startRecording } from 'rust-http-playback-proxy';
+import { spawn } from 'child_process';
+import { createRequire } from 'module';
+import Net from 'net';
+import Path from 'path';
+import { Proxy as RustProxy, startRecording } from 'rust-http-playback-proxy';
 import { InventoryRepository } from './inventory.js';
+async function getAvailablePort() {
+    return new Promise((resolve, reject) => {
+        const server = Net.createServer();
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address && typeof address === 'object') {
+                const port = address.port;
+                server.close(() => resolve(port));
+            }
+            else {
+                server.close(() => reject(new Error('Failed to get port from server address')));
+            }
+        });
+        server.on('error', reject);
+    });
+}
+async function waitForPort(port, timeoutMs = 60000) {
+    const startTime = Date.now();
+    let delay = 50;
+    while (Date.now() - startTime < timeoutMs) {
+        try {
+            await new Promise((resolve, reject) => {
+                const socket = Net.createConnection({ port, host: '127.0.0.1' });
+                socket.on('connect', () => {
+                    socket.destroy();
+                    resolve();
+                });
+                socket.on('error', reject);
+                socket.setTimeout(1000, () => {
+                    socket.destroy();
+                    reject(new Error('Connection timeout'));
+                });
+            });
+            return;
+        }
+        catch {
+            await new Promise((resolve) => setTimeout(resolve, delay));
+            delay = Math.min(delay * 1.5, 500);
+        }
+    }
+    throw new Error(`Timeout waiting for port ${port} to become available`);
+}
 export class RecordingProxy {
     rustProxy;
     inventoryRepository;
     entryUrl;
     deviceType;
     requestedPort;
+    excludePatterns;
     dependency;
     constructor(options, dependency) {
         options ||= {};
@@ -18,16 +65,30 @@ export class RecordingProxy {
         this.deviceType = options.deviceType;
         // Port
         this.requestedPort = options.port;
+        // Exclude patterns
+        this.excludePatterns = options.excludePatterns;
     }
     async start() {
         this.dependency.logger?.info(`Starting recording proxy...`);
         const proxyPort = this.requestedPort || 0;
-        this.rustProxy = await startRecording({
-            entryUrl: this.entryUrl,
-            deviceType: this.deviceType,
-            inventoryDir: this.inventoryRepository.dirPath,
-            port: proxyPort,
-        });
+        if (this.excludePatterns && this.excludePatterns.length > 0) {
+            // Use direct binary spawn to support -x exclude patterns
+            this.rustProxy = await startRecordingWithExclude({
+                entryUrl: this.entryUrl,
+                deviceType: this.deviceType,
+                inventoryDir: this.inventoryRepository.dirPath,
+                port: proxyPort,
+                excludePatterns: this.excludePatterns,
+            });
+        }
+        else {
+            this.rustProxy = await startRecording({
+                entryUrl: this.entryUrl,
+                deviceType: this.deviceType,
+                inventoryDir: this.inventoryRepository.dirPath,
+                port: proxyPort,
+            });
+        }
         this.dependency.logger?.info(`Recording proxy started on port ${this.rustProxy.port}`);
     }
     get port() {
@@ -51,6 +112,62 @@ export class RecordingProxy {
         }
     }
 }
+function getProxyBinaryPath() {
+    const require = createRequire(import.meta.url);
+    // Resolve the main entry point (which is allowed by exports) and derive package root
+    const mainPath = require.resolve('rust-http-playback-proxy');
+    // mainPath is like .../node_modules/rust-http-playback-proxy/dist/index.js
+    const pkgDir = Path.resolve(Path.dirname(mainPath), '..');
+    const platform = process.platform === 'win32' ? 'windows' : process.platform;
+    const arch = process.arch;
+    const ext = process.platform === 'win32' ? '.exe' : '';
+    return Path.join(pkgDir, 'bin', `${platform}-${arch}`, `http-playback-proxy${ext}`);
+}
+async function startRecordingWithExclude(options) {
+    const binaryPath = getProxyBinaryPath();
+    let port;
+    if (options.port === undefined || options.port === 0) {
+        port = await getAvailablePort();
+    }
+    else {
+        port = options.port;
+    }
+    const deviceType = options.deviceType || 'mobile';
+    const inventoryDir = options.inventoryDir || './inventory';
+    const args = ['recording'];
+    if (options.entryUrl) {
+        args.push(options.entryUrl);
+    }
+    args.push('--port', port.toString());
+    args.push('--device', deviceType);
+    args.push('--inventory', inventoryDir);
+    for (const pattern of options.excludePatterns) {
+        args.push('--exclude', pattern);
+    }
+    const proc = spawn(binaryPath, args, {
+        stdio: ['ignore', 'inherit', 'inherit'],
+        detached: false,
+    });
+    const proxy = new RustProxy('recording', port, inventoryDir, options.entryUrl, deviceType);
+    proxy.setProcess(proc);
+    let exited = false;
+    proc.on('exit', (code) => {
+        exited = true;
+        if (code !== 0 && code !== null) {
+            console.error(`Proxy process exited early with code ${code}`);
+        }
+    });
+    try {
+        await waitForPort(port, 15000);
+    }
+    catch (err) {
+        if (exited) {
+            throw new Error('Proxy process exited before port became available');
+        }
+        throw err;
+    }
+    return proxy;
+}
 export async function withRecordingProxy(options, dependency, cb) {
     const proxy = new RecordingProxy(options, dependency);
     await proxy.start();
@@ -61,4 +178,4 @@ export async function withRecordingProxy(options, dependency, cb) {
         await proxy.stop();
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVjb3JkaW5nLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3JlY29yZGluZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQXNCLGNBQWMsRUFBRSxNQUFNLDBCQUEwQixDQUFBO0FBRTdFLE9BQU8sRUFBRSxtQkFBbUIsRUFBRSxNQUFNLGdCQUFnQixDQUFBO0FBWXBELE1BQU0sT0FBTyxjQUFjO0lBQ3pCLFNBQVMsQ0FBWTtJQUNyQixtQkFBbUIsQ0FBc0I7SUFDekMsUUFBUSxDQUFTO0lBQ2pCLFVBQVUsQ0FBYTtJQUN2QixhQUFhLENBQVM7SUFDdEIsVUFBVSxDQUEwQjtJQUVwQyxZQUFZLE9BQStCLEVBQUUsVUFBcUM7UUFDaEYsT0FBTyxLQUFLLEVBQUUsQ0FBQTtRQUNkLElBQUksQ0FBQyxVQUFVLEdBQUcsVUFBVSxJQUFJLEVBQUUsQ0FBQTtRQUVsQyx1QkFBdUI7UUFDdkIsSUFBSSxDQUFDLG1CQUFtQixHQUFHLE9BQU8sQ0FBQyxtQkFBbUIsSUFBSSxJQUFJLG1CQUFtQixDQUFDLFNBQVMsRUFBRSxJQUFJLENBQUMsVUFBVSxDQUFDLENBQUE7UUFFN0csWUFBWTtRQUNaLElBQUksQ0FBQyxRQUFRLEdBQUcsT0FBTyxDQUFDLFFBQVEsQ0FBQTtRQUVoQyxjQUFjO1FBQ2QsSUFBSSxDQUFDLFVBQVUsR0FBRyxPQUFPLENBQUMsVUFBVSxDQUFBO1FBRXBDLE9BQU87UUFDUCxJQUFJLENBQUMsYUFBYSxHQUFHLE9BQU8sQ0FBQyxJQUFJLENBQUE7SUFDbkMsQ0FBQztJQUVELEtBQUssQ0FBQyxLQUFLO1FBQ1QsSUFBSSxDQUFDLFVBQVUsQ0FBQyxNQUFNLEVBQUUsSUFBSSxDQUFDLDZCQUE2QixDQUFDLENBQUE7UUFFM0QsTUFBTSxTQUFTLEdBQUcsSUFBSSxDQUFDLGFBQWEsSUFBSSxDQUFDLENBQUE7UUFFekMsSUFBSSxDQUFDLFNBQVMsR0FBRyxNQUFNLGNBQWMsQ0FBQztZQUNwQyxRQUFRLEVBQUUsSUFBSSxDQUFDLFFBQVE7WUFDdkIsVUFBVSxFQUFFLElBQUksQ0FBQyxVQUFVO1lBQzNCLFlBQVksRUFBRSxJQUFJLENBQUMsbUJBQW1CLENBQUMsT0FBTztZQUM5QyxJQUFJLEVBQUUsU0FBUztTQUNoQixDQUFDLENBQUE7UUFFRixJQUFJLENBQUMsVUFBVSxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsbUNBQW1DLElBQUksQ0FBQyxTQUFTLENBQUMsSUFBSSxFQUFFLENBQUMsQ0FBQTtJQUN4RixDQUFDO0lBRUQsSUFBSSxJQUFJO1FBQ04sSUFBSSxDQUFDLElBQUksQ0FBQyxTQUFTO1lBQUUsTUFBTSxJQUFJLEtBQUssQ0FBQyxtQkFBbUIsQ0FBQyxDQUFBO1FBQ3pELE9BQU8sSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLENBQUE7SUFDNUIsQ0FBQztJQUVELElBQUksZ0JBQWdCO1FBQ2xCLE9BQU8sSUFBSSxDQUFDLG1CQUFtQixDQUFDLE9BQU8sQ0FBQTtJQUN6QyxDQUFDO0lBRUQsS0FBSyxDQUFDLElBQUk7UUFDUixJQUFJLElBQUksQ0FBQyxTQUFTLEVBQUUsQ0FBQztZQUNuQixJQUFJLENBQUMsVUFBVSxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMsNkJBQTZCLENBQUMsQ0FBQTtZQUUzRCxzRUFBc0U7WUFDdEUsNkVBQTZFO1lBQzdFLE1BQU0sSUFBSSxDQUFDLFNBQVMsQ0FBQyxJQUFJLEVBQUUsQ0FBQTtZQUUzQiwwREFBMEQ7WUFDMUQscUVBQXFFO1lBQ3JFLE1BQU0sSUFBSSxPQUFPLENBQUMsQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLFVBQVUsQ0FBQyxPQUFPLEVBQUUsSUFBSSxDQUFDLENBQUMsQ0FBQTtZQUV6RCxJQUFJLENBQUMsVUFBVSxDQUFDLE1BQU0sRUFBRSxJQUFJLENBQUMseUJBQXlCLENBQUMsQ0FBQTtRQUN6RCxDQUFDO0lBQ0gsQ0FBQztDQUNGO0FBRUQsTUFBTSxDQUFDLEtBQUssVUFBVSxrQkFBa0IsQ0FDdEMsT0FBOEIsRUFDOUIsVUFBb0MsRUFDcEMsRUFBNEM7SUFFNUMsTUFBTSxLQUFLLEdBQUcsSUFBSSxjQUFjLENBQUMsT0FBTyxFQUFFLFVBQVUsQ0FBQyxDQUFBO0lBQ3JELE1BQU0sS0FBSyxDQUFDLEtBQUssRUFBRSxDQUFBO0lBQ25CLElBQUksQ0FBQztRQUNILE1BQU0sRUFBRSxDQUFDLEtBQUssQ0FBQyxDQUFBO0lBQ2pCLENBQUM7WUFBUyxDQUFDO1FBQ1QsTUFBTSxLQUFLLENBQUMsSUFBSSxFQUFFLENBQUE7SUFDcEIsQ0FBQztBQUNILENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVjb3JkaW5nLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vc3JjL3JlY29yZGluZy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsS0FBSyxFQUFFLE1BQU0sZUFBZSxDQUFBO0FBQ3JDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxRQUFRLENBQUE7QUFDdEMsT0FBTyxHQUFHLE1BQU0sS0FBSyxDQUFBO0FBQ3JCLE9BQU8sSUFBSSxNQUFNLE1BQU0sQ0FBQTtBQUV2QixPQUFPLEVBQUUsS0FBSyxJQUFJLFNBQVMsRUFBRSxjQUFjLEVBQUUsTUFBTSwwQkFBMEIsQ0FBQTtBQUU3RSxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQTtBQWFwRCxLQUFLLFVBQVUsZ0JBQWdCO0lBQzdCLE9BQU8sSUFBSSxPQUFPLENBQUMsQ0FBQyxPQUFPLEVBQUUsTUFBTSxFQUFFLEVBQUU7UUFDckMsTUFBTSxNQUFNLEdBQUcsR0FBRyxDQUFDLFlBQVksRUFBRSxDQUFBO1FBQ2pDLE1BQU0sQ0FBQyxNQUFNLENBQUMsQ0FBQyxFQUFFLFdBQVcsRUFBRSxHQUFHLEVBQUU7WUFDakMsTUFBTSxPQUFPLEdBQUcsTUFBTSxDQUFDLE9BQU8sRUFBRSxDQUFBO1lBQ2hDLElBQUksT0FBTyxJQUFJLE9BQU8sT0FBTyxLQUFLLFFBQVEsRUFBRSxDQUFDO2dCQUMzQyxNQUFNLElBQUksR0FBRyxPQUFPLENBQUMsSUFBSSxDQUFBO2dCQUN6QixNQUFNLENBQUMsS0FBSyxDQUFDLEdBQUcsRUFBRSxDQUFDLE9BQU8sQ0FBQyxJQUFJLENBQUMsQ0FBQyxDQUFBO1lBQ25DLENBQUM7aUJBQU0sQ0FBQztnQkFDTixNQUFNLENBQUMsS0FBSyxDQUFDLEdBQUcsRUFBRSxDQUFDLE1BQU0sQ0FBQyxJQUFJLEtBQUssQ0FBQyx3Q0FBd0MsQ0FBQyxDQUFDLENBQUMsQ0FBQTtZQUNqRixDQUFDO1FBQ0gsQ0FBQyxDQUFDLENBQUE7UUFD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

package/llmdocs/00-guide.md

@@ -0,0 +1,124 @@
+# pagespeed-quest — reference for AI agents
+
+PageSpeed Quest (`psq`) records a real page load through an HTTP proxy, writes
+it to disk as an editable set of files, and replays it with the **original
+timing** reproduced. You then edit those files — the HTML, the CSS, the images,
+even the per-resource latency — replay again, and measure the difference.
+
+The point is that you do **not** need the site's development environment, its
+repository, or a deploy. Any public page can be frozen into a local, editable,
+repeatable copy of itself. A hypothesis like "inlining critical CSS would gain
+0.4s of LCP" becomes something you can answer in minutes, on someone else's
+site, before writing a line of production code.
+
+Recording is powered by [rust-http-playback-proxy]. Measurement is delegated to
+[Lighthouse] (scores and metrics), [loadshow] (a video of the load) and
+[static-webshot] (screenshots and visual diffs). `psq` is the layer that makes
+the recording **editable** and the comparison **repeatable**.
+
+[rust-http-playback-proxy]: https://github.com/ideamans/rust-http-playback-proxy
+[Lighthouse]: https://developer.chrome.com/docs/lighthouse/overview/
+[loadshow]: https://github.com/ideamans/go-loadshow
+[static-webshot]: https://github.com/ideamans/static-webshot
+
+This reference ships inside the package, so `psq llm` always describes the exact
+version installed in the project you are working in.
+
+## Ground rules
+
+1. **Record once. Compare against that recording, never against the live site.**
+   The live site changes between runs; the recording does not. That is the whole
+   value proposition. A "before" measured against the network and an "after"
+   measured against the inventory are not comparable numbers.
+
+2. **Copy the inventory before you edit it.** There is no undo, and the baseline
+   is the thing you are comparing to.
+
+   ```sh
+   cp -r inventory baseline
+   ```
+
+   Then measure either side by pointing `-i` at it. Keep `baseline/` untouched
+   for the rest of the quest.
+
+3. **`-i/--inventory` is a root option — it goes before the subcommand.**
+   `psq -i ./baseline lighthouse playback` works; `psq lighthouse playback -i
+   ./baseline` does not. The same applies one level down: `-a`, `-t`, `-l` and
+   `-c` belong to the `lighthouse` / `loadshow` group, so they go *before*
+   `recording` / `playback`.
+
+4. **`playback` takes no URL.** The entry URL and the device type are stored in
+   the inventory at recording time and reused. If you need to change either,
+   record again.
+
+5. **Lighthouse throttling is deliberately disabled** (`--throttling.*=0`,
+   `cpuSlowdownMultiplier=1`). Timing is reproduced by the proxy, per resource.
+   Re-enabling Lighthouse throttling would apply the penalty twice.
+
+6. **Unmatched requests get a 404.** The playback proxy only serves what is in
+   the inventory. That is deliberate — falling through to the network would make
+   the replay non-deterministic. So a URL you delete from `index.json` becomes a
+   failed request, not a request that never happens. To model "this resource is
+   gone", also remove the reference to it from the HTML.
+
+7. **Treat small deltas as noise.** Even against a fixed recording, Lighthouse
+   varies by a few points and tens of milliseconds run to run. Repeat a
+   measurement before believing a change under ~5% .
+
+## The loop
+
+```sh
+# 1. Freeze the page (writes ./inventory)
+npx psq lighthouse recording https://example.com/
+
+# 2. Keep the untouched copy
+cp -r inventory baseline
+
+# 3. Measure the baseline  → artifacts/summary.md, artifacts/lighthouse.report.html
+npx psq -i ./baseline lighthouse -a ./artifacts-baseline playback
+
+# 4. Edit ./inventory — see chapter "Experiments"
+
+# 5. Measure the edited version
+npx psq lighthouse playback
+
+# 6. Compare artifacts-baseline/summary.md with artifacts/summary.md
+```
+
+`summary.md` is a short Markdown digest (metrics, per-metric scores with their
+Lighthouse weights, traffic by resource type). It is written for exactly this
+comparison — diff the two files rather than opening two HTML reports.
+
+## What lives where
+
+| Path | What it is |
+| --- | --- |
+| `inventory/index.json` | the resource list and every resource's metadata. This is the file the proxy reads |
+| `inventory/contents/<METHOD>/<protocol>/<host>/<path>` | one file per recorded response body |
+| `artifacts/lighthouse.report.html`, `.report.json` | the full Lighthouse report |
+| `artifacts/summary.md` | the digest to diff |
+| `artifacts/lighthouse.digest.png` | score and metrics as an image |
+| `artifacts/loadshow.mp4` | filmstrip video of the load |
+| `artifacts/capture.png`, `capture-diff.png`, `capture-diff.txt` | screenshot and visual diff |
+
+## Failure modes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `playback` serves nothing, every request 404s | the inventory is empty, or `-i` points at the wrong directory | record first; check `inventory/index.json` exists and `resources` is non-empty |
+| `unknown option '-i'` / the option is ignored | root and group options were placed after the subcommand | `psq -i ./baseline lighthouse -a ./art playback` |
+| the "after" is faster but the page is visibly broken | a referenced resource was deleted from `index.json` but not from the HTML | run `psq capture --compare` and look at the diff before trusting any number |
+| edits to a `.js` / `.css` file seem to have no effect on transfer size | the resource has `"minify": true`, so playback re-minifies before serving | expected — the wire size reflects the minified bytes, which is what the original site shipped |
+| the page looks fine but LCP got worse for no reason | an edit changed the byte size of a resource, and transfer time scales with size at the recorded `mbps` | that *is* the simulation working; check `summary.md` traffic figures |
+| recording captured analytics and ad beacons | third parties were not excluded | re-record with `-x 'google-analytics|doubleclick|facebook'` (repeatable) |
+| `loadshow` / `static-webshot` not found | the postinstall step that downloads them did not run | re-run `npm rebuild pagespeed-quest`, or set `LOADSHOW_PATH` / `WEBSHOT_PATH` |
+| Lighthouse cannot be found | it resolves to `./node_modules/.bin/lighthouse` | run inside the quest project, or set `LIGHTHOUSE_PATH` |
+| numbers drift between identical runs | normal measurement noise | repeat; do not act on deltas under ~5% |
+
+## What this tool will not do
+
+- It does not crawl. One entry URL plus whatever that page load requests.
+- It does not modify the live site, and nothing you edit locally reaches it.
+- It does not rewrite your resources for you. Editing the inventory is the
+  work; this reference tells you which edit models which optimization.
+- It does not replay user interaction. What is recorded is one page load.

package/llmdocs/10-inventory.md

@@ -0,0 +1,133 @@
+# The inventory — what you edit
+
+The inventory is the reverse-engineered page. Everything the browser will
+receive during playback comes from here, and nothing else does.
+
+```
+inventory/
+├── index.json                     ← the resource list. THIS is what the proxy reads
+└── contents/
+    └── GET/
+        └── https/
+            └── example.com/
+                ├── index.html
+                ├── assets/app.css
+                ├── assets/app.js
+                └── img/hero.jpg
+```
+
+- **`index.json` is authoritative.** The playback proxy reads exactly that file
+  name. If a file called `inventory.json` also exists (older recordings wrote
+  both names), `psq` will read *that* one for the entry URL, device type and
+  traffic figures while the proxy serves from `index.json` — the two silently
+  disagree. Delete `inventory.json`, or keep it byte-identical.
+- **`contents/` holds one file per response body.** Text bodies are stored
+  decoded, converted to UTF-8 and pretty-printed, so they are diffable and
+  editable by hand.
+
+## How a URL becomes a path
+
+`contents/<METHOD>/<protocol>/<host>/<pathname>`
+
+| URL | File |
+| --- | --- |
+| `https://example.com/` | `contents/GET/https/example.com/index.html` |
+| `https://example.com/assets/app.css` | `contents/GET/https/example.com/assets/app.css` |
+| `https://example.com/api?id=1` | `contents/GET/https/example.com/api~id=1` |
+| `https://cdn.example.com:8443/a.js` | `contents/GET/https/cdn.example.com~8443/a.js` |
+
+Rules: a trailing `/` (or a path with no extension) gets `index.html`; the query
+string is appended after `~`; a colon in the host becomes `~`; an over-long
+basename is truncated and suffixed with a short SHA-1. Do not rename these files
+by hand — the mapping comes from `contentFilePath` in `index.json`, and the file
+name is only a convenience.
+
+## `index.json`
+
+```json
+{
+  "entryUrl": "https://example.com/",
+  "deviceType": "mobile",
+  "resources": [ ... ]
+}
+```
+
+`entryUrl` and `deviceType` are what `playback` uses instead of asking you for a
+URL. Changing `deviceType` here changes the Lighthouse form factor and the
+loadshow preset on the next playback — it does **not** re-record.
+
+### A resource
+
+| Field | Effect at playback time |
+| --- | --- |
+| `method`, `url` | how the request is matched. A request that matches nothing gets a 404 |
+| `ttfbMs` | **the proxy sleeps this long after receiving the request, before the first byte.** Per request, not an offset from page start |
+| `durationMs` | recorded transfer duration. Informational; playback derives its own from size and `mbps` |
+| `mbps` | transfer speed for the body. Missing → 1.0 Mbps |
+| `statusCode` | the status served |
+| `rawHeaders` | headers served, minus `content-length` and `content-encoding`, which are recomputed |
+| `contentEncoding` | `gzip` / `br` / `deflate` / `zstd` / `compress` / `identity`. The body is **re-compressed with this before it goes on the wire**, so it decides the transferred size |
+| `contentTypeMime`, `contentCharset` | the `Content-Type` served. `contentCharset` re-encodes the body from UTF-8 on the way out |
+| `contentFilePath` | the file under `contents/` to serve |
+| `contentUtf8` / `contentBase64` | inline body, used instead of the file when present |
+| `minify` | `true` → the body is **re-minified before serving**. Set during recording when the original was minified |
+| `httpVersion` | protocol version reported for the response |
+
+### The timing model, precisely
+
+```
+response time ≈ ttfbMs  +  (bytes on the wire × 8) / (mbps × 1,000,000)
+```
+
+- `ttfbMs` is a fixed per-request delay. It models server think time plus
+  connection latency. Lower it to model a faster origin or a nearer CDN edge.
+- The second term is recomputed **from the bytes you leave in the file**, after
+  minification and after `contentEncoding` compression. So shrinking a file
+  makes it arrive sooner, automatically, with no other edit.
+- `--full-throttle` (used internally by `psq capture`) skips both. Never compare
+  a full-throttle run with a normal one.
+
+### Two traps worth stating plainly
+
+**`minify: true` re-minifies your edit.** The pretty-printed file in `contents/`
+is for you; the wire sees the minified form. This keeps the byte count honest —
+the original site shipped minified bytes — but it means whitespace edits have no
+size effect, and it means a syntax error introduced during editing can surface
+as a minifier failure rather than a browser error.
+
+**`contentEncoding` decides the transferred size, not the file size.** A 300 KB
+JavaScript file with `"contentEncoding": "br"` is perhaps 60 KB on the wire, and
+that 60 KB is what the timing is computed from. To model "we turned compression
+off", set it to `identity`; to model "we finally enabled Brotli", set it to
+`br`. Do not edit `content-length` — it is recomputed and your value is
+discarded.
+
+## Editing safely
+
+1. Copy `inventory/` to `baseline/` before the first edit.
+2. Change **one thing at a time**, then measure. Two edits in one run means you
+   cannot attribute the delta.
+3. After a structural edit (removing a script, changing a URL), run
+   `psq capture --compare` and look at the picture. A faster broken page is easy
+   to produce and easy to mistake for a win.
+4. Keep the inventory in version control if the quest lasts more than a day.
+   `git diff` over `contents/` is a readable record of the hypothesis.
+
+## Live editing with a browser
+
+```sh
+psq proxy -p 8080
+```
+
+serves the inventory and **watches it**: any change under `inventory/` restarts
+the proxy, so a browser pointed at `http://localhost:8080` picks up your edit on
+the next reload. The proxy uses a dummy certificate, so the browser has to be
+told to accept it:
+
+```sh
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --ignore-certificate-errors --proxy-server=http://localhost:8080
+```
+
+This is the fastest way to iterate on markup edits before spending a Lighthouse
+run on them.