indytag 1.3.1 → 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 (5) hide show
  1. package/LICENSE +15 -15
  2. package/README.md +243 -141
  3. package/bin/indytag.js +59 -59
  4. package/indytag.py +2142 -233
  5. package/package.json +62 -56
package/LICENSE CHANGED
@@ -1,15 +1,15 @@
1
- ISC License
2
-
3
- Copyright (c) 2026 LuxDev
4
-
5
- Permission to use, copy, modify, and/or distribute this software for any
6
- purpose with or without fee is hereby granted, provided that the above
7
- copyright notice and this permission notice appear in all copies.
8
-
9
- THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
- REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
- AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
- INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
- LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
- OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
- PERFORMANCE OF THIS SOFTWARE.
1
+ ISC License
2
+
3
+ Copyright (c) 2026 LuxDev
4
+
5
+ Permission to use, copy, modify, and/or distribute this software for any
6
+ purpose with or without fee is hereby granted, provided that the above
7
+ copyright notice and this permission notice appear in all copies.
8
+
9
+ THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
10
+ REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11
+ AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
12
+ INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13
+ LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
14
+ OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15
+ PERFORMANCE OF THIS SOFTWARE.
package/README.md CHANGED
@@ -1,141 +1,243 @@
1
- # indytag
2
-
3
- Tag paths in a tree, turn those marks into durable artifacts agents can consume,
4
- then act on the inventory later.
5
-
6
- 1. **Tag** — pick files/folders and assign labels (`project`, `skill`, `vault`, … or custom).
7
- 2. **Write rules + indexes** — emit ignore rules, per-tag files, `index.md`, and a `.indytag/` inventory.
8
- 3. **Act** — import that inventory (or scan a scope) and move / recycle / delete / zip / csv / meta / dedupe / atomize.
9
-
10
- One Python file, standard library only. The npm package is a thin launcher: it
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`.
17
-
18
- ```sh
19
- npm i -g indytag
20
- # or: npm i -g @agnamo/indytag
21
- indytag .
22
- ```
23
-
24
- ## What it writes
25
-
26
- Run against a folder and it produces:
27
-
28
- | Path | What it is |
29
- |---|---|
30
- | `.ignore`, `.aiignore` | gitignore-syntax rules for the paths you tagged |
31
- | `.indytag/tags.<tag>` | one rule file per tag (e.g. `tags.project`, `tags.vault`) |
32
- | `index.md` | layered directory index for humans and agents |
33
- | `.indytag/manifest.json` | counts, tag map and file locations |
34
- | `.indytag/inventory/` | `index.md`, `manifest.json`, `list.csv` |
35
- | `.indytag/index/` | `index-all.md`, `manifest-all.json` (full depth) |
36
-
37
- Everything except `index.md` and `.ignore` lives inside the hidden `.indytag/`
38
- container, so the folder you aimed it at stays readable.
39
-
40
- ## Default tags
41
-
42
- ```
43
- project skill agent archive review private vault app frozen stale
44
- ```
45
-
46
- Files written: `.indytag/tags.project`, `.indytag/tags.skill`, … one per tag.
47
-
48
- Add your own with `--tags` (comma list). Custom names become `tags.<custom>` the same way:
49
-
50
- ```sh
51
- indytag . --tags project,skill,mine,yours
52
- ```
53
-
54
- ## Interactive selector
55
-
56
- ```
57
- indytag . # tag + index, selector first
58
- indytag . --no-select --yes # scripted run, no prompts
59
- ```
60
-
61
- | Key | Action |
62
- |---|---|
63
- | `Space` | tag / untag the current path with the active tag |
64
- | `Tab`, `1`–`9` | switch the active tag (first nine presets) |
65
- | `a` / `n` / `i` | tag all / clear all / invert for the active tag |
66
- | `/` | filter; `Enter` keeps it |
67
- | `←` `→` `e` `c` | collapse, expand, expand all, collapse all |
68
- | `Backspace` / `0` | clear tags on the current path |
69
- | `Enter` | save and continue |
70
- | `q` / `Esc` | cancel, write nothing |
71
-
72
- ## Import a previous run
73
-
74
- Point `--import` at a `manifest.json`, `index.md` or `list.csv` written by
75
- indytag, or by the standalone `index.py` that shares the same manifest shape.
76
- The format is detected from the content, so the file name does not matter.
77
-
78
- ```sh
79
- indytag --import .indytag/inventory/manifest.json # asks what to do
80
- indytag --import index.md --action list # just print them
81
- indytag --import index.md --action csv --target picks.csv
82
- indytag --import manifest-all.json --action zip --target bundle.zip
83
- indytag --import index.md --action move --target ../keep # keeps layout
84
- indytag --import index.md --action recycle --pick 'build/*'
85
- ```
86
-
87
- | Action | Effect |
88
- |---|---|
89
- | `list` | print the imported paths, change nothing |
90
- | `move` | move into `--target`, root-relative layout preserved |
91
- | `recycle` | Recycle Bin on Windows, `.indytag/trash/<stamp>/` elsewhere |
92
- | `delete` | permanent removal of the imported paths |
93
- | `zip` | one archive, root-relative entry names |
94
- | `csv` | imported paths only: path, kind, size, modified, tags |
95
- | `meta` | full scope walk → rich CSV (size, times, mode, sha256) |
96
- | `dedupe` | byte-match duplicates in a scope; recycle extras |
97
- | `atomize` | byte-match duplicates in a scope; permanent delete extras |
98
-
99
- ### meta
100
-
101
- One row per file. Does not need an import when you pass a scope:
102
-
103
- ```sh
104
- indytag --action meta --scope other --other ./tree --target meta.csv
105
- indytag --action meta --scope workspace --no-hash # skip sha256
106
- indytag --action meta --scope drives --drive C:\ --drive Z:\
107
- ```
108
-
109
- Columns: `path, name, parent, kind, extension, size_bytes, size_human,
110
- created_utc, modified_utc, accessed_utc, mode, sha256, is_symlink,
111
- symlink_target, exists`.
112
-
113
- ### dedupe vs atomize
114
-
115
- Both scan a scope (`workspace` / `drives` / `all` / `other`), group files by
116
- size then sha256, keep one copy per set, remove the rest.
117
-
118
- | | `dedupe` | `atomize` |
119
- |---|---|---|
120
- | extras go to | Recycle Bin (or `.indytag/trash/`) | permanent delete — **no recycle** |
121
- | confirm | yes (unless `--yes`) | yes, stronger wording (unless `--yes`) |
122
-
123
- ```sh
124
- indytag --action dedupe --scope other --other ./tree --dry-run
125
- indytag --action atomize --scope other --other ./tree --yes
126
- ```
127
-
128
- Safety: absolute paths, drive letters and `..` segments are refused and
129
- counted, a nested path collapses when its ancestor is already selected,
130
- `--dry-run` writes nothing, and a non-interactive run needs `--yes` before
131
- anything is moved, recycled, deleted or atomized.
132
-
133
- ## Requirements
134
-
135
- Python 3.8 or newer on `PATH`. Override the interpreter with
136
- `INDYTAG_PYTHON` (or `PYTHON`). Node 18+ is only needed for the npm launcher.
137
-
138
- ```
139
- indytag --version
140
- indytag --help
141
- ```
1
+ # indytag
2
+
3
+ Tag paths in a tree, turn those marks into durable artifacts agents can consume,
4
+ then act on the inventory later.
5
+
6
+ 1. **Tag** — pick files/folders and assign labels (`project`, `skill`, `vault`, … or custom).
7
+ 2. **Write rules + indexes** — emit ignore rules, per-tag files, `index.md`, and a `.indytag/` inventory.
8
+ 3. **Act** — import that inventory (or scan a scope) and move / recycle / delete / zip / csv / meta / dedupe / atomize.
9
+
10
+ One Python file, standard library only. The npm package is a thin launcher: it
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.
13
+
14
+ ```sh
15
+ npm i -g 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
19
+ ```
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
+
93
+ ## What it writes
94
+
95
+ Run against a folder and it produces:
96
+
97
+ | Path | What it is |
98
+ |---|---|
99
+ | `.ignore`, `.aiignore` | gitignore-syntax rules for the paths you tagged |
100
+ | `.indytag/tags.<tag>` | one rule file per tag (e.g. `tags.project`, `tags.vault`) |
101
+ | `index.md` | layered directory index for humans and agents |
102
+ | `.indytag/manifest.json` | counts, tag map and file locations |
103
+ | `.indytag/inventory/` | `index.md`, `manifest.json`, `list.csv` |
104
+ | `.indytag/index/` | `index-all.md`, `manifest-all.json` (full depth) |
105
+
106
+ Everything except `index.md` and `.ignore` lives inside the hidden `.indytag/`
107
+ container, so the folder you aimed it at stays readable.
108
+
109
+ ## Default tags
110
+
111
+ ```
112
+ project skill agent archive review private vault app frozen stale
113
+ ```
114
+
115
+ Files written: `.indytag/tags.project`, `.indytag/tags.skill`, … one per tag.
116
+
117
+ Add your own with `--tags` (comma list). Custom names become `tags.<custom>` the same way:
118
+
119
+ ```sh
120
+ indytag . --tags project,skill,mine,yours
121
+ ```
122
+
123
+ ## Interactive selector
124
+
125
+ ```
126
+ indytag . # tag + index, selector first
127
+ indytag . --no-select --yes # scripted run, no prompts
128
+ ```
129
+
130
+ | Key | Action |
131
+ |---|---|
132
+ | `Space` | tag / untag the current path with the active tag |
133
+ | `Tab`, `1`–`9` | switch the active tag (first nine presets) |
134
+ | `a` / `n` / `i` | tag all / clear all / invert for the active tag |
135
+ | `/` or `s` | search; `Enter` keeps it, `Esc` clears it |
136
+ | `←` `→` `e` `c` | collapse, expand, expand all, collapse all |
137
+ | `Backspace` / `0` | clear tags on the current path |
138
+ | `Enter` | save and continue |
139
+ | `q` / `Esc` | cancel, write nothing |
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
+
144
+ ## Import a previous run
145
+
146
+ Point `--import` at a `manifest.json`, `index.md` or `list.csv` written by
147
+ indytag, or by the standalone `index.py` that shares the same manifest shape.
148
+ The format is detected from the content, so the file name does not matter.
149
+
150
+ ```sh
151
+ indytag --import .indytag/inventory/manifest.json # asks what to do
152
+ indytag --import index.md --action list # just print them
153
+ indytag --import index.md --action csv --target picks.csv
154
+ indytag --import manifest-all.json --action zip --target bundle.zip
155
+ indytag --import index.md --action move --target ../keep # keeps layout
156
+ indytag --import index.md --action recycle --pick 'build/*'
157
+ ```
158
+
159
+ | Action | Effect |
160
+ |---|---|
161
+ | `list` | print the imported paths, change nothing |
162
+ | `move` | move into `--target`, root-relative layout preserved |
163
+ | `recycle` | Recycle Bin on Windows, `.indytag/trash/<stamp>/` elsewhere |
164
+ | `delete` | permanent removal of the imported paths |
165
+ | `zip` | one archive, root-relative entry names |
166
+ | `csv` | imported paths only: path, kind, size, modified, tags |
167
+ | `meta` | full scope walk → rich CSV (size, times, mode, sha256) |
168
+ | `dedupe` | byte-match duplicates in a scope; recycle extras |
169
+ | `atomize` | byte-match duplicates in a scope; permanent delete extras |
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
+
175
+ ### meta
176
+
177
+ One row per file. Does not need an import when you pass a scope:
178
+
179
+ ```sh
180
+ indytag --action meta --scope other --other ./tree --target meta.csv
181
+ indytag --action meta --scope workspace --no-hash # skip sha256
182
+ indytag --action meta --scope drives --drive C:\ --drive Z:\
183
+ ```
184
+
185
+ Columns: `path, name, parent, kind, extension, size_bytes, size_human,
186
+ created_utc, modified_utc, accessed_utc, mode, sha256, is_symlink,
187
+ symlink_target, exists`.
188
+
189
+ ### dedupe vs atomize
190
+
191
+ Both scan a scope (`workspace` / `drives` / `all` / `other`), group files by
192
+ size then sha256, keep one copy per set, remove the rest.
193
+
194
+ | | `dedupe` | `atomize` |
195
+ |---|---|---|
196
+ | extras go to | Recycle Bin (or `.indytag/trash/`) | permanent delete — **no recycle** |
197
+ | confirm | yes (unless `--yes`) | yes, stronger wording (unless `--yes`) |
198
+
199
+ ```sh
200
+ indytag --action dedupe --scope other --other ./tree --dry-run
201
+ indytag --action atomize --scope other --other ./tree --yes
202
+ ```
203
+
204
+ Safety: absolute paths, drive letters and `..` segments are refused and
205
+ counted, a nested path collapses when its ancestor is already selected,
206
+ `--dry-run` writes nothing, and a non-interactive run needs `--yes` before
207
+ anything is moved, recycled, deleted or atomized.
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
+
223
+ ## Requirements
224
+
225
+ Python 3.8 or newer on `PATH`. Override the interpreter with
226
+ `INDYTAG_PYTHON` (or `PYTHON`). Node 18+ is only needed for the npm launcher.
227
+
228
+ ```
229
+ indytag --version
230
+ indytag --help
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
+ ```
package/bin/indytag.js CHANGED
@@ -1,59 +1,59 @@
1
- #!/usr/bin/env node
2
- "use strict";
3
-
4
- // Node bin shim for the single-file Python CLI.
5
- //
6
- // It finds a Python 3 interpreter, then hands the terminal to indytag.py with
7
- // inherited stdio - every byte of the raw-mode TUI has to reach the real
8
- // console, so nothing may be piped or buffered here.
9
-
10
- const path = require("path");
11
- const { spawnSync } = require("child_process");
12
-
13
- const script = path.join(__dirname, "..", "indytag.py");
14
-
15
- function launchers() {
16
- const found = [];
17
- const fromEnv = (process.env.INDYTAG_PYTHON || process.env.PYTHON || "").trim();
18
- if (fromEnv) {
19
- found.push([fromEnv]);
20
- }
21
- if (process.platform === "win32") {
22
- found.push(["py", "-3"]);
23
- }
24
- found.push(["python3"], ["python"]);
25
- return found;
26
- }
27
-
28
- function runs(argv) {
29
- const probe = spawnSync(argv[0], argv.slice(1).concat(["--version"]), {
30
- stdio: "ignore",
31
- });
32
- return !probe.error && probe.status === 0;
33
- }
34
-
35
- const launcher = launchers().find(runs);
36
-
37
- if (!launcher) {
38
- process.stderr.write(
39
- "indytag: no Python 3 interpreter found.\n" +
40
- "Install Python 3 and put `python3` (or `python`) on PATH,\n" +
41
- "or set INDYTAG_PYTHON to the interpreter to use.\n"
42
- );
43
- process.exit(1);
44
- }
45
-
46
- const result = spawnSync(
47
- launcher[0],
48
- launcher.slice(1).concat([script], process.argv.slice(2)),
49
- { stdio: "inherit" }
50
- );
51
-
52
- if (result.error) {
53
- process.stderr.write(
54
- "indytag: failed to launch " + launcher[0] + ": " + result.error.message + "\n"
55
- );
56
- process.exit(1);
57
- }
58
-
59
- process.exit(result.status === null ? 1 : result.status);
1
+ #!/usr/bin/env node
2
+ "use strict";
3
+
4
+ // Node bin shim for the single-file Python CLI.
5
+ //
6
+ // It finds a Python 3 interpreter, then hands the terminal to indytag.py with
7
+ // inherited stdio - every byte of the raw-mode TUI has to reach the real
8
+ // console, so nothing may be piped or buffered here.
9
+
10
+ const path = require("path");
11
+ const { spawnSync } = require("child_process");
12
+
13
+ const script = path.join(__dirname, "..", "indytag.py");
14
+
15
+ function launchers() {
16
+ const found = [];
17
+ const fromEnv = (process.env.INDYTAG_PYTHON || process.env.PYTHON || "").trim();
18
+ if (fromEnv) {
19
+ found.push([fromEnv]);
20
+ }
21
+ if (process.platform === "win32") {
22
+ found.push(["py", "-3"]);
23
+ }
24
+ found.push(["python3"], ["python"]);
25
+ return found;
26
+ }
27
+
28
+ function runs(argv) {
29
+ const probe = spawnSync(argv[0], argv.slice(1).concat(["--version"]), {
30
+ stdio: "ignore",
31
+ });
32
+ return !probe.error && probe.status === 0;
33
+ }
34
+
35
+ const launcher = launchers().find(runs);
36
+
37
+ if (!launcher) {
38
+ process.stderr.write(
39
+ "indytag: no Python 3 interpreter found.\n" +
40
+ "Install Python 3 and put `python3` (or `python`) on PATH,\n" +
41
+ "or set INDYTAG_PYTHON to the interpreter to use.\n"
42
+ );
43
+ process.exit(1);
44
+ }
45
+
46
+ const result = spawnSync(
47
+ launcher[0],
48
+ launcher.slice(1).concat([script], process.argv.slice(2)),
49
+ { stdio: "inherit" }
50
+ );
51
+
52
+ if (result.error) {
53
+ process.stderr.write(
54
+ "indytag: failed to launch " + launcher[0] + ": " + result.error.message + "\n"
55
+ );
56
+ process.exit(1);
57
+ }
58
+
59
+ process.exit(result.status === null ? 1 : result.status);