@hydranium/cli 1.0.0-next.39 → 1.0.0-next.391

package/src/commands/harness-args.ts

@@ -31,11 +31,12 @@
  * parser rejects is an invocation that fails for no visible reason.
  */
 
-import type { LogThreshold } from '@hydranium/protocol';
+import { describeError, type LogThreshold } from '@hydranium/protocol';
 import { statSync } from 'node:fs';
+import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parseLogLevelOption } from '../log-level.js';
+import { type LogOptions, parseLogLevelOption } from '../log-level.js';
 
 /**
  * How a parser reports a usage problem. It never returns, so a parser can treat
@@ -56,9 +57,18 @@ export function exitWithUsage(message: string): never {
    process.exit(2);
 }
 
-/** The value flag {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+/** Names the head's services module; every harness subcommand requires it. */
 export const SERVICES_FLAG = '--services';
 
+/**
+ * Registers a loader in the driver child that imports the head. The child is a
+ * fresh `node`, so a loader registered on the CLI's own process never reaches it.
+ */
+export const IMPORT_FLAG = '--import';
+
+/** The value flags {@link parseHarnessArgs} consumes itself, before any the subcommand declares. */
+export const HARNESS_VALUE_FLAGS = [SERVICES_FLAG, IMPORT_FLAG] as const;
+
 /**
  * The one spelling of the log threshold, shared by both subcommand families.
  *
@@ -68,33 +78,68 @@ export const SERVICES_FLAG = '--services';
  * on which command a caller happened to reach for.
  */
 export const LOG_LEVEL_FLAG = '--log-level';
+export const LOG_FILE_FLAG = '--log-file';
+export const LOG_FILE_LEVEL_FLAG = '--log-file-level';
+
+/** The log flags every subcommand takes, read by {@link logOptions}. */
+export const LOG_VALUE_FLAGS = [LOG_LEVEL_FLAG, LOG_FILE_FLAG, LOG_FILE_LEVEL_FLAG] as const;
 
 /** The value flags {@link parseServerSpawnOptions} consumes itself. */
-export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', LOG_LEVEL_FLAG];
+export const SERVER_SPAWN_VALUE_FLAGS: readonly string[] = ['--server', '--cwd', ...LOG_VALUE_FLAGS];
 
 /**
- * The `--help` line every subcommand describes {@link LOG_LEVEL_FLAG} with.
+ * The `--help` lines every subcommand describes {@link LOG_VALUE_FLAGS} with.
  *
  * Shared text, per-command padding: `command-args.test.ts` compares the flags a
  * help block DESCRIBES against the flags the parser accepts, and it recognises a
- * description by the two-space indent — so the line has to be a real option entry
+ * description by the two-space indent — so each line has to be a real option entry
  * in each block, and the column each block aligns its descriptions at is the
- * block's own.
+ * block's own. A flag too wide for that column takes its description on the
+ * next line, at the column.
  */
-export function logLevelHelpLine(padTo: number): string {
-   return `  ${`${LOG_LEVEL_FLAG} <lvl>`.padEnd(padTo)}Log threshold for the head this boots (off|error|warn|info|debug|trace).`;
+export function logHelpLines(padTo: number, head = 'the head this boots'): string[] {
+   return [
+      helpLine(`${LOG_LEVEL_FLAG} <lvl>`, `Log threshold for ${head} (off|error|warn|info|debug|trace).`, padTo),
+      helpLine(
+         `${LOG_FILE_FLAG} <file>`,
+         `Also write ${head}'s log to <file>; {workspace} expands to the workspace, {pid} to the process id.`,
+         padTo
+      ),
+      helpLine(`${LOG_FILE_LEVEL_FLAG} <lvl>`, `Threshold for that file, which the log-level setting does not change.`, padTo)
+   ].flat();
+}
+
+/** The `--help` lines every `--services` subcommand describes {@link IMPORT_FLAG} with, aligned as {@link logHelpLines}. */
+export function importHelpLines(padTo: number): string[] {
+   return helpLine(`${IMPORT_FLAG} <specifier>`, 'Loader to register before importing <module>, e.g. tsx (repeatable).', padTo);
+}
+
+function helpLine(flag: string, text: string, padTo: number): string[] {
+   return flag.length < padTo - 1 ? [`  ${flag.padEnd(padTo)}${text}`] : [`  ${flag}`, `${' '.repeat(padTo + 2)}${text}`];
 }
 
 /**
- * Narrow a raw {@link LOG_LEVEL_FLAG} value that {@link parseHarnessArgs}
- * collected, leaving an absent flag absent.
+ * Narrow the raw {@link LOG_VALUE_FLAGS} values a parser collected, leaving
+ * absent flags absent.
+ *
+ * `--log-file` resolves against the caller's directory: the child may run
+ * elsewhere (`--cwd`), and a relative path would land the log there.
  *
  * Throws rather than reaching `onError`, matching {@link parseServerSpawnOptions}:
  * the level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  */
-export function logLevelOption(value: string | undefined): LogThreshold | undefined {
-   return value === undefined ? undefined : parseLogLevelOption(value);
+export function logOptions(options: Readonly<Record<string, string | undefined>>): LogOptions {
+   const level = (flag: string): LogThreshold | undefined => {
+      const value = options[flag];
+      return value === undefined ? undefined : parseLogLevelOption(value, flag);
+   };
+   const logFile = options[LOG_FILE_FLAG];
+   return {
+      logLevel: level(LOG_LEVEL_FLAG),
+      logFile: logFile === undefined ? undefined : path.resolve(logFile),
+      logFileLevel: level(LOG_FILE_LEVEL_FLAG)
+   };
 }
 
 /**
@@ -134,6 +179,8 @@ export function printHelp(lines: readonly string[]): void {
 /** What {@link parseHarnessArgs} recovered from an argv. */
 export interface ParsedHarnessArgs {
    servicesModule: string;
+   /** The {@link IMPORT_FLAG} values in the order given, absent when there were none. */
+   imports?: string[];
    /**
     * An absolute directory path, resolved by {@link resolveWorkspaceArgument} and
     * checked to exist. `''` when the subcommand declared `requireWorkspace: false`.
@@ -163,12 +210,12 @@ export interface HarnessArgsConfig {
 
 /**
  * Shared parser for the headless-harness subcommands. Consumes the required
- * `--services <module>` value flag and a single positional `<workspace>`, plus
- * the `valueFlags` (each takes a value) and `boolFlags` (presence-only, recorded
- * as `'true'`) the subcommand recognises. Unknown flags or a missing
- * `--services`/`<workspace>` are usage errors, and so is a `<workspace>` that
- * reaches no directory — see {@link resolveWorkspaceArgument} for why that cannot
- * be left to the run.
+ * `--services <module>` value flag, the repeatable `--import <specifier>` and a
+ * single positional `<workspace>`, plus the `valueFlags` (each takes a value)
+ * and `boolFlags` (presence-only, recorded as `'true'`) the subcommand
+ * recognises. Unknown flags or a missing `--services`/`<workspace>` are usage
+ * errors, and so is a `<workspace>` that reaches no directory — see
+ * {@link resolveWorkspaceArgument} for why that cannot be left to the run.
  */
 export function parseHarnessArgs(
    args: string[],
@@ -185,6 +232,7 @@ export function parseHarnessArgs(
    const options: Record<string, string | undefined> = {};
    const values: Record<string, string[]> = {};
    let servicesModule: string | undefined;
+   let imports: string[] | undefined;
    let workspace: string | undefined;
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -196,8 +244,10 @@ export function parseHarnessArgs(
          index += 1;
          return value;
       };
-      if (flag === '--services') {
+      if (flag === SERVICES_FLAG) {
          servicesModule = next();
+      } else if (flag === IMPORT_FLAG) {
+         (imports ??= []).push(next());
       } else if (boolSet.has(flag)) {
          options[flag] = 'true';
       } else if (repeatableSet.has(flag)) {
@@ -213,7 +263,8 @@ export function parseHarnessArgs(
       }
    }
    return {
-      servicesModule: assertRequired(servicesModule, '--services', commandName, onError),
+      servicesModule: assertRequired(servicesModule, SERVICES_FLAG, commandName, onError),
+      imports,
       workspace: requireWorkspace
          ? resolveWorkspaceArgument(assertRequired(workspace, '<workspace>', commandName, onError), commandName, onError)
          : (workspace ?? ''),
@@ -257,7 +308,7 @@ export function resolveWorkspaceArgument(workspace: string, commandName: string,
    try {
       stats = statSync(resolved, { throwIfNoEntry: false });
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not reachable: '${workspace}' resolved to ${resolved} (${detail}) ${help}`);
    }
    if (stats === undefined) {
@@ -276,7 +327,7 @@ function toWorkspacePath(workspace: string, commandName: string, onError: UsageE
    try {
       return fileURLToPath(workspace);
    } catch (err: unknown) {
-      const detail = err instanceof Error ? err.message : String(err);
+      const detail = describeError(err);
       onError(`<workspace> is not a usable file URI: '${workspace}' (${detail}) (hydranium-cli ${commandName} --help)`);
    }
 }
@@ -336,11 +387,10 @@ function kebabToCamel(name: string): string {
 }
 
 /** What {@link parseServerSpawnOptions} recovered from an argv. */
-export interface SpawnOptions {
+export interface SpawnOptions extends LogOptions {
    serverCommand: string;
    serverArgs: string[];
    cwd?: string;
-   logLevel?: LogThreshold;
    /** The tokens this parser did not claim, for the subcommand's own options. */
    extra: string[];
 }
@@ -363,10 +413,10 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 
 /**
  * Shared option parser for subcommands that spawn a data-server child. Consumes
- * `--server` / `--cwd` / `--log-level` and returns the surviving tokens as
+ * `--server` / `--cwd` / the {@link LOG_VALUE_FLAGS} and returns the surviving tokens as
  * `extra` for {@link parseFlagOptions} to finish.
  *
- * An unrecognised `--log-level` value throws rather than reaching `onError`: the
+ * An unrecognised log level value throws rather than reaching `onError`: the
  * level vocabulary belongs to the protocol package, which reports it, and the
  * entry point's catch turns that into the same message-and-exit.
  *
@@ -383,7 +433,7 @@ function isRelativePathToken(token: string, isCommand: boolean): boolean {
 export function parseServerSpawnOptions(args: string[], commandName: string, onError: UsageError = exitWithUsage): SpawnOptions {
    let serverSpec: string | undefined;
    let cwd: string | undefined;
-   let logLevel: LogThreshold | undefined;
+   const logFlags: Record<string, string> = {};
    const extra: string[] = [];
    for (let index = 0; index < args.length; index += 1) {
       const flag = args[index];
@@ -399,8 +449,8 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          serverSpec = claim();
       } else if (flag === '--cwd') {
          cwd = claim();
-      } else if (flag === LOG_LEVEL_FLAG) {
-         logLevel = parseLogLevelOption(claim());
+      } else if ((LOG_VALUE_FLAGS as readonly string[]).includes(flag)) {
+         logFlags[flag] = claim();
       } else {
          extra.push(flag);
       }
@@ -425,5 +475,23 @@ export function parseServerSpawnOptions(args: string[], commandName: string, onE
          );
       }
    }
-   return { serverCommand, serverArgs, cwd, logLevel, extra };
+   return { serverCommand, serverArgs, cwd, ...logOptions(logFlags), extra };
+}
+
+/**
+ * Resolve the `--content` argument to its textual form. The `@<path>`
+ * prefix reads from a file (parses as UTF-8); anything else is taken
+ * literally. The leading `@` can be escaped as `\@` for content that
+ * legitimately starts with `@`.
+ */
+export async function resolveContent(content: string, readFile?: (path: string) => Promise<string>): Promise<string> {
+   if (content.startsWith('@')) {
+      const file = content.slice(1);
+      const reader = readFile ?? ((target: string) => fs.readFile(target, 'utf8'));
+      return reader(file);
+   }
+   if (content.startsWith('\\@')) {
+      return content.slice(1);
+   }
+   return content;
 }

package/src/commands/headless-harness.ts

@@ -8,14 +8,14 @@
  ********************************************************************************/
 
 import type * as HydraniumCoreNode from '@hydranium/core/node';
-import type { LogThreshold } from '@hydranium/protocol';
 import { spawn } from 'node:child_process';
 import { statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { logLevelEnv } from '../log-level.js';
-import { SERVICES_FLAG } from './harness-args.js';
+import { driverHeapArgs, type HeapReading } from '../driver-heap.js';
+import { logEnv, type LogOptions } from '../log-level.js';
+import { IMPORT_FLAG, SERVICES_FLAG } from './harness-args.js';
 
 /** The flag every report-producing subcommand names its destination file with. */
 export const OUT_FILE_FLAG = '--out-file';
@@ -43,13 +43,15 @@ export interface HeadlessContext {
  * its `createServices` thunk AND the `@hydranium/core/node` harness, both
  * resolved from the HEAD's location rather than the CLI's.
  *
- * The module is an ESM file (typically a compiled `lib/*.js`) exporting a
- * ZERO-ARG `createServices(): { shared }`. `hydranium-cli` is language-agnostic
+ * The module is an ESM file exporting a ZERO-ARG `createServices(): { shared }`:
+ * a compiled `lib/*.js`, or the TypeScript source when the child was started
+ * with a loader through {@link IMPORT_FLAG}. `hydranium-cli` is language-agnostic
  * and cannot statically import a head's `create<Lang>Services`, so the dynamic
  * import is the seam that keeps the binary head-neutral. Resolving the harness
- * from the head's graph (via `createRequire` rooted at the head module) means the
- * CLI itself needs no `@hydranium/core` dependency — the head always has it — and
- * guarantees the harness runs against the SAME core copy as `createServices`.
+ * from the head's graph (via `createRequire` rooted at the head module) rather
+ * than from the CLI's guarantees it runs against the SAME core copy as
+ * `createServices`, which a second copy of the module would break even where
+ * both resolve.
  *
  * Throws a clear error when the path names no file, and when the export is
  * missing or not a function.
@@ -64,12 +66,17 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    if (stats === undefined || !stats.isFile()) {
       throw new Error(
          `${SERVICES_FLAG} must name an existing ESM file; '${servicesModule}' resolved to ${modulePath}, ` +
-            `which is not one. Pass the head's COMPILED entry, e.g. \`${SERVICES_FLAG} ./lib/services.js\` — ` +
-            'not the TypeScript source and not a package name.'
+            "which is not one. Pass the path of the server package's built `lib/node/services.js` from where you run this — " +
+            'not a package name.'
       );
    }
    const moduleUrl = pathToFileURL(modulePath).href;
-   const imported = (await import(moduleUrl)) as Record<string, unknown>;
+   let imported: Record<string, unknown>;
+   try {
+      imported = (await import(moduleUrl)) as Record<string, unknown>;
+   } catch (err: unknown) {
+      throw withLoaderHint(err, modulePath);
+   }
    const createServices = imported.createServices;
    if (typeof createServices !== 'function') {
       throw new Error(
@@ -84,6 +91,32 @@ export async function loadHeadlessContext(servicesModule: string): Promise<Headl
    return { createServices: createServices as ServicesFactory, coreNode };
 }
 
+/** The codes Node fails a TypeScript entry with when no loader handled it, depending on its version. */
+const UNLOADED_TYPESCRIPT_CODES: ReadonlySet<string> = new Set([
+   'ERR_UNKNOWN_FILE_EXTENSION',
+   'ERR_MODULE_NOT_FOUND',
+   'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX'
+]);
+
+/**
+ * Append a loader hint to a TypeScript entry's import failure, unless the child
+ * was started with {@link IMPORT_FLAG}, where the hint would only repeat the
+ * caller's own command. Appended rather than substituted: a loader set through
+ * `NODE_OPTIONS` does not show in `execArgv`, and under it the failure can be a
+ * missing module that only Node's own message names.
+ */
+function withLoaderHint(err: unknown, modulePath: string): unknown {
+   if (!(err instanceof Error) || !/\.[cm]?ts$/.test(modulePath) || !('code' in err) || typeof err.code !== 'string') {
+      return err;
+   }
+   if (!UNLOADED_TYPESCRIPT_CODES.has(err.code) || process.execArgv.some(arg => arg.startsWith(IMPORT_FLAG))) {
+      return err;
+   }
+   return new Error(`${err.message}\nA TypeScript head needs a loader registered with \`${IMPORT_FLAG}\`, e.g. \`${IMPORT_FLAG} tsx\`.`, {
+      cause: err
+   });
+}
+
 /**
  * Child-side: deliver a finished report — to `outFile` when one was named, else
  * to stdout.
@@ -101,8 +134,9 @@ export function emitReport(report: string, outFile: string | undefined): void {
    }
    writeFileSync(outFile, report.endsWith('\n') ? report : `${report}\n`);
    // Progress on stderr, so a caller that also captures stdout gets a clean
-   // stream rather than a note where the report used to be.
-   console.error(`Wrote ${outFile}`);
+   // stream rather than a note where the report used to be. Not `console.error`,
+   // which a configured log file records as an error line.
+   process.stderr.write(`Wrote ${outFile}\n`);
 }
 
 /**
@@ -129,37 +163,64 @@ export function spawnNodeChild(execArgs: string[], env?: Record<string, string>)
 /** How a subcommand parent reaches its driver child; the seam `__spawnForTest` replaces. */
 export type SpawnDriverChild = (execArgs: string[], env?: Record<string, string>) => Promise<number>;
 
-/** What every `--services` subcommand carries for the child it spawns, on top of its own options. */
-export interface DriverSpawnOptions {
-   /**
-    * Log threshold for the head the driver boots. Absent leaves the child's
-    * inherited environment alone, so an ambient `HYDRANIUM_LOG_LEVEL` still wins
-    * where a caller set one.
-    */
-   readonly logLevel?: LogThreshold;
+/**
+ * What every `--services` subcommand carries for the child it spawns, on top of
+ * its own options. The log options apply to the head the driver boots; an
+ * absent one leaves the child's inherited environment alone, so an ambient
+ * variable still wins where a caller set one.
+ */
+export interface DriverSpawnOptions extends LogOptions {
+   /** Specifiers the driver child registers with Node's `--import`, in order, before it imports the head. */
+   readonly imports?: readonly string[];
    /** Test-only: capture the node argv and env instead of spawning the real child. */
    readonly __spawnForTest?: SpawnDriverChild;
+   /**
+    * Test-only: decide the heap ceiling from a stated cgroup reading rather
+    * than the machine's. Without it an argv assertion means one thing on a
+    * workstation and nothing at all under a memory limit, so a suite that
+    * asserts the ceiling is present passes vacuously in a container.
+    */
+   readonly __heapReadingForTest?: HeapReading;
 }
 
 /**
  * Parent-side: run a subcommand's driver child and propagate its exit code, so a
  * shell or CI step sees the gate.
  *
- * **The log threshold travels in the child's ENVIRONMENT, not its argv.** The
- * head's logger reads `HYDRANIUM_LOG_LEVEL` while `createServices` constructs it,
- * which is inside the driver's dynamic import — a flag the driver parsed would
- * arrive after the only moment it can be read. Setting it here rather than
- * exporting it also leaves the CLI's own output alone, unlike an ambient
- * `HYDRANIUM_LOG_LEVEL=…` the parent would carry too.
+ * **The log options travel in the child's ENVIRONMENT, not its argv.** The
+ * head's logger reads its `HYDRANIUM_LOG_*` variables while `createServices`
+ * constructs it, which is inside the driver's dynamic import — a flag the driver
+ * parsed would arrive after the only moment it can be read. Setting them here
+ * rather than exporting them also leaves the CLI's own output alone, unlike
+ * ambient variables the parent would carry too.
  *
  * A head that binds a logger of its own decides for itself whether the flag means
  * anything, which is the intended seam: the CLI is language-agnostic and cannot
  * reach past `createServices`.
+ *
+ * **The heap ceiling is prepended HERE rather than passed by each subcommand.**
+ * Every caller wants the same answer to the same question, and the answer is not
+ * a constant — see {@link driverHeapArgs}. A literal at the call site is a place
+ * the container case can be missed, and the caller that misses it takes the whole
+ * cgroup down with it rather than failing on its own.
  */
 export async function runDriverChild(execArgs: string[], options: DriverSpawnOptions): Promise<void> {
    const spawnChild = options.__spawnForTest ?? spawnNodeChild;
-   const code = await spawnChild(execArgs, options.logLevel === undefined ? undefined : logLevelEnv(options.logLevel));
+   const importArgs = (options.imports ?? []).map(specifier => `${IMPORT_FLAG}=${loaderSpecifier(specifier)}`);
+   const code = await spawnChild([...driverHeapArgs(options.__heapReadingForTest), ...importArgs, ...execArgs], logEnv(options));
    if (code) {
       process.exitCode = code;
    }
 }
+
+/**
+ * A path, absolute or `./`/`../` relative with either separator, becomes a file
+ * URL resolved against the caller's directory. Node reads `--import` as a URL or
+ * package specifier, so it would take a Windows `C:\…` for the URL scheme `c:`
+ * and a `.\…` for a package name. Any other specifier passes through as Node
+ * reads it.
+ */
+function loaderSpecifier(specifier: string): string {
+   const isPath = path.isAbsolute(specifier) || /^\.\.?[\\/]/.test(specifier);
+   return isPath ? pathToFileURL(path.resolve(specifier)).href : specifier;
+}

package/src/commands/init-args.ts

@@ -28,6 +28,7 @@
 
 import { assertRequired, exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
 import { isNonEmptyDir, runInit, type InitHead } from './init.js';
+import type { InitHost } from './init-hosts.js';
 import { createClackPrompt } from './init-prompt.js';
 import { runInitWizard } from './init-wizard.js';
 import { createNodeWorkspaceProbe, detectWorkspace } from './init-workspace.js';
@@ -46,6 +47,7 @@ export interface ParsedInitArgs {
    name?: string;
    force: boolean;
    heads?: InitHead[];
+   hosts?: InitHost[];
    monorepo: boolean;
    scope?: string;
    public: boolean;
@@ -62,6 +64,7 @@ export interface ParsedInitArgs {
 export const INIT_FLAGS: readonly string[] = [
    '--name',
    '--heads',
+   '--hosts',
    '--force',
    '--monorepo',
    '--scope',
@@ -76,7 +79,15 @@ export const INIT_FLAGS: readonly string[] = [
  * The subset that takes a value, so `--help` in a value position reads as data.
  * The rest are presence-only.
  */
-export const INIT_VALUE_FLAGS: readonly string[] = ['--name', '--heads', '--scope', '--grammar', '--extensions', '--language-id'];
+export const INIT_VALUE_FLAGS: readonly string[] = [
+   '--name',
+   '--heads',
+   '--hosts',
+   '--scope',
+   '--grammar',
+   '--extensions',
+   '--language-id'
+];
 
 /**
  * Parse `init`'s flags without deciding whether the result is complete.
@@ -94,6 +105,7 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
    let name: string | undefined;
    let force = false;
    let heads: InitHead[] | undefined;
+   let hosts: InitHost[] | undefined;
    let monorepo = false;
    let scope: string | undefined;
    let isPublic = false;
@@ -137,11 +149,14 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
             scoped().diagram = true;
             break;
          case '--heads': {
-            // Validated in `resolveInitComposition`, which owns the rule that
-            // `lsp` is mandatory; the cast only gets the strings that far.
+            // Validated in `resolveInitComposition`; the cast only gets the
+            // strings that far.
             heads = next().split(',') as InitHead[];
             break;
          }
+         case '--hosts':
+            hosts = next().split(',') as InitHost[];
+            break;
          case '--force':
             force = true;
             break;
@@ -169,7 +184,7 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
             }
       }
    }
-   return { targetDir, name, force, heads, monorepo, scope, public: isPublic, grammars };
+   return { targetDir, name, force, heads, hosts, monorepo, scope, public: isPublic, grammars };
 }
 
 /**
@@ -180,46 +195,71 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
  * authoritative, and a flag missing from it is a capability nobody finds.
  */
 export const INIT_HELP: readonly string[] = [
-   'Usage: hydranium-cli init <target-dir> --name <Name> [--heads <list>] [--force]',
-   '                            [--monorepo] [--scope <@scope>] [--public]',
+   'Usage: hydranium-cli init <target-dir> --name <Name> [--heads <list>]',
+   '                            [--hosts <list>] [--force] [--monorepo]',
+   '                            [--scope <@scope>] [--public]',
    '                            ( --grammar <Name> [--extensions <list>]',
    '                                              [--language-id <id>] [--diagram] )...',
    '',
-   'Scaffold a new Hydranium language project end-to-end: a starter grammar per',
-   '--grammar, the `create<Name>Services` DI wiring, an LSP + data-server launch,',
-   'langium-config, package.json, and build scripts. Does NOT run `npm install` or',
-   '`langium generate` — those are printed as next steps. Refuses a non-empty',
-   'directory without --force.',
+   'Scaffold a new Hydranium language project end-to-end: its packages and a',
+   'starter workspace, each in its own directory. server/ holds a starter grammar',
+   'per --grammar, the `create<Name>Services` DI wiring, a launch of every head',
+   'and build scripts; protocol/ holds what the server and its clients both',
+   'import; client/, with a diagram, holds its host-neutral client side;',
+   'host-<name>/ holds each --hosts application, vscode-servers/ the server',
+   'launch of the VS Code and Theia ones, and theia/ the Theia extension;',
+   'workspace/ holds two starter model files per grammar. A standalone project',
+   'also gets a root manifest naming the packages as npm workspaces.',
+   'Does NOT run `npm install` or `langium generate` — those are printed as next',
+   'steps. Refuses a non-empty directory without --force.',
    '',
    'Run it with no --name on a terminal to be prompted instead. The wizard echoes',
    'the command it composed before running it, so every answer is reproducible as',
    'flags. Without a terminal a missing --name stays an error, so CI never hangs.',
    '',
    'Project options (position-free):',
-   '  <target-dir>          Directory to scaffold into (required).',
+   '  <target-dir>          The project directory to scaffold into (required).',
    '  --name <Name>         PascalCase PROJECT name; drives the services and the',
    '                        Langium projectName, i.e. the shared generated symbols',
    '                        (<Name>AstReflection, <Name>GeneratedSharedModule) (required).',
-   '  --heads <list>        Comma-separated protocol heads: lsp, data, glsp.',
-   '                        `lsp` is mandatory — it owns the workspace, the build',
-   '                        pipeline and the shared tier the others read through.',
-   '                        The emitted dependencies, main.ts and module bindings',
-   '                        all follow this set. Default: lsp,data.',
+   '  --heads <list>        Comma-separated protocol heads: lsp, data, glsp, any',
+   '                        non-empty set. Without lsp, main.ts serves the socket',
+   '                        heads from a workspace path it is given and prints',
+   '                        their ports. The emitted dependencies, main.ts and',
+   '                        module bindings all follow this set. Default: lsp,data.',
+   '  --hosts <list>        Comma-separated host applications to emit around the',
+   '                        heads: browser, a page running every head in a web',
+   '                        worker, which needs lsp or glsp; without lsp it has',
+   '                        no editor and saves through the diagram. vscode, a',
+   '                        VS Code extension and the servers-only extension it',
+   '                        starts the server through, which needs lsp.',
+   '                        theia-browser, a Theia browser application, its',
+   '                        Theia extension and the servers-only extension it',
+   '                        sideloads, which needs lsp. theia-electron, the',
+   '                        same in a Theia Electron application. Without',
+   '                        --hosts, the server with its Node entry points, and',
+   '                        with glsp the client/ package a host mounts.',
    '  --force               Scaffold into a non-empty directory anyway.',
-   '  --monorepo            Scaffold a member of the surrounding npm workspace:',
-   '                        tsconfig extends the root config that actually carries',
-   '                        compilerOptions, .gitignore is left to the root, and the',
-   '                        scripts address the package by --prefix. Errors when no',
-   '                        ancestor declares `workspaces`. Never writes outside the',
-   '                        target — the root `workspaces` entry is printed, not added.',
-   '  --scope <@scope>      npm scope for the package name, e.g. @acme. Not inferred:',
+   '  --monorepo            Scaffold the packages as members of the surrounding npm',
+   '                        workspace, with no root of their own: each tsconfig',
+   '                        extends the root config that actually carries',
+   '                        compilerOptions, and the scripts address the server by',
+   '                        --prefix. Errors when no ancestor declares `workspaces`.',
+   '                        Never writes outside the target — the root `workspaces`',
+   '                        entries and dependency pins are printed, not added.',
+   '  --scope <@scope>      npm scope for the package names, e.g. @acme. Not inferred:',
    '                        a root manifest is usually named for the repo, not the',
    '                        scope. The wizard offers the siblings’ scope as a default.',
-   '  --public              Omit "private": true, so the package can be published.',
-   '                        The scaffold emits it by default, because the manifest',
-   '                        it also emits declares license "UNLICENSED": a package',
-   '                        granting no rights on a public registry contradicts',
-   '                        itself. Pass this once the project has picked a licence.',
+   '                        The VS Code extensions stay unscoped, since vsce',
+   '                        refuses a scoped extension name.',
+   '  --public              Omit "private": true from the server, protocol,',
+   '                        client and Theia extension packages, so they can be',
+   '                        published together; a host package stays private.',
+   '                        The scaffold emits it by default, because the',
+   '                        manifests also declare license "UNLICENSED": a',
+   '                        package granting no rights on a public registry',
+   '                        contradicts itself. Pass this once the project has',
+   '                        picked a licence.',
    '',
    'Grammar options — each applies to the PRECEDING --grammar:',
    '  --grammar <Name>      PascalCase GRAMMAR name; drives the `grammar X` declaration',
@@ -233,8 +273,12 @@ export const INIT_HELP: readonly string[] = [
    '                        (default: <project-id>-<grammar-id>).',
    '  --diagram             Scaffold a GLSP diagram for that grammar. Requires',
    '                        `glsp` in --heads. Derived when there is exactly one',
-   '                        grammar; required when there are several, because a',
-   '                        diagram type binds exactly one grammar.',
+   '                        grammar; required when there are several, because the',
+   '                        scaffolded diagram is typed over one grammar’s model.',
+   '',
+   'Example — one grammar, three heads, in a browser page:',
+   '  hydranium-cli init ./bookstore --name Bookstore --heads lsp,data,glsp \\',
+   '    --hosts browser',
    '',
    'Example — three grammars, one with a differing extension, three heads:',
    '  hydranium-cli init ./order-flow --name OrderFlow --heads lsp,data,glsp \\',
@@ -265,6 +309,7 @@ export async function runInitCommand(args: string[]): Promise<void> {
       name: assertRequired(parsed.name, '--name', 'init'),
       grammars: parsed.grammars,
       heads: parsed.heads,
+      hosts: parsed.hosts,
       force: parsed.force,
       monorepo: parsed.monorepo,
       scope: parsed.scope,