Code Standards

Purpose #

The TypeScript / monorepo / file-emission conventions every package follows.

Language and runtime #

From ADR-0001 and CLAUDE.md §7.1:

Runtime: Node.js 20+ (LTS). Node 22 must work without modification.
Language: TypeScript 5.4+, strict mode, ESM-only.
Module resolution: nodenext. Imports use .js extensions (TypeScript resolves to .ts).
No CJS dual publish.

// Correct
import { Adapter } from './contract.js';

// Incorrect (breaks at runtime in ESM)
import { Adapter } from './contract';

Monorepo conventions #

pnpm workspaces + Turborepo.
Workspace deps use workspace:*; Changesets rewrites at publish.
.npmrc enforces node-linker=isolated (strict mode), auto-install-peers=false, strict-peer-dependencies=true, save-exact=true.
Every package declares engines.node: ">=20.0.0" and "type": "module".

File organisation #

Per CLAUDE.md §7.3:

One responsibility per file.
Public surface goes through index.ts per package.
No default exports in @aidokit/core — named exports keep IDE refactoring honest.
Co-locate unit tests with source: src/foo.ts ↔ src/foo.test.ts.

Error handling #

All thrown errors inside the codebase are AidoError with a machine-readable code.
The CLI maps AidoError.code to exit codes via packages/cli/src/exit-codes.ts.
See reference/error-codes.md.

File system and shell #

All async filesystem work uses fs/promises. No fs.*Sync in command paths.
Shell execution goes through the single helper in @aidokit/core so capability declarations stay enforceable.
Direct child_process.spawn outside that helper is a code-review red flag. AD-STD-CAP-01 conformance check catches this for adapters.

Templates #

Live under packages/*/src/files/ as real files mirroring their target layout.
Tree-copied to dist/files/ by scripts/copy-files.mjs after tsc.
Variable substitution only via interpolate(template, vars) from @aidokit/core.
{{varName}} syntax; unknown variable throws.
No template engines. No Handlebars, EJS, Nunjucks, Mustache. Complex emission is programmatic.

Cross-package imports #

From concepts/three-layer-architecture.md:

Strict downward dependency.
@aidokit/core MUST have zero runtime deps on other @aidokit/* packages.
Adapters MUST NOT import stack packs (and vice versa).
Only @aidokit/cli consumes both.

Naming #

Packages: @aidokit/<name> (scoped) or aidokit (unscoped CLI).
Adapter packages: @aidokit/adapter-<name>.
Stack-pack packages: @aidokit/stack-pack-<name>.
Third-party: @scope/aidokit-adapter-<name> or unscoped aidokit-adapter-<name> (ADR-0004 §2).

Linting and formatting #

ESLint (flat config: eslint.config.js).
Prettier (.prettierrc, .prettierignore).
Run via pnpm lint / pnpm format at the root.
CI fails the build on lint errors.

Library choices (locked via ADRs) #

Argument parser: Commander (ADR-0009).
Prompts: @clack/prompts (ADR-0010).
Schema: Zod, re-exported from @aidokit/core/schema (ADR-0011).
Test runner: Vitest.
Build orchestrator: Turborepo.
Release: Changesets.

Adding a new dependency that occupies one of these slots requires a new ADR.

What NOT to do #

Per CLAUDE.md §8:

No template engines (Handlebars / EJS / Nunjucks / Mustache).
No YAML-as-code where a TypeScript interface fits.
No runtime plugin discovery (post-v1.0 SDK work).
No LLM calls of any kind from aidokit itself.
No telemetry, phone-home, anonymous metrics, version-check pings.
No cross-package upward imports; no adapter ↔ stack-pack imports.
No overwriting user files without diff + confirm.
No auto-installing prereqs (ADR-0008).
No speculative features not in the v1.0 In-Scope list.