appydave-tools 0.83.0 → 0.84.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7b1472f59045694d5411b4112d3c66c04dfa724197ff9a6caa6fe8dde4437a6a
-  data.tar.gz: 9088a3cc358367481e06602912df404694af78d5271d2b90458e08ee63dc272c
+  metadata.gz: bbde49937db92444ee47416c1fbd53d0cd3ca6c99bc65b30e30a58cf2490facc
+  data.tar.gz: 1807239701f53c00bd7e692c51e6792056b2e951d0b71720059fdd5c5fbd4414
 SHA512:
-  metadata.gz: 9dd76f56f7e9886dbd88b8ab9a2a4e026abd1ddaad935046c61a9fc7a9b72cbf316edb8fcb3d81889a55833cca273c3e09abee6d066bad035b7337afa823aab5
-  data.tar.gz: 1c32c5827d8b838d9c4f723ecfc0c4695c6d5189fc0f19401b365ca9c9888f3e57de8a167fdc9ba67edb4dc56d3519207e19df95c3382f9f7d50b3af5eef85c7
+  metadata.gz: be1b84a9fb1b45b7377c8cc0e0371f234b5b56e96f23a44f1733e6face17c489a288bd3f8128a5e8548eb09247ff3deffd38144eb6480214b5ba8401406bf022
+  data.tar.gz: e3cffdedb85686158bc251361f04b0b2ea44f354f472968efd92bf84c165dd1aa69ca37aa0e1105c191b5f84d70ccccbf0ed7e9418e0e194dbf1a1dceca0bfd8

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [0.83.0](https://github.com/appydave/appydave-tools/compare/v0.82.0...v0.83.0) (2026-04-04)
+
+
+### Bug Fixes
+
+* rename format_tokens param n to count to satisfy Naming/MethodParameterName ([e49d615](https://github.com/appydave/appydave-tools/commit/e49d61517a89b05f6c21bd4c5852a3ec59a74a55))
+
+
+### Features
+
+* add --smart flag for auto-routing output by token size ([a9466e0](https://github.com/appydave/appydave-tools/commit/a9466e059b5164a83902580bbfac5031e3a2dfe3))
+
 # [0.82.0](https://github.com/appydave/appydave-tools/compare/v0.81.0...v0.82.0) (2026-04-04)
 
 

data/docs/planning/query-location-feature/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,142 @@
+# FR-NEW: Query Location & App Registry Integration
+
+**Status**: Proposed
+**Priority**: Medium
+**Created**: 2026-04-05
+**Relates to**: `query_brain`, `llm_context` pipeline; `locations.json`, `apps.json`
+
+---
+
+## Problem
+
+`query_brain` and `llm_context` work well for brain files but have no way to resolve project paths from the existing registries. When a user says "package the FliVideo project for LLM research", there is no single command that:
+1. Looks up the project path from `locations.json` or `apps.json`
+2. Knows which file groupings are relevant (docs, code, prompts, tests)
+3. Feeds those paths directly into `llm_context`
+
+Instead, the user must manually look up the path and write the `llm_context` invocation by hand every time.
+
+---
+
+## Proposed Solution
+
+### Option A — `query_location` CLI (preferred)
+
+New binary `bin/query_location.rb` that queries `~/.config/appydave/locations.json` and `~/.config/appydave/apps.json` by key, name, type, or brand.
+
+```bash
+# Find a project by key or name
+query_location --find flivideo
+query_location --find ss-prompt
+
+# List all products
+query_location --type product
+
+# Get path only (for piping)
+query_location --find flivideo --path-only
+
+# Get JSON metadata
+query_location --find flivideo --meta
+
+# List all apps from apps.json
+query_location --apps
+query_location --apps --status active
+```
+
+Output modes:
+- Default: path on a single line (pipeable to `llm_context`)
+- `--meta`: JSON with key, path, description, type, status
+- `--path-only`: bare path string
+
+### Option B — Extend `jump.rb` with a query subcommand
+
+Add `jump.rb query --find flivideo` rather than a new binary. Lower overhead, shares existing location-loading code.
+
+**Recommendation**: Option B — reuse `jump.rb` infrastructure, add a `query` subcommand that outputs path/meta. Less surface area, same capability.
+
+---
+
+## File Groupings (Phase 2)
+
+Once location lookup works, the second gap is "which files within a project are relevant for LLM research?" Today the user must specify patterns manually.
+
+**Proposed**: A `.llm-groups.yaml` sidecar file at the project root declaring named groupings:
+
+```yaml
+# .llm-groups.yaml
+groups:
+  docs:
+    - "docs/**/*.md"
+    - "README.md"
+    - "CLAUDE.md"
+  code:
+    - "lib/**/*.rb"
+    - "bin/**/*.rb"
+  tests:
+    - "spec/**/*.rb"
+  prompts:
+    - "poem/**/*.json"
+    - "poem/**/*.yaml"
+```
+
+Then:
+```bash
+# Package docs group for LLM
+query_location --find appydave-tools --path-only | xargs -I{} llm_context -b {} --groups docs
+
+# Or inline
+llm_context -b ~/dev/ad/appydave-tools --groups docs,code
+```
+
+`llm_context` would read `.llm-groups.yaml` if present and expand the named groupings into `-i` patterns.
+
+---
+
+## Pipeline Vision (Full)
+
+```bash
+# Today (manual, fragile)
+llm_context -b ~/dev/ad/flivideo -i 'lib/**/*.rb' -i 'docs/**/*.md' -f content -o clipboard
+
+# After this feature (location-aware)
+query_location --find flivideo --path-only | xargs -I{} llm_context -b {} --groups docs,code -f content -o clipboard
+
+# Or shorthand once groups file exists
+llm_context --project flivideo --groups docs -o clipboard
+```
+
+---
+
+## Acceptance Criteria
+
+- [ ] `jump.rb query --find <term>` returns matching location path(s)
+- [ ] `jump.rb query --find <term> --meta` returns JSON with key, path, description, type
+- [ ] `jump.rb query --type product` lists all product locations
+- [ ] Output is pipeable to `llm_context -b`
+- [ ] Apps from `apps.json` are also queryable (or a separate `--apps` flag)
+- [ ] Spec coverage for new query subcommand
+
+### Phase 2 (separate backlog item)
+- [ ] `llm_context` reads `.llm-groups.yaml` and expands `--groups` flag into `-i` patterns
+- [ ] `.llm-groups.yaml` standard defined and documented
+- [ ] At least 3 projects have `.llm-groups.yaml` files (appydave-tools, flivideo, ss-prompt)
+
+---
+
+## Related Systems
+
+- `~/.config/appydave/locations.json` — 70+ project locations (source of truth for `jump`)
+- `~/.config/appydave/apps.json` — app registry with ports, start scripts, status
+- `query_brain` — parallel tool for brain files; this is the project equivalent
+- `llm_context` — the consumer; needs paths to operate
+- `system-comprehension-pattern.md` — the pattern that produces the mental model; needs groupings to be useful at scale
+- `appydave:system-context` skill — MISSING skill that generates `CONTEXT.md` per project; relates to Phase 2 groupings
+
+---
+
+## Notes
+
+- Do NOT create a separate JSON registry — `locations.json` is already the source of truth
+- The `jump` skill already knows about `locations.json`; extending `jump.rb` keeps things consistent
+- Phase 2 (`.llm-groups.yaml`) is the real value unlock — Phase 1 is just plumbing
+- This feature is what enables the "package project X for LLM research" workflow without manual path lookup every time

data/docs/planning/query-location-feature/system-context-gap-analysis.md

@@ -0,0 +1,107 @@
+# Gap Analysis: system-context vs system-comprehension-pattern
+
+**Context**: The `CONTEXT.md` file in this repo was generated by `/appydave:system-context` — a skill
+that doesn't yet exist in appydave-plugins. This note compares what that skill *produced* (the output)
+against the `system-comprehension-pattern.md` in the prompt-patterns brain to assess the gap.
+
+**Created**: 2026-04-05
+
+---
+
+## What system-context Produced (CONTEXT.md output)
+
+Looking at `CONTEXT.md` (generated 2026-04-03), the skill produced:
+
+```yaml
+# Frontmatter
+generated: 2026-04-03
+generator: system-context
+status: snapshot
+sources: [README.md, gemspec, lib/tools.rb, brand_resolver.rb, project_resolver.rb, jump/commands/generate.rb, docs/dam/batch-s3-listing-requirements.md, CHANGELOG.md (versions 0.76.0-0.77.7)]
+regenerate: "Run /appydave:system-context in the repo root"
+```
+
+Sections produced:
+1. **Purpose** — one sentence
+2. **Domain Concepts** — key vocabulary (Brand, Project, DAM, Project Naming, Configuration, Multi-channel)
+3. **Design Decisions** — 6 decisions with rationale
+4. **Scope Limits** — 6 explicit "does NOT" statements
+
+---
+
+## What system-comprehension-pattern Produces (Level 1)
+
+The 8-dimension Level 1 prompt produces:
+
+1. REAL PURPOSE — pain solved, world without it
+2. MENTAL MODEL — central metaphor or abstraction
+3. CORE ABSTRACTIONS — 3-5 building blocks and how they relate
+4. KEY WORKFLOWS — 2-4 end-to-end workflows (intent → outcome, not API calls)
+5. DESIGN DECISIONS — why it's built this way, alternatives considered
+6. NON-OBVIOUS CONSTRAINTS — things that look like they should work but don't
+7. EXPERT VS BEGINNER — mental shift from competent to expert
+8. SCOPE LIMITS — explicit non-scope + what handles those things instead
+
+---
+
+## Gap Analysis
+
+| Dimension | system-context | system-comprehension Level 1 |
+|-----------|---------------|------------------------------|
+| Purpose / Real problem | ✅ One sentence | ✅ Full explanation + "world without it" |
+| Domain concepts / Core abstractions | ✅ Reasonable depth | ✅ Richer — explains relationships between concepts |
+| Mental model / Central metaphor | ❌ Not present | ✅ The central "how does the system think?" question |
+| Key workflows | ❌ Not present | ✅ End-to-end workflows (intent → outcome) |
+| Design decisions | ✅ Good — 6 decisions with rationale | ✅ Same coverage + alternatives considered |
+| Non-obvious constraints | ❌ Not present | ✅ The "looks like it should work but doesn't" list |
+| Expert vs beginner mental shift | ❌ Not present | ✅ The hardest thing to get from docs |
+| Scope limits | ✅ Good — 6 explicit "does NOT" statements | ✅ Same + what handles those things instead |
+
+**Score: system-context covers ~4/8 dimensions well. Missing the 4 that are hardest to get from docs.**
+
+---
+
+## The Core Gap
+
+`system-context` is essentially an **automated documentation snapshot** — it reads source files and
+produces a structured summary. It does this well and efficiently (no LLM needed, or minimal).
+
+`system-comprehension-pattern` Level 1 is a **mental model prompt** — it produces reasoning about the
+system, not just facts about it. The 4 missing dimensions (mental model, key workflows, non-obvious
+constraints, expert vs beginner) are precisely the things that make a reasoning partner vs a fact retriever.
+
+**Practical implication**: `CONTEXT.md` is useful as orientation context for an LLM session. But an LLM
+given only `CONTEXT.md` would produce competent-but-generic answers. An LLM given the Level 1
+comprehension output would produce expert-level, system-aware answers.
+
+---
+
+## What This Means for the system-context Skill (when built)
+
+When `/appydave:system-context` is built as a proper skill, it should:
+
+1. **Keep what works**: automated extraction of purpose, domain concepts, design decisions, scope limits
+   (these come from README, gemspec, source files — no deep reasoning needed)
+
+2. **Add what's missing**: either
+   - Prompt the LLM to produce the missing 4 dimensions as part of the generation
+   - Or leave a `## Pending Comprehension` section flagging that Level 1 comprehension hasn't been run
+
+3. **Add a query_brain groupings block** — this is the new gap not in either system:
+   ```yaml
+   llm_groups:
+     docs: ["docs/**/*.md", "README.md", "CLAUDE.md"]
+     code: ["lib/**/*.rb", "bin/**/*.rb"]
+     tests: ["spec/**/*.rb"]
+   ```
+   So that `llm_context --project appydave-tools --groups docs` works without manual pattern entry.
+
+---
+
+## Recommendation
+
+- **`system-context` as-is**: Good for quick onboarding context. Use it.
+- **Before deep work**: Also run Level 1 comprehension from `system-comprehension-pattern.md` and append
+  the output to `CONTEXT.md` or keep it in a separate `COMPREHENSION.md`.
+- **Long-term**: Build the `system-context` skill to include LLM-driven comprehension + groupings block.
+  The skill that produces `CONTEXT.md` should be the same skill that makes the project queryable.

data/lib/appydave/tools/jump/cli.rb

@@ -54,6 +54,8 @@ module Appydave
             run_remove(args)
           when 'validate'
             run_validate(args)
+          when 'query'
+            run_query(args)
           when 'report'
             run_report(args)
           when 'generate'
@@ -128,6 +130,35 @@ module Appydave
           exit_code_for(result)
         end
 
+        def run_query(args)
+          meta_mode = args.delete('--meta')
+
+          find_terms = extract_multi_option(args, '--find')
+          type_filter = extract_option(args, '--type')
+          brand_filter = extract_option(args, '--brand')
+          args.delete('--path-only')
+
+          cmd = Commands::Query.new(
+            load_config,
+            find: find_terms,
+            type: type_filter,
+            brand: brand_filter
+          )
+          result = cmd.run
+
+          if result[:success]
+            if meta_mode
+              format_output(result, 'json')
+            else
+              format_output(result, 'paths')
+            end
+          else
+            warn result[:error]
+          end
+
+          exit_code_for(result)
+        end
+
         def run_get(args)
           format = format_option(args)
           key = args.first
@@ -350,6 +381,20 @@ module Appydave
           attrs
         end
 
+        def extract_multi_option(args, flag)
+          values = []
+          loop do
+            index = args.index(flag)
+            break unless index
+
+            value = args[index + 1]
+            args.delete_at(index + 1)
+            args.delete_at(index)
+            values << value if value
+          end
+          values
+        end
+
         def extract_option(args, flag)
           index = args.index(flag)
           return nil unless index
@@ -407,6 +452,7 @@ module Appydave
               search <terms>        Fuzzy search across all location metadata
               get <key>             Get location by exact key
               list                  List all locations
+              query                 Scriptable location lookup (pipeline-friendly)
 
             CRUD Operations:
               add                   Add a new location
@@ -445,6 +491,8 @@ module Appydave
           topic = args.first
 
           case topic
+          when 'query'
+            show_query_help
           when 'search'
             show_search_help
           when 'add'
@@ -464,6 +512,36 @@ module Appydave
           end
         end
 
+        def show_query_help
+          output.puts <<~HELP
+            jump query - Scriptable location lookup (pipeline-friendly)
+
+            Usage: jump query [--find <term>] [--type <type>] [--brand <brand>] [--path-only|--meta]
+
+            Filters (all are AND-combined):
+              --find <term>     Match term against key, name, brand, type, tags, description
+                                Repeat for AND logic: --find appydave --find ruby
+              --type <type>     Filter by location type (e.g. tool, gem, product)
+              --brand <brand>   Filter by brand (e.g. appydave, flivideo)
+
+            Output modes:
+              (default)         One path per line — pipeable (same as --path-only)
+              --path-only       Explicit path-per-line mode
+              --meta            JSON array with key, path, description, type, brand, status
+
+            Exit codes:
+              0                 Matches found
+              1                 No matches (NOT_FOUND)
+
+            Examples:
+              jump query --find flivideo
+              jump query --find flivideo --meta
+              jump query --type tool
+              jump query --find appydave --type tool
+              jump query --find flivideo | xargs llm_context -b
+          HELP
+        end
+
         def show_search_help
           output.puts <<~HELP
             jump search - Fuzzy search locations

data/lib/appydave/tools/jump/commands/query.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Appydave
+  module Tools
+    module Jump
+      module Commands
+        # Query command provides scriptable location lookup
+        #
+        # Designed for pipeline use — default output is bare paths, one per line.
+        # Use --meta for structured JSON output.
+        #
+        # @example Find by term
+        #   cmd = Commands::Query.new(config, find: ['flivideo'])
+        #   result = cmd.run
+        #   result[:results]  # => Array of matching location hashes
+        #
+        # @example Filter by type
+        #   cmd = Commands::Query.new(config, type: 'product')
+        #   result = cmd.run
+        class Query < Base
+          attr_reader :find_terms, :type_filter, :brand_filter
+
+          def initialize(config, **options)
+            super
+            @find_terms  = Array(options[:find]).map { |t| t.to_s.downcase.strip }.reject(&:empty?)
+            @type_filter = normalize_option(options[:type])
+            @brand_filter = normalize_option(options[:brand])
+          end
+
+          def run
+            matches = config.locations.select { |loc| matches?(loc) }
+
+            if matches.empty?
+              return error_result(
+                'No locations found matching the given criteria',
+                code: 'NOT_FOUND'
+              )
+            end
+
+            results = matches.map.with_index(1) do |location, index|
+              location_to_result(location, index)
+            end
+
+            success_result(
+              count: results.size,
+              results: results
+            )
+          end
+
+          private
+
+          def matches?(location)
+            return false if type_filter && location.type&.downcase != type_filter
+            return false if brand_filter && location.brand&.downcase != brand_filter
+            return false unless find_terms_match?(location)
+
+            true
+          end
+
+          def find_terms_match?(location)
+            return true if find_terms.empty?
+
+            # All find terms must match (AND logic) — each term matches if it appears
+            # in any of the searchable fields of the location
+            find_terms.all? { |term| term_matches_location?(term, location) }
+          end
+
+          def term_matches_location?(term, location)
+            fields = [
+              location.key,
+              location.type,
+              location.brand,
+              location.client,
+              location.description,
+              location.path
+            ].compact.map(&:downcase)
+
+            tag_fields = location.tags.map(&:downcase)
+
+            fields.any? { |f| f.include?(term) } || tag_fields.any? { |t| t.include?(term) }
+          end
+
+          def normalize_option(value)
+            return nil unless value
+
+            value.to_s.downcase.strip
+          end
+
+          def location_to_result(location, index)
+            {
+              index: index,
+              key: location.key,
+              path: expand_path(location.path),
+              description: location.description,
+              type: location.type,
+              brand: location.brand,
+              client: location.client,
+              tags: location.tags,
+              status: 'active'
+            }.compact
+          end
+
+          def expand_path(path)
+            return path unless path
+
+            File.expand_path(path)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/appydave/tools/version.rb

@@ -2,6 +2,6 @@
 
 module Appydave
   module Tools
-    VERSION = '0.83.0'
+    VERSION = '0.84.0'
   end
 end

data/lib/appydave/tools.rb

@@ -109,6 +109,7 @@ require 'appydave/tools/jump/commands/remove'
 require 'appydave/tools/jump/commands/validate'
 require 'appydave/tools/jump/commands/report'
 require 'appydave/tools/jump/commands/generate'
+require 'appydave/tools/jump/commands/query'
 require 'appydave/tools/jump/cli'
 
 require 'appydave/tools/youtube_manager/models/youtube_details'

data/package.json

@@ -1,6 +1,6 @@
 {
   "name": "appydave-tools",
-  "version": "0.83.0",
+  "version": "0.84.0",
   "description": "AppyDave YouTube Automation Tools",
   "scripts": {
     "release": "semantic-release"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: appydave-tools
 version: !ruby/object:Gem::Version
-  version: 0.83.0
+  version: 0.84.0
 platform: ruby
 authors:
 - David Cruwys
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-04 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -329,6 +329,8 @@ files:
 - docs/planning/micro-cleanup/AGENTS.md
 - docs/planning/micro-cleanup/IMPLEMENTATION_PLAN.md
 - docs/planning/micro-cleanup/assessment.md
+- docs/planning/query-location-feature/IMPLEMENTATION_PLAN.md
+- docs/planning/query-location-feature/system-context-gap-analysis.md
 - docs/planning/s3-operations-split/AGENTS.md
 - docs/planning/s3-operations-split/IMPLEMENTATION_PLAN.md
 - docs/planning/test-coverage-gaps/AGENTS.md
@@ -404,6 +406,7 @@ files:
 - lib/appydave/tools/jump/commands/add.rb
 - lib/appydave/tools/jump/commands/base.rb
 - lib/appydave/tools/jump/commands/generate.rb
+- lib/appydave/tools/jump/commands/query.rb
 - lib/appydave/tools/jump/commands/remove.rb
 - lib/appydave/tools/jump/commands/report.rb
 - lib/appydave/tools/jump/commands/update.rb