@aws/nx-plugin 1.1.1 → 1.2.0

package/src/utils/greengrass/naming.js

@@ -0,0 +1,67 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import { pascalCase } from "../names.js";
+import { getNpmScope } from "../npm-scope.js";
+/**
+ * Characters a Greengrass v2 `ComponentName` may contain. Matches the
+ * `CreateComponentVersion` API's own constraint.
+ */ export const COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9-_.]+$/;
+/** Longest `ComponentName` the `CreateComponentVersion` API accepts. */ export const MAX_COMPONENT_NAME_LENGTH = 128;
+/** Longest name that fits the CDK artifact prefix with its 32-character hash. */ export 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 const RESERVED_COMPONENT_NAME_PREFIX = 'aws.greengrass.';
+/**
+ * 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 const validateComponentName = (componentName)=>{
+    const issues = [];
+    if (!COMPONENT_NAME_PATTERN.test(componentName)) {
+        issues.push({
+            reason: 'invalid-characters',
+            message: `ComponentName "${componentName}" must match ${COMPONENT_NAME_PATTERN} (letters, digits, hyphens, underscores and dots only).`
+        });
+    }
+    if (componentName.length > MAX_COMPONENT_NAME_LENGTH) {
+        issues.push({
+            reason: 'too-long',
+            message: `ComponentName "${componentName}" is ${componentName.length} characters long, exceeding the ${MAX_COMPONENT_NAME_LENGTH} character limit.`
+        });
+    }
+    if (componentName.startsWith(RESERVED_COMPONENT_NAME_PREFIX)) {
+        issues.push({
+            reason: 'reserved-prefix',
+            message: `ComponentName "${componentName}" uses the "${RESERVED_COMPONENT_NAME_PREFIX}" prefix, which AWS reserves for its own components.`
+        });
+    }
+    return issues;
+};
+/**
+ * Validate a `ComponentName`, throwing an actionable error naming every
+ * violated constraint when it is invalid.
+ */ export const assertValidComponentName = (componentName)=>{
+    const issues = validateComponentName(componentName);
+    if (issues.length > 0) {
+        throw new Error(issues.map((issue)=>issue.message).join(' '));
+    }
+};
+/**
+ * Reduce an npm scope to the character set {@link COMPONENT_NAME_PATTERN}
+ * allows: lower-cased, any other character collapsed to a single `-`, and
+ * leading/trailing separators trimmed so the result never starts or ends a
+ * `ComponentName` segment with a stray punctuation mark.
+ */ const sanitizeForComponentName = (segment)=>segment.toLowerCase().replace(/[^a-z0-9-_.]+/g, '-').replace(/^[-_.]+|[-_.]+$/g, '');
+/**
+ * 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 const buildDefaultComponentName = (tree, name)=>`com.${sanitizeForComponentName(getNpmScope(tree) ?? 'monorepo')}.${pascalCase(name)}`;
+
+//# sourceMappingURL=naming.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/greengrass/naming.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 { pascalCase } from '../names.js';\nimport { getNpmScope } from '../npm-scope.js';\n\n/**\n * Characters a Greengrass v2 `ComponentName` may contain. Matches the\n * `CreateComponentVersion` API's own constraint.\n */\nexport const COMPONENT_NAME_PATTERN = /^[a-zA-Z0-9-_.]+$/;\n\n/** Longest `ComponentName` the `CreateComponentVersion` API accepts. */\nexport const MAX_COMPONENT_NAME_LENGTH = 128;\n\n/** Longest name that fits the CDK artifact prefix with its 32-character hash. */\nexport const MAX_CDK_COMPONENT_NAME_LENGTH = 68;\n\n/**\n * Prefix AWS reserves for its own public components. A user-authored\n * `ComponentName` starting with this is rejected by the service, so the\n * plugin rejects it up front with an actionable message instead.\n */\nexport const RESERVED_COMPONENT_NAME_PREFIX = 'aws.greengrass.';\n\n/** Why a `ComponentName` failed validation. */\nexport type ComponentNameIssueReason =\n  | 'invalid-characters'\n  | 'too-long'\n  | 'reserved-prefix';\n\nexport interface ComponentNameIssue {\n  readonly reason: ComponentNameIssueReason;\n  readonly message: string;\n}\n\n/**\n * Validate a `ComponentName` against the constraints the service enforces:\n * the allowed character set, the length limit, and the reserved\n * `aws.greengrass.` prefix. Returns one issue per violated constraint, empty\n * when the name is valid.\n */\nexport const validateComponentName = (\n  componentName: string,\n): ComponentNameIssue[] => {\n  const issues: ComponentNameIssue[] = [];\n\n  if (!COMPONENT_NAME_PATTERN.test(componentName)) {\n    issues.push({\n      reason: 'invalid-characters',\n      message: `ComponentName \"${componentName}\" must match ${COMPONENT_NAME_PATTERN} (letters, digits, hyphens, underscores and dots only).`,\n    });\n  }\n\n  if (componentName.length > MAX_COMPONENT_NAME_LENGTH) {\n    issues.push({\n      reason: 'too-long',\n      message: `ComponentName \"${componentName}\" is ${componentName.length} characters long, exceeding the ${MAX_COMPONENT_NAME_LENGTH} character limit.`,\n    });\n  }\n\n  if (componentName.startsWith(RESERVED_COMPONENT_NAME_PREFIX)) {\n    issues.push({\n      reason: 'reserved-prefix',\n      message: `ComponentName \"${componentName}\" uses the \"${RESERVED_COMPONENT_NAME_PREFIX}\" prefix, which AWS reserves for its own components.`,\n    });\n  }\n\n  return issues;\n};\n\n/**\n * Validate a `ComponentName`, throwing an actionable error naming every\n * violated constraint when it is invalid.\n */\nexport const assertValidComponentName = (componentName: string): void => {\n  const issues = validateComponentName(componentName);\n  if (issues.length > 0) {\n    throw new Error(issues.map((issue) => issue.message).join(' '));\n  }\n};\n\n/**\n * Reduce an npm scope to the character set {@link COMPONENT_NAME_PATTERN}\n * allows: lower-cased, any other character collapsed to a single `-`, and\n * leading/trailing separators trimmed so the result never starts or ends a\n * `ComponentName` segment with a stray punctuation mark.\n */\nconst sanitizeForComponentName = (segment: string): string =>\n  segment\n    .toLowerCase()\n    .replace(/[^a-z0-9-_.]+/g, '-')\n    .replace(/^[-_.]+|[-_.]+$/g, '');\n\n/**\n * Build the default `ComponentName` for a new component: `com.<sanitized\n * workspace npm scope>.<PascalCaseName>`, the reversed-domain style the\n * service's own samples use. Reflects the workspace's npm scope at\n * generation time; re-scoping the workspace afterwards does not rename\n * already-generated components.\n */\nexport const buildDefaultComponentName = (tree: Tree, name: string): string =>\n  `com.${sanitizeForComponentName(getNpmScope(tree) ?? 'monorepo')}.${pascalCase(name)}`;\n"],"names":["pascalCase","getNpmScope","COMPONENT_NAME_PATTERN","MAX_COMPONENT_NAME_LENGTH","MAX_CDK_COMPONENT_NAME_LENGTH","RESERVED_COMPONENT_NAME_PREFIX","validateComponentName","componentName","issues","test","push","reason","message","length","startsWith","assertValidComponentName","Error","map","issue","join","sanitizeForComponentName","segment","toLowerCase","replace","buildDefaultComponentName","tree","name"],"mappings":"AAAA;;;CAGC,GAED,SAASA,UAAU,QAAQ,cAAc;AACzC,SAASC,WAAW,QAAQ,kBAAkB;AAE9C;;;CAGC,GACD,OAAO,MAAMC,yBAAyB,oBAAoB;AAE1D,sEAAsE,GACtE,OAAO,MAAMC,4BAA4B,IAAI;AAE7C,+EAA+E,GAC/E,OAAO,MAAMC,gCAAgC,GAAG;AAEhD;;;;CAIC,GACD,OAAO,MAAMC,iCAAiC,kBAAkB;AAahE;;;;;CAKC,GACD,OAAO,MAAMC,wBAAwB,CACnCC;IAEA,MAAMC,SAA+B,EAAE;IAEvC,IAAI,CAACN,uBAAuBO,IAAI,CAACF,gBAAgB;QAC/CC,OAAOE,IAAI,CAAC;YACVC,QAAQ;YACRC,SAAS,CAAC,eAAe,EAAEL,cAAc,aAAa,EAAEL,uBAAuB,uDAAuD,CAAC;QACzI;IACF;IAEA,IAAIK,cAAcM,MAAM,GAAGV,2BAA2B;QACpDK,OAAOE,IAAI,CAAC;YACVC,QAAQ;YACRC,SAAS,CAAC,eAAe,EAAEL,cAAc,KAAK,EAAEA,cAAcM,MAAM,CAAC,gCAAgC,EAAEV,0BAA0B,iBAAiB,CAAC;QACrJ;IACF;IAEA,IAAII,cAAcO,UAAU,CAACT,iCAAiC;QAC5DG,OAAOE,IAAI,CAAC;YACVC,QAAQ;YACRC,SAAS,CAAC,eAAe,EAAEL,cAAc,YAAY,EAAEF,+BAA+B,oDAAoD,CAAC;QAC7I;IACF;IAEA,OAAOG;AACT,EAAE;AAEF;;;CAGC,GACD,OAAO,MAAMO,2BAA2B,CAACR;IACvC,MAAMC,SAASF,sBAAsBC;IACrC,IAAIC,OAAOK,MAAM,GAAG,GAAG;QACrB,MAAM,IAAIG,MAAMR,OAAOS,GAAG,CAAC,CAACC,QAAUA,MAAMN,OAAO,EAAEO,IAAI,CAAC;IAC5D;AACF,EAAE;AAEF;;;;;CAKC,GACD,MAAMC,2BAA2B,CAACC,UAChCA,QACGC,WAAW,GACXC,OAAO,CAAC,kBAAkB,KAC1BA,OAAO,CAAC,oBAAoB;AAEjC;;;;;;CAMC,GACD,OAAO,MAAMC,4BAA4B,CAACC,MAAYC,OACpD,CAAC,IAAI,EAAEN,yBAAyBnB,YAAYwB,SAAS,YAAY,CAAC,EAAEzB,WAAW0B,OAAO,CAAC"}

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

@@ -0,0 +1,143 @@
+import { z } from 'zod';
+export declare const NEXT_VERSION_SENTINELS: readonly ["NEXT_PATCH", "NEXT_MINOR", "NEXT_MAJOR"];
+export type NextVersionSentinel = (typeof NEXT_VERSION_SENTINELS)[number];
+/** Whether a value requests deploy-time component version resolution. */
+export declare const isNextVersionSentinel: (value: string) => value is NextVersionSentinel;
+/** Maps a version sentinel to its semantic-version bump strategy. */
+export declare const nextVersionStrategy: (sentinel: NextVersionSentinel) => "patch" | "minor" | "major";
+/** Whether a value is a semantic version or a deploy-time version sentinel. */
+export declare const isValidComponentVersion: (value: string) => boolean;
+/**
+ * Typed model of the Greengrass v2 recipe format (`RecipeFormatVersion`
+ * `2020-01-25`) and a zod schema over it.
+ *
+ * `recipe.yaml` is user-owned (vended once with `OverwriteStrategy.KeepExisting`,
+ * never rewritten wholesale), so validation covers ONLY the fields the plugin
+ * itself reads or rewrites: `ComponentName`, `ComponentVersion`, and the
+ * manifest/artifact/lifecycle paths a future build step touches. Every schema
+ * below is a loose object: fields the plugin does not model pass through
+ * `parseRecipe`/`validateRecipe` untouched rather than being stripped or
+ * rejected. There is deliberately no whole-document string substitution
+ * anywhere in this module; a caller that needs to rewrite a value does so on
+ * the parsed object at its specific path (eg. `raw.Manifests[0].Artifacts[0].Uri`)
+ * and re-serializes with `yaml.dump`.
+ */
+/**
+ * A component lifecycle step's arguments. Step names (`Run`, `Install`,
+ * `Startup`, `Shutdown`, `Bootstrap`, `Recover`, ...) and each step's shape
+ * (a bare script string, an object with `script`/`requiresPrivilege`/`setEnv`/
+ * `timeout`, or a per-platform selection map) are entirely user-authored and
+ * not modeled field-by-field here, so an unrecognised step or key is
+ * preserved rather than rejected.
+ */
+export type Lifecycle = Record<string, unknown>;
+/** `Manifests[].Platform`. */
+export interface RecipePlatform {
+    readonly os?: string;
+    readonly architecture?: string;
+    readonly [key: string]: unknown;
+}
+/** `Manifests[].Artifacts[]`. */
+export interface RecipeArtifact {
+    readonly Uri: string;
+    readonly [key: string]: unknown;
+}
+/** `Manifests[]`. */
+export interface RecipeManifest {
+    readonly Platform?: RecipePlatform;
+    readonly Name?: string;
+    readonly Lifecycle?: Lifecycle;
+    readonly Artifacts?: readonly RecipeArtifact[];
+    readonly Selections?: readonly string[];
+    readonly [key: string]: unknown;
+}
+/** `ComponentConfiguration`. */
+export interface ComponentConfiguration {
+    readonly DefaultConfiguration?: Record<string, unknown>;
+    readonly [key: string]: unknown;
+}
+export type ComponentDependencyType = 'HARD' | 'SOFT';
+/** A single entry of `ComponentDependencies`. */
+export interface ComponentDependencyRequirement {
+    readonly VersionRequirement?: string;
+    readonly DependencyType?: ComponentDependencyType;
+    readonly [key: string]: unknown;
+}
+/** `ComponentDependencies`, keyed by the dependency's `ComponentName`. */
+export type ComponentDependencies = Record<string, ComponentDependencyRequirement>;
+/** The full Greengrass v2 recipe document. */
+export interface GreengrassRecipe {
+    readonly RecipeFormatVersion: string;
+    readonly ComponentName: string;
+    readonly ComponentVersion: string;
+    readonly ComponentDescription?: string;
+    readonly ComponentPublisher?: string;
+    readonly ComponentConfiguration?: ComponentConfiguration;
+    readonly ComponentDependencies?: ComponentDependencies;
+    readonly Manifests: readonly RecipeManifest[];
+    readonly [key: string]: unknown;
+}
+/**
+ * Schema for the fields the plugin consumes. `.looseObject` at every level
+ * means an unrecognised top-level key, manifest key or lifecycle key parses
+ * through unchanged rather than being stripped; `ComponentName` and
+ * `ComponentVersion` are the only fields checked against a service
+ * constraint, via `superRefine` so both issues surface together when a
+ * recipe violates both.
+ */
+export declare const GreengrassRecipeSchema: z.ZodObject<{
+    RecipeFormatVersion: z.ZodString;
+    ComponentName: z.ZodString;
+    ComponentVersion: z.ZodString;
+    ComponentDescription: z.ZodOptional<z.ZodString>;
+    ComponentPublisher: z.ZodOptional<z.ZodString>;
+    ComponentConfiguration: z.ZodOptional<z.ZodObject<{
+        DefaultConfiguration: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$loose>>;
+    ComponentDependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        VersionRequirement: z.ZodOptional<z.ZodString>;
+        DependencyType: z.ZodOptional<z.ZodEnum<{
+            HARD: "HARD";
+            SOFT: "SOFT";
+        }>>;
+    }, z.core.$loose>>>;
+    Manifests: z.ZodArray<z.ZodObject<{
+        Platform: z.ZodOptional<z.ZodObject<{
+            os: z.ZodOptional<z.ZodString>;
+            architecture: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        Name: z.ZodOptional<z.ZodString>;
+        Lifecycle: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        Artifacts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            Uri: z.ZodString;
+        }, z.core.$loose>>>;
+        Selections: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** One validation failure, with the recipe path it applies to. */
+export interface RecipeValidationIssue {
+    /** Dot-separated path into the recipe, eg. `Manifests.0.Artifacts.0.Uri`. */
+    readonly path: string;
+    readonly message: string;
+}
+/**
+ * Validate an already-parsed recipe object against {@link GreengrassRecipeSchema},
+ * returning every violation found rather than throwing on the first. Empty
+ * when the recipe is valid.
+ */
+export declare const validateRecipe: (raw: unknown) => RecipeValidationIssue[];
+export interface ParsedRecipe {
+    /** The validated, typed view of the recipe. */
+    readonly recipe: GreengrassRecipe;
+    /** The unvalidated result of parsing the YAML, exactly as loaded. */
+    readonly raw: unknown;
+}
+/**
+ * Parse a recipe YAML document and validate it, throwing when the fields the
+ * plugin consumes are invalid. `raw` is the plain object `js-yaml` produced,
+ * before validation; a caller that needs to rewrite the recipe (eg. to
+ * substitute an artifact URI) mutates `raw` at the specific path and
+ * re-serializes it with `yaml.dump`, so fields this module does not model are
+ * never disturbed.
+ */
+export declare const parseRecipe: (yamlSource: string) => ParsedRecipe;

package/src/utils/greengrass/recipe.js

@@ -0,0 +1,119 @@
+/**
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */ import yaml from "js-yaml";
+import { valid as validSemver } from "semver";
+import { z } from "zod";
+import { validateComponentName } from "./naming.js";
+export const NEXT_VERSION_SENTINELS = [
+    'NEXT_PATCH',
+    'NEXT_MINOR',
+    'NEXT_MAJOR'
+];
+/** Whether a value requests deploy-time component version resolution. */ export const isNextVersionSentinel = (value)=>NEXT_VERSION_SENTINELS.includes(value);
+/** Maps a version sentinel to its semantic-version bump strategy. */ export const nextVersionStrategy = (sentinel)=>{
+    switch(sentinel){
+        case 'NEXT_PATCH':
+            return 'patch';
+        case 'NEXT_MINOR':
+            return 'minor';
+        case 'NEXT_MAJOR':
+            return 'major';
+    }
+};
+/** Whether a value is a semantic version or a deploy-time version sentinel. */ export const isValidComponentVersion = (value)=>Boolean(validSemver(value)) || isNextVersionSentinel(value);
+const RecipePlatformSchema = z.looseObject({
+    os: z.string().optional(),
+    architecture: z.string().optional()
+});
+const RecipeArtifactSchema = z.looseObject({
+    Uri: z.string()
+});
+const LifecycleSchema = z.record(z.string(), z.unknown());
+const RecipeManifestSchema = z.looseObject({
+    Platform: RecipePlatformSchema.optional(),
+    Name: z.string().optional(),
+    Lifecycle: LifecycleSchema.optional(),
+    Artifacts: z.array(RecipeArtifactSchema).optional(),
+    Selections: z.array(z.string()).optional()
+});
+const ComponentConfigurationSchema = z.looseObject({
+    DefaultConfiguration: z.record(z.string(), z.unknown()).optional()
+});
+const ComponentDependencyRequirementSchema = z.looseObject({
+    VersionRequirement: z.string().optional(),
+    DependencyType: z.enum([
+        'HARD',
+        'SOFT'
+    ]).optional()
+});
+const ComponentDependenciesSchema = z.record(z.string(), ComponentDependencyRequirementSchema);
+/**
+ * Schema for the fields the plugin consumes. `.looseObject` at every level
+ * means an unrecognised top-level key, manifest key or lifecycle key parses
+ * through unchanged rather than being stripped; `ComponentName` and
+ * `ComponentVersion` are the only fields checked against a service
+ * constraint, via `superRefine` so both issues surface together when a
+ * recipe violates both.
+ */ export const GreengrassRecipeSchema = z.looseObject({
+    RecipeFormatVersion: z.string(),
+    ComponentName: z.string(),
+    ComponentVersion: z.string(),
+    ComponentDescription: z.string().optional(),
+    ComponentPublisher: z.string().optional(),
+    ComponentConfiguration: ComponentConfigurationSchema.optional(),
+    ComponentDependencies: ComponentDependenciesSchema.optional(),
+    Manifests: z.array(RecipeManifestSchema)
+}).superRefine((recipe, ctx)=>{
+    for (const issue of validateComponentName(recipe.ComponentName)){
+        ctx.addIssue({
+            code: 'custom',
+            message: issue.message,
+            path: [
+                'ComponentName'
+            ]
+        });
+    }
+    if (!isValidComponentVersion(recipe.ComponentVersion)) {
+        ctx.addIssue({
+            code: 'custom',
+            message: `ComponentVersion "${recipe.ComponentVersion}" must be a valid semantic version (eg. "1.0.0") or one of NEXT_PATCH, NEXT_MINOR, NEXT_MAJOR.`,
+            path: [
+                'ComponentVersion'
+            ]
+        });
+    }
+});
+const toValidationIssues = (error)=>error.issues.map((issue)=>({
+            path: issue.path.join('.'),
+            message: issue.message
+        }));
+/**
+ * Validate an already-parsed recipe object against {@link GreengrassRecipeSchema},
+ * returning every violation found rather than throwing on the first. Empty
+ * when the recipe is valid.
+ */ export const validateRecipe = (raw)=>{
+    const result = GreengrassRecipeSchema.safeParse(raw);
+    return result.success ? [] : toValidationIssues(result.error);
+};
+/**
+ * Parse a recipe YAML document and validate it, throwing when the fields the
+ * plugin consumes are invalid. `raw` is the plain object `js-yaml` produced,
+ * before validation; a caller that needs to rewrite the recipe (eg. to
+ * substitute an artifact URI) mutates `raw` at the specific path and
+ * re-serializes it with `yaml.dump`, so fields this module does not model are
+ * never disturbed.
+ */ export const parseRecipe = (yamlSource)=>{
+    const raw = yaml.load(yamlSource);
+    const result = GreengrassRecipeSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = toValidationIssues(result.error).map((issue)=>`  - ${issue.path || '(root)'}: ${issue.message}`).join('\n');
+        throw new Error(`Invalid Greengrass recipe:\n${issues}`);
+    }
+    return {
+        recipe: result.data,
+        raw
+    };
+};
+
+//# sourceMappingURL=recipe.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../packages/nx-plugin/src/utils/greengrass/recipe.ts"],"sourcesContent":["/**\n * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.\n * SPDX-License-Identifier: Apache-2.0\n */\nimport yaml from 'js-yaml';\nimport { valid as validSemver } from 'semver';\nimport { z } from 'zod';\nimport { validateComponentName } from './naming.js';\n\nexport const NEXT_VERSION_SENTINELS = [\n  'NEXT_PATCH',\n  'NEXT_MINOR',\n  'NEXT_MAJOR',\n] as const;\n\nexport type NextVersionSentinel = (typeof NEXT_VERSION_SENTINELS)[number];\n\n/** Whether a value requests deploy-time component version resolution. */\nexport const isNextVersionSentinel = (\n  value: string,\n): value is NextVersionSentinel =>\n  NEXT_VERSION_SENTINELS.includes(value as NextVersionSentinel);\n\n/** Maps a version sentinel to its semantic-version bump strategy. */\nexport const nextVersionStrategy = (\n  sentinel: NextVersionSentinel,\n): 'patch' | 'minor' | 'major' => {\n  switch (sentinel) {\n    case 'NEXT_PATCH':\n      return 'patch';\n    case 'NEXT_MINOR':\n      return 'minor';\n    case 'NEXT_MAJOR':\n      return 'major';\n  }\n};\n\n/** Whether a value is a semantic version or a deploy-time version sentinel. */\nexport const isValidComponentVersion = (value: string): boolean =>\n  Boolean(validSemver(value)) || isNextVersionSentinel(value);\n\n/**\n * Typed model of the Greengrass v2 recipe format (`RecipeFormatVersion`\n * `2020-01-25`) and a zod schema over it.\n *\n * `recipe.yaml` is user-owned (vended once with `OverwriteStrategy.KeepExisting`,\n * never rewritten wholesale), so validation covers ONLY the fields the plugin\n * itself reads or rewrites: `ComponentName`, `ComponentVersion`, and the\n * manifest/artifact/lifecycle paths a future build step touches. Every schema\n * below is a loose object: fields the plugin does not model pass through\n * `parseRecipe`/`validateRecipe` untouched rather than being stripped or\n * rejected. There is deliberately no whole-document string substitution\n * anywhere in this module; a caller that needs to rewrite a value does so on\n * the parsed object at its specific path (eg. `raw.Manifests[0].Artifacts[0].Uri`)\n * and re-serializes with `yaml.dump`.\n */\n\n/**\n * A component lifecycle step's arguments. Step names (`Run`, `Install`,\n * `Startup`, `Shutdown`, `Bootstrap`, `Recover`, ...) and each step's shape\n * (a bare script string, an object with `script`/`requiresPrivilege`/`setEnv`/\n * `timeout`, or a per-platform selection map) are entirely user-authored and\n * not modeled field-by-field here, so an unrecognised step or key is\n * preserved rather than rejected.\n */\nexport type Lifecycle = Record<string, unknown>;\n\n/** `Manifests[].Platform`. */\nexport interface RecipePlatform {\n  readonly os?: string;\n  readonly architecture?: string;\n  readonly [key: string]: unknown;\n}\n\n/** `Manifests[].Artifacts[]`. */\nexport interface RecipeArtifact {\n  readonly Uri: string;\n  readonly [key: string]: unknown;\n}\n\n/** `Manifests[]`. */\nexport interface RecipeManifest {\n  readonly Platform?: RecipePlatform;\n  readonly Name?: string;\n  readonly Lifecycle?: Lifecycle;\n  readonly Artifacts?: readonly RecipeArtifact[];\n  readonly Selections?: readonly string[];\n  readonly [key: string]: unknown;\n}\n\n/** `ComponentConfiguration`. */\nexport interface ComponentConfiguration {\n  readonly DefaultConfiguration?: Record<string, unknown>;\n  readonly [key: string]: unknown;\n}\n\nexport type ComponentDependencyType = 'HARD' | 'SOFT';\n\n/** A single entry of `ComponentDependencies`. */\nexport interface ComponentDependencyRequirement {\n  readonly VersionRequirement?: string;\n  readonly DependencyType?: ComponentDependencyType;\n  readonly [key: string]: unknown;\n}\n\n/** `ComponentDependencies`, keyed by the dependency's `ComponentName`. */\nexport type ComponentDependencies = Record<\n  string,\n  ComponentDependencyRequirement\n>;\n\n/** The full Greengrass v2 recipe document. */\nexport interface GreengrassRecipe {\n  readonly RecipeFormatVersion: string;\n  readonly ComponentName: string;\n  readonly ComponentVersion: string;\n  readonly ComponentDescription?: string;\n  readonly ComponentPublisher?: string;\n  readonly ComponentConfiguration?: ComponentConfiguration;\n  readonly ComponentDependencies?: ComponentDependencies;\n  readonly Manifests: readonly RecipeManifest[];\n  readonly [key: string]: unknown;\n}\n\nconst RecipePlatformSchema = z.looseObject({\n  os: z.string().optional(),\n  architecture: z.string().optional(),\n});\n\nconst RecipeArtifactSchema = z.looseObject({\n  Uri: z.string(),\n});\n\nconst LifecycleSchema = z.record(z.string(), z.unknown());\n\nconst RecipeManifestSchema = z.looseObject({\n  Platform: RecipePlatformSchema.optional(),\n  Name: z.string().optional(),\n  Lifecycle: LifecycleSchema.optional(),\n  Artifacts: z.array(RecipeArtifactSchema).optional(),\n  Selections: z.array(z.string()).optional(),\n});\n\nconst ComponentConfigurationSchema = z.looseObject({\n  DefaultConfiguration: z.record(z.string(), z.unknown()).optional(),\n});\n\nconst ComponentDependencyRequirementSchema = z.looseObject({\n  VersionRequirement: z.string().optional(),\n  DependencyType: z.enum(['HARD', 'SOFT']).optional(),\n});\n\nconst ComponentDependenciesSchema = z.record(\n  z.string(),\n  ComponentDependencyRequirementSchema,\n);\n\n/**\n * Schema for the fields the plugin consumes. `.looseObject` at every level\n * means an unrecognised top-level key, manifest key or lifecycle key parses\n * through unchanged rather than being stripped; `ComponentName` and\n * `ComponentVersion` are the only fields checked against a service\n * constraint, via `superRefine` so both issues surface together when a\n * recipe violates both.\n */\nexport const GreengrassRecipeSchema = z\n  .looseObject({\n    RecipeFormatVersion: z.string(),\n    ComponentName: z.string(),\n    ComponentVersion: z.string(),\n    ComponentDescription: z.string().optional(),\n    ComponentPublisher: z.string().optional(),\n    ComponentConfiguration: ComponentConfigurationSchema.optional(),\n    ComponentDependencies: ComponentDependenciesSchema.optional(),\n    Manifests: z.array(RecipeManifestSchema),\n  })\n  .superRefine((recipe, ctx) => {\n    for (const issue of validateComponentName(recipe.ComponentName)) {\n      ctx.addIssue({\n        code: 'custom',\n        message: issue.message,\n        path: ['ComponentName'],\n      });\n    }\n\n    if (!isValidComponentVersion(recipe.ComponentVersion)) {\n      ctx.addIssue({\n        code: 'custom',\n        message: `ComponentVersion \"${recipe.ComponentVersion}\" must be a valid semantic version (eg. \"1.0.0\") or one of NEXT_PATCH, NEXT_MINOR, NEXT_MAJOR.`,\n        path: ['ComponentVersion'],\n      });\n    }\n  });\n\n/** One validation failure, with the recipe path it applies to. */\nexport interface RecipeValidationIssue {\n  /** Dot-separated path into the recipe, eg. `Manifests.0.Artifacts.0.Uri`. */\n  readonly path: string;\n  readonly message: string;\n}\n\nconst toValidationIssues = (error: z.ZodError): RecipeValidationIssue[] =>\n  error.issues.map((issue) => ({\n    path: issue.path.join('.'),\n    message: issue.message,\n  }));\n\n/**\n * Validate an already-parsed recipe object against {@link GreengrassRecipeSchema},\n * returning every violation found rather than throwing on the first. Empty\n * when the recipe is valid.\n */\nexport const validateRecipe = (raw: unknown): RecipeValidationIssue[] => {\n  const result = GreengrassRecipeSchema.safeParse(raw);\n  return result.success ? [] : toValidationIssues(result.error);\n};\n\nexport interface ParsedRecipe {\n  /** The validated, typed view of the recipe. */\n  readonly recipe: GreengrassRecipe;\n  /** The unvalidated result of parsing the YAML, exactly as loaded. */\n  readonly raw: unknown;\n}\n\n/**\n * Parse a recipe YAML document and validate it, throwing when the fields the\n * plugin consumes are invalid. `raw` is the plain object `js-yaml` produced,\n * before validation; a caller that needs to rewrite the recipe (eg. to\n * substitute an artifact URI) mutates `raw` at the specific path and\n * re-serializes it with `yaml.dump`, so fields this module does not model are\n * never disturbed.\n */\nexport const parseRecipe = (yamlSource: string): ParsedRecipe => {\n  const raw = yaml.load(yamlSource);\n  const result = GreengrassRecipeSchema.safeParse(raw);\n\n  if (!result.success) {\n    const issues = toValidationIssues(result.error)\n      .map((issue) => `  - ${issue.path || '(root)'}: ${issue.message}`)\n      .join('\\n');\n    throw new Error(`Invalid Greengrass recipe:\\n${issues}`);\n  }\n\n  return { recipe: result.data as GreengrassRecipe, raw };\n};\n"],"names":["yaml","valid","validSemver","z","validateComponentName","NEXT_VERSION_SENTINELS","isNextVersionSentinel","value","includes","nextVersionStrategy","sentinel","isValidComponentVersion","Boolean","RecipePlatformSchema","looseObject","os","string","optional","architecture","RecipeArtifactSchema","Uri","LifecycleSchema","record","unknown","RecipeManifestSchema","Platform","Name","Lifecycle","Artifacts","array","Selections","ComponentConfigurationSchema","DefaultConfiguration","ComponentDependencyRequirementSchema","VersionRequirement","DependencyType","enum","ComponentDependenciesSchema","GreengrassRecipeSchema","RecipeFormatVersion","ComponentName","ComponentVersion","ComponentDescription","ComponentPublisher","ComponentConfiguration","ComponentDependencies","Manifests","superRefine","recipe","ctx","issue","addIssue","code","message","path","toValidationIssues","error","issues","map","join","validateRecipe","raw","result","safeParse","success","parseRecipe","yamlSource","load","Error","data"],"mappings":"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"}

package/src/utils/greengrass-constructs/files/cdk/app/greengrass-component/__componentDirName__.ts.template

@@ -0,0 +1,42 @@
+import * as url from 'url';
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import {
+  type GreengrassArtifactBucket,
+  GreengrassComponentVersion,
+} from '../../core/greengrass/index<% if (esm) { %>.js<% } %>';
+
+export interface <%- componentNameClassName %>Props {
+  /** The bucket this component version's artifact is uploaded to. */
+  readonly bucket: GreengrassArtifactBucket;
+
+  /**
+   * @default RemovalPolicy.RETAIN
+   */
+  readonly removalPolicy?: RemovalPolicy;
+}
+
+/**
+ * Publish "<%- componentDisplayName %>" from its <%- componentDirName %>-artifact build.
+ * Keep these paths aligned with the host project when editing this construct.
+ */
+export class <%- componentNameClassName %> extends GreengrassComponentVersion {
+  constructor(scope: Construct, id: string, props: <%- componentNameClassName %>Props) {
+    super(scope, id, {
+      recipesDir: url.fileURLToPath(
+        new URL(
+          '../../../../../../<%- recipesDirFromRoot %>',
+          <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
+        ),
+      ),
+      artifactsDir: url.fileURLToPath(
+        new URL(
+          '../../../../../../<%- artifactsDirFromRoot %>',
+          <% if (esm) { %>import.meta.url<% } else { %>require('url').pathToFileURL(__filename).href<% } %>,
+        ),
+      ),
+      bucket: props.bucket,
+      removalPolicy: props.removalPolicy,
+    });
+  }
+}

package/src/utils/greengrass-constructs/files/cdk/core/greengrass/artifact-bucket.ts.template

@@ -0,0 +1,82 @@
+import { RemovalPolicy, Tags } from 'aws-cdk-lib';
+import { Grant, type IGrantable } from 'aws-cdk-lib/aws-iam';
+import { suppressRules } from '../checkov<% if (esm) { %>.js<% } %>';
+import {
+  BlockPublicAccess,
+  Bucket,
+  BucketEncryption,
+  type IBucket,
+} from 'aws-cdk-lib/aws-s3';
+import { Construct } from 'constructs';
+
+export interface GreengrassArtifactBucketProps {
+  /**
+   * Physical name for a new bucket; ignored when importing a bucket.
+   */
+  readonly bucketName?: string;
+
+  /**
+   * Import a bucket with its existing encryption, versioning and access settings.
+   */
+  readonly existingBucketName?: string;
+
+  /**
+   * Retention for the created repository; ignored when importing a bucket.
+   * @default RemovalPolicy.RETAIN
+   */
+  readonly removalPolicy?: RemovalPolicy;
+}
+
+/**
+ * Own a retained, versioned, encrypted, TLS-only artifact repository.
+ * Import it into other stacks with existingBucketName.
+ */
+export class GreengrassArtifactBucket extends Construct {
+  public readonly bucket: IBucket;
+
+  constructor(
+    scope: Construct,
+    id: string,
+    props: GreengrassArtifactBucketProps = {},
+  ) {
+    super(scope, id);
+
+    if (props.existingBucketName) {
+      this.bucket = Bucket.fromBucketName(
+        this,
+        'ImportedBucket',
+        props.existingBucketName,
+      );
+      return;
+    }
+
+    this.bucket = new Bucket(this, 'Bucket', {
+      bucketName: props.bucketName,
+      versioned: true,
+      encryption: BucketEncryption.S3_MANAGED,
+      enforceSSL: true,
+      blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
+      removalPolicy: props.removalPolicy ?? RemovalPolicy.RETAIN,
+    });
+    suppressRules(
+      this.bucket,
+      ['CKV_AWS_18'],
+      'Server access logging would need a second retained log bucket; component artifacts are immutable published bytes and reads are auditable through CloudTrail data events',
+    );
+    // Mark retained repositories for inventory and deliberate cleanup.
+    Tags.of(this.bucket).add('greengrass-artifact-repository', 'true');
+    // Keep artifact keys until no published version needs them.
+  }
+
+  /**
+   * Grant artifact reads within keyPrefix, defaulting to the workspace namespace.
+   */
+  public grantReadTo(grantee: IGrantable, keyPrefix: string = '<%- componentKeyPrefix %>'): Grant {
+    return Grant.addToPrincipalOrResource({
+      grantee,
+      actions: ['s3:GetObject'],
+      resourceArns: [this.bucket.arnForObjects(keyPrefix)],
+      resource: this.bucket,
+    });
+  }
+}