ctx_cli 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 6757c9c4e28fdbf88436ead17a364fc8dcb7fc2d4fda107654fd278c0d5229c3
4
- data.tar.gz: a727b09657a6b79ab821c2a2f8f899c1d09b248faf659ff288306514c07d0a68
3
+ metadata.gz: b464099a905c64a24b68ae31968fe954f8160ab59ae68edafed68f21164807c8
4
+ data.tar.gz: c08eda04c35fa9360ff72f2a5373a10cc75652e27e9515402da50d3446fdbf56
5
5
  SHA512:
6
- metadata.gz: d0d80afb9a473f4bceff0dc6f0cfbb7b78d2987b8aed673c4b230e1c05086bdbc9f2fa950ee1f54dc95cbfe487f803178ecace433d40ac758257e7b0633c726e
7
- data.tar.gz: ee8af08341391087d93c40df85d61b486346fcfef8c92ee8b675704749e4ad3e4dcededc8126edadb7d52fc1d82190725fa1e1774c6604cd36124c6c9f938c6e
6
+ metadata.gz: 56034b19ee9105f545279e0c01dabf52108269c646553a37bc15a21c5e6624c4a090905314ab93dfd54840312483497586bfe0dd668fc5eefa942e907803a288
7
+ data.tar.gz: 681f69619a054508d607106a3791b05515041f6ccddae9edce3129815128c434059d34df43574b059a0ad1a434be6afe228ac1e63c993f3bc64346e4f7ea9792
data/CHANGELOG.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ## 0.4.0 (2026-10-29)
6
+
7
+ - Add an injected Apply entry point for checksummed plans, explicit item selection, interactive confirmation and safe failure reporting, without domain, runner or connector dependencies.
8
+
9
+ ## 0.3.0 (2026-10-24)
10
+
11
+ - Use JSON Pointer keys in configuration field provenance, separating literal dots, slashes, tildes, empty keys and nested mappings.
12
+ - Remove only actual descendant sources when a mapping is replaced; preserve array replacement and empty-mapping merge behavior.
13
+ - Breaking change: sources.fields and host --show-config output no longer expose dotted-path aliases; migrate field lookups to JSON Pointer.
14
+
5
15
  ## 0.2.1 (2026-10-23)
6
16
 
7
17
  - Use English command help, prompts and collection/review diagnostics.
data/README.md CHANGED
@@ -53,6 +53,8 @@ files.environment # .env 加原进程环境;不修改 ENV
53
53
  files.sources # 路径与字段来源,不包含环境值
54
54
  ```
55
55
 
56
+ `sources["fields"]` 使用 JSON Pointer 作为字段键,例如 `/parallel`、`/ssh/known_hosts`。字面键 `a.b` 对应 `/a.b`,嵌套 `a → b` 对应 `/a/b`;键内 `/` 编为 `~1`、`~` 编为 `~0`。数组作为整体字段记录来源。宿主的 `path_fields` 声明语法不变,来源索引不保留点分键别名。
57
+
56
58
  默认依次搜索 `/etc/<namespace>`、`/usr/local/etc/<namespace>`、`$XDG_CONFIG_HOME/<namespace>`(否则 `~/.config/<namespace>`)、入口目录和启动目录。每层读取 `<namespace>.yml` 与 `<name>.yml`,显式文件最后。共享文件按 `common` 和工具名称分区;name 与 namespace 相同时使用普通独立文件。`directories:` 可以完整替换搜索范围。
57
59
 
58
60
  宿主把各层公共环境值转换成领域字段后,通过 `Configuration.merge(defaults, dotenv_values, yaml, process_values, cli)` 实现 CLI > 进程环境 > YAML > .env > 默认值。数组整层替换,false/nil 保留。相对路径按来源目录解释;支持 `path_literals:`(如 `system`)和 URI。`load` 重复调用不重新读文件。
@@ -73,7 +75,7 @@ Options 协作者沿用现有入口协议:`informational?`、`validate_interac
73
75
  bundle install
74
76
  bundle exec rake
75
77
  bundle exec rake build
76
- ruby script/verify_package.rb pkg/ctx_cli-0.2.1.gem
78
+ ruby script/verify_package.rb pkg/ctx_cli-0.4.0.gem
77
79
  ```
78
80
 
79
81
  默认任务包括 RSpec、RuboCop 和离线示例。安装验证在独立 GEM_HOME/GEM_PATH 下运行普通与最小 Bundler 应用,检查实际加载来源。CI 参照 ctx_parser 的固定 action 提交和候选制品校验;发布需另行明确授权。
@@ -92,3 +94,5 @@ Input reads default to a 16 MiB byte budget (`CtxCli::Input.read(max_bytes:)`).
92
94
  失败只输出异常类型,返回 2;中断返回 130;诊断流失败不覆盖原始退出码。帮助不加载证据或调用适配器。此类不读取凭据、连接设备或判断业务健康。默认单文件 16 MiB、批次原始正文总计 64 MiB、文件数 10000;宿主可通过 `max_bytes:`、`max_total_bytes:`、`max_files:` 调整。JSON 默认嵌套限制保持开启;上述限制不是进程 RSS 的精确上限。
93
95
 
94
96
  `Collection` 对普通参数/依赖异常只显示类型;宿主需要公开操作提示时使用 `CtxCli::Collection::Error`,其正文必须由宿主构造,不得直接包装外部异常正文、凭据或设备回显。该类型继承 ArgumentError,既有库调用方仍可按参数错误捕获。
97
+
98
+ `CtxCli::Apply` 负责版本计划的校验和、`--item` 选择、终端确认及退出码;通过 `adapter:` 和 `execution:` 注入领域校验、凭据、会话、日志及执行器。ctx_cli 不依赖 ctx_runner 或连接器。
data/docs/migration.md CHANGED
@@ -17,4 +17,14 @@ ctx_cli 初始版本为 0.1.0。首次发布依赖顺序先 ctx_cli,再 net-co
17
17
  - `CtxCli::Initialization` / `ctx_cli/initialization` 改为 `CtxCli::Initializer` / `ctx_cli/initializer`,仅负责模板安全发布。
18
18
  - `CtxCli::Application` / `ctx_cli/application` 改为 `CtxCli::Router` / `ctx_cli/router`,仅负责全局信息和子命令分发。
19
19
 
20
- 旧常量和 require 路径不保留别名。宿主需同步修改引用,并将 ctx_cli 依赖更新为 `~> 0.2.0`。`create`、`existing?`、`run` 的结果约定不变;初始化参数询问和厂商语义不迁入这两个对象。0.2.0 当前为本地候选,尚未发布。
20
+ 旧常量和 require 路径不保留别名。宿主需同步修改引用,并在应用锁文件中选择包含新接口的 ctx_cli 版本。`create`、`existing?`、`run` 的结果约定不变;初始化参数询问和厂商语义不迁入这两个对象。这些名称从 0.2.0 起使用。
21
+
22
+ ## 0.3.0 配置来源字段
23
+
24
+ `Configuration#sources["fields"]` 的键统一使用 [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901):`parallel` 改为 `/parallel`,`ssh.port` 的嵌套路径改为 `/ssh/port`。字面键 `ssh.port` 则为 `/ssh.port`,两者拥有独立来源。空键为 `/`;每段中的 `~` 编为 `~0`,`/` 编为 `~1`,不作 Unicode 归一化。
25
+
26
+ 来源值仍是 YAML 文件路径;数组整体替换,来源记在数组字段上。空映射合并不覆盖既有非空映射的来源。宿主透传的 `--show-config` 同步采用此结构;外部来源索引调用方须迁移键查找,不提供点分键回退或格式开关。`path_fields` 仍是宿主声明哪些字段要解析为文件路径的独立语法。
27
+
28
+ ## 0.4.0 Apply
29
+
30
+ VXLAN/Wireless 的交互执行入口组合 `CtxCli::Apply`;宿主注入 adapter 和 execution 协作者,领域命令和会话仍由宿主维护。统一要求具名 `--item`、plan.json.sha256 和绑定设备/摘要/所选项的终端确认,取消为 1、预检或执行失败为 2、中断为 130。ctx_cli 自身不加载 Runner 或连接器。
@@ -0,0 +1,46 @@
1
+ # Configuration Source Paths Implementation Plan
2
+
3
+ > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
4
+
5
+ **Goal:** Give every merged configuration field an unambiguous source identity.
6
+
7
+ **Architecture:** Configuration emits JSON Pointer keys in sources.fields. Existing hosts forward the source map unchanged; their tests and documentation migrate together. No new abstraction or alternate format.
8
+
9
+ **Tech Stack:** Ruby, YAML, RSpec/Minitest, Bundler.
10
+
11
+ **Spec:** `docs/superpowers/specs/2026-10-24-configuration-source-paths.md`
12
+
13
+ ## Global Constraints
14
+
15
+ - Ruby >= 3.4; no dependency or version-policy change.
16
+ - lib method comments Chinese; business literals English.
17
+ - Preserve WIP, no commit/push/release.
18
+ - Preserve merge semantics, source-relative paths and domain ownership.
19
+ - JSON Pointer applies to sources.fields only; no dot-path aliases.
20
+
21
+ ## Review Focus
22
+
23
+ - Literal dots/slashes cannot collide with nesting.
24
+ - Tilde escape order preserves literal ~1 and ~0.
25
+ - Empty keys and Unicode keys retain exact identity without normalization.
26
+ - Replacing a parent removes only its actual descendant sources.
27
+ - Arrays and empty mappings keep their existing merge/source semantics.
28
+
29
+ ### Task 1: Replace ambiguous source keys and migrate consumers
30
+
31
+ **Files:**
32
+ - Modify ctx_cli: `lib/ctx_cli/configuration.rb`, `spec/configuration_spec.rb`, `README.md`, `docs/migration.md`, `CHANGELOG.md`.
33
+ - Create ctx_cli: this plan and its spec.
34
+ - Modify VXLAN: `spec/cli/configuration_sources_spec.rb`.
35
+ - Modify Wireless: `spec/cli/options_spec.rb`.
36
+ - Modify net-connector: `test/config_test.rb`, `test/cli_setup_test.rb`.
37
+
38
+ **Interfaces:**
39
+ - Consumes: validated string-keyed YAML mappings and previous merged mapping.
40
+ - Produces: `Configuration#sources["fields"]` mapping from JSON Pointer to file path, deeply frozen; examples `/parallel`, `/ssh/port`, `/a.b`, `/a~1b`, `/m~0n`, `/`.
41
+
42
+ - [x] **Step 1:** Add real layered-YAML regressions for colliding literal and nested keys, parent replacement, escaped tokens, empty/Unicode keys, arrays and nil/false. Migrate existing source expectations to pointer keys.
43
+ - [x] **Step 2:** Run `bundle exec rspec spec/configuration_spec.rb`; expect RED from dot-path collisions or missing pointer keys.
44
+ - [x] **Step 3:** Change `record_fields` prefix construction to escaped slash tokens and descendant removal to slash-separated prefixes. Keep all merge and ownership logic. Update consumer source-key assertions and docs; no compatibility branch.
45
+ - [x] **Step 4:** Run ctx_cli default rake, consumer targeted tests and complete gates in isolated worktrees. Run the existing three-size benchmark before/after; verify same configuration/source counts. Expect green gates and no return to quadratic leaf scans.
46
+ - [x] **Step 5:** One independent final review. Guard-copy only listed files into actual checkouts, validate ordinary consumer gates using exact installed CLI candidate, and run plain/Bundler installed source/preview probes. Compare all package metadata/source bytes. Keep uncommitted work and evidence; mark all steps only with passing receipts.
@@ -0,0 +1,27 @@
1
+ # Configuration 来源身份
2
+
3
+ ## 问题与选择
4
+
5
+ Configuration 合并结果允许任意字符串键,但来源索引把层级拼为点分字符串。字面键 `a.b` 和嵌套 `a → b` 共享索引;用标量替换映射 `a` 时,前缀删除还会误删字面键的来源。这使 `--show-config` 的来源与实际配置不一致。
6
+
7
+ 使用 [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901) JSON Pointer 表达 `sources["fields"]` 的键。每层以 `/` 分隔;token 内 `~` 编为 `~0`,`/` 编为 `~1`。字面点不转义,空键使用 `/`。只生成指针,不增加求值器或依赖。来源值仍为文件路径,不含配置值。
8
+
9
+ 拒绝含点的合法键会人为限制宿主数据;自定义点转义会新增不必要的语法。采用标准指针统一迁移,不保留点分别名或旧格式选择。
10
+
11
+ ## 不变量与职责
12
+
13
+ - 合并、来源相对路径、数组替换、false/nil/缺失、空映射合并语义保持不变。
14
+ - 来源索引的叶子/祖先替换必须与实际合并一致;兄弟字面键不能被前缀删除。
15
+ - 数组是整体替换值,在数组字段指针上记录来源,不逐元素建表;空映射作为值时也记录其字段。
16
+ - `path_fields` 是宿主声明路径字段的既有语法,和来源输出不同,不在此阶段改变。
17
+ - 库保持 Ruby >= 3.4,不依赖 Runner/Parser/connector;lib 方法说明中文、业务字面量英文。
18
+ - VXLAN/Wireless/connector 仍透传来源结构;其领域校验、命令、状态与资源所有权不迁移。
19
+ - 保留所有既有 WIP 和当前依赖政策,不提交、推送或发布。
20
+
21
+ ## 范围
22
+
23
+ 11 个文件:ctx_cli 的 configuration.rb、configuration_spec.rb、README、migration、Changelog、本规格及计划;VXLAN/Wireless 各一个参数来源测试;connector 的 config_test 和 cli_setup_test。没有新增配置项或生产适配器。
24
+
25
+ ## 验收
26
+
27
+ 回归从真实 YAML 层证明字面点与层级不同、slash/tilde/空键/Unicode 不碰撞、替换映射只删除真正后代、数组整体替换、冻结及不含秘密值。先观察旧实现失败,再修改来源键构造与后代前缀。迁移消费端断言后运行四模块 gates、实际入口和精确候选普通/Bundler 安装。使用既有 500/1000/3000 字段基准检查规模趋势,不为共享主机设硬性能阈值。一次独立审查,无双格式接口。
@@ -0,0 +1,92 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+ require "json"
5
+ require_relative "command"
6
+ require_relative "configuration"
7
+ require_relative "terminal"
8
+ require_relative "input"
9
+ require_relative "output"
10
+
11
+ module CtxCli
12
+ # 单项交互变更的终端入口;领域校验与会话、执行账本均通过显式协作者提供。
13
+ class Apply
14
+ def initialize(adapter:, execution:, name:, out: $stdout, error: $stderr, input: $stdin)
15
+ @adapter, @execution_class, @name = adapter, execution, name
16
+ @out, @error, @input = out, error, input
17
+ @output = Output.new(out: out, error: error)
18
+ end
19
+
20
+ def run(argv)
21
+ @execution = nil
22
+ command = options
23
+ values = command.parse(argv)
24
+ return 0 if command.informational?
25
+ terminal = Terminal.new(input: @input, out: @out)
26
+ terminal.require_tty!(@error)
27
+ unless values[:plan] && values[:item] && values[:port].between?(1, 65_535)
28
+ raise ArgumentError, "A plan and explicit --item are required"
29
+ end
30
+ body = Input.read(path: values[:plan])
31
+ sha256 = Digest::SHA256.hexdigest(body)
32
+ unless Input.read(path: "#{values[:plan]}.sha256", max_bytes: 128).strip == sha256
33
+ raise ArgumentError, "Plan checksum verification failed"
34
+ end
35
+ # 外部领域回调不能改变刚验证的计划、选择或连接参数。
36
+ values = Configuration.freeze_tree(Configuration.copy(values))
37
+ document = Configuration.freeze_tree(Configuration.copy(JSON.parse(body)))
38
+ plan = Configuration.freeze_tree(Configuration.copy(@adapter.select_plan(document, item: values[:item])))
39
+ change = @adapter.validate_plan(plan)
40
+ host = plan.fetch("device").fetch("host")
41
+ @out.puts "Target: #{plan['device']['name']}(#{host}); #{plan['scope']}; #{plan['title']}"
42
+ @out.puts "Impact: #{plan['impact']}"
43
+ @out.puts Array(plan["prerequisites"]).map { |value| "Prerequisite: #{value}" }
44
+ @out.puts "Plan SHA256: #{sha256}\nProposed commands:\n#{change.commands.join("\n")}\nConditional rollback (not executed automatically):\n#{change.rollback.join("\n")}"
45
+ token = "APPLY #{host} #{sha256[0, 12]} #{values[:item]}"
46
+ unless terminal.confirm(token: token, prompt: "After reviewing the service policy and maintenance window, enter #{token}; any other input cancels: ")
47
+ @out.puts "Cancelled; no device connection opened."
48
+ return 1
49
+ end
50
+ settings = @adapter.credentials(values)
51
+ journal = @adapter.report(values)
52
+ @execution = @execution_class.new(plan: plan, change: change, journal: journal, plan_sha256: sha256, item: values[:item])
53
+ @execution.run { |operation| @adapter.with_session(plan.fetch("device"), settings, &operation) }
54
+ @out.puts "Configuration readback confirmed; service acceptance is still required. Configuration was not saved to startup configuration. Log: #{journal.directory}/execution.json"
55
+ 0
56
+ rescue Interrupt
57
+ failure("Operation interrupted")
58
+ 130
59
+ rescue StandardError, LoadError => error
60
+ failure("Apply stopped (#{error.class.name})")
61
+ 2
62
+ end
63
+
64
+ def inspect = "#<#{self.class.name}>"
65
+ alias to_s inspect
66
+ def pretty_print(printer) = printer.text(inspect)
67
+
68
+ private
69
+
70
+ def options
71
+ Command.new(banner: "Usage: #{@name} apply --plan FILE --item ID [--env-file FILE] (interactive confirmation required)",
72
+ defaults: { directory: File.join(Dir.pwd, "#{@name}-executions"), port: 22 }, out: @out) do |parser, values|
73
+ parser.on("--plan FILE", "Versioned plan with an adjacent .sha256 checksum") { |value| values[:plan] = value }
74
+ parser.on("--item ID", "Explicitly select one change") { |value| values[:item] = value }
75
+ parser.on("--env-file FILE", "Credentials file; process environment takes precedence") { |value| values[:env_file] = value }
76
+ parser.on("--directory DIR", "Private execution journal directory") { |value| values[:directory] = value }
77
+ parser.on("--port N", Integer, "SSH port, default 22") { |value| values[:port] = value }
78
+ parser.on("-h", "--help", "Show help") { values[:help] = true }
79
+ end
80
+ end
81
+
82
+ def failure(message)
83
+ if @execution&.journal_failed?
84
+ @output.diagnostic "Execution log finalization is unconfirmed; existing checkpoints retained."
85
+ end
86
+ detail = @execution&.started? ? "Effects are uncertain; read back before proceeding. Do not replay commands." : "No service configuration was sent."
87
+ @output.diagnostic "#{message}; #{detail}"
88
+ rescue Interrupt
89
+ nil
90
+ end
91
+ end
92
+ end
@@ -341,9 +341,10 @@ module CtxCli
341
341
  self.class.merge(previous, resolved)
342
342
  end
343
343
 
344
- def record_fields(document, source, fields, prefix = nil, previous: {})
344
+ # 用 JSON Pointer 区分字面键与层级,只移除被替换映射的真正后代来源。
345
+ def record_fields(document, source, fields, prefix = "", previous: {})
345
346
  document.each do |key, value|
346
- name = [ prefix, key ].compact.join(".")
347
+ name = "#{prefix}/#{key.gsub("~", "~0").gsub("/", "~1")}"
347
348
  before = previous.is_a?(Hash) ? previous[key] : nil
348
349
  next if value.is_a?(Hash) && value.empty? && before.is_a?(Hash) && !before.empty?
349
350
 
@@ -353,7 +354,7 @@ module CtxCli
353
354
  else
354
355
  # 只有旧映射被整体替换才需要删除后代;新增/覆盖叶子直接赋值。
355
356
  if before.is_a?(Hash) && !before.empty?
356
- descendant_prefix = "#{name}."
357
+ descendant_prefix = "#{name}/"
357
358
  fields.delete_if { |field, _| field.start_with?(descendant_prefix) }
358
359
  end
359
360
  fields[name] = source
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module CtxCli
4
- VERSION = "0.2.1"
4
+ VERSION = "0.4.0"
5
5
  end
data/lib/ctx_cli.rb CHANGED
@@ -11,3 +11,4 @@ require_relative "ctx_cli/input"
11
11
  require_relative "ctx_cli/output"
12
12
  require_relative "ctx_cli/collection"
13
13
  require_relative "ctx_cli/review"
14
+ require_relative "ctx_cli/apply"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ctx_cli
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.1
4
+ version: 0.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Gatework contributors
@@ -23,6 +23,20 @@ dependencies:
23
23
  - - ">="
24
24
  - !ruby/object:Gem::Version
25
25
  version: '0'
26
+ - !ruby/object:Gem::Dependency
27
+ name: digest
28
+ requirement: !ruby/object:Gem::Requirement
29
+ requirements:
30
+ - - ">="
31
+ - !ruby/object:Gem::Version
32
+ version: '0'
33
+ type: :runtime
34
+ prerelease: false
35
+ version_requirements: !ruby/object:Gem::Requirement
36
+ requirements:
37
+ - - ">="
38
+ - !ruby/object:Gem::Version
39
+ version: '0'
26
40
  - !ruby/object:Gem::Dependency
27
41
  name: fileutils
28
42
  requirement: !ruby/object:Gem::Requirement
@@ -117,9 +131,12 @@ files:
117
131
  - LICENSE
118
132
  - README.md
119
133
  - docs/migration.md
134
+ - docs/superpowers/plans/2026-10-24-configuration-source-paths.md
135
+ - docs/superpowers/specs/2026-10-24-configuration-source-paths.md
120
136
  - examples/configuration.rb
121
137
  - examples/offline.rb
122
138
  - lib/ctx_cli.rb
139
+ - lib/ctx_cli/apply.rb
123
140
  - lib/ctx_cli/collection.rb
124
141
  - lib/ctx_cli/command.rb
125
142
  - lib/ctx_cli/configuration.rb