tsoft-cli 3.12.3 → 3.13.0

package/src/commands/store.js

@@ -3,6 +3,7 @@ import { listKnownStores, setActiveStore, getActiveTheme } from '../storage.js';
 import { brandedSelect, brandedSearch, showSuccess, showError, showInfo } from '../ui/prompt-wrapper.js';
 import { isJsonMode, jsonOut } from '../output-mode.js';
 import { t } from '../i18n.js';
+import { renderTable } from '../ui/table.js';
 
 const SEARCH_THRESHOLD = 7;
 
@@ -43,11 +44,17 @@ export async function storeListCommand() {
 
     console.log(chalk.bold.cyan(t('store.count', { count: stores.length }) + '\n'));
 
-    for (const entry of stores) {
+    const rows = stores.map((entry) => {
         const marker = entry.active ? chalk.green('●') : chalk.gray('○');
         const name = entry.active ? chalk.bold.green(entry.store) : chalk.white(entry.store);
-        console.log(`${marker} ${name} ${sessionLabel(entry)}`);
-    }
+
+        return [`${marker} ${name}`, sessionLabel(entry)];
+    });
+
+    console.log(renderTable({
+        head: [t('table.head.store'), t('table.head.session')],
+        rows,
+    }));
 
     console.log();
 }

package/src/commands/theme-dev.js

@@ -4,7 +4,8 @@ import path from 'path';
 import chokidar from 'chokidar';
 import {createApiClient} from '../api-client.js';
 import open from 'open';
-import {normalizeStoreDomain, slugify, setActiveTheme, getActiveTheme, getActiveStore, getWorkspaceRoot} from '../storage.js';
+import {normalizeStoreDomain, slugify, setActiveTheme, getActiveTheme, getActiveStore, getWorkspaceRoot, getWorkspaceContext} from '../storage.js';
+import {buildThemeMissingHint, formatThemeMissingHint} from '../ui/workspace-hint.js';
 import {decorateThemeName} from '../ui/theme-choice.js';
 import {brandedConfirm, brandedSelect, showWarning, showError, showInfo} from '../ui/prompt-wrapper.js';
 import {themeSectionMenuCommand} from './theme-section.js';
@@ -471,7 +472,13 @@ export async function themeDevCommand(themeName) {
 
         const exists = await fs.access(themePath).then(() => true).catch(() => false);
         if (!exists) {
-            showError(t('dev.theme_not_found', { path: themePath }));
+            const missing = buildThemeMissingHint({
+                context: getWorkspaceContext(),
+                activeStore: store,
+                activeTheme: themeDir,
+                workspaceRoot: getWorkspaceRoot(),
+            });
+            showError(formatThemeMissingHint(missing, themePath));
             return;
         }
 

package/src/commands/theme-init.js

@@ -130,7 +130,9 @@ export async function themeInitCommand(fromSlug) {
         console.log(chalk.cyan('  ' + t('init.source_label') + ' ') + chalk.white(`${forkedData.source.name} v${forkedData.source.version}`));
         console.log(chalk.cyan('  ' + t('init.location_label') + '  ') + chalk.white(`${storeSlug}/${forkedSlug}/`));
         console.log();
-        console.log(chalk.gray(t('init.dev_tip', { slug: forkedSlug })));
+        console.log(chalk.gray(t('init.dev_tip')));
+        console.log(chalk.white(`  cd ${storeSlug}/${forkedSlug}`));
+        console.log(chalk.white('  tsoft theme dev'));
         console.log();
 
     } catch (error) {

package/src/commands/theme-section.js

@@ -7,6 +7,7 @@ import {getActiveTheme, getThemeUuidBySlug, normalizeStoreDomain, getActiveStore
 import {brandedConfirm, brandedSelect, brandedSearch, brandedInput, showWarning, showSuccess, showInfo} from '../ui/prompt-wrapper.js';
 import { t } from '../i18n.js';
 import {mergeThemeArchive} from '../theme-download.js';
+import {renderTable} from '../ui/table.js';
 
 const SECTION_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 
@@ -52,30 +53,28 @@ export async function themeSectionListCommand() {
         console.log(chalk.bold.cyan(t('section.list.count', { count: blocks.length }) + '\n'));
 
         blocks.forEach((block) => {
-            // Block başlığı
-            console.log(chalk.bold.cyan(`📦 ${block.name}`));
-            console.log(chalk.gray(`   ${t('section.list.id_label')} ${block.id}`));
-            console.log(chalk.gray(`   ${t('section.list.folder_label')} ${block.folder}`));
+            console.log(chalk.bold.cyan(`📦 ${block.name}`) + chalk.gray(`  ${block.folder}`));
 
-            // Section'lar
             if (block.default_sections && block.default_sections.length > 0) {
-                console.log(chalk.yellow('   ' + t('section.list.sections_label', { count: block.default_sections.length })));
-
-                block.default_sections.forEach((section) => {
-                    console.log(chalk.white(`     • ${section.name} ${chalk.gray(`(ID: ${section.id}, v${section.version})`)}`));
-
-                    // Meta bilgiler varsa göster
-                    if (section.meta) {
-                        if (section.meta.description) {
-                            console.log(chalk.gray(`       ${section.meta.description}`));
-                        }
-                        if (section.meta.tags && section.meta.tags.length > 0) {
-                            console.log(chalk.gray(`       ${t('section.list.tags_label')} ${section.meta.tags.join(', ')}`));
-                        }
-                    }
-
-                    console.log(chalk.gray(`       ${t('section.list.file_label')} ${section.content}`));
-                });
+                const rows = block.default_sections.map((section) => [
+                    chalk.white(section.name),
+                    chalk.gray(`v${section.version}`),
+                    chalk.gray(String(section.id)),
+                    chalk.gray(section.content),
+                    chalk.gray(section.meta?.description ?? ''),
+                ]);
+
+                console.log(renderTable({
+                    head: [
+                        t('table.head.section'),
+                        t('table.head.version'),
+                        t('table.head.id'),
+                        t('table.head.file'),
+                        t('table.head.description'),
+                    ],
+                    rows,
+                    indent: '  ',
+                }));
             } else {
                 console.log(chalk.red('   ' + t('section.list.no_sections')));
             }

package/src/commands/theme.js

@@ -7,6 +7,7 @@ import {normalizeStoreDomain, slugify, setActiveTheme, getActiveTheme, getActive
 import {brandedConfirm, brandedSelect, brandedSearch, showWarning} from '../ui/prompt-wrapper.js';
 import {fetchAllThemes} from '../theme-list.js';
 import {themeLabels, decorateThemeName} from '../ui/theme-choice.js';
+import {renderTable} from '../ui/table.js';
 import { isJsonMode, jsonOut } from '../output-mode.js';
 import { mapError } from '../errors/error-mapper.js';
 import { t } from '../i18n.js';
@@ -48,18 +49,32 @@ export async function themeListCommand() {
 
         const localTheme = await getActiveTheme();
 
-        themes.forEach((theme) => {
+        const rows = themes.map((theme) => {
             const labels = themeLabels(theme, localTheme);
             const indicator = labels.includes('selected')
                 ? chalk.cyan('●')
                 : (labels.includes('published') ? chalk.green('●') : chalk.gray('○'));
-            const description = theme.description ? chalk.gray(` - ${theme.description}`) : '';
-
-            console.log(`${indicator} ${decorateThemeName(theme, localTheme)}${description}`);
-            console.log(chalk.gray(`   ${t('theme.folder_label')} ${theme.theme_folder || theme.alias}`));
-            console.log();
+            const name = labels.includes('selected')
+                ? chalk.bold.cyan(theme.name)
+                : chalk.white(theme.name);
+            const marks = labels.map(label => label === 'selected'
+                ? chalk.cyan(t('theme.mark.selected'))
+                : chalk.green(t('theme.mark.published')));
+
+            return [
+                `${indicator} ${name}`,
+                chalk.gray(`v${theme.version}`),
+                chalk.gray(theme.theme_folder || theme.alias),
+                marks.join(' '),
+            ];
         });
 
+        console.log(renderTable({
+            head: [t('table.head.theme'), t('table.head.version'), t('table.head.folder'), t('table.head.status')],
+            rows,
+        }));
+        console.log();
+
     } catch (error) {
         if (isJsonMode()) {
             const mapped = mapError(error, { command: 'theme list' });
@@ -301,6 +316,7 @@ export async function themeCreateCommand(themeName) {
         console.log(chalk.bold.green(t('theme.create_success')));
         console.log(chalk.gray('   ' + t('theme.create_location', { path: `${storeSlug}/${themeSlug}/` }) + '\n'));
         console.log(chalk.cyan(t('theme.dev_start_tip')));
+        console.log(chalk.white(`  cd ${storeSlug}/${themeSlug}`));
         console.log(chalk.white('  tsoft theme dev\n'));
 
     } catch (error) {
@@ -385,6 +401,9 @@ export async function themePullCommand() {
 
         console.log(chalk.bold.green(t('theme.pull.success')));
         console.log(chalk.gray('   ' + t('theme.create_location', { path: `${storeSlug}/${themeSlug}/` }) + '\n'));
+        console.log(chalk.cyan(t('theme.dev_start_tip')));
+        console.log(chalk.white(`  cd ${storeSlug}/${themeSlug}`));
+        console.log(chalk.white('  tsoft theme dev\n'));
     } catch (error) {
         console.error(chalk.red('\n❌ Hata: ') + error.message);
         if (error.response?.status === 401) {

package/src/commands/upgrade.js

@@ -0,0 +1,116 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+import chalk from 'chalk';
+import axios from 'axios';
+import { isJsonMode, jsonOut } from '../output-mode.js';
+import { showError, showInfo, showSuccess } from '../ui/prompt-wrapper.js';
+import { t } from '../i18n.js';
+import {
+    PACKAGE_NAME,
+    detectInstallMethod,
+    upgradeCommandFor,
+    isNewerAvailable,
+} from '../upgrade-plan.js';
+
+const run = promisify(execFile);
+const require = createRequire(import.meta.url);
+const REGISTRY_URL = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+const CHECK_TIMEOUT_MS = 3000;
+
+function installedVersion() {
+    return require('../../package.json').version;
+}
+
+function modulePath() {
+    return fileURLToPath(import.meta.url);
+}
+
+export async function fetchLatestVersion(timeout = CHECK_TIMEOUT_MS) {
+    try {
+        const { data } = await axios.get(REGISTRY_URL, { timeout });
+
+        return typeof data?.version === 'string' ? data.version : null;
+    } catch {
+        return null;
+    }
+}
+
+export async function upgradeCommand() {
+    const current = installedVersion();
+    const method = detectInstallMethod({ modulePath: modulePath() });
+    const command = upgradeCommandFor(method);
+
+    if (!isJsonMode()) {
+        console.log(chalk.cyan(t('upgrade.checking')));
+    }
+
+    const latest = await fetchLatestVersion();
+
+    if (!latest) {
+        if (isJsonMode()) {
+            jsonOut({ status: 'error', command: 'upgrade', error: { message: t('upgrade.check_failed'), hint: null } });
+            process.exit(1);
+        }
+        showError(t('upgrade.check_failed'));
+        process.exit(1);
+    }
+
+    if (!isNewerAvailable(current, latest)) {
+        if (isJsonMode()) {
+            jsonOut({ status: 'ok', command: 'upgrade', current, latest, upToDate: true });
+            return;
+        }
+        showSuccess(t('upgrade.current', { version: current }));
+        return;
+    }
+
+    if (isJsonMode()) {
+        jsonOut({ status: 'ok', command: 'upgrade', current, latest, upToDate: false, installMethod: method, command_hint: command });
+        return;
+    }
+
+    console.log(chalk.yellow(t('upgrade.available', { current, latest })));
+    console.log();
+
+    if (!command) {
+        showInfo(method === 'npx' ? t('upgrade.npx_notice') : t('upgrade.unknown_install'));
+        return;
+    }
+
+    console.log(chalk.gray(t('upgrade.running', { command })));
+    console.log();
+
+    const [file, ...args] = command.split(' ');
+
+    try {
+        const { stdout } = await run(file, args, { timeout: 120000 });
+
+        if (stdout.trim()) {
+            console.log(chalk.gray(stdout.trim()));
+        }
+
+        showSuccess(t('upgrade.success', { version: latest }));
+    } catch (error) {
+        showError(t('upgrade.failed', { error: error.stderr?.trim() || error.message }));
+        process.exit(1);
+    }
+}
+
+export async function buildUpgradeNotice() {
+    const current = installedVersion();
+    const latest = await fetchLatestVersion();
+
+    if (!isNewerAvailable(current, latest)) {
+        return null;
+    }
+
+    const method = detectInstallMethod({ modulePath: modulePath() });
+
+    return {
+        current,
+        latest,
+        command: upgradeCommandFor(method) ?? `npm install -g ${PACKAGE_NAME}@latest`,
+    };
+}

package/src/index.js

@@ -3,8 +3,8 @@
 import { createRequire } from 'module';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { setJsonMode, setVerboseMode } from './output-mode.js';
-import { initLocale } from './i18n.js';
+import { setJsonMode, setVerboseMode, isJsonMode, jsonOut } from './output-mode.js';
+import { initLocale, t } from './i18n.js';
 import { renderBrandedHelp } from './ui/help-renderer.js';
 import { loginCommand } from './commands/login.js';
 import { logoutCommand } from './commands/logout.js';
@@ -18,7 +18,15 @@ import { themeSubmitCommand } from './commands/theme-submit.js';
 import { themeInitCommand } from './commands/theme-init.js';
 import { orgSwitchCommand } from './commands/org-switch.js';
 import { storeListCommand, storeUseCommand } from './commands/store.js';
-import { setStoreOverride, applyWorkspaceContext } from './storage.js';
+import { docsCommand } from './commands/docs.js';
+import { upgradeCommand, buildUpgradeNotice } from './commands/upgrade.js';
+import { configAutoupgradeCommand } from './commands/config.js';
+import { getAutoupgrade, getLastCheck, setLastCheck } from './cli-settings.js';
+import { setStoreOverride, applyWorkspaceContext, getWorkspaceContext, getWorkspaceRoot, getActiveStore, getActiveTheme } from './storage.js';
+import { buildWorkspaceHint, formatWorkspaceHint, commandUsesThemeContext } from './ui/workspace-hint.js';
+import { suggestCommand, formatUnknownCommand } from './ui/command-suggestion.js';
+import { collectCommandTree, renderCompletion, SUPPORTED_SHELLS } from './ui/completion.js';
+import { showError, brandedConfirm } from './ui/prompt-wrapper.js';
 
 const require = createRequire(import.meta.url);
 const { version } = require('../package.json');
@@ -38,7 +46,7 @@ program.option('--verbose', 'Verbose debug output');
 program.option('--store <domain>', 'Run this command against a specific store');
 
 // preAction hook: runs before every command
-program.hook('preAction', async (thisCommand) => {
+program.hook('preAction', async (thisCommand, actionCommand) => {
   const opts = thisCommand.opts();
   if (opts.json) {
     setJsonMode(true);
@@ -51,10 +59,130 @@ program.hook('preAction', async (thisCommand) => {
     setStoreOverride(opts.store);
   }
   await applyWorkspaceContext();
+  await warnWhenOutsideThemeDirectory(actionCommand);
+  await noticeNewVersion(actionCommand);
 });
 
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NO_CHECK_COMMANDS = new Set(['upgrade', 'update', 'completion', 'config autoupgrade']);
+
+async function noticeNewVersion(actionCommand) {
+  if (isJsonMode() || NO_CHECK_COMMANDS.has(commandPathOf(actionCommand))) {
+    return;
+  }
+
+  try {
+    if (!(await getAutoupgrade())) {
+      return;
+    }
+
+    const now = Date.now();
+
+    if (now - (await getLastCheck()) < CHECK_INTERVAL_MS) {
+      return;
+    }
+
+    await setLastCheck(now);
+
+    const notice = await buildUpgradeNotice();
+
+    if (notice) {
+      console.log(chalk.yellow(t('upgrade.notice', notice)));
+      console.log(chalk.gray('  ' + t('upgrade.notice_disable')));
+      console.log();
+    }
+  } catch {
+    return;
+  }
+}
+
+function commandPathOf(actionCommand) {
+  const segments = [];
+
+  for (let cmd = actionCommand; cmd?.parent; cmd = cmd.parent) {
+    segments.unshift(cmd.name());
+  }
+
+  return segments.join(' ');
+}
+
+async function warnWhenOutsideThemeDirectory(actionCommand) {
+  if (isJsonMode() || !commandUsesThemeContext(commandPathOf(actionCommand))) {
+    return;
+  }
+
+  const activeStore = await getActiveStore();
+
+  if (!activeStore) {
+    return;
+  }
+
+  const hint = buildWorkspaceHint({
+    context: getWorkspaceContext(),
+    activeStore,
+    activeTheme: await getActiveTheme(activeStore),
+    workspaceRoot: getWorkspaceRoot(),
+  });
+
+  if (hint) {
+    console.log(formatWorkspaceHint(hint));
+    console.log();
+  }
+}
+
+function visibleNames(cmd) {
+  const names = [];
+
+  for (const sub of cmd.commands) {
+    if (sub._hidden) {
+      continue;
+    }
+    names.push(sub.name());
+    if (sub.alias()) {
+      names.push(sub.alias());
+    }
+  }
+
+  return names;
+}
+
+async function rejectUnknownCommand(cmd, parentPath = null) {
+  const [unknown] = cmd.args;
+  const message = formatUnknownCommand(unknown, visibleNames(cmd), parentPath);
+
+  if (isJsonMode()) {
+    jsonOut({ status: 'error', error: { message, hint: null } });
+    process.exit(1);
+  }
+
+  showError(message);
+
+  const suggestion = suggestCommand(unknown, visibleNames(cmd));
+
+  if (suggestion && process.stdin.isTTY) {
+    const full = parentPath ? `${parentPath} ${suggestion}` : suggestion;
+    const accepted = await brandedConfirm({
+      message: t('error.run_suggestion', { command: `tsoft ${full}` }),
+      default: true,
+    });
+
+    if (accepted) {
+      const rest = cmd.args.slice(1);
+      await program.parseAsync([...process.argv.slice(0, 2), ...full.split(' '), ...rest]);
+      return;
+    }
+  }
+
+  process.exit(1);
+}
+
 // Show branded help when no arguments provided
-program.action(async () => {
+program.action(async (_options, cmd) => {
+  if (cmd.args.length) {
+    await rejectUnknownCommand(cmd);
+    return;
+  }
+
   await renderBrandedHelp(program);
 });
 
@@ -88,6 +216,47 @@ program
     await whoamiCommand();
   });
 
+program
+  .command('docs')
+  .description('Open the developer documentation in your browser')
+  .action(async () => {
+    await docsCommand();
+  });
+
+program
+  .command('upgrade')
+  .alias('update')
+  .description('Update the CLI to the latest version')
+  .action(async () => {
+    await upgradeCommand();
+  });
+
+const configCmd = program
+  .command('config')
+  .description('Show and change CLI settings');
+
+configCmd
+  .command('autoupgrade [action]')
+  .description('Turn the version check on or off (on | off | status)')
+  .action(async (action) => {
+    await configAutoupgradeCommand(action ?? 'status');
+  });
+
+program
+  .command('completion <shell>')
+  .description(`Generate a shell completion script (${SUPPORTED_SHELLS.join(', ')})`)
+  .action((shell) => {
+    if (!SUPPORTED_SHELLS.includes(shell)) {
+      showError(t('completion.unsupported_shell', {
+        shell,
+        supported: SUPPORTED_SHELLS.join(', '),
+      }));
+      process.exit(1);
+    }
+
+    process.stdout.write(renderCompletion(shell, collectCommandTree(program)));
+  });
+
 const theme = program
   .command('theme')
   .description('Theme management commands');
@@ -195,7 +364,12 @@ org
 const section = theme
   .command('section')
   .description('Section management commands')
-  .action(async () => {
+  .action(async (_options, cmd) => {
+    if (cmd.args.length) {
+      await rejectUnknownCommand(cmd, 'theme section');
+      return;
+    }
+
     await themeSectionMenuCommand();
   });
 

package/src/theme-download.js

@@ -21,79 +21,85 @@ async function stageArchive(stream, stagingPath) {
     await fs.rm(zipPath, { force: true });
 }
 
-/**
- * Tema arşivini indirir, doğrular ve ancak ondan sonra hedefin üzerine açar.
- *
- * Hedefteki dosyalar silinmez; arşivdekiler üzerine yazılır. Bozuk veya yarım
- * inen bir arşiv hedefe hiç dokunmaz.
- *
- * @param {import('stream').Readable} stream - Arşiv veri akışı
- * @param {string} themePath - Arşivin açılacağı dizin
- * @returns {Promise<void>}
- */
-export async function mergeThemeArchive(stream, themePath) {
-    await fs.mkdir(themePath, { recursive: true });
+async function withStaging(themePath, apply) {
+    const parent = path.dirname(themePath);
+    await fs.mkdir(parent, { recursive: true });
 
-    const staging = await fs.mkdtemp(path.join(themePath, '.tsoft-update-'));
+    const staging = await fs.mkdtemp(path.join(parent, `.${path.basename(themePath)}-`));
 
     try {
-        const zipPath = path.join(staging, 'theme.zip');
+        return await apply(staging);
+    } finally {
+        await fs.rm(staging, { recursive: true, force: true });
+    }
+}
 
-        await pipeline(stream, createWriteStream(zipPath));
+async function copyInto(sourceDir, targetDir) {
+    for (const entry of await fs.readdir(sourceDir)) {
+        await fs.cp(path.join(sourceDir, entry), path.join(targetDir, entry), {
+            recursive: true,
+            force: true,
+        });
+    }
+}
 
-        const { size } = await fs.stat(zipPath);
+/**
+ * Arşivde bulunmayan girdileri hedeften siler.
+ *
+ * Dizini yeniden adlandırmak Windows'ta içine girilmişse veya içindeki bir
+ * dosya açıksa EBUSY verir; bu yüzden hedef dizin yerinde bırakılır ve yalnızca
+ * fazlalık girdiler kaldırılır. Kalıcı bir kilit tek bir dosyayı geride
+ * bırakabilir, ama temanın geri kalanı yine güncellenmiş olur.
+ */
+async function removeStaleEntries(themePath, stagingPath) {
+    const fresh = new Set(await fs.readdir(stagingPath));
 
-        if (size === 0) {
-            throw new Error('EMPTY_ARCHIVE');
+    for (const entry of await fs.readdir(themePath)) {
+        if (!fresh.has(entry)) {
+            await fs.rm(path.join(themePath, entry), { recursive: true, force: true });
         }
-
-        const zip = new AdmZip(zipPath);
-        zip.extractAllTo(themePath, true);
-    } finally {
-        await fs.rm(staging, { recursive: true, force: true });
     }
 }
 
 /**
- * Tema arşivini indirir, doğrular ve ancak ondan sonra hedefin üzerine koyar.
+ * Tema arşivini indirir, doğrular ve ancak ondan sonra hedefe yerleştirir.
  *
  * Arşiv hedefin yanındaki geçici dizine açılır; indirme yarıda koparsa veya
- * arşiv bozuksa hedef dizine dokunulmaz. Böylece başarısız bir indirme
- * kullanıcının mevcut tema dosyalarını silmez.
+ * arşiv bozuksa hedef dizine dokunulmaz. Hedef dizinin kendisi taşınmaz,
+ * yalnızca içeriği değiştirilir — dizin bir editörde veya kabukta açıkken de
+ * çalışır.
  *
  * @param {import('stream').Readable} stream - Arşiv veri akışı
  * @param {string} themePath - Temanın açılacağı hedef dizin
  * @returns {Promise<void>}
  */
 export async function extractThemeArchive(stream, themePath) {
-    const parent = path.dirname(themePath);
-    await fs.mkdir(parent, { recursive: true });
-
-    const staging = await fs.mkdtemp(path.join(parent, `.${path.basename(themePath)}-`));
-    const backup = `${staging}-previous`;
-
-    try {
+    await withStaging(themePath, async (staging) => {
         await stageArchive(stream, staging);
-    } catch (error) {
-        await fs.rm(staging, { recursive: true, force: true });
-        throw error;
-    }
 
-    const hadPrevious = await fs.access(themePath).then(() => true).catch(() => false);
+        await fs.mkdir(themePath, { recursive: true });
 
-    if (hadPrevious) {
-        await fs.rename(themePath, backup);
-    }
+        await copyInto(staging, themePath);
+        await removeStaleEntries(themePath, staging);
+    });
+}
 
-    try {
-        await fs.rename(staging, themePath);
-    } catch (error) {
-        if (hadPrevious) {
-            await fs.rename(backup, themePath);
-        }
-        await fs.rm(staging, { recursive: true, force: true });
-        throw error;
-    }
+/**
+ * Tema arşivini indirir, doğrular ve ancak ondan sonra hedefin üzerine açar.
+ *
+ * Hedefteki dosyalar silinmez; arşivdekiler üzerine yazılır. Bozuk veya yarım
+ * inen bir arşiv hedefe hiç dokunmaz.
+ *
+ * @param {import('stream').Readable} stream - Arşiv veri akışı
+ * @param {string} themePath - Arşivin açılacağı dizin
+ * @returns {Promise<void>}
+ */
+export async function mergeThemeArchive(stream, themePath) {
+    await withStaging(themePath, async (staging) => {
+        await stageArchive(stream, staging);
+
+        await fs.mkdir(themePath, { recursive: true });
 
-    await fs.rm(backup, { recursive: true, force: true });
+        await copyInto(staging, themePath);
+    });
 }