rcdebug 1.0.0__py3-none-any.whl

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.
rcdebug/__init__.py ADDED
@@ -0,0 +1,7 @@
1
+ """
2
+ rcdebug - Revan Cool Debugger
3
+ Local Roblox Studio Runtime Bridge & MCP Security/Performance Auditor
4
+ """
5
+
6
+ __version__ = "1.0.0"
7
+ __author__ = "Revan"
rcdebug/cli.py ADDED
@@ -0,0 +1,475 @@
1
+ """
2
+ CLI entrypoint for rcdebug (Revan Cool Debugger).
3
+ """
4
+
5
+ from __future__ import annotations
6
+
7
+ import argparse
8
+ import sys
9
+ import time
10
+
11
+ from pathlib import Path
12
+
13
+ from . import __version__
14
+ from .client_bridge import DebugReportHandler, RobloxLogTailer, RuntimeBridgeServer, run_client_mode
15
+ from .debugger_pack import get_debugger_pack
16
+ from .flaw_catalog import get_catalog
17
+ from .github_harvester import harvest_github_luau
18
+ from .learner import AutonomousBrainSync, CommandHistory, seed_training_history
19
+ from .mcp_inspector import audit_local_path, find_studio_mcp, run_live_mcp_audit, run_server_mode
20
+ from .models import AuditSession, SeverityFilter, matches_filter, normalize_filter_set, normalize_severity
21
+ from .terminal import BOLD, CYAN, DIM, GREEN, RED, RESET, YELLOW, print_banner, severity_badge
22
+
23
+
24
+ def build_parser() -> argparse.ArgumentParser:
25
+ parser = argparse.ArgumentParser(
26
+ prog="rcdebug",
27
+ description=(
28
+ "rcdebug (Revan Cool Debugger) — macOS CLI developer and security-auditing tool "
29
+ "for Roblox Studio (Runtime Bridge & MCP Inspector)."
30
+ ),
31
+ formatter_class=argparse.RawDescriptionHelpFormatter,
32
+ epilog=(
33
+ "Examples:\n"
34
+ " rcdebug --client Start local bridge on 127.0.0.1:8765 & copy Luau snippet\n"
35
+ " rcdebug --client --filter WARN --export audit.md\n"
36
+ " rcdebug --server Auto-discover Roblox Studio MCP & run static audit\n"
37
+ " rcdebug --server --place ./src --export static_audit.md\n"
38
+ " rcdebug --client --simulate --export demo_report.md\n"
39
+ ),
40
+ )
41
+
42
+ parser.add_argument(
43
+ "-v",
44
+ "--version",
45
+ action="version",
46
+ version=f"rcdebug {__version__}",
47
+ )
48
+
49
+ mode_group = parser.add_mutually_exclusive_group(required=False)
50
+ mode_group.add_argument(
51
+ "--client",
52
+ action="store_true",
53
+ help="Start Studio Runtime Bridge listener (127.0.0.1:8765) & auto-copy Luau diagnostic snippet via pbcopy",
54
+ )
55
+ mode_group.add_argument(
56
+ "--server",
57
+ action="store_true",
58
+ help="Auto-discover Roblox Studio MCP config & perform static scene/script security audits",
59
+ )
60
+ mode_group.add_argument(
61
+ "--catalog",
62
+ nargs="?",
63
+ const="",
64
+ default=None,
65
+ metavar="QUERY",
66
+ help="Search or inspect the 120,000-flaw database loaded from flaws_120000.txt",
67
+ )
68
+ mode_group.add_argument(
69
+ "--learn",
70
+ nargs="?",
71
+ const="",
72
+ default=None,
73
+ metavar="PATH",
74
+ help="Learn flaw patterns from a local place/scripts path, live Studio MCP, or recent Roblox logs",
75
+ )
76
+ mode_group.add_argument(
77
+ "--history",
78
+ action="store_true",
79
+ help="Show JSON terminal command history & learned brain statistics (~/.rcdebug/command_history.json)",
80
+ )
81
+ mode_group.add_argument(
82
+ "--pack",
83
+ nargs="?",
84
+ const="",
85
+ default=None,
86
+ metavar="QUERY",
87
+ help="Search or inspect the 120-source Light Luau Debugger Pack",
88
+ )
89
+ mode_group.add_argument(
90
+ "--watch",
91
+ action="store_true",
92
+ help="Run continuous autonomous brain sync watching command_history.json & Roblox logs",
93
+ )
94
+
95
+ parser.add_argument(
96
+ "--export",
97
+ metavar="FILE.md",
98
+ type=str,
99
+ default=None,
100
+ help="Generate a clean Markdown security & QA audit report after the session",
101
+ )
102
+ parser.add_argument(
103
+ "--filter",
104
+ metavar="SEVERITY",
105
+ type=str,
106
+ choices=["CRITICAL", "WARN", "WARNING", "INFO", "critical", "warn", "warning", "info"],
107
+ default=None,
108
+ help="Filter terminal & exported findings by severity (CRITICAL, WARN, or INFO)",
109
+ )
110
+ parser.add_argument(
111
+ "--critical",
112
+ action="store_true",
113
+ help="Show only CRITICAL flaws (combine with --warning / --info to include multiple levels)",
114
+ )
115
+ parser.add_argument(
116
+ "--warning",
117
+ "--warn",
118
+ action="store_true",
119
+ help="Show only WARN flaws (combine with --critical / --info to include multiple levels)",
120
+ )
121
+ parser.add_argument(
122
+ "--info",
123
+ action="store_true",
124
+ help="Show only INFO flaws (combine with --critical / --warning to include multiple levels)",
125
+ )
126
+ parser.add_argument(
127
+ "--host",
128
+ type=str,
129
+ default="127.0.0.1",
130
+ help="Host address for --client HTTP/WebSocket listener (default: 127.0.0.1)",
131
+ )
132
+ parser.add_argument(
133
+ "--port",
134
+ type=int,
135
+ default=8765,
136
+ help="Port for --client HTTP/WebSocket listener (default: 8765)",
137
+ )
138
+ parser.add_argument(
139
+ "--place",
140
+ metavar="PATH",
141
+ type=str,
142
+ default=None,
143
+ help="Optional path to a local .rbxlx/.rbxmx place file or Luau scripts folder for --server static audit",
144
+ )
145
+ parser.add_argument(
146
+ "--no-clipboard",
147
+ action="store_true",
148
+ help="Disable automatic pbcopy clipboard copy in --client mode",
149
+ )
150
+ parser.add_argument(
151
+ "--no-log-tail",
152
+ action="store_true",
153
+ help="Disable automatic ~/Library/Logs/Roblox/ log bridge tailing in --client mode",
154
+ )
155
+ parser.add_argument(
156
+ "--replay-log",
157
+ action="store_true",
158
+ help="Replay existing [rcdebug-wire]/[rcdebug-console] lines from the newest Roblox log file on startup",
159
+ )
160
+ parser.add_argument(
161
+ "--simulate",
162
+ action="store_true",
163
+ help="Run a self-contained simulation of Studio telemetry or MCP static audit for testing/preview",
164
+ )
165
+ parser.add_argument(
166
+ "--github",
167
+ action="store_true",
168
+ help="In --learn mode, harvest open-source Luau repositories from GitHub into FlawBrain",
169
+ )
170
+ parser.add_argument(
171
+ "--limit",
172
+ type=int,
173
+ default=20,
174
+ help="Maximum results to display in --catalog mode (default: 20)",
175
+ )
176
+
177
+ return parser
178
+
179
+
180
+ def resolve_filter_levels(args: argparse.Namespace) -> SeverityFilter:
181
+ levels: set[str] = set()
182
+ if getattr(args, "filter", None):
183
+ levels.add(normalize_severity(args.filter))
184
+ if getattr(args, "critical", False):
185
+ levels.add("CRITICAL")
186
+ if getattr(args, "warning", False):
187
+ levels.add("WARN")
188
+ if getattr(args, "info", False):
189
+ levels.add("INFO")
190
+ return frozenset(levels) if levels else None
191
+
192
+
193
+ def _run_catalog_mode(query: str, filter_level: SeverityFilter, limit: int) -> int:
194
+ catalog = get_catalog()
195
+ print_banner(
196
+ "FLAW KNOWLEDGE BASE",
197
+ subtitle=f"{catalog.signature_count():,} Domain Signatures + {catalog.static_rule_count()} Static Rules ({catalog.count():,} total)",
198
+ )
199
+ results = catalog.search(query, limit=max(1, limit * 5))
200
+ if filter_level:
201
+ results = [r for r in results if matches_filter(r.severity, filter_level)]
202
+ results = results[: max(1, limit)]
203
+
204
+ if not results:
205
+ print(f"\n{YELLOW}No flaw signatures matched query '{query}'.{RESET}\n")
206
+ return 0
207
+
208
+ print(f"\n{BOLD}Showing {len(results)} matching signatures{f' for {query!r}' if query else ''}:{RESET}\n")
209
+ for sig in results:
210
+ print(f"{severity_badge(sig.severity)} {BOLD}{CYAN}{sig.code}{RESET} {BOLD}{sig.title}{RESET}")
211
+ print(f" {DIM}Flaw:{RESET} {sig.flaw}")
212
+ print(f" {DIM}Abuse:{RESET} {sig.abuse}")
213
+ print(f" {GREEN}Fix:{RESET} {sig.fix}\n")
214
+ return 0
215
+
216
+
217
+ def _run_learn_mode(target_path: str, filter_level: SeverityFilter, limit: int) -> int:
218
+ catalog = get_catalog()
219
+ print_banner(
220
+ "ADAPTIVE PLACE LEARNER",
221
+ subtitle=f"{catalog.count():,} Base Flaws + {len(catalog.learner.learned_tokens)} Learned Patterns",
222
+ )
223
+
224
+ session = AuditSession(mode="learn", target_name="Place Learning Session")
225
+ if target_path:
226
+ p = Path(target_path).expanduser().resolve()
227
+ if not p.exists():
228
+ print(f"{RED}✖ Path does not exist: {p}{RESET}\n")
229
+ return 1
230
+ session.target_name = f"Place ({p.name})"
231
+ print(f"\n{CYAN}→ Learning from place/scripts:{RESET} {BOLD}{p}{RESET}")
232
+ audit_local_path(p, session, filter_level=filter_level)
233
+ else:
234
+ # 1. Learn from recent Roblox Player/Studio logs
235
+ print(f"\n{CYAN}→ Scanning recent Roblox logs & Studio MCP for learnable patterns...{RESET}")
236
+ temp_srv = RuntimeBridgeServer(("127.0.0.1", 0), DebugReportHandler, session=session, filter_level=filter_level)
237
+ try:
238
+ tailer = RobloxLogTailer(temp_srv, replay_latest=True)
239
+ tailer._init_offsets()
240
+ tailer.poll_once()
241
+ finally:
242
+ temp_srv.server_close()
243
+
244
+ # 2. Also probe live Studio MCP if available
245
+ mcp_info = find_studio_mcp()
246
+ if mcp_info:
247
+ run_live_mcp_audit(mcp_info["config"], session, filter_level=filter_level)
248
+
249
+ new_tokens = catalog.learner.learn_from_session(session, catalog)
250
+ print(f"\n{GREEN}{BOLD}✔ Learning Complete:{RESET} +{new_tokens} new token(s) learned from {len(session.findings)} finding(s).")
251
+ print(f" {BOLD}Total Learned Patterns:{RESET} {len(catalog.learner.learned_tokens)}")
252
+ print(f" {BOLD}Knowledge Store:{RESET} {CYAN}{catalog.learner.store_path}{RESET}")
253
+ print(f" {BOLD}Text Export:{RESET} {CYAN}{catalog.learner.txt_path}{RESET}")
254
+
255
+ if catalog.learner.learned_tokens:
256
+ print(f"\n{BOLD}Top Learned Game Patterns:{RESET}")
257
+ top = sorted(
258
+ catalog.learner.learned_tokens.items(),
259
+ key=lambda kv: (-int(kv[1].get("seen_count", 1)), kv[0]),
260
+ )[: max(1, limit)]
261
+ for tok, info in top:
262
+ print(
263
+ f" {severity_badge(str(info.get('severity', 'WARN')))} {BOLD}{tok}{RESET} "
264
+ f"{DIM}(seen {info.get('seen_count', 1)}x, domain: {info.get('domain', 'Learned')}){RESET}"
265
+ )
266
+ print()
267
+ return 0
268
+
269
+
270
+ def _run_history_mode(history: CommandHistory, limit: int) -> int:
271
+ catalog = get_catalog()
272
+ print_banner(
273
+ "COMMAND HISTORY & BRAIN",
274
+ subtitle=f"{len(history.entries)} Logged Commands | {len(catalog.learner.learned_tokens)} Learned Tokens | {catalog.count():,} Base Flaws",
275
+ )
276
+ print(f"\n{BOLD}History JSON:{RESET} {CYAN}{history.history_path}{RESET}")
277
+ print(f"{BOLD}Learned JSON:{RESET} {CYAN}{catalog.learner.store_path}{RESET}")
278
+ print(
279
+ f"{BOLD}Flaw Brain:{RESET} {CYAN}{catalog.brain.brain_path}{RESET} "
280
+ f"{DIM}({catalog.brain.total_flaws_learned:,} flaws learned, {len(catalog.brain.token_domain_weights):,} concepts){RESET}"
281
+ )
282
+
283
+ if history.domain_weights:
284
+ top_doms = sorted(history.domain_weights.items(), key=lambda kv: (-kv[1], kv[0]))[:8]
285
+ dom_str = ", ".join(f"{d} ({n}x)" for d, n in top_doms)
286
+ print(f"{BOLD}Top Domains:{RESET} {dom_str}")
287
+
288
+ recent = history.entries[-max(1, limit):]
289
+ print(f"\n{BOLD}Recent {len(recent)} Command(s):{RESET}\n")
290
+ for item in reversed(recent):
291
+ tag = f"{DIM}[SEED]{RESET} " if item.get("synthetic") else f"{GREEN}[LIVE]{RESET} "
292
+ print(
293
+ f" {tag}{DIM}{item.get('timestamp', '')}{RESET} {BOLD}{item.get('command', '')}{RESET} "
294
+ f"{DIM}({item.get('findings_count', 0)} findings, +{item.get('learned_tokens_added', 0)} learned, {item.get('duration_ms', 0):.1f}ms){RESET}"
295
+ )
296
+ print()
297
+ return 0
298
+
299
+
300
+ def _run_pack_mode(query: str, filter_level: SeverityFilter, limit: int) -> int:
301
+ pack = get_debugger_pack()
302
+ print_banner(
303
+ "LIGHT LUAU DEBUGGER PACK",
304
+ subtitle=f"{pack.count()} Compiled Luau Probes (Selene, luau-lsp, luau-lang, Trove, Janitor, Iris, Cmdr, TestEZ, Roblox)",
305
+ )
306
+ results = pack.search(query, limit=max(1, limit * 4))
307
+ if filter_level:
308
+ results = [p for p in results if matches_filter(p.severity, filter_level)]
309
+ results = results[: max(1, limit)]
310
+
311
+ if not results:
312
+ print(f"\n{YELLOW}No debugger probes matched '{query}'.{RESET}\n")
313
+ return 0
314
+
315
+ print(f"\n{BOLD}Showing {len(results)} probe(s){f' for {query!r}' if query else ''}:{RESET}\n")
316
+ for p in results:
317
+ print(f"{severity_badge(p.severity)} {BOLD}{CYAN}{p.id}{RESET} {BOLD}{p.name}{RESET} {DIM}[{p.source}]{RESET}")
318
+ print(f" {DIM}Cause:{RESET} {p.root_cause}")
319
+ print(f" {GREEN}Fix:{RESET} {p.fix}\n")
320
+ return 0
321
+
322
+
323
+ def _run_watch_mode(catalog, history: CommandHistory, sync: AutonomousBrainSync) -> int:
324
+ print_banner(
325
+ "AUTONOMOUS BRAIN WATCHER",
326
+ subtitle="Continuously learning from command_history.json & ~/Library/Logs/Roblox/ (Ctrl+C to stop)",
327
+ )
328
+ print(f"\n{GREEN}● Watching:{RESET} {CYAN}{history.history_path}{RESET}")
329
+ print(f"{GREEN}● Watching:{RESET} {CYAN}{sync.log_dir}{RESET}")
330
+ print(f"{DIM} Current learned tokens: {len(catalog.learner.learned_tokens)} | Base flaws: {catalog.count():,}{RESET}\n")
331
+ try:
332
+ while True:
333
+ added = sync.sync_once(catalog, history)
334
+ if added > 0:
335
+ print(
336
+ f"{GREEN}[brain-sync]{RESET} Learned +{added} new token(s) "
337
+ f"({len(catalog.learner.learned_tokens)} total)"
338
+ )
339
+ time.sleep(2.0)
340
+ except KeyboardInterrupt:
341
+ print(f"\n{YELLOW}[rcdebug] Autonomous watcher stopped.{RESET}\n")
342
+ return 0
343
+
344
+
345
+ def main(argv: list[str] | None = None) -> int:
346
+ t0 = time.perf_counter()
347
+ raw_argv = list(argv) if argv is not None else sys.argv[1:]
348
+ parser = build_parser()
349
+ args = parser.parse_args(argv)
350
+ if (
351
+ not args.client
352
+ and not args.server
353
+ and args.catalog is None
354
+ and args.learn is None
355
+ and not args.history
356
+ and args.pack is None
357
+ and not args.watch
358
+ ):
359
+ args.client = True
360
+
361
+ filter_level = resolve_filter_levels(args)
362
+ filter_list = sorted(normalize_filter_set(filter_level) or ())
363
+
364
+ catalog = get_catalog()
365
+ history = CommandHistory()
366
+ if not history.entries:
367
+ seed_training_history(catalog, history=history, count=24)
368
+
369
+ # Always read command_history.json & Roblox logs to learn automatically on every run
370
+ brain_sync = AutonomousBrainSync()
371
+ brain_sync.sync_once(catalog, history)
372
+
373
+ if args.watch:
374
+ return _run_watch_mode(catalog, history, brain_sync)
375
+
376
+ if args.pack is not None:
377
+ rc = _run_pack_mode(args.pack, filter_level=filter_level, limit=args.limit)
378
+ history.record_run(
379
+ argv=raw_argv,
380
+ mode="pack",
381
+ target=args.pack or "*",
382
+ filters=filter_list,
383
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
384
+ )
385
+ return rc
386
+
387
+ if args.history:
388
+ rc = _run_history_mode(history, limit=args.limit)
389
+ history.record_run(
390
+ argv=raw_argv,
391
+ mode="history",
392
+ filters=filter_list,
393
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
394
+ )
395
+ return rc
396
+
397
+ if args.learn is not None:
398
+ if args.github:
399
+ res = harvest_github_luau(query=args.learn or "roblox luau", brain=catalog.brain)
400
+ print(f"\n{GREEN}{BOLD}✔ GitHub Harvester:{RESET} {res.message} (+{res.patterns_learned} distilled)\n")
401
+ return 0
402
+ before_learned = len(catalog.learner.learned_tokens)
403
+ rc = _run_learn_mode(args.learn, filter_level=filter_level, limit=args.limit)
404
+ history.record_run(
405
+ argv=raw_argv,
406
+ mode="learn",
407
+ target=args.learn or "RobloxLogs/StudioMCP",
408
+ filters=filter_list,
409
+ learned_added=max(0, len(catalog.learner.learned_tokens) - before_learned),
410
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
411
+ )
412
+ return rc
413
+
414
+ if args.catalog is not None:
415
+ rc = _run_catalog_mode(args.catalog, filter_level=filter_level, limit=args.limit)
416
+ history.record_run(
417
+ argv=raw_argv,
418
+ mode="catalog",
419
+ target=args.catalog or "*",
420
+ filters=filter_list,
421
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
422
+ )
423
+ return rc
424
+
425
+ if args.client:
426
+ before_learned = len(catalog.learner.learned_tokens)
427
+ session = run_client_mode(
428
+ host=args.host,
429
+ port=args.port,
430
+ filter_level=filter_level,
431
+ export_path=args.export,
432
+ auto_clipboard=not args.no_clipboard,
433
+ simulate=args.simulate,
434
+ enable_log_tail=not args.no_log_tail,
435
+ replay_latest_log=args.replay_log,
436
+ )
437
+ history.record_run(
438
+ argv=raw_argv,
439
+ mode="client",
440
+ target=session.target_name,
441
+ filters=filter_list,
442
+ findings_count=len(session.findings),
443
+ severity_counts=session.counts_by_severity(),
444
+ domains_seen=[str(f.metadata.get("domain", f.category)) for f in session.findings],
445
+ learned_added=max(0, len(catalog.learner.learned_tokens) - before_learned),
446
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
447
+ )
448
+ return 0
449
+
450
+ if args.server:
451
+ before_learned = len(catalog.learner.learned_tokens)
452
+ session = run_server_mode(
453
+ filter_level=filter_level,
454
+ export_path=args.export,
455
+ place_path=args.place,
456
+ simulate=args.simulate,
457
+ )
458
+ history.record_run(
459
+ argv=raw_argv,
460
+ mode="server",
461
+ target=session.target_name,
462
+ filters=filter_list,
463
+ findings_count=len(session.findings),
464
+ severity_counts=session.counts_by_severity(),
465
+ domains_seen=[str(f.metadata.get("domain", f.category)) for f in session.findings],
466
+ learned_added=max(0, len(catalog.learner.learned_tokens) - before_learned),
467
+ duration_ms=(time.perf_counter() - t0) * 1000.0,
468
+ )
469
+ return 0
470
+
471
+ return 1
472
+
473
+
474
+ if __name__ == "__main__":
475
+ sys.exit(main())