@leyman/nx-plugin 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jacob Ley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,217 @@
-# Temporary Holding Version
+<div style="text-align:center">
 
-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.
+# @leyman/nx-plugin
+
+Nx plugin inferring the build, test, lint and package-check targets of TypeScript ESM packages: SWC and tsc builds, Mocha or Vitest under c8, ESLint, Biome and check-package.
+
+[![npm package](https://badge.fury.io/js/@leyman%2Fnx-plugin.svg)](https://www.npmjs.com/package/@leyman/nx-plugin)
+[![License](https://img.shields.io/npm/l/@leyman/nx-plugin.svg)](https://github.com/JacobLey/leyman/blob/main/leyman/nx-plugin/LICENSE)
+
+</div>
+
+- **Targets from files** — a project with `src/` and `tsconfig.json` gets `tsc`, one with `test/unit` and Mocha installed gets `mocha-unit-test`, a public one gets `check-package`, and so on.
+- **Cached precisely** — each target hashes only what its result depends on: its sources, the shared configs, and the built output of its dependencies (not their source), so editing a dependency's tests reruns nothing downstream.
+- **Builds that respect the support floor** — SWC compiles to the ES year of the oldest Node.js `engines.node` allows, and `tsc` checks types and writes declarations.
+- **Coverage over all of a project's tests** — each test target runs under c8, and `coverage-report` checks the coverage of all of them together.
+- **Overridable** — rename a target, turn it off, include or exclude projects, or override any part in `project.json`.
+- **Generators** — `init` sets an Nx workspace up for the plugin (`nx add @leyman/nx-plugin` runs it), and `package` adds a package with the targets it gets already declared.
+- **Or written out** — a workspace that can't load the plugin (because it builds it, say) writes the same targets into `nx.json` and each `project.json` with the `targets` executor, which fails on drift in CI.
+
+It is the setup of the [leyman](https://github.com/JacobLey/leyman) monorepo, published as-is. Expect it to be opinionated and to change: see [Versioning](#versioning).
+
+## Contents
+
+- [Install](#install)
+- [Example](#example)
+- [Usage](#usage)
+- [Targets](#targets)
+- [Options](#options)
+- [Generators](#generators)
+- [The targets executor](#the-targets-executor)
+- [API](#api)
+- [Versioning](#versioning)
+
+## Install
+
+```sh
+nx add @leyman/nx-plugin
+```
+
+That installs the plugin and runs its [`init`](#init) generator. Or install it yourself:
+
+```sh
+npm i -D @leyman/nx-plugin @leyman/configs
+```
+
+Each project then installs what its targets run: `@swc/cli`, `@swc/core` and `typescript` to build, `mocha` or `vitest` and `c8` to test, `eslint`, and `@biomejs/biome` at the workspace root. `check-package` runs [`@leyman/check-package`](https://www.npmjs.com/package/@leyman/check-package), and `update-ts-references` needs `@nx/js`.
+
+## Example
+
+`nx.json`:
+
+```json
+{
+  "plugins": [
+    {
+      "plugin": "@leyman/nx-plugin",
+      "options": {
+        "checkPackage": { "profile": "esm-only" }
+      }
+    }
+  ]
+}
+```
+
+A package with `package.json` (with `mocha` in `devDependencies`), `project.json`, `tsconfig.json`, `src/`, `test/tsconfig.json`, `test/unit/` and `eslint.config.js` gets `biome`, `eslint`, `check-package`, `update-ts-references`, `tsc`, `tsc-test`, `mocha-unit-test` and `coverage-report`:
+
+```sh
+nx run my-package:tsc
+nx run-many -t mocha-unit-test
+```
+
+## Usage
+
+The plugin infers targets for each project with a `project.json`. It says how each target runs and what it hashes, not when: wire the order yourself with `dependsOn` (in `nx.json` `targetDefaults` or `project.json`), or with [nx-lifecycle](https://www.npmjs.com/package/nx-lifecycle), binding each target to a stage. nx-lifecycle wires the targets a `project.json` declares, so declare them there as `{}`.
+
+Targets run from the project's directory. The defaults read the shared configs from the project's own `node_modules/@leyman/configs`, so each project installs [`@leyman/configs`](https://www.npmjs.com/package/@leyman/configs), as its `tsconfig.json` extends it anyway.
+
+Anything in `project.json` is merged over the inferred target, key by key, so a project can change one option of a target and keep the rest.
+
+## Targets
+
+| Target                   | Inferred when                                                   | Runs                                                                                                              |
+| ------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `biome`                  | Always                                                          | `biome format --write .`, or only checks in CI. `-c check` only checks.                                           |
+| `eslint`                 | `eslint.config.js`                                              | `eslint` on the project. `-c fix` fixes.                                                                          |
+| `check-package`          | `tsc` is, and `package.json` isn't `private`                    | `check-package`, on the package as it would be published.                                                         |
+| `update-ts-references`   | `tsconfig.json`                                                 | Nx's TypeScript sync generator, which keeps `references` in step with dependencies.                               |
+| `tsc`                    | `tsconfig.json` and `src/`                                      | Clears `dist/`, compiles `src/` with SWC, then `tsc` for types and declarations.                                  |
+| `tsc-test`               | `test/tsconfig.json`                                            | Compiles `test/` into `dist-test/` with SWC, then type-checks it with `tsc -p ./test`.                            |
+| `mocha-unit-test`        | `test/unit/`, and `mocha` in `devDependencies`                  | Mocha on `dist-test/unit/**/*.spec.*js`, under c8.                                                                |
+| `mocha-integration-test` | `test/integration/`, and `mocha` in `devDependencies`           | Mocha on `dist-test/integration/**/*.spec.*js`, under c8, with a 10 second timeout.                               |
+| `vitest-unit-test`       | `test/unit/`, and `vitest` but not `mocha` in `devDependencies` | Vitest on the compiled tests, under c8.                                                                           |
+| `coverage-report`        | `tsc` and a test target are                                     | Checks the coverage the test targets wrote, together, against the c8 config's thresholds.                         |
+| `sync-injected`          | Another project's `package.json` depends on this one            | Mirrors the package into the copies pnpm injected into its dependents (`injectWorkspacePackages`), after a build. |
+
+`tsc`, `tsc-test`, `coverage-report`, `biome` and `sync-injected` run the package's scripts, as its bins:
+
+| Bin                      | Usage                                                                                                                                 |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `leyman-clean-dist`      | Clears `dist/`, keeping `tsc`'s build info and declarations while they are exactly those of the current sources, so `tsc` stays fast. |
+| `leyman-swc-compile`     | `leyman-swc-compile <source> <output> <swcrc>`: compiles with SWC, to the ES year of the package's support floor.                     |
+| `leyman-coverage-report` | `leyman-coverage-report <c8rc> [c8 options...]`                                                                                       |
+| `leyman-biome-format`    | Formats with Biome; only checks in CI.                                                                                                |
+| `leyman-sync-injected`   | Mirrors the package into its injected copies, and writes the fields of `package.json` that dependents hash.                           |
+
+The targets also define the named inputs `dependency-files`, `package-files`, `eslint-input`, `ts-source`, `dependency-builds` and `test-source` on each project.
+
+## Options
+
+All optional.
+
+| Option                       | Default                                                                 | Description                                                                                                                                  |
+| ---------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `targets.<target>`           | `{}`                                                                    | `false` to infer the target nowhere, or `{ name, include, exclude }`: its name, and roots of projects that always or never get it.           |
+| `configs.swc`                | `node_modules/@leyman/configs/swcrc.jsonc`                              | SWC config, relative to each project.                                                                                                        |
+| `configs.c8`                 | `node_modules/@leyman/configs/c8rc.json`                                | c8 config, relative to each project.                                                                                                         |
+| `configs.vitest`             | `node_modules/@leyman/configs/vitest.config.js`                         | Vitest config, relative to each project.                                                                                                     |
+| `coverage`                   | —                                                                       | `{ branches, functions, lines, statements }`: thresholds passed to c8 over the c8 config's.                                                  |
+| `checkPackage.profile`       | check-package's, `strict`                                               | `strict`, `node16` or `esm-only`.                                                                                                            |
+| `checkPackage.floorTsconfig` | `@leyman/configs/tsconfig.node-{major}.json`                            | The config a package's `tsconfig.json` must extend for its support floor, or `false`.                                                        |
+| `checkPackage.inputs`        | `[{ "externalDependencies": ["@leyman/check-package", "typescript"] }]` | What a change of check-package itself is hashed by.                                                                                          |
+| `inputs.configs`             | `[{ "externalDependencies": ["@leyman/configs"] }]`                     | What a change of the shared configs is hashed by. A workspace keeping them in a project of its own lists their paths instead.                |
+| `inputs.tools`               | `[{ "externalDependencies": ["@leyman/nx-plugin"] }]`                   | What a change of the scripts is hashed by.                                                                                                   |
+| `scripts`                    | —                                                                       | A directory to run the scripts from instead of the bins, such as `${NX_WORKSPACE_ROOT}/tools/nx-plugin/scripts` for a copy in the workspace. |
+| `namedInputs.<name>`         | —                                                                       | Inputs added to the end of a named input, such as `{ "test-source": ["{projectRoot}/schema.sql"] }` for a file the tests read.               |
+
+The options are checked against [`out/schema.json`](./out/schema.json); an invalid one fails with its path.
+
+## Generators
+
+### `init`
+
+```sh
+nx g @leyman/nx-plugin:init
+```
+
+Sets the workspace up for the plugin, leaving alone anything already set:
+
+- `nx.json`: the plugin, and [nx-lifecycle](https://www.npmjs.com/package/nx-lifecycle)'s plugin with the stages install, prepare (generate, format), check (lint), build (run, post, sync), test (compile, run, report) and verify, and each target bound to one, under the name the options give it. `--lifecycle=false` leaves nx-lifecycle out.
+- `devDependencies` of the root `package.json`: the plugin, `@leyman/configs`, `@biomejs/biome`, `@leyman/check-package`, `@nx/js` and `nx-lifecycle`.
+- `biome.json`, extending `@leyman/configs/biome.base.json`.
+- `pnpm-workspace.yaml`, if there is one: `injectWorkspacePackages: true` and `dedupeInjectedDeps: false`, so dependents get workspace packages as published, which `sync-injected` keeps current.
+- `.claude/skills/principles/SKILL.md`, pointing coding agents at the [principles](https://jacobley.github.io/leyman/framework/principles) of the setup. `--skill=false` leaves it out.
+
+Then it installs the dependencies, unless `--skipInstall`.
+
+### `package`
+
+```sh
+nx g @leyman/nx-plugin:package packages/my-lib --description "Does things."
+```
+
+Adds a TypeScript ESM package: `package.json`, `tsconfig.json` (extending `@leyman/configs`), `src/index.ts`, a first test with its `test/tsconfig.json`, `eslint.config.js`, a `README.md`, and a `project.json` declaring as `{}` the targets the plugin infers from those files, so nx-lifecycle wires them. Then it installs the dependencies, unless `--skipInstall`, and `nx sync` adds the `tsconfig.json` references.
+
+| Option            | Default                   | Description                                                                                                                                                                                             |
+| ----------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `directory`       | —                         | Where the package goes, relative to the workspace root. The first argument.                                                                                                                             |
+| `description`     | —                         | For `package.json` and the README.                                                                                                                                                                      |
+| `name`            | The directory's last part | Name of the package.                                                                                                                                                                                    |
+| `published`       | `false`                   | Published to npm, rather than `private`: it gets `engines`, extends its support floor's `@leyman/configs/tsconfig.node-{floor}.json`, takes `@types/node` of that major, and the workspace's `LICENSE`. |
+| `floor`           | `22`                      | Major of the oldest Node.js a published package supports.                                                                                                                                               |
+| `test`            | `mocha`                   | `mocha`, `vitest`, or `none`.                                                                                                                                                                           |
+| `repository`      | —                         | URL of the workspace's GitHub repository, for a published package's `repository`, `homepage` and `bugs`.                                                                                                |
+| `author`          | —                         | `author` of `package.json`.                                                                                                                                                                             |
+| `license`         | —                         | `license` of `package.json`.                                                                                                                                                                            |
+| `devDependencies` | —                         | More packages to add to `devDependencies`.                                                                                                                                                              |
+| `config`          | The options in `nx.json`  | A file of the plugin [options](#options), for a workspace running the [targets executor](#the-targets-executor).                                                                                        |
+| `skipInstall`     | `false`                   | Don't install the dependencies.                                                                                                                                                                         |
+
+Set the ones a workspace always passes as defaults in `nx.json`:
+
+```json
+{
+  "generators": {
+    "@leyman/nx-plugin": {
+      "package": { "repository": "https://github.com/owner/repo", "license": "MIT" }
+    }
+  }
+}
+```
+
+Each dependency's version comes from the workspace if it can: `workspace:^` for one of its own packages, `catalog:` for one in the pnpm catalog (`catalog:node-{floor}` for a published package's `@types/node`), or the range another package already uses. Otherwise it is the version this plugin was published with, and a package with none of those fails.
+
+## The targets executor
+
+A workspace that can't load the plugin, such as one that builds it, writes the same targets out instead:
+
+```json
+{
+  "targets": {
+    "nx-plugin-targets": {
+      "executor": "@leyman/nx-plugin:targets",
+      "options": { "config": "tools/nx-plugin.json" }
+    }
+  }
+}
+```
+
+`config` is a file of the [options](#options), relative to the workspace root, which can name `./node_modules/@leyman/nx-plugin/out/schema.json` as its `$schema`. The executor writes the named inputs and target defaults into `nx.json`, keeping each target default's `dependsOn`, and into each `project.json` the targets the project gets, as `{}`. A declaration with options of its own is kept. With `check` (the default when `CI` is set), it fails instead of writing when a file is out of date.
+
+## API
+
+The plugin's pieces, for tools built on it:
+
+- `createNodes`, `name`: the Nx plugin.
+- `resolveOptions(options?)`: every option, with defaults.
+- `targetConfigurations(resolved)`, `namedInputs(resolved)`: each target's configuration and each named input.
+- `inferTargets(project, resolved)`: the targets a project gets, from `{ root, packageJson, isDependency, has(path) }`; `inferencePaths` are the paths `has` is asked about.
+- `loadProjects(workspaceRoot, roots)`: reads that for each project.
+- `syncTargets({ root, projects, options, optionsSource, check })`: what the executor does.
+- `initGenerator(tree, options?)`, `packageGenerator(tree, options)`: the generators. `lifecycleStages` and `lifecycleBindings` are the nx-lifecycle options `init` writes.
+- `readWorkspaceVersions(tree)`, `resolveVersion(name, versions)`: the version a generator gives a dependency.
+- `assertOptions(options, where)`, `optionsJsonSchema`, `executorJsonSchema`, `initGeneratorJsonSchema`, `packageGeneratorJsonSchema`: option validation and the JSON schemas.
+
+## Versioning
+
+Before 1.0, a release that can make a passing workspace fail (a new target inferred, a stricter command, a changed default) is a minor, and other changes are patches.

package/dist/executors/targets.d.ts

@@ -0,0 +1,30 @@
+import type { ExecutorContext } from '@nx/devkit';
+/**
+ * Where the plugin options are, and whether to only check them.
+ */
+export interface TargetsExecutorOptions {
+    /**
+     * Path of the file holding the plugin options, relative to the workspace root.
+     */
+    readonly config: string;
+    /**
+     * Fail rather than write when a file is out of date.
+     *
+     * @default true in CI (`CI` set to anything but `false` or `0`)
+     */
+    readonly check?: boolean;
+}
+/**
+ * Nx executor writing the plugin's named inputs and target defaults into `nx.json`, and the targets each project
+ * gets into its `project.json`, from the options in a file.
+ *
+ * @param options - where the plugin options are, and whether to only check
+ * @param context - Nx executor context
+ * @returns success, as failures reject
+ * @rejects {Error} when the options are invalid, or a file is out of date in `check` mode
+ */
+declare const targetsExecutor: (options: TargetsExecutorOptions, context: Pick<ExecutorContext, 'projectsConfigurations' | 'root'>) => Promise<{
+    success: boolean;
+}>;
+export default targetsExecutor;
+//# sourceMappingURL=targets.d.ts.map

package/dist/executors/targets.js

@@ -0,0 +1,31 @@
+import { readFile } from 'node:fs/promises';
+import Path from 'node:path';
+import { syncTargets } from '../lib/sync.js';
+const isCi = (ci)=>![
+        '',
+        '0',
+        'false',
+        undefined
+    ].includes(ci);
+const targetsExecutor = async (options, context)=>{
+    const config = Path.join(context.root, options.config);
+    const written = await syncTargets({
+        root: context.root,
+        projects: Object.entries(context.projectsConfigurations.projects).map(([name, { root }])=>({
+                name,
+                root
+            })),
+        options: JSON.parse(await readFile(config, 'utf8')),
+        optionsSource: options.config,
+        check: options.check ?? isCi(process.env.CI)
+    });
+    for (const path of written){
+        console.info(`Updated ${Path.relative(context.root, path)}`);
+    }
+    return {
+        success: true
+    };
+};
+export default targetsExecutor;
+
+//# sourceMappingURL=targets.js.map

package/dist/generators/init.d.ts

@@ -0,0 +1,82 @@
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+/**
+ * What the `init` generator sets up.
+ */
+export interface InitGeneratorOptions {
+    /**
+     * Wire the targets' order with nx-lifecycle.
+     *
+     * @default true
+     */
+    readonly lifecycle?: boolean;
+    /**
+     * Write a `.claude/skills/principles/SKILL.md` pointing coding agents at the principles behind the setup.
+     *
+     * @default true
+     */
+    readonly skill?: boolean;
+    /**
+     * Don't install dependencies afterwards.
+     *
+     * @default false
+     */
+    readonly skipInstall?: boolean;
+}
+/**
+ * The stages the plugin's targets run in, as nx-lifecycle options: install, prepare (generate, format), check (lint),
+ * build (run, post, sync), test (compile, run, report) and verify.
+ */
+export declare const lifecycleStages: {
+    readonly install: {
+        readonly dependsOn: readonly ['^build'];
+    };
+    readonly prepare: {
+        readonly hooks: readonly ['generate', 'format'];
+        readonly dependsOn: readonly ['install'];
+    };
+    readonly check: {
+        readonly hooks: readonly ['lint'];
+        readonly dependsOn: readonly ['^build', 'prepare', 'build'];
+    };
+    readonly build: {
+        readonly hooks: readonly ['run', 'post', 'sync'];
+        readonly dependsOn: readonly ['^build', 'prepare'];
+    };
+    readonly test: {
+        readonly hooks: readonly ['compile', 'run', 'report'];
+        readonly dependsOn: readonly ['build'];
+    };
+    readonly verify: {
+        readonly dependsOn: readonly ['check', 'test'];
+    };
+};
+/**
+ * The stage hook each of the plugin's targets is bound to.
+ */
+export declare const lifecycleBindings: {
+    readonly biome: 'prepare:format';
+    readonly eslint: 'check:lint';
+    readonly 'check-package': 'check:lint';
+    readonly 'update-ts-references': 'prepare:generate';
+    readonly tsc: 'build:run';
+    readonly 'tsc-test': 'test:compile';
+    readonly 'mocha-unit-test': 'test:run';
+    readonly 'mocha-integration-test': 'test:run';
+    readonly 'vitest-unit-test': 'test:run';
+    readonly 'coverage-report': 'test:report';
+    readonly 'sync-injected': 'build:sync';
+};
+/**
+ * Nx generator setting an Nx workspace up for the plugin: adds it (and nx-lifecycle, with stages and bindings for its
+ * targets) to `nx.json`, installs it and the tools its targets run at the root, extends the shared Biome config, has
+ * pnpm inject workspace packages, and points coding agents at the principles. Run by `nx add @leyman/nx-plugin`.
+ * Leaves alone what is already set.
+ *
+ * @param tree - Nx's view of the files
+ * @param options - what to set up
+ * @returns the task installing dependencies, unless `skipInstall`
+ * @rejects {Error} when the plugin's options in `nx.json` are invalid
+ */
+declare const initGenerator: (tree: Tree, options?: InitGeneratorOptions) => Promise<GeneratorCallback | undefined>;
+export default initGenerator;
+//# sourceMappingURL=init.d.ts.map

package/dist/generators/init.js

@@ -0,0 +1,190 @@
+import { installPackagesTask, readJson, readNxJson, writeJson } from '@nx/devkit';
+import { parse } from 'yaml';
+import { resolveOptions } from '../lib/options.js';
+import { name as pluginName } from '../lib/plugin.js';
+import { assertOptions } from '../lib/schema.js';
+import { readWorkspaceVersions, resolveVersion } from '../lib/versions.js';
+export const lifecycleStages = {
+    install: {
+        dependsOn: [
+            '^build'
+        ]
+    },
+    prepare: {
+        hooks: [
+            'generate',
+            'format'
+        ],
+        dependsOn: [
+            'install'
+        ]
+    },
+    check: {
+        hooks: [
+            'lint'
+        ],
+        dependsOn: [
+            '^build',
+            'prepare',
+            'build'
+        ]
+    },
+    build: {
+        hooks: [
+            'run',
+            'post',
+            'sync'
+        ],
+        dependsOn: [
+            '^build',
+            'prepare'
+        ]
+    },
+    test: {
+        hooks: [
+            'compile',
+            'run',
+            'report'
+        ],
+        dependsOn: [
+            'build'
+        ]
+    },
+    verify: {
+        dependsOn: [
+            'check',
+            'test'
+        ]
+    }
+};
+export const lifecycleBindings = {
+    biome: 'prepare:format',
+    eslint: 'check:lint',
+    'check-package': 'check:lint',
+    'update-ts-references': 'prepare:generate',
+    tsc: 'build:run',
+    'tsc-test': 'test:compile',
+    'mocha-unit-test': 'test:run',
+    'mocha-integration-test': 'test:run',
+    'vitest-unit-test': 'test:run',
+    'coverage-report': 'test:report',
+    'sync-injected': 'build:sync'
+};
+const lifecyclePlugin = 'nx-lifecycle/plugin';
+const rootDependencies = [
+    pluginName,
+    '@biomejs/biome',
+    '@leyman/check-package',
+    '@leyman/configs',
+    '@nx/js'
+];
+const principlesSkill = `---
+name: principles
+description: The principles behind this setup (the bar for packages, versioning, support floors, dependencies, lint, generated content, patches, and how work is committed and verified), and why
+---
+
+# Principles
+
+Read the [principles](https://jacobley.github.io/leyman/framework/principles) of the setup this workspace follows before a design, a review or an audit, and decide anything no other skill covers by them.
+`;
+const pluginOf = (entry)=>typeof entry === 'string' ? entry : entry.plugin;
+const injectSettings = `# Install workspace dependencies as copies of their published files, like a package from the registry.
+# Builds keep the copies current (\`sync-injected\`).
+injectWorkspacePackages: true
+`;
+const dedupeSettings = `# Otherwise pnpm symlinks to the source again whenever peers allow it
+dedupeInjectedDeps: false
+`;
+const injectWorkspacePackages = (tree)=>{
+    const yaml = tree.read('pnpm-workspace.yaml', 'utf8');
+    if (yaml === null) {
+        return;
+    }
+    const settings = parse(yaml) ?? {};
+    const added = [
+        ...Object.hasOwn(settings, 'injectWorkspacePackages') ? [] : [
+            injectSettings
+        ],
+        ...Object.hasOwn(settings, 'dedupeInjectedDeps') ? [] : [
+            dedupeSettings
+        ]
+    ];
+    if (added.length === 0) {
+        return;
+    }
+    const separator = yaml === '' || yaml.endsWith('\n') ? '' : '\n';
+    tree.write('pnpm-workspace.yaml', `${yaml}${separator}${added.join('')}`);
+};
+const initGenerator = async (tree, options = {})=>{
+    const { lifecycle = true, skill = true } = options;
+    const nxJson = readNxJson(tree) ?? {};
+    const plugins = [
+        ...nxJson.plugins ?? []
+    ];
+    const existing = plugins.find((entry)=>pluginOf(entry) === pluginName);
+    if (existing === undefined) {
+        plugins.push({
+            plugin: pluginName,
+            options: {}
+        });
+    }
+    const pluginOptions = typeof existing === 'object' ? existing.options ?? {} : {};
+    assertOptions(pluginOptions, 'nx.json');
+    const resolved = resolveOptions(pluginOptions);
+    if (lifecycle && plugins.every((entry)=>pluginOf(entry) !== lifecyclePlugin)) {
+        const bindings = Object.entries(lifecycleBindings).flatMap(([target, hook])=>{
+            const targetOptions = resolved.targets[target];
+            return targetOptions === false ? [] : [
+                [
+                    targetOptions.name,
+                    hook
+                ]
+            ];
+        });
+        plugins.push({
+            plugin: lifecyclePlugin,
+            options: {
+                stages: lifecycleStages,
+                bindings: Object.fromEntries(bindings)
+            }
+        });
+    }
+    writeJson(tree, 'nx.json', {
+        ...nxJson,
+        plugins
+    });
+    const versions = await readWorkspaceVersions(tree);
+    const packageJson = readJson(tree, 'package.json');
+    const devDependencies = {
+        ...packageJson.devDependencies
+    };
+    for (const dependency of [
+        ...rootDependencies,
+        ...lifecycle ? [
+            'nx-lifecycle'
+        ] : []
+    ]){
+        devDependencies[dependency] ??= resolveVersion(dependency, versions);
+    }
+    writeJson(tree, 'package.json', {
+        ...packageJson,
+        devDependencies
+    });
+    if (!tree.exists('biome.json') && !tree.exists('biome.jsonc')) {
+        writeJson(tree, 'biome.json', {
+            $schema: './node_modules/@biomejs/biome/configuration_schema.json',
+            extends: [
+                '@leyman/configs/biome.base.json'
+            ]
+        });
+    }
+    injectWorkspacePackages(tree);
+    const skillPath = '.claude/skills/principles/SKILL.md';
+    if (skill && !tree.exists(skillPath)) {
+        tree.write(skillPath, principlesSkill);
+    }
+    return options.skipInstall === true ? undefined : installPackagesTask.bind(undefined, tree);
+};
+export default initGenerator;
+
+//# sourceMappingURL=init.js.map

package/dist/generators/package.d.ts

@@ -0,0 +1,79 @@
+import type { GeneratorCallback, Tree } from '@nx/devkit';
+/**
+ * What the `package` generator adds, and where.
+ */
+export interface PackageGeneratorOptions {
+    /**
+     * Where the package goes, relative to the workspace root, e.g. `packages/my-lib`.
+     */
+    readonly directory: string;
+    /**
+     * A placeholder export, for the first test to import until the package has an API.
+     *
+     * @default the directory's last segment
+     */
+    readonly name?: string;
+    /**
+     * Description, for `package.json` and the README.
+     */
+    readonly description: string;
+    /**
+     * Published to npm, rather than private.
+     *
+     * @default false
+     */
+    readonly published?: boolean;
+    /**
+     * Major of the oldest Node.js a published package supports.
+     *
+     * @default 22
+     */
+    readonly floor?: number;
+    /**
+     * Test runner, or `none` for no tests.
+     *
+     * @default 'mocha'
+     */
+    readonly test?: 'mocha' | 'none' | 'vitest';
+    /**
+     * URL of the workspace's GitHub repository, for a published package's `repository`, `homepage` and `bugs`.
+     */
+    readonly repository?: string;
+    /**
+     * `author` of `package.json`.
+     */
+    readonly author?: string;
+    /**
+     * `license` of `package.json`. A published package also gets a copy of the workspace's `LICENSE`.
+     */
+    readonly license?: string;
+    /**
+     * More packages to add to `devDependencies`.
+     */
+    readonly devDependencies?: readonly string[];
+    /**
+     * File of the plugin options, relative to the workspace root, for a workspace running the `targets` executor.
+     *
+     * @default the options of the plugin in `nx.json`
+     */
+    readonly config?: string;
+    /**
+     * Don't install dependencies afterwards.
+     *
+     * @default false
+     */
+    readonly skipInstall?: boolean;
+}
+/**
+ * Nx generator adding a TypeScript ESM package: its `package.json`, configs, a first source file and test, and a
+ * `project.json` declaring the targets the plugin infers from them.
+ *
+ * @param tree - the workspace
+ * @param options - what to add
+ * @returns the task installing dependencies, unless `skipInstall`
+ * @rejects {Error} when the directory already holds a package, the plugin options are invalid, or a dependency has
+ * no version in the workspace
+ */
+declare const packageGenerator: (tree: Tree, options: PackageGeneratorOptions) => Promise<GeneratorCallback | undefined>;
+export default packageGenerator;
+//# sourceMappingURL=package.d.ts.map