@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/src/commands/init-wizard.ts

@@ -55,8 +55,9 @@
  */
 
 import * as path from 'node:path';
-import { DEFAULT_INIT_HEADS, INIT_HEADS, type InitHead, isNonEmptyDir, kebab } from './init.js';
-import { InitWizardCancelled, OPTIONAL_HEAD_CHOICES, type PromptPort } from './init-prompt.js';
+import { DEFAULT_INIT_HEADS, INIT_HEADS, type InitHead, isNonEmptyDir, isUsableExtension, memberPlacements } from './init.js';
+import { kebab } from './kebab.js';
+import { HEAD_CHOICES, InitWizardCancelled, type PromptPort } from './init-prompt.js';
 import { type WorkspaceDetection } from './init-workspace.js';
 
 /** One grammar as the wizard collected it. */
@@ -158,13 +159,13 @@ export function formatCommand(argv: readonly string[]): string {
 /** Validate a file extension, and reject one another grammar already claims. */
 function extensionProblem(value: string, taken: ReadonlySet<string>): string | undefined {
    const extension = value.replace(/^\./, '');
-   if (!/^[A-Za-z0-9][A-Za-z0-9-]*$/.test(extension)) {
+   if (!isUsableExtension(extension)) {
       return `'${value}' is not a usable file extension.`;
    }
    // Checked here rather than left to the scaffolder so the answer is corrected
    // while the grammar that owns it is still on screen. Langium routes documents
    // to a language BY extension, so a duplicate is a silent mis-route.
-   return taken.has(extension) ? `'.${extension}' is already claimed by another grammar.` : undefined;
+   return taken.has(extension.toLowerCase()) ? `'.${extension}' is already claimed by another grammar.` : undefined;
 }
 
 /**
@@ -198,31 +199,19 @@ async function askGrammar(
    return { name, extension: extension.replace(/^\./, ''), diagram: false };
 }
 
-/**
- * Ask for the protocol head set.
- *
- * `lsp` is not offered, it is stated: it owns the workspace, the build pipeline
- * and the shared tier the other heads read through, so a project without it has
- * nothing for them to serve. Presenting it as a checkbox would offer a choice
- * the scaffolder then refuses.
- */
+/** Ask for the protocol head set, in composition order whatever order they were picked in. */
 async function askHeads(prompt: PromptPort): Promise<InitHead[]> {
-   const optional = await prompt.multiselect({
-      message: 'Protocol heads — lsp is always included',
-      choices: OPTIONAL_HEAD_CHOICES,
-      initialValues: DEFAULT_INIT_HEADS.filter((head): head is Exclude<InitHead, 'lsp'> => head !== 'lsp')
-   });
-   const chosen = new Set<InitHead>(['lsp', ...optional]);
-   return INIT_HEADS.filter(head => chosen.has(head));
+   const chosen = await prompt.multiselect({ message: 'Protocol heads', choices: HEAD_CHOICES, initialValues: DEFAULT_INIT_HEADS });
+   return INIT_HEADS.filter(head => chosen.includes(head));
 }
 
 /**
  * Mark the grammar a scaffolded diagram edits.
  *
- * Only a real question with `glsp` on AND several grammars: a diagram type
- * binds exactly ONE grammar, and with a single grammar the scaffolder derives
- * that answer already — so asking would offer a choice whose "no" it would
- * silently overrule.
+ * Only a real question with `glsp` on AND several grammars: the scaffolded
+ * diagram is typed over one grammar's model, and with a single grammar the
+ * scaffolder derives that answer already — so asking would offer a choice
+ * whose "no" it would silently overrule.
  */
 async function askDiagramGrammar(
    prompt: PromptPort,
@@ -268,10 +257,11 @@ async function askWorkspaceMembership(
    if (detection === undefined) {
       return { monorepo: false };
    }
+   const uncovered = memberPlacements(detection).filter(placement => placement.coveredBy === undefined);
    const covered =
-      detection.coveredBy === undefined
-         ? `The root manifest has no entry covering it, so one is printed for you to add.`
-         : `Already covered by the "${detection.coveredBy}" workspaces entry.`;
+      uncovered.length === 0
+         ? 'Its packages are already covered by the workspaces entries.'
+         : `The root manifest has no entry covering ${uncovered.map(placement => placement.path).join(', ')}, so ${uncovered.length === 1 ? 'one is' : 'they are'} printed for you to add.`;
    // The placement is named, not just the root. The root alone reads as "this
    // ran somewhere I did not ask for" whenever the command was issued from a
    // different directory than the target, which is the normal case.
@@ -364,7 +354,7 @@ export async function runInitWizard(
       const grammar = await askGrammar(prompt, grammars.length, grammars.length === 0 ? name : undefined, takenNames, takenExtensions);
       grammars.push(grammar);
       takenNames.add(grammar.name);
-      takenExtensions.add(grammar.extension);
+      takenExtensions.add(grammar.extension.toLowerCase());
    } while (await prompt.confirm({ message: 'Add another grammar?', initialValue: false }));
 
    const withDiagram = await askDiagramGrammar(prompt, heads, grammars);

package/src/commands/init-workspace.ts

@@ -169,14 +169,6 @@ export interface WorkspaceDetection {
    readonly workspaces: readonly string[];
    /** POSIX path of the target relative to {@link rootDir}, e.g. `packages/foo`. */
    readonly targetPath: string;
-   /**
-    * The `workspaces` glob already covering {@link targetPath}, if any.
-    *
-    * Absent means the root manifest needs a new entry — which is why this is
-    * computed per target rather than assumed: a `packages/*` glob covers a new
-    * package for free, while a repo that lists its examples one by one does not.
-    */
-   readonly coveredBy?: string;
    /** The npm scope the sibling packages agree on (`@acme`), when they agree. */
    readonly scope?: string;
    /**
@@ -186,10 +178,14 @@ export interface WorkspaceDetection {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can drop what it inherits. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The root prettier config's `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The root formatter config's `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the root eslint config, when there is one. Absent means the repo does not lint. */
    readonly eslintConfig?: string;
+   /** Filename of the root Oxlint config, when present. */
+   readonly oxlintConfig?: string;
+   /** The npm version the root's `packageManager` field declares, when it names npm. */
+   readonly packageManagerNpm?: string;
 }
 
 /**
@@ -339,7 +335,7 @@ export function findBaseTsconfig(
 }
 
 /**
- * The repo's prettier `printWidth`, so the emitted sources wrap where the repo
+ * The repo's formatter `printWidth`, so the emitted sources wrap where the repo
  * wraps instead of at the scaffold's own default.
  *
  * **Why this is worth detecting at all.** There is no width that is stable for
@@ -360,19 +356,21 @@ export function findBaseTsconfig(
  * adopter's formatter rewraps on first commit. So a heuristic that is usually
  * right strictly improves on no detection, and can break nothing.
  */
-export function findPrettierPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
+export function findFormatterPrintWidth(rootDir: string, probe: WorkspaceProbe): number | undefined {
    const manifest = probe.readJson(path.join(rootDir, 'package.json'));
    if (isJsonObject(manifest) && isJsonObject(manifest.prettier) && typeof manifest.prettier.printWidth === 'number') {
       return manifest.prettier.printWidth;
    }
    const present = probe.listFiles(rootDir);
-   for (const file of present.filter(name => name === '.prettierrc' || name === '.prettierrc.json')) {
+   for (const file of present.filter(name => name === '.oxfmtrc.json' || name === '.prettierrc' || name === '.prettierrc.json')) {
       const parsed = probe.readJson(path.join(rootDir, file));
       if (isJsonObject(parsed) && typeof parsed.printWidth === 'number') {
          return parsed.printWidth;
       }
    }
-   for (const file of present.filter(name => /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s)$/.test(name))) {
+   for (const file of present.filter(name =>
+      /^(\.prettierrc\.[cm]?[jt]s|prettier\.config\.[cm]?[jt]s|oxfmt\.config\.[cm]?[jt]s)$/.test(name)
+   )) {
       const width = /\bprintWidth\s*:\s*(\d+)/.exec(probe.readText(path.join(rootDir, file)) ?? '');
       if (width) {
          return Number(width[1]);
@@ -398,6 +396,22 @@ export function findEslintConfig(rootDir: string, probe: WorkspaceProbe): string
    return probe.listFiles(rootDir).find(name => /^eslint\.config\.[cm]?[jt]s$/.test(name) || /^\.eslintrc(\..+)?$/.test(name));
 }
 
+/** Detect Oxlint without evaluating executable configuration files. */
+export function findOxlintConfig(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   return probe.listFiles(rootDir).find(name => /^(oxlint\.config\.[cm]?[jt]s|\.oxlintrc\.jsonc?)$/.test(name));
+}
+
+/** The npm version the root's `packageManager` field declares (`npm@11.15.0` gives `11.15.0`), when it names npm. */
+export function findPackageManagerNpm(rootDir: string, probe: WorkspaceProbe): string | undefined {
+   const manifest = probe.readJson(path.join(rootDir, 'package.json'));
+   return parseNpmVersion(isJsonObject(manifest) && typeof manifest.packageManager === 'string' ? manifest.packageManager : undefined);
+}
+
+/** The npm version, prerelease included, of a `packageManager` field (`npm@…`) or a user agent (`npm/…`); undefined for another tool. */
+export function parseNpmVersion(spec: string | undefined): string | undefined {
+   return /^npm[@/](\d+\.\d+\.\d+(?:-[\w.]+)?)/.exec(spec ?? '')?.[1];
+}
+
 /** POSIX-style relative path, which is what both `extends` and `--prefix` want on every platform. */
 function posixRelative(from: string, to: string): string {
    return path.relative(from, to).split(path.sep).join('/');
@@ -432,11 +446,12 @@ export function detectWorkspace(targetDir: string, probe: WorkspaceProbe): Works
       rootDir,
       workspaces,
       targetPath,
-      coveredBy: workspaces.find(glob => workspaceGlobCovers(glob, targetPath)),
       scope: inferPackageScope(rootDir, workspaces, probe),
       baseTsconfig: base && posixRelative(absoluteTarget, path.join(rootDir, base.file)),
       baseCompilerOptions: base?.compilerOptions,
-      printWidth: findPrettierPrintWidth(rootDir, probe),
-      eslintConfig: findEslintConfig(rootDir, probe)
+      printWidth: findFormatterPrintWidth(rootDir, probe),
+      eslintConfig: findEslintConfig(rootDir, probe),
+      oxlintConfig: findOxlintConfig(rootDir, probe),
+      packageManagerNpm: findPackageManagerNpm(rootDir, probe)
    };
 }

package/src/commands/init.ts

@@ -9,15 +9,21 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { buildInitTemplates, readFrameworkVersion, UNPUBLISHED_FRAMEWORK_VERSION } from './init-templates.js';
-import { createNodeWorkspaceProbe, detectWorkspace, type JsonValue, type WorkspaceProbe } from './init-workspace.js';
+import { buildInitTemplates, readFrameworkVersion, workspaceRootPins } from './init-templates.js';
+import { kebab } from './kebab.js';
+import {
+   createNodeWorkspaceProbe,
+   detectWorkspace,
+   parseNpmVersion,
+   workspaceGlobCovers,
+   type JsonValue,
+   type WorkspaceDetection,
+   type WorkspaceProbe
+} from './init-workspace.js';
 
 /**
- * The protocol heads a scaffold can start, in composition order.
- *
- * `lsp` is mandatory rather than optional: it owns the workspace, the build
- * pipeline and the shared service tier every other head reads through, so a
- * project without it has nothing for `data` or `glsp` to serve.
+ * The protocol heads a scaffold can start, in composition order. Any non-empty
+ * set: without `lsp`, the socket heads bring the workspace up themselves.
  */
 export const INIT_HEADS = ['lsp', 'data', 'glsp'] as const;
 
@@ -27,6 +33,35 @@ export type InitHead = (typeof INIT_HEADS)[number];
 /** The heads a scaffold emits when `--heads` is not given. */
 export const DEFAULT_INIT_HEADS: readonly InitHead[] = ['lsp', 'data'];
 
+/**
+ * The library packages of a scaffolded project, each in the directory of its
+ * name, in the order a workspace lists them.
+ */
+export const INIT_MEMBERS = ['protocol', 'server'] as const;
+
+/** One library member — see {@link INIT_MEMBERS}. */
+export type InitMember = (typeof INIT_MEMBERS)[number];
+
+/** A member's path relative to the workspace root, and the `workspaces` entry already covering it. */
+export interface InitMemberPlacement {
+   readonly path: string;
+   readonly coveredBy?: string;
+}
+
+/**
+ * Where each member lands in a detected workspace.
+ *
+ * Judged per member rather than for the project directory, which holds no
+ * package: a root listing its members one by one needs an entry for each,
+ * while a `packages/*` glob covers none of them one level deeper.
+ */
+export function memberPlacements(detection: WorkspaceDetection): readonly InitMemberPlacement[] {
+   return INIT_MEMBERS.map(member => {
+      const memberPath = `${detection.targetPath}/${member}`;
+      return { path: memberPath, coveredBy: detection.workspaces.find(glob => workspaceGlobCovers(glob, memberPath)) };
+   });
+}
+
 /** True for a string naming one of {@link INIT_HEADS}. */
 export function isInitHead(value: string): value is InitHead {
    return (INIT_HEADS as readonly string[]).includes(value);
@@ -55,10 +90,9 @@ export interface InitGrammarSpec {
    /**
     * Scaffold a GLSP diagram for this grammar. Requires the `glsp` head.
     *
-    * Per grammar rather than per project because
-    * `AbstractHydraniumGlspDiagramModule.declareLanguage()` returns ONE grammar's
-    * `LanguageMetaData` — a diagram type has exactly one grammar, and a grammar
-    * with no diagram sitting on the same server is the normal case.
+    * Per grammar rather than per project because the scaffolded diagram is typed
+    * over one grammar's model, and a grammar with no diagram sitting on the same
+    * server is the normal case.
     */
    readonly diagram?: boolean;
 }
@@ -128,10 +162,16 @@ export interface InitWorkspacePlacement {
    readonly baseTsconfig?: string;
    /** That tsconfig's `compilerOptions`, so the emitted one can omit what it would inherit unchanged. */
    readonly baseCompilerOptions?: Readonly<Record<string, JsonValue>>;
-   /** The workspace's prettier `printWidth`, so emitted sources wrap where the repo wraps. */
+   /** The workspace's formatter `printWidth`, so emitted sources wrap where the repo wraps. */
    readonly printWidth?: number;
    /** Filename of the workspace's eslint config; its presence is what makes the scaffold emit a `lint` script. */
    readonly eslintConfig?: string;
+   /** Filename of the workspace Oxlint config, when present. */
+   readonly oxlintConfig?: string;
+   /** The npm version the workspace root's `packageManager` declares; with {@link npmVersion} it decides the scaffold's `vitest` range. */
+   readonly packageManagerNpm?: string;
+   /** The npm running `init`, when known. npm does not enforce `packageManager`, so a declaration alone cannot lift `vitest`. */
+   readonly npmVersion?: string;
 }
 
 /**
@@ -185,7 +225,7 @@ export interface InitComposition {
     * one data server per project, not one per language).
     */
    readonly projectId: string;
-   /** The protocol heads to start, always including `lsp`. */
+   /** The protocol heads to start, at least one. */
    readonly heads: readonly InitHead[];
    /** The grammars, in the order given. The first is the configuration root. */
    readonly grammars: readonly InitGrammarNames[];
@@ -226,10 +266,9 @@ export interface InitCommandOptions {
    readonly force?: boolean;
    /**
     * Scaffold a member of the surrounding npm workspace: extend its base
-    * tsconfig, leave `.gitignore` to the root, and address the package by
-    * `--prefix` in the scripts it prints back at itself. Errors when no ancestor
-    * declares `workspaces`, rather than silently degrading to a standalone
-    * project the caller did not ask for.
+    * tsconfig and address the package by `--prefix` in the scripts it prints
+    * back at itself. Errors when no ancestor declares `workspaces`, rather than
+    * silently degrading to a standalone project the caller did not ask for.
     */
    readonly monorepo?: boolean;
    /** npm scope for the package name, e.g. `@acme`. */
@@ -244,21 +283,26 @@ export interface InitCommandOptions {
    readonly __writeFilesForTest?: (targetDir: string, files: readonly InitFile[]) => void;
 }
 
-/** Kebab-case a PascalCase/camelCase name. */
-export function kebab(name: string): string {
-   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
-}
-
 /** True for a PascalCase identifier legal as a generated TypeScript symbol prefix. */
 function isPascalIdentifier(value: string): boolean {
    return /^[A-Za-z][A-Za-z0-9]*$/.test(value);
 }
 
-/** Strip a leading dot and reject an extension that is empty or dotted through. */
+/**
+ * True for a file extension, without its leading dot, that is safe in an
+ * emitted file name and string literal: letters, digits and dashes.
+ */
+export function isUsableExtension(extension: string): boolean {
+   return /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(extension);
+}
+
+/** Strip a leading dot and reject an extension {@link isUsableExtension} refuses. */
 function normalizeExtension(value: string, grammar: string): string {
    const extension = value.replace(/^\./, '');
-   if (extension.length === 0) {
-      throw new Error(`Invalid extension '${value}' for grammar '${grammar}': an extension cannot be empty.`);
+   if (!isUsableExtension(extension)) {
+      throw new Error(
+         `Invalid extension '${value}' for grammar '${grammar}': use letters, digits and dashes, starting with a letter or digit.`
+      );
    }
    return extension;
 }
@@ -282,6 +326,11 @@ function resolveGrammar(spec: InitGrammarSpec, projectId: string, qualify: boole
    if (extensions.length === 0) {
       throw new Error(`Invalid --extensions for grammar '${spec.name}': at least one extension is required.`);
    }
+   if (spec.languageId !== undefined && !/^[a-z0-9][a-z0-9-]*$/.test(spec.languageId)) {
+      throw new Error(
+         `Invalid --language-id '${spec.languageId}' for grammar '${spec.name}': use lowercase letters, digits and dashes, e.g. 'my-lang'.`
+      );
+   }
    return {
       grammar: spec.name,
       grammarId,
@@ -298,8 +347,9 @@ function resolveGrammar(spec: InitGrammarSpec, projectId: string, qualify: boole
  *
  * With the `glsp` head on and nothing marked, a lone grammar is unambiguous and
  * is taken as the diagram's; with several it is a real choice, so it is required
- * rather than guessed — binding a diagram to the wrong grammar surfaces much
- * later as references resolving against the wrong scope.
+ * rather than guessed — the scaffolded state, storage and GModel factory are
+ * typed over the chosen grammar's model, so a wrong guess emits a diagram of
+ * the wrong model.
  */
 function resolveDiagrams(specs: readonly InitGrammarSpec[], heads: readonly InitHead[]): boolean[] {
    const marked = specs.map(spec => spec.diagram === true);
@@ -325,18 +375,13 @@ function resolveDiagrams(specs: readonly InitGrammarSpec[], heads: readonly Init
    );
 }
 
-/** Validate the head set: known names only, and `lsp` present. */
+/** Validate the head set: known names only. */
 function resolveHeads(heads: readonly InitHead[] | undefined): readonly InitHead[] {
    const resolved = heads === undefined || heads.length === 0 ? DEFAULT_INIT_HEADS : heads;
    const unknown = resolved.filter(head => !isInitHead(head));
    if (unknown.length > 0) {
       throw new Error(`Unknown head(s) '${unknown.join(', ')}': expected one of ${INIT_HEADS.join(', ')}.`);
    }
-   if (!resolved.includes('lsp')) {
-      throw new Error(
-         "--heads must include 'lsp': it owns the workspace, the build pipeline and the shared service tier the other heads read through."
-      );
-   }
    // De-duplicated and put back in composition order, so the order the heads
    // were named in does not change the emitted project.
    return INIT_HEADS.filter(head => resolved.includes(head));
@@ -368,15 +413,18 @@ function assertNoCollisions(grammars: readonly InitGrammarNames[]): void {
       }
       byLanguageId.set(grammar.languageId, grammar.grammar);
 
+      // Case-folded: a starter file is named by extension, and `nodes.Foo` and
+      // `nodes.foo` are one file on a case-insensitive file system.
       for (const extension of grammar.extensions) {
-         const clashingExtension = byExtension.get(extension);
+         const key = extension.toLowerCase();
+         const clashingExtension = byExtension.get(key);
          if (clashingExtension !== undefined) {
             throw new Error(
                `File extension '.${extension}' is claimed by both '${clashingExtension}' and '${grammar.grammar}'. ` +
                   'Langium routes documents by extension, so each grammar needs its own.'
             );
          }
-         byExtension.set(extension, grammar.grammar);
+         byExtension.set(key, grammar.grammar);
       }
    }
 }
@@ -432,6 +480,8 @@ export interface InitPackagingOptions {
    readonly scope?: string;
    readonly public?: boolean;
    readonly probe?: WorkspaceProbe;
+   /** The npm running `init`. Defaults to the one `npm_config_user_agent` names, which `npx` and `npm run` set. */
+   readonly npmVersion?: string;
 }
 
 /**
@@ -466,7 +516,10 @@ export function resolveInitPackaging(targetDir: string, options: InitPackagingOp
          baseTsconfig: detection.baseTsconfig,
          baseCompilerOptions: detection.baseCompilerOptions,
          printWidth: detection.printWidth,
-         eslintConfig: detection.eslintConfig
+         eslintConfig: detection.eslintConfig,
+         oxlintConfig: detection.oxlintConfig,
+         packageManagerNpm: detection.packageManagerNpm,
+         npmVersion: options.npmVersion ?? parseNpmVersion(process.env.npm_config_user_agent)
       }
    };
 }
@@ -509,45 +562,60 @@ export function runInit(options: InitCommandOptions): void {
       write('\n');
       write(`Workspace root: ${detection.rootDir}\n`);
       if (detection.baseTsconfig !== undefined) {
-         write(`  tsconfig.json extends ${detection.baseTsconfig}, minus the options it inherits unchanged.\n`);
+         write(
+            `  Each package's tsconfig.json extends the root's ${path.posix.basename(detection.baseTsconfig)}, minus the options it inherits unchanged.\n`
+         );
       } else {
-         write('  No root tsconfig carries compilerOptions, so the emitted one stands alone.\n');
+         write("  No root tsconfig carries compilerOptions, so each package's stands alone.\n");
       }
-      write("  .gitignore holds `syntaxes/` only — the workspace root's covers the rest.\n");
       if (detection.printWidth !== undefined) {
-         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s prettier config.\n`);
+         write(`  Sources wrapped at ${detection.printWidth} columns, from ${detection.rootDir}'s formatter config.\n`);
       }
-      if (detection.eslintConfig !== undefined) {
-         write(`  A lint script was added — ${detection.eslintConfig} says this repo lints. Adjust it if your invocation differs.\n`);
+      if (detection.oxlintConfig !== undefined || detection.eslintConfig !== undefined) {
+         write(
+            `  Each package got a lint script — ${detection.oxlintConfig ?? detection.eslintConfig} says this repo lints. Adjust them if your invocation differs.\n`
+         );
       }
       // Printed rather than applied: `init` writes inside the target directory
       // and nowhere else, so a scaffold can never surprise-edit a manifest that
       // is under review, mid-rebase, or simply not the caller's to change.
-      if (detection.coveredBy === undefined) {
-         write(`  Add this to "workspaces" in ${path.join(detection.rootDir, 'package.json')}:\n`);
-         write(`    "${detection.targetPath}"\n`);
-      } else {
-         write(`  Already covered by the "${detection.coveredBy}" workspaces entry — no root manifest change needed.\n`);
+      const placements = memberPlacements(detection);
+      const uncovered = placements.filter(placement => placement.coveredBy === undefined);
+      if (uncovered.length > 0) {
+         write(`  Add ${uncovered.length === 1 ? 'this' : 'these'} to "workspaces" in ${path.join(detection.rootDir, 'package.json')}:\n`);
+         write(`${uncovered.map(placement => `    "${placement.path}"`).join(',\n')}\n`);
+      }
+      for (const placement of placements.filter(candidate => candidate.coveredBy !== undefined)) {
+         write(`  ${placement.path} is already covered by the "${placement.coveredBy}" workspaces entry.\n`);
       }
+      const pins = workspaceRootPins(composition.heads).map(([name, version]) => `    "${name}": "${version}"`);
+      write(
+         `  Add these to "devDependencies" in ${path.join(detection.rootDir, 'package.json')}, so another member's version of one ` +
+            `cannot displace the copy these packages share with the framework:\n${pins.join(',\n')}\n`
+      );
       if (composition.packaging.scope === undefined && detection.scope !== undefined) {
          write(`  Sibling packages all use the "${detection.scope}" scope; pass --scope ${detection.scope} to match them.\n`);
       }
    }
    write('\n');
    write('Next steps:\n');
-   write(`  cd ${options.targetDir}\n`);
-   // The warning is conditional on the pins this scaffold actually carries — see
-   // `UNPUBLISHED_FRAMEWORK_VERSION`.
-   write(
-      composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-         ? '  npm install              # 404s until @hydranium/* is published — see README\n'
-         : '  npm install\n'
-   );
-   write('  npm run build            # langium generate + tsc\n');
-   write('  npm test                 # the scaffolded DI-composition test\n');
+   // A workspace member's project has no manifest of its own, so its steps run
+   // from the workspace root and name the server by `--prefix`.
+   const server = detection === undefined ? 'server' : `${detection.targetPath}/server`;
+   if (detection === undefined) {
+      write(`  cd ${options.targetDir}\n`);
+      write('  npm install\n');
+      write('  npm run build            # langium generate + tsc, every package\n');
+      write('  npm test                 # the server tests\n');
+   } else {
+      write(`  cd ${detection.rootDir}\n`);
+      write('  npm install\n');
+      write(`  npm --prefix ${server} run build   # langium generate + tsc, protocol included\n`);
+      write(`  npm --prefix ${server} test\n`);
+   }
    // `npx`, not a bare invocation: `@hydranium/cli` is a devDependency of the
    // scaffold, so the binary is on PATH inside an npm script and nowhere else.
-   write('  npx hydranium-cli reflect --services ./lib/services.js\n');
+   write(`  npx hydranium-cli reflect --services ./${server}/lib/node/services.js\n`);
    write('\n');
    write('The emitted sources carry no license header — run your own header tool if\n');
    write('your repo gates them. See the README section on that.\n');

package/src/commands/kebab.ts

@@ -0,0 +1,17 @@
+/********************************************************************************
+ * Copyright (c) 2026 EclipseSource and others.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the MIT License which is available in the project root.
+ *
+ * SPDX-License-Identifier: MIT
+ ********************************************************************************/
+
+/**
+ * Kebab-case a PascalCase/camelCase name. Shared by `init`, which derives a
+ * grammar's id from it, and the languages emitter, whose constant names have
+ * to split a grammar name the same way.
+ */
+export function kebab(name: string): string {
+   return name.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+}

package/src/commands/lint-grammar-args.ts

@@ -9,34 +9,36 @@
 
 import {
    exitWithUsage,
+   HARNESS_VALUE_FLAGS,
    helpRequested,
-   LOG_LEVEL_FLAG,
-   logLevelHelpLine,
-   logLevelOption,
+   importHelpLines,
+   LOG_VALUE_FLAGS,
+   logHelpLines,
+   logOptions,
    parseHarnessArgs,
    printHelp,
-   SERVICES_FLAG,
    type UsageError
 } from './harness-args.js';
 import { runLintGrammar, type LintGrammarCommandOptions } from './lint-grammar.js';
 
-const VALUE_FLAGS = [LOG_LEVEL_FLAG] as const;
+const VALUE_FLAGS = [...LOG_VALUE_FLAGS] as const;
 const BOOL_FLAGS = ['--strict', '--json'] as const;
 const REPEATABLE_VALUE_FLAGS = ['--name-property'] as const;
 
 /**
  * Every flag `lint-grammar` accepts, derived from the sets the parser is handed
- * so the list cannot claim a flag the parser would reject. `--services` is
- * consumed by the shared harness parser itself, so it is in neither set.
+ * so the list cannot claim a flag the parser would reject.
+ * {@link HARNESS_VALUE_FLAGS} are consumed by the shared harness parser itself,
+ * so they are in neither set.
  */
-export const LINT_GRAMMAR_FLAGS: readonly string[] = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
+export const LINT_GRAMMAR_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS, ...BOOL_FLAGS];
 
 /** The subset that takes a value, so `--help` in a value position reads as data. */
-export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [SERVICES_FLAG, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS];
+export const LINT_GRAMMAR_VALUE_FLAGS: readonly string[] = [...HARNESS_VALUE_FLAGS, ...REPEATABLE_VALUE_FLAGS, ...VALUE_FLAGS];
 
 /** The `--help` text, as data, held to {@link LINT_GRAMMAR_FLAGS} by a test. */
 export const LINT_GRAMMAR_HELP: readonly string[] = [
-   'Usage: hydranium-cli lint-grammar --services <module> [--name-property <p>]... [--strict] [--json] [--log-level <lvl>]',
+   'Usage: hydranium-cli lint-grammar --services <module> [--import <specifier>]... [--name-property <p>]... [--strict] [--json] [--log-level <lvl>] [--log-file <file>] [--log-file-level <lvl>]',
    '',
    "Check a head's grammar against the framework's conventions — a CI gate: the",
    'process exits non-zero when a violation is found. Read-only: no workspace is',
@@ -48,25 +50,27 @@ export const LINT_GRAMMAR_HELP: readonly string[] = [
    '',
    'Options:',
    '  --services <module>    ESM module exporting `createServices(): { shared }` (required).',
+   ...importHelpLines(23),
    '  --name-property <p>    Property that satisfies the nameability convention',
    '                         (repeatable). Default: name.',
    '  --strict               Also fail (non-zero exit) on warnings, not only errors.',
    '  --json                 Emit the raw JSON result instead of the human report.',
-   logLevelHelpLine(23)
+   ...logHelpLines(23)
 ];
 
 export function parseLintGrammarArgs(args: string[], onError: UsageError = exitWithUsage): LintGrammarCommandOptions {
-   const { servicesModule, options, values } = parseHarnessArgs(args, 'lint-grammar', VALUE_FLAGS, BOOL_FLAGS, {
+   const { servicesModule, imports, options, values } = parseHarnessArgs(args, 'lint-grammar', VALUE_FLAGS, BOOL_FLAGS, {
       requireWorkspace: false,
       repeatableValueFlags: REPEATABLE_VALUE_FLAGS,
       onError
    });
    return {
       servicesModule,
+      imports,
       nameProperties: values['--name-property'],
       strict: options['--strict'] === 'true',
       json: options['--json'] === 'true',
-      logLevel: logLevelOption(options[LOG_LEVEL_FLAG])
+      ...logOptions(options)
    };
 }
 

package/src/commands/lint-grammar-driver.ts

@@ -16,6 +16,7 @@
  * only spawned.
  */
 
+import { describeError } from '@hydranium/protocol';
 import { loadHeadlessContext } from './headless-harness.js';
 import { formatLintReport, lintExitCode } from './lint-grammar-report.js';
 
@@ -78,6 +79,6 @@ async function main(argv: string[]): Promise<number> {
 main(process.argv.slice(2))
    .then(code => process.exit(code))
    .catch((error: unknown) => {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(describeError(error));
       process.exit(1);
    });

package/src/commands/lint-grammar.ts

@@ -53,5 +53,5 @@ export function buildLintGrammarDriverArgs(options: LintGrammarCommandOptions):
  * `createServices` module, keeping the binary language-agnostic.
  */
 export function runLintGrammar(options: LintGrammarCommandOptions): Promise<void> {
-   return runDriverChild(['--max-old-space-size=8192', DRIVER, ...buildLintGrammarDriverArgs(options)], options);
+   return runDriverChild([DRIVER, ...buildLintGrammarDriverArgs(options)], options);
 }