fix: gate runtime with package debug flag

Author: linhay

.agents/tritonkit-skills/public/tritonkit-dev-feedback/SKILL.md

@@ -238,20 +238,16 @@ SwiftPM:
 https://github.com/NeptuneKit/TritonKit.git
 ```
 
-Add the `TritonKit` product to the iOS app target. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the library's Release no-op behavior.
+Add only the `TritonKit` product to the iOS app target. `TritonKitShared` is an internal shared-contract target pulled in transitively; app integrations should not select or import it directly. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the package runtime guard.
 
-SwiftPM / Xcode package product dependencies do not have a CocoaPods-style `:configurations => ['Debug']` switch. The supported SwiftPM path is source-level Debug isolation with the dedicated bootstrap file below, plus TritonKit's Release no-op runtime. If the production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
+SwiftPM supports configuration-scoped build settings, so TritonKit defines `TRITONKIT_RUNTIME_ENABLED` only for Debug package builds and keeps the embedded runtime no-op in Release. SwiftPM / Xcode package product dependencies still do not have a CocoaPods-style `:configurations => ['Debug']` switch: the package product may remain attached to the target even though the runtime is disabled. If the production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
 
-CocoaPods during development, restricted to Debug configurations:
+CocoaPods during development, restricted to Debug configurations. Do not add `TritonKitShared` explicitly; `TritonKit` resolves it transitively.
 
 ```ruby
 target 'YourApp' do
   use_frameworks!
 
-  pod 'TritonKitShared',
-      :git => 'https://github.com/NeptuneKit/TritonKit.git',
-      :branch => 'main',
-      :configurations => ['Debug']
   pod 'TritonKit',
       :git => 'https://github.com/NeptuneKit/TritonKit.git',
       :branch => 'main',
@@ -476,7 +472,7 @@ If more than one iOS Simulator app connects to the same `triton serve`, use `tri
 
 - For physical devices or local-network testing, add `NSLocalNetworkUsageDescription` to the app target if iOS prompts for local network access.
 - If App Transport Security blocks cleartext local development traffic, use a debug-only ATS exception. Do not ship broad ATS exceptions in production.
-- Release builds should compile, but `TritonKit.isRuntimeEnabled` is false and the embedded runtime does not connect, collect hierarchy, upload data, or respond to control messages. App-side integration files should still be explicitly wrapped in `#if DEBUG` so production entry points do not import or start TritonKit.
+- Release package builds should compile, but `TritonKit.isRuntimeEnabled` is false because `TRITONKIT_RUNTIME_ENABLED` is not defined; the embedded runtime does not connect, collect hierarchy, upload data, or respond to control messages. App-side integration files should still be explicitly wrapped in `#if DEBUG` so production entry points do not import or start TritonKit.
 
 ## Harmony App Integration Guide
 

.agents/tritonkit-skills/public/tritonkit-real-project-regression/SKILL.md

@@ -27,7 +27,7 @@ Real-project validation is not the same as demo smoke. Treat the business app as
    - If the task needs iOS embedded runtime access, use the iOS package path below.
    - If the task needs Harmony embedded runtime access, use the Harmony package/source path below and keep provider semantics opt-in.
    - SwiftPM or CocoaPods as requested; CocoaPods examples must use `:configurations => ['Debug']`.
-   - For SwiftPM, do not claim configuration-scoped package dependencies exist. Use source-level `#if DEBUG` isolation, or create a separate Debug-only app target/scheme if Release must not link TritonKit at all.
+   - For SwiftPM, distinguish build settings from product dependencies: TritonKit uses the package `TRITONKIT_RUNTIME_ENABLED` Debug compile flag, but SwiftPM still does not provide CocoaPods-style configuration-scoped product dependencies. Keep source-level `#if DEBUG` isolation, or create a separate Debug-only app target/scheme if Release must not link TritonKit at all.
    - Put all app-side TritonKit code in a dedicated iOS file such as `TritonKitDebugBootstrap.swift`.
    - Wrap the entire file in `#if DEBUG`, including `import TritonKit` and `TritonKit.shared.start(...)`.
    - Call the bootstrap only from a `#if DEBUG` branch in AppDelegate, SceneDelegate, or SwiftUI `onAppear`.
@@ -257,20 +257,16 @@ SwiftPM:
 https://github.com/NeptuneKit/TritonKit.git
 ```
 
-Add the `TritonKit` product to the iOS app target. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the library's Release no-op behavior.
+Add only the `TritonKit` product to the iOS app target. `TritonKitShared` is an internal shared-contract target pulled in transitively; app integrations should not select or import it directly. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the package runtime guard.
 
-SwiftPM / Xcode package product dependencies do not have a CocoaPods-style `:configurations => ['Debug']` switch. The supported SwiftPM path is source-level Debug isolation with the dedicated bootstrap file below, plus TritonKit's Release no-op runtime. If the production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
+SwiftPM supports configuration-scoped build settings, so TritonKit defines `TRITONKIT_RUNTIME_ENABLED` only for Debug package builds and keeps the embedded runtime no-op in Release. SwiftPM / Xcode package product dependencies still do not have a CocoaPods-style `:configurations => ['Debug']` switch: the package product may remain attached to the target even though the runtime is disabled. If the production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
 
-CocoaPods during development:
+CocoaPods during development. Do not add `TritonKitShared` explicitly; `TritonKit` resolves it transitively:
 
 ```ruby
 target 'YourApp' do
   use_frameworks!
 
-  pod 'TritonKitShared',
-      :git => 'https://github.com/NeptuneKit/TritonKit.git',
-      :branch => 'main',
-      :configurations => ['Debug']
   pod 'TritonKit',
       :git => 'https://github.com/NeptuneKit/TritonKit.git',
       :branch => 'main',

Package.swift

@@ -17,7 +17,10 @@ let package = Package(
         .target(
             name: "TritonKit",
             dependencies: ["TritonKitShared"],
-            path: "Sources/TritonKit"
+            path: "Sources/TritonKit",
+            swiftSettings: [
+                .define("TRITONKIT_RUNTIME_ENABLED", .when(configuration: .debug))
+            ]
         ),
         .testTarget(
             name: "TritonKitSharedTests",
@@ -27,7 +30,10 @@ let package = Package(
         .testTarget(
             name: "TritonKitTests",
             dependencies: ["TritonKit"],
-            path: "Tests/TritonKitTests"
+            path: "Tests/TritonKitTests",
+            swiftSettings: [
+                .define("TRITONKIT_RUNTIME_ENABLED", .when(configuration: .debug))
+            ]
         ),
     ]
 )

README.md

@@ -30,9 +30,9 @@ In Xcode, add this package URL:
 https://github.com/NeptuneKit/TritonKit.git
 ```
 
-Add the `TritonKit` product to the iOS app target. `TritonKitShared` is pulled in as a package target dependency. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the library's Release no-op behavior.
+Add only the `TritonKit` product to the iOS app target. `TritonKitShared` is an internal shared-contract target pulled in transitively; app integrations should not select or import it directly. Keep every app-side source file that imports or starts TritonKit behind `#if DEBUG`; do not rely only on the package runtime guard.
 
-SwiftPM / Xcode package product dependencies do not have a CocoaPods-style `:configurations => ['Debug']` switch. The supported SwiftPM path is source-level Debug isolation with the dedicated bootstrap file below, plus TritonKit's Release no-op runtime. If your production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
+SwiftPM supports configuration-scoped build settings, so TritonKit defines `TRITONKIT_RUNTIME_ENABLED` only for Debug package builds and keeps the embedded runtime no-op in Release. SwiftPM / Xcode package product dependencies still do not have a CocoaPods-style `:configurations => ['Debug']` switch: the package product may remain attached to the target even though the runtime is disabled. If the production Release target must not link TritonKit at all, create a separate Debug-only app target or scheme and attach the `TritonKit` product only to that target.
 
 For command-line package manifests:
 
@@ -42,16 +42,12 @@ For command-line package manifests:
 
 #### CocoaPods
 
-During development, point CocoaPods at the repository and restrict both pods to Debug configurations:
+During development, point CocoaPods at the repository and restrict the TritonKit pod to Debug configurations. Do not add `TritonKitShared` explicitly; the `TritonKit` podspec resolves the matching shared-contract pod transitively.
 
 ```ruby
 target 'YourApp' do
   use_frameworks!
 
-  pod 'TritonKitShared',
-      :git => 'https://github.com/NeptuneKit/TritonKit.git',
-      :branch => 'main',
-      :configurations => ['Debug']
   pod 'TritonKit',
       :git => 'https://github.com/NeptuneKit/TritonKit.git',
       :branch => 'main',
@@ -207,7 +203,7 @@ If your app blocks cleartext development traffic through App Transport Security,
 
 ### 4. iOS Runtime Boundary
 
-`TritonKit.isRuntimeEnabled` is `true` only in `DEBUG` builds. In Release builds the public API remains compileable, but the embedded runtime does not connect, collect hierarchy, upload data, or respond to control messages. App-side integration files should still be explicitly wrapped in `#if DEBUG` so production entry points do not import or start TritonKit.
+`TritonKit.isRuntimeEnabled` is `true` only when the package build defines `TRITONKIT_RUNTIME_ENABLED` (the default Debug package configuration). In Release package builds the public API remains compileable, but the embedded runtime does not connect, collect hierarchy, upload data, or respond to control messages. App-side integration files should still be explicitly wrapped in `#if DEBUG` so production entry points do not import or start TritonKit.
 
 ### 5. WebView Observation
 

Sources/TritonKit/TritonKit.swift

@@ -167,7 +167,7 @@ public class TritonKit {
     }
 
     public static var isRuntimeEnabled: Bool {
-        #if DEBUG
+        #if TRITONKIT_RUNTIME_ENABLED
         true
         #else
         false

Tests/TritonKitTests/TKPlatformFallbackTests.swift

@@ -7,9 +7,9 @@ import Darwin
 
 @Suite
 struct TKPlatformFallbackTests {
-    @Test("runtime is enabled only in DEBUG builds")
+    @Test("runtime is enabled only when the package debug flag is defined")
     func runtimeEnabledFlagMatchesBuildConfiguration() {
-        #if DEBUG
+        #if TRITONKIT_RUNTIME_ENABLED
         #expect(TritonKit.isRuntimeEnabled)
         #else
         #expect(!TritonKit.isRuntimeEnabled)
@@ -126,8 +126,12 @@ struct TKPlatformFallbackTests {
             config.autoReconnect = false
         })
 
+        #if TRITONKIT_RUNTIME_ENABLED
         #expect(started)
         try await Task.sleep(nanoseconds: 500_000_000)
+        #else
+        #expect(!started)
+        #endif
         #expect(kit.state == .disconnected)
         #expect(observedErrors.isEmpty)
     }

docs-linhay/dev/20260519-cocoapods-support.md

@@ -10,8 +10,9 @@ TritonKit 需要支持业务 App 通过 CocoaPods 引入 embedded runtime，同
 
 - Given 业务 App 的 Podfile 引入 `pod 'TritonKit'`
 - When CocoaPods 解析依赖
-- Then `TritonKit` 会依赖同版本 `TritonKitShared`
-- And Swift module 边界与 SwiftPM 一致，`import TritonKitShared` 可解析
+- Then 业务 Podfile 只需要显式引入 `pod 'TritonKit'`
+- And `TritonKit` podspec 会传递依赖同版本 `TritonKitShared`
+- And 内部 Swift module 边界与 SwiftPM 一致，CLI / runtime 仍可解析 `import TritonKitShared`
 - And 对外示例必须使用 `:configurations => ['Debug']`，避免 Release 配置安装 embedded runtime
 
 ### 场景 2：CocoaPods 集成遵守 Debug-only runtime
@@ -34,7 +35,7 @@ TritonKit 需要支持业务 App 通过 CocoaPods 引入 embedded runtime，同
 1. `TritonKitShared.podspec` 只包含 `Sources/TritonKitShared/**/*.swift`。
 2. `TritonKit.podspec` 只包含 `Sources/TritonKit/**/*.swift`，并依赖同版本 `TritonKitShared`。
 3. CocoaPods 不打包 `Sources/TritonKitCLI`；SwiftPM 根 `Package.swift` 也不声明 CLI executable 与 CLI-only package dependencies，避免把 macOS CLI / Hummingbird / ArgumentParser 依赖带入业务 App。
-4. README 与 public skill 中的 Podfile 示例必须给 `TritonKitShared` 与 `TritonKit` 同时加 `:configurations => ['Debug']`。
+4. README 与 public skill 中的用户 Podfile 示例只允许显式添加 `pod 'TritonKit'`，并加 `:configurations => ['Debug']`；不得要求用户手写 `pod 'TritonKitShared'`，该依赖由 `TritonKit.podspec` 传递解析。
 5. 业务 App 侧推荐将全部 TritonKit 启动代码放入独立 `TritonKitDebugBootstrap.swift`，并用文件级 `#if DEBUG` 包住 `import TritonKit` 和 `TritonKit.shared.start()` / `start { config in ... }` 调用。
 6. podspec 版本暂与当前 CLI 版本保持一致：`0.1.0`。正式发布 CocoaPods 前，需要先创建对应 `v0.1.0` tag，或在发布时同步调整版本。
 7. 当前项目仍处开发阶段，podspec license metadata 使用 `Custom`，正式发布前应补齐稳定 license 文件与发布策略。

docs-linhay/dev/20260519-debug-only-pm-runtime.md

@@ -2,22 +2,24 @@
 
 ## 背景
 
-TritonKit 作为 Package Manager 依赖提供给业务 App 时，embedded runtime 不应在 Release 构建中实际连接、采集或响应控制。该约束只跟编译配置有关，不跟 iOS/macOS、UIKit 是否可导入等端类型绑定。同时，业务 App 侧接入文件必须显式使用 `#if DEBUG`，不能只依赖库内部 Release no-op。
+TritonKit 作为 Package Manager 依赖提供给业务 App 时，embedded runtime 不应在 Release 构建中实际连接、采集或响应控制。该约束由 SwiftPM package target 的 Debug-only compile flag `TRITONKIT_RUNTIME_ENABLED` 表达，不跟 iOS/macOS、UIKit 是否可导入等端类型绑定。同时，业务 App 侧接入文件必须显式使用 `#if DEBUG`，不能只依赖包内部 Release no-op。
 
 ## 验收场景
 
 ### 场景 1：Debug 构建启用 embedded runtime
 
 - Given App 通过 Package Manager 引入 TritonKit
-- When 使用 `DEBUG` 编译配置构建
-- Then `TritonKit.isRuntimeEnabled == true`
+- When 使用 Debug 编译配置构建
+- Then `TRITONKIT_RUNTIME_ENABLED` 被定义
+- And `TritonKit.isRuntimeEnabled == true`
 - And `connect`、消息处理、hierarchy 采集和 data upload 按现有逻辑执行
 
 ### 场景 2：Release 构建禁用 embedded runtime
 
 - Given App 通过 Package Manager 引入 TritonKit
 - When 使用 Release 编译配置构建
 - Then package 仍可编译通过
+- And `TRITONKIT_RUNTIME_ENABLED` 不被定义
 - And `TritonKit.isRuntimeEnabled == false`
 - And runtime 不连接、不采集、不上传、不响应控制
 
@@ -40,13 +42,15 @@ TritonKit 作为 Package Manager 依赖提供给业务 App 时，embedded runtim
 
 - Given README 或 public skill 提供 SwiftPM 接入说明
 - When 用户要求 Debug-only 接入
-- Then 文档必须说明 SwiftPM / Xcode package product dependency 没有 CocoaPods-style `:configurations => ['Debug']`
-- And 默认推荐源码级 `#if DEBUG` bootstrap + Release no-op runtime
+- Then 文档必须说明 SwiftPM 支持 configuration-scoped build settings / compile conditions
+- And TritonKit package 内部使用 `TRITONKIT_RUNTIME_ENABLED` 在 Debug package build 启用 runtime
+- And 文档必须说明 SwiftPM / Xcode package product dependency 没有 CocoaPods-style `:configurations => ['Debug']`
+- And 默认推荐 package Debug compile flag + 源码级 `#if DEBUG` bootstrap + Release no-op runtime
 - And 若 Release target 必须完全不链接 TritonKit，则推荐独立 Debug-only app target / scheme
 
 ## 实现约定
 
-1. 用 `#if DEBUG` 定义 `TritonKit.isRuntimeEnabled`，作为 runtime 是否生效的唯一配置边界。
+1. 在 `Package.swift` 的 `TritonKit` target 通过 `.define("TRITONKIT_RUNTIME_ENABLED", .when(configuration: .debug))` 定义 package 内部 runtime 启用边界；`TritonKit.isRuntimeEnabled` 只读取该宏，不直接绑定裸 `#if DEBUG`。
 2. Release 下保留 public API，避免业务 App 仅因依赖存在而编译失败。
 3. Release 下 runtime 行为采用 no-op 或明确错误：`connect` / `send` / reconnect / ping no-op，hierarchy 返回空数组，data upload 抛出 `TritonKitRuntimeError.disabledOutsideDebug`，request handler 返回 disabled 错误。
 4. `canImport(UIKit)` 仍只用于保护 UIKit 符号可编译性，不用于决定 runtime 是否启用。
@@ -56,9 +60,9 @@ TritonKit 作为 Package Manager 依赖提供给业务 App 时，embedded runtim
 
 ## 验证
 
-- `swift test` 覆盖 Debug 分支，确认 `TritonKit.isRuntimeEnabled == true`。
-- `swift test -c release` 覆盖 Release 分支，确认 `TritonKit.isRuntimeEnabled == false`。
+- `swift test` 覆盖 Debug package 分支，确认 `TRITONKIT_RUNTIME_ENABLED` 生效且 `TritonKit.isRuntimeEnabled == true`。
+- `swift test -c release` 覆盖 Release package 分支，确认 `TRITONKIT_RUNTIME_ENABLED` 不生效且 `TritonKit.isRuntimeEnabled == false`。
 - `swift build -c release --target TritonKit` 确认 Package Manager 的 Release library target 可编译。
 - `swift build --package-path CLI --scratch-path .build/cli -c release --product triton` 确认 CLI release 产物不受影响。
-- `docs-linhay/scripts/verify-ios-debug-isolation.sh` 校验 `Examples/TritonKitDemo` 的 app-side 接入示例采用文件级 `#if DEBUG`，并确认 runtime 内部 Release no-op 防线存在。
+- `docs-linhay/scripts/verify-ios-debug-isolation.sh` 校验 `Examples/TritonKitDemo` 的 app-side 接入示例采用文件级 `#if DEBUG`，并确认 package 内部 `TRITONKIT_RUNTIME_ENABLED` Release no-op 防线存在。
 - 文档、skill 与 `Examples/TritonKitDemo` 自检确认所有 app-side 接入示例都采用文件级 `#if DEBUG`、CocoaPods Debug-only 配置、推荐显式 opt-in 开关，并明确 SwiftPM 的 Debug-only target / source-level fallback 策略。