infinity_make 1.0.0__py3-none-any.whl

infinity_make/__init__.py

@@ -0,0 +1,16 @@
+"""infinity_make —— expr 模式构建系统：infmake.infd 是一棵操作树。
+
+分层结构：
+
+  - :mod:`infinity_make.executor`：操作树执行器（子图去重 + VFS 注入 + 节点缓存）
+  - :mod:`infinity_make.nixenv`：Nix 环境引导（env.infd → ``nix develop`` 重入 / ``--run``）
+  - :mod:`infinity_make.main`：CLI 薄壳（``infmake`` 入口）
+  - :mod:`infinity_make.vfs`：构建工作区 VFS（临时目录 + 按 key 持久缓存）
+
+公共 API：:class:`Executor`、:class:`BuildError`、:func:`main`。
+"""
+
+from infinity_make.executor import BuildError, Executor
+from infinity_make.main import main
+
+__all__ = ['BuildError', 'Executor', 'main']

infinity_make/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m infinity_make`` 入口（Nix 环境重入构建用）。"""
+
+import sys
+
+from infinity_make.main import main
+
+if __name__ == '__main__':
+    sys.exit(main())

infinity_make/executor.py

@@ -0,0 +1,286 @@
+"""操作树执行器：子图 hash 去重 + VFS 注入 + 持久化节点缓存。
+
+每个操作模板 = 数据字段 + _impl（内嵌 Python 实现）。执行器遍历操作树：
+
+  1. 先求值数据字段（子节点先「物化」为记录：输入 + 计算输出）
+  2. 调用节点自带 impl(**数据字段)
+  3. impl 返回的 dict 合并回节点记录（覆盖语义：计算结果优先）
+  4. 根节点最终 = 完整物化树（自包含、可审计、可写为 JSON 产物）
+
+进阶特性：
+  - 子图 hash 去重：相同（模板 + 实现 + 物化输入）的子图只求值一次，结果复用
+  - VFS 注入：impl 签名含 ``vfs`` 参数时注入工作区 VFS（临时目录分配 + 按 key 缓存）
+  - 持久化节点缓存：<工作区>/node_cache/<hash>.json，``dump_to_json`` /
+    ``load_from_json`` 无损往返（Decimal / path / noexist 以自描述标记编码）
+
+与 infd_builder 玩具版的差异（上游 infinity_data 3.x API）：
+  - 无模板 dataclass 生成（templates.py 类型契约）与自动 dataclass 注解扫描注入：
+    impl 收到的参数是**降维后的普通 Python 值**（dict / list / 标量 / PurePosixPath），
+    不再按注解实例化 dataclass
+
+约定：
+  - 入口字段为顶层 ``target``（一棵操作树）
+  - ``_impl`` 源码内定义名为 ``impl`` 的函数（与模板名解耦）
+  - ``_impl`` / ``_gen`` / ``_cache`` 是「元数据」字段，不进物化记录
+  - 无 ``_impl`` 的节点是纯数据节点：直接物化为记录
+"""
+
+import hashlib
+import inspect
+from decimal import Decimal
+from pathlib import Path
+from typing import Any
+
+from infinity_data import CompilationResult
+from infinity_data.emit import dump_to_json, load_from_json
+from infinity_data.semantic.std import (
+    StdArray,
+    StdField,
+    StdLiteral,
+    StdObject,
+    StdValue,
+    python_to_std,
+    std_to_python,
+)
+
+from infinity_make.vfs import VFS, NodeVFS
+
+ENTRY_FIELD = 'target'
+"""顶层入口字段：操作树根。"""
+
+IMPL_FIELD = '_impl'
+"""实现字段：内嵌 Python 源码（定义 ``impl`` 函数）。"""
+
+GEN_FIELD = '_gen'
+"""生成字段声明：模板里 ``_gen: dict = {...}`` 声明 impl 输出字段。
+
+元数据（同 ``_impl``），不进物化记录。"""
+
+CACHE_FIELD = '_cache'
+"""节点缓存开关：模板声明 ``_cache: bool = false`` 关闭持久化缓存（每次执行 impl）。
+
+默认 true（参与 <hash>.json 节点缓存）。元数据字段，不进物化记录。"""
+
+VFS_PARAM = 'vfs'
+"""impl 签名中的 VFS 注入参数名：声明即注入。"""
+
+
+class BuildError(Exception):
+    """构建错误：编译失败、缺 impl、执行失败。"""
+
+
+def _tpl_name(node: StdObject) -> str:
+    """节点模板名（无模板时回退 '?'）。"""
+    return node.template.name if node.template is not None else '?'
+
+
+def _loc_prefix(node: StdObject) -> str:
+    """节点在配置中的位置前缀（``[文件:行:列] ``）；无来源（合成值，如 !var 引用）返回空。"""
+    src = node.source
+    if src is None:
+        return ''
+    return f'[{src.file.name}:{src.start.line}:{src.start.col}] '
+
+
+def _field(node: StdObject, name: str) -> StdValue:
+    """取节点字段值；缺失/无值抛 BuildError。"""
+    for f in node.fields:
+        if f.name == name:
+            if f.value is None:
+                raise BuildError(f'节点 {_tpl_name(node)} 字段 {name!r} 无值')
+            return f.value
+    raise BuildError(f'节点 {_tpl_name(node)} 缺少字段 {name!r}')
+
+
+def _impl_source(node: StdObject) -> str:
+    """取节点自带 _impl 源码（校验为 str）。"""
+    src = _field(node, IMPL_FIELD)
+    if not isinstance(src, StdLiteral) or src.kind != 'str':
+        raise BuildError(f'节点 {_tpl_name(node)} 的 _impl 必须是字符串')
+    return str(src.value)
+
+
+def _impl_func(source: str, tpl_name: str) -> Any:
+    """编译 _impl 源码 → 可调用函数（约定定义名为 ``impl``）。"""
+    ns: dict[str, Any] = {'Any': Any}
+    exec(compile(source, f'<impl:{tpl_name}>', 'exec'), ns)
+    fn = ns.get('impl')
+    if fn is None:
+        raise BuildError(f"节点 {tpl_name} 的 _impl 未定义函数 'impl'")
+    return fn
+
+
+def _hashable(v: Any) -> Any:
+    """字面量值 → 稳定可哈希表示（Decimal → str）。"""
+    return str(v) if isinstance(v, Decimal) else v
+
+
+def _std_fingerprint(value: StdValue | None) -> tuple[Any, ...]:
+    """StdValue 的稳定内容指纹（子图 hash 去重的输入部分）。
+
+    往返一致性：StdObject 排除 noexist / None 字段 —— noexist 不参与构建语义，
+    新鲜态与缓存加载态（emit 往返后仍保留 noexist 标记）指纹保持一致，
+    避免冷启动后下游节点 hash 逐层漂移（缓存永远不中）。
+    """
+    if value is None:
+        return ('none',)
+    if isinstance(value, StdLiteral):
+        return ('lit', value.kind, _hashable(value.value))
+    if isinstance(value, StdArray):
+        return ('arr', tuple(_std_fingerprint(e) for e in value.elements))
+    # 此处 value 已收窄为 StdObject
+    return (
+        'obj',
+        tuple(
+            sorted(
+                (f.name, _std_fingerprint(f.value)) for f in value.fields if f.value is not None and not f.is_noexist
+            )
+        ),
+    )
+
+
+def _key_hash(key: tuple[Any, ...]) -> str:
+    """子图 key（模板名 + 实现 + 输入指纹）→ 稳定 hash（缓存目录名）。"""
+    return hashlib.sha256(repr(key).encode()).hexdigest()[:16]
+
+
+def _node_inputs_key(merged: dict[str, StdValue]) -> tuple[Any, ...]:
+    """物化输入 → 排序后的稳定指纹（字段名无关顺序）。"""
+    return tuple(sorted((name, _std_fingerprint(v)) for name, v in merged.items()))
+
+
+class Executor:
+    """操作树执行器：子图 hash 去重 + VFS 签名注入。
+
+    - **子图去重**：以（模板名 + _impl 源码 + 物化输入指纹）为 key，相同子图只求值一次
+    - **VFS 注入**：impl 签名含 ``vfs`` 参数时注入工作区 VFS（否则不注入）
+    - **无 dataclass 注入**：impl 参数即降维后的普通 Python 值（dict / list / 标量）
+    """
+
+    def __init__(self, vfs: VFS) -> None:
+        self._vfs = vfs
+        self._memo: dict[tuple[Any, ...], StdValue] = {}
+
+    def execute(self, node: StdValue) -> StdValue:
+        """递归执行操作树，返回物化节点（原生 StdValue 域）。"""
+        if isinstance(node, StdLiteral):
+            return node
+        if isinstance(node, StdArray):
+            return StdArray(elements=[self.execute(e) for e in node.elements])
+
+        # 1) 子节点先物化；_impl / _gen / _cache 是元数据字段，不进记录
+        merged: dict[str, StdValue] = {}
+        for f in node.fields:
+            if f.value is None or f.name in (IMPL_FIELD, GEN_FIELD, CACHE_FIELD):
+                continue
+            merged[f.name] = self.execute(f.value)
+
+        if not any(f.name == IMPL_FIELD for f in node.fields):
+            return StdObject(fields=[StdField(name=n, value=v) for n, v in merged.items()])
+
+        # 2) 子图 hash：相同（模板 + 实现 + 输入）只求值一次
+        impl_src = _impl_source(node)
+        key = (_tpl_name(node), impl_src, _node_inputs_key(merged))
+        node_hash = _key_hash(key)  # 复用子图 hash 做缓存指纹（同构同缓存）
+        cached = self._memo.get(key)
+        if cached is not None:
+            return cached
+
+        # 2b) 持久化节点缓存：<node_hash>.json 命中 → 加载物化结果，跳过 impl
+        #     节点默认可缓存；声明 ``_cache: bool = false``（如 ~File 内容检测）→ 每次执行
+        if self._node_cacheable(node):
+            disk = self._load_node_cache(node_hash)
+            if disk is not None:
+                self._memo[key] = disk
+                return disk
+
+        # 3) 调用 impl：字段降维为 Python 实参（std_to_python 忠实转换，noexist 丢弃）；
+        #    签名含 vfs 则注入节点作用域代理
+        #    失败（BuildError / impl 内部异常）→ 附加节点配置位置（stdvalue.source）
+        try:
+            fn = _impl_func(impl_src, _tpl_name(node))
+            args = {name: std_to_python(v, keep_noexist=False) for name, v in merged.items()}
+            result_std = python_to_std(self._call(fn, args, node_hash))
+        except BuildError as e:
+            raise BuildError(f'{_loc_prefix(node)}{e}') from e
+        except Exception as e:
+            raise BuildError(f'{_loc_prefix(node)}{type(e).__name__}: {e}') from e
+
+        # 4) 合并覆盖：impl 返回的 dict 优先于输入
+        if isinstance(result_std, StdObject):
+            for rf in result_std.fields:
+                if rf.value is not None:
+                    merged[rf.name] = rf.value
+            record: StdValue = StdObject(fields=[StdField(name=n, value=v) for n, v in merged.items()])
+        else:
+            record = result_std
+        # 4b) 落盘节点缓存（``_cache: bool = false`` 声明关闭的节点不落盘）
+        if self._node_cacheable(node):
+            self._store_node_cache(node_hash, record)
+        self._memo[key] = record
+        return record
+
+    def _node_cacheable(self, node: StdObject) -> bool:
+        """节点是否参与持久化缓存：默认 true；模板可声明 ``_cache: bool = false`` 关闭。"""
+        for f in node.fields:
+            if f.name == CACHE_FIELD:
+                if isinstance(f.value, StdLiteral):
+                    return bool(f.value.value)
+                return True
+        return True
+
+    def _node_cache_dir(self) -> Path:
+        """持久化节点缓存目录（<工作区>/node_cache）。"""
+        p = self._vfs.root / 'node_cache'
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def _load_node_cache(self, node_hash: str) -> StdValue | None:
+        """按节点 hash 加载持久化物化结果（<node_hash>.json）；缺失/损坏 → None。
+
+        上游 3.x：emit 层 ``load_from_json`` 还原自描述标记（Decimal / path / noexist），
+        再经 ``python_to_std`` 回 StdValue —— 与 ``dump_to_json`` 无损闭环。
+        """
+        path = self._node_cache_dir() / f'{node_hash}.json'
+        if not path.exists():
+            return None
+        try:
+            return python_to_std(load_from_json(path.read_text(encoding='utf-8')))
+        except Exception:
+            return None  # 损坏缓存 → 重新执行
+
+    def _store_node_cache(self, node_hash: str, record: StdValue) -> None:
+        """持久化物化结果到 <node_hash>.json（失败不影响构建）。
+
+        上游 3.x：``dump_to_json`` 默认全语义保留（Decimal / path / noexist 标记编码），
+        与 ``load_from_json`` 无损闭环。
+        """
+        try:
+            path = self._node_cache_dir() / f'{node_hash}.json'
+            path.write_text(dump_to_json(record), encoding='utf-8')
+        except Exception:
+            pass  # 缓存写失败 → 本次不缓存，下次重算
+
+    def _call(self, fn: Any, args: dict[str, Any], node_hash: str) -> Any:
+        """签名扫描：``vfs`` 参数注入节点代理；其余按名直传（无 dataclass 注解注入）。
+
+        impl 参数即降维后的普通 Python 值（dict / list / 标量 / PurePosixPath）。
+        """
+        kwargs: dict[str, Any] = {}
+        for name in inspect.signature(fn).parameters:
+            if name == VFS_PARAM:
+                kwargs[name] = NodeVFS(self._vfs, node_hash)
+            elif name in args:
+                kwargs[name] = args[name]
+        return fn(**kwargs)
+
+
+def entry_value(result: CompilationResult) -> StdValue:
+    """取顶层入口字段（操作树根）。"""
+    root = result.document.root
+    for f in root.fields:
+        if f.name == ENTRY_FIELD:
+            if f.value is None:
+                raise BuildError(f'顶层字段 {ENTRY_FIELD!r} 无值')
+            return f.value
+    raise BuildError(f'顶层缺少入口字段 {ENTRY_FIELD!r}')

infinity_make/main.py

@@ -0,0 +1,151 @@
+"""infinity_make —— expr 模式构建系统 CLI：infmake.infd 是一棵操作树。
+
+本模块只做「编排」：argparse 解析 → 编译（infinity_data）→ 执行操作树 →
+输出物化 JSON。三层拆分：
+
+  - :mod:`infinity_make.executor`：操作树执行器
+    （子图 hash 去重 + VFS 注入 + 持久化节点缓存，见模块 docstring）
+  - :mod:`infinity_make.nixenv`：Nix 环境引导
+    （env.infd → ``nix develop`` 重入 / ``--run``）
+  - 本模块：CLI 薄壳 + 装配
+
+与 infd_builder 玩具版的差异（上游 infinity_data 3.x API）：
+  - 无模板 dataclass 生成（templates.py 类型契约）与自动 dataclass 注解扫描注入
+  - 物化输出经 ``infinity_data.emit.to_json`` 投影（path → 字符串）；
+    节点缓存经 ``dump_to_json`` / ``load_from_json`` 无损往返（见 executor）
+
+用法::
+
+    python -m infinity_make -i infmake.infd -o make_result.json
+"""
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from infinity_data import SandboxConfig, load
+from infinity_data.emit import to_json
+
+from infinity_make.executor import BuildError, Executor, entry_value
+from infinity_make.nixenv import ENV_FILE, bootstrap, clone_repos, load_spec, run_command
+from infinity_make.vfs import VFS
+
+DEFAULT_WORKSPACE = '.builder'
+"""默认 VFS 工作区目录（相对 infmake.infd 所在目录）。"""
+
+
+def _reentry_argv(input_path: Path, args: argparse.Namespace) -> list[str]:
+    """Nix 重入 argv：首项为 ``--input``（本 CLI 用选项参数而非位置参数）；
+    路径参数一律绝对化（nix develop 的 CWD = env.infd 所在目录，相对路径会
+    被二次解析而叠加目录，如 examples/yaml_test/examples/yaml_test/result.json）。
+    """
+    argv = ['--input', str(input_path)]
+    if args.output:
+        argv += ['--output', args.output]
+    if args.env:
+        argv += ['--env', args.env]
+    if args.workspace:
+        argv += ['--workspace', args.workspace]
+    if args.dev:
+        argv.append('--dev')
+    return argv
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog='infmake',
+        description='基于 infinity data 的 expr 模式构建系统（infmake.infd 是一棵操作树）',
+    )
+    parser.add_argument('-i', '--input', type=str, default='infmake.infd', help='构建配置')
+    parser.add_argument('-o', '--output', type=str, default='make_result.json', help='构建结果位置')
+    parser.add_argument('-e', '--env', type=str, default=None, help='Nix 环境声明文件（默认 <input> 同目录 env.infd）')
+    parser.add_argument(
+        '-w', '--workspace', type=str, default=None, help='VFS 工作区目录（默认 <input> 同目录 .builder）'
+    )
+    parser.add_argument('--dev', action='store_true', help='开发模式沙盒（full_access：!from / !file / !env 全开）')
+    parser.add_argument(
+        '--run', metavar='CMD', default=None, help='进入 env.infd 的 Nix 环境运行命令（不构建），如 --run "code ."'
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    """CLI：编译 → 执行操作树 → 输出物化结果。
+
+    ``--dev``：开发模式沙盒（``SandboxConfig.full_access()``，允许 ``!from``
+    模板导入 / ``!file`` / ``!env``，模板可位于项目外）；缺省零信任 ``deny_all()``。
+
+    Nix 环境引导：infmake.infd 同目录存在 ``env.infd`` 时，先以 safe_load 加载
+    （纯数据），生成 ``nix develop`` 环境并重入执行（``!env import`` 在环境内可用）。
+    """
+    args = _build_parser().parse_args(argv)
+
+    # 配置/输出/工作区路径先基于调用方 CWD 解析为绝对路径；
+    # 执行期相对路径（sources / output）以 infmake.infd 所在目录为基准
+    cwd = Path.cwd()
+    input_path = (cwd / args.input).resolve()
+    out_path = (cwd / args.output).resolve()
+    env_path = (cwd / args.env).resolve() if args.env else input_path.parent / ENV_FILE
+    workspace = (cwd / args.workspace).resolve() if args.workspace else None
+    # 规范化路径参数为绝对路径：Nix 环境重入后 CWD 变为 env.infd 所在目录，
+    # 相对路径会被二次解析而叠加目录（如 examples/yaml_test/examples/yaml_test/result.json）
+    args.output = str(out_path)
+    args.env = str(env_path)
+    args.workspace = str(workspace) if workspace else None
+
+    env_spec = load_spec(env_path)
+
+    # ── clone：按 env.infd 声明克隆项目到指定位置（锁 tag/commit，幂等）──
+    if env_spec is not None and env_spec.clone:
+        code = clone_repos(env_spec, env_path)
+        if code != 0:
+            return code
+
+    # ── --run：进入 env.infd 的 Nix 环境运行命令（不构建），如 --run "code ." ──
+    if args.run is not None:
+        if env_spec is None:
+            print('错误: --run 需要 env.infd（build 同目录或 --env 指定）', file=sys.stderr)
+            return 1
+        return run_command(env_spec, env_path, args.run)
+
+    # ── Nix 环境引导：env.infd（纯数据，safe_load）→ 生成 nix develop 环境 → 重入 ──
+    if env_spec is not None:
+        inner_args = _reentry_argv(input_path, args)
+        code = bootstrap(env_spec, env_path, inner_args)
+        if code is not None:
+            return code  # 重入子进程已完成（或跳过引导），其退出码即结果
+
+    sandbox = SandboxConfig.full_access() if args.dev else SandboxConfig.deny_all()
+
+    result = load(input_path, sandbox=sandbox)
+    if result.has_errors:
+        for d in result.diagnostics:
+            loc = d.location or '<root>'
+            print(f'  {d.severity.name:7s} {loc} [{d.code}] {d.message}', file=sys.stderr)
+        print('编译失败，见上方诊断', file=sys.stderr)
+        return 1
+
+    # 与 InfinityData 导入语义一致：相对路径以配置文件目录为基准
+    os.chdir(input_path.parent)
+    vfs = VFS(workspace if workspace is not None else input_path.parent / DEFAULT_WORKSPACE)
+    vfs.clean_tmp()  # 临时目录每次构建从干净区开始（缓存保留）
+    try:
+        value_std = Executor(vfs).execute(entry_value(result))
+    except BuildError as e:
+        print(f'构建失败: {e}', file=sys.stderr)
+        return 1
+    except Exception as e:  # impl 内的执行错误（如命令失败）清晰上报
+        print(f'构建失败: {type(e).__name__}: {e}', file=sys.stderr)
+        return 1
+
+    # 物化树是 StdValue 原生域，末端用 emit 层 to_json 投影为 JSON（有损：path → 字符串）
+    text = to_json(value_std)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text(text + '\n', encoding='utf-8')
+    print(f'✓ 构建成功，物化结果: {out_path}')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

infinity_make/nixenv.py

@@ -0,0 +1,395 @@
+"""Nix 环境引导：env.infd（纯数据）→ ``nix develop`` 环境 → 重入构建 / ``--run``。
+
+- :func:`load_spec`：加载 env.infd 并经 schema（schemas/env.inft 模板 EnvSpec）约束
+  —— 字段结构 / 类型 / 额外字段全部由上游 infinity_data 校验，不做手动检查
+- :func:`clone_repos`：按 env.infd 的 ``clone`` 声明克隆项目到指定位置（锁 tag/commit，幂等）
+- :func:`bootstrap`：未在生成环境内且存在 env.infd → ``nix develop`` 重入构建
+  （impure --expr 路径，或显式 ``flake = {...}`` 的 flake 模式）；已在环境内 → None
+- :func:`run_command`：进入 env.infd 的 Nix 环境运行命令（不构建，如 ``code .``）
+
+重入通过环境变量 :data:`ENV_MARKER`（= env.infd 指纹）防死循环：指纹匹配 = 已在生成环境内。
+指纹取**语法层**（``parse_source`` → ``Document.canonical()`` 的 sha256 前缀，与上游模板身份同方案）——
+注释/格式/字段顺序变化不改变指纹，只有字段值变化才改变。
+"""
+
+import hashlib
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, cast
+
+from infinity_data import SandboxConfig, Schema, load
+from infinity_data.frontend import parse_source
+from infinity_data.infra.file import DiskFile
+from infinity_data.infra.path import native_to_posix
+
+ENV_FILE = 'env.infd'
+"""Nix 环境声明文件（infmake.infd 同目录，纯数据，schema 约束加载）。"""
+
+ENV_MARKER = 'INFMAKE_NIX_ENV'
+"""已进入生成 Nix 环境的标记环境变量（值 = env.infd 指纹）。"""
+
+SCHEMA_TEMPLATE = 'EnvSpec'
+"""env.infd 顶层 schema 模板名（见 schemas/env.inft）。"""
+
+
+@dataclass
+class CloneSpec:
+    """env.infd 的 ``clone`` 声明：克隆一个 git 项目到指定位置，锁 tag 或 commit。"""
+
+    url: str
+    dest: Path
+    tag: str | None = None
+    commit: str | None = None
+
+
+@dataclass
+class EnvSpec:
+    """env.infd 解析结果：Nix 包 + 环境变量 + shell_hook + flake 控制 + clone 声明。"""
+
+    packages: list[str] = field(default_factory=list[str])
+    env: dict[str, str] = field(default_factory=dict[str, str])
+    shell_hook: str = ''
+    flake: dict[str, Any] | None = None  # flake = {...}：显式启用 flake 模式（inputs/system 配置）；缺省=impure --expr
+    clone: list[CloneSpec] = field(default_factory=list[CloneSpec])
+
+
+def _schema_path() -> Path:
+    """定位随包分发的 env schema 模板（<包>/schemas/env.inft，package-data）。"""
+    p = Path(__file__).resolve().parent / 'schemas' / 'env.inft'
+    if not p.exists():
+        raise FileNotFoundError(f'未找到 {p}（infinity_make 包内 schema）')
+    return p
+
+
+def load_spec(env_path: Path) -> EnvSpec | None:
+    """加载 env.infd 并经 schema（包内 schemas/env.inft 模板 EnvSpec）约束；文件不存在 → None。
+
+    字段结构 / 类型 / 额外字段 / 必填全部由上游校验（strict），失败打印诊断并退出；
+    这里只读回**已校验**的值并组装 EnvSpec（schema 不注入默认值，缺失键仍需回退）。
+    """
+    if not env_path.exists():
+        return None
+    schema_path = _schema_path()
+    result = load(
+        env_path,
+        # 沙盒白名单按语言内 POSIX 形式匹配：Windows 上原生路径（D:\...）须转 /d/...
+        sandbox=SandboxConfig(allow_templates=[native_to_posix(schema_path)]),
+        schema=Schema(template=SCHEMA_TEMPLATE, from_file=str(schema_path)),
+    )
+    if result.has_errors:
+        for d in result.diagnostics:
+            loc = d.location or '<root>'
+            print(f'  {d.severity.name:7s} {loc} [{d.code}] {d.message}', file=sys.stderr)
+        print('env.infd 加载失败，见上方诊断', file=sys.stderr)
+        raise SystemExit(1)
+    value = result.value
+    raw_env = value.get('env')
+    env: dict[str, str] = {}
+    if isinstance(raw_env, dict):
+        env = {str(k): str(v) for k, v in cast(dict[str, Any], raw_env).items()}
+    # flake 模式开关：显式 `flake = {...}`（inputs/system 配置）；缺省 / null = impure --expr
+    raw_clone = value.get('clone')
+    clones: list[CloneSpec] = []
+    if isinstance(raw_clone, list):
+        for item in cast(list[Any], raw_clone):
+            d = cast(dict[str, Any], item)
+            clones.append(
+                CloneSpec(
+                    url=str(d['url']),
+                    dest=Path(str(d['dest'])),
+                    tag=str(d['tag']) if 'tag' in d else None,
+                    commit=str(d['commit']) if 'commit' in d else None,
+                )
+            )
+    return EnvSpec(
+        packages=list(value['packages']) if 'packages' in value else [],
+        env=env,
+        shell_hook=str(value['shell_hook']) if 'shell_hook' in value else '',
+        flake=value.get('flake'),
+        clone=clones,
+    )
+
+
+def _nixpkgs_path() -> str:
+    """解析 <nixpkgs> 频道为 store 路径（纯模式嵌入，避免频道查找；失败返回空串）。"""
+    try:
+        out = subprocess.run(
+            ['nix-instantiate', '--find-file', 'nixpkgs'],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=120,
+        )
+        p = out.stdout.strip()
+        return p if p.startswith('/nix/store/') else ''
+    except (OSError, subprocess.SubprocessError):
+        return ''
+
+
+def _nix_expr(spec: EnvSpec, nixpkgs_path: str = '') -> str:
+    """env.infd → ``nix develop --expr`` 表达式（impure 路径）。
+
+    env 值里的 ``${attr}/path`` 展开为 nix 字符串插值 ``"${pkgs.attr}/path"``。
+    """
+    src = nixpkgs_path if nixpkgs_path else '<nixpkgs>'
+    return (
+        f'{{ pkgs ? import {src} {{ }} }}:\n'
+        'pkgs.mkShell {\n'
+        f'  packages = with pkgs; [ {" ".join(f"pkgs.{p}" for p in spec.packages)} ];\n'
+        f'  {_env_lines(spec)}\n'
+        '}\n'
+    )
+
+
+def _env_lines(spec: EnvSpec) -> str:
+    """env 声明 → nix mkShell 属性（${attr} → ${pkgs.attr} 插值）。"""
+    return '\n  '.join(f'{k} = "{v.replace("${", "${pkgs.")}";' for k, v in spec.env.items())
+
+
+def _nix_system() -> str:
+    """当前 Nix 系统（如 x86_64-linux）。"""
+    try:
+        out = subprocess.run(
+            ['nix', 'eval', '--impure', '--raw', 'builtins.currentSystem'],
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=60,
+        )
+        return out.stdout.strip() or 'x86_64-linux'
+    except (OSError, subprocess.SubprocessError):
+        return 'x86_64-linux'
+
+
+def _flake_content(spec: EnvSpec, system: str, nixpkgs_path: str) -> str:
+    """flake 模式：nixpkgs 作输入（默认 path: 本机源，可经 flake.inputs 配置为
+    github:/git+ URL → flake.lock 记录 rev，commit 级锁定），输出 devShell。
+
+    env.infd 示例:
+        flake = { inputs = { nixpkgs = "github:nixos/nixpkgs/nixos-unstable" } }
+    缺省 nixpkgs 输入 → path:（内容级锁定，离线可用）。
+    """
+    cfg = spec.flake or {}
+    inputs: dict[str, str] = {}
+    raw_inputs = cfg.get('inputs')
+    if isinstance(raw_inputs, dict):
+        inputs = {str(k): str(v) for k, v in cast(dict[str, Any], raw_inputs).items()}
+    if 'nixpkgs' not in inputs:
+        inputs['nixpkgs'] = f'path:{nixpkgs_path}'
+    system = str(cfg.get('system') or system)
+    # nix 缩进字符串 ''...'' 里 ${ 是插值起始 → 转义为 ''${（bash 的 ${} 原样保留）
+    hook = spec.shell_hook.replace('${', "''${")
+    inputs_nix = ''.join(f'  inputs.{name}.url = "{url}";\n' for name, url in inputs.items())
+    return (
+        '{\n'
+        f'{inputs_nix}'
+        # ... 通配：允许 flake.inputs 里额外的自定义输入（非 nixpkgs）
+        f'  outputs = {{ self, nixpkgs, ... }}: let pkgs = nixpkgs.legacyPackages.{system}; in {{\n'
+        f'    devShells.{system}.default = pkgs.mkShell {{\n'
+        f'      packages = with pkgs; [ {" ".join(f"pkgs.{p}" for p in spec.packages)} ];\n'
+        f'      {_env_lines(spec)}\n'
+        f"      shellHook = ''\n{hook}\n      '';\n"
+        '    };\n'
+        '  };\n'
+        '}\n'
+    )
+
+
+def _use_flake(spec: EnvSpec) -> bool:
+    """flake 模式判定：显式 ``flake = {...}`` 即启用；缺省走 impure --expr。"""
+    return spec.flake is not None
+
+
+def _nix_develop_cmd(spec: EnvSpec, env_path: Path) -> tuple[list[str], bool]:
+    """构建 ``nix develop`` 命令：flake 模式 → 项目目录临时 flake；否则 --impure + --expr。
+
+    Returns:
+        (nix_cmd, flake_on)
+    """
+    if not _use_flake(spec):
+        return (['nix', 'develop', '--impure', '--expr', _nix_expr(spec)], False)
+    # 显式配置了 nixpkgs 输入（如 github: URL）→ 无需本机路径解析（锁 commit）
+    cfg_inputs = (spec.flake or {}).get('inputs')
+    has_explicit_nixpkgs = isinstance(cfg_inputs, dict) and 'nixpkgs' in cfg_inputs
+    nixpkgs_path = ''
+    if not has_explicit_nixpkgs:
+        nixpkgs_path = _nixpkgs_path()
+        if not nixpkgs_path:
+            print('警告: nixpkgs 路径解析失败，flake 模式回退 impure', file=sys.stderr)
+            return (['nix', 'develop', '--impure', '--expr', _nix_expr(spec)], False)
+    proj = env_path.parent
+    # 自动检测 git 仓库；非仓库则自动 git init（flake 模式要求）
+    in_git = (
+        subprocess.run(
+            ['git', '-C', str(proj), 'rev-parse', '--is-inside-work-tree'],
+            capture_output=True,
+            text=True,
+            check=False,
+        ).returncode
+        == 0
+    )
+    if not in_git:
+        print(f'[env] {proj} 非 git 仓库，自动 git init（flake 模式要求）...')
+        subprocess.run(['git', '-C', str(proj), 'init', '-q'], check=False)
+    # flake.nix 直接生成在 env.infd 同目录（可见可审计）；git add 即可（无需 commit）
+    flake_path = proj / 'flake.nix'
+    flake_path.write_text(_flake_content(spec, _nix_system(), nixpkgs_path))
+    # -f：项目目录可能在 .gitignore 内，仍需 stage 供 nix 识别
+    subprocess.run(['git', '-C', str(proj), 'add', '-f', 'flake.nix'], check=False)
+    return (['nix', 'develop', str(proj)], True)
+
+
+def _env_fingerprint(env_path: Path) -> str:
+    """env.infd → 语法层指纹：``sha256(Document.canonical())`` 前缀（与上游模板身份同方案）。
+
+    canonical 是**标准 infd 源码**（无注释/空白，字段有序）——注释/格式/字段顺序
+    变化不改变指纹，只有字段值变化才改变 → 重入标记对格式无关，避免格式化
+    env.infd 后误判「环境已变」而反复重建。
+
+    解析失败（语法错误）→ 回退字节级 hash（load_spec 已在上游校验并退出，此处仅兜底）。
+    """
+    try:
+        doc, collector = parse_source(DiskFile.from_fullpath(env_path))
+        if not collector.has_errors:
+            return hashlib.sha256(doc.canonical().encode('utf-8')).hexdigest()[:16]
+    except OSError:
+        pass
+    return hashlib.sha256(env_path.read_bytes()).hexdigest()[:16]
+
+
+def _env_reentry(spec: EnvSpec, env_path: Path, inner: list[str]) -> int:
+    """进入 Nix 环境（重入）运行 inner 命令，返回其退出码（CWD = env.infd 目录）。"""
+    fingerprint = _env_fingerprint(env_path)
+    nix_cmd, flake_on = _nix_develop_cmd(spec, env_path)
+    cmd = [*nix_cmd, '--command', 'env', f'{ENV_MARKER}={fingerprint}', *inner]
+    print(f'[env] 进入 Nix 环境（env.infd 指纹 {fingerprint}，flake 模式={"on" if flake_on else "off"}）...')
+    return subprocess.run(cmd, cwd=str(env_path.parent)).returncode
+
+
+def bootstrap(spec: EnvSpec, env_path: Path, inner_args: list[str]) -> int | None:
+    """若未在生成环境内且 env.infd 存在 → ``nix develop`` 重入构建。
+
+    Args:
+        inner_args: 重入时执行的 argv（首项为绝对 build 路径，其余为绝对化后的 CLI 参数）
+
+    Returns:
+        重入子进程的退出码；None = 无需引导（已在环境内 / 无 nix）。
+    """
+    fingerprint = _env_fingerprint(env_path)
+    if os.environ.get(ENV_MARKER) == fingerprint:
+        return None  # 已在生成环境内
+    if shutil.which('nix') is None:
+        print('警告: 未找到 nix，跳过环境引导（可复现性下降）', file=sys.stderr)
+        return None
+    if spec.shell_hook:
+        # shell_hook：进入环境后、构建前执行的 bash（含 hook + exec 构建）
+        python_cmd = shlex.join([sys.executable, '-m', 'infinity_make', *inner_args])
+        reentry = ['bash', '-c', f'{spec.shell_hook}\nexec {python_cmd}']
+    else:
+        reentry = [sys.executable, '-m', 'infinity_make', *inner_args]
+    return _env_reentry(spec, env_path, reentry)
+
+
+def run_command(spec: EnvSpec, env_path: Path, command: str) -> int:
+    """``--run``：进入 env.infd 定义的 Nix 环境运行命令（不构建）。
+
+    - 已在环境内 / 无 nix → 直接运行（shell_hook 后接 command）
+    - 否则 → ``nix develop`` 重入运行（CWD = env.infd 目录，如 ``code .``）
+    """
+    fingerprint = _env_fingerprint(env_path)
+    body = f'{spec.shell_hook}\n{command}' if spec.shell_hook else command
+    inner = ['bash', '-c', body]
+    if os.environ.get(ENV_MARKER) == fingerprint:
+        return subprocess.run(inner, cwd=str(env_path.parent)).returncode
+    if shutil.which('nix') is None:
+        print('警告: 未找到 nix，跳过环境引导（可复现性下降）', file=sys.stderr)
+        return subprocess.run(inner, cwd=str(env_path.parent)).returncode
+    return _env_reentry(spec, env_path, inner)
+
+
+# ── clone：克隆项目到指定位置（锁 tag/commit） ─────────────────────────────
+
+
+def _git(dest: Path, *args: str, check: bool = False) -> subprocess.CompletedProcess[str]:
+    """在指定 git 仓库执行命令（``git -C dest ...``），捕获输出。"""
+    return subprocess.run(
+        ['git', '-C', str(dest), *args],
+        capture_output=True,
+        text=True,
+        check=check,
+    )
+
+
+def _clone_one(cs: CloneSpec, base: Path) -> int:
+    """克隆单个项目并锁定 tag/commit（幂等，HEAD 校验保证可复现）。
+
+    - 目标不存在 → ``git clone`` 到目标目录
+    - 目标已存在且是 git 仓库 → 远端收敛到声明 URL 并 ``fetch``（URL 变更也能收敛）
+    - 目标已存在但不是 git 仓库 → 报错（不覆盖已有目录）
+    - 锁 commit 时额外显式拉取该提交（非分支/标签顶端也能检出）
+    - 最后 ``checkout --detach`` 锁定引用，并校验 ``HEAD == <lock>^{commit}``
+
+    Returns:
+        0 = 成功；1 = 失败（已打印诊断）
+    """
+    dest = (base / cs.dest).resolve()
+    lock = cs.commit or cs.tag
+    if lock is None:
+        print(f'[clone] 错误: {cs.url} 未声明 tag 或 commit', file=sys.stderr)
+        return 1
+    try:
+        if dest.exists():
+            if not (dest / '.git').is_dir():
+                print(f'[clone] 错误: 目标 {dest} 已存在但不是 git 仓库（不覆盖）', file=sys.stderr)
+                return 1
+            # 已克隆：远端收敛到声明 URL 后拉取（幂等）
+            _git(dest, 'remote', 'set-url', 'origin', cs.url)
+            r = _git(dest, 'fetch', '--tags', 'origin')
+        else:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            r = subprocess.run(['git', 'clone', cs.url, str(dest)], capture_output=True, text=True)
+        if r.returncode != 0:
+            detail = (r.stderr or r.stdout).strip()
+            print(f'[clone] 克隆/拉取失败 {cs.url} → {dest}: {detail}', file=sys.stderr)
+            return 1
+        if cs.commit:
+            # 锁 commit：常规 fetch 未覆盖（非分支/标签顶端）时显式拉取该提交
+            _git(dest, 'fetch', 'origin', cs.commit)
+        r = _git(dest, 'checkout', '--detach', lock)
+        if r.returncode != 0:
+            print(f'[clone] 检出锁定 {lock} 失败 {cs.url}: {(r.stderr or r.stdout).strip()}', file=sys.stderr)
+            return 1
+        head = _git(dest, 'rev-parse', 'HEAD').stdout.strip()
+        resolved = _git(dest, 'rev-parse', f'{lock}^{{commit}}').stdout.strip()
+        if head != resolved:
+            print(f'[clone] 锁校验失败 {cs.url}: HEAD={head}，锁定 {lock}={resolved}', file=sys.stderr)
+            return 1
+        print(f'[clone] ✓ {cs.dest.as_posix()} ← {cs.url} @ {lock}（{head[:12]}）')
+        return 0
+    except (OSError, subprocess.SubprocessError) as e:
+        print(f'[clone] 执行失败 {cs.url}: {e}', file=sys.stderr)
+        return 1
+
+
+def clone_repos(spec: EnvSpec, env_path: Path) -> int:
+    """按 env.infd 的 ``clone`` 声明克隆项目（锁 tag/commit，幂等）。
+
+    目标目录相对 env.infd 所在目录解析；每个声明逐个克隆，任一失败 → 返回 1
+    （其余继续，便于一次性修完所有问题）。无 clone 声明 → 0。
+    """
+    if not spec.clone:
+        return 0
+    if shutil.which('git') is None:
+        print('错误: 未找到 git，无法执行 env.infd 的 clone 声明', file=sys.stderr)
+        return 1
+    base = env_path.parent
+    ok = True
+    for cs in spec.clone:
+        if _clone_one(cs, base) != 0:
+            ok = False
+    return 0 if ok else 1

infinity_make/schemas/env.inft

@@ -0,0 +1,28 @@
+# ═══════════════════════════════════════════════════════════════════════════
+# env.inft —— env.infd 顶层 schema 模板（EnvSpec）
+#
+# nixenv.load_spec 用它经上游 infinity_data schema 机制校验 env.infd：
+#   - 字段结构 / 类型 / 额外字段 / 必填全部由上游校验（本文件是唯一事实来源），
+#     不再在 nixenv 里手动 isinstance 检查
+#   - packages:   Nix 包列表（每项 str）
+#   - env:        环境变量 dict
+#   - shell_hook: 进入环境后、构建前执行的 bash
+#   - flake:      可选；显式 ``flake = {...}`` 启用 flake 模式（inputs/system 配置），
+#                 缺省 / null = impure ``nix develop --expr``
+#   - clone:      可选；git 项目克隆声明（每项锁 tag 或 commit，二选一）
+# ═══════════════════════════════════════════════════════════════════════════
+~CloneSpec {
+    url: str
+    dest: path
+    tag: str? = noexist
+    commit: str? = noexist
+    : <one(has(tag), has(commit))>,
+}
+
+~EnvSpec {
+    packages: <list, each(str)> = []
+    env: dict = {}
+    shell_hook: str = ""
+    flake: dict? = null
+    clone: <list, each(CloneSpec)> = []
+}

infinity_make/vfs/__init__.py

@@ -0,0 +1,3 @@
+from .vfs import VFS, NodeVFS
+
+__all__ = ['NodeVFS', 'VFS']

infinity_make/vfs/vfs.py

@@ -0,0 +1,78 @@
+"""构建工作区 VFS：分配临时目录 + 按 key 持久缓存。
+
+impl 函数签名里声明 ``vfs`` 参数即可获得注入（执行器用 ``inspect.signature`` 扫描）。
+注入的是 :class:`NodeVFS` —— 节点作用域代理，缓存自动以**当前节点 hash 指纹**为 key::
+
+    def impl(tag, vfs):
+        tmp = vfs.tmp("stage")          # 一次性临时目录（每次调用新建）
+        cache = vfs.cache("repo")       # → cache/<节点hash>/repo（免自定义 key，跨运行复用）
+        shared = vfs.global_.cache("pcm")  # → cache/pcm（全局共享，显式 key）
+        return {"tmp_dir": str(tmp), "cache_dir": str(cache)}
+
+- ``tmp``：脏副作用 / 暂存用的临时目录，每次调用分配新目录，避免互相污染
+- ``cache(name)``：**节点级**持久缓存，key = 当前节点 hash（模板 + 实现 + 输入指纹）
+- ``global_``：全局 VFS（需要跨节点共享时用，如所有模块共用的 pcm 目录）
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+
+class VFS:
+    """构建工作区 VFS。根目录结构：``<root>/tmp``（临时）与 ``<root>/cache``（缓存）。"""
+
+    def __init__(self, root: Path) -> None:
+        self._root = Path(root)
+        self._tmp_root = self._root / 'tmp'
+        self._cache_root = self._root / 'cache'
+        self._counter = 0
+
+    @property
+    def root(self) -> Path:
+        """VFS 根目录（工作区）。"""
+        return self._root
+
+    def tmp(self, name: str) -> Path:
+        """分配一次性临时目录（每次调用新建，永不复用）。"""
+        self._counter += 1
+        p = self._tmp_root / f'{self._counter:04d}-{name}'
+        p.mkdir(parents=True, exist_ok=False)
+        return p
+
+    def cache(self, key: str, name: str = 'artifact') -> Path:
+        """按 key 持久缓存目录：key 相同 → 返回同一目录（幂等复用）。"""
+        p = self._cache_root / key / name
+        p.mkdir(parents=True, exist_ok=True)
+        return p
+
+    def clean_tmp(self) -> None:
+        """清空临时目录（保留缓存）。"""
+        if self._tmp_root.exists():
+            shutil.rmtree(self._tmp_root)
+
+
+class NodeVFS:
+    """节点作用域 VFS 代理：缓存自动以当前节点 hash 指纹为 key。
+
+    执行器把 :class:`VFS` 包一层注入 ``vfs`` 参数 —— impl 无需自定义缓存 key：
+    相同（模板 + 实现 + 输入）的节点 = 相同 hash = 相同缓存目录（跨运行复用）。
+    """
+
+    def __init__(self, base: VFS, node_hash: str) -> None:
+        self._base = base
+        self.node_hash = node_hash
+
+    @property
+    def global_(self) -> VFS:
+        """全局 VFS（共享缓存 / 临时目录的逃生口）。"""
+        return self._base
+
+    def cache(self, name: str = 'artifact') -> Path:
+        """节点级持久缓存：``<cache>/<节点hash>/<name>``，免自定义 key。"""
+        return self._base.cache(f'{self.node_hash}/{name}')
+
+    def tmp(self, name: str) -> Path:
+        """一次性临时目录（全局，每次构建从干净区开始）。"""
+        return self._base.tmp(name)

infinity_make-1.0.0.dist-info/METADATA

@@ -0,0 +1,272 @@
+Metadata-Version: 2.4
+Name: infinity_make
+Version: 1.0.0
+Summary: 基于 InfinityData 的自定义构建系统
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: infinity_data[tool]>=3.2.0
+
+# infinity_make
+
+基于 [InfinityData](https://github.com/yinbailiang/infinity_data)（`.infd` 声明式配置语言）的自定义构建系统。
+
+`infmake.infd` 是一棵**操作树**：每个节点是一个带内嵌 Python 实现的模板实例。编译 `.infd` → 执行操作树 → 输出物化 JSON 产物，全程带子图去重、VFS 注入与持久化节点缓存。
+
+```bash
+uv run infmake -i infmake.infd --dev -o make_result.json
+```
+
+## 特性
+
+- **操作树构建**：`.infd` 声明构建流程，节点 = 模板 + 数据字段 + 内嵌 `impl`（Python）
+- **子图 hash 去重**：相同（模板 + 实现 + 物化输入）的子图只求值一次，结果复用
+- **持久化节点缓存**：节点物化结果按 hash 落盘（`<workspace>/node_cache/<hash>.json`），跨运行复用
+- **VFS 注入**：`impl` 签名声明 `vfs` 参数即注入构建工作区（临时目录 + 按 key 缓存）
+- **Nix 环境引导**：`env.infd` → 自动 `nix develop` 重入构建（flake / impure 两种模式）
+- **沙盒安全**：默认零信任 `deny_all()`；`--dev` 开发模式 `full_access()`（`!from` / `!file` / `!env` 全开）
+- **可审计产物**：输出为自包含的物化 JSON 树
+
+## 安装
+
+需要 Python ≥ 3.14。
+
+```bash
+# 作为项目依赖（uv 本地路径 / 已发布包）
+uv add --editable /path/to/infinity_make
+
+# 或直接在本仓库安装
+uv sync
+uv run infmake --help
+```
+
+安装后提供 `infmake` 命令（`python -m infinity_make` 亦可）。
+
+## 快速开始
+
+一个最小示例，三件套：模板文件 → 构建配置 → 运行。
+
+**1. 模板** `templates/hello.inft`（`.inft` = 仅模板定义的源文件）：
+
+```infd
+~Hello {
+    name: str = "world"
+
+    _gen: dict = {
+        message: str = ""
+    }
+    _impl: str = ```python
+def impl(name: str) -> dict[str, str]:
+    return {"message": f"hello, {name}!"}
+    ```
+}
+```
+
+- `_gen`：声明 `impl` 产出的字段（元数据，不进物化记录）
+- `_impl`：内嵌 Python 源码（三重反引号多行字符串），约定定义名为 `impl` 的函数
+- `impl` 收到的参数是**降维后的普通 Python 值**（`str` / `int` / `list` / `dict` / `PurePosixPath`），返回的 `dict` 合并回节点记录
+
+**2. 构建配置** `infmake.infd`：
+
+```infd
+!from p"templates/hello.inft" import Hello
+
+!var Hello(name = "world") import . as hello
+
+target = $hello
+```
+
+- `!from ... import`：导入模板
+- `!var ... import . as ...`：定义变量（节点实例）
+- `target`：顶层入口字段，即操作树根
+
+**3. 运行**：
+
+```bash
+uv run infmake -i infmake.infd --dev -o make_result.json
+```
+
+产物 `make_result.json`：
+
+```json
+{
+  "name": "world",
+  "message": "hello, world!"
+}
+```
+
+> 使用了 `!from` / `!file` / `!env` 的配置必须加 `--dev`（默认沙盒为零信任 `deny_all()`，禁止导入）。
+
+## 命令行
+
+```
+usage: infmake [-h] [-i INPUT] [-o OUTPUT] [-e ENV] [-w WORKSPACE] [--dev] [--run CMD]
+
+options:
+  -h, --help            显示帮助
+  -i, --input INPUT     构建配置（默认 infmake.infd）
+  -o, --output OUTPUT   构建结果位置（默认 make_result.json）
+  -e, --env ENV         Nix 环境声明文件（默认 <input> 同目录 env.infd）
+  -w, --workspace WORKSPACE
+                        VFS 工作区目录（默认 <input> 同目录 .builder）
+  --dev                 开发模式沙盒（full_access：!from / !file / !env 全开）
+  --run CMD             进入 env.infd 的 Nix 环境运行命令（不构建），如 --run "code ."
+```
+
+执行流程：加载 `env.infd`（存在则引导 Nix 环境重入）→ 编译 `infmake.infd` → 执行操作树 → 输出物化 JSON。
+
+## Nix 环境（env.infd）
+
+`infmake.infd` 同目录放置 `env.infd`（纯数据，经包内 `schemas/env.inft` 的 `EnvSpec` 模板严格校验）后，构建会自动 `nix develop` 重入，环境内 `!env import` 可用：
+
+```infd
+packages = [
+    "clang",
+    "cmake",
+    "ninja",
+]
+
+env = {
+    CMAKE_PREFIX_PATH = "${cmake}",
+}
+
+shell_hook = ```bash
+export NIX_HARDENING_ENABLE="pic relro"
+```
+
+flake = {
+    inputs = { nixpkgs = "github:nixos/nixpkgs/nixos-26.05" }
+}
+
+clone = [
+    {
+        url = "https://github.com/foo/bar.git"
+        dest = p"deps/bar"
+        tag = "v1.2.3"
+    }
+    {
+        url = "git@github.com:foo/baz.git"
+        dest = p"src/baz"
+        commit = "3f2a1c9d8b7e"
+    }
+]
+```
+
+- `packages`：Nix 包列表
+- `env`：环境变量，`${attr}` 自动展开为 nix 字符串插值 `${pkgs.attr}`
+- `shell_hook`：进入环境后、构建前执行的 bash（再 `exec` 构建）
+- `flake = {...}`：显式启用 **flake 模式**（自动生成 `flake.nix` + `flake.lock`，commit 级锁定 nixpkgs）；缺省 = impure `nix develop --expr`
+- `clone`：可选；**git 项目克隆声明**，在构建/进入环境前把项目克隆到指定位置（相对 `env.infd` 所在目录）。每项必须**锁 tag 或 commit（二选一）**，克隆后校验 `HEAD == 锁定提交` 保证可复现：
+  - `url`：git 仓库地址（必填）
+  - `dest`：目标目录（`p"..."` 路径字面量）
+  - `tag`：锁定 tag
+  - `commit`：锁定 commit（非分支/标签顶端的提交也会显式拉取）
+  - 幂等：目标已存在且是 git 仓库时收敛远端并拉取、检出锁定；已存在但非 git 仓库则报错不覆盖
+
+重入通过环境变量 `INFMAKE_NIX_ENV`（= env.infd 语法层指纹）防死循环；`env.infd` 内容变化才触发重建。
+
+`--run` 可只进入该环境运行命令而不构建：
+
+```bash
+uv run infmake --run "code ."        # 在 Nix 环境里打开 VS Code
+uv run infmake --run "bash gen_pkgconfig.sh"
+```
+
+## 进阶用法
+
+### 模板与实现外置
+
+实现代码可外置到 `.py` 文件，用 `!file ... as raw` 导入为字符串（模板内再引用）：
+
+```infd
+# core.inft
+!file p"impl/compile.py" as raw import . as CompileImpl
+
+~Compile {
+    compiler: Compiler
+    source: File
+    flags: <list, each(str)> = []
+    _gen: dict = {
+        object: str = "",
+        compile_command: object = {},
+    }
+    _impl: str = $CompileImpl
+}
+```
+
+```python
+# impl/compile.py
+def impl(compiler: dict, source: dict, flags: list[str], vfs) -> dict:
+    ...
+    return {"object": obj, "compile_command": cmd}
+```
+
+### 内容快照节点（~File）
+
+`path` 类型的字段（`p"src"`）由 `impl` 收到 `PurePosixPath`；若要**文件内容**参与节点 hash（内容变化 → 下游缓存自动失效），用 `~File` 节点对文件/目录算内容指纹，下游 `$file` 引用它即可（指纹自动传播进下游节点 key）：
+
+```infd
+~File {
+    path: path
+    ignore: <list, each(str)> = []
+    mtime: bool = false        # mtime 快照加速
+    _cache: bool = false       # 内容检测节点：每次执行重读
+    _gen: dict = {
+        path: str = "",
+        hash: str = "",
+        entries: int = 0,
+        exists: bool = false,
+    }
+    _impl: str = ```python
+def impl(path: str, ignore: list[str], mtime: bool, vfs) -> dict:
+    ...   # 递归内容指纹（sha256）
+    ```
+}
+```
+
+### VFS 注入
+
+`impl` 签名含 `vfs` 参数即注入节点作用域代理（缓存自动以当前节点 hash 为 key）：
+
+```python
+def impl(tag, vfs):
+    tmp = vfs.tmp("stage")            # 一次性临时目录（每次调用新建）
+    cache = vfs.cache("repo")         # → cache/<节点hash>/repo（跨运行复用）
+    shared = vfs.global_.cache("pcm") # → cache/pcm（全局共享）
+    return {"tmp_dir": str(tmp), "cache_dir": str(cache)}
+```
+
+### 节点缓存
+
+- 默认开启：节点物化结果经 `dump_to_json` / `load_from_json` 无损往返落盘 `<workspace>/node_cache/<hash>.json`（`Decimal` / `path` / `noexist` 以自描述标记编码）
+- 模板声明 `_cache: bool = false` 关闭（如 `~File` 内容检测）
+
+## 项目结构
+
+```
+src/infinity_make/
+  __init__.py      公共 API（Executor / BuildError / main）
+  __main__.py      python -m infinity_make 入口
+  main.py          CLI 薄壳：argparse → 编译 → 执行 → 输出 JSON
+  executor.py      操作树执行器（子图 hash 去重 + VFS 注入 + 节点缓存）
+  nixenv.py        Nix 环境引导（env.infd → nix develop 重入 / --run）
+  vfs/             构建工作区 VFS（tmp + cache + node_cache）
+  schemas/env.inft env.infd 的 EnvSpec schema（包内分发）
+```
+
+工作区（默认 `<input> 同目录 .builder/`）：
+
+```
+.builder/
+  tmp/         一次性临时目录（每次构建从干净区开始，缓存保留）
+  cache/       VFS 缓存（<key>/<name>，跨运行复用）
+  node_cache/  节点物化缓存（<hash>.json）
+```
+
+## 开发
+
+```bash
+uv sync --group dev        # ruff / pyright / pre-commit / pytest
+uv run ruff check .
+uv run pyright
+uv run pytest
+```

infinity_make-1.0.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+infinity_make/__init__.py,sha256=gxlRbdpfoydN1Ikzf5XiglGsnM0URJjy3hZcv_FbRsQ,682
+infinity_make/__main__.py,sha256=RfS_NdBDqjr_i0Gzssy5RwEgvG3yj1kAQY8pl6dxGrA,173
+infinity_make/executor.py,sha256=_hffSmvA7YrKO1uMasRlubgUsDmtm1diETB2H-b-NMQ,12042
+infinity_make/main.py,sha256=NndMD4hGU4rECdZlxetvyEKUhEvc2Jb8XkcPV1U1Kkg,6868
+infinity_make/nixenv.py,sha256=cis5BYDoIuFimJQ64F_57B17FktAadSd0EwUVnKaWoY,17408
+infinity_make/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+infinity_make/schemas/env.inft,sha256=zTa2uQ9tSnCUS7eSyeu_bFIq1nkw2Xlh71a-inzMyOk,1453
+infinity_make/vfs/__init__.py,sha256=4G4CL7HDuDjuPMf4loMBCICJeHSDC704NLy4wZFd-Mo,60
+infinity_make/vfs/vfs.py,sha256=dslo5S3pQNxdmG_rSbTxl2CPyB5VA5-y6N_b2Zs_JN0,3152
+infinity_make-1.0.0.dist-info/METADATA,sha256=D_NY-_y83JBYtvQd9CJGHJpAuL-PIh8o0PHCcROvi3g,8990
+infinity_make-1.0.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+infinity_make-1.0.0.dist-info/entry_points.txt,sha256=_0x9OG4yRjt8cdvncFjDePEUWIs7BnNV9iM5Z6FFMog,52
+infinity_make-1.0.0.dist-info/top_level.txt,sha256=ERrn1vIXEBisoXzvsuGG70S_J45PIlYA78KoHYe2R44,14
+infinity_make-1.0.0.dist-info/RECORD,,

infinity_make-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

infinity_make-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+infmake = infinity_make.main:main

infinity_make-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+infinity_make