@simonesiega/codex-limits 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -16,6 +16,28 @@ All notable changes to codex-limits are documented in this file.
 
 ### Security
 
+## [1.1.0] - 2026-07-31
+
+### Added
+
+- Added explicit OpenCode, pi, and GitHub Copilot CLI package subpath exports while keeping the package root dedicated to OpenCode loading and the internal core private.
+
+### Changed
+
+- Changed package safety messaging to distinguish read-only inspection commands from the explicitly confirmed `reset` remote mutation.
+- Changed packed-runtime checks to validate the packed CLI on macOS with Node.js 22.
+
+### Fixed
+
+- Fixed packed-package validation for canonical temporary-directory paths on macOS.
+- Fixed inconsistent reset-coupon counts to be reported as partial data instead of complete availability.
+- Fixed agent summaries to label unknown usage percentages as unknown instead of displaying them as 0%.
+
+### Security
+
+- Kept usage endpoint metadata and coupon redemption identifiers outside the combined limits data supplied to read-only TUI and agent renderers, and enforced resolved-path containment for local state reads.
+- Bounded pi integration filter matching against adversarial configuration patterns and updated the locked `brace-expansion` dependency to a non-vulnerable release.
+
 ## [1.0.0] - 2026-07-23
 
 ### Added

package/CONTRIBUTING.md

@@ -166,7 +166,7 @@ New agents should use the same small adapter shape as [`src/agents/opencode`](sr
 | 5    | Add installer, formatter, and host-behavior tests. When end-to-end automation is impractical, document the manual validation.   |
 | 6    | Add `docs/readme/agents/<agent-name>.md`.                                                                                       |
 | 7    | Add the integration to [Agent Integrations](docs/readme/agent-integrations.md).                                                 |
-| 8    | Update the README supported-agent summary and any target-specific package/build metadata.                                       |
+| 8    | Add `src/package/<agent-name>.ts`, its host-only `./<agent-name>` subpath, and the shared package-build metadata.               |
 | 9    | Add or update screenshots when the visual output changes.                                                                       |
 | 10   | Run the documentation link and schema checks.                                                                                   |
 

package/README.md

@@ -3,7 +3,11 @@
 </h1>
 
 <p align="center">
-  A polished terminal dashboard for checking Codex usage limits, reset times, and reset-credit coupons.
+  <strong>Monitor OpenAI Codex usage limits, reset times, and reset-credit coupons directly from your terminal.</strong>
+</p>
+
+<p align="center">
+  Every inspection command is read-only. Only <code>codex-limits reset</code> can modify remote state, and it always requires explicit interactive confirmation.
 </p>
 
 <p align="center">
@@ -16,7 +20,10 @@
 
 <p align="center">
   <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
-  <img src="https://img.shields.io/badge/test_coverage-96.2%25_lines-brightgreen" alt="Test coverage: 96.2% lines" />
+  <a href="https://www.npmjs.com/package/@simonesiega/codex-limits">
+    <img src="https://img.shields.io/npm/dm/@simonesiega/codex-limits?label=monthly%20downloads" alt="npm downloads in the last month"/>
+  </a>
+  <a href="https://github.com/simonesiega/codex-limits/actions/workflows/check.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/simonesiega/codex-limits/check.yml?branch=main&amp;label=tests" alt="Automated test status" /></a>
 </p>
 
 <p align="center">
@@ -154,7 +161,7 @@ The GitHub Copilot CLI integration adds a `/codex-limits` command that displays
 
 ### Adding new agents
 
-New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help, installer, and read-only diagnostic check; registering that descriptor in `src/agents/index.ts` automatically connects shared installation, compatibility help, and doctor diagnostics. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
+New agents use the same four-file adapter layout under `src/agents/<agent-name>`: `format.ts`, `install.ts`, `integration.ts`, and `plugin.ts`. The integration descriptor owns its metadata, environment help, installer, and read-only diagnostic check; registering that descriptor in `src/agents/index.ts` automatically connects shared installation, compatibility help, and doctor diagnostics. Every registered agent must also use a matching `src/package/<agent-name>.ts` host wrapper and expose `@simonesiega/codex-limits/<agent-name>` through the shared package-entry build. Each integration should show Codex limit information quickly and safely without exposing tokens, account IDs, cookies, auth headers, or raw local files.
 
 See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
 
@@ -162,17 +169,33 @@ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for a
 
 **`codex-limits`** is built around a shared core with different output surfaces on top of it.
 
-| Area               | Path                   | Purpose                                                                                                                                    |
-| ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| CLI entry          | `src/package/cli.ts`   | Starts the `codex-limits` command and delegates to the shared command registry.                                                            |
-| Core logic         | `src/package/core`     | Detects Codex data, normalizes live and local information, performs confirmed coupon redemption, and keeps sensitive values out of output. |
-| CLI commands       | `src/package/commands` | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers.                                  |
-| Terminal UI        | `src/package/tui`      | Renders the clean Ink-based dashboard from normalized usage data.                                                                          |
-| Agent integrations | `src/agents`           | Contains optional coding-agent adapters used by the `codex-limits agents` command group.                                                   |
-| Tests              | `tests`                | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic.                                   |
+| Area               | Path                          | Purpose                                                                                                                                    |
+| ------------------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| CLI entry          | `src/package/cli.ts`          | Starts the `codex-limits` command and delegates to the shared command registry.                                                            |
+| Agent host entries | `src/package/<agent-name>.ts` | Publish narrow, agent-specific host contracts through one shared package-entry build.                                                      |
+| Core logic         | `src/package/core`            | Detects Codex data, normalizes live and local information, performs confirmed coupon redemption, and keeps sensitive values out of output. |
+| CLI commands       | `src/package/commands`        | Defines command metadata, shared parsing and help, scoped runtime services, and focused command handlers.                                  |
+| Terminal UI        | `src/package/tui`             | Renders the clean Ink-based dashboard from normalized usage data.                                                                          |
+| Agent integrations | `src/agents`                  | Contains optional coding-agent adapters used by the `codex-limits agents` command group.                                                   |
+| Tests              | `tests`                       | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic.                                   |
 
 This structure keeps the project easy to extend: the core owns data meaning and authenticated network operations, while commands control when capabilities are used and the TUI and agents remain rendering-only surfaces.
 
+### Supported package interfaces
+
+For general use and automation, the supported interfaces are the `codex-limits` CLI and its documented [JSON output](docs/readme/json-output.md). The package does not currently expose a general-purpose JavaScript API.
+
+The npm module exports are reserved for supported agent hosts:
+
+| Module specifier                     | Purpose                                                                                   |
+| ------------------------------------ | ----------------------------------------------------------------------------------------- |
+| `@simonesiega/codex-limits`          | OpenCode plugin entry point retained at the package root for plugin-loader compatibility. |
+| `@simonesiega/codex-limits/opencode` | Explicit alias for the same OpenCode plugin module.                                       |
+| `@simonesiega/codex-limits/pi`       | Host-only entry point for the bundled pi extension.                                       |
+| `@simonesiega/codex-limits/copilot`  | Host-only entry point for the bundled GitHub Copilot CLI extension.                       |
+
+There is intentionally no `@simonesiega/codex-limits/core` export. Files under `src/package/core` are shared implementation details and are not covered by the package's public compatibility contract. The presence of an agent module export does not install or enable that integration; use `codex-limits agents install <agent-name>` for setup.
+
 ## Environment
 
 **`codex-limits`** works out of the box when it can find the required Codex data automatically. By default, it tries to detect the local Codex data directory and discover the information needed to show usage limits and reset-credit coupons. Most users do not need to configure anything manually.
@@ -236,7 +259,7 @@ codex-limits doctor
 ```text
 Codex Limits diagnostics
 
-Package version:                1.0.0
+Package version:                1.1.0
 Node.js version:                22.0.0
 Operating system:               Windows
 Codex home detected:            Yes

package/SECURITY.md

@@ -74,15 +74,15 @@ Please do not publicly disclose the vulnerability until a fix is available or di
 
 `codex-limits` is designed to keep raw local Codex files and sensitive values on your machine. It makes authenticated requests to the recognized ChatGPT Codex endpoints when retrieving live usage or reset-credit information, and only sends a reset-credit consume request after the user invokes and confirms `codex-limits reset`.
 
-The CLI performs bounded, read-only inspection of recognized Codex home candidates. It reads small non-sensitive JSON state files, bounded `sessions/**/rollout-*.jsonl` logs, and `auth.json` only for credential resolution. Traversal depth, directory entries, file counts, file sizes, JSONL line sizes, and response sizes are limited; nested symbolic links are skipped. Filesystem diagnostics are path-free, and fallback reset-duration text is accepted only in a compact normalized form. Raw local files, private paths, and credentials are never returned by the public CLI or JSON contracts.
+The CLI performs bounded, read-only inspection of recognized Codex home candidates. It reads small non-sensitive JSON state files, bounded `sessions/**/rollout-*.jsonl` logs, and `auth.json` only for credential resolution. Traversal depth, directory entries, file counts, file sizes, JSONL line sizes, and response sizes are limited; nested symbolic links are skipped, and resolved state files must remain inside the detected Codex home. Filesystem diagnostics are path-free, and fallback reset-duration text is accepted only in a compact normalized form. Raw local files, private paths, and credentials are never returned by the public CLI or JSON contracts.
 
 For live usage and coupon information, the project contacts the default ChatGPT Codex endpoints. The only environment endpoint override is `CODEX_LIMITS_USAGE_ENDPOINT`, mainly for testing or advanced setups. Overrides must use HTTPS, except for loopback HTTP during local testing. Authenticated requests reject redirects, use bounded timeouts and responses, and never include credential headers in diagnostics.
 
 The reset command first refreshes the coupon list and matches either the requested display index or the available coupon with the earliest expiration. Coupon timestamps must be bounded RFC 3339 values before they can reach public output or participate in selection. Redemption requires an exact internal service ID and the recognized `codex_rate_limits` reset type; `--soonest` refuses incomplete or inconsistent availability details rather than selecting a different coupon. It requires an interactive terminal, a displayed recap, and an explicit `y` or `yes` answer. The consume request includes the selected coupon's internal service ID and a fresh UUID idempotency key; transport fallback reuses the same request body. Coupon IDs and reset types remain internal and are not added to text or JSON coupon output. Known no-op service outcomes are reported without claiming that a coupon was used, and malformed or ambiguous responses are reported as unconfirmed.
 
-Agent integrations follow the same safety model: they should display a read-only summary by reusing the shared core, not send private Codex data to the agent, and not expose sensitive values inside the agent UI. The pi extension runs only its local command handler and does not inject a user or custom message into the model context. The GitHub Copilot CLI extension registers only a local session command, writes its safe result to the host timeline, and does not call the SDK's model-message methods.
+Agent integrations follow the same safety model: they should display a read-only summary by reusing the shared core, not send private Codex data to the agent, and not expose sensitive values inside the agent UI. Before combined limits data reaches TUI or agent renderers, the core removes usage endpoint metadata, opaque coupon identifiers, and coupon reset types needed only by the confirmed reset flow. The pi extension runs only its local command handler and does not inject a user or custom message into the model context. The GitHub Copilot CLI extension registers only a local session command, writes its safe result to the host timeline, and does not call the SDK's model-message methods.
 
-Agent installers use bounded reads and owner-only atomic replacements. The pi installer registers the already installed local package root and does not download a package or execute dependency lifecycle scripts. The Copilot installer copies the bounded extension bundle already present in the package, refuses to overwrite an unrecognized entry point, and does not install the SDK or another package.
+Agent installers use bounded reads and owner-only atomic replacements. The pi installer uses bounded package-filter matching, registers the already installed local package root, and does not download a package or execute dependency lifecycle scripts. The Copilot installer copies the bounded extension bundle already present in the package, refuses to overwrite an unrecognized entry point, and does not install the SDK or another package.
 
 The `codex-limits doctor` command exposes only package/runtime labels and bounded availability statuses. Its Codex, OpenCode, pi, and GitHub Copilot CLI checks never return credential values, private paths, endpoint URLs, configuration contents, or raw local files. The optional live reachability check uses the same authenticated, bounded, redirect-free usage transport as the dashboard.