Jarvis-Forge 1.0.0__py3-none-any.whl

jarvis_forge/__init__.py

@@ -0,0 +1,4 @@
+"""Independent command orchestration and acceptance evidence for Jarvis."""
+
+__version__ = "1.0.0"
+

jarvis_forge/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+raise SystemExit(main())
+

jarvis_forge/apt_cli.py

@@ -0,0 +1,234 @@
+"""APT-shaped commands backed by Forge recipes, never the system apt binary."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+import shlex
+from typing import Optional
+
+from packaging.version import Version
+import typer
+
+from .catalog import Catalog, requirement, source_config
+from .packages import (edit_sources, environment_path, install, installed, plan_install,
+                       plan_remove, remove, update)
+from .storage import ForgeError
+
+
+app = typer.Typer(invoke_without_command=True, no_args_is_help=False,
+                  help="Manage source-built packages in your Forge home without sudo.\n\n"
+                       "Command help: jforge apt COMMAND -h")
+
+
+def _emit(ctx, command, **values):
+    from .cli import emit
+    return emit(ctx, "apt " + command, **values)
+
+
+@app.callback()
+def apt(ctx: typer.Context):
+    if ctx.invoked_subcommand is None:
+        if ctx.obj.as_json:
+            _emit(ctx, "help", commands=sorted(ctx.command.commands))
+        else:
+            typer.echo(ctx.get_help())
+
+
+@app.command("list")
+def list_packages(ctx: typer.Context,
+                  pattern: str = typer.Argument("*", help="Package name pattern.", metavar="<pattern>"),
+                  installed_only: bool = typer.Option(False, "--installed", help="Show recorded installations only."),
+                  upgradable: bool = typer.Option(False, "--upgradable", help="Show active packages with newer recipes.")):
+    """List available or installed user-local packages."""
+    records = installed(ctx.obj.home)
+    catalog = Catalog(ctx.obj.home)
+    if installed_only:
+        packages = records
+    else:
+        packages = []
+        for recipe in catalog.list():
+            matches = [r for r in records if r["name"] == recipe["name"] and r["version"] == recipe["version"]]
+            active = next((r for r in matches if r["active"]), None)
+            packages.append({"name": recipe["name"], "version": recipe["version"],
+                             "status": "installed" if matches else "available", "active": bool(active),
+                             "prefix": active["prefix"] if active else "", "description": recipe["description"]})
+    if upgradable:
+        packages = [r for r in records if r["active"] and any(
+            p["name"] == r["name"] and (Version(p["version"]) > Version(r["version"]) or
+             (Version(p["version"]) == Version(r["version"]) and p["source"] != r.get("source")))
+            for p in catalog.list())]
+    _emit(ctx, "list", packages=[p for p in packages if fnmatch.fnmatchcase(p["name"], pattern)])
+
+
+@app.command()
+def search(ctx: typer.Context,
+           query: str = typer.Argument(..., help="Match package names and descriptions.", metavar="<query>")):
+    """Search the recipe catalog without downloading or installing."""
+    _emit(ctx, "search", packages=[{"name": p["name"], "version": p["version"], "description": p["description"]}
+                                  for p in Catalog(ctx.obj.home).list(query)])
+
+
+@app.command()
+def show(ctx: typer.Context,
+         package: str = typer.Argument(..., help="Package or package=version.", metavar="<package>")):
+    """Show recipe details, dependencies and installed locations."""
+    req = requirement(package)
+    choices = [p for p in Catalog(ctx.obj.home).list() if p["name"] == req.name and Version(p["version"]) in req.specifier]
+    if not choices:
+        raise ForgeError(f"No recipe matches {package}.", hint="jforge apt search <query>")
+    recipe = max(choices, key=lambda p: Version(p["version"]))
+    _emit(ctx, "show", package=recipe, installed_instances=[r for r in installed(ctx.obj.home) if r["name"] == req.name])
+
+
+def _install(ctx, packages, jobs, timeout, dry_run, mode):
+    from .cli import _console
+    if dry_run:
+        result = plan_install(ctx.obj.home, packages or [], jobs=jobs, mode=mode)
+        _emit(ctx, mode, dry_run=True, plan=result)
+    else:
+        result = install(ctx.obj.home, packages or [], jobs=jobs, timeout=timeout, mode=mode,
+                         progress=lambda message: _console(stderr=True).print(message, markup=False))
+        _emit(ctx, mode, **result)
+
+
+@app.command("install")
+def install_packages(ctx: typer.Context,
+                     packages: list[str] = typer.Argument(..., help="Package names or name=version specs.", metavar="<packages>"),
+                     jobs: int = typer.Option(1, "--jobs", "-j", min=1, help="Parallel build jobs."),
+                     timeout: float = typer.Option(3600, "--timeout", help="Timeout per build/check command, in seconds."),
+                     dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show the plan without writing or downloading.")):
+    """Download, verify, build and install into private prefixes."""
+    _install(ctx, packages, jobs, timeout, dry_run, "install")
+
+
+@app.command()
+def reinstall(ctx: typer.Context,
+              packages: list[str] = typer.Argument(..., help="Packages to rebuild into new instances.", metavar="<packages>"),
+              jobs: int = typer.Option(1, "--jobs", "-j", min=1, help="Parallel build jobs."),
+              timeout: float = typer.Option(3600, "--timeout", help="Timeout per build/check command, in seconds."),
+              dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show the reinstall plan only.")):
+    """Rebuild requested packages while keeping working instances."""
+    _install(ctx, packages, jobs, timeout, dry_run, "reinstall")
+
+
+@app.command()
+def upgrade(ctx: typer.Context,
+            packages: Optional[list[str]] = typer.Argument(None, help="Upgrade these packages, or all manual roots.", metavar="<packages>"),
+            jobs: int = typer.Option(1, "--jobs", "-j", min=1, help="Parallel build jobs."),
+            timeout: float = typer.Option(3600, "--timeout", help="Timeout per build/check command, in seconds."),
+            dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show the upgrade plan only.")):
+    """Select newer compatible recipes and retain previous instances."""
+    _install(ctx, packages, jobs, timeout, dry_run, "upgrade")
+
+
+@app.command("full-upgrade")
+def full_upgrade(ctx: typer.Context,
+                 jobs: int = typer.Option(1, "--jobs", "-j", min=1, help="Parallel build jobs."),
+                 timeout: float = typer.Option(3600, "--timeout", help="Timeout per build/check command, in seconds."),
+                 dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show the full upgrade plan only.")):
+    """Upgrade all roots and dependencies; old instances are retained."""
+    _install(ctx, [], jobs, timeout, dry_run, "full-upgrade")
+
+
+@app.command()
+def satisfy(ctx: typer.Context,
+            constraints: list[str] = typer.Argument(..., help="Version constraints, such as 'eigen>=3.4'.", metavar="<constraints>"),
+            jobs: int = typer.Option(1, "--jobs", "-j", min=1, help="Parallel build jobs."),
+            timeout: float = typer.Option(3600, "--timeout", help="Timeout per build/check command, in seconds."),
+            dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Resolve constraints without installing.")):
+    """Install recipes satisfying explicit version constraints."""
+    if dry_run:
+        _emit(ctx, "satisfy", dry_run=True, plan=plan_install(ctx.obj.home, constraints, jobs=jobs))
+    else:
+        from .cli import _console
+        _emit(ctx, "satisfy", **install(ctx.obj.home, constraints, jobs=jobs, timeout=timeout,
+                                      progress=lambda m: _console(stderr=True).print(m, markup=False)))
+
+
+def _remove(ctx, packages, automatic, yes, dry_run):
+    command = "autoremove" if automatic else "remove"
+    plan = plan_remove(ctx.obj.home, packages, automatic=automatic)
+    if dry_run:
+        _emit(ctx, command, dry_run=True, **plan)
+        return
+    if plan["packages"] and not yes:
+        import sys
+        if ctx.obj.as_json or not sys.stdin.isatty():
+            raise ForgeError("Removal requires --yes in non-interactive/JSON mode.",
+                             hint=f"jforge apt {command} {' '.join(packages)} --yes")
+        names = ", ".join(f"{p['name']}={p['version']} ({p['install_id']})" for p in plan["packages"])
+        if not typer.confirm(f"Remove {names}?", default=False):
+            raise ForgeError("Removal cancelled.")
+    _emit(ctx, command, **remove(ctx.obj.home, packages, automatic=automatic, expected_keys=plan["keys"]))
+
+
+@app.command("remove")
+def remove_packages(ctx: typer.Context,
+                    packages: list[str] = typer.Argument(..., help="Package names or name=version specs.", metavar="<packages>"),
+                    yes: bool = typer.Option(False, "--yes", "-y", help="Confirm removal of the selected installations."),
+                    dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show what would be removed.")):
+    """Remove Forge-owned installations after dependency checks."""
+    _remove(ctx, packages, False, yes, dry_run)
+
+
+@app.command()
+def autoremove(ctx: typer.Context,
+               yes: bool = typer.Option(False, "--yes", "-y", help="Confirm removal of unused automatic dependencies."),
+               dry_run: bool = typer.Option(False, "--dry-run", "-s", help="Show unused automatic dependencies.")):
+    """Remove automatic packages unreachable from retained manual installs."""
+    _remove(ctx, [], True, yes, dry_run)
+
+
+@app.command("update")
+def update_sources(ctx: typer.Context):
+    """Refresh recipe indexes; installed software is not changed."""
+    _emit(ctx, "update", **update(ctx.obj.home))
+
+
+@app.command("import")
+def import_official(ctx: typer.Context,
+                    package: str = typer.Argument(..., help="Official binary or source package name.", metavar="<package>"),
+                    suite: str = typer.Option(..., "--suite", help="Distribution codename, such as bookworm or jammy.", metavar="<str>"),
+                    origin: str = typer.Option("debian", "--origin", help="Official distribution: debian or ubuntu.", metavar="<debian|ubuntu>"),
+                    component: str = typer.Option("main", "--component", help="Repository component.", metavar="<str>"),
+                    name: Optional[str] = typer.Option(None, "--name", help="Forge package name.", metavar="<str>"),
+                    template: Optional[str] = typer.Option(None, "--template", help="Reuse a reviewed Forge recipe's build adapter.", metavar="<str>"),
+                    source_version: Optional[str] = typer.Option(None, "--source-version", help="Pin an exact Debian source version.", metavar="<str>"),
+                    keyring: Optional[Path] = typer.Option(None, "--keyring", help="Require gpgv verification using this trusted archive keyring.", metavar="<path>")):
+    """Import official source metadata and track recipes with apt update."""
+    from .official import import_package
+    result = import_package(ctx.obj.home, package, origin=origin, suite=suite, component=component,
+                            name=name, template_name=template, source_version=source_version, keyring=keyring)
+    _emit(ctx, "import", **result)
+
+
+@app.command("edit-sources")
+def configure_sources(ctx: typer.Context,
+                      add: Optional[str] = typer.Option(None, "--add", help="Add a local directory/file or HTTPS YAML index.", metavar="<source>"),
+                      remove_source: Optional[str] = typer.Option(None, "--remove", help="Remove a configured source.", metavar="<source>"),
+                      yes: bool = typer.Option(False, "--yes", "-y", help="Confirm removal of a configured source.")):
+    """Show or edit Forge recipe sources without opening an editor."""
+    if add or remove_source:
+        if remove_source and not yes:
+            import sys
+            if ctx.obj.as_json or not sys.stdin.isatty():
+                raise ForgeError("Removing a source requires --yes in non-interactive/JSON mode.")
+            if not typer.confirm(f"Remove recipe source {remove_source}?", default=False):
+                raise ForgeError("Source removal cancelled.")
+        _emit(ctx, "edit-sources", **edit_sources(ctx.obj.home, add=add, remove_source=remove_source))
+    else:
+        _emit(ctx, "edit-sources", path=str(ctx.obj.home.root / "apt/sources.json"), **source_config(ctx.obj.home))
+
+
+@app.command("env")
+def env(ctx: typer.Context,
+        path: bool = typer.Option(False, "--path", help="Print only the current activation script path.")):
+    """Locate the versioned activation script for active packages."""
+    if path and ctx.obj.as_json:
+        raise ForgeError("--path and --json are mutually exclusive.")
+    activation = environment_path(ctx.obj.home)
+    if path:
+        print(activation)
+    else:
+        _emit(ctx, "env", activation=activation, source_command="source " + shlex.quote(activation))

jarvis_forge/catalog.py

@@ -0,0 +1,171 @@
+"""Recipe catalogs and explicit version constraints for user-local packages."""
+
+from __future__ import annotations
+
+from importlib.resources import files
+import json
+from pathlib import Path
+import re
+
+from jsonschema import Draft202012Validator
+from packaging.requirements import InvalidRequirement, Requirement
+from packaging.version import InvalidVersion, Version
+import yaml
+
+from .downloads import fetch
+from .storage import ForgeError, ForgeHome, digest, now, read_json, write_json
+from .suite import UniqueLoader
+
+
+def requirement(text: str) -> Requirement:
+    value = re.sub(r"\s*\(([^()]+)\)\s*$", r"\1", text.strip())
+    value = re.sub(r"(?<=[A-Za-z0-9_])=(?!=)", "==", value)
+    try:
+        req = Requirement(value)
+    except InvalidRequirement as exc:
+        raise ForgeError(f"Invalid package constraint: {text!r}") from exc
+    if req.extras or req.marker or req.url or not re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", req.name):
+        raise ForgeError(f"Unsupported package constraint: {text!r}")
+    return req
+
+
+def validate_recipe(recipe: dict, origin: str) -> dict:
+    schema = json.loads(files("jarvis_forge").joinpath("schemas/recipe.schema.json").read_text())
+    error = next(iter(Draft202012Validator(schema).iter_errors(recipe)), None)
+    if error:
+        raise ForgeError(f"Invalid recipe in {origin}: {error.message}")
+    if recipe.get("provenance", {}).get("status") == "draft":
+        raise ForgeError(f"Recipe is a draft and needs a build adapter: {origin}")
+    if recipe["source"].get("patch_archive") and "patch" not in recipe.get("requires_tools", []):
+        raise ForgeError(f"Recipes with patch archives must require the patch tool: {origin}")
+    try:
+        Version(recipe["version"])
+    except InvalidVersion as exc:
+        raise ForgeError(f"Invalid package version in {origin}: {recipe['version']}") from exc
+    subdir = Path(recipe["source"]["subdir"])
+    if subdir.is_absolute() or ".." in subdir.parts:
+        raise ForgeError(f"Invalid source subdirectory in {origin}.")
+    for dep in recipe.get("depends", []):
+        requirement(dep)
+    return recipe
+
+
+def read_recipes(text: str, origin: str) -> list[dict]:
+    try:
+        data = yaml.load(text, Loader=UniqueLoader)
+    except (yaml.YAMLError, UnicodeError) as exc:
+        raise ForgeError(f"Cannot read recipe source {origin}: {exc}") from exc
+    if isinstance(data, dict) and "packages" in data:
+        if set(data) != {"schema_version", "packages"} or data["schema_version"] != 1 or not isinstance(data["packages"], list):
+            raise ForgeError(f"Invalid recipe index: {origin}")
+        recipes = data["packages"]
+    else:
+        recipes = [data]
+    return [validate_recipe(item, origin) for item in recipes]
+
+
+class Catalog:
+    def __init__(self, home: ForgeHome):
+        self.home = home
+        self.items = {}
+        for path in sorted(files("jarvis_forge").joinpath("recipes").iterdir(), key=lambda p: p.name):
+            if path.name.endswith(".yaml"):
+                self._add(read_recipes(path.read_text(), f"bundled:{path.name}"), f"bundled:{path.name}")
+        cached = home.root / "cache/apt/catalog.json"
+        if cached.exists():
+            record = read_json(cached)
+            if record.get("schema_version") != 1 or not isinstance(record.get("packages"), list):
+                raise ForgeError(f"Invalid cached catalog: {cached}")
+            for item in record["packages"]:
+                if not isinstance(item, dict) or not isinstance(item.get("origin"), str):
+                    raise ForgeError(f"Invalid cached recipe entry: {cached}")
+                self._add([validate_recipe(item.get("recipe"), item["origin"])], item["origin"])
+        official = home.root / "cache/apt/official.json"
+        if official.exists():
+            record = read_json(official)
+            if record.get("schema_version") != 1 or not isinstance(record.get("packages"), list):
+                raise ForgeError(f"Invalid official-source catalog: {official}")
+            for item in record["packages"]:
+                self._add([validate_recipe(item["recipe"], item["origin"])], item["origin"])
+        for path in sorted((home.root / "recipes").glob("*.yaml")):
+            self._add(read_recipes(path.read_text(encoding="utf-8"), str(path)), str(path))
+
+    def _add(self, recipes, origin):
+        for recipe in recipes:
+            self.items[(recipe["name"], recipe["version"])] = {"recipe": recipe, "origin": origin}
+
+    def list(self, query="") -> list[dict]:
+        return [dict(item["recipe"], origin=item["origin"]) for _, item in sorted(self.items.items())
+                if query.lower() in (item["recipe"]["name"] + " " + item["recipe"]["description"]).lower()]
+
+    def resolve(self, specs: list[str]) -> list[dict]:
+        def solve(pending, selected, constraints):
+            if not pending:
+                return selected
+            req, *rest = pending
+            limits = {key: list(value) for key, value in constraints.items()}
+            limits.setdefault(req.name, []).append(req.specifier)
+            matches = lambda v: all(v in spec for spec in limits[req.name])
+            if req.name in selected:
+                return solve(rest, selected, limits) if matches(Version(selected[req.name]["version"])) else None
+            choices = [item["recipe"] for (name, _), item in self.items.items()
+                       if name == req.name and matches(Version(item["recipe"]["version"]))]
+            for choice in sorted(choices, key=lambda r: Version(r["version"]), reverse=True):
+                found = solve([requirement(dep) for dep in choice.get("depends", [])] + rest,
+                              {**selected, req.name: choice}, limits)
+                if found is not None:
+                    return found
+            return None
+
+        selected = solve([requirement(s) for s in specs], {}, {})
+        if selected is None:
+            raise ForgeError(f"No compatible recipes satisfy: {', '.join(specs)}", hint="jforge apt search <name>")
+        ordered, visiting, done = [], set(), set()
+
+        def visit(name):
+            if name in visiting:
+                raise ForgeError(f"Recipe dependency cycle involving {name}.")
+            if name in done:
+                return
+            visiting.add(name)
+            for spec in selected[name].get("depends", []):
+                visit(requirement(spec).name)
+            visiting.remove(name)
+            done.add(name)
+            ordered.append(selected[name])
+
+        for name in selected:
+            visit(name)
+        return ordered
+
+
+def source_config(home: ForgeHome) -> dict:
+    path = home.root / "apt/sources.json"
+    config = read_json(path) if path.exists() else {"schema_version": 1, "sources": []}
+    if (config.get("schema_version") != 1 or not isinstance(config.get("sources"), list)
+            or not all(isinstance(s, str) for s in config["sources"])):
+        raise ForgeError(f"Invalid source configuration: {path}")
+    return config
+
+
+def update_catalog(home: ForgeHome, operation: Path) -> dict:
+    entries, sources = [], []
+    for index, source in enumerate(source_config(home)["sources"]):
+        if source.startswith("https://"):
+            path = operation / f"source-{index}.yaml"
+            fetch(source, path, operation / f"source-{index}")
+            paths = [path]
+        else:
+            location = Path(source).expanduser()
+            if not location.is_absolute():
+                raise ForgeError(f"Local recipe sources must be absolute paths: {source}")
+            paths = sorted(location.glob("*.yaml")) if location.is_dir() else [location]
+            if not location.exists():
+                raise ForgeError(f"Recipe source does not exist: {source}")
+        for path in paths:
+            for recipe in read_recipes(path.read_text(encoding="utf-8"), source):
+                entries.append({"recipe": recipe, "origin": source})
+            sources.append({"source": source, "path": str(path), "sha256": digest(path)})
+    result = {"schema_version": 1, "updated_at": now(), "packages": entries, "sources": sources}
+    write_json(home.root / "cache/apt/catalog.json", result)
+    return {"sources": sources, "available": len(Catalog(home).list()), "updated_at": result["updated_at"]}