editmamei 1.5.1 → 1.7.0

package/dist/tools/gimp-checkpoint-tools.js

@@ -0,0 +1,541 @@
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { existsSync, lstatSync, mkdirSync, readdirSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { validateArgs } from '../utils/validate.js';
+import { toolGimpErrorResult, unknownDiscriminator } from '../utils/tool-helpers.js';
+import { GimpError } from '../backends/gimp/errors.js';
+import { GIMP_IMAGE_PROP } from './gimp-shared.js';
+export const MAX_CHECKPOINTS_PER_IMAGE = 5;
+export const MAX_CHECKPOINTS_TOTAL = 20;
+const checkpointSchema = {
+    type: 'object',
+    properties: {
+        op: {
+            type: 'string',
+            enum: ['create', 'restore', 'list', 'delete'],
+            description: "'create' exports the image's current state — every live filter included — to a " +
+                "disk-backed snapshot and returns a checkpoint_id. 'restore' reopens that snapshot as a " +
+                'NEW image and closes the old one (replace semantics, not a copy: the old image id stops ' +
+                "working once the close succeeds — see 'close_failed' below for when it doesn't). " +
+                "'list' reports every checkpoint (optionally scoped to one image): checkpoint_id, the " +
+                'image it currently belongs to (open: false if that image is confirmed gone — still ' +
+                'restorable; pending: true while still being created), created_at, bytes — never a file ' +
+                "path. 'delete' removes one, freeing its slot.",
+        },
+        image: {
+            ...GIMP_IMAGE_PROP,
+            description: (GIMP_IMAGE_PROP.description ?? '') +
+                ' Required for create. Optional for list (omit to list checkpoints for every image).',
+        },
+        checkpoint_id: {
+            type: 'string',
+            description: 'Required for restore / delete. The id create (or a prior list) reported for this checkpoint.',
+        },
+    },
+    required: ['op'],
+};
+function isSessionRestartedError(error) {
+    return error instanceof GimpError && error.code === 'gimp_session_restarted';
+}
+function isImageAlreadyClosedError(error) {
+    return (error instanceof GimpError &&
+        error.code === 'invalid_argument' &&
+        /no open image with id/i.test(error.message));
+}
+async function refreshOpenness(gimp, registry, opts) {
+    if (registry.size === 0)
+        return;
+    const applyGenerationCheck = () => {
+        const currentGeneration = gimp.generation;
+        if (currentGeneration === undefined)
+            return;
+        for (const record of registry.values()) {
+            if (record.open &&
+                record.generation !== undefined &&
+                record.generation !== currentGeneration) {
+                record.open = false;
+            }
+        }
+    };
+    applyGenerationCheck();
+    if (opts.requireAlreadyRunning && gimp.state !== 'ready')
+        return;
+    let ping;
+    try {
+        ping = await gimp.call('ping', {});
+    }
+    catch {
+        applyGenerationCheck();
+        return;
+    }
+    if (!Array.isArray(ping.images))
+        return;
+    const openIds = new Set(ping.images);
+    for (const record of registry.values()) {
+        if (record.open && !openIds.has(record.image))
+            record.open = false;
+    }
+}
+export function repointSiblings(registry, from, to, generation, newGeneration) {
+    for (const sibling of registry.values()) {
+        if (sibling.image !== from)
+            continue;
+        if (generation !== undefined) {
+            if (sibling.generation !== generation)
+                continue;
+        }
+        else if (sibling.open === false) {
+            continue;
+        }
+        sibling.image = to;
+        sibling.open = true;
+        sibling.generation = newGeneration;
+    }
+}
+function markSiblingsGone(registry, image, generation) {
+    for (const sibling of registry.values()) {
+        if (sibling.image !== image)
+            continue;
+        if (generation !== undefined && sibling.generation !== generation)
+            continue;
+        sibling.open = false;
+    }
+}
+const STORE_DIR_NAME_RE = /^checkpoints-(\d+)-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code !== 'ESRCH';
+    }
+}
+const DEAD_PID_MIN_AGE_MS = 60 * 60 * 1000;
+export function sweepStaleCheckpointDirs(parentDir, ownDir, trackedDirs, processStartedAt = Date.now() - process.uptime() * 1000) {
+    const entries = readdirSync(parentDir);
+    for (const name of entries) {
+        const match = STORE_DIR_NAME_RE.exec(name);
+        if (!match)
+            continue;
+        const path = join(parentDir, name);
+        if (path === ownDir)
+            continue;
+        const pid = Number(match[1]);
+        let stat;
+        try {
+            stat = lstatSync(path);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        if (pid === process.pid) {
+            if (trackedDirs.has(path))
+                continue;
+            if (stat.birthtimeMs >= processStartedAt)
+                continue;
+            try {
+                rmSync(path, { recursive: true, force: true });
+            }
+            catch {
+            }
+            continue;
+        }
+        if (isPidAlive(pid))
+            continue;
+        if (Date.now() - stat.mtimeMs < DEAD_PID_MIN_AGE_MS)
+            continue;
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
+}
+export function cleanupCheckpointDirs(dirs) {
+    for (const dir of dirs) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch {
+        }
+    }
+}
+const trackedDirs = new Set();
+let exitCleanupRegistered = false;
+function registerDirForExitCleanup(dir) {
+    trackedDirs.add(dir);
+    if (exitCleanupRegistered)
+        return;
+    exitCleanupRegistered = true;
+    process.once('exit', () => cleanupCheckpointDirs(trackedDirs));
+}
+export function isTrackedForExitCleanup(dir) {
+    return trackedDirs.has(dir);
+}
+async function ensureStoreDir(gimp, store) {
+    if (store.dir !== undefined)
+        return store.dir;
+    if (store.dirPromise !== undefined)
+        return store.dirPromise;
+    const attempt = (async () => {
+        await gimp.prepare();
+        const dir = gimp.tempPath(`checkpoints-${process.pid}-${randomUUID()}`);
+        try {
+            mkdirSync(dirname(dir), { recursive: true });
+            mkdirSync(dir);
+        }
+        catch {
+            throw new GimpError('gimp_op_failed', 'could not create the checkpoint storage directory.');
+        }
+        store.dir = dir;
+        registerDirForExitCleanup(dir);
+        return dir;
+    })();
+    store.dirPromise = attempt;
+    try {
+        return await attempt;
+    }
+    finally {
+        store.dirPromise = undefined;
+    }
+}
+export function maybeSweepSiblingDirs(store, dir) {
+    if (store.sweepDone)
+        return;
+    try {
+        sweepStaleCheckpointDirs(dirname(dir), dir, trackedDirs);
+        store.sweepDone = true;
+    }
+    catch {
+    }
+}
+async function checkpointCreate(gimp, args, store) {
+    const { registry } = store;
+    const image = args.image;
+    if (typeof image !== 'number') {
+        throw new GimpError('invalid_argument', '"image" is required for op=create.');
+    }
+    const dir = await ensureStoreDir(gimp, store);
+    maybeSweepSiblingDirs(store, dir);
+    await refreshOpenness(gimp, registry, { requireAlreadyRunning: false });
+    if (registry.size >= MAX_CHECKPOINTS_TOTAL) {
+        throw new GimpError('invalid_argument', `this checkpoint store already holds ${MAX_CHECKPOINTS_TOTAL} checkpoints, its overall ` +
+            `limit across every image (including ones whose image has since closed — they still hold ` +
+            `disk space until deleted). Delete one first — gimp_checkpoint op=delete — or list them ` +
+            `with op=list.`);
+    }
+    const existingOpen = [...registry.values()].filter((r) => r.image === image && r.open);
+    if (existingOpen.length >= MAX_CHECKPOINTS_PER_IMAGE) {
+        throw new GimpError('invalid_argument', `image ${image} already has ${MAX_CHECKPOINTS_PER_IMAGE} checkpoints, the maximum per image. ` +
+            `Delete one first — gimp_checkpoint op=delete, checkpoint_id one of: ` +
+            `${existingOpen.map((r) => r.id).join(', ')} — or list them with op=list.`);
+    }
+    const id = randomUUID();
+    const path = join(dir, `${id}.xcf`);
+    const createdAt = new Date().toISOString();
+    registry.set(id, {
+        id,
+        image,
+        path,
+        bytes: 0,
+        createdAt,
+        open: true,
+        pending: true,
+        generation: gimp.generation,
+    });
+    try {
+        const result = await gimp.call('export', { image, path });
+        const record = registry.get(id);
+        if (!record) {
+            throw new GimpError('gimp_op_failed', `checkpoint "${id}" vanished from the registry.`);
+        }
+        record.bytes = result.bytes;
+        record.pending = false;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Checkpoint "${id}" created from image ${image} (${result.bytes.toLocaleString()} bytes). ` +
+                        `Restore it later with gimp_checkpoint op=restore, checkpoint_id: "${id}".`,
+                },
+            ],
+            structuredContent: { checkpoint_id: id, image, bytes: result.bytes, created_at: createdAt },
+        };
+    }
+    catch (error) {
+        registry.delete(id);
+        try {
+            await rm(path, { force: true });
+        }
+        catch {
+        }
+        throw error;
+    }
+}
+async function checkpointList(gimp, args, store) {
+    const { registry } = store;
+    await refreshOpenness(gimp, registry, { requireAlreadyRunning: true });
+    const image = args.image;
+    const scoped = typeof image === 'number';
+    const filtered = [...registry.values()].filter((r) => {
+        if (!scoped)
+            return true;
+        return r.image === image && r.open;
+    });
+    const checkpoints = filtered.map((r) => ({
+        checkpoint_id: r.id,
+        image: r.image,
+        open: r.open,
+        pending: r.pending,
+        bytes: r.bytes,
+        created_at: r.createdAt,
+    }));
+    const goneCount = checkpoints.filter((c) => !c.open).length;
+    const scopedNote = scoped ? ` for image ${image}` : '';
+    const goneNote = goneCount > 0
+        ? ` (${goneCount} for an image that is now gone — still restorable by checkpoint_id)`
+        : '';
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${checkpoints.length} checkpoint(s)${scopedNote}.${goneNote}`,
+            },
+        ],
+        structuredContent: { checkpoints },
+    };
+}
+function requireKnownCheckpoint(args, op, registry) {
+    const checkpointId = args.checkpoint_id;
+    if (typeof checkpointId !== 'string' || checkpointId.length === 0) {
+        throw new GimpError('invalid_argument', `"checkpoint_id" is required for op=${op}.`);
+    }
+    const record = registry.get(checkpointId);
+    if (!record) {
+        const known = [...registry.keys()];
+        throw new GimpError('invalid_argument', `unknown checkpoint_id "${checkpointId}". ` +
+            (known.length > 0
+                ? `Known checkpoint ids: ${known.join(', ')}.`
+                : 'No checkpoints exist yet.'));
+    }
+    if (record.pending) {
+        throw new GimpError('invalid_argument', `checkpoint "${checkpointId}" is still being created — try again shortly.`);
+    }
+    return record;
+}
+async function checkpointDelete(args, store) {
+    const { registry } = store;
+    const record = requireKnownCheckpoint(args, 'delete', registry);
+    try {
+        await rm(record.path, { force: true });
+    }
+    catch {
+        throw new GimpError('gimp_op_failed', `could not delete checkpoint "${record.id}" — its file may still be open elsewhere.`);
+    }
+    registry.delete(record.id);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Deleted checkpoint "${record.id}" (was from image ${record.image}, ` +
+                    `${record.bytes.toLocaleString()} bytes).`,
+            },
+        ],
+        structuredContent: { checkpoint_id: record.id, deleted: true },
+    };
+}
+async function checkpointRestore(gimp, args, store) {
+    const { registry } = store;
+    const record = requireKnownCheckpoint(args, 'restore', registry);
+    let opened;
+    try {
+        opened = await gimp.call('open', {
+            path: record.path,
+        });
+    }
+    catch (openError) {
+        if (openError instanceof GimpError && openError.code === 'file_not_found') {
+            if (!existsSync(record.path)) {
+                registry.delete(record.id);
+                throw new GimpError('invalid_argument', `checkpoint "${record.id}"'s file is missing; it has been removed and can no longer be restored.`);
+            }
+            throw new GimpError('gimp_op_failed', `could not open checkpoint "${record.id}"'s file — retry gimp_checkpoint op=restore.`);
+        }
+        throw openError;
+    }
+    const oldImage = record.image;
+    const oldGeneration = record.generation;
+    const currentGeneration = gimp.generation;
+    const generationsKnown = oldGeneration !== undefined && currentGeneration !== undefined;
+    const generationChanged = generationsKnown && oldGeneration !== currentGeneration;
+    let closeNote;
+    let closeFailed = false;
+    if (oldImage === opened.image) {
+        closeNote = `image ${oldImage} is the id restore just reopened — nothing to close`;
+        if (generationChanged) {
+            markSiblingsGone(registry, oldImage, oldGeneration);
+        }
+    }
+    else if (generationChanged) {
+        closeNote =
+            `image ${oldImage} belonged to a GIMP process that has since restarted — left untouched ` +
+                `(its number may now belong to a different, unrelated image)`;
+        markSiblingsGone(registry, oldImage, oldGeneration);
+    }
+    else {
+        try {
+            await gimp.call('close', { image: oldImage });
+            closeNote = `image ${oldImage} closed`;
+            repointSiblings(registry, oldImage, opened.image, oldGeneration, currentGeneration);
+        }
+        catch (closeError) {
+            const generationAfterClose = gimp.generation;
+            if (currentGeneration !== undefined &&
+                generationAfterClose !== undefined &&
+                generationAfterClose !== currentGeneration) {
+                throw new GimpError('gimp_op_failed', `the GIMP process restarted while restoring checkpoint "${record.id}" — the checkpoint ` +
+                    'file itself is unaffected; retry gimp_checkpoint op=restore with the same checkpoint_id.');
+            }
+            if (isSessionRestartedError(closeError)) {
+                closeNote = `image ${oldImage} was already gone (the GIMP session had restarted)`;
+                markSiblingsGone(registry, oldImage, oldGeneration);
+            }
+            else if (isImageAlreadyClosedError(closeError)) {
+                closeNote = `image ${oldImage} was already closed`;
+                markSiblingsGone(registry, oldImage, oldGeneration);
+            }
+            else {
+                closeFailed = true;
+                const msg = closeError instanceof Error ? closeError.message : String(closeError);
+                closeNote = `image ${oldImage} could not be closed (${msg}) — it is still open`;
+            }
+        }
+    }
+    record.image = opened.image;
+    record.generation = currentGeneration;
+    record.open = true;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${closeNote}; restored as image ${opened.image} ` +
+                    `(${opened.width}x${opened.height}) — use ${opened.image} from now on.`,
+            },
+        ],
+        structuredContent: {
+            checkpoint_id: record.id,
+            old_image: oldImage,
+            image: opened.image,
+            width: opened.width,
+            height: opened.height,
+            base_type: opened.base_type,
+            precision: opened.precision,
+            layers: opened.layers,
+            close_failed: closeFailed,
+        },
+    };
+}
+async function gimpCheckpoint(gimp, rawArgs, store) {
+    try {
+        const args = validateArgs(checkpointSchema, rawArgs);
+        const op = args.op;
+        if (op !== 'create' && op !== 'restore' && op !== 'list' && op !== 'delete') {
+            return unknownDiscriminator('op', op, ['create', 'restore', 'list', 'delete']);
+        }
+        if (op === 'create')
+            return await checkpointCreate(gimp, args, store);
+        if (op === 'list')
+            return await checkpointList(gimp, args, store);
+        if (op === 'delete')
+            return await checkpointDelete(args, store);
+        return await checkpointRestore(gimp, args, store);
+    }
+    catch (error) {
+        return toolGimpErrorResult('Error managing GIMP checkpoint', error);
+    }
+}
+export function createGimpCheckpointTools(gimp) {
+    const store = {
+        registry: new Map(),
+        dir: undefined,
+        dirPromise: undefined,
+        sweepDone: false,
+    };
+    return [
+        {
+            tool: {
+                name: 'gimp_checkpoint',
+                description: 'Headless GIMP: disk-backed checkpoints — the substitute for undo in a session that has ' +
+                    "none. op=create exports the image's CURRENT state, every live filter included, to a " +
+                    'snapshot file and returns a checkpoint_id. op=restore reopens that snapshot as a NEW ' +
+                    'image and closes the old one — replace semantics, not a copy: the old image id stops ' +
+                    'working once the close succeeds (if it fails instead — reported as close_failed: true ' +
+                    '— the old image stays open, and both ids are valid). It returns the new image id and ' +
+                    'says so plainly, e.g. "image N closed; restored as image M — use M from now on". A ' +
+                    'checkpoint survives a GIMP crash or timeout: restore reopens the FILE, not anything the ' +
+                    'crashed process held, so it still works right after a gimp_session_restarted error — ' +
+                    "that is the whole point of keeping it on disk instead of in GIMP's own memory. Each " +
+                    `image holds at most ${MAX_CHECKPOINTS_PER_IMAGE} checkpoints; a checkpoint whose own ` +
+                    "image has since closed doesn't count against a different image that later reuses the " +
+                    'same number. A 6th op=create for the same still-open image REFUSES outright rather ' +
+                    'than silently evicting the oldest — delete one first (op=delete) or list them ' +
+                    `(op=list) to see what exists. This store also holds at most ${MAX_CHECKPOINTS_TOTAL} ` +
+                    'checkpoints in total, across every image, since each one still takes up disk space ' +
+                    'until deleted. Checkpoint files are kept while this server runs and removed when it ' +
+                    'exits; files left by a server that crashed or was killed are cleaned up by a later ' +
+                    'server, once they are more than an hour old, the next time a checkpoint is made. ' +
+                    'op=list reports checkpoint_id, the image it currently belongs to, created_at, and its ' +
+                    'size in bytes — never a file path (a full path carries the username) — plus open: ' +
+                    'false for a checkpoint whose image has since closed (still restorable; just excluded ' +
+                    "from that image's own scoped list and cap) and pending: true while a create is still " +
+                    "in flight. op=restore also returns the reopened image's base_type, precision, and " +
+                    'layers, the same as gimp_open_document. An unknown checkpoint_id on restore or delete ' +
+                    'is refused, naming every checkpoint_id that IS known.',
+                inputSchema: checkpointSchema,
+                outputSchema: {
+                    type: 'object',
+                    properties: {
+                        checkpoint_id: { type: 'string' },
+                        image: { type: 'number' },
+                        old_image: { type: 'number' },
+                        width: { type: 'number' },
+                        height: { type: 'number' },
+                        base_type: { type: 'string' },
+                        precision: { type: 'string' },
+                        layers: { type: 'array', items: { type: 'string' } },
+                        bytes: { type: 'number' },
+                        created_at: { type: 'string' },
+                        deleted: { type: 'boolean' },
+                        close_failed: { type: 'boolean' },
+                        checkpoints: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    checkpoint_id: { type: 'string' },
+                                    image: { type: 'number' },
+                                    open: { type: 'boolean' },
+                                    pending: { type: 'boolean' },
+                                    bytes: { type: 'number' },
+                                    created_at: { type: 'string' },
+                                },
+                            },
+                        },
+                    },
+                },
+                annotations: {
+                    title: 'Manage GIMP Checkpoints',
+                    readOnlyHint: false,
+                    destructiveHint: true,
+                    idempotentHint: false,
+                    openWorldHint: false,
+                },
+            },
+            handler: async (args) => gimpCheckpoint(gimp, args, store),
+        },
+    ];
+}