gene-archive 0.4.0__tar.gz

gene_archive-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Melnikov and gene-archive contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gene_archive-0.4.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: gene-archive
+Version: 0.4.0
+Summary: Static site generator for a family history archive: tree, people, places, documents, story — in Russian, English and Romanian
+Author: Igor Melnikov
+License: MIT
+Project-URL: Homepage, https://github.com/igormel81/gene_archive
+Project-URL: Documentation, https://github.com/igormel81/gene_archive/tree/main/docs
+Keywords: genealogy,family tree,gedcom,static site,family history,родословная
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Sociology :: Genealogy
+Classifier: Natural Language :: Russian
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Romanian
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: images
+Requires-Dist: Pillow>=10; extra == "images"
+Dynamic: license-file
+
+<div align="center">
+
+# gene-archive
+
+### Your family's history as a website — every fact backed by its document.
+
+[![Release](https://img.shields.io/github/v/release/igormel81/gene_archive?color=8a4b2a)](https://github.com/igormel81/gene_archive/releases)
+[![CI](https://github.com/igormel81/gene_archive/actions/workflows/ci.yml/badge.svg)](https://github.com/igormel81/gene_archive/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2e7d32)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab)
+![Languages](https://img.shields.io/badge/UI-English%20·%20Русский%20·%20Română-6b5b95)
+
+**[▶ Live demo](https://igormel81.github.io/gene_archive/)** ·
+**[Quick start](#quick-start)** ·
+**[Documentation](#documentation)** ·
+**[Русская версия](README.ru.md)**
+
+</div>
+
+Scans in shoeboxes, dates in a grandmother's notebook, a tree in MyHeritage, stories that
+only one aunt still remembers. **gene-archive** gathers all of it into one beautiful website
+your whole family can open on a phone: an interactive tree, a card for every person with the
+documents behind each date, an archive of scans with transcriptions, a map of family places
+and the story of the family — in English, Russian and Romanian.
+
+Relatives don't just read it. They leave comments, suggest corrections and, with an account,
+edit the archive right in the browser. You keep everything: one JSON file, your own domain,
+free hosting, full history in git, GEDCOM in and out.
+
+![The tree and a person's card](docs/img/tree-en.png)
+
+> Grew out of a real family archive: ~550 people, ~500 documents, three countries, relatives
+> commenting in three languages. The [demo](https://igormel81.github.io/gene_archive/) is a
+> fictional family made to show every feature.
+
+## Why gene-archive
+
+|   |   |
+|---|---|
+| 📜 **Proof for every fact** | Each date and place shows where it comes from — a document, a family story, a calculation from an age — and `S12` in any text opens the scan. Doubtful links are drawn dashed, not hidden. |
+| 👨‍👩‍👧 **Made for the whole family** | Relatives read it like a book, find themselves in the tree, ask "how are we related?", comment and suggest corrections — no registration on a platform. |
+| ✏️ **Edit in the browser** | Accounts for editors and administrators, checks before every save, nobody overwrites anybody, every change is a git commit you can undo. |
+| 🔒 **Private by default** | Living people show only their names — no dates, places or documents, not even in the data file or the GEDCOM export. |
+| 🏠 **Your data, your site** | One JSON file, plain HTML, free hosting on GitHub Pages or Netlify, or your own server. No subscription, no lock-in: GEDCOM import and export. |
+| 🌍 **Three languages** | English, Russian and Romanian interface out of the box; your own texts can be translated too. |
+| 🤖 **AI-ready** | Every new site gets `AGENTS.md` for Claude Code and Codex, plus guides and ready prompts for research in archives and open sources. |
+
+## Features
+
+### 🌳 Tree, people and "How we are related"
+
+- **Hourglass tree** around any person, a whole-tree chart, export to PNG, branches by surname.
+- **Person card**: dates and places with their documents, alternative versions of a date,
+  relatives, a connected life story.
+- **How we are related**: the exact relation between any two people — *second cousin once
+  removed*, *great-uncle*, *half-brother*, in-laws — with the chain of people in between.
+  In Russian and Romanian too, with their own kinship terms.
+- **Search everything** from the magnifier: names, villages, any word of a document transcription, places, the story,
+  leads — word endings, the pre-1918 spelling and Latin/Cyrillic letters do not get in the way (“Kolodin” finds Колодин).
+- **People**: a calendar of birthdays and anniversaries, surname pages, the zodiac.
+
+![How we are related](docs/img/kinship-en.png)
+
+### 🗂 Archive of documents
+
+- Every scan and photograph with a transcription, the back of a photo, PDF previews.
+- Filters by type of document and by family line; restored photos next to originals.
+- **Sources**: every archive and database you searched — what it is, what was found there,
+  the documents and the research-log entries for each; plus a log of corrections.
+
+| | |
+|---|---|
+| ![Archive, Russian edition](docs/img/archive-ru.png) | ![Calendar](docs/img/calendar-en.png) |
+
+### 🗺 Places and the family story
+
+- A map (Leaflet + OpenStreetMap) with family branches, moves between places,
+  "then and now" names and timelines.
+- The **Story** page: your narrative with a timeline and a "by place" filter.
+- **Questions to relatives**: what the family does not know yet — answered right on the site.
+
+### ✏️ Online editor
+
+- People, families, documents (with scan uploads) and places in a browser — on a phone too.
+- Dates the way people write them: "about 1899", "between 1900 and 1905", "9.10.1899".
+- A change that would break the data is not saved; the editor says what is wrong.
+- Two people editing the same record? The second one is warned instead of overwriting.
+- Every change goes to the corrections log and becomes a git commit by its author;
+  an administrator can restore any version.
+- **Suggest a correction**: readers send a fix from a person's card; an administrator
+  applies it in one click.
+
+![The online editor](docs/img/editor-en.png)
+
+### 🔎 Research assistant
+
+- **Data checks** (`gene hints` and the editor's "Checks" tab): impossible facts first — born
+  after the mother's death, a parent aged 11 — then gaps: no dates, a date without a document,
+  people not connected to the tree, documents nobody refers to.
+- A step-by-step **research guide** and ready **AI prompts** for archives and open sources.
+
+| | |
+|---|---|
+| ![Data checks](docs/img/hints-en.png) | ![Readers' proposals](docs/img/proposals-en.png) |
+
+### 🚀 Publish anywhere
+
+- `gene build` → plain HTML for GitHub Pages, Netlify, Cloudflare Pages or any web server.
+- `gene serve` or the Docker image adds comments, a PIN for a private archive and the editor.
+- **Share** any person, document or place: the link shows a photo, a name and a description in
+  Telegram, WhatsApp and Facebook.
+- Search engines find every person and surname: static pages, sitemap, Schema.org;
+  living people are `noindex`.
+
+## How it compares
+
+| | gene-archive | Platforms (MyHeritage, Ancestry…) | Self-hosted apps (webtrees, Gramps Web) |
+|---|:-:|:-:|:-:|
+| Your own site and domain | ✓ | — | ✓ |
+| Free static hosting, no database | ✓ | — | — |
+| Free, open source | ✓ (MIT) | subscription | ✓ |
+| A document behind every fact, on the page | ✓ | partly | partly |
+| Story, map and archive in one site | ✓ | partly | partly |
+| Relatives comment and suggest corrections | ✓ | ✓ | partly |
+| Editing in a browser with roles and history | ✓ | ✓ | ✓ |
+| DNA matches, hints from billions of records | — | ✓ | — |
+
+gene-archive does not try to be a database of the world's records. It is the place where
+**your** family's evidence and stories live — and where your relatives actually look.
+
+## Quick start
+
+You need Python 3.10+. [Pillow](https://pypi.org/project/Pillow/) makes thumbnails
+(optional), `pdftoppm` from poppler-utils makes PDF previews (optional).
+
+```sh
+pip install "gene-archive[images] @ git+https://github.com/igormel81/gene_archive"
+
+gene init my-family --example     # a copy of the demo family to look around
+gene serve my-family              # → http://127.0.0.1:8111
+```
+
+Start your own archive:
+
+```sh
+gene init my-family --lang en     # an empty site: family_tree.json + site.json
+gene import tree.ged my-family    # …or start from a GEDCOM file
+gene validate my-family           # check the data
+gene build my-family              # the site is in my-family/_site
+```
+
+Then fill in `family_tree.json` (people, families, documents, places — see
+[the data format](docs/data-format.md)) and `site.json` ([settings](docs/configuration.md)),
+put scans into `sources/`, and write the story in `content/story.html`
+([content pages](docs/content.md)).
+
+**New to genealogy?** Read [How to start researching your family history](docs/research-guide.md):
+interviews, home documents, online databases, archives, evidence and how to record it.
+
+## Quick start with an AI assistant
+
+Works in any AI coding environment — Claude Code, Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI.
+Open an empty folder in it and paste:
+
+```text
+Set up a family archive site with gene-archive (https://github.com/igormel81/gene_archive) in this folder.
+1. Install it: pip install "gene-archive[images] @ git+https://github.com/igormel81/gene_archive"
+2. Create the site: gene init . --lang en (or gene import <my file>.ged . if I give you a GEDCOM file),
+   then git init and a first commit.
+3. Read AGENTS.md and follow it in all further work: never invent facts or relationships,
+   cite a document for every fact, keep doubtful things as leads.
+4. Ask me about the family (my parents, grandparents, what documents and photos we have at home)
+   and fill family_tree.json and site.json from my answers.
+5. Run gene validate and gene serve ., give me the link and show what you changed.
+```
+
+Then just talk to it: "here is a scan of my grandfather's birth certificate", "my aunt says…".
+More ready-made requests and the rules for reviewing the agent's work:
+[docs/ai-assistants.md](docs/ai-assistants.md).
+
+## Documentation
+
+| | English | Русский |
+|---|---|---|
+| How to start the research | [research-guide.md](docs/research-guide.md) | [research-guide.ru.md](docs/research-guide.ru.md) |
+| AI requests for research in open sources and archives | [research-prompts.md](docs/research-prompts.md) | [research-prompts.ru.md](docs/research-prompts.ru.md) |
+| Filling the site with Claude or Codex | [ai-assistants.md](docs/ai-assistants.md) | [ai-assistants.ru.md](docs/ai-assistants.ru.md) |
+| Data format (`family_tree.json`) | [data-format.md](docs/data-format.md) | [data-format.ru.md](docs/data-format.ru.md) |
+| Settings (`site.json`) | [configuration.md](docs/configuration.md) | [configuration.ru.md](docs/configuration.ru.md) |
+| Story, biographies, news | [content.md](docs/content.md) | [content.ru.md](docs/content.ru.md) |
+| Languages and translations | [translations.md](docs/translations.md) | [translations.ru.md](docs/translations.ru.md) |
+| Publishing: GitHub Pages, server, Docker, comments | [deploy.md](docs/deploy.md) | [deploy.ru.md](docs/deploy.ru.md) |
+| Online editor: accounts, history, readers' proposals | [editor.md](docs/editor.md) | [editor.ru.md](docs/editor.ru.md) |
+| Contributing to the engine | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md) |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gene init <folder> [--lang ru\|en\|ro] [--example]` | a new site (or a copy of the demo) |
+| `gene import tree.ged <folder> [--root @I12@]` | a new site from GEDCOM |
+| `gene validate [folder]` | errors and warnings in the data |
+| `gene build [folder] [-o out] [--base-url URL]` | build the static site |
+| `gene serve [folder] [--pin 1234] [--moderate]` | build and serve with comments |
+| `gene serve <folder> --editor` | … and the online editor at `/edit/` |
+| `gene users <folder> add NAME [--role admin] \| invite \| list \| role \| disable \| passwd` | editor accounts |
+| `gene comments <folder> list\|approve ID\|hide ID\|done ID "note"` | moderate comments |
+| `gene gedcom [folder] [-o file.ged] [--version 5.5.1\|7.0] [--for geni\|public]` | GEDCOM for Gramps and others; `--for geni` — for uploading to Geni, MyHeritage, Ancestry; `--for public` — for open forums, living people without names (`--full`: with living people, for your own backup) |
+| `gene translations <folder> <lang>` | your texts that have no translation yet |
+| `gene hints [folder] [--json]` | gaps and doubtful facts — a to-do list for the research |
+
+Messages are in Russian when the system language is Russian (or `GENE_LANG=ru`).
+
+## License
+
+[MIT](LICENSE). Leaflet is BSD-licensed, map tiles © OpenStreetMap contributors — see
+[THIRD_PARTY.md](THIRD_PARTY.md).

gene_archive-0.4.0/README.md

@@ -0,0 +1,217 @@
+<div align="center">
+
+# gene-archive
+
+### Your family's history as a website — every fact backed by its document.
+
+[![Release](https://img.shields.io/github/v/release/igormel81/gene_archive?color=8a4b2a)](https://github.com/igormel81/gene_archive/releases)
+[![CI](https://github.com/igormel81/gene_archive/actions/workflows/ci.yml/badge.svg)](https://github.com/igormel81/gene_archive/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-2e7d32)](LICENSE)
+![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-3776ab)
+![Languages](https://img.shields.io/badge/UI-English%20·%20Русский%20·%20Română-6b5b95)
+
+**[▶ Live demo](https://igormel81.github.io/gene_archive/)** ·
+**[Quick start](#quick-start)** ·
+**[Documentation](#documentation)** ·
+**[Русская версия](README.ru.md)**
+
+</div>
+
+Scans in shoeboxes, dates in a grandmother's notebook, a tree in MyHeritage, stories that
+only one aunt still remembers. **gene-archive** gathers all of it into one beautiful website
+your whole family can open on a phone: an interactive tree, a card for every person with the
+documents behind each date, an archive of scans with transcriptions, a map of family places
+and the story of the family — in English, Russian and Romanian.
+
+Relatives don't just read it. They leave comments, suggest corrections and, with an account,
+edit the archive right in the browser. You keep everything: one JSON file, your own domain,
+free hosting, full history in git, GEDCOM in and out.
+
+![The tree and a person's card](docs/img/tree-en.png)
+
+> Grew out of a real family archive: ~550 people, ~500 documents, three countries, relatives
+> commenting in three languages. The [demo](https://igormel81.github.io/gene_archive/) is a
+> fictional family made to show every feature.
+
+## Why gene-archive
+
+|   |   |
+|---|---|
+| 📜 **Proof for every fact** | Each date and place shows where it comes from — a document, a family story, a calculation from an age — and `S12` in any text opens the scan. Doubtful links are drawn dashed, not hidden. |
+| 👨‍👩‍👧 **Made for the whole family** | Relatives read it like a book, find themselves in the tree, ask "how are we related?", comment and suggest corrections — no registration on a platform. |
+| ✏️ **Edit in the browser** | Accounts for editors and administrators, checks before every save, nobody overwrites anybody, every change is a git commit you can undo. |
+| 🔒 **Private by default** | Living people show only their names — no dates, places or documents, not even in the data file or the GEDCOM export. |
+| 🏠 **Your data, your site** | One JSON file, plain HTML, free hosting on GitHub Pages or Netlify, or your own server. No subscription, no lock-in: GEDCOM import and export. |
+| 🌍 **Three languages** | English, Russian and Romanian interface out of the box; your own texts can be translated too. |
+| 🤖 **AI-ready** | Every new site gets `AGENTS.md` for Claude Code and Codex, plus guides and ready prompts for research in archives and open sources. |
+
+## Features
+
+### 🌳 Tree, people and "How we are related"
+
+- **Hourglass tree** around any person, a whole-tree chart, export to PNG, branches by surname.
+- **Person card**: dates and places with their documents, alternative versions of a date,
+  relatives, a connected life story.
+- **How we are related**: the exact relation between any two people — *second cousin once
+  removed*, *great-uncle*, *half-brother*, in-laws — with the chain of people in between.
+  In Russian and Romanian too, with their own kinship terms.
+- **Search everything** from the magnifier: names, villages, any word of a document transcription, places, the story,
+  leads — word endings, the pre-1918 spelling and Latin/Cyrillic letters do not get in the way (“Kolodin” finds Колодин).
+- **People**: a calendar of birthdays and anniversaries, surname pages, the zodiac.
+
+![How we are related](docs/img/kinship-en.png)
+
+### 🗂 Archive of documents
+
+- Every scan and photograph with a transcription, the back of a photo, PDF previews.
+- Filters by type of document and by family line; restored photos next to originals.
+- **Sources**: every archive and database you searched — what it is, what was found there,
+  the documents and the research-log entries for each; plus a log of corrections.
+
+| | |
+|---|---|
+| ![Archive, Russian edition](docs/img/archive-ru.png) | ![Calendar](docs/img/calendar-en.png) |
+
+### 🗺 Places and the family story
+
+- A map (Leaflet + OpenStreetMap) with family branches, moves between places,
+  "then and now" names and timelines.
+- The **Story** page: your narrative with a timeline and a "by place" filter.
+- **Questions to relatives**: what the family does not know yet — answered right on the site.
+
+### ✏️ Online editor
+
+- People, families, documents (with scan uploads) and places in a browser — on a phone too.
+- Dates the way people write them: "about 1899", "between 1900 and 1905", "9.10.1899".
+- A change that would break the data is not saved; the editor says what is wrong.
+- Two people editing the same record? The second one is warned instead of overwriting.
+- Every change goes to the corrections log and becomes a git commit by its author;
+  an administrator can restore any version.
+- **Suggest a correction**: readers send a fix from a person's card; an administrator
+  applies it in one click.
+
+![The online editor](docs/img/editor-en.png)
+
+### 🔎 Research assistant
+
+- **Data checks** (`gene hints` and the editor's "Checks" tab): impossible facts first — born
+  after the mother's death, a parent aged 11 — then gaps: no dates, a date without a document,
+  people not connected to the tree, documents nobody refers to.
+- A step-by-step **research guide** and ready **AI prompts** for archives and open sources.
+
+| | |
+|---|---|
+| ![Data checks](docs/img/hints-en.png) | ![Readers' proposals](docs/img/proposals-en.png) |
+
+### 🚀 Publish anywhere
+
+- `gene build` → plain HTML for GitHub Pages, Netlify, Cloudflare Pages or any web server.
+- `gene serve` or the Docker image adds comments, a PIN for a private archive and the editor.
+- **Share** any person, document or place: the link shows a photo, a name and a description in
+  Telegram, WhatsApp and Facebook.
+- Search engines find every person and surname: static pages, sitemap, Schema.org;
+  living people are `noindex`.
+
+## How it compares
+
+| | gene-archive | Platforms (MyHeritage, Ancestry…) | Self-hosted apps (webtrees, Gramps Web) |
+|---|:-:|:-:|:-:|
+| Your own site and domain | ✓ | — | ✓ |
+| Free static hosting, no database | ✓ | — | — |
+| Free, open source | ✓ (MIT) | subscription | ✓ |
+| A document behind every fact, on the page | ✓ | partly | partly |
+| Story, map and archive in one site | ✓ | partly | partly |
+| Relatives comment and suggest corrections | ✓ | ✓ | partly |
+| Editing in a browser with roles and history | ✓ | ✓ | ✓ |
+| DNA matches, hints from billions of records | — | ✓ | — |
+
+gene-archive does not try to be a database of the world's records. It is the place where
+**your** family's evidence and stories live — and where your relatives actually look.
+
+## Quick start
+
+You need Python 3.10+. [Pillow](https://pypi.org/project/Pillow/) makes thumbnails
+(optional), `pdftoppm` from poppler-utils makes PDF previews (optional).
+
+```sh
+pip install "gene-archive[images] @ git+https://github.com/igormel81/gene_archive"
+
+gene init my-family --example     # a copy of the demo family to look around
+gene serve my-family              # → http://127.0.0.1:8111
+```
+
+Start your own archive:
+
+```sh
+gene init my-family --lang en     # an empty site: family_tree.json + site.json
+gene import tree.ged my-family    # …or start from a GEDCOM file
+gene validate my-family           # check the data
+gene build my-family              # the site is in my-family/_site
+```
+
+Then fill in `family_tree.json` (people, families, documents, places — see
+[the data format](docs/data-format.md)) and `site.json` ([settings](docs/configuration.md)),
+put scans into `sources/`, and write the story in `content/story.html`
+([content pages](docs/content.md)).
+
+**New to genealogy?** Read [How to start researching your family history](docs/research-guide.md):
+interviews, home documents, online databases, archives, evidence and how to record it.
+
+## Quick start with an AI assistant
+
+Works in any AI coding environment — Claude Code, Codex, Cursor, GitHub Copilot, Windsurf, Gemini CLI.
+Open an empty folder in it and paste:
+
+```text
+Set up a family archive site with gene-archive (https://github.com/igormel81/gene_archive) in this folder.
+1. Install it: pip install "gene-archive[images] @ git+https://github.com/igormel81/gene_archive"
+2. Create the site: gene init . --lang en (or gene import <my file>.ged . if I give you a GEDCOM file),
+   then git init and a first commit.
+3. Read AGENTS.md and follow it in all further work: never invent facts or relationships,
+   cite a document for every fact, keep doubtful things as leads.
+4. Ask me about the family (my parents, grandparents, what documents and photos we have at home)
+   and fill family_tree.json and site.json from my answers.
+5. Run gene validate and gene serve ., give me the link and show what you changed.
+```
+
+Then just talk to it: "here is a scan of my grandfather's birth certificate", "my aunt says…".
+More ready-made requests and the rules for reviewing the agent's work:
+[docs/ai-assistants.md](docs/ai-assistants.md).
+
+## Documentation
+
+| | English | Русский |
+|---|---|---|
+| How to start the research | [research-guide.md](docs/research-guide.md) | [research-guide.ru.md](docs/research-guide.ru.md) |
+| AI requests for research in open sources and archives | [research-prompts.md](docs/research-prompts.md) | [research-prompts.ru.md](docs/research-prompts.ru.md) |
+| Filling the site with Claude or Codex | [ai-assistants.md](docs/ai-assistants.md) | [ai-assistants.ru.md](docs/ai-assistants.ru.md) |
+| Data format (`family_tree.json`) | [data-format.md](docs/data-format.md) | [data-format.ru.md](docs/data-format.ru.md) |
+| Settings (`site.json`) | [configuration.md](docs/configuration.md) | [configuration.ru.md](docs/configuration.ru.md) |
+| Story, biographies, news | [content.md](docs/content.md) | [content.ru.md](docs/content.ru.md) |
+| Languages and translations | [translations.md](docs/translations.md) | [translations.ru.md](docs/translations.ru.md) |
+| Publishing: GitHub Pages, server, Docker, comments | [deploy.md](docs/deploy.md) | [deploy.ru.md](docs/deploy.ru.md) |
+| Online editor: accounts, history, readers' proposals | [editor.md](docs/editor.md) | [editor.ru.md](docs/editor.ru.md) |
+| Contributing to the engine | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md) |
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `gene init <folder> [--lang ru\|en\|ro] [--example]` | a new site (or a copy of the demo) |
+| `gene import tree.ged <folder> [--root @I12@]` | a new site from GEDCOM |
+| `gene validate [folder]` | errors and warnings in the data |
+| `gene build [folder] [-o out] [--base-url URL]` | build the static site |
+| `gene serve [folder] [--pin 1234] [--moderate]` | build and serve with comments |
+| `gene serve <folder> --editor` | … and the online editor at `/edit/` |
+| `gene users <folder> add NAME [--role admin] \| invite \| list \| role \| disable \| passwd` | editor accounts |
+| `gene comments <folder> list\|approve ID\|hide ID\|done ID "note"` | moderate comments |
+| `gene gedcom [folder] [-o file.ged] [--version 5.5.1\|7.0] [--for geni\|public]` | GEDCOM for Gramps and others; `--for geni` — for uploading to Geni, MyHeritage, Ancestry; `--for public` — for open forums, living people without names (`--full`: with living people, for your own backup) |
+| `gene translations <folder> <lang>` | your texts that have no translation yet |
+| `gene hints [folder] [--json]` | gaps and doubtful facts — a to-do list for the research |
+
+Messages are in Russian when the system language is Russian (or `GENE_LANG=ru`).
+
+## License
+
+[MIT](LICENSE). Leaflet is BSD-licensed, map tiles © OpenStreetMap contributors — see
+[THIRD_PARTY.md](THIRD_PARTY.md).

gene_archive-0.4.0/gene_archive/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

gene_archive-0.4.0/gene_archive/apply.py

@@ -0,0 +1,92 @@
+"""`gene apply`: changes to family_tree.json from scripts and AI assistants, through the same path as the online editor —
+the checks (a change that adds an error is refused), the corrections and research logs, a git commit per change by
+its author and, with --build, a rebuild of the site.
+
+    echo '{"op": "save", "kind": "people", "record": {"given_names": "Пётр", "surname": "Колодин", "sex": "M"}}' \\
+        | gene apply my-family --author "Igor" --build
+
+Requests (one JSON object, a list, or one object per line):
+  {"op": "save", "kind": K, "record": {...}, "reason": "…", "source_ids": ["S12"]}
+        a new record (no id) or an update of the record with this id: the fields given are merged into it
+        (nested objects too; a field set to null is removed)
+  {"op": "delete", "kind": K, "id": "I12", "reason": "…"}
+  {"op": "log", "action": "what was searched and where", "result": "what came out", "scope": "…"}
+K is one of people, families, sources, places, research_leads (person, family, source, place, lead also work).
+Answer: one JSON object per request, {"ok": true, ...} or {"ok": false, "error": "…", "errors": [...]}.
+"""
+import copy
+import json
+
+from .editor import KINDS, SaveError, Store
+
+ALIASES = {"person": "people", "family": "families", "source": "sources", "place": "places", "lead": "research_leads"}
+
+
+def merge(old, new):
+    """Fields of `new` over `old`; nested objects merged; None removes a field."""
+    out = copy.deepcopy(old)
+    for k, v in new.items():
+        if v is None:
+            out.pop(k, None)
+        elif isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def parse(text):
+    text = text.strip()
+    if not text:
+        return []
+    try:
+        req = json.loads(text)
+        return req if isinstance(req, list) else [req]
+    except json.JSONDecodeError:
+        return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def run_one(store, user, req, dry_run=False):
+    op = req.get("op", "save")
+    if op == "log":
+        return store.log(user, req.get("action"), req.get("result"), req.get("scope", ""), dry_run=dry_run)
+    kind = ALIASES.get(req.get("kind"), req.get("kind"))
+    if kind not in KINDS:
+        raise SaveError(f"kind must be one of {', '.join(KINDS)}", 400)
+    key_field, _ = KINDS[kind]
+    current = {r.get(key_field): r for r in store.load().get(kind, [])}
+    if op == "delete":
+        key = req.get("id") or req.get(key_field)
+        if key not in current:
+            raise SaveError(f"no {key} in {kind}", 404)
+        return store.delete(user, kind, current[key], req.get("reason", ""), dry_run=dry_run)
+    if op != "save":
+        raise SaveError(f"unknown op {op!r}", 400)
+    record = req.get("record")
+    if not isinstance(record, dict):
+        raise SaveError("record must be an object", 400)
+    key = record.get(key_field) or req.get("id")
+    if key and key in current:   # update: merge into the stored record, which is also the base (no lost edits)
+        base = current[key]
+        rec = merge(base, record)
+        rec[key_field] = key
+        return store.save(user, kind, rec, base=base, reason=req.get("reason", ""),
+                          source_ids=req.get("source_ids"), dry_run=dry_run)
+    if key and kind != "places":
+        raise SaveError(f"no {key} in {kind} (leave the id out to create a record)", 404)
+    return store.save(user, kind, record, reason=req.get("reason", ""), source_ids=req.get("source_ids"), dry_run=dry_run)
+
+
+def apply(folder, requests, author="gene apply", login="cli", dry_run=False):
+    store = Store(folder)
+    user = {"name": login, "display": author, "role": "editor"}
+    out = []
+    for req in requests:
+        try:
+            r = run_one(store, user, req if isinstance(req, dict) else {}, dry_run)
+            out.append({"ok": True, **r})
+        except SaveError as e:
+            out.append({"ok": False, "error": str(e), "status": e.status, **e.extra})
+        except (ValueError, TypeError, KeyError) as e:
+            out.append({"ok": False, "error": f"bad request: {e}", "status": 400})
+    return out