refactor(functions): Create kits install API and include env seeding support

[wandamora]

Description

This PR refactors the Function Kits installation workflow from src/commands/functions-kits-install.ts into a reusable, programmatic library in src/functions/kits/, enabling shared usage by both firebase functions:kits:install and firebase ext:migrate:

• Shared Installation Orchestrator (src/functions/kits/install.ts):
  • Introduces installKitOrInstance(options: InstallKitOrInstanceOptions): Promise<InstallKitOrInstanceResult>, which coordinates the full installation flow (package validation, security check/prompt, ID prompting/resolution, scaffolding, npm install/build, config update, env seeding, and deploy reporting).
  • Handles both brand-new kit installations (installedKit), adding instances to an existing kit (addedInstance), and environment guidance for existing instances (configuredEnv).
  • Supports optional kitId and instanceId overrides in InstallKitOrInstanceOptions to allow programmatic callers (like ext:migrate) to specify IDs directly and bypass interactive prompts.
  • Moves all interactive prompts (promptKitId, promptKitInstanceId, promptSecurityConfirmation, promptExistingInstanceForProject, addKitInstanceOrConfigureProject) and deploy reporting (printKitFirstDeployReport) into the library.
  • Lazy-loads template files at runtime instead of top-level module load.
• Environment Parameter Seeding (src/functions/kits/env.ts):
  • Implements seedKitInstanceEnv to write/seed instance environment variables into .env.<projectId>, supporting primitives, arrays (comma-separated), and nested map/JSON objects (e.g. for migrating extension parameters).
• Thin Command Wrapper (src/commands/functions-kits-install.ts):
  • Simplifies the CLI command to assert the kits experiment, validate input presence, and delegate directly to installKitOrInstance.
• Unit Tests (src/functions/kits/*.spec.ts, src/commands/functions-kits-install.spec.ts):
  • Co-locates comprehensive unit tests with the library covering package validation, ID collision handling, security prompts, scaffolding, existing kit flows, environment seeding, and command argument delegation.

Scenarios Tested

• Unit tests across all kit installation and environment modules:
  • Valid and invalid NPM package names/specifiers.
  • Unique ID generation and collision handling for kit IDs, instance IDs, and codebase names.
  • Third-party packages and npm-shrinkwrap.json security confirmation flows.
  • Template resolution and lazy loading for installation and migration templates.
  • Seeding .env.<projectId> with strings, numbers, booleans, arrays, and JSON objects.
  • Adding a new instance or configuring env when the kit package already exists in firebase.json.
  • Command argument delegation and experiment verification in functions:kits:install.

Sample Commands

# Existing CLI usage remains unchanged:
firebase functions:kits:install --package @firebase-functions-kits/firestore-bigquery-export

/* Programmatic API usage by other features: */
const result = await installKit({
  config: options.config,
  package: plan.kitPackage,
  template: "migration",
  instanceId: plan.instanceId,
  seedEnv: {
    projectId,
    envs: plan.instance.config.params,
  },
  nonInteractive: options.nonInteractive,
  project: options.project,
  projectId,
  rc: options.rc,
});

[wiz-9635d3485b]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	23
Software Management Findings	-
Total	23

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

[gemini-code-assist]

Code Review

This pull request refactors the function kits installation logic by extracting utility functions and scaffolding helpers from src/commands/functions-kits-install.ts into a new dedicated module under src/functions/kits/, accompanied by comprehensive unit tests in install.spec.ts and env.spec.ts. The review feedback highlights several key improvement opportunities: ensuring robust configuration updates in addInstanceToKitConfig by searching the configuration array instead of relying on object reference identity, utilizing a discriminated union for KitInstanceEnvSeed to enforce compile-time safety when environment variables are provided, and replacing string-based .replace() calls with global regular expressions to prevent partial template replacement bugs.

[ajperel]

I think this likely needs more thought to be the right abstraction as to what we have easily available for ext:migrate to use, but I'm approving it as is since it might be easier to coordinate with Thomas on the next iteration if it's merged and I don't think this is bad so much as not quite right.

[ajperel]

This feels like another place where we're exacerbating the problem with how migrate index.js is doing a probably invalid JSON.parse. Is now the time to fix that?

[wandamora]

This handles arrays, but this is a good reminder that I'm not handling map values here. I'm going to serialize map/object values into a JSON string, as that is what the template expects.

[ajperel]

I think the biggest thing is we need to be clear on what needs to be in this command file vs. a library more. Honestly my first take would have been that functions-kits-install is only this new command and everything else lives in functions/kits/install.ts for maximum flexibility.

And even there... what does ext:migrate want to have in overlapping behavior. We still in that flow want to prompt about 3rd party, shrink wrap, etc. I think even the majority of this command should probably move into the library and ext migrate can do something like:

installKit({
   package: <identified npm package>,
   template: <migration template>,
   env: <dict>
})```

And we have a discussion of if that should also accept kit id or kit instance id into the install command. And then basically `ext:migrate` once it has identified what kit needs to be installed can delegate all details of it to `installKit` and get back the info it needs (kit name, instance id, etc.) Or provide it upfront.

We could land this and iterate in a future PR, or see if you can get a few minutes with Thomas and iterate on it in this PR. I'm not sure what's better.

[wandamora]

Thanks for calling this out. I moved the remaining logic to the library and created an InstallKitOrInstance (just to be a bit more self-documenting about how it can add either), and the function should be able to take kit or instance id to override defaults. This function also returns an "action" field to provide more information on what action was performed. I think this warrants another review, PTAL.

[ajperel]

Nice. I think this makes things maximally re-useable for ext:migrate and very composable/easy to change from here if needed.