@dolphy-app/create-extension 0.2.0 → 0.3.0

package/README.md

@@ -1,23 +1,25 @@
 # @dolphy-app/create-extension
 
-Генератор проекта расширения: create-dolphy-extension <каталог>
+Extension project generator: create-dolphy-extension <directory>
 
-Версия пакетов равна версии приложения Dolphy, из релиза которого они опубликованы (0.2.0).
+The package version equals the version of the Dolphy app release it was published from (0.3.0).
 
-Генератор проекта расширения.
+Generator of an extension project: `src/index.ts` with the host and a
+view, a manifest, tests, and typed ids (`.dolphy/ids.d.ts`, generated from
+`extension.json`).
 
 ```sh
-npx @dolphy-app/create-extension <каталог>
+npx @dolphy-app/create-extension <directory>
 ```
 
-Проект получает тесты, сборку и README.
+The project gets tests, a build and a README.
 
-## Установка
+## Installation
 
 ```sh
 npm install @dolphy-app/create-extension
 ```
 
-## Документация
+## Documentation
 
-[Расширения Dolphy](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).
+[Dolphy extensions](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).

package/dist/cli/main.js

@@ -4,12 +4,39 @@ import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
 
 //#region packages/extension-api/src/index.ts
 const EXTENSION_ID_PATTERN = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
-/** Тег элемента по умолчанию: `dolphy.sql` → `dolphy-sql-answer`. */
-const defaultElementName = (id) => `${id.replaceAll(".", "-")}-answer`;
+/** Limits on commands and panels (R1, R3); they match those checked by the manifest, host, and engine. */
+const EXTENSION_COMMAND_LIMITS = Object.freeze({
+	/** Commands per extension. */
+	commands: 64,
+	/** Panels per extension. */
+	panels: 8,
+	titleLength: 60,
+	categoryLength: 40,
+	descriptionLength: 200,
+	/** `JSON.stringify(args).length` at the engine boundary. */
+	argsChars: 2e5,
+	/** JSON text of the result in UTF-8 bytes. */
+	resultBytes: 65536,
+	/** Length of `notify` in UTF-16 code units. */
+	notifyChars: 500,
+	/** Handler budget, ms. */
+	handlerMs: 1e4
+});
+/** Extension storage limits (R2); they match the engine's limits, which enforces them. */
+const EXTENSION_STORAGE_LIMITS = Object.freeze({
+	/** Key length in UTF-16 code units. */
+	keyLength: 128,
+	/** JSON text of a single value in UTF-8 bytes. */
+	valueBytes: 65536,
+	/** Number of keys. */
+	keys: 256,
+	/** Sum of JSON texts of all values in UTF-8 bytes. */
+	totalBytes: 1048576
+});
 
 //#endregion
 //#region packages/create-extension/src/template.ts
-/** Версия расширения в шаблоне и его умолчание для `apiVersion`. */
+/** Extension version in the template and its default for `apiVersion`. */
 const INITIAL_VERSION = "0.1.0";
 const lines = (parts) => `${parts.join("\n")}\n`;
 const packageJson = ({ id, dependencies }) => `${JSON.stringify({
@@ -20,6 +47,8 @@ const packageJson = ({ id, dependencies }) => `${JSON.stringify({
 	scripts: {
 		build: "dolphy-ext build",
 		dev: "dolphy-ext build --watch",
+		types: "dolphy-ext types",
+		typecheck: "dolphy-ext types && tsc",
 		validate: `dolphy-ext validate dist-ext/${id}`,
 		test: "vitest run"
 	},
@@ -48,13 +77,14 @@ const tsconfigJson = () => lines([
 	"    \"skipLibCheck\": true,",
 	"    \"noEmit\": true",
 	"  },",
-	"  \"include\": [\"src\", \"test\"]",
+	"  \"include\": [\"src\", \"test\", \".dolphy/ids.d.ts\"]",
 	"}"
 ]);
 const manifestJson = (id) => `{
   "id": "${id}",
   "version": "${INITIAL_VERSION}",
   "apiVersion": 1,
+  "tags": ["learning"],
   "contributes": {
     "exerciseTypes": [
       {
@@ -70,26 +100,53 @@ const manifestJson = (id) => `{
         },
         "answerSchema": { "type": "string" }
       }
+    ],
+    "settings": [
+      {
+        "id": "${id}.trim",
+        "type": "boolean",
+        "label": "Ignore spaces around the answer",
+        "default": true
+      }
+    ],
+    "commands": [
+      { "id": "${id}.status", "title": "Show how answers are compared" }
     ]
   }
 }
 `;
-const mainTs = (id) => `import { defineExerciseType, defineExtension } from '@dolphy-app/extension-sdk';
+const indexTs = (id) => `import {
+  defineAnswerView,
+  defineExerciseType,
+  defineExtension,
+  inActivate,
+  notify,
+} from '@dolphy-app/extension-sdk';
+import type { ExtensionViews } from '@dolphy-app/extension-sdk';
 
 interface Spec {
   expected: string;
   ignoreCase?: boolean;
 }
 
+// filled from the setting in \`activate\`, read by the handlers below
+const options = { trim: true };
+
 const matches = (answer: string, spec: Spec): boolean => {
+  const given = options.trim ? answer.trim() : answer;
   if (spec.ignoreCase === true) {
-    return answer.toLowerCase() === spec.expected.toLowerCase();
+    return given.toLowerCase() === spec.expected.toLowerCase();
   }
-  return answer === spec.expected;
+  return given === spec.expected;
 };
 
-// схемы из extension.json уже проверили spec и ответ до вызова обработчиков
-export default defineExtension({
+// extension code: runs in the extension process of the app
+// the schemas from extension.json have already checked \`spec\` and the answer
+// before the handlers run
+// the ids come from extension.json: \`dolphy-ext types\` (and every build)
+// writes them to .dolphy/ids.d.ts, so a misspelt id, a declared id without a
+// handler or an undeclared setting fails \`pnpm typecheck\`
+export const host = defineExtension({
   exerciseTypes: {
     '${id}': defineExerciseType<Spec, string, Record<string, never>>({
       project: () => ({}),
@@ -100,50 +157,72 @@ export default defineExtension({
       referenceAnswer: ({ spec }) => spec.expected,
     }),
   },
+  // this command is registered in \`activate\`: the marker names the id there
+  commands: { '${id}.status': inActivate },
+  activate(ctx) {
+    options.trim = ctx.settings.get('${id}.trim');
+    ctx.settings.onDidChange((change) => {
+      if (change.id === '${id}.trim') options.trim = change.value;
+    });
+    ctx.commands.register('${id}.status', () =>
+      notify(
+        options.trim
+          ? 'Answers are compared without the spaces around them.'
+          : 'Answers are compared exactly as typed.',
+      ),
+    );
+  },
 });
+
+// the answer input: runs in the app window; the build defines the custom
+// element with the tag from extension.json
+export const views = {
+  '${id}': defineAnswerView((api, initial) => {
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.spellcheck = false;
+    if (api.label !== null) input.setAttribute('aria-label', api.label);
+
+    const applyValue = (value: unknown) => {
+      input.value = typeof value === 'string' ? value : '';
+    };
+    let appliedValue = initial.value;
+    applyValue(appliedValue);
+    input.disabled = initial.disabled;
+
+    input.addEventListener('input', () => {
+      api.setAnswer(input.value, input.value.trim().length > 0);
+    });
+    input.addEventListener('keydown', (event) => {
+      if (event.key === 'Enter') api.submit();
+    });
+    api.root.append(input);
+
+    return {
+      update: (props) => {
+        input.disabled = props.disabled;
+        // apply the value only when the app really changed it
+        if (props.value !== appliedValue) {
+          appliedValue = props.value;
+          applyValue(appliedValue);
+        }
+      },
+    };
+  }),
+} satisfies ExtensionViews;
 `;
-const viewTs = (id) => `import { defineAnswerElement } from '@dolphy-app/extension-sdk';
-
-defineAnswerElement('${defaultElementName(id)}', (api, initial) => {
-  const input = document.createElement('input');
-  input.type = 'text';
-  input.spellcheck = false;
-  if (api.label !== null) input.setAttribute('aria-label', api.label);
-
-  const applyValue = (value: unknown) => {
-    input.value = typeof value === 'string' ? value : '';
-  };
-  let appliedValue = initial.value;
-  applyValue(appliedValue);
-  input.disabled = initial.disabled;
-
-  input.addEventListener('input', () => {
-    api.setAnswer(input.value, input.value.trim().length > 0);
-  });
-  input.addEventListener('keydown', (event) => {
-    if (event.key === 'Enter') api.submit();
-  });
-  api.root.append(input);
-
-  return {
-    update: (props) => {
-      input.disabled = props.disabled;
-      // value применяется, только когда приложение его действительно сменило
-      if (props.value !== appliedValue) {
-        appliedValue = props.value;
-        applyValue(appliedValue);
-      }
-    },
-  };
-});
-`;
-const mainTestTs = (id) => `import {
+const indexTestTs = (id) => `// @vitest-environment happy-dom
+import type { SettingContribution } from '@dolphy-app/extension-sdk';
+import {
+  createMemorySettings,
   createSchemaValidator,
+  loadCommands,
   loadExerciseType,
+  loadView,
 } from '@dolphy-app/extension-sdk/testing';
 import { afterEach, describe, expect, it } from 'vitest';
 import manifest from '../extension.json';
-import module from '../src/main.ts';
+import { host, views } from '../src/index.ts';
 
 const [contribution] = manifest.contributes.exerciseTypes;
 const validateSpec = createSchemaValidator(contribution.specSchema);
@@ -151,24 +230,35 @@ const validateAnswer = createSchemaValidator(contribution.answerSchema);
 
 const spec = { expected: 'Hello' };
 
-const disposables: { dispose(): Promise<void> }[] = [];
+const disposables: { dispose(): unknown }[] = [];
 afterEach(async () => {
   await Promise.all(disposables.splice(0).map((item) => item.dispose()));
 });
 
-const load = async () => {
-  const type = await loadExerciseType(module, '${id}');
+const newSettings = () =>
+  createMemorySettings(manifest.contributes.settings as SettingContribution[]);
+
+const load = async (settings = newSettings()) => {
+  const type = await loadExerciseType(host, '${id}', { settings });
   disposables.push(type);
   return type;
 };
 
-describe('${id}: обработчик', () => {
-  it('project не раскрывает эталон', async () => {
+const mount = async (label?: string) => {
+  const view = await loadView(views, '${id}', label === undefined ? {} : { label });
+  disposables.push(view);
+  const input = view.query<HTMLInputElement>('input');
+  if (input === null) throw new Error('no input');
+  return { view, input };
+};
+
+describe('${id}: handler', () => {
+  it('project does not reveal the reference', async () => {
     const type = await load();
     expect(await type.project(spec)).toEqual({});
   });
 
-  it('grade: совпадение засчитывается, расхождение нет', async () => {
+  it('grade: a match passes, a mismatch does not', async () => {
     const type = await load();
     expect(await type.grade({ spec, answer: 'Hello' })).toEqual({
       outcome: 'passed',
@@ -179,7 +269,7 @@ describe('${id}: обработчик', () => {
     });
   });
 
-  it('grade: ignoreCase отключает различие регистров', async () => {
+  it('grade: ignoreCase turns case sensitivity off', async () => {
     const type = await load();
     const relaxed = { ...spec, ignoreCase: true };
     expect(await type.grade({ spec: relaxed, answer: 'hELLO' })).toEqual({
@@ -187,7 +277,7 @@ describe('${id}: обработчик', () => {
     });
   });
 
-  it('referenceAnswer сам проходит проверку', async () => {
+  it('referenceAnswer passes the check itself', async () => {
     const type = await load();
     const reference = await type.referenceAnswer(spec);
     expect(reference).toEqual({ found: true, answer: 'Hello' });
@@ -198,158 +288,166 @@ describe('${id}: обработчик', () => {
   });
 });
 
-describe('${id}: схемы', () => {
+describe('${id}: settings and commands', () => {
+  it('the trim setting decides whether the spaces around an answer count', async () => {
+    const settings = newSettings();
+    const type = await load(settings);
+    expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
+      outcome: 'passed',
+    });
+    await settings.set('${id}.trim', false);
+    expect(await type.grade({ spec, answer: ' Hello ' })).toEqual({
+      outcome: 'failed',
+      reason: 'mismatch',
+    });
+  });
+
+  it('the status command reports the current mode', async () => {
+    const settings = newSettings();
+    const commands = await loadCommands(host, {
+      declaredCommands: ['${id}.status'],
+      settings,
+    });
+    disposables.push(commands);
+    expect(await commands.run('${id}.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared without the spaces around them.',
+    });
+    await settings.set('${id}.trim', false);
+    expect(await commands.run('${id}.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared exactly as typed.',
+    });
+  });
+});
+
+describe('${id}: schemas', () => {
   it.each([[{ expected: 'a' }], [{ expected: 'a', ignoreCase: true }]])(
-    'spec %j допустим',
+    'spec %j is valid',
     (value) => {
       expect(validateSpec(value)).toEqual([]);
     },
   );
 
   it.each([
-    ['нет expected', {}],
-    ['пустой expected', { expected: '' }],
-    ['ignoreCase не boolean', { expected: 'a', ignoreCase: 'yes' }],
-    ['лишнее поле', { expected: 'a', extra: 1 }],
-  ])('spec: %s отклоняется', (_name, value) => {
+    ['no expected', {}],
+    ['empty expected', { expected: '' }],
+    ['ignoreCase is not a boolean', { expected: 'a', ignoreCase: 'yes' }],
+    ['an extra field', { expected: 'a', extra: 1 }],
+  ])('spec: %s is rejected', (_name, value) => {
     expect(validateSpec(value)).not.toEqual([]);
   });
 
-  it('answer: строка допустима, число нет', () => {
+  it('answer: a string is valid, a number is not', () => {
     expect(validateAnswer('text')).toEqual([]);
     expect(validateAnswer(42)).not.toEqual([]);
   });
 });
-`;
-const viewTestTs = (id) => {
-	const tag = defaultElementName(id);
-	return `// @vitest-environment happy-dom
-import { ANSWER_EVENT } from '@dolphy-app/extension-sdk';
-import type { AnswerChangeDetail } from '@dolphy-app/extension-sdk';
-import { afterEach, describe, expect, it } from 'vitest';
-import '../src/view.ts';
-
-interface AnswerElement extends HTMLElement {
-  view: unknown;
-  value: unknown;
-  disabled: boolean;
-}
-
-const flush = () => Promise.resolve();
-
-const mountElement = async (label: string | null = null) => {
-  const element = document.createElement('${tag}') as AnswerElement;
-  if (label !== null) element.setAttribute('aria-label', label);
-  document.body.append(element);
-  await flush();
-  const changes: AnswerChangeDetail[] = [];
-  element.addEventListener(ANSWER_EVENT.change, (event) => {
-    changes.push((event as CustomEvent<AnswerChangeDetail>).detail);
-  });
-  const input = element.shadowRoot?.querySelector('input');
-  if (input === null || input === undefined) throw new Error('no input');
-  return { element, input, changes };
-};
-
-afterEach(() => {
-  document.body.replaceChildren();
-});
 
-describe('${tag}', () => {
-  it('ввод текста сообщает ответ; пустой ввод неполный', async () => {
-    const { input, changes } = await mountElement();
+describe('${id}: view', () => {
+  it('typing reports the answer; an empty input is incomplete', async () => {
+    const { view, input } = await mount();
     input.value = 'Hello';
     input.dispatchEvent(new Event('input'));
     input.value = '  ';
     input.dispatchEvent(new Event('input'));
-    expect(changes).toEqual([
+    expect(view.changes).toEqual([
       { value: 'Hello', complete: true },
       { value: '  ', complete: false },
     ]);
   });
 
-  it('Enter отправляет ответ', async () => {
-    const { element, input } = await mountElement();
-    let submits = 0;
-    element.addEventListener(ANSWER_EVENT.submit, () => void (submits += 1));
+  it('Enter submits the answer', async () => {
+    const { view, input } = await mount();
     input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
-    expect(submits).toBe(1);
+    expect(view.submissions).toBe(1);
   });
 
-  it('disabled блокирует поле', async () => {
-    const { element, input } = await mountElement();
-    element.disabled = true;
-    await flush();
+  it('disabled blocks the input', async () => {
+    const { view, input } = await mount();
+    await view.update({ disabled: true });
     expect(input.disabled).toBe(true);
   });
 
-  it('value восстанавливает ответ без событий', async () => {
-    const { element, input, changes } = await mountElement();
-    element.value = 'Hello';
-    await flush();
+  it('value restores the answer without events', async () => {
+    const { view, input } = await mount();
+    await view.update({ value: 'Hello' });
     expect(input.value).toBe('Hello');
-    expect(changes).toEqual([]);
+    expect(view.changes).toEqual([]);
   });
 
-  it('aria-label хоста попадает на поле', async () => {
-    const { input } = await mountElement('Ваш ответ');
-    expect(input.getAttribute('aria-label')).toBe('Ваш ответ');
+  it('the aria-label of the host goes to the input', async () => {
+    const { input } = await mount('Your answer');
+    expect(input.getAttribute('aria-label')).toBe('Your answer');
   });
 });
 `;
-};
 const readme = (id) => lines([
 	`# ${id}`,
 	"",
-	"Расширение Dolphy: вид задания «text match» (ученик вводит строку, она",
-	"сравнивается с `spec.expected`). Сгенерировано `create-dolphy-extension`.",
+	"A Dolphy extension: the \"text match\" exercise type (the learner types a",
+	"string, it is compared with `spec.expected`), a setting and a command.",
+	"Generated by `create-dolphy-extension`.",
 	"",
-	"## Раскладка",
+	"## Layout",
 	"",
-	"- `extension.json` — манифест (схемы `spec` и ответа записаны прямо в нём);",
-	"- `src/main.ts` — код расширения: `defineExtension` + `defineExerciseType`;",
-	"- `src/view.ts` — элемент ввода ответа: `defineAnswerElement`;",
-	"- `test/` — тесты обработчика и элемента (`vitest`, `happy-dom`).",
+	"- `extension.json` — the manifest (the `spec` and answer schemas are written",
+	"  in it);",
+	"- `src/index.ts` — all the extension code: `host` (`defineExtension` +",
+	"  `defineExerciseType`) and `views` (`defineAnswerView`); the build splits",
+	"  it into `main.mjs` and `view.mjs`;",
+	"- `.dolphy/ids.d.ts` — generated from `extension.json` by",
+	"  `dolphy-ext types` (and by every build): the ids the manifest declares,",
+	"  as TypeScript types. Not committed. A misspelt id, a declared id without",
+	"  a handler or a view, or `ctx.settings.get` of an undeclared setting fails",
+	"  `pnpm typecheck`;",
+	"- `test/index.test.ts` — tests (`vitest`, `happy-dom`).",
 	"",
-	"## Цикл разработки",
+	"## Development loop",
 	"",
 	"```sh",
 	"pnpm install",
-	`pnpm dev # dolphy-ext build --watch: пересборка в dist-ext/${id}`,
+	`pnpm dev # dolphy-ext build --watch: rebuilds into dist-ext/${id}`,
 	"```",
 	"",
-	"Запустите приложение с корнем режима разработчика — каталогом `dist-ext`",
-	"этого проекта (абсолютный путь):",
+	"Start the app with the developer root pointing at the `dist-ext` directory",
+	"of this project (an absolute path):",
 	"",
 	"```sh",
-	"DOLPHY_DEV_EXTENSIONS=<путь к проекту>/dist-ext pnpm dev # из репозитория Dolphy",
+	"DOLPHY_DEV_EXTENSIONS=<path to the project>/dist-ext pnpm dev # from the Dolphy repository",
 	"```",
 	"",
-	"Правка файла в `dist-ext` перезапускает хосты и перезагружает окно.",
-	"Ошибки загрузки видны в «Настройки → Расширения».",
+	"A change to a file in `dist-ext` is applied live: the window does not",
+	"reload, mounted answer inputs are recreated. Load errors are shown in",
+	"\"Settings → Extensions\".",
 	"",
-	"## Сборка, проверка, тесты",
+	"## Build, check, test",
 	"",
 	"```sh",
-	`pnpm build     # dist-ext/${id}`,
-	"pnpm validate  # тот же разбор манифеста, что делает приложение",
+	`pnpm build      # dist-ext/${id}`,
+	"pnpm validate   # the same manifest parsing the app does",
+	"pnpm typecheck  # writes .dolphy/ids.d.ts, then tsc",
 	"pnpm test",
 	"```",
 	"",
-	"## Установка вручную",
+	"## Manual installation",
 	"",
-	`Скопируйте каталог \`dist-ext/${id}\` в \`<userData>/extensions/\``,
-	"и перезапустите приложение. Установки из приложения пока нет."
+	`Copy the \`dist-ext/${id}\` directory to \`<userData>/extensions/\``,
+	"and restart the app. There is no installation from the app yet."
+]);
+const gitignore = () => lines([
+	"node_modules",
+	"dist-ext",
+	".dolphy"
 ]);
-const gitignore = () => lines(["node_modules", "dist-ext"]);
 
 //#endregion
 //#region packages/create-extension/src/generate.ts
-/** Совпадает с ограничением манифеста (`parseManifest`). */
+/** Matches the manifest limit (`parseManifest`). */
 const MAX_ID_CHARS = 64;
-/** Без сборки (исходники, `--local`) версия пакетов условная. */
+/** Without a build (sources, `--local`) the package version is a placeholder. */
 const UNPUBLISHED_VERSION = "^0.0.0";
-const builtPackageVersion = () => "0.2.0";
+const builtPackageVersion = () => "0.3.0";
 var GenerateError = class extends Error {
 	code;
 	constructor(code, message) {
@@ -395,17 +493,15 @@ const assertEmpty = async (dir) => {
 	if (info === null) return;
 	if ((info.isDirectory() ? await readdir(dir) : ["(file)"]).length > 0) throw new GenerateError("target-not-empty", `${dir} is not empty`);
 };
-/** Файлы проекта: относительный путь → содержимое. */
+/** Project files: relative path → content. */
 const renderProject = (input) => {
 	const { id } = input;
 	return /* @__PURE__ */ new Map([
 		["package.json", packageJson(input)],
 		["tsconfig.json", tsconfigJson()],
 		["extension.json", manifestJson(id)],
-		["src/main.ts", mainTs(id)],
-		["src/view.ts", viewTs(id)],
-		["test/main.test.ts", mainTestTs(id)],
-		["test/view.test.ts", viewTestTs(id)],
+		["src/index.ts", indexTs(id)],
+		["test/index.test.ts", indexTestTs(id)],
 		["README.md", readme(id)],
 		[".gitignore", gitignore()]
 	]);
@@ -441,11 +537,11 @@ const EXIT_PROBLEMS = 1;
 const EXIT_USAGE = 2;
 const USAGE = `usage: create-dolphy-extension <dir> [--id <id>] [--local <repoRoot>]
 
-  <dir>              каталог нового проекта (должен быть пуст или отсутствовать)
-  --id <id>          id расширения (по умолчанию — kebab-case имени каталога)
-  --local <repoRoot> корень репозитория Dolphy: @dolphy-app/extension-sdk и
-                     @dolphy-app/extension-tools подключаются как link:<repoRoot>/packages/...
-  --help             эта справка
+  <dir>              new project directory (must be empty or not exist)
+  --id <id>          extension id (default: kebab-case of the directory name)
+  --local <repoRoot> Dolphy repository root: @dolphy-app/extension-sdk and
+                     @dolphy-app/extension-tools are linked as link:<repoRoot>/packages/...
+  --help             show this help
 `;
 const parseArgs = (argv) => {
 	if (argv.includes("--help") || argv.includes("-h")) return { help: true };
@@ -455,40 +551,40 @@ const parseArgs = (argv) => {
 		const arg = argv[i];
 		if (arg === "--id" || arg === "--local") {
 			const value = argv[++i];
-			if (value === void 0) return { usageError: `${arg} требует значение` };
+			if (value === void 0) return { usageError: `${arg} requires a value` };
 			values.set(arg, value);
-		} else if (arg.startsWith("-")) return { usageError: `неизвестный флаг: ${arg}` };
+		} else if (arg.startsWith("-")) return { usageError: `unknown flag: ${arg}` };
 		else positional.push(arg);
 	}
 	const [dir, ...extra] = positional;
-	if (dir === void 0) return { usageError: "не указан каталог" };
-	if (extra.length > 0) return { usageError: `лишние аргументы: ${extra.join(" ")}` };
+	if (dir === void 0) return { usageError: "no directory given" };
+	if (extra.length > 0) return { usageError: `unexpected arguments: ${extra.join(" ")}` };
 	return {
 		dir,
 		id: values.get("--id"),
 		local: values.get("--local")
 	};
 };
-const PLACEHOLDER_NOTE = "\nЗамечание: @dolphy-app/extension-sdk и @dolphy-app/extension-tools не опубликованы, версия ^0.0.0 не установится.\nУкажите пути к репозиторию Dolphy: create-dolphy-extension <dir> --local <repoRoot>.\n";
+const PLACEHOLDER_NOTE = "\nNote: @dolphy-app/extension-sdk and @dolphy-app/extension-tools are not published, version ^0.0.0 cannot be installed.\nPoint to the Dolphy repository: create-dolphy-extension <dir> --local <repoRoot>.\n";
 const installNote = ({ isLocal, isPublished }) => {
 	if (isLocal) return "";
 	return isPublished ? "" : PLACEHOLDER_NOTE;
 };
 const nextSteps = (result) => {
 	const { dir, id } = result;
-	return `\nДальше:\n${[
+	return `\nNext steps:\n${[
 		`  cd ${dir}`,
 		"  pnpm install",
 		"  pnpm test",
-		`  pnpm dev    # пересборка в dist-ext/${id}`,
+		`  pnpm dev    # rebuilds into dist-ext/${id}`,
 		"",
-		"Запуск приложения с вашим расширением (из репозитория Dolphy):",
+		"Run the app with your extension (from the Dolphy repository):",
 		`  DOLPHY_DEV_EXTENSIONS=${path.join(dir, "dist-ext")} pnpm dev`
 	].join("\n")}\n${installNote(result)}`;
 };
 /**
-* `create-dolphy-extension`; `argv` без `node` и имени скрипта, относительные пути
-* считаются от `cwd`.
+* `create-dolphy-extension`; `argv` without `node` and the script name; relative paths
+* are resolved against `cwd`.
 */
 const runCli = async (argv, io, cwd = process.cwd()) => {
 	const parsed = parseArgs(argv);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dolphy-app/create-extension",
-  "version": "0.2.0",
-  "description": "Генератор проекта расширения: create-dolphy-extension <каталог>",
+  "version": "0.3.0",
+  "description": "Extension project generator: create-dolphy-extension <directory>",
   "type": "module",
   "bin": {
     "create-dolphy-extension": "./dist/cli/main.js"