diff --git a/memory-bank/aiConfig.md b/memory-bank/aiConfig.md index 9ba5fd2..c0dd00b 100644 --- a/memory-bank/aiConfig.md +++ b/memory-bank/aiConfig.md @@ -345,9 +345,10 @@ from severity, scope, path and source). It is read-only and silent, and shares t - **Read state.** Each reader's report carries a `layer` (`ProviderConfigLayer`, the ref plus its source `kind`). The user file is `missing` (ENOENT), `invalid` (unreadable, bad JSONC, or a - whole-file salvage failure; a zero-byte file is invalid, as its issue says), `empty` (sets no - `providers`/`agentEngines` key) or `found`; env payloads and legacy layers are `not set` when - absent. + whole-file salvage failure; a comment-only file is invalid), `empty` (sets no + `providers`/`agentEngines` key, or is blank: zero bytes or whitespace only, with no issue) or + `found`; env payloads and legacy layers are `not set` when absent. `parseProvidersConfig` and + `parseProvidersConfigTolerant` own the blank rule, so every reader and the mutation path agree. - **No second copy of precedence.** `resolveProviderCatalogReport` and the explainer both run `foldProviderCatalog` (rank, recover, enablement layers, `agentEngines` fold). The explainer replays the same merge step (`foldConfigLayers`, also used by `mergeAndValidate` and the @@ -558,7 +559,11 @@ without managing locking, atomicity, or watch lifecycle themselves. a `proper-lockfile` lock (with retries and stale detection), an in-process serialization queue per config path, race-safe first-creation via the exclusive `wx` flag, atomic write (temp file + rename), and seed-metadata - injection (`$schema`, `version`) on first creation. `$schema` is seeded with + injection (`$schema`, `version`) on first creation. Creation opens the file + and writes the seed before the lock, so the file can be blank in between (or + for good, if the writer stops there); a mutation that finds it blank seeds it + as if it had created it, writes through `atomicWrite`, and returns `true`. + `$schema` is seeded with `PROVIDERS_SCHEMA_URL` (`node/paths.ts`), the hosted `providers.schema.json` at `assistant.posit.co/schemas/providers.schema.json` — editors resolve and cache that URL natively, so no local sidecar file or diff --git a/packages/ai-config/src/__tests__/load-config.test.ts b/packages/ai-config/src/__tests__/load-config.test.ts index adf3108..f5ff79b 100644 --- a/packages/ai-config/src/__tests__/load-config.test.ts +++ b/packages/ai-config/src/__tests__/load-config.test.ts @@ -9,7 +9,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { createConfigFileFixture } from "../../tests/helpers/config-file-fixture.js"; import type { ConfigFileFixture } from "../../tests/helpers/config-file-fixture.js"; import { loadProviderCatalogReport, loadResolvedProviderCatalog } from "../node/load-catalog.js"; -import { readEnvFragment } from "../node/load-config.js"; +import { readEnvFragment, readFileConfig } from "../node/load-config.js"; import type { ResolvedProvider } from "../types.js"; import { BUILTIN_PROVIDER_IDS } from "../vocabulary.js"; @@ -1078,6 +1078,40 @@ describe("loadResolvedProviderCatalog", () => { // ======================================================================== describe("whole-source failures", () => { + it("reads a blank file as empty, without an issue", async () => { + await fixture.writeRawJsonc(" \n"); + + const report = await loadProviderCatalogReport({ + envVars: process.env, + configPath, + logger: mockLogger, + }); + const file = await readFileConfig(configPath); + + expect(report.issues).toEqual([]); + expect(mockLogger.warn).not.toHaveBeenCalled(); + expect(file.layer.state).toBe("empty"); + expect(file.source?.config).toEqual({}); + }); + + it("reads a comment-only file as invalid", async () => { + await fixture.writeRawJsonc("// nothing\n"); + + const report = await loadProviderCatalogReport({ + envVars: process.env, + configPath, + }); + const file = await readFileConfig(configPath); + + expect(report.issues).toEqual([ + expect.objectContaining({ + severity: "error", + message: expect.stringContaining("Invalid JSONC"), + }), + ]); + expect(file.layer.state).toBe("invalid"); + }); + it("reports a syntax error as an error-severity issue with line and column", async () => { // Missing comma after the `providers` block: the parser reports // CommaExpected at the `"version"` token on line 3. diff --git a/packages/ai-config/src/__tests__/mutate-config.test.ts b/packages/ai-config/src/__tests__/mutate-config.test.ts index 4ff0512..c751e44 100644 --- a/packages/ai-config/src/__tests__/mutate-config.test.ts +++ b/packages/ai-config/src/__tests__/mutate-config.test.ts @@ -480,6 +480,38 @@ describe("mutateProvidersConfig first creation and seed boundaries", () => { expect(content.version).toBe(PROVIDERS_CONFIG_VERSION); }); + it.each([ + ["an empty", ""], + ["a whitespace-only", " \n"], + ])("seeds %s file left by an interrupted creation", async (_, blank) => { + await fixture.writeRawJsonc(blank); + + const wrote = await mutateProvidersConfig( + (current) => ({ ...current, providers: { anthropic: { enabled: true } } }), + { configPath, logger: mockLogger }, + ); + + expect(wrote).toBe(true); + const content = JSON.parse(await fixture.readRaw()); + expect(content.providers?.anthropic?.enabled).toBe(true); + expect(content.$schema).toBe(PROVIDERS_SCHEMA_URL); + expect(content.version).toBe(PROVIDERS_CONFIG_VERSION); + }); + + it("repairs a blank file when the mutation changes nothing", async () => { + await fixture.writeRawJsonc(""); + + const wrote = await mutateProvidersConfig((current) => current, { + configPath, + logger: mockLogger, + }); + + expect(wrote).toBe(true); + const content = JSON.parse(await fixture.readRaw()); + expect(content.$schema).toBe(PROVIDERS_SCHEMA_URL); + expect(content.version).toBe(PROVIDERS_CONFIG_VERSION); + }); + it("does NOT re-inject $schema/version when a user removes them", async () => { // Create an initial file without $schema or version await fixture.writeTypedConfig({ diff --git a/packages/ai-config/src/__tests__/read-user-custom-provider-entries.test.ts b/packages/ai-config/src/__tests__/read-user-custom-provider-entries.test.ts index 6c3aec4..5a60498 100644 --- a/packages/ai-config/src/__tests__/read-user-custom-provider-entries.test.ts +++ b/packages/ai-config/src/__tests__/read-user-custom-provider-entries.test.ts @@ -58,6 +58,15 @@ describe("readUserCustomProviderEntries", () => { ).resolves.toEqual(new Map()); }); + it("returns an empty map when providers.json is blank", async () => { + const fixture = await configFixture(); + await fixture.writeRawJsonc(""); + + await expect( + readUserCustomProviderEntries({ configPath: fixture.configPath }), + ).resolves.toEqual(new Map()); + }); + it("returns an empty map for an empty custom map", async () => { const fixture = await configFixture(); await fixture.writeTypedConfig({ version: 1, providers: { custom: {} } }); diff --git a/packages/ai-config/src/node/mutate-config.ts b/packages/ai-config/src/node/mutate-config.ts index f511585..d1f10fc 100644 --- a/packages/ai-config/src/node/mutate-config.ts +++ b/packages/ai-config/src/node/mutate-config.ts @@ -25,7 +25,7 @@ import { isPlainObject } from "../is-plain-object.js"; import { providersConfigSchema } from "../schema.js"; import type { ProvidersConfig } from "../types.js"; import { parseJsonc } from "./parse-jsonc.js"; -import { parseProvidersConfig } from "./parse-providers-config.js"; +import { isBlankConfigText, parseProvidersConfig } from "./parse-providers-config.js"; import { LEGACY_PROVIDERS_SCHEMA_PATH, PROVIDERS_CONFIG_PATH, @@ -79,7 +79,8 @@ function enqueue(configPath: string, fn: () => Promise): Promise { * @param opts - Optional path override and logger. * @returns `true` if the mutation wrote new content to the file, `false` if * the result was unchanged and nothing was written. (Creating a missing file - * whose only content is the seed metadata reports `false`.) + * whose only content is the seed metadata reports `false`. Repairing a blank + * file reports `true`.) */ export async function mutateProvidersConfig( mutator: (current: ProvidersConfig) => ProvidersConfig | Promise, @@ -233,6 +234,10 @@ async function performLockedMutation( // Re-read current state under lock const { raw, config: current } = await readCurrentConfig(configPath); + // A blank file is one whose creation was interrupted before its seed + // was written: seed it now, as if this call had created it. + const seeding = fileCreated || isBlankConfigText(raw); + // Apply mutation let updated = await mutator(current); @@ -240,10 +245,10 @@ async function performLockedMutation( // into the first mutation result so mutators don't need to preserve them. // This is seed-only — subsequent mutations pass through whatever the // user/mutator wrote. If a user later removes $schema, that's their choice. - if (fileCreated && updated.$schema === undefined) { + if (seeding && updated.$schema === undefined) { updated = { $schema: PROVIDERS_SCHEMA_URL, ...updated }; } - if (fileCreated && updated.version === undefined) { + if (seeding && updated.version === undefined) { updated = { ...updated, version: PROVIDERS_CONFIG_VERSION }; } @@ -264,7 +269,7 @@ async function performLockedMutation( } const normalized = normalizeJsonValue(result.data); - const output = fileCreated ? JSON.stringify(normalized, null, 2) : editJsonc(raw, result.data); + const output = seeding ? JSON.stringify(normalized, null, 2) : editJsonc(raw, result.data); if (output === raw) { logger?.debug("[ai-config] Config mutation made no changes"); @@ -296,7 +301,8 @@ async function performLockedMutation( * after race-safe creation, an unreadable or missing file is anomalous, and * treating invalid content as `{}` would silently discard user configuration. * Invalid content throws {@link ProvidersConfigInvalidError} so hosts can say - * why; read failures throw a plain error. + * why; read failures throw a plain error. A blank file holds no configuration + * to discard, so it reads as `{}`. */ async function readCurrentConfig( configPath: string, @@ -346,7 +352,11 @@ async function atomicWrite(configPath: string, text: string): Promise { * where two concurrent callers both observe ENOENT and then one clobbers the * other's completed write with an empty `{}`. * - * On file creation, seeds the file with `$schema` and `version` fields. + * On file creation, seeds the file with `$schema` and `version` fields. The + * open and the write are separate steps taken before the lock, so other + * processes can see the file blank in between, and a process stopped there + * leaves it blank. Readers report a blank file as empty, and the next + * mutation seeds it. * * @returns `true` if this call created the file (first write), `false` if * it already existed. The caller uses this to inject seed metadata into diff --git a/packages/ai-config/src/node/parse-providers-config.ts b/packages/ai-config/src/node/parse-providers-config.ts index 8fc03d8..13cf599 100644 --- a/packages/ai-config/src/node/parse-providers-config.ts +++ b/packages/ai-config/src/node/parse-providers-config.ts @@ -11,17 +11,35 @@ import type { ProvidersConfig } from "../types.js"; import { parseJsonc } from "./parse-jsonc.js"; /** - * Parse providers.json as JSONC and validate its complete on-disk shape. + * Whether providers.json text is empty or whitespace only. Such a file holds + * no configuration, so it parses as `{}` rather than as invalid JSONC: another + * process sees exactly this while a first mutation is between creating the + * file and seeding it, and a writer stopped there leaves it behind for good. + * A file holding only comments is still invalid, since only a user writes + * comments. + */ +export function isBlankConfigText(text: string): boolean { + return text.trim() === ""; +} + +/** + * Parse providers.json as JSONC and validate its complete on-disk shape. Blank + * text is `{}`. * * Syntax failures propagate as `SyntaxError`; schema failures propagate as a * Zod error. Loaders can therefore report and degrade by failure kind, while * mutations can abort without duplicating either policy. */ export function parseProvidersConfig(text: string): ProvidersConfig { - return providersConfigSchema.parse(parseJsonc(text)); + return isBlankConfigText(text) ? {} : providersConfigSchema.parse(parseJsonc(text)); } -/** Parse JSONC syntax, then salvage independently valid provider blocks. */ +/** + * Parse JSONC syntax, then salvage independently valid provider blocks. Blank + * text is `{}`, with no issues. + */ export function parseProvidersConfigTolerant(text: string): SalvagedProvidersConfig { - return salvageProvidersConfig(parseJsonc(text)); + return isBlankConfigText(text) + ? { config: {}, issues: [] } + : salvageProvidersConfig(parseJsonc(text)); }