kitowall 1.0.7 → 2.0.0

package/README.md

@@ -4,7 +4,7 @@
 
 `Kitowall` is a wallpaper manager for Hyprland/Wayland using `swww`.
 
-Current version: `1.0.6`.
+Current version: `1.0.7`.
 
 ## What You Can Do
 - Rotate wallpapers with transitions.

package/dist/cli.js

@@ -55,6 +55,7 @@ const staticUrl_1 = require("./adapters/staticUrl");
 const logs_1 = require("./core/logs");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const workshop_1 = require("./core/workshop");
 function getCliVersion() {
     try {
         const pkgPath = (0, node_path_1.join)(__dirname, '..', 'package.json');
@@ -116,6 +117,17 @@ Commands:
   logs [--limit <n>] [--source <name>] [--pack <name>] [--level <info|warn|error>] [--q <text>]
                                          Show system logs (requests/downloads/errors)
   logs clear                             Clear system logs
+  we config set-api-key <key>            Save Steam Web API key (~/.config/kitowall/we.json)
+  we search [--text <q>] [--tags <a,b>] [--sort <top|newest|trend|subscribed|updated>] [--page <n>] [--page-size <n>] [--days <n>] [--fixtures]
+                                         Search Wallpaper Engine workshop items (appid 431960)
+  we details <publishedfileid> [--fixtures]
+                                         Fetch workshop item details and additional previews
+  we download <publishedfileid> [--target-dir <path>] [--steam-user <user>] [--steam-pass-env <ENV>] [--steam-guard <code>] [--coexist]
+                                         Queue steamcmd download job (async)
+  we job <job_id>                        Show one download job
+  we jobs [--limit <n>]                  List recent download jobs
+  we library                             List downloaded workshop items
+  we coexist enter|exit|status           Temporarily stop/restore wallpaper rotation services
   check [--namespace <ns>] [--json]        Quick system check (no changes)
 
   init [--namespace <ns>] [--apply] [--force]       Setup kitowall (install daemon + watcher + next.service), validate deps
@@ -284,6 +296,117 @@ async function main() {
         process.exitCode = report.ok ? 0 : 2;
         return;
     }
+    if (cmd === 'we') {
+        const action = cleanOpt(args[1] ?? null);
+        if (!action) {
+            throw new Error('Usage: we <config|search|details|download|job|jobs|library|run-job|coexist> ...');
+        }
+        if (action === 'config') {
+            const sub = cleanOpt(args[2] ?? null);
+            if (sub !== 'set-api-key')
+                throw new Error('Usage: we config set-api-key <key>');
+            const key = cleanOpt(args[3] ?? null);
+            if (!key)
+                throw new Error('Usage: we config set-api-key <key>');
+            (0, workshop_1.setWorkshopApiKey)(key);
+            console.log(JSON.stringify({ ok: true, updated: 'steamWebApiKey' }, null, 2));
+            return;
+        }
+        if (action === 'search') {
+            const text = cleanOpt(getOptionValue(args, '--text'));
+            const tags = parseList(getOptionValue(args, '--tags'));
+            const sort = cleanOpt(getOptionValue(args, '--sort'));
+            const pageRaw = cleanOpt(getOptionValue(args, '--page'));
+            const pageSizeRaw = cleanOpt(getOptionValue(args, '--page-size'));
+            const daysRaw = cleanOpt(getOptionValue(args, '--days'));
+            const fixtures = args.includes('--fixtures');
+            const out = await (0, workshop_1.workshopSearch)({
+                text,
+                tags,
+                sort,
+                page: pageRaw ? Number(pageRaw) : undefined,
+                pageSize: pageSizeRaw ? Number(pageSizeRaw) : undefined,
+                days: daysRaw ? Number(daysRaw) : undefined,
+                fixtures
+            });
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'details') {
+            const id = cleanOpt(args[2] ?? null);
+            if (!id)
+                throw new Error('Usage: we details <publishedfileid> [--fixtures]');
+            const fixtures = args.includes('--fixtures');
+            const out = await (0, workshop_1.workshopDetails)(id, fixtures);
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'download') {
+            const id = cleanOpt(args[2] ?? null);
+            if (!id)
+                throw new Error('Usage: we download <publishedfileid> [--target-dir <path>] [--steam-user <user>] [--steam-pass-env <ENV>] [--steam-guard <code>] [--coexist]');
+            const out = (0, workshop_1.workshopQueueDownload)({
+                publishedfileid: id,
+                targetDir: cleanOpt(getOptionValue(args, '--target-dir')),
+                steamUser: cleanOpt(getOptionValue(args, '--steam-user')),
+                steamPasswordEnv: cleanOpt(getOptionValue(args, '--steam-pass-env')),
+                steamGuardCode: cleanOpt(getOptionValue(args, '--steam-guard')),
+                useCoexistence: args.includes('--coexist')
+            });
+            console.log(JSON.stringify({ ok: true, ...out }, null, 2));
+            return;
+        }
+        if (action === 'run-job') {
+            const jobId = cleanOpt(args[2] ?? null);
+            if (!jobId)
+                throw new Error('Usage: we run-job <job_id>');
+            const out = await (0, workshop_1.workshopRunJob)(jobId);
+            console.log(JSON.stringify({ ok: true, job: out }, null, 2));
+            return;
+        }
+        if (action === 'job') {
+            const jobId = cleanOpt(args[2] ?? null);
+            if (!jobId)
+                throw new Error('Usage: we job <job_id>');
+            const out = (0, workshop_1.workshopGetJob)(jobId);
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'jobs') {
+            const limitRaw = cleanOpt(getOptionValue(args, '--limit'));
+            const limit = limitRaw ? Number(limitRaw) : 40;
+            if (!Number.isFinite(limit) || limit <= 0)
+                throw new Error(`Invalid --limit value: ${limitRaw}`);
+            const out = (0, workshop_1.workshopListJobs)(Math.floor(limit));
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'library') {
+            const out = (0, workshop_1.workshopLibrary)();
+            console.log(JSON.stringify(out, null, 2));
+            return;
+        }
+        if (action === 'coexist') {
+            const sub = cleanOpt(args[2] ?? null);
+            if (sub === 'enter') {
+                const out = await (0, workshop_1.workshopCoexistenceEnter)();
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            if (sub === 'exit') {
+                const out = await (0, workshop_1.workshopCoexistenceExit)();
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            if (sub === 'status') {
+                const out = await (0, workshop_1.workshopCoexistenceStatus)();
+                console.log(JSON.stringify(out, null, 2));
+                return;
+            }
+            throw new Error('Usage: we coexist <enter|exit|status>');
+        }
+        throw new Error('Usage: we <config|search|details|download|job|jobs|library|run-job|coexist> ...');
+    }
     // Regular commands (need config/state)
     const config = (0, config_1.loadConfig)();
     const state = (0, state_1.loadState)();

package/dist/core/workshop.js

@@ -0,0 +1,740 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setWorkshopApiKey = setWorkshopApiKey;
+exports.workshopSearch = workshopSearch;
+exports.workshopDetails = workshopDetails;
+exports.workshopQueueDownload = workshopQueueDownload;
+exports.workshopCoexistenceEnter = workshopCoexistenceEnter;
+exports.workshopCoexistenceExit = workshopCoexistenceExit;
+exports.workshopCoexistenceStatus = workshopCoexistenceStatus;
+exports.workshopRunJob = workshopRunJob;
+exports.workshopGetJob = workshopGetJob;
+exports.workshopListJobs = workshopListJobs;
+exports.workshopLibrary = workshopLibrary;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const hash_1 = require("../utils/hash");
+const fs_1 = require("../utils/fs");
+const net_1 = require("../utils/net");
+const logs_1 = require("./logs");
+const exec_1 = require("../utils/exec");
+const WE_APP_ID = 431960;
+const SEARCH_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_PAGE_SIZE = 24;
+function now() {
+    return Date.now();
+}
+function clean(input) {
+    if (input == null)
+        return undefined;
+    const v = input.trim();
+    return v.length > 0 ? v : undefined;
+}
+function getWePaths() {
+    const root = node_path_1.default.join(node_os_1.default.homedir(), '.local', 'share', 'kitsune', 'we');
+    return {
+        root,
+        steamcmd: node_path_1.default.join(root, 'steamcmd'),
+        downloads: node_path_1.default.join(root, 'downloads'),
+        previews: node_path_1.default.join(root, 'previews'),
+        metadata: node_path_1.default.join(root, 'metadata'),
+        cache: node_path_1.default.join(root, 'cache'),
+        jobs: node_path_1.default.join(root, 'jobs'),
+        runtime: node_path_1.default.join(root, 'runtime')
+    };
+}
+function ensureWePaths(paths) {
+    (0, fs_1.ensureDir)(paths.root);
+    (0, fs_1.ensureDir)(paths.steamcmd);
+    (0, fs_1.ensureDir)(paths.downloads);
+    (0, fs_1.ensureDir)(paths.previews);
+    (0, fs_1.ensureDir)(paths.metadata);
+    (0, fs_1.ensureDir)(paths.cache);
+    (0, fs_1.ensureDir)(paths.jobs);
+    (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'));
+}
+function getWeConfigPath() {
+    return node_path_1.default.join(node_os_1.default.homedir(), '.config', 'kitowall', 'we.json');
+}
+function readWeConfig() {
+    const p = getWeConfigPath();
+    if (!node_fs_1.default.existsSync(p))
+        return {};
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function setWorkshopApiKey(apiKey) {
+    const key = clean(apiKey);
+    if (!key)
+        throw new Error('steam_web_api_key is required');
+    const p = getWeConfigPath();
+    const current = readWeConfig();
+    current.steamWebApiKey = key;
+    (0, fs_1.writeJson)(p, current);
+    return { ok: true };
+}
+function getSteamWebApiKey() {
+    const envKey = clean(process.env.STEAM_WEB_API_KEY) ?? clean(process.env.KITOWALL_STEAM_WEB_API_KEY);
+    if (envKey)
+        return envKey;
+    const cfg = readWeConfig();
+    return clean(cfg.steamWebApiKey);
+}
+function getCoexistServices() {
+    const cfg = readWeConfig();
+    const defaults = [
+        'swww-daemon.service',
+        'hyprwall-watch.service',
+        'hyprwall-next.timer',
+        'kitowall-next.timer'
+    ];
+    const configured = Array.isArray(cfg.coexistServices) ? cfg.coexistServices.map(v => String(v).trim()).filter(Boolean) : [];
+    return configured.length > 0 ? configured : defaults;
+}
+function getSearchCacheFile(query, paths) {
+    const key = (0, hash_1.sha256Hex)(JSON.stringify(query));
+    return node_path_1.default.join(paths.cache, 'search', `${key}.json`);
+}
+function parseTags(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const tag of raw) {
+        if (typeof tag === 'string') {
+            const t = clean(tag);
+            if (t)
+                out.push(t);
+            continue;
+        }
+        const t = clean(tag?.tag);
+        if (t)
+            out.push(t);
+    }
+    return out;
+}
+function getPreviewUrl(item) {
+    return clean(item.preview_url) ?? clean(item.previewurl);
+}
+function isMotionUrl(url) {
+    const v = clean(url);
+    if (!v)
+        return false;
+    const lower = v.toLowerCase();
+    return (lower.includes('.mp4') ||
+        lower.includes('.webm') ||
+        lower.includes('.mov') ||
+        lower.includes('.mkv') ||
+        lower.includes('.gif'));
+}
+function pickMotionPreview(item) {
+    if (Array.isArray(item.additional_previews)) {
+        for (const p of item.additional_previews) {
+            const candidate = typeof p === 'string' ? clean(p) : (clean(p.preview_url) ?? clean(p.url));
+            if (isMotionUrl(candidate))
+                return candidate;
+        }
+    }
+    if (Array.isArray(item.previews)) {
+        for (const p of item.previews) {
+            const candidate = clean(p.url) ?? clean(p.preview_url) ?? clean(p.filename);
+            if (isMotionUrl(candidate))
+                return candidate;
+            if (clean(p.preview_type)?.toLowerCase() === 'video' && candidate)
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function normalizeMeta(item, paths) {
+    const id = clean(item.publishedfileid) ?? '';
+    const thumbDir = node_path_1.default.join(paths.previews, id);
+    const thumbJpg = node_path_1.default.join(thumbDir, 'thumb.jpg');
+    const thumbPng = node_path_1.default.join(thumbDir, 'thumb.png');
+    const thumbWebp = node_path_1.default.join(thumbDir, 'thumb.webp');
+    let previewThumbLocal;
+    if (node_fs_1.default.existsSync(thumbJpg))
+        previewThumbLocal = thumbJpg;
+    else if (node_fs_1.default.existsSync(thumbPng))
+        previewThumbLocal = thumbPng;
+    else if (node_fs_1.default.existsSync(thumbWebp))
+        previewThumbLocal = thumbWebp;
+    const score = typeof item.score === 'number'
+        ? item.score
+        : (typeof item.vote_data?.score === 'number' ? item.vote_data.score : undefined);
+    return {
+        id,
+        title: clean(item.title) ?? `Workshop ${id}`,
+        preview_url_remote: getPreviewUrl(item),
+        preview_motion_remote: pickMotionPreview(item),
+        preview_thumb_local: previewThumbLocal,
+        author_name: clean(item.creator),
+        tags: parseTags(item.tags),
+        score,
+        time_updated: typeof item.time_updated === 'number' ? item.time_updated : undefined
+    };
+}
+function resolveSortToQueryType(sort, hasText) {
+    if (hasText)
+        return 12;
+    if (sort === 'top')
+        return 0;
+    if (sort === 'newest')
+        return 1;
+    if (sort === 'trend')
+        return 3;
+    if (sort === 'subscribed')
+        return 9;
+    if (sort === 'updated')
+        return 21;
+    return 0;
+}
+function getFixturesDir() {
+    const fromEnv = clean(process.env.KITOWALL_WE_FIXTURES_DIR);
+    if (fromEnv)
+        return fromEnv;
+    return node_path_1.default.join(process.cwd(), 'fixtures', 'we');
+}
+function readFixtureJson(name) {
+    const file = node_path_1.default.join(getFixturesDir(), name);
+    if (!node_fs_1.default.existsSync(file))
+        throw new Error(`Fixture not found: ${file}`);
+    return JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+}
+async function callSteamService(method, payload, fixtures) {
+    if (fixtures || process.env.KITOWALL_WE_USE_FIXTURES === '1') {
+        return method === 'QueryFiles'
+            ? readFixtureJson('query-files.json')
+            : readFixtureJson('get-details.json');
+    }
+    const key = getSteamWebApiKey();
+    if (!key) {
+        throw new Error('Missing Steam Web API key. Set STEAM_WEB_API_KEY or run: kitowall we config set-api-key <key>');
+    }
+    const endpoint = `https://api.steampowered.com/IPublishedFileService/${method}/v1/?key=${encodeURIComponent(key)}`;
+    const body = new URLSearchParams({
+        input_json: JSON.stringify(payload)
+    });
+    (0, logs_1.appendSystemLog)({
+        level: 'info',
+        source: 'workshop',
+        action: `steam-api:${method.toLowerCase()}`,
+        url: endpoint
+    });
+    const response = await (0, net_1.fetchWithRetry)(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/x-www-form-urlencoded' },
+        body: body.toString()
+    }, { timeoutMs: 20000, retries: 2, backoffMs: 350 });
+    const json = await response.json();
+    return json;
+}
+function extractItemsFromQuery(response) {
+    const root = response;
+    const fromA = root.response?.publishedfiledetails;
+    if (Array.isArray(fromA))
+        return fromA;
+    const fromB = root.response?.publishedfile_details;
+    if (Array.isArray(fromB))
+        return fromB;
+    return [];
+}
+function extractSingleFromDetails(response) {
+    const items = extractItemsFromQuery(response);
+    if (items.length > 0)
+        return items[0];
+    const root = response;
+    const details = root.response?.publishedfiledetails;
+    if (Array.isArray(details) && details.length > 0)
+        return details[0];
+    return null;
+}
+function toShortDescription(item) {
+    return clean(item.short_description) ?? clean(item.file_description);
+}
+function maybeAdditionalPreviews(item) {
+    if (!Array.isArray(item.additional_previews))
+        return [];
+    const out = [];
+    for (const p of item.additional_previews) {
+        if (typeof p === 'string') {
+            const v = clean(p);
+            if (v)
+                out.push(v);
+            continue;
+        }
+        const v = clean(p.preview_url) ?? clean(p.url);
+        if (v)
+            out.push(v);
+    }
+    return out;
+}
+function extFromUrl(url) {
+    try {
+        const u = new URL(url);
+        const ext = node_path_1.default.extname(u.pathname).toLowerCase();
+        if (ext === '.jpg' || ext === '.jpeg' || ext === '.png' || ext === '.webp')
+            return ext;
+        return '.jpg';
+    }
+    catch {
+        return '.jpg';
+    }
+}
+async function cachePreviewImage(id, imageUrl, customName) {
+    if (!imageUrl)
+        return undefined;
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const targetDir = node_path_1.default.join(paths.previews, id);
+    (0, fs_1.ensureDir)(targetDir);
+    const ext = extFromUrl(imageUrl);
+    const fileName = customName ?? `thumb${ext}`;
+    const target = node_path_1.default.join(targetDir, fileName);
+    if (node_fs_1.default.existsSync(target))
+        return target;
+    try {
+        const response = await (0, net_1.fetchWithRetry)(imageUrl, undefined, { timeoutMs: 15000, retries: 1 });
+        const bytes = Buffer.from(await response.arrayBuffer());
+        node_fs_1.default.writeFileSync(target, bytes);
+        return target;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writeMetaFile(meta) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const p = node_path_1.default.join(paths.metadata, `${meta.id}.json`);
+    (0, fs_1.writeJson)(p, {
+        ...meta,
+        cached_at: now()
+    });
+}
+async function workshopSearch(input) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const text = clean(input.text) ?? '';
+    const page = Number.isFinite(input.page) && (input.page ?? 1) > 0 ? Math.floor(input.page ?? 1) : 1;
+    const pageSize = Number.isFinite(input.pageSize) && (input.pageSize ?? DEFAULT_PAGE_SIZE) > 0
+        ? Math.floor(input.pageSize ?? DEFAULT_PAGE_SIZE)
+        : DEFAULT_PAGE_SIZE;
+    const sort = input.sort ?? 'top';
+    const tags = (input.tags ?? []).map(v => String(v).trim()).filter(Boolean);
+    const days = Number.isFinite(input.days) && (input.days ?? 7) > 0 ? Math.floor(input.days ?? 7) : 7;
+    const hasText = text.length > 0;
+    const queryType = resolveSortToQueryType(sort, hasText);
+    const queryPayload = {
+        query_type: queryType,
+        page,
+        numperpage: pageSize,
+        appid: WE_APP_ID,
+        creator_appid: WE_APP_ID,
+        filetype: 0,
+        search_text: text,
+        return_tags: true,
+        return_vote_data: true,
+        return_previews: true,
+        return_short_description: true,
+        requiredtags: tags.length > 0 ? tags : undefined,
+        match_all_tags: false
+    };
+    if (queryType === 3) {
+        queryPayload.days = days;
+        queryPayload.include_recent_votes_only = true;
+    }
+    const cacheFile = getSearchCacheFile(queryPayload, paths);
+    if (node_fs_1.default.existsSync(cacheFile)) {
+        try {
+            const cachedRaw = JSON.parse(node_fs_1.default.readFileSync(cacheFile, 'utf8'));
+            if (now() - cachedRaw.ts <= SEARCH_TTL_MS) {
+                return { ...cachedRaw.payload, cached: true };
+            }
+        }
+        catch {
+            // ignore malformed cache and refresh.
+        }
+    }
+    const json = await callSteamService('QueryFiles', queryPayload, Boolean(input.fixtures));
+    const itemsRaw = extractItemsFromQuery(json);
+    const items = itemsRaw
+        .map(item => normalizeMeta(item, paths))
+        .filter(item => item.id.length > 0);
+    for (const item of items) {
+        writeMetaFile(item);
+    }
+    await Promise.allSettled(items.slice(0, 16).map(item => cachePreviewImage(item.id, item.preview_url_remote)));
+    const root = json;
+    const total = typeof root.response?.total === 'number'
+        ? root.response.total
+        : (typeof root.response?.total_matching === 'number' ? root.response.total_matching : undefined);
+    const payload = { items, page, page_size: pageSize, total };
+    (0, fs_1.writeJson)(cacheFile, { ts: now(), payload });
+    return { ...payload, cached: false };
+}
+async function workshopDetails(publishedfileid, fixtures = false) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const id = clean(publishedfileid);
+    if (!id)
+        throw new Error('publishedfileid is required');
+    const payload = {
+        publishedfileids: [id],
+        includetags: true,
+        includeadditionalpreviews: true
+    };
+    const json = await callSteamService('GetDetails', payload, fixtures);
+    const raw = extractSingleFromDetails(json);
+    if (!raw)
+        throw new Error(`Workshop item not found: ${id}`);
+    const meta = normalizeMeta(raw, paths);
+    const additional = maybeAdditionalPreviews(raw);
+    const details = {
+        ...meta,
+        additional_previews: additional,
+        description_short: toShortDescription(raw),
+        file_size: typeof raw.file_size === 'number' ? raw.file_size : undefined,
+        item_url: `https://steamcommunity.com/sharedfiles/filedetails/?id=${id}`
+    };
+    writeMetaFile(details);
+    await cachePreviewImage(id, details.preview_url_remote);
+    await Promise.allSettled(additional.slice(0, 8).map((url, idx) => cachePreviewImage(id, url, `preview-${idx + 1}${extFromUrl(url)}`)));
+    return details;
+}
+function jobFile(jobId, paths) {
+    return node_path_1.default.join(paths.jobs, `${jobId}.json`);
+}
+function readJob(jobId) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const p = jobFile(jobId, paths);
+    if (!node_fs_1.default.existsSync(p))
+        return null;
+    return JSON.parse(node_fs_1.default.readFileSync(p, 'utf8'));
+}
+function writeJob(job) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    (0, fs_1.writeJson)(jobFile(job.id, paths), job);
+}
+function appendJobLog(job, line) {
+    const clipped = line.length > 2000 ? `${line.slice(0, 2000)}...` : line;
+    job.logs.push(clipped);
+    if (job.logs.length > 120) {
+        job.logs = job.logs.slice(job.logs.length - 120);
+    }
+}
+function setJobStatus(job, status, message) {
+    job.status = status;
+    job.updatedAt = now();
+    if (message)
+        appendJobLog(job, message);
+    writeJob(job);
+}
+function resolveTargetDir(targetDir) {
+    const paths = getWePaths();
+    if (!targetDir)
+        return paths.downloads;
+    if (targetDir === '~')
+        return node_os_1.default.homedir();
+    if (targetDir.startsWith('~/'))
+        return node_path_1.default.join(node_os_1.default.homedir(), targetDir.slice(2));
+    return targetDir;
+}
+function getChildCliPath() {
+    const current = process.argv[1];
+    return node_path_1.default.resolve(current);
+}
+function workshopQueueDownload(input) {
+    const id = clean(input.publishedfileid);
+    if (!id)
+        throw new Error('publishedfileid is required');
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const targetDir = resolveTargetDir(input.targetDir);
+    const jobId = (0, hash_1.sha256Hex)(`${id}:${Date.now()}:${Math.random()}`).slice(0, 16);
+    const job = {
+        id: jobId,
+        status: 'queued',
+        publishedfileid: id,
+        targetDir,
+        createdAt: now(),
+        updatedAt: now(),
+        logs: [],
+        steamUser: clean(input.steamUser),
+        steamPasswordEnv: clean(input.steamPasswordEnv) ?? 'STEAM_PASSWORD',
+        steamGuardCode: clean(input.steamGuardCode),
+        useCoexistence: input.useCoexistence ?? false
+    };
+    writeJob(job);
+    const child = (0, node_child_process_1.spawn)(process.execPath, [getChildCliPath(), 'we', 'run-job', jobId], {
+        detached: true,
+        stdio: 'ignore',
+        env: process.env
+    });
+    child.unref();
+    return { job_id: jobId, status: 'queued' };
+}
+function safeMkdir(p) {
+    if (!node_fs_1.default.existsSync(p))
+        (0, fs_1.ensureDir)(p);
+}
+function redacted(input, secret) {
+    if (!secret)
+        return input;
+    if (!secret.length)
+        return input;
+    return input.split(secret).join('***');
+}
+async function runSteamCmdDownload(job) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    safeMkdir(paths.steamcmd);
+    safeMkdir(node_path_1.default.join(paths.steamcmd, 'logs'));
+    const logFile = node_path_1.default.join(paths.steamcmd, 'logs', `${job.id}.log`);
+    const steamPassword = job.steamPasswordEnv ? clean(process.env[job.steamPasswordEnv]) : undefined;
+    const loginCmd = job.steamUser
+        ? `login ${job.steamUser} ${steamPassword ?? ''}${job.steamGuardCode ? ` ${job.steamGuardCode}` : ''}`
+        : 'login anonymous';
+    const commands = [
+        `force_install_dir ${paths.steamcmd}`,
+        loginCmd,
+        `workshop_download_item ${WE_APP_ID} ${job.publishedfileid}`,
+        'quit'
+    ];
+    await new Promise((resolve, reject) => {
+        const child = (0, node_child_process_1.spawn)('steamcmd', [], {
+            cwd: paths.steamcmd,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        const onData = (chunk) => {
+            const raw = String(chunk);
+            const cleanLine = redacted(raw, steamPassword);
+            node_fs_1.default.appendFileSync(logFile, cleanLine, 'utf8');
+            appendJobLog(job, cleanLine.trim());
+            writeJob(job);
+        };
+        child.stdout.on('data', onData);
+        child.stderr.on('data', onData);
+        child.on('error', reject);
+        child.on('close', (code) => {
+            if (code && code !== 0) {
+                reject(new Error(`steamcmd exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+        child.stdin.write(`${commands.join('\n')}\n`);
+        child.stdin.end();
+    });
+}
+function resolveDownloadedSource(publishedfileid) {
+    const paths = getWePaths();
+    return node_path_1.default.join(paths.steamcmd, 'steamapps', 'workshop', 'content', String(WE_APP_ID), publishedfileid);
+}
+async function copyDownloadedContent(job) {
+    const source = resolveDownloadedSource(job.publishedfileid);
+    if (!node_fs_1.default.existsSync(source)) {
+        throw new Error(`Downloaded workshop folder not found: ${source}`);
+    }
+    const baseTarget = resolveTargetDir(job.targetDir);
+    (0, fs_1.ensureDir)(baseTarget);
+    const target = node_path_1.default.join(baseTarget, job.publishedfileid);
+    if (node_fs_1.default.existsSync(target)) {
+        node_fs_1.default.rmSync(target, { recursive: true, force: true });
+    }
+    node_fs_1.default.cpSync(source, target, { recursive: true });
+    return target;
+}
+function snapshotFile(paths) {
+    return node_path_1.default.join(paths.runtime, 'coexistence.snapshot.json');
+}
+async function isUnitActive(unit) {
+    try {
+        const out = await (0, exec_1.run)('systemctl', ['--user', 'show', unit, '--property', 'ActiveState', '--value']);
+        return out.stdout.trim() === 'active';
+    }
+    catch {
+        return false;
+    }
+}
+async function workshopCoexistenceEnter() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const units = getCoexistServices();
+    const active = [];
+    for (const unit of units) {
+        if (await isUnitActive(unit))
+            active.push(unit);
+    }
+    for (const unit of active) {
+        try {
+            await (0, exec_1.run)('systemctl', ['--user', 'stop', unit]);
+        }
+        catch {
+            // best effort
+        }
+    }
+    (0, fs_1.writeJson)(snapshotFile(paths), { ts: now(), active });
+    return { ok: true, stopped: active, snapshot: active };
+}
+async function workshopCoexistenceExit() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const snapPath = snapshotFile(paths);
+    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)) : [];
+    const restored = [];
+    for (const unit of active) {
+        try {
+            await (0, exec_1.run)('systemctl', ['--user', 'start', unit]);
+            restored.push(unit);
+        }
+        catch {
+            // best effort
+        }
+    }
+    try {
+        node_fs_1.default.unlinkSync(snapPath);
+    }
+    catch {
+        // ignore
+    }
+    return { ok: true, restored };
+}
+async function workshopCoexistenceStatus() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const snapPath = snapshotFile(paths);
+    const snapshot = node_fs_1.default.existsSync(snapPath)
+        ? (JSON.parse(node_fs_1.default.readFileSync(snapPath, 'utf8')).active ?? [])
+        : [];
+    const units = getCoexistServices();
+    const current = {};
+    for (const unit of units) {
+        current[unit] = await isUnitActive(unit);
+    }
+    return { ok: true, snapshot, current };
+}
+async function workshopRunJob(jobId) {
+    const job = readJob(jobId);
+    if (!job)
+        throw new Error(`Job not found: ${jobId}`);
+    setJobStatus(job, 'downloading', 'Starting steamcmd download');
+    (0, logs_1.appendSystemLog)({
+        level: 'info',
+        source: 'workshop',
+        action: 'download:start',
+        message: `job=${job.id} id=${job.publishedfileid}`
+    });
+    let coexistEntered = false;
+    try {
+        if (job.useCoexistence) {
+            const coexist = await workshopCoexistenceEnter();
+            coexistEntered = true;
+            appendJobLog(job, `Coexistence enter: ${coexist.stopped.join(', ') || 'none'}`);
+            writeJob(job);
+        }
+        await runSteamCmdDownload(job);
+        setJobStatus(job, 'moving', 'Moving downloaded content to target directory');
+        const outputDir = await copyDownloadedContent(job);
+        job.outputDir = outputDir;
+        await workshopDetails(job.publishedfileid, false).catch(() => undefined);
+        setJobStatus(job, 'done', `Download ready at ${outputDir}`);
+        (0, logs_1.appendSystemLog)({
+            level: 'info',
+            source: 'workshop',
+            action: 'download:done',
+            message: `job=${job.id} id=${job.publishedfileid}`,
+            meta: { outputDir }
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        job.error = message;
+        setJobStatus(job, 'error', message);
+        (0, logs_1.appendSystemLog)({
+            level: 'error',
+            source: 'workshop',
+            action: 'download:error',
+            message: `job=${job.id} id=${job.publishedfileid} err=${message}`
+        });
+    }
+    finally {
+        if (coexistEntered) {
+            await workshopCoexistenceExit().catch(() => undefined);
+        }
+    }
+    return job;
+}
+function workshopGetJob(jobId) {
+    const job = readJob(jobId);
+    if (!job)
+        throw new Error(`Job not found: ${jobId}`);
+    return job;
+}
+function workshopListJobs(limit = 40) {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const files = node_fs_1.default.readdirSync(paths.jobs)
+        .filter(name => name.endsWith('.json'))
+        .map(name => node_path_1.default.join(paths.jobs, name));
+    const jobs = [];
+    for (const file of files) {
+        try {
+            const data = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+            jobs.push(data);
+        }
+        catch {
+            // ignore corrupted file
+        }
+    }
+    jobs.sort((a, b) => b.updatedAt - a.updatedAt);
+    return { jobs: jobs.slice(0, Math.max(1, Math.floor(limit))) };
+}
+function workshopLibrary() {
+    const paths = getWePaths();
+    ensureWePaths(paths);
+    const items = [];
+    if (!node_fs_1.default.existsSync(paths.downloads))
+        return { root: paths.downloads, items };
+    const dirs = node_fs_1.default.readdirSync(paths.downloads, { withFileTypes: true });
+    for (const entry of dirs) {
+        if (!entry.isDirectory())
+            continue;
+        const id = entry.name;
+        const p = node_path_1.default.join(paths.downloads, id);
+        const metadataFile = node_path_1.default.join(paths.metadata, `${id}.json`);
+        let meta;
+        if (node_fs_1.default.existsSync(metadataFile)) {
+            try {
+                meta = JSON.parse(node_fs_1.default.readFileSync(metadataFile, 'utf8'));
+            }
+            catch {
+                meta = undefined;
+            }
+        }
+        items.push({
+            id,
+            path: p,
+            metadata: node_fs_1.default.existsSync(metadataFile) ? metadataFile : undefined,
+            meta
+        });
+    }
+    items.sort((a, b) => a.id.localeCompare(b.id));
+    return { root: paths.downloads, items };
+}

package/dist/utils/exec.js

@@ -6,7 +6,7 @@ const child_process_1 = require("child_process");
 function run(cmd, args = [], options = {}) {
     return new Promise((resolve, reject) => {
         const isFlatpak = Boolean(process.env.FLATPAK_ID);
-        const hostCommands = new Set(['swww', 'swww-daemon', 'hyprctl', 'systemctl', 'which', 'xdg-open']);
+        const hostCommands = new Set(['swww', 'swww-daemon', 'hyprctl', 'systemctl', 'which', 'xdg-open', 'steamcmd']);
         const useHost = isFlatpak && hostCommands.has(cmd);
         const finalCmd = useHost ? 'flatpak-spawn' : cmd;
         const finalArgs = useHost ? ['--host', cmd, ...args] : args;

package/package.json

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