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>

.agents/memory/bot-agents-child-processes.md

@@ -1,5 +1,5 @@
 ---
-description: Child processes use plain node:child_process spawn (explicit stdio, uid/gid, whole env); src/child.ts has exitCode (128+signo) and echo; no execFile maxBuffer
+description: Child processes use plain node:child_process spawn (explicit stdio, uid/gid, whole env); src/processes/child.ts has exitCode (128+signo) and echo; no execFile maxBuffer
 ---
 
 Every call site calls `spawn` from `node:child_process` itself, with
@@ -15,7 +15,7 @@ everything explicit:
 - No `execFile`/`exec`: their `maxBuffer` (1 MiB) kills a chatty child. Read
   piped streams incrementally instead.
 
-`src/child.ts` holds what the call sites share:
+`src/processes/child.ts` holds what the call sites share:
 
 - **`exitCode(child)`**: call it right after `spawn`. It settles on `exit`
   (not `close`, which a daemonized grandchild can hold open), maps a signal to
@@ -28,9 +28,9 @@ Tests use `spawnSync` for short commands.
 
 Other port details:
 
-- **`src/errors.ts`** `isNotFound` checks `ENOENT` (file) or `ESRCH` (process).
+- **`src/common/errors.ts`** `isNotFound` checks `ENOENT` (file) or `ESRCH` (process).
 - Temporary files are an exclusive `wx` create with mode `0600`.
-- `src/json.ts` holds type guards used instead of `as` casts on parsed JSON.
+- `src/common/json.ts` holds type guards used instead of `as` casts on parsed JSON.
 - `process` and `Buffer` must come from `node:` imports:
   `no-restricted-globals` in `scripts/project-lint.ts` enforces it
   ([[lint-parity-never-shrinks]]).

.agents/memory/bot-agents-lint-opt-outs.md

@@ -15,7 +15,7 @@ when the migration PR was approved:
   ([[lint-overrides-policy]]).
 
 Size and complexity limits match Deno, which had none here, so every Oxlint
-limit rule is `"off"` ([[lint-config-shape]]). `run.ts` and `post.ts` keep
+limit rule is `"off"` ([[lint-config-shape]]). `src/run/index.ts` and `src/post/index.ts` keep
 main's single-file layout (2026-10-17 revert of the size splits). Sequential
 awaits in loops became recursion or a `reduce` chain (`no-await-in-loop`) to
 stay sequential. Add no other opt-out without the user.

.agents/memory/bot-agents-migration-decisions.md

@@ -1,5 +1,5 @@
 ---
-description: bot-agents migration decisions: live @main action for six repos, JSON profiles, Node 24.2+, no eslint-plugin-* packages needed
+description: bot-agents migration decisions: live @main action for six repos, JSON profiles, Node 24.2+, lints with eslint-plugin-import-structure and explicit-types (concrete, absence)
 ---
 
 Decisions for `commons/bot-agents` (Capsulizers Gitea), from the Deno to
@@ -15,16 +15,19 @@ Node + Vite+ migration (PR #20, `node-migration`, 2026-10-15/16):
   removed the only runtime dependency (`@std/yaml`); keep it free of runtime
   dependencies (`@eslint/core` and the other devDependencies serve only the
   tooling).
-- **Node 24.2+**, not 22: `src/post.ts` uses `import.meta.main`. There is no
+- **Node 24.2+**, not 22: `src/post/index.ts` uses `import.meta.main`. There is no
   `engines` (user decision 2026-10-18): the `node:24-bookworm` job image
   decides the version ([[bot-agents-runtime-no-build]]).
-- **No `eslint-plugin-*` packages** (`eslint-plugin-explicit-types`,
-  `eslint-plugin-import-structure`, `eslint-plugin-lit-robust`; unscoped
-  since 2026-10-18, formerly `@cunarist/...`). The Deno setup enabled no
-  plugin, so this repo depends on none and CI passes without them being
-  published. Planned (2026-10-17): once the plugins are on npm, add
-  `eslint-plugin-import-structure` (rule prefix `import-structure/`) here for
-  its import checks.
+- **Published lint plugins** (2026-10-18, after they reached npm):
+  `eslint-plugin-import-structure` (`modules` config) and
+  `eslint-plugin-explicit-types` (`concrete` and `absence` configs) are
+  devDependencies, enabled in `vite.config.ts`. explicit-types' `naming`
+  config is left off: its `upper-snake-string-unions` and
+  `no-upper-snake-object-keys` rules fire on wire tokens this repo does not
+  name (profile types such as `"claude"`, failure reasons posted to Gitea,
+  environment variable names), which cannot change without changing
+  behavior. Open question for the user. `eslint-plugin-lit-robust` does not apply
+  (no Lit).
 - **Stricter input checks were accepted** in the migration: Gitea `/user` and
   comment responses, the runtime manifest, and the outcome's profile type are
   validated; some type errors became `TypeError` with the same messages.

.agents/memory/bot-agents-runtime-no-build.md

@@ -10,7 +10,7 @@ dependency**. Hence `tsconfig.json` has `erasableSyntaxOnly` and
 properties, no decorators) and relative `.ts` imports.
 
 - **Image:** the steps assume the `node:24-bookworm` job container. Node must
-  be 24.2+ for `import.meta.main` in `post.ts`. That image is the only Node
+  be 24.2+ for `import.meta.main` in `src/post/index.ts`. That image is the only Node
   pin (`package.json` has no `engines`); `check.yml` prints `node --version`
   to confirm the cached image's minor.
 - **Root-owned source copy:** `scripts/protect-source.sh` copies the action

.agents/memory/bot-agents-tests-root-only.md

@@ -2,24 +2,24 @@
 description: Isolation and credential tests need root and use test.skipIf(!IS_ROOT); locally 5 skip, CI runs as root so all 66 run; verify isolation changes in node:24-bookworm as root
 ---
 
-Some tests exercise real UID isolation, process cleanup, and `prepare.ts`
+Some tests exercise real UID isolation, process cleanup, and the prepare phase's
 credential cleanup. They need root and are written as
 `test.skipIf(!IS_ROOT)(...)` (`IS_ROOT` from `#testing`), so they show
 as skipped instead of silently passing.
 
 - As a normal user `vp test` passes 61 and skips 5. In CI (self-hosted
   runner, root) all 66 run.
-- When changing `isolation.ts`, `runtime.ts`, `credentials.ts`, `prepare.ts`,
+- When changing `isolation.ts`, `runtime.ts`, `credentials.ts`, `prepare/index.ts`,
   or `child.ts`, run the suite as root in `node:24-bookworm` (e.g. a
   container with the repo mounted) before pushing; a green non-root run
   proves nothing about those paths.
 - The migration also ran an end-to-end smoke as root with fake
   `codex`/`claude`/`npx` binaries and a fake Gitea through
-  `protect-source.sh` -> `prepare.ts` -> `run.ts` -> `post.ts`; repeat that
+  `protect-source.sh` -> `prepare/index.ts` -> `run/index.ts` -> `post/index.ts`; repeat that
   for changes to the phase flow ([[bot-agents-runtime-no-build]]).
 - `src/testing/index.ts` holds the shared test helpers (user IDs, temp dirs,
   `runCommand`) behind the `#testing` alias. Every test imports it as
   `#testing`. It imports no source module, so `tests/` (which may not use
   `../`) never reaches internals. Tests follow
-  [[tests-layout-vitest]] (unit tests in `src/*.test.ts`, repo-level ones in
+  [[tests-layout-vitest]] (unit tests next to their code in `src/`, repo-level ones in
   `tests/`).

.agents/memory/imports-aliases-barrels.md

@@ -97,7 +97,8 @@ It is not a plugin rule.
 - Every `package.json` `imports` alias points only at the `index.ts` of a
   direct subfolder of `src/`, e.g. `"#helpers": "./src/helpers/index.ts"`.
   No alias to a single file, a deeper folder, or anything outside `src/`.
-  Here the one alias is `"#testing": "./src/testing/index.ts"`.
+  Here the aliases are `#prepare`, `#run`, `#post`, `#agents`, `#processes`, `#runtime`, `#profiles`,
+  `#common`, and `#testing`, in that layer order.
 - Code outside `src/` (`scripts/`, `tests/`, `vite.config.ts`) gets no alias
   of its own and imports its own files by `./` relative paths. It reaches
   `src/` only through the aliases, since `../` is banned.

.agents/memory/toolchain-node-vite-plus.md

@@ -14,7 +14,7 @@ description: Node.js (no engines in apps; images pin 24) with Vite+ (vp) and npm
   `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.ts` needs 24.2+ (`import.meta.main`).
+  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.