hereya-cli 0.84.0 → 0.85.0

package/dist/backend/cloud/cloud-backend.js

@@ -109,8 +109,6 @@ export class CloudBackend {
             body.version = input.version;
         if (input.parameters)
             body.parameters = input.parameters;
-        if (input.hereyaVarsYaml !== undefined)
-            body.hereyaVarsYaml = input.hereyaVarsYaml;
         const response = await fetch(`${this.config.url}/api/apps/${encodeURIComponent(input.name)}/deployments`, {
             body: JSON.stringify(body),
             headers: {
@@ -207,6 +205,27 @@ export class CloudBackend {
         const result = await response.json();
         return { deployment: result.deployment, success: true };
     }
+    async getAppVersion(input) {
+        const url = input.version
+            ? `${this.config.url}/api/apps/${encodeURIComponent(input.name)}/versions/${encodeURIComponent(input.version)}`
+            : `${this.config.url}/api/apps/${encodeURIComponent(input.name)}/versions/latest`;
+        const response = await fetch(url, {
+            headers: { 'Authorization': `Bearer ${this.config.accessToken}` },
+            method: 'GET',
+        });
+        if (!response.ok) {
+            const error = await this.safeResponseJson(response);
+            let errorMessage = error.error || `Failed to get app version (status ${response.status})`;
+            if (response.status === 404) {
+                errorMessage = input.version
+                    ? `App version '${input.name}@${input.version}' not found`
+                    : `App '${input.name}' not found`;
+            }
+            return { reason: errorMessage, success: false };
+        }
+        const result = await response.json();
+        return { appVersion: result.appVersion ?? result.version, success: true };
+    }
     async getExecutorJobStatus(input) {
         const url = new URL(`${this.config.url}/api/workspaces/${encodeURIComponent(input.workspace)}/jobs/${encodeURIComponent(input.jobId)}`);
         if (input.poll) {
@@ -621,6 +640,8 @@ export class CloudBackend {
             requestBody.description = input.description;
         if (input.visibility !== undefined)
             requestBody.visibility = input.visibility;
+        if (input.parameters !== undefined)
+            requestBody.parameters = input.parameters;
         const response = await fetch(`${this.config.url}/api/apps/${encodeURIComponent(input.name)}/versions`, {
             body: JSON.stringify(requestBody),
             headers: {

package/dist/commands/app/deploy/index.d.ts

@@ -7,8 +7,6 @@ export default class AppDeploy extends Command {
     static examples: string[];
     static flags: {
         parameter: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
-        vars: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'vars-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         version: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
     };

package/dist/commands/app/deploy/index.js

@@ -1,8 +1,8 @@
 import { Args, Command, Flags } from '@oclif/core';
 import { ListrLogger, ListrLogLevels } from 'listr2';
-import fs from 'node:fs/promises';
 import { CloudBackend } from '../../../backend/cloud/cloud-backend.js';
 import { getBackend } from '../../../backend/index.js';
+import { resolveAppParameters } from '../../../lib/app-parameters.js';
 import { arrayOfStringToObject } from '../../../lib/object-utils.js';
 import { pollExecutorJob } from '../../../lib/remote-job-utils.js';
 export default class AppDeploy extends Command {
@@ -13,8 +13,7 @@ export default class AppDeploy extends Command {
     static examples = [
         '<%= config.bin %> <%= command.id %> my-org/my-app -w my-workspace',
         '<%= config.bin %> <%= command.id %> my-org/my-app -w prod --version 1.2.0',
-        '<%= config.bin %> <%= command.id %> my-org/my-app -w prod -V \'app.yaml: "key: value"\'',
-        '<%= config.bin %> <%= command.id %> my-org/my-app -w prod --vars-file ./hereyavars.yaml',
+        '<%= config.bin %> <%= command.id %> my-org/my-app -w prod -p organizationId=org-123',
     ];
     static flags = {
         parameter: Flags.string({
@@ -23,15 +22,6 @@ export default class AppDeploy extends Command {
             description: 'parameter for the app deployment, in the form of key=value (repeatable)',
             multiple: true,
         }),
-        vars: Flags.string({
-            char: 'V',
-            description: 'YAML string mapping hereyavars filename -> YAML body (mutually exclusive with --vars-file)',
-            exclusive: ['vars-file'],
-        }),
-        'vars-file': Flags.string({
-            description: 'path to a YAML file mapping hereyavars filename -> YAML body (mutually exclusive with --vars)',
-            exclusive: ['vars'],
-        }),
         version: Flags.string({
             description: 'specific app version to deploy (defaults to latest)',
         }),
@@ -49,27 +39,23 @@ export default class AppDeploy extends Command {
         }
         const cloudBackend = backend;
         const myLogger = new ListrLogger({ useIcons: false });
-        // Parse parameters
-        const parameters = arrayOfStringToObject(flags.parameter);
-        // Resolve hereyaVarsYaml
-        let hereyaVarsYaml;
-        if (flags.vars && flags['vars-file']) {
-            this.error('Cannot use both --vars and --vars-file at the same time.');
-        }
-        else if (flags.vars) {
-            hereyaVarsYaml = flags.vars;
+        // Parse user-provided parameters
+        const provided = arrayOfStringToObject(flags.parameter);
+        // Fetch the target version's declared parameters before submitting any cloud job.
+        const versionResult = await cloudBackend.getAppVersion({
+            name: args.name,
+            version: flags.version,
+        });
+        if (!versionResult.success) {
+            this.error(`Failed to resolve app version: ${versionResult.reason}`);
         }
-        else if (flags['vars-file']) {
-            try {
-                hereyaVarsYaml = await fs.readFile(flags['vars-file'], 'utf8');
-            }
-            catch (error) {
-                this.error(`Failed to read vars file ${flags['vars-file']}: ${error.message}`);
-            }
+        const declared = versionResult.appVersion.parameters ?? {};
+        const { errors, parameters } = resolveAppParameters({ declared, provided });
+        if (errors.length > 0) {
+            this.error(['Cannot deploy app due to parameter errors:', ...errors.map((e) => `  - ${e}`)].join('\n'));
         }
         myLogger.log(ListrLogLevels.STARTED, `Deploying ${args.name}${flags.version ? `@${flags.version}` : ''} to workspace ${flags.workspace}...`);
         const deployResult = await cloudBackend.deployApp({
-            hereyaVarsYaml,
             name: args.name,
             parameters: Object.keys(parameters).length > 0 ? parameters : undefined,
             version: flags.version,

package/dist/commands/executor/start/index.d.ts

@@ -30,4 +30,6 @@ export default class ExecutorStart extends Command {
     private executeInitJob;
     private executeJob;
     private markAppDeploymentFailed;
+    private readDeclaredParameters;
+    private resolveAndSubstituteParams;
 }

package/dist/commands/executor/start/index.js

@@ -10,8 +10,8 @@ import { saveCloudCredentials } from '../../../backend/config.js';
 import { clearBackend, getBackend } from '../../../backend/index.js';
 import { LocalExecutor } from '../../../executor/local.js';
 import { destroyPackage, provisionPackage } from '../../../infrastructure/index.js';
+import { resolveAppParameters, substituteAppParameters } from '../../../lib/app-parameters.js';
 import * as appSourceLib from '../../../lib/app-source.js';
-import { applyHereyaVars } from '../../../lib/app-vars.js';
 import { SimpleConfigManager } from '../../../lib/config/simple.js';
 import { cloneWithCredentialHelper, gitUtils } from '../../../lib/git-utils.js';
 import { runShell, shellUtils } from '../../../lib/shell.js';
@@ -64,6 +64,18 @@ function normalizePackageList(raw) {
     }
     return [];
 }
+async function runPreDeployCommand(input) {
+    if (!input.command)
+        return { success: true };
+    try {
+        input.logger.info('Running pre-deploy command...');
+        await runShell(input.command, [], { directory: input.directory, logger: input.logger });
+        return { success: true };
+    }
+    catch (error) {
+        return { reason: `pre-deploy command failed: ${error.message}`, success: false };
+    }
+}
 /**
  * Strip credentials from log strings before flushing them to the cloud.
  * Removes:
@@ -211,7 +223,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
     }
     async executeAppDeployJob(job, cloudBackend, logger) {
         const payload = job.payload;
-        const { appName, commit, hereyaVarsYaml, parameters, repository, sha256, version, workspace } = payload;
+        const { appName, commit, parameters: providedParameters, repository, sha256, version, workspace } = payload;
         if (!appName || !workspace || !repository) {
             return {
                 reason: 'Missing appName, workspace, or repository in app-deploy job payload',
@@ -224,17 +236,17 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             const downloadResult = await appSourceLib.appSource.download({ commit, logger, repository, sha256 });
             cleanup = downloadResult.cleanup;
             const { rootDir } = downloadResult;
-            // Apply hereyavars overrides
-            try {
-                const { filesWritten } = await applyHereyaVars(rootDir, hereyaVarsYaml);
-                if (filesWritten.length > 0) {
-                    logger.info(`Wrote ${filesWritten.length} hereyavars override file(s).`);
-                }
-            }
-            catch (error) {
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: error.message, workspace }, cloudBackend);
-                return { reason: `Failed to apply hereyavars overrides: ${error.message}`, success: false };
+            // Re-read declarations + substitute hereyavars before any package work.
+            const paramsResult = await this.resolveAndSubstituteParams({
+                logger,
+                provided: providedParameters,
+                rootDir,
+            });
+            if (!paramsResult.success) {
+                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: paramsResult.reason, workspace }, cloudBackend);
+                return { reason: paramsResult.reason, success: false };
             }
+            const { parameters: resolvedParameters } = paramsResult;
             // Read hereya.yaml from app source
             const hereyaYamlPath = await getAnyExisting(path.join(rootDir, 'hereya.yaml'), path.join(rootDir, 'hereya.yml'));
             if (!hereyaYamlPath) {
@@ -256,6 +268,15 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                 status: 'deploying',
                 workspace,
             });
+            const preDeployResult = await runPreDeployCommand({
+                command: parsedHereyaYaml.preDeployCommand,
+                directory: rootDir,
+                logger,
+            });
+            if (!preDeployResult.success) {
+                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: preDeployResult.reason, workspace }, cloudBackend);
+                return { reason: preDeployResult.reason, success: false };
+            }
             const mergedEnv = {};
             // 1) Provision regular packages
             /* eslint-disable no-await-in-loop */
@@ -264,7 +285,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                     isDeploying: true,
                     logger,
                     package: pkg.spec,
-                    parameters,
+                    parameters: resolvedParameters,
                     projectRootDir: rootDir,
                     workspace,
                 });
@@ -280,7 +301,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                     isDeploying: true,
                     logger,
                     package: pkg.spec,
-                    parameters,
+                    parameters: resolvedParameters,
                     projectEnv: { ...workspaceEnv, ...mergedEnv },
                     projectRootDir: rootDir,
                     workspace,
@@ -327,7 +348,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
     }
     async executeAppDestroyJob(job, cloudBackend, logger) {
         const payload = job.payload;
-        const { appName, commit, hereyaVarsYaml, parameters, repository, sha256, workspace } = payload;
+        const { appName, commit, parameters: providedParameters, repository, sha256, workspace } = payload;
         if (!appName || !workspace || !repository) {
             return {
                 reason: 'Missing appName, workspace, or repository in app-destroy job payload',
@@ -340,13 +361,22 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             const downloadResult = await appSourceLib.appSource.download({ commit, logger, repository, sha256 });
             cleanup = downloadResult.cleanup;
             const { rootDir } = downloadResult;
-            // Apply hereyavars overrides — destroy needs the same vars to drive Terraform.
-            try {
-                await applyHereyaVars(rootDir, hereyaVarsYaml);
-            }
-            catch (error) {
-                return { reason: `Failed to apply hereyavars overrides: ${error.message}`, success: false };
+            // Re-read declarations + substitute hereyavars before any package work.
+            const paramsResult = await this.resolveAndSubstituteParams({
+                logger,
+                provided: providedParameters,
+                rootDir,
+            });
+            if (!paramsResult.success) {
+                await cloudBackend.updateAppDeployment({
+                    lastJobId: job.id,
+                    name: appName,
+                    status: 'failed',
+                    workspace,
+                });
+                return { reason: paramsResult.reason, success: false };
             }
+            const { parameters: resolvedParameters } = paramsResult;
             const hereyaYamlPath = await getAnyExisting(path.join(rootDir, 'hereya.yaml'), path.join(rootDir, 'hereya.yml'));
             if (!hereyaYamlPath) {
                 return { reason: 'App source does not contain a hereya.yaml file', success: false };
@@ -361,6 +391,20 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                 status: 'destroying',
                 workspace,
             });
+            const preDeployResult = await runPreDeployCommand({
+                command: parsedHereyaYaml.preDeployCommand,
+                directory: rootDir,
+                logger,
+            });
+            if (!preDeployResult.success) {
+                await cloudBackend.updateAppDeployment({
+                    lastJobId: job.id,
+                    name: appName,
+                    status: 'failed',
+                    workspace,
+                });
+                return { reason: preDeployResult.reason, success: false };
+            }
             // Iterate in REVERSE: deploy packages first (depend on regular pkgs), then regular pkgs.
             const reversed = [...deployPackages.reverse(), ...packages.reverse()];
             const workspaceEnvResult = await cloudBackend.getWorkspaceEnv({ workspace });
@@ -371,7 +415,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                     isDeploying: true,
                     logger,
                     package: pkg.spec,
-                    parameters,
+                    parameters: resolvedParameters,
                     projectEnv: workspaceEnv,
                     projectRootDir: rootDir,
                     workspace,
@@ -741,4 +785,34 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             // best-effort; failure of the PATCH must not bubble out
         }
     }
+    async readDeclaredParameters(rootDir) {
+        const hereyarcPath = await getAnyExisting(path.join(rootDir, 'hereyarc.yaml'), path.join(rootDir, 'hereyarc.yml'));
+        if (!hereyarcPath) {
+            return {};
+        }
+        const content = await fs.readFile(hereyarcPath, 'utf8');
+        const parsed = (yaml.parse(content) ?? {});
+        return parsed.parameters ?? {};
+    }
+    async resolveAndSubstituteParams(input) {
+        const declared = await this.readDeclaredParameters(input.rootDir);
+        const resolved = resolveAppParameters({ declared, provided: input.provided });
+        if (resolved.errors.length > 0) {
+            return { reason: `Parameter validation failed: ${resolved.errors.join('; ')}`, success: false };
+        }
+        try {
+            const { filesWritten } = await substituteAppParameters({
+                declaredNames: Object.keys(declared),
+                parameters: resolved.parameters,
+                rootDir: input.rootDir,
+            });
+            if (filesWritten.length > 0) {
+                input.logger.info(`Substituted parameters in ${filesWritten.length} hereyavars file(s).`);
+            }
+        }
+        catch (error) {
+            return { reason: `Failed to substitute hereyavars parameters: ${error.message}`, success: false };
+        }
+        return { parameters: resolved.parameters, success: true };
+    }
 }

package/dist/commands/publish/index.d.ts

@@ -1,4 +1,5 @@
 import { Command } from '@oclif/core';
+import { IParameterSpec } from '../../lib/package/index.js';
 interface HereyarcConfig {
     description?: string;
     iac?: string;
@@ -9,6 +10,7 @@ interface HereyarcConfig {
         pkg: string;
         version: string;
     };
+    parameters?: Record<string, unknown>;
     version: string;
     visibility?: 'PRIVATE' | 'private' | 'PUBLIC' | 'public';
 }
@@ -28,6 +30,7 @@ export default class Publish extends Command {
     loadConfig(packageDir: string): Promise<HereyarcConfig>;
     loadReadme(packageDir: string): string | undefined;
     run(): Promise<void>;
+    validateAppParameters(rawParameters: unknown): Record<string, IParameterSpec>;
     validateConfig(config: HereyarcConfig): void;
     private publishApp;
 }

package/dist/commands/publish/index.js

@@ -5,6 +5,7 @@ import { simpleGit } from 'simple-git';
 import * as yaml from 'yaml';
 import { CloudBackend } from '../../backend/cloud/cloud-backend.js';
 import { getBackend } from '../../backend/index.js';
+import { PARAMETER_NAME_PATTERN, ParameterSpec } from '../../lib/package/index.js';
 export default class Publish extends Command {
     static description = 'Publish a package to the Hereya registry';
     static examples = [
@@ -225,6 +226,24 @@ export default class Publish extends Command {
             this.error(error instanceof Error ? error.message : String(error));
         }
     }
+    validateAppParameters(rawParameters) {
+        if (rawParameters === null || typeof rawParameters !== 'object' || Array.isArray(rawParameters)) {
+            this.error('hereyarc.yaml "parameters" must be a mapping of name -> spec');
+        }
+        const result = {};
+        for (const [name, rawSpec] of Object.entries(rawParameters)) {
+            if (!PARAMETER_NAME_PATTERN.test(name)) {
+                this.error(`Invalid parameter name '${name}' in hereyarc.yaml. Names must match ${PARAMETER_NAME_PATTERN.source}`);
+            }
+            const parsed = ParameterSpec.safeParse(rawSpec);
+            if (!parsed.success) {
+                const issues = parsed.error.issues.map((i) => i.message).join('; ');
+                this.error(`Invalid parameter '${name}' in hereyarc.yaml: ${issues}`);
+            }
+            result[name] = parsed.data;
+        }
+        return result;
+    }
     validateConfig(config) {
         if (!config.name) {
             this.error('Missing required field "name" in hereyarc.yaml');
@@ -291,11 +310,17 @@ export default class Publish extends Command {
         }
         this.log('   ✓ Authenticated with Hereya Cloud');
         this.log('\n📤 Publishing app version to registry...');
+        // Validate the parameters block (if any) against the zod schema before sending.
+        let validatedParameters;
+        if (config.parameters !== undefined) {
+            validatedParameters = this.validateAppParameters(config.parameters);
+        }
         const result = await backend.publishAppVersion({
             commit: commit.trim(),
             description: config.description,
             hereyaYaml: hereyaYamlContent,
             name: config.name,
+            ...(validatedParameters === undefined ? {} : { parameters: validatedParameters }),
             repository,
             sha256,
             version: config.version,

package/dist/lib/app-parameters.d.ts

@@ -0,0 +1,41 @@
+import { IParameterSpec } from './package/index.js';
+export interface ResolveAppParametersInput {
+    declared?: Record<string, IParameterSpec>;
+    provided?: Record<string, string>;
+}
+export interface ResolveAppParametersOutput {
+    errors: string[];
+    parameters: Record<string, string>;
+}
+/**
+ * Build the resolved parameter map for an app deployment by:
+ *   1. Starting with each declared parameter's `default` (if present).
+ *   2. Overlaying user-provided values (`-p key=value`).
+ *
+ * Validates:
+ *   - No unknown keys in `provided` (must match declared names).
+ *   - Every mandatory declared parameter ends up with a value.
+ *
+ * Multiple errors are aggregated; a non-empty `errors` array means the caller
+ * MUST refuse to submit the deploy.
+ */
+export declare function resolveAppParameters(input: ResolveAppParametersInput): ResolveAppParametersOutput;
+export interface SubstituteAppParametersInput {
+    declaredNames: string[];
+    parameters: Record<string, string>;
+    rootDir: string;
+}
+export interface SubstituteAppParametersOutput {
+    filesWritten: string[];
+}
+/**
+ * Walk `<rootDir>/hereyaconfig/hereyavars/` recursively. For every `*.yaml`
+ * or `*.yml` file, replace `{{name}}` for each (name, value) pair. After the
+ * pass, error if any leftover `{{<declaredName>}}` is found in the file.
+ *
+ * Replacement order: longest parameter name first, to avoid prefix collisions
+ * (e.g., `{{org}}` should not match part of `{{organization}}`).
+ *
+ * If the hereyavars directory doesn't exist, this is a no-op.
+ */
+export declare function substituteAppParameters(input: SubstituteAppParametersInput): Promise<SubstituteAppParametersOutput>;

package/dist/lib/app-parameters.js

@@ -0,0 +1,120 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Build the resolved parameter map for an app deployment by:
+ *   1. Starting with each declared parameter's `default` (if present).
+ *   2. Overlaying user-provided values (`-p key=value`).
+ *
+ * Validates:
+ *   - No unknown keys in `provided` (must match declared names).
+ *   - Every mandatory declared parameter ends up with a value.
+ *
+ * Multiple errors are aggregated; a non-empty `errors` array means the caller
+ * MUST refuse to submit the deploy.
+ */
+export function resolveAppParameters(input) {
+    const declared = input.declared ?? {};
+    const provided = input.provided ?? {};
+    const errors = [];
+    // Reject unknown keys
+    const declaredNames = new Set(Object.keys(declared));
+    const unknownKeys = [];
+    for (const key of Object.keys(provided)) {
+        if (!declaredNames.has(key)) {
+            unknownKeys.push(key);
+        }
+    }
+    if (unknownKeys.length > 0) {
+        errors.push(`Unknown parameter(s): ${unknownKeys.sort().join(', ')}. Declared parameters: ${[...declaredNames].sort().join(', ') || '(none)'}`);
+    }
+    // Build resolved map
+    const parameters = {};
+    // 1) Apply declared defaults
+    for (const [name, spec] of Object.entries(declared)) {
+        if (spec.default !== undefined) {
+            parameters[name] = spec.default;
+        }
+    }
+    // 2) Overlay provided values (only the declared ones — unknown keys reported above)
+    for (const [name, value] of Object.entries(provided)) {
+        if (declaredNames.has(name)) {
+            parameters[name] = value;
+        }
+    }
+    // Validate mandatory
+    const missingMandatory = [];
+    for (const [name, spec] of Object.entries(declared)) {
+        if (spec.mandatory && parameters[name] === undefined) {
+            missingMandatory.push(name);
+        }
+    }
+    if (missingMandatory.length > 0) {
+        errors.push(`Missing required parameter(s): ${missingMandatory
+            .sort()
+            .map((n) => `-p ${n}=<value>`)
+            .join(', ')}`);
+    }
+    return { errors, parameters };
+}
+/**
+ * Walk `<rootDir>/hereyaconfig/hereyavars/` recursively. For every `*.yaml`
+ * or `*.yml` file, replace `{{name}}` for each (name, value) pair. After the
+ * pass, error if any leftover `{{<declaredName>}}` is found in the file.
+ *
+ * Replacement order: longest parameter name first, to avoid prefix collisions
+ * (e.g., `{{org}}` should not match part of `{{organization}}`).
+ *
+ * If the hereyavars directory doesn't exist, this is a no-op.
+ */
+export async function substituteAppParameters(input) {
+    const { declaredNames, parameters, rootDir } = input;
+    const targetDir = path.join(rootDir, 'hereyaconfig', 'hereyavars');
+    let exists = true;
+    try {
+        await fs.access(targetDir);
+    }
+    catch {
+        exists = false;
+    }
+    if (!exists) {
+        return { filesWritten: [] };
+    }
+    // Sort substitution order: longest names first.
+    const sortedEntries = Object.entries(parameters).sort(([aName], [bName]) => bName.length - aName.length);
+    const filesWritten = [];
+    const yamlFiles = await collectYamlFiles(targetDir);
+    for (const filePath of yamlFiles) {
+        // eslint-disable-next-line no-await-in-loop
+        let content = await fs.readFile(filePath, 'utf8');
+        for (const [name, value] of sortedEntries) {
+            content = content.split(`{{${name}}}`).join(value);
+        }
+        // After substitution, error if any declared placeholder remains.
+        for (const name of declaredNames) {
+            if (content.includes(`{{${name}}}`)) {
+                throw new Error(`Unresolved parameter placeholder {{${name}}} remains in ${path.relative(rootDir, filePath)} after substitution`);
+            }
+        }
+        // eslint-disable-next-line no-await-in-loop
+        await fs.writeFile(filePath, content, { encoding: 'utf8' });
+        filesWritten.push(filePath);
+    }
+    return { filesWritten };
+}
+async function collectYamlFiles(dir) {
+    const out = [];
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // eslint-disable-next-line no-await-in-loop
+            const sub = await collectYamlFiles(full);
+            out.push(...sub);
+            continue;
+        }
+        if (entry.isFile() && (entry.name.endsWith('.yaml') || entry.name.endsWith('.yml'))) {
+            out.push(full);
+        }
+    }
+    return out;
+}

package/dist/lib/package/index.d.ts

@@ -31,6 +31,29 @@ export type ResolvePackageOutput = {
 };
 export declare const PackageKind: z.ZodDefault<z.ZodEnum<["app", "package"]>>;
 export type PackageKindType = z.infer<typeof PackageKind>;
+export declare const PARAMETER_NAME_PATTERN: RegExp;
+export declare const ParameterSpec: z.ZodEffects<z.ZodObject<{
+    default: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    mandatory: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    description?: string | undefined;
+    default?: string | undefined;
+    mandatory?: boolean | undefined;
+}, {
+    description?: string | undefined;
+    default?: string | undefined;
+    mandatory?: boolean | undefined;
+}>, {
+    description?: string | undefined;
+    default?: string | undefined;
+    mandatory?: boolean | undefined;
+}, {
+    description?: string | undefined;
+    default?: string | undefined;
+    mandatory?: boolean | undefined;
+}>;
+export type IParameterSpec = z.infer<typeof ParameterSpec>;
 export declare const PackageMetadata: z.ZodObject<{
     dependencies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     deploy: z.ZodOptional<z.ZodBoolean>;
@@ -51,12 +74,46 @@ export declare const PackageMetadata: z.ZodObject<{
     }>>;
     originalInfra: z.ZodOptional<z.ZodNativeEnum<typeof InfrastructureType>>;
     outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{}, "passthrough", z.ZodTypeAny, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">, z.objectInputType<{}, z.ZodTypeAny, "passthrough">>>>;
+    parameters: z.ZodEffects<z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        default: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        mandatory: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+    }, "strip", z.ZodTypeAny, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }>, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }>>>, Record<string, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }> | undefined, Record<string, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }> | undefined>;
     snakeCase: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     infra: InfrastructureType;
     iac: IacType;
     dependencies?: Record<string, string> | undefined;
     kind?: "package" | "app" | undefined;
+    parameters?: Record<string, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }> | undefined;
     deploy?: boolean | undefined;
     devDeploy?: boolean | undefined;
     inputs?: Record<string, z.objectOutputType<{}, z.ZodTypeAny, "passthrough">> | undefined;
@@ -72,6 +129,11 @@ export declare const PackageMetadata: z.ZodObject<{
     iac: IacType;
     dependencies?: Record<string, string> | undefined;
     kind?: "package" | "app" | undefined;
+    parameters?: Record<string, {
+        description?: string | undefined;
+        default?: string | undefined;
+        mandatory?: boolean | undefined;
+    }> | undefined;
     deploy?: boolean | undefined;
     devDeploy?: boolean | undefined;
     inputs?: Record<string, z.objectInputType<{}, z.ZodTypeAny, "passthrough">> | undefined;