@dolphy-app/extension-sdk 0.2.0 → 0.4.0

package/docs/recipe-exercise-type.md

@@ -0,0 +1,379 @@
+# Recipe: an exercise type
+
+A new kind of task: the course author writes `spec` (what to ask), the learner
+types an answer, your code grades it. This recipe is the `exercise` template
+(`npx @dolphy-app/create-extension <dir> --id acme.hello --template exercise`,
+also the default). The files below are exactly what the generator writes for the
+id `acme.hello`. Read [quick-start.md](quick-start.md) first for the project
+layout and commands.
+
+The exercise type here compares the answer with an expected text. It has three
+parts: a declaration, the grading code (`host`) and the answer input (`views`).
+
+## The manifest
+
+File `extension.json` (exercise):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Text match",
+  "description": "Exercise type: the learner types a string that is compared with the expected text.",
+  "author": "your-github-login",
+  "tags": ["learning"],
+  "contributes": {
+    "exerciseTypes": [
+      {
+        "id": "acme.hello",
+        "specSchema": {
+          "type": "object",
+          "required": ["expected"],
+          "additionalProperties": false,
+          "properties": {
+            "expected": { "type": "string", "minLength": 1 },
+            "ignoreCase": { "type": "boolean" }
+          }
+        },
+        "answerSchema": { "type": "string" }
+      }
+    ],
+    "settings": [
+      {
+        "id": "acme.hello.trim",
+        "type": "boolean",
+        "label": "Ignore spaces around the answer",
+        "default": true
+      }
+    ],
+    "commands": [
+      { "id": "acme.hello.status", "title": "Show how answers are compared" }
+    ]
+  }
+}
+```
+
+- `exerciseTypes[].id` is the name a course uses in its exercises. `specSchema`
+  and `answerSchema` are JSON Schemas: the app checks `spec` and the answer
+  against them before your code runs, so `grade` can trust their shape.
+- `settings` declares a user setting; the code below reads it.
+- The command `acme.hello.status` shows in the palette how answers are compared.
+- No `element` key: the tag of the answer element defaults to one derived from
+  the id (`acme.hello` → `acme-hello-answer`), and the build defines the custom
+  element for you.
+
+## The code
+
+File `src/index.ts` (exercise):
+
+```ts
+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 given.toLowerCase() === spec.expected.toLowerCase();
+  }
+  return given === spec.expected;
+};
+
+// 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: {
+    'acme.hello': defineExerciseType<Spec, string, Record<string, never>>({
+      project: () => ({}),
+      grade: ({ spec, answer }) =>
+        matches(answer, spec)
+          ? { outcome: 'passed' }
+          : { outcome: 'failed', reason: 'mismatch' },
+      referenceAnswer: ({ spec }) => spec.expected,
+    }),
+  },
+  // this command is registered in `activate`: the marker names the id there
+  commands: { 'acme.hello.status': inActivate },
+  activate(ctx) {
+    options.trim = ctx.settings.get('acme.hello.trim');
+    ctx.settings.onDidChange((change) => {
+      if (change.id === 'acme.hello.trim') options.trim = change.value;
+    });
+    ctx.commands.register('acme.hello.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 = {
+  'acme.hello': 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;
+```
+
+- `host` runs in the extension process. `defineExerciseType<Spec, Answer, Public>`
+  takes `project` (the part of `spec` the window may see; never put the expected
+  answer there), `grade` (the verdict) and, optionally, `referenceAnswer` (what
+  "show the answer" displays).
+- A verdict is `{ outcome: 'passed' }` or `{ outcome: 'failed', reason }`.
+- `inActivate` marks an id that is registered in `activate`, where `ctx` exists.
+  `ctx.settings.get(id)` is synchronous and typed by the manifest (`boolean`
+  here); `onDidChange` delivers a change from Settings → Extensions to the
+  running extension without a restart.
+- `views` runs in the app window. `defineAnswerView(mount)` gets `api.root` (a
+  shadow root), `api.setAnswer(value, complete)` and `api.submit()`, and returns
+  `update(props)` for new `value` and `disabled`. The keys of `views` must be
+  exactly the declared exercise types; `satisfies ExtensionViews` makes the
+  compiler check it.
+- `src/index.ts` has no side effects on import, so tests import it in plain
+  Node. The build splits it: `host` goes to `main.mjs`, `views` to `view.mjs`.
+
+## The tests
+
+File `test/index.test.ts` (exercise):
+
+```ts
+// @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 { host, views } from '../src/index.ts';
+
+const [contribution] = manifest.contributes.exerciseTypes;
+const validateSpec = createSchemaValidator(contribution.specSchema);
+const validateAnswer = createSchemaValidator(contribution.answerSchema);
+
+const spec = { expected: 'Hello' };
+
+const disposables: { dispose(): unknown }[] = [];
+afterEach(async () => {
+  await Promise.all(disposables.splice(0).map((item) => item.dispose()));
+});
+
+const newSettings = () =>
+  createMemorySettings(manifest.contributes.settings as SettingContribution[]);
+
+const load = async (settings = newSettings()) => {
+  const type = await loadExerciseType(host, 'acme.hello', { settings });
+  disposables.push(type);
+  return type;
+};
+
+const mount = async (label?: string) => {
+  const view = await loadView(views, 'acme.hello', label === undefined ? {} : { label });
+  disposables.push(view);
+  const input = view.query<HTMLInputElement>('input');
+  if (input === null) throw new Error('no input');
+  return { view, input };
+};
+
+describe('acme.hello: handler', () => {
+  it('project does not reveal the reference', async () => {
+    const type = await load();
+    expect(await type.project(spec)).toEqual({});
+  });
+
+  it('grade: a match passes, a mismatch does not', 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 turns case sensitivity off', async () => {
+    const type = await load();
+    const relaxed = { ...spec, ignoreCase: true };
+    expect(await type.grade({ spec: relaxed, answer: 'hELLO' })).toEqual({
+      outcome: 'passed',
+    });
+  });
+
+  it('referenceAnswer passes the check itself', 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('acme.hello: 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('acme.hello.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: ['acme.hello.status'],
+      settings,
+    });
+    disposables.push(commands);
+    expect(await commands.run('acme.hello.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared without the spaces around them.',
+    });
+    await settings.set('acme.hello.trim', false);
+    expect(await commands.run('acme.hello.status')).toEqual({
+      kind: 'notify',
+      text: 'Answers are compared exactly as typed.',
+    });
+  });
+});
+
+describe('acme.hello: schemas', () => {
+  it.each([[{ expected: 'a' }], [{ expected: 'a', ignoreCase: true }]])(
+    'spec %j is valid',
+    (value) => {
+      expect(validateSpec(value)).toEqual([]);
+    },
+  );
+
+  it.each([
+    ['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: a string is valid, a number is not', () => {
+    expect(validateAnswer('text')).toEqual([]);
+    expect(validateAnswer(42)).not.toEqual([]);
+  });
+});
+
+describe('acme.hello: 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(view.changes).toEqual([
+      { value: 'Hello', complete: true },
+      { value: '  ', complete: false },
+    ]);
+  });
+
+  it('Enter submits the answer', async () => {
+    const { view, input } = await mount();
+    input.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter' }));
+    expect(view.submissions).toBe(1);
+  });
+
+  it('disabled blocks the input', async () => {
+    const { view, input } = await mount();
+    await view.update({ disabled: true });
+    expect(input.disabled).toBe(true);
+  });
+
+  it('value restores the answer without events', async () => {
+    const { view, input } = await mount();
+    await view.update({ value: 'Hello' });
+    expect(input.value).toBe('Hello');
+    expect(view.changes).toEqual([]);
+  });
+
+  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');
+  });
+});
+```
+
+`loadExerciseType` activates `host` and gives `project` and `grade` the way the
+app calls them, and checks the shape of the results. `loadView` mounts the view
+in the test DOM (the `@vitest-environment happy-dom` comment) and reports
+`changes` and `submissions`. `createSchemaValidator` checks fixtures against the
+schemas of the manifest, so a change to a schema fails the test.
+
+## Try and ship
+
+```sh
+pnpm install
+pnpm test
+pnpm dev
+```
+
+A course names the exercise type by its id (`acme.hello`) and supplies a `spec`
+that matches `specSchema`. To make it yours, rename the id, change the schemas
+and the grading, and keep the structure.

package/docs/recipe-import-export.md

@@ -0,0 +1,241 @@
+# Recipe: an importer and an exporter
+
+An importer turns a file the user picked into a new course; an exporter turns a
+course (or the learning progress) into a file the user saves. Your code only
+handles strings: the app shows the file dialogs, checks what you return with the
+course compiler, and writes to disk. This recipe has no template of its own:
+start from `blank` and replace the three files below, which are checked as a
+whole project. See [quick-start.md](quick-start.md) for the commands.
+
+## The manifest
+
+File `extension.json` (import-export):
+
+```json
+{
+  "$schema": "./node_modules/@dolphy-app/extension-api/dist/extension.schema.json",
+  "id": "acme.hello",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "name": "Hello cards",
+  "description": "Import flashcards from a CSV file and export a course back to CSV.",
+  "author": "your-github-login",
+  "tags": ["content"],
+  "contributes": {
+    "importers": [
+      { "id": "acme.hello.import", "title": "Cards from CSV", "accept": [".csv"] }
+    ],
+    "exporters": [
+      { "id": "acme.hello.export", "title": "Course to CSV", "scope": "course" }
+    ]
+  }
+}
+```
+
+- An importer has an `id`, a `title` (up to 60 characters), `accept` (1–8
+  lower-case file extensions such as `.csv`) and an optional `input`: `text`
+  (the default, the handler gets the file as a UTF-8 string) or `bytes` (a
+  `Uint8Array`). An exporter has `scope`: `course` or `progress`.
+- No permission is needed: the user choosing the file is the consent, and your
+  code never sees a path. A `progress` exporter reads `ctx.stats` and needs the
+  `learning.stats` permission.
+- The importer appears in the palette as "Import: Cards from CSV", the exporter
+  as "Export: Course to CSV", and both have buttons in Settings → Library.
+
+## The code
+
+File `src/index.ts` (import-export):
+
+```ts
+import { defineExtension } from '@dolphy-app/extension-sdk';
+import type {
+  CourseExportInput,
+  TextImportInput,
+} from '@dolphy-app/extension-sdk';
+
+const json = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
+
+const courseIdOf = (fileName: string): string =>
+  fileName
+    .replace(/\.csv$/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'cards';
+
+export const host = defineExtension({
+  importers: {
+    // one line "front,back" is one flashcard; the paths are relative to the
+    // new course directory the app creates
+    'acme.hello.import': ({ name, text }: TextImportInput) => {
+      const rows = text.split(/\r?\n/).filter((line) => line.trim() !== '');
+      if (rows.length === 0) throw new Error('The file has no rows');
+      const course = courseIdOf(name);
+      const lesson = `${course}::cards`;
+      const files: Record<string, string> = {
+        [`${course}/course_manifest.json`]: json({
+          id: course,
+          name: name.replace(/\.csv$/i, ''),
+          dependencies: [],
+          encompassed: [],
+          superseded: [],
+        }),
+        [`${course}/cards/lesson_manifest.json`]: json({
+          id: lesson,
+          name: 'Cards',
+          course_id: course,
+          dependencies: [],
+          encompassed: [],
+          superseded: [],
+        }),
+      };
+      rows.forEach((row, index) => {
+        const comma = row.indexOf(',');
+        if (comma <= 0 || comma === row.length - 1) {
+          throw new Error(`Row ${index + 1}: expected "front,back"`);
+        }
+        const dir = `${course}/cards/c${index + 1}`;
+        files[`${dir}/exercise_manifest.json`] = json({
+          id: `${lesson}::c${index + 1}`,
+          name: `Card ${index + 1}`,
+          lesson_id: lesson,
+          course_id: course,
+          exercise_type: 'Declarative',
+          exercise_asset: {
+            FlashcardAsset: { front_path: 'front.md', back_path: 'back.md' },
+          },
+        });
+        files[`${dir}/front.md`] = `${row.slice(0, comma).trim()}\n`;
+        files[`${dir}/back.md`] = `${row.slice(comma + 1).trim()}\n`;
+      });
+      return { files };
+    },
+  },
+  exporters: {
+    // the snapshot holds the text files of the chosen course, paths relative
+    // to the course directory
+    'acme.hello.export': ({ title, files }: CourseExportInput) => {
+      const cell = (text: string): string => text.trim().replace(/\s+/g, ' ');
+      const fronts = Object.keys(files)
+        .filter((path) => path.endsWith('/front.md'))
+        .sort((a, b) => a.localeCompare(b, 'en', { numeric: true }));
+      const rows = fronts.map((path) => {
+        const back = files[`${path.slice(0, -'front.md'.length)}back.md`];
+        return `${cell(files[path] ?? '')},${cell(back ?? '')}`;
+      });
+      return {
+        filename: `${title.replace(/[\\/]/g, '-').slice(0, 100)}.csv`,
+        text: `${rows.join('\n')}\n`,
+      };
+    },
+  },
+});
+```
+
+- An importer handler gets `{ name, text }` (or `{ name, bytes }`) and returns
+  `{ files: Record<path, text> }`: the files of a new directory in the library
+  (`imported/<extension id>-<file name>`). At most 5000 files, 2 MiB each and
+  20 MiB in all; a path is relative, uses `/`, and has no `..`, empty or
+  dot-leading segment, backslash, control character, or case-only duplicate.
+  Binary files are not supported: every file is text.
+- The app compiles the tree before it writes anything and shows a summary
+  (courses, lessons, exercises) and diagnostics. With an error the user cannot
+  import, and nothing is left on disk. Importing the same file name again with
+  the same extension replaces the previous directory.
+- An exporter handler gets `{ scope: 'course', courseId, title, files }` (or
+  `{ scope: 'progress' }`) and returns `{ filename, text }` or
+  `{ filename, bytes }` of at most 20 MiB. The file name has no path separator
+  and is at most 120 characters. The app asks the user where to save it.
+- A handler has 30 seconds. Throw an `Error` to refuse: its message reaches the
+  user, and nothing is written.
+- A handler that needs `ctx` is registered in `activate` with
+  `ctx.importers.register(id, handler)` / `ctx.exporters.register(id, handler)`
+  (`inActivate` in the record, as for commands).
+
+## The tests
+
+File `test/index.test.ts` (import-export):
+
+```ts
+import {
+  loadExporters,
+  loadImporters,
+} from '@dolphy-app/extension-sdk/testing';
+import { describe, expect, it } from 'vitest';
+import { host } from '../src/index.ts';
+
+const CSV = 'hola,hello\nadiós,goodbye\n';
+
+describe('acme.hello: importer', () => {
+  it('turns every row into a flashcard of one lesson', async () => {
+    const importers = await loadImporters(host, {
+      declaredImporters: [{ id: 'acme.hello.import' }],
+    });
+    const { files } = await importers.run('acme.hello.import', {
+      name: 'Spanish basics.csv',
+      text: CSV,
+    });
+    expect(Object.keys(files).sort()).toEqual([
+      'spanish-basics/cards/c1/back.md',
+      'spanish-basics/cards/c1/exercise_manifest.json',
+      'spanish-basics/cards/c1/front.md',
+      'spanish-basics/cards/c2/back.md',
+      'spanish-basics/cards/c2/exercise_manifest.json',
+      'spanish-basics/cards/c2/front.md',
+      'spanish-basics/cards/lesson_manifest.json',
+      'spanish-basics/course_manifest.json',
+    ]);
+    expect(files['spanish-basics/cards/c2/front.md']).toBe('adiós\n');
+    await importers.dispose();
+  });
+
+  it('refuses a row without an answer', async () => {
+    const importers = await loadImporters(host, {
+      declaredImporters: [{ id: 'acme.hello.import' }],
+    });
+    await expect(
+      importers.run('acme.hello.import', { name: 'x.csv', text: 'hola\n' }),
+    ).rejects.toThrow('Row 1');
+    await importers.dispose();
+  });
+});
+
+describe('acme.hello: exporter', () => {
+  it('writes the cards of the snapshot back to CSV', async () => {
+    const exporters = await loadExporters(host, {
+      declaredExporters: [{ id: 'acme.hello.export', scope: 'course' }],
+    });
+    const result = await exporters.run('acme.hello.export', {
+      scope: 'course',
+      courseId: 'deck',
+      title: 'Deck / Spanish',
+      files: {
+        'cards/c1/front.md': 'hola\n',
+        'cards/c1/back.md': 'hello\n',
+        'cards/c10/front.md': 'diez\n',
+        'cards/c10/back.md': 'ten\n',
+        'cards/c2/front.md': 'adiós\n',
+        'cards/c2/back.md': 'goodbye\n',
+      },
+    });
+    expect(result).toEqual({
+      filename: 'Deck - Spanish.csv',
+      text: 'hola,hello\nadiós,goodbye\ndiez,ten\n',
+    });
+    await exporters.dispose();
+  });
+});
+```
+
+`loadImporters` and `loadExporters` activate the module in memory and run a
+handler with the rules of the host: the `text`/`bytes` form of a declared
+importer, the `scope` of a declared exporter, the size of the input and the
+shape and limits of the result. A broken result rejects with
+`invalid import result: …` / `invalid export result: …`, so the test fails the
+way the app would refuse it. For a `progress` exporter pass
+`stats: createMemoryStats(…)`.
+
+## Try and ship
+
+Run `pnpm dev`, start the app with `DOLPHY_DEV_EXTENSIONS`, open the palette and
+run "Import: Cards from CSV". After you confirm the summary the course shows up
+in Courses without a restart. See [debugging.md](debugging.md) for the rest.