@hunt-labs/bytekit-cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -10,6 +10,30 @@ today, see [README.md](./README.md), which remains the authoritative usage guide
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-11
+
+### Added
+
+- **Every outgoing request now carries `X-ByteKit-Client: cli/<version>`.** The CLI identifies
+  itself with the sanctioned `client_surface` marker (issue #2906, slice 3 of #2701), so `bytekit`
+  usage is distinguishable in ByteKit's own analytics from both raw API calls (`api_direct`) and
+  programmatic `@hunt-labs/bytekit-sdk` usage (`sdk_ts`) instead of being counted as one of them.
+  `cli` is a member of the closed `client_surface` vocabulary declared in issue #2904; the version
+  affix is this package's own version, resolved from `package.json` at runtime — the same value
+  `bytekit --version` prints.
+
+  Set at exactly ONE place — the header literal inside the private transport core all three CLI
+  transports funnel through — so it rides on every command, on the JSON path, on the raw
+  `/v1/fetch` path, and on the 429 retry attempt alike. **Nothing else about a request changed:**
+  same `Authorization` and `Content-Type`, same body bytes, same per-attempt abort budget, same
+  single-retry 429 behavior, same error taxonomy, same exit codes and output shapes. The marker
+  carries no user data and cannot be set, overridden or read from the command line — `--headers`
+  is a _scrape_ option that travels in the request body to the captured site, and never touches
+  the CLI's own request headers.
+
+  Minor rather than patch because the wire format of every request changes, even though no
+  documented command behavior does. A gateway that does not yet recognize the header ignores it.
+
 ## [0.7.1] - 2026-08-10
 
 ### Changed

package/dist/client.js

@@ -1,4 +1,5 @@
 import { ByteKit, ByteKitError, ByteKitConnectionError } from '@hunt-labs/bytekit-sdk';
+import { PACKAGE_VERSION } from './package-version.js';
 /**
  * The API host the SDK itself defaults to. The SDK's copy is module-private, so the CLI declares
  * its own and always passes an explicit `baseUrl` to the constructor — that way the SDK client and
@@ -289,6 +290,26 @@ async function sendWithRetry(apiKey, baseUrl, timeoutMs, method, path, body, rea
             headers: {
                 Authorization: `Bearer ${apiKey}`,
                 'Content-Type': 'application/json',
+                // The `client_surface` marker (issue #2906, slice 3 of #2701). THE CLI'S ONLY EMIT SITE:
+                // all three CLI transports funnel through this function, and this literal is rebuilt
+                // inside the retry loop, so the 429 retry attempt carries it too (E4) without a second
+                // site to keep in sync.
+                //
+                // The header name below (`CLIENT_SURFACE_HEADER`) and the closed surface vocabulary
+                // (`CLIENT_SURFACES`) are declared in `@bytekit/analytics-contract` — deliberately spelled
+                // as literals here rather than imported, because that package must never become a runtime
+                // dependency of the published CLI (#2906 E6). `__tests__/client-surface-marker.test.ts`
+                // imports the contract as a TEST-ONLY devDependency and binds these literals to the
+                // registry, which is what keeps the two from drifting.
+                //
+                // Grep gate 1 (#2906) counts occurrences of the header name in `src/` outside tests and
+                // expects exactly ONE — so this comment names the CONSTANT rather than re-spelling the
+                // string, and the single occurrence below is the emit site itself.
+                //
+                // The version affix comes from the package manifest via the shared `PACKAGE_VERSION`
+                // helper — the same value commander reports for `--version` — never a second hardcoded
+                // version string.
+                'X-ByteKit-Client': `cli/${PACKAGE_VERSION}`,
             },
         };
         if (body !== undefined) {

package/dist/index.js

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import { realpathSync } from 'node:fs';
-import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { makeScrapeCommand } from './commands/scrape.js';
 import { makeScreenshotsCommand } from './commands/screenshots.js';
@@ -13,12 +12,10 @@ import { makeSearchCommand } from './commands/search.js';
 import { makeAccountCommand } from './commands/account.js';
 import { makeUsageCommand } from './commands/usage.js';
 import { makeWebhookDeliveriesCommand } from './commands/webhook-deliveries.js';
-// Resolve version from package.json at runtime (supports compiled output).
-const require = createRequire(import.meta.url);
-// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-const pkg = require('../package.json');
-// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-const version = typeof pkg.version === 'string' ? pkg.version : '0.1.0';
+// Resolved from package.json at runtime (supports compiled output). Shared with `client.ts`'s
+// `client_surface` marker (#2906) so `--version` and the emitted `cli/<version>` affix can never
+// disagree.
+import { PACKAGE_VERSION as version } from './package-version.js';
 /** Construct the root CLI program. Exported so tests can inspect identity/structure without parsing argv. */
 export function buildProgram() {
     const program = new Command();

package/dist/package-version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Fallback `'0.1.0'` is carried over verbatim from the pre-#2906 inline resolution in `index.ts`.
+ * It cannot be reached from a correctly packed tarball; it exists so a malformed manifest degrades
+ * to a parseable semver instead of `undefined` leaking into `--version` output or onto the wire.
+ */
+export declare const PACKAGE_VERSION: string;

package/dist/package-version.js

@@ -0,0 +1,31 @@
+import { createRequire } from 'node:module';
+/**
+ * This package's own version, resolved at runtime from `package.json`.
+ *
+ * Two consumers share it so the CLI can never report one version to `--version` and affix another
+ * to its outgoing `client_surface` marker: `index.ts` (commander's `.version()`) and `client.ts`
+ * (the `cli/<version>` marker header, issue #2906 — spelled once, at that emit site).
+ *
+ * THIS MODULE MUST STAY DIRECTLY UNDER `src/`. `tsconfig.json` sets `rootDir: ./src` and
+ * `outDir: ./dist`, so `src/package-version.ts` compiles to `dist/package-version.js` and the
+ * `../package.json` below resolves to the PACKAGE ROOT from both trees. A copy of this block under
+ * `src/lib/` would compile to `dist/lib/`, where `../package.json` resolves to `dist/package.json`
+ * — a path that does not exist in the published tarball (`files` ships `dist` + `CHANGELOG.md`,
+ * not the manifest at that depth). `__tests__/entrypoint.test.ts` spawns the BUILT `dist` entry
+ * with `--version` and asserts the output equals the manifest version, so that dist-depth
+ * resolution is proven by an existing live test rather than argued.
+ *
+ * `createRequire(import.meta.url)` rather than a JSON import: the package is `type: module` and
+ * import attributes are still not uniformly available across the `engines.node: >=18` floor.
+ */
+const require = createRequire(import.meta.url);
+// eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+const pkg = require('../package.json');
+/**
+ * Fallback `'0.1.0'` is carried over verbatim from the pre-#2906 inline resolution in `index.ts`.
+ * It cannot be reached from a correctly packed tarball; it exists so a malformed manifest degrades
+ * to a parseable semver instead of `undefined` leaking into `--version` output or onto the wire.
+ */
+export const PACKAGE_VERSION = 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+typeof pkg.version === 'string' ? pkg.version : '0.1.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-cli",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "ByteKit CLI — wraps @hunt-labs/bytekit-sdk as shell subcommands",
   "license": "MIT",
   "type": "module",
@@ -41,7 +41,7 @@
   ],
   "dependencies": {
     "commander": "^12.0.0",
-    "@hunt-labs/bytekit-sdk": "^0.6.1"
+    "@hunt-labs/bytekit-sdk": "^0.7.0"
   },
   "scripts": {
     "build": "rm -rf dist tsconfig.tsbuildinfo && tsc",