@codejen/pack-yeoman 0.0.0-stage → 2.0.1

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @codejen/pack-yeoman
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A [jen](https://learosema.github.io/jen/) pack that runs [Yeoman](https://yeoman.io) generators – [JHipster](https://www.jhipster.tech) included – through jen's plan: never interactive, never online, and nothing is written before you see it.
+
+**Documentation: <https://learosema.github.io/jen/yeoman.html>**
+
+## Install
+
+```sh
+npm install --save-dev @codejen/pack-yeoman generator-code   # or: npm install -g @codejen/jen @codejen/pack-yeoman generator-code
+```
+
+```sh
+jen yeoman:code --extensionType=command-ts --extensionDisplayName="My Extension"
+jen yeoman:jhipster --defaults --base-name=blog
+```
+
+## Credits
+
+[Yeoman](https://yeoman.io) by the Yeoman team, and [JHipster](https://www.jhipster.tech) by the JHipster team, whose environment builder and deferred commit the pack runs JHipster with.
+
+## License
+
+ISC © Lea Rosema

package/dist/common.d.ts

@@ -0,0 +1,36 @@
+/** What every Yeoman runner shares: jen's flags as Yeoman sees them, prompts answered without prompting, mem-fs files as jen actions. */
+import type { Action, Args, Context, PackEnv } from '@codejen/jen';
+export interface Question {
+    name: string;
+    default?: unknown;
+    when?: unknown;
+    [key: string]: unknown;
+}
+export interface MemFsFile {
+    path: string;
+    contents: Buffer | null;
+    state?: string;
+}
+/** Generators jen may fetch on the fly: a fixed list, so a typo (yeoman:jhispter) can never install someone else's package. */
+export declare const FETCHABLE: readonly string[];
+/** Whether `name` is installed – by its package.json, since a generator package's main may not resolve. */
+export declare const isInstalled: (env: PackEnv, name: string) => boolean;
+/** The first of `paths` (in package `name`) that resolves – after fetching `name` for this run if it's on the list and not installed. */
+export declare function locate(env: PackEnv, name: string, paths?: string[]): Promise<string>;
+/** The raw flags and positionals – jen fills them in since 3.0. */
+export declare function argsOf(ctx: Context): Args;
+/** Absolute directory the files go to: the current directory, or --dir. */
+export declare const destination: (ctx: Context) => string;
+export declare const camel: (s: string) => string;
+/** Answers questions from CLI flags (as typed, or camelCased) or the question's own default. Never prompts. */
+export declare function answerPrompt(questions: Question | Question[], flags: Record<string, unknown>): Promise<Record<string, unknown>>;
+/** jen's flags back as a command line, for a generator's own option parser. */
+export declare const toArgv: ({ flags, positionals }: Args) => string[];
+/**
+ * Runs a generator with the network cut off – fetch() and every TCP connection
+ * fail – and fails the run if it tried, even when the generator swallowed the
+ * error: whatever a generator downloads or sends would bypass jen's plan.
+ */
+export declare function offline<T>(run: () => Promise<T>): Promise<T>;
+/** The files a generator left pending in mem-fs, as jen actions with paths from the project root. */
+export declare function toActions(files: MemFsFile[], root: string): Action[];

package/dist/common.js

@@ -0,0 +1,132 @@
+import { Socket } from 'node:net';
+import { join, relative, sep } from 'node:path';
+/** Generators jen may fetch on the fly: a fixed list, so a typo (yeoman:jhispter) can never install someone else's package. */
+export const FETCHABLE = ['generator-code', 'generator-jhipster'];
+/** Whether `name` is installed – by its package.json, since a generator package's main may not resolve. */
+export const isInstalled = (env, name) => env.resolve(`${name}/package.json`) !== null;
+/** The first of `paths` (in package `name`) that resolves – after fetching `name` for this run if it's on the list and not installed. */
+export async function locate(env, name, paths = [name]) {
+    const first = () => paths.map((p) => env.resolve(p)).find((f) => f !== null) ?? null;
+    const installed = isInstalled(env, name);
+    if (!installed && !FETCHABLE.includes(name))
+        throw new Error(`${name} is listed but not installed – run npm install.`);
+    if (!installed && (await env.fetch(name)) === null && !isInstalled(env, name)) {
+        throw new Error(`${name} isn't installed, and fetching is off (JEN_NO_FETCH).`);
+    }
+    return first() ?? fail(`${name} has no generator at ${paths.join(', ')}.`);
+}
+const fail = (message) => {
+    throw new Error(message);
+};
+/** The raw flags and positionals – jen fills them in since 3.0. */
+export function argsOf(ctx) {
+    if (!ctx.args)
+        throw new Error('@codejen/pack-yeoman needs @codejen/jen 3 or later.');
+    return ctx.args;
+}
+/** Absolute directory the files go to: the current directory, or --dir. */
+export const destination = (ctx) => join(ctx.root, ctx.destDir);
+export const camel = (s) => s.replace(/-+([a-z0-9])/g, (_, c) => c.toUpperCase());
+/** What pressing enter would answer: the default – for a list, the choice it points to or the first one; for a confirm, yes. */
+function defaultOf(q) {
+    const choices = Array.isArray(q.choices) ? q.choices.filter((c) => typeof c === 'string' || c.type !== 'separator') : [];
+    const value = (c) => (typeof c === 'object' ? (c.value ?? c.name) : c);
+    const list = ['list', 'rawlist', 'select', 'expand'].includes(String(q.type));
+    if (list && typeof q.default === 'number')
+        return value(choices[q.default]);
+    if (q.default !== undefined)
+        return q.default;
+    if (list)
+        return value(choices[0]);
+    if (q.type === 'confirm')
+        return true;
+    return undefined;
+}
+/** Answers questions from CLI flags (as typed, or camelCased) or the question's own default. Never prompts. */
+export async function answerPrompt(questions, flags) {
+    const given = new Map(Object.entries(flags).map(([k, v]) => [camel(k), v]));
+    const answers = {};
+    const missing = [];
+    for (const q of Array.isArray(questions) ? questions : [questions]) {
+        const when = typeof q.when === 'function' ? await q.when(answers) : (q.when ?? true);
+        if (!when)
+            continue;
+        if (given.has(camel(q.name))) {
+            answers[q.name] = given.get(camel(q.name));
+        }
+        else if (typeof q.default === 'function') {
+            answers[q.name] = await q.default(answers);
+        }
+        else if (defaultOf(q) !== undefined) {
+            answers[q.name] = defaultOf(q);
+        }
+        else {
+            missing.push(q.name);
+        }
+    }
+    if (missing.length > 0) {
+        throw new Error(`Missing: ${missing.map((n) => `--${n}`).join(', ')} (asked by the generator's prompting step; jen never prompts).`);
+    }
+    return answers;
+}
+/** jen's flags back as a command line, for a generator's own option parser. */
+export const toArgv = ({ flags, positionals }) => [
+    ...Object.entries(flags).flatMap(([name, value]) => (typeof value === 'boolean' ? (value ? [`--${name}`] : []) : [`--${name}=${value}`])),
+    ...positionals,
+];
+/**
+ * Runs a generator with the network cut off – fetch() and every TCP connection
+ * fail – and fails the run if it tried, even when the generator swallowed the
+ * error: whatever a generator downloads or sends would bypass jen's plan.
+ */
+export async function offline(run) {
+    const tried = [];
+    const { fetch } = globalThis;
+    const { connect } = Socket.prototype;
+    globalThis.fetch = async (input) => {
+        const url = input instanceof Request ? input.url : String(input);
+        tried.push(url);
+        throw new Error(`${url}: Yeoman generators run offline under jen.`);
+    };
+    Socket.prototype.connect = function (...args) {
+        const [target] = args;
+        const where = typeof target === 'object' ? (target.path ?? `${target.host ?? 'localhost'}:${target.port}`) : String(target);
+        tried.push(where);
+        process.nextTick(() => this.destroy(new Error(`${where}: Yeoman generators run offline under jen.`)));
+        return this;
+    };
+    try {
+        const result = await run();
+        if (tried.length > 0)
+            throw new Error(`The generator tried to reach ${[...new Set(tried)].join(', ')} – Yeoman generators run offline under jen.`);
+        return result;
+    }
+    finally {
+        globalThis.fetch = fetch;
+        Socket.prototype.connect = connect;
+    }
+}
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+/** Text if it's valid UTF-8 without NUL bytes, else the bytes as they are. */
+function decode(contents) {
+    try {
+        const text = utf8.decode(contents);
+        return text.includes('\0') ? contents : text;
+    }
+    catch {
+        return contents;
+    }
+}
+/** The files a generator left pending in mem-fs, as jen actions with paths from the project root. */
+export function toActions(files, root) {
+    const fromRoot = (path) => `/${relative(root, path).split(sep).join('/')}`;
+    return files.flatMap((file) => {
+        if (file.state === 'modified') {
+            const contents = decode(file.contents ?? Buffer.alloc(0));
+            return [typeof contents === 'string' ? { add: fromRoot(file.path), template: contents } : { add: fromRoot(file.path), bytes: contents }];
+        }
+        if (file.state === 'deleted')
+            return [{ delete: fromRoot(file.path) }];
+        return [];
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** jen pack running Yeoman generators – documented at https://learosema.github.io/jen/yeoman.html */
+import type { PackFactory } from '@codejen/jen';
+declare const pack: PackFactory;
+export default pack;

package/dist/index.js

@@ -0,0 +1,20 @@
+import { FETCHABLE, isInstalled } from "./common.js";
+import { jhipsterGenerator } from "./jhipster.js";
+import { shimGenerator } from "./shim.js";
+/** Yeoman's package naming: "generator-code" or "@scope/generator-code" → "code". */
+const YEOMAN_RE = /^(?:@[^/]+\/)?generator-(.+)$/;
+const pack = (env) => {
+    const generators = {};
+    for (const name of new Set([...env.packages(YEOMAN_RE), ...FETCHABLE])) {
+        const short = YEOMAN_RE.exec(name)?.[1] ?? name;
+        if (short in generators)
+            continue;
+        const fetched = isInstalled(env, name) ? '' : ' – fetched when run';
+        generators[short] =
+            name === 'generator-jhipster'
+                ? jhipsterGenerator(env, `JHipster: an app, or a command like jdl${fetched}`)
+                : shimGenerator(name, short, env, `Yeoman ${name}${fetched}`);
+    }
+    return generators;
+};
+export default pack;

package/dist/jhipster.d.ts

@@ -0,0 +1,4 @@
+/** Runs JHipster in its own real yeoman-environment, keeping what it writes in memory for jen's plan. */
+import type { AnyGenerator, PackEnv } from '@codejen/jen';
+/** JHipster's generators, by the same commands as its own CLI. */
+export declare function jhipsterGenerator(env: PackEnv, description: string): AnyGenerator;

package/dist/jhipster.js

@@ -0,0 +1,125 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { answerPrompt, argsOf, camel, locate, offline, destination, toActions } from "./common.js";
+const PRETTIER_CONFIG = /(?:^|[/\\])(?:\.prettierrc[^/\\]*|\.editorconfig)$/;
+/**
+ * JHipster's own commit applies prettier and eslint; with deferCommit it
+ * leaves the results pending instead of writing them. Without a custom
+ * commit task, nothing is committed at all.
+ */
+function deferCommits(env) {
+    env.queueCommit = function queueCommit() {
+        this.queueTask('environment:conflicts', async () => {
+            const requeue = (path) => {
+                const state = this.sharedFs.get(path).state;
+                if (state === 'modified' || state === 'deleted') {
+                    this.sharedFs.removeListener('change', requeue);
+                    this.queueCommit();
+                }
+            };
+            this.sharedFs.on('change', requeue);
+            const task = this.composedStore.customCommitTask;
+            if (typeof task === 'function')
+                await task();
+        }, { once: 'write memory fs to disk' });
+    };
+}
+/** Drops install, end and every custom priority after install – they assume the files are on disk. */
+function skipFromInstall(env) {
+    const queueTask = env.queueTask.bind(env);
+    env.queueTask = (queueName, fn, options) => {
+        const names = env.runLoop.queueNames;
+        const install = names.indexOf('install');
+        if (install >= 0 && names.indexOf(queueName) >= install)
+            return;
+        queueTask(queueName, fn, options);
+    };
+}
+/**
+ * Prettier finds its config on disk, relative to the working directory. jen
+ * runs JHipster from a scratch directory that mirrors only the config files
+ * it generates, so nothing lands in the project before the plan is applied.
+ */
+function mirrorPrettierConfig(env, cwd, scratch) {
+    for (const name of existsSync(cwd) ? readdirSync(cwd) : []) {
+        if (PRETTIER_CONFIG.test(name))
+            copyFileSync(join(cwd, name), join(scratch, name));
+    }
+    env.sharedFs.on('change', (path) => {
+        const file = env.sharedFs.get(path);
+        // mem-fs takes a new file's base from the working directory: keep it the destination
+        file.cwd = cwd;
+        file.base = cwd;
+        const rel = relative(cwd, path);
+        if (!PRETTIER_CONFIG.test(path) || rel.startsWith('..') || !file.contents)
+            return;
+        mkdirSync(dirname(join(scratch, rel)), { recursive: true });
+        writeFileSync(join(scratch, rel), file.contents);
+    });
+}
+/** JHipster asks npm for its latest version, for an update notice: skipped, without turning off its other checks (skipChecks). */
+async function skipVersionCheck(baseCoreFile) {
+    const { default: BaseCore } = (await import(__rewriteRelativeImportExtension(pathToFileURL(baseCoreFile).href)));
+    const { checkForNewVersion } = BaseCore.prototype;
+    BaseCore.prototype.checkForNewVersion = async () => undefined;
+    return () => {
+        BaseCore.prototype.checkForNewVersion = checkForNewVersion;
+    };
+}
+async function run(cliFile, baseCoreFile, ctx) {
+    const args = argsOf(ctx);
+    const here = process.cwd();
+    const cwd = destination(ctx);
+    const { EnvironmentBuilder } = (await import(__rewriteRelativeImportExtension(pathToFileURL(cliFile).href)));
+    // blueprints that aren't installed would be fetched by name from the generator's config, outside jen's plan
+    const builder = await EnvironmentBuilder.create({ cwd, skipInstall: true }).prepare({ disableBlueprints: true });
+    const env = builder.getEnvironment();
+    env.adapter.prompt = async (questions) => answerPrompt(questions, args.flags);
+    deferCommits(env);
+    skipFromInstall(env);
+    // "jen yeoman:jhipster entity Foo" is "jhipster entity Foo"; files given are relative to where jen runs
+    const [first, ...rest] = args.positionals;
+    const command = first && env.getGeneratorMeta(`jhipster:${first}`) ? first : 'app';
+    const positionals = (command === first ? rest : args.positionals).map((p) => (existsSync(resolve(here, p)) ? resolve(here, p) : p));
+    const scratch = mkdtempSync(join(tmpdir(), 'jen-jhipster-'));
+    mirrorPrettierConfig(env, cwd, scratch);
+    const restore = await skipVersionCheck(baseCoreFile);
+    process.chdir(scratch);
+    try {
+        // like JHipster's own CLI: options as an object, camelCased
+        await env.run([`jhipster:${command}`, ...positionals], {
+            ...Object.fromEntries(Object.entries(args.flags).map(([k, v]) => [camel(k), v])),
+            skipInstall: true,
+            skipGit: true,
+            deferCommit: true,
+        });
+    }
+    finally {
+        restore();
+        process.chdir(here);
+        rmSync(scratch, { recursive: true, force: true });
+    }
+    return toActions(env.sharedFs.all(), ctx.root);
+}
+/** JHipster's generators, by the same commands as its own CLI. */
+export function jhipsterGenerator(env, description) {
+    return {
+        description,
+        passthrough: true,
+        actions: async (_answers, _helpers, ctx) => {
+            const cliFile = await locate(env, 'generator-jhipster', ['generator-jhipster/cli']);
+            const baseCoreFile = await locate(env, 'generator-jhipster', ['generator-jhipster/generators/base-core']);
+            return offline(() => run(cliFile, baseCoreFile, ctx));
+        },
+    };
+}

package/dist/shim.d.ts

@@ -0,0 +1,4 @@
+/** Runs a Yeoman generator with just enough of a yeoman-environment faked around it, borrowing yeoman-generator and mem-fs from the generator's own install. */
+import type { AnyGenerator, PackEnv } from '@codejen/jen';
+/** A generator package's default generator – what `yo <name>` runs. */
+export declare function shimGenerator(name: string, short: string, env: PackEnv, description: string): AnyGenerator;

package/dist/shim.js

@@ -0,0 +1,88 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { answerPrompt, argsOf, locate, offline, destination, toActions, toArgv } from "./common.js";
+/** The priorities that run, in order. install/end never do: their side effects assume files already on disk. */
+const PRIORITIES = ['initializing', 'prompting', 'configuring', 'default', 'writing', 'transform', 'conflicts'];
+function makeLog() {
+    const log = ((...args) => {
+        console.log(...args);
+        return log;
+    });
+    for (const level of ['error', 'warn', 'info', 'ok'])
+        log[level] = log;
+    log.debug = () => log;
+    return log;
+}
+async function run(resolved, namespace, ctx) {
+    const args = argsOf(ctx);
+    const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href)));
+    const GeneratorClass = (mod.default ?? mod);
+    if (typeof GeneratorClass !== 'function')
+        throw new Error(`${resolved}: the default export is not a Yeoman generator class.`);
+    const require = createRequire(resolved);
+    const memFs = (await import(__rewriteRelativeImportExtension(pathToFileURL(require.resolve('mem-fs')).href)));
+    const sharedFs = memFs.create();
+    const queues = new Map(PRIORITIES.map((name) => [name, []]));
+    const cwd = destination(ctx);
+    const env = {
+        cwd,
+        logCwd: cwd,
+        sharedFs,
+        options: {},
+        adapter: {
+            log: makeLog(),
+            prompt: async (questions) => answerPrompt(questions, args.flags),
+            // eslint-disable-next-line @typescript-eslint/no-empty-function -- only used for progress messages we don't print
+            progress: async (fn) => fn({ step() { } }),
+        },
+        getVersion: () => '999.0.0',
+        // eslint-disable-next-line @typescript-eslint/no-empty-function -- custom priorities aren't supported, nothing to register
+        addPriority() { },
+        queueTask(queueName, fn) {
+            // install, end and custom priorities are dropped, not run late or folded into another queue
+            queues.get(queueName)?.push(fn);
+        },
+        composeWith() {
+            throw new Error('This generator composes other generators (composeWith), which only JHipster gets a real environment for.');
+        },
+        async runGenerator(generator) {
+            await generator.queueTasks();
+            for (const name of PRIORITIES) {
+                for (const task of queues.get(name) ?? [])
+                    await task();
+            }
+        },
+        // eslint-disable-next-line @typescript-eslint/no-empty-function -- nothing listens on the env, so events are dropped
+        emit() { },
+    };
+    const generator = new GeneratorClass(toArgv(args), {
+        env,
+        resolved,
+        namespace,
+        skipCache: true,
+        skipLocalCache: true,
+        skipInstall: true,
+    });
+    await generator.run();
+    return toActions(sharedFs.all(), ctx.root);
+}
+/** A generator package's default generator – what `yo <name>` runs. */
+export function shimGenerator(name, short, env, description) {
+    return {
+        description,
+        passthrough: true,
+        actions: async (_answers, _helpers, ctx) => {
+            // the package's main, else where yo looks: generators/app, then app
+            const resolved = await locate(env, name, [name, `${name}/generators/app`, `${name}/app`]);
+            return offline(() => run(resolved, `${short}:app`, ctx));
+        },
+    };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@codejen/pack-yeoman",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.1",
+  "description": "jen pack that runs Yeoman generators, JHipster included, through jen's plan: never interactive, nothing written before you see it",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/learosema/jen.git",
+    "directory": "packages/pack-yeoman"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "pretypecheck": "npm run build --prefix ../jen",
+    "prebuild": "npm run build --prefix ../jen",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc",
+    "test": "node --test pack-yeoman.test.ts",
+    "prepublishOnly": "npm test && npm run typecheck && npm run build"
+  },
+  "keywords": [
+    "jen-pack",
+    "yeoman",
+    "jhipster"
+  ],
+  "author": "Lea Rosema",
+  "license": "ISC",
+  "peerDependencies": {
+    "@codejen/jen": "^2.0.0 || ^3.0.0"
+  },
+  "devDependencies": {
+    "@codejen/jen": "^2.0.0 || ^3.0.0",
+    "@types/node": "^26.6.3",
+    "mem-fs": "^6.0.0",
+    "typescript": "^6.0.3",
+    "yeoman-generator": "^10.0.1"
+  }
+}