update

src/cli.rs

@@ -1,12 +1,15 @@
 // src/cli.rs
 use std::path::PathBuf;
-
 use clap::{Parser, Subcommand};
 
 /// Marlin – metadata-driven file explorer (CLI utilities)
 #[derive(Parser, Debug)]
 #[command(author, version, about)]
 pub struct Cli {
+    /// Enable debug logging and extra output
+    #[arg(long)]
+    pub verbose: bool,
+
     #[command(subcommand)]
     pub command: Commands,
 }

src/db/migrations.sql

@@ -1,61 +0,0 @@
-PRAGMA foreign_keys = ON;
-
--- ─── core tables ───────────────────────────────────────────────────────
-CREATE TABLE IF NOT EXISTS files (
-    id    INTEGER PRIMARY KEY,
-    path  TEXT NOT NULL UNIQUE,
-    size  INTEGER,
-    mtime INTEGER
-);
-
-CREATE TABLE IF NOT EXISTS tags (
-    id            INTEGER PRIMARY KEY,
-    name          TEXT NOT NULL UNIQUE,
-    parent_id     INTEGER REFERENCES tags(id),
-    canonical_id  INTEGER REFERENCES tags(id)
-);
-
-CREATE TABLE IF NOT EXISTS file_tags (
-    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
-    tag_id  INTEGER NOT NULL REFERENCES tags(id)  ON DELETE CASCADE,
-    PRIMARY KEY (file_id, tag_id)
-);
-
-CREATE TABLE IF NOT EXISTS attributes (
-    id      INTEGER PRIMARY KEY,
-    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
-    key     TEXT NOT NULL,
-    value   TEXT
-);
-
--- optional free-form JSON metadata
-CREATE TABLE IF NOT EXISTS json_meta (
-    file_id INTEGER PRIMARY KEY REFERENCES files(id) ON DELETE CASCADE,
-    data    TEXT                -- arbitrary JSON blob
-);
-
--- ─── full-text search ──────────────────────────────────────────────────
-CREATE VIRTUAL TABLE IF NOT EXISTS files_fts
-USING fts5(
-    path,
-    content='files', content_rowid='id',
-    prefix='2 3 4 5 6 7 8 9 10'
-);
-
-CREATE TRIGGER IF NOT EXISTS files_ai AFTER INSERT ON files BEGIN
-  INSERT INTO files_fts(rowid, path) VALUES (new.id, new.path);
-END;
-CREATE TRIGGER IF NOT EXISTS files_au AFTER UPDATE ON files BEGIN
-  UPDATE files_fts SET path = new.path WHERE rowid = new.id;
-END;
-CREATE TRIGGER IF NOT EXISTS files_ad AFTER DELETE ON files BEGIN
-  DELETE FROM files_fts WHERE rowid = old.id;
-END;
-
--- ─── version table for incremental migrations ─────────────────────────
-CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY);
-
--- ─── useful indexes ────────────────────────────────────────────────────
-CREATE INDEX IF NOT EXISTS idx_files_path        ON files(path);
-CREATE INDEX IF NOT EXISTS idx_file_tags_tag_id  ON file_tags(tag_id);
-CREATE INDEX IF NOT EXISTS idx_attr_file_key     ON attributes(file_id, key);

src/db/migrations/0001_initial_schema.sql

@@ -0,0 +1,191 @@
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;  -- Use WAL for better concurrency
+
+-- Version 1: Initial Schema (with FTS5-backed search over paths, tags & attrs)
+
+-- Core tables
+
+CREATE TABLE IF NOT EXISTS files (
+    id    INTEGER PRIMARY KEY,
+    path  TEXT    NOT NULL UNIQUE,
+    size  INTEGER,
+    mtime INTEGER,
+    hash  TEXT    -- file content hash (e.g. SHA256)
+);
+
+CREATE TABLE IF NOT EXISTS tags (
+    id           INTEGER PRIMARY KEY,
+    name         TEXT    NOT NULL,           -- tag segment
+    parent_id    INTEGER REFERENCES tags(id) ON DELETE CASCADE,
+    canonical_id INTEGER REFERENCES tags(id) ON DELETE SET NULL,
+    UNIQUE(name, parent_id)
+);
+
+CREATE TABLE IF NOT EXISTS file_tags (
+    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    tag_id  INTEGER NOT NULL REFERENCES tags(id) ON DELETE CASCADE,
+    PRIMARY KEY(file_id, tag_id)
+);
+
+CREATE TABLE IF NOT EXISTS attributes (
+    id      INTEGER PRIMARY KEY,
+    file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+    key     TEXT    NOT NULL,
+    value   TEXT,
+    UNIQUE(file_id, key)
+);
+
+-- Full-text search
+
+-- Drop any old FTS table, then recreate it as a contentless standalone table
+DROP TABLE IF EXISTS files_fts;
+CREATE VIRTUAL TABLE files_fts
+USING fts5(
+    path,                     -- Remove UNINDEXED to enable path searching
+    tags_text,                -- concat of all tag names for this file
+    attrs_text,               -- concat of all key=value attrs
+    content='',               -- Explicitly mark as contentless
+    tokenize="unicode61 remove_diacritics 2"
+);
+
+-- FTS-sync triggers
+
+-- When a file is added
+DROP TRIGGER IF EXISTS files_fts_ai_file;
+CREATE TRIGGER files_fts_ai_file
+AFTER INSERT ON files
+BEGIN
+    INSERT INTO files_fts(rowid, path, tags_text, attrs_text)
+    VALUES (
+        NEW.id, -- Sets files_fts.rowid to files.id
+        NEW.path,
+        (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+           FROM file_tags ft
+           JOIN tags t ON ft.tag_id = t.id
+          WHERE ft.file_id = NEW.id),
+        (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+           FROM attributes a
+          WHERE a.file_id = NEW.id)
+    );
+END;
+
+-- When a file’s path changes
+DROP TRIGGER IF EXISTS files_fts_au_file;
+CREATE TRIGGER files_fts_au_file
+AFTER UPDATE OF path ON files
+BEGIN
+    UPDATE files_fts
+       SET path = NEW.path
+     WHERE rowid = NEW.id; -- rowid refers to files_fts.rowid which matches files.id
+END;
+
+-- When a file is removed
+DROP TRIGGER IF EXISTS files_fts_ad_file;
+CREATE TRIGGER files_fts_ad_file
+AFTER DELETE ON files
+BEGIN
+    DELETE FROM files_fts WHERE rowid = OLD.id; -- OLD.id from files table
+END;
+
+-- When tags are added, replace the entire FTS row
+DROP TRIGGER IF EXISTS file_tags_fts_ai;
+CREATE TRIGGER file_tags_fts_ai
+AFTER INSERT ON file_tags
+BEGIN
+    INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+           (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+              FROM file_tags ft
+              JOIN tags t ON ft.tag_id = t.id
+             WHERE ft.file_id = f.id),
+           (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+              FROM attributes a
+             WHERE a.file_id = f.id)
+      FROM files f
+     WHERE f.id = NEW.file_id;
+END;
+
+-- When tags are removed, replace the entire FTS row
+DROP TRIGGER IF EXISTS file_tags_fts_ad;
+CREATE TRIGGER file_tags_fts_ad
+AFTER DELETE ON file_tags
+BEGIN
+    INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+           (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+              FROM file_tags ft
+              JOIN tags t ON ft.tag_id = t.id
+             WHERE ft.file_id = f.id),
+           (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+              FROM attributes a
+             WHERE a.file_id = f.id)
+      FROM files f
+     WHERE f.id = OLD.file_id;
+END;
+
+-- When attributes are added, replace the entire FTS row
+DROP TRIGGER IF EXISTS attributes_fts_ai;
+CREATE TRIGGER attributes_fts_ai
+AFTER INSERT ON attributes
+BEGIN
+    INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+           (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+              FROM file_tags ft
+              JOIN tags t ON ft.tag_id = t.id
+             WHERE ft.file_id = f.id),
+           (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+              FROM attributes a
+             WHERE a.file_id = f.id)
+      FROM files f
+     WHERE f.id = NEW.file_id;
+END;
+
+-- When attribute values change, replace the entire FTS row
+DROP TRIGGER IF EXISTS attributes_fts_au;
+CREATE TRIGGER attributes_fts_au
+AFTER UPDATE OF value ON attributes
+BEGIN
+    INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+           (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+              FROM file_tags ft
+              JOIN tags t ON ft.tag_id = t.id
+             WHERE ft.file_id = f.id),
+           (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+              FROM attributes a
+             WHERE a.file_id = f.id)
+      FROM files f
+     WHERE f.id = NEW.file_id;
+END;
+
+-- When attributes are removed, replace the entire FTS row
+DROP TRIGGER IF EXISTS attributes_fts_ad;
+CREATE TRIGGER attributes_fts_ad
+AFTER DELETE ON attributes
+BEGIN
+    INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+           (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+              FROM file_tags ft
+              JOIN tags t ON ft.tag_id = t.id
+             WHERE ft.file_id = f.id),
+           (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+              FROM attributes a
+             WHERE a.file_id = f.id)
+      FROM files f
+     WHERE f.id = OLD.file_id;
+END;
+
+-- Versioning & helpful indexes
+
+CREATE TABLE IF NOT EXISTS schema_version (
+    version    INTEGER PRIMARY KEY,
+    applied_on TEXT    NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_files_path       ON files(path);
+CREATE INDEX IF NOT EXISTS idx_files_hash       ON files(hash);
+CREATE INDEX IF NOT EXISTS idx_tags_name_parent ON tags(name, parent_id);
+CREATE INDEX IF NOT EXISTS idx_file_tags_tag_id ON file_tags(tag_id);
+CREATE INDEX IF NOT EXISTS idx_attr_file_key    ON attributes(file_id, key);

src/db/migrations/0002_update_fts_and_triggers.sql

@@ -0,0 +1,91 @@
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;  -- Use WAL for better concurrency
+
+-- Drop old FTS5 triggers so we can fully replace the row on tag/attr changes
+DROP TRIGGER IF EXISTS file_tags_fts_ai;
+DROP TRIGGER IF EXISTS file_tags_fts_ad;
+DROP TRIGGER IF EXISTS attributes_fts_ai;
+DROP TRIGGER IF EXISTS attributes_fts_au;
+DROP TRIGGER IF EXISTS attributes_fts_ad;
+
+-- Recreate triggers with INSERT OR REPLACE to ensure full reindex:
+
+CREATE TRIGGER file_tags_fts_ai
+AFTER INSERT ON file_tags
+BEGIN
+  INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+      (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+         FROM file_tags ft
+         JOIN tags t ON ft.tag_id = t.id
+        WHERE ft.file_id = f.id),
+      (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+         FROM attributes a
+        WHERE a.file_id = f.id)
+    FROM files f
+   WHERE f.id = NEW.file_id;
+END;
+
+CREATE TRIGGER file_tags_fts_ad
+AFTER DELETE ON file_tags
+BEGIN
+  INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+      (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+         FROM file_tags ft
+         JOIN tags t ON ft.tag_id = t.id
+        WHERE ft.file_id = f.id),
+      (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+         FROM attributes a
+        WHERE a.file_id = f.id)
+    FROM files f
+   WHERE f.id = OLD.file_id;
+END;
+
+CREATE TRIGGER attributes_fts_ai
+AFTER INSERT ON attributes
+BEGIN
+  INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+      (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+         FROM file_tags ft
+         JOIN tags t ON ft.tag_id = t.id
+        WHERE ft.file_id = f.id),
+      (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+         FROM attributes a
+        WHERE a.file_id = f.id)
+    FROM files f
+   WHERE f.id = NEW.file_id;
+END;
+
+CREATE TRIGGER attributes_fts_au
+AFTER UPDATE OF value ON attributes
+BEGIN
+  INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+      (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+         FROM file_tags ft
+         JOIN tags t ON ft.tag_id = t.id
+        WHERE ft.file_id = f.id),
+      (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+         FROM attributes a
+        WHERE a.file_id = f.id)
+    FROM files f
+   WHERE f.id = NEW.file_id;
+END;
+
+CREATE TRIGGER attributes_fts_ad
+AFTER DELETE ON attributes
+BEGIN
+  INSERT OR REPLACE INTO files_fts(rowid, path, tags_text, attrs_text)
+    SELECT f.id, f.path,
+      (SELECT IFNULL(GROUP_CONCAT(t.name, ' '), '')
+         FROM file_tags ft
+         JOIN tags t ON ft.tag_id = t.id
+        WHERE ft.file_id = f.id),
+      (SELECT IFNULL(GROUP_CONCAT(a.key || '=' || a.value, ' '), '')
+         FROM attributes a
+        WHERE a.file_id = f.id)
+    FROM files f
+   WHERE f.id = OLD.file_id;
+END;

src/db/mod.rs

@@ -4,53 +4,94 @@ use std::{
     path::{Path, PathBuf},
 };
 
-use anyhow::Result;
+use anyhow::{Context, Result};
 use chrono::Local;
 use rusqlite::{
     backup::{Backup, StepResult},
-    params, Connection, OpenFlags,
+    params,
+    Connection,
+    OpenFlags,
+    OptionalExtension,
 };
+use tracing::{debug, info};
 
-const MIGRATIONS_SQL: &str = include_str!("migrations.sql");
+/// Embed every numbered migration file here.
+const MIGRATIONS: &[(&str, &str)] = &[
+    ("0001_initial_schema.sql", include_str!("migrations/0001_initial_schema.sql")),
+    ("0002_update_fts_and_triggers.sql", include_str!("migrations/0002_update_fts_and_triggers.sql")),
+];
+
+/* ─── connection bootstrap ──────────────────────────────────────────── */
 
-/// Open (or create) the DB, apply migrations, add any missing columns,
-/// and rebuild the FTS index if needed.
 pub fn open<P: AsRef<Path>>(db_path: P) -> Result<Connection> {
-    let conn = Connection::open(&db_path)?;
+    let db_path_ref = db_path.as_ref();
+    let mut conn = Connection::open(db_path_ref)
+        .with_context(|| format!("failed to open DB at {}", db_path_ref.display()))?;
+
     conn.pragma_update(None, "journal_mode", "WAL")?;
-    conn.execute_batch(MIGRATIONS_SQL)?;
+    conn.pragma_update(None, "foreign_keys", "ON")?;
 
-    // example of dynamic column addition: files.hash TEXT
-    ensure_column(&conn, "files", "hash", "TEXT")?;
+    // Apply migrations
+    apply_migrations(&mut conn)?;
 
-    // ensure FTS picks up tokenizer / prefix changes
-    conn.execute("INSERT INTO files_fts(files_fts) VALUES('rebuild')", [])?;
     Ok(conn)
 }
 
-/// Add a column if it does not already exist.
-fn ensure_column(conn: &Connection, table: &str, col: &str, ddl_type: &str) -> Result<()> {
-    // PRAGMA table_info returns rows with (cid, name, type, ...)
-    let mut exists = false;
-    let mut stmt = conn.prepare(&format!("PRAGMA table_info({table});"))?;
-    let rows = stmt.query_map([], |row| row.get::<_, String>(1))?;
-    for name in rows.flatten() {
-        if name == col {
-            exists = true;
-            break;
-        }
-    }
+/* ─── migration runner ──────────────────────────────────────────────── */
 
-    if !exists {
-        conn.execute(
-            &format!("ALTER TABLE {table} ADD COLUMN {col} {ddl_type};"),
-            [],
+fn apply_migrations(conn: &mut Connection) -> Result<()> {
+    conn.execute_batch(
+        "CREATE TABLE IF NOT EXISTS schema_version (
+             version     INTEGER PRIMARY KEY,
+             applied_on  TEXT NOT NULL
+         );",
+    )?;
+
+    // legacy patch (ignore if already exists)
+    let _ = conn.execute("ALTER TABLE schema_version ADD COLUMN applied_on TEXT", []);
+
+    let tx = conn.transaction()?;
+    for (fname, sql) in MIGRATIONS {
+        let version: i64 = fname
+            .split('_')
+            .next()
+            .and_then(|s| s.parse().ok())
+            .expect("migration filenames start with number");
+
+        let already: Option<i64> = tx
+            .query_row(
+                "SELECT version FROM schema_version WHERE version = ?1",
+                [version],
+                |r| r.get(0),
+            )
+            .optional()?;
+
+        if already.is_some() {
+            debug!("migration {fname} already applied");
+            continue;
+        }
+
+        info!("applying migration {fname}");
+        // For debugging:
+        println!(
+            "\nSQL SCRIPT FOR MIGRATION: {}\nBEGIN SQL >>>\n{}\n<<< END SQL\n",
+            fname, sql
+        );
+
+        tx.execute_batch(sql)
+            .with_context(|| format!("could not apply migration {fname}"))?;
+
+        tx.execute(
+            "INSERT INTO schema_version (version, applied_on) VALUES (?1, ?2)",
+            params![version, Local::now().to_rfc3339()],
         )?;
     }
+    tx.commit()?;
     Ok(())
 }
 
-/// Ensure a (possibly hierarchical) tag exists and return the leaf tag id.
+/* ─── helpers ───────────────────────────────────────────────────────── */
+
 pub fn ensure_tag_path(conn: &Connection, path: &str) -> Result<i64> {
     let mut parent: Option<i64> = None;
     for segment in path.split('/').filter(|s| !s.is_empty()) {
@@ -68,13 +109,11 @@ pub fn ensure_tag_path(conn: &Connection, path: &str) -> Result<i64> {
     parent.ok_or_else(|| anyhow::anyhow!("empty tag path"))
 }
 
-/// Look up `files.id` by absolute path.
 pub fn file_id(conn: &Connection, path: &str) -> Result<i64> {
     conn.query_row("SELECT id FROM files WHERE path = ?1", [path], |r| r.get(0))
         .map_err(|_| anyhow::anyhow!("file not indexed: {}", path))
 }
 
-/// Insert or update an attribute.
 pub fn upsert_attr(conn: &Connection, file_id: i64, key: &str, value: &str) -> Result<()> {
     conn.execute(
         r#"
@@ -87,31 +126,27 @@ pub fn upsert_attr(conn: &Connection, file_id: i64, key: &str, value: &str) -> R
     Ok(())
 }
 
-/// Create a **consistent snapshot** of the DB and return the backup path.
+/* ─── backup / restore ──────────────────────────────────────────────── */
+
 pub fn backup<P: AsRef<Path>>(db_path: P) -> Result<PathBuf> {
     let src = db_path.as_ref();
     let dir = src
         .parent()
-        .ok_or_else(|| anyhow::anyhow!("invalid DB path"))?
+        .ok_or_else(|| anyhow::anyhow!("invalid DB path: {}", src.display()))?
         .join("backups");
     fs::create_dir_all(&dir)?;
 
     let stamp = Local::now().format("%Y-%m-%d_%H-%M-%S");
     let dst = dir.join(format!("backup_{stamp}.db"));
 
-    // open connections: src read-only, dst writable
     let src_conn = Connection::open_with_flags(src, OpenFlags::SQLITE_OPEN_READ_ONLY)?;
     let mut dst_conn = Connection::open(&dst)?;
 
-    // run online backup
-    let mut bk = Backup::new(&src_conn, &mut dst_conn)?;
+    let bk = Backup::new(&src_conn, &mut dst_conn)?;
     while let StepResult::More = bk.step(100)? {}
-    // Backup finalised when `bk` is dropped.
-
     Ok(dst)
 }
 
-/// Replace the live DB file with a snapshot (caller must have closed handles).
 pub fn restore<P: AsRef<Path>>(backup_path: P, live_db_path: P) -> Result<()> {
     fs::copy(&backup_path, &live_db_path)?;
     Ok(())

src/main.rs

@@ -5,30 +5,42 @@ mod db;
 mod logging;
 mod scan;
 
-use anyhow::Result;
+use anyhow::{Context, Result};
 use clap::Parser;
-use cli::{AttrCmd, Cli, Commands};
-use glob::glob;
+use glob::Pattern;
 use rusqlite::params;
-use tracing::{error, info};
+use shellexpand;
+use shlex;
+use std::{env, path::PathBuf, process::Command};
+use tracing::{debug, error, info};
+use walkdir::WalkDir;
+
+use cli::{AttrCmd, Cli, Commands};
 
 fn main() -> Result<()> {
+    // Parse CLI and bootstrap logging
+    let args = Cli::parse();
+    if args.verbose {
+        env::set_var("RUST_LOG", "debug");
+    }
     logging::init();
 
-    let args = Cli::parse();
     let cfg = config::Config::load()?;
 
-    // snapshot unless doing an explicit backup / restore
-    if !matches!(args.command, Commands::Backup | Commands::Restore { .. }) {
-        let _ = db::backup(&cfg.db_path);
+    // Backup before any non-init, non-backup/restore command
+    if !matches!(args.command, Commands::Init | Commands::Backup | Commands::Restore { .. }) {
+        match db::backup(&cfg.db_path) {
+            Ok(path) => info!("Pre-command auto-backup created at {}", path.display()),
+            Err(e) => error!("Failed to create pre-command auto-backup: {}", e),
+        }
     }
 
-    // open database (runs migrations / dynamic column adds)
+    // Open (and migrate) the DB
     let mut conn = db::open(&cfg.db_path)?;
 
     match args.command {
         Commands::Init => {
-            info!("database initialised at {}", cfg.db_path.display());
+            info!("Database initialised at {}", cfg.db_path.display());
         }
 
         Commands::Scan { paths } => {
@@ -40,17 +52,22 @@ fn main() -> Result<()> {
             }
         }
 
-        Commands::Tag { pattern, tag_path } => apply_tag(&conn, &pattern, &tag_path)?,
+        Commands::Tag { pattern, tag_path } => {
+            apply_tag(&conn, &pattern, &tag_path)?;
+        }
 
         Commands::Attr { action } => match action {
-            // borrow the Strings so attr_set gets &str
             AttrCmd::Set { pattern, key, value } => {
-                attr_set(&conn, &pattern, &key, &value)?
+                attr_set(&conn, &pattern, &key, &value)?;
+            }
+            AttrCmd::Ls { path } => {
+                attr_ls(&conn, &path)?;
             }
-            AttrCmd::Ls { path } => attr_ls(&conn, &path)?,
         },
 
-        Commands::Search { query, exec } => run_search(&conn, &query, exec)?,
+        Commands::Search { query, exec } => {
+            run_search(&conn, &query, exec)?;
+        }
 
         Commands::Backup => {
             let path = db::backup(&cfg.db_path)?;
@@ -58,118 +75,240 @@ fn main() -> Result<()> {
         }
 
         Commands::Restore { backup_path } => {
-            drop(conn); // close handle
-            db::restore(&backup_path, &cfg.db_path)?;
-            println!("Restored from {}", backup_path.display());
+            drop(conn);
+            db::restore(&backup_path, &cfg.db_path)
+                .with_context(|| format!("Failed to restore DB from {}", backup_path.display()))?;
+            println!("Restored DB file from {}", backup_path.display());
+            db::open(&cfg.db_path)
+                .with_context(|| format!("Could not open restored DB at {}", cfg.db_path.display()))?;
+            info!("Successfully opened and processed restored database.");
         }
     }
 
     Ok(())
 }
 
-/* ─── tagging ────────────────────────────────────────────────────────── */
+/// Apply a hierarchical tag to all files matching the glob pattern.
 fn apply_tag(conn: &rusqlite::Connection, pattern: &str, tag_path: &str) -> Result<()> {
     let tag_id = db::ensure_tag_path(conn, tag_path)?;
+    let expanded = shellexpand::tilde(pattern).into_owned();
+    let pat = Pattern::new(&expanded)
+        .with_context(|| format!("Invalid glob pattern `{}`", expanded))?;
+    let root = determine_scan_root(&expanded);
+
     let mut stmt_file = conn.prepare("SELECT id FROM files WHERE path = ?1")?;
     let mut stmt_insert =
         conn.prepare("INSERT OR IGNORE INTO file_tags(file_id, tag_id) VALUES (?1, ?2)")?;
 
-    for entry in glob(pattern)? {
-        match entry {
-            Ok(path) => {
-                let path_str = path.to_string_lossy();
-                if let Ok(file_id) =
-                    stmt_file.query_row(params![path_str], |row| row.get::<_, i64>(0))
-                {
-                    stmt_insert.execute(params![file_id, tag_id])?;
+    let mut count = 0;
+    for entry in WalkDir::new(&root)
+        .into_iter()
+        .filter_map(Result::ok)
+        .filter(|e| e.file_type().is_file())
+    {
+        let path_str = entry.path().to_string_lossy();
+        debug!("testing path: {}", path_str);
+        if !pat.matches(&path_str) {
+            debug!("  → no match");
+            continue;
+        }
+        debug!("  → matched");
+
+        match stmt_file.query_row(params![path_str.as_ref()], |r| r.get::<_, i64>(0)) {
+            Ok(file_id) => {
+                if stmt_insert.execute(params![file_id, tag_id])? > 0 {
                     info!(file = %path_str, tag = tag_path, "tagged");
+                    count += 1;
                 } else {
-                    error!(file = %path_str, "file not in index – run `marlin scan` first");
+                    debug!(file = %path_str, tag = tag_path, "already tagged");
                 }
             }
-            Err(e) => error!(error = %e, "glob error"),
+            Err(rusqlite::Error::QueryReturnedNoRows) => {
+                error!(file = %path_str, "not indexed – run `marlin scan` first");
+            }
+            Err(e) => {
+                error!(file = %path_str, error = %e, "could not lookup file ID");
+            }
         }
     }
+
+    if count > 0 {
+        info!("Applied tag '{}' to {} file(s).", tag_path, count);
+    } else {
+        info!("No new files were tagged with '{}' (no matches or already tagged).", tag_path);
+    }
     Ok(())
 }
 
-/* ─── attributes ─────────────────────────────────────────────────────── */
-fn attr_set(conn: &rusqlite::Connection, pattern: &str, key: &str, value: &str) -> Result<()> {
-    for entry in glob(pattern)? {
-        match entry {
-            Ok(path) => {
-                let path_str = path.to_string_lossy();
-                let file_id = db::file_id(conn, &path_str)?;
+/// Set a key=value attribute on all files matching the glob pattern.
+fn attr_set(
+    conn: &rusqlite::Connection,
+    pattern: &str,
+    key: &str,
+    value: &str,
+) -> Result<()> {
+    let expanded = shellexpand::tilde(pattern).into_owned();
+    let pat = Pattern::new(&expanded)
+        .with_context(|| format!("Invalid glob pattern `{}`", expanded))?;
+    let root = determine_scan_root(&expanded);
+
+    let mut stmt_file = conn.prepare("SELECT id FROM files WHERE path = ?1")?;
+    let mut count = 0;
+
+    for entry in WalkDir::new(&root)
+        .into_iter()
+        .filter_map(Result::ok)
+        .filter(|e| e.file_type().is_file())
+    {
+        let path_str = entry.path().to_string_lossy();
+        debug!("testing attr path: {}", path_str);
+        if !pat.matches(&path_str) {
+            debug!("  → no match");
+            continue;
+        }
+        debug!("  → matched");
+
+        match stmt_file.query_row(params![path_str.as_ref()], |r| r.get::<_, i64>(0)) {
+            Ok(file_id) => {
                 db::upsert_attr(conn, file_id, key, value)?;
                 info!(file = %path_str, key = key, value = value, "attr set");
+                count += 1;
+            }
+            Err(rusqlite::Error::QueryReturnedNoRows) => {
+                error!(file = %path_str, "not indexed – run `marlin scan` first");
+            }
+            Err(e) => {
+                error!(file = %path_str, error = %e, "could not lookup file ID");
             }
-            Err(e) => error!(error = %e, "glob error"),
         }
     }
+
+    if count > 0 {
+        info!("Attribute '{}: {}' set on {} file(s).", key, value, count);
+    } else {
+        info!("No attributes set (no matches or not indexed).");
+    }
     Ok(())
 }
 
+/// List attributes for a given file path.
 fn attr_ls(conn: &rusqlite::Connection, path: &std::path::Path) -> Result<()> {
     let file_id = db::file_id(conn, &path.to_string_lossy())?;
-    let mut stmt = conn.prepare("SELECT key, value FROM attributes WHERE file_id = ?1")?;
-    let rows = stmt.query_map([file_id], |row| Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?)))?;
-    for row in rows {
+    let mut stmt = conn.prepare(
+        "SELECT key, value FROM attributes WHERE file_id = ?1 ORDER BY key",
+    )?;
+    for row in stmt.query_map([file_id], |r| Ok((r.get::<_, String>(0)?, r.get::<_, String>(1)?)))? {
         let (k, v) = row?;
         println!("{k} = {v}");
     }
     Ok(())
 }
 
-/* ─── search helpers ─────────────────────────────────────────────────── */
-fn run_search(conn: &rusqlite::Connection, raw: &str, exec: Option<String>) -> Result<()> {
-    let hits = search(conn, raw)?;
-
-    if hits.is_empty() && exec.is_none() {
-        eprintln!("No matches for `{}`", raw);
-        return Ok(());
-    }
-
-    if let Some(cmd_tpl) = exec {
-        for path in hits {
-            let cmd_final = if cmd_tpl.contains("{}") {
-                cmd_tpl.replace("{}", &path)
-            } else {
-                format!("{cmd_tpl} \"{path}\"")
-            };
-            let mut parts = cmd_final.splitn(2, ' ');
-            let prog = parts.next().unwrap();
-            let args = parts.next().unwrap_or("");
-            let status = std::process::Command::new(prog)
-                .args(shlex::split(args).unwrap_or_default())
-                .status()?;
-            if !status.success() {
-                error!(file = %path, "command failed");
-            }
-        }
-    } else {
-        for p in hits {
-            println!("{p}");
+/// Build and run an FTS5 search query, with optional exec.
+fn run_search(conn: &rusqlite::Connection, raw_query: &str, exec: Option<String>) -> Result<()> {
+    let mut fts_query_parts = Vec::new();
+    let parts = shlex::split(raw_query).unwrap_or_else(|| vec![raw_query.to_string()]);
+    for part in parts {
+        if ["AND", "OR", "NOT"].contains(&part.as_str()) {
+            fts_query_parts.push(part);
+        } else if let Some(tag) = part.strip_prefix("tag:") {
+            fts_query_parts.push(format!("tags_text:{}", escape_fts_query_term(tag)));
+        } else if let Some(attr) = part.strip_prefix("attr:") {
+            fts_query_parts.push(format!("attrs_text:{}", escape_fts_query_term(attr)));
+        } else {
+            fts_query_parts.push(escape_fts_query_term(&part));
         }
     }
-    Ok(())
-}
-
-fn search(conn: &rusqlite::Connection, raw: &str) -> Result<Vec<String>> {
-    let q = if raw.split_ascii_whitespace().count() == 1
-        && !raw.contains(&['"', '\'', ':', '*', '(', ')', '~', '+', '-'][..])
-    {
-        format!("{raw}*")
-    } else {
-        raw.to_string()
-    };
+    let fts_expr = fts_query_parts.join(" ");
+    debug!("Constructed FTS MATCH expression: {}", fts_expr);
 
     let mut stmt = conn.prepare(
         r#"
-        SELECT f.path FROM files_fts
-        JOIN files f ON f.rowid = files_fts.rowid
-        WHERE files_fts MATCH ?1
+        SELECT f.path
+          FROM files_fts
+          JOIN files f ON f.rowid = files_fts.rowid
+         WHERE files_fts MATCH ?1
+         ORDER BY rank
         "#,
     )?;
-    let rows = stmt.query_map([&q], |row| row.get::<_, String>(0))?;
-    Ok(rows.filter_map(Result::ok).collect())
+    let hits: Vec<String> = stmt
+        .query_map(params![fts_expr], |row| row.get(0))?
+        .filter_map(Result::ok)
+        .collect();
+
+    if let Some(cmd_tpl) = exec {
+        // Exec-on-hits logic
+        let mut ran_without_placeholder = false;
+        // If no hits and no placeholder, run once
+        if hits.is_empty() && !cmd_tpl.contains("{}") {
+            if let Some(mut parts) = shlex::split(&cmd_tpl) {
+                if !parts.is_empty() {
+                    let prog = parts.remove(0);
+                    let status = Command::new(&prog).args(&parts).status()?;
+                    if !status.success() {
+                        error!(command=%cmd_tpl, code=?status.code(), "command failed");
+                    }
+                }
+            }
+            ran_without_placeholder = true;
+        }
+        // Otherwise, run per hit
+        if !ran_without_placeholder {
+            for path in hits {
+                let quoted = shlex::try_quote(&path).unwrap_or(path.clone().into());
+                let cmd_final = if cmd_tpl.contains("{}") {
+                    cmd_tpl.replace("{}", &quoted)
+                } else {
+                    format!("{} {}", cmd_tpl, &quoted)
+                };
+                if let Some(mut parts) = shlex::split(&cmd_final) {
+                    if parts.is_empty() {
+                        continue;
+                    }
+                    let prog = parts.remove(0);
+                    let status = Command::new(&prog).args(&parts).status()?;
+                    if !status.success() {
+                        error!(file=%path, command=%cmd_final, code=?status.code(), "command failed");
+                    }
+                }
+            }
+        }
+    } else {
+        if hits.is_empty() {
+            eprintln!("No matches for query: `{}` (FTS expression: `{}`)", raw_query, fts_expr);
+        } else {
+            for p in hits {
+                println!("{}", p);
+            }
+        }
+    }
+
+    Ok(())
+}
+
+/// Quote terms for FTS when needed.
+fn escape_fts_query_term(term: &str) -> String {
+    if term.contains(|c: char| c.is_whitespace() || "-:()\"".contains(c))
+        || ["AND","OR","NOT","NEAR"].contains(&term.to_uppercase().as_str())
+    {
+        format!("\"{}\"", term.replace('"', "\"\""))  
+    } else {
+        term.to_string()
+    }
+}
+
+/// Determine a filesystem root to limit recursive walking.
+fn determine_scan_root(pattern: &str) -> PathBuf {
+    let wildcard_pos = pattern.find(|c| c == '*' || c == '?' || c == '[').unwrap_or(pattern.len());
+    let prefix = &pattern[..wildcard_pos];
+    let mut root = PathBuf::from(prefix);
+    while root.as_os_str().to_string_lossy().contains(|c| ['*','?','['].contains(&c)) {
+        if let Some(parent) = root.parent() {
+            root = parent.to_path_buf();
+        } else {
+            root = PathBuf::from(".");
+            break;
+        }
+    }
+    root
 }