@woladi/sortai 0.1.1 → 0.2.0

package/README.md

@@ -6,6 +6,9 @@
 
 > macOS CLI that scans a folder, reads every document with **Apple Vision OCR**, and automatically writes **Finder tags** and **Finder comments** — so your files become searchable in Spotlight and browsable by tag in Finder. Runs fully offline by default. Cloud LLMs optional.
 
+> [!NOTE]
+> **Pre-1.0, work in progress.** CLI messages and wizard prompts are currently hardcoded in Polish — DX preference of the maintainer. The README, config keys, and source code are in English. There's no language toggle yet; if you'd like an English UI, open an issue.
+
 ## What it does
 
 `sortai` walks a folder recursively, reads the content of PDFs and images using Apple's on-device Vision framework (via [`macos-vision`](https://www.npmjs.com/package/macos-vision)), and uses a language model to infer what the file is about. It then writes that understanding directly into the file's macOS metadata:
@@ -95,51 +98,73 @@ When `--mask` is set, `sortai` spawns [`pseudonym-mcp`](https://www.npmjs.com/pa
 ## Quick start
 
 ```bash
-# First run creates ~/.config/sortai/config.json and exits
+# First run with no config launches an interactive wizard:
+#  - asks what mode you want (tag / organize / both / discovery)
+#  - asks for Ollama vs Anthropic vs OpenAI, picks model
+#  - samples ~30 files, runs OCR, asks the LLM to propose a taxonomy
+#  - lets you refine tags, then writes ~/.config/sortai/config.json
 npx @woladi/sortai
 
+# Or invoke the wizard explicitly
+npx @woladi/sortai init ~/Desktop
+
 # Dry-run: see what tags would be written, without touching any files
-npx @woladi/sortai ~/Desktop --dry-run
+npx @woladi/sortai tag ~/Desktop --dry-run
 
 # Actually write Finder tags and comments
-npx @woladi/sortai ~/Desktop
+npx @woladi/sortai tag ~/Desktop
+
+# Move files into folders based on Finder tags already on them
+npx @woladi/sortai organize ~/Desktop --apply
+
+# Try the pipeline on 10 random files without writing anything
+npx @woladi/sortai sample ~/Desktop -n 10
 ```
 
-> The first invocation writes the default config and exits. **Edit `~/.config/sortai/config.json`** to match your own tag taxonomy, then re-run.
+> The first invocation without a config opens the interactive wizard. You can re-open it any time with `sortai init` to regenerate the taxonomy.
+
+### Commands
+
+| Command | What it does |
+|---------|--------------|
+| `sortai init [folder]` | Interactive wizard — picks mode/provider/model, samples files, generates and refines a tag taxonomy, writes the config. |
+| `sortai tag [folder]` | Default. OCR + LLM → Finder tags & comments. Same flags as before. |
+| `sortai organize [folder]` | Read existing Finder tags, move files into folders. Default dry-run; pass `--apply` to execute. |
+| `sortai clear [folder]` | Remove all sortai tags & comments from files. |
+| `sortai sample [folder]` | Dry-run the pipeline on N random files (default 20). Useful after editing the config. |
 
 ### Reset metadata before a fresh run
 
 ```bash
 # Remove all Finder tags and comments sortai previously wrote
-npx @woladi/sortai ~/Desktop --clear
+npx @woladi/sortai clear ~/Desktop
 
 # Preview what would be cleared without touching files
-npx @woladi/sortai ~/Desktop --clear --dry-run
+npx @woladi/sortai clear ~/Desktop --dry-run
 ```
 
-After `--clear`, Spotlight is reindexed automatically (`mdimport`) so stale tags disappear from search immediately. Combine with a config change and re-run to start fresh with a new taxonomy.
+After `sortai clear`, Spotlight is reindexed automatically (`mdimport`) so stale tags disappear from search immediately. Combine with a config change and re-run to start fresh with a new taxonomy.
 
 ### Cloud mode (optional)
 
 ```bash
 # Anthropic Claude — OCR text sent to the API
-npx @woladi/sortai ~/Desktop --cloud anthropic --api-key sk-ant-...
+npx @woladi/sortai tag ~/Desktop --cloud anthropic --api-key sk-ant-...
 
 # With PII pseudonymisation: only tokens like [PESEL:1] reach the cloud
-npx @woladi/sortai ~/Desktop --cloud anthropic --mask --api-key sk-ant-...
+npx @woladi/sortai tag ~/Desktop --cloud anthropic --mask --api-key sk-ant-...
 
 # OpenAI
-OPENAI_API_KEY=sk-... npx @woladi/sortai ~/Desktop --cloud openai
+OPENAI_API_KEY=sk-... npx @woladi/sortai tag ~/Desktop --cloud openai
 ```
 
-## CLI flags
+## CLI flags (for `tag`, the default subcommand)
 
 | Flag | Default | Description |
 |------|---------|-------------|
 | `<folder>` | from config | Folder to scan recursively |
 | `--config <path>` | `~/.config/sortai/config.json` | Alternative config file |
 | `--dry-run` | off | Print results without writing tags/comments |
-| `--clear` | off | Remove all sortai-written Finder tags and comments from every file in the folder |
 | `--model <name>` | `mistral-nemo` (Ollama) | LLM model name |
 | `--ollama-url <url>` | `http://localhost:11434` | Ollama server |
 | `--cloud anthropic\|openai` | — | Switch to a cloud LLM |
@@ -150,11 +175,14 @@ OPENAI_API_KEY=sk-... npx @woladi/sortai ~/Desktop --cloud openai
 | `--limit <n>` | — | Process at most N files |
 | `--skip-tagged` | off | Skip files that already carry `cfg.tags.autoTag` (`#AI_Sorted`) |
 | `--no-dedup` | off | Skip SHA256 duplicate detection |
+| `--free` | off | Let the LLM invent new tags outside `tags.allowed`; new tags are reported at the end |
 | `--verbose` | off | Extra logs |
 
+For `organize`: `--target <path>` overrides destination, `--apply` is required to actually move (default is dry-run). For `sample`: `-n <count>` selects how many files to test.
+
 ## Configuration
 
-The first run writes `~/.config/sortai/config.json`. Edit it to fit your taxonomy:
+The first run launches `sortai init`, which writes `~/.config/sortai/config.json` after you answer the wizard. You can also edit it by hand. Layout:
 
 ```json
 {
@@ -187,7 +215,18 @@ The first run writes `~/.config/sortai/config.json`. Edit it to fit your taxonom
       { "pattern": "\\bbank\\b|iban|rachunek", "flags": "i", "tags": ["#Bank"] },
       { "pattern": "faktura|invoice",          "flags": "i", "tags": ["#Faktura"] }
     ],
-    "autoTag": "#AI_Sorted"
+    "autoTag": "#AI_Sorted",
+    "freeForm": false
+  },
+  "organize": {
+    "enabled": false,
+    "target": "~/Documents/Sorted",
+    "strategy": "flat",
+    "priority": ["#Faktura", "#Bank", "#Umowa"],
+    "folderMap": {},
+    "unsorted": "move",
+    "unsortedFolder": "_unsorted",
+    "multiTag": "primary"
   },
   "context": "1-2 sentence description of yourself and ongoing matters — used by the LLM as background."
 }
@@ -199,6 +238,7 @@ Key options:
 - **`tags.strict`** — subset of `allowed`. A strict tag only lands on a file if at least one `strictEvidence` keyword appears verbatim in OCR or filename. Prevents false positives on sensitive categories like `#Bank` or `#Kredyt`.
 - **`tags.autoTag`** — appended to every successfully processed file. Used as a sentinel by `--skip-tagged` so you don't re-process files on the next run.
 - **`tags.pathRules`** — regex rules matched against the full filepath + OCR text. Matched tags become *pre-tags* that are always included and passed to the LLM as hints.
+- **`tags.freeForm`** — when `true`, the LLM may propose tags outside `allowed`; new tags pass a shape check (`#[Unicode-letter/digit/_-]+`, so `#Płatność` works) and are reported in the run summary so you can promote them into `allowed` if you want to keep them. Equivalent to the `--free` CLI flag.
 - **`ocr.startPage` / `ocr.maxPages`** — PDF page range. Default reads pages 1–2; raise `maxPages` for long documents where the key content is deeper.
 - **`context`** — one or two sentences about yourself pinned to the LLM system prompt. The model uses this as background when writing comments (e.g. knowing you're a freelancer or a specific sector helps contextualise ambiguous documents).
 

package/dist/cli.js

@@ -1,296 +1,71 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 import chalk from 'chalk';
-import ora from 'ora';
-import path from 'node:path';
-import { existsSync } from 'node:fs';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
-const execFileAsync = promisify(execFile);
-import { expandHome, loadConfig } from './config.js';
-import { walkFiles } from './walker.js';
-import { extractOcrText } from './ocr.js';
-import { preTagFromPath } from './pretag.js';
-import { mergeTags } from './tags.js';
-import { writeFileMetadata, clearMacosMetadata } from './macos.js';
-import { Masker } from './mask.js';
-import { inferTagsAndComment } from './llm/index.js';
-import { findDuplicates } from './dedup.js';
-function applyOverrides(cfg, opts) {
-    const apiKey = opts.apiKey
-        ?? process.env.SORTAI_API_KEY
-        ?? (opts.cloud === 'anthropic' ? process.env.ANTHROPIC_API_KEY : undefined)
-        ?? (opts.cloud === 'openai' ? process.env.OPENAI_API_KEY : undefined);
-    const provider = opts.cloud ?? 'ollama';
-    const defaultCloudModels = {
-        anthropic: 'claude-sonnet-4-6',
-        openai: 'gpt-4o-mini',
-    };
-    return {
-        ...cfg,
-        scan: {
-            ...cfg.scan,
-            excludeFolders: opts.exclude
-                ? opts.exclude.split(',').map(s => s.trim()).filter(Boolean)
-                : cfg.scan.excludeFolders,
-        },
-        llm: {
-            ...cfg.llm,
-            provider,
-            model: opts.model ?? (opts.cloud ? defaultCloudModels[opts.cloud] ?? cfg.llm.model : cfg.llm.model),
-            ollamaUrl: opts.ollamaUrl ?? cfg.llm.ollamaUrl,
-            apiKey,
-        },
-        mask: {
-            ...cfg.mask,
-            enabled: opts.mask,
-            lang: opts.lang ?? cfg.mask.lang,
-        },
-        dedup: {
-            ...cfg.dedup,
-            enabled: opts.dedup,
-        },
-    };
-}
+import { initCommand } from './commands/init.js';
+import { tagCommand } from './commands/tag.js';
+import { organizeCommand } from './commands/organize.js';
+import { clearCommand } from './commands/clear.js';
+import { sampleCommand } from './commands/sample.js';
 async function main() {
     const program = new Command();
     program
         .name('sortai')
-        .description('macOS CLI that tags files based on OCR + LLM-inferred Finder tags & comments')
-        .version('0.1.0')
-        .argument('[folder]', 'folder to scan (overrides config.scan.folder)')
-        .option('--config <path>', 'path to config JSON (default: ~/.config/sortai/config.json)')
-        .option('--dry-run', 'do not write tags/comments; just log', false)
-        .option('--clear', 'remove all sortai-written Finder tags and comments from every file in the folder', false)
-        .option('--model <name>', 'LLM model name (default depends on provider)')
-        .option('--ollama-url <url>', 'Ollama base URL (default: http://localhost:11434)')
-        .option('--cloud <provider>', "use a cloud LLM: 'anthropic' or 'openai'")
-        .option('--api-key <key>', 'API key for cloud provider (or env SORTAI_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY)')
-        .option('--mask', 'pseudonymise OCR via pseudonym-mcp before sending to cloud LLM', false)
-        .option('--lang <code>', "pseudonym-mcp language: 'en' | 'pl' (default: pl)")
-        .option('--exclude <patterns>', 'comma-separated folder names to skip (overrides config)')
-        .option('--limit <n>', 'process at most N files', v => parseInt(v, 10))
-        .option('--skip-tagged', 'skip files that already have the auto-tag (cfg.tags.autoTag)', false)
-        .option('--no-dedup', 'skip SHA256 duplicate detection (hash-based #Duplikat tag)')
-        .option('--verbose', 'extra logs', false)
-        .parse(process.argv);
-    const opts = program.opts();
-    const folderArg = program.args[0];
-    if (opts.cloud && !['anthropic', 'openai'].includes(opts.cloud)) {
-        process.stderr.write(chalk.red(`Unknown --cloud provider: ${opts.cloud}\n`));
-        process.exit(1);
-    }
-    if (opts.mask && !opts.cloud) {
-        process.stderr.write(chalk.yellow('⚠️  --mask without --cloud is a no-op (local Ollama already keeps data offline).\n'));
-    }
-    let configResult;
-    try {
-        configResult = await loadConfig(opts.config);
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        process.stderr.write(chalk.red(`Config error: ${msg}\n`));
-        process.exit(1);
-    }
-    if (configResult.created) {
-        process.stdout.write(chalk.green(`✨ Created default config at ${configResult.path}\n`));
-        process.stdout.write('   Edit it to customise tags, then re-run.\n');
-        return;
-    }
-    const cfg = applyOverrides(configResult.config, opts);
-    if (cfg.llm.provider !== 'ollama' && !cfg.llm.apiKey) {
-        process.stderr.write(chalk.red(`Missing API key for ${cfg.llm.provider}. Pass --api-key or set the env var.\n`));
-        process.exit(1);
-    }
-    const rawFolder = folderArg ?? cfg.scan.folder;
-    const root = path.resolve(expandHome(rawFolder));
-    if (!existsSync(root)) {
-        process.stderr.write(chalk.red(`Folder does not exist: ${root}\n`));
-        process.exit(1);
-    }
-    let masker;
-    if (cfg.mask.enabled && cfg.llm.provider !== 'ollama') {
-        masker = new Masker(cfg);
-        const spin = ora('Starting pseudonym-mcp…').start();
-        try {
-            await masker.connect();
-            spin.succeed('pseudonym-mcp ready');
-        }
-        catch (err) {
-            spin.fail(err instanceof Error ? err.message : String(err));
-            masker = undefined;
-        }
-    }
-    if (opts.clear) {
-        process.stdout.write(chalk.cyan(`🧹 Clearing sortai metadata from ${root}\n`));
-        if (opts.dryRun)
-            process.stdout.write(chalk.yellow('   [dry-run — no changes will be written]\n'));
-        process.stdout.write('\n');
-        const clearFiles = await walkFiles(root, cfg);
-        let cleared = 0;
-        let clearErrors = 0;
-        for (const filePath of clearFiles) {
-            const rel = path.relative(root, filePath);
-            if (opts.dryRun) {
-                process.stdout.write(chalk.gray(`  🗑  ${rel}\n`));
-                cleared++;
-                continue;
-            }
-            try {
-                await clearMacosMetadata(filePath);
-                execFileAsync('mdimport', [filePath]).catch(() => { });
-                if (opts.verbose)
-                    process.stdout.write(chalk.gray(`  🗑  ${rel}\n`));
-                cleared++;
-            }
-            catch {
-                process.stdout.write(chalk.red(`  ❌ ${rel}\n`));
-                clearErrors++;
-            }
-        }
-        process.stdout.write('═══════════════════════════════════════════════════════\n');
-        process.stdout.write(chalk.bold('✨ Done\n'));
-        process.stdout.write(chalk.green(`   🗑  Cleared: ${cleared}\n`));
-        if (clearErrors)
-            process.stdout.write(chalk.red(`   ❌ Errors:  ${clearErrors}\n`));
-        return;
-    }
-    process.stdout.write(chalk.cyan(`🚀 Scanning ${root}\n`));
-    process.stdout.write(`   Provider: ${cfg.llm.provider} (${cfg.llm.model})`);
-    if (cfg.mask.enabled && masker)
-        process.stdout.write(chalk.gray(' [masked]'));
-    if (opts.dryRun)
-        process.stdout.write(chalk.yellow(' [dry-run]'));
-    process.stdout.write('\n');
-    if (cfg.scan.excludeFolders.length) {
-        process.stdout.write(chalk.gray(`   Excluded: ${cfg.scan.excludeFolders.join(', ')}\n`));
-    }
-    process.stdout.write('\n');
-    let allFiles = await walkFiles(root, cfg);
-    process.stdout.write(`📁 Files: ${allFiles.length}\n`);
-    if (opts.skipTagged) {
-        const before = allFiles.length;
-        const filtered = [];
-        for (const f of allFiles) {
-            try {
-                const { stdout: md } = await execFileAsync('mdls', ['-name', 'kMDItemUserTags', '-raw', f], { timeout: 3_000 });
-                if (!md.includes(cfg.tags.autoTag))
-                    filtered.push(f);
-            }
-            catch {
-                filtered.push(f);
-            }
-        }
-        allFiles = filtered;
-        process.stdout.write(chalk.gray(`   Skip-tagged: ${before - allFiles.length} pominięte, ${allFiles.length} do przetworzenia\n`));
-    }
-    if (opts.limit && opts.limit > 0 && allFiles.length > opts.limit) {
-        allFiles = allFiles.slice(0, opts.limit);
-        process.stdout.write(chalk.gray(`   Limit: ${opts.limit} plików\n`));
-    }
-    let dedup;
-    if (cfg.dedup.enabled && allFiles.length > 1) {
-        process.stdout.write(chalk.gray(`🔢 Hashing ${allFiles.length} files for dedup…\n`));
-        dedup = await findDuplicates(allFiles, cfg);
-        process.stdout.write(chalk.gray(`   Hashed: ${dedup.hashedFiles}, skipped >${cfg.dedup.maxFileSizeMB}MB: ${dedup.skippedLarge}, ` +
-            `duplicate groups: ${dedup.totalGroups}, files in groups: ${dedup.totalDuplicates}\n`));
-    }
-    process.stdout.write('\n');
-    const stats = { ok: 0, preOnly: 0, skipped: 0, errors: 0, total: allFiles.length };
-    const skipExt = new Set(cfg.scan.skipExtensions);
-    const ocrExt = new Set(cfg.scan.ocrExtensions);
-    const videoExt = new Set(cfg.scan.videoExtensions);
-    for (const filePath of allFiles) {
-        const rel = path.relative(root, filePath);
-        const name = path.basename(filePath);
-        const ext = path.extname(filePath).toLowerCase();
-        if (skipExt.has(ext)) {
-            stats.skipped++;
-            continue;
-        }
-        process.stdout.write(chalk.bold(`🔍 ${rel}\n`));
-        let ocrText = '';
-        if (ocrExt.has(ext)) {
-            process.stdout.write('  📖 OCR…');
-            ocrText = await extractOcrText(filePath, cfg);
-            const words = ocrText.split(/\s+/).filter(Boolean).length;
-            process.stdout.write(` ${words} words\n`);
-        }
-        else if (videoExt.has(ext)) {
-            process.stdout.write('  🎬 Video\n');
-        }
-        else {
-            process.stdout.write(`  📄 ${ext}\n`);
-        }
-        const preTagsBase = preTagFromPath(filePath, ocrText, cfg);
-        const dupGroup = dedup?.groupByFile.get(filePath);
-        const preTags = dupGroup ? mergeTags(cfg, preTagsBase, ['#Duplikat']) : preTagsBase;
-        if (dupGroup) {
-            const others = dupGroup.files.filter(f => f !== filePath).map(f => path.basename(f));
-            process.stdout.write(chalk.magenta(`  🧬 Duplicate of: ${others.join(', ')}\n`));
-        }
-        let finalTags;
-        let finalComment;
-        if (preTags.length >= 4 && !ocrText.trim()) {
-            finalTags = mergeTags(cfg, preTags, [cfg.tags.autoTag]);
-            finalComment = `Auto z nazwy/ścieżki: ${name}.`;
-            process.stdout.write(chalk.gray(`  ⚡ Pre-only: ${preTags.join(' ')}\n`));
-            stats.preOnly++;
-        }
-        else {
-            process.stdout.write(chalk.gray(`  🧠 ${cfg.llm.provider}…\n`));
-            const PER_FILE_TIMEOUT_MS = 180_000;
-            let timer;
-            const timeout = new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`per-file timeout after ${PER_FILE_TIMEOUT_MS}ms`)), PER_FILE_TIMEOUT_MS);
-            });
-            try {
-                const result = await Promise.race([
-                    inferTagsAndComment({ fileName: name, ext, preTags, ocrText }, cfg, masker),
-                    timeout,
-                ]);
-                finalTags = mergeTags(cfg, result.tags, [cfg.tags.autoTag]);
-                finalComment = result.comment || `Plik: ${name}.`;
-            }
-            catch (err) {
-                const msg = err instanceof Error ? err.message : String(err);
-                process.stdout.write(chalk.yellow(`  ⏱  ${msg} — fallback\n`));
-                finalTags = mergeTags(cfg, preTags, [cfg.tags.autoTag]).slice(0, 6);
-                finalComment = `Plik: ${name}.`;
-            }
-            finally {
-                if (timer)
-                    clearTimeout(timer);
-            }
-        }
-        if (opts.dryRun) {
-            process.stdout.write(chalk.green(`  ✅ ${finalTags.join(' ')}\n`));
-            process.stdout.write(chalk.gray(`  📝 ${finalComment}\n\n`));
-            stats.ok++;
-            continue;
-        }
-        try {
-            await writeFileMetadata(filePath, finalTags, finalComment);
-            process.stdout.write(chalk.green(`  ✅ ${finalTags.join(' ')}\n`));
-            process.stdout.write(chalk.gray(`  📝 ${finalComment}\n\n`));
-            stats.ok++;
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            process.stdout.write(chalk.red(`  ❌ Write failed: ${msg}\n\n`));
-            stats.errors++;
-        }
-    }
-    if (masker)
-        await masker.close();
-    process.stdout.write('═══════════════════════════════════════════════════════\n');
-    process.stdout.write(chalk.bold('✨ Done\n'));
-    process.stdout.write(chalk.green(`   ✅ Success:       ${stats.ok}\n`));
-    process.stdout.write(chalk.gray(`   ⚡ Pre-only:       ${stats.preOnly}\n`));
-    process.stdout.write(chalk.gray(`   ⏭  Skipped:       ${stats.skipped}\n`));
-    process.stdout.write(chalk.red(`   ❌ Errors:        ${stats.errors}\n`));
+        .description('macOS CLI: OCR + LLM → Finder tags, komentarze i sortowanie do folderów')
+        .version('0.2.0');
+    program
+        .command('init [folder]')
+        .description('Interaktywny wizard: zbuduj config z Twoich plików')
+        .option('--config <path>', 'ścieżka do configu')
+        .option('--api-key <key>', 'klucz API (cloud)')
+        .action((folder, opts) => initCommand(folder, opts));
+    program
+        .command('tag [folder]', { isDefault: true })
+        .description('Otaguj pliki (Finder tagi + komentarze) — akcja domyślna')
+        .option('--config <path>', 'ścieżka do configu')
+        .option('--dry-run', 'podgląd bez zapisu', false)
+        .option('--model <name>', 'nazwa modelu LLM')
+        .option('--ollama-url <url>', 'Ollama base URL')
+        .option('--cloud <provider>', "'anthropic' | 'openai'")
+        .option('--api-key <key>', 'klucz API')
+        .option('--mask', 'pseudonimizuj OCR przed wysyłką do cloud', false)
+        .option('--lang <code>', "'en' | 'pl'")
+        .option('--exclude <patterns>', 'CSV — katalogi do pominięcia')
+        .option('--limit <n>', 'max plików', v => parseInt(v, 10))
+        .option('--skip-tagged', 'pomiń pliki z auto-tagiem', false)
+        .option('--no-dedup', 'pomiń detekcję duplikatów')
+        .option('--free', 'pozwól LLM-owi proponować nowe tagi (free-form)', false)
+        .option('--verbose', 'więcej logów', false)
+        .action((folder, opts) => tagCommand(folder, opts));
+    program
+        .command('organize [folder]')
+        .description('Przenieś pliki do folderów na bazie ich Finder tagów')
+        .option('--config <path>', 'ścieżka do configu')
+        .option('--target <path>', 'folder docelowy (nadpisuje config)')
+        .option('--dry-run', 'pokaż plan, nie przenoś', false)
+        .option('--apply', 'wykonaj przenoszenia (default = dry-run)', false)
+        .option('--verbose', 'więcej logów', false)
+        .action((folder, opts) => organizeCommand(folder, opts));
+    program
+        .command('clear [folder]')
+        .description('Wyczyść wszystkie sortai tagi i komentarze z plików')
+        .option('--config <path>', 'ścieżka do configu')
+        .option('--dry-run', 'podgląd bez kasowania', false)
+        .option('--verbose', 'więcej logów', false)
+        .action((folder, opts) => clearCommand(folder, opts));
+    program
+        .command('sample [folder]')
+        .description('Uruchom pełen pipeline na N losowych plikach (dry-run)')
+        .option('--config <path>', 'ścieżka do configu')
+        .option('-n, --count <count>', 'ile plików', v => parseInt(v, 10), 20)
+        .option('--verbose', 'więcej logów', false)
+        .action((folder, opts) => sampleCommand(folder, opts));
+    await program.parseAsync(process.argv);
 }
 main().catch(err => {
+    if (err instanceof Error && (err.name === 'ExitPromptError' || err.message.includes('force closed'))) {
+        process.stdout.write(chalk.yellow('\nAnulowano.\n'));
+        process.exit(130);
+    }
     process.stderr.write(chalk.red(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`));
     process.exit(1);
 });

package/dist/commands/clear.js

@@ -0,0 +1,55 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import chalk from 'chalk';
+import { expandHome, loadConfig, configExists } from '../config.js';
+import { walkFiles } from '../walker.js';
+import { clearMacosMetadata } from '../macos.js';
+import { runWizard } from '../wizard/index.js';
+const execFileAsync = promisify(execFile);
+export async function clearCommand(folder, opts) {
+    if (!(await configExists(opts.config))) {
+        process.stdout.write(chalk.cyan('🪄 Brak configu — uruchamiam wizard…\n\n'));
+        await runWizard({ configPath: opts.config, folderHint: folder });
+        return;
+    }
+    const { config: cfg } = await loadConfig(opts.config);
+    const rawFolder = folder ?? cfg.scan.folder;
+    const root = path.resolve(expandHome(rawFolder));
+    if (!existsSync(root)) {
+        process.stderr.write(chalk.red(`Folder nie istnieje: ${root}\n`));
+        process.exit(1);
+    }
+    process.stdout.write(chalk.cyan(`🧹 Clearing sortai metadata from ${root}\n`));
+    if (opts.dryRun)
+        process.stdout.write(chalk.yellow('   [dry-run — no changes will be written]\n'));
+    process.stdout.write('\n');
+    const files = await walkFiles(root, cfg);
+    let cleared = 0;
+    let errors = 0;
+    for (const filePath of files) {
+        const rel = path.relative(root, filePath);
+        if (opts.dryRun) {
+            process.stdout.write(chalk.gray(`  🗑  ${rel}\n`));
+            cleared++;
+            continue;
+        }
+        try {
+            await clearMacosMetadata(filePath);
+            execFileAsync('mdimport', [filePath]).catch(() => { });
+            if (opts.verbose)
+                process.stdout.write(chalk.gray(`  🗑  ${rel}\n`));
+            cleared++;
+        }
+        catch {
+            process.stdout.write(chalk.red(`  ❌ ${rel}\n`));
+            errors++;
+        }
+    }
+    process.stdout.write('═══════════════════════════════════════════════════════\n');
+    process.stdout.write(chalk.bold('✨ Done\n'));
+    process.stdout.write(chalk.green(`   🗑  Cleared: ${cleared}\n`));
+    if (errors)
+        process.stdout.write(chalk.red(`   ❌ Errors:  ${errors}\n`));
+}

package/dist/commands/init.js

@@ -0,0 +1,32 @@
+import chalk from 'chalk';
+import { runWizard } from '../wizard/index.js';
+import { tagCommand } from './tag.js';
+import { organizeCommand } from './organize.js';
+export async function initCommand(folder, opts) {
+    const result = await runWizard({
+        configPath: opts.config,
+        apiKey: opts.apiKey,
+        folderHint: folder,
+    });
+    if (result.shouldRunTag) {
+        process.stdout.write('\n' + chalk.bold.cyan('▶ Tagowanie\n\n'));
+        await tagCommand(result.config.scan.folder, {
+            config: opts.config,
+            dryRun: false,
+            verbose: false,
+            skipTagged: false,
+            dedup: result.config.dedup.enabled,
+            mask: result.config.mask.enabled,
+            free: result.config.tags.freeForm,
+        });
+    }
+    if (result.shouldRunOrganize) {
+        process.stdout.write('\n' + chalk.bold.cyan('▶ Sortowanie\n\n'));
+        await organizeCommand(result.config.scan.folder, {
+            config: opts.config,
+            apply: true,
+            dryRun: false,
+            verbose: false,
+        });
+    }
+}