@bitvea/feedback-cli 1.0.0

package/README.md

@@ -0,0 +1,38 @@
+# @bitvea/feedback-cli
+
+The installer for [BitVea Feedback](https://github.com/bitvea/feedback-toolbar): it installs the toolbar into an app, and it registers a deployment as a project.
+
+You are not expected to type this package's name.
+The command everybody uses is the toolbar's:
+
+```bash
+npx @bitvea/feedback-toolbar init --api-url https://feedback.bitvea.com
+```
+
+That package depends on this one and hands it the argv, in the same process, so the command behaves exactly as it did when the installer lived inside it - and so the `prebuild` line it writes keeps working in repositories nobody here can edit.
+
+## Commands
+
+`init` installs the toolbar into the app in the current directory: the dependency, the backend URL, `<FeedbackToolbar />` in the root layout, and a `prebuild` script that registers the deployment on every build.
+Re-running it changes nothing, and a run that cannot find a root layout changes nothing either.
+
+`register` makes sure a deployment exists as a project in the dashboard.
+It is what the `prebuild` line runs, and it is a command of its own because a script-tag install has no build to hook.
+`--optional` reports a failure and exits 0, so a registration problem can never fail somebody's deploy.
+
+`help` and `--version` print usage and the versions in play.
+
+## Which toolbar version does `init` pin?
+
+Whichever one it was launched through.
+`npx @bitvea/feedback-toolbar init` writes a caret on exactly the toolbar npx just downloaded.
+`--toolbar-version <range>` overrides it, `FEEDBACK_TOOLBAR_VERSION` does the same from the environment, and running this package directly falls back to the latest published version.
+
+If none of those answers, `init` refuses and says so before touching your repository.
+It will not guess a range: the one it writes ends up committed in your `package.json`.
+
+## Dependencies
+
+None, permanently.
+This package is installed alongside the toolbar into every app that installs the toolbar, so its dependency tree is somebody else's dependency tree.
+Its publishable check fails if `dependencies` is ever non-empty.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// `npx @bitvea/feedback-cli` - three lines, on purpose.
+//
+// Everything is in ./run.ts so that the toolbar's own bin can call the same
+// function in the same process rather than spawning this file. Two entry
+// points into one `run` is what makes "same argv, same stdout, same exit
+// codes" true by construction instead of by care.
+//
+// The bin is named `feedback-cli` and never `feedback-toolbar`: both packages
+// can end up in one `node_modules/.bin`, and two packages declaring one bin
+// name is a last-writer-wins symlink that npm resolves silently. The loser
+// would be the name every committed `prebuild` line invokes.
+//
+// The rejection handler is the one from the file this replaced, kept rather
+// than swapped for a top-level `await`: an unexpected throw prints the error
+// and exits 1, instead of Node's unhandled-rejection crash.
+import { run } from "./run.js";
+run(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+}, (err) => {
+    console.error(err);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,wDAAwD;AACxD,EAAE;AACF,4EAA4E;AAC5E,yEAAyE;AACzE,yEAAyE;AACzE,kDAAkD;AAClD,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,2EAA2E;AAC3E,6DAA6D;AAC7D,EAAE;AACF,4EAA4E;AAC5E,6EAA6E;AAC7E,4DAA4D;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC7B,CAAC,IAAI,EAAE,EAAE;IACP,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,EACD,CAAC,GAAY,EAAE,EAAE;IACf,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACnB,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CACF,CAAC"}

package/dist/commands/init.d.ts

@@ -0,0 +1,97 @@
+import { API_URL_ENV_VAR } from "../install/env.js";
+import { type InstallerFs } from "../install/fs.js";
+export { API_URL_ENV_VAR };
+import { type Delivery, type InjectionStrategy } from "../install/strategies.js";
+import type { RegisterProjectTransport } from "../registration.js";
+/**
+ * The command wired into the host app's build, and the marker that says it is
+ * already wired. `--optional` is load-bearing: see the comment on
+ * `wirePrebuild` for why a registration failure must not fail a deploy.
+ */
+export declare const REGISTER_COMMAND = "feedback-toolbar register";
+/**
+ * The prebuild line, with the backend URL BAKED IN.
+ *
+ * This is the second half of #11's reopened acceptance criterion, and the
+ * reason it reopened twice. `register` resolves its backend URL from a flag or
+ * from the build environment - and the build environment does not have it:
+ * `init` writes `NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL` into `.env.local`,
+ * which create-next-app gitignores, and a plain node process does not load a
+ * dotenv file anyway. So on a real Vercel build the prebuild step threw "no
+ * backend URL", `--optional` turned that into one warning line, and no project
+ * ever appeared.
+ *
+ * package.json IS committed, so putting the URL here is what carries it into
+ * the build. It is a public URL, not a credential; the key still comes from
+ * `FEEDBACK_TOOLBAR_API_KEY` in the build environment and from nowhere else.
+ */
+export declare function prebuildScript(apiUrl: string): string;
+export interface InitOptions {
+    /** Repository root to install into. */
+    root: string;
+    /** Base URL of the BitVea Feedback backend. */
+    apiUrl: string;
+    /**
+     * Deploy key authorising registration. Optional: without it the install
+     * still happens, and only the registration step is skipped - the prebuild
+     * step this writes registers on the next build instead.
+     */
+    apiKey?: string;
+    /** Deployment URL to register the project under, when it is known. */
+    projectUrl?: string;
+    /**
+     * How to find out which range to write into the host app's `dependencies`
+     * for `@bitvea/feedback-toolbar`.
+     *
+     * It used to be a literal in this file, rewritten inside the toolbar's own
+     * `scripts/release.mjs` at publish time. After the split that rewrite would
+     * have had to reach across a package boundary, and any CLI published
+     * between two toolbar releases would have carried a number it had no way to
+     * know was stale. So the range is asked for, at the moment it is needed,
+     * and there is deliberately no fallback constant: a wrong range silently
+     * committed into somebody else's repository under their name is worse than
+     * a refusal naming a flag. See `resolveToolbarRange`.
+     *
+     * A function rather than a value because only the npm route writes a
+     * dependency at all. A script-tag install has no `package.json` entry to
+     * make, and refusing one for want of a number it will never use - on a
+     * machine that may have no registry to ask - would be a refusal about
+     * nothing.
+     */
+    resolveToolbarRange?: () => string | Promise<string>;
+    /**
+     * What a script-tag install declares as its environment. Ignored by the npm
+     * route, which resolves it from the host build's own provider variables -
+     * see buildEnv.ts, and the neutral `NEXT_PUBLIC_FEEDBACK_TOOLBAR_ENV` for a
+     * host that has no entry there.
+     */
+    environment?: string;
+    /** Injected so tests do not have to reach the network. */
+    registerProject?: RegisterProjectTransport;
+    /** Env bag, for the Vercel git metadata. Defaults to `process.env`. */
+    env?: Record<string, string | undefined>;
+    strategies?: readonly InjectionStrategy[];
+}
+export interface InitResult {
+    /** What actually changed, one line each, for the CLI to print. */
+    changes: string[];
+    /**
+     * Things worth saying that are not changes: a project that was already
+     * registered, or a registration that did not go through. These are kept
+     * apart from `changes` because `alreadyInstalled` is derived from that
+     * list, and a re-run must still report itself as a no-op even though it
+     * talks to the backend every time.
+     */
+    notes: string[];
+    /** True when nothing needed doing, which is what a re-run should report. */
+    alreadyInstalled: boolean;
+    strategy: string;
+    /**
+     * How the host app gets the code. Reported because it decides what the
+     * developer has to do next: an npm install needs a dependency install and a
+     * redeploy, a script tag needs neither.
+     */
+    delivery: Delivery;
+}
+export declare function init(fs: InstallerFs, options: InitOptions): Promise<InitResult>;
+//# sourceMappingURL=init.d.ts.map

package/dist/commands/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAkCA,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,CAAC;AAE3B,OAAO,EAML,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAIhE;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAE5D;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;;;;;;;;;;;;;;;OAkBG;IACH,mBAAmB,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACrD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,wBAAwB,CAAC;IAC3C,uEAAuE;IACvE,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,UAAU;IACzB,kEAAkE;IAClE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,4EAA4E;IAC5E,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAsB,IAAI,CACxB,EAAE,EAAE,WAAW,EACf,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,UAAU,CAAC,CAsLrB"}

package/dist/commands/init.js

@@ -0,0 +1,273 @@
+// `npx @bitvea/feedback-toolbar init` - the whole codemod, as one pure
+// function over an InstallerFs so it can be driven by tests against a tree
+// they control.
+//
+// Two properties matter more than anything else here, because this edits
+// somebody else's repository:
+//
+//   1. Re-running changes nothing. Every step detects its own prior work
+//      rather than blindly appending, so the second run reports "already
+//      installed" and writes no file.
+//   2. It never leaves a half-install. Everything that can fail is computed
+//      before anything is written, so a missing root layout ends the run with
+//      an untouched repository and a message saying what to do by hand.
+//
+// What changed after #11 was reopened: this command no longer pretends to be
+// where registration happens. `init` runs on a laptop, where VERCEL_URL does
+// not exist, so it had nothing to register and said nothing about it - a real
+// install registered silently nothing. It now writes a `prebuild` script that
+// runs `feedback-toolbar register`, so registration happens in the build,
+// where those variables do exist. Registering here too is a convenience for
+// the developer who passed both flags, not the mechanism.
+//
+// And what changed after it reopened a second time: NOTHING THIS COMMAND
+// WRITES MAY DEPEND ON A GITIGNORED FILE. The install used to put the backend
+// URL in `.env.local` alone, which create-next-app gitignores - so the
+// prebuild step reached the build with no URL and skipped itself (one warning
+// line, exit 0, because `--optional` must never fail a deploy), and the
+// deployed toolbar had no URL either and rendered nothing. Two silent
+// failures from one gitignored file. The URL is a public value, so it now
+// goes where it survives a commit: into the injected component, and into the
+// prebuild command in package.json. The only thing left for a developer to
+// set by hand is the deploy KEY, which is a secret and belongs in the build
+// environment - and the notes below say so explicitly.
+import { API_URL_ENV_VAR } from "../install/env.js";
+import { joinPath } from "../install/fs.js";
+export { API_URL_ENV_VAR };
+import { DEFAULT_SCRIPT_ENVIRONMENT, InjectionError, PACKAGE_NAME, SCRIPT_BUNDLE_PATH, STRATEGIES, } from "../install/strategies.js";
+import { API_KEY_ENV_VAR, inferProjectUrl, register } from "./register.js";
+const ENV_FILES = [".env.local", ".env"];
+/**
+ * The command wired into the host app's build, and the marker that says it is
+ * already wired. `--optional` is load-bearing: see the comment on
+ * `wirePrebuild` for why a registration failure must not fail a deploy.
+ */
+export const REGISTER_COMMAND = "feedback-toolbar register";
+/**
+ * The prebuild line, with the backend URL BAKED IN.
+ *
+ * This is the second half of #11's reopened acceptance criterion, and the
+ * reason it reopened twice. `register` resolves its backend URL from a flag or
+ * from the build environment - and the build environment does not have it:
+ * `init` writes `NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL` into `.env.local`,
+ * which create-next-app gitignores, and a plain node process does not load a
+ * dotenv file anyway. So on a real Vercel build the prebuild step threw "no
+ * backend URL", `--optional` turned that into one warning line, and no project
+ * ever appeared.
+ *
+ * package.json IS committed, so putting the URL here is what carries it into
+ * the build. It is a public URL, not a credential; the key still comes from
+ * `FEEDBACK_TOOLBAR_API_KEY` in the build environment and from nowhere else.
+ */
+export function prebuildScript(apiUrl) {
+    return `${REGISTER_COMMAND} --optional --api-url ${apiUrl}`;
+}
+export async function init(fs, options) {
+    const { root, apiUrl } = options;
+    const env = options.env ?? {};
+    const strategies = options.strategies ?? STRATEGIES;
+    const packageJsonPath = joinPath(root, "package.json");
+    if (!fs.exists(packageJsonPath)) {
+        throw new InjectionError(`no package.json at ${root}. Run this from the root of the app you want to install into.`);
+    }
+    const pkg = JSON.parse(fs.readFile(packageJsonPath));
+    // Resolved before the injection, because the script-tag strategy writes it
+    // into the markup and refuses to install without it.
+    const projectUrl = options.projectUrl ?? inferProjectUrl(env);
+    // Find the injection site FIRST. It is the only step that can fail for a
+    // reason the developer has to fix, and finding out after writing package.json
+    // and .env.local is exactly the half-install this must not produce.
+    const strategy = strategies.find((s) => s.detect(fs, root) !== null);
+    if (!strategy) {
+        throw new InjectionError([
+            "could not find a root layout to inject the toolbar into.",
+            `Tried: ${strategies.map((s) => s.label).join(", ")}.`,
+            "Nothing was changed. Add the provider by hand instead:",
+            "",
+            `  import { FeedbackToolbar } from "${PACKAGE_NAME}";`,
+            "  // ...then render <FeedbackToolbar /> inside <body> in your root layout.",
+        ].join("\n"));
+    }
+    const site = strategy.detect(fs, root);
+    const layoutSource = fs.readFile(site.path);
+    const alreadyInjected = strategy.isInstalled(layoutSource);
+    // Computed before any write: `inject` throws rather than returning a
+    // half-edited file, and this is where that throw has to happen.
+    const injected = alreadyInjected
+        ? layoutSource
+        : strategy.inject(layoutSource, {
+            apiUrl,
+            projectUrl,
+            environment: options.environment,
+        });
+    // A script-tag install has no dependency to add, no env file to read at
+    // runtime, and no build to hook - the toolbar is a file served from the
+    // backend and configured from the tag's own attributes. Skipping those
+    // steps is the whole difference between the two delivery routes.
+    const scriptTag = strategy.delivery === "script-tag";
+    const changes = [];
+    const notes = [];
+    let packageJsonChanged = false;
+    // 1. Dependency. Resolved here rather than by the caller because this is
+    //    the only step that needs it, and resolved BEFORE the first write like
+    //    everything else that can fail: a refusal has to leave the tree
+    //    untouched.
+    if (!scriptTag) {
+        const deps = pkg.dependencies ?? {};
+        if (!deps[PACKAGE_NAME]) {
+            if (!options.resolveToolbarRange) {
+                throw new InjectionError(`could not tell which version of ${PACKAGE_NAME} to install. ` +
+                    "Re-run with --toolbar-version <range>.");
+            }
+            const range = await options.resolveToolbarRange();
+            pkg.dependencies = { ...deps, [PACKAGE_NAME]: range };
+            packageJsonChanged = true;
+            changes.push(`added ${PACKAGE_NAME}@${range} to dependencies`);
+        }
+    }
+    // 2. Env var, in whichever env file already exists, else .env.local.
+    //
+    //    A local-development convenience, and only that. It is deliberately NOT
+    //    how the deployed toolbar finds the backend: `.env.local` is gitignored
+    //    by create-next-app, so it never reaches a build, which is why the URL
+    //    is written into the injected component and into the prebuild command
+    //    as well. Kept because a developer running `next dev` before their
+    //    first deploy expects the variable to be there.
+    if (!scriptTag) {
+        const envPath = ENV_FILES.map((f) => joinPath(root, f)).find((p) => fs.exists(p));
+        const targetEnvPath = envPath ?? joinPath(root, ENV_FILES[0]);
+        const existingEnv = envPath ? fs.readFile(envPath) : "";
+        if (!existingEnv.includes(`${API_URL_ENV_VAR}=`)) {
+            const separator = existingEnv.length === 0 || existingEnv.endsWith("\n") ? "" : "\n";
+            fs.writeFile(targetEnvPath, `${existingEnv}${separator}${API_URL_ENV_VAR}=${apiUrl}\n`);
+            changes.push(`wrote ${API_URL_ENV_VAR} to ${targetEnvPath} (local development; the ` +
+                "deployed toolbar reads the URL from the component it injected)");
+        }
+    }
+    // 3. The provider.
+    if (!alreadyInjected) {
+        fs.writeFile(site.path, injected);
+        const what = scriptTag
+            ? `injected the ${SCRIPT_BUNDLE_PATH} script tag into the ${site.description}`
+            : `injected <FeedbackToolbar /> into the ${site.description}`;
+        changes.push(what);
+        if (scriptTag) {
+            // The gate cannot be resolved from a static file - absent means off - so
+            // the tag has to declare one or it mounts nothing. Written rather than
+            // left to the developer, and said out loud here because it is the one
+            // value in the install that decides whether their own customers see a
+            // feedback widget.
+            const environment = options.environment ?? DEFAULT_SCRIPT_ENVIRONMENT;
+            notes.push(`the tag declares data-environment="${environment}", which is what makes it mount. ` +
+                "Change it to production on any page real customers reach, or re-run with " +
+                "--environment production.");
+        }
+    }
+    // 4. The build hook. This is the step #11 was reopened for: without it,
+    //    nothing ever registers the project except a developer who happened to
+    //    pass two flags by hand.
+    if (!scriptTag) {
+        const wired = wirePrebuild(pkg, apiUrl);
+        if (wired) {
+            packageJsonChanged = true;
+            changes.push(wired);
+        }
+    }
+    if (packageJsonChanged) {
+        fs.writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    }
+    // 5. Register the project, if this machine happens to know enough to. On a
+    //    developer's laptop it usually does not, and that is fine now: step 4
+    //    put the command in the build, where the URL and the key live.
+    const apiKey = options.apiKey ?? env[API_KEY_ENV_VAR];
+    if (!projectUrl || !apiKey) {
+        notes.push(registrationDeferredNote({ projectUrl, apiKey, scriptTag }));
+    }
+    else {
+        try {
+            const outcome = await register({
+                apiUrl,
+                apiKey,
+                projectUrl,
+                packageName: pkg.name,
+                env,
+                registerProject: options.registerProject,
+            });
+            if (outcome.created) {
+                changes.push(`registered ${projectUrl} as a project`);
+            }
+            else {
+                notes.push(`${projectUrl} was already registered`);
+            }
+        }
+        catch (err) {
+            // A registration that did not go through is not a failed install: the
+            // code is in place and the next build registers. Say so and carry on.
+            notes.push(`could not register ${projectUrl} (${String(err)}); it will register on the next build`);
+        }
+    }
+    return {
+        changes,
+        notes,
+        alreadyInstalled: changes.length === 0,
+        strategy: strategy.id,
+        delivery: scriptTag ? "script-tag" : "npm-package",
+    };
+}
+/**
+ * Add `feedback-toolbar register` to the host app's `prebuild`, once.
+ *
+ * npm, pnpm and yarn all run `prebuild` before `build`, which is why the hook
+ * goes there rather than into `build` itself: appending to somebody's build
+ * command changes the command they debug, and prepending to it changes what
+ * their CI logs look like at the top. `prebuild` is the slot the package
+ * managers reserve for exactly this.
+ *
+ * `--optional` is not decoration. This runs on every deploy of somebody
+ * else's product forever, and a feedback tool that fails a deploy because our
+ * backend was slow, or because a key was rotated, has done far more damage
+ * than the missing project row it was trying to create.
+ *
+ * Refusing to add it twice is the same idempotency rule as everything else
+ * here, and it has to survive the developer having edited the line: the check
+ * is for the command, not for the exact string this wrote. Like every other
+ * step, a second run says nothing rather than reporting a non-change.
+ *
+ * Returns the line to report, or undefined when there was nothing to do.
+ */
+function wirePrebuild(pkg, apiUrl) {
+    const scripts = pkg.scripts ?? {};
+    const existing = scripts.prebuild;
+    const line = prebuildScript(apiUrl);
+    if (existing === undefined) {
+        pkg.scripts = { ...scripts, prebuild: line };
+        return `added a "prebuild" script that registers this deployment on every build: ${line}`;
+    }
+    if (existing.includes(REGISTER_COMMAND))
+        return undefined;
+    // Their command first, ours after it, joined rather than replaced: the
+    // existing prebuild is somebody's build prerequisite and must still run,
+    // and must still be the thing that fails the build if it fails.
+    pkg.scripts = { ...scripts, prebuild: `${existing} && ${line}` };
+    return (`edited the existing "prebuild" script to also register this deployment: ` +
+        `${existing} && ${line}`);
+}
+/** Why registration did not happen here, and what will do it instead. */
+function registrationDeferredNote(input) {
+    if (input.scriptTag) {
+        // No build to hook, so nothing will do this on its own. #17's answer: run
+        // the command once, from a terminal or CI, where a key belongs.
+        return ("a script-tag install has no build step, so nothing registers the project for you. " +
+            `Run it once: npx ${PACKAGE_NAME} register --project-url <url> --api-key <key>`);
+    }
+    if (!input.apiKey) {
+        return ("no deploy key here, so nothing was registered yet. The prebuild step will do it " +
+            `on the next build, and it needs one thing from you: set ${API_KEY_ENV_VAR} in your ` +
+            "hosting provider's environment variables (dashboard > Settings > Deploy keys). " +
+            "The backend URL is already baked into the prebuild command and into the injected " +
+            "component, so there is nothing else to configure.");
+    }
+    return ("this machine does not report a deployment URL, so nothing was registered yet - " +
+        "the prebuild step will do it on the next build, where VERCEL_URL is set");
+}
+//# sourceMappingURL=init.js.map

package/dist/commands/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}

package/dist/commands/register.d.ts

@@ -0,0 +1,84 @@
+import { type RegisterProjectTransport } from "../registration.js";
+/** Where `--api-url` falls back to. The public name is what a build already has. */
+export declare const API_URL_ENV_VARS: readonly ["NEXT_PUBLIC_FEEDBACK_TOOLBAR_API_URL", "FEEDBACK_TOOLBAR_API_URL"];
+/**
+ * Where `--api-key` falls back to, and the only place a key is ever read from.
+ * Never a file, never a `data-` attribute, never an argument this CLI writes
+ * down: a deploy key's whole power is creating projects, so it lives in the
+ * build environment and nowhere else.
+ */
+export declare const API_KEY_ENV_VAR = "FEEDBACK_TOOLBAR_API_KEY";
+export interface RegisterOptions {
+    /** `--api-url`, else one of API_URL_ENV_VARS. */
+    apiUrl?: string | undefined;
+    /** `--api-key`, else API_KEY_ENV_VAR. */
+    apiKey?: string | undefined;
+    /** `--project-url`, else whatever the build environment reports. */
+    projectUrl?: string | undefined;
+    /** The host app's package name, as a fallback for naming the project. */
+    packageName?: string | undefined;
+    /** The build environment. Explicit so this stays a pure function. */
+    env: Record<string, string | undefined>;
+    /** Injected so tests do not reach the network. */
+    registerProject?: RegisterProjectTransport;
+}
+export interface RegisterOutcome {
+    projectUrl: string;
+    /** False when the URL was already registered, which is a success. */
+    created: boolean;
+    /** What the backend called it, when it said. */
+    projectName?: string | undefined;
+}
+/**
+ * Register the deployment, or confirm it is already registered.
+ *
+ * Idempotent because the backend is: the second call with the same normalised
+ * URL is a no-op that answers `created: false`. That is what makes this safe
+ * as a prebuild step, which runs on every deploy forever.
+ *
+ * Throws `RegistrationError` with a message naming the missing piece when it
+ * cannot proceed. It never guesses: a registration under a URL nobody meant
+ * creates a project that collects feedback from a page that does not exist.
+ */
+export declare function register(options: RegisterOptions): Promise<RegisterOutcome>;
+/**
+ * The URL to register the project under, from the build environment.
+ *
+ * Same precedence as the toolbar's own `resolveConfig`, and that agreement is
+ * the point: the toolbar reports this value back at runtime, so if the two
+ * picked differently the lookup would miss on every preview deployment. The
+ * production hostname wins because a preview URL changes on every commit, and
+ * keying on it would create a project per deploy instead of collecting a
+ * project's feedback in one place.
+ */
+export declare function inferProjectUrl(env: Record<string, string | undefined>): string | undefined;
+/**
+ * The browser origins this deployment serves the toolbar from.
+ *
+ * A DIFFERENT question from `inferProjectUrl`, and conflating them is what
+ * made the toolbar unusable everywhere it was installed. That function answers
+ * "which project is this", and answers it with the production URL because a
+ * project's feedback has to collect in one place across every deploy. This one
+ * answers "where will a browser be calling us from", and on a Vercel install
+ * the answer is never the production URL: the toolbar is off in production by
+ * design, so it only ever runs on a preview, whose origin is per-branch or
+ * per-commit.
+ *
+ * Both are reported, in this order:
+ *
+ *   - `VERCEL_BRANCH_URL` - `<project>-git-<branch>-<team>.vercel.app`. Stable
+ *     for the life of the branch, and the URL a reviewer is actually sent, so
+ *     it is the one that matters. It is also bounded by branch count rather
+ *     than by deploy count, which is what keeps the allow-list from growing
+ *     without limit.
+ *   - `VERCEL_URL` - this deployment alone. Included because a reviewer handed
+ *     a specific deployment's URL is a real case, and because a build with no
+ *     branch alias (a `vercel deploy` from a terminal) has nothing else.
+ *
+ * Empty off Vercel, where neither exists and there is no preview to allow.
+ * The backend normalises and de-duplicates, and drops the project's own URL,
+ * so this does not have to be careful about overlap - only about never
+ * inventing a host it was not told.
+ */
+export declare function inferProjectOrigins(env: Record<string, string | undefined>): string[];
+//# sourceMappingURL=register.d.ts.map

package/dist/commands/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/commands/register.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,iBAAiB,CAAC;AAEzB,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,+EAGnB,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,qEAAqE;IACrE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACxC,kDAAkD;IAClD,eAAe,CAAC,EAAE,wBAAwB,CAAC;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,qEAAqE;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,eAAe,CAAC,CA6C1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,MAAM,GAAG,SAAS,CAGpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,MAAM,EAAE,CAKV"}