PaperClipAI/packages/shared/src/settings-visibility.ts

import { INSTANCE_FEATURE_KEYS, type InstanceFeatureKey } from "./feature-catalog.js";

/**
 * Operator-configurable settings visibility.
 *
 * A hosting operator (a managed cloud, an internal shared server) can hide
 * settings surfaces that do not apply to their deployment by setting the
 * `PAPERCLIP_HIDDEN_SETTINGS` environment variable to a comma-separated
 * list of keys from this registry. An experimental wildcard with named
 * exceptions can also hide future controls automatically. Hiding a surface removes it from the UI
 * (nav, routes, page sections). Surfaces backed by instance-level mutation
 * routes are also floored with a 403 carrying
 * `SETTINGS_OPERATOR_MANAGED_ERROR_CODE`: the Access, Plugins, and Adapters
 * pages, every field-backed General section, every experimental toggle
 * (individually or via the whole Experimental page), and the company Import
 * page (whose whole route surface is floored). The other company pages are
 * UI-visibility keys only: their APIs (memberships, invites, secrets,
 * exports) stay live for agents and integrations.
 *
 * Nothing is hidden by default: with the variable unset, UI and API behave
 * exactly as before this mechanism existed.
 *
 * Unknown keys are ignored (with a server-side warning) rather than rejected,
 * so an operator may roll one list across a fleet of mixed app versions: an
 * image that predates a key simply keeps that surface visible instead of
 * refusing to boot.
 */

/**
 * Instance settings pages that can be hidden (nav entry + route). The General
 * page is deliberately not hideable: it is the settings root and the redirect
 * target for hidden pages. Individual General sections are hideable below.
 */
export const HIDEABLE_INSTANCE_PAGES = [
  "instance.profile",
  "instance.environments",
  "instance.access",
  "instance.experimental",
  "instance.plugins",
  "instance.adapters",
] as const;

export type HideableInstancePage = (typeof HIDEABLE_INSTANCE_PAGES)[number];

/**
 * Company-level settings pages that can be hidden (nav entry + tab + route).
 * The company General page is deliberately not hideable: it is the settings
 * root and the redirect target for hidden pages. `company.import` also floors
 * the import API routes; the rest only hide UI surfaces.
 */
export const HIDEABLE_COMPANY_PAGES = [
  "company.members",
  "company.invites",
  "company.secrets",
  "company.export",
  "company.import",
] as const;

export type HideableCompanyPage = (typeof HIDEABLE_COMPANY_PAGES)[number];

/**
 * Sub-surfaces of company settings pages that can be hidden individually.
 * UI-visibility keys only: the backing APIs stay live for agents and
 * integrations. Hiding the whole page (`company.secrets`) already removes
 * everything inside it; these keys hide one tab while the page stays up.
 */
export const HIDEABLE_COMPANY_SECTIONS = [
  "company.secrets.vaults",
  "company.secrets.proposals",
] as const;

export type HideableCompanySection = (typeof HIDEABLE_COMPANY_SECTIONS)[number];

/**
 * Sections of Instance → General that can be hidden. Field-backed sections
 * (their suffix names a general-settings field) also floor writes to that
 * field; `deploymentStatus` and `signOut` are read-only UI with no field.
 */
export const HIDEABLE_GENERAL_SECTIONS = [
  "instance.general.deploymentStatus",
  "instance.general.censorUsernameInLogs",
  "instance.general.backupRetention",
  "instance.general.feedbackDataSharingPreference",
  "instance.general.signOut",
] as const;

export type HideableGeneralSection = (typeof HIDEABLE_GENERAL_SECTIONS)[number];

/** General sections that are informational UI only, with no settings field. */
export const UI_ONLY_GENERAL_SECTIONS = [
  "instance.general.deploymentStatus",
  "instance.general.signOut",
] as const satisfies readonly HideableGeneralSection[];

export type HideableExperimentalSetting = `instance.experimental.${InstanceFeatureKey}`;

/** The visibility key for an experimental toggle; every boolean flag is hideable. */
export function experimentalSettingKey(key: InstanceFeatureKey): HideableExperimentalSetting {
  return `instance.experimental.${key}`;
}

/** Workspace policy editors and selectors. UI-only; execution and APIs stay active. */
export const HIDEABLE_WORKSPACE_SECTIONS = ["workspaces.isolation"] as const;
export type HideableWorkspaceSection = (typeof HIDEABLE_WORKSPACE_SECTIONS)[number];

export type HideableSettingKey =
  | HideableWorkspaceSection
  | HideableInstancePage
  | HideableCompanyPage
  | HideableCompanySection
  | HideableGeneralSection
  | HideableExperimentalSetting;

/** Concrete setting keys; the parser also accepts the experimental wildcard and exceptions. */
export const HIDEABLE_SETTING_KEYS: readonly HideableSettingKey[] = [
  ...HIDEABLE_WORKSPACE_SECTIONS,
  ...HIDEABLE_INSTANCE_PAGES,
  ...HIDEABLE_COMPANY_PAGES,
  ...HIDEABLE_COMPANY_SECTIONS,
  ...HIDEABLE_GENERAL_SECTIONS,
  ...INSTANCE_FEATURE_KEYS.map(experimentalSettingKey),
];

/** Stable 403 code for writes to operator-hidden settings. */
export const SETTINGS_OPERATOR_MANAGED_ERROR_CODE = "settings_operator_managed";

/** Hide current and future experimental controls, with optional !key exceptions. */
export const EXPERIMENTAL_SETTINGS_WILDCARD = "instance.experimental.*";

export interface ParsedHiddenSettings {
  /** Concrete keys, deduplicated; wildcard-derived keys follow in catalog order. */
  hidden: HideableSettingKey[];
  /** Unrecognized entries, for the caller to warn about. */
  unknown: string[];
}

/**
 * Parse operator settings into concrete keys for both the UI and API.
 * `instance.experimental.*` hides every catalog control except entries such as
 * `!instance.experimental.enableEnvironments`. Exceptions only affect the
 * wildcard; an explicit hidden key or hidden parent page always wins.
 */
export function parseHiddenSettingsList(raw: string | undefined): ParsedHiddenSettings {
  const hidden: HideableSettingKey[] = [];
  const unknown: string[] = [];
  if (!raw) return { hidden, unknown };
  const known = new Set<string>(HIDEABLE_SETTING_KEYS);
  const seen = new Set<string>();
  const exceptions = new Set<string>();
  let hideExperimental = false;
  for (const part of raw.split(",")) {
    const key = part.trim();
    if (!key || seen.has(key)) continue;
    seen.add(key);
    if (key === EXPERIMENTAL_SETTINGS_WILDCARD) {
      hideExperimental = true;
    } else if (key.startsWith("!instance.experimental.") && known.has(key.slice(1))) {
      exceptions.add(key.slice(1));
    } else if (known.has(key)) {
      hidden.push(key as HideableSettingKey);
    } else {
      unknown.push(key);
    }
  }
  if (hideExperimental) {
    for (const feature of INSTANCE_FEATURE_KEYS) {
      const key = experimentalSettingKey(feature);
      if (!exceptions.has(key) && !seen.has(key)) hidden.push(key);
    }
  }
  return { hidden, unknown };
}

export function hidesInstancePage(
  hidden: ReadonlySet<string>,
  page: HideableInstancePage,
): boolean {
  return hidden.has(page);
}

export function hidesCompanyPage(
  hidden: ReadonlySet<string>,
  page: HideableCompanyPage,
): boolean {
  return hidden.has(page);
}

export function hidesCompanySection(
  hidden: ReadonlySet<string>,
  section: HideableCompanySection,
): boolean {
  return hidden.has(section);
}

export function hidesGeneralSection(
  hidden: ReadonlySet<string>,
  section: HideableGeneralSection,
): boolean {
  return hidden.has(section);
}

/**
 * Whether a toggle is hidden, either individually or because the whole
 * Experimental page is hidden.
 */
export function hidesExperimentalSetting(
  hidden: ReadonlySet<string>,
  key: InstanceFeatureKey,
): boolean {
  return hidden.has("instance.experimental") || hidden.has(experimentalSettingKey(key));
}