@chidchanun/bcp 0.2.3 → 0.2.5

package/packages/cli/src/application-packaging.ts

@@ -0,0 +1,1162 @@
+import {
+    createHash,
+} from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+export const APPLICATION_PACKAGE_SCHEMA_VERSION =
+    1;
+export const APPLICATION_PACKAGE_TARGET =
+    "standalone-node";
+export const APPLICATION_PACKAGE_NODE_RANGE =
+    ">=24.11.0";
+
+interface JsonObject {
+    [key: string]: unknown;
+}
+
+interface ApplicationPackageJson
+    extends JsonObject {
+    name?: string;
+    version?: string;
+    type?: string;
+    private?: boolean;
+    scripts?: Record<string, string>;
+    engines?: Record<string, string>;
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    peerDependenciesMeta?: JsonObject;
+    overrides?: JsonObject;
+    packageManager?: string;
+}
+
+interface PackageLockPackage
+    extends JsonObject {
+    name?: string;
+    version?: string;
+    link?: boolean;
+    dev?: boolean;
+    dependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+}
+
+interface PackageLockJson
+    extends JsonObject {
+    name?: string;
+    version?: string;
+    lockfileVersion?: number;
+    packages?: Record<
+        string,
+        PackageLockPackage
+    >;
+}
+
+export interface ApplicationPackageFile {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+
+export interface ApplicationPackageManifest {
+    schemaVersion: 1;
+    target: "standalone-node";
+    frameworkVersion: string;
+    application: {
+        name: string;
+        version: string;
+    };
+    runtime: {
+        node: string;
+        entrypoint: string;
+        startCommand: string;
+    };
+    install: {
+        command: string;
+        lockfile: boolean;
+        devDependenciesIncluded: false;
+    };
+    directories: {
+        client: string;
+        server: string;
+        public: string | null;
+    };
+    buildManifest: string;
+    environmentManifest: string;
+    deploymentManifest: string;
+    files: ApplicationPackageFile[];
+}
+
+export interface ApplicationPackagingResult {
+    outputDirectory: string;
+    packageManifest: ApplicationPackageManifest;
+    lockfileIncluded: boolean;
+    warnings: string[];
+}
+
+export interface PackageApplicationOptions {
+    rootDirectory: string;
+    frameworkVersion: string;
+}
+
+export function packageApplication(
+    options: PackageApplicationOptions
+): ApplicationPackagingResult {
+    const rootDirectory =
+        path.resolve(
+            options.rootDirectory
+        );
+    const buildDirectory =
+        path.join(
+            rootDirectory,
+            ".bcp-framework",
+            "build"
+        );
+    const serverFile =
+        path.join(
+            buildDirectory,
+            "server",
+            "server.mjs"
+        );
+    const buildManifestFile =
+        path.join(
+            buildDirectory,
+            "manifest.json"
+        );
+
+    if (
+        !fs.existsSync(serverFile) ||
+        !fs.existsSync(
+            buildManifestFile
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: production build was not found. Run `bcp build` before packaging."
+        );
+    }
+
+    const sourcePackageFile =
+        path.join(
+            rootDirectory,
+            "package.json"
+        );
+
+    if (
+        !fs.existsSync(
+            sourcePackageFile
+        )
+    ) {
+        throw new Error(
+            "BCP Framework: package.json was not found in the project root."
+        );
+    }
+
+    const sourcePackage =
+        readJson<ApplicationPackageJson>(
+            sourcePackageFile
+        );
+    const productionPackage =
+        createProductionPackageJson(
+            sourcePackage
+        );
+    const outputDirectory =
+        path.join(
+            rootDirectory,
+            ".bcp-framework",
+            "package"
+        );
+
+    fs.rmSync(
+        outputDirectory,
+        {
+            recursive: true,
+            force: true,
+        }
+    );
+    fs.mkdirSync(
+        outputDirectory,
+        {
+            recursive: true,
+        }
+    );
+
+    copyBuildDirectory(
+        buildDirectory,
+        outputDirectory,
+        "client",
+        true
+    );
+    copyBuildDirectory(
+        buildDirectory,
+        outputDirectory,
+        "server",
+        true
+    );
+    copyBuildDirectory(
+        buildDirectory,
+        outputDirectory,
+        "public",
+        false
+    );
+
+    fs.copyFileSync(
+        buildManifestFile,
+        path.join(
+            outputDirectory,
+            "manifest.json"
+        )
+    );
+
+    writeJson(
+        path.join(
+            outputDirectory,
+            "package.json"
+        ),
+        productionPackage
+    );
+
+    const warnings:
+        string[] = [];
+    const lockfileIncluded =
+        writeProductionLockfile(
+            rootDirectory,
+            outputDirectory,
+            productionPackage,
+            warnings
+        );
+    const installCommand =
+        lockfileIncluded
+            ? "npm ci --omit=dev"
+            : "npm install --omit=dev";
+
+    const environmentManifest =
+        createEnvironmentManifest(
+            rootDirectory
+        );
+    writeJson(
+        path.join(
+            outputDirectory,
+            "bcp.env.json"
+        ),
+        environmentManifest
+    );
+
+    const deploymentManifest = {
+        schemaVersion:
+            APPLICATION_PACKAGE_SCHEMA_VERSION,
+        target:
+            APPLICATION_PACKAGE_TARGET,
+        runtime: {
+            name:
+                "node",
+            version:
+                APPLICATION_PACKAGE_NODE_RANGE,
+        },
+        install: {
+            command:
+                installCommand,
+        },
+        start: {
+            command:
+                "npm start",
+            entrypoint:
+                "server/server.mjs",
+        },
+        docker: {
+            file:
+                "Dockerfile",
+        },
+    };
+
+    writeJson(
+        path.join(
+            outputDirectory,
+            "bcp.deployment.json"
+        ),
+        deploymentManifest
+    );
+    fs.writeFileSync(
+        path.join(
+            outputDirectory,
+            "Dockerfile"
+        ),
+        createDockerfile(),
+        "utf8"
+    );
+    fs.writeFileSync(
+        path.join(
+            outputDirectory,
+            ".dockerignore"
+        ),
+        createDockerIgnore(),
+        "utf8"
+    );
+    fs.writeFileSync(
+        path.join(
+            outputDirectory,
+            "README.md"
+        ),
+        createPackageReadme(
+            installCommand
+        ),
+        "utf8"
+    );
+
+    const files =
+        collectPackageFiles(
+            outputDirectory,
+            new Set([
+                "bcp.package.json",
+            ])
+        );
+    const packageManifest:
+        ApplicationPackageManifest = {
+        schemaVersion:
+            APPLICATION_PACKAGE_SCHEMA_VERSION,
+        target:
+            APPLICATION_PACKAGE_TARGET,
+        frameworkVersion:
+            options.frameworkVersion,
+        application: {
+            name:
+                normalizeApplicationName(
+                    productionPackage.name
+                ),
+            version:
+                normalizeApplicationVersion(
+                    productionPackage.version
+                ),
+        },
+        runtime: {
+            node:
+                APPLICATION_PACKAGE_NODE_RANGE,
+            entrypoint:
+                "server/server.mjs",
+            startCommand:
+                "npm start",
+        },
+        install: {
+            command:
+                installCommand,
+            lockfile:
+                lockfileIncluded,
+            devDependenciesIncluded:
+                false,
+        },
+        directories: {
+            client:
+                "client",
+            server:
+                "server",
+            public:
+                fs.existsSync(
+                    path.join(
+                        outputDirectory,
+                        "public"
+                    )
+                )
+                    ? "public"
+                    : null,
+        },
+        buildManifest:
+            "manifest.json",
+        environmentManifest:
+            "bcp.env.json",
+        deploymentManifest:
+            "bcp.deployment.json",
+        files,
+    };
+
+    writeJson(
+        path.join(
+            outputDirectory,
+            "bcp.package.json"
+        ),
+        packageManifest
+    );
+
+    return {
+        outputDirectory,
+        packageManifest,
+        lockfileIncluded,
+        warnings,
+    };
+}
+
+export function createProductionPackageJson(
+    source: ApplicationPackageJson
+): ApplicationPackageJson {
+    const result:
+        ApplicationPackageJson = {
+        name:
+            normalizeApplicationName(
+                source.name
+            ),
+        version:
+            normalizeApplicationVersion(
+                source.version
+            ),
+        private: true,
+        type:
+            source.type === "commonjs"
+                ? "commonjs"
+                : "module",
+        scripts: {
+            start:
+                "node server/server.mjs",
+        },
+        engines: {
+            node:
+                APPLICATION_PACKAGE_NODE_RANGE,
+        },
+    };
+
+    copySortedStringMap(
+        source,
+        result,
+        "dependencies"
+    );
+    copySortedStringMap(
+        source,
+        result,
+        "optionalDependencies"
+    );
+    copySortedStringMap(
+        source,
+        result,
+        "peerDependencies"
+    );
+
+    if (
+        source.peerDependenciesMeta &&
+        isPlainObject(
+            source.peerDependenciesMeta
+        )
+    ) {
+        result.peerDependenciesMeta =
+            sortObject(
+                source.peerDependenciesMeta
+            );
+    }
+
+    if (
+        source.overrides &&
+        isPlainObject(
+            source.overrides
+        )
+    ) {
+        result.overrides =
+            sortObject(
+                source.overrides
+            );
+    }
+
+    if (
+        typeof source.packageManager ===
+            "string" &&
+        source.packageManager.trim() !==
+            ""
+    ) {
+        result.packageManager =
+            source.packageManager;
+    }
+
+    return result;
+}
+
+export function createProductionLockfile(
+    sourceLock:
+        PackageLockJson,
+    productionPackage:
+        ApplicationPackageJson
+): PackageLockJson | null {
+    if (
+        sourceLock.lockfileVersion !== 3 ||
+        !sourceLock.packages ||
+        !sourceLock.packages[""]
+    ) {
+        return null;
+    }
+
+    const sourcePackages =
+        sourceLock.packages;
+    const selected =
+        new Set<string>([
+            "",
+        ]);
+    const queue:
+        string[] = [
+            "",
+        ];
+
+    while (
+        queue.length > 0
+    ) {
+        const packagePath =
+            queue.shift() as string;
+        const packageEntry =
+            packagePath === ""
+                ? createRootLockPackage(
+                    sourcePackages[""],
+                    productionPackage
+                )
+                : sourcePackages[
+                    packagePath
+                ];
+
+        if (!packageEntry) {
+            continue;
+        }
+
+        if (
+            packagePath !== "" &&
+            packageEntry.link === true
+        ) {
+            return null;
+        }
+
+        const dependencyNames =
+            collectDependencyNames(
+                packageEntry
+            );
+
+        for (
+            const dependencyName
+            of dependencyNames
+        ) {
+            const resolvedPath =
+                resolveLockPackagePath(
+                    sourcePackages,
+                    packagePath,
+                    dependencyName
+                );
+
+            if (
+                !resolvedPath ||
+                selected.has(
+                    resolvedPath
+                )
+            ) {
+                continue;
+            }
+
+            const resolvedEntry =
+                sourcePackages[
+                    resolvedPath
+                ];
+
+            if (
+                !resolvedEntry ||
+                resolvedEntry.dev === true
+            ) {
+                continue;
+            }
+
+            selected.add(
+                resolvedPath
+            );
+            queue.push(
+                resolvedPath
+            );
+        }
+    }
+
+    const packages:
+        Record<
+            string,
+            PackageLockPackage
+        > = {};
+
+    for (
+        const packagePath
+        of Array.from(
+            selected
+        ).sort()
+    ) {
+        if (
+            packagePath === ""
+        ) {
+            packages[""] =
+                createRootLockPackage(
+                    sourcePackages[""],
+                    productionPackage
+                );
+            continue;
+        }
+
+        const entry =
+            sourcePackages[
+                packagePath
+            ];
+
+        if (entry) {
+            packages[
+                packagePath
+            ] =
+                entry;
+        }
+    }
+
+    return {
+        name:
+            normalizeApplicationName(
+                productionPackage.name
+            ),
+        version:
+            normalizeApplicationVersion(
+                productionPackage.version
+            ),
+        lockfileVersion: 3,
+        requires:
+            sourceLock.requires ??
+            true,
+        packages,
+    };
+}
+
+export function parseEnvironmentExampleKeys(
+    content: string
+): string[] {
+    const keys =
+        new Set<string>();
+
+    for (
+        const line
+        of content.split(/\r?\n/)
+    ) {
+        const trimmed =
+            line.trim();
+
+        if (
+            trimmed === "" ||
+            trimmed.startsWith("#")
+        ) {
+            continue;
+        }
+
+        const match =
+            /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(
+                trimmed
+            );
+
+        if (match) {
+            keys.add(
+                match[1]
+            );
+        }
+    }
+
+    return Array.from(
+        keys
+    ).sort();
+}
+
+function writeProductionLockfile(
+    rootDirectory: string,
+    outputDirectory: string,
+    productionPackage: ApplicationPackageJson,
+    warnings: string[]
+): boolean {
+    const sourceFile =
+        path.join(
+            rootDirectory,
+            "package-lock.json"
+        );
+
+    if (!fs.existsSync(sourceFile)) {
+        warnings.push(
+            "package-lock.json was not found; deployment will use npm install --omit=dev."
+        );
+        return false;
+    }
+
+    const sourceLock =
+        readJson<PackageLockJson>(
+            sourceFile
+        );
+    const productionLock =
+        createProductionLockfile(
+            sourceLock,
+            productionPackage
+        );
+
+    if (!productionLock) {
+        warnings.push(
+            "package-lock.json could not be safely pruned (npm lockfile v3 without workspace links is required); deployment will use npm install --omit=dev."
+        );
+        return false;
+    }
+
+    writeJson(
+        path.join(
+            outputDirectory,
+            "package-lock.json"
+        ),
+        productionLock
+    );
+
+    return true;
+}
+
+function createEnvironmentManifest(
+    rootDirectory: string
+): JsonObject {
+    const exampleFiles = [
+        ".env.example",
+        ".env.production.example",
+        ".env.production.local.example",
+    ];
+    const declared =
+        new Set<string>();
+    const discoveredFiles:
+        string[] = [];
+
+    for (
+        const fileName
+        of exampleFiles
+    ) {
+        const filePath =
+            path.join(
+                rootDirectory,
+                fileName
+            );
+
+        if (!fs.existsSync(filePath)) {
+            continue;
+        }
+
+        discoveredFiles.push(
+            fileName
+        );
+
+        const keys =
+            parseEnvironmentExampleKeys(
+                fs.readFileSync(
+                    filePath,
+                    "utf8"
+                )
+            );
+
+        for (const key of keys) {
+            declared.add(key);
+        }
+    }
+
+    return {
+        schemaVersion:
+            APPLICATION_PACKAGE_SCHEMA_VERSION,
+        valuesIncluded:
+            false,
+        environmentFilesIncluded:
+            false,
+        sourceExamples:
+            discoveredFiles.sort(),
+        declaredKeys:
+            Array.from(
+                declared
+            ).sort(),
+        runtimeOverrides: [
+            "BCP_HOSTNAME",
+            "BCP_PORT",
+        ],
+        note:
+            "Provide environment values at deployment/runtime. BCP application packages never copy .env files or secret values.",
+    };
+}
+
+function collectPackageFiles(
+    directory: string,
+    excluded: Set<string>
+): ApplicationPackageFile[] {
+    const files:
+        ApplicationPackageFile[] = [];
+
+    walkDirectory(
+        directory,
+        directory,
+        excluded,
+        files
+    );
+
+    return files.sort(
+        (left, right) =>
+            left.path.localeCompare(
+                right.path
+            )
+    );
+}
+
+function walkDirectory(
+    rootDirectory: string,
+    currentDirectory: string,
+    excluded: Set<string>,
+    files: ApplicationPackageFile[]
+): void {
+    const entries =
+        fs.readdirSync(
+            currentDirectory,
+            {
+                withFileTypes: true,
+            }
+        ).sort(
+            (left, right) =>
+                left.name.localeCompare(
+                    right.name
+                )
+        );
+
+    for (const entry of entries) {
+        const absolutePath =
+            path.join(
+                currentDirectory,
+                entry.name
+            );
+        const relativePath =
+            normalizePath(
+                path.relative(
+                    rootDirectory,
+                    absolutePath
+                )
+            );
+
+        if (
+            excluded.has(
+                relativePath
+            )
+        ) {
+            continue;
+        }
+
+        if (entry.isDirectory()) {
+            walkDirectory(
+                rootDirectory,
+                absolutePath,
+                excluded,
+                files
+            );
+            continue;
+        }
+
+        if (!entry.isFile()) {
+            continue;
+        }
+
+        const content =
+            fs.readFileSync(
+                absolutePath
+            );
+
+        files.push({
+            path:
+                relativePath,
+            bytes:
+                content.length,
+            sha256:
+                createHash("sha256")
+                    .update(content)
+                    .digest("hex"),
+        });
+    }
+}
+
+function createRootLockPackage(
+    source: PackageLockPackage,
+    productionPackage: ApplicationPackageJson
+): PackageLockPackage {
+    const root:
+        PackageLockPackage = {
+        ...source,
+        name:
+            normalizeApplicationName(
+                productionPackage.name
+            ),
+        version:
+            normalizeApplicationVersion(
+                productionPackage.version
+            ),
+    };
+
+    delete root.devDependencies;
+    delete root.workspaces;
+
+    syncLockDependencyMap(
+        root,
+        productionPackage,
+        "dependencies"
+    );
+    syncLockDependencyMap(
+        root,
+        productionPackage,
+        "optionalDependencies"
+    );
+    syncLockDependencyMap(
+        root,
+        productionPackage,
+        "peerDependencies"
+    );
+
+    return root;
+}
+
+function syncLockDependencyMap(
+    target: PackageLockPackage,
+    source: ApplicationPackageJson,
+    key:
+        "dependencies" |
+        "optionalDependencies" |
+        "peerDependencies"
+): void {
+    const value =
+        source[key];
+
+    if (
+        value &&
+        Object.keys(value).length > 0
+    ) {
+        target[key] =
+            value;
+    } else {
+        delete target[key];
+    }
+}
+
+function collectDependencyNames(
+    entry: PackageLockPackage
+): string[] {
+    return Array.from(
+        new Set([
+            ...Object.keys(
+                entry.dependencies ?? {}
+            ),
+            ...Object.keys(
+                entry.optionalDependencies ?? {}
+            ),
+            ...Object.keys(
+                entry.peerDependencies ?? {}
+            ),
+        ])
+    ).sort();
+}
+
+function resolveLockPackagePath(
+    packages:
+        Record<
+            string,
+            PackageLockPackage
+        >,
+    requesterPath: string,
+    dependencyName: string
+): string | null {
+    const requesterSegments =
+        requesterPath === ""
+            ? []
+            : normalizePath(
+                requesterPath
+            ).split("/");
+    const candidates:
+        string[] = [];
+
+    for (
+        let length =
+            requesterSegments.length;
+        length >= 0;
+        length--
+    ) {
+        const prefix =
+            requesterSegments
+                .slice(
+                    0,
+                    length
+                )
+                .join("/");
+        const candidate =
+            prefix === ""
+                ? `node_modules/${dependencyName}`
+                : `${prefix}/node_modules/${dependencyName}`;
+
+        candidates.push(
+            candidate
+        );
+    }
+
+    for (const candidate of candidates) {
+        if (
+            packages[
+                candidate
+            ]
+        ) {
+            return candidate;
+        }
+    }
+
+    return null;
+}
+
+function copyBuildDirectory(
+    buildDirectory: string,
+    outputDirectory: string,
+    name: string,
+    required: boolean
+): void {
+    const source =
+        path.join(
+            buildDirectory,
+            name
+        );
+
+    if (!fs.existsSync(source)) {
+        if (required) {
+            throw new Error(
+                `BCP Framework: production build directory "${name}" was not found.`
+            );
+        }
+        return;
+    }
+
+    fs.cpSync(
+        source,
+        path.join(
+            outputDirectory,
+            name
+        ),
+        {
+            recursive: true,
+        }
+    );
+}
+
+function copySortedStringMap(
+    source: ApplicationPackageJson,
+    target: ApplicationPackageJson,
+    key:
+        "dependencies" |
+        "optionalDependencies" |
+        "peerDependencies"
+): void {
+    const value =
+        source[key];
+
+    if (
+        value &&
+        Object.keys(value).length > 0
+    ) {
+        target[key] =
+            sortStringMap(
+                value
+            );
+    }
+}
+
+function sortStringMap(
+    value: Record<string, string>
+): Record<string, string> {
+    return Object.fromEntries(
+        Object.entries(value)
+            .sort(
+                ([left], [right]) =>
+                    left.localeCompare(
+                        right
+                    )
+            )
+    );
+}
+
+function sortObject(
+    value: JsonObject
+): JsonObject {
+    return Object.fromEntries(
+        Object.entries(value)
+            .sort(
+                ([left], [right]) =>
+                    left.localeCompare(
+                        right
+                    )
+            )
+    );
+}
+
+function createDockerfile(): string {
+    return `FROM node:24-alpine\n\nWORKDIR /app\nENV NODE_ENV=production\n\nCOPY package*.json ./\nRUN if [ -f package-lock.json ]; then npm ci --omit=dev; else npm install --omit=dev; fi\n\nCOPY . .\n\nEXPOSE 3000\nCMD ["node", "server/server.mjs"]\n`;
+}
+
+function createDockerIgnore(): string {
+    return `node_modules\nnpm-debug.log*\n.env\n.env.*\n!.env.example\n.git\n.gitignore\n`;
+}
+
+function createPackageReadme(
+    installCommand: string
+): string {
+    return `# BCP Application Package\n\nTarget: \`${APPLICATION_PACKAGE_TARGET}\`\n\nInstall production dependencies:\n\n\`\`\`bash\n${installCommand}\n\`\`\`\n\nStart the application:\n\n\`\`\`bash\nnpm start\n\`\`\`\n\nRuntime configuration and secrets must be supplied by the deployment environment. This package intentionally excludes project \`.env\` files and devDependencies.\n\nFor containers:\n\n\`\`\`bash\ndocker build -t bcp-app .\ndocker run --rm -p 3000:3000 bcp-app\n\`\`\`\n`;
+}
+
+function normalizeApplicationName(
+    value: unknown
+): string {
+    if (
+        typeof value === "string" &&
+        value.trim() !== ""
+    ) {
+        return value.trim();
+    }
+
+    return "bcp-application";
+}
+
+function normalizeApplicationVersion(
+    value: unknown
+): string {
+    if (
+        typeof value === "string" &&
+        value.trim() !== ""
+    ) {
+        return value.trim();
+    }
+
+    return "0.0.0";
+}
+
+function normalizePath(
+    value: string
+): string {
+    return value.replace(
+        /\\/g,
+        "/"
+    );
+}
+
+function readJson<T>(
+    filePath: string
+): T {
+    return JSON.parse(
+        fs.readFileSync(
+            filePath,
+            "utf8"
+        )
+    ) as T;
+}
+
+function writeJson(
+    filePath: string,
+    value: unknown
+): void {
+    fs.writeFileSync(
+        filePath,
+        `${JSON.stringify(
+            value,
+            null,
+            2
+        )}\n`,
+        "utf8"
+    );
+}
+
+function isPlainObject(
+    value: unknown
+): value is JsonObject {
+    return Boolean(
+        value &&
+        typeof value === "object" &&
+        !Array.isArray(value)
+    );
+}