Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions memory-bank/aiConfig.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
36 changes: 35 additions & 1 deletion packages/ai-config/src/__tests__/load-config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand Down Expand Up @@ -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.
Expand Down
32 changes: 32 additions & 0 deletions packages/ai-config/src/__tests__/mutate-config.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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: {} } });
Expand Down
24 changes: 17 additions & 7 deletions packages/ai-config/src/node/mutate-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -79,7 +79,8 @@ function enqueue<T>(configPath: string, fn: () => Promise<T>): Promise<T> {
* @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<ProvidersConfig>,
Expand Down Expand Up @@ -233,17 +234,21 @@ 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);

// If we just created the file, inject seed metadata ($schema, version)
// 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 };
}

Expand All @@ -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");
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -346,7 +352,11 @@ async function atomicWrite(configPath: string, text: string): Promise<void> {
* 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
Expand Down
26 changes: 22 additions & 4 deletions packages/ai-config/src/node/parse-providers-config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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));
}
Loading