refactor: name modules by topic and restructure the docs (#1134)

Replace the util and grab-bag modules with topic-named modules, tidy the
repo root and tooling config, and split the contributor docs into topic
guides that AGENTS.md routes to. No behavior change.

- Split `core/` into `cli/`, `storage/` and `vscode/`, and move
  `container.ts` next to `extension.ts`.
- Split grab-bag modules by topic (`common/fs`, `common/strings`,
  `common/url`, `api/models`, `error/normalize`, `logging/ids`,
  `oauth/tokens`), and move single-consumer helpers into their consumer.
- Rename the `utils` modules in the webview packages after their topic.
  Tests move to mirror their source path.
- Fold `usage.md` into the README, move `esbuild.mjs` to `scripts/`, and
  replace `.vscodeignore` with a `files` allowlist.
- Merge the oxlint configs, remove the Prettier leftovers and unused
  devDependencies, and keep the ESLint cache in `node_modules`.
- Update the Nix flake: pin nixpkgs, use Node 24 and nixpkgs' pnpm.
- Shorten AGENTS.md to a router for `docs/` guides (code structure,
  architecture, testing, tooling) and `packages/AGENTS.md`.

Author: EhabY

.devcontainer/devcontainer.json

@@ -7,7 +7,7 @@
 	"customizations": {
 		"vscode": {
 			"extensions": [
-				"esbenp.prettier-vscode",
+				"oxc.oxc-vscode",
 				"dbaeumer.vscode-eslint",
 				"vitest.explorer",
 				"ms-vscode.extension-test-runner"

.gitignore

@@ -1,17 +1,15 @@
+node_modules/
 /dist/
-/node_modules/
 /out/
 /.vscode-test/
-/.nyc_output/
 /coverage/
 /.pnpm-store/
 *.vsix
 pnpm-debug.log
-.eslintcache
-
-# Workspace packages
-packages/*/node_modules/
 
 # Storybook
 storybook-static/
 debug-storybook.log
+
+# Personal agent instructions
+AGENTS.local.md

.oxfmtrc.jsonc

@@ -3,16 +3,11 @@
 	"printWidth": 80,
 	// Disabled to avoid churning the key order of every package.json in the repo.
 	"sortPackageJson": false,
+	// Oxfmt also skips everything in .gitignore.
 	"ignorePatterns": [
-		"/dist/",
-		"/node_modules/",
-		"/out/",
-		"/.vscode-test/",
-		"/coverage/",
-		"*.vsix",
 		"flake.lock",
 		"pnpm-lock.yaml",
-		"/storybook-static/",
+		// Golden snapshots and generated VS Code theme dumps are written verbatim.
 		"**/__golden__/",
 		".storybook/themes/generated/"
 	],

.oxlintrc.jsonc

@@ -1,7 +1,6 @@
 {
 	"$schema": "./node_modules/oxlint/configuration_schema.json",
-	"extends": [".oxlintrc.react.jsonc"],
-	"plugins": ["unicorn"],
+	"plugins": ["unicorn", "typescript", "oxc"],
 	"categories": {
 		"correctness": "error"
 	},
@@ -21,6 +20,88 @@
 		"storybook-static/**"
 	],
 	"overrides": [
+		{
+			"files": ["packages/**/*.{ts,tsx}"],
+			"rules": {
+				"react/exhaustive-deps": "off",
+				"react/preserve-manual-memoization": "error",
+				"react/incompatible-library": "warn",
+				"react/error-boundaries": "error",
+				"react/globals": "error",
+				"react/immutability": "error",
+				"react/jsx-no-comment-textnodes": "warn",
+				"react/no-array-index-key": "warn",
+				"react/no-clone-element": "warn",
+				"react/no-direct-mutation-state": "error",
+				"react/purity": "warn",
+				"react/refs": "error",
+				"react/rules-of-hooks": "error",
+				"react/set-state-in-effect": "warn",
+				"react/set-state-in-render": "error",
+				"react/static-components": "error",
+				"react/unsupported-syntax": "error",
+				"react/use-memo": "error",
+				"react-x/dom-no-dangerously-set-innerhtml-with-children": "error",
+				"react-x/dom-no-dangerously-set-innerhtml": "warn",
+				"react-x/dom-no-find-dom-node": "error",
+				"react-x/dom-no-flush-sync": "error",
+				"react-x/dom-no-hydrate": "error",
+				"react-x/dom-no-render-return-value": "error",
+				"react-x/dom-no-render": "error",
+				"react-x/dom-no-script-url": "warn",
+				"react-x/dom-no-unsafe-iframe-sandbox": "warn",
+				"react-x/dom-no-use-form-state": "error",
+				"react-x/dom-no-void-elements-with-children": "error",
+				"react-x/jsx-no-children-prop-with-children": "error",
+				"react-x/jsx-no-children-prop": "warn",
+				"react-x/jsx-no-key-after-spread": "error",
+				"react-x/jsx-no-leaked-dollar": "error",
+				"react-x/jsx-no-leaked-semicolon": "warn",
+				"react-x/jsx-no-namespace": "error",
+				"react-x/naming-convention-context-name": "warn",
+				"react-x/naming-convention-id-name": "warn",
+				"react-x/naming-convention-ref-name": "warn",
+				"react-x/no-access-state-in-setstate": "error",
+				"react-x/no-children-count": "warn",
+				"react-x/no-children-for-each": "warn",
+				"react-x/no-children-map": "warn",
+				"react-x/no-children-only": "warn",
+				"react-x/no-children-to-array": "warn",
+				"react-x/no-component-will-mount": "error",
+				"react-x/no-component-will-receive-props": "error",
+				"react-x/no-component-will-update": "error",
+				"react-x/no-context-provider": "warn",
+				"react-x/no-create-ref": "error",
+				"react-x/no-forward-ref": "warn",
+				"react-x/no-missing-key": "error",
+				"react-x/no-nested-component-definitions": "error",
+				"react-x/no-nested-lazy-component-declarations": "error",
+				"react-x/no-set-state-in-component-did-mount": "warn",
+				"react-x/no-set-state-in-component-did-update": "warn",
+				"react-x/no-set-state-in-component-will-update": "warn",
+				"react-x/no-unnecessary-use-prefix": "warn",
+				"react-x/no-unsafe-component-will-mount": "warn",
+				"react-x/no-unsafe-component-will-receive-props": "warn",
+				"react-x/no-unsafe-component-will-update": "warn",
+				"react-x/no-unused-class-component-members": "warn",
+				"react-x/no-use-context": "warn",
+				"react-x/rsc-function-definition": "error",
+				"react-x/use-state": "warn",
+				"react-x/web-api-no-leaked-event-listener": "warn",
+				"react-x/web-api-no-leaked-fetch": "error",
+				"react-x/web-api-no-leaked-intersection-observer": "warn",
+				"react-x/web-api-no-leaked-interval": "warn",
+				"react-x/web-api-no-leaked-resize-observer": "warn",
+				"react-x/web-api-no-leaked-timeout": "warn"
+			},
+			"jsPlugins": [
+				{
+					"name": "react-x",
+					"specifier": "./node_modules/@eslint-react/eslint-plugin/dist/index.js"
+				}
+			],
+			"plugins": ["react"]
+		},
 		{
 			"files": ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
 			"plugins": ["typescript", "import"],
@@ -166,11 +247,7 @@
 			}
 		},
 		{
-			"files": [
-				"esbuild.mjs",
-				"scripts/*.mjs",
-				".storybook/themes/*.{mjs,cjs}"
-			],
+			"files": ["scripts/*.mjs", ".storybook/themes/*.{mjs,cjs}"],
 			"env": {
 				"node": true
 			}
@@ -268,7 +345,7 @@
 			}
 		},
 		{
-			"files": ["src/core/contextManager.ts", "src/core/commandManager.ts"],
+			"files": ["src/vscode/contextManager.ts", "src/vscode/commandManager.ts"],
 			"rules": {
 				"eslint-js/no-restricted-syntax": "off"
 			}

.oxlintrc.react.jsonc

@@ -6,7 +6,8 @@
 			"type": "extensionHost",
 			"request": "launch",
 			"args": ["--extensionDevelopmentPath=${workspaceFolder}"],
-			"outFiles": ["${workspaceFolder}/dist/**/*.js"]
+			"outFiles": ["${workspaceFolder}/dist/**/*.js"],
+			"preLaunchTask": "build"
 		}
 	]
 }

.prettierignore

@@ -2,11 +2,11 @@
 	"version": "2.0.0",
 	"tasks": [
 		{
-			"type": "typescript",
-			"tsconfig": "tsconfig.json",
-			"problemMatcher": ["$tsc"],
-			"group": "build",
-			"label": "tsc: build"
+			"label": "build",
+			"type": "npm",
+			"script": "build",
+			"group": { "kind": "build", "isDefault": true },
+			"problemMatcher": []
 		}
 	]
 }