@otwld/nx-argo 0.0.4 → 0.0.5

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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,13 @@
1
+ ## 0.0.4 (2026-08-12)
2
+
3
+ ### 🚀 Features
4
+
5
+ - **plugins:** add nx helm and argo plugins ([eb30b828](https://github.com/otwld/devops/commit/eb30b828))
6
+
7
+ ### ❤️ Thank You
8
+
9
+ - Tréhout Nathan
10
+
1
11
  ## 0.0.3 (2026-08-12)
2
12
 
3
13
  ### 🚀 Features
package/README.md CHANGED
@@ -2,6 +2,33 @@
2
2
 
3
3
  Nx generator for Argo CD Applications and Helm values files.
4
4
 
5
+ ## GitOps Projects
6
+
7
+ `service-application` creates a GitOps project for one workload and
8
+ environment. It records the deployment service key, depends only on its owning
9
+ app, and creates separate human-owned `values.yaml` and automation-owned
10
+ `artifacts.yaml` files.
11
+
12
+ ```shell
13
+ pnpm exec nx g @otwld/nx-argo:service-application frontend \
14
+ --environment=staging \
15
+ --app=frontend
16
+ ```
17
+
18
+ `preview-stack` creates an explicit multi-workload preview boundary. The
19
+ declared apps are the only Nx dependencies; Argo CD resources remain entirely
20
+ user-defined.
21
+
22
+ ```shell
23
+ pnpm exec nx g @otwld/nx-argo:preview-stack web \
24
+ --apps=frontend,backend
25
+ ```
26
+
27
+ Generated GitOps projects use `validate` and `write-artifact-lock` targets.
28
+ The latter writes one immutable image repository and digest to paths declared
29
+ by project metadata. It does not publish images, invoke Argo CD, or interpret
30
+ Kubernetes resources.
31
+
5
32
  ## Generate an Application
6
33
 
7
34
  ```shell
package/executors.json ADDED
@@ -0,0 +1,15 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
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."
13
+ }
14
+ }
15
+ }
package/generators.json CHANGED
@@ -5,6 +5,16 @@
5
5
  "factory": "./src/generators/application/application",
6
6
  "schema": "./src/generators/application/schema.json",
7
7
  "description": "Create an Argo CD Application and its Helm values file."
8
+ },
9
+ "service-application": {
10
+ "factory": "./src/generators/service-application/service-application",
11
+ "schema": "./src/generators/service-application/schema.json",
12
+ "description": "Create a GitOps Application project for one workload."
13
+ },
14
+ "preview-stack": {
15
+ "factory": "./src/generators/preview-stack/preview-stack",
16
+ "schema": "./src/generators/preview-stack/schema.json",
17
+ "description": "Create a GitOps preview stack project for multiple workloads."
8
18
  }
9
19
  }
10
20
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@otwld/nx-argo",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "private": false,
5
5
  "type": "commonjs",
6
6
  "exports": {
@@ -10,7 +10,8 @@
10
10
  "default": "./src/index.js"
11
11
  },
12
12
  "./package.json": "./package.json",
13
- "./generators.json": "./generators.json"
13
+ "./generators.json": "./generators.json",
14
+ "./executors.json": "./executors.json"
14
15
  },
15
16
  "main": "./src/index.js",
16
17
  "types": "./src/index.d.ts",
@@ -26,5 +27,6 @@
26
27
  "publishConfig": {
27
28
  "access": "public"
28
29
  },
29
- "generators": "./generators.json"
30
+ "generators": "./generators.json",
31
+ "executors": "./executors.json"
30
32
  }
@@ -0,0 +1,7 @@
1
+ /** Options accepted by the Argo CD validation executor. */
2
+ export interface ValidateExecutorSchema {
3
+ /** Application manifest relative to the owning Nx project root. */
4
+ applicationFile?: string;
5
+ /** Artifact lock file relative to the owning Nx project root. */
6
+ artifactsFile?: string;
7
+ }
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "version": 2,
4
+ "title": "Validate Argo CD configuration",
5
+ "description": "Validate optional Argo CD Application and artifact lock files.",
6
+ "type": "object",
7
+ "properties": {
8
+ "applicationFile": {
9
+ "type": "string",
10
+ "description": "Application manifest relative to the owning Nx project root."
11
+ },
12
+ "artifactsFile": {
13
+ "type": "string",
14
+ "description": "Artifact lock file relative to the owning Nx project root."
15
+ }
16
+ }
17
+ }
@@ -0,0 +1,5 @@
1
+ import type { PromiseExecutor } from '@nx/devkit';
2
+ import type { ValidateExecutorSchema } from './schema';
3
+ /** Validates optional Argo CD Application and artifact lock documents. */
4
+ declare const runExecutor: PromiseExecutor<ValidateExecutorSchema>;
5
+ export default runExecutor;
@@ -0,0 +1,40 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const node_fs_1 = require("node:fs");
4
+ const node_path_1 = require("node:path");
5
+ const yaml_1 = require("yaml");
6
+ /** Validates optional Argo CD Application and artifact lock documents. */
7
+ const runExecutor = async (options, context) => {
8
+ const projectRoot = context.projectsConfigurations?.projects[context.projectName ?? '']?.root;
9
+ if (!projectRoot) {
10
+ throw new Error('[nx-argo] Validation requires an Nx project context.');
11
+ }
12
+ const root = (0, node_path_1.resolve)(context.root, projectRoot);
13
+ validateApplication((0, node_path_1.resolve)(root, options.applicationFile || 'application.yaml'));
14
+ validateArtifacts((0, node_path_1.resolve)(root, options.artifactsFile || 'artifacts.yaml'));
15
+ return { success: true };
16
+ };
17
+ /** Validates an Application document when it is present. */
18
+ function validateApplication(filePath) {
19
+ if (!(0, node_fs_1.existsSync)(filePath)) {
20
+ return;
21
+ }
22
+ const document = (0, yaml_1.parseDocument)((0, node_fs_1.readFileSync)(filePath, 'utf8'));
23
+ if (document.errors.length ||
24
+ document.get('apiVersion') !== 'argoproj.io/v1alpha1' ||
25
+ document.get('kind') !== 'Application') {
26
+ throw new Error(`[nx-argo] Invalid Argo CD Application: ${filePath}`);
27
+ }
28
+ }
29
+ /** Validates that an artifact lock is a YAML mapping when it is present. */
30
+ function validateArtifacts(filePath) {
31
+ if (!(0, node_fs_1.existsSync)(filePath)) {
32
+ return;
33
+ }
34
+ const document = (0, yaml_1.parseDocument)((0, node_fs_1.readFileSync)(filePath, 'utf8'));
35
+ if (document.errors.length ||
36
+ (document.contents && !(0, yaml_1.isMap)(document.contents))) {
37
+ throw new Error(`[nx-argo] Invalid artifact lock: ${filePath}`);
38
+ }
39
+ }
40
+ exports.default = runExecutor;
@@ -0,0 +1,13 @@
1
+ /** Options accepted by the artifact lock writer executor. */
2
+ export interface WriteArtifactLockExecutorSchema {
3
+ /** Artifact lock file relative to the owning Nx project root. */
4
+ file: string;
5
+ /** Dot-separated YAML path for the image repository. */
6
+ repositoryPath: string;
7
+ /** Dot-separated YAML path for the immutable image digest. */
8
+ digestPath: string;
9
+ /** Image repository to write. */
10
+ repository: string;
11
+ /** Immutable image digest to write. */
12
+ digest: string;
13
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "version": 2,
4
+ "title": "Write artifact lock",
5
+ "description": "Write one immutable image reference to a declared YAML lock file.",
6
+ "type": "object",
7
+ "properties": {
8
+ "file": {
9
+ "type": "string",
10
+ "description": "Artifact lock file relative to the owning Nx project root."
11
+ },
12
+ "repositoryPath": {
13
+ "type": "string",
14
+ "description": "Dot-separated YAML path for the image repository."
15
+ },
16
+ "digestPath": {
17
+ "type": "string",
18
+ "description": "Dot-separated YAML path for the immutable image digest."
19
+ },
20
+ "repository": {
21
+ "type": "string",
22
+ "description": "Image repository to write."
23
+ },
24
+ "digest": {
25
+ "type": "string",
26
+ "description": "Immutable image digest to write.",
27
+ "pattern": "^sha256:[a-f0-9]{64}$"
28
+ }
29
+ },
30
+ "required": ["file", "repositoryPath", "digestPath", "repository", "digest"],
31
+ "additionalProperties": false
32
+ }
@@ -0,0 +1,5 @@
1
+ import type { PromiseExecutor } from '@nx/devkit';
2
+ import type { WriteArtifactLockExecutorSchema } from './schema';
3
+ /** Writes an immutable image reference to declared paths in an artifact lock. */
4
+ declare const runExecutor: PromiseExecutor<WriteArtifactLockExecutorSchema>;
5
+ export default runExecutor;
@@ -0,0 +1,56 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ const node_fs_1 = require("node:fs");
4
+ const node_path_1 = require("node:path");
5
+ const yaml_1 = require("yaml");
6
+ /** Writes an immutable image reference to declared paths in an artifact lock. */
7
+ const runExecutor = async (options, context) => {
8
+ const projectRoot = context.projectsConfigurations?.projects[context.projectName ?? '']?.root;
9
+ if (!projectRoot) {
10
+ throw new Error('[nx-argo] Artifact locking requires an Nx project context.');
11
+ }
12
+ if (!/^sha256:[a-f0-9]{64}$/.test(options.digest)) {
13
+ throw new Error('[nx-argo] An immutable sha256 image digest is required.');
14
+ }
15
+ const filePath = (0, node_path_1.resolve)(context.root, projectRoot, options.file);
16
+ const lock = (0, node_fs_1.existsSync)(filePath)
17
+ ? parseYaml((0, node_fs_1.readFileSync)(filePath, 'utf8'))
18
+ : {};
19
+ setPath(lock, options.repositoryPath, options.repository);
20
+ setPath(lock, options.digestPath, options.digest);
21
+ (0, node_fs_1.writeFileSync)(filePath, (0, yaml_1.stringify)(lock, { lineWidth: 0 }));
22
+ return { success: true };
23
+ };
24
+ /** Parses a simple YAML object without accepting non-object lock roots. */
25
+ function parseYaml(source) {
26
+ const value = (0, yaml_1.parse)(source);
27
+ if (value === null) {
28
+ return {};
29
+ }
30
+ if (typeof value !== 'object' || Array.isArray(value)) {
31
+ throw new Error('[nx-argo] Artifact locks must contain a YAML mapping.');
32
+ }
33
+ return value;
34
+ }
35
+ /** Sets a dot-separated YAML mapping path. */
36
+ function setPath(root, path, value) {
37
+ const segments = path.split('.').filter(Boolean);
38
+ if (!segments.length) {
39
+ throw new Error('[nx-argo] Artifact mapping paths must not be empty.');
40
+ }
41
+ let current = root;
42
+ for (const segment of segments.slice(0, -1)) {
43
+ const child = current[segment];
44
+ if (child === undefined) {
45
+ current[segment] = {};
46
+ }
47
+ else if (typeof child !== 'object' ||
48
+ child === null ||
49
+ Array.isArray(child)) {
50
+ throw new Error(`[nx-argo] Artifact mapping path conflicts at ${segment}.`);
51
+ }
52
+ current = current[segment];
53
+ }
54
+ current[segments.at(-1)] = value;
55
+ }
56
+ exports.default = runExecutor;
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { PreviewStackGeneratorSchema } from './schema';
3
+ /** Creates a GitOps project boundary for an explicit preview stack. */
4
+ export default function previewStackGenerator(tree: Tree, options: PreviewStackGeneratorSchema): Promise<void>;
@@ -0,0 +1,44 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.default = previewStackGenerator;
4
+ const devkit_1 = require("@nx/devkit");
5
+ /** Creates a GitOps project boundary for an explicit preview stack. */
6
+ async function previewStackGenerator(tree, options) {
7
+ const name = (0, devkit_1.names)(options.name?.trim() || '').fileName;
8
+ const apps = [
9
+ ...new Set(options.apps?.map((app) => app.trim()).filter(Boolean)),
10
+ ];
11
+ const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/previews', name);
12
+ const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
13
+ if (!name || !apps.length) {
14
+ throw new Error('[nx-argo] A stack name and at least one app are required.');
15
+ }
16
+ if (tree.exists(projectFile)) {
17
+ throw new Error(`[nx-argo] A preview stack already exists at ${directory}.`);
18
+ }
19
+ (0, devkit_1.writeJson)(tree, projectFile, {
20
+ name: options.projectName?.trim() || `gitops-preview-${name}`,
21
+ root: directory,
22
+ projectType: 'application',
23
+ tags: ['type:gitops', 'environment:preview', `stack:${name}`],
24
+ implicitDependencies: apps,
25
+ metadata: {
26
+ delivery: {
27
+ previewStack: name,
28
+ },
29
+ },
30
+ targets: {
31
+ validate: {
32
+ executor: '@otwld/nx-argo:validate',
33
+ options: {
34
+ applicationFile: 'application.yaml',
35
+ artifactsFile: 'artifacts.yaml',
36
+ },
37
+ },
38
+ },
39
+ });
40
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'artifacts.yaml'), '# Preview artifact baseline written by automation.\n{}\n');
41
+ if (!options.skipFormat) {
42
+ await (0, devkit_1.formatFiles)(tree);
43
+ }
44
+ }
@@ -0,0 +1,13 @@
1
+ /** Options accepted by the GitOps preview stack generator. */
2
+ export interface PreviewStackGeneratorSchema {
3
+ /** Preview stack identity. */
4
+ name: string;
5
+ /** Nx workload projects intentionally included in this stack. */
6
+ apps: string[];
7
+ /** Parent directory for generated preview stacks. */
8
+ directory?: string;
9
+ /** Generated Nx project name. */
10
+ projectName?: string;
11
+ /** Skip Prettier formatting after generation. */
12
+ skipFormat?: boolean;
13
+ }
@@ -0,0 +1,38 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "$id": "NxArgoPreviewStackGeneratorSchema",
4
+ "title": "GitOps preview stack generator",
5
+ "description": "Create an Nx GitOps project for an explicit multi-workload preview stack.",
6
+ "type": "object",
7
+ "properties": {
8
+ "name": {
9
+ "type": "string",
10
+ "description": "Preview stack identity.",
11
+ "$default": { "source": "argv", "index": 0 },
12
+ "x-priority": "important"
13
+ },
14
+ "apps": {
15
+ "type": "array",
16
+ "description": "Nx workload projects intentionally included in this stack.",
17
+ "items": { "type": "string" },
18
+ "minItems": 1,
19
+ "x-priority": "important"
20
+ },
21
+ "directory": {
22
+ "type": "string",
23
+ "description": "Parent directory for preview stacks.",
24
+ "default": "gitops/previews"
25
+ },
26
+ "projectName": {
27
+ "type": "string",
28
+ "description": "Nx project name. Defaults to gitops-preview-<name>."
29
+ },
30
+ "skipFormat": {
31
+ "type": "boolean",
32
+ "description": "Skip Prettier formatting after generation.",
33
+ "default": false
34
+ }
35
+ },
36
+ "required": ["name", "apps"],
37
+ "additionalProperties": false
38
+ }
@@ -0,0 +1,15 @@
1
+ /** Options accepted by the GitOps service Application generator. */
2
+ export interface ServiceApplicationGeneratorSchema {
3
+ /** Application deployment identity shared by workloads and GitOps. */
4
+ service: string;
5
+ /** Environment name represented by the generated Application. */
6
+ environment: string;
7
+ /** Nx workload project that owns this GitOps Application. */
8
+ app: string;
9
+ /** Parent directory for generated GitOps application files. */
10
+ directory?: string;
11
+ /** Generated Argo CD Application project name. */
12
+ projectName?: string;
13
+ /** Skip Prettier formatting after generation. */
14
+ skipFormat?: boolean;
15
+ }
@@ -0,0 +1,41 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "$id": "NxArgoServiceApplicationGeneratorSchema",
4
+ "title": "GitOps service Application generator",
5
+ "description": "Create an Nx GitOps project for one workload and environment.",
6
+ "type": "object",
7
+ "properties": {
8
+ "service": {
9
+ "type": "string",
10
+ "description": "Application deployment identity shared with the workload.",
11
+ "$default": { "source": "argv", "index": 0 },
12
+ "x-priority": "important"
13
+ },
14
+ "environment": {
15
+ "type": "string",
16
+ "description": "Environment name represented by this Application.",
17
+ "x-priority": "important"
18
+ },
19
+ "app": {
20
+ "type": "string",
21
+ "description": "Owning Nx workload project.",
22
+ "x-priority": "important"
23
+ },
24
+ "directory": {
25
+ "type": "string",
26
+ "description": "Parent directory for GitOps Applications.",
27
+ "default": "gitops/applications"
28
+ },
29
+ "projectName": {
30
+ "type": "string",
31
+ "description": "Nx project name. Defaults to gitops-<service>-<environment>."
32
+ },
33
+ "skipFormat": {
34
+ "type": "boolean",
35
+ "description": "Skip Prettier formatting after generation.",
36
+ "default": false
37
+ }
38
+ },
39
+ "required": ["service", "environment", "app"],
40
+ "additionalProperties": false
41
+ }
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { ServiceApplicationGeneratorSchema } from './schema';
3
+ /** Creates a GitOps project boundary for one workload and environment. */
4
+ export default function serviceApplicationGenerator(tree: Tree, options: ServiceApplicationGeneratorSchema): Promise<void>;
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.default = serviceApplicationGenerator;
4
+ const devkit_1 = require("@nx/devkit");
5
+ /** Creates a GitOps project boundary for one workload and environment. */
6
+ async function serviceApplicationGenerator(tree, options) {
7
+ const service = getName(options.service, 'service');
8
+ const environment = getName(options.environment, 'environment');
9
+ const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/applications', service, environment);
10
+ const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
11
+ if (tree.exists(projectFile)) {
12
+ throw new Error(`[nx-argo] A GitOps project already exists at ${directory}.`);
13
+ }
14
+ (0, devkit_1.writeJson)(tree, projectFile, {
15
+ name: options.projectName?.trim() || `gitops-${service}-${environment}`,
16
+ root: directory,
17
+ projectType: 'application',
18
+ tags: ['type:gitops', `service:${service}`, `environment:${environment}`],
19
+ implicitDependencies: [requireValue(options.app, 'app')],
20
+ metadata: {
21
+ delivery: {
22
+ service,
23
+ artifacts: {
24
+ file: 'artifacts.yaml',
25
+ image: {
26
+ repositoryPath: 'image.repository',
27
+ digestPath: 'image.digest',
28
+ },
29
+ },
30
+ },
31
+ },
32
+ targets: {
33
+ validate: {
34
+ executor: '@otwld/nx-argo:validate',
35
+ options: {
36
+ applicationFile: 'application.yaml',
37
+ artifactsFile: 'artifacts.yaml',
38
+ },
39
+ },
40
+ 'write-artifact-lock': {
41
+ executor: '@otwld/nx-argo:write-artifact-lock',
42
+ cache: false,
43
+ options: {
44
+ file: 'artifacts.yaml',
45
+ repositoryPath: 'image.repository',
46
+ digestPath: 'image.digest',
47
+ },
48
+ },
49
+ },
50
+ });
51
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'artifacts.yaml'), '# Immutable artifacts written by automation.\n{}\n');
52
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'values.yaml'), '# Environment configuration owned by the repository.\n{}\n');
53
+ if (!options.skipFormat) {
54
+ await (0, devkit_1.formatFiles)(tree);
55
+ }
56
+ }
57
+ /** Normalizes an identifier used in directory and tag names. */
58
+ function getName(value, label) {
59
+ const normalized = (0, devkit_1.names)(requireValue(value, label)).fileName;
60
+ if (!normalized) {
61
+ throw new Error(`[nx-argo] A ${label} is required.`);
62
+ }
63
+ return normalized;
64
+ }
65
+ /** Requires a non-empty option. */
66
+ function requireValue(value, label) {
67
+ const normalized = value?.trim();
68
+ if (!normalized) {
69
+ throw new Error(`[nx-argo] A ${label} is required.`);
70
+ }
71
+ return normalized;
72
+ }
package/src/index.d.ts CHANGED
@@ -1,3 +1,7 @@
1
- /** Public generator exports for the Argo CD package. */
1
+ /** Public generator and executor exports for the Argo CD package. */
2
2
  export { default as applicationGenerator } from './generators/application/application';
3
3
  export type { ApplicationGeneratorSchema } from './generators/application/schema';
4
+ export { default as previewStackGenerator } from './generators/preview-stack/preview-stack';
5
+ export type { PreviewStackGeneratorSchema } from './generators/preview-stack/schema';
6
+ export { default as serviceApplicationGenerator } from './generators/service-application/service-application';
7
+ export type { ServiceApplicationGeneratorSchema } from './generators/service-application/schema';
package/src/index.js CHANGED
@@ -3,7 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.applicationGenerator = void 0;
7
- /** Public generator exports for the Argo CD package. */
6
+ exports.serviceApplicationGenerator = exports.previewStackGenerator = exports.applicationGenerator = void 0;
7
+ /** Public generator and executor exports for the Argo CD package. */
8
8
  var application_1 = require("./generators/application/application");
9
9
  Object.defineProperty(exports, "applicationGenerator", { enumerable: true, get: function () { return __importDefault(application_1).default; } });
10
+ var preview_stack_1 = require("./generators/preview-stack/preview-stack");
11
+ Object.defineProperty(exports, "previewStackGenerator", { enumerable: true, get: function () { return __importDefault(preview_stack_1).default; } });
12
+ var service_application_1 = require("./generators/service-application/service-application");
13
+ Object.defineProperty(exports, "serviceApplicationGenerator", { enumerable: true, get: function () { return __importDefault(service_application_1).default; } });