Repository navigation
Expand file tree
/
Copy pathjustfile
More file actions
957 lines (774 loc) · 43 KB
/
Copy pathjustfile
File metadata and controls
957 lines (774 loc) · 43 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
set shell := ["zsh", "-eu", "-o", "pipefail", "-c"]
# Every recipe runs `{{python}}`, never a bare `python3`. It is the project venv
# when `just install` has been run and the system interpreter otherwise, so a
# fresh clone still works and a bootstrapped one is insulated from the day
# Homebrew moves its default python and the site-packages go with it. That day
# is not hypothetical: it happened on 2026-09-09, numpy vanished, and the only
# symptom was `just check` reporting an action-catalog drift — see `just doctor`.
python := if path_exists(justfile_directory() / ".venv/bin/python3") == "true" { justfile_directory() / ".venv/bin/python3" } else { "python3" }
# Variadic recipes forward "$@" rather than an interpolated string, so an
# argument like evidence="... (2026-07-22) ..." survives verbatim instead of
# being re-split and glob-expanded by the shell.
set positional-arguments
default:
@just --list
# Run once per clone, and again after a python upgrade moves the interpreter
# out from under an existing venv. `--clear` because the venv is derived state:
# requirements.txt and .python-version are the source of truth, and recreating
# it is a second. Everything else in this file then runs against .venv.
# Create .venv and install requirements.txt with uv.
install:
@command -v uv >/dev/null || { \
echo "uv not found. Install it with: brew install uv" >&2; \
echo " (or: curl -LsSf https://astral.sh/uv/install.sh | sh)" >&2; \
exit 1; }
uv venv --clear
uv pip install --python .venv/bin/python3 -r requirements.txt
@.venv/bin/python3 tools/doctor.py
# The headers are third-party and deliberately NOT vendored: they carry an Atomix
# copyright with no license text and the download page states no terms, so this
# repo fetches them rather than redistributing them. vendor/ stays gitignored.
# Fetch the Atomix plugin SDK headers into vendor/vdj-sdk/ (`--force` to re-fetch).
download-sdk *args:
@{{python}} tools/download_sdk.py "$@"
# Interpreter, packages, uv, which VirtualDJ is installed against what the
# artifacts are anchored to, and whether the live probe channel answers. Only
# the python section can fail; the rest are notices worth reading before work.
# Environment health in one screen, `brew doctor` style.
doctor:
@{{python}} tools/doctor.py
# The first startable task in TODO.md (HISTORY.md holds finished ones, RETIRED.md the old queue). Refuses to select if any status line
# in the file is malformed, rather than skipping the task it cannot read.
next-task:
@{{python}} tools/task_queue.py next
# Every task with its state; `*` marks the startable ones.
task-queue *args:
@{{python}} tools/task_queue.py list "$@"
# Grep the authored verb prose/examples. For record lookups use `just get-verb`.
grep-verb-docs name:
@rg -n --fixed-strings "{{name}}" \
"docs/VDJScript Verbs.md" \
"docs/Official VDJScript Coverage Audit.md" \
"docs/VDJScript Local Test Tracker.md" \
"docs/Undocumented VDJScript Candidates.md" \
"docs/Effects Engines.md" \
"docs/Effects Usage.md" \
"examples/Pads" \
"tests"
needs-test:
@rg -n "Needs local test|Untested|Partial|Status: Needs local test|Status: Partial" \
"docs/Official VDJScript Coverage Audit.md" \
"docs/VDJScript Local Test Tracker.md" \
"docs/Completeness Roadmap.md" \
"docs/Undocumented VDJScript Candidates.md" \
"TODO.md"
official-needs-test:
@awk '\
/^## Needs Local Test/ { in_section=1; next } \
in_section && /^## / { exit } \
in_section && NF { print } \
' "docs/Official VDJScript Coverage Audit.md"
tracker-untested:
@rg -n "\| .* \| .* \| .* \| Untested \|" "docs/VDJScript Local Test Tracker.md"
tracker-partial:
@rg -n "\| .* \| .* \| .* \| Partial \|" "docs/VDJScript Local Test Tracker.md"
thin-verbs:
@rg -n '^\| `[^`]+` \| — \|' "docs/VDJScript Verbs.md"
status:
@{{python}} -c 'from pathlib import Path; import re; text=Path("docs/Official VDJScript Coverage Audit.md").read_text(); count=re.search(r"Official verb/alias names parsed: (\d+)", text); gap=re.search(r"The formal local-test gap is (\d+) official names", text); print("Official names parsed: {}".format(count.group(1) if count else "unknown")); print("Formal local-test gap: {}".format(gap.group(1) if gap else "unknown"))'
@printf "\nTask queue:\n"
@{{python}} tools/task_queue.py list
# `"$@"` rather than an interpolated {{script}}: interpolation puts the script
# through zsh, which expands a VDJScript global like $ct_top before the request
# is built and leaves `get_var "$ct_top"` querying an empty name.
vdj-query script:
@curl -sS -m 5 -G 'http://localhost/query' --data-urlencode "script=$1"; echo
vdj-execute script:
@curl -sS -m 5 -G 'http://localhost/execute' --data-urlencode "script=$1"; echo
vdj-up:
@curl -sS -m 3 -G 'http://localhost/query' --data-urlencode 'script=get_version' >/dev/null 2>&1 \
&& echo "VirtualDJ HTTP interface reachable on http://localhost/" \
|| { echo "VirtualDJ HTTP interface NOT reachable (is VirtualDJ running with the network interface enabled?)"; exit 1; }
# Screenshot the VirtualDJ window into tests/screenshots/ (macOS; needs Screen
# Recording permission). Pass --out PATH or --list. MCP twin: vdj_screenshot.
screenshot *args:
@{{python}} tools/vdj_screenshot.py {{args}}
# Quit and relaunch VirtualDJ, then wait for HTTP. Refuses while a deck plays.
# --status, --force, --allow-playing, --arg -remote. MCP twin: vdj_restart.
vdj-restart *args:
@{{python}} tools/vdj_restart.py {{args}}
# Serve the store, FX catalog, XML inventory, grammar, linters and the live HTTP
# probe channel to any MCP client over stdio. Zero dependencies; stdout is
# protocol only. `vdj_execute` stays disabled unless VDJ_MCP_EXECUTE=1.
# Registration and tool list: docs/MCP Server.md
mcp-serve:
@{{python}} tools/mcp_server.py
# Smoke-test the MCP server without a client: lists tools and calls a few.
# `--live` adds read-only calls against a running VirtualDJ (skipped if it does not answer).
mcp-check *args:
{{python}} tools/doctor.py --deps-only
@{{python}} tools/mcp_server.py --self-check {{args}}
inventory:
{{python}} tools/extract_xml_inventory.py
# --- skin/pad/mapper XML element inventory ----------------------------------
# One element, every source joined — inventory row, its doc section, the binary's
# reader vocabulary, live probe results (negatives included), real usage, and which
# attributes no doc explains. The counterpart to `just verb`.
element name *args:
@{{python}} tools/element_summary.py "$@"
# The bare inventory row, as `get-verb` is to `verb`.
get-xml-element element:
@{{python}} tools/xmldb.py get "{{element}}"
# Skin and video-skin elements; --family=all includes pads, mappers and samplerbanks.
list-skin-elements *args:
@{{python}} tools/xmldb.py search --family=skin "$@"
# Editorial vocabulary with derived totals; no parser-support claim.
list-skin-categories *args:
@{{python}} tools/xmldb.py categories "$@"
# Literal direct nesting in vendor skin XML, with source hashes and diagnostics.
skin-relations *args:
@{{python}} tools/skin_relations.py "$@"
# Compatibility for existing scripts and frozen planning references.
[private]
list-xml-elements *args:
@{{python}} tools/xmldb.py search "$@"
xml-stats:
@{{python}} tools/xmldb.py stats
verb-index:
{{python}} tools/extract_verb_index.py
# --- verb record store (docs/vdjscript-verbs.json) ---------------------------
# Flat names on purpose: the argument is always data, never a subcommand, so a
# verb called `search` or `get` can never be mistaken for a command.
get-verb name:
@{{python}} tools/verbdb.py get "{{name}}"
# EVERYTHING about one verb on one screen: store record, vendor description,
# real usages, argument shapes with return evidence, every tail candidate by
# source, vocabulary groups, probe state. `--format=json` for structure.
verb name *args:
@{{python}} tools/verb_summary.py "{{name}}" {{args}}
list-verbs *args:
@{{python}} tools/verbdb.py search "$@"
put-verb name *assignments:
@{{python}} tools/verbdb.py put "$@"
next-incomplete-verb:
@{{python}} tools/verbdb.py next-incomplete
verb-stats:
@{{python}} tools/verbdb.py stats
# Non-alias records with no `section`, with their b9246 source module where one
# exists. A query on the store; fill one with `just put-verb <name> section=...`.
uncategorized-verbs *args:
@{{python}} tools/verbdb.py uncategorized {{args}}
# The section vocabulary with per-section verb and tested counts; the names to
# pass to `list-verbs --section=`. A query on the store, never written down.
list-verb-categories *args:
@{{python}} tools/verbdb.py sections {{args}}
# Contract coverage across every verb, per dimension, recounted from the
# artifacts. `--settled` names the finished verbs, `--frontier` names what each
# dimension is waiting on. Read-only; touches no live instance.
coverage *args:
@{{python}} tools/coverage_report.py "$@"
# Generated owned bank; see tests/README.md for preparation and bounded live scope.
probe-sampler-contracts *args:
@{{python}} tools/probe_sampler_contracts.py "$@"
# Prints frozen cases by default; --run plays quiet generated samples and restores.
probe-sampler-playback *args:
@{{python}} tools/probe_sampler_playback.py "$@"
# Requires empty stopped deck 1. Generates temporary audio and verifies restoration.
probe-long-time:
{{python}} tools/probe_long_time.py --run
long-time-forms name="":
@{{python}} tools/probe_long_time.py --get "{{name}}"
# --- human-facing reference page ---------------------------------------------
# Fill design/human-api-reference.template.html from the verb store, skin inventory and evidence
# artifacts (the same join `just verb` makes) into the git-ignored build/ tree.
# A rendered copy of store data: regenerate it, never commit it.
# Render the human-facing reference page; --guides selects the parallel Markdown template.
# `--open` shows it in the default browser; `--out PATH` picks the file.
build-reference *flags:
@{{python}} tools/render_reference.py {{flags}}
# --- native effects catalog (swept via the HTTP interface) -------------------
get-fx effect:
@{{python}} tools/fxdb.py get "{{effect}}"
list-fx *args:
@{{python}} tools/fxdb.py search "$@"
fx-stats:
@{{python}} tools/fxdb.py stats
# --- verb existence probe (HTTP error-code sweep) ---------------------------
# Does this name exist, and what kind is it? Answered from the sweep artifact.
# Re-run the sweep with `just sweep-verb-existence` (needs `just vdj-up`).
verb-probe name:
@{{python}} tools/sweep_verb_existence.py --get "{{name}}"
# AUTHORITATIVE: is this a real verb? Reads VirtualDJ's own verb table.
verb-table name:
@{{python}} tools/extract_verb_table.py --get "{{name}}"
# The exact build-stamped phrase to quote in prose. Copy it; never recall a build number.
verb-table-stamp:
@{{python}} tools/extract_verb_table.py --stamp
extract-verb-table:
@{{python}} tools/extract_verb_table.py > tests/verb-table.json.tmp
@mv tests/verb-table.json.tmp tests/verb-table.json
# STRUCTURAL CONTRACT: capability, query return type, family from ACTION_ RTTI.
verb-contract name:
@{{python}} tools/extract_action_contracts.py --get "{{name}}"
# The call-graph addresses behind one verb's traces (roots, callees, unvisited).
verb-traces name:
@{{python}} tools/extract_action_contracts.py --traces "{{name}}"
extract-action-contracts:
@{{python}} tools/extract_action_contracts.py > tests/action-contracts.json.tmp
@mv tests/action-contracts.json.tmp tests/action-contracts.json
# OBSERVED TYPE: what a query verb actually returns over HTTP (Tier 1).
verb-return-type name:
@{{python}} tools/sweep_return_types.py --get "{{name}}"
sweep-return-types:
@{{python}} tools/sweep_return_types.py > tests/verb-return-types.json.tmp
@mv tests/verb-return-types.json.tmp tests/verb-return-types.json
# --- prepared state (fixtures) ----------------------------------------------
# Argument forms can only be told apart in a state where they would disagree.
# Each fixture verifies its own preconditions and refuses to report success
# otherwise. `fixture-establish` changes live app state; some make sound.
fixtures:
@{{python}} tools/fixtures.py --list
fixture-verify name:
@{{python}} tools/fixtures.py --verify "{{name}}"
fixture-establish name *args:
{{python}} tools/fixtures.py --establish "{{name}}" {{args}}
# Send every vendor snippet through /query and classify the outcome.
corpus-parses *args:
{{python}} tools/check_corpus_parses.py {{args}} > tests/corpus-parse-results.json.tmp
@mv tests/corpus-parse-results.json.tmp tests/corpus-parse-results.json
# Argument tails Atomix wrote in shipped scripts — attested without a probe.
attested-tails *args:
@{{python}} tools/extract_attested_tails.py {{args}}
# The Button Editor's own action descriptions — the official appendix prose,
# offline. `--cross-check` diffs documented parameters against probe findings.
# Historical installers: vendor prose and shipped-skin usages the current app no longer carries.
vendor-history-diff root="/tmp/vdj-history-20260906":
@{{python}} tools/diff_vendor_history.py --root {{root}} --output tests/build-history-2026-09-06/vendor-text-diff.json
action-catalog *args:
@{{python}} tools/extract_action_catalog.py {{args}}
# Every VDJScript snippet Atomix wrote: catalog examples + shipped Built-In XML
# + every factory controller mapping decoded from controllers.dat (needs
# `just controllers-vendor`) + wiki transcriptions + statements compiled into
# the app binary.
script-corpus *args:
@{{python}} tools/extract_script_corpus.py {{args}}
# Do the vendor XML copies under examples/*/Built-In still match the installed
# app? A VirtualDJ update silently ages them, and the corpus then attests a
# value the vendor no longer ships. `--refresh` re-copies; re-extract after.
bundle-copies *args:
@{{python}} tools/check_bundle_copies.py {{args}}
# Argument VOCABULARIES: shared enumerations (stem names, colours, sideview
# pages) recovered as structures from the binary — pointer tables and the
# switch functions that walk them. Tier 2: members are leads for the prober.
binary-vocab *args:
@{{python}} tools/extract_binary_vocabularies.py {{args}}
extract-binary-vocabularies:
@{{python}} tools/extract_binary_vocabularies.py > tests/binary-vocabularies.json.tmp
@mv tests/binary-vocabularies.json.tmp tests/binary-vocabularies.json
# SOURCE MODULE: which of Atomix's own `action_*.cpp` files implements a verb,
# from the unstripped build's STABS. Tier 2 — it groups a verb, and says nothing
# about whether it works. `--sections` says which modules map cleanly onto a
# store section; `extract-action-modules` needs the b9246 pkg expanded.
action-modules *args:
@{{python}} tools/extract_action_modules.py {{args}}
extract-action-modules app:
@{{python}} tools/extract_action_modules.py --app "{{app}}" > tests/action-modules-9246.json.tmp
@mv tests/action-modules-9246.json.tmp tests/action-modules-9246.json
# TAIL GRAMMAR: which trailing tokens a verb actually recognizes (Tier 1).
# Every candidate is measured against nonsense controls, in every fixture.
verb-arg-forms name:
@{{python}} tools/probe_arg_forms.py --get "{{name}}"
# Needs `just vdj-up`. Establishes each fixture in turn; some make sound.
# The tool writes the artifact itself, atomically, and only for a real run —
# `--dry-run` and `--check` leave it untouched; `--merge FILE` updates it itself.
# (A shell redirect here once truncated the evidence on every dry run.)
probe-arg-forms *args:
{{python}} tools/probe_arg_forms.py --out tests/verb-arg-forms.json {{args}}
# EXECUTE-position tails. WRITES to the running instance: allowlisted settings
# verbs only, each round-trip tested first, every value restored and verified.
probe-execute-forms *args:
{{python}} tools/probe_execute_forms.py --out tests/verb-execute-forms.json {{args}}
# Corroborating structured sources (superseded by verb-table for existence).
binary-verb name:
@{{python}} tools/extract_binary_verbs.py --get "{{name}}"
extract-binary-verbs:
@{{python}} tools/extract_binary_verbs.py > tests/binary-verbs.json.tmp
@mv tests/binary-verbs.json.tmp tests/binary-verbs.json
sweep-verb-existence:
@{{python}} tools/sweep_verb_existence.py > tests/verb-existence-sweep.json.tmp
@mv tests/verb-existence-sweep.json.tmp tests/verb-existence-sweep.json
# --- plugin channel: native typed queries (task 10a) -------------------------
# A read-only C++ plugin asks GetInfo/GetStringInfo directly, so return types are
# observed rather than inferred from HTTP's rendered text. Needs the Atomix SDK
# headers under vendor/ (not vendored here — see docs/Plugin SDK.md).
#
# just plugin-build --install # build + drop into VirtualDJ's plugin folder
# (restart VirtualDJ)
# just plugin-prepare # write the probe list
# (restart VirtualDJ — the sweep runs at plugin load)
# just plugin-status # confirm it ran
# just plugin-collect # normalize the capture into tests/
plugin-build *args:
@tools/plugin/build.sh "$@"
plugin-prepare *args:
@{{python}} tools/plugin_introspect.py prepare "$@"
plugin-status:
@{{python}} tools/plugin_introspect.py status
plugin-collect:
@{{python}} tools/plugin_introspect.py collect > tests/plugin-introspection.json.tmp
@mv tests/plugin-introspection.json.tmp tests/plugin-introspection.json
@{{python}} tools/plugin_introspect.py --check
# Follow-up capture: deck context for the silent query verbs, and each recovered
# keyword paired with a nonsense control on the same verb.
plugin-prepare-leads:
@{{python}} tools/plugin_introspect.py prepare --leads
# Any other capture: `just plugin-collect-as controls` -> tests/plugin-introspection-controls.json
plugin-collect-as name:
@{{python}} tools/plugin_introspect.py collect > "tests/plugin-introspection-{{name}}.json.tmp"
@mv "tests/plugin-introspection-{{name}}.json.tmp" "tests/plugin-introspection-{{name}}.json"
@echo "wrote tests/plugin-introspection-{{name}}.json"
plugin-collect-leads:
@{{python}} tools/plugin_introspect.py collect > tests/plugin-introspection-leads.json.tmp
@mv tests/plugin-introspection-leads.json.tmp tests/plugin-introspection-leads.json
@{{python}} tools/plugin_introspect.py leads-report
# OBSERVED NATIVE TYPE: which channel a verb answers on, and with what.
plugin-probe name:
@{{python}} tools/plugin_introspect.py --get "{{name}}"
# Fixed safe predicate calibration. No args prints the plan; --run needs a fresh --output.
statement-branches *args:
@{{python}} tools/probe_statement_branches.py {{args}}
argument-types *args:
@{{python}} tools/probe_argument_types.py {{args}}
# --- cross-corpus topic search ----------------------------------------------
# One term -> matching verbs, effects, XML elements, REAL example files, docs,
# and known quirks. Start here for "how do I do X"; drill in with get-verb etc.
topic *args:
@{{python}} tools/topic.py "$@"
lint-skins *paths:
{{python}} tools/lint_skins.py "$@"
lint-mappers *paths:
{{python}} tools/lint_mappers.py "$@"
# Static VDJScript check: `--script "…" [--context query]`, `--xml FILE…`, `--repo`, `--corpus`.
lint-script *args:
{{python}} tools/lint_script.py "$@"
check:
just offline-parser-check
just offline-xml-check
just offline-skin-host-check
just offline-skin-composition-check
just skin-child-check
{{python}} tools/probe_query_cast_debug.py --check tests/param-cast-types-9644
{{python}} tools/probe_argument_types.py --check tests/argument-types-multiply-9644/values-expanded.json
{{python}} tools/probe_argument_types.py --check tests/argument-types-9644/values.json
{{python}} tools/probe_statement_branches.py --check tests/statement-branches-9644.json
just check-lyrics-cache
just check-linked-sid
just check-runtime-grammar
{{python}} tools/mcp_server.py --self-check
{{python}} tools/probe_long_time.py --check
{{python}} tools/check_bundle_copies.py
{{python}} tools/lint_pads.py
{{python}} tools/lint_skins.py
{{python}} tools/lint_mappers.py
{{python}} tools/lint_script.py --repo
{{python}} tools/test_lint_script.py
{{python}} tools/extract_verb_index.py --check
{{python}} tools/verbdb.py check
{{python}} tools/fxdb.py check
{{python}} tools/sweep_verb_existence.py --check
{{python}} tools/extract_binary_verbs.py --check
{{python}} tools/extract_verb_table.py --check
{{python}} tools/extract_action_contracts.py --check
{{python}} tools/test_reference.py
{{python}} tools/test_reference_guides.py
{{python}} tools/test_sysicon_atlas.py
{{python}} tools/test_action_tail_bounds.py
{{python}} tools/test_contract_assessment.py
{{python}} tools/test_coverage_section.py
{{python}} tools/test_sampler_contracts.py
{{python}} tools/test_sampler_playback.py
{{python}} tools/action_tail_leads.py --check
{{python}} tools/sweep_return_types.py --check
{{python}} tools/plugin_introspect.py --check
{{python}} tools/plugin_skin.py --check
{{python}} tools/topic.py check
{{python}} tools/fixtures.py --check
{{python}} tools/probe_arg_forms.py --check
{{python}} tools/probe_known_positions.py --check
{{python}} tools/probe_bpm_transition.py --check
{{python}} tools/probe_arg_positions.py --check
{{python}} tools/probe_execute_forms.py --check
{{python}} tools/extract_action_catalog.py --check
{{python}} tools/extract_script_corpus.py --check
{{python}} tools/extract_attested_tails.py --check
{{python}} tools/extract_binary_vocabularies.py --check
{{python}} tools/extract_action_modules.py --check
{{python}} tools/check_corpus_parses.py --check
{{python}} tools/extract_xml_inventory.py --check
{{python}} tools/xmldb.py categories --check
{{python}} tools/skin_relations.py --check
{{python}} tools/test_skin_metadata.py
{{python}} -m unittest discover -s tools -p test_skin_schema.py
{{python}} -m unittest discover -s tools -p test_skin_structure.py
{{python}} -m unittest discover -s tools -p test_skin_dispatch.py
{{python}} tools/skin_dispatch.py --check
{{python}} tools/probe_skin_expansion.py check
{{python}} tools/skin_condition_evidence.py --check > /dev/null
{{python}} tools/extract_skin_readers.py --check
{{python}} tools/extract_skin_classes.py --check
{{python}} tools/check_reference_status.py
{{python}} tools/task_queue.py check
{{python}} tools/task_queue.py selftest
git diff --check
# What the skin XML readers in the binary actually compare against, and which
# of those names appear in no shipped skin and no SDK doc.
skin-readers:
@{{python}} tools/extract_skin_readers.py > tests/skin-reader-vocabulary.json.tmp
@mv tests/skin-reader-vocabulary.json.tmp tests/skin-reader-vocabulary.json
@echo "wrote tests/skin-reader-vocabulary.json"
skin-reader name:
@{{python}} tools/extract_skin_readers.py --get "{{name}}"
skin-candidates:
@{{python}} tools/extract_skin_readers.py --candidates
# get_time's position arguments against three independently known positions.
# Writes to a live VirtualDJ (deck 1, stopped, no audio) and restores it.
known-positions:
@{{python}} tools/probe_known_positions.py --run > tests/get-time-positions.json.tmp
@mv tests/get-time-positions.json.tmp tests/get-time-positions.json
@echo "wrote tests/get-time-positions.json"
@{{python}} tools/probe_known_positions.py --check
# auto_bpm_transition's three documented parameters, read by WHERE the pair of
# decks settles rather than by whether a transition is running. Writes to a live
# VirtualDJ (decks 1 and 2, stopped, no audio) and restores both.
bpm-transition:
@{{python}} tools/probe_bpm_transition.py --run > tests/bpm-transition-forms.json.tmp
@mv tests/bpm-transition-forms.json.tmp tests/bpm-transition-forms.json
@echo "wrote tests/bpm-transition-forms.json"
@{{python}} tools/probe_bpm_transition.py --check
# Which ARGUMENT POSITIONS a verb reads: hold the attested shape, vary one
# position within its own class, see whether the answer moves. Query-only.
# `just probe-arg-positions --keywords=attested,catalog,vocab` widens the second
# keyword source; the default two are what the queue ratified.
probe-arg-positions *args:
@{{python}} tools/probe_arg_positions.py --run "$@" > tests/verb-arg-positions.json.tmp
@mv tests/verb-arg-positions.json.tmp tests/verb-arg-positions.json
@{{python}} tools/probe_arg_positions.py --check
# Which verbs a probe run would reach and what evidence each rests on. Needs no
# live VirtualDJ, so coverage is measurable before the instance is up.
probe-arg-positions-plan *args:
@{{python}} tools/probe_arg_positions.py --plan "$@"
verb-arg-positions name:
@{{python}} tools/probe_arg_positions.py --get "{{name}}"
# Confirm argument keywords against their nonsense controls in any capture.
plugin-keyword-report capture *args:
@{{python}} tools/plugin_introspect.py keyword-report --capture "tests/plugin-introspection-{{capture}}.json" {{args}}
# Re-sweep the delayed probe list right now, without restarting VirtualDJ.
# Set the app up by hand first (load a track, highlight a song), then trigger.
plugin-go:
@{{python}} tools/plugin_introspect.py go
# Collect the delayed/triggered capture: `just plugin-collect-late prepared`
plugin-collect-late name:
@{{python}} tools/plugin_introspect.py collect --late > "tests/plugin-introspection-{{name}}.json.tmp"
@mv "tests/plugin-introspection-{{name}}.json.tmp" "tests/plugin-introspection-{{name}}.json"
@echo "wrote tests/plugin-introspection-{{name}}.json"
# GetSongBuffer: the raw PCM of the loaded song, at any position. No other
# channel exposes it — this is the input side of the waveform questions.
# Needs a track loaded; `just plugin-songbuffer` then `just plugin-go`.
plugin-songbuffer:
@{{python}} tools/plugin_introspect.py songbuffer
# --- runtime skin loop (task 10a follow-on) ---------------------------------
# The Sound Effect build made with `tools/plugin/build.sh --skin --install`
# answers OnGetUserInterface with VDJINTERFACE_SKIN and serves these two files
# fresh on every call, so a skin edit costs a panel re-open, not a restart:
#
# just plugin-skin-prepare # write skin.png + the probe skin.xml
# just plugin-skin-prepare tests/Skins/runtime-probe/my.xml
# just plugin-skin-reload # close + re-open the panel (needs HTTP)
# just plugin-skin-log # how many times VirtualDJ asked
plugin-skin-prepare *xml:
@{{python}} tools/plugin_skin.py prepare {{ if xml == "" { "" } else { "--xml " + xml } }}
plugin-skin-log:
@{{python}} tools/plugin_skin.py log
# Toggling the panel is what makes VirtualDJ re-ask for the XML.
plugin-skin-reload:
@curl -sS -m 6 -G 'http://localhost/execute' --data-urlencode "script=deck 1 effect_show_gui 'VDJIntrospectSkin'" >/dev/null
@sleep 1
@curl -sS -m 6 -G 'http://localhost/execute' --data-urlencode "script=deck 1 effect_show_gui 'VDJIntrospectSkin'" >/dev/null
@echo 'panel re-opened; run `just plugin-skin-log` to see the new call'
plugin-songbuffer-report:
@{{python}} tools/plugin_introspect.py songbuffer-report
# OnKey/mouse events — the only channel that might carry press vs release.
plugin-keylog:
@{{python}} tools/plugin_introspect.py keylog
# Atlas cells joined to wiki names, live results and binary candidates.
sysicon-atlas *args:
@{{python}} tools/sysicon_atlas.py "$@"
# The skin object classes and the elements that build them (Tier 2 leads).
# Bare: a read-time summary. `--element panel` says which class builds an element,
# `--get CSkinPanel` the whole record, `--attributes CSkinPanel` just its attribute
# candidates. Read the artifact's own `limitations` before citing: absence
# establishes nothing.
skin-classes *args:
@{{python}} tools/extract_skin_classes.py "$@"
# Print the preferred symbol-rich bundle for method discovery, alongside the
# installed build for an explicit current-image comparison. --path is scriptable.
binary-source *args:
@{{python}} tools/binary_source.py "$@"
# Build-stamped XML ownership pilot; ordinary queries require only stdlib.
skin-schema *args:
@{{python}} tools/skin_schema.py "$@"
check-skin-schema:
@{{python}} -m unittest discover -s tools -p test_skin_schema.py
# Every skin object class, one line each. Filters: --base, --has-attr,
# --element-backed, --format=json. Untruncated, as the other list-* are.
list-skin-classes *args:
@{{python}} tools/extract_skin_classes.py --list "$@"
# Historical skin class source provenance (Tier 2; many-to-many STABS relation).
skin-modules *args:
@{{python}} tools/extract_skin_modules.py {{args}}
extract-skin-modules app:
@{{python}} tools/extract_skin_modules.py --app "{{app}}" > tests/skin-modules-9246.json.tmp
@mv tests/skin-modules-9246.json.tmp tests/skin-modules-9246.json
# Tier-2 bounded method/helper literal leads and ranked live probe queue.
action-tail-leads *args:
@{{python}} tools/action_tail_leads.py {{args}}
extract-action-tail-leads:
@{{python}} tools/action_tail_leads.py --generate > tests/action-tail-leads.json.tmp
@mv tests/action-tail-leads.json.tmp tests/action-tail-leads.json
# H4: frozen candidate tests, exact-script HTTP observations, bounded binary evidence.
runtime-grammar *args:
@{{python}} tools/runtime_grammar_probes.py "$@"
# Paired editor appearance and HTTP results, with failed predictions retained.
runtime-grammar-editor *args:
@{{python}} tools/runtime_grammar_editor.py "$@"
extract-runtime-parser app:
@{{python}} tools/extract_runtime_parser.py --app "{{app}}" --output tests/runtime-parser-9246
runtime-parser-frontier *args:
@{{python}} tools/runtime_parser_frontier.py --report "$@"
# Say what each queued indirect site actually is: factory, vtable, or artifact.
frontier-closure *args:
@{{python}} tools/resolve_frontier_sites.py "$@"
# Which deck-wrapper token was in flight at an exit. Read-only payloads, journal
# flushed before each send, process identity checked after every probe.
probe-deck-targets *args:
@{{python}} tools/probe_deck_targets.py "$@"
# Are bare names per-deck, $ shared and @ a separate name? Writes probe variables
# under a zzprobescope name and sets them back to 0, verifying the teardown.
probe-variable-scope *args:
@{{python}} tools/probe_variable_scope.py "$@"
# Whether the request pattern alone precedes an exit: fresh vs reused connection.
probe-http-stability *args:
@{{python}} tools/probe_http_stability.py "$@"
# H4: deck-scope keywords with selection and master pinned to DIFFERENT decks.
# Needs four unloaded, stopped decks; it refuses to mutate anything otherwise.
runtime-grammar-master *args:
@{{python}} tools/runtime_grammar_master.py "$@"
check-runtime-grammar:
@{{python}} tools/test_runtime_parser_branch_routes.py
@{{python}} tools/test_runtime_grammar_audit.py
@{{python}} tools/runtime_grammar_probes.py --audit > /dev/null
@{{python}} tools/test_runtime_grammar_playing.py
@{{python}} tools/build_runtime_editor_help_cases.py --check
@{{python}} tools/build_runtime_quote_consumer_cases.py --check
@{{python}} tools/build_runtime_quote_consumer_cases.py --arity-controls --check
@{{python}} tools/build_runtime_unmatched_quote_cases.py --check
@{{python}} tools/build_runtime_setting_eval_cases.py --check
@{{python}} tools/build_runtime_setting_eval_cases.py --discrimination --check
@{{python}} tools/build_runtime_setting_eval_cases.py --types --check
@{{python}} tools/build_runtime_display_float_cases.py --check
@{{python}} tools/build_runtime_display_float_cases.py --conversions --check
@{{python}} tools/test_runtime_display_float.py
@{{python}} tools/build_runtime_math_reader_cases.py --check
@{{python}} tools/test_runtime_math_reader.py
@{{python}} tools/build_runtime_text_reader_cases.py --check
@{{python}} tools/test_runtime_text_reader.py
@{{python}} tools/test_runtime_setting_eval.py
@{{python}} tools/test_runtime_quote_consumer.py
@{{python}} tools/build_runtime_boundary_cases.py --check
@{{python}} tools/build_runtime_boundary_confirmation.py --check
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-boundary-9598.json > /dev/null
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-boundary-confirmation-9598.json > /dev/null
@{{python}} tools/test_runtime_grammar_editor.py
@{{python}} tools/runtime_grammar_editor.py --check > /dev/null
@{{python}} tools/runtime_parser_frontier.py --check > /dev/null
@{{python}} tools/resolve_frontier_sites.py --check > /dev/null
@{{python}} tools/test_runtime_grammar_actions.py
@{{python}} tools/build_runtime_effect_boolean_cases.py --check
@{{python}} tools/build_runtime_effect_boolean_cases.py --confirmation --check
@{{python}} tools/test_runtime_effect_boolean.py
@{{python}} tools/build_runtime_incoming_cases.py --check
@{{python}} tools/build_runtime_incoming_action_cases.py --check
@{{python}} tools/build_runtime_incoming_action_cases.py --pipeline --check
@{{python}} tools/build_runtime_incoming_action_cases.py --bounded --check
@{{python}} tools/build_runtime_incoming_action_cases.py --fresh --check
@{{python}} tools/build_runtime_incoming_action_cases.py --confirmation --check
@{{python}} tools/test_runtime_incoming.py
@{{python}} tools/build_runtime_pair_float_cases.py --check
@{{python}} tools/test_runtime_pair_float.py
@{{python}} tools/test_runtime_grammar_scopes.py
@{{python}} tools/test_runtime_grammar_master.py
@{{python}} tools/runtime_grammar_master.py --check > /dev/null
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-actions-initial-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-actions-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-scopes-initial-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-scopes-second-attempt-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-scopes-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-action-fallback-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-action-default-initial-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-action-default-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-scope-followup-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-whitespace-9598.json
@{{python}} tools/test_runtime_grammar_probes.py
@{{python}} tools/runtime_grammar_probes.py --check
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-live-9598.json
@{{python}} tools/runtime_grammar_probes.py --check --artifact tests/runtime-grammar-followup-9598.json
# The decoded archive the corpus mines, under gitignored vendor/ (vendor copyright,
# like the SDK headers). One tree per archive, keyed by app build AND the
# archive's own revision — vendor/controllers/18.0.9598-r2241/ — with the
# committed manifest at tests/controllers-manifests/<key>.json. Idempotent: an
# existing key is verified, never overwritten, so decoding on a new build ADDS
# a record; then `just script-corpus > tests/vdjscript-corpus.json` to re-anchor.
controllers-vendor:
@uv run tools/read_controllers.py --vendor
@{{python}} tools/extract_script_corpus.py --vendor-check
# Every controller archive with a committed manifest, and which are decoded here.
controllers-archives *args:
@{{python}} tools/controller_archives.py {{args}}
# What changed in controllers.dat between two builds, from the manifests alone:
# `just controllers-diff 18.0.9583 18.0.9598`, `--root mapper`, `--format=json`.
controllers-diff older newer *args:
@{{python}} tools/controllers_diff.py "{{older}}" "{{newer}}" {{args}}
# Decode every original device/mapper/audio XML member; output dir must be new.
controllers-extract *args:
@uv run tools/read_controllers.py "$@"
# Offline vocabulary and mapper cross-checks; --path /device/slider or --device DDJGRV6
# (--controls [--match loop] lists the definition's control names).
controllers *args:
@{{python}} tools/controller_schema_inventory.py "$@"
# Linked-track SID calculation from prepared metadata, or an offline snapshot audit.
linked-sid *args:
@{{python}} tools/linked_sid.py "$@"
# Historical symbol-bounded SID extraction; requires capstone, writes JSON to stdout.
extract-linked-sid *args:
@{{python}} tools/extract_linked_sid.py "$@"
# Execute historical reducer/hash instructions on synthetic inputs; requires unicorn.
probe-linked-sid-binary *args:
@{{python}} tools/probe_linked_sid_binary.py "$@"
check-linked-sid:
@{{python}} tools/test_linked_sid.py
# Every stored linked-track relationship; missing metadata stays visible by SID.
list-linked-tracks *args:
@{{python}} tools/list_linked_tracks.py "$@"
# Lyric key conversions, payload parsing and offline cache inspection.
lyrics-cache *args:
@{{python}} tools/lyrics_cache.py "$@"
# Historical lyric-cache binary capture; capstone required, JSON on stdout.
extract-lyrics-cache *args:
@{{python}} tools/extract_lyrics_cache.py "$@"
# Synthetic original-instruction tests; Unicorn required, JSON on stdout.
probe-lyrics-binary *args:
@{{python}} tools/probe_lyrics_binary.py "$@"
check-lyrics-cache:
@{{python}} tools/test_lyrics_cache.py
# Bounded live memory probe: separate passthrough effect, no general probe lists.
plugin-memory-build *args:
tools/plugin/build.sh --memory {{args}}
# Verify live image UUID, build, table address and every name/id/flags record.
plugin-memory-check capture *args:
{{python}} tools/plugin_memory.py {{quote(capture)}} {{args}}
plugin-memory-test:
clang++ -std=c++17 -arch arm64 -I vendor/vdj-sdk/audio-plugin-dsp-example-1 -framework CoreFoundation tools/plugin/test_memory.cpp -o /tmp/vdj-memory-test
/tmp/vdj-memory-test
# Named build-9246 argument-consumer pilot, anchored to the memory probe.
tail-consumers *args:
@{{python}} tools/tail_consumers.py {{args}}
tail-consumers-test:
@{{python}} -m unittest discover -s tools -p test_tail_consumers.py
# Verified Ghidra export from the existing analyzed build-9246 project.
ghidra-time-consumers *args:
@{{python}} tools/ghidra_time_consumers.py {{args}}
ghidra-time-consumers-test:
@{{python}} -m unittest discover -s tools -p test_ghidra_time_consumers.py
# Fixed-input, build-gated parser object experiment; never executes parsed scripts.
offline-parser *args:
@{{python}} tools/offline_parser.py {{args}}
# Saved-capture parity and converter rejection tests; does not load vendor code.
offline-parser-check:
@{{python}} -m unittest discover -s tools -p test_offline_parser.py
@{{python}} tools/offline_parser.py check --output tests/offline-parser-9644.json
@{{python}} tools/offline_parser.py check --output tests/offline-parser-9246.json
@{{python}} tools/offline_parser.py check --output tests/offline-parser-9644-generated-guards.json
plugin-parser-build *args:
tools/plugin/build.sh --parser {{args}}
plugin-parser-test:
clang++ -std=c++17 -arch arm64 -I vendor/vdj-sdk/audio-plugin-dsp-example-1 -framework CoreFoundation tools/plugin/test_parser.cpp -o /tmp/vdj-parser-test
/tmp/vdj-parser-test
{{python}} -m unittest discover -s tools -p test_parser_objects.py
{{python}} tools/prepare_parser_probe.py --check
# Small decoded view; validates complete capture, guards, ownership and repeat agreement.
parser-objects *args:
{{python}} tools/parser_objects.py {{args}}
# Current-build is_using consumer candidates joined to public SDK capture results.
is-using-keywords:
{{python}} tools/is_using_keywords.py
plugin-keywords-build *args:
tools/plugin/build.sh --keywords {{args}}
# Verify stopped sign captures, boundary readbacks and restoration evidence.
time-sign-check:
{{python}} tools/probe_time_sign_positions.py --check tests/time-sign-positions-9644.json
{{python}} -m unittest discover -s tools -p test_time_sign_positions.py
{{python}} tools/probe_time_sign_loaded.py --check tests/time-sign-loaded-9644.json
{{python}} -m unittest discover -s tools -p test_time_sign_loaded.py
# Build-scoped named XML reader audit; queries need only stdlib.
skin-reader-audit *args:
@{{python}} tools/skin_reader_audit.py {{args}}
# Breadth-first structural entries with canonical shared readers; no behavior claim.
skin-structure *args:
@{{python}} tools/skin_structure.py {{args}}
# Paired native fixtures for class, placeholder and condition expansion on 9246 (Tier 2).
# `check` reads the saved capture; prepare/run need the binary and capstone.
skin-expansion *args:
@{{python}} tools/probe_skin_expansion.py {{args}}
# Which tags 9246 recognizes where, and the role each plays (object, wrapper, directive,
# slot, container, data). Queries read the saved capture; --extract/--check --app need the binary.
skin-dispatch *args:
@{{python}} tools/skin_dispatch.py {{args}}
# Shared skin attribute contracts; Markdown is a stdout artifact, JSON retains evidence.
skin-attributes element *args:
@{{python}} tools/skin_attributes.py {{quote(element)}} {{args}}
# Fixed-input native XML/skin factory spike on symbol-rich 9246.
offline-xml *args:
@{{python}} tools/offline_xml.py {{args}}
offline-xml-trace *args:
@{{python}} tools/trace_offline_xml.py {{args}}
# Saved evidence only; does not load vendor code or start a debugger.
offline-xml-check:
@{{python}} tools/check_offline_xml.py
just offline-xml-unknowns-check
# Paired known/unknown XML inputs and hardware read watches.
offline-xml-unknowns *args:
@{{python}} tools/probe_xml_unknowns.py {{args}}
offline-xml-unknowns-check:
@{{python}} tools/check_xml_unknowns.py
# Native skin loading and GPU-backed headless preview spike.
offline-skin-host *args:
@{{python}} tools/probe_skin_host.py {{args}}
# Validate saved frame and traces without executing vendor code.
offline-skin-host-check:
@{{python}} tools/check_skin_host.py
# Native composition fixtures, or show a saved tree without running vendor code.
offline-skin-composition *args:
@{{python}} tools/probe_skin_composition.py {{args}}
offline-skin-composition-check:
@{{python}} tools/check_skin_composition.py
# Partial native parent/child rules; unknown coverage is not a rejection rule.
native-skin-children *args:
@{{python}} tools/native_skin_children.py {{args}}
skin-child-readers *args:
@{{python}} tools/extract_skin_relationships.py {{args}}
skin-child-probe *args:
@{{python}} tools/probe_skin_relationships.py {{args}}
skin-child-trace *args:
@{{python}} tools/trace_skin_relationships.py {{args}}
skin-child-check:
@{{python}} tools/check_skin_relationships.py