Skip to content

refactor(cli): organize migrated workflow modules#3163

Merged
cv merged 3 commits into
mainfrom
refactor/reorg-migrated-workflows
May 7, 2026
Merged

refactor(cli): organize migrated workflow modules#3163
cv merged 3 commits into
mainfrom
refactor/reorg-migrated-workflows

Conversation

@cv

@cv cv commented May 7, 2026

Copy link
Copy Markdown
Collaborator

Summary

Organizes the recently migrated internal workflows so command, action, domain, and adapter directories explain the intended layering. The PR also makes two environment-sensitive tests hermetic so local pre-push checks pass on Spark/router developer machines.

Changes

  • Move migrated DNS, uninstall, dev-shim, and installer action modules into workflow-specific src/lib/actions/<area>/ directories.
  • Move dev shim domain helpers under src/lib/domain/dev/npm-link-or-shim.ts.
  • Update internal command imports to use the reorganized action paths.
  • Add small orientation READMEs for src/commands/internal, src/lib/actions, src/lib/domain, and src/lib/adapters.
  • Isolate Model Router and NVIDIA platform tests from ambient localhost port and host firmware state.

Type of Change

  • Code change (feature, bug fix, or refactor)
  • Code change with doc updates
  • Doc only (prose changes, no code sample modifications)
  • Doc only (includes code sample changes)

Verification

  • npx prek run --all-files passes
  • npm test passes
  • Tests added or updated for new or changed behavior
  • No secrets, API keys, or credentials committed
  • Docs updated for user-facing behavior changes
  • make docs builds without warnings (doc changes only)
  • Doc pages follow the style guide (doc changes only)
  • New doc pages include SPDX header and frontmatter (new pages only)

Signed-off-by: Carlos Villela cvillela@nvidia.com

Summary by CodeRabbit

  • Documentation

    • Added architectural docs clarifying internal CLI commands, and the Actions, Adapters, and Domain module boundaries and layouts.
  • Bug Fixes

    • Improved GPU detection for generic Linux systems.
    • Made Model Router onboarding use dynamic ports so provider configuration works with non-default router ports.

@cv cv self-assigned this May 7, 2026
@coderabbitai

coderabbitai Bot commented May 7, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: ba197998-7b64-449d-91ed-6ef28fd4baf6

📥 Commits

Reviewing files that changed from the base of the PR and between 9da1121 and c0cb87d.

📒 Files selected for processing (3)
  • src/lib/actions/dns/index.test.ts
  • src/lib/actions/dns/index.ts
  • test/onboard.test.ts

📝 Walkthrough

Walkthrough

This PR restructures module imports across the codebase to nested paths (e.g., action/domain nesting), adds READMEs for Actions/Domain/Adapters, updates CLI/action/test imports to the new layout, and improves tests with firmware mocking and dynamic router port allocation.

Changes

Module Restructuring and Architectural Documentation

Layer / File(s) Summary
Architectural Documentation
src/commands/internal/README.md, src/lib/actions/README.md, src/lib/adapters/README.md, src/lib/domain/README.md
Four README files document the role of Commands (CLI entrypoints), Actions (workflow orchestration), Domain (pure logic), and Adapters (I/O boundaries), with guidance on delegating concerns across layers.
Domain Module Updates
src/lib/domain/dev/npm-link-or-shim.test.ts, test/npm-link-or-shim.test.ts
Test imports updated to reference npm-link-or-shim instead of dev-shim.
Action Module Import Refactoring
src/lib/actions/dev/npm-link-or-shim.ts, src/lib/actions/dev/npm-link-or-shim.test.ts, src/lib/actions/dns/index.ts, src/lib/actions/dns/index.test.ts, src/lib/actions/installer/plan.ts, src/lib/actions/installer/plan.test.ts, src/lib/actions/uninstall/plan.ts, src/lib/actions/uninstall/plan.test.ts, src/lib/actions/uninstall/run-plan.ts, src/lib/actions/uninstall/run-plan.test.ts
Action files update imports from ../domain/... to ../../domain/... and migrate flat module names (e.g., installer-plan) to nested paths (e.g., installer/plan). Exported APIs and runtime logic remain unchanged.
Command Layer Updates
src/commands/internal/dev/npm-link-or-shim.ts, src/commands/internal/installer/normalize-env.ts, src/commands/internal/installer/plan.ts, src/commands/internal/uninstall/classify-shim.ts, src/commands/internal/uninstall/plan.ts, src/commands/internal/uninstall/run-plan.ts
CLI command files redirect imports to the reorganized action module paths; command behavior and signatures are unchanged.

Test Infrastructure Improvements

Layer / File(s) Summary
GPU Detection Test Helpers
src/lib/nim.test.ts
Introduces withGenericLinuxFirmware helper to mock /sys/class/dmi/id/product_name and /sys/firmware/devicetree/base/model for isolated firmware testing. Jetson AGX Orin and Xavier GPU detection tests are wrapped in this helper.
Dynamic Router Port Allocation
test/onboard.test.ts
Model Router integration test computes routerPort from process PID and dynamically patches blueprint.yaml endpoint and provider command assertions instead of using hardcoded port 4000, enabling parallel test execution.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

NemoClaw CLI, priority: medium, NV QA

Poem

🐰 I hopped through paths both neat and clean,
From flat modules to a hierarchy keen,
Actions delegate, domain stays pure,
Adapters handle what's unsure. 🏗️
Tests now mock their firmware dreams,
With dynamic ports in organized schemes.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly and concisely summarizes the main change: reorganizing migrated workflow modules into a more structured directory layout with explicit layering (commands, actions, domain, adapters).
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

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

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/reorg-migrated-workflows

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

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🧹 Nitpick comments (1)
test/onboard.test.ts (1)

2481-2488: ⚡ Quick win

Fail fast if blueprint patch replacement stops matching

Line 2485/Line 2486 use exact string replacements; if blueprint formatting changes, this silently no-ops and can regress to the default router port path. Add a guard so the test fails explicitly when patching does not occur.

Suggested patch
 fs.readFileSync = (filePath, ...args) => {
   const raw = originalReadFileSync(filePath, ...args);
   if (filePath === blueprintPath || String(filePath) === blueprintPath) {
-    return String(raw)
-      .replace('endpoint: "http://localhost:4000/v1"', 'endpoint: "http://localhost:' + routerPort + '/v1"')
-      .replace("port: 4000", "port: " + routerPort);
+    const next = String(raw)
+      .replace(
+        /endpoint:\s*"http:\/\/localhost:4000\/v1"/,
+        `endpoint: "http://localhost:${routerPort}/v1"`,
+      )
+      .replace(/port:\s*4000\b/, `port: ${routerPort}`);
+    if (next === String(raw)) {
+      throw new Error("Failed to patch blueprint router endpoint/port in test fixture");
+    }
+    return next;
   }
   return raw;
 };
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/onboard.test.ts` around lines 2481 - 2488, The fs.readFileSync test shim
that patches the blueprint (overriding fs.readFileSync and using blueprintPath,
originalReadFileSync, and routerPort) should fail the test if the expected
string replacements did not occur; after performing the two .replace calls,
detect whether the returned string actually changed (or whether it contains the
expected patched substrings like the new endpoint or port) and throw or assert
(fail fast) when the patch hasn't been applied so the test will break if
blueprint formatting changes.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/onboard.test.ts`:
- Around line 2481-2488: The fs.readFileSync test shim that patches the
blueprint (overriding fs.readFileSync and using blueprintPath,
originalReadFileSync, and routerPort) should fail the test if the expected
string replacements did not occur; after performing the two .replace calls,
detect whether the returned string actually changed (or whether it contains the
expected patched substrings like the new endpoint or port) and throw or assert
(fail fast) when the patch hasn't been applied so the test will break if
blueprint formatting changes.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 2c9c1b48-d4d2-4642-ae6f-4387063a8a3b

📥 Commits

Reviewing files that changed from the base of the PR and between 2c3a392 and 9da1121.

📒 Files selected for processing (25)
  • src/commands/internal/README.md
  • src/commands/internal/dev/npm-link-or-shim.ts
  • src/commands/internal/installer/normalize-env.ts
  • src/commands/internal/installer/plan.ts
  • src/commands/internal/uninstall/classify-shim.ts
  • src/commands/internal/uninstall/plan.ts
  • src/commands/internal/uninstall/run-plan.ts
  • src/lib/actions/README.md
  • src/lib/actions/dev/npm-link-or-shim.test.ts
  • src/lib/actions/dev/npm-link-or-shim.ts
  • src/lib/actions/dns/index.test.ts
  • src/lib/actions/dns/index.ts
  • src/lib/actions/installer/plan.test.ts
  • src/lib/actions/installer/plan.ts
  • src/lib/actions/uninstall/plan.test.ts
  • src/lib/actions/uninstall/plan.ts
  • src/lib/actions/uninstall/run-plan.test.ts
  • src/lib/actions/uninstall/run-plan.ts
  • src/lib/adapters/README.md
  • src/lib/domain/README.md
  • src/lib/domain/dev/npm-link-or-shim.test.ts
  • src/lib/domain/dev/npm-link-or-shim.ts
  • src/lib/nim.test.ts
  • test/npm-link-or-shim.test.ts
  • test/onboard.test.ts

@wscurran wscurran added NemoClaw CLI refactor PR restructures code without intended behavior change labels May 7, 2026

@cjagwani cjagwani left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

approved

@cv cv enabled auto-merge (squash) May 7, 2026 17:27
@cv cv merged commit edb85f0 into main May 7, 2026
13 of 14 checks passed
jyaunches pushed a commit that referenced this pull request May 8, 2026
## Summary
- Bump the docs release metadata to `0.0.37`.
- Document release-prep updates for messaging policy presets, sandbox
runtime utilities, and the GPU CDI troubleshooting path.
- Refresh generated `nemoclaw-user-*` skills from the updated docs.

## Source summary
- #3159 -> `docs/reference/troubleshooting.md`: Documents the GPU CDI
preflight warning and remediation for `nvidia.com/gpu=all` gateway start
failures.
- #2415 -> `docs/reference/network-policies.md`,
`docs/manage-sandboxes/messaging-channels.md`,
`docs/network-policy/customize-network-policy.md`: Clarifies that
Telegram, Discord, and Slack egress comes from opt-in messaging presets,
not the baseline policy.
- #3091 -> `docs/deployment/sandbox-hardening.md`,
`docs/network-policy/customize-network-policy.md`: Documents the
retained sandbox utilities `vi`, `jq`, and `dos2unix` while keeping
host-side policy files as the durable source of truth.

## Test plan
- `python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix
nemoclaw-user`
- `make docs`
- `npm run build:cli`
- `npm run typecheck:cli`
- Commit and pre-push hooks: markdownlint, docs-to-skills verification,
gitleaks, commitlint, CLI typecheck

## Skipped
- #3193 and #3191 matched `docs/.docs-skip` entries for experimental
shields/config paths.
- #3200 and #3183 were test-only fixes.
- #3189 and #3163 were internal documentation/refactor changes with no
public docs impact.

Made with [Cursor](https://cursor.com)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Clarified which utilities remain in the sandbox runtime for
lightweight inspection and cleanup
* Noted that messaging endpoints (Discord, Slack, Telegram) are not in
the baseline policy and that channel presets are applied during
onboarding
  * Added GPU passthrough troubleshooting for gateway startup
* Updated release/version bump and release-prep workflow guidance,
including Discord preset description updates
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
@cv cv deleted the refactor/reorg-migrated-workflows branch May 27, 2026 21:18
@wscurran wscurran added area: cli Command line interface, flags, terminal UX, or output and removed NemoClaw CLI labels Jun 3, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: cli Command line interface, flags, terminal UX, or output refactor PR restructures code without intended behavior change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants