hereya-cli 0.85.4 → 0.85.5

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

@@ -3,70 +3,22 @@ import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import * as yaml from 'yaml';
 import { CloudBackend } from '../../../backend/cloud/cloud-backend.js';
 import { loginWithToken } from '../../../backend/cloud/login.js';
 import { saveCloudCredentials } from '../../../backend/config.js';
 import { clearBackend, getBackend } from '../../../backend/index.js';
 import { LocalExecutor } from '../../../executor/local.js';
-import { resolveAppParameters, substituteAppParameters } from '../../../lib/app-parameters.js';
 import * as appSourceLib from '../../../lib/app-source.js';
 import { SimpleConfigManager } from '../../../lib/config/simple.js';
-import { getEnvManager } from '../../../lib/env/index.js';
 import { cloneWithCredentialHelper, gitUtils } from '../../../lib/git-utils.js';
-import { stripOrgPrefix } from '../../../lib/org-utils.js';
 import { runShell, shellUtils } from '../../../lib/shell.js';
-async function getAnyExisting(...candidates) {
-    for (const candidate of candidates) {
-        try {
-            // eslint-disable-next-line no-await-in-loop
-            await fs.access(candidate);
-            return candidate;
-        }
-        catch {
-            // try next
-        }
-    }
-    return undefined;
-}
-function normalizePackageList(raw) {
-    if (!raw)
-        return [];
-    if (Array.isArray(raw)) {
-        return raw
-            .filter((entry) => typeof entry === 'string' && entry.length > 0)
-            .map((entry) => {
-            const [name, version] = entry.split('@');
-            return {
-                name,
-                spec: entry,
-                version,
-            };
-        });
-    }
-    if (typeof raw === 'object') {
-        return Object.entries(raw).map(([name, info]) => {
-            const version = info?.version;
-            return {
-                name,
-                spec: version ? `${name}@${version}` : name,
-                version,
-            };
-        });
-    }
-    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 };
-    }
+/**
+ * Workspaces look like `org/name`, which is not filesystem-safe. The
+ * write-side in `app deploy --local` (commands/app/deploy/index.ts) MUST use
+ * the same sanitization.
+ */
+function sanitizeWorkspaceForFilename(workspace) {
+    return workspace.replaceAll('/', '-');
 }
 /**
  * Strip credentials from log strings before flushing them to the cloud.
@@ -213,12 +165,14 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
         }
         this.log('Executor stopped.');
     }
-    async executeAppDeployJob(job, cloudBackend, logger) {
+    async executeAppJob(job, cloudBackend, logger) {
+        const isDeploy = job.type === 'app-deploy';
+        const subcommand = isDeploy ? 'deploy' : 'destroy';
         const payload = job.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',
+                reason: `Missing appName, workspace, or repository in ${job.type} job payload`,
                 success: false,
             };
         }
@@ -228,128 +182,53 @@ 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;
-            // 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) {
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: 'Missing hereya.yaml', workspace }, cloudBackend);
-                return { reason: 'App source does not contain a hereya.yaml file', success: false };
-            }
-            const hereyaYamlContent = await fs.readFile(hereyaYamlPath, 'utf8');
-            const parsedHereyaYaml = (yaml.parse(hereyaYamlContent) ?? {});
-            // Build package lists
-            const packages = normalizePackageList(parsedHereyaYaml.packages);
-            const deployPackages = normalizePackageList(parsedHereyaYaml.deployPackages ?? parsedHereyaYaml.deploy);
-            // Mark deployment as deploying
+            // Mark deployment as deploying / destroying.
             await cloudBackend.updateAppDeployment({
                 lastJobId: job.id,
                 name: appName,
-                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 };
-            }
-            // Mirror project-deploy env machinery exactly:
-            //   1. Each regular pkg is provisioned in isolation. LocalExecutor.provision
-            //      auto-loads workspace env; pkg outputs are persisted via
-            //      envManager.addProjectEnv to .hereya/env.<workspace>.yaml.
-            //   2. projectEnv for deploy pkgs is built from envManager.getProjectEnv
-            //      (.hereya/env.<workspace>.yaml + .env + hereyaconfig/hereyastaticenv)
-            //      — explicitly NOT including workspace env. That keeps the deploy
-            //      Lambda env block under AWS's 4 KB limit.
-            //   3. deployEnv accumulates only deploy-package outputs and is the
-            //      AppDeployment's public env surface (cloud UI + `hereya app env`).
-            const executor = new LocalExecutor();
-            const envMgr = getEnvManager();
-            const deployEnv = {};
-            /* eslint-disable no-await-in-loop */
-            for (const pkg of packages) {
-                const result = await executor.provision({
-                    isDeploying: true,
-                    logger,
-                    package: pkg.spec,
-                    parameters: resolvedParameters,
-                    project: appName,
-                    projectRootDir: rootDir,
-                    workspace,
-                });
-                if (!result.success) {
-                    await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: result.reason, workspace }, cloudBackend);
-                    return { reason: `Failed to provision package ${pkg.name}: ${result.reason}`, success: false };
-                }
-                await envMgr.addProjectEnv({
-                    env: result.env,
-                    infra: result.metadata.originalInfra ?? result.metadata.infra,
-                    pkg: result.pkgName,
-                    projectRootDir: rootDir,
-                    snakeCase: result.metadata.snakeCase,
-                    workspace,
-                });
-            }
-            // Build projectEnv for deploy packages from saved per-package outputs.
-            const profile = stripOrgPrefix(workspace);
-            const projectEnvResult = await envMgr.getProjectEnv({
-                markSecret: true,
-                profile,
-                project: appName,
-                projectRootDir: rootDir,
+                status: isDeploy ? 'deploying' : 'destroying',
                 workspace,
             });
-            if (!projectEnvResult.success) {
-                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: projectEnvResult.reason, workspace }, cloudBackend);
-                return { reason: `Failed to build projectEnv: ${projectEnvResult.reason}`, success: false };
-            }
-            const projectEnv = projectEnvResult.env;
-            for (const pkg of deployPackages) {
-                const result = await executor.provision({
-                    isDeploying: true,
+            // Build -p flag args from job payload parameters.
+            const parameters = providedParameters ?? {};
+            const paramFlags = [];
+            for (const [key, value] of Object.entries(parameters)) {
+                paramFlags.push('-p', `${key}=${value}`);
+            }
+            // For app-deploy, forward --version so the local command can serialize it into
+            // the deploy-env file's `state` block (which the cloud reads back via PATCH).
+            const versionFlags = isDeploy && version ? ['--version', version] : [];
+            // Shell out to `hereya app <subcommand> <appName> -w <workspace> [-p ...] [--version ...] --local`.
+            // The local command holds the provisioning logic (mirrors deploy/undeploy shell-out pattern).
+            logger.info(`Running hereya app ${subcommand} ${appName} -w ${workspace} --local...`);
+            let runResult;
+            try {
+                runResult = await shellUtils.runShell('hereya', ['app', subcommand, appName, '-w', workspace, ...paramFlags, ...versionFlags, '--local'], {
+                    directory: rootDir,
+                    env: { ...process.env, HEREYA_LOCAL_EXECUTION: 'true', HEREYA_PROJECT_ROOT_DIR: rootDir },
                     logger,
-                    package: pkg.spec,
-                    parameters: resolvedParameters,
-                    project: appName,
-                    projectEnv,
-                    projectRootDir: rootDir,
-                    workspace,
                 });
-                if (!result.success) {
-                    await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: result.reason, workspace }, cloudBackend);
-                    return { reason: `Failed to provision deploy package ${pkg.name}: ${result.reason}`, success: false };
-                }
-                Object.assign(deployEnv, result.env);
             }
-            /* eslint-enable no-await-in-loop */
-            // 3) PATCH AppDeployment with final state — only deploy package outputs
-            const updateResult = await cloudBackend.updateAppDeployment({
-                env: deployEnv,
-                lastJobId: job.id,
-                name: appName,
-                state: {
-                    deployPackages: deployPackages.map((p) => ({ name: p.name, version: p.version })),
-                    packages: packages.map((p) => ({ name: p.name, version: p.version })),
-                    version,
-                },
-                status: 'deployed',
+            catch (error) {
+                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason: error.message, workspace }, cloudBackend);
+                return { reason: `hereya app ${subcommand} failed: ${error.message}`, success: false };
+            }
+            if (runResult && runResult.status !== 0) {
+                const reason = `hereya app ${subcommand} exited with code ${runResult.status}`;
+                await this.markAppDeploymentFailed({ appName, jobId: job.id, reason, workspace }, cloudBackend);
+                return { reason, success: false };
+            }
+            // PATCH final state to the cloud.
+            const patchResult = await this.patchAppFinalState({
+                appName,
+                cloudBackend,
+                isDeploy,
+                jobId: job.id,
+                rootDir,
                 workspace,
             });
-            if (!updateResult.success) {
-                return { reason: `Provisioning succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
+            if (!patchResult.success) {
+                return patchResult;
             }
             return { success: true };
         }
@@ -360,127 +239,7 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
             catch {
                 // best-effort
             }
-            return { reason: `app-deploy failed: ${error.message}`, success: false };
-        }
-        finally {
-            if (cleanup) {
-                await cleanup();
-            }
-        }
-    }
-    async executeAppDestroyJob(job, cloudBackend, logger) {
-        const payload = job.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',
-                success: false,
-            };
-        }
-        let cleanup;
-        try {
-            logger.info(`Downloading app source for destroy: ${repository}${commit ? `@${commit}` : ''}...`);
-            const downloadResult = await appSourceLib.appSource.download({ commit, logger, repository, sha256 });
-            cleanup = downloadResult.cleanup;
-            const { rootDir } = downloadResult;
-            // 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 };
-            }
-            const parsedHereyaYaml = (yaml.parse(await fs.readFile(hereyaYamlPath, 'utf8')) ?? {});
-            const packages = normalizePackageList(parsedHereyaYaml.packages);
-            const deployPackages = normalizePackageList(parsedHereyaYaml.deployPackages ?? parsedHereyaYaml.deploy);
-            // Mark deployment as destroying
-            await cloudBackend.updateAppDeployment({
-                lastJobId: job.id,
-                name: appName,
-                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 };
-            }
-            // Mirror project-destroy env machinery:
-            //   - LocalExecutor.destroy auto-loads workspace env.
-            //   - projectEnv for deploy-pkg destroy comes from envManager.getProjectEnv
-            //     (saved pkg outputs + .env + hereyastaticenv), NOT workspace env.
-            // Iterate in REVERSE: deploy packages first (depend on regular pkgs), then regular pkgs.
-            const executor = new LocalExecutor();
-            const envMgr = getEnvManager();
-            const profile = stripOrgPrefix(workspace);
-            const projectEnvResult = await envMgr.getProjectEnv({
-                markSecret: true,
-                profile,
-                project: appName,
-                projectRootDir: rootDir,
-                workspace,
-            });
-            const projectEnv = projectEnvResult.success ? projectEnvResult.env : {};
-            const reversed = [...deployPackages.reverse(), ...packages.reverse()];
-            /* eslint-disable no-await-in-loop */
-            for (const pkg of reversed) {
-                const result = await executor.destroy({
-                    isDeploying: true,
-                    logger,
-                    package: pkg.spec,
-                    parameters: resolvedParameters,
-                    project: appName,
-                    projectEnv,
-                    projectRootDir: rootDir,
-                    workspace,
-                });
-                if (!result.success) {
-                    await cloudBackend.updateAppDeployment({
-                        lastJobId: job.id,
-                        name: appName,
-                        status: 'failed',
-                        workspace,
-                    });
-                    return { reason: `Failed to destroy package ${pkg.name}: ${result.reason}`, success: false };
-                }
-            }
-            /* eslint-enable no-await-in-loop */
-            const updateResult = await cloudBackend.updateAppDeployment({
-                env: {},
-                lastJobId: job.id,
-                name: appName,
-                status: 'destroyed',
-                workspace,
-            });
-            if (!updateResult.success) {
-                return { reason: `Destroy succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
-            }
-            return { success: true };
-        }
-        catch (error) {
-            return { reason: `app-destroy failed: ${error.message}`, success: false };
+            return { reason: `app-${subcommand} failed: ${error.message}`, success: false };
         }
         finally {
             if (cleanup) {
@@ -750,30 +509,17 @@ Set the HEREYA_CLOUD_URL environment variable to target a specific hereya cloud
                 this.log(`Job ${job.id} ${initResult.success ? 'completed' : 'failed'} (init)`);
                 return;
             }
-            if (job.type === 'app-deploy') {
-                const appDeployResult = await this.executeAppDeployJob(job, cloudBackend, logger);
-                clearInterval(logInterval);
-                clearInterval(heartbeatInterval);
-                await cloudBackend.updateExecutorJob({
-                    jobId: job.id,
-                    logs: logBuffer,
-                    result: appDeployResult,
-                    status: appDeployResult.success ? 'completed' : 'failed',
-                });
-                this.log(`Job ${job.id} ${appDeployResult.success ? 'completed' : 'failed'} (app-deploy)`);
-                return;
-            }
-            if (job.type === 'app-destroy') {
-                const appDestroyResult = await this.executeAppDestroyJob(job, cloudBackend, logger);
+            if (job.type === 'app-deploy' || job.type === 'app-destroy') {
+                const appJobResult = await this.executeAppJob(job, cloudBackend, logger);
                 clearInterval(logInterval);
                 clearInterval(heartbeatInterval);
                 await cloudBackend.updateExecutorJob({
                     jobId: job.id,
                     logs: logBuffer,
-                    result: appDestroyResult,
-                    status: appDestroyResult.success ? 'completed' : 'failed',
+                    result: appJobResult,
+                    status: appJobResult.success ? 'completed' : 'failed',
                 });
-                this.log(`Job ${job.id} ${appDestroyResult.success ? 'completed' : 'failed'} (app-destroy)`);
+                this.log(`Job ${job.id} ${appJobResult.success ? 'completed' : 'failed'} (${job.type})`);
                 return;
             }
             const result = job.type === 'provision'
@@ -821,34 +567,45 @@ 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,
+    async patchAppFinalState(input) {
+        const { appName, cloudBackend, isDeploy, jobId, rootDir, workspace } = input;
+        if (!isDeploy) {
+            const updateResult = await cloudBackend.updateAppDeployment({
+                env: {},
+                lastJobId: jobId,
+                name: appName,
+                status: 'destroyed',
+                workspace,
             });
-            if (filesWritten.length > 0) {
-                input.logger.info(`Substituted parameters in ${filesWritten.length} hereyavars file(s).`);
+            if (!updateResult.success) {
+                return { reason: `Destroy succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
             }
+            return { success: true };
+        }
+        // Read .hereya/deploy-env.<workspace>.json that was written by `app deploy --local`.
+        // Filename sanitization MUST match the write side (see `sanitizeWorkspaceForFilename`).
+        const deployEnvFile = path.join(rootDir, '.hereya', `deploy-env.${sanitizeWorkspaceForFilename(workspace)}.json`);
+        let parsed;
+        try {
+            const content = await fs.readFile(deployEnvFile, 'utf8');
+            parsed = JSON.parse(content);
         }
         catch (error) {
-            return { reason: `Failed to substitute hereyavars parameters: ${error.message}`, success: false };
+            const reason = `Failed to read deploy env file at ${deployEnvFile}: ${error.message}`;
+            await this.markAppDeploymentFailed({ appName, jobId, reason, workspace }, cloudBackend);
+            return { reason, success: false };
+        }
+        const updateResult = await cloudBackend.updateAppDeployment({
+            env: parsed.env ?? {},
+            lastJobId: jobId,
+            name: appName,
+            state: parsed.state,
+            status: 'deployed',
+            workspace,
+        });
+        if (!updateResult.success) {
+            return { reason: `Provisioning succeeded but PATCH to deployment failed: ${updateResult.reason}`, success: false };
         }
-        return { parameters: resolved.parameters, success: true };
+        return { success: true };
     }
 }

package/dist/executor/interface.d.ts

@@ -2,6 +2,7 @@ import { InfrastructureType } from '../infrastructure/common.js';
 import { Logger } from '../lib/log.js';
 import { IPackageMetadata } from '../lib/package/index.js';
 export type ExecutorProvisionInput = {
+    app?: string;
     isDeploying?: boolean;
     logger?: Logger;
     package: string;

package/dist/executor/local.js

@@ -4,8 +4,10 @@ import { mintInstallationToken } from '../lib/github-app.js';
 import { resolvePackage } from '../lib/package/index.js';
 export class LocalExecutor {
     async destroy(input) {
+        // For apps, we use `app` as the project-name source for workspace env resolution
+        // (workspace name normalization just needs the org-prefixed scope name).
         const getWorkspaceEnvOutput = await this.getWorkspaceEnv({
-            project: input.project,
+            project: input.app ?? input.project,
             skipResolve: true,
             workspace: input.workspace,
         });
@@ -51,8 +53,10 @@ export class LocalExecutor {
         return { metadata, pkgName, success: true, version };
     }
     async provision(input) {
+        // For apps, we use `app` as the project-name source for workspace env resolution
+        // (workspace name normalization just needs the org-prefixed scope name).
         const getWorkspaceEnvOutput = await this.getWorkspaceEnv({
-            project: input.project,
+            project: input.app ?? input.project,
             skipResolve: true,
             workspace: input.workspace,
         });

package/dist/infrastructure/index.d.ts

@@ -10,7 +10,8 @@ export declare function resolveEnvValues(env: Record<string, string>): Promise<R
 export declare function getInfrastructure(input: GetInfrastructureInput): GetInfrastructureOutput;
 export declare function destroyPackage(input: DestroyPackageInput): Promise<DestroyPackageOutput>;
 export declare function provisionPackage(input: ProvisionPackageInput): Promise<ProvisionPackageOutput>;
-export declare function getProvisioningLogicalId({ pkg, project, workspace }: {
+export declare function getProvisioningLogicalId({ app, pkg, project, workspace }: {
+    app?: string;
     pkg: string;
     project?: string;
     workspace?: string;
@@ -18,6 +19,7 @@ export declare function getProvisioningLogicalId({ pkg, project, workspace }: {
 export type DestroyPackageInput = ProvisionPackageInput;
 export type DestroyPackageOutput = ProvisionPackageOutput;
 export type ProvisionPackageInput = {
+    app?: string;
     env?: {
         [key: string]: string;
     };

package/dist/infrastructure/index.js

@@ -43,6 +43,20 @@ export function getInfrastructure(input) {
         }
     }
 }
+/**
+ * When `input.app` is set, scope the provisioning row by `app` (workspace-scoped).
+ * Otherwise, scope by `project`. Apps and projects are mutually exclusive scopes
+ * for the cloud's provisioning-id row.
+ */
+function buildProvisioningIdInput({ canonicalName, input, pkgName }) {
+    return {
+        app: input.app,
+        logicalId: getProvisioningLogicalId({ app: input.app, pkg: pkgName, project: input.project, workspace: input.workspace }),
+        packageCanonicalName: canonicalName,
+        project: input.app ? undefined : input.project,
+        workspace: input.workspace,
+    };
+}
 export async function destroyPackage(input) {
     const resolvePackageOutput = await resolvePackage({ isDeploying: input.isDeploying, logger: input.logger, package: input.package, projectRootDir: input.projectRootDir });
     if (!resolvePackageOutput.found) {
@@ -62,12 +76,7 @@ export async function destroyPackage(input) {
     }
     const { infrastructure } = infrastructure$;
     const backend = await getBackend();
-    const id$ = await backend.getProvisioningId({
-        logicalId: getProvisioningLogicalId({ pkg: pkgName, project: input.project, workspace: input.workspace }),
-        packageCanonicalName: canonicalName,
-        project: input.project,
-        workspace: input.workspace,
-    });
+    const id$ = await backend.getProvisioningId(buildProvisioningIdInput({ canonicalName, input, pkgName }));
     if (!id$.success) {
         return { reason: id$.reason, success: false };
     }
@@ -214,12 +223,7 @@ export async function provisionPackage(input) {
     }
     const { infrastructure } = infrastructure$;
     const backend = await getBackend();
-    const id$ = await backend.getProvisioningId({
-        logicalId: getProvisioningLogicalId({ pkg: pkgName, project: input.project, workspace: input.workspace }),
-        packageCanonicalName: canonicalName,
-        project: input.project,
-        workspace: input.workspace,
-    });
+    const id$ = await backend.getProvisioningId(buildProvisioningIdInput({ canonicalName, input, pkgName }));
     if (!id$.success) {
         return { reason: id$.reason, success: false };
     }
@@ -233,8 +237,11 @@ export async function provisionPackage(input) {
     }
     return { env: provisionOutput.env, metadata, pkgName, success: true, version: version || '' };
 }
-export function getProvisioningLogicalId({ pkg, project, workspace }) {
-    const projectName = project ? stripOrgPrefix(project) : project;
+export function getProvisioningLogicalId({ app, pkg, project, workspace }) {
+    // Apps and projects are mutually exclusive scopes for the logical id. When `app` is set,
+    // the logical id is keyed by the app name (workspace-scoped, not project-scoped).
+    const scope = app ?? project;
+    const scopeName = scope ? stripOrgPrefix(scope) : scope;
     const workspaceName = workspace ? stripOrgPrefix(workspace) : workspace;
-    return [pkg.replaceAll('/', '.'), workspaceName, projectName].filter(Boolean).join('.');
+    return [pkg.replaceAll('/', '.'), workspaceName, scopeName].filter(Boolean).join('.');
 }

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

@@ -1,3 +1,4 @@
+import { Logger } from './log.js';
 import { IParameterSpec } from './package/index.js';
 export interface ResolveAppParametersInput {
     declared?: Record<string, IParameterSpec>;
@@ -39,3 +40,25 @@ export interface SubstituteAppParametersOutput {
  * If the hereyavars directory doesn't exist, this is a no-op.
  */
 export declare function substituteAppParameters(input: SubstituteAppParametersInput): Promise<SubstituteAppParametersOutput>;
+export interface ResolveAndSubstituteAppParamsInput {
+    logger?: Logger;
+    provided?: Record<string, string>;
+    rootDir: string;
+}
+export type ResolveAndSubstituteAppParamsOutput = {
+    parameters: Record<string, string>;
+    success: true;
+} | {
+    reason: string;
+    success: false;
+};
+/**
+ * Read declared parameters from `<rootDir>/hereyarc.yaml`, validate provided
+ * values against the declarations, then substitute `{{name}}` placeholders in
+ * any `hereyaconfig/hereyavars/*.yaml` files. Returns the resolved parameter
+ * map for the caller to forward to `executor.provision({parameters})`.
+ *
+ * Used by `hereya app deploy --local`, `hereya app destroy --local`, and the
+ * remote executor wrapper (which now shells out to those commands).
+ */
+export declare function resolveAndSubstituteAppParams(input: ResolveAndSubstituteAppParamsInput): Promise<ResolveAndSubstituteAppParamsOutput>;