@nitra/ci-docs 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+Усі помітні зміни цього пакета документуються тут.
+
+Формат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).
+
+## [0.0.2] - 2026-05-12
+
+### Added
+
+- CLI `ci-docs` з subcommand `sync-schema` — синкає GraphQL-схему в споживацький `npm/`-пакет (bump + CHANGELOG + копіювання SDL).
+- Аргументи (тільки `--key value`, без env-vars): `--new-schema <path>` (обовʼязковий), `--docs <path>` (default `./docs`), `--schema-name <file>` (default `maya.graphql`), `--db-sha <sha>` (default `unknown`).

package/README.md

@@ -0,0 +1 @@
+#

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nitra/ci-docs",
+  "version": "0.0.2",
+  "description": "Nitra CI tooling: sync GraphQL schema to a docs npm package (and more to come).",
+  "homepage": "https://github.com/nitra/ci-docs",
+  "bugs": {
+    "url": "https://github.com/nitra/ci-docs/issues"
+  },
+  "license": "ISC",
+  "author": "v@nitra.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nitra/ci-docs.git"
+  },
+  "files": [
+    "src",
+    "types",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "types": "./types/index.d.ts",
+  "bin": {
+    "ci-docs": "./src/cli.mjs"
+  },
+  "dependencies": {
+    "@graphql-inspector/core": "^6.2.1",
+    "graphql": "^16.9.0"
+  },
+  "engines": {
+    "bun": ">=1.3",
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@nitra/cursor": "^1.9.4"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+/**
+ * `@nitra/ci-docs` — CLI-диспатчер.
+ *
+ * Запуск: `npx -y @nitra/ci-docs <subcommand> [args...]`
+ *
+ * Доступні subcommands:
+ *   sync-schema  — інтроспект Hasura → bump → CHANGELOG → копіювання SDL
+ */
+
+const SUBCOMMANDS = {
+  'sync-schema': () => import('./sync-schema/main.mjs').then(m => m.cli)
+}
+
+const [subcommand, ...rest] = process.argv.slice(2)
+
+if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+  console.log(`Usage: ci-docs <subcommand> [args...]
+
+Subcommands:
+  ${Object.keys(SUBCOMMANDS).join('\n  ')}
+
+Run \`ci-docs <subcommand> --help\` for subcommand-specific options.`)
+  process.exit(subcommand ? 0 : 2)
+}
+
+const loader = SUBCOMMANDS[subcommand]
+if (!loader) {
+  console.error(`Unknown subcommand: ${subcommand}`)
+  console.error(`Available: ${Object.keys(SUBCOMMANDS).join(', ')}`)
+  process.exit(2)
+}
+
+const run = await loader()
+await run(rest)

package/src/sync-schema/__fixtures__/new-schema.graphql

@@ -0,0 +1,10 @@
+type Query {
+  hello: String
+  newField: Int
+}
+
+type User {
+  id: ID!
+  name: String
+  email: String
+}

package/src/sync-schema/__fixtures__/old-schema.graphql

@@ -0,0 +1,9 @@
+type Query {
+  hello: String
+  deprecated_field: Int
+}
+
+type User {
+  id: ID!
+  name: String
+}

package/src/sync-schema/main.mjs

@@ -0,0 +1,290 @@
+import { readFileSync, writeFileSync, existsSync, appendFileSync, mkdirSync } from 'node:fs'
+import { dirname } from 'node:path'
+import { parseArgs } from 'node:util'
+import { buildSchema, buildClientSchema, printSchema, getIntrospectionQuery } from 'graphql'
+import { diff } from '@graphql-inspector/core'
+
+const REMOVAL_TYPES = new Set([
+  'FIELD_REMOVED',
+  'TYPE_REMOVED',
+  'ENUM_VALUE_REMOVED',
+  'INPUT_FIELD_REMOVED',
+  'DIRECTIVE_REMOVED',
+  'DIRECTIVE_ARGUMENT_REMOVED',
+  'UNION_MEMBER_REMOVED',
+  'OBJECT_TYPE_INTERFACE_REMOVED',
+  'FIELD_ARGUMENT_REMOVED'
+])
+
+const ALLOWED_BUMP_KINDS = new Set(['major', 'minor', 'patch'])
+
+/**
+ * Класифікує зміни схеми у секції changelog та визначає тип bump.
+ * @param {Array<{type?: string, message: string, criticality?: {level: string}}>} changes масив змін від graphql-inspector
+ * @returns {{bump: 'minor'|'patch'|null, sections: {added: string[], removed: string[], changed: string[]}}} тип bump та секції changelog
+ */
+export function classifyChanges(changes) {
+  const sections = { added: [], removed: [], changed: [] }
+  let hasBreaking = false
+  let hasAnyChange = false
+
+  for (const change of changes) {
+    hasAnyChange = true
+    const level = change.criticality?.level
+    if (level === 'BREAKING') hasBreaking = true
+
+    if (level === 'BREAKING' && REMOVAL_TYPES.has(change.type)) {
+      sections.removed.push(change.message)
+    } else if (change.type?.endsWith('_ADDED')) {
+      sections.added.push(change.message)
+    } else {
+      sections.changed.push(change.message)
+    }
+  }
+
+  let bump = null
+  if (hasAnyChange) bump = hasBreaking ? 'minor' : 'patch'
+  return { bump, sections }
+}
+
+/**
+ * Будує markdown-блок changelog для версії.
+ * @param {{version: string, date: string, dbSha: string, sections: {added: string[], removed: string[], changed: string[]}, first?: boolean}} params параметри блоку
+ * @returns {string} markdown-блок з трейлінговим порожнім рядком
+ */
+export function formatChangelogBlock({ version, date, dbSha, sections, first = false }) {
+  const lines = [`## [${version}] - ${date}`, '']
+
+  const changed = [...sections.changed]
+  if (first) {
+    changed.unshift('Початкове додавання GraphQL-схеми з Hasura.')
+  } else {
+    changed.unshift(`Оновлено GraphQL-схему з Hasura (\`db@${dbSha}\`).`)
+  }
+
+  if (sections.added.length > 0) {
+    lines.push('### Added', '')
+    for (const item of sections.added) lines.push(`- ${item}`)
+    lines.push('')
+  }
+
+  lines.push('### Changed', '')
+  for (const item of changed) lines.push(`- ${item}`)
+  lines.push('')
+
+  if (sections.removed.length > 0) {
+    lines.push('### Removed', '')
+    for (const item of sections.removed) lines.push(`- ${item}`)
+    lines.push('')
+  }
+
+  return lines.join('\n') + '\n'
+}
+
+/**
+ * Обчислює розділювач між існуючим текстом і блоком, що додається.
+ * @param {string} existing існуючий вміст
+ * @returns {string} '', '\n' або '\n\n' — щоб новий блок починався з відступу одного порожнього рядка
+ */
+function separatorFor(existing) {
+  if (existing.endsWith('\n\n')) return ''
+  if (existing.endsWith('\n')) return '\n'
+  return '\n\n'
+}
+
+/**
+ * Вставляє новий блок changelog перед першим існуючим записом (або після хедера, якщо записів нема).
+ * @param {string} existing вміст CHANGELOG.md
+ * @param {string} newBlock новий блок версії
+ * @returns {string} оновлений вміст
+ */
+export function prependChangelog(existing, newBlock) {
+  const firstEntryIdx = existing.indexOf('\n## [')
+  if (firstEntryIdx === -1) {
+    return existing + separatorFor(existing) + newBlock
+  }
+  const insertAt = firstEntryIdx + 1
+  return existing.slice(0, insertAt) + newBlock + existing.slice(insertAt)
+}
+
+/**
+ * Запускає graphql-inspector diff між двома SDL.
+ * @param {string} oldSdl стара GraphQL-схема (SDL)
+ * @param {string} newSdl нова GraphQL-схема (SDL)
+ * @returns {Promise<Array<{type: string, message: string, criticality: {level: string}}>>} список змін
+ */
+export async function runInspector(oldSdl, newSdl) {
+  const oldSchema = buildSchema(oldSdl)
+  const newSchema = buildSchema(newSdl)
+  return await diff(oldSchema, newSchema)
+}
+
+/**
+ * Читає SDL з файлу або повертає null, якщо файл відсутній/порожній.
+ * @param {string} path шлях до SDL
+ * @returns {string|null} вміст або null
+ */
+export function readSdl(path) {
+  if (!existsSync(path)) return null
+  const content = readFileSync(path, 'utf8')
+  return content.trim().length === 0 ? null : content
+}
+
+/**
+ * Збільшує semver-версію за типом bump.
+ * @param {string} version поточна semver-версія (наприклад '0.1.2')
+ * @param {'major'|'minor'|'patch'} kind тип bump
+ * @returns {string} нова версія
+ */
+function incrementSemver(version, kind) {
+  const parts = version.split('.').map(s => Number.parseInt(s, 10))
+  if (parts.length !== 3 || parts.some(n => Number.isNaN(n))) {
+    throw new Error(`Invalid semver: ${version}`)
+  }
+  let [major, minor, patch] = parts
+  if (kind === 'major') {
+    major += 1
+    minor = 0
+    patch = 0
+  } else if (kind === 'minor') {
+    minor += 1
+    patch = 0
+  } else {
+    patch += 1
+  }
+  return `${major}.${minor}.${patch}`
+}
+
+/**
+ * Підіймає версію у package.json напряму (без виклику зовнішнього `npm`).
+ * @param {string} npmDir шлях до директорії пакета
+ * @param {'major'|'minor'|'patch'} kind тип bump
+ * @returns {string} нова версія
+ */
+export function bumpVersion(npmDir, kind) {
+  if (!ALLOWED_BUMP_KINDS.has(kind)) {
+    throw new Error(`Unsupported bump kind: ${kind}`)
+  }
+  const pkgPath = `${npmDir}/package.json`
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+  pkg.version = incrementSemver(pkg.version, kind)
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+  return pkg.version
+}
+
+/**
+ * Пише пари key=value у файл, на який вказує `GITHUB_OUTPUT`.
+ * @param {Record<string, string>} values пари для запису
+ * @returns {void}
+ */
+export function writeGithubOutput(values) {
+  const outPath = process.env.GITHUB_OUTPUT
+  if (!outPath) return
+  const lines = Object.entries(values).map(([k, v]) => `${k}=${v}`)
+  appendFileSync(outPath, lines.join('\n') + '\n')
+}
+
+/**
+ * Шле introspection-запит до Hasura і повертає SDL-рядок.
+ * @param {string} hasuraUrl URL ендпоінта GraphQL
+ * @param {string} [adminSecret] значення `X-Hasura-Admin-Secret` (опціонально для публічних ендпоінтів)
+ * @returns {Promise<string>} SDL-схема у вигляді рядка
+ */
+export async function fetchSdl(hasuraUrl, adminSecret) {
+  const res = await fetch(hasuraUrl, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      ...(adminSecret ? { 'X-Hasura-Admin-Secret': adminSecret } : {})
+    },
+    body: JSON.stringify({ query: getIntrospectionQuery() })
+  })
+  if (!res.ok) throw new Error(`Introspection failed: ${res.status} ${res.statusText}`)
+  const { data, errors } = await res.json()
+  if (errors?.length) throw new Error(`GraphQL errors: ${JSON.stringify(errors)}`)
+  return printSchema(buildClientSchema(data))
+}
+
+/**
+ * Оркеструє весь flow: diff схем → bump → CHANGELOG → запис SDL.
+ * @param {{newSdl: string, docsRoot: string, dbSha: string, date: string, schemaFilename?: string}} params параметри запуску
+ * @returns {Promise<{changed: boolean, bump: 'minor'|'patch'|null, version: string|null}>} результат
+ */
+export async function main({ newSdl, docsRoot, dbSha, date, schemaFilename = 'maya.graphql' }) {
+  const oldSchemaPath = `${docsRoot}/npm/schema/${schemaFilename}`
+  const oldSdl = readSdl(oldSchemaPath)
+
+  const first = oldSdl === null
+  const changes = first ? [] : await runInspector(oldSdl, newSdl)
+  const { bump: classifiedBump, sections } = classifyChanges(changes)
+  const bump = first ? 'patch' : classifiedBump
+
+  if (!first && bump === null) {
+    return { changed: false, bump: null, version: null }
+  }
+
+  const npmDir = `${docsRoot}/npm`
+  const version = bumpVersion(npmDir, bump)
+
+  const block = formatChangelogBlock({ version, date, dbSha: dbSha.slice(0, 7), sections, first })
+  const changelogPath = `${npmDir}/CHANGELOG.md`
+  const existingChangelog = readFileSync(changelogPath, 'utf8')
+  writeFileSync(changelogPath, prependChangelog(existingChangelog, block))
+
+  mkdirSync(dirname(oldSchemaPath), { recursive: true })
+  writeFileSync(oldSchemaPath, newSdl)
+
+  return { changed: true, bump, version }
+}
+
+/**
+ * CLI-обгортка для sync-schema. Приймає параметри як `--key value`.
+ *
+ * Обовʼязковий:
+ *   --hasura-url <url>      URL GraphQL-ендпоінта (введроспект)
+ *
+ * Необовʼязкові:
+ *   --hasura-secret <s>     значення `X-Hasura-Admin-Secret`
+ *   --docs <path>           корінь docs-репо (default './docs')
+ *   --schema-name <file>    назва файлу в `npm/schema/` (default 'maya.graphql')
+ *   --db-sha <sha>          SHA коміту db (default 'unknown')
+ *
+ * @param {string[]} [argv] аргументи (без 'node' та script path). Default — process.argv.slice(2).
+ * @returns {Promise<{changed: boolean, bump: string|null, version: string|null}>} результат main()
+ */
+export async function cli(argv = process.argv.slice(2)) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      'hasura-url': { type: 'string' },
+      'hasura-secret': { type: 'string' },
+      docs: { type: 'string', default: './docs' },
+      'schema-name': { type: 'string', default: 'maya.graphql' },
+      'db-sha': { type: 'string', default: 'unknown' }
+    },
+    allowPositionals: false,
+    strict: true
+  })
+
+  const hasuraUrl = values['hasura-url']
+  if (!hasuraUrl) {
+    throw new Error('--hasura-url is required')
+  }
+
+  const newSdl = await fetchSdl(hasuraUrl, values['hasura-secret'])
+
+  const result = await main({
+    newSdl,
+    docsRoot: values.docs,
+    dbSha: values['db-sha'],
+    date: new Date().toISOString().slice(0, 10),
+    schemaFilename: values['schema-name']
+  })
+  console.log(JSON.stringify(result, null, 2))
+  writeGithubOutput({
+    changed: String(result.changed),
+    bump: result.bump ?? '',
+    version: result.version ?? ''
+  })
+  return result
+}

package/src/sync-schema/main.test.mjs

@@ -0,0 +1,280 @@
+import { describe, it, expect, afterEach } from 'bun:test'
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { buildSchema, graphqlSync } from 'graphql'
+import { classifyChanges, cli, formatChangelogBlock, main, prependChangelog, runInspector } from './main.mjs'
+
+const HEADER = `# Changelog\n\nУсі помітні зміни цього пакета документуються тут.\n\nФормат — [Keep a Changelog](https://keepachangelog.com/uk/1.1.0/), нумерація — [SemVer](https://semver.org/lang/uk/).\n\n`
+const OLD_SDL = readFileSync(join(import.meta.dir, '__fixtures__/old-schema.graphql'), 'utf8')
+const NEW_SDL = readFileSync(join(import.meta.dir, '__fixtures__/new-schema.graphql'), 'utf8')
+
+describe('classifyChanges', () => {
+  it('повертає bump=null коли немає змін', () => {
+    expect(classifyChanges([])).toEqual({ bump: null, sections: { added: [], removed: [], changed: [] } })
+  })
+
+  it('повертає bump=patch для NON_BREAKING додавань', () => {
+    const result = classifyChanges([
+      { type: 'FIELD_ADDED', criticality: { level: 'NON_BREAKING' }, message: "Field 'foo' was added to type 'Bar'" }
+    ])
+    expect(result.bump).toBe('patch')
+    expect(result.sections.added).toEqual(["Field 'foo' was added to type 'Bar'"])
+  })
+
+  it('повертає bump=minor для будь-якого BREAKING', () => {
+    const result = classifyChanges([
+      { type: 'FIELD_REMOVED', criticality: { level: 'BREAKING' }, message: "Field 'old' was removed from type 'User'" },
+      { type: 'FIELD_ADDED', criticality: { level: 'NON_BREAKING' }, message: "Field 'new' was added to type 'User'" }
+    ])
+    expect(result.bump).toBe('minor')
+    expect(result.sections.removed).toEqual(["Field 'old' was removed from type 'User'"])
+    expect(result.sections.added).toEqual(["Field 'new' was added to type 'User'"])
+  })
+
+  it('повертає bump=patch для DANGEROUS', () => {
+    const result = classifyChanges([
+      { type: 'FIELD_ARGUMENT_DEFAULT_CHANGED', criticality: { level: 'DANGEROUS' }, message: "Default for arg 'limit' changed" }
+    ])
+    expect(result.bump).toBe('patch')
+    expect(result.sections.changed).toEqual(["Default for arg 'limit' changed"])
+  })
+
+  it('класифікує BREAKING модифікації у `changed`', () => {
+    const result = classifyChanges([
+      { type: 'TYPE_KIND_CHANGED', criticality: { level: 'BREAKING' }, message: "Type 'Foo' changed kind" }
+    ])
+    expect(result.sections.changed).toEqual(["Type 'Foo' changed kind"])
+    expect(result.sections.removed).toEqual([])
+  })
+})
+
+describe('formatChangelogBlock', () => {
+  const baseInput = { version: '0.1.0', date: '2026-05-11', dbSha: 'a1b2c3d', sections: { added: [], removed: [], changed: [] } }
+
+  it('завжди містить "Changed" з посиланням на db-SHA', () => {
+    const out = formatChangelogBlock(baseInput)
+    expect(out).toContain('## [0.1.0] - 2026-05-11')
+    expect(out).toContain('### Changed')
+    expect(out).toContain('Оновлено GraphQL-схему з Hasura (`db@a1b2c3d`)')
+  })
+
+  it('додає секцію Removed для breaking-видалень', () => {
+    const out = formatChangelogBlock({ ...baseInput, sections: { added: [], removed: ["Field 'old' removed"], changed: [] } })
+    expect(out).toContain('### Removed')
+    expect(out).toContain("- Field 'old' removed")
+  })
+
+  it('додає секцію Added для non-breaking додавань', () => {
+    const out = formatChangelogBlock({ ...baseInput, sections: { added: ["Field 'new' added"], removed: [], changed: [] } })
+    expect(out).toContain('### Added')
+    expect(out).toContain("- Field 'new' added")
+  })
+
+  it('не друкує порожні секції', () => {
+    const out = formatChangelogBlock(baseInput)
+    expect(out).not.toContain('### Added')
+    expect(out).not.toContain('### Removed')
+  })
+
+  it('first-run шаблон, коли first=true', () => {
+    const out = formatChangelogBlock({ ...baseInput, first: true })
+    expect(out).toContain('Початкове додавання GraphQL-схеми')
+    expect(out).not.toContain('Оновлено GraphQL-схему')
+  })
+
+  it('закінчується одним порожнім рядком (для коректного prepend)', () => {
+    const out = formatChangelogBlock(baseInput)
+    expect(out.endsWith('\n\n')).toBe(true)
+  })
+})
+
+describe('runInspector', () => {
+  it('повертає порожній масив для ідентичних схем', async () => {
+    const sdl = `type Query { hello: String }`
+    const changes = await runInspector(sdl, sdl)
+    expect(changes).toEqual([])
+  })
+
+  it('детектить BREAKING при видаленні поля', async () => {
+    const oldSdl = `type Query { hello: String, bye: String }`
+    const newSdl = `type Query { hello: String }`
+    const changes = await runInspector(oldSdl, newSdl)
+    const breaking = changes.find(c => c.criticality.level === 'BREAKING')
+    expect(breaking).toBeDefined()
+    expect(breaking.type).toBe('FIELD_REMOVED')
+  })
+
+  it('детектить NON_BREAKING при додаванні поля', async () => {
+    const oldSdl = `type Query { hello: String }`
+    const newSdl = `type Query { hello: String, newField: Int }`
+    const changes = await runInspector(oldSdl, newSdl)
+    const nb = changes.find(c => c.type === 'FIELD_ADDED')
+    expect(nb).toBeDefined()
+    expect(nb.criticality.level).toBe('NON_BREAKING')
+  })
+})
+
+describe('prependChangelog', () => {
+  it('вставляє новий блок між хедером і першим існуючим записом', () => {
+    const existing = HEADER + '## [0.0.2] - 2026-05-11\n\n### Added\n\n- щось.\n'
+    const block = '## [0.0.3] - 2026-05-12\n\n### Changed\n\n- нове.\n\n'
+    const out = prependChangelog(existing, block)
+    expect(out.indexOf('## [0.0.3]')).toBeLessThan(out.indexOf('## [0.0.2]'))
+    expect(out.startsWith('# Changelog')).toBe(true)
+  })
+
+  it('додає блок після хедера, якщо записів ще нема', () => {
+    const block = '## [0.0.1] - 2026-05-11\n\n### Added\n\n- перший запис.\n\n'
+    const out = prependChangelog(HEADER, block)
+    expect(out).toBe(HEADER + block)
+  })
+})
+
+describe('main (e2e via fixtures)', () => {
+  let tmp
+
+  function setupTmpDocs({ withOldSchema = true, schemaFilename = 'maya.graphql' } = {}) {
+    tmp = mkdtempSync(join(tmpdir(), 'sync-schema-'))
+    const npmDir = join(tmp, 'npm')
+    mkdirSync(npmDir, { recursive: true })
+    writeFileSync(join(npmDir, 'package.json'), JSON.stringify({ name: '@nitra/efes-docs', version: '0.0.2' }, null, 2))
+    writeFileSync(join(npmDir, 'CHANGELOG.md'), HEADER + '## [0.0.2] - 2026-05-10\n\n### Added\n\n- Базовий каркас.\n')
+    if (withOldSchema) {
+      mkdirSync(join(npmDir, 'schema'), { recursive: true })
+      writeFileSync(join(npmDir, 'schema', schemaFilename), OLD_SDL)
+    }
+    return { docsRoot: tmp, npmDir }
+  }
+
+  afterEach(() => {
+    if (tmp && existsSync(tmp)) rmSync(tmp, { recursive: true, force: true })
+  })
+
+  it('NON_BREAKING зміна → bump patch, CHANGELOG.Added', async () => {
+    const { docsRoot, npmDir } = setupTmpDocs()
+    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
+    console.log(JSON.stringify(result, null, 2))
+
+    expect(result.changed).toBe(true)
+    expect(result.version).toBe('0.0.3')
+
+    const changelog = readFileSync(join(npmDir, 'CHANGELOG.md'), 'utf8')
+    expect(changelog).toContain('## [0.0.3] - 2026-05-11')
+    expect(changelog.indexOf('## [0.0.3]')).toBeLessThan(changelog.indexOf('## [0.0.2]'))
+
+    const schema = readFileSync(join(npmDir, 'schema/maya.graphql'), 'utf8')
+    expect(schema).toBe(NEW_SDL)
+  })
+
+  it('однакові схеми → changed=false, нічого не записує', async () => {
+    const { docsRoot, npmDir } = setupTmpDocs()
+    const result = await main({ newSdl: OLD_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
+    console.log(JSON.stringify(result, null, 2))
+
+    expect(result.changed).toBe(false)
+    expect(result.bump).toBeNull()
+
+    const pkg = JSON.parse(readFileSync(join(npmDir, 'package.json'), 'utf8'))
+    expect(pkg.version).toBe('0.0.2')
+  })
+
+  it('first-run (нема старої схеми) → bump patch, CHANGELOG з "Початкове додавання"', async () => {
+    const { docsRoot, npmDir } = setupTmpDocs({ withOldSchema: false })
+    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11' })
+    console.log(JSON.stringify(result, null, 2))
+
+    expect(result.changed).toBe(true)
+    expect(result.bump).toBe('patch')
+    expect(result.version).toBe('0.0.3')
+
+    const changelog = readFileSync(join(npmDir, 'CHANGELOG.md'), 'utf8')
+    expect(changelog).toContain('Початкове додавання GraphQL-схеми')
+    expect(existsSync(join(npmDir, 'schema/maya.graphql'))).toBe(true)
+  })
+
+  it('кастомний schemaFilename (smart.graphql) — записує саме його', async () => {
+    const { docsRoot, npmDir } = setupTmpDocs({ schemaFilename: 'smart.graphql' })
+    const result = await main({ newSdl: NEW_SDL, docsRoot, dbSha: 'abc1234567', date: '2026-05-11', schemaFilename: 'smart.graphql' })
+
+    expect(result.changed).toBe(true)
+    expect(existsSync(join(npmDir, 'schema/smart.graphql'))).toBe(true)
+    expect(existsSync(join(npmDir, 'schema/maya.graphql'))).toBe(false)
+  })
+})
+
+describe('cli (тільки args)', () => {
+  let tmp
+  let server
+  let receivedHeaders
+
+  function setupBareDocs() {
+    tmp = mkdtempSync(join(tmpdir(), 'sync-schema-cli-'))
+    const npmDir = join(tmp, 'npm')
+    mkdirSync(npmDir, { recursive: true })
+    writeFileSync(join(npmDir, 'package.json'), JSON.stringify({ name: '@nitra/x-docs', version: '0.0.2' }, null, 2))
+    writeFileSync(join(npmDir, 'CHANGELOG.md'), HEADER + '## [0.0.2] - 2026-05-10\n\n### Added\n\n- щось.\n')
+    return tmp
+  }
+
+  function startMockHasura(sdl) {
+    const schema = buildSchema(sdl)
+    server = Bun.serve({
+      port: 0,
+      async fetch(req) {
+        receivedHeaders = req.headers
+        const { query } = await req.json()
+        const result = graphqlSync({ schema, source: query })
+        return Response.json(result)
+      }
+    })
+    return `http://localhost:${server.port}/v1/graphql`
+  }
+
+  afterEach(() => {
+    if (server) {
+      server.stop()
+      server = undefined
+    }
+    receivedHeaders = undefined
+    if (tmp && existsSync(tmp)) rmSync(tmp, { recursive: true, force: true })
+  })
+
+  it('інтроспектить Hasura через --hasura-url і синкає схему', async () => {
+    const docsRoot = setupBareDocs()
+    const url = startMockHasura(NEW_SDL)
+    const result = await cli(['--hasura-url', url, '--docs', docsRoot, '--schema-name', 'test.graphql', '--db-sha', 'abcdef1234'])
+
+    expect(result.changed).toBe(true)
+    expect(result.bump).toBe('patch')
+    expect(existsSync(join(docsRoot, 'npm', 'schema', 'test.graphql'))).toBe(true)
+  })
+
+  it('передає --hasura-secret як X-Hasura-Admin-Secret заголовок', async () => {
+    const docsRoot = setupBareDocs()
+    const url = startMockHasura(NEW_SDL)
+    await cli(['--hasura-url', url, '--hasura-secret', 'super-secret', '--docs', docsRoot])
+
+    expect(receivedHeaders.get('x-hasura-admin-secret')).toBe('super-secret')
+  })
+
+  it('без --hasura-secret заголовок не надсилається', async () => {
+    const docsRoot = setupBareDocs()
+    const url = startMockHasura(NEW_SDL)
+    await cli(['--hasura-url', url, '--docs', docsRoot])
+
+    expect(receivedHeaders.get('x-hasura-admin-secret')).toBeNull()
+  })
+
+  it('схема за замовчуванням — maya.graphql', async () => {
+    const docsRoot = setupBareDocs()
+    const url = startMockHasura(NEW_SDL)
+    await cli(['--hasura-url', url, '--docs', docsRoot])
+
+    expect(existsSync(join(docsRoot, 'npm', 'schema', 'maya.graphql'))).toBe(true)
+  })
+
+  it('викидає якщо не передано --hasura-url', () => {
+    expect(cli(['--docs', '/tmp/nowhere'])).rejects.toThrow('--hasura-url is required')
+  })
+})

package/types/index.d.ts

@@ -0,0 +1 @@
+export {}