@otwld/nx-helm 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.
package/CHANGELOG.md CHANGED
@@ -1,3 +1,10 @@
1
+ ## Unreleased
2
+
3
+ ### Breaking Changes
4
+
5
+ - Build chart dependencies from the committed lockfile without refreshing Helm
6
+ repositories.
7
+
1
8
  ## 0.0.5 (2026-08-12)
2
9
 
3
10
  ### Breaking Changes
package/README.md CHANGED
@@ -22,17 +22,37 @@ charts/service/
22
22
  Generated projects use the `helm-<name>` project name. The `directory`,
23
23
  `projectName`, `starter`, and `tags` options customize generation.
24
24
 
25
+ ## Generate an Umbrella Stack
26
+
27
+ Use `stack` when one chart should package several app-owned charts and other
28
+ Helm dependencies:
29
+
30
+ ```shell
31
+ pnpm exec nx g @otwld/nx-helm:stack public \
32
+ --dependencies='[{"name":"public-app","version":"0.1.0","repository":"file://../../apps/public/chart","condition":"public-app.enabled"}]'
33
+ ```
34
+
35
+ The generator creates `charts/public/Chart.yaml`, `values.yaml`, a chart template,
36
+ and the `helm-public` Nx project marker. Run `helm dependency update charts/public`
37
+ after adding dependencies so the generated `Chart.lock` is committed; validation
38
+ and packaging then use `helm dependency build --skip-refresh`.
39
+
25
40
  ## Inferred Targets
26
41
 
27
42
  Charts with sibling `Chart.yaml` and `project.json` files receive these targets:
28
43
 
29
44
  - `helm:validate` runs `helm lint` and `helm template`.
30
45
  - `helm:package` packages the chart into `dist/<project-root>/helm`.
46
+ - `helm:dependency-build` is inferred when `Chart.yaml` declares dependencies.
47
+ It builds the dependency output before validation and packaging.
31
48
  - `nx-release-publish` is inferred only when an OCI registry is configured.
32
49
 
33
50
  Each inferred validate and package target is cacheable, declares its direct
34
51
  output where applicable, and includes the installed Helm version as a runtime
35
- input.
52
+ input. Local dependency directories are also inputs, and the dependency-build
53
+ target declares Helm's generated `charts` directory and `Chart.lock` as outputs.
54
+ Dependency builds use the committed lockfile without refreshing Helm repositories.
55
+ Charts without local dependencies keep the original target graph.
36
56
 
37
57
  ## Configuration
38
58
 
package/generators.json CHANGED
@@ -12,6 +12,11 @@
12
12
  "factory": "./src/generators/chart/chart",
13
13
  "schema": "./src/generators/chart/schema.json",
14
14
  "description": "Create a standalone Helm chart Nx project."
15
+ },
16
+ "stack": {
17
+ "factory": "./src/generators/stack/stack",
18
+ "schema": "./src/generators/stack/schema.json",
19
+ "description": "Create a generic Helm umbrella chart Nx project."
15
20
  }
16
21
  }
17
22
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@otwld/nx-helm",
3
- "version": "0.0.5",
3
+ "version": "0.0.7",
4
4
  "private": false,
5
5
  "type": "commonjs",
6
6
  "exports": {
@@ -0,0 +1,27 @@
1
+ /** A Helm dependency used by the umbrella chart generator. */
2
+ export interface StackDependency {
3
+ /** Dependency chart name and values key. */
4
+ name: string;
5
+ /** Semver version required by Chart.yaml. */
6
+ version: string;
7
+ /** Helm repository URL, including file:// for app-owned charts. */
8
+ repository: string;
9
+ /** Optional values condition controlling dependency rendering. */
10
+ condition?: string;
11
+ }
12
+
13
+ /** Options accepted by the generic Helm stack generator. */
14
+ export interface StackGeneratorSchema {
15
+ /** Stack chart name and directory suffix. */
16
+ name: string;
17
+ /** Parent directory for the generated chart. */
18
+ directory?: string;
19
+ /** Explicit Nx project name. */
20
+ projectName?: string;
21
+ /** Chart dependencies rendered by the umbrella chart. */
22
+ dependencies?: StackDependency[];
23
+ /** Nx project tags assigned to the chart. */
24
+ tags?: string[];
25
+ /** Skip Prettier formatting after generation. */
26
+ skipFormat?: boolean;
27
+ }
@@ -0,0 +1,50 @@
1
+ {
2
+ "$schema": "https://json-schema.org/schema",
3
+ "$id": "NxHelmStackGeneratorSchema",
4
+ "title": "Helm stack generator",
5
+ "description": "Create a generic Helm umbrella chart project.",
6
+ "type": "object",
7
+ "properties": {
8
+ "name": {
9
+ "type": "string",
10
+ "description": "Stack chart name and directory suffix.",
11
+ "$default": { "source": "argv", "index": 0 },
12
+ "x-priority": "important"
13
+ },
14
+ "directory": {
15
+ "type": "string",
16
+ "description": "Parent directory for the generated chart.",
17
+ "default": "charts"
18
+ },
19
+ "projectName": {
20
+ "type": "string",
21
+ "description": "Explicit Nx project name."
22
+ },
23
+ "dependencies": {
24
+ "type": "array",
25
+ "description": "Dependencies declared in the umbrella Chart.yaml.",
26
+ "items": {
27
+ "type": "object",
28
+ "properties": {
29
+ "name": { "type": "string", "minLength": 1 },
30
+ "version": { "type": "string", "minLength": 1 },
31
+ "repository": { "type": "string", "minLength": 1 },
32
+ "condition": { "type": "string", "minLength": 1 }
33
+ },
34
+ "required": ["name", "version", "repository"],
35
+ "additionalProperties": false
36
+ }
37
+ },
38
+ "tags": {
39
+ "type": "array",
40
+ "items": { "type": "string" },
41
+ "default": ["type:chart", "type:stack"]
42
+ },
43
+ "skipFormat": {
44
+ "type": "boolean",
45
+ "default": false
46
+ }
47
+ },
48
+ "required": ["name"],
49
+ "additionalProperties": false
50
+ }
@@ -0,0 +1,4 @@
1
+ import { type Tree } from '@nx/devkit';
2
+ import type { StackGeneratorSchema } from './schema';
3
+ /** Creates a generic Helm umbrella chart without repository-specific services. */
4
+ export default function stackGenerator(tree: Tree, options: StackGeneratorSchema): Promise<void>;
@@ -0,0 +1,214 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.default = stackGenerator;
4
+ const devkit_1 = require("@nx/devkit");
5
+ const yaml_1 = require("yaml");
6
+ /** Creates a generic Helm umbrella chart without repository-specific services. */
7
+ async function stackGenerator(tree, options) {
8
+ const chartName = normalizeName(options.name, 'name');
9
+ const projectRoot = (0, devkit_1.joinPathFragments)(options.directory?.trim() || 'charts', chartName);
10
+ const chartFile = (0, devkit_1.joinPathFragments)(projectRoot, 'Chart.yaml');
11
+ const projectName = options.projectName?.trim() || `helm-${chartName}`;
12
+ if (tree.exists(chartFile)) {
13
+ throw new Error(`[nx-helm] A Helm chart already exists at ${projectRoot}.`);
14
+ }
15
+ const dependencies = normalizeDependencies(options.dependencies);
16
+ tree.write(chartFile, (0, yaml_1.stringify)({
17
+ apiVersion: 'v2',
18
+ name: chartName,
19
+ description: `Umbrella chart for the ${chartName} application stack.`,
20
+ type: 'application',
21
+ version: '0.1.0',
22
+ appVersion: '0.1.0',
23
+ ...(dependencies.length ? { dependencies } : {}),
24
+ }, { lineWidth: 0 }));
25
+ tree.write((0, devkit_1.joinPathFragments)(projectRoot, 'values.yaml'), (0, yaml_1.stringify)(createValues(dependencies), { lineWidth: 0 }));
26
+ tree.write((0, devkit_1.joinPathFragments)(projectRoot, 'templates/mongodb-password.yaml'), createMongoPasswordTemplate());
27
+ tree.write((0, devkit_1.joinPathFragments)(projectRoot, 'templates/mongodb.yaml'), createMongoTemplate());
28
+ (0, devkit_1.writeJson)(tree, (0, devkit_1.joinPathFragments)(projectRoot, 'project.json'), {
29
+ name: projectName,
30
+ root: projectRoot,
31
+ projectType: 'application',
32
+ tags: options.tags?.length ? options.tags : ['type:chart', 'type:stack'],
33
+ metadata: { helm: { publish: false, releaseName: chartName } },
34
+ });
35
+ if (!options.skipFormat) {
36
+ await (0, devkit_1.formatFiles)(tree);
37
+ }
38
+ }
39
+ /** Builds the opinionated stack values contract for dependency toggles and MongoDB. */
40
+ function createValues(dependencies) {
41
+ const values = {
42
+ global: {
43
+ environment: 'local',
44
+ imagePullPolicy: 'IfNotPresent',
45
+ imagePullSecrets: [],
46
+ previewId: '',
47
+ previewDomain: '',
48
+ sourceRevision: '',
49
+ },
50
+ mongodb: {
51
+ enabled: false,
52
+ namespace: '',
53
+ version: '7.0.5',
54
+ storage: '8Gi',
55
+ secret: {
56
+ mode: 'generated',
57
+ encryptedData: { password: '' },
58
+ },
59
+ },
60
+ };
61
+ for (const dependency of dependencies) {
62
+ values[dependency.name] = { enabled: false };
63
+ }
64
+ return values;
65
+ }
66
+ /** Renders the generated or sealed MongoDB password contract. */
67
+ function createMongoPasswordTemplate() {
68
+ return `{{/* Render the stack's explicit MongoDB credential contract. */}}
69
+ {{- if .Values.mongodb.enabled }}
70
+ {{- $mode := default "generated" .Values.mongodb.secret.mode }}
71
+ {{- if eq $mode "sealed" }}
72
+ apiVersion: bitnami.com/v1alpha1
73
+ kind: SealedSecret
74
+ metadata:
75
+ name: mongodb-app-password
76
+ {{ with .Values.mongodb.namespace }}
77
+ namespace: {{ . | quote }}
78
+ {{ end }}
79
+ annotations:
80
+ {{ with .Values.mongodb.namespace }}
81
+ argocd.argoproj.io/tracking-id: {{ printf "%s:/Secret:%s/mongodb-app-password" . . | quote }}
82
+ {{ end }}
83
+ argocd.argoproj.io/sync-wave: '-10'
84
+ spec:
85
+ encryptedData:
86
+ password: {{ required "mongodb.secret.encryptedData.password is required for sealed credentials" (dig "encryptedData" "password" "" .Values.mongodb.secret) | quote }}
87
+ template:
88
+ metadata:
89
+ name: mongodb-app-password
90
+ {{ with .Values.mongodb.namespace }}
91
+ namespace: {{ . | quote }}
92
+ {{ end }}
93
+ annotations:
94
+ sealedsecrets.bitnami.com/managed: 'true'
95
+ type: Opaque
96
+ {{- else if eq $mode "generated" }}
97
+ apiVersion: v1
98
+ kind: Secret
99
+ metadata:
100
+ name: mongodb-app-password
101
+ {{ with .Values.mongodb.namespace }}
102
+ namespace: {{ . | quote }}
103
+ {{ end }}
104
+ annotations:
105
+ argocd.argoproj.io/sync-wave: '-10'
106
+ delivery.otwld.com/generated-secret: random
107
+ type: Opaque
108
+ data:
109
+ password: {{ randAlphaNum 32 | b64enc | quote }}
110
+ {{- else }}
111
+ {{- fail (printf "mongodb.secret.mode must be sealed or generated, got %q" $mode) }}
112
+ {{- end }}
113
+ {{- end }}
114
+ `;
115
+ }
116
+ /** Renders the opinionated MongoDBCommunity application contract. */
117
+ function createMongoTemplate() {
118
+ return `{{/* Render the opinionated MongoDBCommunity application contract. */}}
119
+ {{- if .Values.mongodb.enabled }}
120
+ apiVersion: mongodbcommunity.mongodb.com/v1
121
+ kind: MongoDBCommunity
122
+ metadata:
123
+ name: mongodb
124
+ {{ with .Values.mongodb.namespace }}
125
+ namespace: {{ . | quote }}
126
+ {{ end }}
127
+ spec:
128
+ members: 1
129
+ type: ReplicaSet
130
+ version: {{ .Values.mongodb.version | quote }}
131
+ security:
132
+ authentication:
133
+ modes:
134
+ - SCRAM
135
+ users:
136
+ - name: app
137
+ db: app
138
+ passwordSecretRef:
139
+ name: mongodb-app-password
140
+ key: password
141
+ roles:
142
+ - name: dbOwner
143
+ db: app
144
+ scramCredentialsSecretName: mongodb-app-scram
145
+ connectionStringSecretName: mongodb-app-connection
146
+ statefulSet:
147
+ spec:
148
+ template:
149
+ spec:
150
+ containers:
151
+ - name: mongod
152
+ resources:
153
+ limits: {}
154
+ requests: {}
155
+ - name: mongodb-agent
156
+ resources:
157
+ limits: {}
158
+ requests: {}
159
+ initContainers:
160
+ - name: mongod-posthook
161
+ resources:
162
+ limits: {}
163
+ requests: {}
164
+ - name: mongodb-agent-readinessprobe
165
+ resources:
166
+ limits: {}
167
+ requests: {}
168
+ volumeClaimTemplates:
169
+ - metadata:
170
+ name: data-volume
171
+ spec:
172
+ accessModes:
173
+ - ReadWriteOnce
174
+ resources:
175
+ requests:
176
+ storage: {{ .Values.mongodb.storage | quote }}
177
+ {{- end }}
178
+ `;
179
+ }
180
+ /** Normalizes dependency values while preserving Helm repository URLs. */
181
+ function normalizeDependencies(dependencies) {
182
+ if (!dependencies)
183
+ return [];
184
+ return dependencies.map((dependency, index) => {
185
+ if (!dependency || typeof dependency !== 'object') {
186
+ throw new Error(`[nx-helm] Dependency ${index} must be an object.`);
187
+ }
188
+ const name = normalizeName(dependency.name, `dependencies[${index}].name`);
189
+ const version = requireValue(dependency.version, `dependencies[${index}].version`);
190
+ const repository = requireValue(dependency.repository, `dependencies[${index}].repository`);
191
+ return {
192
+ name,
193
+ version,
194
+ repository,
195
+ ...(dependency.condition?.trim()
196
+ ? { condition: dependency.condition.trim() }
197
+ : {}),
198
+ };
199
+ });
200
+ }
201
+ /** Normalizes an identifier used by the chart and project paths. */
202
+ function normalizeName(value, label) {
203
+ const normalized = (0, devkit_1.names)(requireValue(value, label)).fileName;
204
+ if (!normalized)
205
+ throw new Error(`[nx-helm] A ${label} is required.`);
206
+ return normalized;
207
+ }
208
+ /** Requires a non-empty option. */
209
+ function requireValue(value, label) {
210
+ const normalized = value?.trim();
211
+ if (!normalized)
212
+ throw new Error(`[nx-helm] A ${label} is required.`);
213
+ return normalized;
214
+ }
package/src/index.d.ts CHANGED
@@ -2,3 +2,5 @@
2
2
  export { createNodes, type HelmPackageTargetOptions, type HelmPluginOptions, type HelmPublishTargetOptions, type HelmValidateTargetOptions, } from './plugins/plugin';
3
3
  export { default as chartGenerator } from './generators/chart/chart';
4
4
  export type { ChartGeneratorSchema } from './generators/chart/schema';
5
+ export { default as stackGenerator } from './generators/stack/stack';
6
+ export type { StackDependency, StackGeneratorSchema, } from './generators/stack/schema';
package/src/index.js CHANGED
@@ -3,9 +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.chartGenerator = exports.createNodes = void 0;
6
+ exports.stackGenerator = exports.chartGenerator = exports.createNodes = void 0;
7
7
  /** Public inferred-task, generator, and release exports for the Helm package. */
8
8
  var plugin_1 = require("./plugins/plugin");
9
9
  Object.defineProperty(exports, "createNodes", { enumerable: true, get: function () { return plugin_1.createNodes; } });
10
10
  var chart_1 = require("./generators/chart/chart");
11
11
  Object.defineProperty(exports, "chartGenerator", { enumerable: true, get: function () { return __importDefault(chart_1).default; } });
12
+ var stack_1 = require("./generators/stack/stack");
13
+ Object.defineProperty(exports, "stackGenerator", { enumerable: true, get: function () { return __importDefault(stack_1).default; } });
@@ -4,9 +4,11 @@ exports.createNodes = void 0;
4
4
  const devkit_1 = require("@nx/devkit");
5
5
  const node_fs_1 = require("node:fs");
6
6
  const node_path_1 = require("node:path");
7
+ const yaml_1 = require("yaml");
7
8
  const chartFilePattern = '**/Chart.yaml';
8
9
  const defaultValidateTargetName = 'helm:validate';
9
10
  const defaultPackageTargetName = 'helm:package';
11
+ const dependencyBuildTargetName = 'helm:dependency-build';
10
12
  const releasePublishTargetName = 'nx-release-publish';
11
13
  const defaultKubeVersion = '1.32.0';
12
14
  const helmInputs = [
@@ -51,6 +53,15 @@ function createNodesInternal(chartFilePath, options, context) {
51
53
  const validateTargetName = getTargetName(options.validate?.target, defaultValidateTargetName);
52
54
  const packageTargetName = getTargetName(options.package?.target, defaultPackageTargetName);
53
55
  const outputPath = getPackageOutputPath(chartRoot.projectRoot);
56
+ const dependencies = getChartDependencies(chartRoot.directory, context.workspaceRoot);
57
+ const chartInputs = [...helmInputs, ...dependencies.localInputs];
58
+ const dependencyInputs = [
59
+ '{projectRoot}/Chart.yaml',
60
+ '{projectRoot}/Chart.lock',
61
+ helmInputs[1],
62
+ ...dependencies.localInputs,
63
+ ];
64
+ const hasDependencies = dependencies.hasDependencies;
54
65
  const releaseName = project.metadata.releaseName?.trim() ||
55
66
  options.validate?.releaseName?.trim() ||
56
67
  project.name;
@@ -65,30 +76,47 @@ function createNodesInternal(chartFilePath, options, context) {
65
76
  if (validationValues?.length) {
66
77
  validateOptions['valuesFiles'] = validationValues;
67
78
  }
68
- const targets = {
69
- [validateTargetName]: {
70
- executor: '@otwld/nx-helm:validate',
79
+ const targets = {};
80
+ if (hasDependencies) {
81
+ targets[dependencyBuildTargetName] = {
82
+ executor: 'nx:run-commands',
71
83
  cache: true,
72
- inputs: helmInputs,
73
- options: validateOptions,
74
- metadata: {
75
- technologies: ['helm'],
76
- description: 'Lint and render the root Helm chart.',
77
- },
78
- },
79
- [packageTargetName]: {
80
- executor: '@otwld/nx-helm:package',
81
- cache: true,
82
- dependsOn: [validateTargetName],
83
- inputs: helmInputs,
84
- outputs: [`{workspaceRoot}/${outputPath}`],
84
+ inputs: dependencyInputs,
85
+ outputs: ['{projectRoot}/charts', '{projectRoot}/Chart.lock'],
85
86
  options: {
86
- outputPath,
87
+ command: 'helm dependency build --skip-refresh .',
88
+ cwd: chartRoot.projectRoot,
87
89
  },
88
90
  metadata: {
89
91
  technologies: ['helm'],
90
- description: 'Package the root Helm chart.',
92
+ description: 'Build local and remote Helm chart dependencies.',
91
93
  },
94
+ };
95
+ }
96
+ const dependencyTarget = hasDependencies ? [dependencyBuildTargetName] : [];
97
+ targets[validateTargetName] = {
98
+ executor: '@otwld/nx-helm:validate',
99
+ cache: true,
100
+ ...(dependencyTarget.length ? { dependsOn: dependencyTarget } : {}),
101
+ inputs: chartInputs,
102
+ options: validateOptions,
103
+ metadata: {
104
+ technologies: ['helm'],
105
+ description: 'Lint and render the root Helm chart.',
106
+ },
107
+ };
108
+ targets[packageTargetName] = {
109
+ executor: '@otwld/nx-helm:package',
110
+ cache: true,
111
+ dependsOn: [...dependencyTarget, validateTargetName],
112
+ inputs: chartInputs,
113
+ outputs: [`{workspaceRoot}/${outputPath}`],
114
+ options: {
115
+ outputPath,
116
+ },
117
+ metadata: {
118
+ technologies: ['helm'],
119
+ description: 'Package the root Helm chart.',
92
120
  },
93
121
  };
94
122
  const registry = normalizeRegistry(project.metadata.registry ?? options.publish?.registry);
@@ -104,6 +132,9 @@ function createNodesInternal(chartFilePath, options, context) {
104
132
  };
105
133
  }
106
134
  const targetNames = [validateTargetName, packageTargetName];
135
+ if (hasDependencies) {
136
+ targetNames.unshift(dependencyBuildTargetName);
137
+ }
107
138
  if (releasePublishTargetName in targets) {
108
139
  targetNames.push(releasePublishTargetName);
109
140
  }
@@ -122,6 +153,50 @@ function createNodesInternal(chartFilePath, options, context) {
122
153
  },
123
154
  };
124
155
  }
156
+ /**
157
+ * Finds declared chart dependencies and workspace-local dependency directories.
158
+ * @param chartDirectory Absolute chart directory.
159
+ * @param workspaceRoot Absolute workspace root.
160
+ * @returns Whether dependencies exist and Nx input globs for local content.
161
+ */
162
+ function getChartDependencies(chartDirectory, workspaceRoot) {
163
+ const chartFilePath = (0, node_path_1.join)(chartDirectory, 'Chart.yaml');
164
+ const document = (0, yaml_1.parseDocument)((0, node_fs_1.readFileSync)(chartFilePath, 'utf8'), {
165
+ prettyErrors: false,
166
+ });
167
+ if (document.errors.length > 0) {
168
+ throw new Error(`[nx-helm] Chart ${chartFilePath} contains invalid YAML: ${document.errors[0].message}`);
169
+ }
170
+ const manifest = document.toJS();
171
+ const dependencies = manifest.dependencies;
172
+ if (!Array.isArray(dependencies)) {
173
+ return { hasDependencies: false, localInputs: [] };
174
+ }
175
+ const paths = new Set();
176
+ for (const dependency of dependencies) {
177
+ if (!dependency ||
178
+ typeof dependency !== 'object' ||
179
+ Array.isArray(dependency)) {
180
+ continue;
181
+ }
182
+ const repository = dependency['repository'];
183
+ if (typeof repository !== 'string' || !repository.startsWith('file://')) {
184
+ continue;
185
+ }
186
+ const dependencyPath = (0, node_path_1.resolve)(chartDirectory, decodeURIComponent(repository.slice('file://'.length)));
187
+ const workspacePath = (0, node_path_1.relative)(workspaceRoot, dependencyPath)
188
+ .split(node_path_1.sep)
189
+ .join('/');
190
+ if (!workspacePath ||
191
+ workspacePath === '..' ||
192
+ workspacePath.startsWith('../') ||
193
+ (0, node_path_1.isAbsolute)(workspacePath)) {
194
+ continue;
195
+ }
196
+ paths.add(`{workspaceRoot}/${workspacePath}/**/*`);
197
+ }
198
+ return { hasDependencies: dependencies.length > 0, localInputs: [...paths] };
199
+ }
125
200
  /**
126
201
  * Resolves a Chart.yaml directory and verifies the standalone project marker.
127
202
  * @param chartFilePath Chart.yaml path matched by Nx.