@otwld/nx-argo 0.0.7 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/CHANGELOG.md +6 -3
  2. package/README.md +14 -13
  3. package/executors.json +34 -9
  4. package/package.json +1 -1
  5. package/src/executors/copy-image-lock/copy-image-lock.d.ts +5 -0
  6. package/src/executors/copy-image-lock/copy-image-lock.js +14 -0
  7. package/src/executors/copy-image-lock/schema.d.ts +19 -0
  8. package/src/executors/copy-image-lock/schema.json +48 -0
  9. package/src/executors/copy-source-revision/copy-source-revision.d.ts +5 -0
  10. package/src/executors/copy-source-revision/copy-source-revision.js +29 -0
  11. package/src/executors/copy-source-revision/schema.d.ts +19 -0
  12. package/src/executors/copy-source-revision/schema.json +41 -0
  13. package/src/executors/image-lock.d.ts +16 -0
  14. package/src/executors/image-lock.js +53 -0
  15. package/src/executors/set-source-revision/schema.d.ts +15 -0
  16. package/src/executors/set-source-revision/schema.json +28 -0
  17. package/src/executors/set-source-revision/set-source-revision.d.ts +5 -0
  18. package/src/executors/set-source-revision/set-source-revision.js +20 -0
  19. package/src/executors/shared.d.ts +28 -0
  20. package/src/executors/shared.js +112 -0
  21. package/src/executors/source-revision.d.ts +9 -0
  22. package/src/executors/source-revision.js +30 -0
  23. package/src/executors/validate-application/schema.d.ts +7 -0
  24. package/src/executors/validate-application/schema.json +19 -0
  25. package/src/executors/validate-application/validate-application.d.ts +5 -0
  26. package/src/executors/validate-application/validate-application.js +38 -0
  27. package/src/executors/validate-application-set/schema.d.ts +7 -0
  28. package/src/executors/validate-application-set/schema.json +20 -0
  29. package/src/executors/validate-application-set/validate-application-set.d.ts +5 -0
  30. package/src/executors/validate-application-set/validate-application-set.js +65 -0
  31. package/src/executors/validate-image-lock/schema.d.ts +15 -0
  32. package/src/executors/validate-image-lock/schema.json +36 -0
  33. package/src/executors/validate-image-lock/validate-image-lock.d.ts +5 -0
  34. package/src/executors/validate-image-lock/validate-image-lock.js +11 -0
  35. package/src/executors/{write-artifact-lock → write-image-lock}/schema.d.ts +5 -5
  36. package/src/executors/{write-artifact-lock → write-image-lock}/schema.json +10 -9
  37. package/src/executors/write-image-lock/write-image-lock.d.ts +5 -0
  38. package/src/executors/write-image-lock/write-image-lock.js +55 -0
  39. package/src/generators/environment-project/environment-project.d.ts +1 -1
  40. package/src/generators/environment-project/environment-project.js +56 -35
  41. package/src/generators/environment-project/schema.d.ts +11 -3
  42. package/src/generators/environment-project/schema.json +25 -7
  43. package/src/generators/preview-project/preview-project.d.ts +1 -1
  44. package/src/generators/preview-project/preview-project.js +16 -11
  45. package/src/generators/preview-project/schema.d.ts +6 -2
  46. package/src/generators/preview-project/schema.json +15 -7
  47. package/src/index.d.ts +14 -0
  48. package/src/index.js +15 -1
  49. package/src/executors/validate/schema.d.ts +0 -11
  50. package/src/executors/validate/schema.json +0 -28
  51. package/src/executors/validate/validate.d.ts +0 -5
  52. package/src/executors/validate/validate.js +0 -190
  53. package/src/executors/write-artifact-lock/write-artifact-lock.d.ts +0 -5
  54. package/src/executors/write-artifact-lock/write-artifact-lock.js +0 -168
package/CHANGELOG.md CHANGED
@@ -1,8 +1,11 @@
1
- ## 0.0.7 (unreleased)
1
+ ## 0.0.8 (2026-08-12)
2
2
 
3
- ### Fixes
3
+ ### Breaking changes
4
4
 
5
- - Require preview ApplicationSets to consume PR-scoped immutable locks last.
5
+ - Replace overloaded `validate` and `write-artifact-lock` with composable Application, ApplicationSet, image-lock, and source-revision executors.
6
+ - Make GitHub PR-preview rules an explicit `github-pr-preview` ApplicationSet policy instead of a default validation requirement.
7
+ - Replace `app` and `apps` generator options with optional generic `dependencies`; environment image locks and application files are opt-in.
8
+ - Rename environment boundaries around a generic required `name`, retaining required `service` metadata.
6
9
 
7
10
  ## 0.0.6 (2026-08-12)
8
11
 
package/README.md CHANGED
@@ -1,34 +1,35 @@
1
1
  # @otwld/nx-argo
2
2
 
3
- Nx contract tooling for GitOps projects. It does not create or operate Argo CD resources.
3
+ Nx contract tooling for generic Argo CD project boundaries. It does not create or operate Argo CD resources.
4
4
 
5
5
  ## Generators
6
6
 
7
- `environment-project` creates `gitops/environments/<service>/<environment>` with:
8
-
9
- - `project.json`: `gitops-<service>-<environment>`, one owning app dependency, delivery metadata, validation, and uncached artifact writes.
10
- - `values.yaml`: human-owned configuration.
11
- - `artifacts.yaml`: automation-owned immutable artifact lock.
7
+ `environment-project` creates `gitops/environments/<name>/<environment>` with `values.yaml`, generic delivery metadata, and deduplicated `dependencies` plus an optional `chartProject`. `service` remains a required deployment identity. It only creates `artifacts.yaml`, `validate-image-lock`, and `write-image-lock` when `imageLock` is true; it only declares `validate-application` when `applicationFile` is supplied.
12
8
 
13
9
  ```shell
14
- pnpm exec nx g @otwld/nx-argo:environment-project frontend \
15
- --environment=staging --app=frontend
10
+ pnpm exec nx g @otwld/nx-argo:environment-project web \
11
+ --service=frontend --environment=staging --dependencies=frontend,web-chart \
12
+ --imageLock --applicationFile=application.yaml
16
13
  ```
17
14
 
18
- `preview-project` creates `gitops/previews/<name>/project.json` with explicit app dependencies and `delivery.previewStack`. It creates no PR-specific lock. Add `application-set.yaml` before running validation.
15
+ `preview-project` creates `gitops/previews/<name>/project.json` with optional `dependencies`, generic preview metadata, and `validate-application-set`. `applicationSetFile` defaults to `application-set.yaml`. The optional `github-pr-preview` policy is the only GitHub-specific behavior.
19
16
 
20
17
  ```shell
21
18
  pnpm exec nx g @otwld/nx-argo:preview-project web \
22
- --apps=frontend,backend
19
+ --dependencies=frontend,backend --policy=github-pr-preview
23
20
  ```
24
21
 
25
22
  ## Contracts
26
23
 
27
- Environment validation accepts either a pending or completed `artifacts.yaml`. A pending lock has `artifact.pending: true` and exactly empty string values for `image.repository`, `image.digest`, `artifact.service`, and `artifact.sourceRevision`. A completed lock has `artifact.pending: false` (or no pending field), a nonempty repository/service/source revision, and an immutable digest. An optional `application.yaml` must be an Argo CD `Application`; when it declares Helm value files, `artifacts.yaml` is last.
24
+ `validate-application` validates Application kind and spec. Its optional `finalValueFile` requires that basename to end each declared Helm `valueFiles` list; image locks are never implied.
25
+
26
+ `validate-application-set` validates ApplicationSet kind, spec, template, and template spec. By default it imposes no provider rules. With `policy: github-pr-preview`, it also requires a pull request generator, literal template project, automated `enabled`, `prune`, and `selfHeal`, no `preserveResourcesOnDeletion`, and a PR lock as the final Helm values file.
27
+
28
+ `validate-image-lock` uses canonical `image.repository`, `image.digest`, `artifact.service`, and `artifact.sourceRevision` paths unless mappings are supplied. `write-image-lock` requires explicit mapping paths. A pending lock contains exactly empty values; a completed lock has a nonempty repository, service, source revision, and SHA-256 digest. Writes require an existing project-local file, complete valid pending locks, and are idempotent for identical source-revision values.
28
29
 
29
- Preview validation requires an Argo CD `ApplicationSet` at `application-set.yaml`, a PR generator, a literal nonempty template project, enabled automated sync with `prune` and `selfHeal`, and no `preserveResourcesOnDeletion`.
30
+ `copy-image-lock` validates the completed source lock before writing the explicit destination file. `set-source-revision` and `copy-source-revision` identify exactly one Application source by required `repoURL` plus at least one of `chart`, `path`, or `ref`; neither accepts numeric source indexes.
30
31
 
31
- `write-artifact-lock` requires an existing project-local lock and accepts image repository/digest plus service/source revision values. It converts a valid pending lock to `artifact.pending: false`, advances a new revision, and only verifies identical service, repository, and digest for an existing revision.
32
+ All executor file options are explicitly project-relative and reject path escapes.
32
33
 
33
34
  ## Package Targets
34
35
 
package/executors.json CHANGED
@@ -1,15 +1,40 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/schema",
3
3
  "executors": {
4
- "validate": {
5
- "implementation": "./src/executors/validate/validate",
6
- "schema": "./src/executors/validate/schema.json",
7
- "description": "Validate an Argo CD Application and declared artifact lock files."
8
- },
9
- "write-artifact-lock": {
10
- "implementation": "./src/executors/write-artifact-lock/write-artifact-lock",
11
- "schema": "./src/executors/write-artifact-lock/schema.json",
12
- "description": "Write an immutable image reference to a declared artifact lock file."
4
+ "validate-application": {
5
+ "implementation": "./src/executors/validate-application/validate-application",
6
+ "schema": "./src/executors/validate-application/schema.json",
7
+ "description": "Validate an Argo CD Application manifest."
8
+ },
9
+ "validate-application-set": {
10
+ "implementation": "./src/executors/validate-application-set/validate-application-set",
11
+ "schema": "./src/executors/validate-application-set/schema.json",
12
+ "description": "Validate an Argo CD ApplicationSet manifest and optional policy."
13
+ },
14
+ "validate-image-lock": {
15
+ "implementation": "./src/executors/validate-image-lock/validate-image-lock",
16
+ "schema": "./src/executors/validate-image-lock/schema.json",
17
+ "description": "Validate a pending or completed image lock."
18
+ },
19
+ "write-image-lock": {
20
+ "implementation": "./src/executors/write-image-lock/write-image-lock",
21
+ "schema": "./src/executors/write-image-lock/schema.json",
22
+ "description": "Write or verify an immutable image lock."
23
+ },
24
+ "copy-image-lock": {
25
+ "implementation": "./src/executors/copy-image-lock/copy-image-lock",
26
+ "schema": "./src/executors/copy-image-lock/schema.json",
27
+ "description": "Copy a completed image lock between Nx projects."
28
+ },
29
+ "set-source-revision": {
30
+ "implementation": "./src/executors/set-source-revision/set-source-revision",
31
+ "schema": "./src/executors/set-source-revision/schema.json",
32
+ "description": "Set targetRevision for one selected Application source."
33
+ },
34
+ "copy-source-revision": {
35
+ "implementation": "./src/executors/copy-source-revision/copy-source-revision",
36
+ "schema": "./src/executors/copy-source-revision/schema.json",
37
+ "description": "Copy a selected Application source revision between Nx projects."
13
38
  }
14
39
  }
15
40
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@otwld/nx-argo",
3
- "version": "0.0.7",
3
+ "version": "0.0.8",
4
4
  "private": false,
5
5
  "type": "commonjs",
6
6
  "exports": {
@@ -0,0 +1,5 @@
1
+ import type { PromiseExecutor } from '@nx/devkit';
2
+ import type { CopyImageLockExecutorSchema } from './schema';
3
+ /** Copies a completed image lock between explicitly named Nx project files. */
4
+ declare const runExecutor: PromiseExecutor<CopyImageLockExecutorSchema>;
5
+ export default runExecutor;
@@ -0,0 +1,14 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const image_lock_1 = require("../image-lock");
4
+ const shared_1 = require("../shared");
5
+ /** Copies a completed image lock between explicitly named Nx project files. */
6
+ const runExecutor = async (options, context) => {
7
+ const sourcePath = (0, shared_1.resolveProjectFile)((0, shared_1.getProjectRoot)(context, options.sourceProject), options.sourceFile, 'Source image lock file');
8
+ const destinationPath = (0, shared_1.resolveProjectFile)((0, shared_1.getProjectRoot)(context, options.destinationProject), options.destinationFile, 'Destination image lock file');
9
+ const source = (0, shared_1.readYamlMapping)(sourcePath, 'source image lock');
10
+ (0, image_lock_1.validateImageLock)(source, (0, image_lock_1.getImageLockPaths)(options), sourcePath, false);
11
+ (0, shared_1.writeYamlMapping)(destinationPath, source);
12
+ return { success: true };
13
+ };
14
+ exports.default = runExecutor;
@@ -0,0 +1,19 @@
1
+ /** Options accepted by the image-lock copier. */
2
+ export interface CopyImageLockExecutorSchema {
3
+ /** Nx project containing the source lock. */
4
+ sourceProject: string;
5
+ /** Source lock file relative to sourceProject. */
6
+ sourceFile: string;
7
+ /** Nx project containing the destination lock. */
8
+ destinationProject: string;
9
+ /** Destination lock file relative to destinationProject. */
10
+ destinationFile: string;
11
+ /** Optional repository YAML path. */
12
+ repositoryPath?: string;
13
+ /** Optional digest YAML path. */
14
+ digestPath?: string;
15
+ /** Optional service YAML path. */
16
+ servicePath?: string;
17
+ /** Optional source revision YAML path. */
18
+ sourceRevisionPath?: string;
19
+ }
@@ -0,0 +1,48 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "version": 2,
4
+ "title": "Copy image lock",
5
+ "description": "Copy a completed image lock between explicitly named Nx project files.",
6
+ "type": "object",
7
+ "properties": {
8
+ "sourceProject": {
9
+ "type": "string",
10
+ "description": "Nx project containing the source lock."
11
+ },
12
+ "sourceFile": {
13
+ "type": "string",
14
+ "description": "Source lock file relative to sourceProject."
15
+ },
16
+ "destinationProject": {
17
+ "type": "string",
18
+ "description": "Nx project containing the destination lock."
19
+ },
20
+ "destinationFile": {
21
+ "type": "string",
22
+ "description": "Destination lock file relative to destinationProject."
23
+ },
24
+ "repositoryPath": {
25
+ "type": "string",
26
+ "description": "Optional repository YAML path."
27
+ },
28
+ "digestPath": {
29
+ "type": "string",
30
+ "description": "Optional digest YAML path."
31
+ },
32
+ "servicePath": {
33
+ "type": "string",
34
+ "description": "Optional service YAML path."
35
+ },
36
+ "sourceRevisionPath": {
37
+ "type": "string",
38
+ "description": "Optional source revision YAML path."
39
+ }
40
+ },
41
+ "required": [
42
+ "sourceProject",
43
+ "sourceFile",
44
+ "destinationProject",
45
+ "destinationFile"
46
+ ],
47
+ "additionalProperties": false
48
+ }
@@ -0,0 +1,5 @@
1
+ import type { PromiseExecutor } from '@nx/devkit';
2
+ import type { CopySourceRevisionExecutorSchema } from './schema';
3
+ /** Copies a selected Application source revision between two project-local files. */
4
+ declare const runExecutor: PromiseExecutor<CopySourceRevisionExecutorSchema>;
5
+ export default runExecutor;
@@ -0,0 +1,29 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const shared_1 = require("../shared");
4
+ const source_revision_1 = require("../source-revision");
5
+ /** Copies a selected Application source revision between two project-local files. */
6
+ const runExecutor = async (options, context) => {
7
+ const sourcePath = (0, shared_1.resolveProjectFile)((0, shared_1.getProjectRoot)(context, options.sourceProject), options.sourceFile, 'Source Application file');
8
+ const destinationPath = (0, shared_1.resolveProjectFile)((0, shared_1.getProjectRoot)(context, options.destinationProject), options.destinationFile, 'Destination Application file');
9
+ const sourceApplication = readApplication(sourcePath, 'source');
10
+ const source = (0, source_revision_1.selectSource)(sourceApplication, options);
11
+ if (!(0, shared_1.isNonEmptyString)(source['targetRevision'])) {
12
+ throw new Error('[nx-argo] The selected source targetRevision must be a nonempty string.');
13
+ }
14
+ const destinationApplication = readApplication(destinationPath, 'destination');
15
+ (0, source_revision_1.selectSource)(destinationApplication, options)['targetRevision'] =
16
+ source['targetRevision'];
17
+ (0, shared_1.writeYamlMapping)(destinationPath, destinationApplication);
18
+ return { success: true };
19
+ };
20
+ /** Reads an Application document for source revision copying. */
21
+ function readApplication(filePath, label) {
22
+ const application = (0, shared_1.readYamlMapping)(filePath, `${label} Argo CD Application`);
23
+ if (application['apiVersion'] !== 'argoproj.io/v1alpha1' ||
24
+ application['kind'] !== 'Application') {
25
+ throw new Error(`[nx-argo] Invalid ${label} Argo CD Application: ${filePath}`);
26
+ }
27
+ return application;
28
+ }
29
+ exports.default = runExecutor;
@@ -0,0 +1,19 @@
1
+ /** Options accepted by the Application source-revision copier. */
2
+ export interface CopySourceRevisionExecutorSchema {
3
+ /** Nx project containing the source Application. */
4
+ sourceProject: string;
5
+ /** Source Application file relative to sourceProject. */
6
+ sourceFile: string;
7
+ /** Nx project containing the destination Application. */
8
+ destinationProject: string;
9
+ /** Destination Application file relative to destinationProject. */
10
+ destinationFile: string;
11
+ /** Repository URL of the source to copy. */
12
+ repoURL: string;
13
+ /** Optional chart selector. */
14
+ chart?: string;
15
+ /** Optional path selector. */
16
+ path?: string;
17
+ /** Optional ref selector. */
18
+ ref?: string;
19
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "version": 2,
4
+ "title": "Copy Application source revision",
5
+ "description": "Copy targetRevision for an exactly selected Application source.",
6
+ "type": "object",
7
+ "properties": {
8
+ "sourceProject": {
9
+ "type": "string",
10
+ "description": "Nx project containing the source Application."
11
+ },
12
+ "sourceFile": {
13
+ "type": "string",
14
+ "description": "Source Application file relative to sourceProject."
15
+ },
16
+ "destinationProject": {
17
+ "type": "string",
18
+ "description": "Nx project containing the destination Application."
19
+ },
20
+ "destinationFile": {
21
+ "type": "string",
22
+ "description": "Destination Application file relative to destinationProject."
23
+ },
24
+ "repoURL": {
25
+ "type": "string",
26
+ "minLength": 1,
27
+ "description": "Repository URL of the source to copy."
28
+ },
29
+ "chart": { "type": "string", "description": "Optional chart selector." },
30
+ "path": { "type": "string", "description": "Optional path selector." },
31
+ "ref": { "type": "string", "description": "Optional ref selector." }
32
+ },
33
+ "required": [
34
+ "sourceProject",
35
+ "sourceFile",
36
+ "destinationProject",
37
+ "destinationFile",
38
+ "repoURL"
39
+ ],
40
+ "additionalProperties": false
41
+ }
@@ -0,0 +1,16 @@
1
+ /** Configurable YAML mappings for the four canonical image-lock values. */
2
+ export interface ImageLockPaths {
3
+ repository: string[];
4
+ digest: string[];
5
+ service: string[];
6
+ sourceRevision: string[];
7
+ }
8
+ /** Builds image-lock mappings from explicit options or canonical defaults. */
9
+ export declare function getImageLockPaths(options: {
10
+ repositoryPath?: string;
11
+ digestPath?: string;
12
+ servicePath?: string;
13
+ sourceRevisionPath?: string;
14
+ }): ImageLockPaths;
15
+ /** Validates a pending or complete canonical image lock. */
16
+ export declare function validateImageLock(lock: Record<string, unknown>, paths: ImageLockPaths, filePath: string, allowPending?: boolean): void;
@@ -0,0 +1,53 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.getImageLockPaths = getImageLockPaths;
4
+ exports.validateImageLock = validateImageLock;
5
+ const shared_1 = require("./shared");
6
+ /** Builds image-lock mappings from explicit options or canonical defaults. */
7
+ function getImageLockPaths(options) {
8
+ const paths = {
9
+ repository: (0, shared_1.parsePath)(options.repositoryPath ?? shared_1.canonicalImageLockPaths.repository),
10
+ digest: (0, shared_1.parsePath)(options.digestPath ?? shared_1.canonicalImageLockPaths.digest),
11
+ service: (0, shared_1.parsePath)(options.servicePath ?? shared_1.canonicalImageLockPaths.service),
12
+ sourceRevision: (0, shared_1.parsePath)(options.sourceRevisionPath ?? shared_1.canonicalImageLockPaths.sourceRevision),
13
+ };
14
+ assertDistinctPaths(paths);
15
+ return paths;
16
+ }
17
+ /** Validates a pending or complete canonical image lock. */
18
+ function validateImageLock(lock, paths, filePath, allowPending = true) {
19
+ const pending = (0, shared_1.getPath)(lock, ['artifact', 'pending']);
20
+ const values = [
21
+ (0, shared_1.getPath)(lock, paths.repository),
22
+ (0, shared_1.getPath)(lock, paths.digest),
23
+ (0, shared_1.getPath)(lock, paths.service),
24
+ (0, shared_1.getPath)(lock, paths.sourceRevision),
25
+ ];
26
+ if (pending === true) {
27
+ if (allowPending && values.every((value) => value === '')) {
28
+ return;
29
+ }
30
+ throw new Error(`[nx-argo] Invalid pending image lock: ${filePath}`);
31
+ }
32
+ if (pending !== undefined && pending !== false) {
33
+ throw new Error(`[nx-argo] Invalid image lock: ${filePath}`);
34
+ }
35
+ if (!(0, shared_1.isNonEmptyString)(values[0]) ||
36
+ !(0, shared_1.isDigest)(values[1]) ||
37
+ !(0, shared_1.isNonEmptyString)(values[2]) ||
38
+ !(0, shared_1.isNonEmptyString)(values[3])) {
39
+ throw new Error(`[nx-argo] Invalid image lock: ${filePath}`);
40
+ }
41
+ }
42
+ /** Rejects equal or overlapping mappings before writes can corrupt a lock. */
43
+ function assertDistinctPaths(paths) {
44
+ const entries = Object.entries(paths);
45
+ for (const [index, [name, path]] of entries.entries()) {
46
+ for (const [otherName, otherPath] of entries.slice(index + 1)) {
47
+ if (path.every((segment, pathIndex) => otherPath[pathIndex] === segment) ||
48
+ otherPath.every((segment, pathIndex) => path[pathIndex] === segment)) {
49
+ throw new Error(`[nx-argo] Image-lock mapping paths conflict: ${name} and ${otherName}.`);
50
+ }
51
+ }
52
+ }
53
+ }
@@ -0,0 +1,15 @@
1
+ /** Options accepted by the Application source-revision writer. */
2
+ export interface SetSourceRevisionExecutorSchema {
3
+ /** Application manifest relative to the owning Nx project root. */
4
+ file: string;
5
+ /** Repository URL of the source to update. */
6
+ repoURL: string;
7
+ /** Optional chart selector. */
8
+ chart?: string;
9
+ /** Optional path selector. */
10
+ path?: string;
11
+ /** Optional ref selector. */
12
+ ref?: string;
13
+ /** Revision to set. */
14
+ targetRevision: string;
15
+ }
@@ -0,0 +1,28 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "version": 2,
4
+ "title": "Set Application source revision",
5
+ "description": "Set targetRevision for exactly one selected Application source.",
6
+ "type": "object",
7
+ "properties": {
8
+ "file": {
9
+ "type": "string",
10
+ "description": "Application manifest relative to the owning Nx project root."
11
+ },
12
+ "repoURL": {
13
+ "type": "string",
14
+ "minLength": 1,
15
+ "description": "Repository URL of the source to update."
16
+ },
17
+ "chart": { "type": "string", "description": "Optional chart selector." },
18
+ "path": { "type": "string", "description": "Optional path selector." },
19
+ "ref": { "type": "string", "description": "Optional ref selector." },
20
+ "targetRevision": {
21
+ "type": "string",
22
+ "minLength": 1,
23
+ "description": "Revision to set."
24
+ }
25
+ },
26
+ "required": ["file", "repoURL", "targetRevision"],
27
+ "additionalProperties": false
28
+ }
@@ -0,0 +1,5 @@
1
+ import type { PromiseExecutor } from '@nx/devkit';
2
+ import type { SetSourceRevisionExecutorSchema } from './schema';
3
+ /** Sets targetRevision for the Application source identified by stable fields. */
4
+ declare const runExecutor: PromiseExecutor<SetSourceRevisionExecutorSchema>;
5
+ export default runExecutor;
@@ -0,0 +1,20 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const shared_1 = require("../shared");
4
+ const source_revision_1 = require("../source-revision");
5
+ /** Sets targetRevision for the Application source identified by stable fields. */
6
+ const runExecutor = async (options, context) => {
7
+ if (!options.targetRevision.trim()) {
8
+ throw new Error('[nx-argo] targetRevision is required.');
9
+ }
10
+ const filePath = (0, shared_1.resolveProjectFile)((0, shared_1.getProjectRoot)(context), options.file, 'Application file');
11
+ const application = (0, shared_1.readYamlMapping)(filePath, 'Argo CD Application');
12
+ if (application['apiVersion'] !== 'argoproj.io/v1alpha1' ||
13
+ application['kind'] !== 'Application') {
14
+ throw new Error(`[nx-argo] Invalid Argo CD Application: ${filePath}`);
15
+ }
16
+ (0, source_revision_1.selectSource)(application, options)['targetRevision'] = options.targetRevision;
17
+ (0, shared_1.writeYamlMapping)(filePath, application);
18
+ return { success: true };
19
+ };
20
+ exports.default = runExecutor;
@@ -0,0 +1,28 @@
1
+ import type { ExecutorContext } from '@nx/devkit';
2
+ /** Canonical image-lock paths used when a validator or copier omits mappings. */
3
+ export declare const canonicalImageLockPaths: {
4
+ readonly repository: "image.repository";
5
+ readonly digest: "image.digest";
6
+ readonly service: "artifact.service";
7
+ readonly sourceRevision: "artifact.sourceRevision";
8
+ };
9
+ /** Resolves a project root from an executor context. */
10
+ export declare function getProjectRoot(context: ExecutorContext, project?: string): string;
11
+ /** Resolves a required project-local file without permitting path escapes. */
12
+ export declare function resolveProjectFile(root: string, file: string | undefined, optionName: string): string;
13
+ /** Reads an existing YAML mapping with a domain-specific error label. */
14
+ export declare function readYamlMapping(filePath: string, label: string): Record<string, unknown>;
15
+ /** Writes a YAML mapping using the package's stable formatting. */
16
+ export declare function writeYamlMapping(filePath: string, value: Record<string, unknown>): void;
17
+ /** Narrows a YAML value to a simple mapping. */
18
+ export declare function isMap(value: unknown): value is Record<string, unknown>;
19
+ /** Reads a nested mapping path without coercing malformed values. */
20
+ export declare function getPath(root: Record<string, unknown>, path: string[]): unknown;
21
+ /** Parses a dot-separated mapping path. */
22
+ export declare function parsePath(path: string, label?: string): string[];
23
+ /** Sets a mapping path and rejects scalar conflicts on the route. */
24
+ export declare function setPath(root: Record<string, unknown>, segments: string[], value: unknown): void;
25
+ /** Requires a nonempty string scalar. */
26
+ export declare function isNonEmptyString(value: unknown): value is string;
27
+ /** Validates an immutable SHA-256 image digest. */
28
+ export declare function isDigest(value: unknown): value is string;
@@ -0,0 +1,112 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.canonicalImageLockPaths = void 0;
4
+ exports.getProjectRoot = getProjectRoot;
5
+ exports.resolveProjectFile = resolveProjectFile;
6
+ exports.readYamlMapping = readYamlMapping;
7
+ exports.writeYamlMapping = writeYamlMapping;
8
+ exports.isMap = isMap;
9
+ exports.getPath = getPath;
10
+ exports.parsePath = parsePath;
11
+ exports.setPath = setPath;
12
+ exports.isNonEmptyString = isNonEmptyString;
13
+ exports.isDigest = isDigest;
14
+ const node_fs_1 = require("node:fs");
15
+ const node_path_1 = require("node:path");
16
+ const yaml_1 = require("yaml");
17
+ /** Canonical image-lock paths used when a validator or copier omits mappings. */
18
+ exports.canonicalImageLockPaths = {
19
+ repository: 'image.repository',
20
+ digest: 'image.digest',
21
+ service: 'artifact.service',
22
+ sourceRevision: 'artifact.sourceRevision',
23
+ };
24
+ /** Resolves a project root from an executor context. */
25
+ function getProjectRoot(context, project) {
26
+ const projectName = project ?? context.projectName;
27
+ const projectRoot = projectName
28
+ ? context.projectsConfigurations?.projects[projectName]?.root
29
+ : undefined;
30
+ if (!projectRoot) {
31
+ throw new Error('[nx-argo] The referenced Nx project does not exist.');
32
+ }
33
+ return (0, node_path_1.resolve)(context.root, projectRoot);
34
+ }
35
+ /** Resolves a required project-local file without permitting path escapes. */
36
+ function resolveProjectFile(root, file, optionName) {
37
+ if (!file?.trim() ||
38
+ (0, node_path_1.isAbsolute)(file) ||
39
+ file.split(/[\\/]+/).includes('..')) {
40
+ throw new Error(`[nx-argo] ${optionName} must stay within the project root.`);
41
+ }
42
+ const filePath = (0, node_path_1.resolve)(root, file);
43
+ const pathFromRoot = (0, node_path_1.relative)(root, filePath);
44
+ if (!pathFromRoot ||
45
+ pathFromRoot === '..' ||
46
+ pathFromRoot.startsWith(`..${node_path_1.sep}`) ||
47
+ (0, node_path_1.isAbsolute)(pathFromRoot)) {
48
+ throw new Error(`[nx-argo] ${optionName} must stay within the project root.`);
49
+ }
50
+ return filePath;
51
+ }
52
+ /** Reads an existing YAML mapping with a domain-specific error label. */
53
+ function readYamlMapping(filePath, label) {
54
+ if (!(0, node_fs_1.existsSync)(filePath)) {
55
+ throw new Error(`[nx-argo] Required ${label} is missing: ${filePath}`);
56
+ }
57
+ const document = (0, yaml_1.parseDocument)((0, node_fs_1.readFileSync)(filePath, 'utf8'));
58
+ if (document.errors.length || !isMap(document.toJS())) {
59
+ throw new Error(`[nx-argo] Invalid ${label}: ${filePath}`);
60
+ }
61
+ return document.toJS();
62
+ }
63
+ /** Writes a YAML mapping using the package's stable formatting. */
64
+ function writeYamlMapping(filePath, value) {
65
+ (0, node_fs_1.writeFileSync)(filePath, (0, yaml_1.stringify)(value, { lineWidth: 0 }));
66
+ }
67
+ /** Narrows a YAML value to a simple mapping. */
68
+ function isMap(value) {
69
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
70
+ }
71
+ /** Reads a nested mapping path without coercing malformed values. */
72
+ function getPath(root, path) {
73
+ let current = root;
74
+ for (const segment of path) {
75
+ if (!isMap(current)) {
76
+ return undefined;
77
+ }
78
+ current = current[segment];
79
+ }
80
+ return current;
81
+ }
82
+ /** Parses a dot-separated mapping path. */
83
+ function parsePath(path, label = 'mapping path') {
84
+ const segments = path.split('.');
85
+ if (segments.some((segment) => !segment.trim())) {
86
+ throw new Error(`[nx-argo] ${label} must not contain empty segments.`);
87
+ }
88
+ return segments;
89
+ }
90
+ /** Sets a mapping path and rejects scalar conflicts on the route. */
91
+ function setPath(root, segments, value) {
92
+ let current = root;
93
+ for (const segment of segments.slice(0, -1)) {
94
+ const child = current[segment];
95
+ if (child === undefined) {
96
+ current[segment] = {};
97
+ }
98
+ else if (!isMap(child)) {
99
+ throw new Error(`[nx-argo] Mapping path conflicts at ${segment}.`);
100
+ }
101
+ current = current[segment];
102
+ }
103
+ current[segments.at(-1)] = value;
104
+ }
105
+ /** Requires a nonempty string scalar. */
106
+ function isNonEmptyString(value) {
107
+ return typeof value === 'string' && Boolean(value.trim());
108
+ }
109
+ /** Validates an immutable SHA-256 image digest. */
110
+ function isDigest(value) {
111
+ return typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
112
+ }
@@ -0,0 +1,9 @@
1
+ /** Identifies an Application source without relying on array positions. */
2
+ export interface SourceSelector {
3
+ repoURL: string;
4
+ chart?: string;
5
+ path?: string;
6
+ ref?: string;
7
+ }
8
+ /** Finds exactly one matching source in an Application spec. */
9
+ export declare function selectSource(application: Record<string, unknown>, selector: SourceSelector): Record<string, unknown>;