api-tracer-kit 1.0.0 → 1.1.0

package/cli/setup.mjs

@@ -0,0 +1,182 @@
+/**
+ * `api-tracer setup` — wire the tracer into an application.
+ *
+ * Writing this file by hand is three decisions people get wrong: where the
+ * entry point is, which environment flag the bundler will actually fold, and
+ * that `init()` must be called from exactly one place. So the command makes all
+ * three, and is safe to re-run.
+ */
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative, dirname } from 'node:path';
+
+/** the frameworks we can tell apart, and how each one gates a dev-only import */
+const FRAMEWORKS = {
+  cra: {
+    label: 'Create React App',
+    /*
+     * REACT_APP_ENV, not NODE_ENV: a dev or stage deploy is a production build,
+     * so gating on NODE_ENV would compile the tracer out of exactly the
+     * environments it is meant for. Compared directly rather than through a
+     * variable so DefinePlugin substitutes the literal and the branch folds.
+     */
+    gate: `const isEnabled =\n  process.env.REACT_APP_ENV === "dev" || process.env.REACT_APP_ENV === "stage";`,
+    envLabel: 'process.env.REACT_APP_ENV',
+    consoleUrl: `process.env.REACT_APP_API_CONSOLE_URL ||\n  process.env.REACT_APP_TRACKER_URL ||\n  "http://localhost:4400"`,
+    entries: ['src/index.js', 'src/index.jsx', 'src/index.tsx', 'src/index.ts'],
+  },
+  vite: {
+    label: 'Vite',
+    gate: `const isEnabled = import.meta.env.DEV;`,
+    envLabel: 'import.meta.env.MODE',
+    consoleUrl: `import.meta.env.VITE_API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['src/main.ts', 'src/main.tsx', 'src/main.js', 'src/main.jsx'],
+  },
+  next: {
+    label: 'Next.js',
+    gate: `const isEnabled = process.env.NODE_ENV === "development";`,
+    envLabel: 'process.env.NODE_ENV',
+    consoleUrl: `process.env.NEXT_PUBLIC_API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['app/layout.tsx', 'app/layout.jsx', 'pages/_app.tsx', 'pages/_app.jsx', 'pages/_app.js'],
+  },
+  node: {
+    label: 'Node / plain JavaScript',
+    gate: `const isEnabled = process.env.NODE_ENV !== "production";`,
+    envLabel: 'process.env.NODE_ENV',
+    consoleUrl: `process.env.API_CONSOLE_URL || "http://localhost:4400"`,
+    entries: ['src/index.js', 'src/index.ts', 'index.js', 'index.mjs', 'src/main.js'],
+  },
+};
+
+/** which framework this project is, from what it actually depends on */
+export function detectFramework(root) {
+  let pkg = {};
+  try {
+    pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  } catch {
+    return 'node';
+  }
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (deps.next) return 'next';
+  if (deps['react-scripts']) return 'cra';
+  if (deps.vite) return 'vite';
+  return 'node';
+}
+
+export const usesAxios = (root) => {
+  try {
+    const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.axios);
+  } catch {
+    return false;
+  }
+};
+
+export const usesTypeScript = (root) =>
+  existsSync(join(root, 'tsconfig.json'));
+
+/** the first entry file that exists, so the import lands somewhere that runs */
+export function findEntry(root, framework) {
+  for (const candidate of FRAMEWORKS[framework].entries) {
+    if (existsSync(join(root, candidate))) return candidate;
+  }
+  return null;
+}
+
+/**
+ * The module that does the wiring. It is a file rather than a line in the entry
+ * point so that the gate, the console URL and the axios hand-over live together
+ * and are obvious to the next person.
+ */
+export function recorderSource({ framework, axios, envelope }) {
+  const f = FRAMEWORKS[framework];
+  const importAxios = axios ? 'import axios from "axios";\n' : '';
+  const attachAxios = axios
+    ? `  apiTracer.useAxios(axios);\n`
+    : '';
+  const transports = axios
+    ? `    // axios is attached below; the XHR it rides on must not be traced twice\n    transports: [],\n`
+    : '';
+  const envelopeLine = envelope
+    ? `    // this API answers 200 and puts the real verdict in the envelope\n    envelope: { codeFields: ["status", "code"], okField: "success", failFrom: 400 },\n`
+    : '';
+
+  return `/**
+ * Streams every API call this app makes to the API console.
+ *
+ * Generated by \`api-tracer setup\`. Imported once from the entry point.
+ *
+ * This is the only place the tracer is configured. \`init()\` is idempotent: a
+ * second call from somewhere else keeps this configuration and warns about the
+ * options it ignored, which is a confusing way to find out you have two.
+ *
+ * Credentials never leave the browser -- header values and credential-looking
+ * fields are replaced before anything is posted.
+ */
+${importAxios}import { apiTracer } from "api-tracer-kit";
+
+const CONSOLE_URL =
+  ${f.consoleUrl};
+
+${f.gate}
+
+if (isEnabled) {
+  apiTracer.init({
+    reportTo: CONSOLE_URL,
+${envelopeLine}${transports}  });
+${attachAxios}  // eslint-disable-next-line no-console
+  console.info(\`[api-tracer] \${${f.envLabel}}: streaming API calls to \${CONSOLE_URL}\`);
+}
+
+export default isEnabled;
+`;
+}
+
+/** adds the import to the entry file, after the last import already there */
+export function addImport(source, specifier) {
+  if (source.includes(specifier)) return { source, added: false };
+
+  const lines = source.split('\n');
+  let last = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^\s*(import\s|const\s+\w+\s*=\s*require\()/.test(lines[i])) last = i;
+    // stop at the first real statement: a later import is inside a function
+    if (last !== -1 && /^\s*(function|class|export default|ReactDOM|createRoot)/.test(lines[i])) break;
+  }
+
+  const line = `import "${specifier}";`;
+  const comment = '// dev only: streams API calls to the console, dropped from a production build';
+  if (last === -1) lines.unshift(comment, line, '');
+  else lines.splice(last + 1, 0, comment, line);
+
+  return { source: lines.join('\n'), added: true };
+}
+
+/** the tracer must be configured in one place; find anyone else doing it */
+export function findExistingInits(root, files) {
+  const hits = [];
+  for (const file of files) {
+    try {
+      const text = readFileSync(join(root, file), 'utf8');
+      if (/\bapiTracer\s*\.\s*init\s*\(|\binitApiTracer\s*\(/.test(text)) hits.push(file);
+    } catch {
+      /* unreadable file is not a conflict */
+    }
+  }
+  return hits;
+}
+
+export function ensureGitignore(root) {
+  const file = join(root, '.gitignore');
+  let text = '';
+  try {
+    text = readFileSync(file, 'utf8');
+  } catch {
+    /* no .gitignore yet */
+  }
+  if (/^\.api-tracer\/?$/m.test(text)) return false;
+  const addition = `${text.endsWith('\n') || !text ? '' : '\n'}\n# api-tracer-kit console captures: real request and response bodies\n.api-tracer/\n`;
+  writeFileSync(file, text + addition);
+  return true;
+}
+
+export { FRAMEWORKS };

package/cli/test.mjs

@@ -14,6 +14,7 @@ import { guessAuth, guessBaseUrls, guessPreset, collectFiles, defaults } from '.
 import { importHar, importCurl, matchEndpoint, parseQuery, toComparablePath } from './import.mjs';
 import { shapeOf, diffShapes, summarizeDrift } from './shape.mjs';
 import { buildReport, toMarkdown } from './report.mjs';
+import { addImport, detectFramework, findEntry, findExistingInits, recorderSource, usesAxios, usesTypeScript } from './setup.mjs';
 
 let checks = 0;
 const check = (name, fn) => {
@@ -335,6 +336,102 @@ check('the markdown export renders without a run history', () => {
   assert.match(md, /Standard `X_AUTH`/);
 });
 
+/* --- setup: wiring the tracer into an app ----------------------------- */
+
+const app = (deps, files) => {
+  const dir = mkdtempSync(join(tmpdir(), 'api-tracer-setup-'));
+  mkdirSync(join(dir, 'src'), { recursive: true });
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'x', dependencies: deps }));
+  for (const [name, text] of Object.entries(files)) {
+    mkdirSync(join(dir, name.split('/').slice(0, -1).join('/') || '.'), { recursive: true });
+    writeFileSync(join(dir, name), text);
+  }
+  return dir;
+};
+
+check('the framework is detected from what the project depends on', () => {
+  assert.equal(detectFramework(app({ 'react-scripts': '5' }, {})), 'cra');
+  assert.equal(detectFramework(app({ vite: '5' }, {})), 'vite');
+  assert.equal(detectFramework(app({ next: '14' }, {})), 'next');
+  assert.equal(detectFramework(app({}, {})), 'node');
+  // Next ships React too, so the more specific answer has to win
+  assert.equal(detectFramework(app({ next: '14', react: '18' }, {})), 'next');
+});
+
+check('axios and TypeScript are detected rather than assumed', () => {
+  assert.equal(usesAxios(app({ axios: '1' }, {})), true);
+  assert.equal(usesAxios(app({}, {})), false);
+  assert.equal(usesTypeScript(app({}, { 'tsconfig.json': '{}' })), true);
+  assert.equal(usesTypeScript(app({}, {})), false);
+});
+
+check('the entry file is the first one that actually exists', () => {
+  assert.equal(findEntry(app({}, { 'src/index.js': '' }), 'cra'), 'src/index.js');
+  assert.equal(findEntry(app({}, { 'src/main.tsx': '' }), 'vite'), 'src/main.tsx');
+  assert.equal(findEntry(app({}, { 'pages/_app.tsx': '' }), 'next'), 'pages/_app.tsx');
+  assert.equal(findEntry(app({}, {}), 'cra'), null, 'a project with no entry says so');
+});
+
+check('the CRA gate folds away in a production build', () => {
+  const src = recorderSource({ framework: 'cra', axios: true, envelope: true });
+  // compared directly, not through a variable, so DefinePlugin can substitute it
+  assert.match(src, /process\.env\.REACT_APP_ENV === "dev"/);
+  assert.ok(!/NODE_ENV/.test(src), 'NODE_ENV would compile it out of dev and stage deploys');
+});
+
+check('axios is attached only when the project uses it', () => {
+  assert.match(recorderSource({ framework: 'cra', axios: true }), /useAxios\(axios\)/);
+  assert.match(recorderSource({ framework: 'cra', axios: true }), /transports: \[\]/);
+  const without = recorderSource({ framework: 'cra', axios: false });
+  assert.ok(!/useAxios/.test(without));
+  assert.ok(!/from "axios"/.test(without), 'no import of a package that is not there');
+});
+
+check('each framework gets the gate and env convention that works for it', () => {
+  assert.match(recorderSource({ framework: 'vite', axios: false }), /import\.meta\.env\.DEV/);
+  assert.match(recorderSource({ framework: 'vite', axios: false }), /VITE_API_CONSOLE_URL/);
+  assert.match(recorderSource({ framework: 'next', axios: false }), /NEXT_PUBLIC_API_CONSOLE_URL/);
+  assert.match(recorderSource({ framework: 'node', axios: false }), /NODE_ENV !== "production"/);
+});
+
+check('the envelope is included unless the API is said not to need it', () => {
+  assert.match(recorderSource({ framework: 'cra', axios: false, envelope: true }), /envelope:/);
+  assert.ok(!/envelope:/.test(recorderSource({ framework: 'cra', axios: false, envelope: false })));
+});
+
+check('the import goes in after the last top-level import', () => {
+  const entry = 'import React from "react";\nimport App from "./App";\n\nReactDOM.render(<App />, root);\n';
+  const { source, added } = addImport(entry, './apiTracer');
+  assert.equal(added, true);
+  const lines = source.split('\n');
+  assert.match(lines[2], /^\/\//, 'a comment explains why it is there');
+  assert.equal(lines[3], 'import "./apiTracer";');
+  assert.ok(source.indexOf('import "./apiTracer"') < source.indexOf('ReactDOM.render'));
+});
+
+check('running setup twice does not import twice', () => {
+  const entry = 'import React from "react";\n';
+  const once = addImport(entry, './apiTracer').source;
+  const twice = addImport(once, './apiTracer');
+  assert.equal(twice.added, false);
+  assert.equal(twice.source, once);
+});
+
+check('an entry file with no imports still gets one', () => {
+  const { source, added } = addImport('console.log("hi");\n', './apiTracer');
+  assert.equal(added, true);
+  assert.match(source.split('\n')[1], /^import "/);
+});
+
+check('a stray init() somewhere else is found and reported', () => {
+  const dir = app({}, {
+    'src/services/index.js': 'import { apiTracer } from "api-tracer-kit";\napiTracer.init();\n',
+    'src/clean.js': 'export const x = 1;\n',
+  });
+  const found = findExistingInits(dir, ['src/services/index.js', 'src/clean.js', 'src/missing.js']);
+  assert.deepEqual(found, ['src/services/index.js'], 'the exact mistake that leaves a tracer reporting nowhere');
+});
+
 rmSync(project, { recursive: true, force: true });
 rmSync(other, { recursive: true, force: true });
 rmSync(fetchy, { recursive: true, force: true });

package/cli/web/app.css

@@ -158,8 +158,7 @@ header {
   border-right: 1px solid var(--line);
 }
 .brand .logo {
-  /* the app's own wordmark (public/images/conx.svg, the white-ink variant --
-     conx-dark.svg is dark ink, meant for light backgrounds) */
+  /* logo.svg, drawn with currentColor so it inherits the header's ink */
   height: 26px;
   width: auto;
   display: block;

package/dist/axios.cjs

@@ -687,6 +687,13 @@ function createReporter(baseUrl) {
 
 // src/core/tracer.ts
 var DEFAULT_REPORT_URL = "http://localhost:4400";
+function warnIgnoredOptions(options) {
+  const ignored = Object.keys(options).filter((k) => k !== "onTrace");
+  if (!ignored.length) return;
+  console.warn(
+    `[api-tracer] init() was called again on a tracer that is already running, so these options were ignored: ${ignored.join(", ")}. The configuration from the first init() is still in effect. Configure the tracer in one place, or call destroy() before re-initialising.`
+  );
+}
 var ApiTracer = class {
   constructor() {
     this.storage = new MemoryTraceStorage();
@@ -712,6 +719,7 @@ var ApiTracer = class {
   init(options = {}) {
     if (this.started) {
       if (options.onTrace) this.subscribe(options.onTrace);
+      warnIgnoredOptions(options);
       return this;
     }
     this.options = {