projen 0.101.6 → 0.101.8

package/lib/javascript/node-package.d.ts

@@ -1,3 +1,4 @@
+import type { PnpmWorkspaceYamlOptions } from "./pnpm-workspace";
 import type { YarnrcOptions } from "./yarnrc";
 import { Component } from "../component";
 import { JsonFile } from "../json";
@@ -288,6 +289,12 @@ export interface NodePackageOptions {
      * @default - Yarn Berry v4 with all default options
      */
     readonly yarnBerryOptions?: YarnBerryOptions;
+    /**
+     * Options for pnpm
+     *
+     * @default - all default options
+     */
+    readonly pnpmOptions?: PnpmOptions;
     /**
      * Configure the `devEngines` field in `package.json`.
      *
@@ -315,6 +322,39 @@ export interface NodePackageOptions {
      * @default true
      */
     readonly deleteOrphanedLockFiles?: boolean;
+    /**
+     * List of dependency (package) names that are allowed to run lifecycle
+     * install scripts (`preinstall`, `install`, `postinstall`, `prepare`)
+     * during dependency installation.
+     *
+     * These scripts can execute arbitrary code, making them a common
+     * supply-chain attack vector. Package managers are moving toward
+     * blocking them by default and requiring an explicit allowlist.
+     * Configuring `allowScripts` sets up that allowlist so scripts only run
+     * for the packages you have explicitly reviewed and trust.
+     *
+     * Support for this setting depends on the configured `packageManager`:
+     *
+     * - `NPM`: written to the native `allowScripts` field in `package.json`
+     *   (requires npm >= 11.16; see https://docs.npmjs.com/cli/v11/commands/npm-approve-scripts).
+     * - `BUN`: written to the native `trustedDependencies` field in
+     *   `package.json` (see https://bun.com/docs/pm/lifecycle).
+     * - `PNPM`: written to the `onlyBuiltDependencies` setting in
+     *   `pnpm-workspace.yaml` (see https://pnpm.io/settings#onlybuiltdependencies).
+     * - `YARN2`, `YARN_BERRY`: written to the native
+     *   `dependenciesMeta.<pkg>.built` allowlist in `package.json`, combined
+     *   with `enableScripts: false` in `.yarnrc.yml` (see
+     *   https://yarnpkg.com/features/security#postinstalls). If you set
+     *   `yarnBerryOptions.yarnRcOptions.enableScripts` explicitly, that value
+     *   is respected instead of being overridden.
+     * - `YARN`, `YARN_CLASSIC`: not supported. Yarn Classic has no native
+     *   mechanism to allowlist install scripts for specific dependencies.
+     *   Setting this option with one of these package managers throws an
+     *   error at synthesis time.
+     *
+     * @default - all install scripts are allowed to run (package manager default)
+     */
+    readonly allowScripts?: string[];
 }
 /**
  * A dependency entry for the `devEngines` field in `package.json`.
@@ -555,6 +595,7 @@ export declare class NodePackage extends Component {
     private readonly scripts;
     private readonly scriptsToBeRemoved;
     private readonly keywords;
+    private readonly allowedScripts;
     private readonly bin;
     private readonly engines;
     private readonly peerDependencyOptions;
@@ -620,6 +661,27 @@ export declare class NodePackage extends Component {
      * @param keywords The keywords to add
      */
     addKeywords(...keywords: string[]): void;
+    /**
+     * Allows the given dependency (package) names to run lifecycle install
+     * scripts (`preinstall`, `install`, `postinstall`, `prepare`), in addition
+     * to any already allowed via the `allowScripts` option or previous calls.
+     *
+     * Useful for project types that want to allowlist a package by default
+     * while still letting consumers add further packages via `allowScripts`.
+     *
+     * @param packages The dependency (package) names to allow.
+     * @see NodePackageOptions.allowScripts
+     */
+    addAllowedScripts(...packages: string[]): void;
+    /**
+     * Removes the given dependency (package) names from the `allowScripts`
+     * allowlist, whether they were added via the `allowScripts` option, a
+     * project type default, or a previous call to `addAllowedScripts`.
+     *
+     * @param packages The dependency (package) names to remove.
+     * @see NodePackageOptions.allowScripts
+     */
+    removeAllowedScripts(...packages: string[]): void;
     addBin(bins: Record<string, string>): void;
     /**
      * Add a npm package.json script.
@@ -722,6 +784,46 @@ export declare class NodePackage extends Component {
      */
     private resolveDepsAndWritePackageJson;
     private renderPackageResolutions;
+    /**
+     * Renders the native npm `allowScripts` field (`{ "pkg": true }`) from the
+     * `allowScripts` allowlist.
+     *
+     * @see https://docs.npmjs.com/cli/v11/commands/npm-approve-scripts
+     */
+    private renderNpmAllowScripts;
+    /**
+     * Renders the native bun `trustedDependencies` field from the
+     * `allowScripts` allowlist.
+     *
+     * @see https://bun.com/docs/pm/lifecycle
+     */
+    private renderBunTrustedDependencies;
+    /**
+     * Renders the native yarn berry per-package script allowlist via
+     * `dependenciesMeta.<pkg>.built = true`. Combined with the global
+     * `enableScripts: false` yarnrc setting (set in `configureYarnBerry`),
+     * this allows install scripts to run only for the listed packages.
+     *
+     * @see https://yarnpkg.com/configuration/manifest#dependenciesMeta.built
+     * @see https://yarnpkg.com/features/security#postinstalls
+     */
+    private renderYarnBerryDependenciesMeta;
+    /**
+     * Validates and configures the `allowScripts` allowlist for the resolved
+     * package manager, throwing a descriptive error for package managers that
+     * have no native way to allowlist install scripts per-dependency.
+     */
+    private configureAllowScripts;
+    /**
+     * Configures the `PnpmWorkspaceYaml` component, merging `onlyBuiltDependencies`
+     * from `allowScripts` and any explicit `pnpmOptions.workspaceYamlOptions`.
+     * The merge is resolved lazily (at synthesis time), so calls to
+     * `addAllowedScripts`/`removeAllowedScripts` made after this runs are
+     * still reflected. The file is only written if it ends up with actual
+     * content (see `omitEmpty`), so this is safe to call unconditionally for
+     * every pnpm project.
+     */
+    private configurePnpm;
     private renderPublishConfig;
     private renderKeywords;
     private renderEngines;
@@ -841,6 +943,17 @@ export interface YarnBerryOptions {
      */
     readonly zeroInstalls?: boolean;
 }
+/**
+ * Configure pnpm
+ */
+export interface PnpmOptions {
+    /**
+     * The `pnpm-workspace.yaml` configuration.
+     *
+     * @default - a blank pnpm-workspace.yaml file
+     */
+    readonly workspaceYamlOptions?: PnpmWorkspaceYamlOptions;
+}
 /**
  * Why a dependency install was triggered during synthesis.
  */