@otwld/nx-argo 0.0.7 → 0.0.9

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 (59) hide show
  1. package/CHANGELOG.md +6 -3
  2. package/README.md +56 -13
  3. package/executors.json +34 -9
  4. package/generators.json +5 -0
  5. package/package.json +1 -1
  6. package/src/executors/copy-image-lock/copy-image-lock.d.ts +5 -0
  7. package/src/executors/copy-image-lock/copy-image-lock.js +14 -0
  8. package/src/executors/copy-image-lock/schema.d.ts +19 -0
  9. package/src/executors/copy-image-lock/schema.json +48 -0
  10. package/src/executors/copy-source-revision/copy-source-revision.d.ts +5 -0
  11. package/src/executors/copy-source-revision/copy-source-revision.js +29 -0
  12. package/src/executors/copy-source-revision/schema.d.ts +19 -0
  13. package/src/executors/copy-source-revision/schema.json +41 -0
  14. package/src/executors/image-lock.d.ts +16 -0
  15. package/src/executors/image-lock.js +53 -0
  16. package/src/executors/set-source-revision/schema.d.ts +15 -0
  17. package/src/executors/set-source-revision/schema.json +28 -0
  18. package/src/executors/set-source-revision/set-source-revision.d.ts +5 -0
  19. package/src/executors/set-source-revision/set-source-revision.js +20 -0
  20. package/src/executors/shared.d.ts +28 -0
  21. package/src/executors/shared.js +112 -0
  22. package/src/executors/source-revision.d.ts +9 -0
  23. package/src/executors/source-revision.js +30 -0
  24. package/src/executors/validate-application/schema.d.ts +7 -0
  25. package/src/executors/validate-application/schema.json +19 -0
  26. package/src/executors/validate-application/validate-application.d.ts +5 -0
  27. package/src/executors/validate-application/validate-application.js +38 -0
  28. package/src/executors/validate-application-set/schema.d.ts +7 -0
  29. package/src/executors/validate-application-set/schema.json +20 -0
  30. package/src/executors/validate-application-set/validate-application-set.d.ts +5 -0
  31. package/src/executors/validate-application-set/validate-application-set.js +69 -0
  32. package/src/executors/validate-image-lock/schema.d.ts +15 -0
  33. package/src/executors/validate-image-lock/schema.json +36 -0
  34. package/src/executors/validate-image-lock/validate-image-lock.d.ts +5 -0
  35. package/src/executors/validate-image-lock/validate-image-lock.js +11 -0
  36. package/src/executors/{write-artifact-lock → write-image-lock}/schema.d.ts +5 -5
  37. package/src/executors/{write-artifact-lock → write-image-lock}/schema.json +10 -9
  38. package/src/executors/write-image-lock/write-image-lock.d.ts +5 -0
  39. package/src/executors/write-image-lock/write-image-lock.js +55 -0
  40. package/src/generators/environment-project/environment-project.d.ts +1 -1
  41. package/src/generators/environment-project/environment-project.js +56 -35
  42. package/src/generators/environment-project/schema.d.ts +11 -3
  43. package/src/generators/environment-project/schema.json +25 -7
  44. package/src/generators/preview-project/preview-project.d.ts +1 -1
  45. package/src/generators/preview-project/preview-project.js +16 -11
  46. package/src/generators/preview-project/schema.d.ts +6 -2
  47. package/src/generators/preview-project/schema.json +15 -7
  48. package/src/generators/stack-project/schema.d.ts +55 -0
  49. package/src/generators/stack-project/schema.json +110 -0
  50. package/src/generators/stack-project/stack-project.d.ts +4 -0
  51. package/src/generators/stack-project/stack-project.js +428 -0
  52. package/src/index.d.ts +16 -0
  53. package/src/index.js +17 -1
  54. package/src/executors/validate/schema.d.ts +0 -11
  55. package/src/executors/validate/schema.json +0 -28
  56. package/src/executors/validate/validate.d.ts +0 -5
  57. package/src/executors/validate/validate.js +0 -190
  58. package/src/executors/write-artifact-lock/write-artifact-lock.d.ts +0 -5
  59. package/src/executors/write-artifact-lock/write-artifact-lock.js +0 -168
@@ -2,62 +2,83 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.default = environmentProjectGenerator;
4
4
  const devkit_1 = require("@nx/devkit");
5
- /** Creates a GitOps project boundary for one service environment. */
5
+ /** Creates a generic GitOps project boundary for one environment. */
6
6
  async function environmentProjectGenerator(tree, options) {
7
+ const name = getName(options.name, 'name');
7
8
  const service = getName(options.service, 'service');
8
9
  const environment = getName(options.environment, 'environment');
9
- const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/environments', service, environment);
10
+ const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/environments', name, environment);
10
11
  const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
11
12
  if (tree.exists(projectFile)) {
12
13
  throw new Error(`[nx-argo] A GitOps environment project already exists at ${directory}.`);
13
14
  }
14
15
  (0, devkit_1.writeJson)(tree, projectFile, {
15
- name: `gitops-${service}-${environment}`,
16
+ name: `gitops-${name}-${environment}`,
16
17
  root: directory,
17
18
  projectType: 'application',
18
- tags: ['type:gitops', `service:${service}`, `environment:${environment}`],
19
- implicitDependencies: [requireValue(options.app, 'app')],
19
+ tags: [
20
+ 'type:gitops',
21
+ `deployment:${name}`,
22
+ `service:${service}`,
23
+ `environment:${environment}`,
24
+ ],
25
+ implicitDependencies: getDependencies(options),
20
26
  metadata: {
21
27
  delivery: {
28
+ name,
22
29
  service,
23
- artifacts: {
24
- file: 'artifacts.yaml',
25
- image: {
26
- repositoryPath: 'image.repository',
27
- digestPath: 'image.digest',
28
- },
29
- sourceRevisionPath: 'artifact.sourceRevision',
30
- servicePath: 'artifact.service',
31
- },
32
- },
33
- },
34
- targets: {
35
- validate: {
36
- executor: '@otwld/nx-argo:validate',
37
- options: {
38
- mode: 'environment',
39
- artifactsFile: 'artifacts.yaml',
40
- },
41
- },
42
- 'write-artifact-lock': {
43
- executor: '@otwld/nx-argo:write-artifact-lock',
44
- cache: false,
45
- options: {
46
- file: 'artifacts.yaml',
47
- repositoryPath: 'image.repository',
48
- digestPath: 'image.digest',
49
- servicePath: 'artifact.service',
50
- sourceRevisionPath: 'artifact.sourceRevision',
51
- },
30
+ environment,
52
31
  },
53
32
  },
33
+ targets: getTargets(options),
54
34
  });
55
35
  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");
36
+ if (options.imageLock) {
37
+ tree.write((0, devkit_1.joinPathFragments)(directory, 'artifacts.yaml'), "# Immutable image lock written by automation.\nartifact:\n pending: true\n service: ''\n sourceRevision: ''\nimage:\n repository: ''\n digest: ''\n");
38
+ }
57
39
  if (!options.skipFormat) {
58
40
  await (0, devkit_1.formatFiles)(tree);
59
41
  }
60
42
  }
43
+ /** Declares only the targets needed by files selected for this project. */
44
+ function getTargets(options) {
45
+ const targets = {};
46
+ if (options.applicationFile) {
47
+ targets['validate-application'] = {
48
+ executor: '@otwld/nx-argo:validate-application',
49
+ options: {
50
+ file: options.applicationFile,
51
+ ...(options.imageLock ? { finalValueFile: 'artifacts.yaml' } : {}),
52
+ },
53
+ };
54
+ }
55
+ if (options.imageLock) {
56
+ targets['validate-image-lock'] = {
57
+ executor: '@otwld/nx-argo:validate-image-lock',
58
+ options: { file: 'artifacts.yaml' },
59
+ };
60
+ targets['write-image-lock'] = {
61
+ executor: '@otwld/nx-argo:write-image-lock',
62
+ cache: false,
63
+ options: {
64
+ file: 'artifacts.yaml',
65
+ repositoryPath: 'image.repository',
66
+ digestPath: 'image.digest',
67
+ servicePath: 'artifact.service',
68
+ sourceRevisionPath: 'artifact.sourceRevision',
69
+ },
70
+ };
71
+ }
72
+ return targets;
73
+ }
74
+ /** Builds deduplicated project dependencies from all selected inputs. */
75
+ function getDependencies(options) {
76
+ return [
77
+ ...new Set([...(options.dependencies ?? []), options.chartProject]
78
+ .filter((dependency) => Boolean(dependency?.trim()))
79
+ .map((dependency) => dependency.trim())),
80
+ ];
81
+ }
61
82
  /** Normalizes an identifier used in directory and tag names. */
62
83
  function getName(value, label) {
63
84
  const normalized = (0, devkit_1.names)(requireValue(value, label)).fileName;
@@ -1,11 +1,19 @@
1
1
  /** Options accepted by the GitOps environment project generator. */
2
2
  export interface EnvironmentProjectGeneratorSchema {
3
- /** Deployment identity shared with workloads and GitOps. */
3
+ /** Deployment name used for the project boundary and directory. */
4
+ name: string;
5
+ /** Deployment service identity recorded in metadata. */
4
6
  service: string;
5
7
  /** Environment represented by the generated GitOps project. */
6
8
  environment: string;
7
- /** Nx workload project that owns this GitOps environment. */
8
- app: string;
9
+ /** Nx projects this GitOps project implicitly depends on. */
10
+ dependencies?: string[];
11
+ /** Optional Nx chart project dependency. */
12
+ chartProject?: string;
13
+ /** Create the canonical artifacts.yaml image lock and its targets. */
14
+ imageLock?: boolean;
15
+ /** Optional declared Application file relative to the generated project. */
16
+ applicationFile?: string;
9
17
  /** Parent directory for generated GitOps environments. */
10
18
  directory?: string;
11
19
  /** Skip Prettier formatting after generation. */
@@ -2,24 +2,42 @@
2
2
  "$schema": "https://json-schema.org/schema",
3
3
  "$id": "NxArgoEnvironmentProjectGeneratorSchema",
4
4
  "title": "GitOps environment project generator",
5
- "description": "Create an Nx GitOps project for one service environment.",
5
+ "description": "Create an Nx GitOps project for one environment.",
6
6
  "type": "object",
7
7
  "properties": {
8
- "service": {
8
+ "name": {
9
9
  "type": "string",
10
- "description": "Deployment identity shared with workloads and GitOps.",
10
+ "description": "Deployment name used for the project boundary and directory.",
11
11
  "$default": { "source": "argv", "index": 0 },
12
12
  "x-priority": "important"
13
13
  },
14
+ "service": {
15
+ "type": "string",
16
+ "description": "Deployment service identity recorded in metadata.",
17
+ "x-priority": "important"
18
+ },
14
19
  "environment": {
15
20
  "type": "string",
16
21
  "description": "Environment represented by this GitOps project.",
17
22
  "x-priority": "important"
18
23
  },
19
- "app": {
24
+ "dependencies": {
25
+ "type": "array",
26
+ "description": "Nx projects this GitOps project implicitly depends on.",
27
+ "items": { "type": "string" }
28
+ },
29
+ "chartProject": {
20
30
  "type": "string",
21
- "description": "Owning Nx workload project.",
22
- "x-priority": "important"
31
+ "description": "Optional Nx chart project dependency."
32
+ },
33
+ "imageLock": {
34
+ "type": "boolean",
35
+ "description": "Create the canonical artifacts.yaml image lock and its targets.",
36
+ "default": false
37
+ },
38
+ "applicationFile": {
39
+ "type": "string",
40
+ "description": "Optional declared Application file relative to the generated project."
23
41
  },
24
42
  "directory": {
25
43
  "type": "string",
@@ -32,6 +50,6 @@
32
50
  "default": false
33
51
  }
34
52
  },
35
- "required": ["service", "environment", "app"],
53
+ "required": ["name", "service", "environment"],
36
54
  "additionalProperties": false
37
55
  }
@@ -1,4 +1,4 @@
1
1
  import { type Tree } from '@nx/devkit';
2
2
  import type { PreviewProjectGeneratorSchema } from './schema';
3
- /** Creates a GitOps project boundary for an explicit preview stack. */
3
+ /** Creates a generic GitOps project boundary for an ApplicationSet workflow. */
4
4
  export default function previewProjectGenerator(tree: Tree, options: PreviewProjectGeneratorSchema): Promise<void>;
@@ -2,16 +2,18 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.default = previewProjectGenerator;
4
4
  const devkit_1 = require("@nx/devkit");
5
- /** Creates a GitOps project boundary for an explicit preview stack. */
5
+ /** Creates a generic GitOps project boundary for an ApplicationSet workflow. */
6
6
  async function previewProjectGenerator(tree, options) {
7
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)),
8
+ const dependencies = [
9
+ ...new Set(options.dependencies
10
+ ?.map((dependency) => dependency.trim())
11
+ .filter(Boolean)),
10
12
  ];
11
13
  const directory = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'gitops/previews', name);
12
14
  const projectFile = (0, devkit_1.joinPathFragments)(directory, 'project.json');
13
- if (!name || !apps.length) {
14
- throw new Error('[nx-argo] A preview name and at least one app are required.');
15
+ if (!name) {
16
+ throw new Error('[nx-argo] A preview name is required.');
15
17
  }
16
18
  if (tree.exists(projectFile)) {
17
19
  throw new Error(`[nx-argo] A GitOps preview project already exists at ${directory}.`);
@@ -21,18 +23,21 @@ async function previewProjectGenerator(tree, options) {
21
23
  root: directory,
22
24
  projectType: 'application',
23
25
  tags: ['type:gitops', 'environment:preview', `stack:${name}`],
24
- implicitDependencies: apps,
26
+ implicitDependencies: dependencies,
25
27
  metadata: {
26
28
  delivery: {
27
- previewStack: name,
29
+ preview: {
30
+ name,
31
+ ...(options.policy ? { policy: options.policy } : {}),
32
+ },
28
33
  },
29
34
  },
30
35
  targets: {
31
- validate: {
32
- executor: '@otwld/nx-argo:validate',
36
+ 'validate-application-set': {
37
+ executor: '@otwld/nx-argo:validate-application-set',
33
38
  options: {
34
- mode: 'preview',
35
- applicationSetFile: 'application-set.yaml',
39
+ file: options.applicationSetFile ?? 'application-set.yaml',
40
+ ...(options.policy ? { policy: options.policy } : {}),
36
41
  },
37
42
  },
38
43
  },
@@ -2,8 +2,12 @@
2
2
  export interface PreviewProjectGeneratorSchema {
3
3
  /** Preview stack identity. */
4
4
  name: string;
5
- /** Nx workload projects intentionally included in this stack. */
6
- apps: string[];
5
+ /** Nx projects this preview project implicitly depends on. */
6
+ dependencies?: string[];
7
+ /** Optional ApplicationSet policy to enforce. */
8
+ policy?: 'github-pr-preview';
9
+ /** Declared ApplicationSet file relative to the generated project. */
10
+ applicationSetFile?: string;
7
11
  /** Parent directory for generated preview stacks. */
8
12
  directory?: string;
9
13
  /** Skip Prettier formatting after generation. */
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://json-schema.org/schema",
3
3
  "$id": "NxArgoPreviewProjectGeneratorSchema",
4
4
  "title": "GitOps preview project generator",
5
- "description": "Create an Nx GitOps project for an explicit multi-workload preview stack.",
5
+ "description": "Create an Nx GitOps project for a generic ApplicationSet preview workflow.",
6
6
  "type": "object",
7
7
  "properties": {
8
8
  "name": {
@@ -11,12 +11,20 @@
11
11
  "$default": { "source": "argv", "index": 0 },
12
12
  "x-priority": "important"
13
13
  },
14
- "apps": {
14
+ "dependencies": {
15
15
  "type": "array",
16
- "description": "Nx workload projects intentionally included in this stack.",
17
- "items": { "type": "string" },
18
- "minItems": 1,
19
- "x-priority": "important"
16
+ "description": "Nx projects this preview project implicitly depends on.",
17
+ "items": { "type": "string" }
18
+ },
19
+ "policy": {
20
+ "type": "string",
21
+ "enum": ["github-pr-preview"],
22
+ "description": "Optional ApplicationSet policy to enforce."
23
+ },
24
+ "applicationSetFile": {
25
+ "type": "string",
26
+ "default": "application-set.yaml",
27
+ "description": "Declared ApplicationSet file relative to the generated project."
20
28
  },
21
29
  "directory": {
22
30
  "type": "string",
@@ -29,6 +37,6 @@
29
37
  "default": false
30
38
  }
31
39
  },
32
- "required": ["name", "apps"],
40
+ "required": ["name"],
33
41
  "additionalProperties": false
34
42
  }
@@ -0,0 +1,55 @@
1
+ /** Repository identity used by generated Argo sources and preview generators. */
2
+ export interface StackRepository {
3
+ /** Full Git repository URL. */
4
+ url?: string;
5
+ /** GitHub owner used by the optional pull-request generator. */
6
+ owner?: string;
7
+ /** GitHub repository name used by the optional pull-request generator. */
8
+ name?: string;
9
+ /** Branch or revision used by the stable Applications. */
10
+ revision?: string;
11
+ }
12
+
13
+ /** Explicit value-file paths owned by the generated stack project. */
14
+ export interface StackValueFiles {
15
+ /** Staging value file relative to the GitOps project. */
16
+ staging?: string;
17
+ /** Production value file relative to the GitOps project. */
18
+ production?: string;
19
+ /** Preview base value file relative to the GitOps project. */
20
+ preview?: string;
21
+ /** Pull-request value-file pattern relative to the GitOps project. */
22
+ pullRequest?: string;
23
+ }
24
+
25
+ /** Options accepted by the generic GitOps stack project generator. */
26
+ export interface StackProjectGeneratorSchema {
27
+ /** Stack identity and generated directory suffix. */
28
+ name: string;
29
+ /** Workspace-relative Helm chart path used by generated Argo sources. */
30
+ chartPath: string;
31
+ /** Nx project name for the Helm chart. */
32
+ chartProject: string;
33
+ /** Values-key to Nx project mapping for direct stack image dependencies. */
34
+ applications: Record<string, string>;
35
+ /** Git repository identity used by generated Argo sources. */
36
+ repository: StackRepository | string;
37
+ /** Namespace prefix used for stable and pull-request destinations. */
38
+ namespacePrefix: string;
39
+ /** Explicit project-local values paths. */
40
+ values?: StackValueFiles;
41
+ /** Argo CD project assigned to generated Applications. */
42
+ argoProject?: string;
43
+ /** Optional ApplicationSet policy for GitHub pull-request previews. */
44
+ policy?: 'github-pr-preview';
45
+ /** GitHub token secret name used by the optional preview generator. */
46
+ githubTokenSecretName?: string;
47
+ /** GitHub token secret key used by the optional preview generator. */
48
+ githubTokenSecretKey?: string;
49
+ /** Pull-request label required by the optional preview generator. */
50
+ previewLabel?: string;
51
+ /** ApplicationSet pull-request polling interval in seconds. */
52
+ requeueAfterSeconds?: number;
53
+ /** Skip Prettier formatting after generation. */
54
+ skipFormat?: boolean;
55
+ }
@@ -0,0 +1,110 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "$id": "NxArgoStackProjectGeneratorSchema",
4
+ "title": "GitOps stack project generator",
5
+ "description": "Create one generic GitOps boundary for a Helm application stack.",
6
+ "type": "object",
7
+ "properties": {
8
+ "name": {
9
+ "type": "string",
10
+ "description": "Stack identity and generated directory suffix.",
11
+ "$default": { "source": "argv", "index": 0 },
12
+ "x-priority": "important"
13
+ },
14
+ "chartPath": {
15
+ "type": "string",
16
+ "description": "Workspace-relative Helm chart path used by Argo sources.",
17
+ "x-priority": "important"
18
+ },
19
+ "chartProject": {
20
+ "type": "string",
21
+ "description": "Nx project name for the Helm chart.",
22
+ "x-priority": "important"
23
+ },
24
+ "applications": {
25
+ "type": "object",
26
+ "description": "Values-key to Nx project mapping for stack image dependencies.",
27
+ "minProperties": 1,
28
+ "additionalProperties": { "type": "string", "minLength": 1 },
29
+ "x-priority": "important"
30
+ },
31
+ "repository": {
32
+ "description": "Repository URL or identity object used by Argo sources.",
33
+ "oneOf": [
34
+ { "type": "string", "minLength": 1 },
35
+ {
36
+ "type": "object",
37
+ "properties": {
38
+ "url": { "type": "string", "minLength": 1 },
39
+ "owner": { "type": "string", "minLength": 1 },
40
+ "name": { "type": "string", "minLength": 1 },
41
+ "revision": { "type": "string", "minLength": 1 }
42
+ },
43
+ "additionalProperties": false,
44
+ "minProperties": 1
45
+ }
46
+ ],
47
+ "x-priority": "important"
48
+ },
49
+ "namespacePrefix": {
50
+ "type": "string",
51
+ "description": "Namespace prefix for stable and pull-request destinations.",
52
+ "x-priority": "important"
53
+ },
54
+ "values": {
55
+ "type": "object",
56
+ "description": "Optional project-relative value-file paths.",
57
+ "properties": {
58
+ "staging": { "type": "string", "minLength": 1 },
59
+ "production": { "type": "string", "minLength": 1 },
60
+ "preview": { "type": "string", "minLength": 1 },
61
+ "pullRequest": { "type": "string", "minLength": 1 }
62
+ },
63
+ "additionalProperties": false
64
+ },
65
+ "argoProject": {
66
+ "type": "string",
67
+ "description": "Argo CD project assigned to generated Applications.",
68
+ "default": "default"
69
+ },
70
+ "policy": {
71
+ "type": "string",
72
+ "enum": ["github-pr-preview"],
73
+ "description": "Optional GitHub pull-request preview policy."
74
+ },
75
+ "githubTokenSecretName": {
76
+ "type": "string",
77
+ "description": "GitHub token secret name for the preview generator."
78
+ },
79
+ "githubTokenSecretKey": {
80
+ "type": "string",
81
+ "description": "GitHub token secret key for the preview generator.",
82
+ "default": "token"
83
+ },
84
+ "previewLabel": {
85
+ "type": "string",
86
+ "description": "Pull-request label required for preview generation.",
87
+ "default": "preview-ready"
88
+ },
89
+ "requeueAfterSeconds": {
90
+ "type": "integer",
91
+ "minimum": 1,
92
+ "description": "ApplicationSet pull-request polling interval in seconds.",
93
+ "default": 1800
94
+ },
95
+ "skipFormat": {
96
+ "type": "boolean",
97
+ "description": "Skip Prettier formatting after generation.",
98
+ "default": false
99
+ }
100
+ },
101
+ "required": [
102
+ "name",
103
+ "chartPath",
104
+ "chartProject",
105
+ "applications",
106
+ "repository",
107
+ "namespacePrefix"
108
+ ],
109
+ "additionalProperties": false
110
+ }
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { StackProjectGeneratorSchema } from './schema';
3
+ /** Creates one generic GitOps project boundary for a complete Helm stack. */
4
+ export default function stackProjectGenerator(tree: Tree, options: StackProjectGeneratorSchema): Promise<void>;