argsbarg 5.1.8 → 5.1.10

package/src/config/bindings.test.ts

@@ -0,0 +1,72 @@
+/*
+Tests for config/bindings module.
+*/
+
+import { describe, expect, test } from "bun:test";
+import type { CliAppConfigEntry } from "../types.ts";
+import {
+  bindingForKey,
+  CONFIG_BINDINGS_KEY,
+  clearBinding,
+  clearFileValue,
+  isKeyAddressed,
+  readBindings,
+  setBinding,
+} from "./bindings.ts";
+
+const optionalEntry: CliAppConfigEntry = { description: "Optional.", required: false };
+const requiredEntry: CliAppConfigEntry = { description: "Required.", env: "API_TOKEN" };
+
+describe("config/bindings", () => {
+  test("readBindings returns empty when absent", () => {
+    expect(readBindings({})).toEqual({});
+  });
+
+  test("setBinding and readBindings round-trip", () => {
+    const next = setBinding({}, "apiToken", "env");
+    expect(readBindings(next)).toEqual({ apiToken: "env" });
+    expect(next[CONFIG_BINDINGS_KEY]).toEqual({ apiToken: "env" });
+  });
+
+  test("clearBinding removes entry", () => {
+    const withBinding = setBinding({}, "apiToken", "env");
+    const cleared = clearBinding(withBinding, "apiToken");
+    expect(readBindings(cleared)).toEqual({});
+    expect(CONFIG_BINDINGS_KEY in cleared).toBe(false);
+  });
+
+  test("clearFileValue removes literal", () => {
+    expect(clearFileValue({ apiToken: "x" }, "apiToken")).toEqual({});
+  });
+
+  test("isKeyAddressed with binding env", () => {
+    const data = setBinding({}, "apiToken", "env");
+    expect(isKeyAddressed("apiToken", data, requiredEntry)).toBe(true);
+  });
+
+  test("isKeyAddressed with literal file value", () => {
+    expect(isKeyAddressed("apiToken", { apiToken: "tok" }, requiredEntry)).toBe(true);
+  });
+
+  test("isKeyAddressed false when unaddressed", () => {
+    expect(isKeyAddressed("apiToken", {}, requiredEntry)).toBe(false);
+  });
+
+  test("isKeyAddressed skip binding", () => {
+    const data = setBinding({}, "note", "skip");
+    expect(isKeyAddressed("note", data, optionalEntry)).toBe(true);
+  });
+
+  test("bindingForKey prefers explicit binding", () => {
+    const data = setBinding({}, "apiToken", "env");
+    expect(bindingForKey("apiToken", data, true)).toBe("env");
+  });
+
+  test("bindingForKey infers file from literal", () => {
+    expect(bindingForKey("apiToken", { apiToken: "x" }, true)).toBe("file");
+  });
+
+  test("bindingForKey missing when unset", () => {
+    expect(bindingForKey("apiToken", {}, false)).toBe("missing");
+  });
+});

package/src/config/bindings.ts

@@ -0,0 +1,115 @@
+/*
+Per-key config binding metadata (`_bindings`) — records how each schema key is satisfied.
+*/
+
+import type { CliAppConfigEntry } from "../types.ts";
+
+/** Reserved top-level config file key for per-entry binding metadata. */
+export const CONFIG_BINDINGS_KEY = "_bindings";
+
+export type ConfigBinding = "env" | "file" | "skip";
+
+const BINDING_VALUES = new Set<string>(["env", "file", "skip"]);
+
+/** True for argsbarg-reserved top-level keys (e.g. `_bindings`). */
+export function isFrameworkConfigKey(key: string): boolean {
+  return key.startsWith("_");
+}
+
+function isPresent(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "string" && value.length === 0) return false;
+  return true;
+}
+
+/** Read `_bindings` from raw file data; returns `{}` when absent or invalid. */
+export function readBindings(fileData: Record<string, unknown>): Record<string, ConfigBinding> {
+  const raw = fileData[CONFIG_BINDINGS_KEY];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return {};
+  }
+  const out: Record<string, ConfigBinding> = {};
+  for (const [key, val] of Object.entries(raw)) {
+    if (typeof val === "string" && BINDING_VALUES.has(val)) {
+      out[key] = val as ConfigBinding;
+    }
+  }
+  return out;
+}
+
+/** Validate `_bindings` shape when present. */
+export function validateBindingsShape(fileData: Record<string, unknown>, pathPrefix = "$"): string[] {
+  const raw = fileData[CONFIG_BINDINGS_KEY];
+  if (raw === undefined) return [];
+  const errors: string[] = [];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    errors.push(`${pathPrefix}.${CONFIG_BINDINGS_KEY}: must be object`);
+    return errors;
+  }
+  for (const [key, val] of Object.entries(raw)) {
+    if (typeof val !== "string" || !BINDING_VALUES.has(val)) {
+      errors.push(`${pathPrefix}.${CONFIG_BINDINGS_KEY}.${key}: must be "env", "file", or "skip"`);
+    }
+  }
+  return errors;
+}
+
+/** Return a new file object with an updated binding for `key`. */
+export function setBinding(
+  fileData: Record<string, unknown>,
+  key: string,
+  binding: ConfigBinding,
+): Record<string, unknown> {
+  const bindings = { ...readBindings(fileData), [key]: binding };
+  return { ...fileData, [CONFIG_BINDINGS_KEY]: bindings };
+}
+
+/** Return a new file object without a binding for `key`. */
+export function clearBinding(fileData: Record<string, unknown>, key: string): Record<string, unknown> {
+  const bindings = readBindings(fileData);
+  if (!(key in bindings)) {
+    return fileData;
+  }
+  const nextBindings = { ...bindings };
+  delete nextBindings[key];
+  const next = { ...fileData };
+  if (Object.keys(nextBindings).length === 0) {
+    delete next[CONFIG_BINDINGS_KEY];
+  } else {
+    next[CONFIG_BINDINGS_KEY] = nextBindings;
+  }
+  return next;
+}
+
+/** Remove a literal value from file data (used when binding to env). */
+export function clearFileValue(fileData: Record<string, unknown>, key: string): Record<string, unknown> {
+  if (!(key in fileData)) {
+    return fileData;
+  }
+  const next = { ...fileData };
+  delete next[key];
+  return next;
+}
+
+/** Whether the user already addressed this key (skip wizard re-prompt). */
+export function isKeyAddressed(key: string, fileData: Record<string, unknown>, _entry: CliAppConfigEntry): boolean {
+  const bindings = readBindings(fileData);
+  if (bindings[key] === "skip" || bindings[key] === "env" || bindings[key] === "file") {
+    return true;
+  }
+  return isPresent(fileData[key]);
+}
+
+/** Binding for status display; `missing` when unset. */
+export function bindingForKey(
+  key: string,
+  fileData: Record<string, unknown>,
+  resolvedPresent: boolean,
+): ConfigBinding | "missing" {
+  const bindings = readBindings(fileData);
+  const b = bindings[key];
+  if (b) return b;
+  if (isPresent(fileData[key])) return "file";
+  if (resolvedPresent) return "env";
+  return "missing";
+}

package/src/config/bootstrap.ts

@@ -6,14 +6,10 @@ settings are present before the CLI or MCP server handles a request.
 import { readSync } from "node:fs";
 import { readPromptLine as readStdinLine } from "../prompt.ts";
 import type { CliAppConfigEntry, CliProgram } from "../types.ts";
+import { bindingForKey, clearFileValue, isKeyAddressed, readBindings, setBinding } from "./bindings.ts";
+import { configEntryRequired, configEntrySensitive, defaultConfigEntryTitle, jsonSchemaRequiredKeys } from "./entry.ts";
 import {
-  configEntryRequired,
-  configEntrySensitive,
-  defaultConfigEntryTitle,
-  jsonSchemaRequiredKeys,
-} from "./entry.ts";
-import {
-  appConfigInstalled,
+  appConfigFileExists,
   displayAppConfigPath,
   readAppConfigFile,
   readAppConfigFileRaw,
@@ -53,13 +49,8 @@ export interface ConfigBootstrapResult {
 }
 
 /** Read the config file, merge env overrides, and export mapped values into `process.env`. */
-export function bootstrapAppConfig(
-  program: CliProgram,
-  opts: { validateFile: boolean },
-): ConfigBootstrapResult {
-  const fileData = opts.validateFile
-    ? readAppConfigFile(program)
-    : readAppConfigFileRaw(resolveAppConfigPath(program));
+export function bootstrapAppConfig(program: CliProgram, opts: { validateFile: boolean }): ConfigBootstrapResult {
+  const fileData = opts.validateFile ? readAppConfigFile(program) : readAppConfigFileRaw(resolveAppConfigPath(program));
   const hostEnv = captureMappedHostEnv(program);
   const resolved = resolveAppConfig(program, fileData, hostEnv);
   exportConfigToEnv(program, resolved, hostEnv);
@@ -88,7 +79,6 @@ function readSensitiveLine(): string {
       }
       const byte = buf[0];
       if (byte === 3) {
-        // Raw mode delivers Ctrl+C as ETX instead of SIGINT.
         process.stderr.write("\n");
         process.exit(130);
       }
@@ -130,10 +120,7 @@ function readPromptLine(mask: boolean): string {
 }
 
 /** Whether this setting already has a non-empty value in the user's shell environment. */
-function resolvedFromEnv(
-  entry: CliAppConfigEntry,
-  hostEnv: Record<string, string | undefined>,
-): boolean {
+function resolvedFromEnv(entry: CliAppConfigEntry, hostEnv: Record<string, string | undefined>): boolean {
   if (!entry.env) {
     return false;
   }
@@ -165,7 +152,7 @@ function promptConfigKey(
   if (hasCurrent) {
     process.stderr.write(`  Current: ${sensitive ? "REDACTED" : stringifyConfigValue(current)}\n`);
     const acceptPrompt = resolvedFromEnv(entry, hostEnv)
-      ? `  Value (Enter to copy from env)${valueHintSuffix}: `
+      ? `  Value (Enter to use env)${valueHintSuffix}: `
       : `  Value (Enter to keep)${valueHintSuffix}: `;
     process.stderr.write(acceptPrompt);
   } else {
@@ -202,6 +189,16 @@ function shouldShowConfigureSetupHeading(program: CliProgram): boolean {
   return Object.keys(program.appConfig.entries).length > 0;
 }
 
+function isPresent(value: unknown): boolean {
+  if (value === undefined || value === null) return false;
+  if (typeof value === "string" && value.length === 0) return false;
+  return true;
+}
+
+function bindingsDiffer(a: Record<string, unknown>, b: Record<string, unknown>): boolean {
+  return JSON.stringify(readBindings(a)) !== JSON.stringify(readBindings(b));
+}
+
 /** Ask the user for each required setting that is still empty; returns updates to save to the config file. */
 function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   const appConfig = program.appConfig;
@@ -212,31 +209,29 @@ function promptMissingRequired(program: CliProgram): Record<string, unknown> {
   const jsonSchema = effectiveJsonSchema(program);
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
   const hostEnv = captureMappedHostEnv(program);
-  const { resolved } = bootstrapAppConfig(program, { validateFile: false });
+  const path = resolveAppConfigPath(program);
+  const fileData = readAppConfigFileRaw(path);
+  const resolved = resolveAppConfig(program, fileData, hostEnv);
   let headingWritten = false;
   for (const [key, entry] of Object.entries(appConfig.entries)) {
     if (!configEntryRequired(key, entry, fromSchema)) {
       continue;
     }
-    const current = resolved[key];
-    if (current !== undefined && current !== null && String(current).length > 0) {
+    const bindings = readBindings(fileData);
+    if (bindings[key] === "env" && !isPresent(resolved[key])) {
+      // Re-prompt when env binding is broken.
+    } else if (isKeyAddressed(key, fileData, entry) && isPresent(resolved[key])) {
       continue;
     }
+    const current = resolved[key];
     if (!headingWritten) {
       writeConfigureSetupHeading();
       headingWritten = true;
     }
-    const { value, userTyped } = promptConfigKey(
-      key,
-      entry,
-      undefined,
-      false,
-      fromSchema,
-      hostEnv,
-      jsonSchema,
-    );
-    if (value !== undefined && String(value).length > 0) {
+    const { value, userTyped } = promptConfigKey(key, entry, current, false, fromSchema, hostEnv, jsonSchema);
+    if (userTyped && value !== undefined && String(value).length > 0) {
       updates[key] = value;
+      Object.assign(updates, setBinding(updates, key, "file"));
     }
   }
   return updates;
@@ -267,7 +262,7 @@ export function runConfigure(
   const jsonSchema = effectiveJsonSchema(program);
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
   const resolved = resolveAppConfig(program, existing, hostEnv);
-  const next: Record<string, unknown> = { ...existing };
+  let next: Record<string, unknown> = { ...existing };
   let changed = false;
 
   if (opts.showHeading !== false && shouldShowConfigureSetupHeading(program)) {
@@ -275,35 +270,51 @@ export function runConfigure(
   }
 
   for (const [key, entry] of Object.entries(program.appConfig.entries)) {
+    const bindings = readBindings(existing);
+    if (bindings[key] === "env" && !isPresent(resolved[key])) {
+      // Re-prompt when env binding is broken.
+    } else if (isKeyAddressed(key, existing, entry)) {
+      continue;
+    }
+
     const before = next[key];
+    const bindingsBefore = readBindings(next);
     const current = resolved[key];
-    const { value, userTyped } = promptConfigKey(
-      key,
-      entry,
-      current,
-      true,
-      fromSchema,
-      hostEnv,
-      jsonSchema,
-    );
-    if (value !== undefined && String(value).length > 0) {
+    const required = configEntryRequired(key, entry, fromSchema);
+    const { value, userTyped } = promptConfigKey(key, entry, current, true, fromSchema, hostEnv, jsonSchema);
+
+    if (userTyped && value !== undefined && String(value).length > 0) {
+      if (JSON.stringify(value) !== JSON.stringify(before) || bindingsBefore[key] !== "file") {
+        changed = true;
+      }
+      next = setBinding({ ...next, [key]: value }, key, "file");
+      continue;
+    }
+
+    if (!userTyped && isPresent(current) && resolvedFromEnv(entry, hostEnv)) {
       const storedInFile =
-        key in existing &&
-        existing[key] !== undefined &&
-        existing[key] !== null &&
-        String(existing[key]).length > 0;
-      if (!userTyped && !storedInFile) {
-        continue;
+        key in existing && existing[key] !== undefined && existing[key] !== null && String(existing[key]).length > 0;
+      if (!storedInFile) {
+        const withBinding = setBinding(clearFileValue(next, key), key, "env");
+        if (bindingsDiffer(next, withBinding) || key in next) {
+          changed = true;
+        }
+        next = withBinding;
       }
-      if (JSON.stringify(value) !== JSON.stringify(before)) {
+      continue;
+    }
+
+    if (!userTyped && !required && !isPresent(current) && inputWasSkipped(value, userTyped)) {
+      const withBinding = setBinding(next, key, "skip");
+      if (bindingsDiffer(next, withBinding)) {
         changed = true;
       }
-      next[key] = value;
+      next = withBinding;
     }
   }
 
   if (changed) {
-    writeAppConfigFile(program, next);
+    writeAppConfigFile(program, next, { partial: true });
     const updated = resolveAppConfig(program, next, hostEnv);
     exportConfigToEnv(program, updated, hostEnv);
     return { path, changed: true };
@@ -311,12 +322,16 @@ export function runConfigure(
   return { path, changed: false };
 }
 
+function inputWasSkipped(value: unknown, userTyped: boolean): boolean {
+  return !userTyped && (value === undefined || String(value).length === 0);
+}
+
 /** Summary for `configure --status`: config path, whether the file exists, and which required settings are set (never their values). */
 export function appConfigStatus(program: CliProgram):
   | {
       path: string;
       exists: boolean;
-      required: Array<{ key: string; set: boolean }>;
+      required: Array<{ key: string; set: boolean; binding?: "env" | "file" | "skip" | "missing" }>;
     }
   | undefined {
   if (!program.appConfig) {
@@ -336,19 +351,19 @@ export function appConfigStatus(program: CliProgram):
   const fromSchema = jsonSchema ? jsonSchemaRequiredKeys(jsonSchema) : undefined;
   const required = Object.entries(program.appConfig.entries)
     .filter(([key, entry]) => configEntryRequired(key, entry, fromSchema))
-    .map(([key]) => ({
-      key,
-      set:
-        resolved[key] !== undefined && resolved[key] !== null && String(resolved[key]).length > 0,
-    }));
-  return { path, exists: appConfigInstalled(program), required };
+    .map(([key]) => {
+      const set = resolved[key] !== undefined && resolved[key] !== null && String(resolved[key]).length > 0;
+      return {
+        key,
+        set,
+        binding: bindingForKey(key, fileData, set),
+      };
+    });
+  return { path, exists: appConfigFileExists(program), required };
 }
 
 /** Load config at startup, optionally prompt the user, and fail if required settings are still missing. */
-export function ensureAppConfig(
-  program: CliProgram,
-  opts: EnsureAppConfigOpts,
-): ConfigBootstrapResult | undefined {
+export function ensureAppConfig(program: CliProgram, opts: EnsureAppConfigOpts): ConfigBootstrapResult | undefined {
   if (!program.appConfig) {
     return undefined;
   }
@@ -377,7 +392,7 @@ export function ensureAppConfig(
     const updates = promptMissingRequired(program);
     if (Object.keys(updates).length > 0) {
       const merged = { ...fileData, ...updates };
-      writeAppConfigFile(program, merged);
+      writeAppConfigFile(program, merged, { partial: true });
       fileData = merged;
       resolved = resolveAppConfig(program, fileData, hostEnv);
       exportConfigToEnv(program, resolved, hostEnv);

package/src/config/context.test.ts

@@ -79,4 +79,49 @@ describe("config/context", () => {
     expect(ctx.dir).toBe(resolveAppConfigDir(program));
     expect(ctx.dir).toBe(dirname(ctx.path));
   });
+
+  test("AppConfigSnapshot unsafe read/write", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-unsafe-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
+    const prevToken = process.env.API_TOKEN;
+    delete process.env.API_TOKEN;
+    try {
+      const fileData = { apiToken: "tok" };
+      const resolved = resolveAppConfig(program, fileData);
+      const ctx = createAppConfigSnapshot(program, fileData, resolved);
+      expect(ctx.getUnsafe("apiToken")).toBe("tok");
+      expect(ctx.readUnsafe().apiToken).toBe("tok");
+      ctx.setUnsafe("note", "raw");
+      expect(ctx.getUnsafe("note")).toBe("raw");
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      if (prevToken === undefined) delete process.env.API_TOKEN;
+      else process.env.API_TOKEN = prevToken;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("EmptyAppConfigSnapshot unsafe read/write", () => {
+    const dir = mkdtempSync(join(tmpdir(), "ctx-empty-unsafe-"));
+    const prevHome = process.env.HOME;
+    process.env.HOME = dir;
+    try {
+      const programWithoutConfig: CliProgram = {
+        key: "rawapp",
+        version: "1.0.0",
+        description: "No config.",
+        handler: () => {},
+      };
+      const empty = createAppConfigSnapshot(programWithoutConfig, {}, {});
+      empty.setUnsafe("custom", 42);
+      expect(empty.getUnsafe("custom")).toBe(42);
+      expect(empty.readUnsafe().custom).toBe(42);
+    } finally {
+      if (prevHome === undefined) delete process.env.HOME;
+      else process.env.HOME = prevHome;
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });

package/src/config/context.ts

@@ -3,13 +3,36 @@ Handler-facing resolved app config snapshot (ctx.appConfig).
 */
 
 import type { CliProgram } from "../types.ts";
-import { resolveAppConfigDir, resolveAppConfigPath, writeAppConfigFile } from "./file.ts";
+import { isFrameworkConfigKey, setBinding } from "./bindings.ts";
+import {
+  readAppConfigFileRaw,
+  resolveAppConfigDir,
+  resolveAppConfigPath,
+  writeAppConfigFile,
+  writeAppConfigFileRaw,
+} from "./file.ts";
 import type { ResolvedConfig } from "./resolve.ts";
 import { captureMappedHostEnv, exportConfigToEnv, resolveAppConfig } from "./resolve.ts";
+import { configPropertySchema, effectiveJsonSchema } from "./schema.ts";
+import { validateParsedConfigValue } from "./validate.ts";
+
+function rebuildResolved(program: CliProgram, fileData: Record<string, unknown>): ResolvedConfig {
+  const hostEnv = captureMappedHostEnv(program);
+  const resolved = resolveAppConfig(program, fileData, hostEnv);
+  exportConfigToEnv(program, resolved, hostEnv);
+  return resolved;
+}
 
 /** Empty snapshot when program.appConfig is not set. */
 export class EmptyAppConfigSnapshot {
-  constructor(private readonly program: CliProgram) {}
+  private fileData: Record<string, unknown>;
+
+  constructor(
+    private readonly program: CliProgram,
+    fileData?: Record<string, unknown>,
+  ) {
+    this.fileData = fileData ?? readAppConfigFileRaw(resolveAppConfigPath(program));
+  }
 
   get(_key: string): undefined {
     return undefined;
@@ -27,6 +50,20 @@ export class EmptyAppConfigSnapshot {
     return {};
   }
 
+  readUnsafe(): Record<string, unknown> {
+    return { ...this.fileData };
+  }
+
+  getUnsafe(key: string): unknown {
+    return this.fileData[key];
+  }
+
+  setUnsafe(key: string, value: unknown): void {
+    const next = { ...this.fileData, [key]: value };
+    writeAppConfigFileRaw(this.program, next);
+    this.fileData = next;
+  }
+
   /** Resolved absolute path to the app JSON config file (OS default from `program.key`). */
   get path(): string {
     return resolveAppConfigPath(this.program);
@@ -59,11 +96,7 @@ export class AppConfigSnapshot {
 
   require(key: string): unknown {
     const value = this.get(key);
-    if (
-      value === undefined ||
-      value === null ||
-      (typeof value === "string" && value.length === 0)
-    ) {
+    if (value === undefined || value === null || (typeof value === "string" && value.length === 0)) {
       throw new Error(`Missing required configuration: ${key}`);
     }
     return value;
@@ -71,18 +104,34 @@ export class AppConfigSnapshot {
 
   set(key: string, value: unknown): void {
     this.assertEntryKey(key);
-    const hostEnv = captureMappedHostEnv(this.program);
-    const next = { ...this.fileData, [key]: value };
-    writeAppConfigFile(this.program, next);
-    this.fileData = next;
-    this.snapshot = resolveAppConfig(this.program, next, hostEnv);
-    exportConfigToEnv(this.program, this.snapshot, hostEnv);
+    const jsonSchema = effectiveJsonSchema(this.program);
+    if (!jsonSchema) {
+      throw new Error("Internal error: missing effective jsonSchema.");
+    }
+    const propSchema = configPropertySchema(jsonSchema, key);
+    validateParsedConfigValue(value, propSchema, jsonSchema);
+    const next = setBinding({ ...this.fileData, [key]: value }, key, "file");
+    this.persistFileData(next);
   }
 
   read(): ResolvedConfig {
     return { ...this.snapshot };
   }
 
+  readUnsafe(): Record<string, unknown> {
+    return { ...this.fileData };
+  }
+
+  getUnsafe(key: string): unknown {
+    return this.fileData[key];
+  }
+
+  setUnsafe(key: string, value: unknown): void {
+    this.assertUnsafeKey(key);
+    const next = { ...this.fileData, [key]: value };
+    this.persistFileData(next);
+  }
+
   /** Resolved absolute path to the app JSON config file (`~/.local/lib/<key>/config.json`). */
   get path(): string {
     return resolveAppConfigPath(this.program);
@@ -99,12 +148,23 @@ export class AppConfigSnapshot {
     this.snapshot = { ...resolved };
   }
 
+  private persistFileData(next: Record<string, unknown>): void {
+    writeAppConfigFile(this.program, next, { partial: true });
+    this.fileData = next;
+    this.snapshot = rebuildResolved(this.program, next);
+  }
+
   private assertEntryKey(key: string): void {
     const entries = this.program.appConfig?.entries;
     if (!entries || !(key in entries)) {
       throw new Error(`Unknown configuration key: ${key}`);
     }
   }
+
+  private assertUnsafeKey(key: string): void {
+    if (isFrameworkConfigKey(key)) return;
+    this.assertEntryKey(key);
+  }
 }
 
 export type AnyAppConfigSnapshot = AppConfigSnapshot | EmptyAppConfigSnapshot;
@@ -115,7 +175,7 @@ export function createAppConfigSnapshot(
   resolved: ResolvedConfig,
 ): AnyAppConfigSnapshot {
   if (!program.appConfig) {
-    return new EmptyAppConfigSnapshot(program);
+    return new EmptyAppConfigSnapshot(program, fileData);
   }
   return new AppConfigSnapshot(program, fileData, resolved);
 }

package/src/config/entry.ts

@@ -46,9 +46,7 @@ export function configUserConfigKey(key: string): string {
 }
 
 /** Required keys from a JSON Schema object root. */
-export function jsonSchemaRequiredKeys(
-  jsonSchema: Record<string, unknown>,
-): Set<string> | undefined {
+export function jsonSchemaRequiredKeys(jsonSchema: Record<string, unknown>): Set<string> | undefined {
   const required = jsonSchema.required;
   if (!Array.isArray(required)) {
     return undefined;