@otwld/nx-argo 0.0.5 → 0.0.7

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 (29) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/README.md +18 -61
  3. package/generators.json +8 -13
  4. package/package.json +1 -1
  5. package/src/executors/validate/schema.d.ts +5 -1
  6. package/src/executors/validate/schema.json +14 -3
  7. package/src/executors/validate/validate.d.ts +1 -1
  8. package/src/executors/validate/validate.js +164 -14
  9. package/src/executors/write-artifact-lock/schema.d.ts +8 -0
  10. package/src/executors/write-artifact-lock/schema.json +29 -1
  11. package/src/executors/write-artifact-lock/write-artifact-lock.d.ts +1 -1
  12. package/src/executors/write-artifact-lock/write-artifact-lock.js +128 -16
  13. package/src/generators/environment-project/environment-project.d.ts +4 -0
  14. package/src/generators/{service-application/service-application.js → environment-project/environment-project.js} +13 -9
  15. package/src/generators/environment-project/schema.d.ts +13 -0
  16. package/src/generators/{service-application → environment-project}/schema.json +7 -11
  17. package/src/generators/preview-project/preview-project.d.ts +4 -0
  18. package/src/generators/{preview-stack/preview-stack.js → preview-project/preview-project.js} +7 -8
  19. package/src/generators/{preview-stack → preview-project}/schema.d.ts +2 -4
  20. package/src/generators/{preview-stack → preview-project}/schema.json +2 -6
  21. package/src/index.d.ts +4 -6
  22. package/src/index.js +5 -7
  23. package/src/generators/application/application.d.ts +0 -9
  24. package/src/generators/application/application.js +0 -263
  25. package/src/generators/application/schema.d.ts +0 -27
  26. package/src/generators/application/schema.json +0 -97
  27. package/src/generators/preview-stack/preview-stack.d.ts +0 -4
  28. package/src/generators/service-application/schema.d.ts +0 -15
  29. package/src/generators/service-application/service-application.d.ts +0 -4
@@ -3,41 +3,145 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  const node_fs_1 = require("node:fs");
4
4
  const node_path_1 = require("node:path");
5
5
  const yaml_1 = require("yaml");
6
- /** Writes an immutable image reference to declared paths in an artifact lock. */
6
+ /** Writes or verifies one immutable artifact lock for a source revision. */
7
7
  const runExecutor = async (options, context) => {
8
8
  const projectRoot = context.projectsConfigurations?.projects[context.projectName ?? '']?.root;
9
9
  if (!projectRoot) {
10
10
  throw new Error('[nx-argo] Artifact locking requires an Nx project context.');
11
11
  }
12
+ if (!isNonEmptyString(options.repository)) {
13
+ throw new Error('[nx-argo] An image repository is required.');
14
+ }
12
15
  if (!/^sha256:[a-f0-9]{64}$/.test(options.digest)) {
13
16
  throw new Error('[nx-argo] An immutable sha256 image digest is required.');
14
17
  }
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);
18
+ if (!isNonEmptyString(options.service) ||
19
+ !isNonEmptyString(options.sourceRevision)) {
20
+ throw new Error('[nx-argo] A service and source revision are required.');
21
+ }
22
+ const root = (0, node_path_1.resolve)(context.root, projectRoot);
23
+ const filePath = resolveProjectFile(root, options.file);
24
+ if (!(0, node_fs_1.existsSync)(filePath)) {
25
+ throw new Error(`[nx-argo] Artifact lock file is missing: ${filePath}`);
26
+ }
27
+ const paths = {
28
+ repository: parsePath(options.repositoryPath),
29
+ digest: parsePath(options.digestPath),
30
+ service: parsePath(options.servicePath),
31
+ sourceRevision: parsePath(options.sourceRevisionPath),
32
+ };
33
+ assertDistinctPaths(paths);
34
+ const lock = parseYaml((0, node_fs_1.readFileSync)(filePath, 'utf8'));
35
+ const isPending = getPath(lock, ['artifact', 'pending']) === true;
36
+ if (isPending) {
37
+ validatePendingLock(lock, paths);
38
+ setPath(lock, ['artifact', 'pending'], false);
39
+ }
40
+ const existingRevision = getPath(lock, paths.sourceRevision);
41
+ if (!isPending &&
42
+ existingRevision !== undefined &&
43
+ !isNonEmptyString(existingRevision)) {
44
+ throw new Error('[nx-argo] Artifact source revision must be a string.');
45
+ }
46
+ if (!isPending && existingRevision === options.sourceRevision) {
47
+ verifyValue(lock, paths.service, options.service, 'service');
48
+ verifyValue(lock, paths.repository, options.repository, 'repository');
49
+ verifyValue(lock, paths.digest, options.digest, 'digest');
50
+ return { success: true };
51
+ }
52
+ setPath(lock, paths.repository, options.repository);
53
+ setPath(lock, paths.digest, options.digest);
54
+ setPath(lock, paths.service, options.service);
55
+ setPath(lock, paths.sourceRevision, options.sourceRevision);
21
56
  (0, node_fs_1.writeFileSync)(filePath, (0, yaml_1.stringify)(lock, { lineWidth: 0 }));
22
57
  return { success: true };
23
58
  };
24
- /** Parses a simple YAML object without accepting non-object lock roots. */
59
+ /** Resolves a required project-local file without accepting path escapes. */
60
+ function resolveProjectFile(root, file) {
61
+ if (!file.trim() || (0, node_path_1.isAbsolute)(file) || file.split(/[\\/]+/).includes('..')) {
62
+ throw new Error('[nx-argo] Artifact lock file must stay within the project root.');
63
+ }
64
+ const filePath = (0, node_path_1.resolve)(root, file);
65
+ const pathFromRoot = (0, node_path_1.relative)(root, filePath);
66
+ if (!pathFromRoot ||
67
+ pathFromRoot === '..' ||
68
+ pathFromRoot.startsWith(`..${node_path_1.sep}`) ||
69
+ (0, node_path_1.isAbsolute)(pathFromRoot)) {
70
+ throw new Error('[nx-argo] Artifact lock file must stay within the project root.');
71
+ }
72
+ return filePath;
73
+ }
74
+ /** Requires the four declared lock values to be empty before enrollment. */
75
+ function validatePendingLock(lock, paths) {
76
+ const pendingValues = [
77
+ getPath(lock, paths['repository']),
78
+ getPath(lock, paths['digest']),
79
+ getPath(lock, paths['service']),
80
+ getPath(lock, paths['sourceRevision']),
81
+ ];
82
+ if (!pendingValues.every((value) => value === '')) {
83
+ throw new Error('[nx-argo] Pending artifact locks require empty artifact values.');
84
+ }
85
+ }
86
+ /** Parses a YAML mapping without accepting malformed or empty documents. */
25
87
  function parseYaml(source) {
26
88
  const value = (0, yaml_1.parse)(source);
27
- if (value === null) {
28
- return {};
29
- }
30
- if (typeof value !== 'object' || Array.isArray(value)) {
89
+ if (value === null || typeof value !== 'object' || Array.isArray(value)) {
31
90
  throw new Error('[nx-argo] Artifact locks must contain a YAML mapping.');
32
91
  }
33
92
  return value;
34
93
  }
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) {
94
+ /** Parses a dot-separated YAML mapping path. */
95
+ function parsePath(path) {
96
+ const segments = path.split('.');
97
+ if (segments.some((segment) => !segment.trim())) {
39
98
  throw new Error('[nx-argo] Artifact mapping paths must not be empty.');
40
99
  }
100
+ return segments;
101
+ }
102
+ /** Rejects equal or overlapping mapping paths before a write can corrupt data. */
103
+ function assertDistinctPaths(paths) {
104
+ const entries = [
105
+ ['repository', paths.repository],
106
+ ['digest', paths.digest],
107
+ ['service', paths.service],
108
+ ['sourceRevision', paths.sourceRevision],
109
+ ];
110
+ for (const [index, [name, path]] of entries.entries()) {
111
+ for (const [otherName, otherPath] of entries.slice(index + 1)) {
112
+ if (path.every((segment, pathIndex) => otherPath[pathIndex] === segment) ||
113
+ otherPath.every((segment, pathIndex) => path[pathIndex] === segment)) {
114
+ throw new Error(`[nx-argo] Artifact mapping paths conflict: ${name} and ${otherName}.`);
115
+ }
116
+ }
117
+ }
118
+ }
119
+ /** Reads a mapping path and reports malformed intermediate values. */
120
+ function getPath(root, path) {
121
+ let current = root;
122
+ for (const [index, segment] of path.entries()) {
123
+ const value = current[segment];
124
+ if (index === path.length - 1) {
125
+ return value;
126
+ }
127
+ if (value === undefined) {
128
+ return undefined;
129
+ }
130
+ if (!isRecord(value)) {
131
+ throw new Error(`[nx-argo] Artifact mapping path conflicts at ${segment}.`);
132
+ }
133
+ current = value;
134
+ }
135
+ return undefined;
136
+ }
137
+ /** Verifies an idempotent write against the values recorded for its revision. */
138
+ function verifyValue(lock, path, expected, label) {
139
+ if (getPath(lock, path) !== expected) {
140
+ throw new Error(`[nx-argo] Artifact ${label} conflicts with the existing source revision.`);
141
+ }
142
+ }
143
+ /** Sets a dot-separated YAML mapping path. */
144
+ function setPath(root, segments, value) {
41
145
  let current = root;
42
146
  for (const segment of segments.slice(0, -1)) {
43
147
  const child = current[segment];
@@ -53,4 +157,12 @@ function setPath(root, path, value) {
53
157
  }
54
158
  current[segments.at(-1)] = value;
55
159
  }
160
+ /** Narrows unknown YAML values to simple object mappings. */
161
+ function isRecord(value) {
162
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
163
+ }
164
+ /** Requires a non-empty string option. */
165
+ function isNonEmptyString(value) {
166
+ return typeof value === 'string' && Boolean(value.trim());
167
+ }
56
168
  exports.default = runExecutor;
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { EnvironmentProjectGeneratorSchema } from './schema';
3
+ /** Creates a GitOps project boundary for one service environment. */
4
+ export default function environmentProjectGenerator(tree: Tree, options: EnvironmentProjectGeneratorSchema): Promise<void>;
@@ -1,18 +1,18 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.default = serviceApplicationGenerator;
3
+ exports.default = environmentProjectGenerator;
4
4
  const devkit_1 = require("@nx/devkit");
5
- /** Creates a GitOps project boundary for one workload and environment. */
6
- async function serviceApplicationGenerator(tree, options) {
5
+ /** Creates a GitOps project boundary for one service environment. */
6
+ async function environmentProjectGenerator(tree, options) {
7
7
  const service = getName(options.service, 'service');
8
8
  const environment = getName(options.environment, 'environment');
9
- const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/applications', service, environment);
9
+ const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/environments', service, environment);
10
10
  const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
11
11
  if (tree.exists(projectFile)) {
12
- throw new Error(`[nx-argo] A GitOps project already exists at ${directory}.`);
12
+ throw new Error(`[nx-argo] A GitOps environment project already exists at ${directory}.`);
13
13
  }
14
14
  (0, devkit_1.writeJson)(tree, projectFile, {
15
- name: options.projectName?.trim() || `gitops-${service}-${environment}`,
15
+ name: `gitops-${service}-${environment}`,
16
16
  root: directory,
17
17
  projectType: 'application',
18
18
  tags: ['type:gitops', `service:${service}`, `environment:${environment}`],
@@ -26,6 +26,8 @@ async function serviceApplicationGenerator(tree, options) {
26
26
  repositoryPath: 'image.repository',
27
27
  digestPath: 'image.digest',
28
28
  },
29
+ sourceRevisionPath: 'artifact.sourceRevision',
30
+ servicePath: 'artifact.service',
29
31
  },
30
32
  },
31
33
  },
@@ -33,7 +35,7 @@ async function serviceApplicationGenerator(tree, options) {
33
35
  validate: {
34
36
  executor: '@otwld/nx-argo:validate',
35
37
  options: {
36
- applicationFile: 'application.yaml',
38
+ mode: 'environment',
37
39
  artifactsFile: 'artifacts.yaml',
38
40
  },
39
41
  },
@@ -44,12 +46,14 @@ async function serviceApplicationGenerator(tree, options) {
44
46
  file: 'artifacts.yaml',
45
47
  repositoryPath: 'image.repository',
46
48
  digestPath: 'image.digest',
49
+ servicePath: 'artifact.service',
50
+ sourceRevisionPath: 'artifact.sourceRevision',
47
51
  },
48
52
  },
49
53
  },
50
54
  });
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');
55
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'values.yaml'), '# Environment configuration owned by humans.\n{}\n');
56
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'artifacts.yaml'), "# Immutable artifacts written by automation.\nartifact:\n pending: true\n service: ''\n sourceRevision: ''\nimage:\n repository: ''\n digest: ''\n");
53
57
  if (!options.skipFormat) {
54
58
  await (0, devkit_1.formatFiles)(tree);
55
59
  }
@@ -0,0 +1,13 @@
1
+ /** Options accepted by the GitOps environment project generator. */
2
+ export interface EnvironmentProjectGeneratorSchema {
3
+ /** Deployment identity shared with workloads and GitOps. */
4
+ service: string;
5
+ /** Environment represented by the generated GitOps project. */
6
+ environment: string;
7
+ /** Nx workload project that owns this GitOps environment. */
8
+ app: string;
9
+ /** Parent directory for generated GitOps environments. */
10
+ directory?: string;
11
+ /** Skip Prettier formatting after generation. */
12
+ skipFormat?: boolean;
13
+ }
@@ -1,19 +1,19 @@
1
1
  {
2
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.",
3
+ "$id": "NxArgoEnvironmentProjectGeneratorSchema",
4
+ "title": "GitOps environment project generator",
5
+ "description": "Create an Nx GitOps project for one service environment.",
6
6
  "type": "object",
7
7
  "properties": {
8
8
  "service": {
9
9
  "type": "string",
10
- "description": "Application deployment identity shared with the workload.",
10
+ "description": "Deployment identity shared with workloads and GitOps.",
11
11
  "$default": { "source": "argv", "index": 0 },
12
12
  "x-priority": "important"
13
13
  },
14
14
  "environment": {
15
15
  "type": "string",
16
- "description": "Environment name represented by this Application.",
16
+ "description": "Environment represented by this GitOps project.",
17
17
  "x-priority": "important"
18
18
  },
19
19
  "app": {
@@ -23,12 +23,8 @@
23
23
  },
24
24
  "directory": {
25
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>."
26
+ "description": "Parent directory for GitOps environments.",
27
+ "default": "gitops/environments"
32
28
  },
33
29
  "skipFormat": {
34
30
  "type": "boolean",
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { PreviewProjectGeneratorSchema } from './schema';
3
+ /** Creates a GitOps project boundary for an explicit preview stack. */
4
+ export default function previewProjectGenerator(tree: Tree, options: PreviewProjectGeneratorSchema): Promise<void>;
@@ -1,9 +1,9 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.default = previewStackGenerator;
3
+ exports.default = previewProjectGenerator;
4
4
  const devkit_1 = require("@nx/devkit");
5
5
  /** Creates a GitOps project boundary for an explicit preview stack. */
6
- async function previewStackGenerator(tree, options) {
6
+ async function previewProjectGenerator(tree, options) {
7
7
  const name = (0, devkit_1.names)(options.name?.trim() || '').fileName;
8
8
  const apps = [
9
9
  ...new Set(options.apps?.map((app) => app.trim()).filter(Boolean)),
@@ -11,13 +11,13 @@ async function previewStackGenerator(tree, options) {
11
11
  const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/previews', name);
12
12
  const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
13
13
  if (!name || !apps.length) {
14
- throw new Error('[nx-argo] A stack name and at least one app are required.');
14
+ throw new Error('[nx-argo] A preview name and at least one app are required.');
15
15
  }
16
16
  if (tree.exists(projectFile)) {
17
- throw new Error(`[nx-argo] A preview stack already exists at ${directory}.`);
17
+ throw new Error(`[nx-argo] A GitOps preview project already exists at ${directory}.`);
18
18
  }
19
19
  (0, devkit_1.writeJson)(tree, projectFile, {
20
- name: options.projectName?.trim() || `gitops-preview-${name}`,
20
+ name: `gitops-preview-${name}`,
21
21
  root: directory,
22
22
  projectType: 'application',
23
23
  tags: ['type:gitops', 'environment:preview', `stack:${name}`],
@@ -31,13 +31,12 @@ async function previewStackGenerator(tree, options) {
31
31
  validate: {
32
32
  executor: '@otwld/nx-argo:validate',
33
33
  options: {
34
- applicationFile: 'application.yaml',
35
- artifactsFile: 'artifacts.yaml',
34
+ mode: 'preview',
35
+ applicationSetFile: 'application-set.yaml',
36
36
  },
37
37
  },
38
38
  },
39
39
  });
40
- tree.write((0, devkit_1.joinPathFragments)(directory, 'artifacts.yaml'), '# Preview artifact baseline written by automation.\n{}\n');
41
40
  if (!options.skipFormat) {
42
41
  await (0, devkit_1.formatFiles)(tree);
43
42
  }
@@ -1,13 +1,11 @@
1
- /** Options accepted by the GitOps preview stack generator. */
2
- export interface PreviewStackGeneratorSchema {
1
+ /** Options accepted by the GitOps preview project generator. */
2
+ export interface PreviewProjectGeneratorSchema {
3
3
  /** Preview stack identity. */
4
4
  name: string;
5
5
  /** Nx workload projects intentionally included in this stack. */
6
6
  apps: string[];
7
7
  /** Parent directory for generated preview stacks. */
8
8
  directory?: string;
9
- /** Generated Nx project name. */
10
- projectName?: string;
11
9
  /** Skip Prettier formatting after generation. */
12
10
  skipFormat?: boolean;
13
11
  }
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json-schema.org/schema",
3
- "$id": "NxArgoPreviewStackGeneratorSchema",
4
- "title": "GitOps preview stack generator",
3
+ "$id": "NxArgoPreviewProjectGeneratorSchema",
4
+ "title": "GitOps preview project generator",
5
5
  "description": "Create an Nx GitOps project for an explicit multi-workload preview stack.",
6
6
  "type": "object",
7
7
  "properties": {
@@ -23,10 +23,6 @@
23
23
  "description": "Parent directory for preview stacks.",
24
24
  "default": "gitops/previews"
25
25
  },
26
- "projectName": {
27
- "type": "string",
28
- "description": "Nx project name. Defaults to gitops-preview-<name>."
29
- },
30
26
  "skipFormat": {
31
27
  "type": "boolean",
32
28
  "description": "Skip Prettier formatting after generation.",
package/src/index.d.ts CHANGED
@@ -1,7 +1,5 @@
1
1
  /** Public generator and executor exports for the Argo CD package. */
2
- export { default as applicationGenerator } from './generators/application/application';
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';
2
+ export { default as environmentProjectGenerator } from './generators/environment-project/environment-project';
3
+ export type { EnvironmentProjectGeneratorSchema } from './generators/environment-project/schema';
4
+ export { default as previewProjectGenerator } from './generators/preview-project/preview-project';
5
+ export type { PreviewProjectGeneratorSchema } from './generators/preview-project/schema';
package/src/index.js CHANGED
@@ -3,11 +3,9 @@ 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.serviceApplicationGenerator = exports.previewStackGenerator = exports.applicationGenerator = void 0;
6
+ exports.previewProjectGenerator = exports.environmentProjectGenerator = void 0;
7
7
  /** Public generator and executor exports for the Argo CD package. */
8
- var application_1 = require("./generators/application/application");
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; } });
8
+ var environment_project_1 = require("./generators/environment-project/environment-project");
9
+ Object.defineProperty(exports, "environmentProjectGenerator", { enumerable: true, get: function () { return __importDefault(environment_project_1).default; } });
10
+ var preview_project_1 = require("./generators/preview-project/preview-project");
11
+ Object.defineProperty(exports, "previewProjectGenerator", { enumerable: true, get: function () { return __importDefault(preview_project_1).default; } });
@@ -1,9 +0,0 @@
1
- import { type Tree } from '@nx/devkit';
2
- import type { ApplicationGeneratorSchema } from './schema';
3
- /**
4
- * Creates a multi-source Argo CD Application and its Helm values file.
5
- * @param tree Workspace tree to update.
6
- * @param options Generator options supplied by Nx.
7
- * @returns A promise that resolves after optional formatting.
8
- */
9
- export default function applicationGenerator(tree: Tree, options: ApplicationGeneratorSchema): Promise<void>;