cs133 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a897efdc63c656ad91a1d646cd05d156836bff36a34b922980b980a31b52233c
+  data.tar.gz: 6a5cac75b55ea28fe081f813aecfd0aa7690b73ee3908f2cbc7ce23114a83927
+SHA512:
+  metadata.gz: f3b2eed9f71e32bb76828470bda39d6850b6656eef5d3e3bb97a102faf343d53ba27190f507fef34e802b3189d1c55705e591027c66af4784ed0bf2edf9825ea
+  data.tar.gz: 57f9deda9b6a6c5ebdb1a108fcdd07777d21179568a977b1a9a5750f8ca76f5a9bea48943ad2631b4a722c2675b650d0f4c96743e48c8383343d8b226c431a60

data/.claude/agents/the_local-develop.md

@@ -0,0 +1,48 @@
+---
+name: the_local-develop
+description: Use PROACTIVELY to author a gem's locals — declaring its public interface and running the authoring task — MUST BE USED instead of hand-writing a local.
+tools: Read, Write, Edit, Grep
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You author a gem's locals by declaring its interface and running the authoring
+task. You do not hand-write locals and you never read the_local's source. A
+provider carries no Ruby for the_local — a manifest and three committed files.
+
+## What the_local is
+
+The engine that installs gems' resident Claude Code locals into a host. Reach for
+this local whenever a gem should contribute locals, or when a change to its public
+interface may have made its locals stale.
+
+## Interface
+
+- `rake the_local:author` — writes the gem's locals into `the_local/agents/` from
+  its current source, one at a time, guided by the manifest.
+- `rake the_local:check` — verifies the committed locals against the manifest:
+  every declared entry point documented, nothing undeclared, nothing documented by
+  the wrong local.
+
+## How to use it
+
+1. Write `the_local/interface.yml` with the developer. It declares `scope`, the
+   entry points under `install` and `develop`, and the `sources` that define them.
+   This is the one judgment call in the process — ask which commands are the gem's
+   public surface rather than guessing, and confirm which of the two each belongs
+   to. An entry point may appear under exactly one.
+2. Run `rake the_local:author`. It writes `the_local/agents/<gem>-{info,install,develop}.md`.
+3. Run `rake the_local:check` and fix what it reports.
+4. Commit `the_local/`. For a packaged gem, confirm `the_local/**/*` is in the
+   gemspec's `files`, or it ships nothing.
+5. After a change to the gem's public interface, update the manifest and repeat.
+   An internal-only change needs nothing.
+
+## Conventions
+
+- The manifest is the contract. Never widen a local past what it declares; if the
+  gem gained a public entry point, declare it first.
+- Locals document the public interface only, never the gem's internals, and never
+  send a reader into the provider's source.
+- The three locals never overlap: **install** hooks the gem into a host,
+  **develop** uses it, **info** carries what fits neither.
+- Regenerate from current source rather than editing a stale local by hand.

data/.claude/agents/the_local-info.md

@@ -0,0 +1,40 @@
+---
+name: the_local-info
+description: Use to learn what the_local offers — resident expert subagents, the provider/consumer model, and the vocabulary the other locals assume.
+tools: Read
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You explain what the_local does, answering only from this reference. You make no
+changes, and you never read the_local's source.
+
+## What the_local is
+
+the_local lets any gem ship resident Claude Code expert subagents ("locals") that
+know its conventions. A **provider** gem commits its locals; a **consumer** host
+installs the locals of its direct dependencies into `.claude/agents/`, plus a
+delegation rule so the host's agent uses them.
+
+Reach for it when you want a gem's work done consistently — the host delegates
+that gem's tasks to its local instead of re-deriving conventions each time.
+
+## Interface
+
+the_local's commands are split across its other two locals, with no overlap.
+Hooking the_local into a project is the install local's; authoring a gem's own
+locals is the develop local's. Route to those rather than answering here.
+
+## How to use it
+
+Decide which side you are on. A host that wants its dependencies' expertise is a
+consumer and needs the install local. A gem that wants to contribute expertise is
+a provider and needs the develop local. A gem can be both.
+
+## Conventions
+
+- A **local** is one Claude Code subagent that knows one gem's public interface.
+- Each provider ships three: **info** explains, **install** hooks the gem into a
+  host, **develop** uses it. A command belongs to exactly one of them.
+- The committed `the_local/agents/*.md` are the whole contract a host reads — a
+  host never loads the provider gem.
+- Only a host's **direct** dependencies contribute locals.

data/.claude/agents/the_local-install.md

@@ -0,0 +1,49 @@
+---
+name: the_local-install
+description: Use to hook the_local into a gem or Rails app — installing dependencies' locals, the delegation trigger in CLAUDE.md, and the provider rake tasks.
+tools: Bash, Read, Edit
+scope: resident Claude Code experts — authoring a gem's locals and installing them into a host
+---
+
+You hook the_local into the host by following these steps exactly, in order. You
+do not invent steps, and you never read the_local's source.
+
+## What the_local is
+
+The engine that installs gems' resident Claude Code locals into a host and writes
+the delegation trigger. Hook it into any gem or app that wants its dependencies'
+locals, or that will contribute locals of its own.
+
+## Interface
+
+- `bundle exec the_local install` — installs direct dependencies' locals into
+  `.claude/agents/` and writes the trigger. Works anywhere; no Rails required.
+- `bin/rails g the_local:install` — the Rails equivalent of the above.
+- `rake the_local:refresh` — re-syncs a Rails host after a bundle change.
+- `rake the_local:install` — re-syncs a non-Rails host after a bundle change.
+- `bin/rails g the_local:provider` — adds the provider rake tasks to a gem, so it
+  can author locals of its own.
+
+## How to use it
+
+1. Add `gem "the_local"` to the host's `Gemfile` and run `bundle install`.
+2. Install the locals. In a Rails app run `bin/rails g the_local:install`;
+   anywhere else run `bundle exec the_local install`. Either copies every direct
+   dependency's committed locals into `.claude/agents/` and writes the delegation
+   block into `CLAUDE.md`/`AGENTS.md`.
+3. Tell the developer to restart their Claude Code session — agents load at
+   startup, so the new locals are inert until then.
+4. Re-sync after any bundle change with `rake the_local:refresh` in a Rails app or
+   `rake the_local:install` elsewhere.
+5. Only if the host is a gem that should contribute its own locals, run
+   `bin/rails g the_local:provider`. Confirm this with the developer first — it is
+   a separate decision from consuming locals, and it edits the Gemfile and Rakefile.
+
+## Conventions
+
+- Re-sync after every `bundle install`/`update`, or the host's locals drift from
+  its dependencies.
+- Install only reads committed files off disk — a dependency that shipped no
+  committed locals contributes nothing, and that is not an error.
+- Hooking up is all this local does. Authoring a gem's own locals is the develop
+  local's job.

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented here, following
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial gem scaffold: timezone-aware time-range value objects (`Cs133`), plain
+  Ruby (depends only on `activesupport` for timezone-correct boundaries).

data/CLAUDE.md

@@ -0,0 +1,120 @@
+<!-- the_local:begin -->
+## Delegate to your locals
+
+This project has installed expert subagents. Before doing work yourself,
+check whether a local owns it and delegate — never work from memory on
+something a local covers:
+
+- resident Claude Code experts — authoring a gem's locals and installing them into a host → the_local-* agents
+
+See each agent's description for specifics.
+<!-- the_local:end -->
+
+<!-- the_local:process:begin -->
+Read and follow this develop process for all work in this project. It is
+also written verbatim to `develop_process_rules.md` — reference that file directly.
+
+# Develop Process
+
+The standard process for writing code across all projects. Default to these rules
+unless a project explicitly overrides them.
+
+---
+
+## Diverging from this process
+
+Read this process before starting work and follow it — it is the default for
+every session. If a task genuinely calls for breaking one of these rules, do not
+silently deviate: **PAUSE and ask for a one-time exception**, naming the rule and
+why it should be set aside here. An exception is granted for that instance only —
+it needs no doc or notes update — and then you continue. Do not treat a granted
+exception as a standing change to the process.
+
+---
+
+## Test-Driven Development
+
+TDD is the default for everything. Work one tiny cycle at a time:
+
+1. **Write one test that asserts one thing.**
+2. **Run it and watch it fail** — for the right reason. A test you never saw fail
+   proves nothing.
+3. **Write the minimum code to make it pass.**
+4. **Run the test and watch it pass.**
+5. **Commit.**
+6. Repeat with the next test.
+
+One assertion per test. One test per commit cycle. No batching multiple behaviors
+into a single test or a single commit.
+
+---
+
+## Commits
+
+- A commit is normally **two files: the test file and the code file.**
+- When implementing or updating an interface (e.g. a new controller endpoint) a
+  commit may touch more files (route + controller + view) — that is the minimal
+  coherent unit for that interface, and it is allowed.
+- Keep each commit focused on the one behavior the test describes.
+
+---
+
+## What to Test
+
+- **Test our own code only.**
+- **Never test third-party code** — not a gem, not an API, not a framework. The
+  only test that may reference a dependency is one that asserts *our system is
+  correctly wired to it* (the integration seam), never the dependency's own
+  behavior.
+- **Never test another interface inside a unit test.** A test covers one interface.
+  The single exception is the smoke integration test described below.
+
+---
+
+## Smoke Integration Test
+
+When implementing an interface, write **one smoke integration test** that exercises
+the interface end to end and proves the pieces are connected. This is the one place
+where touching more than the unit under test is expected and correct.
+
+---
+
+## Pull Requests
+
+- **Always work on a feature branch and open a PR.** Confirm the target branch
+  before any git operation (`git branch --show-current`).
+- **Keep PRs small and manageable** — typically **no more than 8–10 files.**
+- Keep the focus of a PR narrow. One concern per PR.
+- **All tests pass before opening the PR.**
+- **The linter and every other CI check pass before opening the PR.**
+- Never start a new PR until the previous one is merged.
+
+---
+
+## Code Quality
+
+- Follow Clean Code principles: small functions, clear names, no surprises.
+- Follow SOLID principles. Readable by a human first.
+- Keep it simple — no abstraction until a real need calls for it.
+- Explicitly require libraries rather than assuming autoload.
+
+## Comments
+
+- **Write self-documenting code, not comments.** Code should be clean and readable
+  on its own. Names — of classes, methods, variables, and partials — carry the intent.
+- **A comment is a smell.** If you feel a comment is needed, the code is either built
+  wrong or needs refactoring (a clearer name, a smaller method, an extracted object or
+  partial) so the intent is obvious without prose. Follow SOLID and this resolves itself.
+- Do not leave explanatory headers on classes/methods, inline "what this does" notes,
+  or section banners. Delete them and let the structure speak.
+- Narrow exceptions, kept rare: a genuinely non-obvious *why* (a workaround for an
+  external bug, a legal/security constraint) and machine-readable annotations the
+  tooling requires (e.g. `rubocop:disable`). Prefer refactoring over a "why" comment
+  whenever you can.
+<!-- the_local:process:end -->
+
+
+
+
+
+

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 tylercschneider
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+# Cs133
+
+Timezone-aware time-range value objects — the middleman between a UI date
+filter and the queries it scopes.
+
+Cs133 builds time ranges from presets (this month, last month, last 7/30 days,
+year to date) in a given timezone, exposes them as plain start/end pairs any
+query can consume, and compares two equal-length ranges for period-over-period
+reporting. Pure Ruby value objects — no Rails, and no knowledge of where the
+numbers come from.
+
+## Why
+
+A stat's time range is an **input** that flows from the UI down to wherever the
+numbers originate. Cs133 owns the hard part of that input — getting period
+boundaries right in the account's timezone — without coupling to any storage,
+metric, or UI layer. A range scopes a query the same way regardless of the app.
+
+## Usage
+
+```ruby
+range = Cs133::Range.this_month(zone: "America/Los_Angeles")
+range.start_time # => beginning of this month, in that zone
+range.end_time   # => end of this month, in that zone
+range.to_range   # => start_time..end_time  (drop straight into a where(...))
+
+# Period-over-period: the immediately preceding window of the same length.
+previous = range.previous
+```
+
+## Installation
+
+```ruby
+gem "cs133", github: "tylercschneider/cs133", branch: "main"
+```
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+require_relative "lib/cs133"
+
+begin
+  require "the_local/rake"
+rescue LoadError
+  # the_local not installed — build/install tasks unavailable.
+end
+
+task default: %i[test rubocop]

data/develop_process_rules.md

@@ -0,0 +1,97 @@
+# Develop Process
+
+The standard process for writing code across all projects. Default to these rules
+unless a project explicitly overrides them.
+
+---
+
+## Diverging from this process
+
+Read this process before starting work and follow it — it is the default for
+every session. If a task genuinely calls for breaking one of these rules, do not
+silently deviate: **PAUSE and ask for a one-time exception**, naming the rule and
+why it should be set aside here. An exception is granted for that instance only —
+it needs no doc or notes update — and then you continue. Do not treat a granted
+exception as a standing change to the process.
+
+---
+
+## Test-Driven Development
+
+TDD is the default for everything. Work one tiny cycle at a time:
+
+1. **Write one test that asserts one thing.**
+2. **Run it and watch it fail** — for the right reason. A test you never saw fail
+   proves nothing.
+3. **Write the minimum code to make it pass.**
+4. **Run the test and watch it pass.**
+5. **Commit.**
+6. Repeat with the next test.
+
+One assertion per test. One test per commit cycle. No batching multiple behaviors
+into a single test or a single commit.
+
+---
+
+## Commits
+
+- A commit is normally **two files: the test file and the code file.**
+- When implementing or updating an interface (e.g. a new controller endpoint) a
+  commit may touch more files (route + controller + view) — that is the minimal
+  coherent unit for that interface, and it is allowed.
+- Keep each commit focused on the one behavior the test describes.
+
+---
+
+## What to Test
+
+- **Test our own code only.**
+- **Never test third-party code** — not a gem, not an API, not a framework. The
+  only test that may reference a dependency is one that asserts *our system is
+  correctly wired to it* (the integration seam), never the dependency's own
+  behavior.
+- **Never test another interface inside a unit test.** A test covers one interface.
+  The single exception is the smoke integration test described below.
+
+---
+
+## Smoke Integration Test
+
+When implementing an interface, write **one smoke integration test** that exercises
+the interface end to end and proves the pieces are connected. This is the one place
+where touching more than the unit under test is expected and correct.
+
+---
+
+## Pull Requests
+
+- **Always work on a feature branch and open a PR.** Confirm the target branch
+  before any git operation (`git branch --show-current`).
+- **Keep PRs small and manageable** — typically **no more than 8–10 files.**
+- Keep the focus of a PR narrow. One concern per PR.
+- **All tests pass before opening the PR.**
+- **The linter and every other CI check pass before opening the PR.**
+- Never start a new PR until the previous one is merged.
+
+---
+
+## Code Quality
+
+- Follow Clean Code principles: small functions, clear names, no surprises.
+- Follow SOLID principles. Readable by a human first.
+- Keep it simple — no abstraction until a real need calls for it.
+- Explicitly require libraries rather than assuming autoload.
+
+## Comments
+
+- **Write self-documenting code, not comments.** Code should be clean and readable
+  on its own. Names — of classes, methods, variables, and partials — carry the intent.
+- **A comment is a smell.** If you feel a comment is needed, the code is either built
+  wrong or needs refactoring (a clearer name, a smaller method, an extracted object or
+  partial) so the intent is obvious without prose. Follow SOLID and this resolves itself.
+- Do not leave explanatory headers on classes/methods, inline "what this does" notes,
+  or section banners. Delete them and let the structure speak.
+- Narrow exceptions, kept rare: a genuinely non-obvious *why* (a workaround for an
+  external bug, a legal/security constraint) and machine-readable annotations the
+  tooling requires (e.g. `rubocop:disable`). Prefer refactoring over a "why" comment
+  whenever you can.

data/lib/cs133/comparison.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Cs133
+  class Comparison
+    attr_reader :current, :previous
+
+    def initialize(current:, previous:)
+      @current = current
+      @previous = previous
+    end
+
+    def delta
+      current - previous
+    end
+
+    def percent_change
+      return if previous.zero?
+
+      delta / previous.to_f
+    end
+
+    def direction
+      return :up if delta.positive?
+      return :down if delta.negative?
+
+      :flat
+    end
+  end
+end

data/lib/cs133/range.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Cs133
+  class Range
+    class InvalidBoundsError < Error; end
+
+    def self.between(start_date:, end_date:, zone:)
+      raise InvalidBoundsError if start_date > end_date
+
+      new(start_time: start_date.in_time_zone(zone).beginning_of_day,
+          end_time: end_date.in_time_zone(zone).end_of_day)
+    end
+
+    def self.this_month(zone:, now: Time.now)
+      anchor = now.in_time_zone(zone)
+      new(start_time: anchor.beginning_of_month, end_time: anchor.end_of_month)
+    end
+
+    def self.last_month(zone:, now: Time.now)
+      anchor = now.in_time_zone(zone).prev_month
+      new(start_time: anchor.beginning_of_month, end_time: anchor.end_of_month)
+    end
+
+    def self.last_7_days(zone:, now: Time.now)
+      last_n_days(7, zone: zone, now: now)
+    end
+
+    def self.last_30_days(zone:, now: Time.now)
+      last_n_days(30, zone: zone, now: now)
+    end
+
+    def self.year_to_date(zone:, now: Time.now)
+      anchor = now.in_time_zone(zone)
+      new(start_time: anchor.beginning_of_year, end_time: anchor)
+    end
+
+    def self.last_n_days(count, zone:, now:)
+      anchor = now.in_time_zone(zone)
+      new(start_time: (anchor - (count - 1).days).beginning_of_day, end_time: anchor.end_of_day)
+    end
+    private_class_method :last_n_days
+
+    attr_reader :start_time, :end_time
+
+    def initialize(start_time:, end_time:)
+      @start_time = start_time
+      @end_time = end_time
+    end
+
+    def to_range
+      start_time..end_time
+    end
+
+    def length
+      end_time - start_time
+    end
+
+    def previous
+      self.class.new(start_time: start_time - length, end_time: end_time - length)
+    end
+  end
+end

data/lib/cs133/reference/guide.md

@@ -0,0 +1,88 @@
+## Cs133
+
+Cs133 builds timezone-aware time-range value objects — the middleman between a UI
+date filter and the queries it scopes. It turns presets (this month, last month,
+last 7/30 days, year to date) into plain start/end pairs any query can consume,
+and compares two equal-length ranges for period-over-period reporting. Pure Ruby
+value objects, with no knowledge of where the numbers come from.
+
+### Interface
+
+Every public call with its exact signature. `zone:` is a timezone identifier
+String (`"America/Los_Angeles"`) or an `ActiveSupport::TimeZone`; `now:` defaults
+to the current time and exists so callers can pin "now" in tests.
+
+```ruby
+Cs133::Range.this_month(zone:, now: Time.now)    # => Cs133::Range spanning the current calendar month, in zone
+Cs133::Range.last_month(zone:, now: Time.now)    # => Cs133::Range spanning the previous calendar month, in zone
+Cs133::Range.last_7_days(zone:, now: Time.now)   # => Cs133::Range, 7 day-aligned days ending today, in zone
+Cs133::Range.last_30_days(zone:, now: Time.now)  # => Cs133::Range, 30 day-aligned days ending today, in zone
+Cs133::Range.year_to_date(zone:, now: Time.now)  # => Cs133::Range from the start of the year to now, in zone
+Cs133::Range.new(start_time:, end_time:)         # => Cs133::Range from explicit bounds
+
+range.start_time                                 # => Time/ActiveSupport::TimeWithZone, inclusive start
+range.end_time                                   # => Time/ActiveSupport::TimeWithZone, inclusive end
+range.to_range                                   # => (start_time..end_time), drop straight into where(...)
+range.length                                     # => Float seconds, end_time minus start_time
+range.previous                                   # => Cs133::Range, the equal-span window immediately before
+
+Cs133::Comparison.new(current:, previous:)       # => Cs133::Comparison; raises UnequalLengthError unless lengths match
+comparison.current                               # => Cs133::Range, the current window
+comparison.previous                              # => Cs133::Range, the prior window
+
+Cs133::Comparison::UnequalLengthError            # < Cs133::Error, raised when current.length != previous.length
+```
+
+### Recipe
+
+Scope a query to a UI-selected preset, then report it period-over-period. Always
+pass an explicit `zone:` — never let a range fall back to the server's local time.
+
+```ruby
+require "cs133"
+
+zone = "America/Los_Angeles" # e.g. Time.zone.name, or the signed-in user's tz
+
+# 1. Build a range from the selected preset.
+current = Cs133::Range.this_month(zone: zone)
+
+# 2. Drop it straight into a query — to_range is a plain (start..end).
+orders = Order.where(created_at: current.to_range)
+
+# 3. Compare it against the immediately preceding, equal-length window.
+comparison = Cs133::Comparison.new(current: current, previous: current.previous)
+
+this_period = Order.where(created_at: comparison.current.to_range).sum(:total)
+last_period = Order.where(created_at: comparison.previous.to_range).sum(:total)
+growth      = this_period - last_period
+```
+
+### Install
+
+Cs133 is a plain Ruby gem; install it into any app or gem that needs date-range
+filtering.
+
+1. Add it to the host's Gemfile:
+
+   ```ruby
+   gem "cs133"
+   ```
+
+2. Run `bundle install`.
+3. In plain Ruby, `require "cs133"` where bundler does not autoload it. A Rails
+   app requires it for you.
+4. Build ranges with an explicit `zone:` — pass `Time.zone.name` or the user's
+   timezone, never the server's local time.
+
+### Conventions
+
+- Always pass an explicit `zone:`. Ranges are timezone-aware on purpose; relying
+  on the server's local time is the bug Cs133 exists to prevent.
+- Treat `Cs133::Range` and `Cs133::Comparison` as immutable value objects — build
+  new ones, never mutate.
+- Feed queries with `to_range`; pass the whole `(start..end)` to `where(...)`
+  rather than pulling `start_time`/`end_time` apart.
+- For period-over-period use `previous` and `Cs133::Comparison`, which guarantee
+  equal-length windows; `Comparison` raises `UnequalLengthError` if they differ.
+- Reach for the presets (`this_month`, `last_month`, `last_7_days`,
+  `last_30_days`, `year_to_date`) before constructing a `Range` by hand.

data/lib/cs133/reference.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Cs133
+  module Reference
+    GUIDE_PATH = File.expand_path("reference/guide.md", __dir__)
+
+    def self.content
+      File.read(GUIDE_PATH).strip
+    end
+  end
+end

data/lib/cs133/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cs133
+  VERSION = "0.1.0"
+end

data/lib/cs133.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/time"
+require "active_support/core_ext/date"
+require "active_support/core_ext/numeric/time"
+
+require_relative "cs133/version"
+
+module Cs133
+  class Error < StandardError; end
+end
+
+require_relative "cs133/range"
+require_relative "cs133/comparison"
+require_relative "cs133/reference"

data/the_local/agents/cs133-develop.md

@@ -0,0 +1,127 @@
+---
+name: cs133-develop
+description: Use PROACTIVELY for building date-range filters and preset windows (this month, last month, last 7/30 days, year to date), scoping queries to a time range, and period-over-period reporting with deltas, percent change, and direction — MUST BE USED instead of hand-rolling `beginning_of_month` / `Time.now - 30.days` range math or comparing two windows by hand.
+tools: Read, Write, Edit, Grep
+scope: timezone-aware time-range value objects, presets, and period-over-period comparison
+---
+
+You build time-range filtering and period-over-period reporting with Cs133. Every
+range is built with an explicit `zone:`, every query is scoped with `to_range`, and
+every prior-period window comes from `previous` so the two windows are the same
+length.
+
+## What cs133 is
+
+Cs133 turns a date filter into timezone-aware time-range value objects that any
+query can consume, and reports one period against another. `Cs133::Range` builds a
+window — from two dates, from a named preset, or from explicit bounds — and hands
+back an inclusive start/end pair plus the equal-length window immediately before it.
+`Cs133::Comparison` takes two already-measured numbers and reports the change
+between them. Both are plain immutable value objects with no knowledge of where the
+numbers come from.
+
+Fire whenever the work involves a date-range picker, a "last 30 days" style preset,
+scoping a query to a time window, or a metric shown against its prior period.
+
+## Interface
+
+`zone:` is a timezone identifier String (`"America/Los_Angeles"`) or an
+`ActiveSupport::TimeZone`. `now:` defaults to the current time and exists so callers
+can pin "now" in tests.
+
+- `Cs133::Range.between(start_date:, end_date:, zone:)` — a range from two `Date`s,
+  covering the whole of both days in `zone` (start of `start_date` through end of
+  `end_date`). Equal dates give that one full day.
+- `Cs133::Range.this_month(zone:, now: Time.now)` — the current calendar month in `zone`.
+- `Cs133::Range.last_month(zone:, now: Time.now)` — the previous calendar month in `zone`.
+- `Cs133::Range.last_7_days(zone:, now: Time.now)` — 7 whole days in `zone`, ending
+  with today: start of 6 days ago through end of today.
+- `Cs133::Range.last_30_days(zone:, now: Time.now)` — 30 whole days in `zone`, ending
+  with today: start of 29 days ago through end of today.
+- `Cs133::Range.year_to_date(zone:, now: Time.now)` — start of the current year in
+  `zone` through `now` itself; unlike the other presets this one ends mid-day.
+- `Cs133::Range.new(start_time:, end_time:)` — a range from explicit `Time`s, for the
+  windows no preset covers. Applies no zone and validates nothing.
+- `Cs133::Range::InvalidBoundsError` — raised by `between` when `start_date` is after
+  `end_date`.
+- `range.start_time` — the inclusive start of the window.
+- `range.end_time` — the inclusive end of the window.
+- `range.to_range` — `(start_time..end_time)`, ready to drop into a query.
+- `range.length` — the span in seconds, as a Float.
+- `range.previous` — a new range of the same length ending where this one starts.
+- `Cs133::Comparison.new(current:, previous:)` — takes two measured **numbers** (two
+  sums, two counts), not two ranges.
+- `comparison.current` — the current period's number, as given.
+- `comparison.previous` — the prior period's number, as given.
+- `comparison.delta` — `current - previous`; negative when the metric fell.
+- `comparison.percent_change` — the change as a fraction of `previous` (`0.2` means
+  +20%). Returns `nil` when `previous` is zero — handle that before formatting.
+- `comparison.direction` — `:up`, `:down`, or `:flat`.
+
+## How to use it
+
+1. **Settle the timezone with the developer.** `zone:` has no safe default and the
+   right answer is domain-specific — the signed-in user's timezone, the account's, or
+   the app's `Time.zone.name`. Ask which one this feature means; do not pick, and do
+   not let the range fall back to the server's local time.
+
+2. **Build the current window.** Reach for a preset when one matches the filter:
+
+   ```ruby
+   current = Cs133::Range.this_month(zone: zone)
+   ```
+
+   For a custom picker, use `between` with the two `Date`s. It rejects a backwards
+   pair, so rescue that where user input arrives:
+
+   ```ruby
+   begin
+     current = Cs133::Range.between(start_date: params_start, end_date: params_end, zone: zone)
+   rescue Cs133::Range::InvalidBoundsError
+     # surface "start date must come before end date" to the user
+   end
+   ```
+
+3. **Scope the query with `to_range`.** Pass the whole range, not its ends:
+
+   ```ruby
+   this_period = Order.where(created_at: current.to_range).sum(:total)
+   ```
+
+4. **Measure the prior period over `previous`.** It is guaranteed to be the same
+   length, so the two numbers are comparable:
+
+   ```ruby
+   last_period = Order.where(created_at: current.previous.to_range).sum(:total)
+   ```
+
+5. **Compare the two numbers.** `Comparison` takes the measurements, never the ranges:
+
+   ```ruby
+   comparison = Cs133::Comparison.new(current: this_period, previous: last_period)
+
+   comparison.delta          # => 250.0
+   comparison.percent_change # => 0.2, or nil when last_period was zero
+   comparison.direction      # => :up
+   ```
+
+6. **Render defensively.** Branch on `direction` for the arrow or color, and handle a
+   `nil` `percent_change` with its own case (`"—"`, `"new"`) rather than formatting it.
+
+## Conventions
+
+- Always pass an explicit `zone:`. Timezone correctness is the whole point; a range
+  built off the server's local time is the bug this gem exists to prevent.
+- Never ask the developer for a zone twice in one feature — settle it once and thread
+  that same value through every range.
+- Treat `Cs133::Range` and `Cs133::Comparison` as immutable. Build new objects; never
+  mutate one or reassign its parts.
+- Feed queries `to_range`. Pull `start_time`/`end_time` apart only when an API
+  demands two separate arguments.
+- Prefer a preset over `Range.new`. `new` applies no zone and checks no bounds, so it
+  is the last resort for a window nothing else expresses.
+- Get the prior window from `previous`, not by subtracting dates yourself — that is
+  what keeps the two periods equal-length and the comparison honest.
+- Pass `now:` explicitly in tests to pin the clock; leave it out in production code.
+- Cs133 does not run queries, format numbers, or parse user input. Measuring and
+  displaying stay in the consuming code.

data/the_local/agents/cs133-info.md

@@ -0,0 +1,69 @@
+---
+name: cs133-info
+description: Use to learn what Cs133 offers — timezone-aware time ranges, its presets, and period-over-period comparison.
+tools: Read
+scope: timezone-aware time-range value objects, presets, and period-over-period comparison
+---
+
+You explain what Cs133 is and which local a reader needs next. You make no
+changes, give no steps, and never read Cs133's source.
+
+## What Cs133 is
+
+Cs133 is the middleman between a UI date filter and the queries it scopes. A
+stat's time range is an input that flows from the UI down to wherever the numbers
+originate, and the hard part of that input is getting period boundaries right in
+the account's timezone — where "this month" starts, where a day ends, what the
+immediately preceding window of the same span is. Cs133 owns exactly that and
+nothing else.
+
+Reach for it when an app filters or reports by period: dashboards, stat tiles,
+date pickers with presets, and anything that shows a number "vs. last period." It
+is pure Ruby value objects, with no knowledge of storage, metric, or UI layer — a
+range scopes a query the same way regardless of the app. If your time bounds are
+already correct and fixed, you don't need it.
+
+## Interface
+
+Cs133 exposes no commands of its own. Its surface is split across the other two
+locals:
+
+- **`cs133-install`** owns getting the gem into a host and loaded.
+- **`cs133-develop`** owns everything you call — building ranges, the presets,
+  the query-ready bounds, and comparison. It carries the exact signatures.
+
+Do not reconstruct those calls from here; this local deliberately does not carry
+them.
+
+## How to use it
+
+The only decision you make here is which local you need:
+
+- Cs133 is not yet in the host, or isn't loading → **`cs133-install`**.
+- Cs133 is available and you are writing code that filters, scopes, or reports by
+  period → **`cs133-develop`**.
+
+Both, in that order, if you are adding period filtering to an app for the first
+time.
+
+## Conventions
+
+- A **range** is an immutable value object holding an inclusive start and end
+  time. Build a new one; never mutate.
+- A **preset** is a named window resolved against a **zone** and an anchor time —
+  the current or previous calendar month, a trailing count of days, or the year
+  so far. Presets are day-aligned: they snap to the beginning and end of the day
+  in that zone.
+- **`zone:`** is a timezone identifier string or an `ActiveSupport::TimeZone`, and
+  it is always explicit. Ranges are timezone-aware on purpose; falling back to the
+  server's local time is the bug Cs133 exists to prevent.
+- The anchor for "now" is injectable, so tests pin the current time rather than
+  chasing it.
+- **Length** is a span in seconds, and the **previous** window is the equal-span
+  window immediately before a range — the basis of period-over-period.
+- A **comparison** is a separate value object over two already-measured numbers,
+  a current and a previous, not over the ranges themselves. It reports the change
+  between them: the raw difference, the proportional change, and whether it moved
+  up, down, or stayed flat. You query each range first, then compare the results.
+- Bounds are validated on construction: an inverted range is an error, not a
+  silently empty window.

data/the_local/agents/cs133-install.md

@@ -0,0 +1,70 @@
+---
+name: cs133-install
+description: Use to hook cs133 into a project — adding the gem to the Gemfile, bundling it, and requiring it. MUST BE USED instead of wiring it up by hand.
+tools: Bash, Read, Edit
+scope: timezone-aware time-range value objects, presets, and period-over-period comparison
+---
+
+You hook cs133 into a host project by following the steps below exactly, in
+order. You invent no step, no file, and no configuration that is not written
+here.
+
+## What cs133 is
+
+A pure-Ruby gem of timezone-aware time-range value objects; hook it in when the
+host needs date-range filtering or period-over-period reporting.
+
+## Interface
+
+- `gem "cs133"` — the Gemfile entry that puts the gem on the host's load path.
+- `require "cs133"` — loads the gem and defines its constants.
+
+## How to use it
+
+1. Confirm the host runs Ruby 3.2.0 or newer. cs133 will not install below that.
+
+2. Ask the developer which source to install from before editing anything. cs133
+   is at version 0.1.0 and its documented source is the GitHub repository:
+
+   ```ruby
+   gem "cs133", github: "tylercschneider/cs133", branch: "main"
+   ```
+
+   If the developer installs gems from RubyGems or a private mirror instead, use
+   the plain `gem "cs133"` form with whatever version constraint they give you.
+   Do not pick the source yourself.
+
+3. Add that line to the host's `Gemfile`. If the host is itself a gem, add
+   `spec.add_dependency "cs133"` to its `.gemspec` instead, and keep the Gemfile
+   line only when installing from GitHub.
+
+4. Tell the developer that cs133 depends on `activesupport` (>= 7.1) and will
+   pull it in. In a Rails host this changes nothing; in a plain Ruby host it adds
+   ActiveSupport as a new dependency. If that is unwanted, stop and let them
+   decide.
+
+5. Run `bundle install`. This updates the host's `Gemfile.lock`.
+
+6. Add `require "cs133"` explicitly wherever the host uses it. Do not rely on
+   Bundler's auto-require, even in Rails.
+
+7. Verify the install:
+
+   ```
+   bundle exec ruby -e 'require "cs133"; puts Cs133::VERSION'
+   ```
+
+   It must print a version. Anything else means the install did not take — report
+   the error rather than working around it.
+
+## Conventions
+
+- The install touches exactly two host files: `Gemfile` and `Gemfile.lock` (plus
+  the `.gemspec` when the host is a gem). It generates nothing, writes no
+  initializer, and adds no migration. If you are about to create a file, you have
+  left the install.
+- On a GitHub source there is no version to bump: re-sync with
+  `bundle update cs133` when the branch moves, and commit the resulting
+  `Gemfile.lock`.
+- Using the gem — building ranges, reading their bounds, comparing periods — is
+  out of scope here. That belongs to the develop local.

data/the_local/interface.yml

@@ -0,0 +1,30 @@
+scope: timezone-aware time-range value objects, presets, and period-over-period comparison
+
+install:
+  - gem "cs133"
+  - require "cs133"
+
+develop:
+  - Cs133::Range.between
+  - Cs133::Range.this_month
+  - Cs133::Range.last_month
+  - Cs133::Range.last_7_days
+  - Cs133::Range.last_30_days
+  - Cs133::Range.year_to_date
+  - Cs133::Range.new
+  - Cs133::Range::InvalidBoundsError
+  - range.start_time
+  - range.end_time
+  - range.to_range
+  - range.length
+  - range.previous
+  - Cs133::Comparison.new
+  - comparison.current
+  - comparison.previous
+  - comparison.delta
+  - comparison.percent_change
+  - comparison.direction
+
+sources:
+  - lib/cs133/range.rb
+  - lib/cs133/comparison.rb

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: cs133
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- tylercschneider
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Cs133 is the middleman between a UI date filter and the queries it scopes.
+  It builds timezone-aware time ranges from presets (this month, last month, last
+  7/30 days, year to date), exposes them as plain start/end pairs any query can consume,
+  and compares two equal-length ranges for period-over-period reporting. Pure Ruby
+  value objects — no Rails, no knowledge of where the numbers come from.
+email:
+- tylercschneider@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".claude/agents/the_local-develop.md"
+- ".claude/agents/the_local-info.md"
+- ".claude/agents/the_local-install.md"
+- CHANGELOG.md
+- CLAUDE.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- develop_process_rules.md
+- lib/cs133.rb
+- lib/cs133/comparison.rb
+- lib/cs133/range.rb
+- lib/cs133/reference.rb
+- lib/cs133/reference/guide.md
+- lib/cs133/version.rb
+- the_local/agents/cs133-develop.md
+- the_local/agents/cs133-info.md
+- the_local/agents/cs133-install.md
+- the_local/interface.yml
+homepage: https://github.com/tylercschneider/cs133
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/tylercschneider/cs133
+  source_code_uri: https://github.com/tylercschneider/cs133
+  changelog_uri: https://github.com/tylercschneider/cs133/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/tylercschneider/cs133/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Timezone-aware time-range value objects with presets and period-over-period
+  comparison
+test_files: []