pwn 0.5.783 → 0.5.785

data/lib/pwn/migrate.rb

@@ -4,6 +4,9 @@ require 'json'
 require 'yaml'
 require 'fileutils'
 require 'time'
+require 'digest'
+require 'find'
+require 'securerandom'
 
 module PWN
   # PWN::Migrate — the ~/.pwn state **doctor** and **auto-migrator**.
@@ -49,7 +52,7 @@ module PWN
     # Bump this whenever the shape of any file under ~/.pwn changes in a
     # way that requires a one-time transform.  Add the transform as an
     # entry in MIGRATIONS keyed by the NEW schema number.
-    SCHEMA_VERSION = 10
+    SCHEMA_VERSION = 12
 
     OK   = "\e[32mok\e[0m"
     BAD  = "\e[31mFAIL\e[0m"
@@ -81,7 +84,7 @@ module PWN
 
           enc = PWN::Plugins::Vault.file_encrypted?(file: p)
           # Shape (missing keys vs env_template) is checked separately in
-          # .vault_drift because it requires the decryptor.
+          # .vault_drift because it requires access to the legacy key or YubiKey.
           { ok: enc, why: enc ? nil : 'not encrypted (run PWN::Plugins::Vault.create)' }
         }
       },
@@ -242,33 +245,41 @@ module PWN
         File.write(path, YAML.dump(raw))
         io.puts "    · agents.yml added default model to #{patched} personas"
       },
-      4 => lambda { |_root, io|
+      4 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml ai_sandbox, ai_router, model_routes task classes'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
       },
-      5 => lambda { |_root, io|
+      5 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml ai.agent.skill_review'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
       },
-      6 => lambda { |_root, io|
+      6 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml ai.tui.theme'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
       },
-      7 => lambda { |_root, io|
+      7 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml ai.tui.theme.title'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
       },
       8 => lambda { |_root, io|
         io.puts '    · guarded session_cleanup default cron payload and job'
         PWN::Cron.install_defaults
       },
-      9 => lambda { |_root, io|
+      9 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml plugins.meshtastic.channel short_name'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
       },
-      10 => lambda { |_root, io|
+      10 => lambda { |_root, io, vault_opts = {}|
         io.puts '    · pwn.yaml ai reasoning_effort for anthropic, gemini, ollama, openwebui'
-        PWN::Migrate.backfill_vault(io: io)
+        PWN::Migrate.backfill_vault(vault_opts.merge(io: io))
+      },
+      11 => lambda { |_root, io|
+        io.puts '    · versioned housekeeping policy and managed session_cleanup helper'
+        PWN::Cron.install_defaults
+      },
+      12 => lambda { |root, io|
+        io.puts '    · global seven-folder recovery policy; legacy relocation remains explicit'
+        PWN::Backups.configure(root: File.join(root, 'backup'))
       }
     }.freeze
 
@@ -302,14 +313,15 @@ module PWN
     end
 
     # Supported Method Parameters::
-    # rows = PWN::Migrate.status
+    # rows = PWN::Migrate.status(pwn_env_path: 'optional - Selected configuration vault path')
     #
     # Per-file compatibility report — the machine-readable half of
     # `.check`.  Never writes.  Never raises (each verifier is rescued).
 
-    public_class_method def self.status
+    public_class_method def self.status(opts = {})
+      selected_vault = opts[:pwn_env_path] || vault_paths[:file]
       files = STATE_FILES.map do |rel, meta|
-        path = File.join(PWN_ROOT, rel)
+        path = meta[:kind] == :vault ? selected_vault : File.join(PWN_ROOT, rel)
         exists = meta[:kind] == :dir ? File.directory?(path) : File.file?(path)
         raw = exists && meta[:kind] != :dir ? safe_read(path: path) : nil
         v = verify_one(path: path, raw: raw, meta: meta)
@@ -378,19 +390,25 @@ module PWN
     # and decryptor available)  5. stamp .schema.
 
     public_class_method def self.run(opts = {})
+      return PWN::Backups.transaction(root: BACKUP_ROOT) { run(opts) } unless opts[:dry_run] || PWN::Backups.active?
+
       fix     = opts[:fix] ? true : false
       dry_run = opts[:dry_run] ? true : false
       backup  = opts.fetch(:backup, true)
       io      = opts[:io] || $stdout
 
-      FileUtils.mkdir_p(PWN_ROOT)
-      before = status
+      FileUtils.mkdir_p(PWN_ROOT) unless dry_run
+      before = status(pwn_env_path: opts[:pwn_env_path])
       io.puts "PWN::Migrate — pwn #{before[:pwn_version]} · ~/.pwn schema " \
               "#{before[:schema_installed]} → #{before[:schema_current]}" \
               "#{'  (dry-run)' if dry_run}"
 
+      vault_opts = { key: opts[:key], iv: opts[:iv], yubikey: opts[:yubikey], pwn_env_path: opts[:pwn_env_path], pwn_dec_path: opts[:pwn_dec_path] }
+      drift = fix ? vault_drift(vault_opts) : nil
+      changes = before[:schema_installed] < SCHEMA_VERSION ||
+                (fix && (!before[:incompatible].empty? || (drift && !drift[:missing].empty?)))
       bpath = nil
-      if backup && !dry_run && File.directory?(PWN_ROOT)
+      if backup && changes && !dry_run && File.directory?(PWN_ROOT)
         bpath = backup!
         io.puts "  backup   : #{bpath}"
       end
@@ -402,7 +420,9 @@ module PWN
         next unless m
 
         io.puts "  migrate  : v#{n - 1} → v#{n}"
-        m.call(PWN_ROOT, io) unless dry_run
+        unless dry_run
+          m.arity == 2 ? m.call(PWN_ROOT, io) : m.call(PWN_ROOT, io, vault_opts)
+        end
         applied << n
       end
 
@@ -418,13 +438,13 @@ module PWN
 
         # pwn.yaml key backfill runs even when the vault verifier passed —
         # "encrypted" ≠ "has every key this release added".
-        vd = backfill_vault(key: opts[:key], iv: opts[:iv], dry_run: dry_run, io: io)
+        vd = backfill_vault(vault_opts.merge(dry_run: dry_run, io: io))
         fixed << vd if vd && vd[:added].to_i.positive?
       end
 
-      stamp! unless dry_run
+      stamp! if !dry_run && changes
 
-      after = status
+      after = status(pwn_env_path: opts[:pwn_env_path])
       io.puts
       io.puts "  result   : #{after[:incompatible].length} incompatible remaining " \
               "(was #{before[:incompatible].length}) · schema now #{after[:schema_installed]}"
@@ -442,16 +462,15 @@ module PWN
     #
     # Deep-diff the user's decrypted pwn.yaml against the current
     # PWN::Config.env_template.  → { missing: [dotted.paths], user: {…} }
-    # Returns nil when the decryptor is unavailable (never prompts).
+    # Returns nil when vault access is unavailable (never prompts).
 
     public_class_method def self.vault_drift(opts = {})
-      key, iv = decryptor(opts)
-      return nil unless key && iv
-
-      yaml = File.join(PWN_ROOT, 'pwn.yaml')
+      paths = vault_paths(opts)
+      yaml = paths[:file]
       return nil unless File.file?(yaml) && PWN::Plugins::Vault.file_encrypted?(file: yaml)
 
-      user = PWN::Plugins::Vault.dump(file: yaml, key: key, iv: iv)
+      access = PWN::Plugins::Vault.access_options(paths.merge(key: opts[:key], iv: opts[:iv], yubikey: opts[:yubikey]))
+      user = PWN::Plugins::Vault.dump(access.merge(file: yaml))
       tmpl = env_template
       { missing: missing_paths(tmpl: tmpl, user: user), user: user, template: tmpl }
     rescue StandardError
@@ -464,7 +483,7 @@ module PWN
     # )
     #
     # Decrypt → deep-merge template UNDER user (never overwrites) →
-    # re-encrypt with the SAME key/iv.  This is the fix for the #1
+    # re-encrypt with the SAME legacy key/iv or hardware selector. This fixes the
     # upgrade break: `NoMethodError: undefined method '[]' for nil` when
     # a release added `env[:ai][:new_engine][:…]` and the user's vault
     # predates it.
@@ -472,9 +491,9 @@ module PWN
     public_class_method def self.backfill_vault(opts = {})
       io      = opts[:io] || $stdout
       dry_run = opts[:dry_run] ? true : false
-      d = vault_drift(key: opts[:key], iv: opts[:iv])
+      d = vault_drift(opts)
       unless d
-        io.puts '  vault    : skipped (no decryptor available — run with --pwn-dec or set key:/iv:)'
+        io.puts '  vault    : skipped (vault access unavailable — check YubiKey or legacy decryptor/key/IV)'
         return nil
       end
       if d[:missing].empty?
@@ -487,13 +506,10 @@ module PWN
       io.puts "             … (+#{d[:missing].length - 8} more)" if d[:missing].length > 8
       return { rel: 'pwn.yaml', added: d[:missing].length, missing: d[:missing], dry_run: true } if dry_run
 
-      merged = deep_defaults(user: d[:user], tmpl: d[:template])
-      yaml   = File.join(PWN_ROOT, 'pwn.yaml')
-      key, iv = decryptor(opts)
-      # Same colon-stripping default_env uses so the file stays diff-clean.
-      File.write(yaml, YAML.dump(merged).gsub(/^(\s*):/, '\1'))
-      File.chmod(0o600, yaml)
-      PWN::Plugins::Vault.encrypt(file: yaml, key: key, iv: iv)
+      access = vault_paths(opts).merge(key: opts[:key], iv: opts[:iv], yubikey: opts[:yubikey])
+      PWN::Plugins::Vault.update(access) do |user|
+        user.replace(deep_defaults(user: user, tmpl: d[:template]))
+      end
 
       { rel: 'pwn.yaml', added: d[:missing].length, missing: d[:missing] }
     rescue StandardError => e
@@ -612,19 +628,74 @@ module PWN
       "dropped #{bad} bad line(s), kept #{good.length}"
     end
 
+    # Supported Method Parameters::
+    # PWN::Migrate.prune_backups(dry_run: true)
+    # Retention now runs only at shared producer admission, never separately.
+    public_class_method def self.prune_backups(opts = {})
+      { eligible: [], deleted: [], retained: [], incomplete: false,
+        dry_run: opts.fetch(:dry_run, true), keep: PWN::Backups::LIMIT,
+        scope: 'global', retention: 'shared_producer_admission' }
+    end
+
+    private_class_method def self.backup_input_names
+      (STATE_FILES.keys.map { |rel| rel.delete_suffix('/') } + %w[.schema pwn.yaml.decryptor]).uniq.reject { |rel| %w[sessions swarm].include?(rel.split('/').first) }
+    end
+
+    private_class_method def self.backup_inventory(opts = {})
+      path = opts[:path]
+      admission = opts[:admission]
+      names = opts[:names]
+      raise IOError, 'Unsafe backup directory' unless File.realpath(path) == path && File.directory?(path)
+
+      rows = {}
+      Find.find(path) do |file|
+        next if file == path
+
+        rel = file.delete_prefix("#{path}/")
+        Find.prune if names && names.none? { |name| rel == name || rel.start_with?("#{name}/") || name.start_with?("#{rel}/") }
+        stat = File.lstat(file)
+        raise IOError, 'Unsafe backup entry' unless (stat.file? || stat.directory?) && stat.uid == Process.uid
+        next if names && names.none? { |name| rel == name || rel.start_with?("#{name}/") }
+        raise IOError, 'Backup work budget exhausted' if admission && !admission.call(stat.file? ? stat.size + 1 : 0)
+
+        row = [stat.ftype, stat.mode, stat.uid, stat.gid]
+        if stat.file?
+          row += [stat.size, Digest::SHA256.file(file).hexdigest]
+          after = File.lstat(file)
+          raise IOError, 'Backup changed while hashing' unless [stat.ino, stat.size, stat.mtime, stat.ctime] == [after.ino, after.size, after.mtime, after.ctime]
+        end
+        rows[rel] = row
+      end
+      rows
+    end
+
     private_class_method def self.backup!
-      ts  = Time.now.utc.strftime('%Y%m%d_%H%M%S')
-      dst = File.join(BACKUP_ROOT, ts)
-      FileUtils.mkdir_p(dst)
-      Dir.children(PWN_ROOT).each do |c|
-        next if %w[backup quarantine sessions swarm].include?(c) # large / regenerable
+      PWN::Backups.transaction(root: BACKUP_ROOT) do
+        dst = PWN::Backups.directory(label: 'migration')
+        names = backup_input_names
+        inventory = backup_inventory(path: PWN_ROOT, names: names)
+        names.each do |name|
+          src = File.join(PWN_ROOT, name)
+          next unless File.exist?(src)
+
+          target = File.join(dst, name)
+          FileUtils.mkdir_p(File.dirname(target), mode: 0o700)
+          FileUtils.cp_r(src, target, preserve: true)
+        end
+        raise IOError, 'Migration input changed during backup' unless inventory == backup_inventory(path: PWN_ROOT, names: names)
+        raise IOError, 'Backup verification failed' unless inventory == backup_inventory(path: dst, names: names)
 
-        src = File.join(PWN_ROOT, c)
-        FileUtils.cp_r(src, dst)
-      rescue StandardError
-        next
+        inventory.each do |name, row|
+          File.open(File.join(dst, name), File::RDONLY, &:fsync) if row.first == 'file'
+        end
+        File.open(File.join(dst, '.snapshot-manifest.json'), File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+          file.write(JSON.generate(version: 1, complete: true, scope: names.sort, files: inventory))
+          file.flush
+          file.fsync
+        end
+        File.open(dst, File::RDONLY, &:fsync)
+        dst
       end
-      dst
     end
 
     private_class_method def self.stamp!
@@ -640,18 +711,12 @@ module PWN
       SCHEMA_VERSION
     end
 
-    private_class_method def self.decryptor(opts = {})
-      key = opts[:key]
-      iv  = opts[:iv]
-      return [key, iv] if key && iv
-
-      dec = File.join(PWN_ROOT, 'pwn.yaml.decryptor')
-      return [nil, nil] unless File.file?(dec)
-
-      d = YAML.load_file(dec, symbolize_names: true)
-      [d[:key], d[:iv]]
-    rescue StandardError
-      [nil, nil]
+    private_class_method def self.vault_paths(opts = {})
+      driver = defined?(PWN::Env) && PWN::Env.is_a?(Hash) ? PWN::Env[:driver_opts] : nil
+      driver = {} unless driver.is_a?(Hash)
+      file = opts[:pwn_env_path] || driver[:pwn_env_path] || File.join(PWN_ROOT, 'pwn.yaml')
+      decryptor_file = opts[:pwn_dec_path] || driver[:pwn_dec_path] || "#{file}.decryptor"
+      { file: file, decryptor_file: decryptor_file }
     end
 
     private_class_method def self.safe_read(opts = {})
@@ -743,7 +808,9 @@ module PWN
         #{self}.needed?
 
         # Run status and return its result
-        #{self}.status
+        #{self}.status(
+          pwn_env_path: 'optional - Vault path; defaults to driver options then ~/.pwn/pwn.yaml'
+        )
 
         # Human-readable ~/.pwn state doctor.  Read-only.  Called from
         #{self}.check(
@@ -757,20 +824,35 @@ module PWN
           dry_run: 'optional - report what WOULD happen, write nothing (default false)',
           key: 'optional - vault key   (default: read ~/.pwn/pwn.yaml.decryptor)',
           iv: 'optional - vault iv    (default: read ~/.pwn/pwn.yaml.decryptor)',
+          yubikey: 'optional - Hardware selector overrides: slot, serial, reader, device_path, connection, timeout',
+          pwn_env_path: 'optional - Vault path; defaults to driver options then ~/.pwn/pwn.yaml',
+          pwn_dec_path: 'optional - Legacy decryptor path; defaults to driver options then vault sidecar',
           io: 'optional - IO to write to (default $stdout)'
         )
 
         # Run vault drift and return its result
         #{self}.vault_drift(
-          key: 'optional - vault key, iv: optional - vault iv'
+          key: 'optional - Legacy vault key override',
+          iv: 'optional - Legacy vault IV override',
+          yubikey: 'optional - Hardware selector overrides: slot, serial, reader, device_path, connection, timeout',
+          pwn_env_path: 'optional - Vault path; defaults to driver options then ~/.pwn/pwn.yaml',
+          pwn_dec_path: 'optional - Legacy decryptor path; hardware vaults need no sidecar'
         )
 
         # Run backfill vault and return its result
         #{self}.backfill_vault(
-          key: 'optional - optional, iv: optional, dry_run: false, io: $stdout',
-          io: 'optional - io value consumed by #backfill_vault',
-          dry_run: 'optional - dry run value consumed by #backfill_vault',
-          iv: 'optional - iv value consumed by #backfill_vault'
+          key: 'optional - Legacy vault key override',
+          iv: 'optional - Legacy vault IV override',
+          yubikey: 'optional - Hardware selector overrides: slot, serial, reader, device_path, connection, timeout',
+          pwn_env_path: 'optional - Vault path; defaults to driver options then ~/.pwn/pwn.yaml',
+          pwn_dec_path: 'optional - Legacy decryptor path; hardware vaults need no sidecar',
+          io: 'optional - Report output; defaults to $stdout',
+          dry_run: 'optional - Report missing keys without writing; defaults to false'
+        )
+
+        # Compatibility report; shared producer admission owns retention.
+        #{self}.prune_backups(
+          dry_run: 'optional - preview without writes, default true'
         )
 
         # Run env template and return its result

data/lib/pwn/module_skills.rb

@@ -273,6 +273,13 @@ module PWN
           pending = []
           next
         end
+        if line =~ /^\s*class\s+([A-Z][\w:]*)/
+          ident = Regexp.last_match(1)
+          if snake(name: ident.split('::').last) == File.basename(src, '.rb')
+            const = ident.include?('::') ? ident : (stack + [ident]).join('::')
+            blurb = pending.join(' ').strip if blurb.empty?
+          end
+        end
         pending = []
         next if line =~ /^\s*private_class_method/