feat: pristine harness JSON interfaces and require-existing semantic mode (P2)

harness/tht/cli/vector_cmd.py

@@ -1,3 +1,5 @@
+import hashlib
+import json
 from pathlib import Path
 
 import typer
@@ -11,6 +13,14 @@ from tht.vectorstore.store import SyncStats, content_hash
 vector_app = typer.Typer(help="Indice semantico Qdrant (derivato, rigenerabile)")
 
 
+def _artifact_digest(path: Path) -> str:
+    return "sha256:" + hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def _emit_json(payload: dict) -> None:
+    typer.echo(json.dumps(payload, ensure_ascii=False, sort_keys=True))
+
+
 def make_embedder(embeddings_cfg):
     """Factory del client embeddings (monkeypatchabile nei test)."""
     from tht.vectorstore.embeddings import OllamaEmbeddings
@@ -117,9 +127,14 @@ def init_cmd(
 
 
 @vector_app.command("index-schema")
-def index_schema_cmd(config: Path = CONFIG_OPT) -> None:
+def index_schema_cmd(
+    config: Path = CONFIG_OPT,
+    json_output: bool = typer.Option(False, "--json"),
+) -> None:
     """Embedda e sincronizza i record schema (tabelle e colonne) nel semantic store."""
+    from tht.adapters.factory import build_vector_store
     from tht.mschema.models import Annotations, PhysicalSchema
+    from tht.ports.vector import VectorStoreError
     from tht.vectorstore.records import schema_records
 
     cfg = _load_config_or_exit(config)
@@ -127,20 +142,69 @@ def index_schema_cmd(config: Path = CONFIG_OPT) -> None:
     require_vector_cfg(cfg)
     phys_file = physical_path(cfg)
     if not phys_file.exists():
-        typer.secho(
-            f"ERRORE: {phys_file} non trovato. Esegui prima `tht schema introspect`.",
-            fg=typer.colors.RED, err=True,
-        )
+        message = f"ERRORE: {phys_file} non trovato. Esegui prima `tht schema introspect`."
+        if json_output:
+            _emit_json({
+                "code": "schema_missing",
+                "error": "physical schema is missing",
+                "operation": "index_schema",
+                "schemaVersion": 1,
+                "status": "failed",
+                "workspaceId": cfg._workspace_id,
+                "workspaceRevision": cfg._workspace_revision,
+            })
+        else:
+            typer.secho(message, fg=typer.colors.RED, err=True)
         raise typer.Exit(code=1)
     physical = PhysicalSchema.from_yaml(phys_file)
-    annotations = Annotations.from_yaml(annotations_path(cfg))
+    annotations_file = annotations_path(cfg)
+    annotations = Annotations.from_yaml(annotations_file)
     records = schema_records(physical, annotations)
-    from tht.adapters.factory import build_vector_store
-
-    stats = sync_canonical_records(
-        "schema_records",
-        records,
-        store=build_vector_store(cfg, require_write=True),
-        embedder=make_embedder(cfg.embeddings),
-    )
+    try:
+        stats = sync_canonical_records(
+            "schema_records",
+            records,
+            store=build_vector_store(cfg, require_write=True),
+            embedder=make_embedder(cfg.embeddings),
+        )
+    except VectorStoreError as exc:
+        code = str(exc)
+        error = "semantic index incompatible" if code == "semantic_index_incompatible" else "schema indexing failed"
+        if json_output:
+            _emit_json({
+                "code": code,
+                "error": error,
+                "operation": "index_schema",
+                "schemaVersion": 1,
+                "status": "failed",
+                "workspaceId": cfg._workspace_id,
+                "workspaceRevision": cfg._workspace_revision,
+            })
+        else:
+            typer.secho(f"ERRORE: {error}", fg=typer.colors.RED, err=True)
+        raise typer.Exit(code=1) from None
+    if json_output:
+        _emit_json({
+            "artifactIdentities": [
+                {"digest": _artifact_digest(annotations_file), "kind": "schema_annotations"},
+                {"digest": _artifact_digest(phys_file), "kind": "physical_schema"},
+            ],
+            "code": "ok",
+            "collection": cfg.vectors.collection,
+            "counts": {
+                "added": stats.added,
+                "columns": sum(len(table.columns) for table in physical.tables.values()),
+                "deleted": stats.deleted,
+                "records": len(records),
+                "tables": len(physical.tables),
+                "unchanged": stats.unchanged,
+                "updated": stats.updated,
+            },
+            "operation": "index_schema",
+            "schemaVersion": 1,
+            "status": "succeeded",
+            "workspaceId": cfg._workspace_id,
+            "workspaceRevision": cfg._workspace_revision,
+        })
+        return
     _print_stats(stats)