FluxScript 0.1.0__py3-none-any.whl

fluxscript/cli.py

@@ -0,0 +1,303 @@
+"""FluxScript command line interface."""
+from __future__ import annotations
+import argparse
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from . import __version__
+from .backends import BACKENDS
+from .dependencies import ensure_target_dependencies
+from .analyzer import analyze_path, write_report
+from .integrations import status as integration_status
+from .integrations.execution_service import ExecutionServiceClient, ExecutionServiceError
+from .parser import parse_file, SourceError
+from .project import default_storage, generate_project
+
+EXAMPLE = '''"""Describe an application using FluxScript's safe declarative Python API."""
+from fluxscript import App, Page, Heading, Text, Button, Input
+
+app = App("Research Manager")
+home = Page("/", title="Research Manager")
+home.add(Heading("Welcome to Research Manager"))
+home.add(Text("Describe your interface once and generate a project for a target platform."))
+home.add(Input("Project name", name="project_name"))
+home.add(Button("Save project", action="save_project"))
+app.add_page(home)
+'''
+
+GUIDE = r'''FluxScript 0.1.0 — COMMAND GUIDE
+================================
+
+GET STARTED
+  python -m pip install .             (run from the extracted source directory)
+  # After PyPI publication: python -m pip install --upgrade FluxScript
+  fluxscript --version
+  fluxscript new my_app
+  cd my_app
+  fluxscript check app.py
+
+BUILDERS (builder commands install the latest required Python validation helper)
+  fluxscript website app.py               (clean alias; website-builder also works)
+  fluxscript website-builder app.py --out build/site
+  fluxscript android app.py               (clean alias; android-builder also works)
+  fluxscript ios app.py                   (clean alias; ios-builder also works)
+  fluxscript cli app.py                   (clean alias; cli-builder also works)
+  fluxscript build app.py --target all --out build/all
+  Add --no-install-deps to prevent automatic pip installation.
+
+GENERATE PROJECT (creates a directory AND ZIP in storage)
+  fluxscript generateproject --source app.py --target web  (generate-project also works)
+  fluxscript generate-project --source app.py --target android --storage ~/FluxScriptProjects
+  fluxscript generate-project --source app.py --target all
+  Default storage: /storage/emulated/0/FluxScriptProjects when writable, otherwise
+  ~/FluxScriptProjects. Both the generated directory and a ZIP archive are saved there.
+
+PROJECT UTILITIES
+  fluxscript new [directory]      Create a starter source project
+  fluxscript check [source.py]    Validate source without executing it
+  fluxscript targets              List supported source generators
+  fluxscript doctor               Detect local native/toolchain executables
+  fluxscript device               Detect current runtime device/OS type
+  fluxscript developer            Show project developer name
+  fluxscript integrations         Show built-in capabilities and optional toolchains
+  fluxscript analyze ./source     Inspect source files without executing them
+  fluxscript analyze ./source --out report.json
+  fluxscript review ./source      Alias for the read-only analyzer
+  fluxscript guide                Print this full command guide
+
+REMOTE EXECUTION SERVICE
+  fluxscript service status
+  export FLUXSCRIPT_SERVICE_URL='http://127.0.0.1:2000/api/v2'
+  export FLUXSCRIPT_SERVICE_TOKEN='your-token-if-required'
+  fluxscript service runtimes
+  fluxscript service run python 3.12 main.py
+  fluxscript service run javascript 20.11.1 app.js --stdin-file input.txt
+  Remote non-local endpoints must use HTTPS. The service must be separately deployed;
+  FluxScript never silently executes submitted code on your own machine.
+
+NOTES
+  The source format is a restricted declarative Python subset, not arbitrary Python.
+  Android compilation needs a JDK, Android SDK and compatible Gradle environment.
+  iOS compilation/signing needs macOS and Xcode. pip cannot install those toolchains.
+  Generated buttons emit action requests; connect real business logic and APIs yourself.
+'''
+
+def _new(path: Path) -> int:
+    path = path.expanduser()
+    if path.exists() and not path.is_dir():
+        print(f"error: not a directory: {path}", file=sys.stderr); return 2
+    path.mkdir(parents=True, exist_ok=True)
+    source = path / "app.py"
+    if source.exists(): print(f"error: refusing to overwrite existing file: {source}", file=sys.stderr); return 2
+    source.write_text(EXAMPLE, encoding="utf-8")
+    (path / "fluxscript.toml").write_text('[project]\nname = "Research Manager"\nsource = "app.py"\nversion = "0.1.0"\n\n[targets]\ndefault = ["web"]\n', encoding="utf-8")
+    print(f"Created project at {path}\nNext: cd {path} && fluxscript check app.py && fluxscript website-builder app.py")
+    return 0
+
+def _validate_generated(target: str, output: Path) -> None:
+    if target == "web":
+        from bs4 import BeautifulSoup
+        html = (output / "index.html").read_text(encoding="utf-8")
+        soup = BeautifulSoup(html, "html.parser")
+        if soup.title is None or soup.main is None or not soup.find_all("section", attrs={"data-route": True}):
+            raise RuntimeError("Generated web output failed structural HTML validation.")
+        if not (output / "styles.css").is_file() or not (output / "app.js").is_file():
+            raise RuntimeError("Generated web output is missing CSS or JavaScript.")
+    elif target == "android":
+        from defusedxml import ElementTree
+        manifest = output / "app/src/main/AndroidManifest.xml"
+        ElementTree.parse(str(manifest))
+        if not (output / "app/src/main/java/dev/fluxscript/generated/MainActivity.kt").is_file():
+            raise RuntimeError("Generated Android output is missing its Kotlin entry point.")
+    elif target == "ios":
+        source = output / "GeneratedApp.swift"
+        if not source.is_file() or "@main" not in source.read_text(encoding="utf-8"):
+            raise RuntimeError("Generated iOS output is missing its SwiftUI entry point.")
+    elif target == "cli":
+        import ast
+        source = output / "app_cli.py"
+        ast.parse(source.read_text(encoding="utf-8"), filename=str(source))
+
+def _builder(source: Path, target: str, out: Path, *, no_install_deps: bool = False) -> int:
+    try:
+        dependencies = ensure_target_dependencies(target, no_install=no_install_deps)
+        spec = parse_file(source)
+        files = BACKENDS[target](spec, out.expanduser())
+        _validate_generated(target, out.expanduser())
+        print(f"FluxScript {target} builder: validated {len(files)} generated files in {out}")
+        print("Python validation helpers: " + (", ".join(dependencies) if dependencies else "none required"))
+        if target == "android": print("Native build requirement: JDK + Android SDK + compatible Gradle/Android Gradle Plugin.")
+        if target == "ios": print("Native build requirement: macOS + Xcode; this command generates source, not an IPA.")
+        return 0
+    except (SourceError, OSError, ValueError, RuntimeError, ImportError) as exc:
+        print(f"builder error: {exc}", file=sys.stderr); return 2
+
+def _build(source: Path, target: str, out: Path, no_install_deps: bool = False) -> int:
+    if target == "all":
+        code = 0
+        for name in BACKENDS:
+            result = _builder(source, name, out / name, no_install_deps=no_install_deps)
+            if result: code = result
+        return code
+    return _builder(source, target, out, no_install_deps=no_install_deps)
+
+def _service(args: argparse.Namespace) -> int:
+    try:
+        client = ExecutionServiceClient(base_url=args.url, token=args.token, timeout=args.timeout)
+        if args.service_command == "status":
+            endpoint = args.url or os.environ.get("FLUXSCRIPT_SERVICE_URL")
+            print(json.dumps({"service": "FluxScript remote execution API", "base_url": client.base_url,
+                "endpoint_configured": bool(endpoint), "using_default_endpoint": not bool(endpoint),
+                "token_configured": bool(client.token), "network_checked": False}, indent=2))
+            return 0
+        if args.service_command == "runtimes":
+            print(json.dumps(client.runtimes(), indent=2, ensure_ascii=False)); return 0
+        if args.service_command == "run":
+            code = Path(args.file).read_text(encoding="utf-8")
+            stdin = Path(args.stdin_file).read_text(encoding="utf-8") if args.stdin_file else (args.stdin or "")
+            result = client.execute(args.language, args.runtime_version, code, stdin=stdin, args=args.arg or [], run_timeout_ms=args.run_timeout)
+            print(json.dumps(result, indent=2, ensure_ascii=False))
+            run = result.get("run", {})
+            return 0 if run.get("code", 0) == 0 and not run.get("signal") else 1
+    except (ExecutionServiceError, OSError, ValueError) as exc:
+        print(f"service error: {exc}", file=sys.stderr); return 2
+    return 2
+
+def _device_info() -> dict[str, object]:
+    """Return best-effort host/device details without installing extra packages."""
+    system = platform.system() or os.name
+    release = platform.release()
+    machine = platform.machine()
+    env = os.environ
+    if env.get("ANDROID_ARGUMENT") or env.get("ANDROID_ROOT") or "ANDROID_DATA" in env:
+        device_type = "android"
+    elif sys.platform == "ios":
+        device_type = "ios"
+    elif system == "Windows":
+        device_type = "windows_pc"
+    elif system == "Darwin":
+        device_type = "mac"
+    elif system == "Linux":
+        device_type = "linux_device"
+    else:
+        device_type = "unknown"
+    return {
+        "device_name": platform.node() or "unknown",
+        "device_type": device_type,
+        "system": system,
+        "system_release": release,
+        "machine_architecture": machine,
+        "python_version": platform.python_version(),
+        "python_executable": sys.executable,
+        "termux": bool(env.get("TERMUX_VERSION")),
+        "note": "Best-effort runtime detection; some phones/tablets report the terminal or host name rather than the hardware model.",
+    }
+
+def _doctor() -> int:
+    checks = {"device": _device_info(), "python_version": sys.version.split()[0], "python_supported": sys.version_info >= (3, 10),
+        "node": shutil.which("node"), "npm": shutil.which("npm"), "java": shutil.which("java"),
+        "gradle": shutil.which("gradle"), "xcodebuild": shutil.which("xcodebuild"),
+        "android_home": os.environ.get("ANDROID_HOME") or os.environ.get("ANDROID_SDK_ROOT")}
+    print(json.dumps(checks, indent=2)); return 0 if checks["python_supported"] else 1
+
+def main(argv: list[str] | None = None) -> int:
+    raw_args = list(sys.argv[1:] if argv is None else argv)
+    # Friendly command names omit punctuation. Legacy hyphenated forms remain accepted.
+    aliases = {
+        "new": "new", "check": "check", "build": "build", "guide": "guide",
+        "targets": "targets", "doctor": "doctor", "device": "device", "detectdevice": "device",
+        "developer": "developer", "author": "developer", "integrations": "integrations",
+        "analyze": "analyze", "review": "review", "service": "service",
+        "website": "website-builder", "web": "website-builder", "websitebuilder": "website-builder",
+        "webbuilder": "website-builder", "android": "android-builder", "androidbuilder": "android-builder",
+        "ios": "ios-builder", "iosbuilder": "ios-builder", "cli": "cli-builder", "clibuilder": "cli-builder",
+        "generate": "generate-project", "generateproject": "generate-project",
+    }
+    if raw_args:
+        first = raw_args[0].lower()
+        normalized = first.replace("-", "").replace("_", "")
+        # Also accept familiar two-word command forms such as "website builder".
+        if len(raw_args) >= 2 and (first + " " + raw_args[1].lower()) in {
+            "website builder", "web builder", "android builder", "ios builder", "cli builder", "generate project"
+        }:
+            phrase = first + " " + raw_args[1].lower()
+            target = {"website builder": "website-builder", "web builder": "website-builder",
+                      "android builder": "android-builder", "ios builder": "ios-builder",
+                      "cli builder": "cli-builder", "generate project": "generate-project"}[phrase]
+            raw_args[:2] = [target]
+        elif normalized in aliases:
+            raw_args[0] = aliases[normalized]
+    parser = argparse.ArgumentParser(prog="fluxscript", description="FluxScript — a Python-first multi-target project generator")
+    parser.add_argument("--version", action="version", version=f"FluxScript {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    newp = sub.add_parser("new", help="create a starter project"); newp.add_argument("path", nargs="?", default=".")
+    check = sub.add_parser("check", help="validate declarative source without executing it"); check.add_argument("source", nargs="?", default="app.py")
+    build = sub.add_parser("build", help="build one or all generated source targets"); build.add_argument("source", nargs="?", default="app.py"); build.add_argument("--target", choices=["web", "android", "ios", "cli", "all"], default="web"); build.add_argument("--out", default="build"); build.add_argument("--no-install-deps", "--noinstalldeps", dest="no_install_deps", action="store_true")
+    for command, target, description in [
+        ("website-builder", "web", "generate and validate a website project"),
+        ("android-builder", "android", "generate and validate an Android project"),
+        ("ios-builder", "ios", "generate and validate an iOS source project"),
+        ("cli-builder", "cli", "generate a standalone command-line application"),
+    ]:
+        bp = sub.add_parser(command, help=description); bp.add_argument("source", nargs="?", default="app.py"); bp.add_argument("--out", default=f"build/{target}"); bp.add_argument("--no-install-deps", "--noinstalldeps", dest="no_install_deps", action="store_true"); bp.set_defaults(builder_target=target)
+    analyze = sub.add_parser("analyze", help="read-only source/project analysis; never executes analyzed files"); analyze.add_argument("path", nargs="?", default="."); analyze.add_argument("--out", default=None, help="write JSON report to this path")
+    review = sub.add_parser("review", help="alias for the read-only source/project analyzer"); review.add_argument("path", nargs="?", default="."); review.add_argument("--out", default=None, help="write JSON report to this path")
+    gp = sub.add_parser("generate-project", help="generate project files and export a ZIP into storage")
+    gp.add_argument("--source", default="app.py"); gp.add_argument("--target", choices=["web", "android", "ios", "cli", "all"], default="web"); gp.add_argument("--storage", default=None, help="output storage directory (default: shared Android storage or ~/FluxScriptProjects)"); gp.add_argument("--no-install-deps", "--noinstalldeps", dest="no_install_deps", action="store_true")
+    sub.add_parser("guide", help="print all FluxScript commands and usage examples")
+    sub.add_parser("device", help="detect the current runtime device/operating-system type")
+    sub.add_parser("developer", help="show FluxScript developer/author information")
+    sub.add_parser("integrations", help="show built-in capabilities and detected toolchains")
+    sub.add_parser("targets", help="list available generation targets")
+    sub.add_parser("doctor", help="check local development toolchains")
+    service = sub.add_parser("service", help="call a configured remote execution service")
+    svc = service.add_subparsers(dest="service_command", required=True)
+    for name, help_text in [("status", "show local service configuration"), ("runtimes", "fetch available remote runtimes")]:
+        sp = svc.add_parser(name, help=help_text); sp.add_argument("--url", default=None); sp.add_argument("--token", default=None); sp.add_argument("--timeout", type=float, default=10.0)
+    run = svc.add_parser("run", help="submit source to the remote execution service"); run.add_argument("language"); run.add_argument("runtime_version"); run.add_argument("file"); run.add_argument("--stdin", default=None); run.add_argument("--stdin-file"); run.add_argument("--arg", action="append", default=[]); run.add_argument("--run-timeout", type=int, default=3000); run.add_argument("--url", default=None); run.add_argument("--token", default=None); run.add_argument("--timeout", type=float, default=10.0)
+    args = parser.parse_args(raw_args)
+    if args.command == "new": return _new(Path(args.path))
+    if args.command == "guide": print(GUIDE); return 0
+    if args.command == "device": print(json.dumps(_device_info(), indent=2)); return 0
+    if args.command == "developer": print(json.dumps({"name": "Md Safarujjaman", "project": "FluxScript", "version": __version__}, indent=2)); return 0
+    if args.command == "integrations": print(json.dumps(integration_status(), indent=2)); return 0
+    if args.command == "targets":
+        print(json.dumps({"web": {"description": "HTML/CSS/JavaScript/TypeScript", "validation": "HTML structure", "native_toolchain": "browser; Node.js optional"}, "android": {"description": "Kotlin/Gradle project", "validation": "XML manifest structure", "native_toolchain": "JDK + Android SDK + Gradle"}, "ios": {"description": "SwiftUI source project", "validation": "SwiftUI entry-point checks", "native_toolchain": "macOS + Xcode"}, "cli": {"description": "Python argparse command-line project", "validation": "Python syntax parsing", "native_toolchain": "Python 3.10+"}}, indent=2)); return 0
+    if args.command == "doctor": return _doctor()
+    if args.command == "service": return _service(args)
+    if args.command == "check":
+        try:
+            spec = parse_file(args.source); print(f"OK: {spec.name} ({len(spec.pages)} page(s)); source parsed without executing it."); return 0
+        except (SourceError, OSError) as exc: print(f"error: {exc}", file=sys.stderr); return 2
+    if args.command in {"analyze", "review"}:
+        try:
+            report = analyze_path(args.path)
+            if args.out:
+                destination = write_report(report, args.out)
+                print(f"Analysis report written to {destination}")
+                print(json.dumps(report["summary"], indent=2))
+            else:
+                print(json.dumps(report, indent=2, ensure_ascii=False))
+            return 1 if report["summary"]["errors"] else 0
+        except (OSError, ValueError) as exc:
+            print(f"analysis error: {exc}", file=sys.stderr); return 2
+    if args.command == "build": return _build(Path(args.source), args.target, Path(args.out), args.no_install_deps)
+    if args.command in {"website-builder", "android-builder", "ios-builder", "cli-builder"}:
+        return _builder(Path(args.source), args.builder_target, Path(args.out), no_install_deps=args.no_install_deps)
+    if args.command == "generate-project":
+        try:
+            storage = Path(args.storage).expanduser() if args.storage else default_storage()
+            for target in (["web", "android", "ios", "cli"] if args.target == "all" else [args.target]):
+                ensure_target_dependencies(target, no_install=args.no_install_deps)
+            directory, archive, files = generate_project(Path(args.source), args.target, storage)
+            print(f"Project directory: {directory}\nProject ZIP: {archive}\nGenerated files: {len(files)}")
+            return 0
+        except (SourceError, OSError, ValueError, RuntimeError, ImportError) as exc:
+            print(f"project generation error: {exc}", file=sys.stderr); return 2
+    return 2
+
+if __name__ == "__main__": raise SystemExit(main())

fluxscript/dependencies.py

@@ -0,0 +1,96 @@
+"""Safe, on-demand management of FluxScript's build-time helper packages.
+
+FluxScript's parser accepts a restricted declarative format and does not execute
+arbitrary application imports, so it intentionally does not guess or install
+third-party runtime dependencies for user applications. This module manages only
+packages used by FluxScript itself to validate generated output.
+"""
+from __future__ import annotations
+
+import importlib.util
+import subprocess
+import sys
+from dataclasses import dataclass
+from typing import Iterable
+
+
+@dataclass(frozen=True)
+class Dependency:
+    distribution: str
+    module: str
+    purpose: str
+
+
+# Only third-party packages genuinely used by the generated-output validators.
+# iOS and CLI validators use the Python standard library and need no pip package.
+TARGET_DEPENDENCIES: dict[str, tuple[Dependency, ...]] = {
+    "web": (Dependency("beautifulsoup4", "bs4", "validate generated HTML structure"),),
+    "android": (Dependency("defusedxml", "defusedxml", "safely parse generated Android XML"),),
+    "ios": (),
+    "cli": (),
+}
+
+
+def _is_importable(module: str) -> bool:
+    try:
+        return importlib.util.find_spec(module) is not None
+    except (ImportError, ValueError, AttributeError):
+        return False
+
+
+def ensure_target_dependencies(
+    target: str,
+    *,
+    no_install: bool = False,
+    upgrade: bool = True,
+    extra_dependencies: Iterable[Dependency] = (),
+) -> list[str]:
+    """Ensure the selected target's validator packages are available.
+
+    By default, missing packages are installed and already-present packages are
+    upgraded when a target builder is invoked. Set ``no_install`` to require all
+    packages to be preinstalled. ``upgrade=False`` installs missing packages but
+    leaves existing installations unchanged. All pip invocations use the active
+    interpreter, disable pip's version-check notice, and fail with an actionable
+    error rather than silently continuing.
+    """
+    if target not in TARGET_DEPENDENCIES:
+        raise ValueError(f"Unknown target: {target}")
+
+    dependencies = (*TARGET_DEPENDENCIES[target], *tuple(extra_dependencies))
+    ensured: list[str] = []
+    for dep in dependencies:
+        installed = _is_importable(dep.module)
+        if no_install:
+            if not installed:
+                raise RuntimeError(
+                    f"Missing dependency {dep.distribution!r} ({dep.purpose}). "
+                    "Install it with 'python -m pip install " + dep.distribution +
+                    "' or rerun without --no-install-deps."
+                )
+            ensured.append(dep.distribution)
+            continue
+
+        if installed and not upgrade:
+            ensured.append(dep.distribution)
+            continue
+
+        action = "upgrade" if installed else "install"
+        print(f"FluxScript: {action} {dep.distribution} ({dep.purpose})...", flush=True)
+        command = [sys.executable, "-m", "pip", "install", "--disable-pip-version-check"]
+        if upgrade and installed:
+            command.append("--upgrade")
+        command.append(dep.distribution)
+        try:
+            subprocess.run(command, check=True)
+        except (OSError, subprocess.CalledProcessError) as exc:
+            raise RuntimeError(
+                f"Could not {action} {dep.distribution}. Check internet access and pip permissions. "
+                f"If it is already installed, rerun with --no-install-deps to skip pip."
+            ) from exc
+        if not _is_importable(dep.module):
+            raise RuntimeError(
+                f"pip reported success, but module {dep.module!r} is still not importable."
+            )
+        ensured.append(dep.distribution)
+    return ensured

fluxscript/dsl.py

@@ -0,0 +1,25 @@
+"""Declarative Python API. The compiler parses source; it never imports this file."""
+from .models import AppSpec, PageSpec, ElementSpec
+
+class App:
+    def __init__(self, name: str): self.spec = AppSpec(str(name))
+    def add_page(self, page: "Page") -> "App": self.spec.pages.append(page.spec); return self
+class Page:
+    def __init__(self, path: str = "/", title: str = ""):
+        self.spec = PageSpec(str(path), str(title))
+    def add(self, element: "Element") -> "Page": self.spec.elements.append(element.spec); return self
+class Element:
+    def __init__(self, spec: ElementSpec): self.spec = spec
+class Text(Element):
+    def __init__(self, text: str): super().__init__(ElementSpec("text", str(text)))
+class Heading(Element):
+    def __init__(self, text: str, level: int = 1):
+        level = int(level)
+        if level not in (1,2,3,4,5,6): raise ValueError("Heading level must be 1–6")
+        super().__init__(ElementSpec("heading", str(text), attributes={"level": level}))
+class Button(Element):
+    def __init__(self, text: str, action: str): super().__init__(ElementSpec("button", str(text), action=str(action)))
+class Input(Element):
+    def __init__(self, label: str, name: str, input_type: str = "text"):
+        if input_type not in {"text", "email", "number", "password", "date"}: raise ValueError("Unsupported input_type")
+        super().__init__(ElementSpec("input", str(label), name=str(name), attributes={"input_type": input_type}))

fluxscript/integrations/__init__.py

@@ -0,0 +1,23 @@
+"""FluxScript's built-in capability registry."""
+from importlib.util import find_spec
+from shutil import which
+
+_CAPABILITIES = (
+    {"name": "web-builder", "purpose": "Generate HTML, CSS, JavaScript and TypeScript", "kind": "built-in", "module": None, "command": None},
+    {"name": "android-builder", "purpose": "Generate Kotlin and Gradle project source", "kind": "built-in", "module": None, "command": None},
+    {"name": "ios-builder", "purpose": "Generate SwiftUI project source", "kind": "built-in", "module": None, "command": None},
+    {"name": "cli-builder", "purpose": "Generate a standalone argparse-based CLI", "kind": "built-in", "module": None, "command": None},
+    {"name": "source-analyzer", "purpose": "Read-only source inventory and static review", "kind": "built-in", "module": None, "command": None},
+    {"name": "remote-execution", "purpose": "Call a configured remote source execution API", "kind": "optional-service", "module": None, "command": None},
+    {"name": "node-toolchain", "purpose": "Optional JavaScript and TypeScript validation", "kind": "local-toolchain", "module": None, "command": "node"},
+    {"name": "android-toolchain", "purpose": "Optional Android native compilation", "kind": "local-toolchain", "module": None, "command": "gradle"},
+    {"name": "ios-toolchain", "purpose": "Optional Apple-platform compilation (macOS only)", "kind": "local-toolchain", "module": None, "command": "xcodebuild"},
+)
+
+def status() -> list[dict[str, str | bool]]:
+    result = []
+    for item in _CAPABILITIES:
+        row = dict(item)
+        row["available"] = True if item["kind"] == "built-in" else bool(item["command"] and which(item["command"]))
+        result.append(row)
+    return result

fluxscript/integrations/commands.py

@@ -0,0 +1,29 @@
+"""Explicit, bounded external CLI invocation helpers. Never uses a shell."""
+from __future__ import annotations
+import shutil
+import subprocess
+from pathlib import Path
+
+class ExternalToolError(RuntimeError): pass
+
+def run_tool(executable: str, args: list[str], *, cwd: str | Path | None = None,
+             timeout: float = 30.0, output_limit: int = 1_000_000) -> dict:
+    """Run an explicitly named installed tool; callers must obtain user approval first.
+
+    The function does not interpret shell syntax. It does not download or install tools.
+    Use only with trusted executable names/paths and reviewed arguments.
+    """
+    resolved = shutil.which(executable)
+    if not resolved: raise ExternalToolError(f"Required external executable is not installed: {executable}")
+    if not isinstance(args, list) or any(not isinstance(x, str) for x in args):
+        raise TypeError("args must be a list of strings")
+    try:
+        completed = subprocess.run([resolved, *args], cwd=str(cwd) if cwd else None,
+                                   capture_output=True, text=True, timeout=max(1.0, min(timeout, 300.0)),
+                                   shell=False, check=False)
+    except subprocess.TimeoutExpired as exc:
+        raise ExternalToolError(f"External tool timed out after {exc.timeout} seconds") from exc
+    stdout, stderr = completed.stdout or "", completed.stderr or ""
+    if len(stdout) > output_limit: stdout = stdout[:output_limit] + "\n[output truncated]"
+    if len(stderr) > output_limit: stderr = stderr[:output_limit] + "\n[output truncated]"
+    return {"command": resolved, "returncode": completed.returncode, "stdout": stdout, "stderr": stderr}

fluxscript/integrations/execution_service.py

@@ -0,0 +1,50 @@
+"""Explicit, bounded client for an operator-configured FluxScript-compatible execution API."""
+from __future__ import annotations
+import ipaddress, json, os
+from urllib.parse import urlsplit
+from urllib.request import Request, urlopen
+from urllib.error import HTTPError, URLError
+
+class ExecutionServiceError(RuntimeError): pass
+class ExecutionServiceClient:
+    def __init__(self, base_url: str | None = None, token: str | None = None, timeout: float = 10.0):
+        self.base_url = (base_url or os.environ.get("FLUXSCRIPT_SERVICE_URL", "http://127.0.0.1:2000/api/v2")).rstrip("/")
+        self.token = token if token is not None else os.environ.get("FLUXSCRIPT_SERVICE_TOKEN")
+        self.timeout = max(1.0, min(float(timeout), 60.0))
+        parts = urlsplit(self.base_url)
+        if parts.scheme not in {"http", "https"} or not parts.hostname or parts.username or parts.password or parts.query or parts.fragment:
+            raise ValueError("Execution service URL must be an HTTP(S) base URL without credentials, query, or fragment")
+        if parts.scheme == "http":
+            host = parts.hostname.lower().rstrip(".")
+            local = host == "localhost"
+            try: local = local or ipaddress.ip_address(host).is_loopback
+            except ValueError: pass
+            if not local: raise ValueError("Non-local execution-service endpoints must use HTTPS")
+    def _request(self, path: str, payload: dict | None = None):
+        data = None if payload is None else json.dumps(payload).encode("utf-8")
+        headers = {"Accept": "application/json", "User-Agent": "FluxScript/0.1.0"}
+        if data is not None: headers["Content-Type"] = "application/json"
+        if self.token: headers["Authorization"] = f"Bearer {self.token}"
+        req = Request(f"{self.base_url}/{path.lstrip('/')}", data=data, headers=headers, method="POST" if data is not None else "GET")
+        try:
+            with urlopen(req, timeout=self.timeout) as response:
+                raw = response.read(2_000_001)
+                if len(raw) > 2_000_000: raise ExecutionServiceError("Execution service response exceeded 2 MB limit")
+                result = json.loads(raw.decode("utf-8"))
+        except HTTPError as exc: raise ExecutionServiceError(f"Execution service returned HTTP {exc.code}") from exc
+        except (URLError, TimeoutError, OSError) as exc: raise ExecutionServiceError(f"Could not reach configured execution service ({exc.__class__.__name__})") from exc
+        except (UnicodeDecodeError, json.JSONDecodeError) as exc: raise ExecutionServiceError("Execution service returned invalid JSON") from exc
+        return result
+    def runtimes(self) -> list[dict]:
+        result = self._request("runtimes")
+        if not isinstance(result, list) or any(not isinstance(x, dict) for x in result): raise ExecutionServiceError("Unexpected runtimes response schema")
+        return result
+    def execute(self, language: str, version: str, code: str, *, stdin: str = "", args: list[str] | None = None, compile_timeout_ms: int = 10_000, run_timeout_ms: int = 3_000) -> dict:
+        if not isinstance(language, str) or not language.strip() or not isinstance(version, str) or not version.strip(): raise ValueError("language and version are required")
+        if not isinstance(code, str) or len(code.encode("utf-8")) > 1_000_000: raise ValueError("Source must be text no larger than 1 MB")
+        if not isinstance(stdin, str) or len(stdin.encode("utf-8")) > 100_000: raise ValueError("stdin must be text no larger than 100 KB")
+        if args is not None and (not isinstance(args, list) or any(not isinstance(x, str) for x in args)): raise ValueError("args must be a list of strings")
+        payload = {"language": language, "version": version, "files": [{"name": "main", "content": code}], "stdin": stdin, "args": list(args or []), "compile_timeout": max(100, min(int(compile_timeout_ms), 30_000)), "run_timeout": max(100, min(int(run_timeout_ms), 10_000)), "compile_memory_limit": 128_000_000, "run_memory_limit": 128_000_000}
+        result = self._request("execute", payload)
+        if not isinstance(result, dict) or not isinstance(result.get("run"), dict): raise ExecutionServiceError("Unexpected execute response schema")
+        return result

fluxscript/models.py

@@ -0,0 +1,56 @@
+"""Stable, JSON-serializable semantic model shared by FluxScript backends."""
+from dataclasses import dataclass, field
+from typing import Any
+
+@dataclass
+class ElementSpec:
+    kind: str
+    text: str = ""
+    action: str | None = None
+    name: str | None = None
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+@dataclass
+class PageSpec:
+    path: str = "/"
+    title: str = ""
+    elements: list[ElementSpec] = field(default_factory=list)
+
+@dataclass
+class AppSpec:
+    name: str
+    pages: list[PageSpec] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def validate(self) -> list[str]:
+        issues: list[str] = []
+        if not isinstance(self.name, str) or not self.name.strip():
+            issues.append("Application name must be a non-empty string.")
+        if len(self.name) > 120:
+            issues.append("Application name must be at most 120 characters.")
+        if not self.pages:
+            issues.append("Application must define at least one page.")
+        paths: set[str] = set()
+        for page in self.pages:
+            if not page.path.startswith("/") or ".." in page.path.split("/") or "\\" in page.path:
+                issues.append(f"Page path must be an absolute, normalized URL path: {page.path!r}")
+            if page.path in paths:
+                issues.append(f"Duplicate page path: {page.path}")
+            paths.add(page.path)
+            if len(page.title) > 160:
+                issues.append(f"Page title for {page.path!r} must be at most 160 characters.")
+            for element in page.elements:
+                if element.kind not in {"text", "heading", "button", "input"}:
+                    issues.append(f"Unsupported element kind: {element.kind!r}")
+                if len(element.text) > 10_000:
+                    issues.append("Element text exceeds 10000 characters.")
+                if element.kind == "button":
+                    if not element.action or not element.action.strip(): issues.append(f"Button {element.text!r} has no action name.")
+                    elif not element.action.isidentifier(): issues.append(f"Button action must be a valid identifier: {element.action!r}")
+                if element.kind == "input":
+                    if not element.name or not element.name.isidentifier(): issues.append(f"Input field name must be a valid identifier: {element.name!r}")
+                    if element.attributes.get("input_type", "text") not in {"text", "email", "number", "password", "date"}:
+                        issues.append(f"Unsupported input type: {element.attributes.get('input_type')!r}")
+                if element.kind == "heading" and element.attributes.get("level", 1) not in (1,2,3,4,5,6):
+                    issues.append("Heading level must be between 1 and 6.")
+        return issues