Mira v1.3.0

Phase 0's test harness is now complete: the project has a real end-to-end browser test
that boots the actual API and drives a live visitor↔operator conversation. Plus the
security scanning the roadmap asks for in Phase 1.

Added

• Real E2E test (tests/e2e/, Playwright) — the last unchecked item of Phase 0 task 4
  • Visitor opens the widget on the demo page → sends a message → the operator sees the
    conversation appear live → replies → the reply reaches the visitor without a reload,
    proving the whole Socket.io path
  • A second test sends <script> and <img onerror> through the widget and asserts the
    operator's DOM is clean and nothing executed — rule 5 (sanitizeMessageContent)
  • Runs in CI in a new E2E job: Postgres + Redis service containers, migrations, seed,
    the API booted with the same command the Dockerfile uses, and the dashboard bundle served
• CodeQL SAST (codeql.yml) — TypeScript and PHP, on every PR and push plus a weekly run
• Dependency review (dependency-review.yml) — blocks PRs adding vulnerable or
  licence-incompatible dependencies
• 12 unit tests for the security headers middleware — the only significant piece of
  security logic that had no coverage. Guards real bug #5 (X-Powered-By leaking on static
  files) and real bug #6 (CSP applied to JSON but not HTML, including the query-string case
  that caused it)

Changed

• AGENTS.md §9 now describes all three test levels honestly, and states plainly what is
  still uncovered: the AI/worker path, the WordPress plugin, and the settings/reports pages

Notes

Two things were learned by running the stack rather than reading it, and are worth knowing:
reloading the dashboard logs the operator out (tokens are held in memory, by design), and
the login endpoint is throttled to 10 requests/minute — running the E2E suite repeatedly
back to back trips that limit, which is the rate limiter working correctly rather than a
flaky test.

---

Install on a Debian/Ubuntu server

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

Full guide (all distributions, WordPress, troubleshooting):
package/INSTALL.md
— also available in Persian:
package/INSTALL.fa.md

WordPress plugin: install mira-wordpress-plugin.zip from the WordPress admin.

Docker images

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

Mira v1.2.0

Phase 0 of the roadmap, as far as it can go without hardware: the project has an automated
test suite for the first time, and the roadmap itself now lives in the repository.

Added

• Test suite (npm test) — the project had none before this release
  • 55 unit tests over the pure logic that has historically broken: input sanitization,
    keyword splitting (both , and the Persian ،), the AI confidence parse and its
    fail-safe hand-off, permission resolution, business hours in the Tehran timezone, and
    user-agent parsing
  • 27 integration tests against real Postgres + Redis service containers in CI —
    migrations, schema shape, multi-tenant siteId isolation, and message idempotency.
    They self-skip without TEST_DATABASE_URL, so npm test stays green on any machine
  • A Tests job in CI, running both as a required check
• ROADMAP.md / ROADMAP.fa.md — the seven-phase enterprise
  roadmap, checked line by line against the code before being committed
• docs/PHASE0-RUNBOOK.md — step-by-step instructions for the
  three Phase 0 tasks that need real hardware (WordPress install, Debian deployment,
  production dashboard image), each with pass criteria

Changed

• parseModelOutput moved out of bot-reply.ts into apps/worker/src/ai/parse-model-output.ts
  and the automation keyword splitter into splitKeywords() in packages/shared-types —
  both were unreachable from a test before. Behaviour is unchanged
• AGENTS.md §9 now describes the test suite honestly: unit and integration coverage
  exists, browser E2E does not

Notes

Three claims in the roadmap draft did not survive checking against the code and were
corrected before commit: the seed script contains no placeholder knowledge-base document or
offlineMessage (those are rows in a local dev database, not code), a non-default admin
password is already enforced, and the phase tags were realigned to the real version line.
The dead AI_MAX_TOKENS_PER_CONVERSATION config was confirmed real and stays scheduled for
Phase 2.

---

Install on a Debian/Ubuntu server

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

Full guide (all distributions, WordPress, troubleshooting):
package/INSTALL.md
— also available in Persian:
package/INSTALL.fa.md

WordPress plugin: install mira-wordpress-plugin.zip from the WordPress admin.

Docker images

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

Mira v1.1.0

English is now the canonical language of every surface a visitor sees, with a Persian
mirror alongside it. The product itself stays Persian-first — this release changes
documentation and tooling, not the UI.

Fixed

• The WooCommerce integration never worked, from the very first commit. The API sent a
  header named X-میرا-Api-Key; a non-ASCII header name is invalid, so fetch threw
  before sending and no request ever reached WordPress. The function's own catch
  swallowed the error and returned null, so the dashboard reported "not configured or
  customer not found" — making a hard failure indistinguishable from an unconfigured site.
  The header is now X-Mira-Api-Key, matching what the plugin reads. Verified against a
  mock server implementing the plugin's hash_equals auth: the request now returns HTTP
  200 with the customer's data.

Added

• package/INSTALL.md — the installation guide in English; both it and the Persian
  INSTALL.fa.md ship inside the .deb
• docs/fa.html — the Persian landing page, with a language switcher on both pages
• Persian mirrors kept under the .fa.md suffix: AGENTS.fa.md, CONTRIBUTING.fa.md,
  SECURITY.fa.md, CHANGELOG.fa.md, package/README.fa.md, docs/brand/README.fa.md

Changed

• README, AGENTS, CONTRIBUTING, SECURITY, CHANGELOG, the brand guide and the
  package docs are English at their canonical names; CODE_OF_CONDUCT.md is reordered
  English first
• Every user-visible GitHub surface is English: workflow, job and step names (shown in the
  public Actions tab), the issue forms, the PR template, and the title and body of every
  GitHub Release — release notes are now read from the English CHANGELOG.md
• The mira CLI, install.sh, build-deb.sh, the Debian maintainer scripts and the backup
  loop print English, following Debian command-line convention; .env.example comments are
  English
• docs/index.html (the GitHub Pages entry point) is the English landing page
• The design-system preview is dir="ltr" with the Persian specimens explicitly marked
  dir="rtl" — English text inside the RTL container rendered with punctuation on the
  wrong side
• Package description fields and the brand SVG aria-labels are English
• The language policy is now written down in CONTRIBUTING.md, AGENTS.md and CLAUDE.md:
  documentation and public surfaces English (canonical) with a .fa.md mirror; code
  comments, product UI and user-facing error messages Persian; commit messages English
• Corrected a false claim in the phase-3 test checklist: the WooCommerce order panel had
  only been verified at the WordPress endpoint with curl, never end to end through Mira

---

Install on a Debian/Ubuntu server

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

Full guide (all distributions, WordPress, troubleshooting):
package/INSTALL.md
— also available in Persian:
package/INSTALL.fa.md

WordPress plugin: install mira-wordpress-plugin.zip from the WordPress admin.

Docker images

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

میرا v1.0.2

تغییر

• فیلد Maintainer پکیج دبیان به ایمیل واقعی نگه‌دارنده برگشت. در نسخه‌ی ۱.۰.۱ از سر
  احتیاط آدرس noreply گیت‌هاب گذاشته شده بود، ولی این فیلد در استاندارد دبیان راه
  تماس کاربران با نگه‌دارنده‌ی پکیج است و با noreply عملاً غیرقابل‌استفاده می‌شد.
  حالا با ایمیل داخل متادیتای کامیت‌ها هم یکدست است.

---

نصب روی سرور دبیان/اوبونتو

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

راهنمای کامل (همه‌ی توزیع‌ها، وردپرس، عیب‌یابی):
package/INSTALL.fa.md

افزونه‌ی وردپرس: فایل mira-wordpress-plugin.zip را از پیشخوان وردپرس نصب کنید.

ایمیج‌های Docker

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

میرا v1.0.1

آماده‌سازی مخزن برای انتشار عمومی.

افزوده

• README دوزبانه: README.md انگلیسی (چهره‌ی عمومی پروژه) و README.fa.md فارسی
  (مستندات کامل) با نوار جابه‌جایی زبان
• اسکرین‌شات‌های واقعی محصول در docs/screenshots/ (داشبورد، ویجت، ورود، دیزاین‌سیستم)
  با فرمت WebP — مجموعاً ~۱۷۶ کیلوبایت
• لندینگ GitHub Pages در docs/index.html — self-contained، بدون هیچ درخواست خارجی،
  آماده برای اتصال دامنه‌ی اختصاصی در آینده
• CODE_OF_CONDUCT.md (دوزبانه)، .editorconfig
• فیلدهای license و repository در همه‌ی package.jsonها

تغییر

• تگ ریلیزهای فازی (0.0.1 تا 0.0.7) به کامیت واقعی همان فاز منتقل شدند
  (قبلاً چون از رابط وب ساخته شده بودند، همگی به HEAD وقتِ ساخت اشاره می‌کردند)
• ایمیل نگه‌دارنده در پکیج دبیان به آدرس noreply گیت‌هاب تغییر کرد
• .claude/ به .gitignore مخزن اضافه شد (قبلاً فقط با gitignore سراسری ماشین محافظت می‌شد)
• اعتبارنامه‌های نمونه‌ی توسعه در README و CONTRIBUTING صراحتاً «فقط توسعه» برچسب خوردند
• ارجاع مرده‌ی promt/ در AGENTS.md اصلاح شد

امنیت

• /demo.html دیگر در NODE_ENV=production سرو نمی‌شود (سرو widget-dist دست‌نخورده
  باقی می‌ماند) — تا هیچ استقرار واقعی یک صفحه‌ی دموی عمومی با کلید ویجت نمونه باز نگذارد
• ممیزی کامل تاریخچه‌ی گیت پیش از عمومی‌سازی: هیچ سکرتی هرگز کامیت نشده بود

---

نصب روی سرور دبیان/اوبونتو

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

راهنمای کامل (همه‌ی توزیع‌ها، وردپرس، عیب‌یابی):
package/INSTALL.fa.md

افزونه‌ی وردپرس: فایل mira-wordpress-plugin.zip را از پیشخوان وردپرس نصب کنید.

ایمیج‌های Docker

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

میرا v1.0.0

اولین نسخه‌ی رسمی و قابل انتشار: میرا از «کد کامل ولی بدون هویت و بدون مسیر نصب» به یک
محصول با برند، پکیج نصب و انتشار خودکار رسید.

هویت بصری و UI/UX

• هویت برند کامل بر اساس لوگوی میرا: پالت (آبی #2E6BE6، فیروزه‌ای #17B8A6،
  نارنجی #F5A623) به‌صورت توکن در tailwind.config.js، لوگوی وکتوری و
  لوگوی انیمیشنی SVG، راهنمای برند و صفحه‌ی پیش‌نمایش دیزاین‌سیستم (docs/brand/)
• بازطراحی کامل داشبورد: پوسته‌ی جدید با سایدبار (آیکون‌های درون‌خطی، نشان نخوانده،
  بلوک پروفایل)، فونت وزیرمتن (self-host از npm، بدون CDN)، صفحه‌ی ورود جدید با
  گرادیان برند و لوگوی انیمیشنی، اولین دکمه‌ی خروج، favicon
• بازطراحی ویجت: نشان SVG برند به‌جای ایموجی، گرادیان، انیمیشن‌های ورود/باز شدن/تایپ،
  تفکیک بصری پیام ربات، رعایت prefers-reduced-motion — حجم gzip ‏~۲۱KB (سقف ۵۰KB)
• بازطراحی صفحه‌ی تنظیمات افزونه‌ی وردپرس: هدر برند، کارت‌بندی بخش‌ها،
  انتخاب‌گر رنگ واقعی به‌جای فیلد متنی

نصب و استقرار

• پکیج دبیان (mira_<version>_all.deb) + ابزار خط فرمان mira
  (setup/start/stop/restart/status/logs/update/backup/restore/doctor) + سرویس systemd
• mira setup همه‌ی رمزها و کلیدها را تصادفی و امن تولید می‌کند، در
  /etc/mira/mira.env با chmod 600 می‌گذارد و فقط یک‌بار نمایش می‌دهد
• راهنمای کامل نصب فارسی برای دبیان ۱۲/۱۳، اوبونتو و توزیع‌های RHEL-based:
  package/INSTALL.fa.md (+ install.sh برای توزیع‌های غیر deb)
• داشبورد پروداکشن دیگر Vite dev server نیست — باندل استاتیک با nginx

انتشار ایمیج‌های Docker

• انتشار خودکار سه ایمیج در GitHub Container Registry با هر push به main و هر tag:
  ghcr.io/hami9/mira-api، ghcr.io/hami9/mira-worker، ghcr.io/hami9/mira-dashboard
• ایمیج داشبورد روی هر دامنه‌ای کار می‌کند: آدرس API به‌جای زمان build، زمان اجرا
  از config.js خوانده می‌شود (اسکریپت entrypoint در ایمیج nginx)
• گزینه‌ی «ایمیج آماده» در mira setup — نصب بدون build و در چند دقیقه
  (پیش‌فرض همچنان build از سورس، چون دسترسی ghcr از هر سروری تضمینی نیست)

زیرساخت مخزن

• لایسنس AGPL-3.0 (افزونه‌ی وردپرس طبق الزام اکوسیستم: GPLv2+)
• CI (لینت/فرمت/بیلد همه‌ی workspaceها/سقف حجم ویجت/ساخت deb) و Release خودکار با هر tag
• قالب‌های issue/PR فارسی، dependabot، ‏CONTRIBUTING، ‏SECURITY، ‏CHANGELOG و README برنددار

رفع باگ

• vite build روی پکیج workspace با خروجی CJS می‌شکست ("SocketEvent" is not exported)
  — با build.commonjsOptions رفع شد؛ build پروداکشن داشبورد تا این نسخه هرگز اجرا نشده بود
• seed.ts مقدار position: 'bottom-end' می‌نوشت که ویجت نمی‌فهمد
  (فقط bottom-left/bottom-right) — به مقدار معتبر و رنگ برند اصلاح شد
• حذف ایمیل توسعه‌ی هاردکدشده از فرم ورود داشبورد
• رفع دو خطای قدیمی ESLint و یکدست‌سازی فرمت کل ریپو
  (format:check سراسری تا این نسخه هرگز pass نمی‌شد)

---

نصب روی سرور دبیان/اوبونتو

sudo dpkg -i mira_*_all.deb || sudo apt -f install
sudo mira setup && sudo mira start

راهنمای کامل (همه‌ی توزیع‌ها، وردپرس، عیب‌یابی):
package/INSTALL.fa.md

افزونه‌ی وردپرس: فایل mira-wordpress-plugin.zip را از پیشخوان وردپرس نصب کنید.

ایمیج‌های Docker

ghcr.io/hami9/mira-api
ghcr.io/hami9/mira-worker
ghcr.io/hami9/mira-dashboard

سخت سازی و استقرار نهایی

هدر CSP دقیق برای صفحه‌ای که ویجت توش لود می‌شه (script-src, connect-src محدود به دامنه سرور خودت)
CORS محدود به دامنه‌های ثبت‌شده هر site (نه *)
Rate limiting روی endpoint های عمومی ویجت (شروع مکالمه، ارسال پیام)
هیچ داده حساسی (توکن، PII) در localStorage ویجت ذخیره نمیشه؛ فقط حافظه یا کوکی httpOnly
پیوست‌های آپلودی: محدودیت نوع فایل و حجم + بررسی نوع واقعی فایل (نه فقط پسوند) + لینک دانلود امضادار با انقضا (نه پابلیک دائمی)
Idempotency روی ارسال پیام و اعلان ایمیلی (جلوگیری از ارسال تکراری هنگام قطعی شبکه)
Index دیتابیس روی ستون‌های پرکوئری (site_id, conversation_id, created_at) + صفحه‌بندی (pagination) تاریخچه چت
همه timestampها در UTC ذخیره و در نمایش به وقت تهران تبدیل بشن
health-check endpoint برای هر سرویس + سیاست restart در docker-compose
مدیریت secret ها فقط از طریق env، لاگ نباید هیچ‌وقت توکن/رمز چاپ کنه
راهنمای استقرار production در README: تنظیم دامنه، SSL خودکار (Caddy/Let's Encrypt)، بک‌آپ دوره‌ای Postgres، rotate لاگ
یک امکان ساده «حذف داده بازدیدکننده» برای درخواست‌های حریم خصوصی

امکانات اضافه

• قوانین اتوماسیون ساده (اگر شرط X آنگاه اکشن Y — مثل مسیریابی خودکار بر اساس کلمه کلیدی)
• یادداشت داخلی خصوصی روی مکالمه
• API عمومی + وب‌هوک برای رویدادها (پیام جدید، مکالمه بسته شد)
• احراز هویت دومرحله‌ای (2FA) برای اپراتورها
• تنظیم دسترسی نقش‌محور دقیق‌تر

گزارش‌گیری

• داشبورد آمار: تعداد گفتگوی روزانه/هفتگی، میانگین زمان اولین پاسخ، نرخ CSAT، عملکرد هر اپراتور
• خروجی CSV/Excel از گزارش‌ها

هوش مصنویی

• لایه AiProvider انتزاعی (interface یکسان برای OpenAI-compatible و Anthropic API، انتخاب با env)
• پایگاه دانش: آپلود فایل/متن → chunk کردن → تولید embedding → ذخیره در pgvector
• ربات پاسخ‌گوی اول: هنگام پیام جدید بازدیدکننده، اگر هیچ اپراتوری assign نشده، ربات با RAG از پایگاه دانش پاسخ بده (با ارجاع به منبع در پاسخ)
• Handoff بی‌درز: اگر بازدیدکننده صریحاً انسان بخواد، یا ربات مطمئن نباشه (آستانه اطمینان قابل تنظیم)، مکالمه به صف اپراتورهای آنلاین منتقل بشه و کل تاریخچه در پنل اپراتور نمایش داده بشه (بدون نیاز به تکرار توسط کاربر)
• Copilot اپراتور: دکمه «پیشنهاد پاسخ» در پنجره چت اپراتور — پاسخ پیشنهادی رو قبل از ارسال می‌تونه ویرایش کنه
• خلاصه‌سازی خودکار گفتگوهای طولانی هنگام بسته شدن تیکت
• تشخیص احساس/فوریت پیام برای escalation خودکار (مثلاً کلمات مرتبط با نارضایتی شدید → اولویت بالا)
• تمام فراخوانی‌های AI باید در صف BullMQ پردازش بشن، نه مستقیم روی مسیر درخواست (جلوگیری از بلاک شدن چت زنده)، و باید محدودیت هزینه/تعداد توکن per-conversation داشته باشن
• نکته چندمستأجری: هر کوئری RAG باید بر اساس site_id فیلتر بشه — پایگاه دانش یک سایت هرگز نباید در پاسخ سایت دیگه نشت کنه
• معیار پذیرش: آپلود چند سند نمونه، پرسیدن سوال از ویجت که ربات با ارجاع به سند پاسخ بده، و تست دستی handoff به اپراتور.