Skip to content

Conversation

@flyingrobots
Copy link
Member

@flyingrobots flyingrobots commented Feb 4, 2026

Summary

  • Add JSONL command envelope helpers and result envelope utilities
  • Add alfredctl CLI plus JSONL command example/tests
  • Bump ecosystem version to 0.10.0 and update docs/changelogs

Packages Changed

  • @git-stunts/alfred (version bump + changelog entry)
  • @git-stunts/alfred-live (command channel + CLI)
  • Root docs/aggregated changelog

Testing

  • pnpm -r run lint
  • pnpm -r test

Summary by CodeRabbit

  • New Features

    • Added alfredctl CLI for emitting JSONL commands and a JSONL command envelope system (validation, encode/decode, execution) plus a command-channel example.
  • Documentation

    • Updated README and package docs with CLI and JSONL command channel usage; bumped release to v0.10.0.
  • Tests

    • Added unit tests covering encode/decode, execution, and error envelopes.
  • Chores

    • Added preflight/install checks and pre-push hook to validate lockfile and run release preflight.

@coderabbitai
Copy link

coderabbitai bot commented Feb 4, 2026

Warning

Rate limit exceeded

@flyingrobots has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 1 minutes and 46 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📝 Walkthrough

Walkthrough

Adds a JSONL command-envelope system and CLI to alfred-live; introduces encoding/decoding/validation/execution helpers, types, example, and tests. Both packages are bumped to v0.10.0 and alfred-live publishes a new alfredctl binary entry.

Changes

Cohort / File(s) Summary
Version Bumps
alfred/jsr.json, alfred/package.json, alfred-live/jsr.json, alfred-live/package.json
Bump from 0.9.1 → 0.10.0 for both packages. alfred-live/package.json adds bin mapping for alfredctl and updates dependency on @git-stunts/alfred.
Changelogs & Docs
CHANGELOG.md, COOKBOOK.md, README.md, alfred-live/CHANGELOG.md, alfred-live/README.md
Add 0.10.0 release notes and documentation for JSONL command channel and alfredctl; rename recipe to "Control plane CLI (JSONL)" and add usage examples.
Command Envelope Module
alfred-live/src/command-envelope.js, alfred-live/src/index.d.ts, alfred-live/src/index.js
New core JSONL envelope implementation and types (CommandEnvelope, ResultEnvelope). Adds validate/decode/encode/build/execute helpers and re-exports seven functions from index.
CLI Tool
alfred-live/bin/alfredctl.js
New Node CLI that builds and emits encoded command envelopes (subcommands: list, read, write), supports --id and --auth, and prints encoded JSONL to stdout with robust error handling.
Example & Tests
alfred-live/examples/control-plane/jsonl-channel.js, alfred-live/test/unit/command-envelope.test.js
New example wiring registry/router and executeCommandLine; unit tests for encode/decode round-trips, validation, execution flow, and error envelopes.
Scripts & Release
scripts/hooks/pre-push, scripts/release/preflight.mjs
Pre-push hook updated to run release preflight when package manifests change. Preflight now runs pnpm install --frozen-lockfile early and fails fast on install errors.

Sequence Diagram

sequenceDiagram
    participant CLI as alfredctl CLI
    participant Envelope as Envelope Handler
    participant Router as CommandRouter
    participant Registry as ConfigRegistry
    participant Result as Result Builder

    CLI->>Envelope: parse args → build CommandEnvelope
    Envelope->>Envelope: validateCommandEnvelope(envelope)
    CLI->>Envelope: encodeCommandEnvelope(envelope)
    Envelope-->>CLI: JSONL string (stdout)

    Note over CLI,Result: execution via executeCommandLine
    CLI->>Envelope: decodeCommandEnvelope(line)
    Envelope->>Router: executeCommandEnvelope(router, envelope)
    Router->>Registry: perform read/write/list
    Registry-->>Router: return data or error
    Router->>Result: buildResultEnvelope(id, result)
    Result->>Envelope: encodeResultEnvelope(resultEnvelope)
    Envelope-->>CLI: ResultEnvelope JSONL string
Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • Release v0.8.0 #8: Related prior work extending control-plane primitives (ConfigRegistry/CommandRouter) that the new JSONL envelope and CLI integrate with.

Poem

I nibble bytes and hum with glee,
JSONL carrots for you and me,
alfredctl sends a hopping line,
Envelopes bounce, results align,
A little rabbit cheers: "Deploy!" 🐰✨

🚥 Pre-merge checks | ✅ 2 | ❌ 1
❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 30.43% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and specifically summarizes the main change: adding JSONL command channel support with the v0.10.0 release, which is the primary focus across added envelope utilities, CLI, examples, and version bumps.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch release/v0.10.0

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Fix all issues with AI agents
In `@alfred-live/bin/alfredctl.js`:
- Around line 109-114: The error details printed when
encodeCommandEnvelope(envelope) fails may include sensitive fields like auth;
redact any auth/token fields before writing encoded.error.details to stderr.
Update the error printing logic that checks encoded.ok to sanitize
encoded.error.details (e.g., remove or replace auth, token, password keys) prior
to JSON.stringify, referencing encodeCommandEnvelope, encoded, and
encoded.error.details so the stderr output never contains the envelope.auth
contents.

In `@alfred-live/src/command-envelope.js`:
- Around line 205-210: validateOkResultEnvelope currently only ensures 'error'
is absent for ok results but allows envelopes with ok: true and missing data;
update validateOkResultEnvelope to also verify that envelope hasOwnProperty
'data' and that envelope.data is not undefined (or null if you prefer) and
return a ValidationError like 'data is required when ok is true.' when missing;
locate the validateOkResultEnvelope function and add this additional check
alongside the existing error-check.
🧹 Nitpick comments (1)
alfred-live/examples/control-plane/jsonl-channel.js (1)

11-20: Add explicit error handling for registry.register().

register() returns a Result object that indicates success or failure. The example currently ignores this return value and may fail later if registration fails (e.g., invalid path or duplicate registration). Since the example already handles errors from executeCommandLine() (line 31–32), add the same check here for consistency and robustness:

Suggested addition
-registry.register('retry/count', retryCount, {
+const result = registry.register('retry/count', retryCount, {
   parse: (value) => {
     const parsed = Number(value);
     if (!Number.isFinite(parsed)) {
       throw new Error('retry/count must be a number');
     }
     return parsed;
   },
   format: (value) => value.toString(),
 });
+if (!result.ok) {
+  throw new Error(result.error.message);
+}

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 Fix all issues with AI agents
In `@scripts/hooks/pre-push`:
- Around line 7-13: The script currently sets BASE_REF to "@{u}" then falls back
to "origin/main" and runs git diff into CHANGED_FILES which can fail if
origin/main doesn't exist; modify the logic around BASE_REF (the BASE_REF
variable and CHANGED_FILES assignment in the pre-push hook) to verify the chosen
ref exists before using it (e.g., use git rev-parse --verify or git show-ref)
and if it does not exist fall back to a safe ref such as HEAD or an empty tree,
then compute CHANGED_FILES from that verified ref so git diff won't error under
set -e; update conditionals that set BASE_REF to perform this existence check.

In `@scripts/release/preflight.mjs`:
- Around line 125-130: The current spawnSync call storing result in
installResult can leave error details hidden when pnpm is missing
(installResult.status may be null and installResult.error populated); update the
post-spawn handling around spawnSync('pnpm', ...) to check installResult.error
and log a clear message (including installResult.error.message or the error
object) before calling process.exit(installResult.status ?? 1), ensuring both
non-zero status and spawn errors are surfaced; refer to the installResult
variable, the spawnSync invocation, and the process.exit call when making this
change.

@flyingrobots
Copy link
Member Author

@coderabbitai Do you approve? Or do you have more changes you'd like to see?

@coderabbitai
Copy link

coderabbitai bot commented Feb 4, 2026

@flyingrobots This PR looks great! I'm happy to approve. Here's what stands out:

Well-structured release:

  • Consistent version bumps across all packages (0.9.1 → 0.10.0)
  • Comprehensive JSONL command envelope system with proper validation
  • New alfredctl CLI with good error handling and help output

Quality practices:

  • Unit tests added for the new command envelope functionality
  • Documentation thoroughly updated (README, COOKBOOK, CHANGELOGs)
  • Fixes incorporated for sensitive error details and ok result data requirements
  • Enhanced pre-push hooks with frozen lockfile validation

API design:

  • Clean separation with encode/decode utilities
  • Proper TypeScript definitions for the new API surface
  • Example code provided in jsonl-channel.js

The testing (lint + tests) has passed, and the scope is appropriate for a minor version bump. Nice work on this release!

✅ Actions performed

Comments resolved.

@flyingrobots flyingrobots merged commit 653ce58 into main Feb 4, 2026
2 checks passed
@flyingrobots flyingrobots deleted the release/v0.10.0 branch February 4, 2026 15:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant