@singbox-iac/cli 0.1.0

package/docs/rule-templates.md

@@ -0,0 +1,122 @@
+# Rule Templates
+
+Built-in rule templates are intended to cover the repetitive cases that most developer-oriented setups run into:
+
+- third-party AI sites
+- common third-party developer tooling sites
+- international video sites that should exit through a specific region
+- mainland video sites that should stay direct
+
+Templates are not a replacement for the compiler's built-in policy. They sit on top of it and are meant for fast customization.
+
+## Current Templates
+
+### Developer
+
+- `developer-ai-sites`
+  Routes common third-party AI sites to `AI-Out`.
+  Includes:
+  - `openrouter.ai`
+  - `perplexity.ai`
+
+- `developer-common-sites`
+  Routes common third-party developer sites to `Dev-Common-Out`.
+  Includes:
+  - `gitlab.com`
+  - `npmjs.com`
+  - `registry.npmjs.org`
+  - `vercel.com`
+  - `cloudflare.com`
+  - `docker.com`
+  - `hub.docker.com`
+  - `stackoverflow.com`
+  - `huggingface.co`
+
+### Video
+
+- `video-us`
+  Routes international streaming sites to `US`.
+
+- `video-hk`
+  Routes international streaming sites to `HK`.
+
+- `video-sg`
+  Routes international streaming sites to `SG`.
+
+- `video-jp`
+  Routes Japan-oriented video sites to `JP`.
+
+- `cn-video-direct`
+  Keeps common mainland video sites on `direct`.
+
+The international streaming templates currently cover:
+
+- `youtube.com`
+- `youtu.be`
+- `netflix.com`
+- `nflxvideo.net`
+- `disneyplus.com`
+- `disney-plus.net`
+- `hulu.com`
+- `max.com`
+- `twitch.tv`
+
+The JP template currently covers:
+
+- `abema.tv`
+- `niconico.jp`
+- `dmm.com`
+- `lemino.docomo.ne.jp`
+
+The CN direct template currently covers:
+
+- `bilibili.com`
+- `bilibili.tv`
+- `iqiyi.com`
+- `iq.com`
+- `youku.com`
+- `mgtv.com`
+
+## CLI Usage
+
+List templates:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts templates list
+```
+
+Show one template:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts templates show video-sg
+```
+
+## Natural-Language Mapping
+
+The `author` command can infer templates from short prompts.
+
+Examples:
+
+- `开发者网站走香港，视频网站走新加坡`
+- `AI 工具走香港，视频网站走美国，每45分钟自动更新`
+- `国内视频网站直连，YouTube Netflix 走美国`
+
+Typical mapping behavior:
+
+- `开发者网站` -> `developer-common-sites`
+- `AI 工具` -> `developer-ai-sites`
+- `视频网站走美国` -> `video-us`
+- `视频网站走香港` -> `video-hk`
+- `视频网站走新加坡` -> `video-sg`
+- `日本视频网站` -> `video-jp`
+- `国内视频网站直连` -> `cn-video-direct`
+
+## Design Boundary
+
+Templates are intentionally coarse-grained. They are best for:
+
+- "a whole class of sites should go to one region"
+- "these common developer sites should use the developer selector"
+- "these common AI sites should use the AI selector"
+
+If a user needs one-off exceptions, prefer the DSL instead of adding more template complexity.

package/docs/rules-dsl.md

@@ -0,0 +1,107 @@
+# Rules DSL
+
+## Design Goal
+
+Users should customize routing intent without editing raw `sing-box` JSON.
+
+## Layers
+
+### Layer 1: Built-in system rules
+
+These are protected invariants controlled by the compiler, such as:
+
+- QUIC kill-switch for `udp:443`
+- DNS handling
+- `in-proxifier` high-priority routing
+
+These rules always stay ahead of user rules.
+
+### Layer 2: Declarative user rules
+
+Users write a small YAML DSL with only two insertion points:
+
+- `beforeBuiltins`
+  Inserted after protected system rules and before built-in service rules such as Stitch, OpenAI, AI rule sets, and developer rule sets.
+- `afterBuiltins`
+  Inserted after built-in service rules and before China direct rules.
+
+## File Shape
+
+```yaml
+version: 1
+
+beforeBuiltins:
+  - name: "OpenRouter uses AI"
+    domainSuffix:
+      - "openrouter.ai"
+    route: "AI-Out"
+
+afterBuiltins:
+  - name: "Example mainland domain stays direct"
+    domainSuffix:
+      - "intranet.example.cn"
+    route: "direct"
+```
+
+## Supported Matchers
+
+Each rule may use one or more of these fields:
+
+- `inbound`
+- `protocol`
+- `network`
+- `port`
+- `domain`
+- `domainSuffix`
+- `ruleSet`
+
+Scalar values are allowed for convenience. These are normalized to arrays where needed.
+
+## Supported Actions
+
+- `route: "<outbound-or-group-tag>"`
+- `action: "reject"`
+
+Examples:
+
+```yaml
+version: 1
+
+beforeBuiltins:
+  - name: "OpenRouter uses the AI selector"
+    domainSuffix: "openrouter.ai"
+    route: "AI-Out"
+
+  - name: "Block a specific UDP port"
+    inbound: "in-mixed"
+    network: "udp"
+    port: 443
+    action: "reject"
+```
+
+## Guardrails
+
+- Every rule must define at least one matcher.
+- Every rule must define exactly one action.
+- Route targets must refer to an existing outbound or selector such as `AI-Out`, `HK`, `US`, `direct`, or `Global`.
+- `ruleSet` matchers must refer to configured and active rule-set tags.
+- User rules cannot be inserted ahead of protected system rules.
+
+## Layer 3: Natural language to DSL
+
+Natural-language authoring is now implemented as a separate front door. It still follows the same safety model:
+
+- prompt -> generated DSL
+- generated DSL -> validated user rules
+- validated user rules -> compiled `sing-box` config
+- optional schedule install only when explicitly requested
+
+See:
+
+- `/Users/lvyuanfang/Code/SingBoxConfig/docs/natural-language-authoring.md`
+- `/Users/lvyuanfang/Code/SingBoxConfig/docs/rule-templates.md`
+
+## Non-Goals for v1
+
+- direct natural-language writes to live config
+- arbitrary raw JSON mutation

package/docs/runtime-on-macos.md

@@ -0,0 +1,42 @@
+# Runtime on macOS
+
+## Runtime Goal
+
+The target runtime is a headless macOS deployment:
+
+- `sing-box` installed separately
+- this CLI generates and validates config
+- `launchd` handles periodic updates
+
+## Planned Flow
+
+1. Generate a staging config
+2. Run `sing-box check -c <staging>`
+3. If valid, publish to the live path
+4. Reload `sing-box`
+5. Keep the last-known-good config for recovery
+
+## Current CLI Flow
+
+```bash
+singbox-iac init
+singbox-iac doctor
+singbox-iac build
+singbox-iac verify
+singbox-iac update
+singbox-iac schedule install
+```
+
+## Launchd Notes
+
+- In source-tree development, `schedule install` emits a LaunchAgent that runs `node_modules/.bin/tsx src/cli/index.ts update --config <path>`.
+- In built distributions, the same logic emits a LaunchAgent that runs the compiled CLI entrypoint with `node`.
+- Use `--no-load` during testing to validate the generated plist without calling `launchctl bootstrap`.
+
+## Why `launchd`
+
+For macOS, `launchd` is the correct scheduler primitive. It integrates better with user sessions than `cron` and matches the product's OS target.
+
+## Runtime Safety
+
+The tool must never overwrite the live config with an unchecked file.

package/docs/sing-box-config-primer.md

@@ -0,0 +1,39 @@
+# sing-box Config Primer
+
+## Top-Level Areas
+
+The generated config will primarily work with:
+
+- `dns`
+- `inbounds`
+- `outbounds`
+- `route`
+
+## Product Model
+
+This project will generate:
+
+- fixed inbound listeners
+- dynamic proxy outbounds derived from subscriptions
+- dynamic selector and `urltest` groups
+- rule sets and route rules assembled with stable precedence
+
+## Compatibility Direction
+
+Target `sing-box` version:
+
+- `1.8.x` or newer, with preference for current rule set and rule action formats
+
+The implementation should prefer:
+
+- external `rule_set` references
+- current route actions
+- avoiding deprecated legacy structures where newer forms exist
+
+## Key Invariants
+
+- `udp:443` rejection must stay near the top of route processing
+- DNS handling must happen before ordinary traffic policy
+- `in-proxifier` traffic must have absolute precedence over later domain-based rules
+- China direct-routing rules must remain after higher-priority process and AI rules
+

package/docs/subscription-format.md

@@ -0,0 +1,38 @@
+# Subscription Format Primer
+
+## Reality of Provider Subscriptions
+
+Provider subscriptions are not a `sing-box` native format. In practice they are ecosystem-specific feeds that commonly look like:
+
+1. an HTTP endpoint
+2. returning a Base64-encoded payload
+3. which decodes into plain text
+4. where each line is a share-link URI
+
+Example:
+
+```text
+trojan://password@host:443?sni=example.com#HK-01
+```
+
+## Implication for This Project
+
+This project should not treat provider subscriptions as a final configuration format. It should treat them as a source of nodes to parse into an intermediate representation.
+
+Pipeline:
+
+`fetch -> decode -> parse -> normalize -> compile`
+
+## Phase 1 Scope
+
+Phase 1 supports:
+
+- Base64 line-based subscriptions
+- `trojan://` share links
+
+Later phases may support:
+
+- `vless://`
+- `vmess://`
+- `hysteria2://`
+

package/examples/builder.config.yaml

@@ -0,0 +1,220 @@
+version: 1
+
+subscription:
+  url: "https://example.com/subscription"
+  format: "base64-lines"
+  protocols:
+    - trojan
+
+output:
+  stagingPath: "~/.config/singbox-iac/generated/config.staging.json"
+  livePath: "~/.config/sing-box/config.json"
+  backupPath: "~/.config/singbox-iac/generated/config.last-known-good.json"
+
+runtime:
+  checkCommand: "sing-box check -c {{stagingPath}}"
+  reload:
+    kind: "signal"
+    processName: "sing-box"
+    signal: "HUP"
+
+listeners:
+  mixed:
+    enabled: true
+    listen: "127.0.0.1"
+    port: 39097
+  proxifier:
+    enabled: true
+    listen: "127.0.0.1"
+    port: 39091
+
+ruleSets:
+  - tag: "geosite-cn"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-cn.srs"
+  - tag: "geoip-cn"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geoip-cn.srs"
+  - tag: "geosite-google"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-google.srs"
+  - tag: "geosite-google-gemini"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-google-gemini.srs"
+  - tag: "geosite-google-deepmind"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-google-deepmind.srs"
+  - tag: "geosite-anthropic"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-anthropic.srs"
+  - tag: "geosite-github"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-github.srs"
+  - tag: "geosite-github-copilot"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-github-copilot.srs"
+  - tag: "geosite-cursor"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-cursor.srs"
+  - tag: "geosite-figma"
+    format: "binary"
+    type: "local"
+    path: "~/.config/sing-box/rule-set/geosite-figma.srs"
+
+groups:
+  processProxy:
+    type: "selector"
+    includes:
+      - "US"
+      - "SG"
+      - "JP"
+      - "HK"
+    defaultNodePattern: "OnlyAI"
+  aiOut:
+    type: "selector"
+    includes:
+      - "HK"
+      - "SG"
+      - "US"
+      - "JP"
+    defaultTarget: "HK"
+  devCommonOut:
+    type: "selector"
+    includes:
+      - "HK"
+      - "SG"
+      - "US"
+      - "JP"
+    defaultTarget: "HK"
+  stitchOut:
+    type: "selector"
+    includes:
+      - "US"
+      - "SG"
+      - "JP"
+    defaultTarget: "US"
+  global:
+    type: "urltest"
+    includes:
+      - "HK"
+      - "SG"
+      - "JP"
+      - "US"
+
+rules:
+  userRulesFile: "~/.config/singbox-iac/rules/custom.rules.yaml"
+
+verification:
+  scenarios:
+    - id: "antigravity-auth"
+      name: "Antigravity auth via proxifier stays on the OnlyAI US node"
+      url: "https://accounts.google.com/favicon.ico"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "antigravity-oauth"
+      name: "Antigravity OAuth metadata via proxifier stays on the OnlyAI US node"
+      url: "https://oauth2.googleapis.com/.well-known/openid-configuration"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "antigravity-docs"
+      name: "Antigravity docs via proxifier stay on the OnlyAI US node"
+      url: "https://antigravity.google/docs"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "antigravity-rules-docs"
+      name: "Antigravity rules docs via proxifier stay on the OnlyAI US node"
+      url: "https://antigravity.google/docs/rules"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "antigravity-mcp-docs"
+      name: "Antigravity MCP docs via proxifier stay on the OnlyAI US node"
+      url: "https://antigravity.google/docs/mcp"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "antigravity-google-apis"
+      name: "Antigravity Google API discovery traffic via proxifier stays on the OnlyAI US node"
+      url: "https://www.googleapis.com/discovery/v1/apis"
+      inbound: "in-proxifier"
+      expectedOutbound: "Process-Proxy"
+    - id: "stitch-us"
+      name: "Google Stitch always uses the dedicated US exit"
+      url: "https://stitch.withgoogle.com/favicon.ico"
+      inbound: "in-mixed"
+      expectedOutbound: "Stitch-Out"
+    - id: "cn-direct"
+      name: "China traffic stays direct"
+      url: "https://www.baidu.com/favicon.ico"
+      inbound: "in-mixed"
+      expectedOutbound: "direct"
+    - id: "chatgpt-hk"
+      name: "ChatGPT uses the HK default AI path"
+      url: "https://chatgpt.com/favicon.ico"
+      inbound: "in-mixed"
+      expectedOutbound: "AI-Out"
+    - id: "openrouter-hk"
+      name: "OpenRouter custom DSL rules send traffic to the HK AI path"
+      url: "https://openrouter.ai/favicon.ico"
+      inbound: "in-mixed"
+      expectedOutbound: "AI-Out"
+    - id: "github-hk"
+      name: "GitHub uses the HK default developer path"
+      url: "https://github.com/favicon.ico"
+      inbound: "in-mixed"
+      expectedOutbound: "Dev-Common-Out"
+
+schedule:
+  enabled: true
+  intervalMinutes: 30
+
+authoring:
+  provider: "deterministic"
+  timeoutMs: 4000
+  # To try a local AI CLI safely, switch provider to "auto" or "exec".
+  # provider: "auto"
+  # provider: "exec"
+  # exec:
+  #   command: "gemini"
+  #   args:
+  #     - "-p"
+  #     - "{{full_prompt}}"
+  #
+  # provider: "exec"
+  # exec:
+  #   command: "codebuddy"
+  #   args:
+  #     - "--print"
+  #     - "--output-format"
+  #     - "json"
+  #     - "{{full_prompt}}"
+  #
+  # provider: "exec"
+  # exec:
+  #   command: "codex"
+  #   args:
+  #     - "exec"
+  #     - "--skip-git-repo-check"
+  #     - "--output-schema"
+  #     - "{{schema_file}}"
+  #     - "--output-last-message"
+  #     - "{{output_file}}"
+  #     - "{{full_prompt}}"
+  #
+  # provider: "exec"
+  # exec:
+  #   command: "claude"
+  #   args:
+  #     - "-p"
+  #     - "--output-format"
+  #     - "json"
+  #     - "--json-schema"
+  #     - "{{schema}}"
+  #     - "{{prompt}}"

package/examples/custom.rules.yaml

@@ -0,0 +1,18 @@
+version: 1
+
+beforeBuiltins:
+  - name: "OpenRouter uses the AI selector"
+    domainSuffix:
+      - "openrouter.ai"
+    route: "AI-Out"
+
+  - name: "Perplexity uses the AI selector"
+    domainSuffix:
+      - "perplexity.ai"
+    route: "AI-Out"
+
+afterBuiltins:
+  - name: "Example mainland-only host stays direct"
+    domainSuffix:
+      - "intranet.example.cn"
+    route: "direct"

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@singbox-iac/cli",
+  "version": "0.1.0",
+  "description": "Policy-first subscription compiler for sing-box on macOS.",
+  "type": "module",
+  "license": "MIT",
+  "files": ["dist", "README.md", "docs", "examples"],
+  "bin": {
+    "singbox-iac": "dist/cli/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "keywords": ["sing-box", "proxy", "subscription", "macos", "cli", "proxifier"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "prepare": "npm run build",
+    "prepack": "npm run build",
+    "release:check": "node ./scripts/release-check.mjs",
+    "release:dry-run": "node ./scripts/release-dry-run.mjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "commander": "^13.1.0",
+    "pino": "^9.7.0",
+    "yaml": "^2.8.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2"
+  }
+}