@singbox-iac/cli 0.1.0

package/dist/shared/result.js

@@ -0,0 +1,7 @@
+export function ok(value) {
+    return { ok: true, value };
+}
+export function err(error) {
+    return { ok: false, error };
+}
+//# sourceMappingURL=result.js.map

package/dist/shared/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/shared/result.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,EAAE,CAAI,KAAQ;IAC5B,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED,MAAM,UAAU,GAAG,CAAI,KAAQ;IAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC"}

package/docs/antigravity-endpoints.md

@@ -0,0 +1,77 @@
+# Antigravity Endpoint Notes
+
+These notes were derived from the installed macOS app bundle at `/Applications/Antigravity.app` and local logs under `/Users/lvyuanfang/Library/Application Support/Antigravity/logs`.
+
+## App Identity
+
+- Bundle identifier: `com.google.antigravity`
+- Product links in `product.json`:
+  - `https://antigravity.google/docs`
+  - `https://antigravity.google/docs/rules`
+  - `https://antigravity.google/docs/mcp`
+  - `https://antigravity.google/support`
+
+## Observed Or Referenced Google Endpoints
+
+The installed app and local logs reference these Google-hosted domains that are relevant for routing verification:
+
+- `antigravity.google`
+- `accounts.google.com`
+- `oauth2.googleapis.com`
+- `clients2.google.com`
+- `android.clients.google.com`
+- `apis.google.com`
+- `aiplatform.googleapis.com`
+- `cloud.google.com`
+- `daily-cloudcode-pa.googleapis.com`
+- `firebase.googleapis.com`
+- `fonts.googleapis.com`
+- `fonts.gstatic.com`
+- `lh3.googleusercontent.com`
+- `play.googleapis.com`
+- `antigravity-unleash.goog`
+- `www.googleapis.com`
+- `www.gstatic.com`
+
+## Why These Matter
+
+- `accounts.google.com` is a good auth-path verification target for `in-proxifier`.
+- `oauth2.googleapis.com` is a good OAuth metadata verification target for `in-proxifier`.
+- `antigravity.google` is a good product-surface verification target for `in-proxifier`.
+- `www.googleapis.com` is a stable Google API surface that appeared in real runtime logs and is suitable for verification.
+- `daily-cloudcode-pa.googleapis.com` appears during real model streaming, but it is less stable as a browser verification target and is better tracked as an observed runtime dependency.
+- `play.googleapis.com`, `antigravity-unleash.goog`, `lh3.googleusercontent.com`, `clients2.google.com`, `android.clients.google.com`, `fonts.googleapis.com`, and `www.gstatic.com` regularly appear as supporting traffic during a real Antigravity session.
+
+## User Journey Buckets
+
+### Product Surfaces
+
+- `https://antigravity.google/docs`
+- `https://antigravity.google/docs/rules`
+- `https://antigravity.google/docs/mcp`
+
+### Auth And Session Bootstrap
+
+- `https://accounts.google.com/favicon.ico`
+- `https://oauth2.googleapis.com/.well-known/openid-configuration`
+
+### Control And API Surfaces
+
+- `https://www.googleapis.com/discovery/v1/apis`
+- Observed at runtime, but not used as fixed browser probes:
+  - `daily-cloudcode-pa.googleapis.com`
+  - `play.googleapis.com`
+  - `antigravity-unleash.goog`
+
+## Current Verification Usage
+
+The current verification harness uses:
+
+- `https://accounts.google.com/favicon.ico`
+- `https://oauth2.googleapis.com/.well-known/openid-configuration`
+- `https://antigravity.google/docs`
+- `https://antigravity.google/docs/rules`
+- `https://antigravity.google/docs/mcp`
+- `https://www.googleapis.com/discovery/v1/apis`
+
+All of these are routed through `in-proxifier` and must land on the fixed US `OnlyAI` node.

package/docs/competitive-landscape.md

@@ -0,0 +1,45 @@
+# Competitive Landscape
+
+## Existing Categories
+
+### Generic subscription converters
+
+These tools convert provider subscriptions into one or more target client formats. They are useful, but their center of gravity is format conversion, not runtime-safe policy compilation.
+
+Typical limitations:
+
+- route precedence is often inherited from templates
+- process-aware routing is not a first-class use case
+- runtime validation and staged publish are usually outside scope
+
+### GUI clients and launchers
+
+These tools optimize for usability and visual management. They are convenient but tend to hide merge order, effective config structure, and runtime rollout details.
+
+Typical limitations:
+
+- higher idle resource usage
+- config merge logic is harder to audit
+- process routing and custom listeners become brittle over time
+
+### Library-style generators
+
+These projects expose config generation as an SDK or library. They can be useful implementation references but are not the final product shape targeted here.
+
+Typical limitations:
+
+- not macOS workflow-oriented
+- no opinionated CLI lifecycle
+- no declarative policy authoring model
+
+## Planned Differentiators
+
+`Sing-box IaC Builder` should differentiate on:
+
+- policy-first compilation
+- macOS headless operation
+- explicit staged rollout
+- route ordering invariants
+- user-facing rule DSL
+- future natural-language rule authoring with DSL confirmation
+

package/docs/development-workflow.md

@@ -0,0 +1,80 @@
+# Development Workflow
+
+## Goal
+
+Use OpenSpec for specification control and Superpowers for execution discipline.
+
+## Working Model
+
+- OpenSpec answers: what behavior should exist.
+- Superpowers answers: how this change will be executed safely.
+
+## Standard Flow for Each Phase
+
+1. Clarify scope and non-goals.
+2. Create or update `openspec/changes/<change-id>/proposal.md`.
+3. Write `design.md` only for the important decisions.
+4. Write `tasks.md` with small, executable tasks.
+5. Update the relevant capability specs under `openspec/specs/`.
+6. Write fixtures or tests before implementation where behavior is concrete.
+7. Implement in small batches.
+8. Run validation.
+9. Fold approved behavior back into the long-lived specs.
+
+## MVP Path
+
+For self-hosting and early dogfooding, prefer a vertical slice when the full roadmap would delay first use too much.
+
+Recommended first slice:
+
+1. parse Trojan subscriptions
+2. compile a minimal usable `sing-box` config
+3. expose a `build` command
+4. test locally with manual `sing-box check`
+
+This keeps OpenSpec lightweight:
+
+- use one MVP-oriented change proposal
+- keep specs focused on acceptance criteria and invariants
+- avoid writing extra design documents unless a decision is genuinely hard to reverse
+
+## Phase Guidance
+
+### Phase 0
+
+Use OpenSpec to define project constraints, architecture, and capability boundaries. Use Superpowers to enforce small setup tasks and avoid jumping into parser or compiler code too early.
+
+### Phase 1
+
+Use OpenSpec to lock parser input, output, and failure semantics. Use Superpowers to drive fixture-first implementation and edge-case coverage.
+
+If the immediate goal is self-use, combine the parser with a minimal compiler and `build` command under a vertical MVP change before returning to the broader phase roadmap.
+
+### Phase 2
+
+Use OpenSpec to define compiler invariants and route priority. Use Superpowers to break the compiler into template assembly, grouping, and route generation tasks.
+
+### Phase 3
+
+Use OpenSpec to define CLI contracts and fetch behavior. Use Superpowers to implement command-by-command instead of building the whole pipeline as one opaque step.
+
+### Phase 4
+
+Use OpenSpec to define runtime state transitions and safety rules. Use Superpowers to implement validation, publish, reload, and rollback in explicit steps.
+
+### Future Rule Authoring
+
+Use OpenSpec to define the DSL grammar and compiler guarantees. Use Superpowers to keep natural-language support behind a preview-and-confirm flow.
+
+## Review Focus
+
+Before closing a change, verify:
+
+- specs still match implementation
+- error handling is defensive
+- route ordering invariants are protected
+- user-configurable layers cannot bypass system invariants silently
+
+## Current Recommendation
+
+The next implementation step for this repository is `parse-and-build-first-config`. It is the shortest path from specification baseline to a locally usable config generator.

package/docs/natural-language-authoring.md

@@ -0,0 +1,376 @@
+# Natural-Language Authoring
+
+The `author` command is the bridge between a short routing prompt and the full local workflow:
+
+1. turn a prompt into the YAML rules DSL
+2. write the generated rules file
+3. update the builder config to point at that rules file
+4. build a new `sing-box` config
+5. optionally install a `launchd` schedule that runs `update`
+6. optionally run `update` immediately from the same command
+
+The output still goes through the normal compiler pipeline. Natural language does not mutate `sing-box` JSON directly.
+
+## Provider Modes
+
+The authoring layer supports four provider modes:
+
+- `deterministic`
+  The built-in keyword/template parser. This is the default because it is fast, testable, and does not depend on any external model.
+
+- `auto`
+  Try a supported local AI CLI first, then fall back to the deterministic parser if the local CLI is unavailable, times out, or returns invalid output.
+
+- `claude`
+  Use the local `claude` CLI directly for structured JSON plan generation.
+
+- `exec`
+  Use any local command that can print a JSON authoring plan to stdout or write one to a file.
+
+Recommended default:
+
+```yaml
+authoring:
+  provider: "deterministic"
+  timeoutMs: 4000
+```
+
+Opt in to local AI CLI probing:
+
+```yaml
+authoring:
+  provider: "auto"
+  timeoutMs: 1000
+```
+
+## One-Line Examples
+
+Generate rules and build a staging config:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --prompt "开发者网站走香港，视频网站走新加坡"
+```
+
+Preview what would change without writing files:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --provider deterministic \
+  --prompt "OpenRouter 走香港，YouTube Netflix 走美国，每60分钟自动更新" \
+  --preview
+```
+
+Generate rules, build a config, and install a schedule:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --prompt "OpenRouter 和 Perplexity 走香港，YouTube Netflix 走美国，每45分钟自动更新" \
+  --install-schedule
+```
+
+Generate rules and immediately run `build -> verify -> publish`:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --provider deterministic \
+  --prompt "Google 服务和 GitHub 这类开发类都走香港，Gemini 走新加坡，Antigravity 进程级走美国，每30分钟自动更新" \
+  --update
+```
+
+Force a local AI CLI attempt first, then fall back safely if needed:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --provider auto \
+  --author-timeout-ms 1000 \
+  --prompt "开发者网站走香港，AI 工具走香港，视频网站走新加坡，每45分钟自动更新"
+```
+
+Use a local subscription fixture instead of fetching remotely:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --prompt "国内视频网站直连，AI 工具走香港，每2小时自动更新" \
+  --subscription-file ./tests/fixtures/subscriptions/trojan-sample.b64 \
+  --install-schedule \
+  --no-load
+```
+
+## What the Prompt Can Express
+
+This layer intentionally aims at simple intent, not full policy programming.
+
+It works best for:
+
+- process-aware reminders like `IDE 走 proxifier`
+- site classes like `视频网站走美国`
+- named products like `Google Stitch 走美国`
+- short regional intents like `OpenRouter 走香港`
+- schedule phrases like `每45分钟自动更新`
+- one-sentence developer routing like `GitHub 这类开发类走香港，Antigravity 进程级走美国，Gemini 走新加坡`
+- mainstream subscription vocabulary like `Google 服务`, `Apple 服务`, `Amazon Prime`, `Apple TV`
+
+## Intent-First Behavior
+
+The `author` command does not require the user to think in DSL terms.
+
+For common developer sentences, it now compiles intent across three layers:
+
+1. specific site overrides
+   Example: `Gemini 走新加坡` becomes an explicit rule before built-ins.
+2. selector default changes
+   Example: `开发类都走香港` updates `Dev-Common-Out` to default to `HK`.
+3. verification expectation alignment
+   Example: if the configured verification URL for Gemini previously expected `AI-Out -> HK`, it will be updated so runtime verification now expects `SG`.
+
+That keeps `author -> build -> verify` truthful even after intent-driven changes.
+
+Example:
+
+```bash
+./node_modules/.bin/tsx src/cli/index.ts author \
+  --config ./builder.config.local.yaml \
+  --provider deterministic \
+  --prompt "GitHub 这类开发类都走香港出口，Antigravity 进程级都走独立的入口并路由到美国节点，Gemini 都出口到新加坡，每30分钟自动更新"
+```
+
+Common category-style examples:
+
+- `Google 服务和 GitHub 这类开发类都走香港`
+- `Apple 服务走香港`
+- `Amazon Prime 和 Apple TV 走新加坡`
+- `视频网站走美国`
+
+Supported schedule phrases include:
+
+- `每30分钟`
+- `每45分钟`
+- `每2小时`
+- `schedule`
+- `launchd`
+
+## Output Model
+
+Natural language produces three things:
+
+- generated user rules
+- optional inferred templates
+- optional schedule interval
+- optional selector default changes
+- optional verification expectation overrides
+
+The command then updates:
+
+- `rules.userRulesFile`
+- `schedule.enabled`
+- `schedule.intervalMinutes`
+- selector defaults such as `AI-Out`, `Dev-Common-Out`, or `Process-Proxy`
+- verification scenario expectations when an existing scenario’s target intent changed
+
+and writes a new staging config.
+
+With `--preview`, the command does not write anything. Instead it prints:
+
+- rules diff
+- builder config diff
+- staging config diff
+
+This is the safest way to inspect what a prompt or local AI CLI would change before touching your local files.
+
+## Exec Provider
+
+The `exec` provider is the escape hatch for developer machines that already have local AI tooling.
+This is the recommended way to integrate most AI CLIs beyond the built-in `claude` adapter.
+
+The command receives:
+
+- `SINGBOX_IAC_AUTHOR_PROMPT`
+- `SINGBOX_IAC_AUTHOR_SCHEMA`
+- `SINGBOX_IAC_AUTHOR_CONTEXT`
+
+Arguments may use placeholders:
+
+- `{{prompt}}`
+- `{{schema}}`
+- `{{context_json}}`
+- `{{full_prompt}}`
+- `{{schema_file}}`
+- `{{output_file}}`
+
+Environment variables are also injected for wrapper scripts:
+
+- `SINGBOX_IAC_AUTHOR_PROMPT`
+- `SINGBOX_IAC_AUTHOR_SCHEMA`
+- `SINGBOX_IAC_AUTHOR_CONTEXT`
+- `SINGBOX_IAC_AUTHOR_FULL_PROMPT`
+- `SINGBOX_IAC_AUTHOR_SCHEMA_FILE`
+- `SINGBOX_IAC_AUTHOR_OUTPUT_FILE`
+
+The command must print a JSON object that matches the internal plan schema:
+
+```json
+{
+  "templateIds": ["developer-ai-sites", "video-sg"],
+  "beforeBuiltins": [],
+  "afterBuiltins": [],
+  "notes": [],
+  "scheduleIntervalMinutes": 45
+}
+```
+
+If the CLI is noisy, the provider will also accept:
+
+- a fenced ````json` block that contains the plan
+- a longer text response with one balanced JSON object inside it
+- an output file path populated through `{{output_file}}`
+
+## Common Local AI CLI Integrations
+
+The goal is not to hard-code every AI CLI on the market. The goal is to make almost all of them usable through one bounded adapter.
+
+Recommended support model:
+
+- stable built-ins:
+  - `claude`
+- generic `exec` integrations:
+  - `gemini`
+  - `codebuddy`
+  - `codex`
+  - `opencode`
+  - `qodercli` / `qoder`
+- tooling-only or editor launchers:
+  - `trae`
+
+### Gemini CLI
+
+Best when Gemini is already logged in locally and you want a lightweight prompt-only integration.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 4000
+  exec:
+    command: "gemini"
+    args:
+      - "-p"
+      - "{{full_prompt}}"
+```
+
+### CodeBuddy CLI
+
+`codebuddy` and `cbc` expose `--print` and `--output-format json`, which makes them strong `exec` candidates.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 4000
+  exec:
+    command: "codebuddy"
+    args:
+      - "--print"
+      - "--output-format"
+      - "json"
+      - "{{full_prompt}}"
+```
+
+### Codex CLI
+
+Codex already supports schema files and writing the final response to a file. That maps well onto `{{schema_file}}` and `{{output_file}}`.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 8000
+  exec:
+    command: "codex"
+    args:
+      - "exec"
+      - "--skip-git-repo-check"
+      - "--output-schema"
+      - "{{schema_file}}"
+      - "--output-last-message"
+      - "{{output_file}}"
+      - "{{full_prompt}}"
+```
+
+### OpenCode
+
+`opencode run` supports a non-interactive message flow and a JSON event mode. Use a small wrapper if the raw JSON event stream is too noisy.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 8000
+  exec:
+    command: "opencode"
+    args:
+      - "run"
+      - "--format"
+      - "json"
+      - "{{full_prompt}}"
+```
+
+### Qoder CLI
+
+If Qoder is installed locally, prefer a wrapper script or a direct print/json mode if your local version exposes one.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 8000
+  exec:
+    command: "qodercli"
+    args:
+      - "--print"
+      - "--output-format"
+      - "json"
+      - "{{full_prompt}}"
+```
+
+### Wrapper Pattern
+
+Some CLIs will not print the exact JSON plan directly. In that case, use a tiny local wrapper script.
+
+```yaml
+authoring:
+  provider: "exec"
+  timeoutMs: 8000
+  exec:
+    command: "/Users/you/bin/singbox-author-wrapper"
+    args:
+      - "{{prompt}}"
+      - "{{output_file}}"
+      - "{{schema_file}}"
+```
+
+That wrapper can:
+
+1. call the local AI CLI you prefer
+2. instruct it to output only one JSON plan
+3. write the final JSON object to `{{output_file}}`
+
+This keeps the project neutral and avoids shipping hard-coded adapters for every vendor.
+
+## Guardrails
+
+- Built-in protected system rules still stay first.
+- Generated rules still pass through the DSL validator.
+- Schedule installation is explicit through `--install-schedule`.
+- If a clause maps better to the built-in proxifier flow, the generator emits a note rather than trying to fake process matching inside the DSL.
+- `auto` may fall back to deterministic if a local AI CLI is installed but not usable in the current environment.
+
+## Recommended Usage
+
+For developer-oriented setups, use this workflow:
+
+1. keep `Process-Proxy` reserved for Proxifier-driven IDE and app traffic
+2. use built-in service rules for Stitch, OpenAI, Gemini, Anthropic, GitHub, and Google
+3. use templates or natural language for third-party AI sites and video sites
+4. use the DSL only for small exceptions

package/docs/positioning.md

@@ -0,0 +1,42 @@
+# Positioning
+
+## One-Line Summary
+
+`Sing-box IaC Builder` is a policy-first CLI that compiles subscriptions into safe, headless `sing-box` infrastructure for macOS.
+
+## Problem Statement
+
+Existing workflows usually optimize for importing subscriptions into a GUI client. They do not optimize for:
+
+- deterministic route priority
+- process-aware routing via `Proxifier`
+- multiple listeners with stable semantics
+- headless runtime management
+- low resource usage
+- safe rollout and validation
+
+## Strategic Difference
+
+This project separates three concerns that are often mixed together:
+
+1. provider input
+2. local policy
+3. runtime application
+
+Provider subscriptions are treated as untrusted upstream data. Local policy is declared separately and compiled with stable precedence. Runtime application is validated before live deployment.
+
+## Open Source Position
+
+This project should be published as:
+
+- a `sing-box` compiler, not a generic converter
+- a macOS-first headless runtime tool, not a GUI replacement
+- a policy authoring system, not only a template pack
+
+## Target Users
+
+- advanced macOS users who already run `sing-box`
+- users migrating away from Clash Verge or similar GUI clients
+- users relying on `Proxifier`, AI applications, or mixed app-specific routing
+- users who want a low-overhead headless runtime
+

package/docs/releasing.md

@@ -0,0 +1,72 @@
+# Releasing
+
+This repository is prepared for npm-style distribution. The default package name is now:
+
+```json
+"name": "@singbox-iac/cli"
+```
+
+The repository still intentionally remains `"private": true` until the first real publish.
+
+## Current Release Safety Commands
+
+Use these two commands before any real publish:
+
+```bash
+npm run release:check
+npm run release:dry-run
+```
+
+`release:check` verifies:
+
+- typecheck
+- lint
+- tests
+- build
+- `npm pack`
+- clean-directory install
+- installed `singbox-iac --help`
+
+`release:dry-run` first runs `release:check`, then stages a publishable package copy with:
+
+- `private: false`
+- a publish name
+- compiled `dist`
+- docs/examples/README/LICENSE
+
+and finally runs:
+
+```bash
+npm publish --dry-run
+```
+
+## Package Name
+The chosen default publish target is:
+
+- `@singbox-iac/cli`
+
+The installed command remains:
+
+- `singbox-iac`
+
+## Dry-Run with a Candidate Name
+
+You can still test an alternate future publish name without changing the repository package metadata:
+
+```bash
+SINGBOX_IAC_PACKAGE_NAME=@singbox-iac/experimental-cli npm run release:dry-run
+```
+
+## Real Publish Checklist
+
+1. confirm the license choice
+2. remove `"private": true` in `package.json`
+3. ensure you are logged into npm with access to the `singbox-iac` organization
+4. run `npm run release:check`
+5. run `npm run release:dry-run`
+6. publish from a clean working tree with `npm publish --access public`
+
+## Notes
+
+- `release:dry-run` keeps its staging directory on failure for debugging.
+- `release:check` and `release:dry-run` both avoid mutating the live repository package metadata.