unidecompiler-cli 0.1.2__tar.gz → 0.2.0__tar.gz

unidecompiler_cli-0.2.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: unidecompiler-cli
+Version: 0.2.0
+Summary: Command-line host for unidecompiler plugins
+Author-email: Wker <1670133844@qq.com>
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Wker666/unidecompiler
+Project-URL: Repository, https://github.com/Wker666/unidecompiler
+Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: unidecompiler<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-export<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-simulation-host-python<0.3.0,>=0.2.0
+
+# unidecompiler-cli
+
+`unidecompiler-cli` is the command-line host for installed `unidecompiler`
+frontend plugins. It discovers plugins through the `unidecompiler.frontends`
+entry-point group and uses the public `DecompilerEngine` facade.
+
+Install the CLI and one or more frontend packages:
+
+```sh
+python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
+```
+
+Run `unidecompiler --help` for command-line usage.
+
+Progress is disabled by default so ordinary output remains clean for shell
+pipelines. Enable the single-line two-level progress bar explicitly with
+`--progress` (TTY auto mode) or `--progress always`; it is written only to
+stderr. Use `--progress never` to make the disabled behavior explicit.
+
+Use `-o/--output` to write one successful artifact to a file, or
+`--output-dir` to export every successful artifact from a batch. Directory
+exports use sanitized basenames and never overwrite an existing file; these
+options leave stdout empty and report the destinations on stderr:
+
+```sh
+unidecompiler sample.pyc --output sample.pseudocode.txt
+unidecompiler samples/ --output-dir decompiled/
+unidecompiler samples/ --format ast-json --output-dir ast/
+```
+
+For a VS Code navigation sidecar, opt in explicitly and provide both paths.
+The sidecar is written after the pseudocode file and is never generated by a
+normal export. It is available only for one pseudocode `--output` export, not
+for `--output-dir` or `--format ast-json`:
+
+```sh
+unidecompiler sample.pyc \
+  --output sample.pseudocode.txt \
+  --vscode-metadata sample.pseudocode.txt.unidec.json
+```
+
+The sidecar contains the exported text's UTF-8 SHA-256, UTF-16 source-map
+offsets, and minimal instruction navigation facts. It does not repeat the
+pseudocode or include source paths, AST, IR, CFG, diagnostics, or other engine
+data.
+
+Starter projects are exported through the host-side template package as well:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author "Your Name" \
+  --description "My bytecode frontend" \
+  --requirements "Decode and lift the VM" \
+  --suffix .vm --version 1
+
+unidecompiler template gui_plugin MyPanel -o ./my-panel \
+  --author "Your Name" \
+  --description "A read-only GUI panel" \
+  --requirements "Show analysis data"
+```
+
+The same template export is available as an interactive wizard:
+
+```sh
+unidecompiler template --interactive
+```
+
+The short form is `unidecompiler template -i`. The wizard only collects
+template settings and then calls the same host-side exporter; it does not
+change decompilation or recovery behavior.
+
+Frontend templates can opt into the simulator and AI kit explicitly:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author A --description D --requirements R \
+  --suffix .vm --version 1 \
+  --simulation --ai-guidance \
+  --interpreter-source ./vm_interpreter.c \
+  --bytecode-sample ./sample.bin \
+  --entry-kind symbol --entry-value main
+```
+
+Both options also accept `--no-simulation` and `--no-ai-guidance`; they are
+disabled by default. AI guidance validates the supplied files for size,
+regular-file status, and likely credentials before copying them.
+
+`export-template` is accepted as an alias. Template export is atomic and never
+overwrites an existing destination directory.
+
+The optional simulator command is hosted here, while execution remains in the
+separate simulator library:
+
+```sh
+unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
+```
+
+For trusted programs that require functions outside the lifted module, pass a
+Python environment file. Top-level functions are matched by name, while their
+stdout and stderr are returned as structured simulation events:
+
+```sh
+unidecompiler simulate sample.pyc --function main --environment runtime.py
+```

unidecompiler_cli-0.2.0/README.md

@@ -0,0 +1,104 @@
+# unidecompiler-cli
+
+`unidecompiler-cli` is the command-line host for installed `unidecompiler`
+frontend plugins. It discovers plugins through the `unidecompiler.frontends`
+entry-point group and uses the public `DecompilerEngine` facade.
+
+Install the CLI and one or more frontend packages:
+
+```sh
+python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
+```
+
+Run `unidecompiler --help` for command-line usage.
+
+Progress is disabled by default so ordinary output remains clean for shell
+pipelines. Enable the single-line two-level progress bar explicitly with
+`--progress` (TTY auto mode) or `--progress always`; it is written only to
+stderr. Use `--progress never` to make the disabled behavior explicit.
+
+Use `-o/--output` to write one successful artifact to a file, or
+`--output-dir` to export every successful artifact from a batch. Directory
+exports use sanitized basenames and never overwrite an existing file; these
+options leave stdout empty and report the destinations on stderr:
+
+```sh
+unidecompiler sample.pyc --output sample.pseudocode.txt
+unidecompiler samples/ --output-dir decompiled/
+unidecompiler samples/ --format ast-json --output-dir ast/
+```
+
+For a VS Code navigation sidecar, opt in explicitly and provide both paths.
+The sidecar is written after the pseudocode file and is never generated by a
+normal export. It is available only for one pseudocode `--output` export, not
+for `--output-dir` or `--format ast-json`:
+
+```sh
+unidecompiler sample.pyc \
+  --output sample.pseudocode.txt \
+  --vscode-metadata sample.pseudocode.txt.unidec.json
+```
+
+The sidecar contains the exported text's UTF-8 SHA-256, UTF-16 source-map
+offsets, and minimal instruction navigation facts. It does not repeat the
+pseudocode or include source paths, AST, IR, CFG, diagnostics, or other engine
+data.
+
+Starter projects are exported through the host-side template package as well:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author "Your Name" \
+  --description "My bytecode frontend" \
+  --requirements "Decode and lift the VM" \
+  --suffix .vm --version 1
+
+unidecompiler template gui_plugin MyPanel -o ./my-panel \
+  --author "Your Name" \
+  --description "A read-only GUI panel" \
+  --requirements "Show analysis data"
+```
+
+The same template export is available as an interactive wizard:
+
+```sh
+unidecompiler template --interactive
+```
+
+The short form is `unidecompiler template -i`. The wizard only collects
+template settings and then calls the same host-side exporter; it does not
+change decompilation or recovery behavior.
+
+Frontend templates can opt into the simulator and AI kit explicitly:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author A --description D --requirements R \
+  --suffix .vm --version 1 \
+  --simulation --ai-guidance \
+  --interpreter-source ./vm_interpreter.c \
+  --bytecode-sample ./sample.bin \
+  --entry-kind symbol --entry-value main
+```
+
+Both options also accept `--no-simulation` and `--no-ai-guidance`; they are
+disabled by default. AI guidance validates the supplied files for size,
+regular-file status, and likely credentials before copying them.
+
+`export-template` is accepted as an alias. Template export is atomic and never
+overwrites an existing destination directory.
+
+The optional simulator command is hosted here, while execution remains in the
+separate simulator library:
+
+```sh
+unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
+```
+
+For trusted programs that require functions outside the lifted module, pass a
+Python environment file. Top-level functions are matched by name, while their
+stdout and stderr are returned as structured simulation events:
+
+```sh
+unidecompiler simulate sample.pyc --function main --environment runtime.py
+```

{unidecompiler_cli-0.1.2 → unidecompiler_cli-0.2.0}/pyproject.toml

@@ -4,16 +4,17 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "unidecompiler-cli"
-version = "0.1.2"
+version = "0.2.0"
 description = "Command-line host for unidecompiler plugins"
 readme = "README.md"
 license = "AGPL-3.0-or-later"
 authors = [{ name = "Wker", email = "1670133844@qq.com" }]
 requires-python = ">=3.11"
 dependencies = [
-    "unidecompiler>=0.1.10,<0.2.0",
-    "unidecompiler-simulator>=0.1.5,<0.2.0",
-    "unidecompiler-simulation-host-python>=0.1.2,<0.2.0",
+    "unidecompiler>=0.2.0,<0.3.0",
+    "unidecompiler-export>=0.2.0,<0.3.0",
+    "unidecompiler-simulator>=0.2.0,<0.3.0",
+    "unidecompiler-simulation-host-python>=0.2.0,<0.3.0",
 ]
 
 [project.urls]

unidecompiler_cli-0.2.0/src/unidecompiler_cli/cli.py

@@ -0,0 +1,366 @@
+from __future__ import annotations
+
+import argparse
+import base64
+from dataclasses import fields, is_dataclass
+import json
+import math
+import sys
+from typing import Any
+from pathlib import Path
+
+from unidecompiler.engine import DecompilerEngine
+from unidecompiler_export import (
+    VscodeMetadataExportError,
+    export_pseudocode_documents,
+    export_text_documents,
+    write_pseudocode,
+    write_pseudocode_with_vscode_metadata,
+)
+from unidecompiler.plugin_registry import FrontendRegistry
+from unidecompiler.input_sources import expand_input_path
+from unidecompiler.progress import ProgressEvent, ProgressReporter
+
+
+def main(argv: list[str] | None = None, *, registry: FrontendRegistry | None = None) -> int:
+    command_argv = sys.argv[1:] if argv is None else argv
+    if command_argv and command_argv[0] in {"simulate", "template", "export-template"}:
+        if command_argv[0] in {"template", "export-template"}:
+            from unidecompiler_cli.templates import main as template_main
+
+            return template_main(command_argv[1:])
+        from unidecompiler_cli.simulation import main as simulate_main
+
+        return simulate_main(command_argv[1:], registry=registry)
+    parser = argparse.ArgumentParser(
+        prog="unidecompiler",
+        description="Decompile bytecode into generic pseudocode.",
+        epilog=(
+            "Commands:\n"
+            "  template         export a VM frontend or GUI plugin starter project\n"
+            "  export-template  alias for template\n"
+            "  simulate         run a recovered generic-IR function\n\n"
+            "Template examples:\n"
+            "  unidecompiler template frontend MyVM -o ./my-vm --author NAME "
+            "--description TEXT --requirements TEXT --suffix .vm --version 1\n"
+            "  unidecompiler template --interactive\n\n"
+            "Run 'unidecompiler template --help' for all template options."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("input", nargs="?", help="input bytecode file")
+    parser.add_argument(
+        "--frontend",
+        help="explicit frontend plugin id, e.g. lua",
+        default=None,
+    )
+    parser.add_argument(
+        "--versions",
+        action="store_true",
+        help="print supported frontend version matrix",
+    )
+    parser.add_argument(
+        "--format",
+        choices=("pseudocode", "ast-json"),
+        default="pseudocode",
+        help="output format (default: pseudocode)",
+    )
+    output_group = parser.add_mutually_exclusive_group()
+    output_group.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        help="write one successful result to this file instead of stdout",
+    )
+    output_group.add_argument(
+        "--output-dir",
+        type=Path,
+        help="write every successful result as a separate file in this directory",
+    )
+    parser.add_argument(
+        "--vscode-metadata",
+        type=Path,
+        metavar="PATH",
+        help="write an opt-in VS Code navigation sidecar; requires --output",
+    )
+    parser.add_argument(
+        "--progress",
+        nargs="?",
+        const="auto",
+        default="never",
+        metavar="MODE",
+        help="show a dynamic progress bar on stderr (auto, always, never; default: disabled)",
+    )
+    args = parser.parse_args(command_argv)
+    if args.progress not in {"auto", "always", "never"}:
+        # With an optional argument argparse otherwise treats the positional
+        # input after a bare ``--progress`` as MODE.  Accept that natural
+        # spelling while retaining the explicit ``--progress always`` form.
+        if args.input is None:
+            args.input = args.progress
+            args.progress = "auto"
+        else:
+            parser.error("--progress MODE must be auto, always, or never")
+    if args.vscode_metadata is not None:
+        if args.output_dir is not None:
+            parser.error("--vscode-metadata cannot be used with --output-dir")
+        if args.format == "ast-json":
+            parser.error("--vscode-metadata is available only with --format pseudocode")
+        if args.output is None:
+            parser.error("--vscode-metadata requires --output PATH")
+
+    registry = registry or FrontendRegistry.discover()
+    if args.versions:
+        for plugin, support in registry.version_support():
+            versions = ", ".join(support.versions)
+            print(
+                f"{plugin.id}: {support.family} | {versions} | "
+                f"{support.status} | parser: {support.parser}"
+            )
+        return 0
+
+    if args.input is None:
+        parser.error("input is required unless --versions is used")
+    input_path = Path(args.input)
+    artifacts = expand_input_path(input_path)
+    if not artifacts:
+        raise SystemExit(f"no input files found in {input_path}")
+
+    ast_modules: list[dict[str, Any]] = []
+    successful_results = []
+    processed = 0
+    reporter: ProgressReporter | None = _CLIProgressReporter() if _progress_enabled(args.progress) else None
+    engine = DecompilerEngine.from_registry(registry)
+    results = engine.decompile_artifacts(
+        artifacts,
+        args.frontend,
+        progress=reporter,
+    )
+    for result in results:
+        if result.status == "resource":
+            print(f"resource: {result.display_path}", file=sys.stderr)
+            continue
+        if result.status != "ok":
+            detail = next(
+                (diagnostic.message for diagnostic in result.diagnostics if diagnostic.severity == "error"),
+                result.status,
+            )
+            print(f"error: {result.display_path}: {detail}", file=sys.stderr)
+            continue
+        if args.format == "ast-json":
+            if result.ast is not None:
+                ast_modules.append(_json_value(result.ast))
+        else:
+            if result.pseudocode is not None and args.output is None and args.output_dir is None:
+                print(result.pseudocode.text)
+        successful_results.append(result)
+        processed += 1
+
+    if processed == 0:
+        raise SystemExit(f"no supported input files found in {input_path}")
+    if args.output is not None:
+        if len(successful_results) != 1:
+            raise SystemExit("--output requires exactly one successful input artifact")
+        destination = args.output.expanduser()
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        result = successful_results[0]
+        if args.format == "ast-json":
+            destination.write_text(
+                json.dumps(
+                    {"schema_version": 1, "modules": [_json_value(result.ast)]},
+                    ensure_ascii=False,
+                    sort_keys=True,
+                    allow_nan=False,
+                )
+                + "\n",
+                encoding="utf-8",
+            )
+        else:
+            assert result.pseudocode is not None
+            try:
+                if args.vscode_metadata is None:
+                    write_pseudocode(result, destination)
+                else:
+                    write_pseudocode_with_vscode_metadata(
+                        result,
+                        destination,
+                        args.vscode_metadata.expanduser(),
+                    )
+            except VscodeMetadataExportError as error:
+                raise SystemExit(str(error)) from error
+            except (OSError, ValueError) as error:
+                raise SystemExit(f"could not export pseudocode to {destination}: {error}") from error
+        print(f"exported: {destination}", file=sys.stderr)
+        return 0
+
+    if args.output_dir is not None:
+        directory = args.output_dir.expanduser()
+        directory.mkdir(parents=True, exist_ok=True)
+        if args.format == "ast-json":
+            exported = export_text_documents(
+                (
+                    (
+                        result.display_path,
+                        json.dumps(
+                            {"schema_version": 1, "modules": [_json_value(result.ast)]},
+                            ensure_ascii=False,
+                            sort_keys=True,
+                            allow_nan=False,
+                        )
+                        + "\n",
+                    )
+                    for result in successful_results
+                    if result.ast is not None
+                ),
+                directory,
+                suffix=".ast.json",
+            )
+        else:
+            exported = export_pseudocode_documents(successful_results, directory)
+        print(f"exported {len(exported)} file(s) to: {directory.resolve()}", file=sys.stderr)
+        return 0
+
+    if args.format == "ast-json":
+        print(
+            json.dumps(
+                {"schema_version": 1, "modules": ast_modules},
+                ensure_ascii=False,
+                sort_keys=True,
+                allow_nan=False,
+            )
+        )
+    return 0
+
+
+def _progress_enabled(mode: str) -> bool:
+    return mode == "always" or (mode == "auto" and sys.stderr.isatty())
+
+
+class _CLIProgressReporter:
+    """Render a two-level progress bar without writing to stdout.
+
+    The reporter deliberately uses only carriage-return updates.  This keeps
+    pseudocode/JSON on stdout pipe-safe and avoids making the CLI depend on a
+    terminal UI library for a small host-side presentation concern.
+    """
+
+    _BAR_WIDTH = 24
+
+    def __init__(self, stream=None) -> None:
+        self._stream = sys.stderr if stream is None else stream
+        self._last_length = 0
+        self._finished = False
+
+    def report(self, event: ProgressEvent) -> None:
+        if self._finished:
+            return
+        line = self._format_line(event)
+        padding = max(0, self._last_length - len(line))
+        self._stream.write("\r" + line + (" " * padding))
+        self._stream.flush()
+        self._last_length = len(line)
+        if event.phase == "complete" and event.status in {"completed", "failed", "cancelled"}:
+            is_last = (
+                event.batch_index is None
+                or event.batch_total is None
+                or event.batch_index >= event.batch_total
+            )
+            if is_last:
+                self._stream.write("\n")
+                self._stream.flush()
+                self._finished = True
+
+    def _format_line(self, event: ProgressEvent) -> str:
+        batch_current, batch_total, batch_fraction = self._batch_values(event)
+        file_fraction = self._file_fraction(event)
+        batch = _bar(batch_fraction, self._BAR_WIDTH)
+        current = _bar(file_fraction, self._BAR_WIDTH)
+        batch_count = _count_text(batch_current, batch_total)
+        file_count = _work_count_text(event)
+        detail = event.message or event.phase
+        label = _truncate(event.artifact_label or "artifact", 64)
+        detail_text = f"{event.phase}: {detail} ({label})"
+        return f"Files [{batch}] {batch_count} | File [{current}] {file_count} | {detail_text}"
+
+    @staticmethod
+    def _batch_values(event: ProgressEvent) -> tuple[int | None, int | None, float | None]:
+        if event.batch_index is None or event.batch_total is None:
+            return None, None, None
+        total = event.batch_total
+        current = min(total, max(0, event.batch_index))
+        return current, total, (current / total if total > 0 else None)
+
+    @staticmethod
+    def _file_fraction(event: ProgressEvent) -> float | None:
+        if event.phase == "complete":
+            return 1.0 if event.status in {"completed", "failed", "cancelled"} else 0.0
+        if event.fraction is not None:
+            return event.fraction
+        if event.status == "completed":
+            return 1.0
+        if event.status == "started":
+            return 0.0
+        return None
+
+
+def _bar(fraction: float | None, width: int) -> str:
+    if fraction is None:
+        return "?".ljust(width, "-")
+    filled = min(width, max(0, round(fraction * width)))
+    return "#" * filled + "-" * (width - filled)
+
+
+def _count_text(current: int | None, total: int | None) -> str:
+    if current is None or total is None:
+        return "?/?"
+    return f"{current}/{total}"
+
+
+def _work_count_text(event: ProgressEvent) -> str:
+    if event.completed is None or event.total is None:
+        return "?/?"
+    return f"{event.completed}/{event.total} {event.unit}"
+
+
+def _truncate(value: str, limit: int) -> str:
+    if len(value) <= limit:
+        return value
+    if limit <= 1:
+        return value[:limit]
+    return value[: limit - 1] + "…"
+
+
+def _json_value(value: Any) -> Any:
+    """Convert the generic AST dataclasses into a JSON-compatible tree."""
+    if is_dataclass(value):
+        return {
+            "node_type": type(value).__name__,
+            **{field.name: _json_value(getattr(value, field.name)) for field in fields(value)},
+        }
+    if isinstance(value, bytes | bytearray | memoryview):
+        return {
+            "value_type": "bytes",
+            "base64": base64.b64encode(bytes(value)).decode("ascii"),
+        }
+    if isinstance(value, complex):
+        return {"value_type": "complex", "real": value.real, "imag": value.imag}
+    if isinstance(value, float) and not math.isfinite(value):
+        return {"value_type": "float", "value": repr(value)}
+    if isinstance(value, tuple | list):
+        return [_json_value(item) for item in value]
+    if isinstance(value, dict):
+        if all(isinstance(key, str) for key in value):
+            return {key: _json_value(item) for key, item in value.items()}
+        return {
+            "value_type": "map",
+            "entries": [[_json_value(key), _json_value(item)] for key, item in value.items()],
+        }
+    if isinstance(value, set | frozenset):
+        return {"value_type": "set", "items": [_json_value(item) for item in sorted(value, key=repr)]}
+    if value is None or isinstance(value, str | int | float | bool):
+        return value
+    raise TypeError(f"AST JSON cannot encode {type(value).__name__}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

unidecompiler_cli-0.2.0/src/unidecompiler_cli/templates.py

@@ -0,0 +1,208 @@
+"""CLI host for exporting frontend and GUI plugin starter projects."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from unidecompiler_export.templates import (
+    TemplateExportError,
+    TemplateRequest,
+    derive_project_names,
+    export_template,
+)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        prog="unidecompiler template",
+        description="Export a VM frontend or GUI plugin starter project.",
+    )
+    parser.add_argument(
+        "--interactive", "-i", action="store_true",
+        help="collect template settings through an interactive prompt",
+    )
+    parser.add_argument("kind", choices=("frontend", "gui_plugin"), nargs="?")
+    parser.add_argument("project_name", nargs="?")
+    parser.add_argument("--output-directory", "-o", type=Path)
+    parser.add_argument("--author")
+    parser.add_argument("--description")
+    parser.add_argument("--requirements")
+    parser.add_argument("--vm-name", default=None)
+    parser.add_argument("--suffix", dest="suffixes", action="append", default=[])
+    parser.add_argument("--version", dest="versions", action="append", default=[])
+    parser.add_argument(
+        "--simulation",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="include the optional data-only simulator adapter (frontend templates only; default: disabled)",
+    )
+    parser.add_argument(
+        "--ai-guidance",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="include the AI development kit and copied analysis inputs (frontend templates only; default: disabled)",
+    )
+    parser.add_argument(
+        "--interpreter-source",
+        type=Path,
+        help="VM interpreter source required by --ai-guidance",
+    )
+    parser.add_argument(
+        "--bytecode-sample",
+        type=Path,
+        help="bytecode sample required by --ai-guidance",
+    )
+    parser.add_argument(
+        "--entry-kind",
+        choices=("symbol", "offset", "exported_function"),
+        default="",
+        help="VM entry coordinate kind required by --ai-guidance",
+    )
+    parser.add_argument(
+        "--entry-value",
+        default="",
+        help="VM entry symbol, offset, or exported function required by --ai-guidance",
+    )
+    parser.add_argument(
+        "--entry-context",
+        default="",
+        help="optional initial cursor/base, arguments, and setup facts for AI guidance",
+    )
+    args = parser.parse_args(argv)
+    if args.interactive:
+        try:
+            _collect_interactive(args)
+        except (EOFError, KeyboardInterrupt):
+            print("template generation cancelled", file=sys.stderr)
+            return 130
+    else:
+        required_options = (
+            "kind",
+            "project_name",
+            "output_directory",
+            "author",
+            "description",
+            "requirements",
+        )
+        missing = [option for option in required_options if getattr(args, option) in (None, "")]
+        if missing:
+            parser.error("the following arguments are required in non-interactive mode: " + ", ".join(missing))
+
+    # BooleanOptionalAction uses None above only to let the interactive wizard
+    # apply its documented defaults.  The exporter itself receives real bools.
+    args.simulation = bool(args.simulation)
+    args.ai_guidance = bool(args.ai_guidance)
+
+    try:
+        display_name, project_id, package_name = derive_project_names(args.project_name)
+        request = TemplateRequest(
+            kind=args.kind,
+            project_id=project_id,
+            package_name=package_name,
+            display_name=display_name,
+            author=args.author,
+            description=args.description,
+            requirements=args.requirements,
+            output_directory=args.output_directory,
+            vm_name=args.vm_name or display_name,
+            suffixes=tuple(args.suffixes),
+            versions=tuple(args.versions),
+            include_simulation=args.simulation,
+            include_ai_guidance=args.ai_guidance,
+            interpreter_source=args.interpreter_source,
+            bytecode_sample=args.bytecode_sample,
+            entry_kind=args.entry_kind,
+            entry_value=args.entry_value,
+            entry_context=args.entry_context,
+        )
+        destination = export_template(request)
+    except (TemplateExportError, OSError) as error:
+        parser.error(str(error))
+    print(destination)
+    return 0
+
+
+def _collect_interactive(args: argparse.Namespace) -> None:
+    """Fill an argparse namespace from a small, dependency-free wizard."""
+    args.kind = args.kind or _ask_choice("Template kind", ("frontend", "gui_plugin"), "frontend")
+    args.project_name = args.project_name or _ask_required("Project name")
+    args.output_directory = args.output_directory or Path(_ask_required("Output directory"))
+    args.author = args.author or _ask_required("Author")
+    args.description = args.description or _ask_required("Description")
+    args.requirements = args.requirements or _ask_required("Requested feature / requirements")
+
+    if args.kind == "frontend":
+        args.vm_name = args.vm_name or _ask("VM display name", args.project_name)
+        if not args.suffixes:
+            args.suffixes = _ask_csv("Bytecode suffixes", ".vm")
+        if not args.versions:
+            args.versions = _ask_csv("Bytecode versions", "1")
+        if args.simulation is None:
+            args.simulation = _ask_yes_no("Include the optional simulator adapter", False)
+        if args.ai_guidance is None:
+            args.ai_guidance = _ask_yes_no("Include the AI development kit", False)
+        if args.ai_guidance:
+            args.interpreter_source = args.interpreter_source or Path(
+                _ask_required("VM interpreter source file")
+            )
+            args.bytecode_sample = args.bytecode_sample or Path(
+                _ask_required("Bytecode sample file")
+            )
+            args.entry_kind = args.entry_kind or _ask_choice(
+                "VM entry kind", ("symbol", "offset", "exported_function"), "symbol"
+            )
+            args.entry_value = args.entry_value or _ask_required("VM entry value")
+            args.entry_context = args.entry_context or _ask(
+                "Entry context (optional)", ""
+            )
+def _ask(label: str, default: str | None = None) -> str:
+    suffix = f" [{default}]" if default else ""
+    value = _read_prompt(f"{label}{suffix}: ").strip()
+    return value or (default or "")
+
+
+def _ask_required(label: str) -> str:
+    while True:
+        value = _ask(label)
+        if value:
+            return value
+        print(f"{label} is required.", file=sys.stderr)
+
+
+def _ask_choice(label: str, choices: tuple[str, ...], default: str) -> str:
+    choices_text = "/".join(choices)
+    while True:
+        value = _ask(f"{label} ({choices_text})", default)
+        if value in choices:
+            return value
+        print(f"Choose one of: {choices_text}", file=sys.stderr)
+
+
+def _ask_csv(label: str, default: str) -> list[str]:
+    while True:
+        values = [item.strip() for item in _ask(label, default).split(",") if item.strip()]
+        if values:
+            return values
+        print(f"{label} must contain at least one value.", file=sys.stderr)
+
+
+def _ask_yes_no(label: str, default: bool) -> bool:
+    default_text = "Y/n" if default else "y/N"
+    while True:
+        value = _read_prompt(f"{label} ({default_text}): ").strip().lower()
+        if not value:
+            return default
+        if value in {"y", "yes"}:
+            return True
+        if value in {"n", "no"}:
+            return False
+        print("Please answer yes or no.", file=sys.stderr)
+
+
+def _read_prompt(prompt: str) -> str:
+    print(prompt, end="", file=sys.stderr, flush=True)
+    value = sys.stdin.readline()
+    if value == "":
+        raise EOFError
+    return value.rstrip("\r\n")

unidecompiler_cli-0.2.0/src/unidecompiler_cli.egg-info/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: unidecompiler-cli
+Version: 0.2.0
+Summary: Command-line host for unidecompiler plugins
+Author-email: Wker <1670133844@qq.com>
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/Wker666/unidecompiler
+Project-URL: Repository, https://github.com/Wker666/unidecompiler
+Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: unidecompiler<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-export<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-simulator<0.3.0,>=0.2.0
+Requires-Dist: unidecompiler-simulation-host-python<0.3.0,>=0.2.0
+
+# unidecompiler-cli
+
+`unidecompiler-cli` is the command-line host for installed `unidecompiler`
+frontend plugins. It discovers plugins through the `unidecompiler.frontends`
+entry-point group and uses the public `DecompilerEngine` facade.
+
+Install the CLI and one or more frontend packages:
+
+```sh
+python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
+```
+
+Run `unidecompiler --help` for command-line usage.
+
+Progress is disabled by default so ordinary output remains clean for shell
+pipelines. Enable the single-line two-level progress bar explicitly with
+`--progress` (TTY auto mode) or `--progress always`; it is written only to
+stderr. Use `--progress never` to make the disabled behavior explicit.
+
+Use `-o/--output` to write one successful artifact to a file, or
+`--output-dir` to export every successful artifact from a batch. Directory
+exports use sanitized basenames and never overwrite an existing file; these
+options leave stdout empty and report the destinations on stderr:
+
+```sh
+unidecompiler sample.pyc --output sample.pseudocode.txt
+unidecompiler samples/ --output-dir decompiled/
+unidecompiler samples/ --format ast-json --output-dir ast/
+```
+
+For a VS Code navigation sidecar, opt in explicitly and provide both paths.
+The sidecar is written after the pseudocode file and is never generated by a
+normal export. It is available only for one pseudocode `--output` export, not
+for `--output-dir` or `--format ast-json`:
+
+```sh
+unidecompiler sample.pyc \
+  --output sample.pseudocode.txt \
+  --vscode-metadata sample.pseudocode.txt.unidec.json
+```
+
+The sidecar contains the exported text's UTF-8 SHA-256, UTF-16 source-map
+offsets, and minimal instruction navigation facts. It does not repeat the
+pseudocode or include source paths, AST, IR, CFG, diagnostics, or other engine
+data.
+
+Starter projects are exported through the host-side template package as well:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author "Your Name" \
+  --description "My bytecode frontend" \
+  --requirements "Decode and lift the VM" \
+  --suffix .vm --version 1
+
+unidecompiler template gui_plugin MyPanel -o ./my-panel \
+  --author "Your Name" \
+  --description "A read-only GUI panel" \
+  --requirements "Show analysis data"
+```
+
+The same template export is available as an interactive wizard:
+
+```sh
+unidecompiler template --interactive
+```
+
+The short form is `unidecompiler template -i`. The wizard only collects
+template settings and then calls the same host-side exporter; it does not
+change decompilation or recovery behavior.
+
+Frontend templates can opt into the simulator and AI kit explicitly:
+
+```sh
+unidecompiler template frontend MyVM -o ./my-vm \
+  --author A --description D --requirements R \
+  --suffix .vm --version 1 \
+  --simulation --ai-guidance \
+  --interpreter-source ./vm_interpreter.c \
+  --bytecode-sample ./sample.bin \
+  --entry-kind symbol --entry-value main
+```
+
+Both options also accept `--no-simulation` and `--no-ai-guidance`; they are
+disabled by default. AI guidance validates the supplied files for size,
+regular-file status, and likely credentials before copying them.
+
+`export-template` is accepted as an alias. Template export is atomic and never
+overwrites an existing destination directory.
+
+The optional simulator command is hosted here, while execution remains in the
+separate simulator library:
+
+```sh
+unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
+```
+
+For trusted programs that require functions outside the lifted module, pass a
+Python environment file. Top-level functions are matched by name, while their
+stdout and stderr are returned as structured simulation events:
+
+```sh
+unidecompiler simulate sample.pyc --function main --environment runtime.py
+```

{unidecompiler_cli-0.1.2 → unidecompiler_cli-0.2.0}/src/unidecompiler_cli.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/unidecompiler_cli/__init__.py
 src/unidecompiler_cli/cli.py
 src/unidecompiler_cli/input_sources.py
 src/unidecompiler_cli/simulation.py
+src/unidecompiler_cli/templates.py
 src/unidecompiler_cli.egg-info/PKG-INFO
 src/unidecompiler_cli.egg-info/SOURCES.txt
 src/unidecompiler_cli.egg-info/dependency_links.txt

unidecompiler_cli-0.2.0/src/unidecompiler_cli.egg-info/requires.txt

@@ -0,0 +1,4 @@
+unidecompiler<0.3.0,>=0.2.0
+unidecompiler-export<0.3.0,>=0.2.0
+unidecompiler-simulator<0.3.0,>=0.2.0
+unidecompiler-simulation-host-python<0.3.0,>=0.2.0

unidecompiler_cli-0.1.2/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: unidecompiler-cli
-Version: 0.1.2
-Summary: Command-line host for unidecompiler plugins
-Author-email: Wker <1670133844@qq.com>
-License-Expression: AGPL-3.0-or-later
-Project-URL: Homepage, https://github.com/Wker666/unidecompiler
-Project-URL: Repository, https://github.com/Wker666/unidecompiler
-Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: unidecompiler<0.2.0,>=0.1.10
-Requires-Dist: unidecompiler-simulator<0.2.0,>=0.1.5
-Requires-Dist: unidecompiler-simulation-host-python<0.2.0,>=0.1.2
-
-# unidecompiler-cli
-
-`unidecompiler-cli` is the command-line host for installed `unidecompiler`
-frontend plugins. It discovers plugins through the `unidecompiler.frontends`
-entry-point group and uses the public `DecompilerEngine` facade.
-
-Install the CLI and one or more frontend packages:
-
-```sh
-python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
-```
-
-Run `unidecompiler --help` for command-line usage.
-
-The optional simulator command is hosted here, while execution remains in the
-separate simulator library:
-
-```sh
-unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
-```
-
-For trusted programs that require functions outside the lifted module, pass a
-Python environment file. Top-level functions are matched by name, while their
-stdout and stderr are returned as structured simulation events:
-
-```sh
-unidecompiler simulate sample.pyc --function main --environment runtime.py
-```

unidecompiler_cli-0.1.2/README.md

@@ -1,28 +0,0 @@
-# unidecompiler-cli
-
-`unidecompiler-cli` is the command-line host for installed `unidecompiler`
-frontend plugins. It discovers plugins through the `unidecompiler.frontends`
-entry-point group and uses the public `DecompilerEngine` facade.
-
-Install the CLI and one or more frontend packages:
-
-```sh
-python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
-```
-
-Run `unidecompiler --help` for command-line usage.
-
-The optional simulator command is hosted here, while execution remains in the
-separate simulator library:
-
-```sh
-unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
-```
-
-For trusted programs that require functions outside the lifted module, pass a
-Python environment file. Top-level functions are matched by name, while their
-stdout and stderr are returned as structured simulation events:
-
-```sh
-unidecompiler simulate sample.pyc --function main --environment runtime.py
-```

unidecompiler_cli-0.1.2/src/unidecompiler_cli/cli.py

@@ -1,144 +0,0 @@
-from __future__ import annotations
-
-import argparse
-import base64
-from dataclasses import fields, is_dataclass
-import json
-import math
-import sys
-from typing import Any
-from pathlib import Path
-
-from unidecompiler.backends.pseudocode import GenericPseudocodeBackend
-from unidecompiler.core.astify import module_to_ast
-from unidecompiler.plugin_registry import FrontendRegistry, FrontendSelectionError
-from unidecompiler.plugins import FrontendDecodeError
-from unidecompiler.input_sources import expand_input_path
-
-
-def main(argv: list[str] | None = None, *, registry: FrontendRegistry | None = None) -> int:
-    command_argv = sys.argv[1:] if argv is None else argv
-    if command_argv[:1] == ["simulate"]:
-        from unidecompiler_cli.simulation import main as simulate_main
-
-        return simulate_main(command_argv[1:], registry=registry)
-    parser = argparse.ArgumentParser(
-        prog="unidecompiler",
-        description="Decompile bytecode into generic pseudocode.",
-    )
-    parser.add_argument("input", nargs="?", help="input bytecode file")
-    parser.add_argument(
-        "--frontend",
-        help="explicit frontend plugin id, e.g. lua",
-        default=None,
-    )
-    parser.add_argument(
-        "--versions",
-        action="store_true",
-        help="print supported frontend version matrix",
-    )
-    parser.add_argument(
-        "--format",
-        choices=("pseudocode", "ast-json"),
-        default="pseudocode",
-        help="output format (default: pseudocode)",
-    )
-    args = parser.parse_args(command_argv)
-
-    registry = registry or FrontendRegistry.discover()
-    if args.versions:
-        for plugin, support in registry.version_support():
-            versions = ", ".join(support.versions)
-            print(
-                f"{plugin.id}: {support.family} | {versions} | "
-                f"{support.status} | parser: {support.parser}"
-            )
-        return 0
-
-    if args.input is None:
-        parser.error("input is required unless --versions is used")
-    input_path = Path(args.input)
-    artifacts = expand_input_path(input_path)
-    if not artifacts:
-        raise SystemExit(f"no input files found in {input_path}")
-
-    backend = GenericPseudocodeBackend() if args.format == "pseudocode" else None
-    ast_modules: list[dict[str, Any]] = []
-    processed = 0
-    for artifact in artifacts:
-        try:
-            frontend = registry.select(
-                artifact.data, artifact.display_path, explicit_id=args.frontend
-            )
-        except FrontendSelectionError:
-            print(f"resource: {artifact.display_path}", file=sys.stderr)
-            continue
-        try:
-            decoded = frontend.decode(artifact.data, artifact.display_path)
-        except FrontendDecodeError:
-            print(f"resource: {artifact.display_path}", file=sys.stderr)
-            continue
-        try:
-            module = frontend.lift(decoded)
-            if args.format == "ast-json":
-                ast_modules.append(_json_value(module_to_ast(module)))
-            else:
-                assert backend is not None
-                emitted = backend.emit(module)
-                print(emitted.text)
-        except Exception as error:
-            print(
-                f"error: {artifact.display_path}: {type(error).__name__}: {error}",
-                file=sys.stderr,
-            )
-            continue
-        processed += 1
-
-    if processed == 0:
-        raise SystemExit(f"no supported input files found in {input_path}")
-    if args.format == "ast-json":
-        print(
-            json.dumps(
-                {"schema_version": 1, "modules": ast_modules},
-                ensure_ascii=False,
-                sort_keys=True,
-                allow_nan=False,
-            )
-        )
-    return 0
-
-
-def _json_value(value: Any) -> Any:
-    """Convert the generic AST dataclasses into a JSON-compatible tree."""
-    if is_dataclass(value):
-        return {
-            "node_type": type(value).__name__,
-            **{field.name: _json_value(getattr(value, field.name)) for field in fields(value)},
-        }
-    if isinstance(value, bytes | bytearray | memoryview):
-        return {
-            "value_type": "bytes",
-            "base64": base64.b64encode(bytes(value)).decode("ascii"),
-        }
-    if isinstance(value, complex):
-        return {"value_type": "complex", "real": value.real, "imag": value.imag}
-    if isinstance(value, float) and not math.isfinite(value):
-        return {"value_type": "float", "value": repr(value)}
-    if isinstance(value, tuple | list):
-        return [_json_value(item) for item in value]
-    if isinstance(value, dict):
-        if all(isinstance(key, str) for key in value):
-            return {key: _json_value(item) for key, item in value.items()}
-        return {
-            "value_type": "map",
-            "entries": [[_json_value(key), _json_value(item)] for key, item in value.items()],
-        }
-    if isinstance(value, set | frozenset):
-        return {"value_type": "set", "items": [_json_value(item) for item in sorted(value, key=repr)]}
-    if value is None or isinstance(value, str | int | float | bool):
-        return value
-    raise TypeError(f"AST JSON cannot encode {type(value).__name__}")
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

unidecompiler_cli-0.1.2/src/unidecompiler_cli.egg-info/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: unidecompiler-cli
-Version: 0.1.2
-Summary: Command-line host for unidecompiler plugins
-Author-email: Wker <1670133844@qq.com>
-License-Expression: AGPL-3.0-or-later
-Project-URL: Homepage, https://github.com/Wker666/unidecompiler
-Project-URL: Repository, https://github.com/Wker666/unidecompiler
-Project-URL: Issues, https://github.com/Wker666/unidecompiler/issues
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-Requires-Dist: unidecompiler<0.2.0,>=0.1.10
-Requires-Dist: unidecompiler-simulator<0.2.0,>=0.1.5
-Requires-Dist: unidecompiler-simulation-host-python<0.2.0,>=0.1.2
-
-# unidecompiler-cli
-
-`unidecompiler-cli` is the command-line host for installed `unidecompiler`
-frontend plugins. It discovers plugins through the `unidecompiler.frontends`
-entry-point group and uses the public `DecompilerEngine` facade.
-
-Install the CLI and one or more frontend packages:
-
-```sh
-python -m pip install unidecompiler-cli unidecompiler-plugin-python-pyc
-```
-
-Run `unidecompiler --help` for command-line usage.
-
-The optional simulator command is hosted here, while execution remains in the
-separate simulator library:
-
-```sh
-unidecompiler simulate sample.bytecode --function 'Example.run' --args '[1, 2]'
-```
-
-For trusted programs that require functions outside the lifted module, pass a
-Python environment file. Top-level functions are matched by name, while their
-stdout and stderr are returned as structured simulation events:
-
-```sh
-unidecompiler simulate sample.pyc --function main --environment runtime.py
-```

unidecompiler_cli-0.1.2/src/unidecompiler_cli.egg-info/requires.txt

@@ -1,3 +0,0 @@
-unidecompiler<0.2.0,>=0.1.10
-unidecompiler-simulator<0.2.0,>=0.1.5
-unidecompiler-simulation-host-python<0.2.0,>=0.1.2