feat(config): load repo defaults from .ghaurc / ghau.config.* / package.json ghau key

[ylabonte]

Summary

First half of the v1.1.0 plan: implement the config-file feature that docs/guide/config-file.md has been documenting since the initial release. The docs (and the cosmiconfig + zod deps in package.json) were aspirational — no source file backed them. This PR writes the loader, wires it into the CLI, and reconciles the docs with what actually ships.

Effective options now resolve as CLI flag → config file → built-in default. Tokens are deliberately not loadable from config — they belong in env vars or gh auth token.

What's new (user-visible)

Drop a data-only config file at the repo root and ghau picks it up. Supported filenames: .ghaurc, .ghaurc.json, .ghaurc.yaml, .ghaurc.yml, ghau.config.json, or a ghau key in package.json.

{
  "target": "minor",
  "rejects": ["docker://**"],
  "failOnOutdated": true
}

Schema (strictly validated by zod; unknown keys rejected):

interface GhauConfig {
  target?: 'latest' | 'major' | 'minor' | 'patch' | 'greatest';
  filters?: string[];
  rejects?: string[];
  workflowsDir?: string;
  allowBranchPin?: boolean;
  failOnOutdated?: boolean;
}

A relative workflowsDir is resolved against the config file's directory, so a repo-level .ghaurc.json keeps pointing at <repo-root>/.github/workflows regardless of which subdirectory you invoke ghau from.

Data-only by design

Executable config formats (.js, .cjs, .mjs, .ts) are intentionally not supported. Allowing them would let ghau execute repository-controlled JavaScript during config discovery — and in the composite Action path, GITHUB_TOKEN is already in process.env by the time the CLI starts, so a checked-in ghau.config.mjs from an attacker-controlled PR could read or exfiltrate it even though token is not part of the config schema. Keeping the config surface data-only eliminates that vector. See docs/guide/config-file.md for the full security rationale.

Files

• New: src/core/config.ts (cosmiconfig + zod loader), tests/unit/core/config.test.ts (18 tests), tests/unit/cli.test.ts (22 tests for mergeOptions + isInvokedDirectly), .changeset/feat-config-file.md (minor bump).
• Modified: src/cli.ts (load + merge + isInvokedDirectly fix for symlinked invocations), src/index.ts (re-exports), tests/integration/cli.test.ts (+5 e2e cases), docs/guide/config-file.md (reconciled with implementation + security callout), docs/guide/quickstart.md (Repo-level defaults section), docs/guide/use-as-action.md (target-precedence + changes-output limitation callout), docs/reference/cli.md + README.md (exit-code table extended), plus CLAUDE.md + .github/copilot-instructions.md (meta-lesson on bidirectional doc drift), and action.yml (target default + npx form fix + isInvokedDirectly-related selftest implications).

Test plan

• CI green on this PR (216 tests, four gates).
• Manually: drop a .ghaurc.json in a fresh checkout and confirm pnpm dev -- --verbose --json logs the config path on stderr.
• Manually: drop a malformed config and confirm exit 2 with the error message.
• Self-check workflow: known-red until 1.1.0 publishes (root cause: the published 1.0.0 has a separate `invokedDirectly` bug fixed in this PR; the Action wrapper pulls 1.0.0 from npm). Heals on the next push after 1.1.0 publishes.

[Copilot]

Pull request overview

This PR implements repository config-file support for ghau, wiring a new cosmiconfig/zod loader into the CLI so config defaults can sit between explicit flags and built-in defaults.

Changes:

• Adds src/core/config.ts with schema validation, config discovery, and defineConfig.
• Merges loaded config into CLI options and re-exports config APIs.
• Updates tests, docs, and changeset entries for the new configuration feature.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/core/config.ts	Adds config schema, loader, and TypeScript helper.
src/cli.ts	Loads config and merges it with CLI options.
src/index.ts	Re-exports config APIs and types.
tests/unit/core/config.test.ts	Adds unit coverage for config loading and validation.
tests/integration/cli.test.ts	Adds CLI-level config behavior tests.
README.md	Documents repo-level configuration.
docs/guide/quickstart.md	Adds a quickstart section for config defaults.
docs/guide/config-file.md	Reconciles the full config-file guide with implemented behavior.
CLAUDE.md	Adds guidance about bidirectional doc drift.
.github/copilot-instructions.md	Mirrors the doc-drift guidance.
.changeset/feat-config-file.md	Adds a minor-version changeset for config-file support.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 11 comments.

Comments suppressed due to low confidence (1)

src/core/config.ts:94

• This doc comment still tells users to author ghau.config.ts, but .ts configs were removed from the supported search places above. That makes the public helper documentation contradict the loader; update the example text to the supported typed path (for example ghau.config.mjs with JS type checking) so generated declarations do not advertise an unsupported config file.

/**
 * Identity helper for TS users authoring `ghau.config.ts` with type-safety:
 *
 * ```ts
 * import { defineConfig } from 'github-actions-updater';

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

action.yml:126

• This comment also overstates the supported config names with ghau.config.*; only ghau.config.json is discovered. Keeping the Action script comments precise matters here because executable config formats were intentionally excluded for security reasons.

        # `--target` is conditional so a `target` value in the user's repo config
        # (`.ghaurc` / `ghau.config.*`) is not masked by the Action's pass-through.
        # When the input is empty, we let the CLI fall back to its own default or

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (2)

src/core/config.ts:151

• The escaping-path error mixes normalized paths with the raw workflowsDir value. A Windows-style config value such as ..\escape would be shown with backslashes, unlike the rest of the user-facing path output in this loader and the project convention established by src/utils/paths.ts:3-6; normalize the displayed value here as well.

        `Invalid ghau config in ${toPosixPath(result.filepath)}:\n` +
          `  workflowsDir: '${config.workflowsDir}' resolves outside the config file's directory ` +
          `(${toPosixPath(resolved)}). Repo configs may only point at directories inside the repo.`,

src/core/config.ts:154

• This containment check is purely lexical, so a repo-controlled config can still point workflowsDir at an in-repo symlink whose target is outside the repo/config directory. scanWorkflows uses readdir/stat, which follow directory symlinks, and --write would then operate on files outside the intended tree. Resolve and validate the real path of the configured directory (and the config directory) before accepting it, or reject symlinked workflow directories for config-provided paths.

    const resolved = path.resolve(configDir, config.workflowsDir);
    const relative = path.relative(configDir, resolved);
    if (relative === '..' || relative.startsWith('..' + path.sep)) {
      throw new Error(
        `Invalid ghau config in ${toPosixPath(result.filepath)}:\n` +
          `  workflowsDir: '${config.workflowsDir}' resolves outside the config file's directory ` +
          `(${toPosixPath(resolved)}). Repo configs may only point at directories inside the repo.`,
      );
    }
    config.workflowsDir = resolved;

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (1)

src/core/config.ts:161

• This still won't POSIX-normalize Windows-style input when running on POSIX: toPosixPath() only replaces the current platform separator (src/utils/paths.ts:11-14), and this branch deliberately rejects drive-qualified values on every platform. A config value like C:\wf will therefore be reported with backslashes in Linux/macOS output; normalize backslashes in the user-supplied value explicitly before interpolating it.

        `Invalid ghau config in ${toPosixPath(result.filepath)}:\n` +
          `  workflowsDir: must be a path relative to the config file's directory; ` +
          `got '${toPosixPath(config.workflowsDir)}'. ` +
          `Use the --workflows CLI flag if you really need to point at an absolute path.`,

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 19 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 19 out of 20 changed files in this pull request and generated no new comments.