@codenotch/codenotch.cli 1.0.35 → 1.0.37

package/dist/utils/BuildUtils.d.ts

@@ -1,34 +1,61 @@
-import { ApplicationManifest, IScenarioProjectManifest, IWorkspaceCache, ProjectManifest } from "../models/Codenotch";
+import { ICodenotchProjectManifest, IAppManifest } from "@codenotch/codenotch.core";
 interface IWorkspace {
-    manifest: ProjectManifest;
+    manifest: ICodenotchProjectManifest;
     path: string;
 }
 export interface IBuildOptions {
     cluster?: string;
 }
 export default abstract class BuildUtils {
-    static readonly CN_REACT_VERSION = "2.0.0";
+    static readonly CN_REACT_VERSION = "2.0.1";
     static findWorkspaceFromFile(childPath: string): string | undefined;
     /**
-     * cn react build <target_file>
+     * Builds one React app of a Codenotch project into a ready-to-serve bundle.
+     * Behind the command: cn react build <target_file>
+     *
+     * Everything is staged under the `.codenotch/` folder of the workspace, the sources of the
+     * project are never touched:
+     * - `.codenotch/<appName>-source` — the Vite project: generated package.json, index.html,
+     *   index.jsx (mounts the app component with react 19's createRoot), vite.config.mjs,
+     *   tsconfig.json, the workspace `.npmrc` when there is one, and a copy of every source file of the workspace,
+     *   mirrored flat so that root config files (postcss.config.js, ...) stay where Vite looks.
+     * - `.codenotch/<appName>-dist` — the bundle Vite emits, plus a `.env` holding the Codenotch
+     *   environment (app name, manifests, cluster url) read by the served page.
+     * Both folders are deleted first when a previous build left them behind.
+     *
+     * The build itself runs `npm install` then `npm run build` (vite alone: the copy holds server
+     * files too, typechecking is the job of 'cn validate') inside `-source`, with the Node the CLI
+     * runs under — Node 20 or newer is expected (Vite 8), and npm needs the network.
+     *
+     * On success, prints the `cn react serve '<dist>'` command to try the bundle.
+     *
+     * @param appFilePath Path (absolute, or relative to the current directory) to the app
+     *                    component, e.g. `./apps/index.tsx`. NOT the manifest: the sibling
+     *                    `<name>.manifest.json` is derived from it, and must exist and declare
+     *                    `app.name`, which names the staging folders. The file must live inside
+     *                    a Codenotch workspace (a `manifest.json` in one of its parent folders).
+     * @param clusterUrl  Base URL of the Codenotch cluster the bundle will talk to, written into
+     *                    the `.env` of the dist. Without it the bundle is built all the same,
+     *                    but not bound to a cluster.
+     *
+     * Validation failures (missing file, no workspace, no app name...) print the reason and leave
+     * with `process.exit(1)`: this method is the command, not a library call. See `buildApp2` for
+     * the throwing, CI oriented variant.
      */
-    static buildApp(appFilePath: string, clusterUrl?: string): Promise<void>;
+    static buildReactApp(appFilePath: string, clusterUrl?: string): Promise<void>;
     static buildApp2(appFilePath: string): Promise<string>;
     private static createIndexJsx;
     /**
      * When served from the runtime env variables are not available, the variables are injected into the html file instead
      */
     private static createIndexJsxDeployment;
-    private static fetchTenantName;
     static getCodenotchEnvVariables(workpace: IWorkspace, options: {
         baseUrl?: string;
         accessToken?: string;
         appName?: string;
-        app?: ApplicationManifest;
-        tenantName?: string;
+        app?: IAppManifest;
         clusterUrl?: string;
     }): Promise<any>;
-    static getTenantName(cluster: string): Promise<string | undefined>;
     /** Compiler options shared by the generated build tsconfig and `cn validate` on script files. */
     static defaultCompilerOptions(): {
         target: string;
@@ -47,27 +74,38 @@ export default abstract class BuildUtils {
         jsx: string;
     };
     private static createTsConfig;
-    private static createEmptyModule;
     private static createViteConfig;
     private static createIndexHtml;
     private static createPkgJson;
-    static getFullManifest(manifest: IScenarioProjectManifest, manifestCache: IWorkspaceCache): ProjectManifest;
-    static getFullManifestAt(folderPath: string): ProjectManifest;
-    static getManifestAt(folderPath: string): IScenarioProjectManifest;
-    static getManifestCacheAt(folderPath: string): IWorkspaceCache;
-    static getAumlVariables(workpace: IWorkspace, tenantName: string | undefined, clusterUrl: string | undefined): {
-        serviceName: string;
-        tenant: {
-            displayName: string | undefined;
-            name: string | undefined;
-            clusterUrl: string | undefined;
-        };
-        languages: string[];
-        appManifest: ProjectManifest;
-        packageVersions: {
-            [packageSource: string]: string;
-        };
-    };
-    static getGlobalAumlVariableDefinitions(workpace: IWorkspace, tenantName: string | undefined, clusterUrl: string | undefined): Promise<string>;
+    /**
+     * Starts the Vite dev server of one app, with hot reload on the real sources of the project.
+     * Behind the command: cn react dev <app>
+     *
+     * Unlike {@link BuildUtils.buildReactApp}, nothing of the project is copied: the staging
+     * folder `.codenotch/<appName>-dev` only holds the generated files (package.json, index.html,
+     * index.jsx, vite.config.mjs), and the config aliases the app component to its real path in
+     * the workspace. Editing a project file is therefore picked up live by Vite.
+     *
+     * The `/api/env` endpoint the app reads at startup is served by the dev server itself,
+     * through a small plugin of the generated config: the page behaves like the served bundle.
+     *
+     * Dependencies are installed in the staging on the first run only; delete the folder
+     * (or run 'cn react clean <app>') to force a fresh install.
+     *
+     * Blocks until the server is stopped (Ctrl+C), and returns the exit code it left.
+     */
+    static devReactApp(appFilePath: string, options: {
+        port: number;
+        clusterUrl?: string;
+    }): Promise<number>;
+    /** The dev entry: same contract as the built one, the app itself comes through the '@app' alias */
+    private static createIndexJsxDev;
+    /**
+     * The dev flavoured Vite config: the app is aliased to its real file in the workspace so that
+     * hot reload watches the project sources, and a tiny plugin serves the Codenotch environment.
+     */
+    private static createViteDevConfig;
+    static getFullManifestAt(folderPath: string): ICodenotchProjectManifest;
+    static getManifestAt(folderPath: string): ICodenotchProjectManifest;
 }
 export {};