unoverse 0.1.24 → 0.1.26

package/bin/unoverse.mjs

@@ -60,7 +60,7 @@ const UNIVERSE = findUniverse();
 const OPERATOR_COMMANDS = new Set([
   "start", "stop", "check", "logs", "deploy",
   // kept working, not advertised
-  "ground", "dev", "build", "publish", "init", "doctor", "db-setup", "db-verify", "open",
+  "ground", "dev", "build", "publish", "init",
 ]);
 
 const [, , cmd, ...args] = process.argv;

package/lib/create.mjs

@@ -256,7 +256,7 @@ export async function create(nameArg) {
         env: { ...process.env, UNOVERSE_DOCR_TOKEN: token },
       });
       if (r.status !== 0) {
-        fail(`setup did not finish. Run 'unoverse init'${name === "." ? "" : ` in ./${name}`} to pick it up`);
+        fail(`setup did not finish. Run 'unoverse start'${name === "." ? "" : ` in ./${name}`} to pick it back up`);
         process.exit(r.status ?? 1);
       }
       console.log(`

package/operator/ansible/README.md

@@ -0,0 +1,66 @@
+# Gravity Platform Ansible Automation
+
+Ansible playbooks for deployment, upgrades, and operations.
+
+## Quick Start (Single VM)
+
+There is no inventory to configure — deployments are single-VM by contract
+(INFRASTRUCTURE.md) and `unoverse deploy` builds a temporary inventory from
+`.env.production` each run.
+Just use `.env.production` at the project root:
+
+```bash
+# 1. Configure production environment (Terraform renders it, complete)
+cd infra/digitalocean && terraform apply
+terraform output -raw env_production > ../../.env.production
+
+# 2. Deploy
+gravity deploy
+
+# 3. Verify
+gravity deploy test
+```
+
+The `gravity deploy` command reads `.env.production`, builds a temporary inventory, and runs the playbooks automatically.
+
+## Structure
+
+```
+ansible/
+├── playbooks/                  # All playbooks
+├── templates/
+└── ansible.cfg
+```
+
+## Direct Ansible Usage
+
+For advanced use or multi-VM enterprise deployments:
+
+```bash
+cd ansible
+
+# Single VM (reads .env.production from project root)
+
+# Multi-VM (target specific groups)
+```
+
+## Playbooks
+
+| Playbook                | Purpose                                      |
+| ----------------------- | -------------------------------------------- |
+| `install.yml`           | Fresh install (Docker, images, services)     |
+| `deploy-packages.yml`   | Deploy packages (rsync from local + build)   |
+| `db-setup.yml`          | Database setup and migrations                |
+| `relocate-db.yml`       | RELOCATE a database (dump/restore to another server) — NOT schema migrations (that is db-setup) |
+| `rollback.yml`          | Rollback to previous version                 |
+| `health-check.yml`      | Verify all services healthy                  |
+| `backup.yml`            | Backup UMAP models                           |
+| `restore.yml`           | Restore UMAP models from backup              |
+| `harden.yml`            | Security hardening (SSH, firewall, fail2ban) |
+| `test-connectivity.yml` | Test VM connectivity and ports               |
+
+## Requirements
+
+- Ansible 2.12+
+- SSH access to target VMs
+- DOCR token (for pulling Docker images from DigitalOcean Container Registry)

package/operator/ansible/ansible.cfg

@@ -0,0 +1,19 @@
+[defaults]
+# inventory: none by default — `unoverse deploy` generates a temp inventory from
+# .env.production (multi-VM inventory retired to _legacy/ansible 2026-07-28)
+roles_path = roles
+host_key_checking = False
+retry_files_enabled = False
+# Silence the noisy ansible-core module deprecation warnings (to_text/to_bytes imports in
+# the synchronize module) — they're upstream, not our playbooks. Keeps the deploy log clean.
+deprecation_warnings = False
+gathering = smart
+fact_caching = jsonfile
+fact_caching_connection = /tmp/ansible_facts
+fact_caching_timeout = 3600
+
+[privilege_escalation]
+become = True
+become_method = sudo
+become_user = root
+become_ask_pass = False

package/operator/ansible/playbooks/backup.yml

@@ -0,0 +1,47 @@
+---
+# Gravity Platform Backup Playbook
+# Backs up UMAP models (database backup is customer responsibility)
+#
+# Usage:
+#   POC:        ansible-playbook -i inventory/production.yml playbooks/backup.yml
+#   Enterprise: ansible-playbook -i inventory/production.yml playbooks/backup.yml -l ml_vms
+
+- name: Backup Gravity Platform
+  hosts: all
+  become: yes
+  vars:
+    backup_dir: /opt/gravity/backups
+    backup_timestamp: "{{ ansible_date_time.iso8601_basic_short }}"
+
+  tasks:
+    - name: Create backup directory
+      file:
+        path: "{{ backup_dir }}"
+        state: directory
+        mode: "0755"
+
+    - name: Backup UMAP models
+      archive:
+        path: /opt/gravity/umap/models
+        dest: "{{ backup_dir }}/umap-models-{{ backup_timestamp }}.tar.gz"
+        format: gz
+      when: "'umap' in gravity_services"
+
+    - name: List backups
+      find:
+        paths: "{{ backup_dir }}"
+        patterns: "*.tar.gz,*.dump"
+      register: backup_files
+
+    - name: Display backup info
+      debug:
+        msg: |
+          Backup completed:
+          - UMAP Models: umap-models-{{ backup_timestamp }}.tar.gz
+          - Location: {{ backup_dir }}
+          - Total backups: {{ backup_files.files | length }}
+
+    - name: Clean old backups (keep last 7)
+      shell: |
+        ls -t {{ backup_dir }}/umap-models-*.tar.gz | tail -n +8 | xargs -r rm
+      when: backup_files.files | length > 7

package/operator/ansible/playbooks/db-setup.yml

@@ -0,0 +1,123 @@
+---
+# Gravity Platform Database Setup Playbook
+# Creates database tables - uses CREATE TABLE IF NOT EXISTS (safe to run multiple times)
+#
+# Usage:
+#   ansible-playbook -i inventory/production.yml playbooks/db-setup.yml
+#
+# Prerequisites:
+#   - Core services deployed (install.yml)
+#   - DATABASE_URL configured in /opt/gravity/.env
+#   - Required extensions enabled in your DB provider:
+#     vector, pg_stat_statements
+#     (DigitalOcean: Database → Settings → Allowed Extensions)
+
+- name: Database Setup
+  hosts: all
+  become: yes
+
+  tasks:
+    - name: "[1/5] Verify .env exists"
+      stat:
+        path: /opt/gravity/.env
+      register: env_file
+
+    - name: "[1/5] Fail if .env missing"
+      fail:
+        msg: ".env file not found at /opt/gravity/.env - run install.yml first"
+      when: not env_file.stat.exists
+
+    - name: "[2/5] Check DATABASE_URL is configured"
+      shell: grep -q "^DATABASE_URL=" /opt/gravity/.env
+      register: db_url_check
+      ignore_errors: yes
+
+    - name: "[2/5] Fail if DATABASE_URL missing"
+      fail:
+        msg: "DATABASE_URL not found in .env - configure database connection first"
+      when: db_url_check.rc != 0
+
+    - name: "[3/5] Enable required PostgreSQL extensions"
+      command: >
+        docker compose exec -T -e NODE_TLS_REJECT_UNAUTHORIZED=0 unoverse node -e
+        "const{Pool}=require('pg');
+        const p=new Pool({connectionString:process.env.DATABASE_URL,ssl:{rejectUnauthorized:false}});
+        (async()=>{
+          const exts=['vector','pg_stat_statements'];
+          const results=[];
+          for(const ext of exts){
+            try{await p.query('CREATE EXTENSION IF NOT EXISTS '+ext);results.push(ext+': OK')}
+            catch(e){results.push(ext+': FAILED ('+e.message+')')}
+          }
+          console.log(results.join('\n'));
+          await p.end();
+          process.exit(results.some(r=>r.includes('FAILED'))?1:0);
+        })()"
+      args:
+        chdir: /opt/gravity
+      register: ext_result
+      ignore_errors: yes
+
+    - name: "[3/5] Extension status"
+      debug:
+        msg: "{{ ext_result.stdout_lines | default(['No output']) }}"
+
+    - name: "[3/5] Warn if extensions failed"
+      debug:
+        msg: |
+          ⚠️  Some extensions failed to enable. You must enable them in your
+          database provider's dashboard BEFORE running this playbook.
+
+          DigitalOcean: Database → Settings → Allowed Extensions
+          Enable: vector, pg_stat_statements
+
+          See docs/runbooks/02-database.md for details.
+      when: ext_result.rc != 0
+
+    # Apply the .sql migrations with node-pg-migrate — same as `./unoverse db-setup`
+    # (scripts/lib/db-setup.sh). The old programmatic `require('./dist/db')` table
+    # setup is retired: the engine no longer ships a dist, and .sql migrations under
+    # apps/unoverse/engine/migrations are the single source of truth.
+    - name: "[4/5] Apply database migrations (node-pg-migrate)"
+      shell: |
+        docker compose exec -T -e NODE_TLS_REJECT_UNAUTHORIZED=0 unoverse \
+          npx node-pg-migrate up \
+          --migrations-dir /app/apps/unoverse/engine/migrations \
+          --migration-file-language sql \
+          --no-lock
+      args:
+        chdir: /opt/gravity
+      register: migrate_result
+      ignore_errors: yes
+
+    - name: "[4/5] Migration output"
+      debug:
+        msg: "{{ migrate_result.stdout_lines | default(['No output']) }}"
+
+    - name: "[5/5] Verify database connectivity"
+      uri:
+        url: "http://localhost:4101/health"
+        status_code: 200
+      register: db_check
+      retries: 5
+      delay: 2
+      until: db_check.status == 200
+      ignore_errors: yes
+
+  post_tasks:
+    - name: "=== DATABASE MIGRATION SUMMARY ==="
+      debug:
+        msg: |
+          ============================================
+          DATABASE MIGRATION
+          ============================================
+          Host: {{ inventory_hostname }} ({{ ansible_host }})
+          Extensions: {{ 'OK' if ext_result.rc == 0 else 'FAILED — enable in DB provider dashboard' }}
+          Migration: {{ 'OK' if migrate_result.rc == 0 else 'FAILED — check logs above' }}
+
+          If migration failed, check:
+            - Extensions enabled in DB provider (vector, pg_stat_statements)
+            - DATABASE_URL in /opt/gravity/.env
+            - Database is accessible from VM
+            - See docs/runbooks/02-database.md for setup instructions
+          ============================================

package/operator/ansible/playbooks/deploy-images.yml

@@ -0,0 +1,71 @@
+---
+# DEPLOY IMAGES — the images half of the platform deploy.
+#
+# Pull the latest DOCR images and restart. That's the whole deployment:
+#   - platform code (incl. plugin-base, baked in the unoverse image) = the images
+#   - marketplace nodes CONVERGE at boot (keep-latest: the shared installed_plugins
+#     row is "the newest version anyone chose"; boot reinstalls anything missing
+#     or older — see runtime/plugins/startup.ts)
+#   - component nodes synthesize from rx/ definitions at boot (no build, ever)
+#
+# The CLI's `unoverse deploy` runs this first, then deploy-packages.yml (the
+# local-source half). Use directly only when images alone changed.
+#
+# Usage (via CLI — recommended):
+#   unoverse deploy
+#
+# Usage (direct ansible):
+#   ansible-playbook -i inventory playbooks/deploy-a.yml
+
+- name: Deploy platform images
+  hosts: all
+  become: yes
+
+  vars:
+    gravity_dir: /opt/gravity
+
+  tasks:
+    # Sync the compose FIRST so config changes (env vars, ports, new services) ship with
+    # a normal `deploy` — not only via `deploy init`. Previously deploy just re-ran the
+    # server's existing compose, so a new env var (e.g. MEMORY_SERVICE_URL) silently never
+    # reached prod even though the image had the code. `.env` (per-server values) is left
+    # untouched — only the canonical compose is refreshed from the repo.
+    - name: "[1/4] Sync docker-compose.yml (config travels with the deploy)"
+      copy:
+        src: "{{ playbook_dir }}/../../docker-compose.yml"
+        dest: "{{ gravity_dir }}/docker-compose.yml"
+
+    - name: "[2/4] Pull latest platform images"
+      shell: |
+        cd {{ gravity_dir }}
+        docker compose pull 2>&1 | tail -8
+      register: pull_result
+
+    - name: "[2/4] Pull output"
+      debug:
+        msg: "{{ pull_result.stdout_lines[-8:] | default(['done']) }}"
+
+    - name: "[3/4] Restart on the new images (marketplace converges at boot)"
+      shell: |
+        cd {{ gravity_dir }}
+        docker compose up -d 2>&1 | tail -6
+      register: up_result
+
+    - name: "[4/4] Service status"
+      shell: |
+        cd {{ gravity_dir }}
+        docker compose ps --format '{{ '{{' }}.Name{{ '}}' }}: {{ '{{' }}.Status{{ '}}' }}' 2>&1
+      register: status_result
+
+    - name: "=== IMAGES DEPLOYED ==="
+      debug:
+        msg: |
+          ============================================
+          PLATFORM IMAGES DEPLOYED
+          ============================================
+          Host:   {{ inventory_hostname }} ({{ ansible_host }})
+          {{ status_result.stdout }}
+          Marketplace nodes converge to the recorded
+          versions at boot; component nodes synthesize
+          from rx/ definitions.
+          ============================================

package/operator/ansible/playbooks/harden.yml

@@ -0,0 +1,223 @@
+---
+# Gravity Platform VM Hardening Playbook
+# Enterprise security hardening for production VMs
+
+- name: Harden VM for Enterprise Deployment
+  hosts: all
+  become: yes
+
+  vars:
+    # SSH hardening.
+    # PermitRootLogin MUST be prohibit-password, never "no": unoverse deploy and
+    # unoverse update SSH in as root (DEPLOY_USER=root on DO). "no" locks every
+    # future deploy out of the box after the first harden run; prohibit-password
+    # keeps key-based root working and blocks only password logins — which is
+    # the attack fail2ban and this hardening actually defend against.
+    ssh_port: 22
+    ssh_permit_root_login: "prohibit-password"
+    ssh_password_authentication: "no"
+
+    # NO firewall vars here: the firewall is the ground's (cloud firewall / SGs,
+    # owned by infra/ Terraform). This playbook must never touch app ports —
+    # 4105 (API/MCP: Canvas, Studio, Claude, ChatGPT) and 3001 stay governed by
+    # the load balancer and admin_cidr, so hardening can't cut clients off.
+
+  tasks:
+    # =========================================================================
+    # SYSTEM UPDATES
+    # =========================================================================
+    - name: Update all packages (Debian/Ubuntu)
+      apt:
+        upgrade: safe
+        update_cache: yes
+        cache_valid_time: 3600
+      when: ansible_facts['os_family'] == "Debian"
+
+    - name: Update all packages (RHEL/Amazon Linux)
+      dnf:
+        name: "*"
+        state: latest
+        security: yes
+      when: ansible_facts['os_family'] == "RedHat"
+
+    - name: Install security packages (Debian/Ubuntu)
+      apt:
+        name:
+          - fail2ban
+          - unattended-upgrades
+          - logrotate
+        state: present
+      when: ansible_facts['os_family'] == "Debian"
+
+    - name: Install security packages (RHEL/Amazon Linux)
+      dnf:
+        name:
+          - fail2ban
+          - dnf-automatic
+          - logrotate
+          - audit
+        state: present
+      when: ansible_facts['os_family'] == "RedHat"
+
+    # =========================================================================
+    # SSH HARDENING
+    # =========================================================================
+    - name: Configure SSH - Disable root login
+      lineinfile:
+        path: /etc/ssh/sshd_config
+        regexp: "^#?PermitRootLogin"
+        line: "PermitRootLogin {{ ssh_permit_root_login }}"
+      notify: Restart SSH
+
+    - name: Configure SSH - Disable password authentication
+      lineinfile:
+        path: /etc/ssh/sshd_config
+        regexp: "^#?PasswordAuthentication"
+        line: "PasswordAuthentication {{ ssh_password_authentication }}"
+      notify: Restart SSH
+
+    - name: Configure SSH - Use only SSH protocol 2
+      lineinfile:
+        path: /etc/ssh/sshd_config
+        regexp: "^#?Protocol"
+        line: "Protocol 2"
+      notify: Restart SSH
+
+    - name: Configure SSH - Set login grace time
+      lineinfile:
+        path: /etc/ssh/sshd_config
+        regexp: "^#?LoginGraceTime"
+        line: "LoginGraceTime 60"
+      notify: Restart SSH
+
+    - name: Configure SSH - Limit max auth tries
+      lineinfile:
+        path: /etc/ssh/sshd_config
+        regexp: "^#?MaxAuthTries"
+        line: "MaxAuthTries 3"
+      notify: Restart SSH
+
+    # =========================================================================
+    # FIREWALL: NONE HERE (moved to the ground, 2026-07-28)
+    # =========================================================================
+    # The cloud firewall (DO cloud firewall / AWS security groups, owned by
+    # infra/ Terraform) is the boundary. Host ufw/firewalld was removed: Docker's
+    # iptables rules BYPASS ufw for published ports, so it protected nothing —
+    # the ground firewall structurally can't be bypassed (traffic never reaches
+    # the box). On-prem: firewall at the customer's network layer, not here.
+
+    - name: Configure fail2ban for SSH
+      copy:
+        dest: /etc/fail2ban/jail.local
+        content: |
+          [DEFAULT]
+          bantime = 3600
+          findtime = 600
+          maxretry = 3
+
+          [sshd]
+          enabled = true
+          port = {{ ssh_port }}
+          filter = sshd
+          logpath = /var/log/auth.log
+          maxretry = 3
+      notify: Restart fail2ban
+
+    # =========================================================================
+    # AUTOMATIC SECURITY UPDATES
+    # =========================================================================
+    - name: Enable automatic security updates (Debian/Ubuntu)
+      copy:
+        dest: /etc/apt/apt.conf.d/20auto-upgrades
+        content: |
+          APT::Periodic::Update-Package-Lists "1";
+          APT::Periodic::Unattended-Upgrade "1";
+          APT::Periodic::AutocleanInterval "7";
+      when: ansible_facts['os_family'] == "Debian"
+
+    - name: Enable automatic security updates (RHEL/Amazon Linux)
+      service:
+        name: dnf-automatic.timer
+        state: started
+        enabled: yes
+      when: ansible_facts['os_family'] == "RedHat"
+
+    # =========================================================================
+    # SYSTEM LIMITS
+    # =========================================================================
+    - name: Set file descriptor limits
+      copy:
+        dest: /etc/security/limits.d/gravity.conf
+        content: |
+          # Gravity Platform limits
+          * soft nofile 65535
+          * hard nofile 65535
+          root soft nofile 65535
+          root hard nofile 65535
+
+    # =========================================================================
+    # DOCKER HARDENING
+    # =========================================================================
+    - name: Create Docker daemon config
+      copy:
+        dest: /etc/docker/daemon.json
+        content: |
+          {
+            "log-driver": "json-file",
+            "log-opts": {
+              "max-size": "100m",
+              "max-file": "3"
+            },
+            "live-restore": true,
+            "userland-proxy": false
+          }
+      notify: Restart Docker
+
+    # =========================================================================
+    # AUDIT LOGGING
+    # =========================================================================
+    - name: Install auditd (Debian/Ubuntu)
+      apt:
+        name: auditd
+        state: present
+      when: ansible_facts['os_family'] == "Debian"
+
+    - name: Ensure auditd running (RHEL/Amazon Linux)
+      service:
+        name: auditd
+        state: started
+        enabled: yes
+      when: ansible_facts['os_family'] == "RedHat"
+
+    - name: Configure audit rules for Docker
+      copy:
+        dest: /etc/audit/rules.d/docker.rules
+        content: |
+          # Docker daemon
+          -w /usr/bin/docker -p wa -k docker
+          -w /var/lib/docker -p wa -k docker
+          -w /etc/docker -p wa -k docker
+          -w /lib/systemd/system/docker.service -p wa -k docker
+          -w /etc/docker/daemon.json -p wa -k docker
+      notify: Restart auditd
+
+  handlers:
+    - name: Restart SSH
+      service:
+        name: ssh
+        state: restarted
+
+    - name: Restart fail2ban
+      service:
+        name: fail2ban
+        state: restarted
+
+    - name: Restart Docker
+      service:
+        name: docker
+        state: restarted
+
+    - name: Restart auditd
+      service:
+        name: auditd
+        state: restarted