biz-a-cli 2.3.80-15280 → 2.3.80-15292

package/bin/app.js

@@ -11,10 +11,19 @@ import {
 	constants as cryptoConstants,
 } from "node:crypto";
 import path, { basename } from "node:path";
+import os from "node:os";
 import { env } from "../envs/env.js";
 import { prepareScript, encryptScript } from "./script.js";
 import { spawn } from "node:child_process";
 import { newMigration, runMigrations } from "./migrate.js";
+import {
+	APP_CONFIG_NAME,
+	extractConfigVersion,
+	getChunkedUpsertBlocks,
+	getUpsertBlock,
+	isSemanticVersion,
+	parseConfigForVersion,
+} from "../engine/domain/appConfig.js";
 
 const getKeyFolderPath = () => {
 	const scriptPath =
@@ -76,6 +85,20 @@ const addCommandOptions = {
 		demandOption: false,
 		default: false,
 	},
+	publish: {
+		describe:
+			"Config mode only (directory contains application.js): after saving, publish the domain DDL then the application config — the same as the admin App Config Publish button",
+		type: "boolean",
+		demandOption: false,
+		default: false,
+	},
+	forceFull: {
+		describe:
+			"With --publish: re-sync EVERY entity, ignoring the per-entity DDL hash cache. Use after an out-of-band schema change, or to get a complete redundant-index report",
+		type: "boolean",
+		demandOption: false,
+		default: false,
+	},
 };
 
 const removeCommandOptions = {
@@ -287,6 +310,321 @@ const getFileList = ({ workingDir = process.cwd(), files = null } = {}) => {
 	});
 };
 
+/* ============================================================================
+   CONFIG MODE — `biza add` on a directory containing application.js uploads SYS$CONFIG rows
+   instead of packing an encrypted app bundle, replacing the admin App Config paste/Save/Publish
+   round-trip. Entirely metadata-driven (platform code stays application-agnostic): the domain
+   NAME comes from each file's metadata.name and the VERSION from metadata.version.
+   ============================================================================ */
+
+const APPLICATION_CONFIG_FILE = "application.js";
+/* Parity with the admin editor (appConfig.component.ts executeBlockBodyLimit): the DataSnap
+   `block` call body must stay under 64KB, so an oversized config is upserted in chunks. */
+const EXECUTE_BLOCK_BODY_LIMIT = 2 ** 16;
+
+const findApplicationConfigFile = (fileNames = []) =>
+	fileNames.find(
+		(fileName) =>
+			path.basename(String(fileName)).toLowerCase() === APPLICATION_CONFIG_FILE,
+	) || null;
+
+/* Does this directory ship configs rather than app scripts? Checked BEFORE the jest gate: that
+   gate exists to validate app scripts before they are bundled, and a config directory has nothing
+   to test — worse, jest exits non-zero there ("Could not find a config file", after traversing up),
+   which would abort the upload outright. */
+const isConfigModeDir = (workingDir, files = null) => {
+	try {
+		return !!findApplicationConfigFile(
+			getFileList({ workingDir: path.resolve(workingDir), files }),
+		);
+	} catch {
+		return false;
+	}
+};
+
+/* Run one upsert block against DataSnap. Deliberately NOT db/db.js executeBlock: that path runs
+   flattenSql(), whose `--` comment stripping mangles a config upsert — the whole config is embedded
+   as a single-line quoted literal, so the first `--` ANYWHERE in the config text (a JS comment, a
+   CSS custom property, an HTML template) silently truncates the rest of the statement and Firebird
+   reports "Unexpected end of command". getUpsertBlock already emits single-line SQL, so there is
+   nothing to flatten. This mirrors what the admin editor sends (dataService.executeBlock). */
+const executeConfigBlock = async (blockSql, { server, apiPort, dbIndex }) => {
+	const url = `${server}:${apiPort}/fina/rest/TOrmMethod/%22block%22`;
+	const data = JSON.stringify({
+		_parameters: [
+			JSON.stringify({ dbIndex, method: "block", object: blockSql }),
+		],
+	});
+	const res = await axios.post(url, data, {
+		headers: { "content-type": "text/plain" },
+	});
+	const parsed =
+		typeof res.data === "string" ? JSON.parse(res.data) : res.data;
+	if (parsed && parsed.error) {
+		throw new Error(parsed.error);
+	}
+	return parsed;
+};
+
+const estimateExecuteBlockBodyLength = (blockSql, dbIndex) =>
+	JSON.stringify({
+		_parameters: [
+			JSON.stringify({ dbIndex, method: "block", object: blockSql }),
+		],
+	}).length;
+
+/* One upsert block when it fits, else halve the chunk size until every block fits. Mirrors
+   appConfig.component.ts resolveUpsertBlocksByBodyLimit. */
+const resolveUpsertBlocks = (name, version, content, dbIndex) => {
+	const singleBlock = getUpsertBlock(name, version, content);
+	if (
+		estimateExecuteBlockBodyLength(singleBlock, dbIndex) <=
+		EXECUTE_BLOCK_BODY_LIMIT
+	) {
+		return [singleBlock];
+	}
+
+	let chunkSize = EXECUTE_BLOCK_BODY_LIMIT;
+	while (chunkSize > 0) {
+		const blocks = getChunkedUpsertBlocks(name, version, content, chunkSize);
+		if (
+			blocks.every(
+				(block) =>
+					estimateExecuteBlockBodyLength(block, dbIndex) <=
+					EXECUTE_BLOCK_BODY_LIMIT,
+			)
+		) {
+			return blocks;
+		}
+		chunkSize = Math.floor(chunkSize / 2);
+	}
+
+	throw new Error(
+		`Failed to split "${name}" into executeBlock-sized chunks.`,
+	);
+};
+
+/* PURE-ish (reads files, no network): resolve every config in the directory and validate the
+   WHOLE set before anything is uploaded, so a stray lib or a typo'd metadata can never leave a
+   half-applied config in SYS$CONFIG. Every problem is collected and reported at once, each
+   naming its file. */
+const collectConfigUploads = ({ workingDir, fileNames = [] }) => {
+	const problems = [];
+	const readConfig = (fileName) =>
+		fs
+			.readFileSync(
+				path.isAbsolute(fileName)
+					? fileName
+					: path.join(workingDir, fileName),
+			)
+			.toString();
+
+	const applicationFile = findApplicationConfigFile(fileNames);
+	let application = null;
+	if (applicationFile) {
+		const content = readConfig(applicationFile);
+		let version = null;
+		try {
+			version = extractConfigVersion(content);
+		} catch (error) {
+			problems.push(
+				`${path.basename(applicationFile)}: ${error?.message ?? error}`,
+			);
+		}
+		if (!version) {
+			problems.push(
+				`${path.basename(applicationFile)}: metadata.version is required.`,
+			);
+		} else if (!isSemanticVersion(version)) {
+			problems.push(
+				`${path.basename(applicationFile)}: metadata.version "${version}" must be semantic (x.y.z).`,
+			);
+		}
+		application = { name: APP_CONFIG_NAME, version, content };
+	}
+
+	const domains = [];
+	const seenNames = new Map();
+	for (const fileName of fileNames) {
+		const baseName = path.basename(String(fileName));
+		if (baseName.toLowerCase() === APPLICATION_CONFIG_FILE) continue;
+		/* menu.json is a bundle-only concept; it has no place in a config upload. */
+		if (!baseName.toLowerCase().endsWith(".js")) continue;
+
+		const content = readConfig(fileName);
+		let parsed = null;
+		try {
+			parsed = parseConfigForVersion(content);
+		} catch (error) {
+			problems.push(`${baseName}: ${error?.message ?? error}`);
+			continue;
+		}
+
+		const name = String(parsed?.metadata?.name ?? "").trim();
+		const version = String(parsed?.metadata?.version ?? "").trim();
+		if (!name) {
+			problems.push(
+				`${baseName}: metadata.name is required (expected a domain config).`,
+			);
+			continue;
+		}
+		if (!version) {
+			problems.push(`${baseName}: metadata.version is required.`);
+			continue;
+		}
+		if (!isSemanticVersion(version)) {
+			problems.push(
+				`${baseName}: metadata.version "${version}" must be semantic (x.y.z).`,
+			);
+			continue;
+		}
+		if (seenNames.has(name)) {
+			problems.push(
+				`${baseName}: metadata.name "${name}" is already declared by ${seenNames.get(name)}.`,
+			);
+			continue;
+		}
+		seenNames.set(name, baseName);
+		domains.push({ name, version, content, fileName: baseName });
+	}
+
+	if (problems.length > 0) {
+		throw new Error(
+			`Config upload aborted, nothing was uploaded:\n  - ${problems.join("\n  - ")}`,
+		);
+	}
+
+	return { application, domains };
+};
+
+/* Upsert the configs, then optionally run the same publish the admin button does. Publish order
+   matches appConfig.service.ts publishEditorConfigs: every domain DDL publish first (sequential),
+   then the application-config publish (which regenerates template scaffolding + rebuilds the
+   bundle). */
+async function uploadConfigs({
+	workingDir,
+	fileNames,
+	server,
+	apiPort,
+	dbIndex,
+	sub,
+	publish = false,
+	forceFull = false,
+}) {
+	const { application, domains } = collectConfigUploads({
+		workingDir,
+		fileNames,
+	});
+
+	const apiConfig = {
+		url: `${server}:${apiPort}`,
+		dbindex: dbIndex,
+		timeout: 60000,
+	};
+
+	const saveOne = async ({ name, version, content }) => {
+		const blocks = resolveUpsertBlocks(name, version, content, dbIndex);
+		for (const block of blocks) {
+			await executeConfigBlock(block, { server, apiPort, dbIndex });
+		}
+		console.log(
+			`saved ${name}@${version}${blocks.length > 1 ? ` (${blocks.length} chunks)` : ""}`,
+		);
+	};
+
+	if (application) {
+		await saveOne(application);
+	}
+	for (const domain of domains) {
+		await saveOne(domain);
+	}
+
+	if (!publish) {
+		return {
+			success: true,
+			data: {
+				applicationConfig: application,
+				domains: domains.map(({ name, version }) => ({ name, version })),
+			},
+		};
+	}
+
+	/* Dynamic import: engine/domain/system.js dynamically imports THIS file, so a static import
+	   of the publish entry points would close that cycle. */
+	const { publishConfigs } = await import("../engine/domain/appConfig.js");
+	const { publishApplicationConfig } = await import(
+		"../engine/domain/applicationConfig.js"
+	);
+	/* system.js publishApp reads argv.server / argv.port / argv.dbindex / argv.subdomain. */
+	const publishArgv = {
+		server,
+		port: apiPort,
+		dbindex: dbIndex,
+		subdomain: sub,
+	};
+
+	for (const domain of domains) {
+		const result = await publishConfigs(
+			{
+				domainName: domain.name,
+				domainVersion: domain.version,
+				dbIndex,
+				url: apiConfig.url,
+				forceFull,
+			},
+			publishArgv,
+		);
+		if (!result || result.success !== true) {
+			throw new Error(
+				`Publish ${domain.name}@${domain.version} failed: ${result?.error ?? "no error message from server"}`,
+			);
+		}
+		console.log(`published ${domain.name}@${domain.version}`);
+	}
+
+	if (application) {
+		/* publishApplicationConfig -> publishApp -> addApp({ workingDir: process.cwd() }), and
+		   addApp folds getFileList(cwd) into the bundle. cwd is the CONFIG directory right now, so
+		   without this the configs themselves would be packed as app scripts. Run the publish from
+		   an empty scratch dir so only the generated templates are bundled. */
+		const scratchDir = fs.mkdtempSync(
+			path.join(os.tmpdir(), "biza-publish-"),
+		);
+		const previousCwd = process.cwd();
+		try {
+			process.chdir(scratchDir);
+			const result = await publishApplicationConfig(
+				{
+					applicationConfigName: application.name,
+					applicationConfigVersion: application.version,
+					dbIndex,
+					url: apiConfig.url,
+					subdomain: sub,
+				},
+				publishArgv,
+			);
+			if (!result || result.success !== true) {
+				throw new Error(
+					`Publish ${application.name}@${application.version} failed: ${result?.error ?? "no error message from server"}`,
+				);
+			}
+			console.log(`published ${application.name}@${application.version}`);
+		} finally {
+			process.chdir(previousCwd);
+			fs.rmSync(scratchDir, { force: true, recursive: true });
+		}
+	}
+
+	return {
+		success: true,
+		data: {
+			applicationConfig: application,
+			domains: domains.map(({ name, version }) => ({ name, version })),
+			published: true,
+		},
+	};
+}
+
 const parseApplicationConfigData = (rawConfig) => {
 	if (rawConfig == null) {
 		return null;
@@ -388,6 +726,8 @@ async function addApp({
 	sub,
 	files = null,
 	body = null,
+	publish = false,
+	forceFull = false,
 } = {}) {
 	const oldCwd = process.cwd();
 
@@ -426,6 +766,23 @@ async function addApp({
 			new Set([...sourceFiles, ...bodySourceFiles]),
 		);
 
+		/* CONFIG MODE. An application.js in the working directory means the caller is shipping
+		   SYS$CONFIG rows, not libs — upload the configs instead of packing a bundle. Guarded on
+		   `body == null` so the publish path (publishApplicationConfig -> publishApp -> addApp with
+		   generated template scripts) can never recurse back into config mode. */
+		if (body == null && findApplicationConfigFile(mergedSourceFiles)) {
+			return await uploadConfigs({
+				workingDir: process.cwd(),
+				fileNames: mergedSourceFiles,
+				server,
+				apiPort,
+				dbIndex,
+				sub,
+				publish,
+				forceFull,
+			});
+		}
+
 		if (mergedSourceFiles.length > 0) {
 			const keys = await prepareKeys();
 			if (!keys) {
@@ -578,6 +935,8 @@ async function runUnitTests(options) {
 					dbIndex: options.dbIndex,
 					sub: options.sub,
 					files: options.files,
+					publish: options.publish,
+					forceFull: options.forceFull,
 				});
 			} else {
 				console.error("Biz-A Add aborted");
@@ -598,6 +957,21 @@ const buildCli = () =>
 			"Add Biz-A Application",
 			addCommandOptions,
 			async (commandOptions) => {
+				/* Config mode uploads SYS$CONFIG rows, not app scripts — skip the jest gate. */
+				if (isConfigModeDir(commandOptions.workingDir, commandOptions.files)) {
+					await addApp({
+						workingDir: path.resolve(commandOptions.workingDir),
+						verbose: commandOptions.verbose,
+						server: commandOptions.server,
+						apiPort: commandOptions.apiPort,
+						dbIndex: commandOptions.dbIndex,
+						sub: commandOptions.sub,
+						files: commandOptions.files,
+						publish: commandOptions.publish,
+						forceFull: commandOptions.forceFull,
+					});
+					return;
+				}
 				await runUnitTests(commandOptions);
 			},
 		)
@@ -691,4 +1065,9 @@ export {
 	removeCommandOptions,
 	getFileList,
 	addApp,
+	findApplicationConfigFile,
+	collectConfigUploads,
+	resolveUpsertBlocks,
+	uploadConfigs,
+	isConfigModeDir,
 };

package/engine/domain/appConfig.js

@@ -1,6 +1,7 @@
 import axios from "axios";
 import { IDLE_SOCKET_TIMEOUT_MILLISECONDS } from "../../bin/hubEvent.js";
 import { queryData, executeBlock, getGlobalConfig } from "../../db/db.js";
+import { createHash } from "node:crypto";
 import * as firebirdDdl from "./firebird-ddl.js";
 
 export const TBL_SYS_CONFIG = "SYS$CONFIG";
@@ -1113,7 +1114,7 @@ export const buildAppendOnlySyncPlan = (table, exceptionRows, triggerRows) => {
 
 export const buildDomainDdlPreview = (domainConfigContent, defaultDbIndex) => {
 	const buildResult = buildDomainSchemaInternal(domainConfigContent, defaultDbIndex);
-	const schema = buildResult.schema;
+	const schema = pruneIndexesCoveredByForeignKeys(buildResult.schema);
 	return {
 		schema,
 		ddlSql: schema.tables.length > 0 ? generateCreateSchemaSql(schema, true) : "",
@@ -1637,6 +1638,37 @@ const applyDirectRelationship = (relationship, entityInfos, warnings) => {
 	});
 };
 
+const indexColumnsKey = (columns) =>
+	(columns ?? []).map((column) => String(column).trim().toUpperCase()).join(",");
+
+/* Firebird creates an index for EVERY foreign key constraint automatically, while
+   buildAttributeIndexes independently indexes any lookup / *_ID column — so an FK column used to
+   end up with two identical indexes (71 such pairs in the live schema). The actual-side snapshot
+   cannot even see the clash: indexesSql filters constraint-owned indexes out (`rc.RDB$INDEX_NAME
+   IS NULL`), so the sync kept recreating its own copy forever.
+
+   Drop from the EXPECTED schema any plain index whose column set exactly matches a foreign key on
+   the same table. Exact match only: the deliberate [FK, PK] covering index that
+   applyDirectRelationship builds for joins is a superset and is kept, as are unique and
+   expression indexes (those carry semantics the FK index does not). Idempotent. */
+export const pruneIndexesCoveredByForeignKeys = (schema) => {
+	for (const table of schema?.tables ?? []) {
+		const foreignKeyColumnSets = new Set(
+			(table.foreignKeys ?? []).map((fk) => indexColumnsKey(fk.columns)),
+		);
+		if (foreignKeyColumnSets.size === 0) {
+			continue;
+		}
+		table.indexes = (table.indexes ?? []).filter((index) => {
+			if (index?.unique === true || index?.expression) {
+				return true;
+			}
+			return !foreignKeyColumnSets.has(indexColumnsKey(index?.columns));
+		});
+	}
+	return schema;
+};
+
 const applyManyToManyRelationship = (relationship, entityInfos, tableInfos, tables, warnings) => {
 	const fromInfo = entityInfos.get(relationship.from);
 	const toInfo = entityInfos.get(relationship.to);
@@ -1922,7 +1954,7 @@ const parseDomainConfigContent = (content) => {
 	}
 };
 
-const enrichSchemaWithEntityIndices = (schema, domainConfigContent) => {
+export const enrichSchemaWithEntityIndices = (schema, domainConfigContent) => {
 	const parsed = parseDomainConfigContent(domainConfigContent);
 	const entities = parsed && typeof parsed === "object" ? parsed?.model?.entities : null;
 	if (!entities || typeof entities !== "object") {
@@ -2315,6 +2347,221 @@ const splitSqlStatements = (sqlBatch) => {
 	return statements.map((statement) => sanitizeSql(statement));
 };
 
+
+/* ============================================================================
+   PER-ENTITY DDL HASH — publish used to introspect EVERY table on every run (loadTableSnapshot
+   fires 8 queries per table, so ~640 round-trips for an 80-entity domain) even when nothing had
+   changed. The expected definition of each table is hashed and the map persisted alongside the
+   domain in SYS$CONFIG as `<domain>__DDL_HASH`; a table whose hash is unchanged is skipped without
+   a single query. `forceFull` bypasses the cache — use it after any out-of-band schema change.
+   ============================================================================ */
+
+/* Key order must not affect the hash, so serialize with sorted keys. */
+const stableStringify = (value) => {
+	if (Array.isArray(value)) {
+		return `[${value.map(stableStringify).join(",")}]`;
+	}
+	if (value && typeof value === "object") {
+		return `{${Object.keys(value)
+			.sort()
+			.map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+			.join(",")}}`;
+	}
+	return JSON.stringify(value ?? null);
+};
+
+/* migrationMode is part of the key: the same table yields different DDL under safe vs aggressive. */
+const computeTableDdlHash = (table, migrationMode) =>
+	createHash("sha256")
+		.update(`${migrationMode}|${stableStringify(table)}`)
+		.digest("hex")
+		.slice(0, 32);
+
+export const buildDdlHashConfigKey = (domainName, domainVersion) => ({
+	name: `${domainName}__DDL_HASH`,
+	version: domainVersion,
+});
+
+const loadDdlHashes = async (domainName, domainVersion, config) => {
+	const { name, version } = buildDdlHashConfigKey(domainName, domainVersion);
+	try {
+		const rows = await queryData(getConfigByNameVersionParameters(name, version), config);
+		const raw = rows?.[0]?.data;
+		if (!raw) {
+			return {};
+		}
+		const parsed = JSON.parse(String(raw));
+		return parsed && typeof parsed.tables === "object" && parsed.tables ? parsed.tables : {};
+	} catch {
+		/* Unreadable or corrupt cache must never fail a publish — degrade to a full sync. */
+		return {};
+	}
+};
+
+const writeDdlHashes = async (domainName, domainVersion, tables, config) => {
+	const { name, version } = buildDdlHashConfigKey(domainName, domainVersion);
+	const payload = JSON.stringify({ tables });
+	await executeBlock(getUpsertBlock(name, version, payload), config);
+};
+
+/* Indexes that exist in the DATABASE but no longer earn their keep. Report only — the DROPs are
+   handed back so an operator can review them, never executed by the publish. */
+const collectRedundantIndexes = (table, snapshot) => {
+	const findings = [];
+	const foreignKeyColumnSets = new Map();
+	for (const fk of snapshot?.foreignKeys ?? []) {
+		foreignKeyColumnSets.set(indexColumnsKey(fk.columns), fk.name);
+	}
+	const expectedNames = new Set(
+		(table.indexes ?? []).map((index) => String(index.name).trim().toUpperCase()),
+	);
+	const seenColumnSets = new Map();
+
+	for (const index of snapshot?.indexes ?? []) {
+		const indexName = String(index.name ?? "").trim().toUpperCase();
+		if (!indexName) {
+			continue;
+		}
+		const columnsKey = indexColumnsKey(index.columns);
+		const owningForeignKey = foreignKeyColumnSets.get(columnsKey);
+		if (owningForeignKey && index.unique !== true) {
+			findings.push({
+				table: table.name,
+				indexName,
+				columns: index.columns ?? [],
+				reason: `duplicates the index Firebird maintains for foreign key ${owningForeignKey}`,
+				dropSql: `DROP INDEX ${indexName};`,
+			});
+			continue;
+		}
+		const twin = seenColumnSets.get(columnsKey);
+		if (twin) {
+			findings.push({
+				table: table.name,
+				indexName,
+				columns: index.columns ?? [],
+				reason: `indexes the same columns as ${twin}`,
+				dropSql: `DROP INDEX ${indexName};`,
+			});
+			continue;
+		}
+		seenColumnSets.set(columnsKey, indexName);
+		if (!expectedNames.has(indexName)) {
+			findings.push({
+				table: table.name,
+				indexName,
+				columns: index.columns ?? [],
+				reason: "not declared by the domain config",
+				dropSql: `DROP INDEX ${indexName};`,
+			});
+		}
+	}
+	return findings;
+};
+
+
+/* ORPHAN COLUMNS — a column that exists in the DATABASE but is no longer declared by the config.
+   A rename in the config is an ADD, not a rename: safe mode adds the new column and leaves the old
+   one in place forever (ST_PRC_ROUTE_MAP kept FINA_ITEM_CATEGORY_ID in its old slot long after it
+   became ST_ITEM_CATEGORY_ID). Always reported; dropped only under forceFull.
+
+   The guards and the statement ORDER mirror the aggressive branch of buildTableSyncPlan: a primary
+   key column or one another table's FK points at is never touched, and dependent constraints and
+   indexes come down before the column itself. */
+const collectOrphanColumns = (table, snapshot) => {
+	const expectedColumns = new Set(
+		(table.columns ?? []).map((column) => String(column.name).trim().toUpperCase()),
+	);
+	const primaryKeyColumns = new Set(
+		(snapshot?.primaryKey ?? []).map((value) => String(value).trim().toUpperCase()),
+	);
+	const findings = [];
+
+	for (const actualColumn of snapshot?.columns ?? []) {
+		const columnName = String(actualColumn.name).trim().toUpperCase();
+		if (expectedColumns.has(columnName)) {
+			continue;
+		}
+
+		const base = { table: table.name, column: columnName, dropped: false, dropStatements: [] };
+
+		if (primaryKeyColumns.has(columnName)) {
+			findings.push({ ...base, reason: "part of the primary key - requires manual migration" });
+			continue;
+		}
+
+		const incomingReferences = (snapshot?.incomingForeignKeys ?? []).filter((fk) =>
+			(fk.referenceColumns ?? []).some((column) => String(column).trim().toUpperCase() === columnName),
+		);
+		if (incomingReferences.length > 0) {
+			const names = incomingReferences.map((fk) => `${fk.name} (${fk.tableName})`).join(", ");
+			findings.push({
+				...base,
+				reason: `referenced by foreign key ${names} - requires manual migration`,
+			});
+			continue;
+		}
+
+		const dropStatements = [];
+		for (const fk of snapshot?.foreignKeys ?? []) {
+			if ((fk.columns ?? []).some((column) => String(column).trim().toUpperCase() === columnName)) {
+				dropStatements.push(`ALTER TABLE ${table.name} DROP CONSTRAINT ${fk.name};`);
+			}
+		}
+		for (const uniqueKey of snapshot?.uniqueKeys ?? []) {
+			if ((uniqueKey.columns ?? []).some((column) => String(column).trim().toUpperCase() === columnName)) {
+				dropStatements.push(`ALTER TABLE ${table.name} DROP CONSTRAINT ${uniqueKey.name};`);
+			}
+		}
+		for (const index of snapshot?.indexes ?? []) {
+			if ((index.columns ?? []).some((column) => String(column).trim().toUpperCase() === columnName)) {
+				dropStatements.push(`DROP INDEX ${index.name};`);
+			}
+		}
+		dropStatements.push(`ALTER TABLE ${table.name} DROP ${actualColumn.name};`);
+
+		findings.push({
+			...base,
+			reason: "not declared by the domain config",
+			dropStatements,
+		});
+	}
+
+	return findings;
+};
+
+/* Under forceFull, actually drop the orphans — but never one that still holds data. Dropping a
+   populated column cannot be undone, and a genuine rename ghost is empty by definition, so a
+   non-zero count means the assumption does not hold and a human should look. */
+const dropOrphanColumns = async (orphans, tableDbIndex, ctx) => {
+	for (const orphan of orphans) {
+		if (orphan.dropStatements.length === 0) {
+			continue;
+		}
+		let rowsWithData = 0;
+		try {
+			const countRows = await execRawSql(
+				`SELECT COUNT(${orphan.column}) AS FILLED FROM ${orphan.table};`,
+				tableDbIndex,
+				ctx.config,
+			);
+			rowsWithData = Number(countRows?.[0]?.["filled"] ?? countRows?.[0]?.["FILLED"] ?? 0);
+		} catch {
+			/* Could not establish emptiness -> do not drop. */
+			orphan.reason = "could not verify the column is empty - not dropped";
+			continue;
+		}
+		orphan.rowsWithData = rowsWithData;
+		if (rowsWithData > 0) {
+			orphan.reason = `still holds data in ${rowsWithData} row(s) - not dropped, drop it manually if it is truly dead`;
+			continue;
+		}
+		await executeSqlStatements(orphan.dropStatements, tableDbIndex, ctx.config, ctx);
+		orphan.dropped = true;
+		orphan.reason = "not declared by the domain config - dropped (was empty)";
+	}
+};
+
 const syncTable = async (table, ctx) => {
 	const tableDbIndex = resolveExecutionDbIndex(table?.dbIndex, ctx.config);
 	const exists = await loadTableExists(table.name, tableDbIndex, ctx.config);
@@ -2352,6 +2599,16 @@ const syncTable = async (table, ctx) => {
 	}
 
 	const snapshot = await loadTableSnapshot(table.name, true, tableDbIndex, ctx.config);
+	if (Array.isArray(ctx.redundantIndexes)) {
+		ctx.redundantIndexes.push(...collectRedundantIndexes(table, snapshot));
+	}
+	if (Array.isArray(ctx.orphanColumns)) {
+		const orphans = collectOrphanColumns(table, snapshot);
+		if (ctx.dropOrphanColumns === true) {
+			await dropOrphanColumns(orphans, tableDbIndex, ctx);
+		}
+		ctx.orphanColumns.push(...orphans);
+	}
 	const compareResult = compareTableStructure(table, snapshot);
 	const generatorSyncPlan = await loadGeneratorSyncPlan(table, tableDbIndex, ctx.config);
 	await applyGeneratorSyncPlan(table, generatorSyncPlan, tableDbIndex, ctx.config, ctx);
@@ -2552,16 +2809,71 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 			return { success: true, domainName, domainVersion, tablesProcessed: 0, report };
 		}
 
+		/* An explicitly declared index can duplicate a foreign key just as the auto-generated one
+		   does, and enrichSchemaWithEntityIndices runs after the preview — so prune once more here,
+		   with the full picture. Idempotent. */
+		pruneIndexesCoveredByForeignKeys(preview.schema);
+
 		const orderedTables = orderTablesByDependency(preview.schema.tables);
+		const redundantIndexes = [];
+		const orphanColumns = [];
 		const ctx = {
 			config,
 			migrationMode,
 			executedBlockSignatures: new Set(),
 			report,
+			redundantIndexes,
+			orphanColumns,
 		};
 
+		/* Skip tables whose expected definition is byte-identical to the last successful publish:
+		   no snapshot, no comparison, no DDL. forceFull re-syncs everything. */
+		const forceFull = payload?.forceFull === true;
+		/* forceFull is the only mode that removes orphan columns — a targeted cleanup, NOT the
+		   blanket destructiveness of migrationMode 'aggressive'. */
+		ctx.dropOrphanColumns = forceFull;
+		const storedHashes = forceFull ? {} : await loadDdlHashes(domainName, domainVersion, config);
+		const nextHashes = { ...storedHashes };
+		let tablesSkipped = 0;
+		let tablesProcessed = 0;
+
 		for (const table of orderedTables) {
+			const tableKey = String(table.name).trim().toUpperCase();
+			const tableHash = computeTableDdlHash(table, migrationMode);
+			if (!forceFull && storedHashes[tableKey] === tableHash) {
+				tablesSkipped++;
+				continue;
+			}
 			await syncTable(table, ctx);
+			nextHashes[tableKey] = tableHash;
+			tablesProcessed++;
+		}
+
+		/* Only rewrite the cache when it actually moved — an unchanged publish should cost nothing. */
+		if (stableStringify(nextHashes) !== stableStringify(storedHashes)) {
+			await writeDdlHashes(domainName, domainVersion, nextHashes, config);
+		}
+		if (tablesSkipped > 0) {
+			console.log(
+				`[AppConfig Publish] ${tablesSkipped} table(s) unchanged since the last publish - skipped. Use forceFull to re-sync everything.`,
+			);
+		}
+		if (orphanColumns.length > 0) {
+			const droppedCount = orphanColumns.filter((item) => item.dropped).length;
+			console.log(
+				`[AppConfig Publish] ${orphanColumns.length} orphan column(s) found, ${droppedCount} dropped${forceFull ? "" : " (run with forceFull to drop the empty ones)"}:`,
+			);
+			orphanColumns.forEach((item) =>
+				console.log(`  ${item.table}.${item.column} - ${item.reason}`),
+			);
+		}
+		if (redundantIndexes.length > 0) {
+			console.log(
+				`[AppConfig Publish] ${redundantIndexes.length} redundant index(es) found (REPORT ONLY, nothing dropped):`,
+			);
+			redundantIndexes.forEach((item) =>
+				console.log(`  ${item.table}.${item.indexName} - ${item.reason}  ${item.dropSql}`),
+			);
 		}
 
 		if (report.length > 0) {
@@ -2572,7 +2884,10 @@ export const publishConfigs = async (payload = {}, argv = {}) => {
 			success: true,
 			domainName,
 			domainVersion,
-			tablesProcessed: orderedTables.length,
+			tablesProcessed,
+			tablesSkipped,
+			redundantIndexes,
+			orphanColumns,
 			report,
 		};
 	} catch (error) {

package/engine/domain/applicationConfig.js

@@ -60,6 +60,9 @@ export const normalizeMenuNode = (menu) => {
 		caption,
 		link: Array.isArray(menu?.link) ? menu.link : inferredLink,
 		subMenu: normalizedChildren,
+		// Preserve a generic external-link leaf: a menu node may carry an externalUrl (opened in a new tab
+		// by the client) instead of an internal route. App-agnostic passthrough (only present when set).
+		...(typeof menu?.externalUrl === "string" && menu.externalUrl.trim().length > 0 ? { externalUrl: menu.externalUrl } : {}),
 	};
 };
 

package/engine/ext/live.js

@@ -109,25 +109,47 @@ export function createLiveExtDeps({
 			save({ [table]: record }, cfg(tenant)),
 		);
 
+	// A script reads its FINA connection from `data.arguments`, not from the worker config: the
+	// generated payment scripts (createPayment / callbackPG) build `{ dbindex, url:
+	// http://hostname:port }` out of it, and persistFlipLink passes that on to lib.db.executeBlock,
+	// where the worker MERGES it over its own config. So an empty `arguments` did not merely leave
+	// them unconfigured — it pointed them at http://undefined:undefined. Same shape scheduler
+	// scripts get from datalib.getInputData, minus `smtp`: nothing on the external path sends mail,
+	// so mail credentials have no business crossing this boundary.
+	const scriptArguments = (config) => {
+		const parts = String(config.url || "").split(":");
+		return {
+			hostname: (parts[1] || "").replace("//", ""),
+			port: Number(parts[2]),
+			dbindex: config.dbindex,
+			finaDbIndex: config.finaDbIndex,
+			subdomain: config.subdomain,
+		};
+	};
+
 	// CLI-backed op: run the op's OWN named script (execCLIScriptWorker — the safe named-run
 	// path, NOT hubEvent dispatch) with a server-derived principal (cliInvoke). Op params ride
 	// in as inert data; the script never sees caller roles.
 	const runCliScript = (tenant, op, params, claims) =>
-		executeCliOp(op, params, claims, (scriptRef, p, principal) =>
-			execCLIScriptWorker(
-				// Must carry the FINA `url` (execCLIScriptWorker + datalib build request URLs from
-				// it) — same config the projection/intake paths use, or the worker throws Invalid URL.
-				{ ...cfg(tenant), finaDbIndex: tenant.finaDbIndex },
+		executeCliOp(op, params, claims, (scriptRef, p, principal) => {
+			// Must carry the FINA `url` (execCLIScriptWorker + datalib build request URLs from
+			// it) — same config the projection/intake paths use, or the worker throws Invalid URL.
+			const workerConfig = {
+				...cfg(tenant),
+				finaDbIndex: tenant.finaDbIndex,
+			};
+			return execCLIScriptWorker(
+				workerConfig,
 				{ searchBy: "SCRIPT_NAME", searchValue: scriptRef },
 				{
-					arguments: {},
+					arguments: scriptArguments(workerConfig),
 					body: { params: p, principal },
 					path: "/ext-op",
 					query: {},
 					headers: { "user-agent": "biz-a-ext" },
 				},
-			),
-		);
+			);
+		});
 
 	const manifestStore = createManifestStore({
 		resolveTenant,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "biz-a-cli",
-	"version": "2.3.80-15280",
+	"version": "2.3.80-15292",
 	"description": "",
 	"main": "bin/index.js",
 	"type": "module",