agents-city 0.1.0 → 0.2.0

package/city/web/src/bienvenida.ts

@@ -0,0 +1,520 @@
+/**
+ * First run: a city, built by answering five short questions.
+ *
+ * What was here before was a checklist on a page of statistics about a city
+ * that did not exist yet, and the Hall opened on a map with nothing to draw —
+ * "Not drawn yet" as a first impression. A person arriving for the first time
+ * does not need a dashboard. They need to be told, in their own words, what
+ * this thing is and what to do next.
+ *
+ * So: one question per screen, plain language, every jargon word explained the
+ * first time it appears, and nothing mandatory except the two decisions the
+ * product genuinely cannot invent — what kind of work happens here, and who
+ * does it. Everything is skippable and everything is re-editable afterwards
+ * from the same pages that own it, because this flow writes through the very
+ * same endpoints those pages use. It is a guide, not a second implementation.
+ */
+
+export interface Dominio {
+  id: string;
+  name: string;
+  summary: string;
+}
+export interface Rol {
+  id: string;
+  name: string;
+  summary: string;
+  trade: string;
+}
+export interface RepoDelDisco {
+  nombre: string;
+  ruta: string;
+  cuando: string;
+  mio: boolean;
+}
+
+/** What the onboarding needs from the Hall. Passed in rather than imported, so
+ * this file cannot quietly grow its own way of talking to the server. */
+export interface Puerta {
+  api: <T>(ruta: string, opts?: RequestInit) => Promise<T>;
+  esc: (s: unknown) => string;
+  aviso: (texto: string, malo?: boolean) => void;
+  refresca: () => Promise<void>;
+  /** Leave the guide and open a normal Hall section. */
+  vete: (seccion: string) => void;
+  ciudad: string;
+  yo: string;
+  datos: string;
+}
+
+interface AgenteNuevo {
+  nombre: string;
+  clase: string;
+  rol: string;
+  montajes: string[];
+}
+
+const CLASES: Array<[string, string, string]> = [
+  [
+    'code',
+    'It writes code',
+    'Its house grows with the pull requests it merges. Mounts repositories and worktrees.',
+  ],
+  [
+    'knowledge',
+    'It keeps knowledge',
+    'Its house grows with the documents it writes. Needs no git at all.',
+  ],
+  ['coordinator', 'It coordinates', 'Its house grows with the decisions it records.'],
+];
+
+const PASOS = ['Welcome', 'The work', 'Your chair', 'The agents', 'Ready'];
+
+/** A house, drawn rather than shipped: the same isometric shape the map and the
+ * desktop icon use, so the first thing somebody sees is already the product. */
+function casita(color: string): string {
+  return `<svg viewBox="0 0 120 108" role="img" aria-label="an isometric house" class="bvCasa">
+    <polygon points="60,10 112,40 60,70 8,40" fill="${color}" opacity=".95"/>
+    <polygon points="8,40 60,70 60,100 8,70" fill="${color}" opacity=".62"/>
+    <polygon points="112,40 60,70 60,100 112,70" fill="${color}" opacity=".40"/>
+  </svg>`;
+}
+
+export class Bienvenida {
+  private paso = 0;
+  private dominios: Dominio[] = [];
+  private roles: Rol[] = [];
+  private rolesDeAgente: Rol[] = [];
+  private repos: RepoDelDisco[] = [];
+  private dominio = '';
+  private rol = '';
+  private roster: AgenteNuevo[] = [];
+  private enCurso: AgenteNuevo | null = null;
+  private guardando = false;
+  private buscandoRepos = false;
+  private reposListos = false;
+  private lienzo: HTMLElement | null = null;
+
+  constructor(private readonly p: Puerta) {}
+
+  /** Draw the current step into `lienzo`. The only entry point. */
+  async pinta(lienzo: HTMLElement): Promise<void> {
+    this.lienzo = lienzo;
+    if (!this.dominios.length) {
+      lienzo.innerHTML = '<p class="cargando">reading the domain packs</p>';
+      const [d, ra] = await Promise.all([
+        this.p.api<{ domains: Dominio[] }>('/api/domains'),
+        this.p.api<{ roles: Rol[] }>('/api/roles?scope=agent'),
+      ]);
+      this.dominios = d.domains;
+      this.rolesDeAgente = ra.roles;
+    }
+    lienzo.innerHTML = `<div class="bv">${this.cabecera()}${await this.cuerpo()}</div>`;
+    this.enlaza(lienzo);
+  }
+
+  private cabecera(): string {
+    const puntos = PASOS.map(
+      (nombre, i) =>
+        `<span class="bvPunto ${i === this.paso ? 'aqui' : i < this.paso ? 'hecho' : ''}"
+          title="${this.p.esc(nombre)}"><i></i>${this.p.esc(nombre)}</span>`,
+    ).join('');
+    return `<div class="bvPasos">${puntos}</div>`;
+  }
+
+  private async cuerpo(): Promise<string> {
+    switch (this.paso) {
+      case 0:
+        return this.pantallaHola();
+      case 1:
+        return this.pantallaDominio();
+      case 2:
+        return await this.pantallaRol();
+      case 3:
+        return this.pantallaAgentes();
+      default:
+        return this.pantallaFinal();
+    }
+  }
+
+  // ── 0. what this is ────────────────────────────────────────────────────────
+  private pantallaHola(): string {
+    return `
+      <div class="bvHola">
+        <div class="bvArte">${casita('#7048e8')}${casita('#45b9a7')}${casita('#f2674a')}</div>
+        <div>
+          <span class="sub">welcome</span>
+          <h1>A city is you, and the agents who work with you</h1>
+          <p class="prosa">You take the chair. Each <b>agent</b> is one worker with its own
+          window, its own role and its own corner of your disk — a repository, three of them,
+          a folder of documents, whatever it actually works on. They never talk to each other
+          behind your back: you chair, they answer.</p>
+          <p class="prosa">Everything lives as plain files in
+          <code class="mono">${this.p.esc(this.p.datos)}</code>. Nothing leaves this machine,
+          there is no account, and you can edit any of it by hand afterwards.</p>
+          <p class="prosa"><b>Four questions and you are working.</b> You can skip any of them
+          and change everything later.</p>
+          <div class="bvBotones">
+            <button class="bt ppal" data-bv="siguiente">Let’s build it</button>
+            <button class="bt" data-bv="salir">I’ll set it up myself</button>
+          </div>
+        </div>
+      </div>`;
+  }
+
+  // ── 1. the domain ─────────────────────────────────────────────────────────
+  private pantallaDominio(): string {
+    const tarjetas = this.dominios
+      .map(
+        (d) => `
+      <button class="bvOpcion ${this.dominio === d.id ? 'elegida' : ''}" data-bv="dominio"
+        data-id="${this.p.esc(d.id)}">
+        <b>${this.p.esc(d.name)}</b><span>${this.p.esc(d.summary)}</span></button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">question 1 of 4</span>
+        <h1>What kind of work happens here?</h1>
+        <p class="prosa">It decides the vocabulary, the roles you will be offered and what
+        counts as evidence in a decision. A clinic does not ship pull requests, and a law
+        firm does not measure story points. Pick the closest one — you can change it later.</p>
+        <div class="bvRejilla">${tarjetas}</div>
+        <div class="bvBotones">
+          <button class="bt" data-bv="atras">Back</button>
+          <button class="bt ppal" data-bv="siguiente" ${this.dominio ? '' : 'disabled'}>Next</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 2. your chair ─────────────────────────────────────────────────────────
+  private async pantallaRol(): Promise<string> {
+    if (!this.roles.length || this.roles[0]?.id === undefined) {
+      const r = await this.p.api<{ roles: Rol[] }>(
+        '/api/roles?domain=' + encodeURIComponent(this.dominio),
+      );
+      this.roles = r.roles;
+    }
+    const tarjetas = this.roles
+      .map(
+        (r) => `
+      <button class="bvOpcion ${this.rol === r.id ? 'elegida' : ''}" data-bv="rol"
+        data-id="${this.p.esc(r.id)}">
+        <b>${this.p.esc(r.name)}</b><span>${this.p.esc(r.summary || r.trade)}</span></button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">question 2 of 4</span>
+        <h1>And what are you, here?</h1>
+        <p class="prosa">You chair this city whatever you answer — this is your
+        <b>speciality</b>, not your authority. It shapes the perspective you bring to a
+        decision and the knowledge files the city writes for you. <b>Blank</b> is a real
+        answer: it means no preset knowledge.</p>
+        <div class="bvRejilla">${tarjetas}</div>
+        <div class="bvBotones">
+          <button class="bt" data-bv="atras">Back</button>
+          <button class="bt ppal" data-bv="siguiente" ${this.rol ? '' : 'disabled'}>Next</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 3. the agents ─────────────────────────────────────────────────────────
+  private pantallaAgentes(): string {
+    // The repository index is a disk scan — a minute on a big home the first
+    // time. Awaiting it here froze the guide on the PREVIOUS screen with no
+    // explanation: the person clicks Next and nothing happens. So the step
+    // draws immediately and the list arrives when it arrives.
+    this.buscaReposUnaVez();
+    if (!this.enCurso) return this.listaDeAgentes();
+    return this.formularioDeAgente(this.enCurso);
+  }
+
+  private buscaReposUnaVez(): void {
+    if (this.reposListos || this.buscandoRepos) return;
+    this.buscandoRepos = true;
+    void this.p
+      .api<{ repos: RepoDelDisco[] }>('/api/misrepos?user=' + encodeURIComponent(this.p.yo))
+      .then((r) => {
+        this.repos = (r.repos ?? []).slice(0, 200);
+      })
+      .catch(() => {
+        this.repos = []; // no index is not a reason to block the flow
+      })
+      .finally(() => {
+        this.buscandoRepos = false;
+        this.reposListos = true;
+        // Only repaint if this step is still on screen.
+        if (this.lienzo && this.paso === 3) void this.pinta(this.lienzo);
+      });
+  }
+
+  private listaDeAgentes(): string {
+    const fichas = this.roster
+      .map(
+        (a) => `
+      <div class="bvFicha">
+        <b>${this.p.esc(a.nombre)}</b>
+        <span>${this.p.esc(a.clase)} · ${this.p.esc(a.rol)}</span>
+        <span class="de">${
+          a.montajes.length
+            ? this.p.esc(a.montajes.map((m) => m.split('/').pop()).join(', '))
+            : 'nothing mounted yet'
+        }</span>
+      </div>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">question 3 of 4</span>
+        <h1>${this.roster.length ? 'Who else works here?' : 'Who works with you?'}</h1>
+        <p class="prosa">An <b>agent</b> is one worker: it gets its own window, its own role
+        and its own corner of your disk. It is <b>not</b> a repository — one agent can answer
+        for three services and a folder of documents at once, and an agent whose work is
+        documents needs no git anywhere.</p>
+        ${this.roster.length ? `<div class="bvFichas">${fichas}</div>` : ''}
+        <div class="bvBotones">
+          <button class="bt ppal" data-bv="nuevo">${
+            this.roster.length ? 'Add another agent' : 'Add the first agent'
+          }</button>
+          <button class="bt" data-bv="siguiente">${
+            this.roster.length ? 'That is everyone' : 'Skip — just me for now'
+          }</button>
+        </div>
+      </div>`;
+  }
+
+  private formularioDeAgente(a: AgenteNuevo): string {
+    const clases = CLASES.map(
+      ([id, titulo, porque]) => `
+      <button class="bvOpcion ${a.clase === id ? 'elegida' : ''}" data-bv="clase" data-id="${id}">
+        <b>${titulo}</b><span>${porque}</span></button>`,
+    ).join('');
+    const roles = this.rolesDeAgente
+      .map(
+        (r) =>
+          `<option value="${this.p.esc(r.id)}"${r.id === a.rol ? ' selected' : ''}>${this.p.esc(
+            r.name,
+          )}</option>`,
+      )
+      .join('');
+    const sugeridos = this.repos
+      .filter((r) => r.mio)
+      .slice(0, 12)
+      .map(
+        (r) => `<button class="bvChip ${a.montajes.includes(r.ruta) ? 'elegida' : ''}"
+          data-bv="monta" data-ruta="${this.p.esc(r.ruta)}">${this.p.esc(r.nombre)}</button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">a new agent</span>
+        <h1>Tell me about this one</h1>
+        <div class="campo"><label>What do you call it?</label>
+          <input type="text" id="bvNombre" value="${this.p.esc(a.nombre)}"
+            placeholder="urgencias, api, the handbook — whatever you would say out loud"></div>
+        <label class="bvEtiqueta">What kind of work does it do?</label>
+        <div class="bvRejilla bvTres">${clases}</div>
+        <div class="campo"><label>Its role — its speciality, never authority</label>
+          <select id="bvRol">${roles}</select></div>
+        <label class="bvEtiqueta">What does it work on?</label>
+        <p class="pista">Pick any of your repositories, and add folders by hand. As many as
+        you like — this is the part that makes it an agent and not a repo.</p>
+        ${
+          sugeridos
+            ? `<div class="bvChips">${sugeridos}</div>`
+            : this.buscandoRepos
+              ? '<p class="cargando">looking through your disk for repositories…</p>'
+              : '<p class="pista">No repositories found on this disk — add folders by path below.</p>'
+        }
+        <div class="campo"><label>…or a path, and Enter</label>
+          <input type="text" id="bvRuta" placeholder="~/documents/handbook"></div>
+        ${
+          a.montajes.length
+            ? `<p class="pista">Working on: <b>${this.p.esc(a.montajes.join(', '))}</b></p>`
+            : ''
+        }
+        <div class="bvBotones">
+          <button class="bt" data-bv="cancela">Cancel</button>
+          <button class="bt ppal" data-bv="guarda" ${this.guardando ? 'disabled' : ''}>${
+            this.guardando ? 'adding…' : 'Add this agent'
+          }</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 4. done ───────────────────────────────────────────────────────────────
+  private pantallaFinal(): string {
+    return `
+      <div class="bvPaso">
+        <span class="sub">ready</span>
+        <h1>${this.p.esc(this.p.ciudad)} is alive</h1>
+        <p class="prosa">Your seat is written and ${
+          this.roster.length
+            ? `<b>${this.roster.length}</b> agent${this.roster.length === 1 ? '' : 's'} live here`
+            : 'the city is waiting for its first agent'
+        }. Everything you just answered is a plain file you can read and edit.</p>
+        <p class="prosa">What people usually do next:</p>
+        <div class="bvSiguientes">
+          <button class="bt ppal" data-bv="sesion">Open my session</button>
+          <button class="bt" data-bv="ir-gente">See the agents</button>
+          <button class="bt" data-bv="ir-mapa">Draw the map</button>
+          <button class="bt" data-bv="ir-puesto">Set a goal</button>
+        </div>
+        <p class="pista">A goal is optional, and the city works without one — but a round with
+        no goal is a status report, because there is nothing to argue against.</p>
+      </div>`;
+  }
+
+  // ── wiring ────────────────────────────────────────────────────────────────
+  private enlaza(lienzo: HTMLElement): void {
+    const repinta = (): void => void this.pinta(lienzo);
+    lienzo.querySelectorAll<HTMLElement>('[data-bv]').forEach((el) => {
+      el.onclick = async (evento) => {
+        evento.preventDefault();
+        const que = el.dataset.bv;
+        if (que === 'salir') return this.p.vete('resumen');
+        if (que === 'atras') {
+          this.paso = Math.max(0, this.paso - 1);
+          return repinta();
+        }
+        if (que === 'dominio') {
+          this.dominio = el.dataset.id ?? '';
+          this.roles = [];
+          this.rol = '';
+          return repinta();
+        }
+        if (que === 'rol') {
+          this.rol = el.dataset.id ?? '';
+          return repinta();
+        }
+        if (que === 'nuevo') {
+          this.enCurso = { nombre: '', clase: 'code', rol: 'blank', montajes: [] };
+          return repinta();
+        }
+        if (que === 'clase' && this.enCurso) {
+          this.enCurso.clase = el.dataset.id ?? 'code';
+          this.recogeFormulario(lienzo);
+          return repinta();
+        }
+        if (que === 'monta' && this.enCurso) {
+          const ruta = el.dataset.ruta ?? '';
+          const ya = this.enCurso.montajes.indexOf(ruta);
+          if (ya >= 0) this.enCurso.montajes.splice(ya, 1);
+          else this.enCurso.montajes.push(ruta);
+          this.recogeFormulario(lienzo);
+          return repinta();
+        }
+        if (que === 'cancela') {
+          this.enCurso = null;
+          return repinta();
+        }
+        if (que === 'guarda') return void (await this.guardaAgente(lienzo));
+        if (que === 'siguiente') return void (await this.avanza(lienzo));
+        if (que === 'sesion') return void (await this.abreSesion());
+        if (que === 'ir-gente') return this.p.vete('gente');
+        if (que === 'ir-mapa') return this.p.vete('mapa');
+        if (que === 'ir-puesto') return this.p.vete('puesto');
+      };
+    });
+    const ruta = lienzo.querySelector<HTMLInputElement>('#bvRuta');
+    if (ruta)
+      ruta.onkeydown = (e) => {
+        if (e.key !== 'Enter' || !this.enCurso) return;
+        e.preventDefault();
+        const valor = ruta.value.trim();
+        if (valor) this.enCurso.montajes.push(valor);
+        this.recogeFormulario(lienzo);
+        void this.pinta(lienzo);
+      };
+    lienzo.querySelector<HTMLInputElement>('#bvNombre')?.focus();
+  }
+
+  /** Keep what is typed when a click forces a repaint. */
+  private recogeFormulario(lienzo: HTMLElement): void {
+    if (!this.enCurso) return;
+    const nombre = lienzo.querySelector<HTMLInputElement>('#bvNombre');
+    const rol = lienzo.querySelector<HTMLSelectElement>('#bvRol');
+    if (nombre) this.enCurso.nombre = nombre.value;
+    if (rol) this.enCurso.rol = rol.value;
+  }
+
+  private async guardaAgente(lienzo: HTMLElement): Promise<void> {
+    this.recogeFormulario(lienzo);
+    const a = this.enCurso;
+    if (!a) return;
+    if (!a.nombre.trim()) {
+      this.p.aviso('Give it a name — it is how you will call it in its window', true);
+      return;
+    }
+    this.guardando = true;
+    await this.pinta(lienzo);
+    try {
+      // The seat has to exist before an agent can join it: agents live on the
+      // owner's card. Writing it here is why this step can come before the goal.
+      await this.aseguraFicha();
+      const r = await this.p.api<{ ok?: boolean; agent?: string; error?: string }>('/api/agentes', {
+        method: 'POST',
+        body: JSON.stringify({ name: a.nombre.trim(), kind: a.clase, role: a.rol }),
+      });
+      if (!r.ok || !r.agent) {
+        this.p.aviso(r.error || 'Could not add that agent', true);
+        return;
+      }
+      for (const ruta of a.montajes) {
+        const m = await this.p.api<{ ok?: boolean; error?: string }>('/api/montaje', {
+          method: 'POST',
+          body: JSON.stringify({ agent: r.agent, add: ruta }),
+        });
+        if (!m.ok) this.p.aviso(`${ruta}: ${m.error ?? 'could not mount'}`, true);
+      }
+      this.roster.push({ ...a, nombre: a.nombre.trim() });
+      this.enCurso = null;
+      this.p.aviso(`${a.nombre.trim()} joined the city`);
+      await this.p.refresca();
+    } catch (e) {
+      this.p.aviso(String(e), true);
+    } finally {
+      this.guardando = false;
+      await this.pinta(lienzo);
+    }
+  }
+
+  private async aseguraFicha(): Promise<void> {
+    await this.p.api<{ ok?: boolean; error?: string }>('/api/ficha', {
+      method: 'POST',
+      body: JSON.stringify({ domain: this.dominio || 'software', role: this.rol || 'blank' }),
+    });
+  }
+
+  private async avanza(lienzo: HTMLElement): Promise<void> {
+    // The step moves FIRST, and only then does anything touch the server.
+    // Refreshing the Hall repaints this view, and a repaint that lands after a
+    // slow write would otherwise redraw the step the person just left — the
+    // guide silently bouncing back one screen.
+    const escribeLaFicha = this.paso === 2;
+    this.paso = Math.min(PASOS.length - 1, this.paso + 1);
+    await this.pinta(lienzo);
+    if (escribeLaFicha) {
+      // The chair is written the moment it is answered, so leaving halfway
+      // still leaves a usable city behind rather than nothing.
+      await this.aseguraFicha();
+      await this.p.refresca();
+    }
+  }
+
+  private async abreSesion(): Promise<void> {
+    try {
+      const r = await this.p.api<{ ok?: boolean; attach?: string; error?: string }>('/api/sesion', {
+        method: 'POST',
+        body: JSON.stringify({ user: this.p.yo }),
+      });
+      this.p.aviso(
+        r.ok && r.attach ? `Session built — attach with: ${r.attach}` : (r.error ?? 'Could not'),
+        !r.ok,
+      );
+    } catch (e) {
+      this.p.aviso(String(e), true);
+    }
+  }
+}