kitowall 2.2.0 → 2.4.0

package/dist/cli.js

@@ -131,7 +131,13 @@ Commands:
   we library                             List downloaded workshop items
   we scan-steam                          Detect Steam workshop folders and list downloaded ids
   we sync-steam                          Sync local Steam Workshop 431960 items into Kitsune downloads
-  we app-status                          Detect if Wallpaper Engine (AppID 431960) is installed
+  we app-status                          Detect if Wallpaper Engine and scene engine are installed
+  we active                              Show current livewallpaper authority/lock state
+  we apply <id> --monitor <name> [--backend auto|mpvpaper|linux-wallpaperengine]
+                                         Apply live wallpaper on one monitor (auto resolves by wallpaper type)
+  we apply --map DP-1:<id1>,HDMI-A-1:<id2> [--backend auto|mpvpaper|linux-wallpaperengine]
+                                         Apply wallpapers in batch by monitor map
+  we stop [--monitor <name> | --all]     Stop livewallpaper instances and restore previous services
   we coexist enter|exit|status           Temporarily stop/restore wallpaper rotation services
   check [--namespace <ns>] [--json]        Quick system check (no changes)
 
@@ -418,6 +424,37 @@ async function main() {
             console.log(JSON.stringify(out, null, 2));
             return;
         }
+        if (action === 'active') {
+            const out = (0, workshop_1.workshopActiveStatus)();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'apply') {
+            const mapValue = cleanOpt(getOptionValue(args, '--map'));
+            const backend = cleanOpt(getOptionValue(args, '--backend')) ?? 'auto';
+            if (mapValue) {
+                const out = await (0, workshop_1.workshopApplyMap)({ map: mapValue, backend });
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            const id = cleanOpt(args[2] ?? null);
+            const monitor = cleanOpt(getOptionValue(args, '--monitor'));
+            if (!id || !monitor) {
+                throw new Error('Usage: we apply <id> --monitor <name> [--backend auto|mpvpaper|linux-wallpaperengine] OR we apply --map DP-1:<id1>,HDMI-A-1:<id2>');
+            }
+            const out = await (0, workshop_1.workshopApply)({ id, monitor, backend });
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'stop') {
+            const monitor = cleanOpt(getOptionValue(args, '--monitor'));
+            const out = await (0, workshop_1.workshopStop)({
+                monitor,
+                all: args.includes('--all') || !monitor
+            });
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
         if (action === 'coexist') {
             const sub = cleanOpt(args[2] ?? null);
             if (sub === 'enter') {
@@ -437,7 +474,7 @@ async function main() {
             }
             throw new Error('Usage: we coexist <enter|exit|status>');
         }
-        throw new Error('Usage: we <config|search|details|download|job|jobs|library|scan-steam|sync-steam|app-status|run-job|coexist> ...');
+        throw new Error('Usage: we <config|search|details|download|job|jobs|library|scan-steam|sync-steam|app-status|active|apply|stop|run-job|coexist> ...');
     }
     // Regular commands (need config/state)
     const config = (0, config_1.loadConfig)();

package/dist/core/workshop.js

@@ -7,18 +7,24 @@ exports.setWorkshopApiKey = setWorkshopApiKey;
 exports.workshopGetSteamRoots = workshopGetSteamRoots;
 exports.workshopSetSteamRoots = workshopSetSteamRoots;
 exports.workshopWallpaperEngineStatus = workshopWallpaperEngineStatus;
+exports.workshopSceneEngineStatus = workshopSceneEngineStatus;
 exports.workshopScanSteamDownloads = workshopScanSteamDownloads;
 exports.workshopSyncSteamDownloads = workshopSyncSteamDownloads;
 exports.workshopSearch = workshopSearch;
 exports.workshopDetails = workshopDetails;
 exports.workshopQueueDownload = workshopQueueDownload;
+exports.workshopActiveStatus = workshopActiveStatus;
+exports.workshopSetActive = workshopSetActive;
 exports.workshopCoexistenceEnter = workshopCoexistenceEnter;
 exports.workshopCoexistenceExit = workshopCoexistenceExit;
 exports.workshopCoexistenceStatus = workshopCoexistenceStatus;
+exports.workshopStop = workshopStop;
 exports.workshopRunJob = workshopRunJob;
 exports.workshopGetJob = workshopGetJob;
 exports.workshopListJobs = workshopListJobs;
 exports.workshopLibrary = workshopLibrary;
+exports.workshopApply = workshopApply;
+exports.workshopApplyMap = workshopApplyMap;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -40,6 +46,32 @@ function clean(input) {
     const v = input.trim();
     return v.length > 0 ? v : undefined;
 }
+function isExecutable(filePath) {
+    try {
+        node_fs_1.default.accessSync(filePath, node_fs_1.default.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function resolveOnPath(binary) {
+    const bin = clean(binary);
+    if (!bin)
+        return undefined;
+    if (bin.includes('/')) {
+        const resolved = node_path_1.default.resolve(bin);
+        return node_fs_1.default.existsSync(resolved) && isExecutable(resolved) ? resolved : undefined;
+    }
+    const pathEnv = clean(process.env.PATH) ?? '';
+    const parts = pathEnv.split(':').filter(Boolean);
+    for (const p of parts) {
+        const candidate = node_path_1.default.join(p, bin);
+        if (node_fs_1.default.existsSync(candidate) && isExecutable(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 function getWePaths() {
     const root = node_path_1.default.join(node_os_1.default.homedir(), '.local', 'share', 'kitsune', 'we');
     return {
@@ -64,6 +96,7 @@ function ensureWePaths(paths) {
     (0, fs_1.ensureDir)(paths.runtime);
     (0, fs_1.ensureDir)(node_path_1.default.join(paths.cache, 'search'));
     (0, fs_1.ensureDir)(node_path_1.default.join(paths.steamcmd, 'logs'));
+    (0, fs_1.ensureDir)(node_path_1.default.join(paths.root, 'coexistence', 'snapshots'));
 }
 function getWeConfigPath() {
     return node_path_1.default.join(node_os_1.default.homedir(), '.config', 'kitowall', 'we.json');
@@ -351,6 +384,67 @@ function writeMetaFile(meta) {
         cached_at: now()
     });
 }
+function normalizeWallpaperType(raw) {
+    const t = clean(raw)?.toLowerCase();
+    if (!t)
+        return 'unknown';
+    if (t === 'video')
+        return 'video';
+    if (t === 'scene')
+        return 'scene';
+    if (t === 'web')
+        return 'web';
+    if (t === 'application')
+        return 'application';
+    return 'unknown';
+}
+function detectAudioReactiveFromText(text) {
+    return /(audio|spectrum|visualizer|now[\s_-]?playing|media[\s_-]?integration|fft|bass|reactive)/i.test(text);
+}
+function readProjectInfo(dir) {
+    const projectPath = node_path_1.default.join(dir, 'project.json');
+    if (!node_fs_1.default.existsSync(projectPath)) {
+        return { type: 'unknown', audioReactive: false, entry: undefined };
+    }
+    try {
+        const raw = node_fs_1.default.readFileSync(projectPath, 'utf8');
+        const json = JSON.parse(raw);
+        const type = normalizeWallpaperType(json.type);
+        const title = clean(json.title) ?? '';
+        const fileEntry = clean(json.file);
+        const entry = fileEntry ? node_path_1.default.join(dir, fileEntry) : undefined;
+        const audioReactive = detectAudioReactiveFromText(`${title}\n${raw}`);
+        return { type, audioReactive, entry };
+    }
+    catch {
+        return { type: 'unknown', audioReactive: false, entry: undefined };
+    }
+}
+function inferVideoEntry(dir) {
+    if (!node_fs_1.default.existsSync(dir))
+        return undefined;
+    const files = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    const preferred = ['.mp4', '.webm', '.gif', '.mkv', '.avi', '.mov'];
+    for (const ext of preferred) {
+        const match = files.find((entry) => entry.isFile() && entry.name.toLowerCase().endsWith(ext));
+        if (match)
+            return node_path_1.default.join(dir, match.name);
+    }
+    return undefined;
+}
+function detectTypeFromEntry(entry) {
+    const e = clean(entry)?.toLowerCase();
+    if (!e)
+        return 'unknown';
+    if (e.endsWith('.mp4') || e.endsWith('.webm') || e.endsWith('.gif') || e.endsWith('.mkv') || e.endsWith('.avi') || e.endsWith('.mov')) {
+        return 'video';
+    }
+    if (e.endsWith('index.html') || e.endsWith('.html'))
+        return 'web';
+    if (e.endsWith('scene.json') || e.endsWith('gifscene.json'))
+        return 'scene';
+    return 'unknown';
+}
 function readLibraryFoldersVdf(vdfPath) {
     if (!node_fs_1.default.existsSync(vdfPath))
         return [];
@@ -465,13 +559,37 @@ function workshopWallpaperEngineStatus() {
         if (node_fs_1.default.existsSync(manifest))
             manifests.push(manifest);
     }
+    const engine = workshopSceneEngineStatus();
     return {
         ok: true,
         installed: manifests.length > 0,
         manifests,
-        steamapps
+        steamapps,
+        engine
     };
 }
+function workshopSceneEngineStatus() {
+    const configured = clean(process.env.KITOWALL_SCENE_ENGINE_CMD);
+    const candidates = configured
+        ? [configured]
+        : ['linux-wallpaperengine', 'linux-wallpaperengine-cli', 'wallpaper-engine'];
+    for (const cmd of candidates) {
+        const resolved = resolveOnPath(cmd);
+        if (!resolved)
+            continue;
+        const verOut = (0, node_child_process_1.spawnSync)(resolved, ['--version'], { encoding: 'utf8', timeout: 2500 });
+        const stdout = clean(verOut.stdout) ?? '';
+        const stderr = clean(verOut.stderr) ?? '';
+        const version = (stdout.split('\n')[0] || stderr.split('\n')[0] || '').trim();
+        return {
+            installed: true,
+            path: resolved,
+            version: version || undefined,
+            command: cmd
+        };
+    }
+    return { installed: false, command: configured ?? 'linux-wallpaperengine' };
+}
 function findPreviewCandidate(dir) {
     if (!node_fs_1.default.existsSync(dir))
         return undefined;
@@ -543,6 +661,7 @@ function workshopSyncSteamDownloads() {
                 imported += 1;
             }
             const metadataFile = node_path_1.default.join(paths.metadata, `${id}.json`);
+            const info = readProjectInfo(sourceDir);
             if (!node_fs_1.default.existsSync(metadataFile)) {
                 const previewCandidate = findPreviewCandidate(sourceDir);
                 let thumbLocal;
@@ -561,9 +680,28 @@ function workshopSyncSteamDownloads() {
                     tags: [],
                     preview_thumb_local: thumbLocal,
                     author_name: 'Steam Workshop',
-                    time_updated: Math.floor(Date.now() / 1000)
+                    time_updated: Math.floor(Date.now() / 1000),
+                    wallpaper_type: info.type,
+                    audio_reactive: info.audioReactive,
+                    entry: info.entry
                 });
             }
+            else {
+                try {
+                    const current = JSON.parse(node_fs_1.default.readFileSync(metadataFile, 'utf8'));
+                    if (!current.wallpaper_type || current.wallpaper_type === 'unknown' || current.audio_reactive === undefined || !current.entry) {
+                        writeMetaFile({
+                            ...current,
+                            wallpaper_type: current.wallpaper_type ?? info.type,
+                            audio_reactive: current.audio_reactive ?? info.audioReactive,
+                            entry: current.entry ?? info.entry
+                        });
+                    }
+                }
+                catch {
+                    // ignore malformed metadata
+                }
+            }
         }
     }
     return {
@@ -813,6 +951,78 @@ async function copyDownloadedContent(job) {
 function snapshotFile(paths) {
     return node_path_1.default.join(paths.runtime, 'coexistence.snapshot.json');
 }
+function snapshotDir(paths) {
+    return node_path_1.default.join(paths.root, 'coexistence', 'snapshots');
+}
+function activeLockFile(paths) {
+    return node_path_1.default.join(paths.runtime, 'active.lock');
+}
+function activeStateFile(paths) {
+    return node_path_1.default.join(paths.runtime, 'active.json');
+}
+function readActiveState() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const p = activeStateFile(paths);
+    if (!node_fs_1.default.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeActiveState(state) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    (0, fs_1.writeJson)(activeStateFile(paths), state);
+    node_fs_1.default.writeFileSync(activeLockFile(paths), `${state.mode}:${state.started_at}\n`, 'utf8');
+}
+function clearActiveState() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    try {
+        node_fs_1.default.unlinkSync(activeStateFile(paths));
+    }
+    catch {
+        // ignore
+    }
+    try {
+        node_fs_1.default.unlinkSync(activeLockFile(paths));
+    }
+    catch {
+        // ignore
+    }
+}
+function killPid(pid) {
+    if (!pid || !Number.isFinite(pid) || pid <= 1)
+        return false;
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function workshopActiveStatus() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const state = readActiveState();
+    const lock = node_fs_1.default.existsSync(activeLockFile(paths));
+    return {
+        ok: true,
+        active: lock && !!state,
+        lock_path: activeLockFile(paths),
+        state_path: activeStateFile(paths),
+        state: state ?? undefined
+    };
+}
+function workshopSetActive(state) {
+    writeActiveState(state);
+    return { ok: true, active: true, state };
+}
 async function isUnitActive(unit) {
     try {
         const out = await (0, exec_1.run)('systemctl', ['--user', 'show', unit, '--property', 'ActiveState', '--value']);
@@ -839,8 +1049,11 @@ async function workshopCoexistenceEnter() {
             // best effort
         }
     }
-    (0, fs_1.writeJson)(snapshotFile(paths), { ts: now(), active });
-    return { ok: true, stopped: active, snapshot: active };
+    const snapshotId = String(now());
+    const snap = { id: snapshotId, ts: now(), active };
+    (0, fs_1.writeJson)(node_path_1.default.join(snapshotDir(paths), `${snapshotId}.json`), snap);
+    (0, fs_1.writeJson)(snapshotFile(paths), { id: snapshotId, ts: snap.ts });
+    return { ok: true, stopped: active, snapshot: active, snapshot_id: snapshotId };
 }
 async function workshopCoexistenceExit() {
     const paths = getWePaths();
@@ -849,7 +1062,19 @@ async function workshopCoexistenceExit() {
     if (!node_fs_1.default.existsSync(snapPath))
         return { ok: true, restored: [] };
     const raw = JSON.parse(node_fs_1.default.readFileSync(snapPath, 'utf8'));
-    const active = Array.isArray(raw.active) ? raw.active.map(v => String(v)) : [];
+    let active = Array.isArray(raw.active) ? raw.active.map(v => String(v)) : [];
+    if ((!active || active.length === 0) && raw.id) {
+        const historical = node_path_1.default.join(snapshotDir(paths), `${raw.id}.json`);
+        if (node_fs_1.default.existsSync(historical)) {
+            try {
+                const snap = JSON.parse(node_fs_1.default.readFileSync(historical, 'utf8'));
+                active = Array.isArray(snap.active) ? snap.active.map(v => String(v)) : [];
+            }
+            catch {
+                active = [];
+            }
+        }
+    }
     const restored = [];
     for (const unit of active) {
         try {
@@ -882,6 +1107,46 @@ async function workshopCoexistenceStatus() {
     }
     return { ok: true, snapshot, current };
 }
+async function workshopStop(options) {
+    let state = readActiveState();
+    const hadActive = !!state;
+    const stopped = [];
+    let shouldRestore = false;
+    if (state?.instances) {
+        if (options?.monitor) {
+            const inst = state.instances[options.monitor];
+            if (killPid(inst?.pid))
+                stopped.push(options.monitor);
+            delete state.instances[options.monitor];
+            if (Object.keys(state.instances).length > 0 && !options?.all) {
+                writeActiveState(state);
+            }
+            else {
+                clearActiveState();
+                shouldRestore = true;
+            }
+        }
+        else {
+            for (const [monitor, inst] of Object.entries(state.instances)) {
+                if (killPid(inst?.pid))
+                    stopped.push(monitor);
+            }
+            clearActiveState();
+            shouldRestore = true;
+        }
+    }
+    else if (options?.all) {
+        clearActiveState();
+        shouldRestore = true;
+    }
+    const coexist = shouldRestore ? await workshopCoexistenceExit() : { ok: true, restored: [] };
+    return {
+        ok: true,
+        stopped_instances: stopped,
+        restored_units: coexist.restored,
+        had_active: hadActive
+    };
+}
 async function workshopRunJob(jobId) {
     const job = readJob(jobId);
     if (!job)
@@ -980,6 +1245,16 @@ function workshopLibrary() {
                 meta = undefined;
             }
         }
+        const info = readProjectInfo(p);
+        if (meta) {
+            meta.wallpaper_type = meta.wallpaper_type ?? info.type;
+            if (meta.audio_reactive === undefined) {
+                meta.audio_reactive = info.audioReactive;
+            }
+            if (!meta.entry) {
+                meta.entry = info.entry;
+            }
+        }
         items.push({
             id,
             path: p,
@@ -990,3 +1265,152 @@ function workshopLibrary() {
     items.sort((a, b) => a.id.localeCompare(b.id));
     return { root: paths.downloads, items };
 }
+function spawnMpvpaper(monitor, entry) {
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)('mpvpaper', ['-o', 'no-audio --loop-file=inf', monitor, entry], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env
+        });
+        let settled = false;
+        const done = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        child.once('error', (err) => done(() => reject(err)));
+        setTimeout(() => {
+            done(() => {
+                child.unref();
+                resolve(child.pid ?? 0);
+            });
+        }, 180);
+    });
+}
+function spawnSceneEngine(monitor, wallpaperDir) {
+    const engine = workshopSceneEngineStatus();
+    if (!engine.installed || !engine.path) {
+        throw new Error('Scene engine not installed. Install linux-wallpaperengine first.');
+    }
+    const enginePath = engine.path;
+    return new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)(enginePath, ['--screen-root', monitor, '--bg', wallpaperDir], {
+            detached: true,
+            stdio: 'ignore',
+            env: process.env
+        });
+        let settled = false;
+        const done = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            fn();
+        };
+        child.once('error', (err) => done(() => reject(err)));
+        setTimeout(() => {
+            done(() => {
+                child.unref();
+                resolve(child.pid ?? 0);
+            });
+        }, 220);
+    });
+}
+async function workshopApply(input) {
+    const id = clean(input.id);
+    const monitor = clean(input.monitor);
+    const requestedBackend = clean(input.backend) ?? 'auto';
+    if (!id)
+        throw new Error('id is required');
+    if (!monitor)
+        throw new Error('monitor is required');
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const dir = node_path_1.default.join(paths.downloads, id);
+    if (!node_fs_1.default.existsSync(dir)) {
+        throw new Error(`Wallpaper not found in downloads: ${id}`);
+    }
+    const project = readProjectInfo(dir);
+    const inferredEntry = project.entry && node_fs_1.default.existsSync(project.entry) ? project.entry : inferVideoEntry(dir);
+    const type = project.type !== 'unknown'
+        ? project.type
+        : detectTypeFromEntry(inferredEntry ?? node_path_1.default.join(dir, 'scene.json'));
+    if (type === 'web' || type === 'application' || type === 'unknown') {
+        throw new Error(`Unsupported wallpaper type for apply: ${type}. Supported: video, scene.`);
+    }
+    let state = readActiveState();
+    if (!state) {
+        const coexist = await workshopCoexistenceEnter();
+        state = {
+            mode: 'livewallpaper',
+            started_at: now(),
+            snapshot_id: coexist.snapshot_id,
+            instances: {}
+        };
+    }
+    const current = state.instances[monitor];
+    if (current?.pid) {
+        killPid(current.pid);
+    }
+    let backend;
+    let pid = 0;
+    if (type === 'video') {
+        if (!(requestedBackend === 'auto' || requestedBackend === 'mpvpaper')) {
+            throw new Error(`Invalid backend for video wallpaper: ${requestedBackend}`);
+        }
+        if (!inferredEntry || !node_fs_1.default.existsSync(inferredEntry)) {
+            throw new Error(`Video entry not found for wallpaper: ${id}`);
+        }
+        backend = 'mpvpaper';
+        pid = await spawnMpvpaper(monitor, inferredEntry).catch((err) => {
+            throw new Error(`Failed to launch mpvpaper: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    else if (type === 'scene') {
+        if (!(requestedBackend === 'auto' || requestedBackend === 'linux-wallpaperengine')) {
+            throw new Error(`Invalid backend for scene wallpaper: ${requestedBackend}`);
+        }
+        backend = 'linux-wallpaperengine';
+        pid = await spawnSceneEngine(monitor, dir).catch((err) => {
+            throw new Error(`Failed to launch scene engine: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    }
+    else {
+        throw new Error(`Unsupported wallpaper type for apply: ${type}`);
+    }
+    if (!pid) {
+        throw new Error(`${backend} started without pid`);
+    }
+    state.instances[monitor] = {
+        id,
+        pid,
+        backend,
+        type
+    };
+    writeActiveState(state);
+    return { ok: true, applied: true, monitor, id, backend, pid, state };
+}
+async function workshopApplyMap(input) {
+    const raw = clean(input.map);
+    if (!raw)
+        throw new Error('map is required');
+    const entries = raw.split(',').map(v => v.trim()).filter(Boolean);
+    if (entries.length === 0)
+        throw new Error('map has no entries');
+    const applied = [];
+    for (const pair of entries) {
+        const idx = pair.indexOf(':');
+        if (idx <= 0 || idx === pair.length - 1) {
+            throw new Error(`Invalid map entry: ${pair}. Expected <monitor>:<id>`);
+        }
+        const monitor = pair.slice(0, idx).trim();
+        const id = pair.slice(idx + 1).trim();
+        if (!monitor || !id) {
+            throw new Error(`Invalid map entry: ${pair}. Expected <monitor>:<id>`);
+        }
+        const out = await workshopApply({ id, monitor, backend: input.backend });
+        applied.push({ monitor: out.monitor, id: out.id, backend: out.backend, pid: out.pid });
+    }
+    const state = readActiveState() ?? undefined;
+    return { ok: true, applied, state };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kitowall",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "CLI/daemon for Hyprland wallpapers using swww with pack-based rotation.",
   "license": "SEE LICENSE IN LICENSE.md",
   "type": "commonjs",