@agntn/puzzles

ألغاز تشفير ومكافآت عامة، كسجلات مُنمَّطة. تطلب لغزًا، فتحصل على عنوانه ومادة مفتاحه وما جرى على السلسلة.

لماذا؟

كل خيط لغز يحمل الأشياء الثلاثة نفسها: العناوين، والجوائز، ومن حلّ ماذا. وكل ماسح ومتتبّع يعيد كتابتها من الخيط، بشكل مختلف قليلًا في كل مرة. لذا تعيش هنا مرة واحدة، كشيفرة. اللغز سجل TypeScript. يقرأه مدقّق الأنواع قبل أن يقرأه اختبار. وتقرأ واجهة سطر الأوامر وخادم MCP وإضافتا Pi وOMP سجلًا واحدًا.

الوثائق، صفحة لكل لغز وساحة تجريب مباشرة: puzzles.agntn.dev.

[!WARNING] إصدار ما قبل 1.0. لا تزال واجهة البرمجة وأعلام سطر الأوامر ونموذج البيانات قابلة للتغيير. ثبّت إصدارًا محددًا بدقة إن كنت تبني عليه.

✨ الميزات

• 🧾 البيانات كشيفرة. حرفي PuzzleSpec واحد لكل لغز، يبنيه مصنع puzzle() واحد لكل سلسلة. لا JSON، ولا خطوة بناء.
• 🕳️ الغائب غائب. اللغز الذي لا حالّ له أو لا جائزة له لا يملك هذا المفتاح. لا شيء يُسلسَل كـ null.
• 🔑 مادة المفتاح بكل شكل. Hex، أو WIF، أو حمولة BIP38، أو عبارة استرداد، أو حصص سرية، أو ملف مفتاح Arweave مختوم، أو مجرد عرض بتّي. وكل مفتاح في توقيع متعدد أيضًا. باني واحد.
• 💤 سجل كسول. استيراد الحزمة لا يحمّل أي سجلات. get("bits/71") يستورد وحدة مجموعة واحدة.
• ✅ التحقق قيمة. المفتاح المنشور يشتق العنوان أو لا يشتقه. لا شيء يرمي استثناءً بسبب سجل سيئ.
• 💰 أرصدة حيّة. puzzle.balance() عبر @agntn/explorers. الوحدات الأساسية كـ bigint، ومفاتيح API محجوبة من الأخطاء.
• 👀 مراقبة على السجل. puzzles watch يسرد الإيداعات والمصروفات التي يفوّتها سجل، وجائزة تحرّكت، ومفتاحًا عامًا أفشاه صرف، وصفحة مصدر تغيّرت. لا يعدّل سجلًا أبدًا. أنت من يفعل.
• 📋 قائمة تحقق قبل عطلة نهاية الأسبوع. puzzles eligibility يجمع المصدر، والعنوان، والإجماليات مدى الحياة من المستكشف، والحالة مع دليلها وما يُعدّ حلًّا. وكل ما لا يستطيع أحد ملأه يعود كصف missing، لا تخمينًا.
• 🖼️ اللغز نفسه، لا رابطًا إليه. puzzles_assets يسلّم النموذج الصورة وملفات المراحل والمنشورات المؤرشفة خلف التلميحات، مدقّقة مقابل SHA-256 الذي يثبّته السجل. الروابط تبلى. هذه لا.
• 🤖 خمسة عشر أداة وكيل. منفّذ واحد خلف MCP وPi وOMP. الإجابة نفسها في كل مكان.
• 🌐 يعمل في أي مكان. ESM محايد على Fetch API. Node، والمتصفحات، وعمّال الحافة.

📦 التثبيت

pnpm add @agntn/puzzles

Node.js 26 أو أحدث لـ CLI.

🚀 الاستدعاء الأول

npx @agntn/puzzles stats

يطبع ذلك الإجمالي، وعددًا واحدًا لكل حالة، وكم عدد الألغاز التي تمتلك مفتاحًا عامًا معروفًا. لا مفتاح، لا إعدادات، لا شبكة. تُشحن السجلات داخل الحزمة. الأمر puzzles المجرد أدناه هو pnpm exec puzzles بعد pnpm add محلي، أو مجرد puzzles بعد pnpm add -g @agntn/puzzles.

puzzles show hash-collision/sha256

hash-collision/sha256	unsolved	0.27734251 BTC	35Snmmy3uhaer2gTboc81ayCip4m9DT4ko
chain: bitcoin  address kind: p2sh
hash160: 292fb39df7cd619a396069383928e6bfb74ebec5
redeem script: 6e879169a87ca887 (hash 292fb39df7cd619a396069383928e6bfb74ebec5)
public key: unknown
private key: unknown
started: 2013-09-13 05:59:09
transactions: 1
	funding	2013-09-13 05:59:09	0.1 BTC	397f12ee15f8a3d2ab25c0f6bb7d3c64d2038ca056af10dd8251b98ae0f076b0
explorer: https://blockstream.info/address/35Snmmy3uhaer2gTboc81ayCip4m9DT4ko
source: https://bitcointalk.org/index.php?topic=293382.0

الأوامر

الأمر	ما يطبعه
puzzles stats	الإجماليات وعدد الحالات ومجاميع الجوائز وإصدار البيانات
puzzles collections	صف واحد لكل مجموعة: المفتاح والعدد والمؤلف
puzzles authors [key]	صف واحد لكل مؤلف، أو سجل مؤلف واحد مع حقائقه الموثقة
puzzles author <key>	سجل مؤلف واحد، مباشرةً من أداة puzzles_author
puzzles solvers [key]	صف واحد لكل حالّ مسمّى، أو سجل حالّ واحد: كل عملية حل والملفات الشخصية والحقائق الموثقة
puzzles solver <key>	سجل حالّ واحد، مباشرةً من أداة puzzles_solver
puzzles show <id>	سجل لغز واحد: المادة الأساسية والمعاملات والتلميحات والروابط. --json للبيانات
puzzles hints <id>	تلميحات المجموعة، ثم تلميحات اللغز نفسه، ثم ملفات تلميحاته. --json لكليهما
puzzles stages <id>	مراحل لغز متعدد المراحل مع صفحاتها وملفاتها وأجوبتها المنشورة. --json للقائمة
puzzles assets <id>	الملفات التي يأتي بها اللغز مع SHA-256 والحجم، والصفحات المؤرشفة التي يستشهد بها. --read <path> يكتب واحدًا، و--check/--live يتحققان
puzzles list [collection]	لغز واحد لكل سطر. --address و--chain و--status و--technique و--with-pubkey تضيّقه، و--limit و--offset تقسّمانه إلى صفحات
puzzles verify [id]	مفتاح منشور ووصفته مقابل العنوان. --all أو مرشّحات list لمجموعة، مع الخروج بالرمز 1 عند عدم التطابق
puzzles balance [id]	الرصيد الحيّ. مرشّحات list تفحص مجموعة كاملة، صفًا لكل عنصر. --api-key، أو متغير واحد لكل سلسلة
puzzles watch [id]	ما تعرفه السلسلة ولا يعرفه السجل. --since يفحص صفحات المصدر أيضًا، مع الخروج بالرمز 1 عند أي اكتشاف
puzzles eligibility <query>	قائمة التحقق قبل العمل على جائزة، بالمعرّف أو العنوان. الخروج بالرمز 1 ما دام أي حقل ناقصًا
puzzles export	مجموعة البيانات كاملة مع data_version الخاص بها
puzzles mcp	خادم MCP عبر stdio

--json يطبع البيانات الكامنة وراء النص، مع bigint كسلاسل نصية والحقول الغائبة محذوفة. تأتي الأوامر من نفس تعريفات الأدوات التي يحصل عليها الوكلاء، لذا فإن خطأً مطبعيًا في أحد الأعلام يفشل هنا تمامًا كما يفشل لدى النموذج. الأعلام ورموز الخروج موجودة في دليل CLI.

🧠 المكتبة

import { get, stats, verify } from "@agntn/puzzles";
import { bits } from "@agntn/puzzles/collections/bits";

const puzzle = await get("bits/71"); // loads the bits collection, nothing else
puzzle?.address().value; // "1PWo3JeB9jrGwfHDNpdGK54CRas7fsVzXU"
puzzle?.keyRange(); // [2n ** 70n, 2n ** 71n - 1n]