feat(docs): save chat answers as docs — edit screen, commit + push to the .env docs branch

2026-09-01 03:52:03 -04:00
parent 7b7a834a1a
commit 725af9fac1
32 changed files with 4356 additions and 107 deletions
@@ -0,0 +1,79 @@
+"""doc_drafts: server-side drafts of chat answers saved as docs (phase 59)
+
+Revision ID: 0011
+Revises: 0010
+Create Date: 2026-09-01
+
+Phase 59 (save chat answers as docs — edit screen → commit + push to the
+.env docs branch, owner revision D3 2026-08-31: no PR tooling — one
+additive, reversible table, no other schema change, A13):
+
+* ``doc_drafts`` — one row per "Save as doc" action: the long answer
+  body must live on the **server**, never in a URL. ``token`` is an
+  unguessable 128-bit ``uuid4`` — the edit screen's URL credential
+  (``/doc-edit.html?draft=<token>``, the share-token trust model,
+  phase 51) — UNIQUE (``ix_doc_drafts_token``) + NOT NULL. Unlike the
+  NULLable ``saved_chats.share_token`` there is no "un-drafted" state,
+  so no NULLs ever occur; the unique index is the guard against
+  duplicate tokens.
+* ``title`` / ``path`` / ``body`` — the editable triple (TEXT NOT NULL;
+  the body is the answer's raw markdown, never HTML — the
+  ``bor.chat.v1`` record shape).
+* ``status`` — plain TEXT + server default ``'draft'`` (the
+  ``git_sources.kind`` phase-38 precedent — the ``draft`` | ``pushed``
+  domain is enforced by the API layer, not a CHECK constraint).
+* ``branch`` / ``commit_sha`` — TEXT NULL: set by the push endpoint
+  (task 04) when it commits + pushes the file to the ``BOR_DOCS_REPO``
+  branch, recording the branch + the pushed branch's new HEAD (the UI's
+  branch + sha feedback).
+* ``created_at`` / ``updated_at`` — TIMESTAMPTZ NOT NULL, stamped
+  server-side (``updated_at`` bumps on every row update via the ORM
+  ``onupdate`` — the ``saved_chats`` precedent).
+"""
+from __future__ import annotations
+
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+from alembic import op
+
+revision = "0011"
+down_revision = "0010"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "doc_drafts",
+        sa.Column("id", postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column("token", postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column("title", sa.Text(), nullable=False),
+        sa.Column("path", sa.Text(), nullable=False),
+        sa.Column("body", sa.Text(), nullable=False),
+        sa.Column("status", sa.Text(), nullable=False, server_default=sa.text("'draft'")),
+        sa.Column("branch", sa.Text(), nullable=True),
+        sa.Column("commit_sha", sa.Text(), nullable=True),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+        sa.Column(
+            "updated_at",
+            sa.DateTime(timezone=True),
+            server_default=sa.func.now(),
+            nullable=False,
+        ),
+    )
+    # The token is the URL credential — a unique handle (the
+    # saved_chats.share_token unique-index precedent, phase 51).
+    op.create_index("ix_doc_drafts_token", "doc_drafts", ["token"], unique=True)
+
+
+def downgrade() -> None:
+    # Safe order: drop the token index first, then the table (A13 —
+    # fully reversible, no other schema change).
+    op.drop_index("ix_doc_drafts_token", table_name="doc_drafts")
+    op.drop_table("doc_drafts")