@aws/nx-plugin 1.1.1 → 1.3.0

package/src/utils/files/common/scripts/src/greengrass/recipe-utils.ts.template

@@ -0,0 +1,356 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import yaml from 'js-yaml';
+
+/**
+ * A narrow view of a Greengrass recipe: only the keys this vended toolchain
+ * reads. Every other key - including unknown lifecycle keys - is preserved
+ * untouched wherever a recipe is re-serialized, because the recipe is
+ * user-owned and this toolchain does not model the full recipe schema.
+ */
+export type GreengrassRecipe = Record<string, unknown>;
+
+export interface ResolvedComponent {
+  readonly componentName: string;
+  readonly componentVersion: string;
+  readonly recipe: GreengrassRecipe;
+}
+
+const COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9-_.]+$/;
+const RESERVED_COMPONENT_NAME_PREFIX = 'aws.greengrass.';
+const MAX_COMPONENT_NAME_LENGTH = 128;
+// https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string
+const SEMVER_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+const STRICT_COMPONENT_VERSION_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const DECOMPRESSED_PATH_TOKEN = '{artifacts:decompressedPath}';
+
+export const NEXT_VERSION_SENTINELS = [
+  'NEXT_PATCH',
+  'NEXT_MINOR',
+  'NEXT_MAJOR',
+] as const;
+
+export type NextVersionSentinel = (typeof NEXT_VERSION_SENTINELS)[number];
+
+/** Whether a value requests local deploy-time component version resolution. */
+export function isNextVersionSentinel(
+  value: unknown,
+): value is NextVersionSentinel {
+  return (
+    typeof value === 'string' &&
+    NEXT_VERSION_SENTINELS.includes(value as NextVersionSentinel)
+  );
+}
+
+/**
+ * Resolves a version sentinel on a device: bumps the highest strict M.m.p
+ * version among the installed version and the candidate versions the caller
+ * collected from the nucleus's package stores, or returns 1.0.0 when there is
+ * none. A candidate that is not strict M.m.p is ignored. An installed version
+ * that is not strict M.m.p is an error, because the sentinel cannot bump it.
+ */
+export function resolveLocalNextVersion(
+  installedVersion: string | undefined,
+  candidateVersions: readonly string[],
+  sentinel: NextVersionSentinel,
+): string {
+  if (
+    installedVersion !== undefined &&
+    !STRICT_COMPONENT_VERSION_PATTERN.test(installedVersion)
+  ) {
+    throw new Error(
+      `Installed component version "${installedVersion}" is not a strict M.m.p version, so ${sentinel} cannot resolve it.`,
+    );
+  }
+
+  const highest = [...candidateVersions, installedVersion]
+    .filter(
+      (version): version is string =>
+        version !== undefined && STRICT_COMPONENT_VERSION_PATTERN.test(version),
+    )
+    .reduce<string | undefined>((currentHighest, candidate) => {
+      if (currentHighest === undefined) {
+        return candidate;
+      }
+      const current = STRICT_COMPONENT_VERSION_PATTERN.exec(currentHighest)!;
+      const next = STRICT_COMPONENT_VERSION_PATTERN.exec(candidate)!;
+      for (let index = 1; index <= 3; index++) {
+        const difference = BigInt(next[index]) - BigInt(current[index]);
+        if (difference !== 0n) {
+          return difference > 0n ? candidate : currentHighest;
+        }
+      }
+      return currentHighest;
+    }, undefined);
+  if (highest === undefined) {
+    return '1.0.0';
+  }
+
+  const [, major, minor, patch] =
+    STRICT_COMPONENT_VERSION_PATTERN.exec(highest)!;
+  switch (sentinel) {
+    case 'NEXT_PATCH':
+      return `${major}.${minor}.${(BigInt(patch) + 1n).toString()}`;
+    case 'NEXT_MINOR':
+      return `${major}.${(BigInt(minor) + 1n).toString()}.0`;
+    case 'NEXT_MAJOR':
+      return `${(BigInt(major) + 1n).toString()}.0.0`;
+  }
+}
+
+/** Reads and parses a recipe.yaml. Throws with a clear message on failure. */
+export function loadRecipe(recipePath: string): GreengrassRecipe {
+  let raw: string;
+  try {
+    raw = readFileSync(recipePath, 'utf-8');
+  } catch {
+    throw new Error(`Cannot read recipe at "${recipePath}"`);
+  }
+  const parsed = yaml.load(raw);
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    throw new Error(`"${recipePath}" is not a Greengrass recipe document`);
+  }
+  return parsed as GreengrassRecipe;
+}
+
+/**
+ * Validates only the recipe fields this vended toolchain consumes:
+ * `ComponentName`, `ComponentVersion`, and, for every entry in
+ * `artifactBaseNames`, the `{artifacts:decompressedPath}` reference the
+ * local-deploy lifecycle script must carry so that a deployed component can
+ * find its own artifact once Greengrass decompresses it.
+ *
+ * Throws a single `Error` listing every violation when the recipe is invalid.
+ */
+export function validateRecipe(
+  recipe: GreengrassRecipe,
+  artifactBaseNames: readonly string[],
+): ResolvedComponent {
+  const errors: string[] = [];
+
+  const componentName = recipe.ComponentName;
+  if (typeof componentName !== 'string' || componentName.length === 0) {
+    errors.push('ComponentName is required and must be a non-empty string');
+  } else {
+    if (componentName.length > MAX_COMPONENT_NAME_LENGTH) {
+      errors.push(
+        `ComponentName must be at most ${MAX_COMPONENT_NAME_LENGTH} characters, got ${componentName.length}`,
+      );
+    }
+    if (!COMPONENT_NAME_PATTERN.test(componentName)) {
+      errors.push(
+        'ComponentName may only contain letters, numbers, "-", "_" and "."',
+      );
+    }
+    if (componentName.startsWith(RESERVED_COMPONENT_NAME_PREFIX)) {
+      errors.push(
+        `ComponentName must not start with the reserved prefix "${RESERVED_COMPONENT_NAME_PREFIX}"`,
+      );
+    }
+  }
+
+  const componentVersion = recipe.ComponentVersion;
+  if (
+    typeof componentVersion !== 'string' ||
+    (!SEMVER_PATTERN.test(componentVersion) &&
+      !isNextVersionSentinel(componentVersion))
+  ) {
+    errors.push(
+      'ComponentVersion is required and must be a valid semver version (e.g. "1.0.0") or one of NEXT_PATCH, NEXT_MINOR, NEXT_MAJOR',
+    );
+  }
+
+  for (const baseName of artifactBaseNames) {
+    if (!referencesDecompressedComponentDir(recipe, baseName)) {
+      errors.push(
+        `No lifecycle script references "${DECOMPRESSED_PATH_TOKEN}/${baseName}/" - ` +
+          `the Run script path must match the artifact zip base name ("${baseName}.zip")`,
+      );
+    }
+    if (!declaresComponentZipArtifact(recipe, baseName)) {
+      errors.push(
+        `No manifest declares an artifact whose Uri ends in "/${baseName}.zip" - ` +
+          'Greengrass only unarchives a declared artifact, so ' +
+          `"${DECOMPRESSED_PATH_TOKEN}/${baseName}/" would never resolve on the device`,
+      );
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Invalid recipe:\n${errors.map((e) => `  - ${e}`).join('\n')}`,
+    );
+  }
+
+  return {
+    componentName: componentName as string,
+    componentVersion: componentVersion as string,
+    recipe,
+  };
+}
+
+/**
+ * Recursively searches every string value for a decompressedPath reference to
+ * `componentDirName`, wherever the recipe places its Lifecycle block (top
+ * level or per-manifest).
+ */
+function referencesDecompressedComponentDir(
+  value: unknown,
+  componentDirName: string,
+): boolean {
+  const needle = `${DECOMPRESSED_PATH_TOKEN}/${componentDirName}/`;
+  if (typeof value === 'string') {
+    return value.includes(needle);
+  }
+  if (Array.isArray(value)) {
+    return value.some((entry) =>
+      referencesDecompressedComponentDir(entry, componentDirName),
+    );
+  }
+  if (value !== null && typeof value === 'object') {
+    return Object.values(value).some((entry) =>
+      referencesDecompressedComponentDir(entry, componentDirName),
+    );
+  }
+  return false;
+}
+
+/**
+ * Whether any manifest declares an artifact whose Uri basename is
+ * `<componentDirName>.zip`, which is the name the artifact this toolchain
+ * writes actually carries.
+ */
+function declaresComponentZipArtifact(
+  recipe: GreengrassRecipe,
+  componentDirName: string,
+): boolean {
+  const manifests = Array.isArray(recipe.Manifests) ? recipe.Manifests : [];
+  return manifests.some((manifest) =>
+    manifestDeclaresZipArtifact(manifest, componentDirName),
+  );
+}
+
+/**
+ * Whether one manifest declares an artifact whose Uri basename is
+ * `<componentDirName>.zip`. Case-insensitive on the key so a recipe authored
+ * with `URI` (as some AWS samples spell it) still matches.
+ */
+function manifestDeclaresZipArtifact(
+  manifest: unknown,
+  componentDirName: string,
+): boolean {
+  const suffix = `/${componentDirName}.zip`;
+  const artifacts = (manifest as { Artifacts?: unknown })?.Artifacts;
+  if (!Array.isArray(artifacts)) {
+    return false;
+  }
+  return artifacts.some((artifact) => {
+    if (artifact === null || typeof artifact !== 'object') {
+      return false;
+    }
+    return Object.entries(artifact as Record<string, unknown>).some(
+      ([key, value]) =>
+        key.toLowerCase() === 'uri' &&
+        typeof value === 'string' &&
+        value.endsWith(suffix),
+    );
+  });
+}
+
+/**
+ * Multi-architecture only: checks that every manifest whose
+ * `Platform.architecture` names an architecture this build vendored pairs with
+ * THAT architecture's own artifact, both in its `Artifacts` and in the
+ * lifecycle that unarchives it.
+ *
+ * {@link validateRecipe}'s checks are global - they prove every built zip is
+ * declared and referenced somewhere in the recipe. A recipe that swaps two
+ * manifests' artifacts and Run paths satisfies them, and a swap sends one
+ * architecture's native wheels to the other, which fails only on the device.
+ * A swap is one paste mistake away, because adding a second manifest to an
+ * existing component is a hand edit of a user-owned recipe.
+ *
+ * A manifest with no `Platform.architecture`, or one naming an architecture
+ * this build did not vendor, is left alone: a recipe may carry manifests this
+ * toolchain does not build.
+ */
+export function validateManifestArchitectures(
+  recipe: GreengrassRecipe,
+  baseNameByArchitecture: Readonly<Record<string, string>>,
+): void {
+  const errors: string[] = [];
+  const manifests = Array.isArray(recipe.Manifests) ? recipe.Manifests : [];
+  manifests.forEach((manifest, index) => {
+    const architecture = (
+      manifest as { Platform?: { architecture?: unknown } } | null
+    )?.Platform?.architecture;
+    if (typeof architecture !== 'string') {
+      return;
+    }
+    const baseName = baseNameByArchitecture[architecture];
+    if (!baseName) {
+      return;
+    }
+    if (!manifestDeclaresZipArtifact(manifest, baseName)) {
+      errors.push(
+        `Manifest ${index + 1} declares "architecture: ${architecture}", so its own artifact Uri must end in "/${baseName}.zip" - ` +
+          `that is the zip this build writes for "${architecture}". Manifests must not carry another architecture's artifact`,
+      );
+    }
+    const lifecycle =
+      (manifest as { Lifecycle?: unknown }).Lifecycle ?? recipe.Lifecycle;
+    if (!referencesDecompressedComponentDir(lifecycle, baseName)) {
+      errors.push(
+        `Manifest ${index + 1} declares "architecture: ${architecture}", so its lifecycle must reference ` +
+          `"${DECOMPRESSED_PATH_TOKEN}/${baseName}/" - the directory that architecture's own artifact unarchives to`,
+      );
+    }
+  });
+
+  if (errors.length > 0) {
+    throw new Error(
+      `Invalid recipe:\n${errors.map((e) => `  - ${e}`).join('\n')}`,
+    );
+  }
+}
+
+/**
+ * Reads the single resolved recipe a prior `-artifact` run wrote under a
+ * `greengrass-build/recipes` directory, for scripts that only need to know
+ * which component and version were last built.
+ */
+export function readResolvedRecipe(recipesDir: string): ResolvedComponent {
+  let files: string[];
+  try {
+    files = readdirSync(recipesDir).filter(
+      (f) => f.endsWith('.yaml') || f.endsWith('.yml'),
+    );
+  } catch {
+    throw new Error(
+      `No resolved recipes found at "${recipesDir}" - run the component's "-artifact" target first`,
+    );
+  }
+  if (files.length !== 1) {
+    throw new Error(
+      `Expected exactly one resolved recipe in "${recipesDir}", found ${files.length}`,
+    );
+  }
+  const recipePath = join(recipesDir, files[0]);
+  const recipe = loadRecipe(recipePath);
+  const { ComponentName, ComponentVersion } = recipe;
+  if (
+    typeof ComponentName !== 'string' ||
+    typeof ComponentVersion !== 'string'
+  ) {
+    throw new Error(
+      `"${recipePath}" is missing ComponentName/ComponentVersion`,
+    );
+  }
+  return {
+    componentName: ComponentName,
+    componentVersion: ComponentVersion,
+    recipe,
+  };
+}

package/src/utils/files/common/scripts/src/greengrass/zip-writer.ts.template

@@ -0,0 +1,121 @@
+import { writeFileSync } from 'node:fs';
+// crc32 from node:zlib requires Node >= 20.15 / 22.2.
+import { crc32, deflateRawSync } from 'node:zlib';
+
+/** One file to place in the archive, at a forward-slash relative path. */
+export interface ZipEntry {
+  readonly name: string;
+  readonly data: Buffer;
+}
+
+const LOCAL_FILE_HEADER_SIGNATURE = 0x04034b50;
+const CENTRAL_DIRECTORY_SIGNATURE = 0x02014b50;
+const END_OF_CENTRAL_DIRECTORY_SIGNATURE = 0x06054b50;
+// 20 = version 2.0, the lowest version that documents DEFLATE support.
+const VERSION_NEEDED = 20;
+const DEFLATE_METHOD = 8;
+const STORED_METHOD = 0;
+const MAX_ENTRIES = 65_535;
+
+/**
+ * Fixed MS-DOS timestamp fields (1980-01-01 00:00:00, the DOS epoch).
+ *
+ * The archive must be byte-reproducible: its sha256 keys the artifact's S3
+ * object and is substituted into the recipe, so a rebuild that produced
+ * different bytes for identical content would make CloudFormation try to
+ * replace an already-published, immutable component version and fail with
+ * AlreadyExists. Stamping the build time would do exactly that on every
+ * rebuild.
+ */
+const DOS_EPOCH_TIME = 0;
+const DOS_EPOCH_DATE = (1 << 5) | 1;
+
+/**
+ * Writes `entries` to a plain ZIP archive at `outPath` with no external
+ * dependency - only `node:zlib` for DEFLATE and CRC-32. Supports exactly what
+ * Greengrass artifact packaging needs: a flat set of files, no encryption, no
+ * zip64 (component artifacts are small). Cross-platform: no shell-out to a
+ * system `zip` binary.
+ */
+export function writeZip(entries: readonly ZipEntry[], outPath: string): void {
+  if (entries.length > MAX_ENTRIES) {
+    throw new RangeError(
+      `ZIP64 is not supported; this ZIP writer can store at most 65,535 entries, received ${entries.length}.`,
+    );
+  }
+
+  const fileChunks: Buffer[] = [];
+  const centralRecords: Buffer[] = [];
+  let offset = 0;
+  const time = DOS_EPOCH_TIME;
+  const date = DOS_EPOCH_DATE;
+
+  // Sorted so directory iteration order cannot change the archive's bytes.
+  const sortedEntries = [...entries].sort((a, b) =>
+    a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+  );
+  for (const entry of sortedEntries) {
+    const nameBuf = Buffer.from(entry.name, 'utf-8');
+    const entryCrc32 = crc32(entry.data) >>> 0;
+    const compressed = deflateRawSync(entry.data);
+    const useDeflate = compressed.length < entry.data.length;
+    const method = useDeflate ? DEFLATE_METHOD : STORED_METHOD;
+    const payload = useDeflate ? compressed : entry.data;
+
+    const localHeader = Buffer.alloc(30);
+    localHeader.writeUInt32LE(LOCAL_FILE_HEADER_SIGNATURE, 0);
+    localHeader.writeUInt16LE(VERSION_NEEDED, 4);
+    localHeader.writeUInt16LE(0, 6); // general purpose flags
+    localHeader.writeUInt16LE(method, 8);
+    localHeader.writeUInt16LE(time, 10);
+    localHeader.writeUInt16LE(date, 12);
+    localHeader.writeUInt32LE(entryCrc32, 14);
+    localHeader.writeUInt32LE(payload.length, 18);
+    localHeader.writeUInt32LE(entry.data.length, 22);
+    localHeader.writeUInt16LE(nameBuf.length, 26);
+    localHeader.writeUInt16LE(0, 28); // extra field length
+
+    fileChunks.push(localHeader, nameBuf, payload);
+
+    const centralHeader = Buffer.alloc(46);
+    centralHeader.writeUInt32LE(CENTRAL_DIRECTORY_SIGNATURE, 0);
+    centralHeader.writeUInt16LE(VERSION_NEEDED, 4); // version made by
+    centralHeader.writeUInt16LE(VERSION_NEEDED, 6); // version needed to extract
+    centralHeader.writeUInt16LE(0, 8); // general purpose flags
+    centralHeader.writeUInt16LE(method, 10);
+    centralHeader.writeUInt16LE(time, 12);
+    centralHeader.writeUInt16LE(date, 14);
+    centralHeader.writeUInt32LE(entryCrc32, 16);
+    centralHeader.writeUInt32LE(payload.length, 20);
+    centralHeader.writeUInt32LE(entry.data.length, 24);
+    centralHeader.writeUInt16LE(nameBuf.length, 28);
+    centralHeader.writeUInt16LE(0, 30); // extra field length
+    centralHeader.writeUInt16LE(0, 32); // file comment length
+    centralHeader.writeUInt16LE(0, 34); // disk number start
+    centralHeader.writeUInt16LE(0, 36); // internal file attributes
+    centralHeader.writeUInt32LE(0, 38); // external file attributes
+    centralHeader.writeUInt32LE(offset, 42); // relative offset of local header
+
+    centralRecords.push(centralHeader, nameBuf);
+
+    offset += localHeader.length + nameBuf.length + payload.length;
+  }
+
+  const centralDirectory = Buffer.concat(centralRecords);
+  const centralDirectoryOffset = offset;
+
+  const endRecord = Buffer.alloc(22);
+  endRecord.writeUInt32LE(END_OF_CENTRAL_DIRECTORY_SIGNATURE, 0);
+  endRecord.writeUInt16LE(0, 4); // disk number
+  endRecord.writeUInt16LE(0, 6); // disk with central directory start
+  endRecord.writeUInt16LE(entries.length, 8); // entries on this disk
+  endRecord.writeUInt16LE(entries.length, 10); // total entries
+  endRecord.writeUInt32LE(centralDirectory.length, 12);
+  endRecord.writeUInt32LE(centralDirectoryOffset, 16);
+  endRecord.writeUInt16LE(0, 20); // comment length
+
+  writeFileSync(
+    outPath,
+    Buffer.concat([...fileChunks, centralDirectory, endRecord]),
+  );
+}

package/src/utils/files/terraform/src/core/runtime-config/read/read.tf.template

@@ -18,9 +18,9 @@ variable "namespace" {
 }
 
 locals {
-  config_dir      = "${path.module}/../../../../../../../dist/packages/common/terraform/runtime-config"
-  entries_dir     = "${local.config_dir}/entries/${var.namespace}"
-  namespace_path  = "${local.config_dir}/${var.namespace}.json"
+  config_dir     = "${path.module}/../../../../../../../dist/packages/common/terraform/runtime-config"
+  entries_dir    = "${local.config_dir}/entries/${var.namespace}"
+  namespace_path = "${local.config_dir}/${var.namespace}.json"
 }
 
 # Aggregate leaf entry files into the namespace JSON on every apply. The

package/src/utils/files/terraform/src/metrics/metrics.tf.template

@@ -17,7 +17,7 @@ resource "aws_cloudformation_stack" "metrics" {
 
   template_body = jsonencode({
     AWSTemplateFormatVersion = "2010-09-09"
-    Description = "(${local.metric_id}) (version:${local.metric_version}) (tag:${join(",", local.metric_tags)})"
+    Description              = "(${local.metric_id}) (version:${local.metric_version}) (tag:${join(",", local.metric_tags)})"
     Resources = {
       # Empty stack - used only for metrics tracking via description
       MetricsPlaceholder = {

package/src/utils/greengrass/constants.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * The `RecipeFormatVersion` a Greengrass v2 recipe declares. Fixed by the
+ * service since the format's introduction; there is no later version to
+ * migrate to.
+ */
+export declare const RECIPE_FORMAT_VERSION: "2020-01-25";
+/**
+ * Component platforms the generator supports. Windows and `linux-any` are
+ * deferred. A recipe may carry one manifest per platform - see
+ * `GREENGRASS_PLATFORM_SELECTIONS`.
+ */
+export declare const GREENGRASS_PLATFORMS: readonly ["linux-amd64", "linux-arm64"];
+export type GreengrassPlatform = (typeof GREENGRASS_PLATFORMS)[number];
+/**
+ * `Platform.os` / `Platform.architecture` values written into a recipe manifest.
+ * The nucleus matches `aarch64` (not the Docker-style `arm64`) on 64-bit ARM
+ * devices - verified against a real core device reporting
+ * `{os=linux, architecture=aarch64}`.
+ */
+export interface GreengrassManifestPlatform {
+    readonly os: 'linux';
+    readonly architecture: 'amd64' | 'aarch64';
+}
+/** How a {@link GreengrassPlatform} maps onto a `uv` target platform and a manifest `Platform` block. */
+export interface GreengrassPlatformMapping {
+    /** Value for `uv`'s `--python-platform` flag when vendoring dependencies. */
+    readonly uvPlatform: 'x86_64-manylinux_2_28' | 'aarch64-manylinux_2_28';
+    /**
+     * The `dist/bin/<platform>-<arch>-<cRuntime>` directory name aws-crt uses for
+     * its prebuilt Node addon on this platform. Node's arch token (`x64`,
+     * `arm64`) is not the manifest token (`amd64`, `aarch64`), so both live in one
+     * entry instead of being derived from each other. glibc only - a musl device
+     * needs the escape hatch the guide documents.
+     */
+    readonly nodeCrtAddonDir: 'linux-x64-glibc' | 'linux-arm64-glibc';
+    readonly manifestPlatform: GreengrassManifestPlatform;
+}
+/**
+ * Per-platform `uv` target and recipe manifest `Platform` block. Mirrors the
+ * platform strings `addPythonBundleTarget` uses for Lambda, but this map is
+ * not shared with it: a device's Python floor is not a Lambda runtime.
+ */
+export declare const GREENGRASS_PLATFORM_MAPPINGS: Readonly<Record<GreengrassPlatform, GreengrassPlatformMapping>>;
+/**
+ * What a component generator's `platform` option accepts: one architecture, or
+ * the explicit pair. Deliberately not a `multi` value that means "every
+ * supported architecture" - that would silently change what an existing
+ * invocation produces the day a third architecture lands.
+ */
+export declare const GREENGRASS_PLATFORM_SELECTIONS: readonly ["linux-amd64", "linux-arm64", "linux-amd64-arm64"];
+export type GreengrassPlatformSelection = (typeof GREENGRASS_PLATFORM_SELECTIONS)[number];
+/** The platforms each selection expands to, in manifest order. */
+export declare const GREENGRASS_SELECTION_PLATFORMS: Readonly<Record<GreengrassPlatformSelection, readonly GreengrassPlatform[]>>;
+export declare const resolvePlatforms: (selection: GreengrassPlatformSelection) => readonly GreengrassPlatform[];

package/src/utils/greengrass/constants.js

@@ -0,0 +1,63 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ /**
+ * The `RecipeFormatVersion` a Greengrass v2 recipe declares. Fixed by the
+ * service since the format's introduction; there is no later version to
+ * migrate to.
+ */ export const RECIPE_FORMAT_VERSION = '2020-01-25';
+/**
+ * Component platforms the generator supports. Windows and `linux-any` are
+ * deferred. A recipe may carry one manifest per platform - see
+ * `GREENGRASS_PLATFORM_SELECTIONS`.
+ */ export const GREENGRASS_PLATFORMS = [
+    'linux-amd64',
+    'linux-arm64'
+];
+/**
+ * Per-platform `uv` target and recipe manifest `Platform` block. Mirrors the
+ * platform strings `addPythonBundleTarget` uses for Lambda, but this map is
+ * not shared with it: a device's Python floor is not a Lambda runtime.
+ */ export const GREENGRASS_PLATFORM_MAPPINGS = {
+    'linux-amd64': {
+        uvPlatform: 'x86_64-manylinux_2_28',
+        nodeCrtAddonDir: 'linux-x64-glibc',
+        manifestPlatform: {
+            os: 'linux',
+            architecture: 'amd64'
+        }
+    },
+    'linux-arm64': {
+        uvPlatform: 'aarch64-manylinux_2_28',
+        nodeCrtAddonDir: 'linux-arm64-glibc',
+        manifestPlatform: {
+            os: 'linux',
+            architecture: 'aarch64'
+        }
+    }
+};
+/**
+ * What a component generator's `platform` option accepts: one architecture, or
+ * the explicit pair. Deliberately not a `multi` value that means "every
+ * supported architecture" - that would silently change what an existing
+ * invocation produces the day a third architecture lands.
+ */ export const GREENGRASS_PLATFORM_SELECTIONS = [
+    'linux-amd64',
+    'linux-arm64',
+    'linux-amd64-arm64'
+];
+/** The platforms each selection expands to, in manifest order. */ export const GREENGRASS_SELECTION_PLATFORMS = {
+    'linux-amd64': [
+        'linux-amd64'
+    ],
+    'linux-arm64': [
+        'linux-arm64'
+    ],
+    'linux-amd64-arm64': [
+        'linux-amd64',
+        'linux-arm64'
+    ]
+};
+export const resolvePlatforms = (selection)=>GREENGRASS_SELECTION_PLATFORMS[selection];
+
+//# sourceMappingURL=constants.js.map

package/src/utils/greengrass/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/greengrass/constants.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\n\n/**\n * The `RecipeFormatVersion` a Greengrass v2 recipe declares. Fixed by the\n * service since the format's introduction; there is no later version to\n * migrate to.\n */\nexport const RECIPE_FORMAT_VERSION = '2020-01-25' as const;\n\n/**\n * Component platforms the generator supports. Windows and `linux-any` are\n * deferred. A recipe may carry one manifest per platform - see\n * `GREENGRASS_PLATFORM_SELECTIONS`.\n */\nexport const GREENGRASS_PLATFORMS = ['linux-amd64', 'linux-arm64'] as const;\n\nexport type GreengrassPlatform = (typeof GREENGRASS_PLATFORMS)[number];\n\n/**\n * `Platform.os` / `Platform.architecture` values written into a recipe manifest.\n * The nucleus matches `aarch64` (not the Docker-style `arm64`) on 64-bit ARM\n * devices - verified against a real core device reporting\n * `{os=linux, architecture=aarch64}`.\n */\nexport interface GreengrassManifestPlatform {\n  readonly os: 'linux';\n  readonly architecture: 'amd64' | 'aarch64';\n}\n\n/** How a {@link GreengrassPlatform} maps onto a `uv` target platform and a manifest `Platform` block. */\nexport interface GreengrassPlatformMapping {\n  /** Value for `uv`'s `--python-platform` flag when vendoring dependencies. */\n  readonly uvPlatform: 'x86_64-manylinux_2_28' | 'aarch64-manylinux_2_28';\n  /**\n   * The `dist/bin/<platform>-<arch>-<cRuntime>` directory name aws-crt uses for\n   * its prebuilt Node addon on this platform. Node's arch token (`x64`,\n   * `arm64`) is not the manifest token (`amd64`, `aarch64`), so both live in one\n   * entry instead of being derived from each other. glibc only - a musl device\n   * needs the escape hatch the guide documents.\n   */\n  readonly nodeCrtAddonDir: 'linux-x64-glibc' | 'linux-arm64-glibc';\n  readonly manifestPlatform: GreengrassManifestPlatform;\n}\n\n/**\n * Per-platform `uv` target and recipe manifest `Platform` block. Mirrors the\n * platform strings `addPythonBundleTarget` uses for Lambda, but this map is\n * not shared with it: a device's Python floor is not a Lambda runtime.\n */\nexport const GREENGRASS_PLATFORM_MAPPINGS: Readonly<\n  Record<GreengrassPlatform, GreengrassPlatformMapping>\n> = {\n  'linux-amd64': {\n    uvPlatform: 'x86_64-manylinux_2_28',\n    nodeCrtAddonDir: 'linux-x64-glibc',\n    manifestPlatform: { os: 'linux', architecture: 'amd64' },\n  },\n  'linux-arm64': {\n    uvPlatform: 'aarch64-manylinux_2_28',\n    nodeCrtAddonDir: 'linux-arm64-glibc',\n    manifestPlatform: { os: 'linux', architecture: 'aarch64' },\n  },\n} as const;\n\n/**\n * What a component generator's `platform` option accepts: one architecture, or\n * the explicit pair. Deliberately not a `multi` value that means \"every\n * supported architecture\" - that would silently change what an existing\n * invocation produces the day a third architecture lands.\n */\nexport const GREENGRASS_PLATFORM_SELECTIONS = [\n  'linux-amd64',\n  'linux-arm64',\n  'linux-amd64-arm64',\n] as const;\n\nexport type GreengrassPlatformSelection =\n  (typeof GREENGRASS_PLATFORM_SELECTIONS)[number];\n\n/** The platforms each selection expands to, in manifest order. */\nexport const GREENGRASS_SELECTION_PLATFORMS: Readonly<\n  Record<GreengrassPlatformSelection, readonly GreengrassPlatform[]>\n> = {\n  'linux-amd64': ['linux-amd64'],\n  'linux-arm64': ['linux-arm64'],\n  'linux-amd64-arm64': ['linux-amd64', 'linux-arm64'],\n} as const;\n\nexport const resolvePlatforms = (\n  selection: GreengrassPlatformSelection,\n): readonly GreengrassPlatform[] => GREENGRASS_SELECTION_PLATFORMS[selection];\n"],"names":["RECIPE_FORMAT_VERSION","GREENGRASS_PLATFORMS","GREENGRASS_PLATFORM_MAPPINGS","uvPlatform","nodeCrtAddonDir","manifestPlatform","os","architecture","GREENGRASS_PLATFORM_SELECTIONS","GREENGRASS_SELECTION_PLATFORMS","resolvePlatforms","selection"],"mappings":"AAAA;;;CAGC,GAED;;;;CAIC,GACD,OAAO,MAAMA,wBAAwB,aAAsB;AAE3D;;;;CAIC,GACD,OAAO,MAAMC,uBAAuB;IAAC;IAAe;CAAc,CAAU;AA8B5E;;;;CAIC,GACD,OAAO,MAAMC,+BAET;IACF,eAAe;QACbC,YAAY;QACZC,iBAAiB;QACjBC,kBAAkB;YAAEC,IAAI;YAASC,cAAc;QAAQ;IACzD;IACA,eAAe;QACbJ,YAAY;QACZC,iBAAiB;QACjBC,kBAAkB;YAAEC,IAAI;YAASC,cAAc;QAAU;IAC3D;AACF,EAAW;AAEX;;;;;CAKC,GACD,OAAO,MAAMC,iCAAiC;IAC5C;IACA;IACA;CACD,CAAU;AAKX,gEAAgE,GAChE,OAAO,MAAMC,iCAET;IACF,eAAe;QAAC;KAAc;IAC9B,eAAe;QAAC;KAAc;IAC9B,qBAAqB;QAAC;QAAe;KAAc;AACrD,EAAW;AAEX,OAAO,MAAMC,mBAAmB,CAC9BC,YACkCF,8BAA8B,CAACE,UAAU,CAAC"}

package/src/utils/greengrass/naming.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { Tree } from '@nx/devkit';
+/**
+ * Characters a Greengrass v2 `ComponentName` may contain. Matches the
+ * `CreateComponentVersion` API's own constraint.
+ */
+export declare const COMPONENT_NAME_PATTERN: RegExp;
+/** Longest `ComponentName` the `CreateComponentVersion` API accepts. */
+export declare const MAX_COMPONENT_NAME_LENGTH = 128;
+/** Longest name that fits the CDK artifact prefix with its 32-character hash. */
+export declare const MAX_CDK_COMPONENT_NAME_LENGTH = 68;
+/**
+ * Prefix AWS reserves for its own public components. A user-authored
+ * `ComponentName` starting with this is rejected by the service, so the
+ * plugin rejects it up front with an actionable message instead.
+ */
+export declare const RESERVED_COMPONENT_NAME_PREFIX = "aws.greengrass.";
+/** Why a `ComponentName` failed validation. */
+export type ComponentNameIssueReason = 'invalid-characters' | 'too-long' | 'reserved-prefix';
+export interface ComponentNameIssue {
+    readonly reason: ComponentNameIssueReason;
+    readonly message: string;
+}
+/**
+ * Validate a `ComponentName` against the constraints the service enforces:
+ * the allowed character set, the length limit, and the reserved
+ * `aws.greengrass.` prefix. Returns one issue per violated constraint, empty
+ * when the name is valid.
+ */
+export declare const validateComponentName: (componentName: string) => ComponentNameIssue[];
+/**
+ * Validate a `ComponentName`, throwing an actionable error naming every
+ * violated constraint when it is invalid.
+ */
+export declare const assertValidComponentName: (componentName: string) => void;
+/**
+ * Build the default `ComponentName` for a new component: `com.<sanitized
+ * workspace npm scope>.<PascalCaseName>`, the reversed-domain style the
+ * service's own samples use. Reflects the workspace's npm scope at
+ * generation time; re-scoping the workspace afterwards does not rename
+ * already-generated components.
+ */
+export declare const buildDefaultComponentName: (tree: Tree, name: string) => string;