chore: establish project baseline

central/scripts/register_agent.py

@@ -0,0 +1,61 @@
+"""Administrative CLI: register a new Agent directly against Postgres.
+
+No new HTTP endpoint is needed for this — it's a one-time, operator-run
+action per installation, run from wherever DATABASE_URL is reachable (the
+Hub host, or a machine with network access to Postgres). Only the token's
+SHA-256 hash is ever stored; the plaintext token is printed once and must
+be copied into that installation's local Agent config immediately.
+
+Usage:
+    python central/scripts/register_agent.py --company "Restaurante X" --name "loja-01"
+"""
+import argparse
+import secrets
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(ROOT / "central"))
+
+from sqlalchemy.orm import Session  # noqa: E402
+
+from app.auth import token_hash  # noqa: E402
+from app.db import engine  # noqa: E402
+from app.models import Agent, Tenant  # noqa: E402
+
+
+def register_agent(session, company_name, agent_name, token=None):
+    token = token or secrets.token_urlsafe(32)
+    tenant = session.query(Tenant).filter_by(name=company_name).one_or_none()
+    if tenant is None:
+        tenant = Tenant(name=company_name)
+        session.add(tenant)
+        session.flush()
+    agent = Agent(tenant_id=tenant.id, name=agent_name, token_hash=token_hash(token), enabled=True)
+    session.add(agent)
+    session.commit()
+    # Read everything the caller needs now, while the session is still open —
+    # session.commit() expires ORM attributes by default, and callers may use
+    # these values after the session (and its `with` block) has closed.
+    return {"id": agent.id, "tenant_id": tenant.id, "enabled": agent.enabled}, token
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--company", required=True, help="Company/tenant name (created if it doesn't exist)")
+    parser.add_argument("--name", required=True, help="Human-readable name for this Agent installation, e.g. 'loja-01'")
+    args = parser.parse_args()
+
+    with Session(engine) as session:
+        info, token = register_agent(session, args.company, args.name)
+
+    print("Agent registered. Copy these into that installation's local .env NOW — the token is shown only once:")
+    print(f"  AGENT_ID={info['id']}")
+    print(f"  AGENT_TOKEN={token}")
+    print(f"  COMPANY_ID={info['tenant_id']}")
+    print("  FIREBIRD_WRITES=0")
+    print(f"enabled={info['enabled']}")
+
+
+if __name__ == "__main__":
+    main()