indytag 1.3.2 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +111 -9
  2. package/indytag.py +7138 -5233
  3. package/package.json +62 -56
package/README.md CHANGED
@@ -9,18 +9,87 @@ then act on the inventory later.
9
9
 
10
10
  One Python file, standard library only. The npm package is a thin launcher: it
11
11
  finds a Python 3 interpreter and hands it the real terminal, so the interactive
12
- selector keeps its raw-mode keys, mouse and animation. The tag/index run opens on
13
- a gold splash: rain falls the full width of the terminal, each drop adds volume
14
- where it lands, and the heap slumps under its own weight as the run advances —
15
- 24-bit colour, no dependencies, and skipped entirely for `--no-gold`, `NO_COLOR`
16
- or `INDYTAG_NO_GOLD`.
12
+ selector keeps its raw-mode keys, mouse and animation.
17
13
 
18
14
  ```sh
19
15
  npm i -g indytag
20
- # or: npm i -g @agnamo/indytag
21
- indytag .
16
+ indytag # the hoard screen, on the folder you are standing in
17
+ indytag . # tag + index this folder, selector first
18
+ indytag --no-select --yes # scripted run, no prompts
22
19
  ```
23
20
 
21
+ ## The hoard screen
22
+
23
+ Run `indytag` with no arguments in a terminal and it opens a full-screen,
24
+ charmbracelet-flavoured front door: rounded gold-gradient panels, a coin-rain
25
+ and molten-gold backdrop, gems glinting in the melt, and a menu floating over
26
+ it. It runs on the active root (the folder you launched it from) and never
27
+ indexes its own install directory.
28
+
29
+ | Key | Action |
30
+ |---|---|
31
+ | `↑` `↓` / `j` `k` | move |
32
+ | `Enter` | choose |
33
+ | `/` | filter the menu |
34
+ | `r` | back to the root picker |
35
+ | `q` / `Esc` / `Ctrl-C` | leave the hoard |
36
+
37
+ The menu covers: tag & index the active root, choose another root, import a
38
+ manifest/index, metadata CSV, dedupe (recycles extras), atomize (permanent),
39
+ and quit. Dangerous actions always pass through a red confirm panel.
40
+
41
+ ### Picking any folder
42
+
43
+ "Choose another root…" opens a browser that starts at the active root but is
44
+ never trapped there:
45
+
46
+ | Key | Action |
47
+ |---|---|
48
+ | `↑` `↓` / `j` `k` | move |
49
+ | `→` `Enter` / `l` | open the folder |
50
+ | `←` `Backspace` / `h` | up one level (`..`) |
51
+ | `Space` / `o` | use the highlighted folder as the root |
52
+ | `u` | use the folder you have open |
53
+ | `s` | deep search under the current folder, by name |
54
+ | `/` | fuzzy-filter the listing |
55
+ | `d` | jump to the drive list (every drive on Windows, `/` elsewhere) |
56
+ | `r` | filesystem root |
57
+ | `~` | home |
58
+ | `c` | back to the launch folder |
59
+ | `Tab` | show/hide dotfolders |
60
+ | `q` / `Esc` | back |
61
+
62
+ Search and filter highlight the matched characters, skip `node_modules`,
63
+ `.git`, `__pycache__`, `.indytag` and friends, and stop on a time budget so a
64
+ swollen tree can never freeze the screen.
65
+
66
+ ## The gold splash
67
+
68
+ The tag/index run opens on an animated splash: rain falls the full width of the
69
+ terminal, each drop adds volume where it lands, and the heap slumps under its
70
+ own weight as the run advances — 24-bit colour, no dependencies, skipped
71
+ entirely for `--no-gold`, `NO_COLOR` or `INDYTAG_NO_GOLD`.
72
+
73
+ ## Root, search, find
74
+
75
+ The root defaults to the **active root**: the folder you ran the tool from.
76
+ It is never the folder `indytag.py` lives in, so a global install or an
77
+ `npx`/`npm exec` run indexes what you meant.
78
+
79
+ ```sh
80
+ indytag # active root (cwd)
81
+ indytag --root ../other # explicit folder
82
+ indytag --nearest # climb to the nearest project root (.git, .indytag, package.json, …)
83
+ indytag --find vault # hunt downward for a folder named `vault`
84
+ indytag --search invoice # open the path tree already filtered to `invoice`
85
+ indytag --tui # force the hoard screen
86
+ indytag --no-tui # never open it (pipes already skip it)
87
+ ```
88
+
89
+ `--search` is the selector's initial filter (also reachable with `/` or `s`
90
+ inside the tree); `--nearest` and `--find` decide *which folder* the run works
91
+ on.
92
+
24
93
  ## What it writes
25
94
 
26
95
  Run against a folder and it produces:
@@ -54,7 +123,7 @@ indytag . --tags project,skill,mine,yours
54
123
  ## Interactive selector
55
124
 
56
125
  ```
57
- indytag . # tag + index, selector first
126
+ indytag . # tag + index, selector first
58
127
  indytag . --no-select --yes # scripted run, no prompts
59
128
  ```
60
129
 
@@ -63,12 +132,15 @@ indytag . --no-select --yes # scripted run, no prompts
63
132
  | `Space` | tag / untag the current path with the active tag |
64
133
  | `Tab`, `1`–`9` | switch the active tag (first nine presets) |
65
134
  | `a` / `n` / `i` | tag all / clear all / invert for the active tag |
66
- | `/` | filter; `Enter` keeps it |
135
+ | `/` or `s` | search; `Enter` keeps it, `Esc` clears it |
67
136
  | `←` `→` `e` `c` | collapse, expand, expand all, collapse all |
68
137
  | `Backspace` / `0` | clear tags on the current path |
69
138
  | `Enter` | save and continue |
70
139
  | `q` / `Esc` | cancel, write nothing |
71
140
 
141
+ A faint coin-rain runs behind the tree, tag chips are inverse-gold pills, and
142
+ the footer keeps the charm help-bar shape (`SPACE tag · TAB next tag · …`).
143
+
72
144
  ## Import a previous run
73
145
 
74
146
  Point `--import` at a `manifest.json`, `index.md` or `list.csv` written by
@@ -96,6 +168,10 @@ indytag --import index.md --action recycle --pick 'build/*'
96
168
  | `dedupe` | byte-match duplicates in a scope; recycle extras |
97
169
  | `atomize` | byte-match duplicates in a scope; permanent delete extras |
98
170
 
171
+ The hoard screen can drive the same actions: pick a manifest in the browser,
172
+ then choose list / csv / zip / move / recycle / delete, with a text field for
173
+ the target and a red confirm for anything irreversible.
174
+
99
175
  ### meta
100
176
 
101
177
  One row per file. Does not need an import when you pass a scope:
@@ -130,6 +206,20 @@ counted, a nested path collapses when its ancestor is already selected,
130
206
  `--dry-run` writes nothing, and a non-interactive run needs `--yes` before
131
207
  anything is moved, recycled, deleted or atomized.
132
208
 
209
+ ## Every command, with expected output
210
+
211
+ [`COMMANDS.md`](COMMANDS.md) lists every command and flag combination with the
212
+ output it is expected to produce, generated by running them:
213
+
214
+ ```sh
215
+ python tools/commands.py # regenerates COMMANDS.md, refuses to write lies
216
+ python workshop/test_commands.py
217
+ ```
218
+
219
+ The test suite checks three layers per command: the exit code, that documented
220
+ line, and the **real filesystem effect** (files created, moved, recycled,
221
+ deleted, zipped, hashed, or provably untouched for `--dry-run`).
222
+
133
223
  ## Requirements
134
224
 
135
225
  Python 3.8 or newer on `PATH`. Override the interpreter with
@@ -139,3 +229,15 @@ Python 3.8 or newer on `PATH`. Override the interpreter with
139
229
  indytag --version
140
230
  indytag --help
141
231
  ```
232
+
233
+ ## Tests
234
+
235
+ ```sh
236
+ python workshop/test_ui_render.py # selector + chooser frames
237
+ python workshop/test_tui_fidelity.py # diff paint, ascii, narrow, mouse
238
+ python workshop/test_hoard_ui.py # hoard screen + folder picker
239
+ python workshop/test_commands.py # every command: exit, voice, effect
240
+ python workshop/test_import_e2e.py # every import format and action
241
+ python workshop/test_root_scope.py # active root, --nearest, --find, --version
242
+ # or: npm test
243
+ ```