@blotch/angular-lynx-build 0.0.0-stage → 22.2.3

package/builders/application/schema.json

@@ -0,0 +1,229 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularLynxApplicationBuilder",
+  "title": "AngularLynx application builder",
+  "description": "Builds the Lynx bundle with rspeedy and, with --platform, the iOS and Android binaries.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "platform": {
+      "type": "string",
+      "enum": ["ios", "android", "all"],
+      "description": "Also build native binaries into dist/<platform>/. Without it, only the bundle is built, as `rspeedy build` does."
+    },
+    "watch": {
+      "type": "boolean",
+      "default": false,
+      "description": "Rebuild the bundle when files change, as Angular's `ng build --watch` does. Can't be combined with `platform`."
+    },
+    "config": {
+      "type": "string",
+      "description": "The rspeedy config file, relative to the project root. Defaults to lynx.config.ts (or .js, .mts, .mjs) when the project has one. Without one, the app builds from angular.json: `browser` is the entry, and both the lynx and web environments are built."
+    },
+    "environment": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Only build these rspeedy environments (e.g. lynx). With --platform, only the lynx environment is built."
+    },
+    "browser": {
+      "type": "string",
+      "description": "Angular: the app's entry point. Read by @blotch/rsbuild-plugin-angular-lynx and `ng test`, and rspeedy's `source.entry` unless lynx.config.ts sets one."
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "Angular: the tsconfig the app compiles with."
+    },
+    "polyfills": {
+      "type": ["array", "string"],
+      "items": {
+        "type": "string"
+      },
+      "description": "Angular: modules loaded before the app (e.g. @angular/localize/init)."
+    },
+    "styles": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Angular: global stylesheets."
+    },
+    "assets": {
+      "type": "array",
+      "description": "Angular: used by `ng test` only. Lynx bundles reference assets through imports."
+    },
+    "scripts": {
+      "type": "array",
+      "description": "Angular: used by `ng test` only."
+    },
+    "inlineStyleLanguage": {
+      "type": "string",
+      "description": "Angular: the language of inline component styles."
+    },
+    "fileReplacements": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "replace": {
+            "type": "string"
+          },
+          "with": {
+            "type": "string"
+          }
+        },
+        "required": ["replace", "with"]
+      },
+      "description": "Angular: files swapped at build time, e.g. environment files."
+    },
+    "aot": {
+      "type": "boolean",
+      "description": "Angular: ahead-of-time compilation. Defaults to true."
+    },
+    "optimization": {
+      "type": ["boolean", "object"],
+      "description": "Angular: script and style optimization. Also sets rspeedy's mode: production when scripts are optimized (the default), development otherwise."
+    },
+    "sourceMap": {
+      "type": ["boolean", "object"],
+      "description": "Angular: source maps."
+    },
+    "outputHashing": {
+      "type": "string",
+      "enum": ["none", "all", "media", "bundles"],
+      "description": "Angular: hashes in emitted file names."
+    },
+    "i18nMissingTranslation": {
+      "type": "string",
+      "enum": ["warning", "error", "ignore"],
+      "description": "Angular: how to report missing translations."
+    },
+    "budgets": {
+      "type": "array",
+      "description": "Angular: size budgets, checked against the Lynx bundles (each entry's bundle is its own `initial` budget) and component stylesheets."
+    },
+    "extractLicenses": {
+      "type": "boolean",
+      "description": "Angular: accepted for compatibility with `ng new`."
+    },
+    "outputPath": {
+      "type": ["string", "object"],
+      "description": "Angular: the output folder. Defaults to rspeedy's dist/."
+    },
+    "index": {
+      "type": ["boolean", "string", "object"],
+      "description": "Angular: accepted for compatibility; Lynx apps have no index.html."
+    },
+    "appName": {
+      "type": "string",
+      "description": "The app's name under its icon. Defaults to the project name."
+    },
+    "appId": {
+      "type": "string",
+      "description": "The iOS bundle ID and Android applicationId, e.g. com.example.myapp."
+    },
+    "version": {
+      "type": "string",
+      "description": "The user-facing version, e.g. 1.2.0. Defaults to package.json's version."
+    },
+    "buildNumber": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "The store build number (CFBundleVersion / versionCode). Must increase with every store upload."
+    },
+    "orientation": {
+      "type": "string",
+      "enum": ["portrait", "landscape", "all"],
+      "default": "portrait",
+      "description": "The screen orientations the app supports."
+    },
+    "icon": {
+      "type": "string",
+      "description": "The app icon: a 1024×1024 PNG without transparency, relative to the project root."
+    },
+    "permissions": {
+      "type": "object",
+      "description": "Each permission the app uses, with the reason shown to the user.",
+      "additionalProperties": false,
+      "properties": {
+        "camera": {
+          "type": "string"
+        },
+        "microphone": {
+          "type": "string"
+        },
+        "location": {
+          "type": "string"
+        },
+        "photos": {
+          "type": "string"
+        },
+        "contacts": {
+          "type": "string"
+        },
+        "notifications": {
+          "type": "string"
+        }
+      }
+    },
+    "deepLinkSchemes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Custom URL schemes that open the app, e.g. [\"myapp\"]."
+    },
+    "ios": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "teamId": {
+          "type": "string",
+          "description": "The Apple Developer team ID that signs the app."
+        },
+        "signing": {
+          "type": "object",
+          "description": "An App Store Connect API key for headless signing. Each field names the environment variable holding the value.",
+          "additionalProperties": false,
+          "properties": {
+            "keyIdEnv": {
+              "type": "string"
+            },
+            "issuerIdEnv": {
+              "type": "string"
+            },
+            "keyPathEnv": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "android": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "signing": {
+          "type": "object",
+          "description": "The Google Play upload key. The *Env fields name the environment variables holding the values.",
+          "additionalProperties": false,
+          "properties": {
+            "storeFileEnv": {
+              "type": "string"
+            },
+            "storePasswordEnv": {
+              "type": "string"
+            },
+            "keyAlias": {
+              "type": "string"
+            },
+            "keyPasswordEnv": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/builders/builders.json

@@ -0,0 +1,24 @@
+{
+  "builders": {
+    "application": {
+      "implementation": "./application/index",
+      "schema": "./application/schema.json",
+      "description": "Builds the Lynx bundle with rspeedy (--watch to rebuild on changes) and, with --platform, the iOS and Android binaries"
+    },
+    "dev-server": {
+      "implementation": "./dev-server/index",
+      "schema": "./dev-server/schema.json",
+      "description": "Runs the rspeedy dev server for Lynx Explorer and the web preview"
+    },
+    "unit-test": {
+      "implementation": "./unit-test/index",
+      "schema": "./unit-test/schema.json",
+      "description": "Runs the unit tests with Angular's unit-test builder, set up for AngularLynx"
+    },
+    "extract-i18n": {
+      "implementation": "./extract-i18n/index",
+      "schema": "./extract-i18n/schema.json",
+      "description": "Extracts the i18n messages with Angular's extract-i18n builder, set up for AngularLynx"
+    }
+  }
+}

package/builders/dev-server/index.js

@@ -0,0 +1,82 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDevServer = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const node_path_1 = __importDefault(require("node:path"));
+const rspeedy_1 = require("../rspeedy");
+/**
+ * Starts rspeedy's dev server in this process, as `rspeedy dev` would, and
+ * closes it when Angular CLI tears the builder down (Ctrl+C). rspeedy's own
+ * plugins keep working unchanged, and live reload is rspeedy's. The QR code
+ * plugin, which prints the link Lynx Explorer opens, is added unless
+ * lynx.config.ts lists it.
+ *
+ * Like Angular's own dev server, it builds what `buildTarget` describes: its
+ * options configure the compile, so `ng serve -c production` serves the
+ * production configuration.
+ */
+const startDevServer = async (options, context, deps) => {
+    const projectName = context.target?.project;
+    if (!projectName) {
+        return { success: false, error: 'The builder needs a project target.' };
+    }
+    const metadata = await context.getProjectMetadata(projectName);
+    const projectRoot = node_path_1.default.join(context.workspaceRoot, metadata['root'] ?? '');
+    try {
+        // The same default as Angular's dev server: the project's build target
+        // with its development configuration.
+        const buildTarget = (0, architect_1.targetFromTargetString)(options.buildTarget ?? '::development', projectName, 'build');
+        // Validated against the build builder's schema, which also fills in its
+        // defaults, as the build itself would see them.
+        const buildOptions = (await context.validateOptions(await context.getTargetOptions(buildTarget), await context.getBuilderNameForTarget(buildTarget)));
+        const rspeedy = await (0, rspeedy_1.createRspeedy)({
+            rspeedy: await deps.importRspeedy(),
+            plugin: await deps.importPlugin(),
+            qrCode: await deps.importQRCodePlugin(),
+            projectRoot,
+            angularCli: {
+                workspaceRoot: context.workspaceRoot,
+                project: buildTarget.project,
+                buildOptions,
+            },
+            config: buildOptions.config,
+            environment: options.environment ?? buildOptions.environment,
+            server: { port: options.port, host: options.host },
+        });
+        const { server, urls } = await rspeedy.startDevServer();
+        context.addTeardown(() => server.close());
+        return { success: true, baseUrl: urls[0] };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+/**
+ * `ng serve`. Angular CLI keeps a target running for as long as its outputs
+ * haven't ended, so this reports the server's start and then never ends,
+ * unless the server failed to start.
+ */
+const runDevServer = (options, context, deps = { importRspeedy: rspeedy_1.importRspeedy, importPlugin: rspeedy_1.importPlugin, importQRCodePlugin: rspeedy_1.importQRCodePlugin }) => ({
+    [Symbol.asyncIterator]: () => {
+        let started;
+        return {
+            next: async () => {
+                if (!started) {
+                    started = startDevServer(options, context, deps);
+                    return { value: await started, done: false };
+                }
+                return (await started).success
+                    ? new Promise(() => { })
+                    : { value: undefined, done: true };
+            },
+        };
+    },
+});
+exports.runDevServer = runDevServer;
+exports.default = (0, architect_1.createBuilder)(exports.runDevServer);

package/builders/dev-server/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/builders/dev-server/schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularLynxDevServerBuilder",
+  "title": "AngularLynx dev-server builder",
+  "description": "Runs the rspeedy dev server, which Lynx Explorer and the web preview load the app from.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "buildTarget": {
+      "type": "string",
+      "description": "The build target to serve, as `project:target[:configuration]`, e.g. `my-app:build:development`. Its options (the Angular compiler options, `config`) configure the build, and its `optimization` picks a production or development build. Defaults to the project's build target with its development configuration, as Angular's own dev server does.",
+      "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
+    },
+    "port": {
+      "type": "number",
+      "description": "The port to serve on. Overrides `server.port` in lynx.config.ts."
+    },
+    "host": {
+      "type": "string",
+      "description": "The host to listen on. Overrides `server.host` in lynx.config.ts."
+    },
+    "environment": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Only build these rspeedy environments (e.g. lynx). Defaults to the build target's `environment`, or all of them."
+    }
+  }
+}

package/builders/extract-i18n/index.js

@@ -0,0 +1,70 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runExtractI18n = exports.hasLocalize = void 0;
+const architect_1 = require("@angular-devkit/architect");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const angular_build_1 = require("../angular-build");
+/** Whether the project has @angular/localize, which the extractor runs. */
+const hasLocalize = (projectRoot) => {
+    try {
+        (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, 'package.json')).resolve('@angular/localize/package.json');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.hasLocalize = hasLocalize;
+const defaultDeps = {
+    importAngularBuild: (projectRoot) => (0, angular_build_1.importAngularBuild)(projectRoot),
+    hasLocalize: exports.hasLocalize,
+};
+/**
+ * Angular's own message for a project without @angular/localize suggests
+ * `ng add @angular/localize`, which only sets up Angular's builders: on a
+ * Lynx app, `$localize` would then be missing at runtime.
+ */
+const NO_LOCALIZE = 'i18n extraction requires the @angular/localize package. Run `ng generate @blotch/angular-lynx:add-i18n` to install it and set up i18n.';
+/**
+ * `ng extract-i18n`: Angular's extract-i18n builder
+ * (`@angular/build:extract-i18n`), so the options, formats and messages file
+ * are the ones Angular developers know. Angular CLI picks that builder on its
+ * own only for a project built with one of Angular's builders, so without a
+ * target that names this one, `ng extract-i18n` fails with "Cannot determine
+ * project or target for command."
+ *
+ * Angular's extractor compiles the app with Angular's application builder
+ * from the build target's options. The Lynx build target reaches it as an
+ * Angular one, as in `ng test`: Angular's builder neither rejects the
+ * Lynx-only options nor fails on an imported image, which it has no loader
+ * for by default. No Lynx polyfills load, since the extractor only reads the
+ * compiled code and never runs it.
+ */
+const runExtractI18n = async (options, context, deps = defaultDeps) => {
+    const projectName = context.target?.project;
+    if (!projectName) {
+        return { success: false, error: 'The builder needs a project target.' };
+    }
+    const metadata = await context.getProjectMetadata(projectName);
+    const projectRoot = node_path_1.default.join(context.workspaceRoot, metadata['root'] ?? '');
+    if (!deps.hasLocalize(projectRoot)) {
+        return { success: false, error: NO_LOCALIZE };
+    }
+    let angularBuild;
+    try {
+        angularBuild = await deps.importAngularBuild(projectRoot);
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    return angularBuild.executeExtractI18nBuilder(options, (0, angular_build_1.asAngularBuildTargets)(context));
+};
+exports.runExtractI18n = runExtractI18n;
+exports.default = (0, architect_1.createBuilder)((options, context) => (0, exports.runExtractI18n)(options, context));

package/builders/extract-i18n/schema.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/builders/extract-i18n/schema.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "$id": "AngularLynxExtractI18nBuilder",
+  "title": "AngularLynx extract-i18n builder",
+  "description": "Extracts the i18n messages with Angular's extract-i18n builder (@angular/build:extract-i18n), set up for AngularLynx. The options are Angular's: this file copies its schema.json, and a test keeps the two in step.",
+  "type": "object",
+  "properties": {
+    "buildTarget": {
+      "type": "string",
+      "description": "A builder target to extract i18n messages in the format of `project:target[:configuration]`. You can also pass in more than one configuration name as a comma-separated list. Example: `project:target:production,staging`.",
+      "pattern": "^[^:\\s]*:[^:\\s]*(:[^\\s]+)?$"
+    },
+    "format": {
+      "type": "string",
+      "description": "Output format for the generated file.",
+      "default": "xlf",
+      "enum": [
+        "xmb",
+        "xlf",
+        "xlif",
+        "xliff",
+        "xlf2",
+        "xliff2",
+        "json",
+        "arb",
+        "legacy-migrate"
+      ]
+    },
+    "progress": {
+      "type": "boolean",
+      "description": "Log progress to the console.",
+      "default": true
+    },
+    "outputPath": {
+      "type": "string",
+      "description": "Path where output will be placed."
+    },
+    "outFile": {
+      "type": "string",
+      "description": "Name of the file to output."
+    },
+    "i18nDuplicateTranslation": {
+      "type": "string",
+      "description": "How to handle duplicate translations.",
+      "enum": ["error", "warning", "ignore"]
+    }
+  },
+  "additionalProperties": false
+}

package/builders/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/builders/project-import.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importFromProject = void 0;
+const node_fs_1 = require("node:fs");
+const node_module_1 = require("node:module");
+const node_path_1 = __importDefault(require("node:path"));
+const node_url_1 = require("node:url");
+/**
+ * Imports a package installed in the user's project (rspeedy), not one this
+ * package depends on. The project pins its own rspeedy version in
+ * package.json, and that is the version `ng build` must run, just as
+ * `rspeedy build` would.
+ *
+ * rspeedy is ESM-only, and its `exports` have no `require` condition, so
+ * `require.resolve` can't find its entry point. Its package.json is exported,
+ * though: resolve that and read the `import` entry from it.
+ */
+const importFromProject = async (packageName, projectRoot, installHint) => {
+    const require = (0, node_module_1.createRequire)(node_path_1.default.join(projectRoot, 'package.json'));
+    let packageJsonPath;
+    try {
+        packageJsonPath = require.resolve(`${packageName}/package.json`);
+    }
+    catch {
+        throw new Error(`${packageName} is not installed. ${installHint}`);
+    }
+    const packageJson = JSON.parse((0, node_fs_1.readFileSync)(packageJsonPath, 'utf8'));
+    const entry = resolveImportEntry(packageJson);
+    if (!entry) {
+        throw new Error(`${packageName} has no ESM entry point.`);
+    }
+    return (await import((0, node_url_1.pathToFileURL)(node_path_1.default.join(node_path_1.default.dirname(packageJsonPath), entry)).href));
+};
+exports.importFromProject = importFromProject;
+const resolveImportEntry = (packageJson) => {
+    const exports = packageJson.exports;
+    const root = exports && typeof exports === 'object' && '.' in exports
+        ? exports['.']
+        : exports;
+    return pick(root ?? null) ?? packageJson.module ?? packageJson.main;
+};
+/**
+ * Follows `import` (then `default`) conditions down to a file path.
+ */
+const pick = (value) => {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (!value) {
+        return undefined;
+    }
+    for (const condition of ['import', 'node', 'default']) {
+        if (condition in value) {
+            const found = pick(value[condition]);
+            if (found) {
+                return found;
+            }
+        }
+    }
+    return undefined;
+};