nekostream 2026.4.1 → 2026.4.2

package/README.md

@@ -1,90 +1,169 @@
-# NekoStream CLI
-
-NekoStream CLI là ứng dụng dòng lệnh để tìm, duyệt và xem anime từ nhiều provider phổ biến tại Việt Nam. Ứng dụng tập trung vào trải nghiệm terminal gọn, nhanh, hỗ trợ lịch sử xem, tài khoản provider và trình phát video tích hợp.
-
-## Cài đặt
-
-Yêu cầu:
-
-- Node.js 18 trở lên
-- Windows, macOS hoặc Linux có terminal hỗ trợ màu ANSI
-
-Cài đặt toàn cục từ npm:
-
-```bash
-npm install -g nekostream
-```
-
-Chạy ứng dụng:
-
-```bash
-nekostream
-```
-
-Kiểm tra phiên bản mới nhất trên npm:
-
-```bash
-npm view nekostream version
-```
-
-Cập nhật lên bản mới nhất:
-
-```bash
-npm install -g nekostream@latest
-```
-
-## Tính năng chính
-
-- Tìm anime, xem danh sách thịnh hành và danh sách mới cập nhật.
-- Hỗ trợ nhiều provider: AnimeVietsub, Anime47, AnimeHay.
-- Hiển thị thông tin phim, thể loại, số tập, trạng thái và mô tả.
-- Lưu lịch sử xem local để tiếp tục xem nhanh.
-- Hỗ trợ đăng nhập provider cho các danh sách cá nhân khi provider hỗ trợ.
-- Tùy chỉnh domain provider khi domain mặc định bị chặn.
-- Trình phát video tích hợp bằng Electron/ArtPlayer.
-- Discord Rich Presence có thể bật/tắt trong cài đặt.
-
-## Lệnh phát triển
-
-Cài dependencies:
-
-```bash
-npm install
-```
-
-Chạy bản development:
-
-```bash
-npm start
-```
-
-Build TypeScript:
-
-```bash
-npm run build
-```
-
-Trước khi publish, hãy đảm bảo `version` trong `package.json` và `package-lock.json` đã khớp nhau.
-
-## Gỡ lỗi
-
-Mặc định CLI ẩn log scraper/debug để giao diện terminal sạch hơn.
-
-Bật debug log khi cần kiểm tra provider hoặc AniList:
-
-```bash
-NEKOSTREAM_DEBUG=1 nekostream
-```
-
-Trên Windows PowerShell:
-
-```powershell
-$env:NEKOSTREAM_DEBUG="1"; nekostream
-```
-
-## Miễn trừ trách nhiệm
-
-- Dự án không lưu trữ, phát tán hoặc sở hữu nội dung video.
-- NekoStream CLI chỉ là client kết nối trực tiếp từ máy người dùng đến provider.
-- Dự án không thu thập dữ liệu cá nhân và không sử dụng máy chủ trung gian.
-- Vui lòng sử dụng có trách nhiệm và tuân thủ điều khoản của từng provider.
+<div align="center">
+
+# 🐱 NekoStream CLI
+
+**Tìm, duyệt và xem anime Việt — ngay trong terminal.**
+
+[![npm](https://img.shields.io/npm/v/nekostream?color=8b5cf6&label=npm&logo=npm)](https://www.npmjs.com/package/nekostream)
+[![node](https://img.shields.io/badge/node-%E2%89%A522.12-3c873a?logo=nodedotjs&logoColor=white)](https://nodejs.org)
+[![typescript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](tsconfig.json)
+
+```
+  ╭──────────────────────────────────────────╮
+  │  ❯ nekostream                            │
+  │                                          │
+  │    ▸ Tìm anime                           │
+  │      Thịnh hành          Mới cập nhật    │
+  │      Lịch sử xem         Tài khoản       │
+  │      Cài đặt                             │
+  ╰──────────────────────────────────────────╯
+```
+
+</div>
+
+---
+
+## Dự án này là gì
+
+một CLI dùng được hằng ngày để xem anime từ các provider Việt Nam: không cần mở trình duyệt, không quảng cáo, không server trung gian.
+
+---
+
+## Cài đặt
+
+```bash
+npm install -g nekostream
+nekostream
+```
+
+Yêu cầu: **Node.js ≥ 22.12**, terminal hỗ trợ màu ANSI (Windows / macOS / Linux).
+
+<details>
+<summary><b>Cập nhật &amp; kiểm tra phiên bản</b></summary>
+
+```bash
+npm view nekostream version        # phiên bản mới nhất trên npm
+npm install -g nekostream@latest   # cập nhật
+```
+
+</details>
+
+---
+
+## Tính năng
+
+| | |
+| --- | --- |
+| 🔍 **Tìm &amp; duyệt** | Tìm theo tên, xem danh sách thịnh hành và mới cập nhật |
+| 🎬 **Trình phát tích hợp** | Electron + ArtPlayer, chặn quảng cáo và popup của provider |
+| 🌐 **Đa provider** | AnimeVietsub, Anime47 — kèm AnimeHay ở chế độ *duy trì, không đầu tư thêm* |
+| 📚 **Lịch sử xem** | Lưu local, tiếp tục xem nhanh, giữ 100 mục gần nhất |
+| 👤 **Đăng nhập provider** | Truy cập danh sách cá nhân; session mã hoá AES-256-GCM tại chỗ |
+| 🔗 **Metadata AniList** | Bổ sung mô tả, thể loại, điểm — không bắt buộc, lỗi không làm hỏng luồng |
+| 🎮 **Discord Rich Presence** | Bật/tắt trong Cài đặt |
+| ⚙️ **Domain tuỳ chỉnh** | Đổi domain provider khi domain mặc định bị chặn |
+
+---
+
+## Kiến trúc
+
+```text
+nekostream
+├── cli/                     Tầng giao diện — menu, flow, theme, feedback
+│   ├── menus/               Module độc lập cho từng menu (home, settings, history)
+│   └── flows/               Luồng nghiệp vụ: anime-flow, auth-flow, provider-lists
+├── scrapers/                Tầng dữ liệu & trích xuất
+│   ├── providers/           animevietsub/ · anime47/ · animehay.ts
+│   │   ├── <provider>/parsers/    Cheerio DOM parsers thuần túy (testable offline)
+│   │   └── <provider>/streams/    Trích xuất luồng video & server parsers
+│   ├── auth/                Tầng xác thực & quản lý phiên
+│   │   ├── animevietsub/    Đăng nhập & danh sách theo dõi
+│   │   ├── anime47/         Đăng nhập JWT & client REST API
+│   │   └── auth-session-service.ts  Quản lý trạng thái phiên
+│   ├── auth-service.ts      Facade tương thích ngược cho Auth
+│   ├── http-client.ts       Throttle theo domain, timeout controller, backoff
+│   ├── adblock-policy.ts    Bộ quy tắc chặn quảng cáo, popup và ad network
+│   ├── html-utils.ts        Giải mã HTML, chuẩn hóa URL, phân loại timeout
+│   └── errors.ts            Bảng mã lỗi chuẩn hóa (ProviderUnavailableError, ...)
+├── player-policy.ts         Cô lập host trình phát, kiểm tra payload & ad rules
+├── player-main.js           Electron main process phát video
+├── webview-preload.js       Preload cho <webview> phát video (sandboxing)
+├── storage.ts               Lưu trữ mã hóa AES-256-GCM (settings, history, session)
+├── provider-types.ts        Discriminated union — nguồn sự thật về provider
+└── checks/                  6 bộ test suites chạy hoàn toàn offline
+```
+
+Chi tiết xem tại [ARCHITECTURE.md](ARCHITECTURE.md).
+
+---
+
+## Phát triển
+
+```bash
+npm install
+npm start          # chạy bản dev
+npm run check      # lint → typecheck → test (6 suites) → build → pack:check
+```
+
+`npm run check` là cổng kiểm thử duy nhất. Mọi thay đổi phải vượt qua:
+1. **ESLint**: 0 cảnh báo (`--max-warnings 0`).
+2. **TypeScript**: `tsc --noEmit` chế độ strict.
+3. **6 Offline Test Suites**: `search-check`, `parser-check` (HTML fixtures), `domain-check`, `storage-check`, `scraping-check`, `player-check`.
+4. **Clean Build**: Xóa và biên dịch sạch vào `dist/`.
+5. **Package Check**: Đảm bảo đủ 70 runtime assets trong npm tarball.
+
+<details>
+<summary><b>Gỡ lỗi</b></summary>
+
+CLI ẩn log scraper để terminal sạch. Bật khi cần:
+
+```bash
+NEKOSTREAM_DEBUG=1 nekostream                      # bash / zsh
+$env:NEKOSTREAM_DEBUG="1"; nekostream              # PowerShell
+```
+
+Debug của **trình phát** (DOM dump, Eruda console) bật riêng qua `debugMode` trong menu Cài đặt — không đọc từ biến môi trường của shell, để một biến sót lại không thể tự mở công cụ debug bên trong trang phát.
+
+</details>
+
+<details>
+<summary><b>Cập nhật fixture test</b></summary>
+
+Fixture là snapshot HTML thật của provider. Khi provider đổi markup:
+
+```bash
+npx tsx checks/capture-fixtures.mts
+```
+
+Tool này **không** nằm trong `npm test`: nó cần mạng, còn test thì phải offline và deterministic.
+
+</details>
+
+---
+
+## Đóng góp
+
+Repo này hoan nghênh cả hai loại đóng góp:
+
+- **Code** — đọc [CONTRIBUTING.md](CONTRIBUTING.md) và [CLEANUP_PLAN.md](CLEANUP_PLAN.md) trước; PR nhỏ, một scope, giữ `npm run check` xanh.
+- **Phản biện đánh giá** — nếu bạn cho rằng [CODE_ASSESSMENT.md](CODE_ASSESSMENT.md) chấm sai hoặc bỏ sót một vấn đề, hãy mở issue. Một case study bị phản biện có giá trị hơn một case study được đồng thuận.
+
+---
+
+## Miễn trừ trách nhiệm
+
+- Dự án **không** lưu trữ, phát tán hoặc sở hữu bất kỳ nội dung video nào.
+- NekoStream CLI là client kết nối trực tiếp từ máy người dùng đến provider — **không có server trung gian**.
+- Dự án không thu thập dữ liệu cá nhân. Toàn bộ lịch sử và session nằm trong `~/.nekostream-cli/` trên máy bạn.
+- Vui lòng sử dụng có trách nhiệm và tuân thủ điều khoản của từng provider.
+
+> [!CAUTION]
+> ### TUYÊN BỐ MIỄN TRỪ TRÁCH NHIỆM PHÁP LÝ (DISCLAIMER)
+>
+> 1. **Sử dụng với rủi ro tự chịu (As-Is):** Mã nguồn này được cung cấp theo nguyên trạng "như hiện có" mà không có bất kỳ sự đảm bảo nào, dù là rõ ràng hay ngầm định, bao gồm nhưng không giới hạn ở các bảo đảm về khả năng thương mại hoặc tính phù hợp cho một mục đích cụ thể.
+> 2. **Giới hạn trách nhiệm:** Trong mọi trường hợp, **NekoTech** cũng như các thành viên phát triển không chịu trách nhiệm pháp lý đối với bất kỳ khiếu nại, thiệt hại hoặc tổn thất nào (bao gồm tổn thất dữ liệu, lỗ hổng bảo mật, hoặc thiệt hại về tài chính) phát sinh từ hoặc có liên quan đến việc sử dụng, sửa đổi, hoặc phân phối mã nguồn này.
+> 3. **Không hỗ trợ pháp lý:** Việc bạn sử dụng lại mã nguồn để vận hành các dịch vụ công cộng hoặc thương mại tự chịu hoàn toàn trách nhiệm trước pháp luật hiện hành. NekoTech không có nghĩa vụ bảo vệ, can thiệp hoặc chịu trách nhiệm thay cho bất kỳ hành vi vi phạm bản quyền hay pháp lý nào từ phía bên thứ ba.
+
+<div align="center">
+
+</div>

package/dist/cli/application.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runApplication = runApplication;
+const discord_1 = require("../discord");
+const logger_1 = require("../logger");
+const storage_1 = require("../storage");
+const domain_startup_1 = require("./domain-startup");
+const home_menu_1 = require("./menus/home-menu");
+const update_check_1 = require("./update-check");
+/**
+ * Application entry point: bring up the runtime services, then hand control to
+ * the home menu loop, which owns the interactive session until exit.
+ *
+ * Domain resolution runs after the update check — that one already exits the
+ * process when a newer version exists, so there is no point probing first.
+ */
+async function runApplication() {
+    (0, storage_1.ensureDataDir)();
+    await (0, update_check_1.checkUpdate)();
+    await (0, domain_startup_1.resolveProviderDomains)();
+    await (0, discord_1.initDiscord)();
+    (0, logger_1.debugLog)('NekoStream CLI started');
+    await (0, home_menu_1.showHomeMenu)();
+}

package/dist/cli/domain-startup.js

@@ -0,0 +1,85 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProviderDomains = resolveProviderDomains;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const logger_1 = require("../logger");
+const domain_resolver_1 = require("../scrapers/domain-resolver");
+const feedback_1 = require("./feedback");
+/**
+ * The fast path — probing the domain already in use — normally answers well
+ * inside this window, so no spinner is drawn at all and startup looks unchanged.
+ * The spinner only appears once resolution is slow enough to mean the current
+ * domain failed and the TLD fan-out is running.
+ */
+const SPINNER_DELAY_MS = 900;
+function summarize(outcomes) {
+    return {
+        changed: outcomes.filter((o) => o.status === 'ok' && o.changed),
+        failed: outcomes.filter((o) => o.status === 'failed')
+    };
+}
+/**
+ * A spinner that only materialises if the work outlives `SPINNER_DELAY_MS`.
+ *
+ * The state is kept behind functions rather than a local variable because the
+ * assignment happens inside a timer callback: TypeScript's control-flow analysis
+ * cannot see across that boundary and narrows a plain `let` to `null` forever.
+ */
+function delayedSpinner(text) {
+    let spinner;
+    const timer = setTimeout(() => {
+        spinner = (0, ora_1.default)(text).start();
+    }, SPINNER_DELAY_MS);
+    return {
+        stop: () => {
+            clearTimeout(timer);
+            spinner?.stop();
+        },
+        wasShown: () => spinner !== undefined
+    };
+}
+/**
+ * Pick each provider's live domain before the menu opens.
+ *
+ * Startup resolution is what turns domain discovery from reactive into
+ * proactive: previously a moved provider surfaced as three failed retries and a
+ * Playwright escalation in the middle of a search, and only then fell back.
+ *
+ * This never rejects and never blocks entry to the app. Offline or slow hosts
+ * simply mean the cached or seeded domain is used as-is.
+ */
+async function resolveProviderDomains() {
+    const spinner = delayedSpinner('Đang dò domain provider...');
+    let outcomes;
+    try {
+        outcomes = await (0, domain_resolver_1.resolveAllDomains)();
+    }
+    finally {
+        spinner.stop();
+    }
+    for (const outcome of outcomes) {
+        (0, logger_1.debugLog)(`[Domain] ${outcome.provider}: ${outcome.status} -> ${outcome.baseUrl}`);
+    }
+    const { changed, failed } = summarize(outcomes);
+    // Only speak up when something actually moved. A silent startup is the
+    // expected case and the whole point of the fast path.
+    if (changed.length > 0) {
+        for (const outcome of changed) {
+            console.log(chalk_1.default.cyan(`  Domain ${outcome.provider} đã đổi -> ${outcome.baseUrl}`));
+        }
+        await (0, feedback_1.sleep)(feedback_1.CONFIRM_DELAY_MS);
+        return;
+    }
+    // Only mention a failure if the spinner had appeared. Without that guard an
+    // offline user gets a warning about a domain probe they never asked for and
+    // cannot act on; with it, the line only follows visible work.
+    if (failed.length > 0 && spinner.wasShown()) {
+        const names = failed.map((o) => o.provider).join(', ');
+        console.log(chalk_1.default.yellow(`  Không dò được domain sống cho: ${names}. Dùng domain đã lưu.`));
+        await (0, feedback_1.sleep)(feedback_1.CONFIRM_DELAY_MS);
+    }
+}

package/dist/cli/feedback.js

@@ -0,0 +1,87 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIRM_DELAY_MS = exports.NOTICE_DELAY_MS = void 0;
+exports.sleep = sleep;
+exports.formatToggle = formatToggle;
+exports.flushStdin = flushStdin;
+exports.formatError = formatError;
+exports.reportFailure = reportFailure;
+exports.reportEmpty = reportEmpty;
+exports.withSpinner = withSpinner;
+exports.withSilentSpinner = withSilentSpinner;
+const chalk_1 = __importDefault(require("chalk"));
+const ora_1 = __importDefault(require("ora"));
+const ui_1 = require("../ui");
+/** How long a transient message stays on screen before the menu repaints. */
+exports.NOTICE_DELAY_MS = 2000;
+exports.CONFIRM_DELAY_MS = 1000;
+async function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function formatToggle(value) {
+    return value ? chalk_1.default.green('Bật') : chalk_1.default.red('Tắt');
+}
+/**
+ * Drain buffered keypresses so a prompt does not immediately consume input
+ * typed while the previous screen was still rendering.
+ */
+function flushStdin() {
+    if (!process.stdin.isTTY)
+        return;
+    process.stdin.resume();
+    while (process.stdin.read() !== null) {
+        // Discard whatever was buffered.
+    }
+}
+function formatError(error) {
+    if (error instanceof Error)
+        return error.message;
+    return String(error);
+}
+/** Print a failure and hold it on screen long enough to be read. */
+async function reportFailure(label, error) {
+    const detail = error === undefined ? '' : `: ${formatError(error)}`;
+    (0, ui_1.printError)(`\n${label}${detail}`);
+    await sleep(exports.NOTICE_DELAY_MS);
+}
+/** Print an empty-result notice and hold it on screen. */
+async function reportEmpty(message) {
+    (0, ui_1.printError)(`\n${message}`);
+    await sleep(exports.NOTICE_DELAY_MS);
+}
+/**
+ * Run an async task behind a spinner. Returns `undefined` when the task throws,
+ * after showing `failure` to the user — callers treat that as "abort this step".
+ */
+async function withSpinner(message, failure, task) {
+    const spinner = (0, ora_1.default)(message).start();
+    try {
+        const value = await task();
+        spinner.stop();
+        return value;
+    }
+    catch (error) {
+        spinner.stop();
+        await reportFailure(failure, error);
+        return undefined;
+    }
+}
+/**
+ * Like {@link withSpinner} but keeps the spinner running on success so the
+ * caller can decide the final message.
+ */
+async function withSilentSpinner(message, task) {
+    const spinner = (0, ora_1.default)(message).start();
+    try {
+        const value = await task();
+        spinner.stop();
+        return { ok: true, value };
+    }
+    catch (error) {
+        spinner.stop();
+        return { ok: false, error };
+    }
+}