soft-sort 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 275107ab192d1c7a5b4a0e5e3f5a7a4b68c5549b7309e2463a2e117b3a69b3b7
+  data.tar.gz: 9c7d12b6085ce04206251509b59afc59dae3cbe3e08e88802b09017f066b9ac7
+SHA512:
+  metadata.gz: f751d4027048e81d6ea8964d751502ede00f8c3fe78a6eac4d24fd91fe89e5d2c738b0ae281820c8404febac9aec4ce9e6967127ab1b85b0ee1d6da38ff82123
+  data.tar.gz: '090d15e5f83d903ad64392a3b671a6dffcc6a70f7ecbde1d0bc0f19656f6feaf341124371625be266261172872c1a3671dde7ba43f41cdaefb3f1c19db761b09'

data/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 1.0.0 - 2026-11-13
+
+- Fixed Ruby 3.2 development dependency compatibility by constraining Parallel to the 1.27 series.
+- Fixed scanning on systems without birth timestamps; unavailable creation dates remain nil and automatic date folders use modification time.
+- Excluded vendored dependencies from RuboCop while retaining its default exclusions.
+- Expanded YAML-driven file recognition across development, documentation,
+  configuration, design, font, CAD, database, e-book, and media formats.
+- Added bounded extensionless filename/signature recognition without execution.
+- Added project type subfolders and recursive protection for established trees.
+- Added regression coverage for CivicWatch-style project scripts, sensitive
+  files, unknown formats, and recursive safety.
+- Added explicit dry-run and `organize --apply` execution.
+- Added protected-file detection, SHA-256 pre-move validation, no-overwrite moves, and required-folder creation.
+- Added durable JSONL transaction history and verified undo support.
+- Added duplicate detection, statistics, and explainability commands.
+- Added expanded safety, execution, duplicate, and undo tests.
+- Documented intentionally disabled content, EXIF, AI, watch, and automatic recovery features.
+- Added root-scoped locking, synchronized/fsynced JSONL journal writes, per-operation progress persistence, and filesystem reconciliation for interrupted moves.
+- Added read-only and apply-mode `recover` command with hash-verified recovery reporting.
+- Hardened moves and undo with same-filesystem no-replace hard-link/unlink operations and symlink rejection.
+- Added configurable year, year/month, and year/month/day destination folders.
+- Added opt-in bounded local content evidence for text, Markdown, CSV, JSON, and PDF files.
+- Added explicit `skip`, `review`, and deterministic `rename` collision policies.
+- Added advanced classification and collision regression coverage.
+- Added polling-based, stability-aware `watch` mode with preview-only defaults.
+- Added disabled-by-default AI provider interfaces and bounded PNG metadata support.
+- Added GitHub Actions CI for Ruby/RSpec/RuboCop, CLI smoke tests, gem builds,
+  and macOS/Linux/Windows runner coverage.
+- Added isolated installed-gem smoke verification and release support documentation.
+
+## 0.1.0 - 2026-10-16
+
+- Added read-only scanning, hybrid classification, planning, text output, and JSON reporting.

data/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+Copyright (c) 2026 SoftSort contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files, to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and sell copies of the Software.

data/README.md

@@ -0,0 +1,146 @@
+# SoftSort
+
+SoftSort is a local-first, offline Ruby CLI that scans a selected directory, explains deterministic organization decisions, and—when explicitly requested—moves approved files into generated folders. It never follows symbolic links, silently overwrites files, or deletes files.
+
+## Requirements and installation
+
+Ruby 3.2 or newer is required. SoftSort has no runtime service, database, cloud, or AI dependency.
+
+```sh
+git clone <repository>
+cd soft-sort
+bundle install
+bundle exec ruby bin/soft-sort --help
+```
+
+The same commands work in macOS/Linux shells and Windows PowerShell (use `ruby bin/soft-sort ...` in place of an installed executable).
+
+## CLI usage
+
+```sh
+soft-sort --help
+soft-sort version
+soft-sort scan ~/Downloads
+soft-sort plan ~/Downloads
+soft-sort plan ~/Downloads --recursive
+soft-sort plan ~/Downloads --format json
+soft-sort plan ~/Downloads --config ./rules.yml --verbose
+soft-sort organize ~/Downloads --apply
+soft-sort duplicates ~/Downloads --recursive --format json
+soft-sort history ~/Downloads --limit 20
+soft-sort undo ~/Downloads --dry-run
+soft-sort recover ~/Downloads
+soft-sort recover ~/Downloads --apply
+soft-sort stats ~/Downloads --format json
+soft-sort explain ~/Downloads/example.pdf
+soft-sort plan ~/Downloads --date-folders --inspect-content
+soft-sort organize ~/Downloads --collision rename --apply
+soft-sort watch ~/Downloads --interval 5
+```
+
+`scan` reports discovered, eligible, excluded, categorized, and sized files. `plan` reports source, proposed destination, type, context, rule, confidence, action, and warnings. `organize` previews by default and performs approved moves only with `--apply`. `--recursive` is opt-in. `--format json` emits only JSON on stdout; diagnostics go to stderr.
+
+Recovery is read-only by default. It reconciles unfinished journal transactions against the actual source and destination files using stored SHA-256 identities. Use `recover --apply` only after reviewing the preview. Recovery refuses symlinks, missing identities, collisions, modified files, and operations outside the selected root.
+
+Example:
+
+```text
+MOVE     invoice_2026.pdf -> Finance/Invoices/invoice_2026.pdf (Documents, 0.95)
+MOVE     Screenshot_2026.png -> Images/Screenshots/Screenshot_2026.png (Images, 0.95)
+REVIEW   mystery.xyz -> Others/mystery.xyz (Others, 0.25)
+```
+
+## How classification works
+
+Type classification is YAML-driven and covers documents/e-books, images/graphics, spreadsheets, presentations, video, audio, archives, installers, fonts, design, CAD, databases, development languages, documentation, shell scripts, and configuration. It recognizes Markdown (`md`, `markdown`), shell scripts (`sh`, `bash`, `zsh`, `fish`), development formats (`rb`, `py`, `go`, `js`, `jsx`, `ts`, `tsx`, `sql`), configuration (`json`, `yaml`, `yml`, `toml`, `xml`, `plist`, `ini`, `conf`, `env`), and common format extensions. Extensionless files can use safe filename rules or a bounded signature read for PDF, ZIP, and shebang headers; SoftSort never executes them. Unknown extensions use `Others` and require review.
+
+Context classification tokenizes case-insensitive filenames using common separators. Rules are ordered by priority. The precedence is contextual rule, file type, then unknown fallback. Equal-priority contextual matches are marked `review` rather than chosen arbitrarily. Confidence is a deterministic evidence score, not a statistical probability.
+
+Projects are configured with aliases and optional type destinations. For example, a `CivicWatch-deployment.sh` file can resolve to `Projects/CivicWatch/Development/Scripts/`. Recursive mode protects files already inside an established directory tree by default, so existing project source and manifests are not scattered.
+
+Date folders are disabled by default and can be enabled with `--date-folders` or YAML. Supported formats are `year`, `year_month`, and `year_month_day`; the default date source is a reliable available timestamp, falling back to modification time. Collision handling defaults to conservative review/conflict behavior. Set `organization.collision_policy` to `rename` only when deterministic `(1)`, `(2)` suffixes are desired.
+
+Bounded local content evidence is disabled by default. `--inspect-content` enables small, offline reads for plain text, Markdown, CSV, JSON, and PDF text; protected files are never inspected. The implementation does not execute documents, extract arbitrary archives, or upload content.
+
+`watch` uses polling and is preview-only unless `--apply` is supplied. It waits for files to remain size/timestamp-stable before planning them and inherits all scanner, project, sensitive-file, lock, collision, and journal safeguards. Stop it with Ctrl-C. The optional AI provider interface is disabled by default (`ai.enabled: false`) and has no network implementation; deterministic classification remains the only active fallback.
+
+Default destinations include `Images/Photos`, `Documents`, `Media/Videos`, `Media/Audio`, `Archives`, `Projects/Source`, `Installers`, and contextual destinations such as `Finance/Invoices`, `Images/Screenshots`, and `Documents/Reports`.
+
+## Configuration
+
+Use safe YAML with these top-level sections:
+
+```yaml
+version: 1
+organization:
+  mode: hybrid
+  recursive: false
+  dry_run: true
+safety:
+  follow_symlinks: false
+  include_hidden: false
+categories:
+  Documents:
+    extensions: [pdf, doc, docx, txt]
+    destination: Documents
+context_rules:
+  - name: invoices
+    keywords: [invoice, receipt]
+    destination: Finance/Invoices
+    priority: 100
+projects:
+  civicwatch:
+    aliases: [civicwatch, civic-watch]
+    destination: Projects/CivicWatch
+    destinations:
+      Development Scripts: Projects/CivicWatch/Development/Scripts
+      Development: Projects/CivicWatch/Development
+exclusions:
+  directories: [node_modules]
+  extensions: [part, crdownload]
+```
+
+Destinations must be relative and cannot contain `..`. Safe YAML loading rejects aliases and invalid configuration. Default exclusions include hidden entries, symlinks, `.git`, `node_modules`, `.venv`, `vendor/bundle`, `__pycache__`, and incomplete-download extensions (`.part`, `.crdownload`, `.download`, `.tmp`).
+
+## Safety guarantees and limitations
+
+SoftSort defaults to a dry run. With `organize --apply`, it creates only required destination folders and moves approved, non-sensitive, non-conflicting files. It verifies SHA-256 identity immediately before each move, uses a same-filesystem no-replace hard-link/unlink operation, refuses existing destinations, records append-only JSONL transactions under `.soft-sort`, and supports verified undo and recovery. It never follows symbolic links, leaves the selected root, executes scanned files, unpacks archives, transmits metadata, overwrites or deletes files, or moves protected credentials by default.
+
+Duplicate detection uses size grouping and streamed SHA-256 hashing but never deletes duplicates. Journal recovery is supported for interrupted move transactions; power-loss durability remains subject to the host filesystem's fsync guarantees. Image metadata currently provides bounded PNG dimensions only; full EXIF, HEIC/WebP capture dates, DOCX extraction, OCR, and remote/local model execution remain disabled until they can be implemented with platform-specific safety guarantees. Extension/name classification can be wrong and should be reviewed.
+
+## Project structure
+
+```text
+bin/soft-sort                 CLI executable
+lib/soft_sort/scanning        filesystem scanning and metadata
+lib/soft_sort/classification  type/context/rule classification
+lib/soft_sort/planning        destination and conflict planning
+lib/soft_sort/reporting       text and JSON output
+config/default_rules.yml      default rules
+spec/                         automated tests with temporary fixtures
+```
+
+## Testing and development
+
+```sh
+bundle exec rspec
+bundle exec rubocop
+bundle exec ruby bin/soft-sort scan ./test-files
+bundle exec ruby bin/soft-sort plan ./test-files --recursive --format json
+gem build soft-sort.gemspec
+ruby script/installed_gem_smoke.rb soft-sort-1.0.0.gem
+```
+
+The test suite uses temporary directories rather than personal folders and covers empty/single/nested scans, hidden files, symlinks, exclusions, temporary downloads, missing roots, extension/context classification, priority ambiguity, deterministic planning, already-organized files, configuration safety, CLI output/errors, JSON validity, read-only behavior, execution, undo, recovery reconciliation, malformed journals, date folders, collision renaming, bounded content evidence, PNG metadata, and disabled AI fallback.
+
+## Platform support and release status
+
+SoftSort requires Ruby 3.2 or newer. The source is designed for macOS, Linux, and Windows; hosted CI is configured for Ruby 3.2 and 3.3 on Ubuntu, macOS, and Windows. Local verification has been performed on macOS Apple Silicon. Hosted CI results must be checked before claiming a platform-specific release guarantee.
+
+Same-filesystem organization uses no-replace hard-link/unlink operations. Cross-filesystem moves are rejected rather than copied and deleted. Locking, timestamp precision, symlink behavior, hard-link permissions, and power-loss durability depend on the host filesystem. Watch mode is polling-based and preview-only unless `--apply` is supplied.
+
+The release artifact is built with `gem build soft-sort.gemspec`. The installed-gem smoke test verifies the executable outside the source load path. No publishing workflow is included; publishing requires explicit manual authorization.
+
+## Contributing and license
+
+Keep the scanner and classifiers free of filesystem mutation, add focused temporary-fixture tests for changes, and run RSpec and RuboCop before submitting a change. SoftSort is released under the MIT License; see [LICENSE](LICENSE).

data/bin/soft-sort

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'soft_sort'
+exit(SoftSort::CLI.new(ARGV).run || 0)

data/config/default_rules.yml

@@ -0,0 +1,74 @@
+version: 1
+organization:
+  mode: hybrid
+  recursive: false
+  dry_run: true
+  date_folders: false
+  date_format: year_month
+  date_source: auto
+  collision_policy: skip
+safety:
+  follow_symlinks: false
+  include_hidden: false
+  overwrite: false
+  protect_existing_project_structures: true
+categories:
+  Images: { extensions: [jpg, jpeg, png, gif, webp, heic, svg, tiff], destination: Images/Photos }
+  Documents: { extensions: [pdf, doc, docx, txt, rtf, odt, epub, mobi, azw, azw3], destination: Documents }
+  Spreadsheets: { extensions: [xls, xlsx, csv, ods], destination: Documents/Spreadsheets }
+  Videos: { extensions: [mp4, mov, avi, mkv, webm], destination: Media/Videos }
+  Audio: { extensions: [mp3, wav, flac, aac, m4a], destination: Media/Audio }
+  Archives: { extensions: [zip, rar, 7z, tar, gz, bz2, xz, tgz, iso, cab], destination: Archives }
+  Development: { extensions: [rb, py, go, js, jsx, ts, tsx, rs, java, c, h, cpp, cs, php, swift, kt, dart, lua, r, sql], destination: Projects/Source }
+  Documentation: { extensions: [md, markdown, rst, adoc, tex], destination: Documents/Documentation }
+  Development Scripts: { extensions: [sh, bash, zsh, fish, ps1, bat, cmd], destination: Projects/Source/Scripts }
+  Configuration: { extensions: [json, yaml, yml, toml, xml, plist, ini, conf, cfg, properties, env], destination: Projects/Source/Configuration }
+  Design: { extensions: [fig, sketch, ai, eps, psd, xd, indd], destination: Design }
+  Fonts: { extensions: [ttf, otf, woff, woff2], destination: Fonts }
+  Databases: { extensions: [db, sqlite, sqlite3, sqlitedb, mdb], destination: Data/Databases }
+  CAD: { extensions: [dwg, dxf, step, stp, iges, igs, stl, obj], destination: Design/CAD }
+  Source Code: { extensions: [rb, py, js, jsx, ts, tsx, go, rs, java, html, css], destination: Projects/Source }
+  Installers: { extensions: [dmg, pkg, exe, msi, deb, rpm, appimage], destination: Installers }
+  Presentations: { extensions: [ppt, pptx, odp, key], destination: Documents/Presentations }
+  Graphics: { extensions: [svg, psd, ai, eps], destination: Images/Graphics }
+context_rules:
+  - { name: invoices, keywords: [invoice, receipt], destination: Finance/Invoices, priority: 100 }
+  - { name: screenshots, keywords: [screenshot, screen_shot], destination: Images/Screenshots, priority: 90 }
+  - { name: project_giffy, keywords: [giffy, giffyride], destination: Projects/Giffy, priority: 80 }
+  - { name: resumes, keywords: [resume, cv], destination: Personal/Resumes, priority: 80 }
+  - { name: contracts, keywords: [contract, agreement], destination: Finance/Contracts, priority: 80 }
+  - { name: reports, keywords: [report], destination: Documents/Reports, priority: 70 }
+projects:
+  civicwatch:
+    aliases: [civicwatch, civic-watch]
+    destination: Projects/CivicWatch
+    destinations:
+      Development: Projects/CivicWatch/Development
+      Development Scripts: Projects/CivicWatch/Development/Scripts
+      Configuration: Projects/CivicWatch/Development/Configuration
+      Documentation: Projects/CivicWatch/Documentation
+  giffy:
+    aliases: [giffy, giffyride]
+    destination: Projects/Giffy
+    destinations:
+      Development: Projects/Giffy/Development
+      Development Scripts: Projects/Giffy/Development/Scripts
+      Configuration: Projects/Giffy/Development/Configuration
+      Documentation: Projects/Giffy/Documentation
+      Images: Projects/Giffy/Images
+      Documents: Projects/Giffy/Documents
+filename_types:
+  - { pattern: '^README(?:\.|$)', category: Documentation, destination: Documents/Documentation }
+  - { pattern: '^LICENSE(?:\.|$)', category: Documentation, destination: Documents/Documentation }
+  - { pattern: '^\.env(?:\.|$)', category: Configuration, destination: Projects/Source/Configuration }
+  - { pattern: '^(Makefile|Dockerfile|Procfile)$', category: Development Scripts, destination: Projects/Source/Scripts }
+content_inspection:
+  enabled: false
+  max_bytes: 1048576
+  min_signals: 2
+ai:
+  enabled: false
+  provider: none
+exclusions:
+  directories: [.git, node_modules, .venv, vendor/bundle, __pycache__]
+  extensions: [part, crdownload, download, tmp]

data/lib/soft_sort/classification/ai_provider.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SoftSort
+  module AI
+    class DisabledProvider
+      def classify(_file)
+        nil
+      end
+    end
+
+    class ProviderInterface
+      def classify(_file)
+        raise NotImplementedError, 'AI providers must implement #classify'
+      end
+    end
+  end
+end

data/lib/soft_sort/classification/classification_result.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SoftSort
+  ClassificationResult = Struct.new(:type_category, :context_category, :destination, :matched_rule, :confidence,
+                                    :requires_review, keyword_init: true)
+end

data/lib/soft_sort/classification/content_classifier.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class ContentClassifier
+    RULES = [
+      { name: 'invoice_content', keywords: %w[invoice billing amount due], destination: 'Finance/Invoices', category: 'Documents' },
+      { name: 'research_content', keywords: %w[research methodology references abstract], destination: 'Documents/Education/Research', category: 'Documents' },
+      { name: 'contract_content', keywords: %w[agreement contract parties obligations], destination: 'Finance/Contracts', category: 'Documents' }
+    ].freeze
+
+    def initialize(config)
+      settings = config.data.fetch('content_inspection', {})
+      @enabled = settings.fetch('enabled', false)
+      @max_bytes = settings.fetch('max_bytes', 1_048_576)
+      @min_signals = settings.fetch('min_signals', 2)
+    end
+
+    def classify(file)
+      return nil unless @enabled && readable_format?(file) && !file.sensitive_reason
+
+      content = File.open(file.absolute_path, 'rb') { |stream| stream.read(@max_bytes) }.to_s.force_encoding(Encoding::UTF_8).scrub.downcase
+      match = RULES.map { |rule| [rule, rule[:keywords].count { |keyword| content.include?(keyword) }] }
+                   .select { |_rule, signals| signals >= @min_signals }.max_by(&:last)
+      return nil unless match
+
+      rule, signals = match
+      { category: rule[:category], destination: rule[:destination], name: rule[:name], confidence: [0.70 + (signals * 0.05), 0.90].min.round(2) }
+    rescue SystemCallError, ArgumentError
+      nil
+    end
+
+    private
+
+    def readable_format?(file)
+      %w[txt md markdown csv json pdf].include?(file.extension)
+    end
+  end
+end

data/lib/soft_sort/classification/context_classifier.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class ContextClassifier
+    def initialize(config)
+      projects = config.projects.map do |name, project|
+        { 'name' => "project_#{name}", 'keywords' => project['aliases'],
+          'destination' => project['destination'], 'project_destinations' => project['destinations'],
+          'priority' => project.fetch('priority', 85) }
+      end
+      @rules = (config.context_rules + projects).sort_by { |r| -r.fetch('priority', 0).to_i }
+    end
+
+    def matches(filename)
+      tokens = filename.downcase.scan(/[[:alnum:]]+/)
+      @rules.select do |r|
+        Array(r['keywords']).any? do |k|
+          tokens == k.to_s.downcase.scan(/[[:alnum:]]+/) || tokens.include?(k.to_s.downcase)
+        end
+      end
+    end
+  end
+end

data/lib/soft_sort/classification/rule_matcher.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class RuleMatcher
+    def initialize(config)
+      @config = config
+      @types = TypeClassifier.new(config)
+      @contexts = ContextClassifier.new(config)
+      @content = ContentClassifier.new(config)
+    end
+
+    def classify(file)
+      type, type_dest = @types.classify(file)
+      matches = @contexts.matches(file.filename)
+      if matches.any?
+        top = matches.first
+        tied = matches.take_while do |r|
+          r.fetch('priority', 0).to_i == top.fetch('priority', 0).to_i
+        end
+        destination = tied.length == 1 ? project_destination(top, type, type_dest) : type_dest
+        return ClassificationResult.new(type_category: type,
+                                        context_category: tied.length == 1 ? top['name'].to_s.capitalize : 'Review', destination: destination, matched_rule: tied.length == 1 ? top['name'] : 'ambiguous', confidence: tied.length == 1 ? 0.95 : 0.40, requires_review: tied.length != 1)
+      end
+      content = @content.classify(file)
+      if content
+        return ClassificationResult.new(type_category: content[:category], context_category: 'Content',
+                                        destination: content[:destination], matched_rule: content[:name],
+                                        confidence: content[:confidence], requires_review: false)
+      end
+      known = @types.known?(file)
+      ClassificationResult.new(type_category: type, context_category: nil, destination: type_dest,
+                               matched_rule: known ? "file_type_#{file.extension}" : 'unknown_file', confidence: known ? 0.80 : 0.25, requires_review: !known)
+    end
+
+    def project_destination(rule, type, fallback)
+      return rule['destination'] unless rule['project_destinations'].is_a?(Hash)
+
+      rule['project_destinations'].fetch(type, fallback)
+    end
+  end
+end

data/lib/soft_sort/classification/sensitive_file_detector.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class SensitiveFileDetector
+    PATTERNS = [
+      /(^|\.)env(?:\.|$)/i, /password|secret|credential|token|recovery[-_ ]?code/i,
+      /private[-_ ]?key|id_rsa|keystore|service[-_ ]?account/i, /\.(pem|p12|p8|key|der)$/i
+    ].freeze
+
+    def self.reason(filename)
+      PATTERNS.find { |pattern| filename.match?(pattern) } && 'possible sensitive or security credential'
+    end
+  end
+end

data/lib/soft_sort/classification/type_classifier.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class TypeClassifier
+    def initialize(config)
+      @map = config.extension_categories
+      @filename_rules = config.data.fetch('filename_types', [])
+    end
+
+    def classify(file)
+      return signature_match(file) || filename_match(file) if file.extension.empty? || !@map.key?(file.extension)
+
+      @map.fetch(file.extension)
+    end
+
+    def known?(file)
+      return true if @map.key?(file.extension)
+
+      return true if signature_match(file)
+
+      @filename_rules.any? do |item|
+        File.basename(file.filename).match?(Regexp.new(item['pattern'], Regexp::IGNORECASE))
+      rescue RegexpError
+        false
+      end
+    end
+
+    private
+
+    def signature_match(file)
+      return unless file.absolute_path && File.file?(file.absolute_path)
+
+      header = File.open(file.absolute_path, 'rb') { |stream| stream.read(32) }
+      return %w[Documents Documents] if header&.start_with?('%PDF-')
+      return %w[Archives Archives] if header&.start_with?("PK\x03\x04")
+      return ['Development Scripts', 'Projects/Source/Scripts'] if header&.start_with?('#!')
+
+      nil
+    rescue SystemCallError
+      nil
+    end
+
+    def filename_match(file)
+      rule = @filename_rules.find do |item|
+        File.basename(file.filename).match?(Regexp.new(item['pattern'], Regexp::IGNORECASE))
+      end
+      return [rule['category'], rule['destination']] if rule
+
+      @map.fetch('', %w[Others Others])
+    rescue RegexpError
+      %w[Others Others]
+    end
+  end
+end

data/lib/soft_sort/cli.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module SoftSort
+  class CLI
+    COMMANDS = %w[scan plan organize duplicates history undo recover stats explain watch].freeze
+
+    def initialize(argv)
+      @argv = argv.dup
+    end
+
+    def run
+      return puts help if @argv.empty? || %w[--help -h].include?(@argv.first)
+      return puts "SoftSort #{VERSION}" if @argv.first == 'version'
+
+      command = @argv.shift
+      raise Error, "unsupported command: #{command}" unless COMMANDS.include?(command)
+      options = parse_options
+      root = @argv.shift || '.'
+      raise Error, "unexpected arguments: #{@argv.join(' ')}" unless @argv.empty?
+      config = Configuration.load(options[:config])
+      config = override_config(config, options)
+      dispatch(command, root, config, options)
+    rescue Error, OptionParser::ParseError => e
+      warn "soft-sort: #{e.message}"
+      1
+    end
+
+    def help
+      <<~TEXT
+        Usage: soft-sort <command> DIRECTORY [options]
+          scan, plan, organize, duplicates, history, undo, recover, stats, explain, watch
+          --recursive       Include subdirectories
+          --apply           Execute approved organization moves
+          --dry-run         Preview undo/recovery operations
+          --transaction ID  Select a transaction
+          --limit NUMBER    Limit history output
+          --format FORMAT   Emit text or json
+          --config PATH     Use YAML rules
+          --date-folders    Add configured date folders to destinations
+          --inspect-content Enable bounded local content evidence
+          --collision POLICY  Use skip, review, or rename collision handling
+          --interval SECONDS  Polling interval for watch mode
+      TEXT
+    end
+
+    private
+
+    def parse_options
+      options = { recursive: false, format: 'text', config: nil, apply: false, dry_run: false, transaction: nil, limit: nil, verbose: false,
+                  date_folders: false, inspect_content: false, collision: nil, interval: 5 }
+      parser = OptionParser.new do |o|
+        o.on('--recursive') { options[:recursive] = true }
+        o.on('--apply') { options[:apply] = true }
+        o.on('--dry-run') { options[:dry_run] = true }
+        o.on('--transaction ID') { |v| options[:transaction] = v }
+        o.on('--limit NUMBER', Integer) { |v| options[:limit] = v }
+        o.on('--format FORMAT') { |v| options[:format] = v }
+        o.on('--config PATH') { |v| options[:config] = v }
+        o.on('--verbose') { options[:verbose] = true }
+        o.on('--date-folders') { options[:date_folders] = true }
+        o.on('--inspect-content') { options[:inspect_content] = true }
+        o.on('--collision POLICY') { |v| options[:collision] = v }
+        o.on('--interval SECONDS', Integer) { |v| options[:interval] = v }
+      end
+      parser.parse!(@argv)
+      raise Error, 'format must be text or json' unless %w[text json].include?(options[:format])
+      options
+    end
+
+    def override_config(config, options)
+      return config unless options[:date_folders] || options[:inspect_content] || options[:collision]
+
+      data = Marshal.load(Marshal.dump(config.data))
+      data['organization'] ||= {}
+      data['organization']['date_folders'] = true if options[:date_folders]
+      data['organization']['collision_policy'] = options[:collision] if options[:collision]
+      data['content_inspection'] ||= {}
+      data['content_inspection']['enabled'] = true if options[:inspect_content]
+      Configuration.new(data)
+    end
+
+    def dispatch(command, root, config, options)
+      case command
+      when 'scan', 'plan', 'organize', 'stats', 'explain'
+        scan = DirectoryScanner.new(root, config: config, recursive: options[:recursive]).scan
+        items = OrganizationPlanner.new(root, config).plan(scan[:files])
+        return output(scan_report(scan, root, items), options, text: PreviewFormatter.scan(scan_report(scan, root, items))) if command == 'scan'
+        return output(plan_report(root, items, scan[:warnings]), options, text: PreviewFormatter.plan(items)) if command == 'plan'
+        if command == 'stats'
+          duplicates = DuplicateDetector.new(root).find(scan[:files])
+          return output(StatisticsReporter.build(scan, items, duplicates: duplicates), options)
+        end
+        return explain(root, items, options) if command == 'explain'
+
+        record = Executor.new(root).execute(items, apply: options[:apply])
+        output(record, options)
+      when 'duplicates'
+        scan = DirectoryScanner.new(root, config: config, recursive: options[:recursive]).scan
+        output(DuplicateDetector.new(root).find(scan[:files]), options)
+      when 'history'
+        records = TransactionJournal.new(root).all
+        records = records.last(options[:limit]) if options[:limit]
+        output(records, options)
+      when 'recover'
+        reports = if options[:apply]
+                    RecoveryManager.new(root).apply(transaction_id: options[:transaction])
+                  else
+                    RecoveryManager.new(root).inspect(transaction_id: options[:transaction])
+                  end
+        output(reports, options, text: recovery_text(reports, options[:apply]))
+      when 'undo'
+        result = UndoManager.new(root).undo(transaction_id: options[:transaction], dry_run: options[:dry_run])
+        output(result, options)
+      when 'watch'
+        watcher = DirectoryWatcher.new(root, config: config, recursive: options[:recursive], interval: options[:interval])
+        watcher.run(apply: options[:apply]) do |items, apply|
+          if apply
+            output(Executor.new(root).execute(items, apply: true), options)
+          else
+            output({ root: File.expand_path(root), files: items }, options, text: PreviewFormatter.plan(items))
+          end
+        end
+      end
+    end
+
+    def scan_report(scan, root, items)
+      eligible = scan[:files].select(&:eligible)
+      { root: File.expand_path(root), total: scan[:files].length, eligible: eligible.length,
+        excluded: scan[:files].length - eligible.length, bytes: eligible.sum(&:size), warnings: scan[:warnings],
+        categories: items.group_by { |item| item[:type_category] }.transform_values(&:length) }
+    end
+
+    def plan_report(root, items, warnings)
+      { root: File.expand_path(root), files: items, warnings: warnings }
+    end
+
+    def explain(root, items, options)
+      item = items.first
+      raise Error, 'no eligible files found' unless item
+      output(item.merge(root: File.expand_path(root)), options)
+    end
+
+    def recovery_text(reports, applied)
+      return 'No incomplete transactions require recovery.' if reports.empty?
+
+      lines = ['SoftSort Recovery Preview', '']
+      reports.each do |report|
+        lines << "Transaction: #{report['transaction']}"
+        lines << "Status: #{report['status']}"
+        lines << "Completed: #{report['completed']}"
+        lines << "Pending: #{report['pending']}"
+        lines << "Conflicts: #{report['conflicts']}"
+        lines << "Recoverable: #{report['recoverable']}"
+      end
+      lines << (applied ? 'Recovery actions applied.' : 'No files were modified.')
+      lines.join("\n")
+    end
+
+    def output(value, options, text: nil)
+      if options[:format] == 'json'
+        puts JsonReporter.dump(value)
+      else
+        puts(text || (value.is_a?(Hash) ? value.map { |k, v| "#{k}: #{v}" }.join("\n") : value))
+      end
+    end
+  end
+end