@bitvea/feedback-toolbar 0.0.1

package/dist/cli/init.js

@@ -0,0 +1,266 @@
+// `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 "../config.js";
+import { joinPath } from "./fs.js";
+export { API_URL_ENV_VAR };
+import { DEFAULT_SCRIPT_ENVIRONMENT, InjectionError, PACKAGE_NAME, SCRIPT_BUNDLE_PATH, STRATEGIES, } from "./strategies.js";
+import { API_KEY_ENV_VAR, inferProjectUrl, register } from "./register.js";
+const TOOLBAR_VERSION = "^0.0.1";
+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.
+    if (!scriptTag) {
+        const deps = pkg.dependencies ?? {};
+        if (!deps[PACKAGE_NAME]) {
+            pkg.dependencies = { ...deps, [PACKAGE_NAME]: TOOLBAR_VERSION };
+            packageJsonChanged = true;
+            changes.push(`added ${PACKAGE_NAME} 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/cli/init.js.map

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

package/dist/cli/register.d.ts

@@ -0,0 +1,55 @@
+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;
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/cli/register.ts"],"names":[],"mappings":"AAeA,OAAO,EAGL,KAAK,wBAAwB,EAC9B,MAAM,gBAAgB,CAAC;AAExB,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,CAyC1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GACtC,MAAM,GAAG,SAAS,CAGpB"}

package/dist/cli/register.js

@@ -0,0 +1,84 @@
+// `feedback-toolbar register` - make sure this deployment exists as a project.
+//
+// A first-class command, not a step inside `init`, and issues #11 and #17 both
+// needed it to be:
+//
+//   - #11 reopened because `init` runs on a laptop, where VERCEL_URL does not
+//     exist, so the project URL was undefined and registration was silently
+//     skipped. The fix is to register where those variables DO exist: in the
+//     build. `init` wires this command in as a prebuild step.
+//   - #17 added the script-tag install, which has no build to hook at all. Its
+//     project is registered by running this command once from a terminal or CI.
+//
+// Both callers want the same three things: resolve where the values come from,
+// call the one registration service, and say clearly what happened. None of
+// them wants a second opinion on what a valid URL is - see ./registration.ts.
+import { RegistrationError, postRegistration, } from "./registration.js";
+/** Where `--api-url` falls back to. The public name is what a build already has. */
+export const API_URL_ENV_VARS = [
+    "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 const API_KEY_ENV_VAR = "FEEDBACK_TOOLBAR_API_KEY";
+/**
+ * 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 async function register(options) {
+    const { env } = options;
+    const transport = options.registerProject ?? postRegistration;
+    const apiUrl = options.apiUrl ?? API_URL_ENV_VARS.map((name) => env[name]).find(Boolean);
+    if (!apiUrl) {
+        throw new RegistrationError("no backend URL. Pass --api-url https://feedback.bitvea.com, or set " +
+            `${API_URL_ENV_VARS[0]} in the build environment (\`init\` writes it into .env.local).`);
+    }
+    const apiKey = options.apiKey ?? env[API_KEY_ENV_VAR];
+    if (!apiKey) {
+        throw new RegistrationError(`no deploy key. Pass --api-key, or set ${API_KEY_ENV_VAR} in the build ` +
+            "environment. Create one in the dashboard under Settings > Deploy keys. " +
+            "It must never be committed or put in a page.");
+    }
+    const projectUrl = options.projectUrl ?? inferProjectUrl(env);
+    if (!projectUrl) {
+        throw new RegistrationError("could not tell which URL to register. Pass --project-url https://myapp.com. " +
+            "Inside a Vercel build this is read from VERCEL_PROJECT_PRODUCTION_URL or " +
+            "VERCEL_URL, neither of which is set here.");
+    }
+    const { created, project } = await transport({
+        apiUrl,
+        apiKey,
+        projectUrl,
+        repoOwner: env.VERCEL_GIT_REPO_OWNER,
+        repoSlug: env.VERCEL_GIT_REPO_SLUG,
+        packageName: options.packageName,
+    });
+    return { projectUrl, created, projectName: project?.name };
+}
+/**
+ * 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 function inferProjectUrl(env) {
+    const host = env.VERCEL_PROJECT_PRODUCTION_URL ?? env.VERCEL_URL;
+    return host ? `https://${host}` : undefined;
+}
+//# sourceMappingURL=register.js.map

package/dist/cli/register.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../src/cli/register.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,EAAE;AACF,+EAA+E;AAC/E,mBAAmB;AACnB,EAAE;AACF,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,8DAA8D;AAC9D,+EAA+E;AAC/E,gFAAgF;AAChF,EAAE;AACF,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,GAEjB,MAAM,gBAAgB,CAAC;AAExB,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,sCAAsC;IACtC,0BAA0B;CAClB,CAAC;AAEX;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAyB1D;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,OAAwB;IAExB,MAAM,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;IACxB,MAAM,SAAS,GAAG,OAAO,CAAC,eAAe,IAAI,gBAAgB,CAAC;IAE9D,MAAM,MAAM,GACV,OAAO,CAAC,MAAM,IAAI,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC5E,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,iBAAiB,CACzB,qEAAqE;YACnE,GAAG,gBAAgB,CAAC,CAAC,CAAC,iEAAiE,CAC1F,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,GAAG,CAAC,eAAe,CAAC,CAAC;IACtD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,iBAAiB,CACzB,yCAAyC,eAAe,gBAAgB;YACtE,yEAAyE;YACzE,8CAA8C,CACjD,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,eAAe,CAAC,GAAG,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,MAAM,IAAI,iBAAiB,CACzB,8EAA8E;YAC5E,2EAA2E;YAC3E,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,SAAS,CAAC;QAC3C,MAAM;QACN,MAAM;QACN,UAAU;QACV,SAAS,EAAE,GAAG,CAAC,qBAAqB;QACpC,QAAQ,EAAE,GAAG,CAAC,oBAAoB;QAClC,WAAW,EAAE,OAAO,CAAC,WAAW;KACjC,CAAC,CAAC;IAEH,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AAC7D,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC7B,GAAuC;IAEvC,MAAM,IAAI,GAAG,GAAG,CAAC,6BAA6B,IAAI,GAAG,CAAC,UAAU,CAAC;IACjE,OAAO,IAAI,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC9C,CAAC"}

package/dist/cli/registration.d.ts

@@ -0,0 +1,37 @@
+/** What a build environment can tell the backend about the deployment. */
+export interface RegisterProjectRequest {
+    /** Base URL of the BitVea Feedback backend. */
+    apiUrl: string;
+    /** Deploy key. Read from a flag or the environment, never from a file. */
+    apiKey: string;
+    /** The deployment URL to register, exactly as the caller resolved it. */
+    projectUrl: string;
+    repoOwner?: string | undefined;
+    repoSlug?: string | undefined;
+    packageName?: string | undefined;
+}
+/**
+ * `created` is the whole answer: false means the URL was already registered,
+ * which is a success, not a conflict. `project` is what the backend named it,
+ * so the CLI can echo something recognisable back.
+ */
+export interface RegisterProjectResponse {
+    created: boolean;
+    project?: {
+        id: string;
+        name: string;
+        slug: string;
+        url: string | null;
+    };
+}
+export type RegisterProjectTransport = (input: RegisterProjectRequest) => Promise<RegisterProjectResponse>;
+/**
+ * A failure the person running the command can act on, as opposed to a bug.
+ * The CLI prints `message` and exits; nothing else is expected to catch it.
+ */
+export declare class RegistrationError extends Error {
+    constructor(message: string);
+}
+/** The real transport. Injected everywhere else so tests stay off the network. */
+export declare const postRegistration: RegisterProjectTransport;
+//# sourceMappingURL=registration.d.ts.map

package/dist/cli/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../src/cli/registration.ts"],"names":[],"mappings":"AAcA,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC;CAC1E;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,KAAK,EAAE,sBAAsB,KAC1B,OAAO,CAAC,uBAAuB,CAAC,CAAC;AAEtC;;;GAGG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,kFAAkF;AAClF,eAAO,MAAM,gBAAgB,EAAE,wBAqD9B,CAAC"}

package/dist/cli/registration.js

@@ -0,0 +1,69 @@
+// Talking to the registration endpoint, and nothing else.
+//
+// The rule this file exists to keep is that the CLI does not know what a valid
+// project URL is. Registration's contract - normalise the URL, key on it, be
+// idempotent, lose the race gracefully - lives once in
+// `packages/api/src/services/projects.ts`, behind
+// `POST /api/v1/projects/register`. A second opinion here would be a second
+// implementation, and the failure mode of two implementations disagreeing is a
+// duplicate project: two rows for one deployment, each holding half its
+// feedback, with no way to merge them afterwards.
+//
+// So this module posts what it was given and translates the answer. It trims
+// no slashes, lowercases no hosts, and rejects nothing.
+/**
+ * A failure the person running the command can act on, as opposed to a bug.
+ * The CLI prints `message` and exits; nothing else is expected to catch it.
+ */
+export class RegistrationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegistrationError";
+    }
+}
+/** The real transport. Injected everywhere else so tests stay off the network. */
+export const postRegistration = async (input) => {
+    let res;
+    try {
+        res = await fetch(`${input.apiUrl}/api/v1/projects/register`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${input.apiKey}`,
+            },
+            body: JSON.stringify({
+                url: input.projectUrl,
+                repoOwner: input.repoOwner,
+                repoSlug: input.repoSlug,
+                packageName: input.packageName,
+            }),
+        });
+    }
+    catch (err) {
+        // DNS, TLS, a wrong host, no network in the build container. Worth naming
+        // the URL: the commonest cause is an --api-url pointing at nothing.
+        throw new RegistrationError(`could not reach ${input.apiUrl} (${String(err)}). Check --api-url.`);
+    }
+    if (res.status === 401) {
+        // The commonest real failure, and the one a bare status code explains
+        // worst. Absent, mistyped and revoked all answer 401 on purpose - the
+        // route refuses to be an oracle for which - so say all three.
+        throw new RegistrationError("the deploy key was refused (401): it is missing, wrong or revoked. " +
+            "Create one in the dashboard under Settings > Deploy keys, then pass it as " +
+            "--api-key or set FEEDBACK_TOOLBAR_API_KEY.");
+    }
+    if (!res.ok) {
+        // The backend's own error code, verbatim. `invalid_project_url` is the one
+        // that matters, and paraphrasing it here would be the beginning of a
+        // second set of validation rules.
+        const code = await res
+            .json()
+            .then((body) => body !== null && typeof body === "object" && "error" in body
+            ? String(body.error)
+            : undefined)
+            .catch(() => undefined);
+        throw new RegistrationError(`registration failed with ${res.status}${code ? ` (${code})` : ""}.`);
+    }
+    return (await res.json());
+};
+//# sourceMappingURL=registration.js.map

package/dist/cli/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../src/cli/registration.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,uDAAuD;AACvD,kDAAkD;AAClD,4EAA4E;AAC5E,+EAA+E;AAC/E,wEAAwE;AACxE,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,wDAAwD;AA6BxD;;;GAGG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,gBAAgB,GAA6B,KAAK,EAAE,KAAK,EAAE,EAAE;IACxE,IAAI,GAAa,CAAC;IAClB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,KAAK,CAAC,MAAM,2BAA2B,EAAE;YAC5D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,cAAc,EAAE,kBAAkB;gBAClC,aAAa,EAAE,UAAU,KAAK,CAAC,MAAM,EAAE;aACxC;YACD,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;gBACnB,GAAG,EAAE,KAAK,CAAC,UAAU;gBACrB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,WAAW,EAAE,KAAK,CAAC,WAAW;aAC/B,CAAC;SACH,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,0EAA0E;QAC1E,oEAAoE;QACpE,MAAM,IAAI,iBAAiB,CACzB,mBAAmB,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,GAAG,CAAC,qBAAqB,CACrE,CAAC;IACJ,CAAC;IAED,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QACvB,sEAAsE;QACtE,sEAAsE;QACtE,8DAA8D;QAC9D,MAAM,IAAI,iBAAiB,CACzB,qEAAqE;YACnE,4EAA4E;YAC5E,4CAA4C,CAC/C,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;QACZ,2EAA2E;QAC3E,qEAAqE;QACrE,kCAAkC;QAClC,MAAM,IAAI,GAAG,MAAM,GAAG;aACnB,IAAI,EAAE;aACN,IAAI,CAAC,CAAC,IAAa,EAAE,EAAE,CACtB,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,OAAO,IAAI,IAAI;YAC1D,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;YACpB,CAAC,CAAC,SAAS,CACd;aACA,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1B,MAAM,IAAI,iBAAiB,CACzB,4BAA4B,GAAG,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CACrE,CAAC;IACJ,CAAC;IAED,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA4B,CAAC;AACvD,CAAC,CAAC"}

package/dist/cli/strategies.d.ts

@@ -0,0 +1,98 @@
+import { type InstallerFs } from "./fs.js";
+export declare const PACKAGE_NAME = "@bitvea/feedback-toolbar";
+export declare const COMPONENT_NAME = "FeedbackToolbar";
+/** The file the script-tag route is served as, relative to the backend URL. */
+export declare const SCRIPT_BUNDLE_PATH = "/toolbar.js";
+export interface InjectionSite {
+    /** The file to edit. */
+    path: string;
+    /** Human-readable description of what was found, for the CLI's output. */
+    description: string;
+}
+/**
+ * How a strategy's host app gets the toolbar's *code*, which decides which of
+ * the installer's other steps apply at all.
+ *
+ * `npm-package`: the toolbar is a dependency the host's bundler compiles, so
+ * the install needs a package.json entry, an env var for the API URL, and a
+ * prebuild hook to register the project from the build.
+ *
+ * `script-tag`: the toolbar is a file served from the backend and configured
+ * from `data-` attributes on the tag. There is no dependency to add, no env
+ * file to read at runtime, and - the reason #17 called this out - no build to
+ * hook, so its project is registered by running `register` by hand.
+ */
+export type Delivery = "npm-package" | "script-tag";
+/**
+ * The environment a script-tag install declares, when the developer has not
+ * said otherwise.
+ *
+ * The gate treats "absent" as off, and a static HTML file cannot know which
+ * deployment served it - so a tag with no `data-environment` mounts nothing,
+ * ever. That is the correct default for a value we could only guess, and the
+ * wrong default for an installer whose whole job is to leave a working
+ * install behind: #17 asks for a toolbar that mounts on a plain page with no
+ * build step, and a tag the developer has to hand-edit is not that.
+ *
+ * So `init` writes an environment, and the value is a review environment
+ * because installing a review tool on a page is what the command means. The
+ * result is printed as a change and called out as a note, and `--environment`
+ * overrides it - including with `production`, which is how somebody turns the
+ * tag off without removing it.
+ */
+export declare const DEFAULT_SCRIPT_ENVIRONMENT = "preview";
+/** What `inject` needs to know about the install to write the markup. */
+export interface InjectionContext {
+    /** Base URL of the BitVea Feedback backend, no trailing slash. */
+    apiUrl: string;
+    /** The deployment URL the project is registered under, when known. */
+    projectUrl?: string | undefined;
+    /**
+     * What the injected markup declares as its environment. Only the script-tag
+     * route uses it: an npm install reads `NEXT_PUBLIC_VERCEL_ENV`, which the
+     * host's own build populates per deployment.
+     */
+    environment?: string | undefined;
+}
+export interface InjectionStrategy {
+    /** Stable id, reported in the CLI's output. */
+    readonly id: string;
+    readonly label: string;
+    /** Which of the installer's steps apply. Defaults to `npm-package`. */
+    readonly delivery?: Delivery;
+    /** Find the file to inject into, or null when this strategy does not apply. */
+    detect(fs: InstallerFs, root: string): InjectionSite | null;
+    /** True when the provider is already there, which makes a re-run a no-op. */
+    isInstalled(source: string): boolean;
+    /**
+     * Return the edited source. Only called when `isInstalled` is false, and
+     * throws when it cannot do the edit, so a partial write is not possible:
+     * the caller writes only what this returns.
+     */
+    inject(source: string, context: InjectionContext): string;
+}
+export declare const nextAppRouterStrategy: InjectionStrategy;
+/**
+ * The `<script src>` install, for an app with no build step to add a
+ * dependency to. Second in the list on purpose: an App Router app usually
+ * also has an index.html somewhere, and the npm install is the better one.
+ *
+ * Note what the injected tag does NOT carry: a deploy key. There is no
+ * supported way to put one in a page, and the bundle refuses to mount when it
+ * finds anything that looks like one - a key in a page is a key in every
+ * visitor's hands, and its whole power is creating projects.
+ *
+ * It does carry an environment, and it has to. A static file cannot know which
+ * deployment served it and the gate treats absent as off, so a tag without one
+ * mounts nothing at all - which is what #17's "mounts a working toolbar on a
+ * plain HTML page" cannot mean. The value is written, printed as a change, and
+ * called out as a note; `--environment production` is how a developer turns
+ * the tag off without deleting it. See DEFAULT_SCRIPT_ENVIRONMENT.
+ */
+export declare const htmlScriptTagStrategy: InjectionStrategy;
+/** A failure the developer can act on, as opposed to an internal error. */
+export declare class InjectionError extends Error {
+    constructor(message: string);
+}
+export declare const STRATEGIES: readonly InjectionStrategy[];
+//# sourceMappingURL=strategies.d.ts.map

package/dist/cli/strategies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategies.d.ts","sourceRoot":"","sources":["../../src/cli/strategies.ts"],"names":[],"mappings":"AAOA,OAAO,EAAY,KAAK,WAAW,EAAE,MAAM,MAAM,CAAC;AAElD,eAAO,MAAM,YAAY,6BAA6B,CAAC;AACvD,eAAO,MAAM,cAAc,oBAAoB,CAAC;AAEhD,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,gBAAgB,CAAC;AAEhD,MAAM,WAAW,aAAa;IAC5B,wBAAwB;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,QAAQ,GAAG,aAAa,GAAG,YAAY,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,0BAA0B,YAAY,CAAC;AAEpD,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,MAAM,WAAW,iBAAiB;IAChC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,+EAA+E;IAC/E,MAAM,CAAC,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAAC;IAC5D,6EAA6E;IAC7E,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IACrC;;;;OAIG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAAC;CAC3D;AAUD,eAAO,MAAM,qBAAqB,EAAE,iBAwDnC,CAAC;AAKF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,qBAAqB,EAAE,iBAuCnC,CAAC;AAgEF,2EAA2E;AAC3E,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,UAAU,EAAE,SAAS,iBAAiB,EAGlD,CAAC"}