Feat/log

.github/instructions/ziginit.instructions.md

@@ -14,6 +14,8 @@ applyTo: "tools/ziginit/**/*.zig"
 ## 错误处理
 
 - **系统调用返回值必须检查**，不得在业务模块中用 `_ =` 静默丢弃
+- **CLI 命令失败必须 `exit(1)`**：`sendCommand` 返回 `null`（连接失败）或 `result.isOk() == false` 时，CLI 必须展示 `result.msgSlice()` 错误消息并 `std.process.exit(1)`——脚本和 CI 依赖退出码判断成功/失败
+- **IPC 响应必须携带错误原因**：`handleCommand` 返回 `CommandResult`，失败路径使用 `R.fail(code, fmt, args)` 附带可读错误消息，客户端直接展示给用户。响应线格式：`[2B status LE][2B msg_len LE][msg]`
 - 所有"关闭/释放/best-effort"类操作已封装在 `posix.zig` 的深封装函数中（如 `closeFd`、`unlinkFile`、`writeOnce`、`syncFd`、`reapChildren` 等），业务模块直接调用即可，无需 `_ =`
 - 需要新增 `_ =` 的场景应优先在 `posix.zig` 中封装为语义明确的函数
 - 子进程（fork 后 child）中的关键操作（`setsid`、`dup2`、`chdir`、`open` pid 文件）失败时，必须写 stderr 错误信息（会进入 journal pipe）然后 `_exit(126)`
@@ -72,3 +74,15 @@ applyTo: "tools/ziginit/**/*.zig"
   5. 确认无孤儿进程、无残留 socket/lock 文件
 - **改名/重构类任务**：必须全局搜索旧名称（`grep -r "旧名"`），确认注释、日志、错误提示、argv 显示全部替换完毕
 - **信号处理类变更**：手动发送 SIGINT/SIGTERM/SIGKILL 验证，不能只依赖 `quit` 命令的测试路径
+
+## 安全与防御性编程
+
+- **用户输入必须校验后再使用**：CLI 参数、IPC 消息中的服务名等外部输入，必须先通过 `cfg.findService()` 或长度校验，才能传入 `buildServicePaths` 等内部函数。禁止将未校验的输入直接用于 `@memcpy` 到固定大小缓冲区
+- **固定缓冲区写入前必须做边界检查**：`@memcpy` 到 `[MAX_PATH]u8` 等固定数组前，计算 `total` 并断言 `total < capacity`。路径拼接溢出属于不可恢复的配置/系统错误，应 `@panic` 而非静默截断——静默截断会导致多个路径指向同一文件，引发更隐蔽的故障
+- **禁止静默丢弃数据**：缓冲区满时必须有明确的降级策略（flush 后重试、报错退出、或截断警告），不能 `@min(data.len, avail)` 后默默丢弃超出部分
+- **自引用结构体禁用裸指针**：结构体中不得保存指向外部栈变量的指针（如 `path: [*:0]const u8`），应使用自持缓冲区（如 `path_buf: [MAX_PATH+1]u8`）并用 `@memcpy` 拷贝数据，避免生命周期不匹配导致悬空指针
+
+## 资源与流式数据
+
+- **轮询循环中避免重复获取/释放资源**：follow 模式等 poll 循环中，如果文件使用 truncate 轮转（而非 rename），FD 应在循环外打开、循环结束后统一关闭，循环内仅用 `fstat` 检查大小变化。文件可能延迟创建时，用 `-1` 标记并每轮重试 open
+- **跨 chunk 数据拼接**：流式读取场景（follow 模式、pipe drain）中，`read()` 返回的 chunk 不保证在行边界切分。必须维护 carry buffer，仅在遇到 `\n` 时输出完整行，残留数据保留到下次 read 后拼接

.github/workflows/release-ziginit.yml

@@ -0,0 +1,112 @@
+name: Release ziginit
+
+on:
+    push:
+        tags:
+            - "ziginit/v*"
+
+permissions:
+    contents: write
+
+jobs:
+    release:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  fetch-depth: 0
+
+            - name: Install Zig
+              uses: mlugg/setup-zig@v2
+              with:
+                  version: 0.16.0
+
+            - name: Cache Zig build artifacts
+              uses: actions/cache@v4
+              with:
+                  path: |
+                      ~/.cache/zig
+                      tools/ziginit/.zig-cache
+                  key: ziginit-${{ runner.os }}-zig-${{ hashFiles('tools/ziginit/main.zig', 'tools/ziginit/build.zig') }}
+                  restore-keys: |
+                      ziginit-${{ runner.os }}-zig-
+
+            - name: Parse version and channel from tag
+              id: version
+              run: |
+                  version="${GITHUB_REF#refs/tags/ziginit/}"
+                  echo "version=${version}" >> "$GITHUB_OUTPUT"
+                  if [[ "$version" =~ -alpha ]]; then
+                    echo "channel=dev" >> "$GITHUB_OUTPUT"
+                  elif [[ "$version" =~ -beta ]]; then
+                    echo "channel=beta" >> "$GITHUB_OUTPUT"
+                  else
+                    echo "channel=prod" >> "$GITHUB_OUTPUT"
+                  fi
+
+            - name: Install UPX (production only)
+              if: steps.version.outputs.channel == 'prod'
+              run: sudo apt-get update && sudo apt-get install -y upx
+
+            - name: Cross-compile ziginit
+              run: |
+                  cd tools/ziginit
+                  channel="${{ steps.version.outputs.channel }}"
+                  if [[ "$channel" == "prod" ]]; then
+                    optimize="ReleaseSmall"
+                  else
+                    optimize="ReleaseSafe"
+                  fi
+                  echo "Channel: ${channel}, Optimize: ${optimize}"
+
+                  declare -A targets=(
+                    ["x86_64-linux"]="linux_amd64"
+                    ["aarch64-linux"]="linux_arm64"
+                    ["arm-linux"]="linux_armv7"
+                    ["x86_64-macos"]="darwin_amd64"
+                    ["aarch64-macos"]="darwin_arm64"
+                  )
+                  mkdir -p ../../release-artifacts
+                  for zig_target in "${!targets[@]}"; do
+                    label="${targets[$zig_target]}"
+                    echo "=== Building ziginit for ${zig_target} (${optimize}) ==="
+                    zig build -Doptimize="${optimize}" -Dtarget="${zig_target}"
+                    if [[ "$channel" == "prod" && "$zig_target" == *-linux ]]; then
+                      upx --best --lzma zig-out/bin/ziginit || true
+                    fi
+                    archive="ziginit_${{ steps.version.outputs.version }}_${label}.tar.gz"
+                    tar -czf "../../release-artifacts/${archive}" -C zig-out/bin ziginit
+                    rm -rf zig-out
+                  done
+
+            - name: Generate checksums
+              run: |
+                  cd release-artifacts
+                  sha256sum *.tar.gz > checksums.txt
+                  cat checksums.txt
+
+            - name: Generate changelog (production only)
+              if: steps.version.outputs.channel == 'prod'
+              uses: orhun/git-cliff-action@v4
+              with:
+                  config: cliff.toml
+                  args: --latest --strip header
+              env:
+                  OUTPUT: CHANGES.md
+
+            - name: Create GitHub Release
+              env:
+                  GH_TOKEN: ${{ secrets.RELEASER_TOKEN }}
+              run: |
+                  prerelease=""
+                  notes_arg="--generate-notes"
+                  if [[ "${{ steps.version.outputs.channel }}" != "prod" ]]; then
+                    prerelease="--prerelease"
+                  else
+                    notes_arg="--notes-file CHANGES.md"
+                  fi
+                  gh release create "${{ github.ref_name }}" \
+                    --title "ziginit ${{ steps.version.outputs.version }}" \
+                    $notes_arg \
+                    $prerelease \
+                    release-artifacts/*