biz-a-cli 2.3.80-15385 → 2.3.80-15397

package/bin/hub.js

@@ -130,6 +130,11 @@ const argv = yargs(process.argv.slice(2))
 		   show its rules behave. */
 		default: "observe",
 	})
+	.options("aiGateway", {
+		describe:
+			"Doc 1 0b.6b: base URL of the central AI gateway (biz-a-server /ai) that ccai calls. Defaults to this hub's server (serverMode).",
+		type: "string",
+	})
 	.options("services", {
 		describe:
 			"Comma-separated list of engine jobs this agent handles (e.g., 'BPM,EMAIL')",

package/bin/hubEvent.js

@@ -28,6 +28,14 @@ import { authorizeRequest, principalForCliScript } from "../security/internalPri
 import { whoami } from "../security/whoami.js";
 import { runDraftAction } from "../engine/cc/draftStore.js";
 import { createPgDraftRepo } from "../engine/cc/pgRepo.js";
+import { runMapAction } from "../engine/cc/mapStore.js";
+import { createMapRepo } from "../engine/cc/mapRepo.js";
+import { createGapRepo } from "../engine/cc/gapRepo.js";
+import { createTraceRepo } from "../engine/cc/traceRepo.js";
+import { createConfigReader } from "../engine/cc/currentConfig.js";
+import { runAiAction } from "../engine/cc/aiTurns.js";
+import { createTurnRepo } from "../engine/cc/turnRepo.js";
+import { createAiGatewayClient } from "../security/aiGatewayClient.js";
 import {
 	readUserPreferences,
 	writeUserPreferences,
@@ -47,7 +55,7 @@ import {
 	execPostgresTransaction,
 	isPostgresIndex,
 } from "../engine/domain/dialect.js";
-import { resolveTunnelTarget } from "./tunnelTarget.js";
+import { pipeTunnel } from "./tunnelTarget.js";
 /*
  * Doc 4 §8 — ⚠️ `runAsPrincipal` VALIDATES SYNCHRONOUSLY, so a browser-supplied active tenant outside
  * the signed claim throws out of the CALL, not out of the promise it would have returned. On this
@@ -232,59 +240,34 @@ export const streamEvent = async (socket, argv) =>
 				},
 			});
 
-			// let client = net.connect(argv['port'], argv['hostname']);
-			/* Where this pipe ends. A tenant this CLI serves on PostgreSQL is looped back to the
-			   hub's own FINA-compatible endpoint; every other tenant goes to FINA unchanged.
-			   Without this, biz-a's login — which only ever travels this tunnel — could not be
-			   answered at all on a tenant with no FINA running. */
-			const target = resolveTunnelTarget(argv, isPostgresIndex);
-			let client = target.secure
-				? tls.connect({
-						port: target.port,
-						host: target.host,
-						// Looping back to ourselves, the certificate is our own.
-						rejectUnauthorized: !target.local,
-					})
-				: net.connect(target.port, target.host);
-			client.on("connect", () => {
-				// logger.info(`client connected to ${argv['hostname']}:${argv['port']}`)
-				let s = ss.createStream();
-
-				// s.pipe(client).pipe(s);
-				s.pipe(client).pipe(addCLIAddressAsResponseHeader).pipe(s);
-
-				// use pipeline for better performance, back pressure, memory management, error handling and clean up
-				// pipeline(s, client, addCLIAddressAsResponseHeader, s, (err)=>{if (err) {logger.error(err)}}) // Not work well with heroku
-
-				s.on("end", () => {
-					client.destroy();
-				});
-
-				socket.once(clientId, () => {
-					// hub server shall notify us to end pipeline as soon as possible
-					client.end();
-				});
-
-				ss(socket).emit(clientId, s);
-			});
-
-			client.setTimeout(IDLE_SOCKET_TIMEOUT_MILLISECONDS);
-			client.on("timeout", () => {
-				// in case client not notify to end pipeline, then inactivity timeout will end it
-				client.end();
-			});
-
-			client.on("error", (err) => {
-				// handle connection refusal (create a stream and immediately close it)
-				logger.error(
-					`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ` +
-						`${target.host}:${target.port} — `,
-					err,
-				);
-				let s = ss.createStream();
-				ss(socket).emit(clientId, s);
-				s.end();
+			/*
+			 * Where this pipe ends is decided by the request's FIRST BYTES (bin/tunnelTarget.js): a tenant
+			 * this CLI serves on PostgreSQL, and — since 2026-10-01 — a Firebird tenant's LOGIN, are looped
+			 * back to the hub's own FINA-compatible endpoint; every other request goes to FINA unchanged.
+			 * Without the loop-back a Firebird login never passed through the CLI, so it never received
+			 * the signed principal (Doc 6 on Firebird).
+			 */
+			const s = ss.createStream();
+			pipeTunnel({
+				stream: s,
+				argv,
+				isPostgresIndex,
+				connect: (target) =>
+					target.secure
+						? tls.connect({
+								port: target.port,
+								host: target.host,
+								// Looping back to ourselves, the certificate is our own.
+								rejectUnauthorized: !target.local,
+							})
+						: net.connect(target.port, target.host),
+				transform: () => addCLIAddressAsResponseHeader,
+				idleMs: IDLE_SOCKET_TIMEOUT_MILLISECONDS,
+				// hub server shall notify us to end pipeline as soon as possible
+				onClient: (client) => socket.once(clientId, () => client.end()),
+				logger,
 			});
+			ss(socket).emit(clientId, s);
 		};
 
 		// const cliReqCb = async (data, callback) => {
@@ -480,6 +463,31 @@ const EngineRegistry = {
 		import("../engine/domain/applicationConfig.js"),
 };
 
+/* Doc 1 step 3 — what a Phase B turn needs: the draft store, the gap list, a draft opener that applies the
+   draft store's own rules (Layer 3, owned by Control Center) for the VERIFIED caller, one transaction, and
+   the publisher's DDL preview. */
+async function phaseBDeps(argv, headers) {
+	const exec = (sql) => execPostgres(sql, argv["dbindex"]);
+	const execStatements = (statements) => execPostgresStatements(statements, argv["dbindex"]);
+	const draftRepo = createPgDraftRepo({ exec, execStatements });
+	const principal = principalForCliScript(headers, { mode: argv["principalMode"] || "observe" });
+	const { buildDomainDdlPreview } = await import("../engine/domain/appConfig.js");
+	return {
+		draftRepo,
+		gapRepo: createGapRepo({ exec }),
+		traceRepo: createTraceRepo({ exec }),
+		openDraft: (kind, name) => runDraftAction({ repo: draftRepo, principal, isPostgres: true, action: "open", args: { kind, name } }),
+		execStatements,
+		ddlWarnings: (content) => buildDomainDdlPreview(JSON.stringify(content), argv["dbindex"]).warnings ?? [],
+	};
+}
+
+/* Doc 1 step 4d — what a derive turn reads: the configs as they are now (the OPEN draft, else published). */
+function deriveDeps(argv) {
+	const draftRepo = createPgDraftRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) });
+	return { draftRepo, readConfig: createConfigReader(draftRepo) };
+}
+
 const handleCliCommand = async (data, cb, argv) => {
 	try {
 		const command = data.command.trim().toLowerCase();
@@ -673,6 +681,38 @@ const handleCliCommand = async (data, cb, argv) => {
 			 * publish may). A refusal the user can act on is returned as `problems`, as companytheme
 			 * does; `code` carries CC_DRAFT_STALE for a save made from an old revision.
 			 */
+			/*
+			 * Doc 1 0b.6b — an AI turn from Control Center, through the central gateway
+			 * (engine/cc/aiTurns.js). `send` answers at once; the turn finishes in the background, is
+			 * recorded in SYS$CC_TURN with its cost, and the VERIFIED user is told {turnId, outcome}.
+			 * The CLI holds no AI key: the gateway client signs with this company's biza.ai key.
+			 */
+			case "ccai": {
+				const aiResult = await runAiAction({
+					repo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 2: an interview turn commits the process map. Step 4d: a derive turn commits it WITH its
+					   trace links, in one transaction. */
+					mapRepo: createMapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]), execStatements: (statements) => execPostgresStatements(statements, argv["dbindex"]) }),
+					/* Doc 1 step 4: an interview turn never removes what config implements. */
+					traceRepo: createTraceRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 3: a Phase B turn writes drafts, gaps and trace links in ONE transaction. */
+					config: ["generate", "refine"].includes(data.action) ? await phaseBDeps(argv, data.headers) : data.action === "derive" ? deriveDeps(argv) : undefined,
+					gateway: createAiGatewayClient({ baseUrl: argv["aiGateway"] || argv["server"], subdomain: argv["subdomain"] }),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+					notify: (userId, eventName, payload) => ClientEmitter.emitUsers([userId], eventName, payload),
+					logger,
+				});
+				cb(null, {
+					success: aiResult.ok,
+					...(aiResult.code ? { code: aiResult.code } : {}),
+					problems: aiResult.problems ?? [],
+					data: aiResult.data ?? null,
+				});
+				break;
+			}
 			case "ccdraft": {
 				const ccResult = await runDraftAction({
 					repo: createPgDraftRepo({
@@ -695,6 +735,31 @@ const handleCliCommand = async (data, cb, argv) => {
 				});
 				break;
 			}
+			/*
+			 * Doc 1 step 1 — the Business Process Map behind Process Studio (engine/cc/mapStore.js):
+			 * get / versions / save. A save is a new SYS$CC_PROCESS_MAP version, merged per element.
+			 */
+			case "ccmap": {
+				const mapResult = await runMapAction({
+					repo: createMapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					gapRepo: createGapRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					/* Doc 1 step 4: the trace panel — the links, the turns that told the story, the config they point at. */
+					traceRepo: createTraceRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					turnRepo: createTurnRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) }),
+					readConfig: createConfigReader(createPgDraftRepo({ exec: (sql) => execPostgres(sql, argv["dbindex"]) })),
+					principal: principalForCliScript(data.headers, { mode: argv["principalMode"] || "observe" }),
+					isPostgres: isPostgresIndex(argv["dbindex"]),
+					action: data.action,
+					args: data.args,
+				});
+				cb(null, {
+					success: mapResult.ok,
+					...(mapResult.code ? { code: mapResult.code } : {}),
+					problems: mapResult.problems ?? [],
+					data: mapResult.data ?? null,
+				});
+				break;
+			}
 			case "runextcliscript": {
 				// External-access op invoker — enforces the capability boundary (dispatch.js),
 				// unlike raw `runcliscript`. Safe to expose: no valid token -> UNAUTHENTICATED.

package/bin/tunnelTarget.js

@@ -11,8 +11,35 @@
  * database index, as it is everywhere else in this port.
  */
 
+/*
+ * ⚠️ Doc 6 on Firebird (found live 2026-10-01): the LOGIN of a Firebird tenant went straight to FINA
+ * through this tunnel, so the CLI never saw FINA's answer and never added the signed principal — and
+ * every principal-guarded command (company theme, logo, user preferences) refused on Firebird. The login
+ * is now looped back to the CLI's own endpoint too (finaEndpoint.js forwards it to FINA and appends the
+ * principal); every other Firebird request still goes straight to FINA, byte for byte.
+ *
+ * Recognised by its REQUEST LINE only (method + path), never by anything in a body.
+ */
+const LOGIN_PATH = /%22get_valid_user_id%22|"get_valid_user_id"/i;
+
+export const isLoginRequest = (firstChunk) => {
+	if (!firstChunk || firstChunk.length === 0) return false;
+	const head = Buffer.from(firstChunk).subarray(0, 2048).toString("latin1");
+	const lineEnd = head.indexOf("\r\n");
+	const requestLine = lineEnd === -1 ? head : head.slice(0, lineEnd);
+	const [method, path] = requestLine.split(" ");
+	return method === "POST" && typeof path === "string" && LOGIN_PATH.test(path);
+};
+
+const ownEndpoint = (argv) => ({
+	host: "127.0.0.1", // ourselves — never the public interface
+	port: argv.serverport,
+	secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
+	local: true,
+});
+
 /* Kept separate from hubEvent.js so it can be exercised without importing the socket machinery. */
-export const resolveTunnelTarget = (argv, isPostgresIndex) => {
+export const resolveTunnelTarget = (argv, isPostgresIndex, firstChunk) => {
 	const fina = {
 		host: argv.hostname,
 		port: argv.port,
@@ -20,6 +47,7 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 		local: false,
 	};
 
+	if (isLoginRequest(firstChunk)) return ownEndpoint(argv);
 	if (!argv.dbindex) return fina;
 
 	let servedHere = false;
@@ -32,10 +60,35 @@ export const resolveTunnelTarget = (argv, isPostgresIndex) => {
 	}
 	if (!servedHere) return fina;
 
-	return {
-		host: "127.0.0.1", // ourselves — never the public interface
-		port: argv.serverport,
-		secure: argv.isHttps === true, // how WE listen; argv.secure describes FINA
-		local: true,
-	};
+	return ownEndpoint(argv);
+};
+
+/*
+ * One tunnelled request: biz-a's bytes arrive on `stream`; the connection is opened only once the first
+ * bytes say where it must go (resolveTunnelTarget), that first chunk is written first so nothing is
+ * lost, and the rest is piped. The answer flows back through `transform()` (the response-header
+ * injection). A connection that fails ends the stream, so biz-a is not left waiting.
+ */
+export const pipeTunnel = ({ stream, argv, isPostgresIndex, connect, transform, idleMs, onClient, logger = console }) => {
+	stream.once("data", (first) => {
+		stream.pause();
+		const target = resolveTunnelTarget(argv, isPostgresIndex, first);
+		const client = connect(target);
+		onClient?.(client);
+		if (idleMs) client.setTimeout(idleMs);
+		client.on("timeout", () => client.end());
+		client.on("connect", () => {
+			client.write(first);
+			stream.pipe(client).pipe(transform()).pipe(stream);
+			stream.resume();
+		});
+		client.on("error", (err) => {
+			logger.error?.(
+				`API Error : tunnel could not reach ${target.local ? "this CLI's own endpoint" : "the API"} at ${target.host}:${target.port} — `,
+				err,
+			);
+			stream.end();
+		});
+		stream.on("end", () => client.destroy());
+	});
 };

package/engine/bpm/workflow-runtime.js

@@ -218,14 +218,14 @@ export async function initiate(payload) {
 		current_state_code: def.initial_state_code,
 		status: "ACTIVE",
 		version_no: def.version,
-		created_by: userId || null,
+		created_by: userId ?? null,
 		SYS$BPM_STATE_HISTORY: [
 			{
 				from_state_code: null,
 				to_state_code: def.initial_state_code,
 				trigger_type: "SYSTEM",
 				actor_type: "USER",
-				actor_id: userId || null,
+				actor_id: userId ?? null,
 				request_id: `START_${entityType}_${entityId}_${new Date().getTime()}`,
 			},
 		],
@@ -773,7 +773,7 @@ export async function terminate(payload) {
 			to_state_code: currentStateCode,
 			trigger_type: "USER_EVENT",
 			actor_type: "USER",
-			actor_id: userId || null,
+			actor_id: userId ?? null,
 			request_id: `TERMINATE_${instanceId}_${new Date().getTime()}`,
 		},
 	};