From 8015faab0fd0084595f49ce8083d6010796dd54f Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Fri, 22 May 2026 17:58:59 +0000 Subject: [PATCH] docs: add contribution tracking docs --- 00_STATE.md | 124 ++++++++++++++++++ 01_REPO_MAP.md | 266 +++++++++++++++++++++++++++++++++++++++ 05_PR_CANDIDATES.md | 133 ++++++++++++++++++++ 06_SELECTED_5_PR_PLAN.md | 232 ++++++++++++++++++++++++++++++++++ 4 files changed, 755 insertions(+) create mode 100644 00_STATE.md create mode 100644 01_REPO_MAP.md create mode 100644 05_PR_CANDIDATES.md create mode 100644 06_SELECTED_5_PR_PLAN.md diff --git a/00_STATE.md b/00_STATE.md new file mode 100644 index 0000000000..1a1b54c1e9 --- /dev/null +++ b/00_STATE.md @@ -0,0 +1,124 @@ +# 00_STATE.md — NemoClaw + +## Repository Info +- **Upstream**: `NVIDIA/NemoClaw` +- **Fork**: `okwn/NemoClaw` (cloned to `/root/oss-pr-campaign/repos/NemoClaw`) +- **Default branch**: `main` +- **Language**: TypeScript +- **Archived**: No +- **License**: Apache-2.0 + +## Upstream Stats +- Stars: 20,596 | Forks: 2,714 | Open Issues: 473 | Watchers: 20,596 +- Created: 2026-03-15 + +## Fork Status +- Forked at: 2026-05-22 17:14:06 UTC +- Branches synced: `main` (upstream) + all feature branches (500+ remote branches) +- No local development branches (main only) + +## Repository Structure + +``` +nemoclaw/ +├── bin/ # CJS CLI launchers (nemoclaw.js, nemohermes.js) +├── src/ # TypeScript CLI source +│ ├── lib/ # Core CLI logic +│ │ ├── actions/ # Sandbox, credentials, inference actions +│ │ ├── adapters/ # OpenShell, Docker, Gateway adapters +│ │ ├── cli/ # CLI entry point, commands +│ │ ├── cluster-image-patch.ts +│ │ ├── credentials/ # Credential management +│ │ ├── dashboard/ # Dashboard URL handling +│ │ ├── domain/ # Domain models, lifecycle +│ │ ├── gateway-runtime-action.ts +│ │ ├── inference/ # Inference provider config +│ │ ├── onboard/ # Onboarding FSM, providers +│ │ ├── policies/ # Network policy management +│ │ └── state/ # State management, paths +│ └── commands/ # CLI commands (oclif) +├── nemoclaw/ # OpenClaw plugin (Commander CLI extension) +│ └── src/ +│ ├── blueprint/ # Runner, snapshot, SSRF validation +│ ├── commands/ # Slash commands, migration state +│ └── onboard/ # Plugin onboarding +├── nemoclaw-blueprint/ # YAML blueprint definition +│ ├── policies/ # Network policy presets +│ ├── model-specific-setup/ # Agent-scoped compatibility +│ ├── router/ # Model router config +│ └── scripts/ # Blueprint scripts (TypeScript) +├── agents/ # Agent definitions (Hermes, OpenClaw) +├── test/ # Root-level integration tests (Vitest/ESM) +│ └── e2e/ # End-to-end tests, scenario runner +├── docs/ # Fern MDX docs + legacy MyST +├── fern/ # Fern site config +├── scripts/ # Bash/JS/TS automation +├── ci/ # CI helper scripts +└── tools/ # Development tools +``` + +## Package Info +- **Name**: `nemoclaw` +- **Version**: `0.1.0` +- **Node requirement**: `>=22.16.0` +- **Package manager**: npm +- **Key dependencies**: `@oclif/core@^4.10.5`, `js-yaml`, `yaml`, `p-retry`, `@aws-sdk/client-bedrock-runtime` +- **Dev dependencies**: Vitest, Biome, TypeScript, tsx, commitlint + +## Build & Test +- **Build**: `npm run build:cli` → TypeScript compiles `src/` to `dist/`, generates oclif manifest +- **Tests**: Vitest (5 projects: cli, installer-integration, plugin, e2e-scenario-framework, e2e-branch-validation) +- **Linting**: Biome + prek hooks (pre-commit, commit-msg, pre-push) +- **Format**: Biome format, shfmt for shell scripts +- **CI**: GitHub Actions (PR, nightly-e2e, sandbox-images, etc.) + +## CI/CD Workflows (`.github/workflows/`) +- `pr.yaml` — PR checks, basic-checks, Ollama proxy E2E +- `pr-self-hosted.yaml` — Sandbox image builds on NVIDIA runners +- `main.yaml` — Main branch CI +- `nightly-e2e.yaml` — Nightly E2E test suite +- `e2e-scenarios-all.yaml` — Scenario-based E2E +- `regression-e2e.yaml` — Regression E2E tests +- `brev-nightly-e2e.yaml` — Brev cloud E2E +- `platform-vitest-main.yaml` — Platform-specific Vitest +- `macos-e2e.yaml`, `wsl-e2e.yaml` — Platform E2E +- `base-image.yaml` — Base image builds +- `docs-preview-pr.yaml` — Docs preview for PRs +- `code-scanning.yaml` — CodeQL scanning +- `docker-pin-check.yaml` — Docker image pin validation + +## Test Status +``` +✓ CLI tests run (selected) +✓ Plugin compilation works +✓ TypeScript compiles cleanly +✓ Build artifact: dist/ + nemoclaw/dist/ +``` + +## Code Quality +- **Linter**: Biome (v2.4.14) + prek hooks +- **Formatter**: Biome + shfmt for shell scripts +- **Type system**: TypeScript strict (multiple tsconfig files) +- **Commit format**: Conventional Commits (enforced via commitlint) +- **SPDX headers**: Required on all source files +- **Shell scripts**: ShellCheck enforced + +## Open Issues Summary (473 open) +- **Bug reports**: WSL2/Docker issues, macOS sandbox, DGX Spark GPU +- **Security**: Permission issues (world-readable config), sandbox isolation +- **Policy/Network**: npm/pypi preset restrictions, proxy test behavior +- **Inference**: Ollama local setup, NIM container timeouts, model compatibility +- **Messaging**: Discord Telegram integration issues, channel enrollment +- **E2E**: Nightly test flakiness, OpenClaw version drift, Slack API changes + +## Key Observations +1. Very active development (500+ branches, 30 open PRs as of 2026-05-22) +2. Multi-project TypeScript monorepo (root CLI + nemoclaw plugin + blueprint) +3. Strong CI/CD culture — comprehensive E2E, platform-specific tests +4. Messaging subsystem under active VRDC development (workflow planner, manifest compiler) +5. Dual-language stack: TypeScript + YAML blueprint + Bash/Python scripts +6. Agent skills system for user/maintainer/contributor audiences +7. Large feature branch count suggests parallel development streams +8. Active security focus (permissions, sandbox isolation, SSRF validation) +9. OpenShell dependency critical — many issues reference OpenShell version compatibility +10. Brev cloud E2E testing for cloud provisioning validation \ No newline at end of file diff --git a/01_REPO_MAP.md b/01_REPO_MAP.md new file mode 100644 index 0000000000..8f8c4a8ca9 --- /dev/null +++ b/01_REPO_MAP.md @@ -0,0 +1,266 @@ +# 01_REPO_MAP.md — NemoClaw + +## Repository Hierarchy + +``` +github.com/NVIDIA/NemoClaw (upstream, org: NVIDIA) + └── fork: github.com/okwn/NemoClaw (user fork) +``` + +## Branches + +### Upstream (`NVIDIA/NemoClaw`) +| Branch | Description | +|--------|-------------| +| `main` | Primary development branch | +| `release/v0.0.7`, `release/v0.0.7.1` | Release branches | +| `docs-*` | Documentation updates | +| `ci-*` | CI/CD improvements | +| `refactor/*` | Large-scale refactoring (100+ branches) | +| `test/*` | Test coverage improvements | +| `fix/*` | Bug fixes | +| `feat/*` | Feature development | +| `worktree-*` | Worktree management | +| `upgrade/*` | Dependency upgrades | +| `u/*` | User branches | +| `revert/*` | Revert branches | +| `automation/*` | Automated sync branches | +| `codex/*` | Codex-assisted branches | +| `autoresearch/*` | Auto research branches | + +### Local (`okwn/NemoClaw`) +| Branch | Description | +|--------|-------------| +| `main` | Synced with upstream main | + +## Package Structure + +### Root Package (`nemoclaw`) +``` +nemoclaw (npm package) +├── bin/ +│ ├── nemoclaw.js # CLI launcher entry point (CJS) +│ └── nemohermes.js # Hermes alias launcher (CJS) +├── dist/ # Compiled CLI output +├── src/lib/ # TypeScript source → compiled to dist/ +├── src/commands/ # oclif command tree → dist/commands/ +└── package.json # npm package manifest +``` + +### Plugin Package (`nemoclaw/`) +``` +nemoclaw (oclif plugin) +├── dist/ # Compiled plugin output +├── src/ +│ ├── blueprint/ # Runner, snapshot, SSRF, state +│ ├── commands/ # Slash commands, migration +│ └── onboard/ # Onboarding config +├── openclaw.plugin.json # Plugin manifest +└── package.json # Separate npm project +``` + +### Blueprint Package (`nemoclaw-blueprint/`) +``` +nemoclaw-blueprint (YAML config + TS scripts) +├── blueprint.yaml # Main blueprint definition +├── policies/ # Network policy presets +│ └── presets/ # slack.yaml, discord.yaml, etc. +├── model-specific-setup/ # Per-agent compatibility manifests +├── router/ # Model router config +│ └── pool-config.yaml # Model pool definition +├── scripts/ # TypeScript helpers +└── tsconfig.json +``` + +## Source Code Structure + +``` +src/ +├── lib/ +│ ├── actions/ # Domain actions +│ │ ├── dev/ # npm link/shim actions +│ │ ├── sandbox/ # Sandbox lifecycle (create/destroy/rebuild) +│ │ └── skill-install.ts +│ ├── adapters/ # External system adapters +│ │ ├── openshell-adapter.ts +│ │ ├── docker-adapter.ts +│ │ └── gateway-adapter.ts +│ ├── cli/ +│ │ └── index.ts # CLI entry point +│ ├── cluster-image-patch.ts +│ ├── credentials/ # Credential registry & sanitization +│ │ ├── registry.ts +│ │ └── sanitize.ts +│ ├── dashboard/ # Dashboard URL handling +│ ├── deploy/ # Deployment actions +│ ├── diagnostics/ # Diagnostic tools +│ ├── domain/ # Domain models +│ │ └── lifecycle/ # Lifecycle state machines +│ ├── inference/ # Inference provider config +│ │ ├── config.ts +│ │ ├── local.ts # Ollama, vLLM +│ │ └── nim.ts # NVIDIA NIM +│ ├── onboard/ # Onboarding FSM +│ │ ├── index.ts # Main onboarding orchestrator +│ │ ├── machine/ # State machine transitions +│ │ ├── providers.ts # Provider selection +│ │ └── docker-driver-gateway-env.ts +│ ├── policies/ # Network policy management +│ ├── state/ # State persistence +│ │ └── paths.ts # Path resolution +│ ├── messaging/ # Messaging channel integration +│ └── hermes-provider-auth.ts +│ +└── commands/ # oclif command tree + ├── onboard.ts + ├── connect.ts + ├── status.ts + ├── logs.ts + ├── rebuild.ts + ├── destroy.ts + ├── list.ts + ├── inference/ + │ ├── get.ts + │ └── set.ts + ├── policy/ + ├── channels/ + ├── debug.ts + └── internal/ + ├── installer/ + │ └── plan.ts + └── ... + +nemoclaw/src/ +├── blueprint/ +│ ├── runner.ts # Sandbox runner +│ ├── snapshot.ts # Snapshot create/restore +│ ├── ssrf.ts # SSRF validation +│ └── state.ts # Blueprint state +├── commands/ +│ ├── index.ts # Slash command registry +│ └── migrate.ts # Migration handling +├── onboard/ +│ └── config.ts # Onboarding configuration +└── package-metadata.ts + +nemoclaw-blueprint/ +├── blueprint.yaml # Root blueprint YAML +├── private-networks.yaml # Private network config +├── policies/ # Policy definitions +│ ├── allowlisting/ # Allowlist rules +│ ├── presets/ # Preset policies +│ └── denylisting/ # Denylist rules +├── model-specific-setup/ # Per-model configuration +│ ├── openclaw/ # OpenClaw agent setup +│ └── hermes/ # Hermes agent setup +├── router/ # LLM router config +├── scripts/ # Blueprint TypeScript helpers +└── openclaw-plugins/ # OpenClaw plugin wrappers +``` + +## Test Structure + +``` +test/ # Root-level ESM tests (Vitest) +├── cli.test.ts +├── cli-oclif-compatibility.test.ts +├── install-preflight.test.ts # Slow, opt-in +├── install-openshell-version-check.test.ts # Slow, opt-in +├── seed-wechat-accounts.test.ts +├── generate-openclaw-config.test.ts +├── sandbox-build-context.test.ts +├── openclaw-tool-catalog-patch.test.ts +├── openclaw-tui-chat-correlation.test.ts +├── fetch-guard-patch-regression.test.ts +├── preinstall-node-version.test.ts +└── e2e/ + ├── test-cloud-inference-e2e.sh + ├── test-skill-agent-e2e.sh + ├── test-cloud-onboard-e2e.sh + ├── test-docs-validation.sh + ├── test-rebuild-openclaw.sh + ├── test-openclaw-slack-pairing.sh + ├── brev-e2e.test.ts # Cloud E2E (opt-in) + ├── scenario-framework-tests/ + │ └── e2e-lib-helpers.test.ts + └── lib/ + └── slack-api-proof.sh + +nemoclaw/src/ # Plugin unit tests (TypeScript, co-located) +├── package-metadata.test.ts +└── [co-located with source as *.test.ts] + +vitest.config.ts # Root Vitest config (5 projects) +nemoclaw/vitest.config.ts # Plugin Vitest config +``` + +## Key Files + +| File | Purpose | +|------|---------| +| `package.json` | Root package manifest (nemoclaw CLI) | +| `nemoclaw/package.json` | Plugin package manifest | +| `nemoclaw-blueprint/blueprint.yaml` | Blueprint definition | +| `vitest.config.ts` | Root Vitest configuration | +| `biome.json` | Biome linter/formatter config (shared) | +| `AGENTS.md` | Agent instructions and architecture docs | +| `CONTRIBUTING.md` | Contributing guidelines | +| `Makefile` | Make targets (check, lint, format, docs) | +| `install.sh` | Installer script | +| `uninstall.sh` | Uninstaller script | +| `Dockerfile` | Container build definition | +| `tsconfig.src.json` | CLI TypeScript config | +| `tsconfig.cli.json` | CLI type-check config | +| `jsconfig.json` | JS project references | +| `.github/workflows/*.yaml` | GitHub Actions workflows | +| `fern/fern.config.json` | Fern docs config | +| `pyproject.toml` | Python project config (uv) | + +## Agent Skills + +``` +.agents/skills/ +├── nemoclaw-user-* # End user skills +├── nemoclaw-maintainer-* # Project maintainer skills +└── nemoclaw-contributor-* # Codebase contributor skills +``` + +Load via `nemoclaw-skills-guide` skill for full catalog. + +## Network Policy Presets + +``` +nemoclaw-blueprint/policies/presets/ +├── slack.yaml +├── discord.yaml +├── brave.yaml +├── pypi.yaml +├── npm.yaml +└── [more platform-specific presets] +``` + +## Credentials System + +- Registry at `~/.nemoclaw/credentials/` (or equivalent state dir) +- Sanitization layer prevents credential leakage to sandbox +- Provider credentials: NVIDIA NIM, Ollama, OpenAI, Anthropic, Bedrock, etc. + +## Inference Providers + +- `nvidia` — NVIDIA NIM endpoints +- `openai` — OpenAI compatible +- `anthropic` — Anthropic +- `bedrock` — AWS Bedrock +- `ollama` — Local Ollama +- `ollama-local` — Local Ollama with full features +- `vllm` — vLLM local +- `routed` — Model router (experimental, NVIDIA LLM Router v3) + +## Platform Support Matrix + +| OS | Runtime | Status | +|----|---------|--------| +| Linux | Docker | Primary | +| macOS (Apple Silicon) | Colima, Docker Desktop | Tested (limitations) | +| DGX Spark | Docker | Tested | +| Windows WSL2 | Docker Desktop (WSL backend) | Tested (limitations) | \ No newline at end of file diff --git a/05_PR_CANDIDATES.md b/05_PR_CANDIDATES.md new file mode 100644 index 0000000000..3a9271276c --- /dev/null +++ b/05_PR_CANDIDATES.md @@ -0,0 +1,133 @@ +# 05_PR_CANDIDATES.md — NemoClaw + +## Overview +Analyzed 473 open issues and 30+ open PRs. Identified PRs with clear scope, well-defined changes, and areas where community contributions are welcome. + +## Selection Criteria +- **Clarity**: PR description clearly defines what/why/how +- **Scope**: Bounded, reviewable diff (not massive refactors) +- **Fit**: Areas where an external contributor can realistically make good changes +- **Freshness**: Prioritized recently opened (post-May 2026) +- **Priority**: Higher weight for bugs, security, and onboarding issues + +--- + +## Candidate 1: #4075 — fix(policy): split Claude Code from permissive policies +- **Status**: Open, not draft +- **Labels**: `fix`, `policy` +- **Opened**: 2026-05-22 +- **Branch**: `upstream/fix/policy-split-claude-code` +- **Summary**: Splits Claude Code handling out of permissive policies into a separate, explicit opt-in path +- **Why good candidate**: Clear security/policy fix. Small scope. Well-labeled. Affects policy subsystem which has good test coverage +- **Risk**: Low — targeted policy change +- **Files likely touched**: `nemoclaw-blueprint/policies/`, policy test files + +## Candidate 2: #4054 — fix(security): enforce owner-only permissions on ~/.nemoclaw directory and config files +- **Status**: Open, not draft +- **Labels**: `security`, `fix` +- **Opened**: 2026-05-22 +- **Branch**: `upstream/fix/security-permissions` +- **Summary**: Changes config file permissions from world-readable (644) to owner-only (600/700) after onboard +- **Why good candidate**: Security fix with clear problem/solution. High priority label. Affects credential safety +- **Risk**: Very low — adds permission hardening +- **Files likely touched**: `src/lib/credentials/`, `src/lib/state/`, onboarding flow + +## Candidate 3: #4026 — fix(onboard): mention 'none selected skips' in messaging-channels prompt +- **Status**: Open, not draft +- **Labels**: `NemoClaw CLI`, `enhancement: ui`, `fix`, `v0.0.50` +- **Opened**: 2026-05-22 +- **Referenced**: Issue #3471 +- **Summary**: Adds clarification text to the messaging-channels onboard prompt explaining that selecting "none" causes the step to be skipped +- **Why good candidate**: Small UX improvement. Easy to understand. Low risk. Good for learning codebase +- **Risk**: Very low — UI copy change +- **Files likely touched**: `src/lib/onboard/` prompt text, potentially `nemoclaw/src/onboard/` + +## Candidate 4: #4008 — fix(onboard): use NVIDIA runtime for Jetson sandbox GPU +- **Status**: Open, not draft +- **Labels**: `Platform: Jetson AGX Thor/Orin`, `NemoClaw CLI`, `fix`, `Sandbox`, `v0.0.50` +- **Opened**: 2026-05-21 +- **Summary**: Uses NVIDIA container runtime instead of Docker default for Jetson sandbox GPU passthrough +- **Why good candidate**: Platform-specific fix with clear hardware context. Small scope. Good for learning GPU/sandbox path +- **Risk**: Low — Jetson-specific path +- **Files likely touched**: `src/lib/onboard/sandbox-gpu-mode.ts`, Docker/GPU detection + +## Candidate 5: #4037 — fix(runtime): use prependSystemContext to prevent runtime instructions leaking into chat UI +- **Status**: Open, not draft +- **Labels**: `fix`, `enhancement: policy` +- **Opened**: 2026-05-22 +- **Summary**: Uses prependSystemContext API to prevent runtime instructions from appearing in the chat UI on third message +- **Why good candidate**: Addresses issue #4019 (System runtime instructions leaking into chat UI on third message). Clear bug fix with observable behavior +- **Risk**: Low — uses existing API correctly +- **Files likely touched**: Runtime context handling, chat UI injection points + +## Candidate 6: #4029 — fix(installer): preserve npm lockfiles during install +- **Status**: Open, not draft +- **Labels**: `Platform: macOS`, `NemoClaw CLI`, `fix` +- **Opened**: 2026-05-22 +- **Summary**: Preserves npm lockfiles during install to prevent accidental overwrites +- **Why good candidate**: macOS installer fix. Clear problem. Small scope +- **Risk**: Low — installer behavior change +- **Files likely touched**: `scripts/install.sh`, Node.js version/path detection + +## Candidate 7: #3979 — feature: nemoclaw session export +- **Status**: Open (enhancement request with PR likely) +- **Labels**: `Getting Started`, `NemoClaw CLI`, `enhancement: inference` +- **Opened**: 2026-05-21 +- **Summary**: Add command to export agent session JSONL + trajectory from running sandbox +- **Why good candidate**: New feature with clear CLI interface. Well-scoped. Good documentation value +- **Risk**: Medium — new command surface +- **Files likely touched**: `src/commands/`, state management for sessions + +## Candidate 8: #3826 — docs(contributing): add newcomer contribution path +- **Status**: Open +- **Labels**: `documentation`, `good first issue`, `Getting Started` +- **Opened**: 2026-05-19 +- **Summary**: Add newcomer contribution path and community expectations to CONTRIBUTING.md +- **Why good candidate**: "Good first issue" labeled. Pure documentation. Easy to validate +- **Risk**: Very low — documentation only +- **Files likely touched**: `CONTRIBUTING.md` + +## Candidate 9: #3794 — docs(reference): document openshell settings + sandbox runtime env +- **Status**: Open +- **Labels**: `documentation`, `fix` +- **Opened**: 2026-05-19 +- **Summary**: Document OpenShell settings and sandbox runtime environment variables +- **Why good candidate**: Clear documentation need. Well-scoped. Affects reference docs +- **Risk**: Very low — documentation +- **Files likely touched**: `docs/reference/`, possibly `fern/` docs + +## Candidate 10: #3980 — fix(onboard): fail fast in preflight when all dashboard ports are occupied +- **Status**: Open, not draft +- **Labels**: `bug`, `NemoClaw CLI`, `fix` +- **Opened**: 2026-05-21 +- **Referenced**: Issue #3953 +- **Summary**: Onboard fails fast in preflight when all dashboard ports 18789-18799 are occupied +- **Why good candidate**: Clear bug with existing issue #3953. Pre-flight validation improvement +- **Risk**: Low — adds early validation +- **Files likely touched**: `src/lib/onboard/` preflight checks, port allocation + +--- + +## Issues Worth Addressing (Potential PRs) + +| Issue | Title | Labels | Why Address | +|-------|-------|--------|-------------| +| #3978 | [docs] Agent session JSONL / trajectory paths are stable but undocumented | `documentation`, `priority: high` | High-priority docs gap, clear scope | +| #3990 | [WSL2][Install] fresh install + onboard takes 25-30 min with no progress feedback | `bug`, `Getting Started`, `Platform: Windows/WSL` | UX improvement, parallelization opportunity | +| #3948 | [Brave Search][Policy&Network] Agent still claims no web access despite brave preset enabled | `bug`, `Getting Started`, `NV QA`, `Integration: Brave` | Policy/inference integration issue | +| #4015 | npm preset does not allow @openclaw/microsoft-speech to resolve from registry | `bug`, `NemoClaw CLI`, `NV QA`, `Platform: All` | Policy preset gap, clear fix | +| #4014 | pypi preset does not allow expected GET access to pypi.org/files.pythonhosted.org | `bug`, `NemoClaw CLI`, `NV QA`, `Platform: All` | Policy preset gap, clear fix | +| #3892 | docs: remove local flag from sandbox inference examples | `documentation`, `fix` | Docs cleanup, small scope | +| #3909 | docs: remove prompt markers from Windows setup commands | `documentation`, `Platform: Windows/WSL`, `fix` | Docs cleanup, small scope | + +--- + +## Contributing Notes + +1. **Conventional Commits**: All commits must follow `(): ` format +2. **SPDX headers**: Required on all source files +3. **Biome linting**: Run `npm run check` before submitting +4. **Tests**: Run `npm test` — plugin tests run in pre-commit +5. **DCO**: Sign off on commits (Developer's Certificate of Origin) +6. **CI**: PR checks include basic-checks, platform-vitest, Ollama proxy E2E +7. **Reviewers**: Check CODEOWNERS for relevant maintainers \ No newline at end of file diff --git a/06_SELECTED_5_PR_PLAN.md b/06_SELECTED_5_PR_PLAN.md new file mode 100644 index 0000000000..390afbbf04 --- /dev/null +++ b/06_SELECTED_5_PR_PLAN.md @@ -0,0 +1,232 @@ +# 06_SELECTED_5_PR_PLAN.md — NemoClaw + +## Overview +Selected 5 open PRs for analysis and potential backporting to the `okwn/NemoClaw` fork. Selection prioritizes security fixes, clear scoping, platform diversity, and PRs where the fork can practically add value. + +## Selection Criteria +- **Security first**: Security-labeled PRs get priority +- **Bounded scope**: Prefer PRs with clear, reviewable diffs (not massive refactors) +- **Platform diversity**: Cover Linux, macOS, Jetson, and cross-platform scenarios +- **Fork value**: Areas where our fork can realistically test, validate, or extend +- **Freshness**: Post-May 2026 PRs with active review traction + +--- + +## Selected PR 1: #4075 — `fix(policy): split Claude Code from permissive policies` + +### Why Selected +Security-relevant policy fix. Removes Claude Code-specific egress from permissive sandbox policies and moves it behind an explicit opt-in preset. Fixes issue #4073. Clear problem/solution with well-labeled scope. + +### Scope +| Metric | Value | +|--------|-------| +| Files | 39 | +| Additions | ~400+ | +| Deletions | ~200+ | +| Risk | Low — policy subsystem has good test coverage | +| Review complexity | Medium — policy YAML + TypeScript tests | + +### Files Touched +``` +agents/hermes/policy-permissive.yaml +agents/openclaw/policy-permissive.yaml +docs/reference/network-policies.mdx +docs/security/best-practices.mdx +nemoclaw-blueprint/policies/openclaw-sandbox-permissive.yaml +nemoclaw-blueprint/policies/presets/claude-code.yaml +test/policies.test.ts +(+ 32 policy/test files) +``` + +### Fork Action Plan +1. Create `fork/policy/claude-code-split` branch off `main` +2. Cherry-pick or apply the policy split changes +3. Run `npm test` (policy tests) to validate +4. Validate against existing permissive policy test fixtures +5. Test that `claude-code` preset needs explicit opt-in + +### Verification +```bash +npm test -- --project=cli --grep="policy" +``` + +--- + +## Selected PR 2: #4054 — `fix(security): enforce owner-only permissions on ~/.nemoclaw directory and config files` + +### Why Selected +High-priority security fix (labeled `security`, `priority: high`). Changes world-readable config (644) to owner-only (600/700) after onboard. Addresses issue #4009. Small, targeted, low risk. + +### Scope +| Metric | Value | +|--------|-------| +| Files | 5 | +| Additions | 39 | +| Deletions | 4 | +| Risk | Very low — permission hardening only | +| Review complexity | Low — clear file-by-file change | + +### Files Touched +``` +src/lib/inference/local-adapter-lifecycle.test.ts +src/lib/inference/local-adapter-lifecycle.ts +src/lib/onboard.ts +src/lib/onboard/config-sync.test.ts +src/lib/onboard/config-sync.ts +``` + +### Fork Action Plan +1. Create `fork/security/permission-hardening` branch +2. Apply permission hardening in `config-sync.ts` +3. Verify `~/.nemoclaw` permissions are 700 after `nemoclaw onboard` +4. Validate on Linux (primary), test on macOS + +### Verification +```bash +# After onboard, check permissions +stat -c "%a" ~/.nemoclaw +stat -c "%a" ~/.nemoclaw/config.json +# Expected: 700 and 600 respectively +``` + +--- + +## Selected PR 3: #4029 — `fix(installer): preserve npm lockfiles during install` + +### Why Selected +macOS platform fix. Preserves npm lockfiles during install to prevent accidental overwrites. Clear bug with small scope. Good introduction to the installer subsystem. + +### Scope +| Metric | Value | +|--------|-------| +| Files | 4 | +| Risk | Low — installer behavior change | +| Review complexity | Low — targeted file changes | + +### Files Touched +``` +.github/actions/basic-checks/action.yaml +scripts/install.sh +test/install-preflight.test.ts +test/lockfile-ci-guard.test.ts +``` + +### Fork Action Plan +1. Create `fork/installer/lockfile-preservation` branch +2. Apply lockfile preservation logic in `install.sh` +3. Run installer tests: `npm test -- --project=cli --grep="install"` +4. Validate lockfile is preserved on re-run + +### Verification +```bash +npm test -- --project=cli --grep="lockfile" +``` + +--- + +## Selected PR 4: #4008 — `fix(onboard): use NVIDIA runtime for Jetson sandbox GPU` + +### Why Selected +Platform-specific fix (Jetson AGX Thor/Orin). Uses NVIDIA container runtime instead of Docker default for GPU passthrough. Clear hardware context, well-scoped. Multiple test files provide good coverage signal. + +### Scope +| Metric | Value | +|--------|-------| +| Files | 13 (12 test + 1 source) | +| Risk | Low — Jetson-specific path | +| Review complexity | Medium — GPU detection logic | + +### Files Touched +``` +src/lib/onboard.ts +src/lib/onboard/docker-gpu-patch.test.ts +src/lib/onboard/docker-gpu-patch.ts +src/lib/onboard/docker-gpu-sandbox-create.ts +src/lib/onboard/gateway-gpu-passthrough.test.ts +src/lib/onboard/gateway-gpu-passthrough.ts +src/lib/onboard/gpu-recovery.test.ts +src/lib/onboard/gpu-recovery.ts +src/lib/onboard/sandbox-gpu-mode.test.ts +src/lib/onboard/sandbox-gpu-mode.ts +src/lib/onboard/sandbox-gpu-preflight.test.ts +src/lib/onboard/sandbox-gpu-preflight.ts +``` + +### Fork Action Plan +1. Create `fork/onboard/jetson-nvidia-runtime` branch +2. Apply NVIDIA runtime selection in `sandbox-gpu-mode.ts` +3. Run GPU preflight tests: `npm test -- --project=cli --grep="gpu"` +4. Simulate Jetson detection via mock environment + +### Verification +```bash +npm test -- --project=cli --grep="gpu" +# Validate runtime detection in CI +``` + +--- + +## Selected PR 5: #3980 — `fix(onboard): fail fast in preflight when all dashboard ports are occupied` + +### Why Selected +UX improvement for onboarding. Onboard fails fast in preflight when all dashboard ports (18789-18799) are occupied. References issue #3953. Adds early validation with clear user-facing error. + +### Scope +| Metric | Value | +|--------|-------| +| Files | 3 | +| Additions | 91 | +| Deletions | 4 | +| Risk | Low — adds early validation | +| Review complexity | Low — clear preflight logic | + +### Files Touched +``` +src/lib/onboard.ts +src/lib/onboard/dashboard-port.test.ts +src/lib/onboard/dashboard-port.ts +``` + +### Fork Action Plan +1. Create `fork/onboard/dashboard-port-preflight` branch +2. Apply port availability check in `dashboard-port.ts` +3. Run preflight tests: `npm test -- --project=cli --grep="dashboard"` +4. Validate failure message is clear and actionable + +### Verification +```bash +npm test -- --project=cli --grep="dashboard" +``` + +--- + +## Summary Table + +| PR | Title | Files | Risk | Platform | Priority | +|----|-------|-------|------|----------|----------| +| #4075 | fix(policy): split Claude Code from permissive policies | 39 | Low | All | Security | +| #4054 | fix(security): enforce owner-only permissions | 5 | Very Low | All | Security | +| #4029 | fix(installer): preserve npm lockfiles during install | 4 | Low | macOS | Medium | +| #4008 | fix(onboard): use NVIDIA runtime for Jetson sandbox GPU | 13 | Low | Jetson | Medium | +| #3980 | fix(onboard): fail fast in preflight when ports occupied | 3 | Low | All | Low | + +--- + +## Execution Order + +1. **#4054** (Security) — Smallest scope, highest priority. Start here. +2. **#3980** (UX) — Smallest change, clear feedback loop. Good second. +3. **#4029** (Installer) — Self-contained, easy to validate. +4. **#4008** (Jetson) — Larger but well-tested. Good for platform coverage. +5. **#4075** (Policy) — Largest scope, most files. Finish last with thorough review. + +--- + +## Contributing Notes +1. **Conventional Commits**: All commits must follow `(): ` format +2. **SPDX headers**: Required on all source files +3. **Biome linting**: Run `npm run check` before committing +4. **Tests**: Run `npm test` — plugin tests run in pre-commit +5. **DCO**: Sign off on commits (Developer's Certificate of Origin) +6. **CI**: PR checks include basic-checks, platform-vitest, Ollama proxy E2E +7. **Code Owners**: Check `CODEOWNERS` for relevant maintainers per subsystem \ No newline at end of file