pwn 0.5.708 → 0.5.709

data/lib/pwn/ffi/rtl_sdr.rb

@@ -186,16 +186,46 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # Run available and return its result
           #{self}.available?
+
+          # Run list devices and return its result
           #{self}.list_devices
-          dev = #{self}.open(index: 0)
-          #{self}.configure(device: dev, freq_hz:, rate_hz: 2_048_000, gain_db: nil, ppm: 0)
-          #{self}.tuner_gains(device: dev)
-          iq = #{self}.read_sync(device: dev, bytes: 262_144)  # u8 I/Q String
-          #{self}.close(device: dev)
 
+          # Open a session or connection and return a handle.
+          #{self}.open(
+            index: 'optional - index value consumed by #open'
+          )
+
+          # Close a session previously returned by #open.
+          #{self}.close(
+            device: 'optional - device value consumed by #close'
+          )
+
+          # Run configure and return its result
+          #{self}.configure(
+            device: 'required - pointer from .open',
+            freq_hz: 'required - center frequency Hz',
+            rate_hz: 'optional - sample rate (default 2.048e6)',
+            gain_db: 'optional - tenths of dB (e.g. 496 = 49.6 dB). nil = auto',
+            ppm: 'optional - freq correction ppm (default 0)'
+          )
+
+          # Run read sync and return its result
+          #{self}.read_sync(
+            device: 'required - pointer from .open',
+            bytes: 'optional - number of raw bytes to read (default 262144)'
+          )
+
+          # Run tuner gains and return its result
+          #{self}.tuner_gains(
+            device: 'required - device value consumed by #tuner_gains'
+          )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
 
       class << self

data/lib/pwn/ffi/soapy_sdr.rb

@@ -317,22 +317,72 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
+          # Run available and return its result
           #{self}.available?
+
+          # Run info and return its result
           #{self}.info
-          #{self}.list_devices
-          dev = #{self}.make(args: 'driver=rtlsdr')
-          #{self}.device_keys(device: dev)
-          #{self}.unmake(device: dev)
 
-          h = #{self}.open(args: 'driver=rtlsdr')
-          #{self}.configure(handle: h, freq_hz:, rate_hz: 2_048_000, gain_db: nil)
-          #{self}.start_rx(handle: h)
-          data = #{self}.read_sync(handle: h)   # cs16le interleaved I/Q
-          #{self}.stop_rx(handle: h)
-          #{self}.close(handle: h)
+          # Run list devices and return its result
+          #{self}.list_devices
 
+          # Run make and return its result
+          #{self}.make(
+            args: 'required - args value consumed by #make'
+          )
+
+          # Run unmake and return its result
+          #{self}.unmake(
+            device: 'optional - device value consumed by #unmake'
+          )
+
+          # Run device keys and return its result
+          #{self}.device_keys(
+            device: 'required - device value consumed by #device_keys'
+          )
+
+          # Open a session or connection and return a handle.
+          #{self}.open(
+            args: 'optional - Soapy args string, e.g. driver=rtlsdr',
+            channel: 'optional - RX channel (default 0)'
+          )
+
+          # Run configure and return its result
+          #{self}.configure(
+            handle: 'required - from .open',
+            freq_hz: 'required - center frequency Hz',
+            rate_hz: 'optional - sample rate Hz (default 2_048_000)',
+            gain_db: 'optional - overall gain dB (default AGC on)',
+            bw_hz: 'optional - baseband filter BW Hz'
+          )
+
+          # Sets up + activates a CS16 RX stream. Extends handle in place
+          #{self}.start_rx(
+            handle: 'required - from .open',
+            samples: 'optional - MTU / read block size (default 65536)'
+          )
+
+          # Run read sync and return its result
+          #{self}.read_sync(
+            handle: 'required - from .start_rx',
+            timeout_us: 'optional - microseconds (default 1_000_000)'
+          )
+
+          # Run stop rx and return its result
+          #{self}.stop_rx(
+            handle: 'optional - handle value consumed by #stop_rx'
+          )
+
+          # Close a session previously returned by #open.
+          #{self}.close(
+            handle: 'optional - handle value consumed by #close',
+            device: 'optional - device value consumed by #close'
+          )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/ffi/stdio.rb

@@ -34,17 +34,14 @@ module PWN
       # Display Usage for this Module
 
       public_class_method def self.help
-        # NB: bare `puts` here would resolve to the FFI-attached libc puts
-        # (writes to C stdout, bypasses $stdout capture, flushes at exit).
-        $stdout.puts "USAGE:
-          #{self}.puts string
-          #{self}.printf(\"format string\", str, int, etc)
-
-          scanf_buffer = FFI::MemoryPointer.new(:char, 100)
-          #{self}.scanf(\"format string\", scanf_buffer)
+        puts "USAGE:
+          # Run available and return its result
+          #{self}.available?
 
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
     end
   end

data/lib/pwn/ffi/volk.rb

@@ -173,16 +173,45 @@ module PWN
 
       public_class_method def self.help
         puts "USAGE:
-          #{self}.available?                           # => true/false
-          #{self}.unpack_s16le(data: raw_bytes)        # s16le → Float[-1,1]
-          #{self}.accumulate(samples:)                 # Σ samples
-          #{self}.magnitude_squared(iq:)               # |z|² per complex pair
-          #{self}.sqrt(samples:)
-          #{self}.scale(samples:, factor:)
-          #{self}.dot_prod(a:, b:)
+          # Run available and return its result
+          #{self}.available?
 
+          # Run unpack s16le and return its result
+          #{self}.unpack_s16le(
+            data: 'required - raw String of little-endian signed 16-bit PCM'
+          )
+
+          # Run accumulate and return its result
+          #{self}.accumulate(
+            samples: 'optional - samples value consumed by #accumulate'
+          )
+
+          # Run magnitude squared and return its result
+          #{self}.magnitude_squared(
+            iq: 'required - Array of interleaved I/Q Floats (even length)'
+          )
+
+          # Run sqrt and return its result
+          #{self}.sqrt(
+            samples: 'optional - samples value consumed by #sqrt'
+          )
+
+          # Run scale and return its result
+          #{self}.scale(
+            samples: 'optional - samples value consumed by #scale',
+            factor: 'optional - factor value consumed by #scale'
+          )
+
+          # Run dot prod and return its result
+          #{self}.dot_prod(
+            a: 'required - a value consumed by #dot_prod',
+            b: 'required - b value consumed by #dot_prod'
+          )
+
+          # Print the AUTHOR(S) string for this module.
           #{self}.authors
         "
+        constants.sort
       end
 
       class << self

data/lib/pwn/ffi.rb

@@ -59,6 +59,18 @@ module PWN
     # Display a List of Every PWN::FFI Module
 
     public_class_method def self.help
+      puts "USAGE:
+        # Run available and return its result
+        #{self}.available?(
+          mod: 'required - Symbol or Module (e.g. :Liquid or PWN::FFI::Liquid)'
+        )
+
+        # Returns { ModuleName => true|false } for every registered binding
+        #{self}.backends
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
       constants.sort
     end
   end

data/lib/pwn/memory.rb

@@ -600,22 +600,142 @@ module PWN
 
     # Display Usage for this Module
     public_class_method def self.help
-      puts <<~USAGE
-        USAGE:
-          mem = PWN::Memory.load
-          PWN::Memory.remember(key: :user_prefers_ruby, value: 'Always prefer pure Ruby + RestClient patterns', category: :preference)
-          facts = PWN::Memory.recall(query: 'recon', category: :fact, limit: 10)
-          # session-first (previous response → older), then durable newest-first:
-          sess  = PWN::Memory.recall(limit: 10)  # or session_id: '20260811_...'
-          hits  = PWN::Memory.recall_semantic(query: 'recon', limit: 6)  # embedding-ranked
-          PWN::Memory.forget(key: :some_key)
-          PWN::Memory.forget(key: :operator_pref_x) rescue puts('protected')
-          PWN::Memory.clear(force: true)
-          context_str = PWN::Memory.to_context
-          PWN::Memory.lean!(dry_run: true)  # drop expired session_* + truncate values
-
-          #{self}.authors
-      USAGE
+      puts "USAGE:
+        # Run load and return its result
+        #{self}.load
+
+        # Run save and return its result
+        #{self}.save(
+          mem: 'optional - mem value consumed by #save',
+          force: 'optional - force value consumed by #save'
+        )
+
+        # Run remember and return its result
+        #{self}.remember(
+          key: 'required - Symbol or String key for the memory fact',
+          value: 'required - The value (any JSON serializable)',
+          category: 'optional - e.g. :fact, :preference, :lesson, :env (default: :fact)',
+          source: 'optional - :human | :reflect | :heuristic | :resolve | :consolidate (M3 provenance)',
+          confidence: 'optional - 0.0..1.0 how sure the writer was (M3)',
+          importance: 'optional - 0.0..1.0 retrieval/eviction weight (M2/M3)',
+          ttl: 'optional - seconds until stale (M3; consolidate evicts stale low-conf first)'
+        )
+
+        # Run recall and return its result
+        #{self}.recall(
+          query: 'optional - string to search keys/values/categories (simple match)',
+          category: 'optional - filter by category (:session = transcript only)',
+          limit: 'optional - max results (default 50)',
+          session_id: 'optional - current session (default Env/Pry active id)',
+          include_session: 'optional - include session value consumed by #recall'
+        )
+
+        # Resolve the active pwn-ai session id (Env, then Pry config)
+        #{self}.current_session_id(
+          session_id: 'optional - session id value consumed by #current_session_id'
+        )
+
+        # Walk the current session transcript from the previous assistant response
+        #{self}.session_turns(
+          session_id: 'optional - session id value consumed by #session_turns',
+          query: 'required - search query string',
+          limit: 'optional - limit value consumed by #session_turns'
+        )
+
+        # Run recent dialog and return its result
+        #{self}.recent_dialog(
+          session_id: 'optional - session id value consumed by #recent_dialog',
+          pairs: 'optional - max user/assistant pairs (default 2)',
+          max_chars: 'optional - per-turn truncation (default 1200)'
+        )
+
+        # Previous non-empty user message in the active session (what the human
+        #{self}.prior_user_message(
+          pairs: 'optional - pairs value consumed by #prior_user_message',
+          max_chars: 'optional - max chars value consumed by #prior_user_message (defaults to 4_000)',
+          skip_meta: 'optional - skip meta value consumed by #prior_user_message',
+          session_id: 'optional - session id value consumed by #prior_user_message'
+        )
+
+        # Previous non-empty assistant message in the active session
+        #{self}.prior_assistant_message(
+          pairs: 'optional - pairs value consumed by #prior_assistant_message',
+          max_chars: 'optional - max chars value consumed by #prior_assistant_message (defaults to 4_000)',
+          skip_meta: 'optional - skip meta value consumed by #prior_assistant_message',
+          session_id: 'optional - session id value consumed by #prior_assistant_message'
+        )
+
+        # Build chronological user→assistant pairs from the active session
+        #{self}.turn_pairs(
+          pairs: 'optional - pairs value consumed by #turn_pairs',
+          max_chars: 'optional - max chars value consumed by #turn_pairs',
+          session_id: 'optional - session id value consumed by #turn_pairs',
+          include_orphan_user: 'optional - include orphan user value consumed by #turn_pairs'
+        )
+
+        # Find a user↔assistant pair in the active session
+        #{self}.find_turn_pair(
+          match: 'required - match value consumed by #find_turn_pair',
+          skip_meta: 'optional - skip meta value consumed by #find_turn_pair',
+          session_id: 'optional - session id value consumed by #find_turn_pair',
+          pairs: 'optional - pairs value consumed by #find_turn_pair (defaults to 12)',
+          max_chars: 'optional - max chars value consumed by #find_turn_pair (defaults to 4_000)'
+        )
+
+        # Run meta recall user and return its result
+        #{self}.meta_recall_user?(
+          text: 'optional - text value consumed by #meta_recall_user?'
+        )
+
+        # Run meta recall assistant and return its result
+        #{self}.meta_recall_assistant?(
+          text: 'optional - text value consumed by #meta_recall_assistant?'
+        )
+
+        # Run normalize utterance and return its result
+        #{self}.normalize_utterance(
+          text: 'optional - text value consumed by #normalize_utterance'
+        )
+
+        # Run recall semantic and return its result
+        #{self}.recall_semantic(
+          query: 'optional - search query string',
+          limit: 'optional - limit value consumed by #recall_semantic'
+        )
+
+        # Refuses PROTECT_KEY_PREFIXES / PROTECT_CATEGORIES unless force:true
+        #{self}.forget(
+          key: 'required - key value consumed by #forget',
+          force: 'optional - Boolean bypass protect policy (default false)'
+        )
+
+        # Requires force:true — protected prefs/SOPs must not vanish via bare clear
+        #{self}.clear(
+          force: 'required - force value consumed by #clear'
+        )
+
+        # Run to context and return its result
+        #{self}.to_context(
+          limit: 'optional - limit value consumed by #to_context (defaults to 20)'
+        )
+
+        # True when a memory key must survive cap eviction / age GC
+        #{self}.protected_entry?(
+          key: 'optional - key value consumed by #protected_entry?',
+          entry: 'optional - entry value consumed by #protected_entry?'
+        )
+
+        # Run lean and return its result
+        #{self}.lean!(
+          dry_run: 'optional - Boolean plan only (default false)',
+          value_max_chars: 'optional - truncate values (default VALUE_MAX_CHARS)',
+          ephemeral_ttl_secs: 'optional - drop expired session_* keys'
+        )
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
+      constants.sort
     end
   end
 end

data/lib/pwn/memory_index.rb

@@ -281,25 +281,40 @@ module PWN
     # Display Usage for this Module
 
     public_class_method def self.help
-      puts <<~USAGE
-        USAGE:
-          PWN::MemoryIndex.available?
-          PWN::MemoryIndex.recall_semantic(query: 'nmap sweep', limit: 6)
-          PWN::MemoryIndex.to_context(query: 'nmap sweep', limit: 6)  # PromptBuilder drop-in
-          PWN::MemoryIndex.refresh                                    # incremental (re)embed
-          PWN::MemoryIndex.embed(texts: ['a', 'b'])                   # raw vectors
-          PWN::MemoryIndex.reset
-
-          Config (prefer direct Ollama; Open WebUI is the fallback proxy):
-            PWN::Env[:ai][:ollama][:base_uri] = 'http://127.0.0.1:11434'
-            PWN::Env[:ai][:ollama][:embed_model] = '<embed-model-tag>'
-            # or:
-            PWN::Env[:ai][:openwebui][:base_uri] = 'https://openwebui.local'
-            PWN::Env[:ai][:openwebui][:key] = '<jwt>'
-            PWN::Env[:ai][:openwebui][:embed_model] = '<embed-model-tag>'
-
-          #{self}.authors
-      USAGE
+      puts "USAGE:
+        # Run available and return its result
+        #{self}.available?
+
+        # Run recall semantic and return its result
+        #{self}.recall_semantic(
+          query: 'required - user request / search text',
+          limit: 'optional - top-K by cosine similarity (default 6)'
+        )
+
+        # Run to context and return its result
+        #{self}.to_context(
+          limit: 'optional - limit value consumed by #to_context (defaults to 6)',
+          drop_hygiene_sops: 'optional - drop hygiene sops value consumed by #to_context',
+          query: 'optional - search query string'
+        )
+
+        # Run refresh and return its result
+        #{self}.refresh(
+          mem: 'optional - mem value consumed by #refresh (defaults to PWN::Memory.load)'
+        )
+
+        # Run embed and return its result
+        #{self}.embed(
+          texts: 'required - Array texts value consumed by #embed'
+        )
+
+        # Run reset and return its result
+        #{self}.reset
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
+      constants.sort
     end
   end
 end

data/lib/pwn/migrate.rb

@@ -679,40 +679,50 @@ module PWN
 
     public_class_method def self.help
       puts "USAGE:
-        # Is ~/.pwn older than this pwn release's schema?
-        #{self}.needed?             # => true/false (cheap; used by refresh_env)
+        # Run installed schema and return its result
+        #{self}.installed_schema
 
-        # Read-only per-file compatibility report.
-        #{self}.status              # => { schema_installed:, schema_current:, files:[…], incompatible:[…] }
-        #{self}.check               # human-readable to $stdout
+        # Run needed and return its result
+        #{self}.needed?
 
-        # Apply schema migrations + (optionally) autofix incompatible files.
-        # Always takes a timestamped backup under ~/.pwn/backup/<ts>/ first.
+        # Run status and return its result
+        #{self}.status
+
+        # Human-readable ~/.pwn state doctor.  Read-only.  Called from
+        #{self}.check(
+          io: 'optional - IO to write the report to (default $stdout)'
+        )
+
+        # Run run and return its result
         #{self}.run(
-          fix:     'optional - also autofix per-file (default false)',
-          backup:  'optional - default true',
-          dry_run: 'optional - default false',
-          key:     'optional - vault key (default: ~/.pwn/pwn.yaml.decryptor)',
-          iv:      'optional - vault iv'
+          fix: 'optional - also autofix incompatible files (default: schema-migrations only)',
+          backup: 'optional - take timestamped backup of ~/.pwn first (default true)',
+          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)',
+          io: 'optional - IO to write to (default $stdout)'
         )
 
-        # pwn.yaml specifically — deep-merge missing keys from the
-        # current release template UNDER the user's values, re-encrypt.
-        #{self}.vault_drift         # => { missing: [dotted.paths], … } or nil
-        #{self}.backfill_vault
+        # Run vault drift and return its result
+        #{self}.vault_drift(
+          key: 'optional - vault key, iv: optional - vault iv'
+        )
 
-        # Data:
-        #{self}::SCHEMA_VERSION     # bump when a ~/.pwn file shape changes
-        #{self}::STATE_FILES        # rel-path → owner → verifier → fix
-        #{self}::MIGRATIONS         # ordered idempotent transforms
+        # 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'
+        )
 
-        # From the shell:
-        pwn setup --migrate                # == #{self}.run
-        pwn setup --migrate --fix          # == #{self}.run(fix: true)
-        pwn setup --migrate --dry-run
+        # Run env template and return its result
+        #{self}.env_template
 
+        # Print the AUTHOR(S) string for this module.
         #{self}.authors
       "
+      constants.sort
     end
   end
 end

data/lib/pwn/module_skills.rb

@@ -435,14 +435,45 @@ module PWN
     end
 
     public_class_method def self.help
-      puts <<~USAGE
-        USAGE:
-          #{self}.enumerate
-          #{self}.refresh!
-          #{self}.drift
-          #{self}.install(pwn_skills_path: '~/.pwn/skills')
-          #{self}.authors
-      USAGE
+      puts "USAGE:
+        # Run enumerate and return its result
+        #{self}.enumerate(
+          lib_root: 'optional - lib root value consumed by #enumerate'
+        )
+
+        # Run relpath and return its result
+        #{self}.relpath(
+          source: 'optional - source value consumed by #relpath',
+          const: 'optional - const value consumed by #relpath'
+        )
+
+        # Run render and return its result
+        #{self}.render(
+          module: 'optional - module value consumed by #render (defaults to opts)'
+        )
+
+        # Run refresh and return its result
+        #{self}.refresh!(
+          dest: 'required - dest value consumed by #refresh!',
+          lib_root: 'optional - lib root value consumed by #refresh!'
+        )
+
+        # Run drift and return its result
+        #{self}.drift(
+          dest: 'required - dest value consumed by #drift',
+          lib_root: 'optional - lib root value consumed by #drift'
+        )
+
+        # Run install and return its result
+        #{self}.install(
+          pwn_skills_path: 'required - pwn skills path value consumed by #install',
+          source: 'optional - source value consumed by #install'
+        )
+
+        # Print the AUTHOR(S) string for this module.
+        #{self}.authors
+      "
+      constants.sort
     end
   end
 end

data/lib/pwn/plugins/aflplusplus.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module PWN
+  module Plugins
+    # AFL++ campaign wrapper.
+    module AFLplusplus
+      public_class_method def self.required_bins
+        %w[afl-fuzz]
+      end
+
+      public_class_method def self.fuzz(opts = {})
+        PWN::Plugins::Doctor.require_bin!(name: 'afl-fuzz')
+        in_dir = opts[:in_dir] || opts[:corpus]
+        out_dir = opts[:out_dir] || opts[:output]
+        target = opts[:target]
+        raise 'ERROR: in_dir, out_dir, and target are required' if in_dir.to_s.empty? || out_dir.to_s.empty? || target.to_s.empty?
+
+        cmd = ['afl-fuzz', '-i', in_dir.to_s, '-o', out_dir.to_s, '--', target.to_s]
+        cmd.concat(Array(opts[:args]))
+        stdout, stderr, status = Open3.capture3(*cmd)
+        { stdout: stdout, stderr: stderr, exit: status.exitstatus }
+      end
+
+      public_class_method def self.authors
+        "AUTHOR(S):\n  0day Inc. <support@0dayinc.com>\n"
+      end
+
+      public_class_method def self.help
+        puts "USAGE:
+          # List host binaries this module expects to be installed.
+          #{self}.required_bins
+
+          # Run fuzz and return its result
+          #{self}.fuzz(
+            in_dir: 'required - in dir value consumed by #fuzz (defaults to opts[:corpus])',
+            corpus: 'optional - corpus value consumed by #fuzz',
+            out_dir: 'required - out dir value consumed by #fuzz (defaults to opts[:output])',
+            output: 'optional - output value consumed by #fuzz',
+            target: 'required - hostname, IP, or CIDR to scan',
+            args: 'optional - Array args value consumed by #fuzz'
+          )
+
+          # Print the AUTHOR(S) string for this module.
+          #{self}.authors
+        "
+        constants.sort
+      end
+    end
+  end
+end