@hydranium/cli 1.0.0-next.38 → 1.0.0-next.380

package/src/commands/init.ts

@@ -7,17 +7,26 @@
  * SPDX-License-Identifier: MIT
  ********************************************************************************/
 
+import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
+import { createRequire } from 'node:module';
 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 { editingHeads, INIT_HOSTS, type InitHost, isInitHost, isTheiaHost } from './init-hosts.js';
+import { buildInitTemplates, readFrameworkVersion, SCAFFOLD_NODE_MAJOR, 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 +36,48 @@ 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'];
 
+/** One package of a scaffolded project, in the directory of its name — see {@link initMembers}. */
+export type InitMember = 'protocol' | 'server' | 'client' | 'vscode-servers' | 'theia' | `host-${InitHost}`;
+
+/**
+ * The packages a scaffold with these heads and hosts emits, in the order a
+ * workspace lists them. `client` comes with the `glsp` head, which always
+ * brings a diagram, and each host is a package of its own. `vscode-servers`
+ * comes with the VS Code host, whose server launch it holds, and with a Theia
+ * application, which sideloads it; `theia` is the Theia extension the Theia
+ * applications run.
+ */
+export function initMembers(heads: readonly InitHead[], hosts: readonly InitHost[]): InitMember[] {
+   return [
+      'protocol',
+      'server',
+      ...(heads.includes('glsp') ? (['client'] as const) : []),
+      ...(hosts.includes('vscode') || hosts.some(isTheiaHost) ? (['vscode-servers'] as const) : []),
+      ...(hosts.some(isTheiaHost) ? (['theia'] as const) : []),
+      ...hosts.map(host => `host-${host}` as const)
+   ];
+}
+
+/** 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, members: readonly InitMember[]): readonly InitMemberPlacement[] {
+   return 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 +106,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 +178,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,8 +241,10 @@ 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 host applications emitted around the server, each a package of its own. */
+   readonly hosts: readonly InitHost[];
    /** The grammars, in the order given. The first is the configuration root. */
    readonly grammars: readonly InitGrammarNames[];
    /** How the emitted `package.json` presents itself, and where it sits. */
@@ -222,14 +280,15 @@ export interface InitCommandOptions {
    readonly grammars?: readonly InitGrammarSpec[];
    /** The protocol heads to start. Defaults to {@link DEFAULT_INIT_HEADS}. */
    readonly heads?: readonly InitHead[];
+   /** The host applications to emit around the server. Defaults to none. */
+   readonly hosts?: readonly InitHost[];
    /** Scaffold into a non-empty directory anyway. */
    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 +303,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 +346,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 +367,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,23 +395,34 @@ 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));
 }
 
+/** Validate the host set against the heads: known names only, and one of the heads each host edits through. */
+function resolveHosts(hosts: readonly InitHost[], heads: readonly InitHead[]): readonly InitHost[] {
+   const unknown = hosts.filter(host => !isInitHost(host));
+   if (unknown.length > 0) {
+      throw new Error(`Unknown host(s) '${unknown.join(', ')}': expected one of ${INIT_HOSTS.join(', ')}.`);
+   }
+   for (const host of hosts) {
+      const editing = editingHeads(host);
+      if (!editing.some(head => heads.includes(head))) {
+         const needed = editing.length === 1 ? `the '${editing[0]}' head` : `one of the '${editing.join(', ')}' heads`;
+         throw new Error(`--hosts ${host} needs ${needed}, but the head set is '${heads.join(',')}'.`);
+      }
+   }
+   return INIT_HOSTS.filter(host => hosts.includes(host));
+}
+
 /**
  * Reject the collisions that would otherwise surface as a confusing generator
  * or runtime failure rather than as a bad invocation.
@@ -368,15 +449,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);
       }
    }
 }
@@ -393,7 +477,8 @@ export function resolveInitComposition(
    name: string,
    grammars: readonly InitGrammarSpec[] = [],
    heads?: readonly InitHead[],
-   packaging: InitPackaging = STANDALONE_PACKAGING
+   packaging: InitPackaging = STANDALONE_PACKAGING,
+   hosts: readonly InitHost[] = []
 ): InitComposition {
    if (!isPascalIdentifier(name)) {
       throw new Error(
@@ -405,11 +490,20 @@ export function resolveInitComposition(
       throw new Error(`Invalid --scope '${packaging.scope}': an npm scope starts with '@', e.g. '@acme'.`);
    }
    const resolvedHeads = resolveHeads(heads);
+   const resolvedHosts = resolveHosts(hosts, resolvedHeads);
    const specs = grammars.length > 0 ? grammars : [{ name }];
    const diagrams = resolveDiagrams(specs, resolvedHeads);
    const resolved = specs.map((spec, index) => resolveGrammar(spec, projectId, specs.length > 1, diagrams[index]));
    assertNoCollisions(resolved);
-   return { name, projectId, heads: resolvedHeads, grammars: resolved, packaging, frameworkVersion: readFrameworkVersion() };
+   return {
+      name,
+      projectId,
+      heads: resolvedHeads,
+      hosts: resolvedHosts,
+      grammars: resolved,
+      packaging,
+      frameworkVersion: readFrameworkVersion()
+   };
 }
 
 /**
@@ -432,6 +526,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,24 +562,61 @@ 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)
       }
    };
 }
 
+/**
+ * Format a standalone scaffold as its own `format` script would, with the
+ * `oxfmt` its root pins and the config it emits. A template is written at one
+ * length of the names its tokens stand for, so only a formatter run lets every
+ * project name pass `format:check`. Only the written files, because `--force`
+ * scaffolds beside files that are not ours to restyle. A failure leaves the
+ * files as written, which build all the same, and says so.
+ */
+function formatScaffold(targetDir: string, files: readonly InitFile[], write: (line: string) => void): void {
+   let reason: string | undefined;
+   try {
+      // Not `findPackageJSON`: Node 22.13, which `engines` admits, lacks it.
+      const manifestPath = createRequire(import.meta.url).resolve('oxfmt/package.json');
+      const bin = (JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as { bin: Record<string, string> }).bin.oxfmt;
+      const args = [path.join(path.dirname(manifestPath), bin), ...files.map(file => file.path)];
+      const result = spawnSync(process.execPath, args, { cwd: targetDir, encoding: 'utf-8' });
+      if (result.status !== 0) {
+         reason = result.error?.message ?? `${result.stdout}${result.stderr}${result.signal === null ? '' : `killed by ${result.signal}`}`;
+      }
+   } catch (error: unknown) {
+      reason = error instanceof Error ? error.message : String(error);
+   }
+   if (reason !== undefined) {
+      write(`Warning: oxfmt did not format the scaffold, so run \`npm run format\` after \`npm install\`:\n${reason.trim()}\n`);
+   }
+}
+
 /**
  * Scaffold a new Hydranium language project end-to-end: one starter grammar per
  * `--grammar`, `create<Name>Services` DI wiring, a launcher for each head in
  * `--heads`, `langium-config.json`, `package.json`, and scripts. Does NOT run `npm install`
  * or `langium generate` — those are printed as next steps, so the command stays
- * offline and side-effect-free beyond the files it writes. Refuses a non-empty
- * target directory unless `force`.
+ * offline and changes nothing beyond the files it writes, which a standalone
+ * scaffold's oxfmt then formats. Refuses a non-empty target directory unless
+ * `force`.
  */
 export function runInit(options: InitCommandOptions): void {
    const write = options.write ?? ((line: string) => process.stdout.write(line));
    const targetDir = path.resolve(options.targetDir);
    const detection = options.monorepo ? detectWorkspace(targetDir, options.probe ?? createNodeWorkspaceProbe()) : undefined;
-   const composition = resolveInitComposition(options.name, options.grammars, options.heads, resolveInitPackaging(targetDir, options));
+   const composition = resolveInitComposition(
+      options.name,
+      options.grammars,
+      options.heads,
+      resolveInitPackaging(targetDir, options),
+      options.hosts
+   );
 
    if (!options.force && isNonEmptyDir(targetDir)) {
       throw new Error(`Target directory '${targetDir}' is not empty. Pass --force to scaffold into it anyway.`);
@@ -498,56 +631,126 @@ export function runInit(options: InitCommandOptions): void {
          fs.mkdirSync(path.dirname(absolute), { recursive: true });
          fs.writeFileSync(absolute, file.content, 'utf-8');
       }
+      if (composition.packaging.workspace === undefined) {
+         formatScaffold(targetDir, files, write);
+      }
    }
 
    const grammarList = composition.grammars.map(grammar => (grammar.diagram ? `${grammar.grammar} (diagram)` : grammar.grammar)).join(', ');
    write(
       `Scaffolded ${composition.name} (${files.length} files, heads: ${composition.heads.join(',')}, ` +
+         (composition.hosts.length > 0 ? `hosts: ${composition.hosts.join(',')}, ` : '') +
          `${composition.grammars.length} grammar(s): ${grammarList}) into ${targetDir}\n`
    );
    if (detection !== undefined) {
       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 library package's tsconfig.json extends the root's ${path.posix.basename(detection.baseTsconfig)}, minus the options it inherits unchanged.\n`
+         );
+         if (composition.hosts.length > 0) {
+            // A host's projects compile its page, worker and tests apart, each under options of its own.
+            const members = initMembers(composition.heads, composition.hosts);
+            const extensions = [
+               ...(members.includes('vscode-servers') ? ["the VS Code servers extension's"] : []),
+               ...(members.includes('theia') ? ["the Theia extension's"] : [])
+            ];
+            const also = extensions.length === 0 ? '' : `, as ${extensions.join(' and ')} ${extensions.length === 1 ? 'does' : 'do'}`;
+            write(`  Each host's tsconfigs stand alone${also}.\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, initMembers(composition.heads, composition.hosts));
+      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).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`);
+      // oxfmt and oxlint skip whatever an enclosing repository ignores, this
+      // folder included: https://github.com/oxc-project/oxc/issues/25603
+      if (spawnSync('git', ['check-ignore', '-q', targetDir], { cwd: targetDir }).status === 0) {
+         write('  git init                 # an enclosing repository ignores this folder, so lint and format find no file until then\n');
+      }
+      // A comment, so a pasted block runs without nvm. NVM for Windows ignores
+      // `.nvmrc` and its `install` does not switch, hence both commands.
+      write(
+         `  # on Node ${SCAFFOLD_NODE_MAJOR}, which .nvmrc names. With nvm: nvm install ${SCAFFOLD_NODE_MAJOR}, then nvm use ${SCAFFOLD_NODE_MAJOR}\n`
+      );
+      write('  npm install\n');
+      write('  npm run build            # langium generate + tsc, every package\n');
+      write('  npm test                 # the server tests\n');
+      write('  npm run watch            # rebuild the members on every change; watch:<host> adds a host\n');
+   } else {
+      write(`  cd ${detection.rootDir}\n`);
+      write('  npm install\n');
+      write(`  npm --prefix ${server} run build   # langium generate + tsc, protocol included\n`);
+      // The server's build reaches protocol through its project reference and
+      // nothing else, so each further member is built on its own.
+      for (const member of initMembers(composition.heads, composition.hosts).filter(name => name !== 'protocol' && name !== 'server')) {
+         write(`  npm --prefix ${detection.targetPath}/${member} run build\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`);
+   const hostDir = (host: InitHost): string => (detection === undefined ? `host-${host}` : `${detection.targetPath}/host-${host}`);
+   // A standalone root runs a host as `start:<host>`. A surrounding workspace's root is not ours to add to.
+   const start = (host: InitHost): string => (detection === undefined ? `npm run start:${host}` : `npm --prefix ${hostDir(host)} start`);
+   if (composition.hosts.includes('browser')) {
+      const browser = hostDir('browser');
+      write(`  ${start('browser')}   # serve the page at http://localhost:4937, Ctrl+C to stop\n`);
+      // The smoke test serves the page itself, on the same port.
+      write(`  npm --prefix ${browser} run test:e2e:install && npm --prefix ${browser} run test:e2e   # with start stopped\n`);
+   }
+   if (composition.hosts.includes('vscode')) {
+      const vscode = hostDir('vscode');
+      write(`  ${start('vscode')}   # VS Code with the extension, on the workspace (needs \`code\` on the PATH)\n`);
+      write(`  npm --prefix ${vscode} run test:e2e:install && npm --prefix ${vscode} run test:e2e\n`);
+   }
+   if (composition.hosts.includes('theia-browser')) {
+      const theia = hostDir('theia-browser');
+      write(`  ${start('theia-browser')}   # Theia at http://localhost:3000 on the workspace, Ctrl+C to stop\n`);
+      // The smoke test starts its own backend, on a port of its own.
+      write(`  npm --prefix ${theia} run test:e2e:install && npm --prefix ${theia} run test:e2e\n`);
+   }
+   if (composition.hosts.includes('theia-electron')) {
+      const electron = hostDir('theia-electron');
+      write(`  ${start('theia-electron')}   # the Theia desktop application on the workspace\n`);
+      write(`  npm --prefix ${electron} run test:e2e\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);
 }