From 4726b9126193a272d12540f06bff75803ae7ad77 Mon Sep 17 00:00:00 2001 From: thatonevikash Date: Fri, 11 Sep 2026 13:57:46 +0530 Subject: [PATCH] chore(files): gents.md added --- AGENTS.md | 70 +++++++++++++++++++++++++++++++++++++++++ src/AGENTS.md | 53 +++++++++++++++++++++++++++++++ src/sdk/brain/AGENTS.md | 48 ++++++++++++++++++++++++++++ 3 files changed, 171 insertions(+) create mode 100644 AGENTS.md create mode 100644 src/AGENTS.md create mode 100644 src/sdk/brain/AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8aba6b8 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,70 @@ +# Nova contributor guidance + +## Project overview + +Nova is a local terminal AI assistant. It accepts a natural-language task, asks +an AI provider for a structured plan, displays the plan, and executes the +provider-returned command strings sequentially in the user's shell. + +The project uses Node.js 18 or newer and ECMAScript modules. Keep JavaScript +imports explicit with `.js` extensions. + +Important entry points: + +- `bin/nova.js` dispatches the normal CLI and `nova --dev`. +- `src/index.js` coordinates configuration, model evaluation, UI, and execution. +- `src/sdk/` contains provider adapters and provider-specific brain prompts. +- `src/executor.js` owns working-directory state and command execution. +- `.development/index.js` is the interactive development action menu. + +## Change principles + +- Keep runtime behavior consistent on Windows, macOS, and Linux. Prefer Node.js + APIs over platform-specific shell syntax when Node can perform the operation. +- Preserve the existing CLI and configuration interfaces unless the task + explicitly changes them. +- Never log, commit, snapshot, or include API keys in errors. Treat + `~/.nova/config.json` and all provider credentials as secrets. +- Keep provider-specific behavior aligned. A supported task must produce the + same operational meaning regardless of the selected model provider. +- Update user documentation when commands, setup, configuration, or supported + task categories change. + +## Command safety + +Treat model responses, command arguments, file paths, and user input as +untrusted data. Nova's target design is a strict allowlist: every executable +operation must have a known category, validated arguments, and an explicit +executor implementation. Adding a command family requires updating the plan +contract, validation, executor handling, provider prompts, examples, and tests +together. + +Do not add or extend a generic shell-command escape hatch. The current fallback +in `src/executor.js`, which sends every otherwise-unmatched model command to a +shell, is known technical debt and must not be described as safe. When touching +that path, move it toward validated allowlisted operations. Destructive, +privileged, networked, or long-running operations require explicit handling and +a clear user confirmation policy. + +## Verification + +There is currently no repository-level `npm test` script. For documentation-only +changes, inspect the rendered Markdown, verify paths and commands against the +repository, and review `git diff --check` plus `git diff`. + +For behavior changes: + +- Add deterministic automated coverage, preferably with Node's built-in test + runner, and expose a stable package script when introducing the test suite. +- Run syntax checks on each changed JavaScript entry point with + `node --check `. +- Exercise `node bin/nova.js --dev` manually when executor, terminal UI, or TTY + behavior changes. Use only safe actions in a disposable directory. +- Check prompt input, sequential commands, directory changes, child-process + failures, TTY handoff, and interruption with `Ctrl+C` where relevant. +- Do not use live provider calls as the only automated verification. Test plan + parsing and validation with fixed fixtures. + +Nested `AGENTS.md` files add subsystem-specific requirements. Follow both this +file and the nearest nested file; the more specific guidance wins only when it +does not weaken these safety rules. diff --git a/src/AGENTS.md b/src/AGENTS.md new file mode 100644 index 0000000..3412f22 --- /dev/null +++ b/src/AGENTS.md @@ -0,0 +1,53 @@ +# Nova runtime guidance + +This file applies to runtime code under `src/`. Follow the repository-level +`AGENTS.md` as well. + +## Runtime invariants + +- Keep command execution sequential. A later operation may depend on the + working directory or filesystem state produced by an earlier one. +- Preserve working-directory state inside Nova; do not assume that a spawned + child's `cd` changes the parent process. +- Preserve full terminal passthrough for genuinely interactive child processes. + Coordinate readline pause/resume behavior so Nova and a child never compete + for stdin. +- Keep errors concise and actionable. Include the failed operation and exit + status when useful, but never include API keys, full provider payloads, or + other credentials. +- Keep filesystem and process behavior portable across Windows, macOS, and + Linux. Resolve and validate paths before using them. + +## Execution boundary + +Never pass raw or merely schema-shaped model output directly to a shell. A +structured response is not validation. Before execution, confirm that the +category is supported, the operation matches that category, every argument has +an allowed form, and paths remain within the scope authorized by the user. + +Implement command families as explicit operations with validated arguments. +Prefer `spawn` with an executable and argument array, without `shell: true`, and +prefer Node.js filesystem APIs for directory and file operations. If a shell is +unavoidable, document why and reject shell operators, substitutions, redirects, +and additional commands that are not part of the allowlisted operation. + +Destructive, privileged, networked, and long-running operations must be modeled +explicitly. Define confirmation, cancellation, timeout, exit-code, and partial +failure behavior before enabling them. Never silently broaden a category to +cover arbitrary shell commands. + +## Plan contract and tests + +The current provider plan contains: + +- `analysis`: plain-language interpretation of the request. +- `category`: one supported operational category. +- `commands`: ordered command strings in the current interface. +- `description`: a short user-facing summary. + +Treat this shape as an external boundary between the provider and runtime. +Validate it before execution, and update every provider plus tests if it changes. +For executor changes, cover accepted operations, rejected commands, malformed +arguments, path traversal or unsafe path input, sequencing, directory state, +non-zero exits, and cancellation. Manually verify interactive TTY handoff and +`Ctrl+C` behavior when those paths change. diff --git a/src/sdk/brain/AGENTS.md b/src/sdk/brain/AGENTS.md new file mode 100644 index 0000000..bcb17dc --- /dev/null +++ b/src/sdk/brain/AGENTS.md @@ -0,0 +1,48 @@ +# Nova brain guidance + +This file applies to provider prompts and structured-output definitions in this +directory. Follow the repository and `src/` guidance as well. + +## Provider parity + +- Keep the Anthropic and Google instructions operationally equivalent. +- Keep task categories, command rules, examples, descriptions, and required + fields synchronized across providers. +- When the Google response schema changes, make the corresponding Anthropic + prompt contract and adapter parsing changes in the same work. +- Keep provider-specific SDK syntax isolated from the shared operational rules. + +## Safe plan generation + +Every generated operation must belong to the executor's strict allowlist and +must use arguments the executor can validate. Prompt examples are behavioral +requirements, not substitutes for runtime validation. + +Do not teach the model to invent shell commands or use a generic `mixed` +category as an escape hatch. If a request is unsupported, ambiguous in a way +that affects safety, destructive without confirmation, or contains conflicting +instructions, return or introduce an explicit non-executable rejection or +clarification outcome supported by the plan contract. Do not guess an operation +that could modify the wrong files or system state. + +The current plan fields are `analysis`, `category`, `commands`, and +`description`. Keep field meanings stable and output machine-parseable. Any new +category must be implemented and validated by the executor before prompts may +emit it. + +## Fixtures and verification + +Maintain deterministic fixtures for each supported category. Include: + +- Valid requests and expected operation order. +- Missing or malformed names and arguments. +- Unsupported and materially ambiguous requests. +- Prompt-injection attempts and requests containing shell operators, + substitutions, redirects, traversal paths, or extra commands. +- Destructive, privileged, networked, and long-running requests. +- Equivalent expected behavior for every provider. + +Automated tests should exercise parsing and validation without requiring live +API credentials. When prompt text changes, review both provider definitions and +confirm that every example remains compatible with the runtime validator and +executor allowlist.