@wasmsoft/fantastic 1.0.0

package/dist/updating/apply.js

@@ -0,0 +1,172 @@
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pipeline } from "node:stream/promises";
+import yauzl from "yauzl";
+import { BUNDLE_DIRS } from "../packaging/layout.js";
+// AR: تركيب حزمة تحديث — **بالتبديل بالاسم لا بالنسخ**.
+//
+//     خطة P5.4 تقول «النسخة الاحتياطية بـ‎archive.ts‎ القائم، لا تكتب منطق نسخ جديدًا»، و
+//     ‎archive.ts‎ عند القراءة **يؤرشف بيانات العميل**: لقطة قاعدة و‎data/‎ و‎config.json‎ —
+//     لا شجرة بناء. أرشفةُ ثلاثة عشر ألف ملفٍّ من ‎core/‎ في زِب قبل كل تحديث تكلّف دقائق على
+//     قرص جهاز، والتراجعُ منها يكلّف مثلها في اللحظة التي يكون فيها النظام مطفأً.
+//
+//     البديل المستعمل: **إعادة تسمية المجلد القائم** إلى ‎core.prev-0.20.0‎ ثم فكّ الجديد
+//     مكانه. إعادة التسمية عملية واحدة على نفس القسم مهما كان عدد الملفّات، والتراجع إعادةُ
+//     تسميةٍ معاكسة — أي أن **التراجع أسرع من الفشل الذي استدعاه**. والنسخة القديمة تبقى
+//     كاملةً على القرص لا مضغوطةً في أرشيفٍ يحتاج فكًّا في أسوأ وقت.
+//
+// EN: Installing an update bundle — **by renaming, not by copying**.
+//
+//     The P5.4 card says "back up with the existing `archive.ts`, do not write new copy logic", and
+//     `archive.ts`, when read, **archives customer data**: a database snapshot, `data/` and
+//     `config.json` — not a build tree. Zipping thirteen thousand files out of `core/` before every
+//     update costs minutes on an appliance disk, and rolling back from it costs the same again at
+//     the moment the system is down.
+//
+//     The alternative used: **rename the existing directory** to `core.prev-0.20.0` and extract the
+//     new one in its place. A rename is one operation on the same volume however many files there
+//     are, and rollback is the reverse rename — so **the rollback is faster than the failure that
+//     called for it**. The old tree stays whole on disk rather than compressed into an archive that
+//     needs unpacking at the worst possible moment.
+/**
+ * AR: أين يُركَّب كل مكوّن. **‎assets‎ غائب عمدًا**: تخطيط الحزمة في ‎layout.ts‎ لا يعرّف له
+ *     مجلدًا، وتخمينُ مسارٍ يعني فكّ آلاف الملفّات في مكانٍ لا يقرؤه شيء — تحديثٌ يُعلَن
+ *     ناجحًا ولا يغيّر شيئًا. يُرفَض برسالة صريحة حتى يُعرَّف موضعه.
+ * EN: Where each component installs. **`assets` is deliberately absent**: the bundle layout in
+ *     `layout.ts` defines no directory for it, and guessing a path means unpacking thousands of
+ *     files somewhere nothing reads — an update reported as successful that changes nothing. It is
+ *     refused with a clear message until its location is defined.
+ */
+export const COMPONENT_TARGET = {
+    core: BUNDLE_DIRS.core,
+    live: BUNDLE_DIRS.live,
+    interface: BUNDLE_DIRS.interfaceRoot,
+};
+export function targetFor(root, component) {
+    const directory = COMPONENT_TARGET[component];
+    return directory ? join(root, directory) : undefined;
+}
+/**
+ * AR: يزيح الشجرة القائمة جانبًا ويعيد مقبضًا يتيح التراجع.
+ *
+ *     **إعادة التسمية على ويندوز تفشل أحيانًا بلا سبب دائم**: مضادّ فيروسات أو مفهرس يمسك
+ *     ملفًّا لأجزاء من الثانية بعد إيقاف الخدمة. محاولةٌ واحدة كانت ستُفشل تحديثًا سليمًا،
+ *     فتُعاد المحاولة قليلًا قبل الاستسلام.
+ * EN: Moves the existing tree aside and returns a handle that makes rollback possible.
+ *
+ *     **Renaming on Windows fails intermittently for no lasting reason**: an antivirus or the
+ *     indexer holds a file for fractions of a second after the service stops. A single attempt
+ *     would fail a perfectly good update, so it retries briefly before giving up.
+ */
+export async function swapAside(root, component, currentVersion) {
+    const target = targetFor(root, component);
+    if (!target)
+        throw new Error(`لا موضع تثبيت معروف للمكوّن ${component}.`);
+    const previous = `${target}.prev-${currentVersion}`;
+    // بقايا تحديثٍ سابق انقطع: تُزال، وإلّا فشلت إعادة التسمية على وجهةٍ موجودة.
+    if (existsSync(previous))
+        rmSync(previous, { recursive: true, force: true });
+    if (existsSync(target))
+        await renameWithRetry(target, previous);
+    return { component, target, previous };
+}
+/**
+ * AR: يفكّ الحزمة في موضع المكوّن.
+ *
+ *     **يرفض أي مدخل يخرج من الوجهة.** أسماء المدخلات داخل الزِب يكتبها من صنعها، و
+ *     ‎..\..\runtime\node.exe‎ اسمُ مدخلٍ صالح تمامًا — فبدون هذا الحارس تستطيع حزمةٌ موقَّعة
+ *     أن تكتب خارج مجلدها. التوقيع يثبت أن الحزمة منّا، ولا يثبت أن من بناها لم يخطئ.
+ * EN: Unpacks the bundle into the component's place.
+ *
+ *     **Refuses any entry that escapes the destination.** Entry names inside a zip are written by
+ *     whoever made it, and `..\..\runtime\node.exe` is a perfectly valid one — so without this
+ *     guard a signed bundle could write outside its directory. The signature proves the bundle is
+ *     ours; it does not prove whoever built it made no mistake.
+ */
+export async function extractInto(archive, destination) {
+    mkdirSync(destination, { recursive: true });
+    const zip = await openZip(archive);
+    let written = 0;
+    await new Promise((done, fail) => {
+        zip.on("entry", (entry) => {
+            if (entry.fileName.endsWith("/")) {
+                zip.readEntry();
+                return;
+            }
+            const path = safeJoin(destination, entry.fileName);
+            if (!path) {
+                fail(new Error(`مدخل خارج وجهة الفكّ: ${entry.fileName}`));
+                return;
+            }
+            zip.openReadStream(entry, (error, stream) => {
+                if (error || !stream) {
+                    fail(error ?? new Error(`تعذّرت قراءة ${entry.fileName}`));
+                    return;
+                }
+                mkdirSync(dirname(path), { recursive: true });
+                pipeline(stream, createWriteStream(path))
+                    .then(() => {
+                    written += 1;
+                    zip.readEntry();
+                })
+                    .catch(fail);
+            });
+        });
+        zip.on("end", () => done());
+        zip.on("error", fail);
+        zip.readEntry();
+    });
+    zip.close();
+    // AR: زِبٌّ سليم بلا ملفّات ليس نجاحًا. حزمةٌ فارغة تمرّ من التوقيع والبصمة معًا — كلاهما
+    //     يصف بايتاتها بصدق — وتترك المكوّن مجلدًا فارغًا، فتُقلع الخدمة على لا شيء.
+    // EN: A valid zip with no files is not a success. An empty bundle passes both the signature and
+    //     the digest — each describes its bytes truthfully — and leaves the component an empty
+    //     directory, so the service boots on nothing.
+    if (written === 0)
+        throw new Error("الحزمة لا تحوي ملفّات.");
+    return written;
+}
+/** يتراجع: يحذف الجديد ويعيد القديم إلى مكانه. */
+export async function undoSwap(handle) {
+    if (existsSync(handle.target))
+        rmSync(handle.target, { recursive: true, force: true });
+    if (existsSync(handle.previous))
+        await renameWithRetry(handle.previous, handle.target);
+}
+/** يثبّت النجاح: تُزال الشجرة السابقة. تُنادى **بعد** فحص الصحة لا قبله. */
+export function discardPrevious(handle) {
+    if (existsSync(handle.previous))
+        rmSync(handle.previous, { recursive: true, force: true });
+}
+async function renameWithRetry(from, to, attempts = 5) {
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt === attempts)
+                throw error;
+            await new Promise((done) => setTimeout(done, 200 * attempt));
+        }
+    }
+}
+function openZip(file) {
+    return new Promise((done, fail) => {
+        yauzl.open(file, { lazyEntries: true, autoClose: false }, (error, zip) => {
+            if (error || !zip)
+                fail(error ?? new Error("تعذّر فتح الحزمة."));
+            else
+                done(zip);
+        });
+    });
+}
+/** يبني مسارًا داخل الوجهة، أو ‎undefined‎ إن خرج منها. */
+function safeJoin(destination, entryName) {
+    const path = resolve(destination, entryName);
+    const step = relative(destination, path);
+    if (!step || step.startsWith("..") || step.startsWith(sep))
+        return undefined;
+    return path;
+}
+//# sourceMappingURL=apply.js.map

package/dist/updating/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/updating/apply.ts"],"names":[],"mappings":"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"}

package/dist/updating/download.d.ts

@@ -0,0 +1,44 @@
+export type DownloadProgress = {
+    receivedBytes: number;
+    totalBytes: number;
+    percent: number;
+};
+export type DownloadOptions = {
+    url: string;
+    destination: string;
+    /** الحجم المتوقَّع كما أعلنه البيان الموقَّع — يُستعمل للنسبة فقط، والتحقّق بالبصمة. */
+    expectedBytes: number;
+    onProgress?: (progress: DownloadProgress) => void;
+};
+export type DownloadResult = {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    reason: string;
+    unreachable: boolean;
+};
+/**
+ * AR: ينزّل إلى ملفّ مؤقّت، مستأنفًا ما كُتب منه إن وُجد.
+ *
+ *     **لا شيء في التثبيت يُلمَس هنا.** الوجهة مجلد مؤقّت، والملفّ الناقص يبقى بين المحاولات
+ *     عمدًا — هو رأس مال الاستئناف. ويُحذَف عند فشلٍ نهائيّ لئلّا يبقى نصفُ حزمةٍ يُستأنف
+ *     يومًا فوق إصدارٍ آخر.
+ *
+ *     و**الرمز الموقَّع في الرابط ينتهي بعد ربع ساعة** (P5.3): تنزيلٌ أطول من ذلك يُقابَل
+ *     بـ‎403‎ عند محاولة الاستئناف. لذلك يُميَّز الرفض عن الانقطاع هنا أيضًا — الرفض يوقف
+ *     المحاولات، والانقطاع يعيدها.
+ *
+ * EN: Downloads to a temporary file, resuming whatever was already written.
+ *
+ *     **Nothing in the installation is touched here.** The destination is a temporary directory,
+ *     and a partial file survives between attempts deliberately — it is the capital resumption is
+ *     built on. It is removed on final failure so half a bundle is not resumed one day on top of a
+ *     different release.
+ *
+ *     And **the signed token in the URL expires after fifteen minutes** (P5.3): a download longer
+ *     than that meets a `403` when it tries to resume. So refusal is separated from interruption
+ *     here too — refusal stops the attempts, interruption repeats them.
+ */
+export declare function downloadBundle(options: DownloadOptions): Promise<DownloadResult>;
+//# sourceMappingURL=download.d.ts.map

package/dist/updating/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/updating/download.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,gBAAgB,GAAG;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC3B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAiGtF"}

package/dist/updating/download.js

@@ -0,0 +1,144 @@
+import { createWriteStream, existsSync, mkdirSync, statSync, unlinkSync } from "node:fs";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { dirname } from "node:path";
+// AR: تنزيل حزمة التحديث، باستئناف وتقدّم.
+//
+//     **الاستئناف ليس رفاهية.** الوصلة التي تخدم استراحةً على طريق صحراوي تنقطع، ونصف
+//     غيغابايت يُعاد من الصفر في كل مرّة قد لا يكتمل أبدًا — فيصير التحديث ميزةً موجودة على
+//     الورق ومستحيلة عند من يحتاجها. المركز يدعم ‎Range‎ (P5.3)، وهذا الطرف يستعمله.
+//
+// EN: Downloading the update bundle, with resume and progress.
+//
+//     **Resuming is not a luxury.** The link serving a rest-house on a desert road drops, and half
+//     a gigabyte restarted from zero every time may never finish — making updates a feature that
+//     exists on paper and is impossible for whoever needs it. The centre supports `Range` (P5.3),
+//     and this side uses it.
+const TIMEOUT_MS = 60_000;
+const ATTEMPTS = 4;
+/**
+ * AR: ينزّل إلى ملفّ مؤقّت، مستأنفًا ما كُتب منه إن وُجد.
+ *
+ *     **لا شيء في التثبيت يُلمَس هنا.** الوجهة مجلد مؤقّت، والملفّ الناقص يبقى بين المحاولات
+ *     عمدًا — هو رأس مال الاستئناف. ويُحذَف عند فشلٍ نهائيّ لئلّا يبقى نصفُ حزمةٍ يُستأنف
+ *     يومًا فوق إصدارٍ آخر.
+ *
+ *     و**الرمز الموقَّع في الرابط ينتهي بعد ربع ساعة** (P5.3): تنزيلٌ أطول من ذلك يُقابَل
+ *     بـ‎403‎ عند محاولة الاستئناف. لذلك يُميَّز الرفض عن الانقطاع هنا أيضًا — الرفض يوقف
+ *     المحاولات، والانقطاع يعيدها.
+ *
+ * EN: Downloads to a temporary file, resuming whatever was already written.
+ *
+ *     **Nothing in the installation is touched here.** The destination is a temporary directory,
+ *     and a partial file survives between attempts deliberately — it is the capital resumption is
+ *     built on. It is removed on final failure so half a bundle is not resumed one day on top of a
+ *     different release.
+ *
+ *     And **the signed token in the URL expires after fifteen minutes** (P5.3): a download longer
+ *     than that meets a `403` when it tries to resume. So refusal is separated from interruption
+ *     here too — refusal stops the attempts, interruption repeats them.
+ */
+export async function downloadBundle(options) {
+    const { url, destination, expectedBytes, onProgress } = options;
+    mkdirSync(dirname(destination), { recursive: true });
+    let lastReason = "التنزيل لم يبدأ.";
+    for (let attempt = 1; attempt <= ATTEMPTS; attempt += 1) {
+        const alreadyHave = existsSync(destination) ? statSync(destination).size : 0;
+        // اكتمل من محاولة سابقة: لا نطلب نطاقًا فارغًا (يردّ المركز ‎416‎ وهو محقّ).
+        if (expectedBytes > 0 && alreadyHave >= expectedBytes) {
+            onProgress?.({ receivedBytes: alreadyHave, totalBytes: expectedBytes, percent: 100 });
+            return { ok: true, bytes: alreadyHave };
+        }
+        try {
+            const response = await fetch(url, {
+                headers: alreadyHave > 0 ? { Range: `bytes=${alreadyHave}-` } : {},
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            // AR: **رفضٌ صريح يوقف المحاولات.** ‎403‎ يعني رمزًا انتهى أو إصدارًا سُحب، و‎410‎ يعني
+            //     أن المركز قرّر ألّا يُعطى هذا الإصدار بعد الآن. إعادةُ المحاولة عليها حلقةٌ تنتهي
+            //     بنفس الجواب وقد أضاعت دقائق العميل.
+            // EN: **An explicit refusal stops the attempts.** A `403` means an expired token or a revoked
+            //     release, a `410` means the centre decided this release is no longer to be given out.
+            //     Retrying either is a loop ending in the same answer, having spent the customer's
+            //     minutes.
+            if (response.status === 403 || response.status === 410 || response.status === 404) {
+                cleanup(destination);
+                return {
+                    ok: false,
+                    reason: await refusalMessage(response),
+                    unreachable: false,
+                };
+            }
+            if (!response.ok && response.status !== 206) {
+                lastReason = `الخادم ردّ بـ${response.status}.`;
+                continue;
+            }
+            // AR: **‎200‎ على طلبٍ بنطاق يعني أن الخادم تجاهل الاستئناف** ويرسل من البداية. الكتابة
+            //     في الوضع الملحِق عندها تنتج ملفًّا مضاعفًا تفشل بصمته — فنبدأ من الصفر بدلًا منه.
+            // EN: **A `200` to a ranged request means the server ignored the resume** and is sending from
+            //     the start. Appending then produces a doubled file whose digest fails — so we start over
+            //     instead.
+            const resuming = alreadyHave > 0 && response.status === 206;
+            if (alreadyHave > 0 && !resuming)
+                cleanup(destination);
+            const startAt = resuming ? alreadyHave : 0;
+            const total = expectedBytes > 0 ? expectedBytes : startAt + contentLength(response);
+            if (!response.body) {
+                lastReason = "الخادم لم يرسل محتوى.";
+                continue;
+            }
+            let received = startAt;
+            const source = Readable.fromWeb(response.body);
+            source.on("data", (chunk) => {
+                received += chunk.length;
+                onProgress?.({
+                    receivedBytes: received,
+                    totalBytes: total,
+                    percent: total > 0 ? Math.min(100, Math.round((received / total) * 100)) : 0,
+                });
+            });
+            await pipeline(source, createWriteStream(destination, { flags: resuming ? "a" : "w" }));
+            const finalSize = statSync(destination).size;
+            // AR: حجمٌ ناقص بعد دفقٍ انتهى بلا خطأ = اتصالٌ قُطع بهدوء. **يُعاد لا يُقبَل**: ملفّ
+            //     ناقص يفشل تحقّقه لاحقًا برسالة «البصمة لا تطابق» تتّهم المركز بلا ذنب.
+            // EN: A short file after a stream that ended without error = a connection cut quietly.
+            //     **Retried, not accepted**: a truncated file fails verification later with a "digest
+            //     mismatch" that blames the centre for nothing.
+            if (expectedBytes > 0 && finalSize < expectedBytes) {
+                lastReason = `وصل ${finalSize} من ${expectedBytes} بايت.`;
+                continue;
+            }
+            return { ok: true, bytes: finalSize };
+        }
+        catch (error) {
+            lastReason = error instanceof Error ? error.message : String(error);
+        }
+        if (attempt < ATTEMPTS) {
+            await new Promise((done) => setTimeout(done, 1000 * 2 ** (attempt - 1)));
+        }
+    }
+    cleanup(destination);
+    return { ok: false, reason: lastReason, unreachable: true };
+}
+function contentLength(response) {
+    const raw = response.headers.get("content-length");
+    const value = raw ? Number(raw) : 0;
+    return Number.isFinite(value) ? value : 0;
+}
+/** يقرأ رسالة المركز العربية الجاهزة من غلاف D4، أو يصف الحالة حين لا غلاف. */
+async function refusalMessage(response) {
+    try {
+        const body = (await response.json());
+        if (body.error?.message)
+            return body.error.message;
+    }
+    catch {
+        // ردٌّ ليس JSON: نصف الحالة بدل أن نخترع سببًا.
+    }
+    return `الخادم رفض التنزيل (${response.status}).`;
+}
+function cleanup(path) {
+    if (existsSync(path))
+        unlinkSync(path);
+}
+//# sourceMappingURL=download.js.map

package/dist/updating/download.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.js","sourceRoot":"","sources":["../../src/updating/download.ts"],"names":[],"mappings":"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"}

package/dist/updating/rollback.d.ts

@@ -0,0 +1,33 @@
+import type { Profile } from "../profiles/types.js";
+import { type SwapHandle } from "./apply.js";
+export type RollbackReport = {
+    /** هل عادت الشجرة القديمة إلى مكانها؟ */
+    restored: boolean;
+    /** هل أقلعت الخدمات بعد العودة؟ */
+    running: boolean;
+    /** ما تعذّر، إن تعذّر شيء. يُعرَض للفنيّ: هنا يبدأ التدخّل اليدويّ. */
+    problem?: string;
+};
+/**
+ * AR: يعيد النظام إلى ما كان عليه: يوقف ما أُقلع، ويرجع الشجرة، ثم يشغّل.
+ *
+ *     **يُوقِف أوّلًا حتى لو ظنّ المنادي أن شيئًا لم يُقلع.** فشلُ فحص الصحة يعني أن الخدمة
+ *     **أُقلعت** بالحزمة الجديدة ولم تجب — أي أن عمليةً حيّة تمسك ملفّات الشجرة الجديدة،
+ *     وإعادةُ التسمية فوقها تفشل على ويندوز. الإيقاف قبل التراجع هو ما يجعل التراجع ممكنًا.
+ *
+ *     **ويعيد تقريرًا ولا يرمي.** هذه آخر شبكة أمان في المسار: استثناءٌ يخرج منها يترك المالك
+ *     بأثر مكدّس بدل جملةٍ تقول له ما حال نظامه الآن.
+ *
+ * EN: Returns the system to what it was: stops whatever started, restores the tree, then starts.
+ *
+ *     **It stops first even when the caller believes nothing started.** A failed health check means
+ *     the service **did** start on the new bundle and did not answer — so a live process is holding
+ *     the new tree's files, and renaming over it fails on Windows. Stopping before rolling back is
+ *     what makes the rollback possible.
+ *
+ *     **And it returns a report rather than throwing.** This is the last safety net on the path: an
+ *     exception escaping it leaves the owner with a stack trace instead of a sentence telling them
+ *     what state their system is in now.
+ */
+export declare function rollback(profile: Profile, handle: SwapHandle): Promise<RollbackReport>;
+//# sourceMappingURL=rollback.d.ts.map

package/dist/updating/rollback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.d.ts","sourceRoot":"","sources":["../../src/updating/rollback.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAgBvD,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;IAClB,mCAAmC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,cAAc,CAAC,CA6B5F"}

package/dist/updating/rollback.js

@@ -0,0 +1,54 @@
+import { startServices, stopServices } from "../supervisor/orchestrator.js";
+import { undoSwap } from "./apply.js";
+/**
+ * AR: يعيد النظام إلى ما كان عليه: يوقف ما أُقلع، ويرجع الشجرة، ثم يشغّل.
+ *
+ *     **يُوقِف أوّلًا حتى لو ظنّ المنادي أن شيئًا لم يُقلع.** فشلُ فحص الصحة يعني أن الخدمة
+ *     **أُقلعت** بالحزمة الجديدة ولم تجب — أي أن عمليةً حيّة تمسك ملفّات الشجرة الجديدة،
+ *     وإعادةُ التسمية فوقها تفشل على ويندوز. الإيقاف قبل التراجع هو ما يجعل التراجع ممكنًا.
+ *
+ *     **ويعيد تقريرًا ولا يرمي.** هذه آخر شبكة أمان في المسار: استثناءٌ يخرج منها يترك المالك
+ *     بأثر مكدّس بدل جملةٍ تقول له ما حال نظامه الآن.
+ *
+ * EN: Returns the system to what it was: stops whatever started, restores the tree, then starts.
+ *
+ *     **It stops first even when the caller believes nothing started.** A failed health check means
+ *     the service **did** start on the new bundle and did not answer — so a live process is holding
+ *     the new tree's files, and renaming over it fails on Windows. Stopping before rolling back is
+ *     what makes the rollback possible.
+ *
+ *     **And it returns a report rather than throwing.** This is the last safety net on the path: an
+ *     exception escaping it leaves the owner with a stack trace instead of a sentence telling them
+ *     what state their system is in now.
+ */
+export async function rollback(profile, handle) {
+    try {
+        await stopServices(profile);
+    }
+    catch {
+        // الإيقاف الفاشل لا يمنع المحاولة: قد لا تكون هناك عملية أصلًا.
+    }
+    try {
+        await undoSwap(handle);
+    }
+    catch (error) {
+        return {
+            restored: false,
+            running: false,
+            problem: `تعذّرت إعادة النسخة السابقة من ${handle.previous}: ` +
+                `${error instanceof Error ? error.message : error}`,
+        };
+    }
+    try {
+        const started = await startServices(profile);
+        return { restored: true, running: started.ok };
+    }
+    catch (error) {
+        return {
+            restored: true,
+            running: false,
+            problem: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+//# sourceMappingURL=rollback.js.map

package/dist/updating/rollback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rollback.js","sourceRoot":"","sources":["../../src/updating/rollback.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAmB,MAAM,YAAY,CAAC;AAyBvD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,OAAgB,EAAE,MAAkB;IACjE,IAAI,CAAC;QACH,MAAM,YAAY,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,gEAAgE;IAClE,CAAC;IAED,IAAI,CAAC;QACH,MAAM,QAAQ,CAAC,MAAM,CAAC,CAAC;IACzB,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO;YACL,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK;YACd,OAAO,EACL,kCAAkC,MAAM,CAAC,QAAQ,IAAI;gBACrD,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,EAAE;SACtD,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,OAAO,CAAC,CAAC;QAC7C,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;IACjD,CAAC;IAAC,OAAO,KAAc,EAAE,CAAC;QACxB,OAAO;YACL,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;SAChE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/updating/self.d.ts

@@ -0,0 +1,16 @@
+export declare const PACKAGE_NAME = "@wasmsoft/fantastic";
+export interface PublishedVersion {
+    version: string;
+    /** هل المنشور أحدث ممّا هو مثبَّت؟ */
+    newer: boolean;
+}
+/**
+ * AR: يعيد ‎undefined‎ عند أيّ تعذّر — شبكةٌ مقطوعة، سِجلٌّ صامت، ردٌّ لا يُفهَم. **والصمت هنا
+ *     جوابٌ صحيح**: جهازٌ في استراحةٍ بلا إنترنت يجب أن يعمل بكل أوامره، وسؤالٌ عن تحديثٍ فشل
+ *     ليس عطلًا يستحقّ رسالة حمراء.
+ * EN: Returns `undefined` on any failure — a cut network, a silent registry, an answer that makes no
+ *     sense. **And silence is a correct answer here**: an appliance in a rest-house with no internet
+ *     must run every command, and a failed update check is not a fault deserving a red message.
+ */
+export declare function latestPublished(): Promise<PublishedVersion | undefined>;
+//# sourceMappingURL=self.d.ts.map

package/dist/updating/self.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self.d.ts","sourceRoot":"","sources":["../../src/updating/self.ts"],"names":[],"mappings":"AAsBA,eAAO,MAAM,YAAY,wBAAwB,CAAC;AAKlD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAiB7E"}

package/dist/updating/self.js

@@ -0,0 +1,50 @@
+import { VERSION } from "../version.js";
+import { compareVersions } from "../acquire/compatibility.js";
+// AR: سؤال السِّجلّ العام عن أحدث إصدارٍ من الواجهة نفسها (٠٢٦/US4).
+//
+//     **مصدرٌ واحد للسؤال، ومستهلكان**: أمر ‎self-update‎، والإعلان العابر الذي يظهر مرّةً في
+//     ‎doctor‎. ونسختان من نفس النداء كانتا ستفترقان في المهلة أو في قراءة الردّ.
+//
+//     **والمهلة قصيرة عمدًا.** هذا نداءٌ إضافيّ لا يطلبه المستخدم، وسِجلٌّ بطيء أو شبكةٌ صامتة
+//     يجب ألّا يعلّقا أمرًا جاء ليقول حالة نظام. ثانيتان تكفيان لسؤالٍ ناجح، وما زاد عليهما لا
+//     يستحقّ انتظار الفنّي.
+// EN: Asking the public registry for the CLI's own newest version (026/US4).
+//
+//     **One source for the question, two consumers**: the `self-update` command, and the passing
+//     notice shown once by `doctor`. Two copies of the same call would drift in their timeout or in
+//     how they read the answer.
+//
+//     **And the timeout is deliberately short.** This is an extra call the user never asked for, and
+//     a slow registry or a silent network must not hang a command that came to report a system's
+//     state. Two seconds suffice for a successful ask, and anything beyond is not worth a
+//     technician's waiting.
+export const PACKAGE_NAME = "@wasmsoft/fantastic";
+const REGISTRY = "https://registry.npmjs.org";
+const TIMEOUT_MS = 2_000;
+/**
+ * AR: يعيد ‎undefined‎ عند أيّ تعذّر — شبكةٌ مقطوعة، سِجلٌّ صامت، ردٌّ لا يُفهَم. **والصمت هنا
+ *     جوابٌ صحيح**: جهازٌ في استراحةٍ بلا إنترنت يجب أن يعمل بكل أوامره، وسؤالٌ عن تحديثٍ فشل
+ *     ليس عطلًا يستحقّ رسالة حمراء.
+ * EN: Returns `undefined` on any failure — a cut network, a silent registry, an answer that makes no
+ *     sense. **And silence is a correct answer here**: an appliance in a rest-house with no internet
+ *     must run every command, and a failed update check is not a fault deserving a red message.
+ */
+export async function latestPublished() {
+    try {
+        const response = await fetch(`${REGISTRY}/${encodeURIComponent(PACKAGE_NAME)}/latest`, {
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+            headers: { accept: "application/vnd.npm.install-v1+json" },
+        });
+        if (!response.ok)
+            return undefined;
+        const payload = (await response.json());
+        const version = payload.version?.trim();
+        if (!version)
+            return undefined;
+        return { version, newer: compareVersions(version, VERSION) > 0 };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=self.js.map

package/dist/updating/self.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self.js","sourceRoot":"","sources":["../../src/updating/self.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAC;AAE9D,qEAAqE;AACrE,EAAE;AACF,8FAA8F;AAC9F,kFAAkF;AAClF,EAAE;AACF,+FAA+F;AAC/F,+FAA+F;AAC/F,4BAA4B;AAC5B,6EAA6E;AAC7E,EAAE;AACF,iGAAiG;AACjG,oGAAoG;AACpG,gCAAgC;AAChC,EAAE;AACF,qGAAqG;AACrG,iGAAiG;AACjG,0FAA0F;AAC1F,4BAA4B;AAE5B,MAAM,CAAC,MAAM,YAAY,GAAG,qBAAqB,CAAC;AAElD,MAAM,QAAQ,GAAG,4BAA4B,CAAC;AAC9C,MAAM,UAAU,GAAG,KAAK,CAAC;AAQzB;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,QAAQ,IAAI,kBAAkB,CAAC,YAAY,CAAC,SAAS,EAAE;YACrF,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,UAAU,CAAC;YACvC,OAAO,EAAE,EAAE,MAAM,EAAE,qCAAqC,EAAE;SAC3D,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,SAAS,CAAC;QAEnC,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAyB,CAAC;QAChE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC,OAAO;YAAE,OAAO,SAAS,CAAC;QAE/B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;IACnE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/updating/verify.d.ts

@@ -0,0 +1,25 @@
+export type ChecksumOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+    expected: string;
+    actual: string;
+};
+/**
+ * AR: يقارن بصمة الملفّ المنزَّل بالبصمة الموثوقة.
+ *
+ *     ويُفحَص الحجم أوّلًا لأنه يفرّق سببين بعلاجين: ملفٌّ **أقصر** يعني اتصالًا قُطع، وعلاجُه
+ *     إعادةُ التنزيل؛ وملفٌّ بالحجم الصحيح ببصمة مختلفة يعني **تبديلًا أو تلفًا**، وعلاجه
+ *     ليس إعادة المحاولة. رسالةٌ واحدة لكليهما تُرسل الفنيّ في الاتجاه الخطأ نصف الوقت.
+ * EN: Compares the downloaded file's digest against the trusted one.
+ *
+ *     Size is checked first because it separates two causes with two remedies: a **shorter** file
+ *     means a cut connection and the remedy is downloading again; a file of the right size with a
+ *     different digest means **substitution or corruption**, and retrying is not the remedy. One
+ *     message for both sends the technician the wrong way half the time.
+ */
+export declare function verifyChecksum(file: string, expectedSha256: string, expectedBytes: number): Promise<ChecksumOutcome>;
+/** يحسب البصمة بالبثّ. نصف غيغابايت في ذاكرة جهاز الاستراحة يقتله. */
+export declare function sha256Of(file: string): Promise<string>;
+//# sourceMappingURL=verify.d.ts.map

package/dist/updating/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/updating/verify.ts"],"names":[],"mappings":"AAkCA,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,eAAe,CAAC,CA6B1B;AAED,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAStD"}