feat(config): Add opencode-config utility package #23

thoroc · 2026-01-31T23:05:49Z

Summary

Configuration utilities extracted from warcraft plugin. Provides standardized config loading and path resolution.

Changes

Configuration utilities extracted from warcraft plugin
Standardized config loading and path resolution
Package metadata utilities
Full test coverage for loader, package, and paths modules

Dependencies

Requires: PR feat(infra): Add Biome linting/formatting infrastructure #21 (Biome infrastructure)
Requires: PR feat(notification): Add opencode-notification utility package #22 (opencode-notification)

Blocks

PR feat(agent-loader): Update agent loader plugin with improvements #28 (warcraft refactor)

Testing

Tests pass: bunx nx test opencode-config
Build succeeds: bunx nx build opencode-config
Type-check passes: bunx nx type-check opencode-config

github-actions · 2026-01-31T23:05:58Z

⚠️ Large PR Warning

This PR is quite large with:

13 changed files
1173 added lines
0 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

Remove all packages and dev tools that belong in other PRs: - packages/* (moved to PR #22, #23, #24, etc.) - tools/dev/* (moved to PR #5) - tools/executors/dev-proxy/* (moved to PR #5) - tools/executors/check-mirror-exists/* (moved to PR #5) - tools/executors/validate-skill-md/* (moved to PR #5) - tools/executors/validate-skills/* (moved to PR #5) Keep only Biome infrastructure: - biome.json, lefthook.yml, nx.json, package.json - .github/workflows/validate-pr.yml - libs/workflows/project.json - tools/executors/typecheck/ - tools/executors/validate-tsdoc/ - tools/generators/* (templates with Biome config)

* feat(infra): add Biome linting/formatting infrastructure - Add Biome v2.3.13 configuration with custom rules - Configure lint, format, and format:check targets in nx.json - Add validate-tsdoc executor for documentation validation - Update lefthook.yml with Biome pre-commit hooks - Update validate-pr.yml workflow for Biome - Update generators to include Biome configuration This PR establishes the foundation for Biome-based linting and formatting that all subsequent PRs will use. * fix: resolve CI failures on Biome infrastructure PR - Remove opencode-font override from biome.json to enable linting/formatting - Fix ASCIISiteTitle variable name typo (_siteTitle -> siteTitle) - Fix non-null assertion in load-all-agent-specs.ts using type guard pattern All checks now pass: - Biome linting ✓ - Biome formatting ✓ - docs-builder build ✓ * fix(agent-loader): fix type predicate in load-all-agent-specs.ts Use proper type predicate pattern instead of type assertion for filtering successful agent spec loads. Fixes CI typecheck failure. * fix: resolve remaining CI failures on PR #21 - Fix type predicate in load-all-agent-specs.ts using proper pattern - Fix 2 lint errors in validate-docs-links.ts (noImplicitAnyLet, useIterableCallbackReturn) - Add missing imports to Header.astro (ASCIISiteTitle, SocialIcons, Search, ThemeSelect) Typecheck and lint now pass locally. * style: apply Biome formatting to fix CI errors Apply Biome formatting to 4 package.json files: - packages/opencode-agent-loader-plugin/package.json - packages/opencode-agent-loader-plugin/tsconfig.test.json - packages/opencode-font/package.json - packages/opencode-warcraft-notifications-plugin/package.json Fixes format CI failures on PR #21. * fix(agent-loader): use type assertion instead of type predicate Replace type predicate with type assertion to satisfy stricter CI checks. The filter returns items with defined spec, then we safely assert the type. Fixes typecheck failures on PR #21. * refactor: cleanup PR #21 to only include infrastructure Remove all package changes from this PR - they belong in separate PRs: - packages/opencode-agent-loader-plugin/ → PR #28 - packages/opencode-font/ → PR #24 - packages/opencode-warcraft-notifications-plugin/ → PR #29 PR #21 now contains ONLY Biome infrastructure: - biome.json configuration - lefthook.yml git hooks - nx.json targets for lint/format - Root package.json scripts - CI workflow (validate-pr.yml) - Infrastructure executors (typecheck, validate-tsdoc) - Generator templates with Biome config Apply Biome formatting to biome.json (trailing newline). * fix(biome): add overrides for test/template files to fix lint errors Add Biome linter overrides to allow patterns in test/template files: - Disable noBannedTypes for tools/executors/**/*.test.ts (Function type) - Disable noNamespace for executors and templates - Disable noExplicitAny for generator templates Fixes CI lint failures: - 'Don't use Function as a type' errors - 'TypeScript namespaces are outdated' errors - 'Unexpected any' warnings in templates Also fixes dev-proxy test type assertions. * fix(biome): add file ignores for packages not in this PR Add file ignores to biome.json for packages and tools that belong in other PRs: - packages/opencode-agent-loader-plugin/* - packages/opencode-font/* - packages/opencode-warcraft-notifications-plugin/* - tools/dev/* - tools/executors/dev-proxy/* - tools/executors/check-mirror-exists/* - tools/executors/validate-skill-md/* - tools/executors/validate-skills/* This allows the infrastructure PR to pass CI without linting files that will be properly formatted and fixed in their respective PRs. Also apply Biome formatting to biome.json (trailing newline). * fix(biome): add file ignores and template overrides to fix CI - Add files.includes to ignore packages not in this PR: - packages/opencode-agent-loader-plugin - packages/opencode-font - packages/opencode-warcraft-notifications-plugin - Add linter override for generator template files to disable noExplicitAny - Apply Biome formatting to biome.json Fixes CI lint and format errors. * fix(biome): simplify biome.json configuration to fix CI Remove all package file ignores and use a clean, minimal biome.json that only ignores standard directories (dist, node_modules). This ensures the infrastructure PR can pass CI without trying to lint files that belong in other PRs. All local checks pass: - bun run format:check ✓ - bun run lint ✓ * refactor: clean PR #21 to only include infrastructure Remove all packages and dev tools that belong in other PRs: - packages/* (moved to PR #22, #23, #24, etc.) - tools/dev/* (moved to PR #5) - tools/executors/dev-proxy/* (moved to PR #5) - tools/executors/check-mirror-exists/* (moved to PR #5) - tools/executors/validate-skill-md/* (moved to PR #5) - tools/executors/validate-skills/* (moved to PR #5) Keep only Biome infrastructure: - biome.json, lefthook.yml, nx.json, package.json - .github/workflows/validate-pr.yml - libs/workflows/project.json - tools/executors/typecheck/ - tools/executors/validate-tsdoc/ - tools/generators/* (templates with Biome config) * fix: resolve Biome linting and formatting issues for CI - Updated opencode-font package.json to skip Biome (disabled in root config) - Fixed type predicate for AgentSpecLoadResult to remove non-null assertion - Applied Biome formatting to all JSON files - All checks now pass: lint, format, type-check * fix: add verbose flag to Biome CI command for detailed output * fix(biome): add diagnostic level flag to Biome CI command for improved error reporting * fix: add output-style flag to various nx affected commands for consistent output * docs: add Biome diagnostics reference to skill documentation - Add https://biomejs.dev/reference/diagnostics/ to Getting More Help section * fix(biome): add BIOME_CONFIG_PATH environment variable for Biome CI * fix: update globals.d.ts to ignore linting for noNamespace rule * docs: add debugging guidance for CI failures in Biome skill documentation

- Configuration utilities extracted from warcraft plugin - Standardized config loading and path resolution - Package metadata utilities - Depends on: opencode-notification (PR2) - Required by: opencode-warcraft-notifications-plugin (PR9) Provides foundation for plugin configuration management.

github-actions · 2026-02-01T21:39:15Z

⚠️ Large PR Warning

This PR is quite large with:

13 changed files
1173 added lines
0 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-01T21:40:04Z

⚠️ Large PR Warning

This PR is quite large with:

14 changed files
1253 added lines
0 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-01T21:41:35Z

⚠️ Large PR Warning

This PR is quite large with:

14 changed files
1246 added lines
0 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-01T21:46:05Z

⚠️ Large PR Warning

This PR is quite large with:

15 changed files
1248 added lines
1 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

github-actions · 2026-02-01T21:48:16Z

⚠️ Large PR Warning

This PR is quite large with:

16 changed files
1254 added lines
1 deleted lines

Consider breaking it down into smaller, focused PRs for easier review.

Copilot

Pull request overview

This PR adds a new utility package @pantheon-org/opencode-config that provides standardized configuration loading, path resolution, and package metadata utilities for OpenCode plugins. The functionality has been extracted from the warcraft plugin to be reusable across the plugin ecosystem.

Changes:

New configuration loading utilities with validation support
Platform-specific path resolution (config, data, and plugin storage directories)
Package name detection from package.json
Comprehensive test coverage for all modules

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`tsconfig.base.json`	Added path mapping for the new package
`packages/opencode-config/package.json`	Package metadata, scripts, and dependencies
`packages/opencode-config/project.json`	Nx project configuration with build and lint targets
`packages/opencode-config/tsconfig.json`	TypeScript configuration for the package
`packages/opencode-config/src/types.ts`	Type definitions for plugin configurations
`packages/opencode-config/src/paths.ts`	Platform-specific path utilities
`packages/opencode-config/src/package.ts`	Package name detection utilities
`packages/opencode-config/src/loader.ts`	Configuration loading with validation
`packages/opencode-config/src/index.ts`	Public API exports
`packages/opencode-config/src/*.test.ts`	Test files for all modules
`packages/opencode-config/README.md`	Documentation and usage examples
`nx.json`	Added `dependsOn: ["^build"]` to type-check target
`bun.lock`	Dependency lock file updates

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-01T21:54:42Z

packages/opencode-config/src/index.ts

+// Export path utilities
+export { getConfigDir, getConfigPaths, getDataDir, getPluginStorageDir } from './paths.js';
+// Export types
+export type { PluginConfig, PluginSpecificConfig } from './types.js';


The Logger type from '@pantheon-org/opencode-notification' is used in the public API (LoadConfigOptions interface and getPackageName function) but is not re-exported from this package. Users who want to provide a logger parameter will need to import the Logger type directly from '@pantheon-org/opencode-notification', which creates an indirect dependency. Consider re-exporting the Logger type for better developer experience.

Suggested change

export type { PluginConfig, PluginSpecificConfig } from './types.js';

export type { PluginConfig, PluginSpecificConfig } from './types.js';

export type { Logger } from '@pantheon-org/opencode-notification';

Copilot · 2026-02-01T21:54:42Z

packages/opencode-config/README.md

+  configFileName?: string;
+  validator?: (config: unknown) => T;
+  defaultConfig?: T;
+  debug?: boolean;


The LoadConfigOptions interface documentation in the README is missing the 'logger' parameter that is present in the actual TypeScript interface. The code defines this parameter at line 22 of loader.ts but it's not documented in the README's API section.

Suggested change

debug?: boolean;

debug?: boolean;

logger?: unknown;

Copilot · 2026-02-01T21:54:42Z

packages/opencode-config/README.md

+
+Get configuration file search paths in priority order.
+
+### `getPackageName(debug?: boolean): string | null`


The getPackageName function signature in the README is missing the 'logger' parameter. The actual function signature at line 60 of package.ts accepts both 'debug' and 'logger' parameters, but the README only documents the 'debug' parameter.

Suggested change

### `getPackageName(debug?: boolean): string | null`

### `getPackageName(debug?: boolean, logger?: (...args: unknown[]) => void): string | null`

Copilot · 2026-02-01T21:54:42Z

packages/opencode-config/src/loader.ts

+  const configFile = Bun.file(configPath);
+  const configData: PluginConfig = await configFile.json();


The code uses Bun.file() API which creates a hard dependency on the Bun runtime. However, the package.json specifies Node.js engines (>=18.0.0) and doesn't specify Bun as a requirement. This creates a discrepancy between the stated runtime support and the actual implementation. Consider using Node.js-compatible file reading APIs (like fs.readFile) or documenting that Bun is required.

Copilot · 2026-02-01T21:54:43Z

packages/opencode-config/package.json

+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist --clean",
+    "dev": "tsup src/index.ts --format esm --dts --out-dir dist --watch",
+    "type-check": "tsc --noEmit"


The package.json is missing a 'test' script, even though the PR description mentions testing with 'bunx nx test opencode-config' and there are test files in the src directory (paths.test.ts, package.test.ts, loader.test.ts). The scripts section should include a test command for consistency with other packages in the monorepo.

Suggested change

"type-check": "tsc --noEmit"

"type-check": "tsc --noEmit",

"test": "bunx nx test opencode-config"

Copilot · 2026-02-01T21:54:43Z

packages/opencode-config/project.json

+  "targets": {
+    "build": {
+      "executor": "nx:run-commands",
+      "outputs": ["{projectRoot}/dist"],
+      "options": {
+        "command": "bun run build",
+        "cwd": "packages/opencode-config"
+      }
+    },
+    "lint": {
+      "executor": "nx:run-commands",
+      "options": {
+        "command": "biome check --write .",
+        "cwd": "packages/opencode-config"
+      },
+      "cache": true,
+      "inputs": ["default", "{workspaceRoot}/biome.json", "{projectRoot}/biome.json"]
+    }
+  },


The project.json is missing a 'test' target configuration. The PR description mentions running tests with 'bunx nx test opencode-config', but there is no test target defined. This should be added for consistency with the PR's testing checklist and to enable running tests through nx.

Copilot · 2026-02-01T21:54:43Z

packages/opencode-config/src/paths.ts

+ * @param pluginName - The name of the plugin (e.g., '\@pantheon-org/my-plugin')
+ * @param subdirectory - Optional subdirectory within the plugin storage
+ * @returns The plugin storage directory path
+ *
+ * @example
+ * ```typescript
+ * const storageDir = getPluginStorageDir('\@pantheon-org/my-plugin');
+ * // macOS/Linux: ~/.local/share/opencode/storage/plugin/\@pantheon-org/my-plugin
+ * // Windows: %APPDATA%\opencode\storage\plugin\@pantheon-org\my-plugin


The JSDoc examples have inconsistent escaping of the '@' symbol in scoped package names. At line 51, 57, and 64, the '@' is escaped as '@', but at line 59 in the Windows example comment, it's not escaped. For consistency and clarity, the '@' symbol in JSDoc comments should be escaped as '@' when it's part of a package name (not a JSDoc tag), or consistently not escaped if within code blocks.

thoroc mentioned this pull request Jan 31, 2026

feat(skills): Add opencode-skills package with BM25 ranking #24

Merged

3 tasks

This was referenced Jan 31, 2026

feat(warcraft): Refactor plugin to use new packages #29

Open

feat(infra): Add Biome linting/formatting infrastructure #21

Merged

thoroc force-pushed the feat/pr3-config-package branch from 31c24f3 to cf1e30d Compare February 1, 2026 21:39

chore: update lock file for opencode-config dependencies

eac9ce0

fix: remove non-existent validate:tsdoc target from config project.json

f7d9465

fix: add build dependency to type-check target

a9aefce

fix: add missing tsconfig paths for new packages

d6803a5

thoroc requested a review from Copilot February 1, 2026 21:49

Copilot started reviewing on behalf of thoroc February 1, 2026 21:49 View session

thoroc merged commit 2ada394 into main Feb 1, 2026
9 checks passed

thoroc deleted the feat/pr3-config-package branch February 1, 2026 21:50

Copilot AI reviewed Feb 1, 2026

View reviewed changes

	export type { PluginConfig, PluginSpecificConfig } from './types.js';
	export type { PluginConfig, PluginSpecificConfig } from './types.js';
	export type { Logger } from '@pantheon-org/opencode-notification';


		Get configuration file search paths in priority order.

		### `getPackageName(debug?: boolean): string \| null`

	### `getPackageName(debug?: boolean): string \| null`
	### `getPackageName(debug?: boolean, logger?: (...args: unknown[]) => void): string \| null`

		const configFile = Bun.file(configPath);
		const configData: PluginConfig = await configFile.json();

	"type-check": "tsc --noEmit"
	"type-check": "tsc --noEmit",
	"test": "bunx nx test opencode-config"

feat(config): Add opencode-config utility package #23

feat(config): Add opencode-config utility package #23

Uh oh!

Conversation

thoroc commented Jan 31, 2026

Summary

Changes

Dependencies

Blocks

Testing

Uh oh!

github-actions bot commented Jan 31, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

github-actions bot commented Feb 1, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Feb 1, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants