Let operators supply defaults for selected instance settings (#12285)
## Thinking Path
> - Paperclip is the open source app people use to manage AI agents for
work
> - Hosting operators (a managed cloud, an internal shared server) tune
the settings surface with `PAPERCLIP_HIDDEN_SETTINGS`, but hiding a
control never changes its value
> - An instance whose stored feedback-sharing preference is still the
schema default ("prompt") keeps prompting users even when the operator
hid the control, leaving them no way to answer
> - More generally, operators have no supported way to change what a
setting defaults to without patching code
> - This pull request adds `PAPERCLIP_SETTING_DEFAULTS`, a generic
operator-supplied read-time default overlay for registry-listed general
settings
> - The benefit is that any hosting operator can pair "hide the control"
with "default the value", while explicit user choices and self-hosted
stock behavior stay untouched
## Linked Issues or Issue Description
No public issue exists; following the enhancement template:
**What existing behavior does this improve?**
Hosting operators need to supply the default value of selected instance
settings (first: `feedbackDataSharingPreference`) via configuration,
without patching code and without a hard-coded, opinionated constant in
the product.
**Subsystem affected**
Server (instance-settings service, feedback service, boot) and
`packages/shared` (settings schemas).
**Current behavior**
Setting defaults are fixed in the shared zod schemas.
`PAPERCLIP_HIDDEN_SETTINGS` can hide the feedback-sharing control and
floor writes, but the stored value stays "prompt", so issue-chat
surfaces keep prompting with no way to answer.
**Proposed behavior**
`PAPERCLIP_SETTING_DEFAULTS` takes a JSON object validated against a
shared registry of defaultable fields. The operator value substitutes
for the schema default at read time: a field whose effective value is
still the schema default resolves to the operator value; an explicit
non-default user choice always wins. Never persisted; unsetting the
variable restores stock behavior. Malformed JSON or an invalid value for
a known field refuses startup (fail closed); unknown field names warn
and are ignored (mixed-version fleet safe).
**Reason and benefit**
Any hosting operator can pair "hide the control" with "default the
value" without forking the product. Explicit user choices and
self-hosted stock behavior stay untouched.
**Breaking changes**
None. With the variable unset, every read path is byte-identical to
before.
## What Changed
- New `packages/shared/src/setting-defaults.ts`:
`SETTING_DEFAULTS_ENV_KEY`, `DEFAULTABLE_GENERAL_SETTINGS` registry
(currently `feedbackDataSharingPreference`), `parseSettingDefaults`
(fail-closed for policy content, warn-ignore unknown fields),
`applyOperatorGeneralDefaults` (pure read-time overlay),
`stripOperatorGeneralEchoes` (persist-time echo strip, see below),
re-exported from the package index.
- New `server/src/services/setting-defaults.ts`: parse-once accessor
mirroring `settings-visibility.ts`.
- `server/src/services/instance-settings.ts`: `toGeneralView` applies
the overlay in `get`/`getGeneral`/update responses; persisted writes
never carry operator values. Because general-settings writes materialize
every field, a stored schema-default value is treated as unchosen —
deliberate, documented, and covered by tests.
- `server/src/services/feedback.ts`: the preference-persistence branch
now checks the effective (overlaid) preference, so a stray prompt answer
cannot overwrite an operator default; its local normalize fallback now
returns full schema defaults.
- `server/src/index.ts`: boot-time fail-fast parse with a log line
naming the defaulted settings, mirroring the managed-config posture.
- The hidden-settings write floor (`assertNoHiddenSettingChanges`) keeps
comparing against effective values, so clients echoing a full GET
response keep working. To keep the overlay strictly read-time,
`updateGeneral` strips such echoes at persist time: a write of the
operator value over a field whose stored value is still the schema
default (unchosen) maps back to the schema default, so an echo cannot
promote the operator value into an explicit stored choice and later
changes to (or removal of) `PAPERCLIP_SETTING_DEFAULTS` still take
effect. A write of any other value, or over an explicit stored choice,
persists as given.
- Docs: `PAPERCLIP_SETTING_DEFAULTS` row + "Operator setting defaults"
section in `docs/deploy/environment-variables.md`.
- Tests: `packages/shared/src/setting-defaults.test.ts` (parse matrix,
overlay precedence, echo-strip matrix, immutability) and
`server/src/__tests__/instance-settings-operator-defaults.test.ts`
(accessor, substitution, explicit-choice wins, unset identity,
never-persisted, full-GET echo stays unchosen, explicit non-default
write persists).
## Verification
- `npx vitest run packages/shared/src/setting-defaults.test.ts
server/src/__tests__/instance-settings-operator-defaults.test.ts
server/src/__tests__/instance-settings-managed-overlay.test.ts` — 33
tests passing.
- `npx vitest run server/src/__tests__/instance-settings-routes.test.ts
server/src/__tests__/instance-settings-service.test.ts` — 57 passing;
`npx vitest run server/src/__tests__/feedback-service.test.ts
server/src/__tests__/issue-feedback-routes.test.ts` — 18 passing.
- `pnpm --filter @paperclipai/shared typecheck` and `pnpm --filter
@paperclipai/server typecheck` — clean.
## Risks
- Low. With the variable unset every read path is byte-identical to
before (identity overlay, covered by tests). The overlay is read-time
only and never persisted, so no migration and no data risk. Fail-closed
parsing means a bad policy value is a loud boot failure rather than
silent drift — consistent with the existing managed-config contract.
## Model Used
Claude (Anthropic), model id `claude-fable-5`, extended thinking,
agentic tool use via Claude Code.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
This commit is contained in:
Devin Foley
GitHub
parent
e34ed9801b
commit
8f195c2f49
|
|
@ -20,6 +20,7 @@ All environment variables that Paperclip uses for server configuration.
|
|||
| `PAPERCLIP_DEPLOYMENT_EXPOSURE` | `private` | Exposure policy when deployment mode is `authenticated` |
|
||||
| `PAPERCLIP_API_URL` | (auto-derived) | Paperclip API base URL. When set externally (e.g., via Kubernetes ConfigMap, load balancer, or reverse proxy), the server preserves the value instead of deriving it from the listen host and port. Useful for deployments where the public-facing URL differs from the local bind address. |
|
||||
| `PAPERCLIP_HIDDEN_SETTINGS` | (unset) | Comma-separated settings surfaces to hide from the UI and floor at the API, for operators hosting Paperclip for others (managed cloud, internal shared server). See [Hiding settings surfaces](#hiding-settings-surfaces). |
|
||||
| `PAPERCLIP_SETTING_DEFAULTS` | (unset) | JSON object replacing the schema default of selected instance settings, for hosting operators. See [Operator setting defaults](#operator-setting-defaults). |
|
||||
|
||||
### Hiding settings surfaces
|
||||
|
||||
|
|
@ -58,7 +59,30 @@ All environment variables that Paperclip uses for server configuration.
|
|||
Unknown keys are logged and ignored, so one list can be rolled across a fleet
|
||||
of mixed app versions. With the variable unset nothing is hidden and behavior
|
||||
is identical to earlier releases. Hiding a toggle does not change its value;
|
||||
pair hiding with the desired default where it matters.
|
||||
pair hiding with the desired default where it matters (for general settings,
|
||||
see [Operator setting defaults](#operator-setting-defaults)).
|
||||
|
||||
### Operator setting defaults
|
||||
|
||||
`PAPERCLIP_SETTING_DEFAULTS` takes a JSON object whose fields come from the
|
||||
registry in `packages/shared/src/setting-defaults.ts` (currently
|
||||
`feedbackDataSharingPreference`). The operator value substitutes for the
|
||||
schema default at read time: any field whose effective value is still the
|
||||
schema default resolves to the operator value, while an explicit non-default
|
||||
user choice always wins. The overlay is never persisted, so unsetting the
|
||||
variable restores stock behavior wherever a user has not chosen otherwise.
|
||||
A client that writes back the full settings object it read does not persist
|
||||
the operator value either: writing the operator value over a still-unchosen
|
||||
field is treated as an echo of the overlay and the field stays unchosen.
|
||||
|
||||
Example: `PAPERCLIP_SETTING_DEFAULTS='{"feedbackDataSharingPreference":"allowed"}'`
|
||||
defaults AI feedback sharing to allowed; pairing it with
|
||||
`instance.general.feedbackDataSharingPreference` in `PAPERCLIP_HIDDEN_SETTINGS`
|
||||
also hides the control and floors value-changing writes.
|
||||
|
||||
Unknown field names are logged and ignored (mixed-version fleet safe).
|
||||
Malformed JSON or an invalid value for a known field refuses startup — policy
|
||||
configuration fails closed.
|
||||
|
||||
## Secrets
|
||||
|
||||
|
|
|
|||
|
|
@ -2527,6 +2527,16 @@ export {
|
|||
type HideableSettingKey,
|
||||
type ParsedHiddenSettings,
|
||||
} from "./settings-visibility.js";
|
||||
export {
|
||||
DEFAULTABLE_GENERAL_SETTINGS,
|
||||
SETTING_DEFAULTS_ENV_KEY,
|
||||
applyOperatorGeneralDefaults,
|
||||
parseSettingDefaults,
|
||||
stripOperatorGeneralEchoes,
|
||||
type DefaultableGeneralSetting,
|
||||
type OperatorSettingDefaults,
|
||||
type ParsedSettingDefaults,
|
||||
} from "./setting-defaults.js";
|
||||
|
||||
// --- Runtime exposure (opt-in Tailscale HTTPS for managed branch runtimes) ---
|
||||
// PAP-17049 plan, PAP-17050 threat-model verdict. Contract shared across DB,
|
||||
|
|
|
|||
|
|
@ -0,0 +1,136 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import {
|
||||
DEFAULTABLE_GENERAL_SETTINGS,
|
||||
SETTING_DEFAULTS_ENV_KEY,
|
||||
applyOperatorGeneralDefaults,
|
||||
parseSettingDefaults,
|
||||
stripOperatorGeneralEchoes,
|
||||
} from "./setting-defaults.js";
|
||||
import { instanceGeneralSettingsSchema } from "./validators/instance.js";
|
||||
|
||||
describe("parseSettingDefaults", () => {
|
||||
it("returns null defaults for an unset or blank variable", () => {
|
||||
expect(parseSettingDefaults(undefined)).toEqual({ defaults: null, unknown: [] });
|
||||
expect(parseSettingDefaults("")).toEqual({ defaults: null, unknown: [] });
|
||||
expect(parseSettingDefaults(" ")).toEqual({ defaults: null, unknown: [] });
|
||||
});
|
||||
|
||||
it("parses known fields and validates their values", () => {
|
||||
const { defaults, unknown } = parseSettingDefaults(
|
||||
'{"feedbackDataSharingPreference":"allowed"}',
|
||||
);
|
||||
expect(defaults).toEqual({ feedbackDataSharingPreference: "allowed" });
|
||||
expect(unknown).toEqual([]);
|
||||
});
|
||||
|
||||
it("collects unknown fields instead of failing, for mixed-version fleets", () => {
|
||||
const { defaults, unknown } = parseSettingDefaults(
|
||||
'{"feedbackDataSharingPreference":"not_allowed","someFutureSetting":true}',
|
||||
);
|
||||
expect(defaults).toEqual({ feedbackDataSharingPreference: "not_allowed" });
|
||||
expect(unknown).toEqual(["someFutureSetting"]);
|
||||
});
|
||||
|
||||
it("fails closed on malformed JSON and non-object shapes", () => {
|
||||
expect(() => parseSettingDefaults("{nope")).toThrow(SETTING_DEFAULTS_ENV_KEY);
|
||||
expect(() => parseSettingDefaults('"allowed"')).toThrow(/JSON object/);
|
||||
expect(() => parseSettingDefaults("[1,2]")).toThrow(/JSON object/);
|
||||
expect(() => parseSettingDefaults("null")).toThrow(/JSON object/);
|
||||
});
|
||||
|
||||
it("fails closed on an invalid value for a known field", () => {
|
||||
expect(() =>
|
||||
parseSettingDefaults('{"feedbackDataSharingPreference":"sometimes"}'),
|
||||
).toThrow(/feedbackDataSharingPreference/);
|
||||
});
|
||||
|
||||
it("keeps every registry entry a real general-settings field", () => {
|
||||
const shape = Object.keys(instanceGeneralSettingsSchema.shape);
|
||||
for (const key of DEFAULTABLE_GENERAL_SETTINGS) {
|
||||
expect(shape).toContain(key);
|
||||
}
|
||||
});
|
||||
});
|
||||
|
||||
describe("applyOperatorGeneralDefaults", () => {
|
||||
const schemaDefaults = instanceGeneralSettingsSchema.parse({});
|
||||
|
||||
it("is the identity when no operator defaults are configured", () => {
|
||||
expect(applyOperatorGeneralDefaults(schemaDefaults, null)).toBe(schemaDefaults);
|
||||
});
|
||||
|
||||
it("substitutes the operator value where the schema default still holds", () => {
|
||||
const overlaid = applyOperatorGeneralDefaults(schemaDefaults, {
|
||||
feedbackDataSharingPreference: "allowed",
|
||||
});
|
||||
expect(overlaid.feedbackDataSharingPreference).toBe("allowed");
|
||||
// Other fields are untouched.
|
||||
expect(overlaid.backupRetention).toEqual(schemaDefaults.backupRetention);
|
||||
});
|
||||
|
||||
it("never overrides an explicit non-default choice", () => {
|
||||
const chosen = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const };
|
||||
const overlaid = applyOperatorGeneralDefaults(chosen, {
|
||||
feedbackDataSharingPreference: "allowed",
|
||||
});
|
||||
expect(overlaid.feedbackDataSharingPreference).toBe("not_allowed");
|
||||
expect(overlaid).toBe(chosen);
|
||||
});
|
||||
|
||||
it("does not mutate its input", () => {
|
||||
const input = { ...schemaDefaults };
|
||||
applyOperatorGeneralDefaults(input, { feedbackDataSharingPreference: "allowed" });
|
||||
expect(input.feedbackDataSharingPreference).toBe(
|
||||
schemaDefaults.feedbackDataSharingPreference,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("stripOperatorGeneralEchoes", () => {
|
||||
const schemaDefaults = instanceGeneralSettingsSchema.parse({});
|
||||
const defaults = { feedbackDataSharingPreference: "allowed" as const };
|
||||
|
||||
it("is the identity when no operator defaults are configured", () => {
|
||||
const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const };
|
||||
expect(stripOperatorGeneralEchoes(schemaDefaults, next, null)).toBe(next);
|
||||
});
|
||||
|
||||
it("maps an echoed operator value on an unchosen field back to the schema default", () => {
|
||||
// Stored is still the schema default (unchosen); the incoming full-object
|
||||
// echo carries the overlaid operator value. Persisting it would make the
|
||||
// operator value sticky, so it maps back to the schema default.
|
||||
const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const };
|
||||
const stripped = stripOperatorGeneralEchoes(schemaDefaults, next, defaults);
|
||||
expect(stripped.feedbackDataSharingPreference).toBe(
|
||||
schemaDefaults.feedbackDataSharingPreference,
|
||||
);
|
||||
});
|
||||
|
||||
it("keeps an incoming value that differs from the operator default", () => {
|
||||
const next = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const };
|
||||
const stripped = stripOperatorGeneralEchoes(schemaDefaults, next, defaults);
|
||||
expect(stripped).toBe(next);
|
||||
expect(stripped.feedbackDataSharingPreference).toBe("not_allowed");
|
||||
});
|
||||
|
||||
it("keeps a write over an explicit stored choice, even at the operator value", () => {
|
||||
// The user previously chose "not_allowed" and now picks the operator's
|
||||
// value: stored is not the schema default, so this is a real transition
|
||||
// and persists as given.
|
||||
const stored = { ...schemaDefaults, feedbackDataSharingPreference: "not_allowed" as const };
|
||||
const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const };
|
||||
const stripped = stripOperatorGeneralEchoes(stored, next, defaults);
|
||||
expect(stripped).toBe(next);
|
||||
expect(stripped.feedbackDataSharingPreference).toBe("allowed");
|
||||
});
|
||||
|
||||
it("does not mutate its inputs", () => {
|
||||
const stored = { ...schemaDefaults };
|
||||
const next = { ...schemaDefaults, feedbackDataSharingPreference: "allowed" as const };
|
||||
stripOperatorGeneralEchoes(stored, next, defaults);
|
||||
expect(next.feedbackDataSharingPreference).toBe("allowed");
|
||||
expect(stored.feedbackDataSharingPreference).toBe(
|
||||
schemaDefaults.feedbackDataSharingPreference,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,163 @@
|
|||
import { instanceGeneralSettingsSchema } from "./validators/instance.js";
|
||||
import type { InstanceGeneralSettings } from "./types/instance.js";
|
||||
|
||||
/**
|
||||
* Operator-configurable setting defaults.
|
||||
*
|
||||
* A hosting operator (a managed cloud, an internal shared server) can replace
|
||||
* the schema default of selected instance settings by setting the
|
||||
* `PAPERCLIP_SETTING_DEFAULTS` environment variable to a JSON object, e.g.
|
||||
* `{"feedbackDataSharingPreference":"allowed"}`. The operator value
|
||||
* substitutes for the schema default at read time: any field whose effective
|
||||
* value is still the schema default resolves to the operator value, while an
|
||||
* explicit non-default user choice always wins. The overlay is never
|
||||
* persisted, so unsetting the variable restores stock behavior everywhere a
|
||||
* user has not chosen otherwise.
|
||||
*
|
||||
* Parsing is fail-closed for policy content: malformed JSON or an invalid
|
||||
* value for a known field is an error (the server refuses to boot), because a
|
||||
* silently dropped policy default is worse than a loud failure. Unknown field
|
||||
* names are warned about and ignored, so one value can be rolled across a
|
||||
* fleet of mixed app versions where older images predate a field.
|
||||
*
|
||||
* Pairing note: an operator that also wants the control invisible hides it
|
||||
* with `PAPERCLIP_HIDDEN_SETTINGS` (see settings-visibility.ts); the two
|
||||
* mechanisms are orthogonal.
|
||||
*/
|
||||
|
||||
export const SETTING_DEFAULTS_ENV_KEY = "PAPERCLIP_SETTING_DEFAULTS";
|
||||
|
||||
/** Instance → General fields whose schema default an operator may replace. */
|
||||
export const DEFAULTABLE_GENERAL_SETTINGS = [
|
||||
"feedbackDataSharingPreference",
|
||||
] as const;
|
||||
|
||||
export type DefaultableGeneralSetting = (typeof DEFAULTABLE_GENERAL_SETTINGS)[number];
|
||||
|
||||
export type OperatorSettingDefaults = Partial<
|
||||
Pick<InstanceGeneralSettings, DefaultableGeneralSetting>
|
||||
>;
|
||||
|
||||
export interface ParsedSettingDefaults {
|
||||
/** Validated operator defaults for known fields; null when the var is unset. */
|
||||
defaults: OperatorSettingDefaults | null;
|
||||
/** Unrecognized field names, for the caller to warn about. */
|
||||
unknown: string[];
|
||||
}
|
||||
|
||||
const defaultableFieldsSchema = instanceGeneralSettingsSchema
|
||||
.pick(
|
||||
Object.fromEntries(DEFAULTABLE_GENERAL_SETTINGS.map((key) => [key, true])) as {
|
||||
[K in DefaultableGeneralSetting]: true;
|
||||
},
|
||||
)
|
||||
.partial();
|
||||
|
||||
/** The all-schema-defaults view used to decide whether a value was chosen. */
|
||||
const schemaDefaults: InstanceGeneralSettings = instanceGeneralSettingsSchema.parse({});
|
||||
|
||||
/**
|
||||
* Parse a `PAPERCLIP_SETTING_DEFAULTS`-style JSON object.
|
||||
*
|
||||
* @throws when the JSON is malformed, not an object, or a known field carries
|
||||
* an invalid value — policy configuration fails closed.
|
||||
*/
|
||||
export function parseSettingDefaults(raw: string | undefined): ParsedSettingDefaults {
|
||||
if (raw === undefined || raw.trim() === "") return { defaults: null, unknown: [] };
|
||||
let parsed: unknown;
|
||||
try {
|
||||
parsed = JSON.parse(raw);
|
||||
} catch (error) {
|
||||
throw new Error(
|
||||
`${SETTING_DEFAULTS_ENV_KEY} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
|
||||
);
|
||||
}
|
||||
if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
|
||||
throw new Error(`${SETTING_DEFAULTS_ENV_KEY} must be a JSON object of setting defaults`);
|
||||
}
|
||||
const known: Record<string, unknown> = {};
|
||||
const unknown: string[] = [];
|
||||
const defaultable = new Set<string>(DEFAULTABLE_GENERAL_SETTINGS);
|
||||
for (const [key, value] of Object.entries(parsed)) {
|
||||
if (defaultable.has(key)) {
|
||||
known[key] = value;
|
||||
} else {
|
||||
unknown.push(key);
|
||||
}
|
||||
}
|
||||
const result = defaultableFieldsSchema.safeParse(known);
|
||||
if (!result.success) {
|
||||
throw new Error(
|
||||
`${SETTING_DEFAULTS_ENV_KEY} carries an invalid value: ${result.error.issues
|
||||
.map((issue) => `${issue.path.join(".")}: ${issue.message}`)
|
||||
.join("; ")}`,
|
||||
);
|
||||
}
|
||||
return { defaults: result.data as OperatorSettingDefaults, unknown };
|
||||
}
|
||||
|
||||
/**
|
||||
* Overlay operator defaults onto normalized general settings at read time.
|
||||
*
|
||||
* The operator value substitutes for the schema default: a field still at its
|
||||
* schema default (absent from storage, or stored equal to it) resolves to the
|
||||
* operator value; an explicit non-default choice is untouched. Callers must
|
||||
* never persist the result.
|
||||
*/
|
||||
export function applyOperatorGeneralDefaults(
|
||||
general: InstanceGeneralSettings,
|
||||
defaults: OperatorSettingDefaults | null,
|
||||
): InstanceGeneralSettings {
|
||||
if (!defaults) return general;
|
||||
let next: InstanceGeneralSettings | null = null;
|
||||
for (const key of DEFAULTABLE_GENERAL_SETTINGS) {
|
||||
const value = defaults[key];
|
||||
if (value === undefined) continue;
|
||||
if (general[key] === schemaDefaults[key] && general[key] !== value) {
|
||||
next ??= { ...general };
|
||||
next[key] = value;
|
||||
}
|
||||
}
|
||||
return next ?? general;
|
||||
}
|
||||
|
||||
/**
|
||||
* Strip overlay echoes from a general-settings write at persist time.
|
||||
*
|
||||
* A client that writes back the full object it read (a full-GET echo) sends
|
||||
* the overlaid operator value for a field the user never chose. Persisting
|
||||
* that echo would promote the operator value into an explicit stored choice —
|
||||
* sticky across later changes to, or removal of, the environment variable.
|
||||
* This maps such a write back to the schema default: a field whose stored
|
||||
* value is still the schema default (unchosen) and whose incoming value
|
||||
* equals the operator default stays unchosen, keeping the overlay
|
||||
* strictly read-time.
|
||||
*
|
||||
* A user cannot be distinguished from an echo when they deliberately pick the
|
||||
* value that already shows as the default, so that pick also stays unchosen —
|
||||
* the mirror image of the documented "stored schema default is treated as
|
||||
* unchosen" rule, with identical effective behavior. Any other write persists
|
||||
* as given: an incoming value that differs from the operator default, or a
|
||||
* write over an explicit stored choice.
|
||||
*/
|
||||
export function stripOperatorGeneralEchoes(
|
||||
stored: InstanceGeneralSettings,
|
||||
next: InstanceGeneralSettings,
|
||||
defaults: OperatorSettingDefaults | null,
|
||||
): InstanceGeneralSettings {
|
||||
if (!defaults) return next;
|
||||
let result: InstanceGeneralSettings | null = null;
|
||||
for (const key of DEFAULTABLE_GENERAL_SETTINGS) {
|
||||
const value = defaults[key];
|
||||
if (value === undefined) continue;
|
||||
if (
|
||||
stored[key] === schemaDefaults[key] &&
|
||||
next[key] === value &&
|
||||
next[key] !== schemaDefaults[key]
|
||||
) {
|
||||
result ??= { ...next };
|
||||
result[key] = schemaDefaults[key];
|
||||
}
|
||||
}
|
||||
return result ?? next;
|
||||
}
|
||||
|
|
@ -0,0 +1,132 @@
|
|||
import { describe, expect, it } from "vitest";
|
||||
import type { Db } from "@paperclipai/db";
|
||||
import { instanceSettingsService } from "../services/instance-settings.js";
|
||||
import { getOperatorSettingDefaults } from "../services/setting-defaults.js";
|
||||
|
||||
const DEFAULTS_RAW = JSON.stringify({ feedbackDataSharingPreference: "allowed" });
|
||||
|
||||
function defaultsEnv(raw: string | undefined = DEFAULTS_RAW) {
|
||||
return { PAPERCLIP_SETTING_DEFAULTS: raw };
|
||||
}
|
||||
|
||||
/** Mirrors the stub in instance-settings-managed-overlay.test.ts. */
|
||||
function stubDb(row: Record<string, unknown>) {
|
||||
const persistedSets: Array<Record<string, unknown>> = [];
|
||||
const db = {
|
||||
select: () => ({ from: () => ({ where: () => Promise.resolve([row]) }) }),
|
||||
insert: () => {
|
||||
throw new Error("unexpected insert in test");
|
||||
},
|
||||
update: () => ({
|
||||
set: (values: Record<string, unknown>) => {
|
||||
persistedSets.push(values);
|
||||
return { where: () => ({ returning: () => Promise.resolve([{ ...row, ...values }]) }) };
|
||||
},
|
||||
}),
|
||||
} as unknown as Db;
|
||||
return { db, persistedSets };
|
||||
}
|
||||
|
||||
function settingsRow(general: Record<string, unknown>) {
|
||||
return {
|
||||
id: "row-1",
|
||||
singletonKey: "default",
|
||||
defaultEnvironmentId: null,
|
||||
general,
|
||||
experimental: {},
|
||||
createdAt: new Date("2026-06-20T00:00:00.000Z"),
|
||||
updatedAt: new Date("2026-06-20T00:00:00.000Z"),
|
||||
};
|
||||
}
|
||||
|
||||
describe("getOperatorSettingDefaults", () => {
|
||||
it("returns null with the variable unset", () => {
|
||||
expect(getOperatorSettingDefaults({})).toBeNull();
|
||||
});
|
||||
|
||||
it("parses once and ignores unknown fields", () => {
|
||||
const defaults = getOperatorSettingDefaults(
|
||||
defaultsEnv('{"feedbackDataSharingPreference":"allowed","futureField":1}'),
|
||||
);
|
||||
expect(defaults).toEqual({ feedbackDataSharingPreference: "allowed" });
|
||||
});
|
||||
|
||||
it("throws on malformed policy JSON (fail closed)", () => {
|
||||
expect(() => getOperatorSettingDefaults(defaultsEnv("{broken"))).toThrow(
|
||||
/PAPERCLIP_SETTING_DEFAULTS/,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("instanceSettingsService operator setting defaults", () => {
|
||||
it("substitutes the operator value where the schema default holds", async () => {
|
||||
const { db } = stubDb(settingsRow({}));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const general = await svc.getGeneral();
|
||||
expect(general.feedbackDataSharingPreference).toBe("allowed");
|
||||
});
|
||||
|
||||
it("treats a stored schema-default value as unchosen", async () => {
|
||||
// updateGeneral materializes every field with its schema default, so a
|
||||
// stored "prompt" does not mean the user chose "prompt" — the operator
|
||||
// default still substitutes.
|
||||
const { db } = stubDb(settingsRow({ feedbackDataSharingPreference: "prompt" }));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const general = await svc.getGeneral();
|
||||
expect(general.feedbackDataSharingPreference).toBe("allowed");
|
||||
});
|
||||
|
||||
it("keeps an explicit non-default user choice", async () => {
|
||||
const { db } = stubDb(settingsRow({ feedbackDataSharingPreference: "not_allowed" }));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const general = await svc.getGeneral();
|
||||
expect(general.feedbackDataSharingPreference).toBe("not_allowed");
|
||||
});
|
||||
|
||||
it("changes nothing with the variable unset (self-hosted)", async () => {
|
||||
const { db } = stubDb(settingsRow({}));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: {} });
|
||||
const general = await svc.getGeneral();
|
||||
expect(general.feedbackDataSharingPreference).toBe("prompt");
|
||||
});
|
||||
|
||||
it("overlays reads but never persists the operator value", async () => {
|
||||
const { db, persistedSets } = stubDb(settingsRow({}));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const result = await svc.updateGeneral({ censorUsernameInLogs: true });
|
||||
// The response reflects the overlay...
|
||||
expect(result.general.feedbackDataSharingPreference).toBe("allowed");
|
||||
// ...but what hit the database is the schema default, not the operator's.
|
||||
expect(persistedSets).toHaveLength(1);
|
||||
const persistedGeneral = persistedSets[0]!.general as Record<string, unknown>;
|
||||
expect(persistedGeneral.censorUsernameInLogs).toBe(true);
|
||||
expect(persistedGeneral.feedbackDataSharingPreference).toBe("prompt");
|
||||
});
|
||||
|
||||
it("does not let a full-GET echo promote the operator value into a choice", async () => {
|
||||
// A client PUTs back the full object it read, including the overlaid
|
||||
// "allowed". The stored value is still the schema default (unchosen), so
|
||||
// the echo maps back to the schema default: changing or unsetting
|
||||
// PAPERCLIP_SETTING_DEFAULTS later still takes effect.
|
||||
const { db, persistedSets } = stubDb(settingsRow({}));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const echoed = await svc.getGeneral();
|
||||
expect(echoed.feedbackDataSharingPreference).toBe("allowed");
|
||||
const result = await svc.updateGeneral({ ...echoed, censorUsernameInLogs: true });
|
||||
expect(result.general.feedbackDataSharingPreference).toBe("allowed");
|
||||
expect(persistedSets).toHaveLength(1);
|
||||
const persistedGeneral = persistedSets[0]!.general as Record<string, unknown>;
|
||||
expect(persistedGeneral.censorUsernameInLogs).toBe(true);
|
||||
expect(persistedGeneral.feedbackDataSharingPreference).toBe("prompt");
|
||||
});
|
||||
|
||||
it("persists an explicit write of a value that differs from the operator default", async () => {
|
||||
const { db, persistedSets } = stubDb(settingsRow({}));
|
||||
const svc = instanceSettingsService(db, { runtimeEnv: defaultsEnv() });
|
||||
const result = await svc.updateGeneral({ feedbackDataSharingPreference: "not_allowed" });
|
||||
expect(result.general.feedbackDataSharingPreference).toBe("not_allowed");
|
||||
expect(persistedSets).toHaveLength(1);
|
||||
const persistedGeneral = persistedSets[0]!.general as Record<string, unknown>;
|
||||
expect(persistedGeneral.feedbackDataSharingPreference).toBe("not_allowed");
|
||||
});
|
||||
});
|
||||
|
|
@ -39,6 +39,7 @@ import {
|
|||
getManagedInstanceConfig,
|
||||
type ManagedInstanceConfig,
|
||||
} from "./services/managed-config.js";
|
||||
import { getOperatorSettingDefaults } from "./services/setting-defaults.js";
|
||||
import { setupEnvironmentCustomImageTerminalWebSocketServer } from "./realtime/environment-custom-image-terminal-ws.js";
|
||||
import { setupLiveEventsWebSocketServer } from "./realtime/live-events-ws.js";
|
||||
import { setupRunnerPrpWebSocketServer } from "./realtime/runner-prp-ws.js";
|
||||
|
|
@ -689,6 +690,22 @@ export async function startServer(): Promise<StartedServer> {
|
|||
throw err;
|
||||
}
|
||||
|
||||
// Operator setting defaults (PAPERCLIP_SETTING_DEFAULTS). Same fail-closed
|
||||
// posture as the managed-config parse above: malformed JSON or an invalid
|
||||
// value for a known field refuses startup; unknown field names only warn.
|
||||
try {
|
||||
const operatorDefaults = getOperatorSettingDefaults();
|
||||
if (operatorDefaults && Object.keys(operatorDefaults).length > 0) {
|
||||
logger.warn(
|
||||
{ defaultedSettings: Object.keys(operatorDefaults).sort() },
|
||||
"operator setting defaults active",
|
||||
);
|
||||
}
|
||||
} catch (err) {
|
||||
logger.error({ err }, "invalid PAPERCLIP_SETTING_DEFAULTS; refusing to start (fail closed)");
|
||||
throw err;
|
||||
}
|
||||
|
||||
const uiMode = config.uiDevMiddleware ? "vite-dev" : config.serveUi ? "static" : "none";
|
||||
const storageService = createStorageServiceFromConfig(config);
|
||||
const feedback = feedbackService(db as any, {
|
||||
|
|
|
|||
|
|
@ -25,6 +25,7 @@ import { parseOpenCodeJsonl } from "@paperclipai/adapter-opencode-local/server";
|
|||
import {
|
||||
DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE,
|
||||
DEFAULT_FEEDBACK_DATA_SHARING_TERMS_VERSION,
|
||||
applyOperatorGeneralDefaults,
|
||||
instanceGeneralSettingsSchema,
|
||||
type FeedbackTargetType,
|
||||
type FeedbackTraceBundle,
|
||||
|
|
@ -46,6 +47,7 @@ import {
|
|||
sha256Digest,
|
||||
} from "./feedback-redaction.js";
|
||||
import { getRunLogStore } from "./run-log-store.js";
|
||||
import { getOperatorSettingDefaults } from "./setting-defaults.js";
|
||||
|
||||
const FEEDBACK_SCHEMA_VERSION = "paperclip-feedback-envelope-v2";
|
||||
const FEEDBACK_BUNDLE_VERSION = "paperclip-feedback-bundle-v2";
|
||||
|
|
@ -157,10 +159,7 @@ function contentTypeForPath(filePath: string) {
|
|||
function normalizeInstanceGeneralSettings(raw: unknown) {
|
||||
const parsed = instanceGeneralSettingsSchema.safeParse(raw ?? {});
|
||||
if (parsed.success) return parsed.data;
|
||||
return {
|
||||
censorUsernameInLogs: false,
|
||||
feedbackDataSharingPreference: DEFAULT_FEEDBACK_DATA_SHARING_PREFERENCE,
|
||||
};
|
||||
return instanceGeneralSettingsSchema.parse({});
|
||||
}
|
||||
|
||||
function buildIssuePath(identifier: string | null) {
|
||||
|
|
@ -1977,7 +1976,13 @@ export function feedbackService(db: Db, options: FeedbackServiceOptions = {}) {
|
|||
})
|
||||
.then((rows) => rows[0] ?? null));
|
||||
|
||||
const currentGeneral = normalizeInstanceGeneralSettings(currentInstanceSettings?.general);
|
||||
// Operator setting defaults apply to the effective value: when the
|
||||
// operator supplies a feedback-sharing default, the preference is no
|
||||
// longer "prompt", so a stray answer must not persist over it.
|
||||
const currentGeneral = applyOperatorGeneralDefaults(
|
||||
normalizeInstanceGeneralSettings(currentInstanceSettings?.general),
|
||||
getOperatorSettingDefaults(),
|
||||
);
|
||||
if (currentInstanceSettings && currentGeneral.feedbackDataSharingPreference === "prompt") {
|
||||
const nextSharingPreference = sharedWithLabs ? "allowed" : "not_allowed";
|
||||
const currentGeneralRaw = asRecord(currentInstanceSettings.general) ?? {};
|
||||
|
|
|
|||
|
|
@ -28,8 +28,10 @@ import {
|
|||
type PatchInstanceSettings,
|
||||
type PatchInstanceExperimentalSettings,
|
||||
} from "@paperclipai/shared";
|
||||
import { applyOperatorGeneralDefaults, stripOperatorGeneralEchoes } from "@paperclipai/shared";
|
||||
import { eq } from "drizzle-orm";
|
||||
import { getManagedInstanceConfig, type ManagedInstanceConfig } from "./managed-config.js";
|
||||
import { getOperatorSettingDefaults } from "./setting-defaults.js";
|
||||
|
||||
const DEFAULT_SINGLETON_KEY = "default";
|
||||
const instanceGeneralSettingsStorageSchema = instanceGeneralSettingsSchema.strip();
|
||||
|
|
@ -328,6 +330,15 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
|
|||
// Fail closed: a malformed PAPERCLIP_MANAGED_CONFIG throws here (and at
|
||||
// boot in index.ts) rather than silently running without the overlay.
|
||||
const managedConfig = getManagedInstanceConfig(options.runtimeEnv ?? process.env);
|
||||
// Same posture for PAPERCLIP_SETTING_DEFAULTS: parsed once, applied per
|
||||
// read, never persisted (see applyOperatorGeneralDefaults) — including on
|
||||
// the write path, where a full-GET echo of the overlaid value is stripped
|
||||
// back to the schema default (see stripOperatorGeneralEchoes).
|
||||
const operatorDefaults = getOperatorSettingDefaults(options.runtimeEnv ?? process.env);
|
||||
|
||||
function toGeneralView(raw: unknown): InstanceGeneralSettings {
|
||||
return applyOperatorGeneralDefaults(normalizeGeneralSettings(raw), operatorDefaults);
|
||||
}
|
||||
|
||||
function toExperimentalView(raw: unknown): InstanceExperimentalSettingsWithManaged {
|
||||
const { experimental, managedKeys } = applyManagedExperimentalOverlay(
|
||||
|
|
@ -342,7 +353,7 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
|
|||
return {
|
||||
id: row.id,
|
||||
defaultEnvironmentId: row.defaultEnvironmentId ?? null,
|
||||
general: normalizeGeneralSettings(row.general),
|
||||
general: toGeneralView(row.general),
|
||||
experimental: toExperimentalView(row.experimental),
|
||||
createdAt: row.createdAt,
|
||||
updatedAt: row.updatedAt,
|
||||
|
|
@ -415,7 +426,7 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
|
|||
|
||||
getGeneral: async (): Promise<InstanceGeneralSettings> => {
|
||||
const row = await getOrCreateRow();
|
||||
return normalizeGeneralSettings(row.general);
|
||||
return toGeneralView(row.general);
|
||||
},
|
||||
|
||||
getExperimental: async (): Promise<InstanceExperimentalSettingsWithManaged> => {
|
||||
|
|
@ -425,10 +436,15 @@ export function instanceSettingsService(db: Db, options: InstanceSettingsService
|
|||
|
||||
updateGeneral: async (patch: PatchInstanceGeneralSettings): Promise<InstanceSettings> => {
|
||||
const current = await getOrCreateRow();
|
||||
const nextGeneral = normalizeGeneralSettings({
|
||||
...normalizeGeneralSettings(current.general),
|
||||
...patch,
|
||||
});
|
||||
const storedGeneral = normalizeGeneralSettings(current.general);
|
||||
// A full-GET echo carries the overlaid operator value for a field the
|
||||
// user never chose; stripping it keeps the overlay strictly read-time,
|
||||
// so changing or unsetting the variable later still takes effect.
|
||||
const nextGeneral = stripOperatorGeneralEchoes(
|
||||
storedGeneral,
|
||||
normalizeGeneralSettings({ ...storedGeneral, ...patch }),
|
||||
operatorDefaults,
|
||||
);
|
||||
const now = new Date();
|
||||
const [updated] = await db
|
||||
.update(instanceSettings)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,40 @@
|
|||
import {
|
||||
SETTING_DEFAULTS_ENV_KEY,
|
||||
parseSettingDefaults,
|
||||
type OperatorSettingDefaults,
|
||||
} from "@paperclipai/shared";
|
||||
import { logger } from "../middleware/logger.js";
|
||||
|
||||
export { SETTING_DEFAULTS_ENV_KEY };
|
||||
|
||||
export type SettingDefaultsEnv = Record<string, string | undefined>;
|
||||
|
||||
let cache: { raw: string | undefined; defaults: OperatorSettingDefaults | null } | null = null;
|
||||
|
||||
/**
|
||||
* Operator setting defaults from the `PAPERCLIP_SETTING_DEFAULTS` env var
|
||||
* (JSON object validated against the shared registry). Parse-once accessor
|
||||
* keyed on the raw value, mirroring settings-visibility.ts: tests passing a
|
||||
* custom env re-parse when the raw value differs; process.env callers share
|
||||
* one parse for the process lifetime.
|
||||
*
|
||||
* Unknown field names are warned about once and ignored (mixed-version fleet
|
||||
* safe). Malformed JSON or an invalid value for a known field throws — policy
|
||||
* configuration fails closed, and index.ts calls this at boot so the failure
|
||||
* is loud and immediate.
|
||||
*/
|
||||
export function getOperatorSettingDefaults(
|
||||
env: SettingDefaultsEnv = process.env,
|
||||
): OperatorSettingDefaults | null {
|
||||
const raw = env[SETTING_DEFAULTS_ENV_KEY];
|
||||
if (cache && cache.raw === raw) return cache.defaults;
|
||||
const { defaults, unknown } = parseSettingDefaults(raw);
|
||||
if (unknown.length > 0) {
|
||||
logger.warn(
|
||||
{ unknownKeys: unknown },
|
||||
`${SETTING_DEFAULTS_ENV_KEY} contains unknown fields; they are ignored`,
|
||||
);
|
||||
}
|
||||
cache = { raw, defaults };
|
||||
return cache.defaults;
|
||||
}
|
||||
Loading…
Reference in New Issue