pyarchinit-mini 2.1.68__tar.gz → 2.4.0__tar.gz

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.0}/CHANGELOG.md

@@ -1,3 +1,163 @@
+## [2.4.0] - 2026-05-18
+
+### Added (IT)
+- Modulo `pyarchinit_mini/harris_swimlane/` (5 moduli: row_provider,
+  swimlane_state, period_sync_service, compound_layout, exceptions) per
+  l'editor swimlane di Harris Matrix.
+- `pyarchinit_mini/graphml_io/yed_writer.py` — nuovo emitter
+  yEd-flavored con `y:TableNode + y:Rows + y:ShapeNode`, separato
+  dall'export s3dgraphy clean di Spec 2.
+- 5 nuove route REST per il Harris Creator:
+  `GET/POST /api/swimlanes/<site>`, `GET /api/load/<site>`,
+  `POST /api/save/<site>`, `GET /api/export/<site>/yed-graphml`.
+- Editor `/harris-creator/editor` ora carica swimlane automaticamente
+  (row da `period_table` priorità → fallback distinct values), supporta
+  drag-drop tra row, creazione interattiva di nuove row, save esplicito
+  con auto-regen (Spec 2) post-commit.
+- Export yEd GraphML on-demand → `data/exports/harris_yed/<slug>-harris-yed.graphml`.
+
+### Added (EN)
+- New `pyarchinit_mini/harris_swimlane/` package — backend for Harris
+  Matrix swimlane editing.
+- New `pyarchinit_mini/graphml_io/yed_writer.py` — yEd-flavored GraphML
+  emitter (TableNode + Rows + ShapeNode), separate from Spec 2's
+  s3dgraphy delegate.
+- 5 new REST endpoints under `/harris-creator/api/`.
+- Editor loads swimlanes auto from `period_table` (fallback distinct);
+  drag-drop between rows; interactive row creation; explicit Save with
+  Spec 2 auto-regen. On-demand yEd export.
+
+### Changed
+- `harris_creator_routes.py` extended additively — existing routes
+  unchanged.
+- `editor.html` extended additively — Cytoscape compound nodes,
+  swimlane parents, new toolbar buttons.
+
+### Architecture note
+Two GraphML outputs now coexist:
+- `data/paradata/<slug>/stratigraphy.graphml` (Spec 2 auto-regen,
+  s3dgraphy clean, EM-canonical)
+- `data/exports/harris_yed/<slug>-harris-yed.graphml` (Spec 3-bis,
+  on-demand, yEd-flavored with TableNode)
+
+Legacy `pure_networkx_exporter` stays deprecated (was deprecated in
+Spec 2 PR8). NOT resurrected.
+
+### Dependencies
+- No new dependencies.
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-18-harris-swimlane-template-design.md`
+- Plan: `docs/superpowers/plans/2026-05-18-harris-swimlane-template.md`
+- Spec 3-bis (auxiliary): independent of Spec 3 (SyncEngine + EM
+  Datacenter, on hold pending Datacenter readiness).
+
+## [2.3.0-alpha] - 2026-05-18
+
+### Added (IT)
+- Modulo `pyarchinit_mini/graphproj/` con `GraphProjector` (DB → s3dgraphy.Graph),
+  `ParadataStore` (storage per-sito su filesystem), `GraphIngestor` (preview/apply
+  bidirezionale con staleness check), `auto_regen` (hook post-commit), edge_registry,
+  filesystem helpers.
+- Modulo `pyarchinit_mini/graphml_io/` con writer/reader delegati a
+  `s3dgraphy.exporter.graphml.GraphMLExporter` / `s3dgraphy.importer.import_graphml.GraphMLImporter`.
+- Auto-regen di `data/paradata/<site_slug>/stratigraphy.graphml` su ogni save US/USM
+  (best-effort, errori isolati). Disabilitabile con `PYARCHINIT_DISABLE_AUTO_REGEN=1`
+  o col context manager `auto_regen.disable_regen()`.
+- 5 pagine HTML CRUD per paradata (authors, licenses, embargoes, documents, epochs)
+  con form Bootstrap.
+- REST API completa `/api/v1/paradata/<site>/{authors,licenses,embargoes,documents,epochs}`.
+- Route web `/sites/<site>/graph/{view,download,import-preview,import-apply}` con
+  preview 2-fasi obbligatorio per l'import GraphML + snapshot staleness check.
+
+### Changed
+- `pyarchinit_mini/graphml_converter/{graphml_builder, graphml_exporter,
+  pure_networkx_exporter, converter}.py` marcati deprecati (emettono
+  `DeprecationWarning` all'import). Verranno rimossi in Spec 3.
+- `harris_creator_routes.py` refactored: il branch `graphml` ora usa
+  `GraphProjector.populate_graph()` + `graphml_io.writer.write_graphml()`
+  invece di passare attraverso `HarrisMatrixGenerator.export_to_graphml()` /
+  `GraphMLBuilder`.
+- Edge canonical names allineati a s3dgraphy 0.1.42: `covers` → `overlies`,
+  `leans_against` → `abuts`. Fix del bug latente Spec 1 in
+  `vocab_{en,it}.json` e `s3d_converter._LEGACY_CODE_MAP`.
+
+### Architecture note (paradata storage)
+s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone paradata
+nodes (AuthorNode, etc.) — they're only serialised when wrapped in
+ParadataNodeGroup. Spec 2 therefore adopted a **JSON sidecar pattern**:
+paradata entities live in `data/paradata/<site_slug>/paradata.json`
+(committed to git), while the auto-regenerated `stratigraphy.graphml` is
+purely the stratigraphic projection. Paradata are exposed via REST/UI but
+not embedded in the GraphML output.
+
+### Added (EN)
+- New `pyarchinit_mini/graphproj/` package: GraphProjector, ParadataStore,
+  GraphIngestor (2-phase preview/apply), auto_regen post-commit hook,
+  edge_registry, filesystem helpers.
+- New `pyarchinit_mini/graphml_io/` package delegating to s3dgraphy.
+- Auto-regen of stratigraphy.graphml on US/USM save, error-isolated.
+- 5 paradata CRUD HTML pages + REST API.
+- Graph routes: view, download, import-preview, import-apply with snapshot
+  staleness check (409 on stale).
+- Deprecation warnings on 4 legacy writers.
+
+### Dependencies
+- No new dependencies. Uses s3dgraphy 0.1.42 (bumped in 2.2.0-alpha).
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-17-spec-2-local-graph-paradata-design.md`
+- Plan: `docs/superpowers/plans/2026-05-17-spec-2-local-graph-paradata.md`
+- Spec 2 of 4 for the s3dgraphy bidirectional bridge work.
+
+## [2.2.0-alpha] - 2026-05-17
+
+### Added (IT)
+- Modulo `pyarchinit_mini/vocab/` con `VocabProvider` singleton: legge i tre pillar JSON di s3dgraphy
+  (`s3Dgraphy_node_datamodel.json`, `s3Dgraphy_connections_datamodel.json`, `em_visual_rules.json`)
+  come fonte canonica per tipi di unità, tipi di relazione, e stili visivi.
+- Endpoint REST `/api/v1/vocab/{unit-types, edge-types, visual-style, diagnostics}` per popolare
+  select e form lato web.
+- CLI `pyarchinit-mini-migrate-vocab` per allineare il vocabolario legacy
+  (`USVA`/`USVB` → `USVs`, `USVC` → `USVn`) e fare il backfill della colonna `node_uuid` (UUID v7)
+  su `us_table`, `inventario_materiali_table`, `periodizzazione_table`.
+- Colonna `node_uuid` (prerequisito per il sync futuro col Datacenter EM).
+- Catalogo i18n custom (`pyarchinit_mini/vocab/translations/vocab_{en,it}.json`) con
+  `edge_type_aliases` per il parsing dei `rapporti` italiani.
+
+### Added (EN)
+- New `pyarchinit_mini/vocab/` package with `VocabProvider` singleton reading three s3dgraphy
+  JSON pillars as canonical source of unit types, edge types, and visual styles.
+- REST endpoints `/api/v1/vocab/{unit-types, edge-types, visual-style, diagnostics}` to populate
+  forms in the web UI.
+- CLI `pyarchinit-mini-migrate-vocab` to align legacy vocabulary (`USVA`/`USVB` → `USVs`,
+  `USVC` → `USVn`) and backfill `node_uuid` (UUID v7) across `us_table`,
+  `inventario_materiali_table`, `periodizzazione_table`.
+- `node_uuid` column (prerequisite for future EM Datacenter sync).
+- Custom i18n catalogue with `edge_type_aliases` for parsing Italian `rapporti` strings.
+
+### Changed
+- `graphml_converter/em_palette.py` reads visual styles from `VocabProvider` instead of the
+  hardcoded `PALETTE` dict (kept as deprecated shim emitting `DeprecationWarning` on access).
+- `s3d_integration/s3d_converter.py` parses `rapporti` text and categorizes node families via
+  `VocabProvider` (`italian_aliases`, `family`, `class_name`) instead of hardcoded if/elif chains.
+- Harris Matrix Creator now consumes `VocabProvider` visual styles end-to-end.
+
+### Migration required
+- After upgrading, run `pyarchinit-mini-migrate-vocab --dry-run` to preview, then
+  `--apply` to migrate (auto-backup under `data/backups/`).
+- See `docs/CLI_MIGRATE_VOCAB.md` for full reference.
+
+### Dependencies
+- `s3dgraphy>=0.1.42` (was 0.1.15).
+- New: `uuid7>=0.1.0` (importable as `uuid_extensions`).
+- Dev: `freezegun>=1.5.0`.
+
+### Spec / Plan
+- Spec: `docs/superpowers/specs/2026-05-16-s3dgraphy-web-foundation-design.md`
+- Plan: `docs/superpowers/plans/2026-05-16-s3dgraphy-web-foundation.md`
+- This is Spec 1 of 4 for porting the s3dgraphy bidirectional bridge from the QGIS plugin.
+
 ## [2.1.6] - 2026-02-25
 
 ### Fixed

{pyarchinit_mini-2.1.68/pyarchinit_mini.egg-info → pyarchinit_mini-2.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyarchinit-mini
-Version: 2.1.68
+Version: 2.4.0
 Summary: Lightweight archaeological data management system with REST API, Web UI, Desktop GUI, CLI, multi-user authentication, real-time collaboration, analytics dashboard, PyArchInit import/export, Heriverse/ATON export integration, and 3D CRUD viewer
 Home-page: https://github.com/enzococca/pyarchinit-mini
 Author: PyArchInit Team
@@ -42,7 +42,8 @@ Requires-Dist: networkx>=3.0.0
 Requires-Dist: reportlab>=4.0.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: qrcode[pil]>=7.4.0
-Requires-Dist: s3dgraphy>=0.1.13
+Requires-Dist: s3dgraphy>=0.1.42
+Requires-Dist: uuid7>=0.1.0
 Requires-Dist: click>=8.1.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: inquirer>=3.0.0
@@ -91,6 +92,7 @@ Requires-Dist: black>=23.0.0; extra == "dev"
 Requires-Dist: flake8>=6.0.0; extra == "dev"
 Requires-Dist: isort>=5.12.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: freezegun>=1.5.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: sphinx>=6.0.0; extra == "docs"
 Requires-Dist: sphinx-rtd-theme>=1.2.0; extra == "docs"
@@ -2366,3 +2368,94 @@ This project is licensed under the GNU General Public License v2.0 - see the [LI
 
 
 **Made with ❤️ for the Archaeological Community**
+
+## s3dgraphy integration
+
+Since 2.2.0-alpha, pyarchinit-mini-web reads the canonical Extended Matrix
+vocabulary (unit types, edge types, visual styles) from the
+[s3dgraphy](https://github.com/zalmoxes-laran/s3dgraphy) package's JSON
+catalogues. Unit types like `US`, `USVs`, `USVn`, `RSF`, `USM` come from
+`s3Dgraphy_node_datamodel.json` (v1.5.4 at time of writing).
+
+Bumping s3dgraphy (`pip install --upgrade s3dgraphy`) makes new EM types
+immediately available in form selects without any pyarchinit-mini code change.
+
+After upgrading, run the data alignment to update legacy records:
+
+```bash
+pyarchinit-mini-migrate-vocab --dry-run    # preview changes
+pyarchinit-mini-migrate-vocab --apply      # backup + migrate
+```
+
+See `docs/CLI_MIGRATE_VOCAB.md` for the full CLI reference.
+
+The vocab is exposed to the browser via:
+
+- `GET /api/v1/vocab/unit-types?lang=it`
+- `GET /api/v1/vocab/unit-types/<abbr>`
+- `GET /api/v1/vocab/edge-types?lang=it`
+- `GET /api/v1/vocab/visual-style/<unit_type>`
+- `GET /api/v1/vocab/diagnostics` (admin-only)
+
+## Graph projection & paradata
+
+Since 2.3.0-alpha, pyarchinit-mini-web auto-generates the stratigraphic graph
+as a GraphML file every time you save a US/USM record. Output lives at
+`data/paradata/<site_slug>/stratigraphy.graphml`.
+
+Paradata (authors, licenses, embargoes, documents, epochs) are stored in a
+JSON sidecar:
+```
+data/paradata/<site_slug>/paradata.json
+```
+because s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone
+paradata nodes. The JSON sidecar IS committed to git.
+
+### Paradata editing
+
+Visit `/paradata/<site>/{authors,licenses,embargoes,documents,epochs}` to
+manage paradata. REST endpoints under `/api/v1/paradata/<site>/...` mirror
+the UI. See `docs/PARADATA_GUIDE.md`.
+
+### Graph import
+
+`/sites/<site>/graph/import-preview` accepts a GraphML upload; you see a
+preview of planned INSERT/UPDATE/SKIP and must confirm via
+`/sites/<site>/graph/import-apply` before any DB write.
+
+### Auto-regen control
+
+- Disable globally: `export PYARCHINIT_DISABLE_AUTO_REGEN=1`
+- Disable during bulk ops: `with graphproj.auto_regen.disable_regen():`
+
+See `docs/GRAPH_AUTO_REGEN.md`.
+
+## Harris Swimlane Editor
+
+Since 2.4.0, the Harris Matrix Creator at `/harris-creator/editor`
+displays stratigraphic graphs with **yEd-like swimlanes** — horizontal
+rows representing periods+phases. Existing US records are auto-placed
+in their row based on `periodo_iniziale + fase_iniziale`. Users can
+drag US records between rows, create new rows interactively, and save
+back to the DB.
+
+Row source priority:
+1. `period_table` (formal definitions)
+2. Fallback: distinct `(periodo_iniziale, fase_iniziale)` from
+   `periodizzazione_table` + `us_table`
+
+### Two GraphML outputs
+
+- `data/paradata/<site>/stratigraphy.graphml` (Spec 2, auto-regen):
+  s3dgraphy clean, EM-canonical, for the EM Datacenter
+- `data/exports/harris_yed/<site>-harris-yed.graphml` (Spec 3-bis,
+  on-demand): yEd-flavored with `y:TableNode`, for users editing in
+  yEd Desktop
+
+### Auto-regen integration
+
+Save endpoint also triggers Spec 2's auto_regen for
+`stratigraphy.graphml`, keeping the canonical output consistent with
+DB state.
+
+See `docs/HARRIS_SWIMLANE.md` and `docs/YED_INTEGRATION.md`.

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.0}/README.md

@@ -2264,4 +2264,95 @@ This project is licensed under the GNU General Public License v2.0 - see the [LI
 ---
 
 
-**Made with ❤️ for the Archaeological Community**
+**Made with ❤️ for the Archaeological Community**
+
+## s3dgraphy integration
+
+Since 2.2.0-alpha, pyarchinit-mini-web reads the canonical Extended Matrix
+vocabulary (unit types, edge types, visual styles) from the
+[s3dgraphy](https://github.com/zalmoxes-laran/s3dgraphy) package's JSON
+catalogues. Unit types like `US`, `USVs`, `USVn`, `RSF`, `USM` come from
+`s3Dgraphy_node_datamodel.json` (v1.5.4 at time of writing).
+
+Bumping s3dgraphy (`pip install --upgrade s3dgraphy`) makes new EM types
+immediately available in form selects without any pyarchinit-mini code change.
+
+After upgrading, run the data alignment to update legacy records:
+
+```bash
+pyarchinit-mini-migrate-vocab --dry-run    # preview changes
+pyarchinit-mini-migrate-vocab --apply      # backup + migrate
+```
+
+See `docs/CLI_MIGRATE_VOCAB.md` for the full CLI reference.
+
+The vocab is exposed to the browser via:
+
+- `GET /api/v1/vocab/unit-types?lang=it`
+- `GET /api/v1/vocab/unit-types/<abbr>`
+- `GET /api/v1/vocab/edge-types?lang=it`
+- `GET /api/v1/vocab/visual-style/<unit_type>`
+- `GET /api/v1/vocab/diagnostics` (admin-only)
+
+## Graph projection & paradata
+
+Since 2.3.0-alpha, pyarchinit-mini-web auto-generates the stratigraphic graph
+as a GraphML file every time you save a US/USM record. Output lives at
+`data/paradata/<site_slug>/stratigraphy.graphml`.
+
+Paradata (authors, licenses, embargoes, documents, epochs) are stored in a
+JSON sidecar:
+```
+data/paradata/<site_slug>/paradata.json
+```
+because s3dgraphy 0.1.42's GraphML exporter does not round-trip standalone
+paradata nodes. The JSON sidecar IS committed to git.
+
+### Paradata editing
+
+Visit `/paradata/<site>/{authors,licenses,embargoes,documents,epochs}` to
+manage paradata. REST endpoints under `/api/v1/paradata/<site>/...` mirror
+the UI. See `docs/PARADATA_GUIDE.md`.
+
+### Graph import
+
+`/sites/<site>/graph/import-preview` accepts a GraphML upload; you see a
+preview of planned INSERT/UPDATE/SKIP and must confirm via
+`/sites/<site>/graph/import-apply` before any DB write.
+
+### Auto-regen control
+
+- Disable globally: `export PYARCHINIT_DISABLE_AUTO_REGEN=1`
+- Disable during bulk ops: `with graphproj.auto_regen.disable_regen():`
+
+See `docs/GRAPH_AUTO_REGEN.md`.
+
+## Harris Swimlane Editor
+
+Since 2.4.0, the Harris Matrix Creator at `/harris-creator/editor`
+displays stratigraphic graphs with **yEd-like swimlanes** — horizontal
+rows representing periods+phases. Existing US records are auto-placed
+in their row based on `periodo_iniziale + fase_iniziale`. Users can
+drag US records between rows, create new rows interactively, and save
+back to the DB.
+
+Row source priority:
+1. `period_table` (formal definitions)
+2. Fallback: distinct `(periodo_iniziale, fase_iniziale)` from
+   `periodizzazione_table` + `us_table`
+
+### Two GraphML outputs
+
+- `data/paradata/<site>/stratigraphy.graphml` (Spec 2, auto-regen):
+  s3dgraphy clean, EM-canonical, for the EM Datacenter
+- `data/exports/harris_yed/<site>-harris-yed.graphml` (Spec 3-bis,
+  on-demand): yEd-flavored with `y:TableNode`, for users editing in
+  yEd Desktop
+
+### Auto-regen integration
+
+Save endpoint also triggers Spec 2's auto_regen for
+`stratigraphy.graphml`, keeping the canonical output consistent with
+DB state.
+
+See `docs/HARRIS_SWIMLANE.md` and `docs/YED_INTEGRATION.md`.

{pyarchinit_mini-2.1.68 → pyarchinit_mini-2.4.0}/pyarchinit_mini/__init__.py

@@ -23,7 +23,7 @@ Features:
 - Scalable and modular architecture
 """
 
-__version__ = "2.1.68"
+__version__ = "2.4.0"
 __author__ = "PyArchInit Team"
 __email__ = "enzo.ccc@gmail.com"
 

pyarchinit_mini-2.4.0/pyarchinit_mini/cli/migrate_vocab.py

@@ -0,0 +1,164 @@
+"""CLI: pyarchinit-mini-migrate-vocab
+
+Wraps the 3 Spec 1 Foundation migrations (node_uuid schema → backfill →
+vocab alignment USVA/USVB→USVs USVC→USVn) and the backup module.
+
+Discovery order for target DBs:
+  1. --database <url>  (CLI flag, wins outright)
+  2. $DATABASE_URL     (default app DB)
+  3. data/connections.json  (saved web connections; skip with --only-default)
+
+Usage examples:
+  pyarchinit-mini-migrate-vocab --dry-run
+  pyarchinit-mini-migrate-vocab --apply --yes
+  pyarchinit-mini-migrate-vocab --rollback --yes
+  pyarchinit-mini-migrate-vocab --list-backups
+  pyarchinit-mini-migrate-vocab --apply --script vocab_alignment --database sqlite:///x.db --yes
+"""
+from __future__ import annotations
+
+import argparse
+import importlib
+import json
+import os
+import sys
+from pathlib import Path
+
+# Use importlib to avoid name collisions with the legacy DatabaseMigrations
+# class exported from pyarchinit_mini.database.migrations.__init__.
+_pkg = "pyarchinit_mini.database.migrations"
+schema_m = importlib.import_module(f"{_pkg}._2026_05_node_uuid_schema")
+backfill_m = importlib.import_module(f"{_pkg}._2026_05_node_uuid_backfill")
+align_m = importlib.import_module(f"{_pkg}._2026_05_vocab_alignment")
+
+from pyarchinit_mini.database.migrations.backup import backup_database  # noqa: E402
+
+
+SCRIPTS = {
+    "node_uuid_schema": schema_m,
+    "node_uuid_backfill": backfill_m,
+    "vocab_alignment": align_m,
+}
+ORDER = ["node_uuid_schema", "node_uuid_backfill", "vocab_alignment"]
+
+
+def _discover_dbs(args) -> list[str]:
+    if args.database:
+        return [args.database]
+    dbs: list[str] = []
+    env = os.environ.get("DATABASE_URL")
+    if env:
+        dbs.append(env)
+    if not args.only_default:
+        conns = Path("data/connections.json")
+        if conns.exists():
+            try:
+                data = json.loads(conns.read_text(encoding="utf-8"))
+                for entry in data.get("connections", []):
+                    url = entry.get("url")
+                    if url and url not in dbs:
+                        dbs.append(url)
+            except json.JSONDecodeError:
+                print(f"warning: could not parse {conns}", file=sys.stderr)
+    return dbs
+
+
+def _confirm(prompt: str, yes: bool) -> bool:
+    if yes:
+        return True
+    try:
+        ans = input(f"{prompt} [y/N] ").strip().lower()
+    except EOFError:
+        return False
+    return ans == "y"
+
+
+def _list_backups(backups_dir: Path) -> int:
+    idx = backups_dir / "_index.json"
+    if not idx.exists():
+        print("No backups found.")
+        return 0
+    for r in json.loads(idx.read_text(encoding="utf-8")):
+        print(f"{r['timestamp']}  {r['backup_path']}  ({r['size_bytes']} bytes)")
+    return 0
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(
+        prog="pyarchinit-mini-migrate-vocab",
+        description="Foundation migrations: node_uuid schema + backfill + vocab alignment.",
+    )
+    mode = p.add_mutually_exclusive_group(required=True)
+    mode.add_argument("--dry-run", action="store_true", help="Report changes without mutating")
+    mode.add_argument("--apply", action="store_true", help="Backup then apply migrations")
+    mode.add_argument("--rollback", action="store_true", help="(Manual) restore from backup")
+    mode.add_argument("--list-backups", action="store_true", help="List recorded backups")
+    p.add_argument("--database", type=str, help="Target a specific DB URL")
+    p.add_argument("--script", type=str, choices=list(SCRIPTS.keys()),
+                   help="Run a single script (advanced)")
+    p.add_argument("--only-default", action="store_true",
+                   help="Skip data/connections.json discovery")
+    p.add_argument("--backups-dir", type=Path, default=Path("data/backups"))
+    p.add_argument("--yes", action="store_true", help="Skip confirmation prompts")
+    args = p.parse_args(argv)
+
+    if args.list_backups:
+        return _list_backups(args.backups_dir)
+
+    if args.rollback:
+        # TODO(Spec-2): implement actual rollback (read _index.json → restore latest backup
+        # SQLite via cp / PG via pg_restore). Currently prints manual instructions only.
+        print("Rollback requires manual restore. Use --list-backups to see what's available,")
+        print("then copy/restore the backup file manually (SQLite) or pg_restore (PostgreSQL).")
+        return 0
+
+    dbs = _discover_dbs(args)
+    if not dbs:
+        print("No databases discovered. Use --database <url> or set DATABASE_URL.",
+              file=sys.stderr)
+        return 2
+
+    scripts_to_run = (
+        [SCRIPTS[args.script]] if args.script
+        else [SCRIPTS[k] for k in ORDER]
+    )
+
+    # TODO(Spec-2): acquire data/.migration_lock (PID + timestamp) to reject concurrent
+    # --apply invocations per Spec §6.3
+    overall_status = 0
+    for db in dbs:
+        print(f"== DB: {db} ==")
+        if args.apply:
+            if not _confirm(f"Backup and migrate {db}?", args.yes):
+                print("  skipped (no confirmation)")
+                continue
+            try:
+                rec = backup_database(db, backups_dir=args.backups_dir)
+                print(f"  backup: {rec.backup_path}")
+            except Exception as e:
+                print(f"  backup failed: {e}", file=sys.stderr)
+                overall_status = 1
+                continue
+        for script in scripts_to_run:
+            try:
+                report = script.run(db, dry_run=args.dry_run)
+                print(f"  {report.script}: status={report.status}")
+                if hasattr(report, "tables_changed") and report.tables_changed:
+                    print(f"    tables_changed: {report.tables_changed}")
+                if hasattr(report, "tables_skipped") and report.tables_skipped:
+                    print(f"    tables_skipped: {report.tables_skipped}")
+                if hasattr(report, "rows_updated"):
+                    print(f"    rows_updated: {report.rows_updated}")
+                if hasattr(report, "mappings"):
+                    print(f"    mappings: {report.mappings}")
+            except Exception as e:
+                print(f"  {script.__name__} FAILED: {e}", file=sys.stderr)
+                overall_status = 1
+
+    # TODO(Spec-2): append per-script JSON-line entry to data/migration.log per Spec §6.4
+    # (ts, script, db, rows_updated/mappings/tables_*, duration_ms, status)
+    return overall_status
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pyarchinit_mini-2.4.0/pyarchinit_mini/database/migrations/_2026_05_node_uuid_backfill.py

@@ -0,0 +1,104 @@
+"""Backfill migration (2026-05-16):
+Populates `node_uuid` column with UUID v7 values on us_table,
+inventario_materiali_table, periodizzazione_table. Batched at 1000 rows.
+
+Idempotent: only updates rows WHERE node_uuid IS NULL.
+"""
+import sqlite3
+from dataclasses import dataclass, field
+
+from pyarchinit_mini.database.utils import generate_node_uuid
+
+
+@dataclass
+class MigrationReport:
+    script: str
+    db: str
+    rows_updated: dict = field(default_factory=dict)
+    dry_run: bool = False
+    status: str = "ok"
+
+
+TABLES = ("us_table", "inventario_materiali_table", "periodizzazione_table")
+BATCH = 1000
+
+
+def _backfill_sqlite(db_path: str, dry_run: bool) -> dict:
+    conn = sqlite3.connect(db_path)
+    out = {}
+    try:
+        for t in TABLES:
+            # Determine PK column. For test fixtures it's "id"; for real
+            # pyarchinit_mini.models.us.US it's "id_us". Inspect the table.
+            cols = conn.execute(f"PRAGMA table_info({t})").fetchall()
+            pk_col = next((c[1] for c in cols if c[5]), None)
+            if pk_col is None:
+                out[t] = 0
+                continue
+            col_names = {c[1] for c in cols}
+            if "node_uuid" not in col_names:
+                # Column not yet added (e.g. schema migration was dry-run)
+                out[t] = 0
+                continue
+            rows = conn.execute(
+                f"SELECT {pk_col} FROM {t} WHERE node_uuid IS NULL"
+            ).fetchall()
+            count = len(rows)
+            if count == 0 or dry_run:
+                out[t] = count
+                continue
+            for offset in range(0, count, BATCH):
+                batch = rows[offset:offset + BATCH]
+                for (row_id,) in batch:
+                    conn.execute(
+                        f"UPDATE {t} SET node_uuid=? WHERE {pk_col}=?",
+                        (generate_node_uuid(), row_id)
+                    )
+                conn.commit()
+            out[t] = count
+    finally:
+        conn.close()
+    return out
+
+
+def _backfill_postgresql(url: str, dry_run: bool) -> dict:
+    from sqlalchemy import create_engine, text, inspect
+    eng = create_engine(url)
+    out = {}
+    inspector = inspect(eng)
+    with eng.begin() as c:
+        for t in TABLES:
+            if t not in inspector.get_table_names():
+                out[t] = 0
+                continue
+            pk_cols = inspector.get_pk_constraint(t).get("constrained_columns", [])
+            if not pk_cols:
+                out[t] = 0
+                continue
+            pk_col = pk_cols[0]
+            rows = c.execute(text(f"SELECT {pk_col} FROM {t} WHERE node_uuid IS NULL")).fetchall()
+            count = len(rows)
+            if not dry_run and count > 0:
+                for (row_id,) in rows:
+                    c.execute(
+                        text(f"UPDATE {t} SET node_uuid=:u WHERE {pk_col}=:i"),
+                        {"u": generate_node_uuid(), "i": row_id}
+                    )
+            out[t] = count
+    return out
+
+
+def run(connection_url: str, *, dry_run: bool = False) -> MigrationReport:
+    report = MigrationReport(
+        script="2026_05_node_uuid_backfill",
+        db=connection_url,
+        dry_run=dry_run,
+    )
+    if connection_url.startswith("sqlite"):
+        path = connection_url.replace("sqlite:///", "", 1)
+        report.rows_updated = _backfill_sqlite(path, dry_run)
+    elif connection_url.startswith("postgresql") or connection_url.startswith("postgres"):
+        report.rows_updated = _backfill_postgresql(connection_url, dry_run)
+    else:
+        report.status = "unsupported_backend"
+    return report