bot-agents/.agents/memory/package-json-shape.md

description

description
package.json keys follow Oxfmt's standard order (vp check --fix); standard fields only; no peerDependencies or packageManager

Key order (2026-10-16)

Oxfmt's standard package.json sorting is accepted: there is no fmt: { sortPackageJson: false }, and vp check --fix sets the order. This replaces the earlier hand-written order (metadata, scripts, exports, imports, devDependencies, dependencies).

The imports key order can carry meaning: the modules plugin's enforce-layer-order reads it as the layer order. Never reorder it casually.

Fields

• Standard fields only. engines has only node (never engines.bun). A tool-owned key (eslint-doc-generator) is allowed only because the tool reads nothing else and no other config file is allowed.
• No packageManager. npm is detected from package-lock.json.
• No peerDependencies, ever (user preference, 2026-10-14). If something is needed at runtime, it goes in dependencies.
• dependencies = what runs or is type-referenced at runtime by consumers (the lit plugin ships parse5, oxc-parser, oxc-resolver, and @eslint/core for its public types; they stay external, never bundled).
• devDependencies = everything else: vite-plus, eslint, @typescript-eslint/parser, eslint-doc-generator, esbuild, typescript-6, @types/node. ESLint is a devDependency only; plugins need nothing from it at runtime.

Refresh the lockfile with npm install (or npm install --package-lock-only for a version bump) and commit it with the change.

Alias rule: an alias may point anywhere and owns its target (a folder's index.ts owns the folder and everything below it; any other file owns only itself). No two aliases may own the same file, outside an area only the exact alias reaches it, and ../ is banned in every file (imports-aliases-barrels).