@dolphy-app/create-extension 0.2.0

package/README.md

@@ -0,0 +1,23 @@
+# @dolphy-app/create-extension
+
+Генератор проекта расширения: create-dolphy-extension <каталог>
+
+Версия пакетов равна версии приложения Dolphy, из релиза которого они опубликованы (0.2.0).
+
+Генератор проекта расширения.
+
+```sh
+npx @dolphy-app/create-extension <каталог>
+```
+
+Проект получает тесты, сборку и README.
+
+## Установка
+
+```sh
+npm install @dolphy-app/create-extension
+```
+
+## Документация
+
+[Расширения Dolphy](https://github.com/dolphy-app/dolphy/blob/main/docs/design/extensions.md).

package/dist/cli/main.js

@@ -0,0 +1,527 @@
+#!/usr/bin/env node
+import path from "node:path";
+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`;
+
+//#endregion
+//#region packages/create-extension/src/template.ts
+/** Версия расширения в шаблоне и его умолчание для `apiVersion`. */
+const INITIAL_VERSION = "0.1.0";
+const lines = (parts) => `${parts.join("\n")}\n`;
+const packageJson = ({ id, dependencies }) => `${JSON.stringify({
+	name: id,
+	version: INITIAL_VERSION,
+	private: true,
+	type: "module",
+	scripts: {
+		build: "dolphy-ext build",
+		dev: "dolphy-ext build --watch",
+		validate: `dolphy-ext validate dist-ext/${id}`,
+		test: "vitest run"
+	},
+	devDependencies: {
+		"@dolphy-app/extension-sdk": dependencies.sdk,
+		"@dolphy-app/extension-tools": dependencies.tools,
+		"@types/node": "^22.20.4",
+		"happy-dom": "^20.14.5",
+		typescript: "^6.0.3",
+		vitest: "^5.0.2"
+	}
+}, null, 2)}\n`;
+const tsconfigJson = () => lines([
+	"{",
+	"  \"compilerOptions\": {",
+	"    \"target\": \"ES2023\",",
+	"    \"lib\": [\"ES2023\", \"DOM\"],",
+	"    \"module\": \"ESNext\",",
+	"    \"moduleResolution\": \"bundler\",",
+	"    \"types\": [\"node\"],",
+	"    \"strict\": true,",
+	"    \"resolveJsonModule\": true,",
+	"    \"allowImportingTsExtensions\": true,",
+	"    \"verbatimModuleSyntax\": true,",
+	"    \"isolatedModules\": true,",
+	"    \"skipLibCheck\": true,",
+	"    \"noEmit\": true",
+	"  },",
+	"  \"include\": [\"src\", \"test\"]",
+	"}"
+]);
+const manifestJson = (id) => `{
+  "id": "${id}",
+  "version": "${INITIAL_VERSION}",
+  "apiVersion": 1,
+  "contributes": {
+    "exerciseTypes": [
+      {
+        "id": "${id}",
+        "specSchema": {
+          "type": "object",
+          "required": ["expected"],
+          "additionalProperties": false,
+          "properties": {
+            "expected": { "type": "string", "minLength": 1 },
+            "ignoreCase": { "type": "boolean" }
+          }
+        },
+        "answerSchema": { "type": "string" }
+      }
+    ]
+  }
+}
+`;
+const mainTs = (id) => `import { defineExerciseType, defineExtension } from '@dolphy-app/extension-sdk';
+
+interface Spec {
+  expected: string;
+  ignoreCase?: boolean;
+}
+
+const matches = (answer: string, spec: Spec): boolean => {
+  if (spec.ignoreCase === true) {
+    return answer.toLowerCase() === spec.expected.toLowerCase();
+  }
+  return answer === spec.expected;
+};
+
+// схемы из extension.json уже проверили spec и ответ до вызова обработчиков
+export default defineExtension({
+  exerciseTypes: {
+    '${id}': defineExerciseType<Spec, string, Record<string, never>>({
+      project: () => ({}),
+      grade: ({ spec, answer }) =>
+        matches(answer, spec)
+          ? { outcome: 'passed' }
+          : { outcome: 'failed', reason: 'mismatch' },
+      referenceAnswer: ({ spec }) => spec.expected,
+    }),
+  },
+});
+`;
+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 {
+  createSchemaValidator,
+  loadExerciseType,
+} from '@dolphy-app/extension-sdk/testing';
+import { afterEach, describe, expect, it } from 'vitest';
+import manifest from '../extension.json';
+import module from '../src/main.ts';
+
+const [contribution] = manifest.contributes.exerciseTypes;
+const validateSpec = createSchemaValidator(contribution.specSchema);
+const validateAnswer = createSchemaValidator(contribution.answerSchema);
+
+const spec = { expected: 'Hello' };
+
+const disposables: { dispose(): Promise<void> }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+const load = async () => {
+  const type = await loadExerciseType(module, '${id}');
+  disposables.push(type);
+  return type;
+};
+
+describe('${id}: обработчик', () => {
+  it('project не раскрывает эталон', async () => {
+    const type = await load();
+    expect(await type.project(spec)).toEqual({});
+  });
+
+  it('grade: совпадение засчитывается, расхождение нет', async () => {
+    const type = await load();
+    expect(await type.grade({ spec, answer: 'Hello' })).toEqual({
+      outcome: 'passed',
+    });
+    expect(await type.grade({ spec, answer: 'hello' })).toEqual({
+      outcome: 'failed',
+      reason: 'mismatch',
+    });
+  });
+
+  it('grade: ignoreCase отключает различие регистров', async () => {
+    const type = await load();
+    const relaxed = { ...spec, ignoreCase: true };
+    expect(await type.grade({ spec: relaxed, answer: 'hELLO' })).toEqual({
+      outcome: 'passed',
+    });
+  });
+
+  it('referenceAnswer сам проходит проверку', async () => {
+    const type = await load();
+    const reference = await type.referenceAnswer(spec);
+    expect(reference).toEqual({ found: true, answer: 'Hello' });
+    if (!reference.found) throw new Error('reference expected');
+    expect(await type.grade({ spec, answer: reference.answer })).toEqual({
+      outcome: 'passed',
+    });
+  });
+});
+
+describe('${id}: схемы', () => {
+  it.each([[{ expected: 'a' }], [{ expected: 'a', ignoreCase: true }]])(
+    'spec %j допустим',
+    (value) => {
+      expect(validateSpec(value)).toEqual([]);
+    },
+  );
+
+  it.each([
+    ['нет expected', {}],
+    ['пустой expected', { expected: '' }],
+    ['ignoreCase не boolean', { expected: 'a', ignoreCase: 'yes' }],
+    ['лишнее поле', { expected: 'a', extra: 1 }],
+  ])('spec: %s отклоняется', (_name, value) => {
+    expect(validateSpec(value)).not.toEqual([]);
+  });
+
+  it('answer: строка допустима, число нет', () => {
+    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();
+    input.value = 'Hello';
+    input.dispatchEvent(new Event('input'));
+    input.value = '  ';
+    input.dispatchEvent(new Event('input'));
+    expect(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));
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
+    expect(submits).toBe(1);
+  });
+
+  it('disabled блокирует поле', async () => {
+    const { element, input } = await mountElement();
+    element.disabled = true;
+    await flush();
+    expect(input.disabled).toBe(true);
+  });
+
+  it('value восстанавливает ответ без событий', async () => {
+    const { element, input, changes } = await mountElement();
+    element.value = 'Hello';
+    await flush();
+    expect(input.value).toBe('Hello');
+    expect(changes).toEqual([]);
+  });
+
+  it('aria-label хоста попадает на поле', async () => {
+    const { input } = await mountElement('Ваш ответ');
+    expect(input.getAttribute('aria-label')).toBe('Ваш ответ');
+  });
+});
+`;
+};
+const readme = (id) => lines([
+	`# ${id}`,
+	"",
+	"Расширение Dolphy: вид задания «text match» (ученик вводит строку, она",
+	"сравнивается с `spec.expected`). Сгенерировано `create-dolphy-extension`.",
+	"",
+	"## Раскладка",
+	"",
+	"- `extension.json` — манифест (схемы `spec` и ответа записаны прямо в нём);",
+	"- `src/main.ts` — код расширения: `defineExtension` + `defineExerciseType`;",
+	"- `src/view.ts` — элемент ввода ответа: `defineAnswerElement`;",
+	"- `test/` — тесты обработчика и элемента (`vitest`, `happy-dom`).",
+	"",
+	"## Цикл разработки",
+	"",
+	"```sh",
+	"pnpm install",
+	`pnpm dev # dolphy-ext build --watch: пересборка в dist-ext/${id}`,
+	"```",
+	"",
+	"Запустите приложение с корнем режима разработчика — каталогом `dist-ext`",
+	"этого проекта (абсолютный путь):",
+	"",
+	"```sh",
+	"DOLPHY_DEV_EXTENSIONS=<путь к проекту>/dist-ext pnpm dev # из репозитория Dolphy",
+	"```",
+	"",
+	"Правка файла в `dist-ext` перезапускает хосты и перезагружает окно.",
+	"Ошибки загрузки видны в «Настройки → Расширения».",
+	"",
+	"## Сборка, проверка, тесты",
+	"",
+	"```sh",
+	`pnpm build     # dist-ext/${id}`,
+	"pnpm validate  # тот же разбор манифеста, что делает приложение",
+	"pnpm test",
+	"```",
+	"",
+	"## Установка вручную",
+	"",
+	`Скопируйте каталог \`dist-ext/${id}\` в \`<userData>/extensions/\``,
+	"и перезапустите приложение. Установки из приложения пока нет."
+]);
+const gitignore = () => lines(["node_modules", "dist-ext"]);
+
+//#endregion
+//#region packages/create-extension/src/generate.ts
+/** Совпадает с ограничением манифеста (`parseManifest`). */
+const MAX_ID_CHARS = 64;
+/** Без сборки (исходники, `--local`) версия пакетов условная. */
+const UNPUBLISHED_VERSION = "^0.0.0";
+const builtPackageVersion = () => "0.2.0";
+var GenerateError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "GenerateError";
+		this.code = code;
+	}
+};
+/** `AcmeHello`, `acme_hello`, `acme.hello` → `acme-hello`. */
+const deriveExtensionId = (name) => name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+const isValidExtensionId = (id) => id.length <= MAX_ID_CHARS && EXTENSION_ID_PATTERN.test(id);
+const isDirectory = async (target) => (await stat(target).catch(() => null))?.isDirectory() === true;
+const resolveId = (dir, id) => {
+	const resolved = id ?? deriveExtensionId(path.basename(dir));
+	if (!isValidExtensionId(resolved)) throw new GenerateError("invalid-id", `'${resolved}' is not a valid extension id; pass one with --id`);
+	return resolved;
+};
+const dependencySpecs = async (localRoot, packageVersion) => {
+	if (localRoot === void 0) {
+		const range = packageVersion === null ? UNPUBLISHED_VERSION : `^${packageVersion}`;
+		return {
+			dependencies: {
+				sdk: range,
+				tools: range
+			},
+			isPublished: packageVersion !== null
+		};
+	}
+	const root = path.resolve(localRoot);
+	const sdk = path.join(root, "packages", "extension-sdk");
+	const tools = path.join(root, "packages", "extension-tools");
+	for (const dir of [sdk, tools]) if (!await isDirectory(dir)) throw new GenerateError("invalid-local", `${dir} not found: --local must point to the Dolphy repository root`);
+	return {
+		dependencies: {
+			sdk: `link:${sdk}`,
+			tools: `link:${tools}`
+		},
+		isPublished: false
+	};
+};
+const assertEmpty = async (dir) => {
+	const info = await stat(dir).catch(() => null);
+	if (info === null) return;
+	if ((info.isDirectory() ? await readdir(dir) : ["(file)"]).length > 0) throw new GenerateError("target-not-empty", `${dir} is not empty`);
+};
+/** Файлы проекта: относительный путь → содержимое. */
+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)],
+		["README.md", readme(id)],
+		[".gitignore", gitignore()]
+	]);
+};
+const generateExtension = async (options) => {
+	const dir = path.resolve(options.dir);
+	const id = resolveId(dir, options.id);
+	const { dependencies, isPublished } = await dependencySpecs(options.localRoot, options.packageVersion ?? builtPackageVersion());
+	await assertEmpty(dir);
+	const isLocal = options.localRoot !== void 0;
+	const project = renderProject({
+		id,
+		dependencies
+	});
+	for (const [file, content] of project) {
+		const target = path.join(dir, ...file.split("/"));
+		await mkdir(path.dirname(target), { recursive: true });
+		await writeFile(target, content);
+	}
+	return {
+		dir,
+		files: [...project.keys()].sort(),
+		id,
+		isLocal,
+		isPublished
+	};
+};
+
+//#endregion
+//#region packages/create-extension/src/cli/run.ts
+const EXIT_OK = 0;
+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             эта справка
+`;
+const parseArgs = (argv) => {
+	if (argv.includes("--help") || argv.includes("-h")) return { help: true };
+	const positional = [];
+	const values = /* @__PURE__ */ new Map();
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (arg === "--id" || arg === "--local") {
+			const value = argv[++i];
+			if (value === void 0) return { usageError: `${arg} требует значение` };
+			values.set(arg, value);
+		} else if (arg.startsWith("-")) return { usageError: `неизвестный флаг: ${arg}` };
+		else positional.push(arg);
+	}
+	const [dir, ...extra] = positional;
+	if (dir === void 0) return { usageError: "не указан каталог" };
+	if (extra.length > 0) return { usageError: `лишние аргументы: ${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 installNote = ({ isLocal, isPublished }) => {
+	if (isLocal) return "";
+	return isPublished ? "" : PLACEHOLDER_NOTE;
+};
+const nextSteps = (result) => {
+	const { dir, id } = result;
+	return `\nДальше:\n${[
+		`  cd ${dir}`,
+		"  pnpm install",
+		"  pnpm test",
+		`  pnpm dev    # пересборка в dist-ext/${id}`,
+		"",
+		"Запуск приложения с вашим расширением (из репозитория Dolphy):",
+		`  DOLPHY_DEV_EXTENSIONS=${path.join(dir, "dist-ext")} pnpm dev`
+	].join("\n")}\n${installNote(result)}`;
+};
+/**
+* `create-dolphy-extension`; `argv` без `node` и имени скрипта, относительные пути
+* считаются от `cwd`.
+*/
+const runCli = async (argv, io, cwd = process.cwd()) => {
+	const parsed = parseArgs(argv);
+	if ("help" in parsed) {
+		io.stdout(USAGE);
+		return 0;
+	}
+	if ("usageError" in parsed) {
+		io.stderr(`${parsed.usageError}\n${USAGE}`);
+		return 2;
+	}
+	try {
+		const result = await generateExtension({
+			dir: path.resolve(cwd, parsed.dir),
+			...parsed.id === void 0 ? {} : { id: parsed.id },
+			...parsed.local === void 0 ? {} : { localRoot: path.resolve(cwd, parsed.local) }
+		});
+		io.stdout(`created ${result.id} in ${result.dir} (${result.files.length} files)\n`);
+		io.stdout(nextSteps(result));
+		return 0;
+	} catch (error) {
+		if (!(error instanceof GenerateError)) throw error;
+		io.stderr(`error: ${error.message}\n`);
+		return error.code === "target-not-empty" ? 1 : 2;
+	}
+};
+
+//#endregion
+//#region packages/create-extension/src/cli/main.ts
+process.exitCode = await runCli(process.argv.slice(2), {
+	stdout: (text) => process.stdout.write(text),
+	stderr: (text) => process.stderr.write(text)
+}, process.env["INIT_CWD"] ?? process.cwd());
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@dolphy-app/create-extension",
+  "version": "0.2.0",
+  "description": "Генератор проекта расширения: create-dolphy-extension <каталог>",
+  "type": "module",
+  "bin": {
+    "create-dolphy-extension": "./dist/cli/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {},
+  "engines": {
+    "node": ">=22.12"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dolphy-app/dolphy.git",
+    "directory": "packages/create-extension"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}