@aws/nx-plugin 1.0.0-rc.53 → 1.0.0-rc.55

package/src/utils/connection/open-api/react.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/utils/connection/open-api/react.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { addTargetToLocalDev } from '../../../connection/local-dev';\nimport runtimeConfigGenerator from '../../../ts/react-website/runtime-config/generator';\nimport { addSingleImport, applyGritQL } from '../../ast';\nimport { addDependenciesToPackageJson } from '../../dependencies';\nimport { updateGitIgnore } from '../../git';\nimport { kebabCase, toClassName } from '../../names';\nimport { sortObjectKeys } from '../../object';\nimport { withVersions } from '../../versions';\n\nexport interface AddOpenApiReactClientOptions {\n  /**\n   * The react project to add the openapi client and build targets to\n   */\n  frontendProjectConfig: ProjectConfiguration;\n  /**\n   * The backend project which serves the api\n   */\n  backendProjectConfig: ProjectConfiguration;\n  /**\n   * The project which builds/generates the openapi spec\n   */\n  specBuildProject: ProjectConfiguration;\n  /**\n   * Name of the api\n   */\n  apiName: string;\n  /**\n   * Path to the openapi spec from the workspace root\n   */\n  specPath: string;\n  /**\n   * Fully qualified target name for the target that builds/generates the openapi spec\n   */\n  specBuildTargetName: string;\n  /**\n   * Authentication method\n   */\n  auth: 'iam' | 'cognito' | 'custom';\n  /**\n   * Port on which the backend project's local server listens\n   */\n  port: number;\n  /**\n   * When true, the generated provider reads from runtimeConfig.agentRuntimes\n   * and converts Bedrock AgentCore Runtime ARNs to HTTP URLs.\n   * When false (default), reads from runtimeConfig.apis directly.\n   */\n  isAgentRuntime?: boolean;\n  /**\n   * When true, skips the dev target setup. Use this when the caller\n   * handles dev target configuration separately (e.g. agent connections\n   * that use a component-specific dev target instead of 'serve').\n   */\n  skipLocalDev?: boolean;\n}\n\n/**\n * Adds an OpenAPI React client to the frontend project along with supporting build targets\n */\nexport const addOpenApiReactClient = async (\n  tree: Tree,\n  {\n    apiName,\n    frontendProjectConfig,\n    backendProjectConfig,\n    specBuildProject,\n    specPath,\n    specBuildTargetName,\n    auth,\n    port,\n    isAgentRuntime = false,\n    skipLocalDev = false,\n  }: AddOpenApiReactClientOptions,\n) => {\n  const clientGenTarget = `generate:${kebabCase(apiName)}-client`;\n  const clientGenWatchTarget = `watch-${clientGenTarget}`;\n\n  const generatedClientDir = joinPathFragments('generated', kebabCase(apiName));\n  const generatedClientDirFromRoot = joinPathFragments(\n    frontendProjectConfig.sourceRoot,\n    generatedClientDir,\n  );\n\n  // Add TypeScript client generation to Frontend project.json\n  updateProjectConfiguration(tree, frontendProjectConfig.name, {\n    ...frontendProjectConfig,\n    targets: sortObjectKeys({\n      ...frontendProjectConfig.targets,\n      // Generate should run before compile and bundle as the client is created as part of the website src\n      ...Object.fromEntries(\n        ['compile', 'bundle'].map((target) => [\n          target,\n          {\n            ...frontendProjectConfig.targets?.[target],\n            dependsOn: [\n              ...(\n                frontendProjectConfig.targets?.[target]?.dependsOn ?? []\n              ).filter((t) => t !== clientGenTarget),\n              clientGenTarget,\n            ],\n          },\n        ]),\n      ),\n      [clientGenTarget]: {\n        cache: true,\n        executor: 'nx:run-commands',\n        inputs: [\n          {\n            dependentTasksOutputFiles: '**/*.json',\n          },\n        ],\n        outputs: [\n          joinPathFragments('{workspaceRoot}', generatedClientDirFromRoot),\n        ],\n        options: {\n          commands: [\n            `nx g @aws/nx-plugin:open-api#ts-hooks --openApiSpecPath=\"${specPath}\" --outputPath=\"${generatedClientDirFromRoot}\" --no-interactive`,\n          ],\n        },\n        dependsOn: [specBuildTargetName],\n      },\n      // Watch target for regenerating the client\n      [clientGenWatchTarget]: {\n        executor: 'nx:run-commands',\n        options: {\n          commands: [\n            `nx watch --projects=${specBuildProject.name} --includeDependencies -- nx run ${frontendProjectConfig.name}:\"${clientGenTarget}\"`,\n          ],\n        },\n        continuous: true,\n      },\n    }),\n  });\n\n  const relativeSrcDir = frontendProjectConfig.sourceRoot.slice(\n    frontendProjectConfig.root.length + 1,\n  );\n\n  // Ignore the generated client by default\n  // Users can safely remove the entry from the .gitignore if they prefer to check it in\n  updateGitIgnore(tree, frontendProjectConfig.root, (patterns) => [\n    ...patterns,\n    joinPathFragments(relativeSrcDir, generatedClientDir),\n  ]);\n\n  // Ensure that the frontend has runtime config as we'll use the url for creating the client\n  await runtimeConfigGenerator(tree, {\n    project: frontendProjectConfig.name,\n  });\n\n  // Add sigv4 fetch\n  if (auth === 'iam') {\n    generateFiles(\n      tree,\n      joinPathFragments(import.meta.dirname, '../../files/website/hooks/sigv4'),\n      joinPathFragments(frontendProjectConfig.sourceRoot, 'hooks'),\n      {},\n      {\n        overwriteStrategy: OverwriteStrategy.KeepExisting,\n      },\n    );\n  }\n\n  // Generate the tanstack query provider if it does not exist already\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      '../../files/website/components/tanstack-query',\n    ),\n    joinPathFragments(frontendProjectConfig.sourceRoot, 'components'),\n    {},\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  const apiNameClassName = toClassName(apiName);\n\n  // Add a hook to instantiate the client\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files'),\n    frontendProjectConfig.sourceRoot,\n    {\n      auth,\n      apiName,\n      apiNameClassName,\n      generatedClientDir,\n      isAgentRuntime,\n    },\n  );\n\n  // Update main.tsx to add required providers\n  const mainTsxPath = joinPathFragments(\n    frontendProjectConfig.sourceRoot,\n    'main.tsx',\n  );\n\n  // Add the query client provider if it doesn't exist already\n  await addSingleImport(\n    tree,\n    mainTsxPath,\n    'QueryClientProvider',\n    './components/QueryClientProvider',\n  );\n  await applyGritQL(\n    tree,\n    mainTsxPath,\n    '`<App />` => `<QueryClientProvider><App /></QueryClientProvider>` where { $program <: not contains `<QueryClientProvider>$_</QueryClientProvider>` }',\n  );\n\n  // Add the api provider if it does not exist\n  const providerName = `${apiNameClassName}Provider`;\n  await addSingleImport(\n    tree,\n    mainTsxPath,\n    providerName,\n    `./components/${providerName}`,\n  );\n  await applyGritQL(\n    tree,\n    mainTsxPath,\n    `\\`<App />\\` => \\`<${providerName}><App /></${providerName}>\\` where { $program <: not contains \\`<${providerName}>$_</${providerName}>\\` }`,\n  );\n\n  // Update the dev target on the website to use our local server.\n  // Callers that handle the dev target separately (e.g. agent connections) set skipLocalDev.\n  if (!skipLocalDev) {\n    await addTargetToLocalDev(\n      tree,\n      frontendProjectConfig.name,\n      backendProjectConfig.name,\n      {\n        url: `http://localhost:${port}/`,\n        apiName,\n        // Additionally add a dependency on the generate watch command to ensure that local\n        // API changes that affect the client are also reloaded.\n        // We include a dependency on the generate target as watch ONLY triggers on a change,\n        // and we need to ensure the client is generated the first time if not already present.\n        additionalDependencyTargets: [clientGenTarget, clientGenWatchTarget],\n      },\n    );\n  }\n\n  addDependenciesToPackageJson(\n    tree,\n    withVersions([\n      ...((auth === 'iam'\n        ? [\n            'oidc-client-ts',\n            'react-oidc-context',\n            '@aws-sdk/credential-provider-cognito-identity',\n            'aws4fetch',\n          ]\n        : []) as any),\n      ...((auth === 'cognito' ? ['react-oidc-context'] : []) as any),\n      '@tanstack/react-query',\n      '@tanstack/react-query-devtools',\n    ]),\n    withVersions(['@smithy/types']),\n    joinPathFragments(frontendProjectConfig.root, 'package.json'),\n  );\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","addTargetToLocalDev","runtimeConfigGenerator","addSingleImport","applyGritQL","addDependenciesToPackageJson","updateGitIgnore","kebabCase","toClassName","sortObjectKeys","withVersions","addOpenApiReactClient","tree","apiName","frontendProjectConfig","backendProjectConfig","specBuildProject","specPath","specBuildTargetName","auth","port","isAgentRuntime","skipLocalDev","clientGenTarget","clientGenWatchTarget","generatedClientDir","generatedClientDirFromRoot","sourceRoot","name","targets","Object","fromEntries","map","target","dependsOn","filter","t","cache","executor","inputs","dependentTasksOutputFiles","outputs","options","commands","continuous","relativeSrcDir","slice","root","length","patterns","project","dirname","overwriteStrategy","KeepExisting","apiNameClassName","mainTsxPath","providerName","url","additionalDependencyTargets"],"mappings":"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"}
+{"version":3,"sources":["../../../../../../../packages/nx-plugin/src/utils/connection/open-api/react.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  generateFiles,\n  joinPathFragments,\n  OverwriteStrategy,\n  type ProjectConfiguration,\n  type Tree,\n  updateProjectConfiguration,\n} from '@nx/devkit';\nimport { addTargetToLocalDev } from '../../../connection/local-dev';\nimport runtimeConfigGenerator from '../../../ts/react-website/runtime-config/generator';\nimport { addSingleImport, applyGritQL } from '../../ast';\nimport {\n  type DependencyDeclaration,\n  forDependencies,\n  type MustDeclare,\n} from '../../declared-dependencies';\nimport { addDependenciesToPackageJson } from '../../dependencies';\nimport { updateGitIgnore } from '../../git';\nimport { kebabCase, toClassName } from '../../names';\nimport { sortObjectKeys } from '../../object';\nimport { type ITsDepVersion, withVersions } from '../../versions';\n\n/** Dependencies a caller must declare to add an OpenAPI React client. */\nexport const OPEN_API_REACT_DEPENDENCIES = [\n  { name: 'oidc-client-ts' },\n  { name: 'react-oidc-context' },\n  { name: '@aws-sdk/credential-provider-cognito-identity' },\n  { name: 'aws4fetch' },\n  { name: '@tanstack/react-query' },\n  { name: '@tanstack/react-query-devtools' },\n  { name: '@smithy/types' },\n] as const satisfies readonly { name: ITsDepVersion }[];\n\nexport interface AddOpenApiReactClientOptions {\n  /**\n   * The react project to add the openapi client and build targets to\n   */\n  frontendProjectConfig: ProjectConfiguration;\n  /**\n   * The backend project which serves the api\n   */\n  backendProjectConfig: ProjectConfiguration;\n  /**\n   * The project which builds/generates the openapi spec\n   */\n  specBuildProject: ProjectConfiguration;\n  /**\n   * Name of the api\n   */\n  apiName: string;\n  /**\n   * Path to the openapi spec from the workspace root\n   */\n  specPath: string;\n  /**\n   * Fully qualified target name for the target that builds/generates the openapi spec\n   */\n  specBuildTargetName: string;\n  /**\n   * Authentication method\n   */\n  auth: 'iam' | 'cognito' | 'custom';\n  /**\n   * Port on which the backend project's local server listens\n   */\n  port: number;\n  /**\n   * When true, the generated provider reads from runtimeConfig.agentRuntimes\n   * and converts Bedrock AgentCore Runtime ARNs to HTTP URLs.\n   * When false (default), reads from runtimeConfig.apis directly.\n   */\n  isAgentRuntime?: boolean;\n  /**\n   * When true, skips the dev target setup. Use this when the caller\n   * handles dev target configuration separately (e.g. agent connections\n   * that use a component-specific dev target instead of 'serve').\n   */\n  skipLocalDev?: boolean;\n}\n\n/**\n * Adds an OpenAPI React client to the frontend project along with supporting build targets\n */\nexport const addOpenApiReactClient = async <\n  const D extends DependencyDeclaration,\n>(\n  tree: Tree,\n  {\n    apiName,\n    frontendProjectConfig,\n    backendProjectConfig,\n    specBuildProject,\n    specPath,\n    specBuildTargetName,\n    auth,\n    port,\n    isAgentRuntime = false,\n    skipLocalDev = false,\n  }: AddOpenApiReactClientOptions,\n  declaration: D & MustDeclare<typeof OPEN_API_REACT_DEPENDENCIES, D>,\n) => {\n  const clientGenTarget = `generate:${kebabCase(apiName)}-client`;\n  const clientGenWatchTarget = `watch-${clientGenTarget}`;\n\n  const generatedClientDir = joinPathFragments('generated', kebabCase(apiName));\n  const generatedClientDirFromRoot = joinPathFragments(\n    frontendProjectConfig.sourceRoot,\n    generatedClientDir,\n  );\n\n  // Add TypeScript client generation to Frontend project.json\n  updateProjectConfiguration(tree, frontendProjectConfig.name, {\n    ...frontendProjectConfig,\n    targets: sortObjectKeys({\n      ...frontendProjectConfig.targets,\n      // Generate should run before compile and bundle as the client is created as part of the website src\n      ...Object.fromEntries(\n        ['compile', 'bundle'].map((target) => [\n          target,\n          {\n            ...frontendProjectConfig.targets?.[target],\n            dependsOn: [\n              ...(\n                frontendProjectConfig.targets?.[target]?.dependsOn ?? []\n              ).filter((t) => t !== clientGenTarget),\n              clientGenTarget,\n            ],\n          },\n        ]),\n      ),\n      [clientGenTarget]: {\n        cache: true,\n        executor: 'nx:run-commands',\n        inputs: [\n          {\n            dependentTasksOutputFiles: '**/*.json',\n          },\n        ],\n        outputs: [\n          joinPathFragments('{workspaceRoot}', generatedClientDirFromRoot),\n        ],\n        options: {\n          commands: [\n            `nx g @aws/nx-plugin:open-api#ts-hooks --openApiSpecPath=\"${specPath}\" --outputPath=\"${generatedClientDirFromRoot}\" --no-interactive`,\n          ],\n        },\n        dependsOn: [specBuildTargetName],\n      },\n      // Watch target for regenerating the client\n      [clientGenWatchTarget]: {\n        executor: 'nx:run-commands',\n        options: {\n          commands: [\n            `nx watch --projects=${specBuildProject.name} --includeDependencies -- nx run ${frontendProjectConfig.name}:\"${clientGenTarget}\"`,\n          ],\n        },\n        continuous: true,\n      },\n    }),\n  });\n\n  const relativeSrcDir = frontendProjectConfig.sourceRoot.slice(\n    frontendProjectConfig.root.length + 1,\n  );\n\n  // Ignore the generated client by default\n  // Users can safely remove the entry from the .gitignore if they prefer to check it in\n  updateGitIgnore(tree, frontendProjectConfig.root, (patterns) => [\n    ...patterns,\n    joinPathFragments(relativeSrcDir, generatedClientDir),\n  ]);\n\n  // Ensure that the frontend has runtime config as we'll use the url for creating the client\n  await runtimeConfigGenerator(tree, {\n    project: frontendProjectConfig.name,\n  });\n\n  // Add sigv4 fetch\n  if (auth === 'iam') {\n    generateFiles(\n      tree,\n      joinPathFragments(import.meta.dirname, '../../files/website/hooks/sigv4'),\n      joinPathFragments(frontendProjectConfig.sourceRoot, 'hooks'),\n      {},\n      {\n        overwriteStrategy: OverwriteStrategy.KeepExisting,\n      },\n    );\n  }\n\n  // Generate the tanstack query provider if it does not exist already\n  generateFiles(\n    tree,\n    joinPathFragments(\n      import.meta.dirname,\n      '../../files/website/components/tanstack-query',\n    ),\n    joinPathFragments(frontendProjectConfig.sourceRoot, 'components'),\n    {},\n    {\n      overwriteStrategy: OverwriteStrategy.KeepExisting,\n    },\n  );\n\n  const apiNameClassName = toClassName(apiName);\n\n  // Add a hook to instantiate the client\n  generateFiles(\n    tree,\n    joinPathFragments(import.meta.dirname, 'files'),\n    frontendProjectConfig.sourceRoot,\n    {\n      auth,\n      apiName,\n      apiNameClassName,\n      generatedClientDir,\n      isAgentRuntime,\n    },\n  );\n\n  // Update main.tsx to add required providers\n  const mainTsxPath = joinPathFragments(\n    frontendProjectConfig.sourceRoot,\n    'main.tsx',\n  );\n\n  // Add the query client provider if it doesn't exist already\n  await addSingleImport(\n    tree,\n    mainTsxPath,\n    'QueryClientProvider',\n    './components/QueryClientProvider',\n  );\n  await applyGritQL(\n    tree,\n    mainTsxPath,\n    '`<App />` => `<QueryClientProvider><App /></QueryClientProvider>` where { $program <: not contains `<QueryClientProvider>$_</QueryClientProvider>` }',\n  );\n\n  // Add the api provider if it does not exist\n  const providerName = `${apiNameClassName}Provider`;\n  await addSingleImport(\n    tree,\n    mainTsxPath,\n    providerName,\n    `./components/${providerName}`,\n  );\n  await applyGritQL(\n    tree,\n    mainTsxPath,\n    `\\`<App />\\` => \\`<${providerName}><App /></${providerName}>\\` where { $program <: not contains \\`<${providerName}>$_</${providerName}>\\` }`,\n  );\n\n  // Update the dev target on the website to use our local server.\n  // Callers that handle the dev target separately (e.g. agent connections) set skipLocalDev.\n  if (!skipLocalDev) {\n    await addTargetToLocalDev(\n      tree,\n      frontendProjectConfig.name,\n      backendProjectConfig.name,\n      {\n        url: `http://localhost:${port}/`,\n        apiName,\n        // Additionally add a dependency on the generate watch command to ensure that local\n        // API changes that affect the client are also reloaded.\n        // We include a dependency on the generate target as watch ONLY triggers on a change,\n        // and we need to ensure the client is generated the first time if not already present.\n        additionalDependencyTargets: [clientGenTarget, clientGenWatchTarget],\n      },\n    );\n  }\n\n  addDependenciesToPackageJson(\n    tree,\n    withVersions(\n      forDependencies<typeof OPEN_API_REACT_DEPENDENCIES>(declaration),\n      [\n        ...((auth === 'iam'\n          ? [\n              'oidc-client-ts',\n              'react-oidc-context',\n              '@aws-sdk/credential-provider-cognito-identity',\n              'aws4fetch',\n            ]\n          : []) as any),\n        ...((auth === 'cognito' ? ['react-oidc-context'] : []) as any),\n        '@tanstack/react-query',\n        '@tanstack/react-query-devtools',\n      ],\n    ),\n    withVersions(\n      forDependencies<typeof OPEN_API_REACT_DEPENDENCIES>(declaration),\n      ['@smithy/types'],\n    ),\n    joinPathFragments(frontendProjectConfig.root, 'package.json'),\n  );\n};\n"],"names":["generateFiles","joinPathFragments","OverwriteStrategy","updateProjectConfiguration","addTargetToLocalDev","runtimeConfigGenerator","addSingleImport","applyGritQL","forDependencies","addDependenciesToPackageJson","updateGitIgnore","kebabCase","toClassName","sortObjectKeys","withVersions","OPEN_API_REACT_DEPENDENCIES","name","addOpenApiReactClient","tree","apiName","frontendProjectConfig","backendProjectConfig","specBuildProject","specPath","specBuildTargetName","auth","port","isAgentRuntime","skipLocalDev","declaration","clientGenTarget","clientGenWatchTarget","generatedClientDir","generatedClientDirFromRoot","sourceRoot","targets","Object","fromEntries","map","target","dependsOn","filter","t","cache","executor","inputs","dependentTasksOutputFiles","outputs","options","commands","continuous","relativeSrcDir","slice","root","length","patterns","project","dirname","overwriteStrategy","KeepExisting","apiNameClassName","mainTsxPath","providerName","url","additionalDependencyTargets"],"mappings":"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"}

package/src/utils/declared-dependencies.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { IPyDepVersion, ITsDepVersion } from './versions';
+/**
+ * Which vended dependencies each generator is responsible for, and when each
+ * applies.
+ *
+ * A generator declares every dependency it may add — including those added on
+ * its behalf by helpers it calls — once, and `addTsDependencies` /
+ * `addPyDependencies` add the subset whose `when` predicate the generator's
+ * metadata satisfies. The declaration is the only place packages are listed.
+ *
+ * The same declaration drives the version sync migration, which replays the
+ * predicates against the metadata recorded on each project. Pass the very object
+ * you record as metadata, so what a generator added and what the migration owns
+ * cannot drift.
+ */
+/**
+ * The metadata a generator records, which its predicates read. Deliberately
+ * `object` rather than an index signature, so a generator can type its
+ * declaration against a plain interface.
+ */
+export type DependencyMetadata = object;
+/** What every declared dependency carries, whichever language it belongs to. */
+export interface DeclaredDependency<Name, M extends DependencyMetadata> {
+    readonly name: Name;
+    /**
+     * Whether this dependency applies. Reads the metadata the generator records,
+     * so the migration can evaluate the same predicate later. Any truthy return
+     * counts, so a predicate can hand back the value it read.
+     */
+    readonly when?: (metadata: M) => unknown;
+    /** Added to the workspace root manifest rather than the project's. */
+    readonly root?: boolean;
+    /**
+     * Declared only so the version sync keeps its pinned version current — an
+     * `overrides` entry, say. Never installed as a dependency.
+     */
+    readonly versionOnly?: boolean;
+}
+/**
+ * A TypeScript dependency, which may be a dev dependency.
+ *
+ * `group` is typed as never-present rather than left off, so putting a Python
+ * flag on a TypeScript entry is a type error instead of an ignored property.
+ */
+export interface DeclaredTsDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added as a dev dependency rather than a runtime one. */
+    readonly dev?: boolean;
+    readonly group?: never;
+}
+/** A Python dependency, which may belong to a pyproject dependency group. */
+export interface DeclaredPyDependency<Name, M extends DependencyMetadata> extends DeclaredDependency<Name, M> {
+    /** Added to this pyproject dependency group rather than the main list. */
+    readonly group?: string;
+    readonly dev?: never;
+}
+export interface DependencyDeclaration<Ts extends readonly DeclaredTsDependency<ITsDepVersion, never>[] = readonly DeclaredTsDependency<ITsDepVersion, never>[], Py extends readonly DeclaredPyDependency<IPyDepVersion, never>[] = readonly DeclaredPyDependency<IPyDepVersion, never>[]> {
+    readonly ts: Ts;
+    readonly py: Py;
+}
+/**
+ * Declare the dependencies a generator owns, typed against the metadata it
+ * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration
+ * covers what those helpers add too.
+ */
+export declare const declareDependencies: <M extends DependencyMetadata = Record<string, never>>() => <const Ts extends readonly DeclaredTsDependency<ITsDepVersion, M>[], const Py extends readonly DeclaredPyDependency<IPyDepVersion, M>[]>(declaration: {
+    ts?: Ts;
+    py?: Py;
+}) => DependencyDeclaration<Ts, Py>;
+/**
+ * Narrow entries to a further condition, keeping the one each already carries.
+ *
+ * For a helper's constant spread into a generator that calls it down one branch:
+ * the branch gates the whole set, and each entry's own predicate still gates it
+ * within that branch. Replacing `when` outright would widen ownership to the
+ * helper's every branch.
+ */
+export declare const onlyWhen: <M extends DependencyMetadata, const Entries extends readonly {
+    readonly name: unknown;
+}[]>(entries: Entries, condition: (metadata: M) => unknown) => { readonly [K in keyof Entries]: Omit<Entries[K], "when"> & {
+    when: (m: M) => boolean;
+}; };
+/**
+ * Mark entries as declared for ownership but never installed here — a helper's
+ * constant spread into a generator that doesn't own the project the helper adds
+ * them to.
+ */
+export declare const ownedElsewhere: <const Entries extends readonly unknown[]>(entries: Entries) => { readonly [K in keyof Entries]: Entries[K] & {
+    versionOnly: true;
+}; };
+/** Every package a declaration names, whatever its predicate. */
+export declare const declaredNames: <Name>(entries: readonly {
+    readonly name: Name;
+}[]) => Name[];
+/**
+ * The entries of a declaration whose condition the given metadata satisfies —
+ * everything this occurrence is responsible for, installed here or not.
+ *
+ * A predicate that throws — reading a field the metadata doesn't carry, say —
+ * counts as not applying. The migration evaluates these against whatever a
+ * project happened to record, and must not claim a branch it cannot confirm.
+ */
+export declare const ownedDependencyEntries: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * The entries to install for the given metadata: those it owns, less the ones
+ * declared for their version alone. A `versionOnly` entry is still owned — the
+ * sync keeps its pin current wherever it already sits.
+ */
+export declare const applicableDependencies: <Name, M extends DependencyMetadata, Entry extends DeclaredDependency<Name, M>>(entries: readonly Entry[], metadata: M) => Entry[];
+/**
+ * Requires a caller's declaration to cover `Needed`, naming whatever is missing
+ * in the type error. Helpers that add dependencies take this alongside the
+ * declaration so a forgotten spread can't compile.
+ */
+export type MustDeclare<Needed extends readonly {
+    readonly name: ITsDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['ts'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredDependencies: Exclude<Needed[number]['name'], D['ts'][number]['name']>;
+};
+/** `MustDeclare` for Python dependencies. */
+export type MustDeclarePy<Needed extends readonly {
+    readonly name: IPyDepVersion;
+}[], D extends DependencyDeclaration> = [Exclude<Needed[number]['name'], D['py'][number]['name']>] extends [never] ? unknown : {
+    __missingDeclaredPyDependencies: Exclude<Needed[number]['name'], D['py'][number]['name']>;
+};
+/**
+ * The dependencies a declaration covers, for typing a conditional list without
+ * widening it to every vended package.
+ */
+export type DeclaredTs<D extends DependencyDeclaration> = D['ts'][number]['name'];
+/** `DeclaredTs` for Python dependencies. */
+export type DeclaredPy<D extends DependencyDeclaration> = D['py'][number]['name'];
+/**
+ * Narrows a caller's declaration to the subset a helper adds, which
+ * `MustDeclare` has already proven the caller covers.
+ */
+export declare const forDependencies: <const Ts extends readonly DeclaredDependency<ITsDepVersion, never>[] = [], const Py extends readonly DeclaredDependency<IPyDepVersion, never>[] = []>(declaration: DependencyDeclaration) => DependencyDeclaration<Ts, Py>;

package/src/utils/declared-dependencies.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ /**
+ * Declare the dependencies a generator owns, typed against the metadata it
+ * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration
+ * covers what those helpers add too.
+ */ export const declareDependencies = ()=>(declaration)=>({
+            ts: declaration.ts ?? [],
+            py: declaration.py ?? []
+        });
+/**
+ * Narrow entries to a further condition, keeping the one each already carries.
+ *
+ * For a helper's constant spread into a generator that calls it down one branch:
+ * the branch gates the whole set, and each entry's own predicate still gates it
+ * within that branch. Replacing `when` outright would widen ownership to the
+ * helper's every branch.
+ */ export const onlyWhen = (entries, condition)=>entries.map((entry)=>{
+        // A declaration erases the metadata its predicates read, so calling one back
+        // requires naming the type the caller narrows to.
+        const own = entry.when;
+        return {
+            ...entry,
+            when: (metadata)=>Boolean(condition(metadata)) && Boolean(own?.(metadata) ?? true)
+        };
+    });
+/**
+ * Mark entries as declared for ownership but never installed here — a helper's
+ * constant spread into a generator that doesn't own the project the helper adds
+ * them to.
+ */ export const ownedElsewhere = (entries)=>entries.map((entry)=>({
+            ...entry,
+            versionOnly: true
+        }));
+/** Every package a declaration names, whatever its predicate. */ export const declaredNames = (entries)=>entries.map((entry)=>entry.name);
+/**
+ * The entries of a declaration whose condition the given metadata satisfies —
+ * everything this occurrence is responsible for, installed here or not.
+ *
+ * A predicate that throws — reading a field the metadata doesn't carry, say —
+ * counts as not applying. The migration evaluates these against whatever a
+ * project happened to record, and must not claim a branch it cannot confirm.
+ */ export const ownedDependencyEntries = (entries, metadata)=>entries.filter((entry)=>{
+        if (!entry.when) {
+            return true;
+        }
+        try {
+            return Boolean(entry.when(metadata));
+        } catch  {
+            return false;
+        }
+    });
+/**
+ * The entries to install for the given metadata: those it owns, less the ones
+ * declared for their version alone. A `versionOnly` entry is still owned — the
+ * sync keeps its pin current wherever it already sits.
+ */ export const applicableDependencies = (entries, metadata)=>ownedDependencyEntries(entries, metadata).filter((entry)=>!entry.versionOnly);
+/**
+ * Narrows a caller's declaration to the subset a helper adds, which
+ * `MustDeclare` has already proven the caller covers.
+ */ export const forDependencies = (declaration)=>declaration;
+
+//# sourceMappingURL=declared-dependencies.js.map

package/src/utils/declared-dependencies.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/declared-dependencies.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { IPyDepVersion, ITsDepVersion } from './versions';\n\n/**\n * Which vended dependencies each generator is responsible for, and when each\n * applies.\n *\n * A generator declares every dependency it may add — including those added on\n * its behalf by helpers it calls — once, and `addTsDependencies` /\n * `addPyDependencies` add the subset whose `when` predicate the generator's\n * metadata satisfies. The declaration is the only place packages are listed.\n *\n * The same declaration drives the version sync migration, which replays the\n * predicates against the metadata recorded on each project. Pass the very object\n * you record as metadata, so what a generator added and what the migration owns\n * cannot drift.\n */\n\n/**\n * The metadata a generator records, which its predicates read. Deliberately\n * `object` rather than an index signature, so a generator can type its\n * declaration against a plain interface.\n */\nexport type DependencyMetadata = object;\n\n/** What every declared dependency carries, whichever language it belongs to. */\nexport interface DeclaredDependency<Name, M extends DependencyMetadata> {\n  readonly name: Name;\n  /**\n   * Whether this dependency applies. Reads the metadata the generator records,\n   * so the migration can evaluate the same predicate later. Any truthy return\n   * counts, so a predicate can hand back the value it read.\n   */\n  readonly when?: (metadata: M) => unknown;\n  /** Added to the workspace root manifest rather than the project's. */\n  readonly root?: boolean;\n  /**\n   * Declared only so the version sync keeps its pinned version current — an\n   * `overrides` entry, say. Never installed as a dependency.\n   */\n  readonly versionOnly?: boolean;\n}\n\n/**\n * A TypeScript dependency, which may be a dev dependency.\n *\n * `group` is typed as never-present rather than left off, so putting a Python\n * flag on a TypeScript entry is a type error instead of an ignored property.\n */\nexport interface DeclaredTsDependency<Name, M extends DependencyMetadata>\n  extends DeclaredDependency<Name, M> {\n  /** Added as a dev dependency rather than a runtime one. */\n  readonly dev?: boolean;\n  readonly group?: never;\n}\n\n/** A Python dependency, which may belong to a pyproject dependency group. */\nexport interface DeclaredPyDependency<Name, M extends DependencyMetadata>\n  extends DeclaredDependency<Name, M> {\n  /** Added to this pyproject dependency group rather than the main list. */\n  readonly group?: string;\n  readonly dev?: never;\n}\n\nexport interface DependencyDeclaration<\n  Ts extends readonly DeclaredTsDependency<\n    ITsDepVersion,\n    never\n  >[] = readonly DeclaredTsDependency<ITsDepVersion, never>[],\n  Py extends readonly DeclaredPyDependency<\n    IPyDepVersion,\n    never\n  >[] = readonly DeclaredPyDependency<IPyDepVersion, never>[],\n> {\n  readonly ts: Ts;\n  readonly py: Py;\n}\n\n/**\n * Declare the dependencies a generator owns, typed against the metadata it\n * records. Spread the `*_DEPENDENCIES` of any helper called, so the declaration\n * covers what those helpers add too.\n */\nexport const declareDependencies =\n  <M extends DependencyMetadata = Record<string, never>>() =>\n  <\n    const Ts extends readonly DeclaredTsDependency<ITsDepVersion, M>[],\n    const Py extends readonly DeclaredPyDependency<IPyDepVersion, M>[],\n  >(declaration: {\n    ts?: Ts;\n    py?: Py;\n  }): DependencyDeclaration<Ts, Py> =>\n    ({\n      ts: declaration.ts ?? [],\n      py: declaration.py ?? [],\n    }) as unknown as DependencyDeclaration<Ts, Py>;\n\n/**\n * Narrow entries to a further condition, keeping the one each already carries.\n *\n * For a helper's constant spread into a generator that calls it down one branch:\n * the branch gates the whole set, and each entry's own predicate still gates it\n * within that branch. Replacing `when` outright would widen ownership to the\n * helper's every branch.\n */\nexport const onlyWhen = <\n  M extends DependencyMetadata,\n  const Entries extends readonly { readonly name: unknown }[],\n>(\n  entries: Entries,\n  condition: (metadata: M) => unknown,\n): {\n  readonly [K in keyof Entries]: Omit<Entries[K], 'when'> & {\n    when: (m: M) => boolean;\n  };\n} =>\n  entries.map((entry) => {\n    // A declaration erases the metadata its predicates read, so calling one back\n    // requires naming the type the caller narrows to.\n    const own = (entry as { when?: (m: M) => unknown }).when;\n    return {\n      ...entry,\n      when: (metadata: M) =>\n        Boolean(condition(metadata)) && Boolean(own?.(metadata) ?? true),\n    };\n  }) as never;\n\n/**\n * Mark entries as declared for ownership but never installed here — a helper's\n * constant spread into a generator that doesn't own the project the helper adds\n * them to.\n */\nexport const ownedElsewhere = <const Entries extends readonly unknown[]>(\n  entries: Entries,\n): { readonly [K in keyof Entries]: Entries[K] & { versionOnly: true } } =>\n  entries.map((entry) => ({\n    ...(entry as object),\n    versionOnly: true,\n  })) as never;\n\n/** Every package a declaration names, whatever its predicate. */\nexport const declaredNames = <Name>(\n  entries: readonly { readonly name: Name }[],\n): Name[] => entries.map((entry) => entry.name);\n\n/**\n * The entries of a declaration whose condition the given metadata satisfies —\n * everything this occurrence is responsible for, installed here or not.\n *\n * A predicate that throws — reading a field the metadata doesn't carry, say —\n * counts as not applying. The migration evaluates these against whatever a\n * project happened to record, and must not claim a branch it cannot confirm.\n */\nexport const ownedDependencyEntries = <\n  Name,\n  M extends DependencyMetadata,\n  Entry extends DeclaredDependency<Name, M>,\n>(\n  entries: readonly Entry[],\n  metadata: M,\n): Entry[] =>\n  entries.filter((entry) => {\n    if (!entry.when) {\n      return true;\n    }\n    try {\n      return Boolean(entry.when(metadata));\n    } catch {\n      return false;\n    }\n  });\n\n/**\n * The entries to install for the given metadata: those it owns, less the ones\n * declared for their version alone. A `versionOnly` entry is still owned — the\n * sync keeps its pin current wherever it already sits.\n */\nexport const applicableDependencies = <\n  Name,\n  M extends DependencyMetadata,\n  Entry extends DeclaredDependency<Name, M>,\n>(\n  entries: readonly Entry[],\n  metadata: M,\n): Entry[] =>\n  ownedDependencyEntries(entries, metadata).filter(\n    (entry) => !entry.versionOnly,\n  );\n\n/**\n * Requires a caller's declaration to cover `Needed`, naming whatever is missing\n * in the type error. Helpers that add dependencies take this alongside the\n * declaration so a forgotten spread can't compile.\n */\nexport type MustDeclare<\n  Needed extends readonly { readonly name: ITsDepVersion }[],\n  D extends DependencyDeclaration,\n> = [Exclude<Needed[number]['name'], D['ts'][number]['name']>] extends [never]\n  ? unknown\n  : {\n      __missingDeclaredDependencies: Exclude<\n        Needed[number]['name'],\n        D['ts'][number]['name']\n      >;\n    };\n\n/** `MustDeclare` for Python dependencies. */\nexport type MustDeclarePy<\n  Needed extends readonly { readonly name: IPyDepVersion }[],\n  D extends DependencyDeclaration,\n> = [Exclude<Needed[number]['name'], D['py'][number]['name']>] extends [never]\n  ? unknown\n  : {\n      __missingDeclaredPyDependencies: Exclude<\n        Needed[number]['name'],\n        D['py'][number]['name']\n      >;\n    };\n\n/**\n * The dependencies a declaration covers, for typing a conditional list without\n * widening it to every vended package.\n */\nexport type DeclaredTs<D extends DependencyDeclaration> =\n  D['ts'][number]['name'];\n\n/** `DeclaredTs` for Python dependencies. */\nexport type DeclaredPy<D extends DependencyDeclaration> =\n  D['py'][number]['name'];\n\n/**\n * Narrows a caller's declaration to the subset a helper adds, which\n * `MustDeclare` has already proven the caller covers.\n */\nexport const forDependencies = <\n  const Ts extends readonly DeclaredDependency<ITsDepVersion, never>[] = [],\n  const Py extends readonly DeclaredDependency<IPyDepVersion, never>[] = [],\n>(\n  declaration: DependencyDeclaration,\n): DependencyDeclaration<Ts, Py> =>\n  declaration as unknown as DependencyDeclaration<Ts, Py>;\n"],"names":["declareDependencies","declaration","ts","py","onlyWhen","entries","condition","map","entry","own","when","metadata","Boolean","ownedElsewhere","versionOnly","declaredNames","name","ownedDependencyEntries","filter","applicableDependencies","forDependencies"],"mappings":"AAAA;;;CAGC,GA8ED;;;;CAIC,GACD,OAAO,MAAMA,sBACX,IACA,CAGEC,cAIC,CAAA;YACCC,IAAID,YAAYC,EAAE,IAAI,EAAE;YACxBC,IAAIF,YAAYE,EAAE,IAAI,EAAE;QAC1B,CAAA,EAA+C;AAEnD;;;;;;;CAOC,GACD,OAAO,MAAMC,WAAW,CAItBC,SACAC,YAMAD,QAAQE,GAAG,CAAC,CAACC;QACX,6EAA6E;QAC7E,kDAAkD;QAClD,MAAMC,MAAM,AAACD,MAAuCE,IAAI;QACxD,OAAO;YACL,GAAGF,KAAK;YACRE,MAAM,CAACC,WACLC,QAAQN,UAAUK,cAAcC,QAAQH,MAAME,aAAa;QAC/D;IACF,GAAY;AAEd;;;;CAIC,GACD,OAAO,MAAME,iBAAiB,CAC5BR,UAEAA,QAAQE,GAAG,CAAC,CAACC,QAAW,CAAA;YACtB,GAAIA,KAAK;YACTM,aAAa;QACf,CAAA,GAAa;AAEf,+DAA+D,GAC/D,OAAO,MAAMC,gBAAgB,CAC3BV,UACWA,QAAQE,GAAG,CAAC,CAACC,QAAUA,MAAMQ,IAAI,EAAE;AAEhD;;;;;;;CAOC,GACD,OAAO,MAAMC,yBAAyB,CAKpCZ,SACAM,WAEAN,QAAQa,MAAM,CAAC,CAACV;QACd,IAAI,CAACA,MAAME,IAAI,EAAE;YACf,OAAO;QACT;QACA,IAAI;YACF,OAAOE,QAAQJ,MAAME,IAAI,CAACC;QAC5B,EAAE,OAAM;YACN,OAAO;QACT;IACF,GAAG;AAEL;;;;CAIC,GACD,OAAO,MAAMQ,yBAAyB,CAKpCd,SACAM,WAEAM,uBAAuBZ,SAASM,UAAUO,MAAM,CAC9C,CAACV,QAAU,CAACA,MAAMM,WAAW,EAC7B;AA2CJ;;;CAGC,GACD,OAAO,MAAMM,kBAAkB,CAI7BnB,cAEAA,YAAwD"}

package/src/utils/docker.d.ts

@@ -3,6 +3,15 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import { type ProjectConfiguration, type Tree } from '@nx/devkit';
+import { type DependencyDeclaration, type MustDeclare } from './declared-dependencies';
+/** Dependencies a caller must declare to add a Docker scan target. */
+export declare const DOCKER_DEPENDENCIES: readonly [{
+    readonly name: "ncp";
+}, {
+    readonly name: "rimraf";
+}, {
+    readonly name: "make-dir-cli";
+}];
 /**
  * Substitution variables for the vended Node `Dockerfile` templates: the npm
  * version to install globally, and the versions its dependency overrides pin.
@@ -50,4 +59,4 @@ export interface DockerScanTargetOptions {
  * A \`.trivyignore\` is vended at the project root (kept if it already exists)
  * for suppressing findings.
  */
-export declare const addDockerScanTarget: (tree: Tree, options: DockerScanTargetOptions) => void;
+export declare const addDockerScanTarget: <const D extends DependencyDeclaration>(tree: Tree, options: DockerScanTargetOptions, declaration: D & MustDeclare<typeof DOCKER_DEPENDENCIES, D>) => void;

package/src/utils/docker.js

@@ -2,9 +2,13 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */ import { joinPathFragments } from "@nx/devkit";
-import { FsCommands } from "./fs.js";
+import { forDependencies } from "./declared-dependencies.js";
+import { FS_DEPENDENCIES, FsCommands } from "./fs.js";
 import { addDependencyToTargetIfNotPresent } from "./nx.js";
 import { CONTAINER_VERSIONS, TS_VERSIONS } from "./versions.js";
+/** Dependencies a caller must declare to add a Docker scan target. */ export const DOCKER_DEPENDENCIES = [
+    ...FS_DEPENDENCIES
+];
 const TRIVY_IGNORE_FILE = '.trivyignore';
 const TRIVY_IGNORE_CONTENTS = `# Trivy ignore file. Add one vulnerability ID (e.g. CVE-2021-12345) per line to
 # suppress it during the image scan (\`nx run-many --target trivy\`).
@@ -32,7 +36,7 @@ const TRIVY_IGNORE_CONTENTS = `# Trivy ignore file. Add one vulnerability ID (e.
  *
  * A \`.trivyignore\` is vended at the project root (kept if it already exists)
  * for suppressing findings.
- */ export const addDockerScanTarget = (tree, options)=>{
+ */ export const addDockerScanTarget = (tree, options, declaration)=>{
     const { project, containerEngine, trivyTargetName, dockerTargetName } = options;
     const { imageTags } = options;
     const projectRoot = project.root;
@@ -47,7 +51,7 @@ const TRIVY_IGNORE_CONTENTS = `# Trivy ignore file. Add one vulnerability ID (e.
     const scanKey = imageTags[0].replace(/[^a-zA-Z0-9-]/g, '-');
     const scanDir = joinPathFragments('dist', projectRoot, 'trivy', scanKey);
     const trivyImage = `public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy}`;
-    const fs = new FsCommands(tree);
+    const fs = new FsCommands(tree, forDependencies(declaration));
     const commands = [
         fs.rm(scanDir),
         fs.mkdir(scanDir),

package/src/utils/docker.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/docker.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  joinPathFragments,\n  type ProjectConfiguration,\n  type Tree,\n} from '@nx/devkit';\nimport { FsCommands } from './fs';\nimport { addDependencyToTargetIfNotPresent } from './nx';\nimport { CONTAINER_VERSIONS, TS_VERSIONS } from './versions';\n\nconst TRIVY_IGNORE_FILE = '.trivyignore';\n\nconst TRIVY_IGNORE_CONTENTS = `# Trivy ignore file. Add one vulnerability ID (e.g. CVE-2021-12345) per line to\n# suppress it during the image scan (\\`nx run-many --target trivy\\`).\n# https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids\n`;\n\n/**\n * Substitution variables for the vended Node `Dockerfile` templates: the npm\n * version to install globally, and the versions its dependency overrides pin.\n */\nexport const nodeImageVersions = () => ({\n  npmVersion: TS_VERSIONS.npm,\n  minimatchVersion: TS_VERSIONS.minimatch,\n});\n\nexport interface DockerScanTargetOptions {\n  /**\n   * Project configuration to add the scan target to (mutated in place).\n   */\n  readonly project: ProjectConfiguration;\n  /**\n   * Container engine command to invoke (\\`docker\\` or \\`finch\\`).\n   */\n  readonly containerEngine: string;\n  /**\n   * Name of the scan target to add, e.g. \\`my-agent-trivy\\`.\n   */\n  readonly trivyTargetName: string;\n  /**\n   * Name of the docker target that builds the image(s) to scan. The scan\n   * target depends on it.\n   */\n  readonly dockerTargetName: string;\n  /**\n   * Tags of the images built by the docker target which should be scanned.\n   */\n  readonly imageTags: string[];\n}\n\n/**\n * Add a cacheable Trivy scan target for the images built by a docker target\n * and wire it under the aggregate \\`trivy\\` target. The scan is not part of\n * \\`build\\` — run \\`nx run-many --target trivy\\` (the root \\`trivy\\` script) in CI.\n *\n * The scan target depends on the docker target and declares the project source\n * as its inputs, so an unchanged image is never re-scanned (a cache hit skips\n * the scan entirely). Each image is saved to a tarball under\n * \\`dist/<projectRoot>/trivy/<scan-key>\\` (kept out of any Docker build context)\n * and scanned with the pinned ECR-hosted Trivy image via a workspace-relative\n * bind mount, so the same commands work under both docker and finch. The scan\n * exits non-zero (exit code 1) on HIGH/CRITICAL vulnerabilities.\n *\n * A \\`.trivyignore\\` is vended at the project root (kept if it already exists)\n * for suppressing findings.\n */\nexport const addDockerScanTarget = (\n  tree: Tree,\n  options: DockerScanTargetOptions,\n): void => {\n  const { project, containerEngine, trivyTargetName, dockerTargetName } =\n    options;\n  const { imageTags } = options;\n  const projectRoot = project.root;\n\n  const ignoreFilePath = joinPathFragments(projectRoot, TRIVY_IGNORE_FILE);\n  if (!tree.exists(ignoreFilePath)) {\n    tree.write(ignoreFilePath, TRIVY_IGNORE_CONTENTS);\n  }\n\n  // Stage scan artifacts in a directory unique to this scan target so that\n  // sibling targets in the same project (e.g. multiple agents) don't clobber\n  // each other's tarballs when run in parallel. The first image tag is unique\n  // per target, so it makes a stable, collision-free key.\n  const scanKey = imageTags[0].replace(/[^a-zA-Z0-9-]/g, '-');\n  const scanDir = joinPathFragments('dist', projectRoot, 'trivy', scanKey);\n  const trivyImage = `public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy}`;\n\n  const fs = new FsCommands(tree);\n  const commands = [\n    fs.rm(scanDir),\n    fs.mkdir(scanDir),\n    fs.cp(ignoreFilePath, joinPathFragments(scanDir, TRIVY_IGNORE_FILE)),\n  ];\n\n  imageTags.forEach((imageTag, index) => {\n    const tarName = `image-${index}.tar`;\n    commands.push(\n      `${containerEngine} save -o ${joinPathFragments(scanDir, tarName)} ${imageTag}`,\n      `${containerEngine} run --rm -v \"./${scanDir}\":/scan ${trivyImage} image --input /scan/${tarName} --ignorefile /scan/${TRIVY_IGNORE_FILE} --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q`,\n    );\n  });\n\n  project.targets ??= {};\n  project.targets[trivyTargetName] = {\n    cache: true,\n    // The scanned image is fully determined by the project source, so caching\n    // on the source ensures an unchanged image is never re-scanned.\n    inputs: ['default', '^production'],\n    outputs: [`{workspaceRoot}/${scanDir}`],\n    executor: 'nx:run-commands',\n    options: {\n      commands,\n      parallel: false,\n    },\n    dependsOn: [dockerTargetName],\n  };\n\n  // Aggregate per-component scan targets under a single `trivy` target. The\n  // scan is intentionally NOT wired into `build`: image scanning is slow and\n  // its result depends on the ever-changing vulnerability database (a scan\n  // that passes today can fail tomorrow when a new CVE is published), so\n  // coupling it to `build` would make local and CI builds non-deterministic.\n  // Run `nx run-many --target trivy` (the root `trivy` script) in CI instead.\n  if (trivyTargetName !== 'trivy') {\n    addDependencyToTargetIfNotPresent(project, 'trivy', trivyTargetName);\n  }\n};\n"],"names":["joinPathFragments","FsCommands","addDependencyToTargetIfNotPresent","CONTAINER_VERSIONS","TS_VERSIONS","TRIVY_IGNORE_FILE","TRIVY_IGNORE_CONTENTS","nodeImageVersions","npmVersion","npm","minimatchVersion","minimatch","addDockerScanTarget","tree","options","project","containerEngine","trivyTargetName","dockerTargetName","imageTags","projectRoot","root","ignoreFilePath","exists","write","scanKey","replace","scanDir","trivyImage","trivy","fs","commands","rm","mkdir","cp","forEach","imageTag","index","tarName","push","targets","cache","inputs","outputs","executor","parallel","dependsOn"],"mappings":"AAAA;;;CAGC,GACD,SACEA,iBAAiB,QAGZ,aAAa;AACpB,SAASC,UAAU,QAAQ,UAAO;AAClC,SAASC,iCAAiC,QAAQ,UAAO;AACzD,SAASC,kBAAkB,EAAEC,WAAW,QAAQ,gBAAa;AAE7D,MAAMC,oBAAoB;AAE1B,MAAMC,wBAAwB,CAAC;;;AAG/B,CAAC;AAED;;;CAGC,GACD,OAAO,MAAMC,oBAAoB,IAAO,CAAA;QACtCC,YAAYJ,YAAYK,GAAG;QAC3BC,kBAAkBN,YAAYO,SAAS;IACzC,CAAA,EAAG;AA0BH;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,sBAAsB,CACjCC,MACAC;IAEA,MAAM,EAAEC,OAAO,EAAEC,eAAe,EAAEC,eAAe,EAAEC,gBAAgB,EAAE,GACnEJ;IACF,MAAM,EAAEK,SAAS,EAAE,GAAGL;IACtB,MAAMM,cAAcL,QAAQM,IAAI;IAEhC,MAAMC,iBAAiBtB,kBAAkBoB,aAAaf;IACtD,IAAI,CAACQ,KAAKU,MAAM,CAACD,iBAAiB;QAChCT,KAAKW,KAAK,CAACF,gBAAgBhB;IAC7B;IAEA,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,wDAAwD;IACxD,MAAMmB,UAAUN,SAAS,CAAC,EAAE,CAACO,OAAO,CAAC,kBAAkB;IACvD,MAAMC,UAAU3B,kBAAkB,QAAQoB,aAAa,SAASK;IAChE,MAAMG,aAAa,CAAC,kCAAkC,EAAEzB,mBAAmB0B,KAAK,EAAE;IAElF,MAAMC,KAAK,IAAI7B,WAAWY;IAC1B,MAAMkB,WAAW;QACfD,GAAGE,EAAE,CAACL;QACNG,GAAGG,KAAK,CAACN;QACTG,GAAGI,EAAE,CAACZ,gBAAgBtB,kBAAkB2B,SAAStB;KAClD;IAEDc,UAAUgB,OAAO,CAAC,CAACC,UAAUC;QAC3B,MAAMC,UAAU,CAAC,MAAM,EAAED,MAAM,IAAI,CAAC;QACpCN,SAASQ,IAAI,CACX,GAAGvB,gBAAgB,SAAS,EAAEhB,kBAAkB2B,SAASW,SAAS,CAAC,EAAEF,UAAU,EAC/E,GAAGpB,gBAAgB,gBAAgB,EAAEW,QAAQ,QAAQ,EAAEC,WAAW,qBAAqB,EAAEU,QAAQ,oBAAoB,EAAEjC,kBAAkB,yFAAyF,CAAC;IAEvO;IAEAU,QAAQyB,OAAO,KAAK,CAAC;IACrBzB,QAAQyB,OAAO,CAACvB,gBAAgB,GAAG;QACjCwB,OAAO;QACP,0EAA0E;QAC1E,gEAAgE;QAChEC,QAAQ;YAAC;YAAW;SAAc;QAClCC,SAAS;YAAC,CAAC,gBAAgB,EAAEhB,SAAS;SAAC;QACvCiB,UAAU;QACV9B,SAAS;YACPiB;YACAc,UAAU;QACZ;QACAC,WAAW;YAAC5B;SAAiB;IAC/B;IAEA,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAID,oBAAoB,SAAS;QAC/Bf,kCAAkCa,SAAS,SAASE;IACtD;AACF,EAAE"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/docker.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport {\n  joinPathFragments,\n  type ProjectConfiguration,\n  type Tree,\n} from '@nx/devkit';\nimport {\n  type DependencyDeclaration,\n  forDependencies,\n  type MustDeclare,\n} from './declared-dependencies';\nimport { FS_DEPENDENCIES, FsCommands } from './fs';\nimport { addDependencyToTargetIfNotPresent } from './nx';\nimport { CONTAINER_VERSIONS, TS_VERSIONS } from './versions';\n\n/** Dependencies a caller must declare to add a Docker scan target. */\nexport const DOCKER_DEPENDENCIES = [...FS_DEPENDENCIES] as const;\n\nconst TRIVY_IGNORE_FILE = '.trivyignore';\n\nconst TRIVY_IGNORE_CONTENTS = `# Trivy ignore file. Add one vulnerability ID (e.g. CVE-2021-12345) per line to\n# suppress it during the image scan (\\`nx run-many --target trivy\\`).\n# https://trivy.dev/latest/docs/configuration/filtering/#by-finding-ids\n`;\n\n/**\n * Substitution variables for the vended Node `Dockerfile` templates: the npm\n * version to install globally, and the versions its dependency overrides pin.\n */\nexport const nodeImageVersions = () => ({\n  npmVersion: TS_VERSIONS.npm,\n  minimatchVersion: TS_VERSIONS.minimatch,\n});\n\nexport interface DockerScanTargetOptions {\n  /**\n   * Project configuration to add the scan target to (mutated in place).\n   */\n  readonly project: ProjectConfiguration;\n  /**\n   * Container engine command to invoke (\\`docker\\` or \\`finch\\`).\n   */\n  readonly containerEngine: string;\n  /**\n   * Name of the scan target to add, e.g. \\`my-agent-trivy\\`.\n   */\n  readonly trivyTargetName: string;\n  /**\n   * Name of the docker target that builds the image(s) to scan. The scan\n   * target depends on it.\n   */\n  readonly dockerTargetName: string;\n  /**\n   * Tags of the images built by the docker target which should be scanned.\n   */\n  readonly imageTags: string[];\n}\n\n/**\n * Add a cacheable Trivy scan target for the images built by a docker target\n * and wire it under the aggregate \\`trivy\\` target. The scan is not part of\n * \\`build\\` — run \\`nx run-many --target trivy\\` (the root \\`trivy\\` script) in CI.\n *\n * The scan target depends on the docker target and declares the project source\n * as its inputs, so an unchanged image is never re-scanned (a cache hit skips\n * the scan entirely). Each image is saved to a tarball under\n * \\`dist/<projectRoot>/trivy/<scan-key>\\` (kept out of any Docker build context)\n * and scanned with the pinned ECR-hosted Trivy image via a workspace-relative\n * bind mount, so the same commands work under both docker and finch. The scan\n * exits non-zero (exit code 1) on HIGH/CRITICAL vulnerabilities.\n *\n * A \\`.trivyignore\\` is vended at the project root (kept if it already exists)\n * for suppressing findings.\n */\nexport const addDockerScanTarget = <const D extends DependencyDeclaration>(\n  tree: Tree,\n  options: DockerScanTargetOptions,\n  declaration: D & MustDeclare<typeof DOCKER_DEPENDENCIES, D>,\n): void => {\n  const { project, containerEngine, trivyTargetName, dockerTargetName } =\n    options;\n  const { imageTags } = options;\n  const projectRoot = project.root;\n\n  const ignoreFilePath = joinPathFragments(projectRoot, TRIVY_IGNORE_FILE);\n  if (!tree.exists(ignoreFilePath)) {\n    tree.write(ignoreFilePath, TRIVY_IGNORE_CONTENTS);\n  }\n\n  // Stage scan artifacts in a directory unique to this scan target so that\n  // sibling targets in the same project (e.g. multiple agents) don't clobber\n  // each other's tarballs when run in parallel. The first image tag is unique\n  // per target, so it makes a stable, collision-free key.\n  const scanKey = imageTags[0].replace(/[^a-zA-Z0-9-]/g, '-');\n  const scanDir = joinPathFragments('dist', projectRoot, 'trivy', scanKey);\n  const trivyImage = `public.ecr.aws/aquasecurity/trivy:${CONTAINER_VERSIONS.trivy}`;\n\n  const fs = new FsCommands(\n    tree,\n    forDependencies<typeof DOCKER_DEPENDENCIES>(declaration),\n  );\n  const commands = [\n    fs.rm(scanDir),\n    fs.mkdir(scanDir),\n    fs.cp(ignoreFilePath, joinPathFragments(scanDir, TRIVY_IGNORE_FILE)),\n  ];\n\n  imageTags.forEach((imageTag, index) => {\n    const tarName = `image-${index}.tar`;\n    commands.push(\n      `${containerEngine} save -o ${joinPathFragments(scanDir, tarName)} ${imageTag}`,\n      `${containerEngine} run --rm -v \"./${scanDir}\":/scan ${trivyImage} image --input /scan/${tarName} --ignorefile /scan/${TRIVY_IGNORE_FILE} --scanners vuln --severity HIGH,CRITICAL --ignore-unfixed --exit-code 1 --no-progress -q`,\n    );\n  });\n\n  project.targets ??= {};\n  project.targets[trivyTargetName] = {\n    cache: true,\n    // The scanned image is fully determined by the project source, so caching\n    // on the source ensures an unchanged image is never re-scanned.\n    inputs: ['default', '^production'],\n    outputs: [`{workspaceRoot}/${scanDir}`],\n    executor: 'nx:run-commands',\n    options: {\n      commands,\n      parallel: false,\n    },\n    dependsOn: [dockerTargetName],\n  };\n\n  // Aggregate per-component scan targets under a single `trivy` target. The\n  // scan is intentionally NOT wired into `build`: image scanning is slow and\n  // its result depends on the ever-changing vulnerability database (a scan\n  // that passes today can fail tomorrow when a new CVE is published), so\n  // coupling it to `build` would make local and CI builds non-deterministic.\n  // Run `nx run-many --target trivy` (the root `trivy` script) in CI instead.\n  if (trivyTargetName !== 'trivy') {\n    addDependencyToTargetIfNotPresent(project, 'trivy', trivyTargetName);\n  }\n};\n"],"names":["joinPathFragments","forDependencies","FS_DEPENDENCIES","FsCommands","addDependencyToTargetIfNotPresent","CONTAINER_VERSIONS","TS_VERSIONS","DOCKER_DEPENDENCIES","TRIVY_IGNORE_FILE","TRIVY_IGNORE_CONTENTS","nodeImageVersions","npmVersion","npm","minimatchVersion","minimatch","addDockerScanTarget","tree","options","declaration","project","containerEngine","trivyTargetName","dockerTargetName","imageTags","projectRoot","root","ignoreFilePath","exists","write","scanKey","replace","scanDir","trivyImage","trivy","fs","commands","rm","mkdir","cp","forEach","imageTag","index","tarName","push","targets","cache","inputs","outputs","executor","parallel","dependsOn"],"mappings":"AAAA;;;CAGC,GACD,SACEA,iBAAiB,QAGZ,aAAa;AACpB,SAEEC,eAAe,QAEV,6BAA0B;AACjC,SAASC,eAAe,EAAEC,UAAU,QAAQ,UAAO;AACnD,SAASC,iCAAiC,QAAQ,UAAO;AACzD,SAASC,kBAAkB,EAAEC,WAAW,QAAQ,gBAAa;AAE7D,oEAAoE,GACpE,OAAO,MAAMC,sBAAsB;OAAIL;CAAgB,CAAU;AAEjE,MAAMM,oBAAoB;AAE1B,MAAMC,wBAAwB,CAAC;;;AAG/B,CAAC;AAED;;;CAGC,GACD,OAAO,MAAMC,oBAAoB,IAAO,CAAA;QACtCC,YAAYL,YAAYM,GAAG;QAC3BC,kBAAkBP,YAAYQ,SAAS;IACzC,CAAA,EAAG;AA0BH;;;;;;;;;;;;;;;CAeC,GACD,OAAO,MAAMC,sBAAsB,CACjCC,MACAC,SACAC;IAEA,MAAM,EAAEC,OAAO,EAAEC,eAAe,EAAEC,eAAe,EAAEC,gBAAgB,EAAE,GACnEL;IACF,MAAM,EAAEM,SAAS,EAAE,GAAGN;IACtB,MAAMO,cAAcL,QAAQM,IAAI;IAEhC,MAAMC,iBAAiB1B,kBAAkBwB,aAAahB;IACtD,IAAI,CAACQ,KAAKW,MAAM,CAACD,iBAAiB;QAChCV,KAAKY,KAAK,CAACF,gBAAgBjB;IAC7B;IAEA,yEAAyE;IACzE,2EAA2E;IAC3E,4EAA4E;IAC5E,wDAAwD;IACxD,MAAMoB,UAAUN,SAAS,CAAC,EAAE,CAACO,OAAO,CAAC,kBAAkB;IACvD,MAAMC,UAAU/B,kBAAkB,QAAQwB,aAAa,SAASK;IAChE,MAAMG,aAAa,CAAC,kCAAkC,EAAE3B,mBAAmB4B,KAAK,EAAE;IAElF,MAAMC,KAAK,IAAI/B,WACba,MACAf,gBAA4CiB;IAE9C,MAAMiB,WAAW;QACfD,GAAGE,EAAE,CAACL;QACNG,GAAGG,KAAK,CAACN;QACTG,GAAGI,EAAE,CAACZ,gBAAgB1B,kBAAkB+B,SAASvB;KAClD;IAEDe,UAAUgB,OAAO,CAAC,CAACC,UAAUC;QAC3B,MAAMC,UAAU,CAAC,MAAM,EAAED,MAAM,IAAI,CAAC;QACpCN,SAASQ,IAAI,CACX,GAAGvB,gBAAgB,SAAS,EAAEpB,kBAAkB+B,SAASW,SAAS,CAAC,EAAEF,UAAU,EAC/E,GAAGpB,gBAAgB,gBAAgB,EAAEW,QAAQ,QAAQ,EAAEC,WAAW,qBAAqB,EAAEU,QAAQ,oBAAoB,EAAElC,kBAAkB,yFAAyF,CAAC;IAEvO;IAEAW,QAAQyB,OAAO,KAAK,CAAC;IACrBzB,QAAQyB,OAAO,CAACvB,gBAAgB,GAAG;QACjCwB,OAAO;QACP,0EAA0E;QAC1E,gEAAgE;QAChEC,QAAQ;YAAC;YAAW;SAAc;QAClCC,SAAS;YAAC,CAAC,gBAAgB,EAAEhB,SAAS;SAAC;QACvCiB,UAAU;QACV/B,SAAS;YACPkB;YACAc,UAAU;QACZ;QACAC,WAAW;YAAC5B;SAAiB;IAC/B;IAEA,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,uEAAuE;IACvE,2EAA2E;IAC3E,4EAA4E;IAC5E,IAAID,oBAAoB,SAAS;QAC/BjB,kCAAkCe,SAAS,SAASE;IACtD;AACF,EAAE"}

package/src/utils/fs.d.ts

@@ -3,14 +3,25 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 import type { Tree } from '@nx/devkit';
+import { type DependencyDeclaration, type MustDeclare } from './declared-dependencies';
+/** Dependencies a caller must declare to use `FsCommands`. */
+export declare const FS_DEPENDENCIES: readonly [{
+    readonly name: "ncp";
+}, {
+    readonly name: "rimraf";
+}, {
+    readonly name: "make-dir-cli";
+}];
 /**
- * Utility class for creating platform agnostic commands for filesystem operations.
- * Adds the required dependencies to the root package json
+ * Platform agnostic commands for filesystem operations, adding the CLIs they
+ * need to the root package.json.
  */
-export declare class FsCommands {
+export declare class FsCommands<D extends DependencyDeclaration> {
     private tree;
-    constructor(tree: Tree);
+    private declaration;
+    constructor(tree: Tree, declaration: D & MustDeclare<typeof FS_DEPENDENCIES, D>);
     cp(src: string, dst: string): string;
     rm(dir: string): string;
     mkdir(dir: string): string;
+    private add;
 }

package/src/utils/fs.js

@@ -1,34 +1,47 @@
 /**
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
- */ import { addDependenciesToPackageJson } from "./dependencies.js";
+ */ import { forDependencies } from "./declared-dependencies.js";
+import { addDependenciesToPackageJson } from "./dependencies.js";
 import { withVersions } from "./versions.js";
+/** Dependencies a caller must declare to use `FsCommands`. */ export const FS_DEPENDENCIES = [
+    {
+        name: 'ncp'
+    },
+    {
+        name: 'rimraf'
+    },
+    {
+        name: 'make-dir-cli'
+    }
+];
 /**
- * Utility class for creating platform agnostic commands for filesystem operations.
- * Adds the required dependencies to the root package json
+ * Platform agnostic commands for filesystem operations, adding the CLIs they
+ * need to the root package.json.
  */ export class FsCommands {
     tree;
-    constructor(tree){
+    declaration;
+    constructor(tree, declaration){
         this.tree = tree;
+        this.declaration = declaration;
     }
     cp(src, dst) {
-        addDependenciesToPackageJson(this.tree, {}, withVersions([
-            'ncp'
-        ]));
+        this.add('ncp');
         return `ncp ${src} ${dst}`;
     }
     rm(dir) {
-        addDependenciesToPackageJson(this.tree, {}, withVersions([
-            'rimraf'
-        ]));
+        this.add('rimraf');
         return `rimraf ${dir}`;
     }
     mkdir(dir) {
-        addDependenciesToPackageJson(this.tree, {}, withVersions([
-            'make-dir-cli'
-        ]));
+        this.add('make-dir-cli');
         return `make-dir ${dir}`;
     }
+    add(dep) {
+        addDependenciesToPackageJson(this.tree, {}, withVersions(forDependencies(this.declaration), [
+            dep
+        ]));
+    }
 }
 
 //# sourceMappingURL=fs.js.map

package/src/utils/fs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/fs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { Tree } from '@nx/devkit';\nimport { addDependenciesToPackageJson } from './dependencies';\nimport { withVersions } from './versions';\n\n/**\n * Utility class for creating platform agnostic commands for filesystem operations.\n * Adds the required dependencies to the root package json\n */\nexport class FsCommands {\n  private tree: Tree;\n\n  constructor(tree: Tree) {\n    this.tree = tree;\n  }\n\n  public cp(src: string, dst: string) {\n    addDependenciesToPackageJson(this.tree, {}, withVersions(['ncp']));\n    return `ncp ${src} ${dst}`;\n  }\n\n  public rm(dir: string) {\n    addDependenciesToPackageJson(this.tree, {}, withVersions(['rimraf']));\n    return `rimraf ${dir}`;\n  }\n\n  public mkdir(dir: string) {\n    addDependenciesToPackageJson(this.tree, {}, withVersions(['make-dir-cli']));\n    return `make-dir ${dir}`;\n  }\n}\n"],"names":["addDependenciesToPackageJson","withVersions","FsCommands","tree","cp","src","dst","rm","dir","mkdir"],"mappings":"AAAA;;;CAGC,GAED,SAASA,4BAA4B,QAAQ,oBAAiB;AAC9D,SAASC,YAAY,QAAQ,gBAAa;AAE1C;;;CAGC,GACD,OAAO,MAAMC;IACHC,KAAW;IAEnB,YAAYA,IAAU,CAAE;QACtB,IAAI,CAACA,IAAI,GAAGA;IACd;IAEOC,GAAGC,GAAW,EAAEC,GAAW,EAAE;QAClCN,6BAA6B,IAAI,CAACG,IAAI,EAAE,CAAC,GAAGF,aAAa;YAAC;SAAM;QAChE,OAAO,CAAC,IAAI,EAAEI,IAAI,CAAC,EAAEC,KAAK;IAC5B;IAEOC,GAAGC,GAAW,EAAE;QACrBR,6BAA6B,IAAI,CAACG,IAAI,EAAE,CAAC,GAAGF,aAAa;YAAC;SAAS;QACnE,OAAO,CAAC,OAAO,EAAEO,KAAK;IACxB;IAEOC,MAAMD,GAAW,EAAE;QACxBR,6BAA6B,IAAI,CAACG,IAAI,EAAE,CAAC,GAAGF,aAAa;YAAC;SAAe;QACzE,OAAO,CAAC,SAAS,EAAEO,KAAK;IAC1B;AACF"}
+{"version":3,"sources":["../../../../../packages/nx-plugin/src/utils/fs.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport type { Tree } from '@nx/devkit';\nimport {\n  type DependencyDeclaration,\n  forDependencies,\n  type MustDeclare,\n} from './declared-dependencies';\nimport { addDependenciesToPackageJson } from './dependencies';\nimport { type ITsDepVersion, withVersions } from './versions';\n\n/** Dependencies a caller must declare to use `FsCommands`. */\nexport const FS_DEPENDENCIES = [\n  { name: 'ncp' },\n  { name: 'rimraf' },\n  { name: 'make-dir-cli' },\n] as const satisfies readonly { name: ITsDepVersion }[];\n\n/**\n * Platform agnostic commands for filesystem operations, adding the CLIs they\n * need to the root package.json.\n */\nexport class FsCommands<D extends DependencyDeclaration> {\n  private tree: Tree;\n  private declaration: D;\n\n  constructor(\n    tree: Tree,\n    declaration: D & MustDeclare<typeof FS_DEPENDENCIES, D>,\n  ) {\n    this.tree = tree;\n    this.declaration = declaration;\n  }\n\n  public cp(src: string, dst: string) {\n    this.add('ncp');\n    return `ncp ${src} ${dst}`;\n  }\n\n  public rm(dir: string) {\n    this.add('rimraf');\n    return `rimraf ${dir}`;\n  }\n\n  public mkdir(dir: string) {\n    this.add('make-dir-cli');\n    return `make-dir ${dir}`;\n  }\n\n  private add(dep: (typeof FS_DEPENDENCIES)[number]['name']) {\n    addDependenciesToPackageJson(\n      this.tree,\n      {},\n      withVersions(forDependencies<typeof FS_DEPENDENCIES>(this.declaration), [\n        dep,\n      ]),\n    );\n  }\n}\n"],"names":["forDependencies","addDependenciesToPackageJson","withVersions","FS_DEPENDENCIES","name","FsCommands","tree","declaration","cp","src","dst","add","rm","dir","mkdir","dep"],"mappings":"AAAA;;;CAGC,GAED,SAEEA,eAAe,QAEV,6BAA0B;AACjC,SAASC,4BAA4B,QAAQ,oBAAiB;AAC9D,SAA6BC,YAAY,QAAQ,gBAAa;AAE9D,4DAA4D,GAC5D,OAAO,MAAMC,kBAAkB;IAC7B;QAAEC,MAAM;IAAM;IACd;QAAEA,MAAM;IAAS;IACjB;QAAEA,MAAM;IAAe;CACxB,CAAuD;AAExD;;;CAGC,GACD,OAAO,MAAMC;IACHC,KAAW;IACXC,YAAe;IAEvB,YACED,IAAU,EACVC,WAAuD,CACvD;QACA,IAAI,CAACD,IAAI,GAAGA;QACZ,IAAI,CAACC,WAAW,GAAGA;IACrB;IAEOC,GAAGC,GAAW,EAAEC,GAAW,EAAE;QAClC,IAAI,CAACC,GAAG,CAAC;QACT,OAAO,CAAC,IAAI,EAAEF,IAAI,CAAC,EAAEC,KAAK;IAC5B;IAEOE,GAAGC,GAAW,EAAE;QACrB,IAAI,CAACF,GAAG,CAAC;QACT,OAAO,CAAC,OAAO,EAAEE,KAAK;IACxB;IAEOC,MAAMD,GAAW,EAAE;QACxB,IAAI,CAACF,GAAG,CAAC;QACT,OAAO,CAAC,SAAS,EAAEE,KAAK;IAC1B;IAEQF,IAAII,GAA6C,EAAE;QACzDd,6BACE,IAAI,CAACK,IAAI,EACT,CAAC,GACDJ,aAAaF,gBAAwC,IAAI,CAACO,WAAW,GAAG;YACtEQ;SACD;IAEL;AACF"}

package/src/utils/init.d.ts

@@ -4,7 +4,20 @@
  */
 import { OverwriteStrategy, type Tree } from '@nx/devkit';
 import { type Containers } from './containers';
+import { type DependencyDeclaration, type MustDeclare } from './declared-dependencies';
 import type { Iac } from './iac';
+/** Dependencies a caller must declare to apply the workspace init. */
+export declare const INIT_DEPENDENCIES: readonly [{
+    readonly name: "nx";
+}, {
+    readonly name: "@nx/js";
+}, {
+    readonly name: "@nx/workspace";
+}, {
+    readonly name: "typescript";
+}, {
+    readonly name: "@biomejs/biome";
+}];
 export declare const PNPM_BUILT_DEPENDENCIES: string[];
 /**
  * Options controlling how the workspace is initialised. These mirror the
@@ -56,4 +69,4 @@ export interface ApplyWorkspaceInitOptions {
  * existing projects — those are decisions for the user (see the "add to an
  * existing workspace" guide).
  */
-export declare const applyWorkspaceInit: (tree: Tree, { iac, containers, mcp, readmeOverwriteStrategy, overwriteScripts, catalogs, }: ApplyWorkspaceInitOptions) => Promise<void>;
+export declare const applyWorkspaceInit: <const D extends DependencyDeclaration>(tree: Tree, { iac, containers, mcp, readmeOverwriteStrategy, overwriteScripts, catalogs, }: ApplyWorkspaceInitOptions, declaration: D & MustDeclare<typeof INIT_DEPENDENCIES, D>) => Promise<void>;

package/src/utils/init.js

@@ -4,7 +4,6 @@
  */ import { generateFiles, joinPathFragments, OverwriteStrategy, readNxJson, updateJson, updateNxJson } from "@nx/devkit";
 import { initGenerator } from "@nx/js";
 import yaml from "js-yaml";
-import { readModulePackageJson } from "nx/src/utils/package-json";
 import GeneratorsJson from "../../generators.json" with {
     type: 'json'
 };
@@ -12,6 +11,7 @@ import { SYNC_GENERATOR_NAME as TS_SYNC_GENERATOR_NAME } from "../ts/sync/genera
 import { BASE_TSCONFIG_COMPILER_OPTIONS } from "./base-tsconfig.js";
 import { ensureAwsNxPluginConfig, updateAwsNxPluginConfig } from "./config/utils.js";
 import { inferContainers } from "./containers.js";
+import { forDependencies } from "./declared-dependencies.js";
 import { addDependenciesToPackageJson, detectWorkspacePackageManager } from "./dependencies.js";
 import { getDefaultBiomeConfig } from "./format.js";
 import { configureMcpServers } from "./mcp.js";
@@ -24,6 +24,23 @@ const WORKSPACES = [
     'packages/*'
 ];
 const NX_TYPESCRIPT_SYNC_GENERATOR = '@nx/js:typescript-sync';
+/** Dependencies a caller must declare to apply the workspace init. */ export const INIT_DEPENDENCIES = [
+    {
+        name: 'nx'
+    },
+    {
+        name: '@nx/js'
+    },
+    {
+        name: '@nx/workspace'
+    },
+    {
+        name: 'typescript'
+    },
+    {
+        name: '@biomejs/biome'
+    }
+];
 // Built dependencies whose install scripts the generated workspace trusts.
 // `onlyBuiltDependencies` is the pnpm 10 key (silently ignored by pnpm 11);
 // pnpm 11 reads `allowBuilds` instead. Any dep NOT in this allowlist will
@@ -157,7 +174,7 @@ export const PNPM_BUILT_DEPENDENCIES = [
  * compiler options, migrate a workspace's package manager, or restructure
  * existing projects — those are decisions for the user (see the "add to an
  * existing workspace" guide).
- */ export const applyWorkspaceInit = async (tree, { iac, containers, mcp, readmeOverwriteStrategy = OverwriteStrategy.KeepExisting, overwriteScripts = false, catalogs = true })=>{
+ */ export const applyWorkspaceInit = async (tree, { iac, containers, mcp, readmeOverwriteStrategy = OverwriteStrategy.KeepExisting, overwriteScripts = false, catalogs = true }, declaration)=>{
     const resolvedContainers = !containers || containers === 'infer' ? inferContainers() : containers;
     // The catalogs flag is written explicitly (even when true) so the workspace
     // records its dependency-management choice.
@@ -238,12 +255,13 @@ export const PNPM_BUILT_DEPENDENCIES = [
     // `@nx/js` must be a root dependency for the `@nx/js:typescript-sync`
     // generator registered in nx.json to resolve (npm doesn't hoist the
     // plugin's own copy reliably).
-    const nxVersion = readModulePackageJson('@nx/js').packageJson.version;
     addDependenciesToPackageJson(tree, {}, {
-        nx: nxVersion,
-        '@nx/js': nxVersion,
-        '@nx/workspace': nxVersion,
-        ...withVersions([
+        ...withVersions(forDependencies(declaration), [
+            'nx',
+            '@nx/js',
+            '@nx/workspace'
+        ]),
+        ...withVersions(forDependencies(declaration), [
             'typescript',
             '@biomejs/biome'
         ]),