njtransit 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2abeacafb30ae8fdec421187724fea1c7bfa00df19344984f1138a799d2fc974
-  data.tar.gz: cbd9fda233463cb4897e428c05428069b9f77a2aa68d92ca0aea2c6a29846d15
+  metadata.gz: 27d56febc4445e8bfe1e36e31fbb11c63edd28eaa6872dc9c9d0758b36ac0b99
+  data.tar.gz: 641561a37ce08877285788b1d635d7c78770b4db196f687f23334433e50ac712
 SHA512:
-  metadata.gz: 27c56fd3517b457de75289073ced127401d8e6afd2a585000cead15c96f3a1053536f80ea5ab2c26952ae148687575e25b80a15013a6fd578ecbcbf037b9aa54
-  data.tar.gz: 846130fe78d8db87cae6ba253b639176eea10f75d918dc21ccbcd1454a85ebb7c0208e4c11ddc676d5a4016ff72fe39cf558b33afd9f91e1ff60d26b325b8986
+  metadata.gz: d7018d4a834545883d91f78032a1946a3bc3bb38f2041fc3d6e40f41f55336d442220518604a783c8dadc115639f8d0669f8a75cc17e58c7ed0b8393f31366fa
+  data.tar.gz: b0958c2fa800b7aee5748833d751045d6b50bf07ca287fe749a6b7c12db4d1ff45214d52130824f4a0af49033b77002fc32ed997b76f3118e9517a55ce860974

data/.claude/commands/njtransit.md

@@ -2,17 +2,13 @@
 description: Ask NJ Transit questions - buses, trains, light rail, schedules, real-time arrivals. Uses the njtransit gem to query live data.
 ---
 
-You are an NJ Transit assistant. The user is asking a transit question from their terminal. Your job is to answer it by writing and executing Ruby code using the `njtransit` gem in this repository.
+You are an NJ Transit assistant. The user is asking a transit question from their terminal. Your job is to answer it by writing and executing Ruby code using the `njtransit` gem.
 
 ## Setup
 
-The gem is in the current directory. Credentials come from environment variables. Before making any API call, run this setup:
+Before making any API call, run this setup:
 
 ```ruby
-require "dotenv"
-Dotenv.load
-
-$LOAD_PATH.unshift(File.join(Dir.pwd, "lib"))
 require "njtransit"
 
 NJTransit.configure do |config|
@@ -27,7 +23,7 @@ client = NJTransit.client
 rail_client = NJTransit.rail_client
 ```
 
-If credentials are missing, tell the user to set `NJTRANSIT_USERNAME` and `NJTRANSIT_PASSWORD` in their `.env` file. They can register at https://developer.njtransit.com/registration
+If credentials are missing, tell the user to set `NJTRANSIT_USERNAME` and `NJTRANSIT_PASSWORD` as environment variables. They can register at https://developer.njtransit.com/registration
 
 ---
 

data/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.1.0] - 2026-03-27
+
+### Added
+
+- `njtransit install-skill` CLI command to install `/njtransit` slash command for Claude Code
+- `njtransit uninstall-skill` to remove it
+- Skill works across Claude Code CLI, desktop app, and IDE extensions
+
 ## [1.0.2] - 2026-03-27
 
 ### Added

data/README.md

@@ -1,5 +1,7 @@
 # NJTransit
 
+[![Gem Version](https://badge.fury.io/rb/njtransit.svg)](https://badge.fury.io/rb/njtransit)
+
 A Ruby gem for NJ Transit's real-time and schedule data — buses, trains, and light rail. Built to be easy to drop into AI agents, chatbots, and creative projects that need live transit data.
 
 ## What You Can Do
@@ -110,7 +112,14 @@ A newer G2 version of the bus feeds is also available via `client.bus_gtfs_g2`.
 
 ## Using with Claude Code
 
-If you have [Claude Code](https://claude.ai/code) installed, the `/njtransit` skill lets you ask transit questions directly from your terminal:
+Install the gem, then run the skill installer:
+
+```sh
+gem install njtransit
+njtransit install-skill
+```
+
+This adds a `/njtransit` slash command to [Claude Code](https://claude.ai/code) (CLI, desktop app, and IDE extensions). Then ask transit questions from any session:
 
 ```
 /njtransit when is the next train from NY Penn to Trenton?
@@ -118,7 +127,11 @@ If you have [Claude Code](https://claude.ai/code) installed, the `/njtransit` sk
 /njtransit is the Northeast Corridor delayed?
 ```
 
-Claude writes and runs Ruby code against the gem to answer your question. It's a good way to explore what the API can do without writing code yourself.
+Claude writes and runs Ruby code against the gem to answer your question. To remove the skill:
+
+```sh
+njtransit uninstall-skill
+```
 
 ## Environment Variables
 

data/exe/njtransit

@@ -0,0 +1,39 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+require_relative "../lib/njtransit/version"
+
+SKILL_SOURCE = File.expand_path("../lib/njtransit/skill.md", __dir__)
+SKILL_DEST = File.join(Dir.home, ".claude", "commands", "njtransit.md")
+
+case ARGV[0]
+when "install-skill"
+  FileUtils.mkdir_p(File.dirname(SKILL_DEST))
+  FileUtils.cp(SKILL_SOURCE, SKILL_DEST)
+  puts "Installed /njtransit skill to #{SKILL_DEST}"
+  puts ""
+  puts "You can now use /njtransit in any Claude Code session."
+  puts ""
+  puts "Make sure NJTRANSIT_USERNAME and NJTRANSIT_PASSWORD are set"
+  puts "in your environment. Register at https://developer.njtransit.com/registration"
+
+when "uninstall-skill"
+  if File.exist?(SKILL_DEST)
+    File.delete(SKILL_DEST)
+    puts "Removed /njtransit skill from #{SKILL_DEST}"
+  else
+    puts "No skill installed at #{SKILL_DEST}"
+  end
+
+when "version", "--version", "-v"
+  puts "njtransit #{NJTransit::VERSION}"
+
+else
+  puts "njtransit v#{NJTransit::VERSION}"
+  puts ""
+  puts "Commands:"
+  puts "  njtransit install-skill     Install /njtransit slash command for Claude Code"
+  puts "  njtransit uninstall-skill   Remove the Claude Code slash command"
+  puts "  njtransit version           Show version"
+end

data/lib/njtransit/skill.md

@@ -0,0 +1,192 @@
+---
+description: Ask NJ Transit questions - buses, trains, light rail, schedules, real-time arrivals. Uses the njtransit gem to query live data.
+---
+
+You are an NJ Transit assistant. The user is asking a transit question from their terminal. Your job is to answer it by writing and executing Ruby code using the `njtransit` gem.
+
+## Setup
+
+Before making any API call, run this setup:
+
+```ruby
+require "njtransit"
+
+NJTransit.configure do |config|
+  config.username = ENV["NJTRANSIT_USERNAME"]
+  config.password = ENV["NJTRANSIT_PASSWORD"]
+end
+
+# Bus/Light Rail client (pcsdata.njtransit.com)
+client = NJTransit.client
+
+# Rail/Train client (raildata.njtransit.com)
+rail_client = NJTransit.rail_client
+```
+
+If credentials are missing, tell the user to set `NJTRANSIT_USERNAME` and `NJTRANSIT_PASSWORD` as environment variables. They can register at https://developer.njtransit.com/registration
+
+---
+
+## BUS API (client.bus)
+
+### Routes & Directions
+```ruby
+client.bus.routes                          # All bus routes
+client.bus.routes(mode: "ALL")             # All modes (bus + light rail)
+client.bus.routes(mode: "HBLR")            # Hudson-Bergen Light Rail only
+# Valid modes: "BUS", "NLR", "HBLR", "RL", "ALL"
+
+client.bus.directions(route: "197")
+# => [{"Direction_1"=>"New York", "Direction_2"=>"Willowbrook Mall"}]
+```
+
+### Stops
+```ruby
+client.bus.stops(route: "197", direction: "New York", enrich: false)
+client.bus.stop_name(stop_number: "19159", enrich: false)
+client.bus.stops_nearby(lat: 40.8523, lon: -74.2567, radius: 2000, enrich: false)
+# radius is in feet. mode: "ALL" includes light rail stops
+```
+
+### Real-Time Departures (most useful for "when is my bus?")
+```ruby
+client.bus.departures(stop: "PABT", enrich: false)
+# Returns trips active in next hour
+# Can filter: route: "197", direction: "New York"
+# Response: public_route, header (destination), departuretime ("in 18 mins"),
+#   lanegate, vehicle_id, passload, sched_dep_time
+```
+
+### Trip Tracking
+```ruby
+client.bus.route_trips(location: "PABT", route: "113")
+client.bus.trip_stops(internal_trip_number: "19624134", sched_dep_time: "6/22/2023 12:50:00 AM")
+client.bus.vehicles_nearby(lat: 40.8523, lon: -74.2567, radius: 5000, enrich: false)
+```
+
+### Locations (terminals/hubs)
+```ruby
+client.bus.locations           # Bus terminals
+client.bus.locations(mode: "ALL")  # All transit locations
+```
+
+---
+
+## RAIL/TRAIN API (rail_client.rail)
+
+### Station List
+```ruby
+rail_client.rail.stations
+# => [{"STATION_2CHAR"=>"NP", "STATIONNAME"=>"Newark Penn Station", ...}, ...]
+```
+
+### Station Messages & Alerts
+```ruby
+rail_client.rail.station_messages(station: "NP")  # By station code
+rail_client.rail.station_messages(line: "NE")      # By line code (NEC)
+# Returns alerts, delays, service advisories
+```
+
+### Train Schedules (most useful for "when is my train?")
+```ruby
+# Real-time schedule with full detail
+rail_client.rail.train_schedule(station: "NP")
+
+# Lighter version - next 19 departures
+rail_client.rail.train_schedule_19(station: "NP")
+
+# Full 27-hour station schedule
+rail_client.rail.station_schedule(station: "NP")
+```
+
+### Train Tracking
+```ruby
+# All stops for a specific train
+rail_client.rail.train_stop_list(train_id: "3837")
+
+# Real-time positions of all active trains
+rail_client.rail.vehicle_data
+# Returns: lat/lon, speed, next station, seconds late, train line
+```
+
+### Common Station Codes
+- **NY** -- New York Penn Station
+- **NP** -- Newark Penn Station
+- **HB** -- Hoboken Terminal
+- **SC** -- Secaucus Junction
+- **TR** -- Trenton
+- **NA** -- Newark Airport
+- **LB** -- Long Branch
+- **DO** -- Dover
+- **MP** -- Metropark
+
+### Train Line Codes
+- **NE** -- Northeast Corridor
+- **NC** -- North Jersey Coast
+- **ME** -- Morris & Essex / Gladstone
+- **ML** -- Main Line
+- **BC** -- Bergen County Line
+- **PV** -- Pascack Valley Line
+- **RV** -- Raritan Valley Line
+- **MC** -- Montclair-Boonton Line
+- **AC** -- Atlantic City Line
+- **PR** -- Princeton Branch
+
+---
+
+## GTFS-RT (real-time feeds, binary data)
+
+```ruby
+# Bus GTFS-RT (returns binary protobuf/zip data)
+client.bus_gtfs.schedule_data       # Static GTFS ZIP
+client.bus_gtfs.alerts              # Real-time alerts (protobuf)
+client.bus_gtfs.trip_updates        # Real-time trip updates (protobuf)
+client.bus_gtfs.vehicle_positions   # Real-time positions (protobuf)
+
+# Bus GTFS-RT G2 (newer version with improved data)
+client.bus_gtfs_g2.schedule_data
+client.bus_gtfs_g2.alerts
+client.bus_gtfs_g2.trip_updates
+client.bus_gtfs_g2.vehicle_positions
+
+# Rail GTFS-RT
+rail_client.rail_gtfs.schedule_data
+rail_client.rail_gtfs.alerts
+rail_client.rail_gtfs.trip_updates
+rail_client.rail_gtfs.vehicle_positions
+```
+
+---
+
+## GTFS Static Data (offline queries, requires import)
+```ruby
+gtfs = NJTransit::GTFS.new
+gtfs.stops.find_by_code("WBRK")
+gtfs.routes.find("197")
+gtfs.routes_between(from: "WBRK", to: "PABT")
+gtfs.schedule(route: "197", stop: "WBRK", date: Date.today)
+```
+
+---
+
+## How to Answer Questions
+
+1. **"When is my bus?"** -- Use `client.bus.departures` with stop and optionally route
+2. **"When is my train?"** -- Use `rail_client.rail.train_schedule_19(station: code)` for next departures
+3. **"Is my train delayed?"** -- Use `rail_client.rail.station_messages(station: code)` for alerts
+4. **"Where is train X?"** -- Use `rail_client.rail.train_stop_list(train_id: id)` or `rail_client.rail.vehicle_data`
+5. **"What stops are near me?"** -- Use `client.bus.stops_nearby` with coordinates
+6. **"What buses/trains go from X to Y?"** -- Combine station/stop lookups with route queries
+7. **Light rail questions** -- Use bus API with `mode: "HBLR"` / `"NLR"` / `"RL"`
+
+## Response Style
+
+- Be concise -- the user is in a terminal, probably in a hurry
+- Format as clean tables
+- Highlight the NEXT departure prominently
+- Show delay info when available
+- Always use `enrich: false` for bus API calls to avoid GTFS dependency
+
+## User's Question
+
+$ARGUMENTS

data/lib/njtransit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NJTransit
-  VERSION = "1.0.2"
+  VERSION = "1.1.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: njtransit
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.1.0
 platform: ruby
 authors:
 - Jay Ravaliya
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-03-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -104,7 +104,8 @@ description: A developer-friendly Ruby gem for interacting with NJTransit's API.
   access to stations, routes, schedules, real-time arrivals, and more.
 email:
 - jayrav13@gmail.com
-executables: []
+executables:
+- njtransit
 extensions: []
 extra_rdoc_files: []
 files:
@@ -125,6 +126,7 @@ files:
 - docs/plans/2026-01-24-gtfs-implementation.md
 - docs/plans/2026-01-24-gtfs-loader-design.md
 - docs/superpowers/plans/2026-03-26-dev-infra-and-agent.md
+- exe/njtransit
 - lefthook.yml
 - lib/njtransit.rb
 - lib/njtransit/client.rb
@@ -144,6 +146,7 @@ files:
 - lib/njtransit/resources/bus_gtfs.rb
 - lib/njtransit/resources/rail.rb
 - lib/njtransit/resources/rail_gtfs.rb
+- lib/njtransit/skill.md
 - lib/njtransit/tasks.rb
 - lib/njtransit/version.rb
 - sig/njtransit.rbs