@memberjunction/open-app-engine 5.41.0 → 5.43.0

package/dist/install/install-orchestrator.js

@@ -1,34 +1,36 @@
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { ParseAndValidateManifest } from '../manifest/manifest-loader.js';
 import { CheckMJVersionCompatibility, IsValidUpgrade } from '../dependency/version-checker.js';
 import { ResolveDependencyGraph } from '../dependency/dependency-graph-builder.js';
-import { FetchManifestFromGitHub, DownloadMigrations, GetLatestVersion, ValidateGitHubTag } from '../github/github-client.js';
+import { FetchManifestFromGitHub, DownloadMigrations, GetLatestVersion, ListGitHubReleases, ListGitHubTags, ValidateGitHubTag, ParseGitHubUrl } from '../github/github-client.js';
+import semver from 'semver';
 import { CreateAppSchema, DropAppSchema, SchemaExists, EscapeSqlString } from './schema-manager.js';
 import { RunAppMigrations } from './migration-runner.js';
 import { AddAppPackages, RemoveAppPackages, RunPackageInstall, BumpPrefixedDependencies } from './package-manager.js';
-import { AddServerDynamicPackages, RemoveServerDynamicPackages, ToggleServerDynamicPackages, AddEntityPackageMapping, RemoveEntityPackageMapping } from './config-manager.js';
+import { AddServerDynamicPackages, AddClientDynamicPackages, RemoveServerDynamicPackages, ToggleServerDynamicPackages, AddEntityPackageMapping, RemoveEntityPackageMapping } from './config-manager.js';
 import { AngularConfigManager } from './angular-config-manager.js';
-import { RegenerateClientBootstrap } from './client-bootstrap-gen.js';
 import { Metadata, RunView } from '@memberjunction/core';
-import { RecordAppInstallation, RecordInstallHistoryEntry, RecordAppDependencies, DeleteAppDependencies, SetAppStatus, FindInstalledApp, FindDependentApps, ListInstalledApps, UpdateAppRecord, } from './history-recorder.js';
+import { NormalizeUUID } from '@memberjunction/global';
+import { RecordAppInstallation, RecordInstallHistoryEntry, RecordAppDependencies, ReplaceAppDependenciesAtomically, SetAppStatus, FindInstalledApp, CheckSchemaSharedByOtherApps, FindDependentApps, ListInstalledApps, UpdateAppRecord, } from './history-recorder.js';
 export async function InstallApp(options, context) {
     const startTime = Date.now();
     const { Callbacks } = context;
     let createdAppId;
     let manifest;
+    const subpath = options.Subpath ?? ParseGitHubUrl(options.Source)?.Subpath;
     try {
         const explicitVersion = options.Version;
         if (explicitVersion) {
             Callbacks?.OnProgress?.('Fetch', `Validating version tag v${explicitVersion.replace(/^v/, '')} exists...`);
-            const tagResult = await ValidateGitHubTag(options.Source, explicitVersion, context.GitHubOptions);
+            const tagResult = await ValidateGitHubTag(options.Source, explicitVersion, context.GitHubOptions, subpath);
             if (!tagResult.Exists) {
                 return BuildFailureResult('Install', options.Source, '', 'Schema', startTime, tagResult.ErrorMessage ?? `Version ${explicitVersion} not found`);
             }
         }
         Callbacks?.OnProgress?.('Fetch', `Fetching manifest from ${options.Source}...`);
-        const fetchResult = await FetchManifestFromGitHub(options.Source, explicitVersion, context.GitHubOptions);
+        const fetchResult = await FetchManifestFromGitHub(options.Source, explicitVersion, context.GitHubOptions, subpath);
         if (!fetchResult.Success || !fetchResult.ManifestJSON) {
             return BuildFailureResult('Install', options.Source, '', 'Schema', startTime, fetchResult.ErrorMessage ?? 'Failed to fetch manifest');
         }
@@ -61,7 +63,7 @@ export async function InstallApp(options, context) {
             }
         }
         const existingApp = await FindInstalledApp(context.ContextUser, manifest.name);
-        const isReinstall = existingApp != null && existingApp.Status === 'Removed';
+        const isReinstall = existingApp != null && (existingApp.Status === 'Removed' || existingApp.Status === 'Error');
         if (existingApp && !isReinstall) {
             return BuildFailureResult('Install', manifest.name, manifest.version, 'Schema', startTime, `App '${manifest.name}' is already installed with status '${existingApp.Status}'. Use 'mj app upgrade' to update it.`);
         }
@@ -72,24 +74,24 @@ export async function InstallApp(options, context) {
             if (!schemaResult.Success) {
                 return BuildFailureResult('Install', manifest.name, manifest.version, 'Schema', startTime, schemaResult.ErrorMessage ?? 'Schema creation failed');
             }
-            schemaCreated = !isReinstall;
+            schemaCreated = schemaResult.Created === true;
         }
         if (manifest.migrations && manifest.schema) {
-            const migrationResult = await HandleMigrations(manifest, context);
+            const migrationResult = await HandleMigrations(manifest, context, subpath);
             if (!migrationResult.Success) {
                 await CompensateSchemaOnFailure(manifest, context, schemaCreated, options.AllowDoubleUnderscoreSchema === true, Callbacks);
                 return BuildFailureResult('Install', manifest.name, manifest.version, 'Migration', startTime, migrationResult.ErrorMessage ?? 'Migration failed');
             }
         }
         Callbacks?.OnProgress?.('Record', 'Recording app installation...');
-        const recordResult = await RecordInstallationAtomically(context.ContextUser, manifest, Callbacks);
+        const recordResult = await RecordInstallationAtomically(context.ContextUser, manifest, Callbacks, undefined, subpath);
         if (!recordResult.Success) {
             await CompensateSchemaOnFailure(manifest, context, schemaCreated, options.AllowDoubleUnderscoreSchema === true, Callbacks);
             return BuildFailureResult('Install', manifest.name, manifest.version, 'Record', startTime, recordResult.ErrorMessage ?? 'Failed to record installation');
         }
         createdAppId = recordResult.AppId;
         Callbacks?.OnProgress?.('Config', 'Updating configuration files...');
-        const pkgResult = await HandlePackageInstallation(manifest, context, effectivePackageVersion, effectiveVersionStrategy);
+        const pkgResult = await HandlePackageInstallation(manifest, context, effectivePackageVersion, effectiveVersionStrategy, options.Verbose);
         let npmInstallWarning;
         if (!pkgResult.Success) {
             if (pkgResult.PackageJsonUpdated) {
@@ -110,24 +112,38 @@ export async function InstallApp(options, context) {
         }
         HandleAngularPrebundleExcludes(manifest, context);
         Callbacks?.OnProgress?.('Record', 'Finalizing installation...');
-        await SetAppStatus(context.ContextUser, createdAppId, 'Active');
-        await HandleClientBootstrapRegeneration(context);
+        const finalStatus = npmInstallWarning ? 'Disabled' : 'Active';
+        await SetAppStatus(context.ContextUser, createdAppId, finalStatus);
+        if (finalStatus !== 'Active') {
+            ToggleServerDynamicPackages(context.RepoRoot, manifest.name, false);
+        }
         if (manifest.hooks?.postInstall) {
             Callbacks?.OnProgress?.('Hooks', 'Running postInstall hook...');
             await ExecuteHook(manifest.hooks.postInstall, context.RepoRoot);
         }
-        await RecordInstallHistoryEntry(context.ContextUser, createdAppId, 'Install', manifest, {
-            Success: true,
-            DurationSeconds: GetDurationSeconds(startTime),
-            StartedAt: new Date(startTime),
-            EndedAt: new Date(),
-            Summary: 'Initial installation',
-        });
+        try {
+            await RecordInstallHistoryEntry(context.ContextUser, createdAppId, 'Install', manifest, {
+                Success: true,
+                DurationSeconds: GetDurationSeconds(startTime),
+                StartedAt: new Date(startTime),
+                EndedAt: new Date(),
+                Summary: 'Initial installation',
+            });
+        }
+        catch (histErr) {
+            Callbacks?.OnWarn?.('Record', `App installed, but the history audit entry could not be written: ${histErr instanceof Error ? histErr.message : String(histErr)}`);
+        }
         Callbacks?.OnSuccess?.('Install', `Successfully installed ${manifest.name} v${manifest.version}`);
-        const baseSummary = 'App installed successfully. Restart MJAPI and rebuild MJExplorer to activate.';
-        const summary = npmInstallWarning
-            ? `${baseSummary}\n\n⚠ npm install failed — package.json and config files were updated but dependencies were not installed. Log in to npm ('npm login') or configure your .npmrc, then run 'npm install' to complete the setup.`
-            : baseSummary;
+        let summary;
+        if (npmInstallWarning) {
+            summary = `App installed but left DISABLED — npm install failed, so its packages are not resolved. package.json and config were updated; log in to npm ('npm login') or fix your .npmrc, run 'npm install', then 'mj app enable ${manifest.name}'.`;
+        }
+        else if (manifest.schema) {
+            summary = `App installed. Its schema and tables exist, but entity metadata is generated by CodeGen — run 'mj codegen', then restart MJAPI and rebuild MJExplorer to activate.`;
+        }
+        else {
+            summary = 'App installed successfully. Restart MJAPI and rebuild MJExplorer to activate.';
+        }
         return {
             Success: true,
             Action: 'Install',
@@ -151,11 +167,11 @@ export async function InstallApp(options, context) {
         return BuildFailureResult('Install', options.Source, '', 'Schema', startTime, message);
     }
 }
-async function RecordInstallationAtomically(contextUser, manifest, callbacks, provider) {
+async function RecordInstallationAtomically(contextUser, manifest, callbacks, provider, subpath) {
     const md = (provider ?? new Metadata());
     const tg = await md.CreateTransactionGroup();
     try {
-        const appId = await RecordAppInstallation(contextUser, manifest, callbacks, tg, 'Installing');
+        const appId = await RecordAppInstallation(contextUser, manifest, callbacks, tg, 'Installing', provider, subpath);
         if (manifest.dependencies) {
             await RecordAppDependencies(contextUser, appId, manifest.dependencies, tg);
         }
@@ -199,12 +215,12 @@ export async function UpgradeApp(options, context) {
         upgradeAppId = existingApp.ID;
         previousVersion = existingApp.Version;
         const explicitUpgradeVersion = options.Version;
-        const targetVersion = explicitUpgradeVersion ?? (await GetLatestVersion(existingApp.RepositoryURL, context.GitHubOptions));
+        const targetVersion = explicitUpgradeVersion ?? (await GetLatestVersion(existingApp.RepositoryURL, context.GitHubOptions, existingApp.Subpath ?? undefined));
         if (!targetVersion) {
             return BuildFailureResult('Upgrade', options.AppName, '', 'Schema', startTime, 'Could not determine target version');
         }
         if (explicitUpgradeVersion) {
-            const tagResult = await ValidateGitHubTag(existingApp.RepositoryURL, targetVersion, context.GitHubOptions);
+            const tagResult = await ValidateGitHubTag(existingApp.RepositoryURL, targetVersion, context.GitHubOptions, existingApp.Subpath ?? undefined);
             if (!tagResult.Exists) {
                 return BuildFailureResult('Upgrade', options.AppName, targetVersion, 'Schema', startTime, tagResult.ErrorMessage ?? `Version ${targetVersion} not found`);
             }
@@ -223,8 +239,9 @@ export async function UpgradeApp(options, context) {
                 Summary: upgradeCheck.Message ?? `Already at version ${targetVersion}`,
             };
         }
+        const subpath = existingApp.Subpath ?? undefined;
         Callbacks?.OnProgress?.('Fetch', `Fetching manifest for ${options.AppName} v${targetVersion}...`);
-        const fetchResult = await FetchManifestFromGitHub(existingApp.RepositoryURL, targetVersion, context.GitHubOptions);
+        const fetchResult = await FetchManifestFromGitHub(existingApp.RepositoryURL, targetVersion, context.GitHubOptions, subpath);
         if (!fetchResult.Success || !fetchResult.ManifestJSON) {
             return BuildFailureResult('Upgrade', options.AppName, targetVersion, 'Schema', startTime, fetchResult.ErrorMessage ?? 'Failed to fetch manifest');
         }
@@ -254,16 +271,21 @@ export async function UpgradeApp(options, context) {
         }
         await SetAppStatus(context.ContextUser, existingApp.ID, 'Upgrading');
         if (manifest.migrations && manifest.schema) {
-            const migrationResult = await HandleMigrations(manifest, context);
+            const migrationResult = await HandleMigrations(manifest, context, subpath);
             if (!migrationResult.Success) {
-                await RecordFailureHistory(context.ContextUser, existingApp.ID, 'Upgrade', manifest, 'Migration', migrationResult.ErrorMessage ?? 'Migration failed', startTime, previousVersion);
+                const detail = migrationResult.ErrorMessage ?? 'Migration failed';
+                const recoverable = `${detail}\n\nThe schema may be partially upgraded (migrations are forward-only; there is no ` +
+                    `automatic rollback). Skyway tracks applied migrations, so once the cause is fixed, re-run ` +
+                    `'mj app upgrade ${options.AppName}' to resume from the last successful migration. If the schema ` +
+                    `is left inconsistent, restore it from a backup taken before the upgrade.`;
+                await RecordFailureHistory(context.ContextUser, existingApp.ID, 'Upgrade', manifest, 'Migration', recoverable, startTime, previousVersion);
                 await SetAppStatus(context.ContextUser, existingApp.ID, 'Error');
-                return BuildFailureResult('Upgrade', options.AppName, targetVersion, 'Migration', startTime, migrationResult.ErrorMessage ?? 'Migration failed');
+                return BuildFailureResult('Upgrade', options.AppName, targetVersion, 'Migration', startTime, recoverable);
             }
         }
         const effectiveUpgradeVersion = explicitUpgradeVersion ? targetVersion.replace(/^v/, '') : manifest.version;
         const effectiveUpgradeStrategy = explicitUpgradeVersion ? 'exact' : context.VersionStrategy;
-        const pkgResult = await HandlePackageInstallation(manifest, context, effectiveUpgradeVersion, effectiveUpgradeStrategy);
+        const pkgResult = await HandlePackageInstallation(manifest, context, effectiveUpgradeVersion, effectiveUpgradeStrategy, options.Verbose);
         let npmInstallWarning;
         if (!pkgResult.Success) {
             if (pkgResult.PackageJsonUpdated) {
@@ -288,23 +310,29 @@ export async function UpgradeApp(options, context) {
             ManifestJSON: JSON.stringify(manifest),
             Status: 'Active',
         });
-        await HandleClientBootstrapRegeneration(context);
         if (manifest.hooks?.postUpgrade) {
             Callbacks?.OnProgress?.('Hooks', 'Running postUpgrade hook...');
             await ExecuteHook(manifest.hooks.postUpgrade, context.RepoRoot);
         }
         if (manifest.dependencies) {
-            await DeleteAppDependencies(context.ContextUser, existingApp.ID);
-            await RecordAppDependencies(context.ContextUser, existingApp.ID, manifest.dependencies);
+            const depsReplaced = await ReplaceAppDependenciesAtomically(context.ContextUser, existingApp.ID, manifest.dependencies);
+            if (!depsReplaced) {
+                Callbacks?.OnWarn?.('Record', 'App upgraded, but its dependency records could not be updated atomically — re-run the upgrade to refresh them.');
+            }
+        }
+        try {
+            await RecordInstallHistoryEntry(context.ContextUser, existingApp.ID, 'Upgrade', manifest, {
+                PreviousVersion: previousVersion,
+                Success: true,
+                DurationSeconds: GetDurationSeconds(startTime),
+                StartedAt: new Date(startTime),
+                EndedAt: new Date(),
+                Summary: `Upgraded from ${previousVersion} to ${manifest.version}`,
+            });
+        }
+        catch (histErr) {
+            Callbacks?.OnWarn?.('Record', `App upgraded, but the history audit entry could not be written: ${histErr instanceof Error ? histErr.message : String(histErr)}`);
         }
-        await RecordInstallHistoryEntry(context.ContextUser, existingApp.ID, 'Upgrade', manifest, {
-            PreviousVersion: previousVersion,
-            Success: true,
-            DurationSeconds: GetDurationSeconds(startTime),
-            StartedAt: new Date(startTime),
-            EndedAt: new Date(),
-            Summary: `Upgraded from ${previousVersion} to ${manifest.version}`,
-        });
         Callbacks?.OnSuccess?.('Upgrade', `Successfully upgraded ${options.AppName} to v${manifest.version}`);
         const baseSummary = `Upgraded from ${previousVersion} to ${manifest.version}. Restart MJAPI and rebuild MJExplorer.`;
         const summary = npmInstallWarning
@@ -359,15 +387,73 @@ export async function RemoveApp(options, context) {
             Callbacks?.OnProgress?.('Hooks', 'Running preRemove hook...');
             await ExecuteHook(manifest.hooks.preRemove, context.RepoRoot);
         }
+        const shareCheck = existingApp.SchemaName
+            ? await CheckSchemaSharedByOtherApps(context.ContextUser, existingApp.SchemaName, existingApp.ID)
+            : { Shared: false, CheckFailed: false };
+        const schemaShared = shareCheck.Shared;
+        const shareCheckError = shareCheck.CheckFailed
+            ? `Could not determine whether schema '${existingApp.SchemaName}' is shared by other Open Apps (share-check query failed): ${shareCheck.ErrorMessage ?? 'unknown error'}`
+            : undefined;
+        if (schemaShared && !shareCheck.CheckFailed) {
+            Callbacks?.OnWarn?.('Schema', `Schema '${existingApp.SchemaName}' is still used by another installed Open App — skipping metadata + schema removal to protect co-tenant data.`);
+        }
+        let metadataResult = { Success: true };
+        if (existingApp.SchemaName && !schemaShared) {
+            Callbacks?.OnProgress?.('Metadata', `Removing entity metadata for schema '${existingApp.SchemaName}'...`);
+            metadataResult = await RemoveAppEntityMetadata(existingApp.SchemaName, context.ContextUser, Callbacks);
+        }
+        let teardownResult = { Success: true };
+        if (!options.KeepData) {
+            teardownResult = await HandleTeardown(manifest, context, existingApp.Subpath ?? undefined);
+            if (!teardownResult.Success) {
+                Callbacks?.OnError?.('Metadata', `Teardown failed: ${teardownResult.ErrorMessage}`);
+            }
+        }
+        let schemaDropError;
+        if (!options.KeepData && existingApp.SchemaName && !schemaShared) {
+            Callbacks?.OnProgress?.('Schema', `Dropping schema '${existingApp.SchemaName}'...`);
+            const dropResult = await DropAppSchema(existingApp.SchemaName, context.DatabaseProvider, {
+                allowDoubleUnderscore: options.AllowDoubleUnderscoreSchema === true,
+            });
+            if (!dropResult.Success) {
+                schemaDropError = dropResult.ErrorMessage;
+                Callbacks?.OnError?.('Schema', `Failed to drop schema: ${dropResult.ErrorMessage}`);
+            }
+        }
+        const removalErrors = [
+            shareCheckError,
+            teardownResult.Success ? undefined : teardownResult.ErrorMessage,
+            metadataResult.Success ? undefined : metadataResult.ErrorMessage,
+            schemaDropError,
+        ].filter((e) => !!e);
+        if (removalErrors.length > 0) {
+            const combined = removalErrors.join('; ');
+            await RecordInstallHistoryEntry(context.ContextUser, existingApp.ID, 'Remove', manifest, {
+                Success: false,
+                DurationSeconds: GetDurationSeconds(startTime),
+                StartedAt: new Date(startTime),
+                EndedAt: new Date(),
+                Summary: `Remove failed: ${combined}`,
+            });
+            await SetAppStatus(context.ContextUser, existingApp.ID, 'Error');
+            return BuildFailureResult('Remove', options.AppName, existingApp.Version, 'Schema', startTime, combined);
+        }
         Callbacks?.OnProgress?.('Config', 'Removing config, client bootstrap, and package references...');
         const otherApps = (await ListInstalledApps(context.ContextUser))
             .filter(a => a.Name !== options.AppName && a.Status !== 'Removed');
-        const otherManifests = otherApps.map(a => JSON.parse(a.ManifestJSON));
+        const otherManifests = otherApps.flatMap(a => {
+            try {
+                return [JSON.parse(a.ManifestJSON)];
+            }
+            catch {
+                Callbacks?.OnWarn?.('Config', `Ignoring app '${a.Name}' when computing shared excludes — its ManifestJSON could not be parsed.`);
+                return [];
+            }
+        });
         await Promise.all([
             Promise.resolve(RemoveServerDynamicPackages(context.RepoRoot, options.AppName)),
             Promise.resolve(manifest.schema ? RemoveEntityPackageMapping(context.RepoRoot, manifest.schema.name) : undefined),
             Promise.resolve(HandleAngularPrebundleExcludeRemoval(manifest, otherManifests, context)),
-            HandleClientBootstrapRegeneration(context),
             Promise.resolve(RemoveAppPackages({
                 RepoRoot: context.RepoRoot,
                 ServerPackages: manifest.packages?.server ?? [],
@@ -385,26 +471,18 @@ export async function RemoveApp(options, context) {
         if (!installResult.Success) {
             Callbacks?.OnWarn?.('Packages', `Package install warning during removal: ${installResult.ErrorMessage}`);
         }
-        if (existingApp.SchemaName) {
-            Callbacks?.OnProgress?.('Metadata', `Removing entity metadata for schema '${existingApp.SchemaName}'...`);
-            await RemoveAppEntityMetadata(existingApp.SchemaName, context.ContextUser, Callbacks);
-        }
-        if (!options.KeepData && existingApp.SchemaName) {
-            Callbacks?.OnProgress?.('Schema', `Dropping schema '${existingApp.SchemaName}'...`);
-            const dropResult = await DropAppSchema(existingApp.SchemaName, context.DatabaseProvider, {
-                allowDoubleUnderscore: options.AllowDoubleUnderscoreSchema === true,
+        try {
+            await RecordInstallHistoryEntry(context.ContextUser, existingApp.ID, 'Remove', manifest, {
+                Success: true,
+                DurationSeconds: GetDurationSeconds(startTime),
+                StartedAt: new Date(startTime),
+                EndedAt: new Date(),
+                Summary: options.KeepData ? 'Removed (data kept)' : 'Removed (data dropped)',
             });
-            if (!dropResult.Success) {
-                Callbacks?.OnWarn?.('Schema', `Failed to drop schema: ${dropResult.ErrorMessage}`);
-            }
         }
-        await RecordInstallHistoryEntry(context.ContextUser, existingApp.ID, 'Remove', manifest, {
-            Success: true,
-            DurationSeconds: GetDurationSeconds(startTime),
-            StartedAt: new Date(startTime),
-            EndedAt: new Date(),
-            Summary: options.KeepData ? 'Removed (data kept)' : 'Removed (data dropped)',
-        });
+        catch (histErr) {
+            Callbacks?.OnWarn?.('Record', `App removed, but the history audit entry could not be written: ${histErr instanceof Error ? histErr.message : String(histErr)}`);
+        }
         await UpdateAppRecord(context.ContextUser, existingApp.ID, {
             Status: 'Removed',
         });
@@ -440,9 +518,11 @@ export async function DisableApp(appName, context) {
     if (!app) {
         return BuildFailureResult('Install', appName, '', 'Config', startTime, `App '${appName}' is not installed`);
     }
-    ToggleServerDynamicPackages(context.RepoRoot, appName, false);
+    const toggle = ToggleServerDynamicPackages(context.RepoRoot, appName, false);
+    if (!toggle.Success) {
+        return BuildFailureResult('Install', appName, app.Version, 'Config', startTime, toggle.ErrorMessage ?? 'Failed to update dynamicPackages.server in mj.config.cjs');
+    }
     await SetAppStatus(context.ContextUser, app.ID, 'Disabled');
-    await HandleClientBootstrapRegeneration(context);
     return {
         Success: true,
         Action: 'Install',
@@ -458,9 +538,11 @@ export async function EnableApp(appName, context) {
     if (!app) {
         return BuildFailureResult('Install', appName, '', 'Config', startTime, `App '${appName}' is not installed`);
     }
-    ToggleServerDynamicPackages(context.RepoRoot, appName, true);
+    const toggle = ToggleServerDynamicPackages(context.RepoRoot, appName, true);
+    if (!toggle.Success) {
+        return BuildFailureResult('Install', appName, app.Version, 'Config', startTime, toggle.ErrorMessage ?? 'Failed to update dynamicPackages.server in mj.config.cjs');
+    }
     await SetAppStatus(context.ContextUser, app.ID, 'Active');
-    await HandleClientBootstrapRegeneration(context);
     return {
         Success: true,
         Action: 'Install',
@@ -492,12 +574,12 @@ async function ResolveDependencyChain(manifest, context) {
     }
     const depsToInstall = (result.InstallOrder ?? [])
         .filter((d) => !d.AlreadyInstalled)
-        .map((d) => ({ AppName: d.AppName, Repository: d.Repository, VersionRange: d.VersionRange }));
+        .map((d) => ({ AppName: d.AppName, Repository: d.Repository, VersionRange: d.VersionRange, Subpath: d.Subpath }));
     return { Success: true, DepsToInstall: depsToInstall };
 }
 function BuildManifestFetcher(context) {
-    return async (repoUrl) => {
-        const fetched = await FetchManifestFromGitHub(repoUrl, undefined, context.GitHubOptions);
+    return async (repoUrl, subpath) => {
+        const fetched = await FetchManifestFromGitHub(repoUrl, undefined, context.GitHubOptions, subpath);
         if (!fetched.Success || !fetched.ManifestJSON) {
             return { Success: false, ErrorMessage: fetched.ErrorMessage ?? 'Failed to fetch manifest' };
         }
@@ -524,8 +606,14 @@ async function InstallDependencies(deps, context, inherited) {
             };
         }
         context.Callbacks?.OnProgress?.('Dependencies', `Installing dependency from ${dep.Repository}...`);
+        const resolved = await ResolveDependencyVersion(dep.Repository, dep.VersionRange, context.GitHubOptions);
+        if (resolved.ErrorMessage) {
+            return { Success: false, ErrorMessage: `Cannot install dependency '${dep.AppName}': ${resolved.ErrorMessage}` };
+        }
         const result = await InstallApp({
             Source: dep.Repository,
+            Subpath: dep.Subpath,
+            Version: resolved.Version,
             _skipDependencyResolution: true,
             AllowDoubleUnderscoreSchema: inherited.AllowDoubleUnderscoreSchema,
             Verbose: inherited.Verbose,
@@ -536,6 +624,35 @@ async function InstallDependencies(deps, context, inherited) {
     }
     return { Success: true };
 }
+export async function ResolveDependencyVersion(repoUrl, versionRange, options) {
+    const range = (versionRange ?? '').trim();
+    if (range === '' || range === '*' || range.toLowerCase() === 'latest') {
+        return { Version: undefined };
+    }
+    if (semver.valid(range)) {
+        return { Version: range.replace(/^v/, '') };
+    }
+    if (!semver.validRange(range)) {
+        return { ErrorMessage: `version '${versionRange}' is not a valid semver version or range` };
+    }
+    const [releases, tags] = await Promise.all([
+        ListGitHubReleases(repoUrl, options),
+        ListGitHubTags(repoUrl, options),
+    ]);
+    const candidates = [
+        ...releases.filter((r) => !r.Draft).map((r) => r.TagName.replace(/^v/, '')),
+        ...tags.map((t) => t.replace(/^v/, '')),
+    ].filter((v) => semver.valid(v) != null);
+    if (candidates.length === 0) {
+        return { ErrorMessage: `no published versions found at ${repoUrl} to satisfy '${versionRange}'` };
+    }
+    const best = semver.maxSatisfying(candidates, range);
+    if (!best) {
+        const latest = candidates.sort(semver.rcompare)[0];
+        return { ErrorMessage: `no published version at ${repoUrl} satisfies '${versionRange}' (latest available: ${latest})` };
+    }
+    return { Version: best };
+}
 async function HandleSchemaCreation(manifest, context, isReinstall = false, allowDoubleUnderscore = false) {
     if (!manifest.schema) {
         return { Success: true };
@@ -545,25 +662,26 @@ async function HandleSchemaCreation(manifest, context, isReinstall = false, allo
     if (exists) {
         if (isReinstall || manifest.schema.createIfNotExists !== false) {
             context.Callbacks?.OnProgress?.('Schema', `Reusing existing schema '${manifest.schema.name}'`);
-            return { Success: true };
+            return { Success: true, Created: false };
         }
         return { Success: false, ErrorMessage: `Schema '${manifest.schema.name}' already exists` };
     }
     if (manifest.schema.createIfNotExists !== false) {
         context.Callbacks?.OnProgress?.('Schema', `Creating schema '${manifest.schema.name}'...`);
         const result = await CreateAppSchema(manifest.schema.name, context.DatabaseProvider, { allowDoubleUnderscore });
-        return { Success: result.Success, ErrorMessage: result.ErrorMessage };
+        return { Success: result.Success, ErrorMessage: result.ErrorMessage, Created: result.Success };
     }
     return { Success: false, ErrorMessage: `Schema '${manifest.schema.name}' does not exist and createIfNotExists is false` };
 }
-async function HandleMigrations(manifest, context) {
+async function HandleMigrations(manifest, context, subpath) {
     if (!manifest.schema || !manifest.migrations) {
         return { Success: true };
     }
     context.Callbacks?.OnProgress?.('Migration', 'Downloading migration files...');
     const tempDir = join(tmpdir(), `mj-app-${manifest.name}-${Date.now()}`);
     mkdirSync(tempDir, { recursive: true });
-    const downloadResult = await DownloadMigrations(manifest.repository, manifest.version, manifest.migrations.directory, tempDir, context.GitHubOptions);
+    const platform = context.DatabaseProvider.Dialect.PlatformKey;
+    const downloadResult = await DownloadAppMigrations(manifest, context, tempDir, subpath);
     if (!downloadResult.Success) {
         return { Success: false, ErrorMessage: downloadResult.ErrorMessage };
     }
@@ -574,10 +692,62 @@ async function HandleMigrations(manifest, context) {
         DatabaseConfig: context.DatabaseConfig,
         MJCoreSchema: context.MJCoreSchema,
         ExtraPlaceholders: context.MigrationPlaceholders,
+        Platform: platform,
     });
     return { Success: migrationResult.Success, ErrorMessage: migrationResult.ErrorMessage };
 }
-async function HandlePackageInstallation(manifest, context, packageVersion, versionStrategy) {
+async function HandleTeardown(manifest, context, subpath) {
+    const teardownDir = manifest.migrations?.teardownDirectory;
+    if (!teardownDir) {
+        return { Success: true };
+    }
+    const platform = context.DatabaseProvider.Dialect.PlatformKey;
+    const dir = platform === 'postgresql' ? `${teardownDir}-pg` : teardownDir;
+    const tempDir = join(tmpdir(), `mj-app-${manifest.name}-teardown-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    context.Callbacks?.OnProgress?.('Metadata', 'Downloading teardown scripts...');
+    const download = await DownloadMigrations(manifest.repository, manifest.version, dir, tempDir, context.GitHubOptions, subpath);
+    if (!download.Success) {
+        return { Success: false, ErrorMessage: `Failed to download teardown scripts: ${download.ErrorMessage}` };
+    }
+    const files = (download.Files ?? []).filter((f) => f.endsWith('.sql')).sort();
+    if (files.length === 0) {
+        context.Callbacks?.OnWarn?.('Metadata', `No teardown scripts in '${dir}' — this app's rows in the shared core schema will NOT be retired on remove.`);
+        return { Success: true };
+    }
+    const mjSchema = context.MJCoreSchema ?? '__mj';
+    context.Callbacks?.OnProgress?.('Metadata', `Running ${files.length} teardown script(s) against '${mjSchema}'...`);
+    await context.DatabaseProvider.BeginTransaction();
+    try {
+        for (const file of files) {
+            const sql = readFileSync(join(tempDir, file), 'utf-8').split('${mjSchema}').join(mjSchema);
+            if (sql.trim()) {
+                await context.DatabaseProvider.ExecuteSQL(sql);
+            }
+        }
+        await context.DatabaseProvider.CommitTransaction();
+    }
+    catch (error) {
+        await context.DatabaseProvider.RollbackTransaction();
+        const message = error instanceof Error ? error.message : String(error);
+        return { Success: false, ErrorMessage: `Teardown failed for '${manifest.name}' (rolled back): ${message}` };
+    }
+    context.Callbacks?.OnSuccess?.('Metadata', `Retired this app's rows from '${mjSchema}' (${files.length} teardown script(s)).`);
+    return { Success: true };
+}
+async function DownloadAppMigrations(manifest, context, tempDir, subpath) {
+    const baseDir = manifest.migrations.directory;
+    const isPG = context.DatabaseProvider.Dialect.PlatformKey === 'postgresql';
+    if (isPG) {
+        const pgDir = `${baseDir.replace(/\/+$/, '')}-pg`;
+        const pgResult = await DownloadMigrations(manifest.repository, manifest.version, pgDir, tempDir, context.GitHubOptions, subpath);
+        if (pgResult.Success && (pgResult.Files?.length ?? 0) > 0) {
+            return pgResult;
+        }
+    }
+    return DownloadMigrations(manifest.repository, manifest.version, baseDir, tempDir, context.GitHubOptions, subpath);
+}
+async function HandlePackageInstallation(manifest, context, packageVersion, versionStrategy, verbose) {
     if (!manifest.packages) {
         return { Success: true };
     }
@@ -606,7 +776,7 @@ async function HandlePackageInstallation(manifest, context, packageVersion, vers
         }
     }
     context.Callbacks?.OnProgress?.('Packages', 'Running package install...');
-    const installResult = RunPackageInstall(context.RepoRoot, undefined, manifest.packages.registry, context.PackageManager);
+    const installResult = RunPackageInstall(context.RepoRoot, verbose, manifest.packages.registry, context.PackageManager);
     if (!installResult.Success) {
         return { Success: false, PackageJsonUpdated: true, ErrorMessage: installResult.ErrorMessage };
     }
@@ -618,6 +788,10 @@ function HandleServerConfig(manifest, context) {
     if (!dynamicResult.Success) {
         return { Success: false, ErrorMessage: dynamicResult.ErrorMessage };
     }
+    const clientResult = AddClientDynamicPackages(context.RepoRoot, manifest);
+    if (!clientResult.Success) {
+        return { Success: false, ErrorMessage: clientResult.ErrorMessage };
+    }
     const entityResult = AddEntityPackageMapping(context.RepoRoot, manifest);
     if (!entityResult.Success) {
         return { Success: false, ErrorMessage: entityResult.ErrorMessage };
@@ -646,104 +820,132 @@ function HandleAngularPrebundleExcludeRemoval(manifest, otherManifests, context)
     manager.RemovePrebundleExcludes(manifest, otherManifests);
     manager.Save();
 }
-async function HandleClientBootstrapRegeneration(context) {
-    context.Callbacks?.OnProgress?.('Config', 'Regenerating client bootstrap...');
-    const apps = await ListInstalledApps(context.ContextUser);
-    const appDeps = new Map();
-    for (const app of apps) {
-        const manifest = JSON.parse(app.ManifestJSON);
-        const depNames = manifest.dependencies ? Object.keys(manifest.dependencies) : [];
-        appDeps.set(app.Name, depNames);
-    }
-    const sortedNames = TopologicalSortApps(appDeps);
-    const entries = [];
-    const appsByName = new Map(apps.map((a) => [a.Name, a]));
-    for (const name of sortedNames) {
-        const app = appsByName.get(name);
-        if (!app)
-            continue;
-        const manifest = JSON.parse(app.ManifestJSON);
-        const clientPkgs = [...(manifest.packages?.client ?? []), ...(manifest.packages?.shared ?? [])];
-        for (const pkg of clientPkgs) {
-            entries.push({
-                AppName: app.Name,
-                Version: app.Version,
-                PackageName: pkg.name,
-                Enabled: app.Status === 'Active',
-            });
-        }
-    }
-    RegenerateClientBootstrap(context.RepoRoot, entries, context.ClientPackagePath, context.ClientBootstrapSubpath);
-}
-function TopologicalSortApps(appDeps) {
-    const visited = new Set();
-    const result = [];
-    function Visit(name) {
-        if (visited.has(name))
-            return;
-        visited.add(name);
-        const deps = appDeps.get(name) ?? [];
-        for (const dep of deps) {
-            if (appDeps.has(dep)) {
-                Visit(dep);
-            }
-        }
-        result.push(name);
-    }
-    for (const name of appDeps.keys()) {
-        Visit(name);
-    }
-    return result;
-}
 async function ExecuteHook(command, cwd) {
     const { execSync } = await import('node:child_process');
     execSync(command, { cwd, encoding: 'utf-8', timeout: 120000, stdio: 'inherit' });
 }
-async function RemoveAppEntityMetadata(schemaName, contextUser, callbacks) {
+export async function RemoveAppEntityMetadata(schemaName, contextUser, callbacks, provider) {
     try {
         const rv = new RunView();
         const escaped = EscapeSqlString(schemaName);
+        const md = (provider ?? new Metadata());
+        const tg = await md.CreateTransactionGroup();
+        const queueDeleteByFilterOrThrow = async (entityName, filter) => {
+            const r = await QueueDeleteEntitiesByFilter(rv, contextUser, entityName, filter, tg);
+            if (!r.Success) {
+                throw new Error(r.ErrorMessage ?? `Failed to queue delete of ${entityName} records`);
+            }
+        };
         const entityResult = await rv.RunView({
             EntityName: 'MJ: Entities',
             ExtraFilter: `SchemaName = '${escaped}'`,
             ResultType: 'entity_object',
         }, contextUser);
-        if (!entityResult.Success || entityResult.Results.length === 0) {
-            await DeleteEntitiesByFilter(rv, contextUser, 'MJ: Schema Info', `SchemaName = '${escaped}'`);
+        if (!entityResult.Success) {
+            throw new Error(`Failed to query entities for schema '${schemaName}': ${entityResult.ErrorMessage}`);
+        }
+        if (entityResult.Results.length === 0) {
+            await queueDeleteByFilterOrThrow('MJ: Schema Info', `SchemaName = '${escaped}'`);
+            if (!(await tg.Submit())) {
+                throw new Error('Transaction failed: schema-info cleanup could not be committed');
+            }
             callbacks?.OnSuccess?.('Metadata', `Entity metadata for schema '${schemaName}' removed`);
-            return;
+            return { Success: true };
         }
-        const entityIds = entityResult.Results.map((e) => String(e.Get('ID')));
+        const entityIds = entityResult.Results.map((e) => e.ID);
         const idList = entityIds.map((id) => `'${EscapeSqlString(id)}'`).join(',');
-        const entityIdFilter = `EntityID IN (${idList})`;
-        await Promise.all([
-            DeleteEntitiesByFilter(rv, contextUser, 'MJ: Entity Permissions', entityIdFilter),
-            DeleteEntitiesByFilter(rv, contextUser, 'MJ: Application Entities', entityIdFilter),
-        ]);
-        await DeleteEntitiesByFilter(rv, contextUser, 'MJ: Entity Relationships', `EntityID IN (${idList}) OR RelatedEntityID IN (${idList})`);
-        await DeleteEntitiesByFilter(rv, contextUser, 'MJ: Entity Fields', `EntityID IN (${idList})`);
+        const fieldResult = await rv.RunView({
+            EntityName: 'MJ: Entity Fields',
+            ExtraFilter: `EntityID IN (${idList})`,
+            ResultType: 'entity_object',
+        }, contextUser);
+        if (!fieldResult.Success) {
+            throw new Error(`Failed to query entity fields for schema '${schemaName}': ${fieldResult.ErrorMessage}`);
+        }
+        const fieldIdList = fieldResult.Results.map((f) => `'${EscapeSqlString(f.ID)}'`).join(',');
+        const ownedAppIds = await FindAppOwnedApplications(rv, contextUser, entityIds, idList);
+        if (fieldIdList.length > 0) {
+            await queueDeleteByFilterOrThrow('MJ: Entity Field Values', `EntityFieldID IN (${fieldIdList})`);
+        }
+        await queueDeleteByFilterOrThrow('MJ: Entity Permissions', `EntityID IN (${idList})`);
+        await queueDeleteByFilterOrThrow('MJ: Application Entities', `EntityID IN (${idList})`);
+        await queueDeleteByFilterOrThrow('MJ: Entity Settings', `EntityID IN (${idList})`);
+        await queueDeleteByFilterOrThrow('MJ: Entity Relationships', `EntityID IN (${idList}) OR RelatedEntityID IN (${idList})`);
+        await queueDeleteByFilterOrThrow('MJ: Entity Fields', `EntityID IN (${idList})`);
         for (const entity of entityResult.Results) {
+            entity.TransactionGroup = tg;
             await entity.Delete();
         }
-        await DeleteEntitiesByFilter(rv, contextUser, 'MJ: Schema Info', `SchemaName = '${escaped}'`);
+        await queueDeleteByFilterOrThrow('MJ: Schema Info', `SchemaName = '${escaped}'`);
+        if (!(await tg.Submit())) {
+            throw new Error('Transaction failed: entity metadata cleanup could not be committed atomically');
+        }
+        await DeleteAppOwnedApplications(rv, ownedAppIds, contextUser, callbacks);
         callbacks?.OnSuccess?.('Metadata', `Entity metadata for schema '${schemaName}' removed`);
+        return { Success: true };
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        callbacks?.OnWarn?.('Metadata', `Failed to remove entity metadata: ${message}`);
+        callbacks?.OnError?.('Metadata', `Failed to remove entity metadata: ${message}`);
+        return { Success: false, ErrorMessage: `Failed to remove entity metadata for schema '${schemaName}': ${message}` };
     }
 }
-async function DeleteEntitiesByFilter(rv, contextUser, entityName, filter) {
+async function FindAppOwnedApplications(rv, contextUser, entityIds, idList) {
+    const ours = new Set(entityIds.map((id) => NormalizeUUID(id)));
+    const linked = await rv.RunView({ EntityName: 'MJ: Application Entities', ExtraFilter: `EntityID IN (${idList})`, Fields: ['ApplicationID'], ResultType: 'simple' }, contextUser);
+    if (!linked.Success) {
+        return [];
+    }
+    const candidateIds = [...new Set(linked.Results.map((r) => r.ApplicationID))];
+    if (candidateIds.length === 0) {
+        return [];
+    }
+    const candList = candidateIds.map((id) => `'${EscapeSqlString(id)}'`).join(',');
+    const allLinks = await rv.RunView({ EntityName: 'MJ: Application Entities', ExtraFilter: `ApplicationID IN (${candList})`, Fields: ['ApplicationID', 'EntityID'], ResultType: 'simple' }, contextUser);
+    if (!allLinks.Success) {
+        return [];
+    }
+    const allOursByApp = new Map();
+    for (const link of allLinks.Results) {
+        const wasAllOurs = allOursByApp.get(link.ApplicationID) ?? true;
+        allOursByApp.set(link.ApplicationID, wasAllOurs && ours.has(NormalizeUUID(link.EntityID)));
+    }
+    return [...allOursByApp.entries()].filter(([, allOurs]) => allOurs).map(([appId]) => appId);
+}
+async function DeleteAppOwnedApplications(rv, applicationIds, contextUser, callbacks) {
+    if (applicationIds.length === 0) {
+        return;
+    }
+    const idList = applicationIds.map((id) => `'${EscapeSqlString(id)}'`).join(',');
+    const appsResult = await rv.RunView({ EntityName: 'MJ: Applications', ExtraFilter: `ID IN (${idList})`, ResultType: 'entity_object' }, contextUser);
+    if (!appsResult.Success) {
+        return;
+    }
+    for (const app of appsResult.Results) {
+        try {
+            if (!(await app.Delete())) {
+                callbacks?.OnWarn?.('Metadata', `Left Application '${app.Name}' — it still has dependents; a reinstall will reuse it (${app.LatestResult?.CompleteMessage ?? 'has FK references'}).`);
+            }
+        }
+        catch (error) {
+            callbacks?.OnWarn?.('Metadata', `Could not remove app-owned Application '${app.Name}': ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+async function QueueDeleteEntitiesByFilter(rv, contextUser, entityName, filter, transactionGroup) {
     const result = await rv.RunView({
         EntityName: entityName,
         ExtraFilter: filter,
         ResultType: 'entity_object',
     }, contextUser);
-    if (result.Success) {
-        for (const record of result.Results) {
-            await record.Delete();
-        }
+    if (!result.Success) {
+        return { Success: false, ErrorMessage: `Failed to query ${entityName}: ${result.ErrorMessage}` };
+    }
+    for (const record of result.Results) {
+        record.TransactionGroup = transactionGroup;
+        await record.Delete();
     }
+    return { Success: true };
 }
 function GetDurationSeconds(startTime) {
     return Math.round((Date.now() - startTime) / 1000);