@avivbenhamo/polly-kit 0.8.0 → 0.9.0

package/README.md

@@ -71,7 +71,17 @@ body, so a bare `startPolly()` call in `index.tsx` runs *after* `./App` and ever
 imports — and any module that fires a request at import time would escape interception,
 silently and only sometimes.
 
-Add `/recordings` to `.gitignore`. A HAR holds complete response bodies.
+Add the recordings directory to `.gitignore` — a HAR holds complete response bodies:
+
+```sh
+npx polly-kit init                         # adds /recordings, or /apps/web/recordings
+npx polly-kit init --dir fixtures/har      # when that is not where you record
+```
+
+Run it from the directory the app records in. The entry is anchored at the repository root
+and written out in full — `/apps/web/recordings` from a package inside a monorepo, not
+`/recordings`, which would match nothing there and look like it had. An entry already in the
+file, in any spelling git honours, is left alone; running it twice adds one line.
 
 ## Running it
 
@@ -135,7 +145,7 @@ $env:POLLY_MODE='record'; npm run start:dev
 ```
 
 No Vite plugin and no recording store: `persister-fs` writes the HAR straight to disk.
-Add `/recordings` to `.gitignore`.
+`npx polly-kit init` gitignores the directory.
 
 **Use `{kind: 'only'}`, not `{kind: 'all'}`.** In a browser Polly sees the page's own
 requests. In Node the adapters are process-wide: they also see your service talking to

package/dist/cli.d.ts

@@ -1,5 +1,51 @@
 #!/usr/bin/env node
 export declare function main(argv: string[]): Promise<number>;
+export interface IgnoreOptions {
+    /** Where the command was run. The repository is found by walking up from here. */
+    cwd?: string;
+    /** The recordings directory, as passed to `startPolly`. Default `recordings`. */
+    dir?: string;
+}
+export interface IgnoreResult {
+    /**
+     * `added`   — the entry was appended.
+     * `covered` — a rule already matching the directory was there; nothing written.
+     * `outside` — the directory is not under the repository, so no rule can name it.
+     * `root`    — the directory *is* the repository, which is not something to ignore.
+     */
+    action: 'added' | 'covered' | 'outside' | 'root';
+    /** The `.gitignore` written, or the one that would have been. */
+    path: string;
+    /** The entry, as written or as it would be written. Empty when `outside`. */
+    entry: string;
+    /** The repository root this was resolved against. */
+    root: string;
+    /** The recordings directory, absolute. */
+    recordingsDir: string;
+}
+/**
+ * Adds the recordings directory to the repository's `.gitignore`.
+ *
+ * Two things here are deliberate and were the reason for the command.
+ *
+ * The entry is anchored at the repository root and spelled out in full —
+ * `/apps/web/recordings`, not `/recordings` — because the recordings directory
+ * is configured in the app's own code and so lives wherever the app does. A bare
+ * `/recordings` at the root of a monorepo matches nothing in `apps/web`, and the
+ * failure is silent: the file looks like it handled them and the HARs get
+ * committed anyway.
+ *
+ * Coverage is checked against every spelling git would honour, because the entry
+ * has been written by hand from the README for longer than this command has
+ * existed, and this package's own docs have asked for it as both `/recordings`
+ * and `recordings/`. `recordings` and `recordings/` have no leading slash, so git
+ * matches them at any depth and they already cover the directory — appending a
+ * second rule under one of them is a duplicate somebody then has to delete.
+ *
+ * Negated (`!recordings`) and commented-out entries are not coverage. Reading
+ * either as "already handled" would leave the recordings committed.
+ */
+export declare function ignoreRecordings(options?: IgnoreOptions): IgnoreResult;
 export interface StudioOptions {
     recordingsDir: string;
     port?: number;

package/dist/cli.js

@@ -1,6 +1,10 @@
 #!/usr/bin/env node
 /**
- * The studio, served on its own, for a checkout with no app running.
+ * The two things that are done to a checkout rather than inside an app: serving
+ * the studio with no app running (`studio`), and keeping the recordings out of
+ * git (`init`).
+ *
+ * On `init`, see `ignoreRecordings`. The rest of this is the studio.
  *
  * The mounted form stays the default and is the better one when there *is* a dev
  * server: `app.use('/__polly', pollyUi(...))` — or the Vite plugin, which does
@@ -18,8 +22,8 @@
  * see those.
  */
 import { createServer } from 'node:http';
-import { existsSync } from 'node:fs';
-import { isAbsolute, join, resolve } from 'node:path';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { pollyUi } from './studio/server.js';
 const DEFAULT_PORT = 7788;
@@ -33,11 +37,16 @@ const PORT_TRIES = 20;
 const USAGE = `polly-kit — Polly recordings, in a browser
 
   npx polly-kit studio [--dir DIR] [--port PORT]
+  npx polly-kit init [--dir DIR]
 
   studio    Serve the recording editor on 127.0.0.1. Reads and writes the HAR
             files under DIR (default ${DEFAULT_DIR}), the same ones the mounted
             editor edits.
 
+  init      Add DIR to the repository's .gitignore. A HAR holds complete
+            request and response bodies, so recordings are not something to
+            commit by accident. Safe to run twice.
+
 Mounted in a dev server instead — no second port, and it stops when the server
 does — this is the Vite plugin, or app.use('/__polly', pollyUi({recordingsDir})).
 Recordings held in a browser's localStorage are reachable only from the page
@@ -49,6 +58,24 @@ export async function main(argv) {
         process.stdout.write(USAGE);
         return 0;
     }
+    if (command === 'init' || command === 'setup') {
+        const result = ignoreRecordings({ dir: flag(argv, 'dir') });
+        // Every outcome is exit 0. This runs from a README in some trees and from a
+        // postinstall in others, and "already done" is the steady state in both.
+        if (result.action === 'added') {
+            process.stdout.write(`added to ${result.path}: ${result.entry}\n`);
+        }
+        else if (result.action === 'covered') {
+            process.stdout.write(`${result.entry} is already ignored by ${result.path}\n`);
+        }
+        else if (result.action === 'root') {
+            process.stdout.write(`${result.root} is the repository root, not a recordings directory — pass --dir\n`);
+        }
+        else {
+            process.stdout.write(`${result.recordingsDir} is outside ${result.root} — nothing to ignore there\n`);
+        }
+        return 0;
+    }
     if (command !== 'studio') {
         process.stderr.write(`unknown command: ${command}\n\n${USAGE}`);
         return 2;
@@ -79,6 +106,93 @@ export async function main(argv) {
     await studio.close();
     return 0;
 }
+const IGNORE_COMMENT = '# @avivbenhamo/polly-kit: recorded traffic. A HAR holds complete request and\n# response bodies, including anything the responses carried.';
+/**
+ * Adds the recordings directory to the repository's `.gitignore`.
+ *
+ * Two things here are deliberate and were the reason for the command.
+ *
+ * The entry is anchored at the repository root and spelled out in full —
+ * `/apps/web/recordings`, not `/recordings` — because the recordings directory
+ * is configured in the app's own code and so lives wherever the app does. A bare
+ * `/recordings` at the root of a monorepo matches nothing in `apps/web`, and the
+ * failure is silent: the file looks like it handled them and the HARs get
+ * committed anyway.
+ *
+ * Coverage is checked against every spelling git would honour, because the entry
+ * has been written by hand from the README for longer than this command has
+ * existed, and this package's own docs have asked for it as both `/recordings`
+ * and `recordings/`. `recordings` and `recordings/` have no leading slash, so git
+ * matches them at any depth and they already cover the directory — appending a
+ * second rule under one of them is a duplicate somebody then has to delete.
+ *
+ * Negated (`!recordings`) and commented-out entries are not coverage. Reading
+ * either as "already handled" would leave the recordings committed.
+ */
+export function ignoreRecordings(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const dir = options.dir ?? DEFAULT_DIR;
+    const recordingsDir = isAbsolute(dir) ? resolve(dir) : resolve(cwd, dir);
+    // No git command is run: `.git` is a directory in a normal checkout and a file
+    // in a worktree or submodule, and either one marks the root. Falling back to
+    // cwd covers the directory that is not a repository yet.
+    const root = gitRoot(cwd) ?? resolve(cwd);
+    const path = join(root, '.gitignore');
+    const within = relative(root, recordingsDir);
+    if (within === '') {
+        return { action: 'root', path, entry: '', root, recordingsDir };
+    }
+    if (within.startsWith('..') || isAbsolute(within)) {
+        return { action: 'outside', path, entry: '', root, recordingsDir };
+    }
+    const entry = `/${within.split(sep).join('/')}`;
+    const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+    if (covers(existing, entry)) {
+        return { action: 'covered', path, entry, root, recordingsDir };
+    }
+    // The file's own line ending, not the platform's: git on Windows checks out a
+    // CRLF `.gitignore`, and appending LF lines to it shows the whole file as
+    // changed in the diff.
+    const eol = existing.includes('\r\n') ? '\r\n' : '\n';
+    const lead = existing === '' || /(\r?\n){2}$/.test(existing)
+        ? ''
+        : /\r?\n$/.test(existing)
+            ? eol
+            : `${eol}${eol}`;
+    const block = `${IGNORE_COMMENT}\n${entry}\n`.replace(/\n/g, eol);
+    writeFileSync(path, `${existing}${lead}${block}`, 'utf8');
+    return { action: 'added', path, entry, root, recordingsDir };
+}
+/** Nearest ancestor of `from` holding a `.git`, itself included. */
+function gitRoot(from) {
+    let at = resolve(from);
+    for (;;) {
+        if (existsSync(join(at, '.git')))
+            return at;
+        const up = dirname(at);
+        if (up === at)
+            return undefined;
+        at = up;
+    }
+}
+/** Does any rule in `contents` already ignore `entry` (`/a/b/recordings`)? */
+function covers(contents, entry) {
+    const wanted = entry.replace(/^\/+/, '').replace(/\/+$/, '');
+    const leaf = wanted.slice(wanted.lastIndexOf('/') + 1);
+    return contents.split(/\r?\n/).some((raw) => {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#') || line.startsWith('!'))
+            return false;
+        // A leading `**/` is git's explicit spelling of "at any depth", which is
+        // what a bare name means anyway.
+        const rule = line.replace(/^\*\*\//, '').replace(/^\/+/, '').replace(/\/+$/, '');
+        // Anchored by a leading slash, or by a slash anywhere inside it: git matches
+        // those against the path from the .gitignore's own directory, so it has to be
+        // the same path. Otherwise the rule matches at every depth and the last
+        // segment of the path is enough.
+        return line.startsWith('/') || rule.includes('/') ? rule === wanted : rule === leaf;
+    });
+}
 /**
  * The server, without the process around it.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avivbenhamo/polly-kit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Drop-in record/replay of an app's HTTP traffic with Polly.JS, plus the polly-studio editor. Bring your own host policy.",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,7 @@
     "dist",
     "README.md"
   ],
-  "//bin": "The studio on its own, for a checkout with no dev server to mount it in. The mounted form stays the default.",
+  "//bin": "`studio` on its own, for a checkout with no dev server to mount it in — the mounted form stays the default — and `init`, which gitignores the recordings directory.",
   "bin": {
     "polly-kit": "./dist/cli.js"
   },