Composable command chaining: auto-pass folder between extract/compare/organize

[djdarcy]

Composable command chaining: auto-pass folder between extract/compare/organize

Problem

The primary workflow requires users to manually copy-paste the output folder path between three commands:

notepad-cleanup extract
# Output: C:\Users\Extreme\Desktop\notepad-cleanup-2026-03-15_07-13-30

# User must copy-paste the path:
notepad-cleanup compare "C:\Users\Extreme\Desktop\notepad-cleanup-2026-03-15_07-13-30" -s "..."

# And again:
notepad-cleanup organize "C:\Users\Extreme\Desktop\notepad-cleanup-2026-03-15_07-13-30"

This friction is unnecessary -- extract knows the output path, and the subsequent commands need exactly that path. The existing run command already chains extract->organize internally, but uses a fragile "find most recent folder on Desktop" heuristic that doesn't account for custom output dirs or additional search directories.

Similarly, --search-dirs and --diff-tool must be re-specified on every invocation despite being stable user preferences.

Proposed solution

Two complementary mechanisms:

1. Config-based state persistence (~/.notepad-cleanup.json):

{
  "last_extract": "C:\\Users\\Extreme\\Desktop\\notepad-cleanup-2026-03-15_07-13-30",
  "search_dirs": ["C:\\Users\\Extreme\\Desktop\\Notepad Organize"],
  "diff_tool": "bcomp"
}

After extract completes, it saves last_extract to config. Then compare and organize can be called with no positional argument -- they read from config and print what they're using:

notepad-cleanup extract
# Saved last extraction path to config.

notepad-cleanup compare
# Using last extraction: C:\...\notepad-cleanup-2026-03-15_07-13-30
# Using saved search dirs: C:\Users\Extreme\Desktop\Notepad Organize

notepad-cleanup organize
# Using last extraction: C:\...\notepad-cleanup-2026-03-15_07-13-30

2. Extended run command with --compare and --pause:

notepad-cleanup run --compare --pause --diff
# Runs: extract -> compare (with saved search dirs) -> [pauses for user review] -> organize

3. New config command for persistent preferences:

notepad-cleanup config --search-dir "C:\Users\Extreme\Desktop\Notepad Organize"
notepad-cleanup config --diff-tool bcomp
notepad-cleanup config --show   # display current config

Config persistence design

The config file (~/.notepad-cleanup.json) already exists from the diff-tool work in dedup.py (load_config()/save_config()). This extends it with:

Key	Set by	Used by	Example
last_extract	extract (auto)	compare, organize	"C:\\...\\notepad-cleanup-2026-..."
search_dirs	config --search-dir	compare	["C:\\...\\Notepad Organize"]
diff_tool	config --diff-tool	compare --diff	"bcomp"

When FOLDER is provided explicitly, it overrides last_extract. The config value is a fallback, not a mandate.

Implementation approach

Phase 1 (this issue):

• Make FOLDER argument optional on compare and organize (fallback to last_extract)
• extract saves last_extract to config after successful save
• Add config subcommand for --search-dir, --diff-tool, --show
• Extend run with --compare and --pause flags

Files affected:

• notepad_cleanup/cli.py -- optional FOLDER, config command, run extension
• notepad_cleanup/dedup.py -- extend load_config()/save_config() (already exist)
• notepad_cleanup/saver.py -- save last_extract after extraction

Acceptance criteria

• notepad-cleanup extract saves last_extract path to ~/.notepad-cleanup.json
• notepad-cleanup compare with no FOLDER arg reads last_extract from config
• notepad-cleanup organize with no FOLDER arg reads last_extract from config
• Both commands print "Using last extraction: ..." when reading from config
• Explicit FOLDER argument overrides config value
• notepad-cleanup config --search-dir PATH persists to config
• notepad-cleanup config --diff-tool NAME persists to config
• notepad-cleanup config --show displays current config
• notepad-cleanup run --compare chains extract -> compare -> organize
• notepad-cleanup run --compare --pause pauses after compare for user review
• Error message when no FOLDER provided and no last_extract in config

Related issues

• Refs Pre-organize deduplication: diff new notes against previous sessions and link duplicates #9 -- deduplication feature that introduced the compare command and the three-step workflow
• Refs Support additional AI CLI backends (OpenAI Codex CLI, Gemini CLI, etc.) #6 -- multi-backend support may also benefit from config persistence

Analysis

See 2026-03-15__07-12-44__composable-command-chaining.md for detailed analysis.

[djdarcy]

Design note: configured base paths with shorthand expansion

In addition to --last and config-based defaults, consider a base path shorthand system where users configure named base directories and reference them with a short notation in CLI arguments.

Concept

Users configure common base paths once:

{
  "bases": [
    "C:\\Users\\Extreme\\Desktop",
    "C:\\Users\\Extreme\\Desktop\\Notepad Organize"
  ]
}

Then reference them inline in any path argument using a shorthand (notation TBD -- ..., @0, ~nc, etc.):

# Shorthand expands to full base path inline
notepad-cleanup compare "<base0>\notepad-cleanup-2026-03-15_07-13-30" -s <base1>

Why this is interesting

• Extends the . (here) / .. (parent) mental model to "configured home bases"
• Works as a path prefix (inline expansion), not just a standalone flag
• More general than --last -- solves path friction for any command, not just "most recent"
• Shorthand tokens won't collide with real filenames
• Shells don't expand them, so they pass through cleanly to Python

Open questions

• Exact notation: ... / ...1 (extends dot convention), @base / @1 (explicit), or something else?
• Should this be a notepad-cleanup feature or a shared DazzleTools concept (usable across projects)?
• How does it interact with --last? Complementary (different purposes) or redundant?

Notation decision deferred -- the concept is worth implementing regardless of syntax.

[djdarcy]

Design rules for ... expansion in config set

Two hard rules for the config set command when ... appears in values:

Rule 1: Always resolve to literal

When a user runs config set search_dirs "...\..\Documents\NotepadOrganize":

1. Expand ... to the current configured base path (e.g., C:\Users\Extreme\Desktop)
2. Join with the rest of the path (\..\Documents\NotepadOrganize)
3. Resolve to absolute (C:\Users\Extreme\Documents\NotepadOrganize)
4. Store the resolved absolute path in config

The literal string ... is NEVER stored in ~/.notepad-cleanup.json. This prevents circular/recursive definitions. The ... token is always a read-time expansion, never a stored value.

Rule 2: Validate path exists or offer to create

When config set receives a directory path:

• If the path exists: store it
• If it doesn't exist: prompt "Directory does not exist. Create it? [Y/n]"
• If user says yes: mkdir -p and store
• If user says no: store anyway (they might create it later) but warn

Where expansion happens vs. doesn't

Context	... behavior
config set key value	Expand to literal, store resolved path
compare FOLDER	Expand at runtime
compare -s DIR	Expand at runtime
diff FOLDER	Expand at runtime
organize FOLDER	Expand at runtime
~/.notepad-cleanup.json	Never contains ...