@_linked/cli 1.14.0 → 1.16.0

package/lib/esm/cli-methods.js

@@ -14,7 +14,7 @@ import { getEnvFile } from 'env-cmd/dist/get-env-vars.js';
 import fs from 'fs-extra';
 import path, { dirname } from 'path';
 import { createInterface } from 'readline';
-import { debugInfo, execp, execPromise, getFileImports, getFiles, getLastCommitTime, getPackageJSON, isImportOutsideOfPackage, isImportWithMissingExtension, isInvalidLINCDImport, needsRebuilding, } from './utils.js';
+import { debugInfo, execp, execPromise, getFileImports, getFiles, getLastCommitTime, getPackageJSON, isImportOutsideOfPackage, isInternalLinkedImport, needsRebuilding, } from './utils.js';
 import { renameShippedDotfiles } from './utils/shippedDotfiles.js';
 import { planPackageSetup } from './utils/packageSetup.js';
 import { rewriteExtensionlessImports } from './utils/esmSpecifiers.js';
@@ -124,7 +124,7 @@ export const createApp = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...ar
     // Scaffold from the canonical template repo (single source of truth; CN's
     // server-side createProject clones the same repo). Shallow clone, then drop
     // .git so the new app starts with clean history.
-    yield execPromise(`git clone --depth 1 https://github.com/linked-cm/app-template.git "${targetFolder}"`, false, false);
+    yield execPromise(`git clone --depth 1 https://github.com/linked-fw/app-template.git "${targetFolder}"`, false, false);
     fs.removeSync(path.join(targetFolder, '.git'));
     //make sure the data folder exists (even though its empty).. copying empty folders does not work with fs.copySync
     fs.mkdirSync(path.join(targetFolder, 'data'), { recursive: true });
@@ -137,19 +137,7 @@ export const createApp = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...ar
     if (fs.existsSync(gitignoreTemplate)) {
         fs.renameSync(gitignoreTemplate, path.join(targetFolder, '.gitignore'));
     }
-    const yarnrcTemplate = path.join(targetFolder, 'yarnrc.yml.template');
-    if (fs.existsSync(yarnrcTemplate)) {
-        fs.renameSync(yarnrcTemplate, path.join(targetFolder, '.yarnrc.yml'));
-    }
-    // Mark the new app as a self-contained Yarn project root. Without this,
-    // Yarn climbs ancestor dirs looking for the project root and may decide
-    // a stray yarn.lock further up the tree is "the project" — aborting
-    // install with "the nearest package directory doesn't seem to be part
-    // of the project declared in <ancestor>".
-    const yarnLockPath = path.join(targetFolder, 'yarn.lock');
-    if (!fs.existsSync(yarnLockPath)) {
-        fs.writeFileSync(yarnLockPath, '');
-    }
+    stripYarnProjectFiles(targetFolder);
     // Seed the real (gitignored) Layer 2 config from the committed example so
     // the scaffolded app boots first try. Users can edit either file later.
     const datasetsExample = path.join(targetFolder, 'linked.backend.datasets.example.json');
@@ -165,17 +153,13 @@ export const createApp = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...ar
     // create-app stamps this app's identity into the clone directly rather than
     // relying on ${var} substitution.
     applyAppIdentity(targetFolder, { appName, appPrefix, hyphenName });
-    // Pick a package manager. When both are available and the user is running
-    // create-app interactively, ask. Carry the choice through both the install
-    // step AND the final "next command" message so the user can copy-paste.
-    const interactive = !(options.appName ||
-        options.appPrefix ||
-        options.appDomain);
-    const pm = yield choosePackageManager(interactive);
+    // New apps are npm apps: npm is the package manager the templates, the CI
+    // workflows and the published @_linked/* packages are all tested against, and
+    // the react-native template already installs with npm. Keeping a single
+    // package manager also keeps the scaffolded app to a single lockfile.
+    const pm = CREATE_APP_PACKAGE_MANAGER;
     if (!options.skipInstall) {
-        const installCommand = pm === 'yarn'
-            ? 'export NODE_OPTIONS="--no-network-family-autoselection" && yarn install'
-            : 'npm install';
+        const installCommand = installCommandFor(pm);
         const spinner = ora({
             text: `Installing dependencies (${pm})...`,
             spinner: 'dots',
@@ -207,7 +191,7 @@ export const createApp = (name_1, ...args_1) => __awaiter(void 0, [name_1, ...ar
             }
         }
     }
-    const startCommand = pm === 'yarn' ? 'yarn start' : 'npm start';
+    const startCommand = startCommandFor(pm);
     log(`Your Linked app is ready at ${chalk.blueBright(targetFolder)}`, `\nStorage: linked.backend.storage.ts wires aliases to stores; linked.backend.datasets.json holds endpoints.`, `Defaults to Fuseki at ${chalk.cyan('http://localhost:3030')} (auto-creates the dataset on first boot).`, `Make sure Fuseki is running, e.g.:`, `  ${chalk.blueBright('docker run -d --rm -p 3030:3030 --name fuseki stain/jena-fuseki')}`, `Edit ${chalk.cyan('linked.backend.datasets.json')} to change endpoints or credentials.`, `Mirror file for the frontend: ${chalk.cyan('src/linked.frontend.storage.ts')} + ${chalk.cyan('src/linked.frontend.datasets.json')}.`, `\nTo start:`, `  ${chalk.blueBright(`cd ${hyphenName} && ${startCommand}`)}`);
 });
 /**
@@ -391,9 +375,26 @@ function setEnvVar(envText, key, value) {
  *  - `src/package.ts`: the runtime `linkedPackage` id — shape URIs derive from it.
  *  - pm2 process names + the VS Code launch name (cosmetic, but should match).
  */
+/**
+ * Scaffolded apps are npm apps, so the new app must not also look like a yarn
+ * project. Removes every yarn project file a template clone may still carry —
+ * including the legacy `yarnrc.yml.template` that create-app used to rename
+ * into `.yarnrc.yml`. (No empty `yarn.lock` is written any more either; that
+ * file only existed to pin down Yarn's project-root search.)
+ */
+export function stripYarnProjectFiles(targetFolder) {
+    for (const yarnLeftover of [
+        'yarnrc.yml.template',
+        '.yarnrc.yml',
+        '.yarn',
+        'yarn.lock',
+    ]) {
+        fs.removeSync(path.join(targetFolder, yarnLeftover));
+    }
+}
 function applyAppIdentity(targetFolder, ids) {
     const { appName, appPrefix, hyphenName } = ids;
-    // 1. .env.example (+ seed .env from it so the first `yarn start` is correct).
+    // 1. .env.example (+ seed .env from it so the first `npm start` is correct).
     const envExample = path.join(targetFolder, '.env.example');
     if (fs.existsSync(envExample)) {
         let env = fs.readFileSync(envExample, 'utf8');
@@ -1240,48 +1241,20 @@ const replaceVariablesInFolder = function (folder) {
 const replaceVariablesInFilesWithRoot = function (root, ...files) {
     return replaceVariablesInFiles(...files.map((f) => path.join(root, f)));
 };
-function isAvailable(cmd) {
-    return __awaiter(this, void 0, void 0, function* () {
-        try {
-            const out = (yield execPromise(`${cmd} --version`, false, false));
-            return /\d+/.test(String(out));
-        }
-        catch (_a) {
-            return false;
-        }
-    });
-}
-function detectPackageManagers() {
-    return __awaiter(this, void 0, void 0, function* () {
-        const found = [];
-        if (yield isAvailable('npm'))
-            found.push('npm');
-        if (yield isAvailable('yarn'))
-            found.push('yarn');
-        return found;
-    });
+/**
+ * The package manager `create-app` scaffolds with. Both templates (web and
+ * react-native) install with npm, so a scaffolded app has exactly one lockfile.
+ */
+export const CREATE_APP_PACKAGE_MANAGER = 'npm';
+/** The shell command that installs a scaffolded app's dependencies. */
+export function installCommandFor(pm) {
+    return pm === 'yarn'
+        ? 'export NODE_OPTIONS="--no-network-family-autoselection" && yarn install'
+        : 'npm install';
 }
-function choosePackageManager(interactive) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const available = yield detectPackageManagers();
-        if (available.length === 0) {
-            throw new Error('Neither npm nor yarn is available on PATH. Install one and retry.');
-        }
-        if (available.length === 1)
-            return available[0];
-        if (!interactive) {
-            // Match the historical default: prefer yarn when both are installed.
-            return available.includes('yarn') ? 'yarn' : 'npm';
-        }
-        const fallback = available.includes('yarn') ? 'yarn' : 'npm';
-        const answer = yield promptUser(`Package manager [${available.join('/')}] (default: ${chalk.gray(fallback)}): `);
-        const choice = answer.trim().toLowerCase();
-        if (choice === 'npm' || choice === 'yarn') {
-            if (available.includes(choice))
-                return choice;
-        }
-        return fallback;
-    });
+/** The command printed to the user for starting their new app. */
+export function startCommandFor(pm) {
+    return pm === 'yarn' ? 'yarn start' : 'npm start';
 }
 const ensureFolderExists = function (...folders) {
     let target;
@@ -1400,9 +1373,10 @@ export const createComponent = (name_1, ...args_1) => __awaiter(void 0, [name_1,
         log(`Added an import of this file from ${chalk.magenta(indexPath)}`);
     }
 });
-//read the source of all ts/tsx files in the src folder
-//if there is an import that imports a lincd package with /src/ in it, then warn
-//if there is an import that imports something from outside the src folder, then warn
+// Reads the source of all ts/tsx files in the src folder and fails on imports
+// that reach outside the package source root ('outside_package'), or that point
+// into another Linked package's /src/ or /lib/ ('internal_linked'). Extensionless relative
+// imports are fine: `linked build` rewrites the emitted ESM specifiers.
 export const checkImports = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (sourceFolder = getSourceFolder(), depth = 0, // Used to check if the import is outside the src folder
 invalidImports = new Map()) {
     if (!fs.existsSync(sourceFolder)) {
@@ -1413,12 +1387,8 @@ invalidImports = new Map()) {
     // Start checking each file in the source folder
     for (const file of dir) {
         const filename = path.join(sourceFolder, file);
-        // Skip test sources. Test files (and their helpers/probes)
-        // are not part of the shipped ESM contract, so the missing-extension rule
-        // isn't load-bearing for them; enforcing it only blocks `linked build`
-        // (the real ESM-output gate stays in force for shipped source). This is
-        // what makes `linked build` green for packages whose tests use
-        // extensionless imports (e.g. @_linked/core).
+        // Skip test sources. Test files (and their helpers/probes) are not part
+        // of the shipped package, so the import rules do not apply to them.
         if (/(?:^|[\\/])(?:tests?|__tests__|test-helpers)(?:[\\/]|$)/.test(filename) ||
             /\.(?:test|spec)\.tsx?$/.test(file) ||
             /^type-probe.*\.tsx?$/.test(file)) {
@@ -1432,16 +1402,13 @@ invalidImports = new Map()) {
                 if (statSync(filename).isDirectory()) {
                     yield checkImports(filename, depth + 1, invalidImports);
                 }
-                else {
-                    // Ignore all files that aren't one of the following:
-                    // - .ts
-                    // - .tsx
-                    continue;
-                }
             }
             catch (e) {
                 console.log(e);
             }
+            // A directory has now been recursed into, and any other file is not a
+            // source file: either way there is nothing here to read imports from.
+            continue;
         }
         const allImports = yield getFileImports(filename);
         if (!invalidImports.has(filename)) {
@@ -1454,15 +1421,9 @@ invalidImports = new Map()) {
                     importPath: i,
                 });
             }
-            if (isInvalidLINCDImport(i, depth)) {
+            if (isInternalLinkedImport(i)) {
                 invalidImports.get(filename).push({
-                    type: 'lincd',
-                    importPath: i,
-                });
-            }
-            if (isImportWithMissingExtension(i)) {
-                invalidImports.get(filename).push({
-                    type: 'missing_extension',
+                    type: 'internal_linked',
                     importPath: i,
                 });
             }
@@ -1481,26 +1442,22 @@ invalidImports = new Map()) {
                 if (type === 'outside_package') {
                     message += ' which is outside the package source root';
                 }
-                if (type === 'lincd') {
-                    message +=
-                        ' which should not contain /src/ or /lib/ in the import path';
-                }
-                if (type === 'missing_extension') {
+                if (type === 'internal_linked') {
                     message +=
-                        ' which should end with a file extension. Like .js or .scss';
+                        " which reaches into another Linked package's /src/ or /lib/." +
+                            ' That breaks when its build layout changes and bypasses its' +
+                            ' exports map. Import its public subpath instead.';
                 }
                 res += chalk.red(message + '\n');
             });
         });
-        // Throw so buildStep aborts the compile pipeline — relative imports MUST
-        // have .js (or .scss) extensions for native-ESM-compatible output.
+        // Throw so buildStep aborts the compile pipeline: importing from outside
+        // the package, or into another Linked package's /src/ or /lib/, breaks the
+        // published package.
         throw res;
     }
-    else if (depth === 0 && invalidImports.size === 0) {
-        // console.info('All imports OK');
-        // process.exit(0);
-        return true;
-    }
+    // Nothing invalid: all imports OK.
+    return true;
 });
 export const depCheckStaged = () => __awaiter(void 0, void 0, void 0, function* () {
     console.log('Checking dependencies of staged files');
@@ -2202,7 +2159,6 @@ export const register = function (registryURL) {
     }
 };
 export const buildPackage = (target_1, target2_1, ...args_1) => __awaiter(void 0, [target_1, target2_1, ...args_1], void 0, function* (target, target2, packagePath = process.cwd(), logResults = true) {
-    var _a;
     // Ensure packagePath is absolute and points to a directory containing package.json; if not, go up until we find one
     // First, resolve to absolute path
     let currentPath = path.isAbsolute(packagePath)
@@ -2276,7 +2232,20 @@ export const buildPackage = (target_1, target2_1, ...args_1) => __awaiter(void 0
                     }
                     return previousResult && true;
                 }
-                else if (typeof stepResult === 'object' && stepResult.error) {
+                else if (
+                //a step may report a detail alongside success, e.g. how many files
+                //it changed. Not a warning: the build stays clean.
+                stepResult &&
+                    typeof stepResult === 'object' &&
+                    stepResult.info) {
+                    if (logResults) {
+                        spinner.succeed(step.name + ' - ' + stepResult.info);
+                    }
+                    return previousResult && true;
+                }
+                else if (stepResult &&
+                    typeof stepResult === 'object' &&
+                    stepResult.error) {
                     if (logResults) {
                         spinner.fail(step.name + ' - ' + stepResult.error);
                         spinner.stop();
@@ -2287,13 +2256,21 @@ export const buildPackage = (target_1, target2_1, ...args_1) => __awaiter(void 0
                     //failed and should stop
                     return false;
                 }
+                //anything else — notably a literal false, which several steps return
+                //on failure — is a failure. Name the step, so the build does not end
+                //on a bare 'Build failed'.
+                const failure = step.name + ' failed';
+                if (logResults) {
+                    spinner.fail(failure);
+                    spinner.stop();
+                }
+                else {
+                    console.error(chalk.red(failure));
+                }
+                return false;
             });
         });
     };
-    if (((_a = pkgJson.linked) === null || _a === void 0 ? void 0 : _a.extensionlessImports) === true) {
-        const skipped = "Skipping the import check: package.json sets 'linked.extensionlessImports'";
-        logResults ? spinner.info(skipped) : console.log(skipped);
-    }
     planBuildSteps(pkgJson, packagePath).forEach(buildStep);
     let success = yield buildProcess.catch((err) => {
         let msg = typeof err === 'string' || err instanceof Error
@@ -2306,22 +2283,21 @@ export const buildPackage = (target_1, target2_1, ...args_1) => __awaiter(void 0
                 symbol: chalk.red('✖'),
                 // text: 'Build failed',
             });
+            console.log(msg);
         }
         else {
             console.error(chalk.red(packagePath.split('/').pop(), ' - Build failed:'));
             console.error(err);
-            return msg;
         }
-        console.log(msg);
+        //a failed build always resolves to false, never to a truthy message:
+        //callers decide success by the return value.
+        return false;
     });
-    //will be undefined if there was an error
-    if (typeof success !== 'undefined' && success !== false) {
+    if (success === true) {
         if (logResults) {
             spinner.stopAndPersist({
                 symbol: chalk.greenBright('✔'),
-                text: success === true && !warned
-                    ? 'Build successful'
-                    : 'Build successful with warnings',
+                text: warned ? 'Build successful with warnings' : 'Build successful',
             });
         }
     }
@@ -2333,52 +2309,31 @@ export const buildPackage = (target_1, target2_1, ...args_1) => __awaiter(void 0
             });
         }
     }
-    return success;
+    //true only when every step succeeded (warnings included); false otherwise.
+    return success === true;
 });
-// The ordered `linked build` steps for a linkedPackage. A package whose source
-// uses extensionless relative imports (`"linked": {"extensionlessImports": true}`)
-// skips the import check and gets `.js` added to its emitted ESM specifiers.
-export const planBuildSteps = (pkgJson, packagePath) => {
-    var _a;
-    const extensionlessImports = ((_a = pkgJson.linked) === null || _a === void 0 ? void 0 : _a.extensionlessImports) === true;
-    const steps = [];
-    if (!extensionlessImports) {
-        steps.push({
-            name: 'Checking imports',
-            apply: () => checkImports(packagePath + '/src'),
-        });
-    }
-    steps.push({
+// The ordered `linked build` steps for a linkedPackage. Source may use
+// extensionless relative imports: once `lib/esm` holds everything it will ship,
+// every package gets `.js` added to the relative specifiers in it (JS and
+// declarations). For a package that already writes `.js` this is a no-op.
+export const planBuildSteps = (pkgJson, packagePath) => [
+    {
+        name: 'Checking imports',
+        apply: () => checkImports(packagePath + '/src'),
+    },
+    {
         name: 'Compiling ESM',
         apply: () => __awaiter(void 0, void 0, void 0, function* () {
             return compilePackageESM(packagePath);
         }),
-    });
-    if (extensionlessImports) {
-        steps.push({
-            name: 'Rewriting ESM import specifiers',
-            apply: () => __awaiter(void 0, void 0, void 0, function* () {
-                const libEsm = path.join(packagePath, 'lib', 'esm');
-                if (!fs.existsSync(libEsm)) {
-                    return {
-                        error: "lib/esm was not emitted. 'linked.extensionlessImports' needs an ESM build: add tsconfig-esm.json to the package.",
-                    };
-                }
-                const { unresolved } = yield rewriteExtensionlessImports(libEsm);
-                if (unresolved.length > 0) {
-                    return `could not resolve ${unresolved.length} import(s), left unchanged: ${unresolved.join(', ')}`;
-                }
-                return true;
-            }),
-        });
-    }
-    steps.push({
+    },
+    {
         name: 'Compiling CJS',
         apply: () => __awaiter(void 0, void 0, void 0, function* () {
             return compilePackageCJS(packagePath);
         }),
-    });
-    steps.push({
+    },
+    {
         name: 'Copying files to lib folder',
         apply: () => __awaiter(void 0, void 0, void 0, function* () {
             const files = yield glob(packagePath + '/src/**/*.{json,d.ts,css,scss}');
@@ -2400,8 +2355,8 @@ export const planBuildSteps = (pkgJson, packagePath) => {
                 return allResults.every((r) => r === true);
             });
         }),
-    });
-    steps.push({
+    },
+    {
         name: 'Dual package support',
         apply: () => {
             // Skip if no tsconfig files (e.g. pure-CSS packages).
@@ -2415,19 +2370,48 @@ export const planBuildSteps = (pkgJson, packagePath) => {
                 return res === '';
             });
         },
-    });
-    steps.push({
+    },
+    {
         name: 'Removing old files from lib folder',
         apply: () => __awaiter(void 0, void 0, void 0, function* () {
             return removeOldFiles(packagePath);
         }),
-    });
-    steps.push({
+    },
+    {
+        // MUST run after 'Copying files to lib folder' and after 'Removing old
+        // files from lib folder', because the rewrite resolves each specifier
+        // against the files actually present in lib/esm:
+        // - the copy step brings in the assets (`./x.scss`) and hand-written
+        //   `.d.ts` from src; before it, an asset import looks unresolvable (a
+        //   spurious "build with warnings") and a copied `.d.ts` is never rewritten;
+        // - the cleanup step deletes stale output; before it, a leftover `x.js`
+        //   makes './x' resolve to './x.js' and the cleanup then removes the file
+        //   the specifier now points at.
+        name: 'Rewriting ESM import specifiers',
+        apply: () => __awaiter(void 0, void 0, void 0, function* () {
+            // No tsconfig-esm.json means the ESM compile was skipped (e.g. pure-CSS
+            // packages), so there is nothing to rewrite and nothing to fail over.
+            if (!fs.existsSync(path.join(packagePath, 'tsconfig-esm.json'))) {
+                return true;
+            }
+            const libEsm = path.join(packagePath, 'lib', 'esm');
+            if (!fs.existsSync(libEsm)) {
+                return {
+                    error: 'lib/esm was not emitted while tsconfig-esm.json is present. Check the ESM compile.',
+                };
+            }
+            const { changed, unresolved } = yield rewriteExtensionlessImports(libEsm);
+            if (unresolved.length > 0) {
+                return `could not resolve ${unresolved.length} import(s), left unchanged: ${unresolved.join(', ')}`;
+            }
+            return changed > 0 ? { info: `rewrote ${changed} file(s)` } : true;
+        }),
+    },
+    {
         name: 'Checking dependencies',
         apply: () => depCheck(packagePath),
-    });
-    return steps;
-};
+    },
+];
 export const compilePackage = (...args_1) => __awaiter(void 0, [...args_1], void 0, function* (packagePath = process.cwd()) {
     //echo 'compiling CJS' && tsc -p tsconfig-cjs.json && echo 'compiling ESM' && tsc -p tsconfig-esm.json
     // let cjsConfig = fs.existsSync(path.join(packagePath,'tsconfig-cjs.json'));
@@ -2751,12 +2735,10 @@ export var buildUpdated = function (back_1, target_1, target2_1) {
                     // log('path: ' + pathToBuild);
                     return buildPackage(null, null, pathToBuild, false)
                         .then((res) => {
-                        //empty string or true is success
-                        //false is success with warnings
-                        //any other string is the build error text
-                        //undefined result means it failed
-                        if (typeof res === 'undefined' || typeof res === 'string') {
-                            logError('Failed to build ' + pkg.packageName + '. ' + res ? res : '');
+                        //buildPackage returns true only when the build succeeded
+                        //(warnings included); anything else is a failure.
+                        if (res !== true) {
+                            logError('Failed to build ' + pkg.packageName);
                             process.exit(1);
                         }
                         else {