@openinc/parse-server-opendash 4.1.1 → 4.1.2

package/dist/scripts/migration/passes/12-history.js

@@ -0,0 +1,332 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pass12 = void 0;
+const node_1 = __importDefault(require("parse/node"));
+const index_js_1 = require("../../../types/index.js");
+const acl_js_1 = require("../lib/acl.js");
+const latest_js_1 = require("../lib/latest.js");
+const material_js_1 = require("../lib/material.js");
+const ptr_js_1 = require("../lib/ptr.js");
+const pass_js_1 = require("../lib/pass.js");
+const ticket_js_1 = require("../lib/ticket.js");
+const _08_tickets_js_1 = require("./08-tickets.js");
+function sortEvents(events) {
+    return [...events].sort((a, b) => a.at.getTime() - b.at.getTime());
+}
+/**
+ * Pass 12 — replay the v1 side tables into `OD3_Changelog`.
+ *
+ * The v2 ticket detail page already aggregates changelog entries for
+ * `OD3_Service_Ticket` by objectId and renders each field through that field's own
+ * Display component, so entries written here need no UI work to show up.
+ *
+ * Three things this depends on and cannot work around:
+ *
+ * - **Historical `createdAt`.** The timeline sorts, groups and labels purely by
+ *   `entry.createdAt`. Under the master key Parse would stamp `now` on every entry
+ *   and the whole trail would collapse onto the migration date.
+ * - **`ACL` inside the snapshot.** `beforeSave(OD3_Changelog)` mirrors the changed
+ *   object's ACL, read from `value.ACL` / `original.ACL`. Omit it and history ends
+ *   up more restrictive than the ticket it describes.
+ * - **Parse wire types in the snapshot.** `{__type:"Pointer"}` / `{__type:"Date"}`
+ *   are what make the diff render reference pills and dates instead of raw JSON.
+ *
+ * By construction the final snapshot of the replay equals the flat ticket pass 08
+ * wrote — which `verify.ts` checks, and which is the strongest signal in the whole
+ * migration that both halves agree.
+ */
+exports.pass12 = {
+    id: "12",
+    title: "history",
+    needs: ["08"],
+    async run({ config, map, report, entry }) {
+        const { batchSize, tenantId } = config;
+        const scoped = (cls) => () => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(cls), tenantId);
+        // ── ACLs of the migrated tickets ─────────────────────────────────────────
+        // `beforeSave(OD3_Changelog)` normally mirrors the changed object's ACL onto
+        // the entry, but beforeSave is not registered in migration mode — so each entry
+        // must carry it explicitly, and the snapshot should show the v2 ACL rather than
+        // the v1 one it used to.
+        const ticketAcls = await (0, ticket_js_1.loadTicketAcls)(config);
+        // ── Tag parents, for closure expansion in the tag events ─────────────────
+        const parentOf = new Map();
+        for (const tag of await (0, pass_js_1.all)(() => new node_1.default.Query(index_js_1.Service_Tag), batchSize)) {
+            if (tag.id)
+                parentOf.set(tag.id, (0, pass_js_1.refId)(tag.get("parent")));
+        }
+        // ── Every history table, one query each ──────────────────────────────────
+        const titles = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Title), batchSize);
+        const priorities = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Priority), batchSize);
+        const downtimes = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Downtime), batchSize);
+        const frequencies = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Frequency), batchSize);
+        const restrictions = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Restriction), batchSize);
+        const duedates = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Duedate), batchSize);
+        const sourceRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Source), batchSize);
+        const projectRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Project), batchSize);
+        const categoryRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Issuecategory), batchSize);
+        const stateRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Kanban_State), batchSize);
+        const assignmentRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Assignment), batchSize);
+        const materialRows = await (0, latest_js_1.groupByTicket)(scoped(index_js_1.Maintenance_Ticket_Material), batchSize);
+        // Which tickets already have reconstructed history, so a re-run does not
+        // duplicate a trail. Resumability is per ticket, not per batch — this pass
+        // writes 50k–200k rows and a mid-pass failure must not restart it.
+        const alreadyDone = new Set();
+        for await (const page of (0, pass_js_1.pages)(() => new node_1.default.Query(index_js_1.Changelog)
+            .equalTo("nameOfClass", index_js_1.Service_Ticket.className)
+            .equalTo("operation", "create"), batchSize)) {
+            for (const row of page) {
+                const context = row.get("context");
+                if (context?.migrated)
+                    alreadyDone.add(row.get("changedObject"));
+            }
+        }
+        if (alreadyDone.size > 0) {
+            report.info(entry, `${alreadyDone.size} ticket(s) already have reconstructed history — skipping them`);
+        }
+        let totalEntries = 0;
+        for await (const page of (0, pass_js_1.pages)(() => (0, pass_js_1.scopeToTenant)(new node_1.default.Query(index_js_1.Maintenance_Ticket), tenantId), batchSize)) {
+            for (const ticket of page) {
+                const oldId = ticket.id;
+                if (!oldId)
+                    continue;
+                const newId = map.get(index_js_1.Maintenance_Ticket.className, oldId);
+                if (!newId) {
+                    report.error(entry, `ticket ${oldId} has no migrated counterpart — run pass 08 first`);
+                    continue;
+                }
+                if (alreadyDone.has(newId)) {
+                    entry.skipped++;
+                    continue;
+                }
+                const ticketTenantId = (0, pass_js_1.refId)(ticket.get("tenant"));
+                const creatorId = (0, pass_js_1.refId)(ticket.get("user"));
+                // ── Build the event list ─────────────────────────────────────────────
+                const events = [];
+                const push = (row, changes, legacyClass) => {
+                    // Same clock the fold uses, or the replay ends on a different row than
+                    // the ticket carries. See lib/latest.ts `effectiveAt`.
+                    const at = (0, latest_js_1.effectiveAt)(row);
+                    if (!at || !row.id)
+                        return;
+                    // A row whose value is unset is not a change. The fold treats it the same
+                    // way (`latest?.get(x) ?? fallback`), so emitting `{title: undefined}`
+                    // here would make the trail claim an edit the ticket never took.
+                    const real = Object.fromEntries(Object.entries(changes).filter(([, v]) => v !== undefined && v !== null));
+                    if (Object.keys(real).length === 0)
+                        return;
+                    events.push({
+                        at,
+                        by: (0, pass_js_1.refId)(row.get("user")),
+                        changes: real,
+                        legacyClass,
+                        legacyId: row.id,
+                    });
+                };
+                for (const row of titles.get(oldId) ?? []) {
+                    push(row, { title: row.get("title") }, index_js_1.Maintenance_Ticket_Title.className);
+                }
+                for (const row of priorities.get(oldId) ?? []) {
+                    push(row, { priority: row.get("value") }, index_js_1.Maintenance_Priority.className);
+                }
+                for (const row of downtimes.get(oldId) ?? []) {
+                    push(row, { downtime: row.get("value") }, index_js_1.Maintenance_Downtime.className);
+                }
+                for (const row of frequencies.get(oldId) ?? []) {
+                    push(row, { frequency: row.get("value") }, index_js_1.Maintenance_Frequency.className);
+                }
+                for (const row of restrictions.get(oldId) ?? []) {
+                    push(row, { restriction: row.get("value") }, index_js_1.Maintenance_Restriction.className);
+                }
+                for (const row of duedates.get(oldId) ?? []) {
+                    // One v1 row carries both ends of the range, so this is a single event
+                    // that changes two fields — not two events.
+                    const changes = {};
+                    const end = row.get("end");
+                    const start = row.get("start");
+                    if (end)
+                        changes.dueDate = (0, ptr_js_1.dateVal)(end);
+                    if (start)
+                        changes.startDate = (0, ptr_js_1.dateVal)(start);
+                    push(row, changes, index_js_1.Maintenance_Duedate.className);
+                }
+                for (const row of sourceRows.get(oldId) ?? []) {
+                    const equipmentId = map.get(index_js_1.Source.className, (0, pass_js_1.refId)(row.get("source")) ?? "");
+                    if (equipmentId) {
+                        push(row, { equipment: (0, ptr_js_1.ptr)(index_js_1.Service_Equipment.className, equipmentId) }, index_js_1.Maintenance_Ticket_Source.className);
+                    }
+                }
+                for (const row of projectRows.get(oldId) ?? []) {
+                    const projectId = map.get(index_js_1.Maintenance_Project.className, (0, pass_js_1.refId)(row.get("project")) ?? "");
+                    if (projectId) {
+                        push(row, { project: (0, ptr_js_1.ptr)(index_js_1.Service_Project.className, projectId) }, index_js_1.Maintenance_Ticket_Project.className);
+                    }
+                }
+                for (const row of categoryRows.get(oldId) ?? []) {
+                    const tagId = map.get(index_js_1.Maintenance_Issuecategory.className, (0, pass_js_1.refId)(row.get("issuecategory")) ?? "");
+                    if (tagId) {
+                        // Stored as the closure, matching what the ticket itself carries.
+                        push(row, { tags: (0, _08_tickets_js_1.closureOf)(tagId, parentOf) }, index_js_1.Maintenance_Ticket_Issuecategory.className);
+                    }
+                }
+                for (const row of stateRows.get(oldId) ?? []) {
+                    const statusId = map.get(index_js_1.Maintenance_Kanban_State.className, (0, pass_js_1.refId)(row.get("state")) ?? "");
+                    if (statusId) {
+                        push(row, { status: (0, ptr_js_1.ptr)(index_js_1.Service_Status.className, statusId) }, index_js_1.Maintenance_Ticket_Kanban_State.className);
+                    }
+                }
+                for (const row of materialRows.get(oldId) ?? []) {
+                    // Each v1 row carries the WHOLE list, so every row is a complete
+                    // new value for the column — the same conversion the fold uses, so
+                    // the replay ends on exactly what pass 08 wrote.
+                    //
+                    // An empty result is emitted as an empty array rather than skipped:
+                    // clearing the last material line is a real edit, and `push` drops
+                    // undefined/null but keeps `[]`.
+                    const { entries } = (0, material_js_1.toMaterial)(row.get("itemList"), map);
+                    push(row, { material: entries }, index_js_1.Maintenance_Ticket_Material.className);
+                }
+                // ── Assignments: group by batchStamp ────────────────────────────────
+                // `assignUsersAndRoles` writes one row *per assignee* per change, which is
+                // exactly what `batchStamp` exists to tie back together. Ungrouped, a
+                // three-assignee change would render as three separate timeline events.
+                const batches = new Map();
+                for (const row of assignmentRows.get(oldId) ?? []) {
+                    const stamp = row.get("batchStamp");
+                    if (!stamp)
+                        continue;
+                    const key = stamp.toISOString();
+                    const bucket = batches.get(key);
+                    if (bucket)
+                        bucket.push(row);
+                    else
+                        batches.set(key, [row]);
+                }
+                for (const [stampIso, rows] of batches) {
+                    const users = rows
+                        .map((r) => (0, pass_js_1.refId)(r.get("assignedUser")))
+                        .filter((id) => !!id);
+                    const roles = rows
+                        .map((r) => (0, pass_js_1.refId)(r.get("assignedRole")))
+                        .filter((id) => !!id);
+                    const changes = {};
+                    if (users.length)
+                        changes.assignedUsers = users;
+                    if (roles.length)
+                        changes.assignedRoles = roles;
+                    if (Object.keys(changes).length === 0)
+                        continue;
+                    events.push({
+                        at: new Date(stampIso),
+                        // The acting user is who *made* the assignment, not who was assigned.
+                        by: (0, pass_js_1.refId)(rows[0].get("user")),
+                        changes,
+                        legacyClass: index_js_1.Maintenance_Ticket_Assignment.className,
+                        legacyId: rows.map((r) => r.id).join(","),
+                    });
+                }
+                // ── Replay ──────────────────────────────────────────────────────────
+                const ordered = sortEvents(events);
+                // The creation snapshot: what the ticket looked like before any side-table
+                // row existed. Anything only ever set by a side table is absent here and
+                // appears as its first event, which is the honest reading.
+                const v2Acl = ticketAcls.get(newId);
+                const aclJson = v2Acl?.toJSON() ?? ticket.getACL()?.toJSON();
+                const snapshot = {
+                    objectId: newId,
+                    title: ticket.get("title") ?? "",
+                    deleted: ticket.get("enabled") !== true,
+                    origin: `legacy:${oldId}`,
+                };
+                if (ticket.get("description")) {
+                    snapshot.description = ticket.get("description");
+                }
+                if (ticketTenantId)
+                    snapshot.tenant = (0, ptr_js_1.tenantPtr)(ticketTenantId);
+                if (creatorId)
+                    snapshot.createdBy = (0, ptr_js_1.userPtr)(creatorId);
+                if (aclJson)
+                    snapshot.ACL = aclJson;
+                // Captured before the walk mutates `snapshot`.
+                const createEntry = {
+                    operation: "create",
+                    original: null,
+                    value: { ...snapshot },
+                    at: ticket.createdAt ?? ordered[0]?.at ?? new Date(0),
+                    by: creatorId,
+                    legacyClass: index_js_1.Maintenance_Ticket.className,
+                    legacyId: oldId,
+                };
+                const toWrite = [];
+                for (const event of ordered) {
+                    const before = { ...snapshot };
+                    Object.assign(snapshot, event.changes);
+                    toWrite.push({
+                        operation: "update",
+                        original: before,
+                        value: { ...snapshot },
+                        at: event.at,
+                        by: event.by,
+                        legacyClass: event.legacyClass,
+                        legacyId: event.legacyId,
+                    });
+                }
+                // The `create` entry goes LAST on purpose. `alreadyDone` above treats its
+                // presence as "this ticket's trail is complete", so writing it first would
+                // make a run that died mid-ticket look finished on resume and leave the
+                // trail permanently truncated. Written last, it is a commit marker.
+                // Storage order is irrelevant — the timeline sorts by createdAt.
+                toWrite.push(createEntry);
+                if (config.dryRun) {
+                    entry.created += toWrite.length;
+                    totalEntries += toWrite.length;
+                    continue;
+                }
+                let wrote = 0;
+                for (const item of toWrite) {
+                    const changelog = new index_js_1.Changelog();
+                    changelog.set("nameOfClass", index_js_1.Service_Ticket.className);
+                    changelog.set("changedObject", newId);
+                    changelog.set("operation", item.operation);
+                    changelog.set("masterkey", false);
+                    if (item.by)
+                        changelog.set("actingUser", (0, ptr_js_1.userPtr)(item.by));
+                    changelog.set("original", item.original);
+                    changelog.set("value", item.value);
+                    // Provenance: distinguishes reconstructed history from history the app
+                    // wrote, and lets a re-run recognise what it already did.
+                    changelog.set("context", {
+                        migrated: true,
+                        run: config.runId,
+                        legacyClass: item.legacyClass,
+                        legacyId: item.legacyId,
+                    });
+                    // Whoever can see the ticket can see its history — the grant the
+                    // suppressed changelog hook would have applied.
+                    if (v2Acl)
+                        changelog.setACL(v2Acl);
+                    try {
+                        // The historical timestamp IS the entry: the changelog timeline sorts,
+                        // groups and labels purely by createdAt.
+                        await (0, acl_js_1.saveMigrated)(config, changelog, {
+                            className: index_js_1.Changelog.className,
+                            isNew: true,
+                            createdAt: item.at,
+                            updatedAt: item.at,
+                        });
+                        wrote += 1;
+                    }
+                    catch (error) {
+                        report.error(entry, `changelog for ticket ${oldId} (${item.legacyClass}) failed: ` +
+                            `${error.message}`);
+                    }
+                }
+                entry.created += wrote;
+                totalEntries += wrote;
+            }
+        }
+        report.info(entry, `${totalEntries} changelog entr(ies) reconstructed`);
+    },
+};

package/dist/scripts/migration/run.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/migration/run.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const env_js_1 = require("./lib/env.js");
+const map_js_1 = require("./lib/map.js");
+const report_js_1 = require("./lib/report.js");
+const _01_statuses_js_1 = require("./passes/01-statuses.js");
+const _02_tags_js_1 = require("./passes/02-tags.js");
+const _03_equipment_js_1 = require("./passes/03-equipment.js");
+const _04_projects_js_1 = require("./passes/04-projects.js");
+const _05_articles_js_1 = require("./passes/05-articles.js");
+const _06_formconfigs_js_1 = require("./passes/06-formconfigs.js");
+const _07_meta_configs_js_1 = require("./passes/07-meta-configs.js");
+const _08_tickets_js_1 = require("./passes/08-tickets.js");
+const _09_ticket_meta_js_1 = require("./passes/09-ticket-meta.js");
+const _10_chat_js_1 = require("./passes/10-chat.js");
+const _11_assets_js_1 = require("./passes/11-assets.js");
+const _12_history_js_1 = require("./passes/12-history.js");
+/**
+ * openservice v1 → v2 migration orchestrator.
+ *
+ *   OD_MIGRATION_MODE=1 PARSE_APP_ID=… PARSE_MAINTENANCE_KEY=… \
+ *     node dist/scripts/migration/run.js --tenant=<id> --dry-run
+ *
+ * Flags: --tenant=<id>  --only=01,08  --dry-run  --resume=<runId>  --batch=500
+ *
+ * Pass order is a hard dependency chain (equipment before tickets, tickets before
+ * anything needing the new ids), so the chain is declared on each pass and checked
+ * here rather than left to whoever runs it.
+ *
+ * Full plan: `plugins/openservice/MIGRATION_PLAN.md` in the opendash repo.
+ */
+/**
+ * Registered in dependency order.
+ *
+ * The order is not cosmetic: equipment/tags/statuses/projects must exist before
+ * tickets can point at them, and tickets must exist before anything keyed by the
+ * new ticket id (meta, chat, assets, history).
+ */
+const PASSES = [
+    _01_statuses_js_1.pass01,
+    _02_tags_js_1.pass02,
+    _03_equipment_js_1.pass03,
+    _04_projects_js_1.pass04,
+    _05_articles_js_1.pass05,
+    _06_formconfigs_js_1.pass06,
+    _07_meta_configs_js_1.pass07,
+    _08_tickets_js_1.pass08,
+    _09_ticket_meta_js_1.pass09,
+    _10_chat_js_1.pass10,
+    _11_assets_js_1.pass11,
+    _12_history_js_1.pass12,
+];
+/** Passes the plan defines but which are deliberately not implemented. */
+const PLANNED = ["13 schedules", "14 executions"];
+function selectPasses(config) {
+    if (!config.only)
+        return PASSES;
+    const wanted = new Set(config.only);
+    const unknown = config.only.filter((id) => !PASSES.some((p) => p.id === id));
+    if (unknown.length) {
+        throw new env_js_1.MigrationConfigError(`Unknown pass id(s): ${unknown.join(", ")}.\n` +
+            `  Implemented: ${PASSES.map((p) => p.id).join(", ")}\n` +
+            `  Deferred, not implemented: ${PLANNED.join(", ")}`);
+    }
+    // A selected pass whose prerequisite is neither selected nor already recorded in
+    // the map would read a half-built world. Warn rather than block: re-running a
+    // single pass against a completed earlier run is a legitimate thing to do.
+    const selected = PASSES.filter((p) => wanted.has(p.id));
+    for (const p of selected) {
+        const missing = p.needs.filter((n) => !wanted.has(n));
+        if (missing.length) {
+            console.warn(`⚠ pass ${p.id} (${p.title}) depends on ${missing.join(", ")}, ` +
+                `which are not in --only. It will rely on their MigrationMap rows ` +
+                `already existing from an earlier run.`);
+        }
+    }
+    return selected;
+}
+async function main() {
+    let config;
+    let passes;
+    try {
+        config = (0, env_js_1.readConfig)(process.argv.slice(2));
+        passes = selectPasses(config);
+    }
+    catch (error) {
+        if (error instanceof env_js_1.MigrationConfigError) {
+            console.error(`\n✗ ${error.message}\n`);
+            return 2;
+        }
+        throw error;
+    }
+    console.log(`\nopenservice v1 → v2 migration`);
+    console.log(`  server   ${config.parseUrl}`);
+    console.log(`  tenant   ${config.tenantId ?? "(all)"}`);
+    console.log(`  run      ${config.runId}`);
+    console.log(`  passes   ${passes.map((p) => p.id).join(", ") || "(none)"}`);
+    if (config.dryRun)
+        console.log(`  MODE     DRY RUN — nothing will be written`);
+    if (PLANNED.length) {
+        console.log(`
+  deferred (MIGRATION_PLAN §4.5): ${PLANNED.join(", ")}`);
+    }
+    (0, env_js_1.initParse)(config);
+    const report = new report_js_1.Report();
+    const map = new map_js_1.MigrationMap(config);
+    try {
+        await map.load();
+    }
+    catch (error) {
+        // Almost always an unreachable server or a rejected key, and the raw Parse
+        // error ("Unexpected end of JSON input") says nothing useful about either.
+        console.error(`
+✗ Could not read ${map_js_1.MIGRATION_MAP_CLASS} from ${config.parseUrl}.
+` +
+            `  ${error.message}
+` +
+            `  Check that Parse Server is reachable there, that PARSE_APP_ID matches, ` +
+            `that PARSE_MAINTENANCE_KEY is the server's maintenanceKey, and that this ` +
+            `host is allowed by maintenanceKeyIps (default: localhost only).
+`);
+        return 2;
+    }
+    for (const pass of passes) {
+        const entry = report.begin(`${pass.id} ${pass.title}`);
+        try {
+            await pass.run({ config, map, report, entry });
+        }
+        catch (error) {
+            report.error(entry, `pass aborted: ${error.message}`);
+        }
+        report.end();
+    }
+    report.printSummary(config.runId, config.dryRun);
+    if (report.failed) {
+        console.error(`✗ run finished with errors. Passes are idempotent — fix the cause and ` +
+            `re-run with --resume=${config.runId}.\n`);
+        return 1;
+    }
+    console.log(config.dryRun
+        ? `✓ dry run clean. Re-run without --dry-run to write.\n`
+        : `✓ run complete. Next: verify.ts.\n`);
+    return 0;
+}
+main().then((code) => process.exit(code), (error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/scripts/migration/verify.d.ts

@@ -0,0 +1 @@
+export {};