@hydranium/cli 1.0.0-next.413 → 1.0.0-next.418

package/src/commands/init-args.ts

@@ -26,12 +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, 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 {
@@ -47,6 +49,8 @@ export interface ParsedInitArgs {
    name?: string;
    force: boolean;
    install: boolean;
+   skills?: string;
+   agents?: string;
    heads?: InitHead[];
    hosts?: InitHost[];
    monorepo: boolean;
@@ -68,6 +72,8 @@ export const INIT_FLAGS: readonly string[] = [
    '--hosts',
    '--force',
    '--install',
+   '--skills',
+   '--agents',
    '--monorepo',
    '--scope',
    '--public',
@@ -82,6 +88,8 @@ export const INIT_FLAGS: readonly string[] = [
  * The rest are presence-only.
  */
 export const INIT_VALUE_FLAGS: readonly string[] = [
+   '--skills',
+   '--agents',
    '--name',
    '--heads',
    '--hosts',
@@ -107,6 +115,8 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
    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;
@@ -134,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;
@@ -190,7 +206,7 @@ export function parseInitArgs(args: string[], onError: UsageError = exitWithUsag
             }
       }
    }
-   return { targetDir, name, force, install, heads, hosts, monorepo, scope, public: isPublic, grammars };
+   return { targetDir, name, force, install, skills, agents, heads, hosts, monorepo, scope, public: isPublic, grammars };
 }
 
 /**
@@ -216,8 +232,9 @@ export const INIT_HELP: readonly string[] = [
    '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 by default. With --install, runs `npm install` after writing',
-   'the scaffold. Building remains a next step. Refuses a non-empty directory',
+   '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',
@@ -225,6 +242,8 @@ export const INIT_HELP: readonly string[] = [
    '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>          The project directory to scaffold into (required).',
@@ -249,6 +268,12 @@ export const INIT_HELP: readonly string[] = [
    '                        --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.',
+   '  --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.',
@@ -257,7 +282,8 @@ export const INIT_HELP: readonly string[] = [
    '                        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`',
+   '                        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',
@@ -303,20 +329,24 @@ 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'),
@@ -330,4 +360,14 @@ export async function runInitCommand(args: string[]): Promise<void> {
       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-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;
+   }
+}

package/src/commands/init-wizard.ts

@@ -96,6 +96,8 @@ export interface InitAnswers {
    readonly public: boolean;
    /** Run npm install after writing the scaffold. */
    readonly install: boolean;
+   readonly skills?: string;
+   readonly agents?: string;
 }
 
 /** PascalCase a directory name, splitting on any non-alphanumeric run. */
@@ -161,6 +163,9 @@ export function composeInitArgv(answers: InitAnswers): string[] {
    if (answers.install) {
       argv.push('--install');
    }
+   if (answers.skills !== undefined && answers.agents !== undefined) {
+      argv.push('--skills', answers.skills, '--agents', answers.agents);
+   }
    return argv;
 }
 
@@ -358,7 +363,13 @@ async function askPackaging(
 export async function runInitWizard(
    prompt: PromptPort,
    detect: (targetDir: string) => WorkspaceDetection | undefined,
-   options: { readonly targetDir?: string; readonly isOccupied?: (targetDir: string) => boolean; readonly install?: boolean } = {}
+   options: {
+      readonly targetDir?: string;
+      readonly isOccupied?: (targetDir: string) => boolean;
+      readonly install?: boolean;
+      readonly skills?: string;
+      readonly agents?: string;
+   } = {}
 ): Promise<string[]> {
    prompt.intro('Scaffold a Hydranium language project');
 
@@ -413,7 +424,18 @@ export async function runInitWizard(
             initialValue: false
          })));
 
-   const argv = composeInitArgv({ targetDir, name, heads, hosts, grammars: withDiagram, force, install, ...packaging });
+   const argv = composeInitArgv({
+      targetDir,
+      name,
+      heads,
+      hosts,
+      grammars: withDiagram,
+      force,
+      install,
+      skills: options.skills,
+      agents: options.agents,
+      ...packaging
+   });
    // Echoed as the LAST thing before the scaffold runs, because it is the
    // artefact the session produces: everything above is how it was reached.
    prompt.outro(formatCommand(argv));

package/src/commands/init.ts

@@ -715,13 +715,15 @@ export function runInit(options: InitCommandOptions): void {
             `Could not read npm global configuration (${reason}). Scaffold kept at ${targetDir}; installation was not started.`
          );
       }
+      const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => key.toLowerCase() !== 'npm_config_globalconfig'));
+      env.npm_config_globalconfig = globalconfig;
       // An explicit prefix keeps npm from selecting an enclosing workspace instead of this standalone root.
       // Windows resolves npm through a command shim; only fixed arguments reach the shell.
       const result = spawnSync(npm, ['--prefix', '.', 'install'], {
          cwd: targetDir,
          stdio: 'inherit',
          shell: process.platform === 'win32',
-         env: { ...process.env, npm_config_globalconfig: globalconfig }
+         env
       });
       if (result.error || result.signal || result.status !== 0) {
          const reason = result.error?.message ?? (result.signal ? `signal ${result.signal}` : `exit code ${result.status}`);

package/src/commands/skills.ts

@@ -0,0 +1,146 @@
+/********************************************************************************
+ * 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 * as fs from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolve } from 'import-meta-resolve';
+import { parse } from 'yaml';
+
+/** A compatibility result applies to one installed copy, not just its skill name. */
+export interface SkillCompatibility {
+   readonly file: string;
+   readonly status: 'compatible' | 'incompatible' | 'unverified';
+   readonly detail: string;
+}
+
+export const SKILL_DIRECTORIES = ['.agents/skills', '.claude/skills'] as const;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+   return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** Resolve from the adopter, never from a globally installed CLI's dependencies. */
+export function installedPackageManifest(name: string, from: string): Record<string, unknown> | undefined {
+   const parent = path.join(path.resolve(from), 'package.json');
+   let manifest: string;
+   try {
+      manifest = createRequire(parent).resolve(`${name}/package.json`);
+   } catch {
+      try {
+         let directory = path.dirname(fileURLToPath(resolve(name, pathToFileURL(parent).href)));
+         while (true) {
+            const candidate = path.join(directory, 'package.json');
+            if (fs.existsSync(candidate)) {
+               const value: unknown = JSON.parse(fs.readFileSync(candidate, 'utf8'));
+               if (isRecord(value) && value.name === name) {
+                  return value;
+               }
+            }
+            const next = path.dirname(directory);
+            if (next === directory) {
+               return undefined;
+            }
+            directory = next;
+         }
+      } catch {
+         return undefined;
+      }
+   }
+   const value: unknown = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+   return isRecord(value) && value.name === name ? value : undefined;
+}
+
+/** Missing or malformed requirements never constitute evidence of compatibility. */
+export function checkSkill(file: string, from: string): SkillCompatibility {
+   const result = (status: SkillCompatibility['status'], detail: string): SkillCompatibility => ({ file, status, detail });
+   try {
+      const text = fs.readFileSync(file, 'utf8');
+      const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+      const skill: unknown = frontmatter === undefined ? undefined : parse(frontmatter);
+      const metadata = isRecord(skill) ? skill.metadata : undefined;
+      if (!isRecord(metadata) || metadata['hydranium-compatibility-schema'] !== '1') {
+         return result('unverified', 'No supported Hydranium compatibility metadata.');
+      }
+      const encoded = metadata['hydranium-contracts'];
+      const contracts: unknown = typeof encoded === 'string' ? JSON.parse(encoded) : undefined;
+      if (
+         !isRecord(contracts) ||
+         Object.keys(contracts).length === 0 ||
+         Object.entries(contracts).some(
+            ([name, declarations]) =>
+               !/^(@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/.test(name) ||
+               !isRecord(declarations) ||
+               Object.keys(declarations).length === 0 ||
+               Object.entries(declarations).some(
+                  ([contract, revision]) => !contract.trim() || typeof revision !== 'string' || !revision.trim()
+               )
+         )
+      ) {
+         return result('unverified', 'Invalid package contract requirements.');
+      }
+      const problems: string[] = [];
+      const versions: string[] = [];
+      let mismatch = false;
+      for (const [name, requiredContracts] of Object.entries(contracts)) {
+         const manifest = installedPackageManifest(name, from);
+         const version = manifest?.version;
+         const configuration = manifest?.hydranium;
+         const suppliedContracts = isRecord(configuration) ? configuration.skillContracts : undefined;
+         const contractMatches =
+            isRecord(requiredContracts) &&
+            isRecord(suppliedContracts) &&
+            Object.entries(requiredContracts).every(
+               ([contract, revision]) => Object.hasOwn(suppliedContracts, contract) && suppliedContracts[contract] === revision
+            );
+         if (manifest === undefined) {
+            problems.push(`${name} is not installed; install dependencies and retry.`);
+         } else if (!contractMatches) {
+            mismatch = true;
+            problems.push(`${name} does not declare the required skill contracts.`);
+         } else {
+            versions.push(`${name}${typeof version === 'string' ? `@${version}` : ''} (declared skill contract)`);
+         }
+      }
+      return problems.length > 0
+         ? result(mismatch ? 'incompatible' : 'unverified', problems.join(' '))
+         : result('compatible', `Declared requirements satisfied by ${versions.join(', ')}.`);
+   } catch (error) {
+      return result('unverified', error instanceof Error ? error.message : String(error));
+   }
+}
+
+/** Check every selected copy so an outdated agent-specific copy cannot hide behind a shared one. */
+export function checkSkills(project: string, from = project, names?: readonly string[]): SkillCompatibility[] {
+   const results: SkillCompatibility[] = [];
+   const found = new Set<string>();
+   for (const directory of SKILL_DIRECTORIES) {
+      const root = path.join(project, directory);
+      if (!fs.existsSync(root)) {
+         continue;
+      }
+      for (const name of fs.readdirSync(root)) {
+         if (!(names ? names.includes(name) : name.startsWith('hydranium-'))) {
+            continue;
+         }
+         found.add(name);
+         results.push(checkSkill(path.join(root, name, 'SKILL.md'), from));
+      }
+   }
+   for (const name of names ?? []) {
+      if (!found.has(name)) {
+         results.push({ file: name, status: 'unverified', detail: 'Skill is not installed in a checked project directory.' });
+      }
+   }
+   if (results.length === 0) {
+      results.push({ file: project, status: 'unverified', detail: 'No Hydranium project skills found.' });
+   }
+   return results;
+}