commons/bot-agents
3
0
Fork 0
Code Issues Pull Requests Actions Releases 3 Activity
Files
b97fffcebd4cab0d4724a8d1ebbb1b3c47b39bdc
bot-agents/.agents/memory/toolchain-node-vite-plus.md
T
Danny Kim 32806120b3 Group the sources into aliased modules and lint with the published plugins (#23) 
Groups the flat `src/` into cohesive modules and turns on the published lint plugins. No behavior change.

## Module layout

Each module is a direct `src/` subfolder with an `index.ts` barrel and a `#` alias in `package.json` `imports` (layer order, top first):

| Alias | Files |
| --- | --- |
| `#prepare` | `index.ts` (the prepare phase entry point) |
| `#run` | `index.ts` (the run phase entry point) |
| `#post` | `index.ts` (the post phase entry point), `post.ts`, `post.test.ts` |
| `#agents` | `auth.ts`, `opencode.ts` (Codex / Claude Code sign-in, OpenCode args and output) |
| `#processes` | `child.ts`, `isolation.ts` |
| `#runtime` | `runtime.ts`, `credentials.ts` |
| `#profiles` | `profiles.ts` |
| `#common` | `errors.ts`, `json.ts` |
| `#testing` | `index.ts` (unchanged) |

Every top-level entry of `src/` is an aliased module folder. Tests stay next to their code as `*.test.ts`. Each phase's `index.ts` is its entry point, and `action.yml` now runs `node src/<phase>/index.ts`. The post phase's logic moved to `src/post/post.ts` so its test can import it; `index.ts` keeps the env reading and the `import.meta.main` call. `run`'s prompt URL is now `../../prompt.md`. `scripts/protect-source.sh` now copies `src/` recursively (it used to copy `src/*.ts` only), and the workflow test checks that module files get staged too.

## Lint plugins

- New devDependencies: `eslint-plugin-explicit-types@^0.6.1` and `eslint-plugin-import-structure@^0.10.2`, both in `jsPlugins`. The lockfile comes from a real `npm install`.
- Enabled configs: `importStructure.configs.modules`, `explicitTypes.configs.concrete`, `explicitTypes.configs.absence`.
- **explicit-types `naming` is off** (the other app repos turn it on). Its `upper-snake-string-unions` and `no-upper-snake-object-keys` rules fire on wire tokens this repo doesn't choose: profile types `"claude" | "codex" | "opencode"` from `profiles.json`, failure reasons posted to Gitea, Gitea's `"new" | "old"` side, and environment variable names such as `PATH`. Satisfying them would change behavior or need opt-outs. This is logged as an open question for the user.

Lint fixes, all type-level:
- `Pick<BotProfile, "type" | "model">` became a named `ProfileIdentity` interface that `BotProfile`, `ProfileFailure`, and `RuntimeProfile` extend. `RuntimeOutcome` is now `RuntimeSuccess | RuntimeFailure`.
- Inline object types became named interfaces.
- `Record<string, string>` env maps became `NodeJS.ProcessEnv`. `JsonObject` and the verdict table became `NodeJS.Dict<…>`.
- `T | undefined` locals and returns became `T | null` with matching checks. `typeof fetch` became a `Fetcher` type.
- Claude's result fields are held in camelCase (`isError`, `apiErrorStatus`) after parsing, because `id-match` rejects snake_case interface members.
- Duplicate import sources are merged (`import-structure/no-duplicate-import-source`).

## Verification

- `vp check`: clean.
- `vp test`: 61 passed and 5 skipped as a normal user. All 66 passed as root in `node:24-bookworm`.
- Each phase (`node src/<phase>/index.ts`) run from a `protect-source.sh` copy loads its full alias graph under Node.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Reviewed-on: #23
Reviewed-by: bot <noreply@capsulizers.com>
Co-authored-by: Danny Kim <temeddix@gmail.com>
Co-committed-by: Danny Kim <temeddix@gmail.com>
2026-10-18 15:00:16 +00:00

3.5 KiB
Raw Blame History

description
description
Node.js (no engines in apps; images pin 24) with Vite+ (vp) and npm; only package.json, tsconfig.json, vite.config.ts plus a committed package-lock.json

The stack

  • Runtime: Node.js. App repos have no engines field (user decision 2026-10-18): the container or runner image decides the version, so the Containerfile base image (node:24-alpine) and CI's node-version: "24" are the pins. Published packages (the lint plugins) keep their own engines.node floor. npm run lit-check runs node scripts/lit-check.ts, which needs Node 22.18+ (unflagged type stripping and module.registerHooks); Node 24 satisfies it. Without engines or a .node-version, local vp uses its default Node (vp env default). bot-agents has no Containerfile or setup step: the self-hosted runner's node:24-bookworm job image runs the action and its checks, and src/post/index.ts needs 24.2+ (import.meta.main).
  • Bun is not supported (dropped 2026-10-15). No Bun CI legs, docs, or runtime branches. Oxlint's RuleTester refuses to run under Bun anyway, and vp brings its own Node, the way uv brings its own Python.
  • Toolchain: Vite+ (vite-plus devDependency, command vp): Vite, Vitest, Oxlint, Oxfmt, type checking, tsdown.
  • Package manager: npm everywhere. package-lock.json is committed in apps and libraries (user agreed 2026-10-14: npm ci needs it). There is no packageManager field; Vite+ detects npm from the lockfile.

Config files

Exactly three, plus the lockfile: package.json, tsconfig.json, vite.config.ts. No .oxlintrc.json, .prettierrc, eslint.config.*, vitest.config.*, .npmrc, or tsdown.config.*. Tool options go into vite.config.ts keys (lint, fmt, test, pack) or, when a tool only reads package.json (eslint-doc-generator), into a package.json key. The target is a short vite.config.ts, around 30 lines (not strict).

Commands

Command Does
vp check format check, Oxlint (type-aware), and type check together
vp check --fix the same, applying formatting and safe fixes
vp test Vitest; vp test tests runs only the top-level tests/
vp build Vite production build (apps)
vp dev Vite dev server (apps)
vp pack tsdown library build into dist/ (packages)
npm ci / npm install install; never another package manager

vp check, vp test, and the build (vp build or vp pack) must all pass before any push. CI installs the toolchain with voidzero-dev/setup-vp.

Gotchas found during the migration

  • vp check does not report isolatedDeclarations errors (TS9010); only vp pack does, so packages run vp pack in CI on every PR.
  • Oxfmt sorts package.json keys by default; that order is accepted, so there is no fmt option for it (package-json-shape).
  • Oxlint and Oxfmt skip what .gitignore lists; that is the only reason dist/ and node_modules/ are not linted. Keep build output gitignored.
  • Vite+ bundles vite.config.ts itself and resolves # imports in it.
  • Oxlint loads a .ts plugin file directly on Node 24 (jsPlugins), so repo-local lint plugins need no build step.
Reference in New Issue View Git Blame Copy Permalink