Skip to content

Complete command builder configuration and execution APIs - #113

Merged
konard merged 5 commits into
mainfrom
issue-34-389ba67e
Oct 24, 2026
Merged

konard merged 5 commits into
mainfrom
issue-34-389ba67e

Conversation

@konard

@konard konard commented Sep 9, 2025 •

Copy link
Copy Markdown
Member

Literal command descriptions now support fluent, functional, argv-array, constructor and preset styles consistently in JavaScript, with owned fluent/functional builders in Rust. Descriptions remain lazy and reusable, pass arguments directly to the executable, and support synchronous and asynchronous execution.

Fixes #34

await $.command('cat', './some-file.txt')
  .pipe($.command.stdout('inherit'), $.command.exitCode)
  .run();

Changes:

  • Add immutable argument/configuration methods, nested defaults, configured shell factories and per-execution overrides. Snapshot env/ANSI maps and local-directory arrays; merge explicit environment layers with variable removal. Strict types preserve result selection through long pipelines and reject incompatible transforms.
  • Share the builder across full/core ESM and CommonJS entries. Retain the current monorepo and compatibility APIs, with latest main merged.
  • Fix native synchronous execution to honor inherited/ignored stdio and disabled capture. Inherited output appears once, inherited stdin reaches the child, and piped output still emits events when capture is disabled. Sync buffering and cancellation limits are documented.
  • Extend Rust builders with composition, native environment maps/clear/removal and synchronous execution. Replay environment changes in order using native key comparison, including Windows case-insensitive names. Share native configuration across sync/async and drain output concurrently with buffered stdin.
  • Add the builder guide, library-wide JavaScript comparison and per-project Rust comparison. Cover all twelve JavaScript and fourteen Rust projects in the published audits, plus the issue's Effect reference, across execution, I/O, configuration, lifecycle, shell, streams and development tools. Update stale audit claims and map environment-clear/removal units to executable ports in both exact ledgers.
  • Prepare JavaScript and Rust minor releases with the existing release fragments.

Reproduction and regression coverage:

  • Original focused tests failed for missing fluent methods, argv/options and preset construction, ignored run options and missing Rust composition/environment methods. Tests now execute the exact issue example, hostile argv and executable paths, reusable descriptions, configuration precedence, stdio, streams, pipelines, deadlines and cancellation. Rust includes a 160 KiB input/output case to detect pipe deadlocks.
  • Follow-up tests first failed for sync stdio/capture/inherited stdin, mutable nested presets and unsound long-pipeline types. Runtime and strict type regressions remain in the normal suites. A portable Rust fixture exercises environment clear/remove/re-add and native key semantics in sync/async; Windows CI checks its platform-specific branch.

Validation:

  • Full Bun suite: 2,899 passed, 10 skipped, 0 failed; standalone Node builder suite: 7 passed.
  • Rust all-features suite: 962 passed, 7 ignored, 0 failed in the full serial run.
  • Remote validation on 0acfa3d52ae7b8b4b24504f5d11385a264735c89: 49 checks passed across all eight workflows; six release-only jobs were skipped as expected. Every run was created at 2026-10-24 12:37:39 UTC, after the commit at 12:37:19 UTC. This includes Node 22/24/26, Bun, Rust on Linux/macOS/Windows, package validation, security, benchmarks and repository checks. The Windows Rust log confirms the native environment-key regression passed. All CI checks.
  • JavaScript lint, formatting, duplication and strict TypeScript checks; Rust formatting, all-target/all-feature Clippy and rustdoc with warnings denied.
  • All 37 JavaScript/Rust feature examples pass parity checks; generated documentation and relative documentation links are checked.
  • The first parallel Rust run hit the existing intermittent cancellation assertion at cancelled_output.rs:105. Its focused rerun and full serial suite pass without increasing deadlines; evidence is recorded below.
  • Playwright verification from the initial implementation checks all five comparison alternatives and horizontal overflow. The subsequent changes add Markdown documentation and runtime/type regressions.

The comparison credits competitors' strengths and records specialized contracts and runtime limits. It establishes coverage of the published discovery sets; it does not claim unmeasured universal performance superiority or complete upstream API conformance.

The comparison page before and after correcting competitor support:

Before After
Previous comparison Corrected comparison

Requirement and root-cause evidence.

Adding CLAUDE.md with task information for AI processing.
This file will be removed when the task is complete.

Issue: #34
@konard konard self-assigned this Sep 9, 2025
konard and others added 2 commits September 9, 2025 21:20
🚀 Add $.command() builder API as requested in issue #34:
- CommandBuilder class with fluent API
- Safe argument escaping to prevent shell injection
- Pipe configuration support: $.command.stdout(), $.command.exitCode()
- Full feature set: stdin, env, cwd, capture, mirror options
- Method chaining: .arg(), .env(), .cwd(), .run()
- Direct access via CommandBuilder class and command() function

✅ Features:
- Exactly matches issue example: $.command("cat", "./file").pipe($.command.stdout("inherit"), $.command.exitCode).run()
- Automatic string conversion and shell escaping for safety
- Integration with existing ProcessRunner infrastructure
- Comprehensive test suite with 21 tests covering safety and functionality
- Full documentation with examples and comparison table

🔧 Breaking: Minor version bump to 0.8.0 for new API

Fixes #34

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@konard konard changed the title [WIP] Support command builder Implement command builder API for safe command construction Sep 9, 2025
@konard
konard marked this pull request as ready for review September 9, 2025 18:29
@konard

konard commented Oct 24, 2026 •

Copy link
Copy Markdown
Member Author

Resolve conflicts and double check we fully implement it and beat exactly all our competitors. Support all API styles and configurations and so on, do have clear docs and comparison with competitors across all the features (not only this specific feature).

@konard
konard marked this pull request as draft October 24, 2026 10:17
@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

🤖 AI Work Session Started

Started at 2026-10-24T10:17:20.077Z. Please wait for it to finish before giving feedback.

Runtime: solve v2.39.6 · tool codex · model gpt-6.1-sol · task image konard/hive-mind-dind:2.39.6@sha256:2d5d8294e932465fc7f8065662e8bd9c1f2d25e00a20a6c25c388bcec6d2c00d

@konard konard changed the title Implement command builder API for safe command construction Complete command builder configuration and execution APIs Oct 24, 2026
@konard
konard marked this pull request as ready for review October 24, 2026 10:58
@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

Working session summary

PR #113 is ready for review and remains unmerged.

  • Resolved conflicts with latest main.
  • Expanded JavaScript/Rust builder APIs, regression tests, documentation, and competitor comparisons.
  • CI: 49 passed; six release jobs skipped as expected.
  • Local tests: 2,891 JavaScript, 961 Rust, and five Node tests passed.
  • Working tree is clean.

This summary was automatically extracted from the AI working session output.

@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Model: GPT-6.1 Sol
  • Provider: OpenAI
  • Public pricing estimate: $4.696597

📊 Context and tokens usage:

  • 324.0K input tokens across requests (cumulative, larger than the 272K context window, so not one request's context), 57.0K / 128K (44%) output tokens

Total: (324.0K + 12.7M cached) input tokens, 57.0K output tokens, $4.696597 cost

🤖 Models used:

  • Tool: OpenAI Codex
  • Requested: gpt-6.1-sol
  • Thinking level: xhigh (~31999 tokens)
  • Model: GPT-6.1 Sol (gpt-6.1-sol)

📎 Log file uploaded as Gist (2250KB)


Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

✅ Ready to merge

This pull request is now ready to be merged:

  • All CI checks have passed
  • No merge conflicts
  • No uncommitted changes

Note: Issue #34 has been closed. Reopen issue #34 so auto-merge can complete, or merge this pull request manually.

@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

Double check that #34 and #113 (comment) are fully delivered and we have highest possible quality command builders in multiple commonly used styles, to fully beat all the competitors, and all docs are carefully updated to make sure we really do better than exactly all open-source competitors.

@konard
konard marked this pull request as draft October 24, 2026 11:58
@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

🤖 AI Work Session Started

Started at 2026-10-24T11:58:53.272Z. Please wait for it to finish before giving feedback.

Runtime: solve v2.39.6 · tool codex · model gpt-6.1-sol · task image konard/hive-mind-dind:2.39.6@sha256:2d5d8294e932465fc7f8065662e8bd9c1f2d25e00a20a6c25c388bcec6d2c00d

@konard
konard marked this pull request as ready for review October 24, 2026 12:47
@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

Working session summary

Updated PR #113, marked ready and left unmerged.

Fixed sync execution, preset immutability, pipeline types and Rust environment handling. Expanded comparisons across 26 audited alternatives, documenting remaining differences.

Validation: 2,899 JavaScript, 962 Rust and 7 Node tests passed; 49 CI checks passed. Working tree is clean and latest main is included.

Elapsed: 49 minutes.


This summary was automatically extracted from the AI working session output.

@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

  • Model: GPT-6.1 Sol
  • Provider: OpenAI
  • Public pricing estimate: $4.941557

📊 Context and tokens usage:

  • 356.7K input tokens across requests (cumulative, larger than the 272K context window, so not one request's context), 60.9K / 128K (48%) output tokens

Total: (356.7K + 13.0M cached) input tokens, 60.9K output tokens, $4.941557 cost

🤖 Models used:

  • Tool: OpenAI Codex
  • Requested: gpt-6.1-sol
  • Thinking level: xhigh (~31999 tokens)
  • Model: GPT-6.1 Sol (gpt-6.1-sol)

📎 Log file uploaded as Gist (2416KB)


Now working session is ended, feel free to review and add any feedback on the solution draft.

@konard

konard commented Oct 24, 2026

Copy link
Copy Markdown
Member Author

✅ Ready to merge

This pull request is now ready to be merged:

  • All CI checks have passed
  • No merge conflicts
  • No uncommitted changes

Note: Issue #34 has been closed. Reopen issue #34 so auto-merge can complete, or merge this pull request manually.

@konard
konard merged commit 0d89fdc into main Oct 24, 2026
55 checks passed
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.

Support command builder

1 participant