Clepit

Sebagian besar teks berformat berakhir di basis data sebagai satu bongkah HTML. Itu tidak masalah sampai Anda ingin melakukan sesuatu selain menampilkannya kembali: menemukan setiap halaman yang menyebut seorang pelanggan, menyajikan dokumen yang sama ke halaman web, surel, dan aplikasi seluler, atau membiarkan dua orang menyuntingnya bersamaan tanpa salah satunya kehilangan paragraf. Pada titik itu kata dan formatnya sudah saling terjalin, dan satu-satunya yang masih dapat membaca dokumen itu dengan andal adalah editor yang menulisnya.

Clepit memisahkan keduanya. Sebuah halaman adalah daftar blok, masing-masing objek kecil bertipe, dan dokumennya berupa JSON: tidak ada markup untuk diurai, dan tidak perlu editor untuk membacanya. Itu pula sebabnya editor ini berdiri sendiri. @clepit/core terbit di npm dengan lisensi MIT dan tidak tahu apa-apa tentang sisi terkelola, sementara ruang kerja di app.clepit.com adalah wujud dokumen yang sama setelah diberi kolaborator, izin, riwayat, dan alamat di web publik.

Halaman adalah daftar blok

Sebuah blok terdiri dari empat bidang: id, tipe, data yang ditentukan tipe itu, dan penyetelan apa pun yang dikenakan padanya. Data sebuah paragraf berbentuk lain daripada data sebuah tabel, dan tipe itulah yang memberi tahu bentuk apa yang harus diharapkan, sehingga dokumen tersimpan bisa diperiksa, bukan sekadar diurai. Satu halaman utuh adalah stempel waktu, sebuah versi, dan blok-blok menurut urutannya, cukup kecil untuk dibaca dengan mata sendiri dan ditelaah dalam sebuah pull request. Tidak ada di dalamnya yang menerangkan bagaimana halaman itu seharusnya tampak: itu urusan apa pun yang menggambarnya, dan justru itulah yang membuat satu dokumen bisa menjadi halaman web, surel, dan layar ponsel tanpa perlu ada tiga salinannya.

Menggambar dokumen tanpa peramban

Perender tidak pernah menulis langsung ke peramban. Ia menggambar lewat satu lapisan tipis dengan dua penopang di belakangnya: satu membangun simpul halaman yang sebenarnya, satu lagi membangun untai teks, dan kode blok yang sama berjalan pada keduanya. Begitulah halaman terbit digambar di server yang sama sekali tak punya peramban, dan karena itu apa yang dihasilkan server adalah dokumen yang sama dengan yang akan ditampilkan editor, bukan penerapan kedua yang dibiarkan melenceng. Penopang untai meminta penyaring sebagai argumen wajib dan sengaja tidak punya nilai bawaan: penyaring biasa pada paket ini membangun halaman dulu agar bisa mengurai, jadi tak mungkin berjalan di sana, sedangkan diam-diam beralih ke pelolosan karakter akan mencabut format di dalam setiap dokumen tanpa mengatakannya. Maka celah itu dibiarkan terlihat di tempat ia dipakai, bukan disembunyikan dalam nilai bawaan.

Membaca tidak menuntut JavaScript apa pun dari pembaca

Adapter React mengirim dua paruhnya secara terpisah, sebab keduanya menginginkan hal yang berlawanan. Komponen isi berjalan di server dan mengeluarkan markup jadi selagi halaman dibangun, sehingga pembaca menerima dokumen pada tanggapan pertama. Komponen editor hanya hidup di sisi klien, karena ia memegang daur hidup editor, dan tak ada yang perlu dipegang sebelum ada peramban. Maka membaca dokumen Clepit sama sekali tidak memerlukan JavaScript. Saat menulislah waktu jalan itu datang.

Apa saja yang bisa dimuat sebuah halaman

Dua puluh enam jenis blok ikut dalam paket ini. Sebagian besar adalah yang dibutuhkan editor mana pun: judul, paragraf, daftar, daftar centang, kutipan, kode, tabel, gambar, audio, video, berkas, kotak sorot, dan pemisah. Sisanya ada karena penulisan dokumentasi menuntut hal-hal yang biasanya diabaikan perkakas menulis. Daftar isi yang menyusun dirinya sendiri dari judul-judul dokumen dan menautkan ke masing-masing. Bagian yang bisa dilipat dan kolom. Kartu yang mewakili halaman lain. Sketsa tangan bebas. Dan blok aktivitas yang menyimpan dokumen mana yang diawasi, bukan salinan aktivitasnya, sehingga ia terus menampilkan apa yang sedang terjadi alih-alih membeku pada hari ia disisipkan. Format di dalam blok mencakup tanda-tanda biasa, tebal, miring, garis bawah, coret, kode sebaris, sorotan, dan tautan, ditambah tooltip, label status, dan sebutan. Paket itu sendiri tidak punya ketergantungan waktu jalan apa pun.

Rumus dan diagram, digambar di dalam paket

Dua dari blok-blok itu menampilkan LaTeX dan Mermaid, dan keduanya mengerjakan seluruhnya di dalam paket: mengurai sumber, menghitung tata letak, menggambar hasilnya. Tidak ada pustaka penggambar di bawahnya dan tidak ada panggilan ke layanan mana pun untuk mengubah rumus atau bagan alir menjadi gambar. Itu bukan sekadar selera soal ketergantungan, melainkan akibat dari penopang untai. Sebuah blok yang menjangkau sesuatu yang hanya disediakan peramban, atau menjangkau jaringan, tidak akan bisa digambar di server yang menyajikan halaman terbit, dan halaman yang sama lalu akan tampak berbeda tergantung siapa yang memintanya.

Rujukan API yang tinggal di dalam halaman

Berikan spesifikasi kepada blok OpenAPI, ditempel langsung atau ditunjuk lewat alamat, dan ia akan menggambar apa yang diterangkan spesifikasi itu: operasi-operasinya, jalur dan parameternya, skema permintaan dan tanggapan, serta cara autentikasinya. Untuk tiap operasi ia juga menyusun cuplikan permintaan dalam cURL, TypeScript, Dart, dan Python, dibangkitkan dari spesifikasi alih-alih diketik penulis yang nanti lupa memperbaruinya. Blok sematan memandang dunia luar dengan cara yang sama: ia mengenali segelintir layanan yang benar-benar dapat ditampilkannya, memperlakukan tautan biasa sebagai hasil yang sah dan bukan kegagalan untuk selebihnya, dan terang-terangan menolak menggambar alamat yang tidak dipercayainya.

Dua orang dalam paragraf yang sama

Halaman yang sedang disunting langsung dipegang oleh satu tugas di server, satu untuk tiap halaman, dan setiap pembaruan melewatinya secara berurutan. Itulah yang membuat penyuntingan bersamaan masih bisa dinalar: tidak ada penulis kedua yang berlomba dengan yang pertama. Dokumennya sendiri berupa CRDT, sehingga dua orang yang mengetik di paragraf yang sama akan menyatu alih-alih saling menimpa, dan klien yang tertinggal menyusul dengan bertukar apa pun yang kurang di masing-masing sisi. Setiap pembaruan ditambahkan ke write-ahead log sebelum disiarkan kepada siapa pun, jadi apa yang dilihat orang lain di dalam dokumen sudah tercatat secara tahan lama, bukan sekadar diteruskan. Izin ditegakkan di server dan bukan di antarmuka: rekan yang bergabung tanpa hak menyunting diturunkan menjadi pembaca, dan sesi memeriksa ulang hak itu secara berkala selama dokumen terbuka, sehingga akses yang dicabut mengenai orang yang sedang mengetik alih-alih menunggu ia memuat ulang halaman.

Setiap penulisan lewat satu pintu

Sebuah dokumen dapat diubah oleh orang yang mengetik di dalamnya dan oleh program yang memanggil API, dan dulu kedua jalur itu bisa menulis ke halaman yang sama secara terpisah. Sekarang tidak bisa lagi. Penulisan dari API diteruskan ke sesi yang sama yang memegang dokumen hidup itu, lalu diterapkan sebagai satu transaksi berdampingan dengan suntingan langsung, sehingga hanya ada satu urutan kejadian alih-alih dua penulis dengan pendapat masing-masing tentang isi halaman. Id blok dipertahankan saat dokumen ditulis kembali, sebab komentar berlabuh padanya dan rekonsiliasi yang mencetak id baru akan meninggalkan setiap komentar menunjuk ke kehampaan. Dan bila kumpulan blok yang dihasilkan persis sama dengan yang sudah tersimpan, tidak ada yang ditulis sama sekali.

Satu-satunya jalur yang tak terjangkau kunci mesin

Kunci API pribadi berlaku untuk REST, GraphQL, soket langganan GraphQL, dan MCP. Kunci itu tidak berlaku untuk soket kolaborasi, dan itu disengaja. Setiap pembaruan kolaboratif dicap dengan orang yang melakukannya, dan cap-cap itulah yang menjadi kepengarangan yang tercatat dalam riwayat halaman. Sebuah principal mesin yang menyunting di sana akan menuliskan pengarang yang tak pernah ditulis manusia mana pun, dan membatalkannya belakangan berarti menulis ulang sejarah, bukan menghapus satu baris. Garis pemisahnya bukan antara websoket dan HTTP: melainkan apakah jalur itu menulis riwayat bernama pengarang. Aturan ini ditegakkan oleh bentuk kodenya, bukan oleh ingatan, sebab menerima sebuah kunci menuntut peralihan yang disengaja ke panggilan autentikasi yang lain, dan sebuah pengujian gagal begitu ada jalur yang melakukannya.

Ruang kerja dengan alamatnya sendiri

Setiap ruang kerja adalah tenant dengan subdomainnya sendiri sejak saat dibuat, dan tenant itu ditentukan dari alamat tempat permintaan tiba. Jadi Anda berada di tenant yang mana sudah diputuskan sebelum satu pun data Anda dibaca, bukan lewat saringan yang ditambahkan belakangan dan bisa saja terlupakan. Di bawahnya, basis data sendirilah yang menegakkan batas itu lewat keamanan tingkat baris: tiap permintaan meminjam satu koneksi, mencapkan identitas pemanggil padanya, dan kolam koneksi menghapus keadaan itu ketika koneksi dikembalikan, sehingga identitas satu permintaan tidak bisa merembes ke kueri permintaan berikutnya.

Mengklaim domain tidak sama dengan membuktikannya

Ruang kerja pada paket Enterprise dapat menyajikan halamannya dari domain miliknya sendiri. Mengklaim domain dan menyajikan darinya sengaja dibuat sebagai dua langkah terpisah: domain itu disimpan dalam keadaan belum terverifikasi, dan pemecah alamat mengabaikannya sama sekali sampai sebuah catatan verifikasi muncul di DNS. Siapa pun bisa mengetikkan alamat perusahaan lain ke dalam sebuah formulir. Hanya orang yang menguasai domain itu yang dapat menerbitkan catatan yang membuatnya hidup.

Setiap versi yang pernah dimiliki halaman itu

Clepit menyimpan revisi, bukan satu keadaan terkini saja. Cuplikan diambil otomatis sementara orang bekerja, ditahan lajunya agar pengetikan biasa tidak menghasilkan ratusan: satu cuplikan baru ditulis begitu sepuluh menit berlalu atau sepuluh blok berubah, mana yang lebih dulu. Pemulihan adalah satu transaksi: cuplikan lama diterapkan, blok-blok direkonsiliasi, dan pemulihan itu sendiri ditulis sebagai revisi baru, sehingga langkah mundur tercatat alih-alih dibatalkan diam-diam. Rekonsiliasi sengaja mempertahankan id blok sumbernya, sebab komentar berlabuh pada blok, dan memulihkan halaman dengan id baru akan meninggalkan setiap komentar di sana tanpa labuhan.

Menemukannya kembali

Pencarian berjalan di atas proyeksi halaman-halaman itu, dan kuerinya melewati pengurai pencarian web milik Postgres sendiri alih-alih dirangkai menjadi SQL dengan tangan, sehingga orang bisa mengetik tanda kutip dan tanda minus tanpa satu pun darinya menjadi celah injeksi. Yang penting dalam ruang kerja bersama, bagaimanapun, adalah di mana pemeriksaan izin itu duduk. Pencarian menggabungkan tabel halaman, dan keamanan tingkat baris tabel itu berlaku pada penggabungannya, sehingga hasilnya sudah terbatas pada halaman yang boleh dilihat si penanya. Saringan (sebuah cabang dari pohon halaman, siapa yang terakhir merevisi, kapan terakhir disunting) ditumpangkan di atasnya sebagai syarat tambahan. Setiap satunya mempersempit; tak satu pun bisa memperluas, sebab semuanya duduk di belakang pemeriksaan yang sama.

Menerbitkan membekukan, berbagi tidak

Ini dua hal yang berbeda dan Clepit sengaja memperlakukannya secara berbeda. Menerbitkan sebuah halaman membekukan dokumen yang ada sekarang sebagai satu revisi, mengarahkan halaman itu kepadanya, dan menjadikannya publik: yang dibaca pengunjung di clepit.space, pada alamat semacam acme.clepit.space/handbook, adalah revisi beku itu dan bukan suntingan yang dibuat setelahnya. Membatalkan penerbitan menghapus penunjuk-penunjuk itu tetapi mempertahankan alamat publiknya, sehingga menerbitkan lagi di kemudian hari kembali ke URL yang sama alih-alih mematahkan setiap tautan yang menunjuk ke sana. Tautan berbagi justru sebaliknya: ia menyajikan dokumen yang hidup, sehingga apa yang dilihat penerimanya berubah seiring halaman itu berubah.

Tautan yang bisa Anda tarik kembali

Tautan berbagi adalah token yang dapat Anda cabut, dan bisa diberi masa berlaku saat dibuat. Yang disimpan hanyalah hash dari token itu, jadi tautannya diperlihatkan sekali saja ketika dibuat dan sesudahnya tidak dapat dipulihkan dari basis data, baik oleh kami maupun oleh siapa pun yang sampai ke sana. Tautan semacam ini memberi hak membaca, bukan berkomentar: sebuah komentar butuh pengarang, dan pemegang tautan bukanlah pengarang.

Masuk dari direktori Anda sendiri

Sebuah ruang kerja dapat menyerahkan autentikasi kepada penyedia identitasnya sendiri: OpenID Connect pada paket Business, SAML pada Enterprise, disertai SCIM untuk penyelarasan direktori. SCIM mencakup sumber daya pengguna yang benar-benar dijalankan Okta dan Entra, dan ia membuat satu penyimpangan yang disengaja dari pembacaan paling lugas atas standar itu: penghapusan menonaktifkan anggota alih-alih melenyapkannya. Spesifikasinya mengizinkan hal itu, dan pilihan sebaliknya adalah penyelarasan direktori yang sanggup memusnahkan isi sebuah ruang kerja hanya karena seseorang dikeluarkan dari sebuah grup.

Empat cara berbicara dengannya

REST mencakup empat puluh empat operasi di bawah /v1, yang diterangkan oleh dokumen OpenAPI yang dibangkitkan dari rutenya sendiri alih-alih ditulis di sampingnya, dan integrasi berkelanjutan membandingkan keluaran itu dengan salinan yang tersimpan di repositori, sehingga perubahan rute yang melewati registri tidak bisa masuk diam-diam. GraphQL mencakup model aplikasi dan membawa langganan lewat soketnya sendiri. Realtime adalah proses tersendiri, itulah sebabnya menyalakan ulang gerbangnya tidak menyeret jatuh permukaan permintaan, dan ia memberi izin per soket alih-alih per ruang: untuk tiap kejadian, semua koneksi di dalam tenant dinilai dalam satu pemeriksaan terkumpul dan hanya yang boleh melihatnya yang menerimanya. MCP membuka operasi yang sama kepada agen AI sebagai perkakas, dan tak satu pun perkakas mempercayai id dari pemanggil untuk menentukan ruang kerja mana yang sedang dikerjakannya; penulisan melewati layanan yang sama dengan yang dipakai antarmuka, sehingga pemeriksaan izin dan jejak auditnya pun sama.

Untuk siapa

Untuk tim yang butuh editor yang mereka kendalikan, dan pengembang yang menyematkan konten terstruktur di produk mereka sendiri.

Kunjungi Clepit: clepit.com