Danny Kim
32806120b3
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>
62 lines
3.5 KiB
Markdown
62 lines
3.5 KiB
Markdown
---
|
|
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.
|