@hydranium/cli 1.0.0-next.42 → 1.0.0-next.420

package/src/commands/init-args.ts

@@ -26,11 +26,14 @@
  * association is gone.
  */
 
+import * as path from 'node:path';
 import { assertRequired, exitWithUsage, helpRequested, printHelp, type UsageError } from './harness-args.js';
-import { isNonEmptyDir, runInit, type InitHead } from './init.js';
+import { isNonEmptyDir, runInit, validateInitInstallation, 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';
+import { installSkills, offerSkills, parseSkillInstallation, SKILLS_INSTALLER } from './init-skills.js';
 
 /** One grammar as the command line collected it, before any derivation. */
 export interface ParsedInitGrammar {
@@ -45,7 +48,11 @@ export interface ParsedInitArgs {
    targetDir?: string;
    name?: string;
    force: boolean;
+   install: boolean;
+   skills?: string;
+   agents?: string;
    heads?: InitHead[];
+   hosts?: InitHost[];
    monorepo: boolean;
    scope?: string;
    public: boolean;
@@ -62,7 +69,11 @@ export interface ParsedInitArgs {
 export const INIT_FLAGS: readonly string[] = [
    '--name',
    '--heads',
+   '--hosts',
    '--force',
+   '--install',
+   '--skills',
+   '--agents',
    '--monorepo',
    '--scope',
    '--public',
@@ -76,7 +87,17 @@ 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[] = [
+   '--skills',
+   '--agents',
+   '--name',
+   '--heads',
+   '--hosts',
+   '--scope',
+   '--grammar',
+   '--extensions',
+   '--language-id'
+];
 
 /**
  * Parse `init`'s flags without deciding whether the result is complete.
@@ -93,7 +114,11 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
    let targetDir: string | undefined;
    let name: string | undefined;
    let force = false;
+   let install = false;
+   let skills: string | undefined;
+   let agents: string | undefined;
    let heads: InitHead[] | undefined;
+   let hosts: InitHost[] | undefined;
    let monorepo = false;
    let scope: string | undefined;
    let isPublic = false;
@@ -119,6 +144,12 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
          return current;
       };
       switch (flag) {
+         case '--skills':
+            skills = next();
+            break;
+         case '--agents':
+            agents = next();
+            break;
          case '--name':
             name = next();
             break;
@@ -137,14 +168,20 @@ 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;
+         case '--install':
+            install = true;
+            break;
          case '--monorepo':
             monorepo = true;
             break;
@@ -169,7 +206,7 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
             }
       }
    }
-   return { targetDir, name, force, heads, monorepo, scope, public: isPublic, grammars };
+   return { targetDir, name, force, install, skills, agents, heads, hosts, monorepo, scope, public: isPublic, grammars };
 }
 
 /**
@@ -180,46 +217,87 @@ 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] [--install]',
    '                            ( --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.',
+   'Stays offline unless --install or --skills is requested. With --install,',
+   'runs `npm install` after writing the scaffold. Building remains a next step.',
+   '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.',
+   'For a standalone project, the wizard ends by offering npm install unless',
+   '--install already requested it.',
+   'After a successful scaffold, the wizard offers coding-agent skills separately.',
+   'Skipping or cancelling that offer leaves the scaffold intact.',
    '',
    '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:',
+   '  --skills <names>      After scaffolding, install named skills: hydranium-profiling,',
+   `                        langium. Requires --agents. Downloads with npx ${SKILLS_INSTALLER} add`,
+   '                        --copy, preserving unrelated skills and lock entries.',
+   '                        With --monorepo, skills are written at the workspace root.',
+   '  --agents <names>      Comma-separated agents for --skills: codex, claude-code,',
+   '                        cursor, github-copilot, opencode.',
+   '  --install             Run npm install in the scaffold, with lifecycle scripts',
+   '                        and network access. Cannot be combined with --monorepo:',
+   '                        its parent manifest needs manual edits first.',
+   '  --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`.',
+   '                        Scaffold files stay inside the target; optional skills',
+   '                        go at the workspace root. 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 +311,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 \\',
@@ -247,27 +329,45 @@ export async function runInitCommand(args: string[]): Promise<void> {
       printHelp(INIT_HELP);
       return;
    }
-   const parsed = parseInitArgs(args);
+   let parsed = parseInitArgs(args);
+   validateInitInstallation(parsed);
+   let selection = parseSkillInstallation(parsed.skills, parsed.agents);
+   let prompt: Awaited<ReturnType<typeof createClackPrompt>> | undefined;
    // The wizard's entry point: no `--name` on an interactive terminal. Safe
    // because that combination has no non-wizard meaning, and gated on a TTY
    // because a non-interactive caller must keep failing fast — a prompt in CI
    // hangs the job instead of reporting the missing flag.
    if (parsed.name === undefined && process.stdin.isTTY && process.stdout.isTTY) {
-      const prompt = await createClackPrompt();
+      prompt = await createClackPrompt();
       const argv = await runInitWizard(prompt, targetDir => detectWorkspace(targetDir, createNodeWorkspaceProbe()), {
          targetDir: parsed.targetDir,
+         install: parsed.install,
+         skills: parsed.skills,
+         agents: parsed.agents,
          isOccupied: isNonEmptyDir
       });
-      return runInitCommand(argv);
+      parsed = parseInitArgs(argv);
    }
    runInit({
       targetDir: assertRequired(parsed.targetDir, '<target-dir>', 'init'),
       name: assertRequired(parsed.name, '--name', 'init'),
       grammars: parsed.grammars,
       heads: parsed.heads,
+      hosts: parsed.hosts,
       force: parsed.force,
+      install: parsed.install,
       monorepo: parsed.monorepo,
       scope: parsed.scope,
       public: parsed.public
    });
+   const target = path.resolve(parsed.targetDir!);
+   const project = parsed.monorepo ? detectWorkspace(target, createNodeWorkspaceProbe())!.rootDir : target;
+   if (selection === undefined && prompt !== undefined) {
+      selection = await offerSkills(prompt, project);
+   }
+   if (selection !== undefined) {
+      installSkills(project, path.join(target, 'server'), selection);
+   } else {
+      process.stdout.write('\nOptional agent skills: see the Work with coding-agent skills guide.\n');
+   }
 }

package/src/commands/init-hosts.ts

@@ -0,0 +1,51 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+/**
+ * The host applications `init` can emit around the server: each holds the
+ * clients of the heads it runs, in a sibling package of its own.
+ */
+
+import type { InitHead } from './init.js';
+
+/** The hosts a scaffold can emit, in the order a workspace lists them. */
+export const INIT_HOSTS = ['browser', 'vscode', 'theia-browser', 'theia-electron'] as const;
+
+/** One host application — see {@link INIT_HOSTS}. */
+export type InitHost = (typeof INIT_HOSTS)[number];
+
+/**
+ * The heads a host needs at least one of: those whose client edits and saves
+ * the files. The browser page has no filesystem of its own, so it saves through
+ * the LSP head's editor or the GLSP head's diagram. VS Code and Theia own the
+ * files and reach the server through a language client, so they need the LSP
+ * head. Every other head is optional, and a head the host does not know is left
+ * unused.
+ */
+const EDITING_HEADS: Record<InitHost, readonly InitHead[]> = {
+   browser: ['lsp', 'glsp'],
+   vscode: ['lsp'],
+   'theia-browser': ['lsp'],
+   'theia-electron': ['lsp']
+};
+
+/** True for a string naming one of {@link INIT_HOSTS}. */
+export function isInitHost(value: string): value is InitHost {
+   return (INIT_HOSTS as readonly string[]).includes(value);
+}
+
+/** True for a host that is a Theia application, which runs the Theia extension. */
+export function isTheiaHost(host: InitHost): boolean {
+   return host === 'theia-browser' || host === 'theia-electron';
+}
+
+/** The heads {@link host} needs at least one of in the composition. */
+export function editingHeads(host: InitHost): readonly InitHead[] {
+   return EDITING_HEADS[host];
+}

package/src/commands/init-prompt.ts

@@ -66,7 +66,7 @@ export interface PromptPort {
       readonly choices: ReadonlyArray<PromptChoice<Value>>;
       readonly initialValue?: Value;
    }) => Promise<Value>;
-   /** Ask for any number of several choices, including none. */
+   /** Ask for at least one of several choices. */
    readonly multiselect: <Value extends string>(options: {
       readonly message: string;
       readonly choices: ReadonlyArray<PromptChoice<Value>>;
@@ -78,8 +78,9 @@ export interface PromptPort {
    readonly outro: (message: string) => void;
 }
 
-/** The optional heads, as a checkbox list. `lsp` is not offered — see `askHeads`. */
-export const OPTIONAL_HEAD_CHOICES: ReadonlyArray<PromptChoice<Exclude<InitHead, 'lsp'>>> = [
+/** The heads, as a checkbox list. */
+export const HEAD_CHOICES: ReadonlyArray<PromptChoice<InitHead>> = [
+   { value: 'lsp', label: 'lsp', hint: 'text editing in an LSP client' },
    { value: 'data', label: 'data', hint: 'typed JSON-RPC for forms, trees and code-gen' },
    { value: 'glsp', label: 'glsp', hint: 'graphical editing; adds a scaffolded diagram' }
 ];
@@ -138,9 +139,7 @@ export async function createClackPrompt(): Promise<PromptPort> {
                message: options.message,
                options: toOptions(options.choices),
                initialValues: options.initialValues ? [...options.initialValues] : [],
-               // Legal and meaningful: an `lsp`-only project is a plain LSP
-               // server, so an empty selection must not be rejected.
-               required: false
+               required: true
             })
          ),
       confirm: async options => unwrap(await clack.confirm({ message: options.message, initialValue: options.initialValue })),

package/src/commands/init-skills.ts

@@ -0,0 +1,129 @@
+/********************************************************************************
+ * 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
+ ********************************************************************************/
+
+import { spawnSync } from 'node:child_process';
+import * as path from 'node:path';
+import { InitWizardCancelled, type PromptPort } from './init-prompt.js';
+import { checkSkills } from './skills.js';
+
+export const SKILLS_INSTALLER = 'skills@1.7.6';
+
+export const ADOPTER_SKILLS = {
+   'hydranium-profiling': { source: 'eclipse-emfcloud/hydranium', label: 'Hydranium profiling' },
+   langium: { source: 'eclipse-langium/langium-ai', label: 'Langium grammar and runtime' }
+} as const;
+
+export type AdopterSkill = keyof typeof ADOPTER_SKILLS;
+
+export const SKILL_AGENTS = {
+   codex: 'Codex',
+   'claude-code': 'Claude Code',
+   cursor: 'Cursor',
+   'github-copilot': 'GitHub Copilot',
+   opencode: 'OpenCode'
+} as const;
+
+export type SkillAgent = keyof typeof SKILL_AGENTS;
+
+export interface SkillInstallation {
+   readonly skills: readonly AdopterSkill[];
+   readonly agents: readonly SkillAgent[];
+}
+
+/** Validate before scaffolding so a misspelling cannot leave a half-completed command. */
+export function parseSkillInstallation(skills?: string, agents?: string): SkillInstallation | undefined {
+   if (skills === undefined && agents === undefined) {
+      return undefined;
+   }
+   if (!skills || !agents) {
+      throw new Error('--skills and --agents must be supplied together.');
+   }
+   const selectedSkills = skills.split(',');
+   const selectedAgents = agents.split(',');
+   for (const name of selectedSkills) {
+      if (!Object.hasOwn(ADOPTER_SKILLS, name)) {
+         throw new Error(`Unknown skill '${name}'. Choose ${Object.keys(ADOPTER_SKILLS).join(', ')}.`);
+      }
+   }
+   for (const name of selectedAgents) {
+      if (!Object.hasOwn(SKILL_AGENTS, name)) {
+         throw new Error(`Unknown agent '${name}'. Choose ${Object.keys(SKILL_AGENTS).join(', ')}.`);
+      }
+   }
+   return { skills: [...new Set(selectedSkills)] as AdopterSkill[], agents: [...new Set(selectedAgents)] as SkillAgent[] };
+}
+
+export function skillInstallArgs(skill: AdopterSkill, agents: readonly SkillAgent[]): string[] {
+   return ['--yes', SKILLS_INSTALLER, 'add', ADOPTER_SKILLS[skill].source, '--skill', skill, '--agent', ...agents, '--copy', '--yes'];
+}
+
+/** A failed optional download leaves the scaffold usable and gives an independently runnable retry. */
+export function installSkills(
+   project: string,
+   from: string,
+   selection: SkillInstallation,
+   write: (message: string) => void = message => process.stdout.write(message)
+): void {
+   for (const skill of selection.skills) {
+      const args = skillInstallArgs(skill, selection.agents);
+      write(`\nIn ${project}: npx ${args.join(' ')}\n`);
+      try {
+         // Only catalogued names reach the Windows shim's shell; paths travel as cwd, never shell text.
+         const result = spawnSync(process.platform === 'win32' ? 'npx.cmd' : 'npx', args, {
+            cwd: project,
+            stdio: 'inherit',
+            shell: process.platform === 'win32'
+         });
+         if (result.signal === 'SIGINT' || result.status === 130) {
+            write('Skill installation cancelled. Scaffold kept.\n');
+            return;
+         }
+         if (result.error || result.signal || result.status !== 0) {
+            throw result.error ?? new Error(result.signal ?? `exit code ${result.status}`);
+         }
+         for (const result of checkSkills(project, from, [skill])) {
+            write(`${result.status}: ${result.file}: ${result.detail}\n`);
+         }
+      } catch (error) {
+         write(`Skill installation failed (${error instanceof Error ? error.message : String(error)}). Scaffold kept.\n`);
+         write(`Retry in ${project}: npx ${args.join(' ')}\n`);
+      }
+   }
+   const relative = path.relative(project, from) || '.';
+   const quoted = `'${relative.replace(/'/g, "'\\''")}'`;
+   write(`Check again after installing or updating dependencies: npx hydranium-cli check-skills --from ${quoted}\n`);
+}
+
+/** This prompt runs only after the scaffold succeeds; cancelling it cannot undo the scaffold. */
+export async function offerSkills(prompt: PromptPort, project: string): Promise<SkillInstallation | undefined> {
+   try {
+      prompt.intro('Optional coding-agent skills');
+      if (!(await prompt.confirm({ message: `Install coding-agent skills in ${project}?`, initialValue: false }))) {
+         prompt.outro('Skills skipped.');
+         return undefined;
+      }
+      const skills = await prompt.multiselect<AdopterSkill>({
+         message: 'Skills to install',
+         choices: Object.entries(ADOPTER_SKILLS).map(([value, skill]) => ({ value: value as AdopterSkill, label: skill.label })),
+         initialValues: ['hydranium-profiling', 'langium']
+      });
+      const agents = await prompt.multiselect<SkillAgent>({
+         message: 'Coding agents',
+         choices: Object.entries(SKILL_AGENTS).map(([value, label]) => ({ value: value as SkillAgent, label }))
+      });
+      prompt.outro('Installing selected skills as project files. Commit the files and skills-lock.json.');
+      return { skills, agents };
+   } catch (error) {
+      if (error instanceof InitWizardCancelled) {
+         prompt.outro('Skills skipped. Scaffold kept.');
+         return undefined;
+      }
+      throw error;
+   }
+}