envsitter-guard/AGENTS.md

AGENTS.md — envsitter-guard

This repository is a minimal TypeScript plugin meant to run under OpenCode (@opencode-ai/plugin).

Repo layout

• index.ts: main plugin implementation (EnvSitterGuard).
• tsconfig.json: TypeScript config (strict, noEmit).
• .opencode/: OpenCode packaging/runtime wrapper.
  • .opencode/plugin/envsitter-guard.ts re-exports the plugin from index.ts.
  • .opencode/bun.lock indicates Bun-managed deps inside .opencode/.
• node_modules/: vendored deps (present locally; do not edit).

Commands (build / lint / test)

Install

• Root install (lockfile: package-lock.json):

  • npm ci
  • npm install (ok for local dev; npm ci preferred for reproducibility)

• .opencode/ install (Bun lockfile present):

  • If you need to refresh .opencode/node_modules, use Bun from .opencode/:
    • cd .opencode && bun install
  • If Bun is unavailable, do not guess; ask before changing .opencode/ dependency management.

Build / typecheck

This repo does not emit JS as part of its normal workflow.

• Typecheck (canonical):
  • npm run typecheck
  • Equivalent: npx tsc -p tsconfig.json

Lint / format

• No linting or formatting commands are configured in the root project.
• No .eslintrc*, eslint.config.*, biome.json, or Prettier config exists at repo root.
• Do not introduce new linters/formatters unless explicitly requested.

Tests

Tests use Node’s built-in test runner, compiled via tsc into dist-test/.

• Run all tests (builds then runs):
  • npm test
• Build test output only:
  • npm run build:test
• Run a single test file:
  • npm run build:test && node --test dist-test/test/envsitter-guard.hook.test.js

Pre-commit checks are enforced via Husky:

• npm install installs the git hook.
• .husky/pre-commit runs npm run typecheck and npm test.

TypeScript / module conventions

• ESM project: package.json has "type": "module".
• TS config: module: "NodeNext", moduleResolution: "NodeNext", target: "ES2022", strict: true, noEmit: true.
• Prefer import type { ... } for type-only imports (see index.ts).
• Prefer node: specifier for Node built-ins (e.g. import path from "node:path").

Formatting conventions (match existing code)

• Indentation: 4 spaces.
• Quotes: double quotes.
• Semicolons: required.
• Trailing commas: used in multiline objects/args.
• Keep functions small and single-purpose (see path validation helpers in index.ts).

Naming conventions

• camelCase: functions, locals, parameters.
• PascalCase: exported plugin symbol (EnvSitterGuard).
• Booleans use is* / has* prefixes (e.g. isSensitiveDotEnvPath).

Error handling & validation

This plugin is security-sensitive. Follow these patterns:

• Prefer early validation + throw new Error("...") with a clear, user-facing message.
• Avoid swallowing errors (no empty catch blocks).
• Avoid any and type suppression (as any, @ts-ignore, @ts-expect-error).
• When parsing unknown inputs, narrow types explicitly (e.g. typeof args === "object", then access via Record<string, unknown>).

Security & secrets

• Do not read or print .env values.
• Treat .env.secure as sensitive; never commit secrets.
• This repo’s plugin is designed to block sensitive .env* and .envsitter/pepper access via tooling and to guide users toward safe inspection:
  • envsitter_keys (lists keys only)
  • envsitter_fingerprint (hash/fingerprint only)

Working with .opencode/

• .opencode/ is a packaging/runtime layer for OpenCode plugins; treat it as part of the deployment surface.
• Keep .opencode/plugin/envsitter-guard.ts as a thin re-export (do not add logic there).
• Avoid editing .opencode/node_modules directly.

Change discipline

• Prefer minimal diffs; avoid refactors during bugfixes.
• Keep behavior consistent with index.ts patterns:
  • normalize paths before regex matching
  • ensure file paths stay within worktree
  • throttle UI toasts (lastToastAt pattern)

Plugin behavior notes

• OpenCode entrypoint is EnvSitterGuard exported from index.ts.
• Plugin registration file .opencode/plugin/envsitter-guard.ts must remain a thin re-export.
• Tool surface area intentionally small:
  • envsitter_keys: lists keys only (no values)
  • envsitter_fingerprint: deterministic fingerprint of a single key (no value)
• Blocking behavior is enforced in "tool.execute.before":
  • Blocks reads of .env* (except .env.example).
  • Blocks edits/writes/patching of .env* and .envsitter/pepper.
  • Throttles UI toasts via lastToastAt.

Path handling rules

• Treat all incoming tool args as untrusted.
• Normalize path separators before matching (Windows \\ → /).
• Validate allowed paths before resolving to absolute paths.
• Ensure resolved paths stay within worktree using path.relative() checks.

Output conventions

• Prefer returning structured JSON via JSON.stringify(obj, null, 2).
• Never include secret values in output strings, prompts, or toast messages.
• Errors should be user-facing and actionable (what was blocked + safe alternative).

Dependency & change policy

• Keep this repo minimalist: prefer existing dependencies over adding new ones.
• Do not change .opencode/ dependency management unless you know the OpenCode packaging constraints.
• Never edit vendored node_modules/ or .opencode/node_modules/.

Repo hygiene

• When searching the codebase, exclude node_modules/ and .opencode/node_modules/ unless you are explicitly auditing dependency behavior.
• Do not add new config files (ESLint/Prettier/Biome/etc.) unless explicitly requested.

Verification checklist

• npm run typecheck passes.
• No tool path allows reading raw .env* values.
• .opencode/plugin/envsitter-guard.ts remains a re-export only.
• Error messages remain clear and do not leak file contents.

Cursor / Copilot rules

• No .cursor/rules/, .cursorrules, or .github/copilot-instructions.md were found in this repository.