ngksbuildcore 0.1.4__tar.gz

ngksbuildcore-0.1.4/PKG-INFO

@@ -0,0 +1,52 @@
+Metadata-Version: 2.4
+Name: ngksbuildcore
+Version: 0.1.4
+Summary: NGKsBuildCore
+Author: NGKsSystems
+License: Proprietary
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# NGKsBuildCore
+
+NGKsBuildCore is a Python MVP build runner that executes a DAG build plan with deterministic scheduling, parallel workers, and auditable proof logs.
+
+## Commands
+
+- `python -m ngksbuildcore --help`
+- `python -m ngksbuildcore doctor`
+- `python -m ngksbuildcore run --plan examples\hello_plan.json -j 8`
+- `python -m ngksbuildcore explain --plan examples\hello_plan.json`
+
+## Plan Contract
+
+Plan JSON fields:
+
+- `base_dir` optional, defaults to plan file directory
+- `nodes` array of objects with:
+  - `id` (string)
+  - `desc` (string, optional)
+  - `cwd` (string, optional)
+  - `cmd` (string or string array)
+  - `deps` (string array)
+  - `inputs` (path array)
+  - `outputs` (path array)
+  - `env` (dict, optional)
+
+## Proof Output
+
+Each run writes to timestamped proof directory under `_proof` (or `NGKS_PROOF_ROOT`):
+
+- `events.jsonl`
+- `commands.jsonl`
+- `summary.json`
+- `summary.txt`
+- `environment.txt`
+- `tool_versions.txt`
+- `git_status.txt`
+- `git_head.txt`
+
+## Integration Adapters
+
+- `ngksbuildcore.adapters.graph_adapter.run_graph_plan`
+- `ngksbuildcore.adapters.devfabric_adapter.build_from_manifest`

ngksbuildcore-0.1.4/README.md

@@ -0,0 +1,43 @@
+# NGKsBuildCore
+
+NGKsBuildCore is a Python MVP build runner that executes a DAG build plan with deterministic scheduling, parallel workers, and auditable proof logs.
+
+## Commands
+
+- `python -m ngksbuildcore --help`
+- `python -m ngksbuildcore doctor`
+- `python -m ngksbuildcore run --plan examples\hello_plan.json -j 8`
+- `python -m ngksbuildcore explain --plan examples\hello_plan.json`
+
+## Plan Contract
+
+Plan JSON fields:
+
+- `base_dir` optional, defaults to plan file directory
+- `nodes` array of objects with:
+  - `id` (string)
+  - `desc` (string, optional)
+  - `cwd` (string, optional)
+  - `cmd` (string or string array)
+  - `deps` (string array)
+  - `inputs` (path array)
+  - `outputs` (path array)
+  - `env` (dict, optional)
+
+## Proof Output
+
+Each run writes to timestamped proof directory under `_proof` (or `NGKS_PROOF_ROOT`):
+
+- `events.jsonl`
+- `commands.jsonl`
+- `summary.json`
+- `summary.txt`
+- `environment.txt`
+- `tool_versions.txt`
+- `git_status.txt`
+- `git_head.txt`
+
+## Integration Adapters
+
+- `ngksbuildcore.adapters.graph_adapter.run_graph_plan`
+- `ngksbuildcore.adapters.devfabric_adapter.build_from_manifest`

ngksbuildcore-0.1.4/ngksbuildcore/__init__.py

@@ -0,0 +1,3 @@
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

ngksbuildcore-0.1.4/ngksbuildcore/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ngksbuildcore-0.1.4/ngksbuildcore/adapters/__init__.py

@@ -0,0 +1,4 @@
+from .devfabric_adapter import build_from_manifest
+from .graph_adapter import run_graph_plan
+
+__all__ = ["run_graph_plan", "build_from_manifest"]

ngksbuildcore-0.1.4/ngksbuildcore/adapters/devfabric_adapter.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+from ..loggingx import EventLogger
+from ..runner import make_proof_dir
+from .graph_adapter import run_graph_plan
+
+
+def build_from_manifest(manifest_path: str, jobs: int = 1, proof_dir: str | None = None) -> int:
+    manifest_file = Path(manifest_path).resolve()
+    payload = json.loads(manifest_file.read_text(encoding="utf-8"))
+
+    proof = make_proof_dir(proof_dir)
+    logger = EventLogger(proof)
+    try:
+        logger.emit("DEVFABRIC_MANIFEST_LOAD_OK", manifest=str(manifest_file))
+        plan_path = payload.get("plan_path")
+        if plan_path:
+            return run_graph_plan(plan_path=plan_path, jobs=jobs, proof_dir=proof_dir, extra_env={"NGKS_DEVFABRIC_MODE": "1"})
+
+        graph_exe = os.environ.get("NGKS_GRAPH_EXE")
+        if not graph_exe:
+            logger.emit("GRAPH_NOT_FOUND", reason="NGKS_GRAPH_EXE not set and manifest has no plan_path")
+            return 2
+
+        graph_args = payload.get("graph_args", [])
+        out_plan = payload.get("plan_out", str((manifest_file.parent / "generated_plan.json").resolve()))
+        cmd = [graph_exe, *graph_args, "--out", out_plan]
+        logger.emit("GRAPH_GENERATE_START", cmd=cmd)
+        proc = subprocess.run(cmd, text=True, capture_output=True, encoding="utf-8", errors="replace")
+        logger.emit("GRAPH_GENERATE_END", exit_code=proc.returncode, stdout=proc.stdout, stderr=proc.stderr)
+        if proc.returncode != 0:
+            return proc.returncode
+
+        return run_graph_plan(plan_path=out_plan, jobs=jobs, proof_dir=proof_dir, extra_env={"NGKS_DEVFABRIC_MODE": "1"})
+    finally:
+        logger.close()

ngksbuildcore-0.1.4/ngksbuildcore/adapters/graph_adapter.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+from ..runner import run_build
+
+
+def run_graph_plan(plan_path: str, jobs: int = 1, proof_dir: str | None = None, extra_env: Mapping[str, str] | None = None) -> int:
+    env = dict(extra_env or {})
+    return run_build(plan_path=plan_path, jobs=jobs, proof=proof_dir, extra_env=env)

ngksbuildcore-0.1.4/ngksbuildcore/cli.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+from .plan import load_plan
+from .runner import make_proof_dir, run_build
+
+
+def _default_jobs(value: int | None) -> int:
+    if value is not None:
+        return value
+    env_value = os.environ.get("NGKS_BUILD_JOBS")
+    if env_value and env_value.isdigit():
+        return max(1, int(env_value))
+    return 1
+
+
+def _doctor(proof: str | None) -> int:
+    proof_dir = make_proof_dir(proof)
+    checks: list[tuple[str, bool, str]] = []
+
+    py_ok = sys.version_info >= (3, 9)
+    checks.append(("python_version", py_ok, sys.version.split()[0]))
+
+    state_dir = Path(".ngksbuildcore")
+    proof_root = Path("_proof")
+    try:
+        state_dir.mkdir(parents=True, exist_ok=True)
+        test_file = state_dir / "_write_test.tmp"
+        test_file.write_text("ok\n", encoding="utf-8")
+        test_file.unlink()
+        state_ok = True
+        state_msg = "writable"
+    except Exception as exc:
+        state_ok = False
+        state_msg = str(exc)
+    checks.append(("state_dir_write", state_ok, state_msg))
+
+    try:
+        proof_root.mkdir(parents=True, exist_ok=True)
+        test_file = proof_root / "_write_test.tmp"
+        test_file.write_text("ok\n", encoding="utf-8")
+        test_file.unlink()
+        proof_ok = True
+        proof_msg = "writable"
+    except Exception as exc:
+        proof_ok = False
+        proof_msg = str(exc)
+    checks.append(("proof_root_write", proof_ok, proof_msg))
+
+    try:
+        proc = subprocess.run(
+            [sys.executable, "-c", "print('SPAWN_OK')"],
+            check=True,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+        )
+        spawn_ok = "SPAWN_OK" in proc.stdout
+        spawn_msg = proc.stdout.strip()
+    except Exception as exc:
+        spawn_ok = False
+        spawn_msg = str(exc)
+    checks.append(("process_spawn", spawn_ok, spawn_msg))
+
+    passed = all(item[1] for item in checks)
+    result = {
+        "status": "PASS" if passed else "FAIL",
+        "proof_dir": str(proof_dir),
+        "checks": [{"name": n, "ok": ok, "detail": d} for n, ok, d in checks],
+    }
+    (proof_dir / "doctor.json").write_text(json.dumps(result, indent=2, ensure_ascii=True), encoding="utf-8")
+    report_lines = [f"doctor: {result['status']}"] + [f"- {n}: {'PASS' if ok else 'FAIL'} ({d})" for n, ok, d in checks]
+    text = "\n".join(report_lines) + "\n"
+    (proof_dir / "doctor.txt").write_text(text, encoding="utf-8")
+    print(text, end="")
+    return 0 if passed else 1
+
+
+def _explain(plan_path: str, node_id: str | None) -> int:
+    plan = load_plan(plan_path)
+    if node_id is None:
+        print(f"plan: {plan.plan_path}")
+        print(f"base_dir: {plan.base_dir}")
+        print(f"nodes: {len(plan.nodes)}")
+        for n in sorted(plan.nodes, key=lambda x: x.id):
+            print(f"- {n.id}: deps={n.deps} inputs={len(n.inputs)} outputs={len(n.outputs)}")
+        return 0
+
+    found = None
+    for n in plan.nodes:
+        if n.id == node_id:
+            found = n
+            break
+    if not found:
+        print(f"node not found: {node_id}")
+        return 1
+
+    print(json.dumps(
+        {
+            "id": found.id,
+            "desc": found.desc,
+            "cwd": found.cwd,
+            "cmd": found.cmd,
+            "deps": found.deps,
+            "inputs": found.inputs,
+            "outputs": found.outputs,
+            "env": found.env,
+        },
+        indent=2,
+        ensure_ascii=True,
+    ))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="ngksbuildcore", description="NGKsBuildCore MVP build runner")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_cmd = sub.add_parser("run", help="Run a build plan DAG")
+    run_cmd.add_argument("--plan", required=True, help="Path to plan json")
+    run_cmd.add_argument("--env-lock", default=None, help="Path to env_capsule.lock.json")
+    run_cmd.add_argument("-j", "--jobs", type=int, default=None, help="Parallel jobs")
+    run_cmd.add_argument("--proof", default=None, help="Proof root directory override")
+    run_cmd.add_argument("--pf", default=None, help="Proof root directory override (alias of --proof)")
+
+    doctor_cmd = sub.add_parser("doctor", help="Environment diagnostics")
+    doctor_cmd.add_argument("--proof", default=None, help="Proof root directory override")
+    doctor_cmd.add_argument("--pf", default=None, help="Proof root directory override (alias of --proof)")
+
+    explain_cmd = sub.add_parser("explain", help="Explain plan or node")
+    explain_cmd.add_argument("--plan", required=True, help="Path to plan json")
+    explain_cmd.add_argument("--node", default=None, help="Optional node id")
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "run":
+        jobs = _default_jobs(args.jobs)
+        proof_root = args.pf or args.proof
+        return run_build(plan_path=args.plan, jobs=jobs, proof=proof_root, env_lock=args.env_lock)
+    if args.command == "doctor":
+        proof_root = args.pf or args.proof
+        return _doctor(proof_root)
+    if args.command == "explain":
+        return _explain(args.plan, args.node)
+
+    parser.print_help()
+    return 1

ngksbuildcore-0.1.4/ngksbuildcore/hashing.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def normalize_path(path: str | Path, base_dir: Path) -> Path:
+    p = Path(path)
+    if not p.is_absolute():
+        p = (base_dir / p).resolve()
+    else:
+        p = p.resolve()
+    return p
+
+
+def file_fingerprint(path: Path) -> str:
+    stat = path.stat()
+    raw = f"{path}:{stat.st_mtime_ns}:{stat.st_size}".encode("utf-8", errors="replace")
+    return hashlib.sha256(raw).hexdigest()
+
+
+def input_signature(paths: list[Path]) -> str:
+    joined = "|".join(file_fingerprint(p) for p in sorted(paths))
+    return hashlib.sha256(joined.encode("utf-8", errors="replace")).hexdigest()

ngksbuildcore-0.1.4/ngksbuildcore/loggingx.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import json
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def utc_now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class EventLogger:
+    def __init__(self, proof_dir: Path, console_verbose: bool = True) -> None:
+        self.proof_dir = proof_dir
+        self.proof_dir.mkdir(parents=True, exist_ok=True)
+        self.events_path = self.proof_dir / "events.jsonl"
+        self.commands_path = self.proof_dir / "commands.jsonl"
+        self._events_handle = self.events_path.open("a", encoding="utf-8", newline="\n")
+        self._commands_handle = self.commands_path.open("a", encoding="utf-8", newline="\n")
+        self._lock = threading.Lock()
+        self.console_verbose = console_verbose
+
+    def emit(self, event_type: str, **payload: Any) -> None:
+        evt = {"ts": utc_now_iso(), "event": event_type, **payload}
+        line = json.dumps(evt, ensure_ascii=True)
+        with self._lock:
+            self._events_handle.write(line + "\n")
+            self._events_handle.flush()
+
+    def command(self, **payload: Any) -> None:
+        row = {"ts": utc_now_iso(), **payload}
+        line = json.dumps(row, ensure_ascii=True)
+        with self._lock:
+            self._commands_handle.write(line + "\n")
+            self._commands_handle.flush()
+
+    def print(self, message: str) -> None:
+        if self.console_verbose:
+            print(message, flush=True)
+
+    def close(self) -> None:
+        with self._lock:
+            self._events_handle.close()
+            self._commands_handle.close()

ngksbuildcore-0.1.4/ngksbuildcore/plan.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .hashing import normalize_path
+
+
+@dataclass(slots=True)
+class PlanNode:
+    id: str
+    desc: str = ""
+    cwd: str | None = None
+    cmd: str | list[str] = ""
+    deps: list[str] = field(default_factory=list)
+    inputs: list[str] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    env: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class BuildPlan:
+    plan_path: Path
+    base_dir: Path
+    nodes: list[PlanNode]
+
+
+def _as_str_list(value: object) -> list[str]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise ValueError("expected a list")
+    return [str(x) for x in value]
+
+
+def _legacy_node(raw: dict) -> PlanNode:
+    return PlanNode(
+        id=str(raw["id"]),
+        desc=str(raw.get("desc", "")),
+        cwd=raw.get("cwd"),
+        cmd=raw["cmd"],
+        deps=_as_str_list(raw.get("deps", [])),
+        inputs=_as_str_list(raw.get("inputs", [])),
+        outputs=_as_str_list(raw.get("outputs", [])),
+        env={str(k): str(v) for k, v in (raw.get("env") or {}).items()},
+    )
+
+
+def _graph_action_node(raw: dict) -> PlanNode:
+    argv = raw.get("argv", [])
+    if isinstance(argv, list):
+        cmd: str | list[str] = [str(x) for x in argv]
+    else:
+        cmd = str(argv)
+    return PlanNode(
+        id=str(raw["id"]),
+        desc=str(raw.get("desc", "")),
+        cwd=raw.get("cwd"),
+        cmd=cmd,
+        deps=_as_str_list(raw.get("deps", [])),
+        inputs=_as_str_list(raw.get("inputs", [])),
+        outputs=_as_str_list(raw.get("outputs", [])),
+        env={str(k): str(v) for k, v in (raw.get("env") or {}).items()},
+    )
+
+
+def load_plan(plan_path: str | Path) -> BuildPlan:
+    plan_file = Path(plan_path).resolve()
+    with plan_file.open("r", encoding="utf-8") as f:
+        payload = json.load(f)
+
+    if isinstance(payload.get("actions"), list):
+        raw_nodes = payload["actions"]
+        node_factory = _graph_action_node
+    elif isinstance(payload.get("nodes"), list):
+        raw_nodes = payload["nodes"]
+        node_factory = _legacy_node
+    else:
+        if isinstance(payload, dict) and isinstance(payload.get("targets"), list):
+            raise ValueError(
+                "plan json appears graph-native (targets/steps). Use `ngksgraph buildplan` for NGKsBuildCore-compatible output."
+            )
+        raise ValueError("plan json must include either an 'actions' array or a 'nodes' array")
+
+    base_dir_raw = payload.get("base_dir")
+    if base_dir_raw:
+        base_dir = normalize_path(base_dir_raw, plan_file.parent)
+    else:
+        base_dir = plan_file.parent.resolve()
+
+    nodes: list[PlanNode] = []
+    seen_ids: set[str] = set()
+    for raw in raw_nodes:
+        node = node_factory(raw)
+        if node.id in seen_ids:
+            raise ValueError(f"duplicate node id: {node.id}")
+        seen_ids.add(node.id)
+        nodes.append(node)
+
+    id_set = {n.id for n in nodes}
+    for node in nodes:
+        for dep in node.deps:
+            if dep not in id_set:
+                raise ValueError(f"node '{node.id}' depends on unknown node '{dep}'")
+
+    return BuildPlan(plan_path=plan_file, base_dir=base_dir, nodes=nodes)