@olenbetong/appframe-vite 6.0.4 → 6.1.1

package/lib/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/lib/cli.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { config } from "dotenv";
+import { runGenerateTypes } from "./generateTypes.js";
+import { importJson } from "./importJson.js";
+import { createLogMessage } from "./utils.js";
+async function generateTypes() {
+    config({ path: `${process.cwd()}/.env`, quiet: true });
+    const pkg = await importJson("./package.json", true);
+    const hostname = pkg.appframe.proxy?.hostname ?? "dev.obet.no";
+    const { APPFRAME_LOGIN: username = "", APPFRAME_PWD: password = "" } = process.env;
+    const logger = {
+        info: (msg) => console.log(msg),
+        error: (msg) => console.error(msg),
+    };
+    logger.info(createLogMessage("Generating types…", { source: hostname }));
+    await runGenerateTypes(hostname, username, password, pkg.appframe, logger);
+}
+const [, , command] = process.argv;
+switch (command) {
+    case "generate-types":
+        await generateTypes();
+        break;
+    default:
+        console.error(createLogMessage(`Unknown command: ${command ?? "(none)"}`, { type: "error" }));
+        console.error("Usage: appframe-vite <command>");
+        console.error("Commands:");
+        console.error("  generate-types  Generate TypeScript type definitions");
+        process.exit(1);
+}

package/lib/devServer.js

@@ -1,11 +1,12 @@
-import { Client } from "@olenbetong/appframe-data";
-import dotenv from "dotenv";
-import { JSDOM } from "jsdom";
 import { existsSync } from "node:fs";
 import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { Client } from "@olenbetong/appframe-data";
+import dotenv from "dotenv";
+import { JSDOM } from "jsdom";
 import { importJson } from "./importJson.js";
 import { getStringCache } from "./localization.js";
+import { diagnoseServerResponse } from "./utils.js";
 dotenv.config({ quiet: true });
 let appPkg = await importJson("./package.json", true);
 let { appframe } = appPkg;
@@ -129,7 +130,27 @@ async function getArticleHtml() {
     let { hostname, username, password } = await getLoginInfo();
     let article = appframe.article?.id;
     let client = new Client(hostname);
-    await client.login(username, password);
+    try {
+        await client.login(username, password);
+    }
+    catch (loginError) {
+        const isJsonError = loginError instanceof SyntaxError &&
+            (loginError.message.includes("not valid JSON") || loginError.message.includes("Unexpected token"));
+        if (isJsonError) {
+            let loginBody = `username=${encodeURIComponent(username)}&password=${encodeURIComponent(password)}&remember=true&RequireTwoFactor=0`;
+            let diagnostic = await diagnoseServerResponse(`https://${hostname}/login`, {
+                method: "POST",
+                body: loginBody,
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                followRedirects: true,
+            });
+            throw new Error(`login to ${hostname} (article HTML fetch): server returned non-JSON. Server response:\n${diagnostic}`);
+        }
+        throw loginError;
+    }
     let response = await client.fetch(`/${article}`, {
         timeout: 30_000,
         method: "GET",

package/lib/generateTypes.d.ts

@@ -0,0 +1,4 @@
+import type { ViteDevServer } from "vite";
+type Logger = Pick<ViteDevServer["config"]["logger"], "info" | "error">;
+export declare function runGenerateTypes(hostname: string, username: string, password: string, appframe: any, logger: Logger): Promise<void>;
+export {};

package/lib/generateTypes.js

@@ -0,0 +1,250 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import fs from "node:fs/promises";
+import { resolve } from "node:path";
+import vm from "node:vm";
+import { Client, DataObject, generateApiDataHandler, getDefaultClient, Procedure, setDefaultClient, } from "@olenbetong/appframe-data";
+import { importJson } from "./importJson.js";
+import { createLogMessage, diagnoseServerResponse, wrapJsonError } from "./utils.js";
+// ─── Type generation logic ────────────────────────────────────────────────────
+function afTypeToTsType(type, isProc = false) {
+    if (type === "uniqueidentifier")
+        return "string";
+    if (type && ["date", "datetime"].includes(type))
+        return isProc ? "string | Date" : "Date";
+    return type ?? "string";
+}
+function getDataObjectTypes(af, parameterOverrides = {}) {
+    let result = [];
+    let globals = [];
+    let dataObjects = Object.values((af.article?.dataObjects ?? {})).sort((a, b) => a.getDataSourceId() >= b.getDataSourceId() ? 1 : -1);
+    for (let dataObject of dataObjects) {
+        let id = dataObject.getDataSourceId();
+        let typeName = id.startsWith("ds") ? id.substring(2) : id;
+        typeName = `${typeName}Record`;
+        result.push(`export interface ${typeName} extends Record<string, unknown> {`);
+        for (let field of dataObject.getFields()) {
+            let type = parameterOverrides[id]?.[field.name] ??
+                afTypeToTsType(field.type ?? "string") + (field.nullable ? " | null" : "");
+            let propName = field.alias ?? field.aliasName ?? field.name;
+            let fieldName = propName.indexOf("-") > 0 ? `"${propName}"` : propName;
+            result.push(`\t${fieldName}: ${type};`);
+        }
+        result.push("};");
+        result.push("");
+        globals.push(`${id}: DataObject<${typeName}>;`);
+    }
+    if (globals.length === 0)
+        return "";
+    result.push("declare global {");
+    result.push(globals.map((g) => `\tvar ${g}`).join("\n"));
+    result.push("\tinterface Window {");
+    result.push(globals.map((g) => `\t\t${g}`).join("\n"));
+    result.push("\t}");
+    result.push("}");
+    return result.join("\n");
+}
+function getProcedureTypes(af, parameterOverrides = {}, returnTypes = {}) {
+    let result = [];
+    let globals = [];
+    let procedures = Object.values((af.article?.procedures ?? {})).sort((a, b) => (a.options.procedureId >= b.options.procedureId ? 1 : -1));
+    for (let procedure of procedures) {
+        let id = procedure.options.procedureId;
+        let params = procedure.getParameters();
+        let typeName = id.startsWith("proc") ? id.substring(4) : id;
+        typeName = `${typeName}Params`;
+        if (params.length > 0) {
+            result.push(`export type ${typeName} = {`);
+            for (let param of params) {
+                let type = parameterOverrides[id]?.[param.name] ?? `${afTypeToTsType(param.type, true)} | null`;
+                let required = parameterOverrides[id]?.__required?.includes(param.name);
+                result.push(`\t${param.name}${required || param.required ? "" : "?"}: ${type};`);
+            }
+            result.push("};");
+            result.push("");
+        }
+        else {
+            result.push(`export type ${typeName} = null | undefined | Record<string, never>;\n`);
+        }
+        globals.push(`${id}: Procedure<${typeName}, ${Object.keys(returnTypes).includes(id) ? returnTypes[id] : "any"}>;`);
+    }
+    if (globals.length === 0)
+        return "";
+    result.push("declare global {");
+    result.push(globals.map((g) => `\tvar ${g}`).join("\n"));
+    result.push("\tinterface Window {");
+    result.push(globals.map((g) => `\t\t${g}`).join("\n"));
+    result.push("\t}");
+    result.push("}");
+    return result.join("\n");
+}
+function buildTypes(af, customExists = false, overridesConfig = {}) {
+    let dataObjects = getDataObjectTypes(af, overridesConfig.parameterTypes);
+    let procedures = getProcedureTypes(af, overridesConfig.parameterTypes, overridesConfig.procedureReturnTypes);
+    let types = [];
+    if (dataObjects.length)
+        types.push("DataObject");
+    if (procedures.length)
+        types.push("Procedure");
+    let result = [
+        `import type { ${types.join(", ")} } from "@olenbetong/appframe-data";${customExists && (dataObjects.includes("Custom.") || procedures.includes("Custom."))
+            ? '\nimport type * as Custom from "./custom";'
+            : ""}`,
+    ];
+    if (dataObjects.length)
+        result.push(dataObjects);
+    if (procedures.length)
+        result.push(procedures);
+    return result.join("\n\n");
+}
+// ─── Article features ─────────────────────────────────────────────────────────
+function createArticlesFeaturesDataHandler() {
+    return generateApiDataHandler({
+        client: getDefaultClient(),
+        resource: "aviw_FeatureMgmt_ArticlesFeatures",
+        fields: [
+            { name: "HostName", type: "string", nullable: false },
+            { name: "ArticleId", type: "string", nullable: false },
+            { name: "Key", type: "string", nullable: false },
+            { name: "Name", type: "string", nullable: false },
+            { name: "Description", type: "string", nullable: true },
+        ],
+    });
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function withTimeout(promise, ms, label) {
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out: ${label}`)), ms)),
+    ]);
+}
+/** Run biome format on a file. Silently skips if biome is unavailable. */
+async function formatFile(filePath) {
+    await new Promise((resolve) => {
+        const child = spawn("pnpm", ["biome", "format", filePath, "--write"], {
+            shell: process.platform === "win32",
+            stdio: "pipe",
+        });
+        child.on("close", () => resolve());
+        child.on("error", () => resolve());
+    });
+}
+// ─── Core type generation ─────────────────────────────────────────────────────
+const TIMEOUT_MS = 30_000;
+const MAX_RETRIES = 3;
+const RETRY_DELAY_BASE_MS = 2_000;
+async function doGenerateTypes(hostname, username, password, appframe) {
+    const client = new Client(hostname);
+    setDefaultClient(client);
+    try {
+        await withTimeout(client.login(username, password), TIMEOUT_MS, "login");
+    }
+    catch (loginError) {
+        const isJsonError = loginError instanceof SyntaxError &&
+            (loginError.message.includes("not valid JSON") || loginError.message.includes("Unexpected token"));
+        if (isJsonError) {
+            let loginBody = `username=${encodeURIComponent(username)}&password=${encodeURIComponent(password)}&remember=true&RequireTwoFactor=0`;
+            let diagnostic = await diagnoseServerResponse(`https://${hostname}/login`, {
+                method: "POST",
+                body: loginBody,
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                followRedirects: true,
+            });
+            throw new Error(`login to ${hostname}: server returned non-JSON. Server response:\n${diagnostic}`);
+        }
+        throw loginError;
+    }
+    const articleId = appframe.article?.id ?? appframe.article;
+    const articleHost = appframe.article?.hostname ?? hostname;
+    const scriptGlobal = {
+        __VERSION__: "0.1.0",
+        af: {
+            controls: new Proxy({}, { get: () => class {
+                } }),
+            common: {
+                expose(path, value) {
+                    let properties = path.split(".");
+                    let final = properties.pop();
+                    let current = scriptGlobal;
+                    for (let prop of properties) {
+                        if (!current[prop])
+                            current[prop] = {};
+                        current = current[prop];
+                    }
+                    current[final] = value;
+                },
+                localStorage: {
+                    get(_, fallback) {
+                        return fallback;
+                    },
+                },
+            },
+            DataObject,
+            Procedure,
+        },
+    };
+    const response = await withTimeout(client.fetch(`/file/article/static-script/${articleId}.js`, { timeout: TIMEOUT_MS }), TIMEOUT_MS, "fetch article script");
+    if (!response.ok) {
+        throw new Error(`Failed to fetch article script: ${response.status} ${response.statusText}`);
+    }
+    const scriptText = await response.text();
+    const context = vm.createContext(scriptGlobal);
+    new vm.Script(scriptText).runInContext(context);
+    // Resolve custom types file
+    let customTypesPath = "./src/custom.d.ts";
+    let hasCustomTypesFile = existsSync(resolve(process.cwd(), customTypesPath));
+    if (!hasCustomTypesFile) {
+        customTypesPath = "./src/custom.ts";
+        hasCustomTypesFile = existsSync(resolve(process.cwd(), customTypesPath));
+    }
+    let typeOverrides = {};
+    try {
+        typeOverrides = await importJson("./types.json", true);
+    }
+    catch {
+        // No overrides file — that's fine
+    }
+    let types = buildTypes(scriptGlobal.af, hasCustomTypesFile, typeOverrides);
+    const headerComment = "// This file is automatically generated. Do not modify directly;\n" +
+        "// your changes will be overwritten. To customize the generated types,\n" +
+        "// edit `types.json` and `src/custom.d.ts`.\n\n";
+    types = headerComment + types;
+    // Append article feature flags
+    const dsFeatures = createArticlesFeaturesDataHandler();
+    const features = await wrapJsonError(`fetch article features for '${articleId}' on ${articleHost}`, () => withTimeout(dsFeatures.retrieve({
+        maxRecords: -1,
+        whereClause: `[HostName] = '${articleHost}' AND [ArticleId] = '${articleId}'`,
+    }), TIMEOUT_MS, "fetch article features"));
+    if (features.length) {
+        types += `\n\ndeclare module "@olenbetong/appframe-core" {\n\tinterface AfArticle {\n\t\tfeatures: {\n\t\t\t${features
+            .map((f) => `/**\n\t\t\t * ${f.Name}: ${f.Description}\n\t\t\t */\n\t\t\t${f.Key}: boolean;`)
+            .join("\n\t\t\t")}\n\t\t};\n\t}\n}`;
+    }
+    const outPath = resolve(process.cwd(), "./src/appframe.d.ts");
+    await fs.writeFile(outPath, new Uint8Array(Buffer.from(types)));
+    await formatFile("./src/appframe.d.ts");
+}
+export async function runGenerateTypes(hostname, username, password, appframe, logger) {
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            await doGenerateTypes(hostname, username, password, appframe);
+            logger.info(createLogMessage("typescript types generated successfully", { source: hostname }));
+            return;
+        }
+        catch (error) {
+            if (attempt < MAX_RETRIES) {
+                // Exponential backoff before retry
+                await new Promise((r) => setTimeout(r, RETRY_DELAY_BASE_MS * attempt));
+            }
+            else {
+                logger.error(createLogMessage(`failed to generate types after ${MAX_RETRIES} attempt(s): ${error?.message ?? error}`, {
+                    source: hostname,
+                    type: "error",
+                }));
+            }
+        }
+    }
+}

package/lib/index.js

@@ -2,9 +2,10 @@ import bodyParser from "body-parser";
 import { watch } from "chokidar";
 import { addAppframeBuildConfig } from "./build.js";
 import { createDevMiddleware, getLoginInfo, getProxyRoutes } from "./devServer.js";
-import { importJson } from "./importJson.js";
+import { runGenerateTypes } from "./generateTypes.js";
 import { localizeMiddleware } from "./localization.js";
-import { getLastSession, login } from "./proxy.js";
+import { checkSession, getLastSession, login } from "./proxy.js";
+import { createLogMessage, getServerName } from "./utils.js";
 let command = "build";
 let interval;
 let server;
@@ -22,7 +23,7 @@ try {
     });
 }
 catch (error) {
-    console.log(`Failed to watch package.json: ${error.message}`);
+    console.log(createLogMessage(`failed to watch package.json: ${error.message}`, { type: "warn" }));
 }
 const jsonParser = bodyParser.json();
 export default function appframe() {
@@ -86,14 +87,25 @@ export default function appframe() {
                 let { hostname, username, password } = await getLoginInfo();
                 lastHostname = hostname;
                 await login(hostname, username, password);
+                console.log(createLogMessage(`connected to '${getServerName(hostname)}'`, { source: hostname }));
                 if (interval)
                     clearInterval(interval);
-                // After changing the plugin to use the Vite proxy instead of a custom
-                // express server with node-http-proxy, we can no longer ensure the requests
-                // have a valid login. To reduce the amount of problems we get with expired
-                // sessions, we run the login procedure every 5 minutes to renew the session.
+                // Every 5 minutes, probe /api/user/usersession to check whether the session
+                // is still alive. Only re-authenticates if the server reports it has expired.
+                // Runs silently — only logs if renewal fails.
                 interval = setInterval(async () => {
-                    await login(hostname, username, password);
+                    try {
+                        const alive = await checkSession(hostname);
+                        if (!alive) {
+                            await login(hostname, username, password, { silent: true });
+                        }
+                    }
+                    catch (error) {
+                        server?.config.logger.error(createLogMessage(`session renewal failed: ${error?.message ?? error}`, {
+                            source: hostname,
+                            type: "error",
+                        }));
+                    }
                 }, 1000 * 60 * 5);
                 for (let route of routes) {
                     proxy[route] = {
@@ -123,16 +135,18 @@ export default function appframe() {
             return config;
         },
         async configureServer(_server) {
-            let { appframe } = await importJson("./package.json", true);
+            let { appframe, hostname, username, password } = await getLoginInfo();
             server = _server;
+            // Run type generation in the background — doesn't block the dev server from starting.
+            runGenerateTypes(hostname, username, password, appframe, _server.config.logger);
             _server.middlewares.use(`/api/user/localize/new/${appframe.article.id}`, jsonParser);
             _server.middlewares.use(`/api/user/localize/new/${appframe.article.id}`, localizeMiddleware);
             _server.middlewares.use("/data/Logger/LogError", jsonParser);
             _server.middlewares.use("/data/Logger/LogError", (req, res) => {
                 // @ts-expect-error
-                if (req.body?.error) {
-                    // @ts-expect-error
-                    console.log("[Client error]", req.body?.error);
+                let error = req.body?.error;
+                if (error) {
+                    console.log(createLogMessage(error, { source: "client", type: "error" }));
                 }
                 res.statusCode = 200;
                 res.end("");

package/lib/localization.js

@@ -67,6 +67,13 @@ export const localizeMiddleware = async (req, res, _next) => {
                 "X-Requested-With": "XMLHttpRequest",
             },
         });
+        const contentType = result.headers.get("content-type") ?? "";
+        if (!result.ok || !contentType.includes("application/json")) {
+            let body = await result.text();
+            throw new Error(`POST ${uri} returned ${result.status} ${result.statusText} ` +
+                `(Content-Type: ${contentType || "none"}). ` +
+                `Response snippet: ${body.slice(0, 300)}`);
+        }
         let data = await result.json();
         addStringToCache(text, data);
         res.statusCode = 200;

package/lib/proxy.d.ts

@@ -4,5 +4,13 @@ type LoginCacheEntry = {
     authCookies: CookieObject;
 };
 export declare function getLastSession(hostname: string): LoginCacheEntry | undefined;
-export declare function login(hostname: string, username: string, password: string): Promise<CookieObject>;
+/**
+ * Checks whether the current cached session for the given hostname is still
+ * valid on the server by probing GET /api/user/usersession. Returns true if
+ * the session is alive (200 OK), false if it has expired (redirect/error).
+ */
+export declare function checkSession(hostname: string): Promise<boolean>;
+export declare function login(hostname: string, username: string, password: string, loginOptions?: {
+    silent?: boolean;
+}): Promise<CookieObject>;
 export {};

package/lib/proxy.js

@@ -1,8 +1,55 @@
-import chalk from "chalk";
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
 import https from "node:https";
+import { dirname, resolve } from "node:path";
+import { createLogMessage } from "./utils.js";
 const lastLogin = new Map();
 let currentLogin = null;
 const isInteractive = process.stdout.isTTY;
+// Re-auth only when the cached session is older than this. The keepalive
+// checkSession() probe handles actual liveness, so this just limits how
+// often we do a full HTTP login when restarting dev servers.
+const SESSION_MAX_AGE_MS = 4 * 60 * 60 * 1000; // 4 hours
+// ─── Shared session store ─────────────────────────────────────────────────────
+function findWorkspaceRoot(startDir) {
+    let dir = startDir;
+    while (true) {
+        if (existsSync(resolve(dir, "pnpm-workspace.yaml")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return startDir; // reached fs root, fall back
+        dir = parent;
+    }
+}
+const sharedSessionDir = resolve(findWorkspaceRoot(process.cwd()), "node_modules/.appframe");
+const sharedSessionFile = resolve(sharedSessionDir, "sessions.json");
+async function readSessionStore() {
+    try {
+        const raw = await readFile(sharedSessionFile, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function writeSessionStore(hostname, entry) {
+    // Fire-and-forget: best-effort, errors are silently ignored.
+    (async () => {
+        try {
+            if (!existsSync(sharedSessionDir)) {
+                mkdirSync(sharedSessionDir, { recursive: true });
+            }
+            const store = await readSessionStore();
+            store[hostname] = entry;
+            await writeFile(sharedSessionFile, JSON.stringify(store, null, "\t"));
+        }
+        catch {
+            // Ignore write errors
+        }
+    })();
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
 function write(text) {
     if (isInteractive) {
         process.stdout.write?.(text);
@@ -15,20 +62,64 @@ export function getLastSession(hostname) {
     return lastLogin.get(hostname);
 }
 const agent = new https.Agent({ keepAlive: false });
-export async function login(hostname, username, password) {
+/**
+ * Checks whether the current cached session for the given hostname is still
+ * valid on the server by probing GET /api/user/usersession. Returns true if
+ * the session is alive (200 OK), false if it has expired (redirect/error).
+ */
+export async function checkSession(hostname) {
+    const session = lastLogin.get(hostname);
+    if (!session)
+        return false;
+    const { authCookies } = session;
+    const cookieParts = [];
+    if (authCookies["AppframeWebAuth"])
+        cookieParts.push(`AppframeWebAuth=${authCookies["AppframeWebAuth"]}`);
+    if (authCookies["AppframeWebSession"])
+        cookieParts.push(`AppframeWebSession=${authCookies["AppframeWebSession"]}`);
+    return new Promise((resolve) => {
+        const options = {
+            agent,
+            hostname,
+            port: 443,
+            path: "/api/user/usersession",
+            method: "GET",
+            headers: {
+                Cookie: cookieParts.join(";"),
+                Accept: "application/json",
+            },
+        };
+        const req = https.request(options, (response) => {
+            response.resume(); // drain body to free the connection
+            resolve(response.statusCode === 200);
+        });
+        req.on("error", () => resolve(false));
+        req.end();
+    });
+}
+export async function login(hostname, username, password, loginOptions) {
+    const silent = loginOptions?.silent ?? false;
+    // Hydrate in-memory cache from the shared disk store if this is the first
+    // call for this hostname (covers restarts and cross-app session sharing).
+    if (!lastLogin.has(hostname)) {
+        const store = await readSessionStore();
+        if (store[hostname]) {
+            lastLogin.set(hostname, store[hostname]);
+        }
+    }
     if (currentLogin) {
         await currentLogin;
     }
     let loginPromise = new Promise((resolve, reject) => {
-        let hostPrefix = `[${hostname.split(".")[0]}]`;
         if (lastLogin.has(hostname)) {
-            let { timestamp, authCookies } = lastLogin.get(hostname);
-            if (Date.now() - timestamp < 1000 * 60 * 15) {
+            let { timestamp: cachedAt, authCookies } = lastLogin.get(hostname);
+            if (Date.now() - cachedAt < SESSION_MAX_AGE_MS) {
                 resolve(authCookies);
                 return;
             }
             else {
-                write(`${chalk.bgBlueBright(hostPrefix)} Renewing authentication cookies...`);
+                if (!silent)
+                    write(createLogMessage("renewing authentication cookies...", { source: hostname }));
                 lastLogin.delete(hostname);
             }
         }
@@ -45,14 +136,21 @@ export async function login(hostname, username, password) {
                 "Content-Length": data.length,
             },
         };
-        process.stdout.clearLine?.(0);
-        process.stdout.cursorTo?.(0);
-        write(`\r${chalk.bgBlueBright(hostPrefix)} Authenticating.`);
-        let initialCursorPos = `${hostPrefix} Authenticating.`.length;
+        if (!silent) {
+            process.stdout.clearLine?.(0);
+            process.stdout.cursorTo?.(0);
+        }
+        let initialLogMessage = createLogMessage("authenticating.", { source: hostname });
+        if (!silent) {
+            write(`\r${initialLogMessage}`);
+        }
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: is there another way?
+        let strippedInitialLogMessage = initialLogMessage.replace(/\u001b\[[0-9]+m/g, ""); // remove ANSI color codes for accurate cursor positioning
+        let initialCursorPos = strippedInitialLogMessage.length;
         let start = performance.now();
         let counter = 0;
         let interval = setInterval(() => {
-            if (isInteractive) {
+            if (!silent && isInteractive) {
                 if (counter >= 2) {
                     process.stdout.cursorTo?.(initialCursorPos);
                     write("   ");
@@ -78,21 +176,27 @@ export async function login(hostname, username, password) {
                         cookieObj[key] = value;
                     }
                 }
-                process.stdout.clearLine?.(0);
-                process.stdout.cursorTo?.(0);
-                write(`${chalk.bgBlueBright(hostPrefix)} Authenticated (${Math.floor(performance.now() - start)}ms)\n`);
-                lastLogin.set(hostname, {
-                    timestamp: Date.now(),
-                    authCookies: cookieObj,
-                });
+                if (!silent) {
+                    process.stdout.clearLine?.(0);
+                    process.stdout.cursorTo?.(0);
+                    write(createLogMessage(`authenticated (${Math.floor(performance.now() - start)}ms)\n`, {
+                        source: hostname,
+                    }));
+                }
+                const entry = { timestamp: Date.now(), authCookies: cookieObj };
+                lastLogin.set(hostname, entry);
+                writeSessionStore(hostname, entry);
                 resolve(cookieObj);
             }
             else {
-                reject(Error(`${chalk.bgBlueBright(hostname)}: Authentication failed: ${response.statusCode} ${response.statusMessage}`));
+                reject(Error(createLogMessage(`authentication failed: ${response.statusCode} ${response.statusMessage}`, {
+                    source: hostname,
+                    type: "error",
+                })));
             }
         });
         request.on("error", (error) => {
-            console.error(error.message);
+            console.error(createLogMessage(error.message, { source: hostname, type: "error" }));
         });
         request.write(data);
         request.end();

package/lib/utils.d.ts

@@ -0,0 +1,40 @@
+/** Returns the current time as `HH:mm:ss` in gray, matching Vite's log format. */
+export declare function timestamp(): string;
+/** Standard `[appframe-vite]` tag for plugin-level log messages. */
+export declare const PLUGIN_TAG: string;
+/** Returns a colored environment tag (`[dev]` / `[stage]` / `[prod]`) based on hostname. */
+export declare function getServerPrefix(hostname: string): string;
+export declare function getServerName(hostname: string): string;
+/**
+ * Wraps an async operation. If the caught error is a JSON parse error
+ * (SyntaxError from undici/fetch `.json()` on an HTML response), re-throws
+ * with `context` prepended so it's obvious which network call failed.
+ */
+export declare function wrapJsonError<T>(context: string, fn: () => Promise<T>): Promise<T>;
+/**
+ * Makes a diagnostic HTTP request and returns the full response body + metadata
+ * as a human-readable string. Used to show what the server is actually returning
+ * when a JSON-parse error occurs inside a library that swallows the response body.
+ *
+ * Pass followRedirects: true to follow the redirect chain (useful when the library
+ * auto-follows redirects and fails on the final response).
+ */
+export declare function diagnoseServerResponse(url: string, options?: {
+    method?: string;
+    body?: string;
+    headers?: Record<string, string>;
+    followRedirects?: boolean;
+}): Promise<string>;
+export interface LogMessageOptions {
+    /** Pre-formatted chalk tag, e.g. from `getServerPrefix()` or `PLUGIN_TAG`. */
+    tag?: string;
+    /** Parenthetical source label, e.g. `"client"` renders as `(client)`. */
+    source?: string;
+    /** Controls message text color. Defaults to uncolored. */
+    type?: "info" | "warn" | "error";
+}
+/**
+ * Assembles a consistently-formatted log message:
+ * `HH:mm:ss [tag] (source) message`
+ */
+export declare function createLogMessage(message: string, options?: LogMessageOptions): string;

package/lib/utils.js

@@ -0,0 +1,102 @@
+import chalk from "chalk";
+/** Returns the current time as `HH:mm:ss` in gray, matching Vite's log format. */
+export function timestamp() {
+    return chalk.gray(new Date().toLocaleTimeString("en-GB", { hour: "2-digit", minute: "2-digit", second: "2-digit" }));
+}
+/** Standard `[appframe-vite]` tag for plugin-level log messages. */
+export const PLUGIN_TAG = chalk.cyan("[appframe-vite]");
+/** Returns a colored environment tag (`[dev]` / `[stage]` / `[prod]`) based on hostname. */
+export function getServerPrefix(hostname) {
+    if (hostname.startsWith("dev"))
+        return chalk.bgGreen("[dev]");
+    if (hostname.startsWith("stage"))
+        return chalk.bgYellow("[stage]");
+    return chalk.bgRed("[prod]");
+}
+export function getServerName(hostname) {
+    const devPattern = /^(dev|dev-prod|dev\.synergi)\.obet\.no$/;
+    if (devPattern.test(hostname)) {
+        return "SynergiDev";
+    }
+    const partnerDevPattern = /^(dev|dev-prod)\.partner\.obet\.no$/;
+    if (partnerDevPattern.test(hostname)) {
+        return "PartnerDev";
+    }
+    const stagePattern = /^(stage|stage-prod|stage\.synergi)\.obet\.no$/;
+    if (stagePattern.test(hostname)) {
+        return "SynergiStage";
+    }
+    const partnerStagePattern = /^(stage|stage-prod)\.partner\.obet\.no$/;
+    if (partnerStagePattern.test(hostname)) {
+        return "PartnerStage";
+    }
+    const webPattern = /^(test|test\.synergi|synergi)\.(olenbetong|obet)\.no$/;
+    if (webPattern.test(hostname)) {
+        return "SynergiWeb";
+    }
+    const partnerWebPattern = /^(test|test\.partner|partner)\.(olenbetong|obet)\.no$/;
+    if (partnerWebPattern.test(hostname)) {
+        return "Partner";
+    }
+    return hostname;
+}
+/**
+ * Wraps an async operation. If the caught error is a JSON parse error
+ * (SyntaxError from undici/fetch `.json()` on an HTML response), re-throws
+ * with `context` prepended so it's obvious which network call failed.
+ */
+export async function wrapJsonError(context, fn) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        if (error instanceof SyntaxError &&
+            (error.message.includes("not valid JSON") || error.message.includes("Unexpected token"))) {
+            throw new Error(`${context}: server returned non-JSON — likely an HTML redirect or error page. ` +
+                `Original parse error: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Makes a diagnostic HTTP request and returns the full response body + metadata
+ * as a human-readable string. Used to show what the server is actually returning
+ * when a JSON-parse error occurs inside a library that swallows the response body.
+ *
+ * Pass followRedirects: true to follow the redirect chain (useful when the library
+ * auto-follows redirects and fails on the final response).
+ */
+export async function diagnoseServerResponse(url, options = {}) {
+    const method = options.method ?? "GET";
+    const redirect = options.followRedirects ? "follow" : "manual";
+    try {
+        const res = await fetch(url, {
+            method,
+            headers: { Accept: "text/html,application/json,*/*", ...options.headers },
+            body: options.body,
+            redirect,
+        });
+        const contentType = res.headers.get("content-type") ?? "(none)";
+        const location = res.headers.get("location");
+        const body = await res.text();
+        let info = `${method} ${url} → ${res.status} ${res.statusText} | Content-Type: ${contentType}`;
+        if (location)
+            info += ` | Location: ${location}`;
+        if (res.redirected)
+            info += ` | Final URL: ${res.url}`;
+        info += `\n--- Response body ---\n${body}\n--- End of body ---`;
+        return info;
+    }
+    catch (diagError) {
+        return `${method} ${url} failed: ${diagError?.message ?? diagError}`;
+    }
+}
+/**
+ * Assembles a consistently-formatted log message:
+ * `HH:mm:ss [tag] (source) message`
+ */
+export function createLogMessage(message, options = {}) {
+    const { tag = PLUGIN_TAG, source, type } = options;
+    const coloredMessage = type === "error" ? chalk.red(message) : type === "warn" ? chalk.yellow(message) : message;
+    return [timestamp(), tag, source ? chalk.gray(`(${source})`) : undefined, coloredMessage].filter(Boolean).join(" ");
+}

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@olenbetong/appframe-vite",
-  "version": "6.0.4",
+  "version": "6.1.1",
   "description": "Tools to use and deploy Vite applications to Appframe",
   "main": "./lib/index.js",
   "type": "module",
   "types": "./lib/index.d.ts",
+  "bin": {
+    "appframe-vite": "./lib/cli.js"
+  },
   "exports": {
     ".": "./lib/index.js",
     "./proxy": {
@@ -28,12 +31,12 @@
     "dotenv": "^17.2.3",
     "jsdom": "29.0.2",
     "rollup-plugin-visualizer": "^6.0.5",
-    "@olenbetong/appframe-data": "1.4.1"
+    "@olenbetong/appframe-data": "1.4.2"
   },
   "devDependencies": {
     "@types/jsdom": "^27.0.0",
     "@types/node": "25.6.0",
-    "typescript": "6.0.2",
+    "typescript": "6.0.3",
     "vite": "8.0.8"
   },
   "peerDependencies": {