xharness 0.1.0__tar.gz

xharness-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+**/.venv/
+**/node_modules/
+**/__pycache__/
+**/.pytest_cache/
+**/dist/
+*.egg-info/

xharness-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Kip Yin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

xharness-0.1.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: xharness
+Version: 0.1.0
+Summary: Shared operational harness library: Windows executable packaging, release deployment, configuration, environment, and logging (Python).
+Author-email: Kip Yin <28321392+kipyin@users.noreply.github.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# xharness
+
+面向 Python 和 TypeScript 的共享基础库，提供 Windows 应用打包、发布部署、配置与日志等运维支持。
+
+最低环境要求：Python 3.12 与 Node.js 22。
+
+## 安装
+
+### Python (uv)
+
+```sh
+uv add xharness
+```
+
+### TypeScript / Node.js (npm)
+
+```sh
+npm i @lightxlab/xharness
+```
+
+## 快速上手
+
+xharness 核心用于产品的打包与发布部署。
+
+### 1. 本地打包 Windows 可执行文件
+
+支持 `.py`（基于 PyInstaller）和 `.js`（基于 Node pkg）入口，默认打包输出至 `dist/`。
+
+#### Python
+
+```python
+from xharness import deploy
+
+request = deploy.BuildRequest(entrypoint="app.py")
+output_path = deploy.build(request)
+
+print(f"可执行文件已生成: {output_path}")
+```
+
+也可以直接通过 CLI 打包：
+
+```sh
+uv run xharness-build --entrypoint app.py
+```
+
+#### TypeScript
+
+```ts
+import { deploy } from "@lightxlab/xharness";
+
+const { artifactPath } = await deploy.build({
+  entrypoint: "app.js",
+});
+
+console.log(`可执行文件已生成: ${artifactPath}`);
+```
+
+### 2. 打包配置 (xharness.toml)
+
+如果需要自定义打包名称、输出目录或打包工具参数，可在产品根目录创建 `xharness.toml`：
+
+```toml
+product = "my-product"
+output = "dist"
+
+[pyinstaller]
+hidden-imports = ["uvicorn"]
+resources = [
+  { source = "assets", destination = "assets" }
+]
+
+[pkg]
+compress = "GZip"
+```
+
+### 3. 运行时配置与日志（占位接口）
+
+```python
+from xharness import config, env, logging
+
+logging.configure()
+runtime = env.runtime_name()
+settings = config.load()
+```
+
+> 当前 `config.load`、`env.runtime_name` / `runtimeName` 和 `logging.configure` 为接口占位桩函数（调用抛出 `NotImplementedError` / `Error`），后续版本开放具体实现。
+
+## 许可
+
+[Apache-2.0](LICENSE)

xharness-0.1.0/README.md

@@ -0,0 +1,90 @@
+# xharness
+
+面向 Python 和 TypeScript 的共享基础库，提供 Windows 应用打包、发布部署、配置与日志等运维支持。
+
+最低环境要求：Python 3.12 与 Node.js 22。
+
+## 安装
+
+### Python (uv)
+
+```sh
+uv add xharness
+```
+
+### TypeScript / Node.js (npm)
+
+```sh
+npm i @lightxlab/xharness
+```
+
+## 快速上手
+
+xharness 核心用于产品的打包与发布部署。
+
+### 1. 本地打包 Windows 可执行文件
+
+支持 `.py`（基于 PyInstaller）和 `.js`（基于 Node pkg）入口，默认打包输出至 `dist/`。
+
+#### Python
+
+```python
+from xharness import deploy
+
+request = deploy.BuildRequest(entrypoint="app.py")
+output_path = deploy.build(request)
+
+print(f"可执行文件已生成: {output_path}")
+```
+
+也可以直接通过 CLI 打包：
+
+```sh
+uv run xharness-build --entrypoint app.py
+```
+
+#### TypeScript
+
+```ts
+import { deploy } from "@lightxlab/xharness";
+
+const { artifactPath } = await deploy.build({
+  entrypoint: "app.js",
+});
+
+console.log(`可执行文件已生成: ${artifactPath}`);
+```
+
+### 2. 打包配置 (xharness.toml)
+
+如果需要自定义打包名称、输出目录或打包工具参数，可在产品根目录创建 `xharness.toml`：
+
+```toml
+product = "my-product"
+output = "dist"
+
+[pyinstaller]
+hidden-imports = ["uvicorn"]
+resources = [
+  { source = "assets", destination = "assets" }
+]
+
+[pkg]
+compress = "GZip"
+```
+
+### 3. 运行时配置与日志（占位接口）
+
+```python
+from xharness import config, env, logging
+
+logging.configure()
+runtime = env.runtime_name()
+settings = config.load()
+```
+
+> 当前 `config.load`、`env.runtime_name` / `runtimeName` 和 `logging.configure` 为接口占位桩函数（调用抛出 `NotImplementedError` / `Error`），后续版本开放具体实现。
+
+## 许可
+
+[Apache-2.0](LICENSE)

xharness-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xharness"
+version = "0.1.0"
+description = "Shared operational harness library: Windows executable packaging, release deployment, configuration, environment, and logging (Python)."
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [{ name = "Kip Yin", email = "28321392+kipyin@users.noreply.github.com" }]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.scripts]
+xharness-build = "xharness.deploy.build:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pyinstaller>=6.0",
+]
+
+[tool.uv]
+package = true
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/xharness"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/xharness", "pyproject.toml"]
+ignore-vcs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-ra -m 'not live'"
+markers = [
+    "live: package-manager install outside the default suite",
+]

xharness-0.1.0/src/xharness/__init__.py

@@ -0,0 +1,5 @@
+"""Shared light* coding harness library (Python)."""
+
+from . import config, deploy, env, logging
+
+__all__ = ["config", "deploy", "env", "logging"]

xharness-0.1.0/src/xharness/config.py

@@ -0,0 +1,6 @@
+"""Configuration loading for light* apps (stub)."""
+
+
+def load() -> dict[str, object]:
+    """Load harness configuration from the environment."""
+    raise NotImplementedError("xharness.config.load is not implemented yet")

xharness-0.1.0/src/xharness/deploy/__init__.py

@@ -0,0 +1,5 @@
+"""Unified light* packaging surface (Windows executables today; Docker later)."""
+
+from xharness.deploy.build import BuildError, BuildRequest, build
+
+__all__ = ["BuildError", "BuildRequest", "build"]

xharness-0.1.0/src/xharness/deploy/build.py

@@ -0,0 +1,802 @@
+"""Build the dev executable, or the release trio on the single product tag."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import platform
+import re
+import shutil
+import subprocess
+import sys
+import tomllib
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from importlib.metadata import PackageNotFoundError, version as distribution_version
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+type _Package = Callable[[Path, Path, Path, str], Path]
+
+_PRODUCT_NAME = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,62}")
+_CALVER = re.compile(r"(\d{4})\.(\d{1,2})\.(\d+)")
+_HARNESS_CLOCK_OFFSET = timedelta(hours=8)
+_NODE_MAJOR = "22"
+_PKG_TARGET = f"node{_NODE_MAJOR}-win-x64"
+_PKG_HOSTS = {"linux", "darwin", "win32"}
+_WINDOWS_X64 = {"amd64", "x86_64"}
+_CMD_SUFFIXES = {".cmd", ".bat"}
+_MANIFEST_FIELDS = (
+    "artifact",
+    "backend",
+    "backend_version",
+    "build_host_architecture",
+    "build_host_platform",
+    "checksum_sha256",
+    "commit",
+    "product",
+    "signature",
+    "tag",
+    "target",
+    "target_architecture",
+    "target_platform",
+    "tool_versions",
+    "version",
+)
+_HOST_ARCHITECTURES = {
+    "amd64": "amd64",
+    "x86_64": "amd64",
+    "arm64": "arm64",
+    "aarch64": "arm64",
+    "x86": "x86",
+    "i386": "x86",
+    "i686": "x86",
+}
+_BACKDOOR_TOP_KEYS = {"product", "output", "pyinstaller", "pkg"}
+_PYINSTALLER_KEYS = {"pin", "hidden-imports", "resources"}
+_PKG_KEYS = {"pin", "public-packages", "bytecode", "public", "compress", "config"}
+_COMPRESSIONS = {"Brotli", "GZip", "Zstd", "None"}
+_MODULE_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*")
+_BACKDOOR_CALL_KEYS = {
+    "entrypoint",
+    "target",
+    "backend",
+    "architecture",
+    "runner",
+    "signing",
+    "signing-command",
+    "pre-ship",
+    "pre-ship-command",
+}
+
+
+class BuildError(Exception):
+    """The build stopped before an executable was published."""
+
+
+@dataclass(frozen=True)
+class _Release:
+    """The release identity read from a clean HEAD carrying only the product v* tag."""
+
+    tag: str
+    version: str
+    commit: str
+
+
+@dataclass(frozen=True)
+class _Packager:
+    """The gated packaging backend: the packaging step and its installed tool version."""
+
+    package: _Package
+    tool_version: Callable[[], str]
+
+
+@dataclass(frozen=True)
+class _Backdoor:
+    """Overrides from the optional xharness.toml at the product root."""
+
+    product: str | None = None
+    output: Path | None = None
+    hidden_imports: tuple[str, ...] = ()
+    resources: tuple[tuple[str, str], ...] = ()
+    pkg_args: tuple[str, ...] = ()
+
+
+def _read_backdoor(root: Path) -> _Backdoor:
+    path = root / "xharness.toml"
+    if not path.is_file():
+        return _Backdoor()
+    text = path.read_text(encoding="utf-8")
+    if text.strip() == "":
+        return _Backdoor()
+    try:
+        parsed = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise BuildError(f"xharness.toml is not valid TOML: {error}") from error
+    _check_backdoor_keys(parsed, _BACKDOOR_TOP_KEYS)
+    pyinstaller = _backdoor_table(parsed, "pyinstaller", _PYINSTALLER_KEYS)
+    pkg = _backdoor_table(parsed, "pkg", _PKG_KEYS)
+    # A dev build ignores tool pins; the release workflow honors them.
+    _backdoor_text(pyinstaller, "pin")
+    _backdoor_text(pkg, "pin")
+    output = _backdoor_text(parsed, "output")
+    return _Backdoor(
+        product=_backdoor_text(parsed, "product"),
+        output=None if output is None else Path(output),
+        hidden_imports=_backdoor_hidden_imports(pyinstaller),
+        resources=_backdoor_resources(root, pyinstaller),
+        pkg_args=_backdoor_pkg_args(root, pkg),
+    )
+
+
+def _backdoor_hidden_imports(table: dict[str, object]) -> tuple[str, ...]:
+    value = table.get("hidden-imports")
+    if value is None:
+        return ()
+    if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+        raise BuildError("xharness.toml hidden-imports must be a list of Python module names.")
+    for item in value:
+        if not _MODULE_NAME.fullmatch(item):
+            raise BuildError(f"xharness.toml hidden-imports entry {item!r} is not a Python module name.")
+    return tuple(value)
+
+
+def _backdoor_resources(root: Path, table: dict[str, object]) -> tuple[tuple[str, str], ...]:
+    value = table.get("resources")
+    if value is None:
+        return ()
+    if not isinstance(value, list):
+        raise BuildError("xharness.toml resources must be a list of source/destination pairs.")
+    pairs: list[tuple[str, str]] = []
+    for item in value:
+        fields = item if isinstance(item, dict) else {}
+        source, destination = fields.get("source"), fields.get("destination")
+        if (
+            set(fields) != {"source", "destination"}
+            or not isinstance(source, str)
+            or source.strip() == ""
+            or not isinstance(destination, str)
+            or destination.strip() == ""
+        ):
+            raise BuildError("An xharness.toml resource must name a source and a destination.")
+        source_path = _inside_file(root, source, "resource")
+        _target_relative_path(destination, "resource destination")
+        if os.pathsep in f"{source_path}{destination}":
+            raise BuildError(
+                f"Resource {source!r} cannot be passed to PyInstaller because its path contains {os.pathsep!r}."
+            )
+        pairs.append((source, destination))
+    return tuple(pairs)
+
+
+def _backdoor_pkg_args(root: Path, table: dict[str, object]) -> tuple[str, ...]:
+    args: list[str] = []
+    if _backdoor_flag(table, "bytecode") is False:
+        args.append("--no-bytecode")
+    if _backdoor_flag(table, "public") is True:
+        args.append("--public")
+    public_packages = _backdoor_text(table, "public-packages")
+    if public_packages is not None:
+        args.extend(["--public-packages", public_packages])
+    compress = _backdoor_text(table, "compress")
+    if compress is not None:
+        if compress not in _COMPRESSIONS:
+            raise BuildError(f"xharness.toml compress {compress!r} is not one of Brotli, GZip, Zstd, None.")
+        args.extend(["--compress", compress])
+    config = _backdoor_text(table, "config")
+    if config is not None:
+        args.extend(["--config", str(_inside_file(root, config, "pkg config"))])
+    return tuple(args)
+
+
+def _backdoor_flag(table: dict[str, object], key: str) -> bool | None:
+    value = table.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, bool):
+        raise BuildError(f"xharness.toml key {key!r} must be true or false.")
+    return value
+
+
+def _backdoor_table(parsed: dict[str, object], key: str, allowed: set[str]) -> dict[str, object]:
+    value = parsed.get(key)
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise BuildError(f"xharness.toml section {key!r} must be a table.")
+    _check_backdoor_keys(value, allowed)
+    return value
+
+
+def _check_backdoor_keys(table: dict[str, object], allowed: set[str]) -> None:
+    for key in table:
+        if key.lower().replace("_", "-") in _BACKDOOR_CALL_KEYS:
+            raise BuildError(
+                f"xharness.toml cannot set {key!r}. The entrypoint, target, backend, architecture, "
+                "runner, signing command, and pre-ship command stay on the call."
+            )
+        if key not in allowed:
+            raise BuildError(f"Unknown xharness.toml key {key!r}.")
+
+
+def _backdoor_text(table: dict[str, object], key: str) -> str | None:
+    value = table.get(key)
+    if value is None:
+        return None
+    if not isinstance(value, str) or value.strip() == "":
+        raise BuildError(f"xharness.toml key {key!r} must be a non-empty string.")
+    return value
+
+
+@dataclass(frozen=True)
+class BuildRequest:
+    """A Windows build: an entrypoint, an optional output directory, an optional signing command."""
+
+    entrypoint: str
+    output: Path | None = None
+    signing_command: tuple[str, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if self.output is not None:
+            if str(self.output).strip() == "":
+                raise BuildError("The output directory must be a non-empty path.")
+            object.__setattr__(self, "output", Path(self.output).expanduser())
+        if self.signing_command is not None:
+            object.__setattr__(self, "signing_command", tuple(self.signing_command))
+
+
+def build(request: BuildRequest) -> Path:
+    """Build the Windows executable named by the source state and return its path.
+
+    The current directory is the product root. A ``.py`` entrypoint takes the
+    product name from ``pyproject.toml`` and packages with PyInstaller, which
+    runs on 64-bit Windows only. Any other entrypoint takes the ``package.json``
+    name without a single leading scope and packages with an installed ``pkg``.
+    An optional ``xharness.toml`` at the product root overrides the product
+    name, the output directory, Python hidden imports and resource pairs, and
+    the documented ``pkg`` options; a tool pin in the file stays with the
+    release workflow, and an output directory on the call wins over the file.
+
+    A clean ``HEAD`` whose only tag is ``v`` plus the product CalVer publishes
+    the release trio: ``{product}-{version}-win-windows-x64.exe``, its
+    manifest, and its SHA-256 checksum, where the version is the tag without
+    the ``v``. The trio appears together; a failure removes any partial set.
+    Any other source state writes ``{product}-win-x64-{YYYYMMDDTHHMMSS}-dev.exe``
+    on the harness clock, UTC+08:00. The dev build writes no manifest and no
+    checksum, keeps older dev executables, and downloads neither a packaging
+    tool nor the Windows Node base binary.
+    """
+
+    if request.signing_command is not None:
+        _validate_signing(request.signing_command)
+    root = Path.cwd().resolve()
+    entrypoint = _inside_file(root, request.entrypoint, "entrypoint")
+    backend = "pyinstaller" if entrypoint.name.lower().endswith(".py") else "pkg"
+    backdoor = _read_backdoor(root)
+    product = _check_product_name(
+        backdoor.product if backdoor.product is not None else _product_name(root, backend)
+    )
+    output = _output_path(root, request.output if request.output is not None else backdoor.output)
+    release = _release_identity(root)
+    stem = (
+        f"{product}-{release.version}-win-windows-x64"
+        if release is not None
+        else f"{product}-win-x64-{_dev_timestamp()}-dev"
+    )
+    packager: _Packager = (
+        _gate_pyinstaller(backdoor.hidden_imports, backdoor.resources)
+        if backend == "pyinstaller"
+        else _gate_pkg(backdoor.pkg_args)
+    )
+    output.mkdir(parents=True, exist_ok=True)
+    stage = output / f".xharness-stage-{uuid.uuid4().hex}"
+    stage.mkdir()
+    try:
+        executable = packager.package(root, entrypoint, stage, stem)
+        if request.signing_command is not None:
+            _run_signing_command(request.signing_command, executable)
+        if release is None:
+            destination = output / f"{stem}.exe"
+            os.replace(executable, destination)
+        else:
+            destination = _publish_release(
+                stage,
+                output,
+                stem,
+                executable,
+                release=release,
+                product=product,
+                backend=backend,
+                tool_version=packager.tool_version(),
+                signed=request.signing_command is not None,
+            )
+    except BuildError:
+        raise
+    except OSError as error:
+        raise BuildError(str(error)) from error
+    finally:
+        shutil.rmtree(stage, ignore_errors=True)
+    if release is not None and stage.exists():
+        _remove_output_names(output, _release_filenames(stem))
+        raise BuildError("The build stage could not be removed. Partial outputs were removed.")
+    return destination
+
+
+def main(argv: list[str] | None = None) -> None:
+    """CLI entry for the `xharness-build` script."""
+
+    parser = argparse.ArgumentParser(description="Build the Windows product executable named by the source state.")
+    parser.add_argument("--entrypoint", required=True)
+    parser.add_argument("--output", type=Path)
+    parser.add_argument(
+        "--signing-arg",
+        action="append",
+        dest="signing_command",
+        help="Repeat for each argument of a product-owned signing command. The executable path is appended.",
+    )
+    args = parser.parse_args(argv)
+    try:
+        path = build(
+            BuildRequest(
+                entrypoint=args.entrypoint,
+                output=args.output,
+                signing_command=None if args.signing_command is None else tuple(args.signing_command),
+            )
+        )
+    except BuildError as error:
+        print(error, file=sys.stderr)
+        raise SystemExit(1) from error
+    print(path)
+
+
+def _relative_path(value: str, label: str) -> Path:
+    path = Path(value)
+    if value == "" or path.is_absolute() or ".." in path.parts:
+        raise BuildError(f"The {label} {value!r} must be a relative path inside the product root.")
+    return path
+
+
+def _target_relative_path(value: str, label: str) -> None:
+    # A resource destination is consumed on the Windows target, so check both path dialects.
+    # Python 3.13 treats a drive without a root, such as C:assets, as not absolute.
+    windows = PureWindowsPath(value)
+    if (
+        windows.drive
+        or windows.root
+        or PurePosixPath(value).is_absolute()
+        or ".." in value.replace("\\", "/").split("/")
+    ):
+        raise BuildError(f"The {label} {value!r} must be a relative path inside the product root.")
+
+
+def _is_inside(root: Path, path: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def _inside_file(root: Path, value: str, label: str) -> Path:
+    relative = _relative_path(value, label)
+    path = (root / relative).resolve()
+    if not _is_inside(root, path) or not path.is_file():
+        raise BuildError(f"The {label} {value!r} must be a file inside the product root.")
+    return path
+
+
+def _validate_signing(command: tuple[str, ...]) -> None:
+    if not command or any(argument == "" for argument in command):
+        raise BuildError("Signing is unsigned by default. Provide a product-owned signing command, or omit it.")
+
+
+def _product_name(root: Path, backend: str) -> str:
+    if backend == "pyinstaller":
+        text = _manifest_text(root, "pyproject.toml")
+        try:
+            parsed = tomllib.loads(text)
+        except tomllib.TOMLDecodeError as error:
+            raise BuildError(f"pyproject.toml is not valid TOML: {error}") from error
+        project = parsed.get("project")
+        name = project.get("name") if isinstance(project, dict) else None
+        if not isinstance(name, str) or name.strip() == "":
+            raise BuildError("pyproject.toml is missing [project] name.")
+        return name
+    text = _manifest_text(root, "package.json")
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError as error:
+        raise BuildError(f"package.json is not valid JSON: {error}") from error
+    name = parsed.get("name") if isinstance(parsed, dict) else None
+    if not isinstance(name, str) or name.strip() == "":
+        raise BuildError("package.json is missing a name.")
+    return re.sub(r"^@[^/]+/", "", name, count=1)
+
+
+def _manifest_text(root: Path, name: str) -> str:
+    manifest = root / name
+    if not manifest.is_file():
+        raise BuildError(f"{name} is missing. The current directory is the product root.")
+    return manifest.read_text(encoding="utf-8")
+
+
+def _check_product_name(name: str) -> str:
+    if not _PRODUCT_NAME.fullmatch(name):
+        raise BuildError(
+            f"Product {name!r} must be a file-safe identity "
+            "of letters, digits, dots, underscores, or hyphens."
+        )
+    return name
+
+
+def _output_path(root: Path, value: Path | None) -> Path:
+    output = value if value is not None else Path("dist")
+    if not output.is_absolute():
+        output = root / output
+    output = output.resolve()
+    if output.exists() and not output.is_dir():
+        raise BuildError(f"Output directory {output} is not a directory.")
+    return output
+
+
+def _dev_timestamp() -> str:
+    shifted = datetime.now(timezone.utc) + _HARNESS_CLOCK_OFFSET
+    return shifted.strftime("%Y%m%dT%H%M%S")
+
+
+def _gate_pyinstaller(hidden_imports: tuple[str, ...], resources: tuple[tuple[str, str], ...]) -> _Packager:
+    if sys.platform != "win32" or platform.machine().lower() not in _WINDOWS_X64:
+        raise BuildError(
+            "PyInstaller packaging runs on 64-bit Windows. "
+            f"This host is {sys.platform} ({platform.machine()})."
+        )
+    version = _installed_pyinstaller_version()
+
+    def package(root: Path, entrypoint: Path, stage: Path, stem: str) -> Path:
+        return _run_pyinstaller(root, entrypoint, stage, stem, hidden_imports, resources)
+
+    return _Packager(package=package, tool_version=lambda: version)
+
+
+def _installed_pyinstaller_version() -> str:
+    try:
+        installed = distribution_version("pyinstaller")
+    except PackageNotFoundError as error:
+        raise BuildError(
+            "PyInstaller is not installed in this environment. "
+            "Install PyInstaller 6 or newer. "
+            "Packaging tools are not downloaded."
+        ) from error
+    major = _version_major(installed)
+    if major is None or major < 6:
+        raise BuildError(
+            f"PyInstaller {installed} is not supported. Install PyInstaller 6 or newer. "
+            "Packaging tools are not downloaded."
+        )
+    return installed
+
+
+def _version_major(installed: str) -> int | None:
+    match = re.match(r"(\d+)", installed)
+    if match is None:
+        return None
+    return int(match.group(1))
+
+
+def _gate_pkg(pkg_args: tuple[str, ...]) -> _Packager:
+    if sys.platform not in _PKG_HOSTS:
+        raise BuildError(
+            f"Unsupported build host {sys.platform!r}. "
+            "Node pkg builds the Windows target on linux, darwin, and win32."
+        )
+    tool = shutil.which("pkg")
+    if tool is None:
+        raise BuildError("pkg is not installed. Install pkg explicitly. xharness does not download it.")
+    _require_base_binary()
+
+    def package(root: Path, entrypoint: Path, stage: Path, stem: str) -> Path:
+        return _run_pkg(root, entrypoint, stage, Path(tool), stem, pkg_args)
+
+    return _Packager(package=package, tool_version=lambda: _pkg_version(Path(tool)))
+
+
+def _pkg_version(tool: Path) -> str:
+    completed = subprocess.run(
+        _tool_command(tool, ["--version"]),
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    match = re.search(r"(\d+\.\d+\.\d+)", completed.stdout)
+    if completed.returncode != 0 or match is None:
+        detail = (completed.stderr or completed.stdout).strip()
+        raise BuildError(f"pkg did not report a version.\n{detail[-400:]}")
+    return match.group(1)
+
+
+def _require_base_binary() -> None:
+    binary = f"node{_NODE_MAJOR} win-x64"
+    cache = os.environ.get("PKG_CACHE_PATH", "").strip()
+    if cache == "":
+        raise BuildError(
+            f"Node base binary for {binary} is not installed. "
+            "Set PKG_CACHE_PATH to a directory that already contains it. xharness does not download it."
+        )
+    marker = f"fetched-v{_NODE_MAJOR}."
+    suffix = "-win-x64"
+    root = Path(cache)
+    found = root.is_dir() and any(
+        path.is_file() and path.name.startswith(marker) and path.name.endswith(suffix)
+        for path in root.rglob("*")
+    )
+    if not found:
+        raise BuildError(
+            f"Node base binary for {binary} is not in {cache}. "
+            "Prefetch it with the pinned pkg-fetch before building. xharness does not download it."
+        )
+
+
+def _run_pyinstaller(
+    root: Path,
+    entrypoint: Path,
+    stage: Path,
+    stem: str,
+    hidden_imports: tuple[str, ...],
+    resources: tuple[tuple[str, str], ...],
+) -> Path:
+    dist = stage / "dist"
+    work = stage / "work"
+    dist.mkdir()
+    work.mkdir()
+    command = [
+        sys.executable,
+        "-m",
+        "PyInstaller",
+        "--noconfirm",
+        "--clean",
+        "--noupx",
+        "--onefile",
+        "--name",
+        stem,
+        "--distpath",
+        str(dist),
+        "--workpath",
+        str(work),
+        "--specpath",
+        str(work),
+    ]
+    for hidden_import in hidden_imports:
+        command.extend(["--hidden-import", hidden_import])
+    for source, destination in resources:
+        command.extend(["--add-data", f"{(root / source).resolve()}{os.pathsep}{destination}"])
+    command.append(str(entrypoint))
+    completed = subprocess.run(
+        command,
+        cwd=root,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    executable = dist / f"{stem}.exe"
+    if completed.returncode != 0 or not executable.is_file():
+        detail = (completed.stderr or completed.stdout).strip()
+        raise BuildError(f"PyInstaller failed to build {stem}.exe.\n{detail[-2000:]}")
+    return executable
+
+
+def _run_pkg(root: Path, entrypoint: Path, stage: Path, tool: Path, stem: str, pkg_args: tuple[str, ...]) -> Path:
+    artifact = f"{stem}.exe"
+    executable = stage / artifact
+    command = _tool_command(
+        tool, [str(entrypoint), "--targets", _PKG_TARGET, "--output", str(executable), *pkg_args]
+    )
+    completed = subprocess.run(
+        command,
+        cwd=root,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    if completed.returncode != 0 or not executable.is_file():
+        detail = (completed.stderr or completed.stdout).strip()
+        raise BuildError(f"pkg failed to build {artifact}.\n{detail[-2000:]}")
+    return executable
+
+
+def _tool_command(tool: Path, args: list[str]) -> list[str]:
+    if sys.platform == "win32" and tool.suffix.lower() in _CMD_SUFFIXES:
+        command = " ".join(_cmd_quote(value) for value in [str(tool), *args])
+        return [os.environ.get("ComSpec") or "cmd.exe", "/d", "/s", "/c", f'"{command}"']
+    return [str(tool), *args]
+
+
+def _cmd_quote(value: str) -> str:
+    return '"' + value.replace("%", "%%").replace('"', '""') + '"'
+
+
+def _run_signing_command(command: tuple[str, ...], executable: Path) -> None:
+    completed = subprocess.run(
+        [*command, str(executable)],
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        capture_output=True,
+        check=False,
+    )
+    if completed.returncode != 0:
+        raise BuildError(
+            "The product signing command failed. "
+            "No signing credential is stored. "
+            f"The command exited {completed.returncode}."
+        )
+
+
+def _release_identity(root: Path) -> _Release | None:
+    try:
+        probe = _git_optional(root, ["rev-parse", "--is-inside-work-tree"])
+        if probe is None or probe.strip() != "true":
+            return None
+        status = _git(root, ["status", "--porcelain", "--untracked-files=all", "--", "."])
+        if status.strip():
+            return None
+        commit = _git(root, ["rev-parse", "HEAD"]).strip()
+        names = [line.strip() for line in _git(root, ["tag", "--points-at", "HEAD"]).splitlines() if line.strip()]
+    except BuildError:
+        return None
+    if len(names) != 1:
+        return None
+    tag = names[0]
+    if not tag.startswith("v") or not _is_calver(tag[1:]):
+        return None
+    return _Release(tag=tag, version=tag[1:], commit=commit)
+
+
+def _is_calver(version: str) -> bool:
+    match = _CALVER.fullmatch(version)
+    if match is None:
+        return False
+    month, counter = match.group(2), match.group(3)
+    if str(int(month)) != month or str(int(counter)) != counter:
+        return False
+    return 1 <= int(month) <= 12
+
+
+def _publish_release(
+    stage: Path,
+    output: Path,
+    stem: str,
+    executable: Path,
+    *,
+    release: _Release,
+    product: str,
+    backend: str,
+    tool_version: str,
+    signed: bool,
+) -> Path:
+    publish = stage / "publish"
+    publish.mkdir()
+    artifact = f"{stem}.exe"
+    destination = publish / artifact
+    os.replace(executable, destination)
+    digest = _sha256(destination)
+    manifest = {
+        "artifact": artifact,
+        "backend": backend,
+        "backend_version": tool_version,
+        "build_host_architecture": _host_architecture(),
+        "build_host_platform": "win" if sys.platform == "win32" else sys.platform,
+        "checksum_sha256": digest,
+        "commit": release.commit,
+        "product": product,
+        "signature": "signed" if signed else "unsigned",
+        "tag": release.tag,
+        "target": "win",
+        "target_architecture": "amd64",
+        "target_platform": "win",
+        "tool_versions": {backend: tool_version},
+        "version": release.version,
+    }
+    manifest_path = publish / f"{stem}.manifest.json"
+    checksum_path = publish / f"{stem}.sha256"
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8", newline="\n")
+    checksum_path.write_text(f"{digest}  {artifact}\n", encoding="utf-8", newline="\n")
+    _verify_evidence(publish, stem, digest)
+    _publish(publish, output, _release_filenames(stem))
+    return output / artifact
+
+
+def _host_architecture() -> str:
+    machine = platform.machine().lower()
+    return _HOST_ARCHITECTURES.get(machine, machine)
+
+
+def _verify_evidence(publish: Path, stem: str, digest: str) -> None:
+    artifact = f"{stem}.exe"
+    if _sha256(publish / artifact) != digest:
+        raise BuildError("The executable checksum does not match the evidence. Nothing was published.")
+    checksum_text = (publish / f"{stem}.sha256").read_text(encoding="utf-8")
+    if checksum_text != f"{digest}  {artifact}\n":
+        raise BuildError("The checksum file does not match the executable. Nothing was published.")
+    loaded = json.loads((publish / f"{stem}.manifest.json").read_text(encoding="utf-8"))
+    if set(loaded) != set(_MANIFEST_FIELDS):
+        raise BuildError("The manifest is missing release evidence. Nothing was published.")
+    if loaded["artifact"] != artifact or loaded["checksum_sha256"] != digest:
+        raise BuildError("The manifest does not match the executable. Nothing was published.")
+    if loaded["signature"] not in {"signed", "unsigned"}:
+        raise BuildError("The manifest signature status is not signed or unsigned. Nothing was published.")
+
+
+def _release_filenames(stem: str) -> tuple[str, str, str]:
+    return (f"{stem}.exe", f"{stem}.manifest.json", f"{stem}.sha256")
+
+
+def _publish(publish: Path, output: Path, names: tuple[str, ...]) -> None:
+    incoming: list[Path] = []
+    try:
+        for name in names:
+            temporary = output / f".{name}.incoming"
+            os.replace(publish / name, temporary)
+            incoming.append(temporary)
+        for temporary, name in zip(incoming, names, strict=True):
+            os.replace(temporary, output / name)
+    except OSError as error:
+        _remove_output_names(output, names)
+        raise BuildError("Publishing the verified set failed. Partial outputs were removed.") from error
+
+
+def _remove_output_names(output: Path, names: tuple[str, ...]) -> None:
+    for name in names:
+        (output / name).unlink(missing_ok=True)
+        (output / f".{name}.incoming").unlink(missing_ok=True)
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _git(root: Path, args: list[str]) -> str:
+    completed = _git_command(root, args)
+    if completed.returncode != 0:
+        detail = (completed.stderr or completed.stdout).strip() or f"git {' '.join(args)} failed"
+        raise BuildError(detail)
+    return completed.stdout
+
+
+def _git_optional(root: Path, args: list[str]) -> str | None:
+    completed = _git_command(root, args)
+    if completed.returncode != 0:
+        return None
+    return completed.stdout
+
+
+def _git_command(root: Path, args: list[str]) -> subprocess.CompletedProcess[str]:
+    env = os.environ.copy()
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    for variable in ("GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_PREFIX"):
+        env.pop(variable, None)
+    try:
+        return subprocess.run(
+            ["git", "-c", "color.ui=false", "-c", "safe.directory=*", "-c", "core.autocrlf=false", *args],
+            cwd=root,
+            env=env,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            capture_output=True,
+            check=False,
+        )
+    except FileNotFoundError as error:
+        raise BuildError("git is required to read the product tag and commit.") from error

xharness-0.1.0/src/xharness/env.py

@@ -0,0 +1,6 @@
+"""Environment detection for light* apps (stub)."""
+
+
+def runtime_name() -> str:
+    """Return a short name for the current runtime (dev, test, packaged, etc.)."""
+    raise NotImplementedError("xharness.env.runtime_name is not implemented yet")

xharness-0.1.0/src/xharness/logging.py

@@ -0,0 +1,6 @@
+"""Logging helpers for light* apps (stub)."""
+
+
+def configure() -> None:
+    """Apply default logging configuration."""
+    raise NotImplementedError("xharness.logging.configure is not implemented yet")