ebely 0.0.1 → 0.0.2

package/bin/ebely.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { cp, mkdir, readdir, stat } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const pkgRoot = resolve(__dirname, '..')
+const skillsSrc = join(pkgRoot, 'skills')
+
+async function listSkills() {
+  const entries = await readdir(skillsSrc, { withFileTypes: true })
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name)
+}
+
+async function installSkills({ toUser }) {
+  const base = toUser
+    ? join(process.env.HOME ?? process.cwd(), '.claude', 'skills')
+    : join(process.cwd(), '.claude', 'skills')
+
+  if (!existsSync(skillsSrc)) {
+    console.error(`ebely: skills directory not found at ${skillsSrc}`)
+    process.exit(1)
+  }
+
+  await mkdir(base, { recursive: true })
+  const names = await listSkills()
+
+  for (const name of names) {
+    const dest = join(base, name)
+    await cp(join(skillsSrc, name), dest, { recursive: true })
+    console.log(`  ✓ ${name} → ${dest}`)
+  }
+
+  console.log(
+    `\nГотово. Установлено скиллов: ${names.length}.` +
+      `\nОткрой Claude Code в этом проекте и вызови /ebely-setup для первичной настройки.`,
+  )
+}
+
+function help() {
+  console.log(`ebely — CLI
+
+Использование:
+  npx ebely skills          Установить скиллы в .claude/skills проекта (рекомендуется)
+  npx ebely skills --user   Установить скиллы глобально в ~/.claude/skills
+  npx ebely help            Показать эту справку
+
+Скиллы:
+  /ebely-setup        первичная настройка библиотеки в проекте
+  /ebely-write-tests  написание тестов через ebely`)
+}
+
+const [cmd, ...rest] = process.argv.slice(2)
+
+switch (cmd) {
+  case 'skills':
+    await installSkills({ toUser: rest.includes('--user') })
+    break
+  case undefined:
+  case 'help':
+  case '--help':
+  case '-h':
+    help()
+    break
+  default:
+    console.error(`ebely: неизвестная команда «${cmd}»\n`)
+    help()
+    process.exit(1)
+}

package/dist/index.d.ts

@@ -0,0 +1,273 @@
+declare class BaseStore<Vars extends Record<string, unknown> = Record<string, never>, Api = unknown> {
+    private store;
+    /**
+     * Типизированный доступ к эндпоинтам ИЗНУТРИ методов-сценариев
+     * («actions»): `this.api.<группа>.<метод>(...)`. Само значение
+     * подставляет генерируемый `World` (для user-store — клиент этого
+     * пользователя, для world-store — анонимный клиент), поэтому здесь это
+     * объявление без инициализатора. Тип `Api` пользователь задаёт вторым
+     * дженериком, передавая сгенерированный `WorldApi`:
+     *
+     *   import type { WorldApi } from './generated'
+     *   class UserStore extends BaseStore<Vars, WorldApi> {
+     *     async fullRegister(args: { email: string; password: string }) {
+     *       await this.api.auth.register({ body: args })
+     *       await this.api.auth.confirm({ body: { code: '0000' } })
+     *     }
+     *   }
+     *
+     * (Тип импортируется как `import type` → рантайм-цикла нет, ровно как
+     * у `hooks.ts`; см. ARCHITECTURE.md §7–§8.)
+     */
+    protected api: Api;
+    /** Сохранить внутреннюю переменную пользователя. */
+    set<K extends keyof Vars>(args: {
+        key: K;
+        value: Vars[K];
+    }): void;
+    /** Прочитать внутреннюю переменную пользователя (undefined, если не задана). */
+    get<K extends keyof Vars>(args: {
+        key: K;
+    }): Vars[K] | undefined;
+}
+
+/** Глубоко-частичный тип: на каждом уровне все поля необязательны. */
+type DeepPartial<T> = T extends (infer U)[] ? DeepPartial<U>[] : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+/** Ошибка проваленной проверки `res.assert(...)`. */
+declare class EbelyAssertionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Ответ эндпоинта в режиме `'test'`. Дженерик `M` — карта «статус → тело»,
+ * собранная генератором по swagger.
+ *
+ * - `status` / `body` — фактические значения ответа (не-2xx тоже доступен);
+ * - `assert(status, body?)` — проверка; статус подсказывается интеллисенсом.
+ */
+declare class ApiResponse<M extends Record<number, unknown>> {
+    /** Фактический HTTP-статус ответа. */
+    readonly status: number;
+    /** Распарсенное тело ответа. */
+    readonly body: M[keyof M];
+    constructor(args: {
+        status: number;
+        body: M[keyof M];
+    });
+    /**
+     * Проверяет статус и (опционально) часть тела ответа.
+     *
+     * @param status Ожидаемый статус. Подсказывается интеллисенсом из
+     *   swagger; незадекларированный литерал — ошибка типов. Чтобы
+     *   проверить статус, которого нет в схеме (например `400`),
+     *   используйте `res.assert(400 as any, ...)`.
+     * @param expectedBody Необязательная часть тела: проверяются только
+     *   переданные поля (глубоко-частично), остальные игнорируются.
+     * @returns тот же объект ответа — удобно читать `.body` после проверки.
+     */
+    assert<S extends keyof M>(status: S, expectedBody?: DeepPartial<M[S]>): this;
+}
+
+/**
+ * Изменяемое описание исходящего запроса, доступное хукам. `before`-хук
+ * МОЖЕТ его править (`headers` / `query` / `body` / `pathParams`) —
+ * изменения уедут в реальный fetch. `path` — это ШАБЛОН из swagger
+ * (`/posts/{id}`); подстановка `pathParams` происходит уже после хуков.
+ */
+type HookRequest = {
+    method: string;
+    path: string;
+    pathParams: Record<string, string>;
+    query: Record<string, string | number | boolean | undefined>;
+    body: unknown;
+    headers: Record<string, string>;
+};
+/** Ответ эндпоинта в том виде, в каком его видит `after`-хук (read-only). */
+type HookResponse = {
+    status: number;
+    body: unknown;
+};
+/** Аргумент `before`-хука. `Body` уточняется генератором на каждую операцию. */
+type BeforeHookArgs<Ctx, Body = unknown> = {
+    request: HookRequest & {
+        body: Body;
+    };
+    ctx: Ctx;
+};
+/** Аргумент `after`-хука. `Body` / `ResBody` уточняются генератором. */
+type AfterHookArgs<Ctx, Body = unknown, ResBody = unknown> = {
+    request: HookRequest & {
+        body: Body;
+    };
+    response: {
+        status: number;
+        body: ResBody;
+    };
+    ctx: Ctx;
+};
+/** `before`-хук: вызывается ДО запроса; может мутировать `request`. */
+type BeforeHook<Ctx, Body = unknown> = (args: BeforeHookArgs<Ctx, Body>) => void | Promise<void>;
+/** `after`-хук: вызывается ПОСЛЕ ответа; `response` — только на чтение. */
+type AfterHook<Ctx, Body = unknown, ResBody = unknown> = (args: AfterHookArgs<Ctx, Body, ResBody>) => void | Promise<void>;
+/**
+ * Регистратор хуков, который пользователь передаёт в конфиг одной
+ * переменной (`EbelyConfig.hooks`). Точную типизированную форму аргумента
+ * (`h.<группа>.<метод>.before/after`) задаёт СГЕНЕРИРОВАННЫЙ клиент —
+ * он экспортирует конкретный тип `Hooks`. В библиотеке тип намеренно
+ * широкий (`any`): здесь ещё не известны ни операции, ни класс store.
+ */
+type HooksRegistrar = (registrar: any) => void;
+/**
+ * Реестр хуков. Ключ — `"<группа>.<метод>"` (как `operationId`, напр.
+ * `posts.create`). Несколько хуков на один ключ выполняются ПО ОЧЕРЕДИ в
+ * порядке регистрации.
+ *
+ * Реестр ОБЩИЙ (живёт на экземпляре `World`), но `ctx` подставляется не
+ * при регистрации, а в момент запроса — это store КОНКРЕТНОГО
+ * пользователя, сделавшего вызов. Поэтому запись хуком во внутренние
+ * переменные не «течёт» между пользователями: изоляция получается
+ * бесплатно из того, что `ctx` приходит из инстанса в момент вызова.
+ *
+ * Реестр НЕ знает ни про сеть, ни про то, ЧЕЙ это store — это и есть
+ * архитектурный шов: добавить позже второй уровень контекста (общий
+ * account/session для «один юзер с двух устройств») можно аддитивно,
+ * не меняя этот класс.
+ */
+declare class HookRegistry {
+    private beforeMap;
+    private afterMap;
+    /** Зарегистрировать `before`-хук на ключ `"<группа>.<метод>"`. */
+    before(args: {
+        key: string;
+        fn: BeforeHook<any>;
+    }): void;
+    /** Зарегистрировать `after`-хук на ключ `"<группа>.<метод>"`. */
+    after(args: {
+        key: string;
+        fn: AfterHook<any>;
+    }): void;
+    /** Прогнать все `before`-хуки ключа по очереди (await на async). */
+    runBefore(args: {
+        key: string;
+        request: HookRequest;
+        ctx: unknown;
+    }): Promise<void>;
+    /** Прогнать все `after`-хуки ключа по очереди (await на async). */
+    runAfter(args: {
+        key: string;
+        request: HookRequest;
+        response: HookResponse;
+        ctx: unknown;
+    }): Promise<void>;
+}
+
+/**
+ * Источник swagger/OpenAPI-схемы. Указывается ровно одно из полей:
+ * либо `pathToFile` (локальный файл), либо `url` (HTTP-эндпоинт).
+ */
+type SwaggerSource = {
+    /** Путь к файлу схемы (резолвится от process.cwd()). */
+    pathToFile: `${string}.json`;
+    url?: never;
+} | {
+    /** URL, по которому отдаётся swagger.json. */
+    url: `http${string}.json`;
+    pathToFile?: never;
+};
+
+/**
+ * Режим генерируемого клиента (решается на этапе генерации, влияет на
+ * форму сгенерированного файла):
+ *
+ * - `'test'` — методы возвращают объект-ответ с `.status` / `.body` и
+ *   методом `.assert(status, body?)`. Не-2xx НЕ бросает исключение —
+ *   проверка делается явным `res.assert(...)`.
+ * - `'frontend'` — методы возвращают тело ответа напрямую; не-2xx
+ *   бросает ошибку; метода `.assert` нет. Подходит для использования
+ *   клиента из приложения (фронтенд/сервис), а не только в тестах.
+ */
+type ClientMode = 'test' | 'frontend';
+/** Конфиг ebely, который пользователь объявляет в своём `ebely.ts`. */
+type EbelyConfig = {
+    /** URL бэкенда, который нужно тестировать. */
+    url: string;
+    /**
+     * Класс-хранилище внутренних переменных ОДНОГО пользователя — наследник
+     * `BaseStore`. Передаётся сам класс (конструктор), не его экземпляр.
+     * Может содержать методы-сценарии (`async fullRegister(...)`), которые
+     * через `this.api.<группа>.<метод>` дёргают эндпоинты от лица этого
+     * пользователя (его заголовки, его переменные, его `ctx` в хуках).
+     */
+    userStore: new () => BaseStore<any, any>;
+    /**
+     * Класс-хранилище переменных/сценариев УРОВНЯ WORLD (необязательно).
+     * Тот же `BaseStore`, но его экземпляр — не «один пользователь», а
+     * весь мир: сюда кладут глобальные сценарии подготовки/очистки
+     * (`clearDatabase`, `seed`), доступные как `world.<метод>()`. Внутри
+     * `this.api` — анонимный клиент (без per-user заголовков).
+     * @default undefined — у `World` нет доп. методов
+     */
+    worldStore?: new () => BaseStore<any, any>;
+    /** Откуда брать swagger-схему: из файла (`pathToFile`) или по `url`. */
+    swagger: SwaggerSource;
+    /** Путь, куда писать сгенерированный клиент (резолвится от process.cwd()). */
+    generateClientTo: `${string}.ts`;
+    /**
+     * Режим генерируемого клиента — см. {@link ClientMode}.
+     * @default 'test'
+     */
+    mode?: ClientMode;
+    /**
+     * Регистратор хуков `before` / `after`. Объявляется в ОТДЕЛЬНОМ
+     * типизированном файле (тип `Hooks` экспортирует сгенерированный
+     * клиент) и передаётся сюда одной переменной:
+     *
+     * ```ts
+     * // ebely/hooks.ts
+     * import type { Hooks } from './generated'
+     * export const hooks: Hooks = (h) => {
+     *   h.posts.create.after(({ response, ctx }) => {
+     *     ctx.set({ key: 'lastPostId', value: response.body.id })
+     *   })
+     * }
+     * // ebely/ebely.ts
+     * import { hooks } from './hooks'
+     * export const ebely = { …, hooks } satisfies EbelyConfig
+     * ```
+     *
+     * Регистратор вызывается ОДИН раз при `new World()`. Внутри хука `ctx`
+     * — это store КОНКРЕТНОГО пользователя, сделавшего запрос, поэтому
+     * запись в переменные не «течёт» между пользователями.
+     * @default undefined
+     */
+    hooks?: HooksRegistrar;
+    /**
+     * Из какого модуля СГЕНЕРИРОВАННЫЙ файл импортирует `BaseStore`.
+     * По умолчанию `'ebely'` — имя npm-пакета библиотеки. Менять нужно
+     * только в нестандартной раскладке (монорепо без публикации,
+     * импорт по относительному пути или по alias из tsconfig).
+     * @default 'ebely'
+     */
+    userStoreImport?: string;
+    /**
+     * Из какого модуля СГЕНЕРИРОВАННЫЙ файл импортирует `ebely`-конфиг
+     * (нужен ему для значений по умолчанию: `ebely.url`, `ebely.userStore`).
+     * Это путь ОТ сгенерированного файла К этому конфигу. По умолчанию
+     * `'./ebely'` — т.е. конфиг лежит рядом с генерируемым файлом.
+     * @default './ebely'
+     */
+    configImport?: string;
+};
+
+/**
+ * Читает swagger-схему и пишет типизированный клиент `World` в файл.
+ * Это публичная точка входа библиотеки: пользователь вызывает её из
+ * своего проекта, передавая собственный ebely-конфиг.
+ */
+declare function generateClient(args: EbelyConfig): Promise<{
+    outPath: string;
+    operations: number;
+}>;
+
+export { AfterHook, AfterHookArgs, ApiResponse, BaseStore, BeforeHook, BeforeHookArgs, ClientMode, DeepPartial, EbelyAssertionError, EbelyConfig, HookRegistry, HookRequest, HookResponse, HooksRegistrar, SwaggerSource, generateClient };