Add soft delete, gc, and doctor for bookmark catalogs

* feat: add gc/restore to deleted book marks.

* feat: add doctor for mult-machine mook mark reconcilliation

* chore: version bump

* docs: updated README

Author: polymorcodeus

README.md

@@ -13,7 +13,7 @@
 
 Terminal bookmark manager with hierarchical organization (Shelf → Collection → Mark). Bookmarks are persisted as plain TOML, enabling version control, clean diffs, and [dotfile manager](https://github.com/polymorcodeus/lnk) integration. Supports both interactive TUI and non-interactive CLI modes for scripting.
 
-The roadmap includes search, lazy loading, stable identifiers, and atomic shelf-collection operations.
+Bookmarks ship with stable identifiers (`catalog_id`), full-text search (`book mark search`), atomic writes, schema migration (`book migrate`), and soft-delete recovery (`book mark restore`, `book gc`).
 
 ## Quick Demo
 
@@ -115,6 +115,8 @@ collection_desc = "language and framework docs"
 - `catalog_id` is a stable URL hash — duplicates are rejected across the entire catalog.
 - Collections are keyed by name inside the `[Collections]` table.
 - Marks are inline arrays-of-tables per collection.
+- Optional RFC3339 timestamps (`created_at`, `updated_at`, `deleted_at`) track each entity's lifecycle; `deleted_at` marks a soft-deleted mark.
+- `mark remove` soft-deletes by setting `deleted_at`; the mark is hidden from `list`/`get`/`search` until `book gc` purges it or `mark restore` brings it back.
 - `schema_version` is the on-disk data format version (`2`), independent of the tool's release version (v1.x). `book migrate` upgrades older v1 files in place.
 
 ## Commands
@@ -130,8 +132,15 @@ collection_desc = "language and framework docs"
 | `mark add <url>` | Add a bookmark (optionally non-interactive) |
 | `mark edit` | Edit an existing bookmark (TUI) |
 | `mark get` | Browse bookmarks and open one (TUI) |
-| `mark list` | List bookmarks in a collection |
-| `mark remove` | Remove a bookmark (TUI) |
+| `mark list` | List bookmarks in a collection (`--trash` lists soft-deleted) |
+| `mark search <query>` | Full-text search by title, URL, or tags |
+| `mark remove` | Soft-delete a bookmark (TUI) |
+| `mark restore` | Restore a soft-deleted bookmark (`--id`, or `--shelf`/`--collection`/`--url`) |
+| `migrate` | Upgrade v1 shelf files to the v2 schema |
+| `gc` | Purge soft-deleted marks past the retention window |
+| `index rebuild` | Rebuild the derived search index |
+| `index sync` | Reconcile the index with shelf changes |
+| `doctor` | Detect post-merge duplicates and conflicts (`--fix` auto-merges; alias `sync`) |
 | `catalog theme` | Generate `theme.json` with default TUI theme |
 | `catalog template` | Generate `template.json` with default TUI templates |
 | `catalog config` | Create the config file if missing |

VERSION

@@ -1 +1 @@
-v1.1.1
+v1.2.0

cmd/book/doctor.go

@@ -0,0 +1,168 @@
+package cmd
+
+import (
+	"fmt"
+
+	"github.com/polymorcodeus/book/internal/book"
+	"github.com/polymorcodeus/book/internal/catalog"
+)
+
+// doctor inspects the catalog for post-merge problems: duplicate marks, schema
+// drift, index staleness, and stray debris. With fix it auto-resolves merge
+// duplicates and rewrites the affected shelf files.
+func doctor(config *book.Config, fix bool) error {
+	var shelves book.BookShelves
+	if err := catalog.LoadShelves(&shelves, config); err != nil {
+		return err
+	}
+
+	var duplicates, conflicts []book.MarkConflict
+	for _, c := range shelves.DetectDuplicates() {
+		if c.TrueConflict {
+			conflicts = append(conflicts, c)
+		} else {
+			duplicates = append(duplicates, c)
+		}
+	}
+
+	v1Files, err := catalog.V1ShelfFiles(config.ShelfRoot, config.CatalogFormat)
+	if err != nil {
+		return err
+	}
+	debris, err := catalog.StrayDebris(config.ShelfRoot, config.CatalogFormat)
+	if err != nil {
+		return err
+	}
+	stale, err := indexStaleFiles(config)
+	if err != nil {
+		return err
+	}
+
+	report := doctorReport{
+		Duplicates: duplicates,
+		Conflicts:  conflicts,
+		V1Files:    v1Files,
+		Debris:     debris,
+		Stale:      stale,
+	}
+
+	if fix {
+		if !config.Autoconfirm {
+			return fmt.Errorf("set --confirm to fix merge duplicates")
+		}
+		removed, changed := shelves.ResolveDuplicates()
+		report.Fixed = removed
+		for _, s := range changed {
+			if err := catalog.UpdateShelfFile(s); err != nil {
+				return err
+			}
+			report.FixedFiles = append(report.FixedFiles, s.FilePath)
+		}
+		// Only reconcile the index when no duplicate IDs remain: the index's
+		// primary key on catalog_id cannot represent unresolved conflicts.
+		if len(changed) > 0 && len(shelves.DetectDuplicates()) == 0 {
+			if _, err := syncIndex(config); err != nil {
+				return err
+			}
+		}
+	}
+
+	printDoctorReport(report)
+	return nil
+}
+
+// indexStaleFiles returns shelf paths whose index entries are out of date, or
+// nil when the index has not been built yet.
+func indexStaleFiles(config *book.Config) ([]string, error) {
+	exists, err := catalog.VerifyExists(catalog.IndexPath(config))
+	if err != nil {
+		return nil, err
+	}
+	if !exists {
+		return nil, nil
+	}
+
+	idx, err := catalog.OpenIndex(config)
+	if err != nil {
+		return nil, err
+	}
+	defer func() { _ = idx.Close() }()
+	return idx.StaleFiles(config)
+}
+
+type doctorReport struct {
+	Duplicates []book.MarkConflict
+	Conflicts  []book.MarkConflict
+	V1Files    []string
+	Debris     []string
+	Stale      []string
+	Fixed      int
+	FixedFiles []string
+}
+
+func printDoctorReport(r doctorReport) {
+	clean := len(r.Duplicates) == 0 && len(r.Conflicts) == 0 &&
+		len(r.V1Files) == 0 && len(r.Debris) == 0 && len(r.Stale) == 0 && r.Fixed == 0
+
+	fmt.Println("book doctor")
+	fmt.Println()
+
+	if clean {
+		fmt.Println("catalog is clean")
+		return
+	}
+
+	if len(r.Duplicates) > 0 {
+		fmt.Printf("duplicate marks (%d)\n", len(r.Duplicates))
+		for _, d := range r.Duplicates {
+			fmt.Printf("  %s  %s  (%d copies)\n", d.ID, d.URL, len(d.Marks))
+			for _, m := range d.Marks {
+				fmt.Printf("    - %s / %s\n", m.Shelf.Name, m.Collection.Name)
+			}
+		}
+		if r.Fixed == 0 {
+			fmt.Println("  run `book doctor --fix` to auto-merge these")
+		}
+		fmt.Println()
+	}
+
+	if len(r.Conflicts) > 0 {
+		fmt.Printf("conflicting marks (%d, manual resolution needed)\n", len(r.Conflicts))
+		for _, c := range r.Conflicts {
+			fmt.Printf("  %s  %s\n", c.ID, c.URL)
+			for _, m := range c.Marks {
+				fmt.Printf("    - %s / %s  title=%q tags=%v deleted=%t\n",
+					m.Shelf.Name, m.Collection.Name, m.Name, m.Tags, m.IsDeleted())
+			}
+		}
+		fmt.Println()
+	}
+
+	if len(r.V1Files) > 0 {
+		fmt.Println("v1 schema files (run `book migrate`)")
+		for _, f := range r.V1Files {
+			fmt.Printf("  %s\n", f)
+		}
+		fmt.Println()
+	}
+
+	if len(r.Stale) > 0 {
+		fmt.Println("stale index entries (run `book index sync`)")
+		for _, f := range r.Stale {
+			fmt.Printf("  %s\n", f)
+		}
+		fmt.Println()
+	}
+
+	if len(r.Debris) > 0 {
+		fmt.Println("stray debris")
+		for _, f := range r.Debris {
+			fmt.Printf("  %s\n", f)
+		}
+		fmt.Println()
+	}
+
+	if r.Fixed > 0 {
+		fmt.Printf("fixed: removed %d duplicate mark(s) from %d shelf file(s)\n", r.Fixed, len(r.FixedFiles))
+	}
+}

cmd/book/gc.go

@@ -0,0 +1,51 @@
+package cmd
+
+import (
+	"fmt"
+	"time"
+
+	"github.com/polymorcodeus/book/internal/book"
+	"github.com/polymorcodeus/book/internal/catalog"
+)
+
+// gc purges soft-deleted marks older than retentionDays from the shelf TOML
+// files and reconciles the derived index.
+func gc(config *book.Config, retentionDays int) error {
+	if !config.Autoconfirm {
+		return fmt.Errorf("set --confirm to run gc")
+	}
+	if retentionDays < 0 {
+		return fmt.Errorf("--retention-days must be non-negative")
+	}
+
+	var shelves book.BookShelves
+	if err := catalog.LoadShelves(&shelves, config); err != nil {
+		return err
+	}
+
+	cutoff := time.Now().UTC().AddDate(0, 0, -retentionDays)
+
+	var purged, changed int
+	for i := range shelves {
+		shelf := &shelves[i]
+		n := shelf.PurgeDeletedMarks(cutoff)
+		if n == 0 {
+			continue
+		}
+		if err := catalog.UpdateShelfFile(shelf); err != nil {
+			return err
+		}
+		purged += n
+		changed++
+	}
+
+	if changed > 0 {
+		// Reconcile the derived index so purged marks disappear from search.
+		if _, err := syncIndex(config); err != nil {
+			return err
+		}
+	}
+
+	fmt.Printf("purged %d mark(s) from %d shelf(s)\n", purged, changed)
+	return nil
+}

cmd/book/main.go

@@ -73,6 +73,11 @@ func Main() {
 	var markTags string
 	var markTitle string
 	var searchTags string
+	var restoreURL string
+	var restoreID string
+	var trash bool
+	var retentionDays int
+	var fix bool
 
 	cmd := &cli.Command{
 		Name:                  "book",
@@ -184,8 +189,20 @@ func Main() {
 			// when only a subcommand is given (e.g. "book shelf"), urfave/cli
 			// will auto-render the help text. We skip catalog loading so help
 			// renders quickly without reading the filesystem.
+			// Load Book Shelves only for the data commands (shelf, collection,
+			// mark) and only when a subcommand is given. This skips `mark
+			// search` (which reads the SQLite index) and the catalog admin
+			// tools (migrate, gc, doctor, index, catalog), which load their
+			// own data. When only a subcommand is given (e.g. "book shelf"),
+			// urfave/cli auto-renders help, so we skip loading to keep help
+			// fast. Note the command name must be checked explicitly: a
+			// top-level tool's own flags (e.g. "doctor --fix") would otherwise
+			// leak into Args() and trigger an unwanted load.
 			isSearch := cmd.Args().First() == "mark" && cmd.Args().Get(1) == "search"
-			if cmd.Args().Len() > 1 && !isSearch {
+			needsCatalog := cmd.Args().First() == "shelf" ||
+				cmd.Args().First() == "collection" ||
+				cmd.Args().First() == "mark"
+			if cmd.Args().Len() > 1 && needsCatalog && !isSearch {
 				if err := catalog.LoadCatalog(&bookShelves, config, config.Interactive); err != nil {
 					return ctx, cli.Exit(config.StyledError(err), 1)
 				}
@@ -390,6 +407,11 @@ func Main() {
 								Usage:       "collection selection for mark",
 								Destination: &collection,
 							},
+							&cli.BoolFlag{
+								Name:        "trash",
+								Usage:       "list soft-deleted marks instead of active ones",
+								Destination: &trash,
+							},
 						},
 						Before: func(ctx context.Context, cmd *cli.Command) (context.Context, error) {
 							if !config.Interactive && format == "" {
@@ -398,7 +420,7 @@ func Main() {
 							return ctx, nil
 						},
 						Action: func(ctx context.Context, cmd *cli.Command) error {
-							if err := marks(&bookShelves, shelf, collection, format, config); err != nil {
+							if err := marks(&bookShelves, shelf, collection, format, trash, config); err != nil {
 								return cli.Exit(config.StyledError(err), 1)
 							}
 							return nil
@@ -448,6 +470,38 @@ func Main() {
 							return nil
 						},
 					},
+					{
+						Name:  "restore",
+						Usage: "restore a soft-deleted bookmark",
+						Flags: []cli.Flag{
+							&cli.StringFlag{
+								Name:        "id",
+								Usage:       "catalog_id of the trashed mark to restore (preferred)",
+								Destination: &restoreID,
+							},
+							&cli.StringFlag{
+								Name:        "shelf",
+								Usage:       "shelf containing the trashed mark",
+								Destination: &shelf,
+							},
+							&cli.StringFlag{
+								Name:        "collection",
+								Usage:       "collection containing the trashed mark",
+								Destination: &collection,
+							},
+							&cli.StringFlag{
+								Name:        "url",
+								Usage:       "url of the trashed mark to restore",
+								Destination: &restoreURL,
+							},
+						},
+						Action: func(ctx context.Context, cmd *cli.Command) error {
+							if err := restoreMark(&bookShelves, restoreID, shelf, collection, restoreURL); err != nil {
+								return cli.Exit(config.StyledError(err), 1)
+							}
+							return nil
+						},
+					},
 				},
 			},
 			{
@@ -460,6 +514,42 @@ func Main() {
 					return nil
 				},
 			},
+			{
+				Name:  "gc",
+				Usage: "purge soft-deleted marks older than the retention window",
+				Flags: []cli.Flag{
+					&cli.IntFlag{
+						Name:        "retention-days",
+						Value:       30,
+						Usage:       "purge marks soft-deleted more than this many days ago",
+						Destination: &retentionDays,
+					},
+				},
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					if err := gc(config, retentionDays); err != nil {
+						return cli.Exit(config.StyledError(err), 1)
+					}
+					return nil
+				},
+			},
+			{
+				Name:    "doctor",
+				Aliases: []string{"sync"},
+				Usage:   "detect and fix post-merge catalog problems",
+				Flags: []cli.Flag{
+					&cli.BoolFlag{
+						Name:        "fix",
+						Usage:       "auto-merge duplicate marks (requires --confirm)",
+						Destination: &fix,
+					},
+				},
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					if err := doctor(config, fix); err != nil {
+						return cli.Exit(config.StyledError(err), 1)
+					}
+					return nil
+				},
+			},
 			{
 				Name:  "index",
 				Usage: "manage the derived SQLite search index",