46 Commits
Author SHA1 Message Date
Qiu Yuzhou 0757af988f docs: explain NG2 process architecture 2026-10-24 13:43:58 +08:00
Qiu Yuzhou 17848b6fde ci: add NG2 validation workflow and format checks 2026-10-23 03:05:14 +08:00
Qiu Yuzhou d940e4ef94 docs: add bilingual end-user readmes 2026-10-22 19:18:56 +08:00
Qiu Yuzhou 51667f4839 docs: rename Chinese docs suffix to zh 2026-10-22 17:24:49 +08:00
Qiu Yuzhou faf31a2a78 docs: add English documentation versions 2026-10-22 17:21:17 +08:00
Qiu Yuzhou 8a53575d79 docs: shorten READMEs and extract topic guides 2026-10-19 19:42:38 +08:00
Qiu Yuzhou b6d4c2d637 docs: guide scoped source searches 2026-10-19 19:25:24 +08:00
Qiu Yuzhou 12ae000cb0 refactor(runtime): separate sslocal output from GUI intent 2026-10-19 19:00:43 +08:00
Qiu Yuzhou 003e40d809 refactor(ng2): encrypt proxy listening configuration 2026-10-19 14:31:18 +08:00
Qiu Yuzhou 0f3454602f refactor: separate proxy preferences from listening configuration 2026-10-19 12:10:48 +08:00
Qiu Yuzhou 985153cd56 refactor(rules): separate rule values from storage models 2026-10-19 09:42:38 +08:00
Qiu Yuzhou f1214c4cf5 test: bound asynchronous fixture waits 2026-10-19 04:02:05 +08:00
Qiu Yuzhou b8c6f4d5b4 build: add fail-fast validation task with retained evidence 2026-10-19 03:24:22 +08:00
Qiu Yuzhou 2f0c0d7676 feat: separate local and LAN proxy listeners 2026-10-13 03:58:03 +08:00
Qiu Yuzhou dc64349702 feat(plugins): bundle Cloak v2 client 2026-10-12 12:38:32 +08:00
Qiu Yuzhou f72c50dceb feat(plugins): configure plugin transport mode 2026-10-11 23:58:47 +08:00
Qiu Yuzhou 84c292eb7f feat(plugin): support aliases and local startup arguments 2026-10-11 21:04:59 +08:00
Qiu Yuzhou 7ab774fcfd chore(legacy): 移除 Legacy/ 旧版源码,归档到 legacy-v1 分支
旧版实现已由 shadowsocks/ShadowsocksX-NG 的 legacy-v1 分支跟踪,本仓库不再
保留同一份代码副本。删除 Legacy/ 下 603 个跟踪文件,被 gitignore 的
.DS_Store 一并清理。

删除前核对:Legacy/ShadowsocksX-NG/PACUtils.swift 的 blob hash 与
upstream/legacy-v1 的同名文件完全相同,且工作区在 Legacy/ 下无未提交改动。

配套改动:

- 根 README、AGENTS.md、ShadowsocksX-NG2/README.md:目录结构只留
  ShadowsocksX-NG2/;旧版说明改为指向 shadowsocks/ShadowsocksX-NG 的
  legacy-v1 分支(含其 README);pre-commit 说明去掉 Legacy/。
- codegraph.json 删除 "exclude": ["Legacy/"];.gitignore 与 .zcodeignore
  删除 Legacy 构建产物与依赖条目;.swiftlint.yml 删除 ../Legacy 排除项;
  .githooks/pre-commit 头部注释去掉冻结目录表述。
- docs/research 的 4 份历史研究报告(issue 7/11/12/17)中 129 处
  ../../Legacy/... 相对链接改写为 legacy-v1 的 GitHub blob 链接,正文未改;
  把新 URL 反替换回原相对路径后与 HEAD 版本逐字节相同,证明只动了链接。

验证:全仓库不再有指向 Legacy/ 的路径引用;剩余 Legacy 字样均为概念性用法
(Legacy 导入功能、ADR 与术语表、历史报告正文中的冻结陈述)。本次未改任何
NG2 源码或构建配置,暂存区无 NG2 .swift 文件,pre-commit 直接放行。
2026-10-05 21:39:06 +08:00
Qiu Yuzhou 9b6d73e91c build(signing): 签名身份按 config 注入,Debug 免证书构建
证书与 Team 不入库(开源仓库):Debug 基线改为 ad-hoc,新 clone 与 CI 无
需任何证书即可 task build / task test;Release 基线保持 Developer ID,发
布产物仍须真签名。本机身份由 gitignore 的 Configs/Signing.local.xcconfig
注入,打包门槛的 Team 期望值同源,缺失时明确失败而非静默跳过。

project.yml 不能再设置 CODE_SIGN_IDENTITY / DEVELOPMENT_TEAM:pbxproj 构
建设置优先于 project xcconfig,写死会静默盖掉基线(实测)。整条注入链条
由 Tests/Architecture/SigningConfigurationTests.swift 守卫。

ad-hoc 产物不带 Hardened Runtime(Xcode 对 ad-hoc 签名不传 -o runtime),
嵌套 helper 重签与之一致;Hardened Runtime 仍由 DevID 路径与打包门槛断言。
2026-10-05 21:25:12 +08:00
Qiu Yuzhou 20a62117f2 refactor(tests): 按功能领域重组 Tests/ 目录
Tests/ 根层原有 138 个平铺测试文件,无法从目录读出测试覆盖的功能领域。

按功能领域重组为 17 个目录(Catalog/Workflow 与 Rules/Custom 两处嵌套,分别
对应 App/Application/CatalogWorkflow 与 Domain/Rules/Custom):Architecture /
Support / Agent / Activation / Catalog / Subscription / Rules / ProxyRuntime /
ProxyControl / Runtime / Settings / SystemProxy / Plugin / Diagnostics /
Credentials / Workspace / Servers;Smoke/ 保持独立 target 不动。138 个移动中
132 个是 100% 相似度的纯重命名,其余 6 个在重命名之上带路径反推改写(见下)。

本次不是纯搬移:测试代码比生产代码多一层位置耦合,有 7 处用固定层数的
deletingLastPathComponent() 从 #filePath 反推仓库路径(都假定文件就在 Tests/
根层)。这 7 处改走新增的 Tests/Support/TestSourceTree.swift——从调用点沿父
目录上溯找到含 project.yml 的目录,因此不再依赖父目录层数,以后移动测试文件
也不会静默指错。

配套改动:

- 新增 Tests 布局守卫 TestsLayoutTests,断言 Tests/ 根层无平铺 .swift。比
  Domain 那条弱一档——根层的 Info.plist(info.path 生成物)与
  Fixtures/RuleSnapshots 下的 JSON(folder resource)都必须保留,不能用
  「树下只有 .swift」覆盖。
- project.yml:Smoke target 按文件引用的 Tests/AppArtifact.swift 改指
  Tests/Support/;两处注释里写死的 Tests/SkeletonTests.swift 随移动更新。
  excludes 的裸名 "Smoke" / "Fixtures" 仍匹配 Tests/ 直属子目录,无需改动。
- README 的 Tests 条目展开为目录说明,并修掉 Domain 条目里写死的
  Tests/SkeletonTests.swift。
- 顺带删去 DomainLayoutTests 文档注释里「整理前 62 个文件」这类易漂移的数字。

验证:xcodegen generate 后单测 target 为 139 个源文件(全部非 Smoke 文件,0 个
Smoke 文件混入)且仍以 Fixtures/RuleSnapshots 为资源,Smoke target 为 8 个
Smoke 文件加 AppArtifact;依赖路径反推的 6 个测试类全绿(路径指错即失败);
task format 未改写任何被移动文件;task lint 与整理前同为 21 条内容型 warning;
build 0 error;task test 1025 用例全通过(整理前 1024,+1 为新守卫);
TestsLayoutTests 经变异验证(根层投放探针即失败);packaging-gate ALL CHECKS
PASSED。
2026-10-05 20:37:35 +08:00
Qiu Yuzhou a31e2fa4bf docs(adr): 记录源码目录即分层与主题及守卫约定
App/ 按分层、Domain/ 按主题组织,两个根层只放子目录、不放平铺文件;边界由
Tests/SkeletonTests.swift 的守卫正面圈定断言,而不是禁令加豁免登记。

ADR-0029 只记录组织原则本身:分层与主题划分的依据(Domain 主题名取自
GLOSSARY.md 的章节划分)、四条被否决的备选(平铺加豁免登记、feature-first、
Domain 照搬分层、守卫锁定目录集合),以及两条在代码里不可见的 XcodeGen
约束和跨进程契约按文件引用的代价。

ADR 不维护目录与文件清单——清单由 ShadowsocksX-NG2/README.md 的工程结构
一节维护,避免记录随事实漂移。

project.yml 的两处分层注释与 README 的工程结构一节各加一处引用:前者按该
文件既有写法引用编号,后者用完整链接。
2026-10-05 20:27:11 +08:00
Qiu Yuzhou 856d6b4272 refactor(domain): 按主题重组 Domain/ 源码目录
Domain/ 根目录原有 62 个平铺源文件,无法从目录读出主题划分。

按「目录即主题」重组为 11 个目录(Rules/Custom 为嵌套子目录):Catalog /
Subscription / Rules / Runtime / Activation / Settings / SystemProxy /
Plugin / Credentials / LegacyImport / Diagnostics。纯移动:类型名、模块名
与 import 均未改动,Domain/ 根下不再有散落文件。目录口径取自
GLOSSARY.md 的章节划分(配置与订阅、代理规则、代理控制与网络、设置、
凭据与诊断),而非新造分类。

配套改动:

- project.yml:wrapper 与 helper 两个 target 按文件引用的 15 条显式路径
  随目录改名,并补注释固定这一约定——这 15 条指向不存在的文件时,
  xcodegen generate 以 "missing source directory" 直接失败(实测,不静默)。
- SkeletonTests 新增 DomainLayoutTests:断言 Domain/ 根下无平铺 .swift、
  树下只有 .swift。后者防的是与 App/ 同源的坑——Domain/ 整目录是 app 与
  Core 的 source path,任何非源码文件都会被 XcodeGen 收进 Resources 阶段
  并封进签名后的 bundle。
- README 工程结构说明同步;docs/design 与 docs/research 属历史文档不改。

验证:xcodegen generate 后 app 164 / Core 163 源文件数与整理前一致;Agent
恰好 9 个、Helper 恰好 6 个 Domain 文件(无缺失无多出);app 与 Core 各覆盖
全部 62 个。clean build 0 error;task test 1024 用例全通过(整理前 1022,
+2 为新增守卫);task format 未改写任何被移动文件(证明纯移动);task lint
与整理前同为 21 条内容型 warning;packaging-gate.sh ALL CHECKS PASSED。

布局守卫已做变异验证:临时投放松散 .swift 与非 .swift 文件时两个用例均
失败并点名违规文件,清理后复验为绿。
2026-10-05 20:13:35 +08:00
Qiu Yuzhou fb428f12bc refactor(app): 按分层重组 App/ 源码目录
App/ 根目录原有 73 个散落源文件,已无法从目录读出任何分组信息。

按「目录即分层」重组为 Composition / Application / Presentation / UI /
PlatformEffects / Resources 六个目录,UI 层再按子视图分目录(Workspace、
Home、Servers(含 Plugin)、Subscriptions、Rules、Settings、Diagnostics、
StatusMenu)。纯移动:类型名、模块名与 import 均未改动,App/ 根层不再有
散落文件。

配套改动:

- project.yml:Core 测试镜像的 excludes 由裸文件名改为 `**/` 递归形式。
  XcodeGen 的 exclude 不跨 `/`,裸名只匹配 App 根层;MainApp.swift 下移后
  旧写法会静默失效,把 @main 组合根编进测试镜像。info.path 与
  entitlements.path 指向 App/Resources/;并排除 `**/*.md`——App/ 下任何
  非源码文件都会被 XcodeGen 收进 Resources 阶段并封进签名后的 bundle。
- SkeletonTests 的架构守卫由「默认扫描全部 App/ + 7 个豁免文件 + 1 个豁免
  前缀 + 4 个豁免目录」改为正面圈定 App/UI/,豁免登记全部删除;新增运行时
  适配器放进 Application/ 即自动落在扫描范围外,无需再登记。
- README 工程结构说明同步;根 .gitignore 的生成物路径随 Resources/ 归位。

验证:clean build 0 error;task test 1022 用例全通过(含两个架构守卫);
task format 无改动(证明纯移动);task lint 与移动前同为 21 条内容型
warning;packaging-gate.sh ALL CHECKS PASSED,确认 plist/entitlements 归位
后签名与 entitlements 语义不变。

注意:迁移时须先删旧的生成物再 xcodegen generate,否则遗留的 App/Info.plist
会被当作普通资源扫进 Resources 阶段。
2026-10-05 19:56:18 +08:00
Qiu Yuzhou 6f81b3fd70 Merge branch 'codex/custom-plugin' into develop 2026-10-05 12:05:42 +08:00
Qiu Yuzhou 86779b63ee feat(plugins): add settings management UI 2026-10-05 12:03:52 +08:00
Qiu Yuzhou ca45275810 Merge branch 'codex/custom-plugin' into develop
# Conflicts:
#	ShadowsocksX-NG2/App/Localizable.xcstrings
2026-10-05 11:18:03 +08:00
Qiu Yuzhou 128efcc0d6 feat(plugins): add user plugin catalog and runtime wiring 2026-10-05 00:28:16 +08:00
Qiu Yuzhou 3b3528d232 feat(subscription): show usage and provider dates 2026-10-05 00:10:13 +08:00
Qiu Yuzhou 3aae39799a fix(rules): convert root URL paths to exact domains 2026-10-03 09:56:00 +08:00
Qiu Yuzhou 6e69d92449 feat(rules): convert pathless URL prefixes to exact domains 2026-10-03 09:52:42 +08:00
Qiu Yuzhou a5d96dc990 refactor(rules): keep one conversion path 2026-10-03 02:55:48 +08:00
Qiu Yuzhou fcd5645b68 refactor(rules): slim built-in snapshots 2026-10-03 02:34:04 +08:00
Qiu Yuzhou 851660f1c6 test: split real-process smoke into opt-in target
Real sslocal smoke (11 tests, ~27s) sat on every task test as the
slow tail. Tests/Smoke now builds as a separate target behind the
ShadowsocksX-NG2Smoke scheme; task test:smoke runs it on demand and
the README release gate requires it green next to packaging-gate.

SignalRecorder also gains kill(_, 0) semantics (stale pids report
ESRCH): the GUI-restart test burned the 5s waitForWrapperExit
ceiling on pid 99999, now 0.18s. Default lane: 617 tests ~40s.
2026-09-27 01:11:48 +08:00
Qiu Yuzhou a8cd6262c2 feat(proxy): remove PAC and accept ACL system proxy path
Remove the PAC product feature entirely: PAC HTTP service, port, health
probe, runtime extension, PAC URL system proxy projection, PAC rule
editing, and GFWList URL settings. The product now exposes rule / global /
direct modes only, all projected as a local SOCKS system-proxy target.

First-run defaults are rule + proxyWhenUnmatched, agent on, system proxy
off. Homepage and status menu share one ProxyControlSnapshot showing the
three modes and rule sub-options. Manual servers, subscriptions, Legacy
import, and independent SOCKS/HTTP inbounds are retained.

Fix: include verbose in SslocalListenFingerprint so a verbose-only
contract change restarts sslocal instead of leaving RUST_LOG stale.

Revise CONTEXT.md vocabulary, ADR-0007, and ADR-0009. Record GFWList
exception shadowing, IPv6 system-exception, DNS, and traffic-coverage
boundaries. Add host acceptance evidence document.

Closes #67
2026-09-26 21:58:12 +08:00
Qiu Yuzhou 4a4535b947 feat(proxy): add GFWList proxy candidates for direct-when-unmatched rule mode 2026-09-26 19:20:09 +08:00
Qiu Yuzhou 7a59ca7827 feat(proxy): add China IPv4 CIDR direct candidates to rule mode
Pin gaoyifan/china-operator-ip china.txt and compile its IPv4 CIDRs into
the proxy_all ACL alongside China domain candidates. Explicit maintainer
update normalizes and deduplicates CIDRs and blocks replacement on
abnormal format, corruption, scale change, or all-invalid input.

Closes #64
2026-09-26 18:16:44 +08:00
Qiu Yuzhou 120116627a feat(proxy): add built-in China domain rules and rule mode
Introduce a source-independent rule model (action, domain/CIDR match,
source identity, conflict metadata) and ship a pinned geolocation-cn
snapshot produced by an explicit maintainer update. Rule mode with
proxy-when-unmatched compiles China domains as direct candidates into a
proxy_all ACL; the sub-option is selectable and persisted from home and
the status menu. Ordinary builds only read the local snapshot and fail
when it is missing or corrupt.
2026-09-26 15:25:45 +08:00
Qiu Yuzhou 00fcd61a99 refactor(ng2): change bundle id to ShadowsocksX-NG2
Distinct id from Legacy (com.qiuyuzhou.ShadowsocksX-NG) lets NG2 own
~/Library/Application Support/ShadowsocksX-NG2/ directly; the v2/
subdir prefix is removed from all runtime paths.

- app/agent/tests targets + LaunchAgent plist renamed accordingly
- keychain service, queue labels, and Vendor signIdentifiers follow
  the new bundle id; embedded helpers re-sign at build time
- Legacy handoff/import constants keep pointing at the old id

Migration: dev data under ShadowsocksX-NG/v2/ is not carried over
(fresh catalog/activation); old LaunchAgent registration and old
keychain entries must be cleaned up manually.
2026-09-21 20:33:37 +08:00
Qiu Yuzhou 7bfb90ef5c docs(ng2): reorganize development instructions 2026-09-21 14:42:58 +08:00
Qiu Yuzhou 8578de0ba4 feat(ng2): add PAC runtime and listen scope (#28) 2026-09-20 22:26:45 +08:00
Qiu Yuzhou 6bfd3c0d35 feat(ng2): proxy runtime LaunchAgent, wrapper and sslocal lifecycle (#27)
GUI → LaunchAgent → wrapper → sslocal full chain (spec #21 D2/D5):

- ShadowsocksX-NG2Agent: Swift BundleProgram tool target embedded at
  Contents/MacOS, supervised by launchd via SMAppService agent plist
  (Contents/Library/LaunchAgents, bundle-relative ProgramArguments,
  KeepAlive={SuccessfulExit:false}). Wrapper reads the cross-process
  contract v2/sslocal-active.json, spawns sslocal -c <absolute path>
  and supervises it: SIGTERM chain stop, SIGUSR1 forward for
  server-only changes vs graceful restart on listen fingerprint
  changes, non-zero exit on unexpected child loss for KeepAlive
  replay, invalid/missing contract → clean exit with plain unlink.
- Runtime file protocol: RuntimeFileStore reuses AtomicFileWriter
  (0700 dir self-heal, 0600 temp at creation, atomic replace);
  explicit-stop cleanup unlinks contract, agent pid file and stale
  temporaries. Shared read-side validation via
  SslocalRuntimeDocument.decodeValidated so GUI and wrapper cannot
  drift. Wrapper pid file bridges SMAppService's missing pid.
- GUI: ProxyRuntimeController consumes ActivationStateMachine effects
  through pure ProxyRuntimePlan decision table (ordered actions,
  idempotent skip of identical contract); proxy toggle and launch
  failure presentation (naming endpoint:port) in the status menu;
  launch resync reconciles agent registration, wrapper liveness and
  on-disk contract; catalog commits re-expand immediately.
- Log sanitization baseline: closed RuntimeLogEvent enum plus Redactor,
  wrapper/sslocal output converged to a 0600 agent.log with RUST_LOG
  defaulting to warn.

Tests (126 total, all green): stub-sslocal driven wrapper lifecycle
(start/stop order, SIGTERM chain, crash replay, cleanup, reload
protocol), real sslocal smoke (SOCKS port binding + full SOCKS5
handshake), plan decision table, controller flows with fakes,
runtime file permissions/atomic replace, endpoint probe, redaction.

Manual release-gate items (real launchd/SMAppService): agent
registration approval flow, GUI-quit persistence, bootout behaviors.

Closes #27
2026-09-20 20:26:54 +08:00
Qiu Yuzhou 0cf28c97fe feat(ng2): config catalog domain core with credential refs (#25)
配置目录领域核心(spec #21 D3/D5,票 #25):

- Domain/ 新增配置目录树:单父、显子序、无环;手动/订阅来源严格分离;
  有效启用 = 节点及其全部祖先启用;手动节点携带子树移动与重排;
  非空手动组递归删除(返回被删条目供 Keychain 清理);空组持久保留;
  非法操作(跨来源、身份复用即共享父、成环、订阅节点结构改动、
  订阅服务器直挂根)全部带明确原因拒绝且状态不动。
- 凭据引用:密码/插件参数只在 Keychain 存权威副本,配置树只持
  CredentialReference;KeychainCredentialStore 写读一致、覆盖写、幂等删。
- CatalogFileStore:v2/catalog.json 目录 0700/文件 0600,临时文件原子替换;
  缺失 → 空目录,损坏/版本未知/结构不一致(悬空、共享父、成环含根外孤环、
  不可达)→ 命名明确的 corrupt,结构校验收敛在
  ConfigurationCatalog.validated 工厂。
- 测试 43 项覆盖全部验收项;project.yml 增加 Domain/ 源码目录。
- .swiftlint.yml 关闭 trailing_comma(与 .swift-format 尾逗号基线冲突,
  触发案例见文件内注释),README/AGENTS.md 同步 Domain/ 与工具说明。
2026-09-20 15:22:09 +08:00
Qiu Yuzhou 1b8b1f0767 docs(ng2): move style tool setup from AGENTS.md to README
AGENTS.md keeps only the agent contract: hook enable step, gate
behavior, manual commands, rule-tuning policy. Install steps,
tool baselines, and config rationale are human-facing setup and
now live in README's 代码风格工具 section.

Update stale pointers that sent readers to AGENTS.md for tool
install (root AGENTS.md, pre-commit hook comment and error
message); hook behavior unchanged.
2026-09-20 14:36:35 +08:00
Qiu Yuzhou a20df3001f feat(ng2): external binary supply chain and packaging gate (#24)
Pin sslocal v1.25.0 (aarch64-apple-darwin) and v2ray-plugin v1.3.2 via
committed manifests (tag + asset URL + archive SHA-256 + bundle location +
sign identifier):

- Scripts/fetch-external-binaries.sh downloads the pinned archive, verifies
  its SHA-256 byte-for-byte, extracts only the named member (arm64-only
  check) and stamps the local cache; archive hash mismatch fails hard, and
  any manifest/local-artifact drift forces a re-verified refetch. It re-runs
  as a pre-build phase so tampering fails the build itself.
- project.yml installs both binaries via Copy Files into
  Contents/Helpers[/Plugins]; generate requires the artifacts to exist
  (fetch before generate, else Copy Files phases are silently dropped).
- Scripts/sign-embedded-helpers.sh re-signs each helper Developer ID with
  --options runtime --timestamp and the pinned identifier
  (<bundle-id>[.plugin.]<name>) before Xcode seals the outer app signature.
- Scripts/packaging-gate.sh asserts strict nested signature verification,
  DevID + Hardened Runtime on the app with no App Sandbox entitlement, and
  exact per-binary manifest coverage under Contents/Helpers.
- Tests pin both manifests' schema and anchor hashes.

Verified: build + gate all green; byte-flip, foreign-binary and
missing-binary tampers each caught; 5 unit tests pass; no submodules or
in-repo builds; notarization stays out of scope (#39).
2026-09-20 14:27:21 +08:00
Qiu Yuzhou 3f052e403f feat(ng2): add 2.0 project skeleton and signing baseline (#22)
XcodeGen-managed SwiftUI menu bar app in ShadowsocksX-NG2/: LSUIElement,
inherited bundle id com.qiuyuzhou.ShadowsocksX-NG, macOS 15 arm64,
Hardened Runtime + Developer ID signing, empty entitlements dict (no App
Sandbox; Release disables base entitlement injection). Placeholder status
menu and main window; unit test target wired into the app scheme. Test
bundles sign with the Apple Development cert so Hardened Runtime library
validation accepts injection. Generated .xcodeproj and plists are
gitignored; project.yml is the source of truth. Legacy/ untouched.

Closes #22
2026-09-20 09:00:29 +08:00
Qiu Yuzhou 3a62f473bc chore: restructure repo for modern reimplementation
- Remove GitHub Actions workflows and issue templates
- Move legacy ShadowsocksX-NG project into Legacy/
- Remove git submodules; dependencies will use prebuilt
  binaries copied from upstream releases instead of
  building in-repo
- Add ShadowsocksX-NG2/ directory for the new project
- Update .gitignore paths for the new layout
2026-09-19 22:31:37 +08:00