diff --git a/.agents/skills/update-docs-from-commits/SKILL.md b/.agents/skills/update-docs-from-commits/SKILL.md new file mode 100644 index 000000000..83cd9cac0 --- /dev/null +++ b/.agents/skills/update-docs-from-commits/SKILL.md @@ -0,0 +1,164 @@ +--- +name: update-docs-from-commits +description: Scan recent git commits for changes that affect user-facing behavior, then draft or update the corresponding documentation pages. Use when docs have fallen behind code changes, after a batch of features lands, or when preparing a release. Trigger keywords - update docs, draft docs, docs from commits, sync docs, catch up docs, doc debt, docs behind, docs drift. +--- + +# Update Docs from Commits + +Scan recent git history for commits that affect user-facing behavior and draft documentation updates for each. + +## Prerequisites + +- You must be in the NemoClaw git repository (`NemoClaw`). +- The `docs/` directory must exist with the current doc set. + +## When to Use + +- After a batch of features or fixes has landed and docs may be stale. +- Before a release, to catch any doc gaps. +- When a contributor asks "what docs need updating?" + +## Step 1: Identify Relevant Commits + +Determine the commit range. The user may provide one explicitly (e.g., "since v0.1.0" or "last 30 commits"). If not, default to commits since the head of the main branch. + +```bash +# Commits since a tag +git log v0.1.0..HEAD --oneline --no-merges + +# Or last 50 commits +git log -50 --oneline --no-merges +``` + +Filter to commits that are likely to affect docs. Look for these signals: + +1. **Commit type**: `feat`, `fix`, `refactor`, `perf` commits often change behavior. `docs` commits are already doc changes. `chore`, `ci`, `test` commits rarely need doc updates. +2. **Files changed**: Changes to `nemoclaw/src/`, `nemoclaw-blueprint/`, `bin/`, `scripts/`, or policy-related code are high-signal. +3. **Ignore**: Changes limited to `test/`, `.github/`, or internal-only modules. + +```bash +# Show files changed per commit to assess impact +git log v0.1.0..HEAD --oneline --no-merges --name-only +``` + +## Step 2: Map Commits to Doc Pages + +For each relevant commit, determine which doc page(s) it affects. Use this mapping as a starting point: + +| Code area | Likely doc page(s) | +|---|---| +| `nemoclaw/src/commands/` (launch, connect, status, logs) | `docs/reference/commands.md` | +| `nemoclaw/src/commands/` (new command) | May need a new page or entry in `docs/reference/commands.md` | +| `nemoclaw/src/blueprint/` | `docs/about/architecture.md` | +| `nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts` | `docs/reference/commands.md`, `docs/get-started/quickstart.md` | +| `nemoclaw-blueprint/orchestrator/` | `docs/about/architecture.md` | +| `nemoclaw-blueprint/policies/` | `docs/reference/network-policies.md` | +| `nemoclaw-blueprint/blueprint.yaml` | `docs/about/architecture.md`, `docs/reference/inference-profiles.md` | +| `scripts/` (setup, start) | `docs/get-started/quickstart.md` | +| `Dockerfile` | `docs/about/architecture.md` | +| Inference-related changes | `docs/reference/inference-profiles.md` | + +If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page. + +## Step 3: Read the Commit Details + +For each commit that needs a doc update, read the full diff to understand the change: + +```bash +git show --stat +git show +``` + +Extract: + +- What changed (new flag, renamed command, changed default, new feature). +- Why it changed (from the commit message body, linked issue, or PR description). +- Any breaking changes or migration steps. + +## Step 4: Read the Current Doc Page + +Before editing, read the full target doc page to understand its current content and structure. + +Identify where the new content should go. Follow the page's existing structure. + +## Step 5: Draft the Update + +Write the doc update following these conventions: + +- **Active voice, present tense, second person.** +- **No unnecessary bold.** Reserve bold for UI labels and parameter names. +- **No em dashes** unless used sparingly. Prefer commas or separate sentences. +- **Start sections with an introductory sentence** that orients the reader. +- **No superlatives.** Say what the feature does, not how great it is. +- **Code examples use `console` language** with `$` prompt prefix. +- **Include the SPDX header** if creating a new page. +- **Match existing frontmatter format** if creating a new page. +- **Always write NVIDIA in all caps.** Wrong: Nvidia, nvidia. +- **Always capitalize NemoClaw correctly.** Wrong: nemoclaw (in prose), Nemoclaw. +- **Always capitalize OpenShell correctly.** Wrong: openshell (in prose), Openshell, openShell. +- **Do not number section titles.** Wrong: "Section 1: Configure Inference" or "Step 3: Verify." Use plain descriptive titles. +- **No colons in titles.** Wrong: "Inference: Cloud and Local." Write "Cloud and Local Inference" instead. +- **Use colons only to introduce a list.** Do not use colons as general-purpose punctuation between clauses. + +When updating an existing page: + +- Add content in the logical place within the existing structure. +- Do not reorganize sections unless the change requires it. +- Update any cross-references or "Next Steps" links if relevant. + +When creating a new page: + +- Follow the frontmatter template from existing pages in `docs/`. +- Add the page to the appropriate `toctree` in `docs/index.md`. + +## Step 6: Present the Results + +After drafting all updates, present a summary to the user: + +``` +## Doc Updates from Commits + +### Updated pages +- `docs/reference/commands.md`: Added `eject` command documentation (from commit abc1234). +- `docs/reference/network-policies.md`: Updated policy schema for new egress rule (from commit def5678). + +### New pages needed +- None (or list any new pages created). + +### Commits with no doc impact +- `chore(deps): bump typescript` (abc1234) — internal dependency, no user-facing change. +- `test: add launch command test` (def5678) — test-only change. +``` + +## Step 7: Build and Verify + +After making changes, build the docs locally: + +```bash +make docs +``` + +Check for: + +- Build warnings or errors. +- Broken cross-references. +- Correct rendering of new content. + +## Tips + +- When in doubt about whether a commit needs a doc update, check if the commit message references a CLI flag, config option, or user-visible behavior. +- Group related commits that touch the same doc page into a single update rather than making multiple small edits. +- If a commit is a breaking change, add a note at the top of the relevant section using a `:::{warning}` admonition. +- PRs that are purely internal refactors with no behavior change do not need doc updates, even if they touch high-signal directories. + +## Example Usage + +User says: "Catch up the docs for everything merged since v0.1.0." + +1. Run `git log v0.1.0..HEAD --oneline --no-merges --name-only`. +2. Filter to `feat`, `fix`, `refactor`, `perf` commits touching user-facing code. +3. Map each to a doc page. +4. Read the commit diffs and current doc pages. +5. Draft updates following the style guide. +6. Present the summary. +7. Build with `make docs` to verify. diff --git a/.c8rc.json b/.c8rc.json new file mode 100644 index 000000000..7bb9d7c96 --- /dev/null +++ b/.c8rc.json @@ -0,0 +1,25 @@ +{ + "all": true, + "src": ["bin", "test"], + "exclude": [ + "**/*.test.js", + "node_modules/**", + "nemoclaw/node_modules/**", + "nemoclaw/dist/**", + "nemoclaw-blueprint/**", + "docs/**", + ".devcontainer/**", + ".github/**", + "scripts/**", + "coverage/**", + ".jscpd/**" + ], + "reporter": ["text", "lcov", "html"], + "reports-dir": "coverage", + "check-coverage": true, + "lines": 30, + "functions": 40, + "branches": 65, + "statements": 30, + "per-file": false +} diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 000000000..b79cafd8c --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,171 @@ +# NemoClaw Dev Container + +This directory contains the VS Code Dev Container configuration for NemoClaw development. + +## What is a Dev Container? + +A development container (devcontainer) is a fully configured development environment running in a Docker container. It provides a consistent, reproducible environment for all contributors, whether human developers or autonomous AI agents. + +## Features + +This devcontainer includes: + +### Base Environment +- **Node.js 22** (Debian Bookworm base image) +- **Python 3.11** with pip, uv, and development tools +- **Docker-in-Docker** for testing containerized workflows +- **Git** with LFS support + +### VS Code Extensions + +**TypeScript/JavaScript:** +- ESLint - Linting and code quality +- Prettier - Code formatting +- TypeScript Next - Latest TypeScript language features + +**Python:** +- Python extension - IntelliSense, debugging, testing +- Pylance - Fast type checking +- Ruff - Fast Python linter and formatter + +**Git:** +- GitLens - Git supercharged (blame, history, etc.) +- GitHub Pull Requests - Review and manage PRs from VS Code + +**Documentation:** +- Markdown All in One - Markdown authoring +- markdownlint - Markdown linting + +**General:** +- EditorConfig - Consistent coding styles +- Code Spell Checker - Catch typos + +### Pre-Configured Settings + +- **TypeScript**: Auto-format on save with Prettier, ESLint auto-fix +- **Python**: Auto-format on save with Ruff, import organization +- **Editor**: 100-character ruler, 2-space tabs, trim whitespace +- **Git**: Auto-fetch enabled, safe directory configured + +### Automatic Setup + +The `postCreate.sh` script runs after container creation: +1. Installs Python dependencies (uv sync) +2. Installs TypeScript dependencies (npm install) +3. Installs root dependencies (test runner, code quality tools) +4. Installs pre-commit hooks +5. Builds TypeScript plugin +6. Displays quick start guide + +## Using the Dev Container + +### First Time Setup + +1. **Install Prerequisites:** + - [Visual Studio Code](https://code.visualstudio.com/) + - [Docker Desktop](https://www.docker.com/products/docker-desktop) + - [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) + +2. **Open in Container:** + - Clone the repository + - Open the folder in VS Code + - Click "Reopen in Container" when prompted + - Or use Command Palette (F1): `Dev Containers: Reopen in Container` + +3. **Wait for Initialization:** + - First build takes ~2-3 minutes + - Subsequent starts are much faster (~30 seconds) + - Watch the progress in the terminal + +4. **Start Developing:** + - All dependencies are installed + - Pre-commit hooks are configured + - TypeScript is built and ready + - You can immediately run `npm test`, `make check`, etc. + +### Rebuilding the Container + +If you modify `.devcontainer/devcontainer.json` or `postCreate.sh`: + +1. Command Palette (F1): `Dev Containers: Rebuild Container` +2. Or: `Dev Containers: Rebuild Without Cache` for a clean rebuild + +### SSH Keys and Git + +The devcontainer mounts your local `~/.ssh` directory (read-only) so you can use your SSH keys for Git operations without copying them into the container. + +## For Autonomous Agents + +The devcontainer provides a fully configured environment for autonomous AI agents: + +**Benefits:** +- Consistent environment across all agents +- No "works on my machine" issues +- All tools pre-installed and configured +- Editor settings enforce code quality +- Pre-commit hooks automatically configured + +**Agent Workflow:** +1. Open repository in devcontainer +2. Environment is ready - no setup needed +3. Make changes with all tools available +4. Pre-commit hooks run automatically on commit +5. All linters, formatters, type checkers work out of the box + +**Testing Agent Changes:** +```bash +# All these commands work immediately in the devcontainer: +npm test # Run unit tests +cd nemoclaw && npm run check # TypeScript checks +cd nemoclaw-blueprint && make check # Python checks +make complexity # Complexity analysis +make dead-code # Dead code detection +make duplicates # Duplicate code detection +make tech-debt # Technical debt tracking +``` + +## Troubleshooting + +### Container Won't Build +- Check Docker is running: `docker ps` +- Check disk space: `docker system df` +- Try rebuild without cache + +### Slow Performance +- Allocate more resources to Docker (Settings → Resources) +- Use Docker volumes for node_modules (already configured) + +### Extensions Not Working +- Reload window: `Developer: Reload Window` +- Reinstall extension inside container + +### Post-Create Script Failed +- Check terminal output for specific error +- Run manually: `.devcontainer/postCreate.sh` +- Report issue with error message + +## Configuration Files + +- **devcontainer.json**: Main configuration (image, features, extensions, settings) +- **postCreate.sh**: Initialization script (dependencies, hooks, build) +- **README.md**: This file (documentation) + +## Customization + +To customize for your workflow: + +1. **Add Extensions:** Edit `customizations.vscode.extensions` in devcontainer.json +2. **Change Settings:** Edit `customizations.vscode.settings` in devcontainer.json +3. **Add Tools:** Edit `postCreate.sh` to install additional tools +4. **Change Base Image:** Edit `image` in devcontainer.json (requires rebuild) + +## References + +- [VS Code Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) +- [devcontainer.json reference](https://containers.dev/implementors/json_reference/) +- [Dev Container Features](https://containers.dev/features) +- [NemoClaw AGENTS.md](../AGENTS.md) - Full development guide + +--- + +**Questions?** See [CONTRIBUTING.md](../CONTRIBUTING.md) or ask in GitHub Discussions. diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 000000000..0c0a82dcb --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,107 @@ +{ + "name": "NemoClaw Development", + "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm", + + "features": { + "ghcr.io/devcontainers/features/python:1": { + "version": "3.11", + "installTools": true + }, + "ghcr.io/devcontainers/features/docker-in-docker:2": { + "version": "latest", + "dockerDashComposeVersion": "v2" + }, + "ghcr.io/devcontainers/features/git:1": { + "version": "latest" + } + }, + + "customizations": { + "vscode": { + "extensions": [ + // TypeScript/JavaScript + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "ms-vscode.vscode-typescript-next", + + // Python + "ms-python.python", + "ms-python.vscode-pylance", + "charliermarsh.ruff", + + // Git + "eamodio.gitlens", + "github.vscode-pull-request-github", + + // Documentation + "yzhang.markdown-all-in-one", + "davidanson.vscode-markdownlint", + + // General utilities + "editorconfig.editorconfig", + "streetsidesoftware.code-spell-checker" + ], + "settings": { + // TypeScript/JavaScript + "typescript.tsdk": "node_modules/typescript/lib", + "eslint.validate": ["javascript", "typescript"], + "editor.defaultFormatter": "esbenp.prettier-vscode", + "[typescript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" + } + }, + "[javascript]": { + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" + } + }, + + // Python + "python.defaultInterpreterPath": "/usr/local/bin/python", + "python.linting.enabled": true, + "python.linting.ruffEnabled": true, + "python.formatting.provider": "none", + "[python]": { + "editor.defaultFormatter": "charliermarsh.ruff", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.organizeImports": "explicit", + "source.fixAll": "explicit" + } + }, + + // General editor + "editor.rulers": [100], + "editor.tabSize": 2, + "files.insertFinalNewline": true, + "files.trimTrailingWhitespace": true, + "files.eol": "\n", + + // Git + "git.enableCommitSigning": false, + "git.autofetch": true + } + } + }, + + "onCreateCommand": "echo 'NemoClaw DevContainer initialized!'", + + "postCreateCommand": ".devcontainer/postCreate.sh", + + "postStartCommand": "git config --global --add safe.directory ${containerWorkspaceFolder}", + + "remoteUser": "node", + + "mounts": [ + "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/node/.ssh,readonly,type=bind,consistency=cached" + ], + + "forwardPorts": [], + + "portsAttributes": {} +} diff --git a/.devcontainer/postCreate.sh b/.devcontainer/postCreate.sh new file mode 100644 index 000000000..ca68f60bd --- /dev/null +++ b/.devcontainer/postCreate.sh @@ -0,0 +1,41 @@ +#!/bin/bash +set -e + +echo "🚀 Setting up NemoClaw development environment..." + +# Install Python dependencies +echo "📦 Installing Python dependencies..." +python3 -m pip install --upgrade pip +pip install uv +uv sync --group docs + +# Install TypeScript dependencies +echo "📦 Installing TypeScript dependencies..." +cd nemoclaw +npm install +cd .. + +# Install root dependencies (test runner, code quality tools) +echo "📦 Installing root dependencies..." +npm install + +# Install pre-commit hooks +echo "🪝 Installing pre-commit hooks..." +pip install pre-commit +pre-commit install + +# Build TypeScript +echo "🔨 Building TypeScript plugin..." +cd nemoclaw +npm run build +cd .. + +echo "✅ NemoClaw development environment ready!" +echo "" +echo "Quick start:" +echo " - Run tests: npm test" +echo " - Build TypeScript: cd nemoclaw && npm run build" +echo " - Lint everything: make check" +echo " - Build docs: make docs" +echo "" +echo "See AGENTS.md for complete development guide." diff --git a/.dockerignore b/.dockerignore index 8d42c6b17..49a126f4c 100644 --- a/.dockerignore +++ b/.dockerignore @@ -1,6 +1,64 @@ +# Dependencies (rebuilt inside image) node_modules +**/node_modules + +# Build output (copied explicitly) /dist +nemoclaw/dist + +# Version control .git +.gitignore + +# CI/CD and GitHub +.github/ +.coderabbit.yaml + +# Documentation (not needed in sandbox image) +docs/ +*.md +!nemoclaw-blueprint/**/*.md + +# IDE and editor files +.vscode/ +.idea/ +.editorconfig +*.swp +*.swo +*~ + +# Test files +test/ +**/*.test.js +**/*.test.ts +**/*.spec.js +**/*.spec.ts +coverage/ +.nyc_output/ +.pytest_cache/ + +# Python bytecode *.pyc __pycache__ -.pytest_cache + +# TypeScript source (dist/ is copied instead) +nemoclaw/src/ +nemoclaw/tsconfig.json +nemoclaw/vitest.config.ts +nemoclaw/eslint.config.mjs + +# OS files +.DS_Store +Thumbs.db + +# Environment and secrets +.env +.env.* +.secrets.baseline +*.log + +# Dev config +.husky/ +commitlint.config.js +.nvmrc +.python-version diff --git a/.factory/settings.json b/.factory/settings.json new file mode 100644 index 000000000..6bf84ef95 --- /dev/null +++ b/.factory/settings.json @@ -0,0 +1,5 @@ +{ + "enabledPlugins": { + "core@factory-plugins": true + } +} diff --git a/.factory/skills/build-project/SKILL.md b/.factory/skills/build-project/SKILL.md new file mode 100644 index 000000000..9f5707db8 --- /dev/null +++ b/.factory/skills/build-project/SKILL.md @@ -0,0 +1,383 @@ +--- +name: build-project +description: Build the TypeScript plugin and verify compilation succeeds. Use when making code changes, before testing, or preparing for release. Trigger keywords - build, compile, tsc, typescript, dist. +--- + +# Build Project + +Compile the TypeScript plugin and verify the build succeeds without errors. + +## Prerequisites + +- You must be in the NemoClaw repository root +- Node.js 20+ must be installed +- Dependencies must be installed (`npm install`) + +## When to Use + +- **After code changes** - Verify TypeScript compiles +- **Before running tests** - Tests need compiled code +- **Before publishing** - Ensure distributable builds correctly +- **Troubleshooting import errors** - Rebuild to fix module resolution +- **After pulling changes** - Ensure new code compiles + +## Quick Commands + +### Build Everything + +```bash +# Build TypeScript plugin +make dev +``` + +This runs: +1. `npm install` in nemoclaw/ (install dependencies) +2. `npm run build` in nemoclaw/ (compile TypeScript) + +### Build TypeScript Plugin Only + +```bash +cd nemoclaw + +# One-time build +npm run build + +# Watch mode (auto-rebuild on changes) +npm run dev +``` + +### Clean and Rebuild + +```bash +cd nemoclaw + +# Remove old build artifacts +npm run clean + +# Rebuild from scratch +npm run build +``` + +## Build Process Explained + +### TypeScript Compilation + +The TypeScript plugin (`nemoclaw/`) compiles to JavaScript in `nemoclaw/dist/`: + +``` +nemoclaw/src/*.ts → nemoclaw/dist/*.js +``` + +**Compiler**: TypeScript 5.4+ with strict mode +**Configuration**: `nemoclaw/tsconfig.json` +**Output**: JavaScript (ES2022), type definitions (.d.ts), source maps + +**Build artifacts**: +- `nemoclaw/dist/*.js` - Compiled JavaScript +- `nemoclaw/dist/*.d.ts` - Type definition files +- `nemoclaw/dist/*.js.map` - Source maps for debugging + +### Watch Mode + +For active development, use watch mode to auto-rebuild on file changes: + +```bash +cd nemoclaw +npm run dev +``` + +**Benefits**: +- Instant feedback on TypeScript errors +- No need to manually rebuild after each change +- Faster iteration during development + +**When to use**: +- Developing new features +- Refactoring TypeScript code +- Debugging compilation errors + +## Interpreting Build Output + +### Success + +``` +> nemoclaw@0.1.0 build +> tsc + +✨ Done in 2.34s +``` + +Build succeeded! ✅ Compiled files in `nemoclaw/dist/` + +### Type Errors + +``` +> nemoclaw@0.1.0 build +> tsc + +src/commands/launch.ts:42:7 - error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'. + +42 await launchSandbox("invalid"); + ~~~~~~~ + +Found 1 error in src/commands/launch.ts:42 +``` + +**Fix**: Correct the type error in the indicated file and line. + +### Import Errors + +``` +src/index.ts:3:23 - error TS2307: Cannot find module './commands/new-command' or its corresponding type declarations. + +3 import { execute } from "./commands/new-command"; + ~~~~~~~~~~~~~~~~~~~~~~~ +``` + +**Common causes**: +1. File doesn't exist - Create the missing file +2. Typo in import path - Fix the path +3. Missing .ts extension - Add it to the file + +### Strict Mode Errors + +TypeScript strict mode is enabled, which catches common issues: + +``` +src/utils/helper.ts:12:5 - error TS2322: Type 'string | undefined' is not assignable to type 'string'. + +12 const name: string = data.name; + ~~~~~~ +``` + +**Fix**: Handle undefined cases: + +```typescript +// ❌ BAD: Doesn't handle undefined +const name: string = data.name; + +// ✅ GOOD: Handle undefined with default or guard +const name: string = data.name ?? "default"; +// or +if (!data.name) throw new Error("Name required"); +const name: string = data.name; +``` + +## Common Build Issues + +### Build Fails After Git Pull + +**Problem**: New dependencies or TypeScript version changes + +**Fix**: + +```bash +cd nemoclaw +npm install # Update dependencies +npm run build +``` + +### Module Not Found Errors + +**Problem**: Import paths don't match file structure + +**Fix**: + +```bash +# Check file exists +ls nemoclaw/src/commands/my-command.ts + +# Fix import path +import { execute } from "./commands/my-command"; # correct +``` + +### Build Artifacts Out of Sync + +**Problem**: Old compiled files cached + +**Fix**: + +```bash +cd nemoclaw +npm run clean # Remove dist/ +npm run build # Rebuild +``` + +### TypeScript Version Mismatch + +**Problem**: Different TypeScript version than configured + +**Fix**: + +```bash +cd nemoclaw +npm install typescript@^5.4.0 --save-dev +npm run build +``` + +## Integration with Development Workflow + +### Standard Development Flow + +```bash +# 1. Start watch mode +cd nemoclaw +npm run dev + +# 2. Make changes to TypeScript files +# (watch mode auto-rebuilds) + +# 3. Test changes +cd .. +npm test + +# 4. Stop watch mode (Ctrl+C) +``` + +### Pre-commit Checks + +Pre-commit hooks verify TypeScript compiles: + +```yaml +# .pre-commit-config.yaml +- id: tsc-check + name: tsc --noEmit (TypeScript type check) + entry: bash -c 'cd nemoclaw && npm run check' +``` + +This runs: +- Type checking (no emit) +- Linting +- Formatting checks + +### CI Build + +GitHub Actions builds on every push: + +```yaml +# .github/workflows/ci.yml +- name: Build TypeScript plugin + run: | + cd nemoclaw + npm install + npm run build +``` + +## Build Output Structure + +After successful build: + +``` +nemoclaw/ +├── src/ # Source TypeScript +│ ├── index.ts +│ ├── cli.ts +│ └── commands/*.ts +├── dist/ # Compiled output +│ ├── index.js # Compiled JavaScript +│ ├── index.d.ts # Type definitions +│ ├── index.js.map # Source map +│ ├── cli.js +│ ├── cli.d.ts +│ ├── cli.js.map +│ └── commands/*.js +├── tsconfig.json # TypeScript config +└── package.json # Build scripts +``` + +**Published files** (in npm package): +- `dist/*.js` - Executed by Node.js +- `dist/*.d.ts` - Used by TypeScript consumers +- Source maps - For debugging in production + +## Verification + +After building, verify the build: + +```bash +# Check build artifacts exist +ls nemoclaw/dist/index.js + +# Verify type definitions +ls nemoclaw/dist/index.d.ts + +# Check package can be imported +node -e "require('./nemoclaw/dist/index.js')" +``` + +## Build Performance + +**Typical build times**: +- **Clean build**: 2-5 seconds +- **Incremental build**: <1 second +- **Watch mode rebuild**: <500ms + +**Optimization tips**: +1. Use watch mode during development (faster) +2. Use `tsc --noEmit` for type checking only (no files written) +3. Keep `tsconfig.json` optimized (incremental mode) + +## Best Practices + +1. **Build before committing** - Ensure code compiles +2. **Use watch mode** - Faster feedback during development +3. **Clean periodically** - Prevent stale artifacts +4. **Check type errors** - Don't ignore TypeScript warnings +5. **Keep dependencies updated** - Prevent version conflicts + +## Example Workflows + +### Quick Fix Workflow + +```bash +# 1. Make small change to TypeScript +vim nemoclaw/src/commands/launch.ts + +# 2. Build +cd nemoclaw && npm run build && cd .. + +# 3. Test +npm test + +# 4. Commit +git add -A && git commit -m "fix: handle edge case in launch" +``` + +### Feature Development Workflow + +```bash +# 1. Start watch mode +cd nemoclaw && npm run dev & + +# 2. Develop feature (watch auto-rebuilds) +vim nemoclaw/src/commands/new-feature.ts + +# 3. Test incrementally +npm test test/new-feature.test.js + +# 4. Stop watch mode +killall node + +# 5. Final verification +make check && npm run test:all + +# 6. Commit +git add -A && git commit -m "feat: add new feature" +``` + +## Success Criteria + +✅ TypeScript compiles without errors +✅ All type definitions generated +✅ Source maps created +✅ Build completes in <5 seconds +✅ CLI still works after build + +When all criteria are met, your build is ready! 🎉 + +## Related Commands + +- `make check` - Run type checking + linting + formatting +- `npm run lint` - Check ESLint errors only +- `npm test` - Run tests (requires build) +- `npm run clean` - Remove build artifacts diff --git a/.factory/skills/check-code-quality/SKILL.md b/.factory/skills/check-code-quality/SKILL.md new file mode 100644 index 000000000..ad452e91d --- /dev/null +++ b/.factory/skills/check-code-quality/SKILL.md @@ -0,0 +1,382 @@ +--- +name: check-code-quality +description: Run code quality analysis including complexity checks, dead code detection, duplicate code detection, and technical debt tracking. Use when refactoring, reviewing code health, or before releases. Trigger keywords - code quality, complexity, dead code, duplicates, tech debt, maintainability. +--- + +# Check Code Quality + +Run comprehensive code quality analysis to identify complexity issues, dead code, duplicate code, and technical debt. + +## Prerequisites + +- You must be in the NemoClaw repository root +- Node.js 20+ and Python 3.11+ must be installed +- Dependencies must be installed (`npm install`) + +## When to Use + +- **Before refactoring** - Identify problem areas to improve +- **Code reviews** - Assess code maintainability +- **Before releases** - Ensure code quality standards are met +- **Periodic health checks** - Monitor codebase health over time +- **After large changes** - Verify quality hasn't degraded + +## Quick Commands + +### All Quality Checks + +```bash +# Run all quality checks +make complexity && make dead-code && make duplicates && make tech-debt +``` + +### Individual Checks + +```bash +# Cyclomatic complexity analysis +make complexity + +# Dead code detection +make dead-code + +# Duplicate code detection +make duplicates + +# Technical debt tracking (TODO/FIXME comments) +make tech-debt +``` + +## Quality Checks Explained + +### 1. Cyclomatic Complexity + +**What it measures**: Code complexity based on number of independent paths through code. + +**Configured in**: +- TypeScript: `nemoclaw/eslint.config.mjs` (max: 15) +- Python: `nemoclaw-blueprint/pyproject.toml` (max: 15) + +**Run it**: + +```bash +make complexity +# or +cd nemoclaw && npm run lint +cd nemoclaw-blueprint && make check +``` + +**Interpreting Results**: + +``` +✖ Function 'processInference' has complexity 18 (max: 15) + nemoclaw/src/commands/connect.ts:42 +``` + +**Complexity 1-5**: Simple, easy to understand ✅ +**Complexity 6-10**: Moderate, acceptable ⚠️ +**Complexity 11-15**: Complex, consider refactoring 🔶 +**Complexity 16+**: Too complex, must refactor ❌ + +**How to fix**: Break large functions into smaller ones: + +```typescript +// ❌ BAD: Complexity 18 +function process(data: Data) { + if (cond1) { /* logic */ } + else if (cond2) { /* logic */ } + else if (cond3) { /* logic */ } + // ... many more conditions +} + +// ✅ GOOD: Complexity 3 +function process(data: Data) { + const handlers = { + type1: handleType1, + type2: handleType2, + type3: handleType3, + }; + return handlers[data.type]?.(data); +} +``` + +### 2. Dead Code Detection + +**What it detects**: Unused variables, functions, imports, and exports. + +**Tools**: +- TypeScript: **knip** (configured in `nemoclaw/knip.json`) +- Python: **vulture** (configured in `nemoclaw-blueprint/.vulture`) + +**Run it**: + +```bash +make dead-code +# or +cd nemoclaw && npm run dead-code +cd nemoclaw-blueprint && vulture . +``` + +**Interpreting Results**: + +``` +Unused exports (1) + createLogger nemoclaw/src/logger.ts:42 + +Unused files (1) + nemoclaw/src/utils/old-helper.ts +``` + +**How to fix**: +1. **Remove truly unused code** - Delete it entirely +2. **Mark as intentionally unused** - Add `/* Used externally */` comment +3. **Export if needed** - If code is used but not exported, export it +4. **Ignore in config** - Add to knip.json or .vulture ignore list + +### 3. Duplicate Code Detection + +**What it detects**: Copy-pasted code blocks that violate DRY principle. + +**Tool**: **jscpd** (configured in `.jscpd.json`) + +**Run it**: + +```bash +make duplicates +# or +npm run duplicates +``` + +**Interpreting Results**: + +``` +Found 3 clones with 42 duplicated lines in 2 files (12.4%) + +Clone #1: + nemoclaw/src/commands/launch.ts:42-67 + nemoclaw/src/commands/connect.ts:89-114 + Lines: 26 +``` + +**Thresholds**: +- **<5% duplication**: Excellent ✅ +- **5-10% duplication**: Acceptable ⚠️ +- **>10% duplication**: Needs refactoring ❌ + +**How to fix**: + +```typescript +// ❌ BAD: Duplicated code in launch.ts and connect.ts +async function launch() { + const config = loadConfig(); + validateConfig(config); + await initializeService(config); + // ... same logic in connect.ts +} + +// ✅ GOOD: Extract common logic +async function prepareService() { + const config = loadConfig(); + validateConfig(config); + await initializeService(config); + return config; +} + +async function launch() { + const config = await prepareService(); + // launch-specific logic +} + +async function connect() { + const config = await prepareService(); + // connect-specific logic +} +``` + +### 4. Technical Debt Tracking + +**What it detects**: TODO, FIXME, HACK, XXX comments that represent technical debt. + +**Tool**: **leasot** (scans TypeScript, JavaScript, and Python files) + +**Run it**: + +```bash +make tech-debt +# or +npm run tech-debt +``` + +**Interpreting Results**: + +```markdown +## bin/lib/metrics.js +- [ ] `TODO`: Implement metrics aggregation (line 42) +- [ ] `FIXME`: Handle edge case for empty data (line 89) + +## nemoclaw-blueprint/orchestrator/runner.py +- [ ] `TODO`: Add retry logic for failed steps (line 156) +``` + +**How to manage**: + +1. **Link TODOs to issues**: `TODO(#123): Fix this` links to issue #123 +2. **Prioritize**: FIXME > TODO > NOTE +3. **Set deadlines**: `TODO(v0.2.0): Implement feature X` +4. **Clean up regularly**: Remove completed TODOs +5. **Track in issues**: Create GitHub issues for important TODOs + +**Best practice**: + +```typescript +// ❌ BAD: Vague TODO +// TODO: fix this + +// ✅ GOOD: Specific TODO with context +// TODO(#456): Add timeout to prevent infinite loops (target: v0.2.0) +``` + +## Quality Metrics Dashboard + +After running all checks, you can create a quality dashboard: + +```bash +# Generate all metrics +make complexity > metrics/complexity.txt +make dead-code > metrics/dead-code.txt +make duplicates > metrics/duplicates.txt +make tech-debt > metrics/tech-debt.md +``` + +Track over time: +- **Complexity**: Should trend downward +- **Dead code**: Should be near zero +- **Duplication**: Should stay below 5% +- **Tech debt**: Should decrease before releases + +## Integration with CI + +Quality checks can be enforced in CI: + +```yaml +# Example GitHub Actions job +- name: Check code quality + run: | + make complexity + make dead-code + make duplicates +``` + +Set up quality gates: +- Fail PR if complexity >15 is introduced +- Warn if duplication >10% +- Require TODO cleanup before releases + +## Common Issues and Fixes + +### High Complexity in CLI Commands + +CLI commands often have high complexity due to argument parsing and validation. + +**Fix**: Extract validation and processing logic: + +```typescript +// ❌ BAD: High complexity in command handler +async function onboardCommand(args) { + if (!args.profile) { /* handle */ } + if (args.gpu && !hasGpu()) { /* handle */ } + if (args.model && !validModel(args.model)) { /* handle */ } + // ... many more conditions +} + +// ✅ GOOD: Extract validation +async function onboardCommand(args) { + const config = validateOnboardArgs(args); + await executeOnboard(config); +} + +function validateOnboardArgs(args) { + // validation logic extracted +} +``` + +### False Positive Dead Code + +Some exports are used externally (by OpenClaw plugin system): + +**Fix**: Add knip configuration: + +```json +// nemoclaw/knip.json +{ + "entry": ["src/index.ts"], + "project": ["src/**/*.ts"], + "ignore": ["src/exports.ts"] // Intentionally exported +} +``` + +### Acceptable Duplication + +Some duplication is acceptable (test setup, type definitions): + +**Fix**: Configure jscpd to ignore: + +```json +// .jscpd.json +{ + "ignore": [ + "**/test/**", + "**/*.d.ts" + ] +} +``` + +## Best Practices + +1. **Run quality checks regularly** - Weekly or before each release +2. **Set quality gates** - Enforce maximum complexity and duplication +3. **Prioritize tech debt** - Address FIXMEs before TODOs +4. **Refactor incrementally** - Improve quality with each change +5. **Track trends** - Monitor quality metrics over time + +## Example Workflow + +```bash +# 1. Run full quality analysis +make complexity +make dead-code +make duplicates +make tech-debt + +# 2. Review results and prioritize fixes +# - High complexity functions? → Refactor +# - Unused code? → Delete +# - Duplication? → Extract common logic +# - Old TODOs? → Complete or create issues + +# 3. Make improvements +# ... refactor code ... + +# 4. Verify improvements +make complexity # Should show lower scores +make dead-code # Should show fewer unused items + +# 5. Commit improvements +git add -A +git commit -m "refactor: reduce complexity and remove dead code" +``` + +## Success Criteria + +✅ All functions have complexity ≤15 +✅ No unused exports or files (or justified) +✅ Code duplication <5% +✅ TODOs are tracked with issue numbers +✅ Tech debt decreases over time + +When all criteria are met, your codebase is maintainable and healthy! 🎉 + +## Related Commands + +- `make check` - Run linting and formatting checks +- `npm test` - Run test suite +- `make lint` - Run linters only diff --git a/.factory/skills/generate-release-notes/SKILL.md b/.factory/skills/generate-release-notes/SKILL.md new file mode 100644 index 000000000..68f56a36a --- /dev/null +++ b/.factory/skills/generate-release-notes/SKILL.md @@ -0,0 +1,429 @@ +--- +name: generate-release-notes +description: Generate changelog and release notes from git commits. Use when preparing releases, updating CHANGELOG.md, or documenting changes. Trigger keywords - changelog, release notes, release, version, what changed. +--- + +# Generate Release Notes + +Generate release notes and changelog from git commit history using conventional commit conventions. + +## Prerequisites + +- You must be in the NemoClaw repository root +- Git repository must have commit history +- Node.js 20+ must be installed +- Dependencies must be installed (`npm install`) + +## When to Use + +- **Before creating a release** - Document what's changed +- **Updating CHANGELOG.md** - Keep changelog current +- **Release announcements** - Generate user-facing release notes +- **Version planning** - See what features are ready to ship +- **Contributor attribution** - Acknowledge all contributors + +## Quick Commands + +### Generate Full Changelog + +```bash +# Generate complete changelog from all commits +npm run changelog:full +``` + +Creates/updates `CHANGELOG.md` with all releases. + +### Generate Latest Release Notes + +```bash +# Generate notes for latest changes +npm run changelog +``` + +Generates notes from last tag to HEAD (or all commits if no tags). + +### Manual Generation with Script + +```bash +# Generate release notes for specific version +node scripts/generate-changelog.js --version v0.2.0 + +# Generate from specific tag range +node scripts/generate-changelog.js --from v0.1.0 --to HEAD +``` + +## Commit Message Conventions + +NemoClaw uses **Conventional Commits** for automated changelog generation: + +### Format + +``` +(): + + + +