feat(settings): edit any scopable setting as a project override#10639

@@ -98,33 +104,83 @@ function SettingsTargetBar() {
 
 function SettingsScopeBoundary({ pathname, children }: { pathname: string; children: ReactNode }) {
   const { scope, search, connectedEnvironments } = useSettingsScope();
+  const { environments } = useEnvironments();
+  const hash = useLocation({ select: (location) => location.hash });
+  const searchTarget = getSettingsSearchTargetScope(hash);
+  const autoSettlementAvailability = searchTarget?.requiresThreadAutoSettlement
+    ? getThreadAutoSettlementSearchAvailability(environments, scope)
+    : null;
+  if (
+    scope.kind !== "unavailable" &&
+    searchTarget &&
+    autoSettlementAvailability &&
+    !autoSettlementAvailability.isTargetAvailable
+  ) {
+    return (
+      <SettingsScopeNotice
+        target="environment"
+        targetId={hash}
+        eligibleEnvironmentIds={autoSettlementAvailability.eligibleEnvironmentIds}
+      >
+        {autoSettlementAvailability.eligibleEnvironmentIds.length > 0
+          ? `${searchTarget.title} requires a supporting environment. Choose one to continue.`
+          : `${searchTarget.title} requires a supporting environment. Connect or update an environment to continue.`}
+      </SettingsScopeNotice>
+    );
+  }
+  if (
+    scope.kind !== "unavailable" &&
+    searchTarget &&
+    !isSettingsSearchScopeAvailable(searchTarget.scope, scope.kind)
+  ) {
+    const target =
+      searchTarget.scope === "environment-defaults" ||
+      searchTarget.scope === "project-defaults" ||
+      searchTarget.scope === "connections"
+        ? "all"
+        : searchTarget.scope;
+    return (
+      <SettingsScopeNotice target={target} targetId={hash}>
+        {`${searchTarget.title} is not available for the selected target. Choose its owning scope to continue.`}
+      </SettingsScopeNotice>
+    );
+  }
   if (pathname === "/settings/snap-shot" && scope.kind !== "device") {
     return (
       <SettingsScopeNotice target="device">
         SnapShots are configured on this device.
       </SettingsScopeNotice>
     );
   }
+  const projectCategory: ProjectSettingsCategory | null =
+    pathname === "/settings/general"
+      ? "general"
+      : pathname === "/settings/integrations"
+        ? "integrations"
+        : pathname === "/settings/source-control"
+          ? "source-control"
+          : pathname === "/settings/actions"
+            ? "actions"
+            : pathname === "/settings/projects"
+              ? "overview"
+              : null;
   // Keep the project editor mounted while a grouping change replaces its URL key.
   if (pathname === "/settings/projects" || pathname === "/settings/connections") return children;
+  if (search.project && scope.kind !== "all" && scope.kind !== "device" && projectCategory)
+    return <ProjectsSettings category={projectCategory} />;

@@ -35,10 +66,14 @@ export function SettingsScopeNotice({
           <AlertAction className="flex-wrap gap-2">
             {choices.map((choice) => (
               <Button
-                key={choice.label}
+                key={JSON.stringify(choice.search)}
                 size="sm"
                 variant="outline"
-                onClick={() => selectScope(choice.search)}
+                className="h-auto max-w-full whitespace-normal break-all text-left"

@@ -573,6 +638,144 @@ export type SettingsSearchItemId = (typeof SETTINGS_SEARCH_ITEMS)[number]["id"];
 
 const SEARCH_ITEMS_BY_ID = new Map(SETTINGS_SEARCH_ITEMS.map((item) => [item.id, item] as const));
 
+const SETTINGS_CATEGORY_SCOPES: Readonly<Record<SettingsPath, SettingsSearchScope>> = {
+  "/settings/projects": "project",
+  "/settings/general": "device",
+  "/settings/appearance": "device",
+  "/settings/snap-shot": "device",
+  "/settings/keybindings": "environment",
+  "/settings/providers": "environment",
+  "/settings/integrations": "device",
+  "/settings/source-control": "environment-defaults",
+  "/settings/actions": "project-defaults",
+  "/settings/connections": "connections",
+  "/settings/archived": "project-defaults",
+};
+
+/** Search keeps the selected target. A missing row can explain its owning scope instead. */
+export function getSettingsSearchTargetScope(targetId: string) {
+  const items: readonly SettingsSearchItem[] = SETTINGS_SEARCH_ITEMS;
+  const item =
+    items.find((candidate) => candidate.id === targetId) ??
+    items.find((candidate) => candidate.targetId === targetId);

@@ -573,6 +638,144 @@ export type SettingsSearchItemId = (typeof SETTINGS_SEARCH_ITEMS)[number]["id"];
 
 const SEARCH_ITEMS_BY_ID = new Map(SETTINGS_SEARCH_ITEMS.map((item) => [item.id, item] as const));
 
+const SETTINGS_CATEGORY_SCOPES: Readonly<Record<SettingsPath, SettingsSearchScope>> = {
+  "/settings/projects": "project",
+  "/settings/general": "device",
+  "/settings/appearance": "device",
+  "/settings/snap-shot": "device",
+  "/settings/keybindings": "environment",
+  "/settings/providers": "environment",
+  "/settings/integrations": "device",
+  "/settings/source-control": "environment-defaults",
+  "/settings/actions": "project-defaults",
+  "/settings/connections": "connections",
+  "/settings/archived": "project-defaults",
+};
+
+/** Search keeps the selected target. A missing row can explain its owning scope instead. */
+export function getSettingsSearchTargetScope(targetId: string) {
+  const items: readonly SettingsSearchItem[] = SETTINGS_SEARCH_ITEMS;
+  const item =
+    items.find((candidate) => candidate.id === targetId) ??
+    items.find((candidate) => candidate.targetId === targetId);
+  return item
+    ? { title: item.title, scope: item.scope ?? SETTINGS_CATEGORY_SCOPES[item.to] }
+    : null;
+}
+
+export function isSettingsSearchScopeAvailable(
+  requiredScope: SettingsSearchScope,
+  scopeKind: ResolvedSettingsScope["kind"],
+): boolean {
+  switch (requiredScope) {
+    case "connections":
+      return true;
+    case "device":
+    case "environment":
+    case "checkout":
+      return requiredScope === scopeKind;
+    case "project":
+      return scopeKind === "project" || scopeKind === "checkout";
+    case "environment-defaults":
+      return scopeKind === "environment" || scopeKind === "all";
+    case "project-defaults":
+      return (
+        scopeKind === "environment" ||
+        scopeKind === "all" ||
+        scopeKind === "project" ||
+        scopeKind === "checkout"
+      );
+  }
+}
+
+function settingsScopeKindFromSearch(search: SettingsScopeSearch): ResolvedSettingsScope["kind"] {
+  const target = validateSettingsScopeSearch({ ...search });
+  if (target.scope) return target.scope;
+  if (target.checkout && !target.project) return "unavailable";
+  if (target.project) return target.checkout ? "checkout" : "project";
+  return target.machine ? "environment" : "device";
+}
+
+export function isSettingsOverviewVisible(search: SettingsScopeSearch): boolean {
+  const kind = settingsScopeKindFromSearch(search);
+  return kind === "project" || kind === "checkout";
+}
+
+type SettingsPageSection = { readonly label: string; readonly targetId: string };
+
+/** The sidebar lives outside the scope provider, so its sections follow the URL target. */
+export function settingsPageSections(
+  path: SettingsPath,
+  search: SettingsScopeSearch,
+  {
+    hasThreadAutoSettlement = true,
+    hasConnectedEnvironment = true,
+  }: { hasThreadAutoSettlement?: boolean; hasConnectedEnvironment?: boolean } = {},
+): readonly SettingsPageSection[] {
+  const kind = settingsScopeKindFromSearch(search);

@@ -4,33 +4,68 @@ import { SettingsPageContainer } from "./settingsLayout";
 import { useSettingsScope } from "./SettingsScopeContext";
 import { useEnvironments } from "../../state/environments";
 import type { SettingsScopeSearch } from "./settingsScope";
+import { useSettingsProjectGroups } from "./useSettingsProjectGroups";
+import { useNavigate } from "@tanstack/react-router";
+import type { EnvironmentId } from "@t3tools/contracts";
 
 /** Offer an explicit target change when a category has no settings at this scope. */
 export function SettingsScopeNotice({
   children,
   target,
+  targetId,
+  eligibleEnvironmentIds,
 }: {
   children: string;
-  target: "device" | "environment" | "all";
+  target: "device" | "environment" | "all" | "project" | "checkout";
+  targetId?: string;
+  eligibleEnvironmentIds?: readonly EnvironmentId[];
 }) {
-  const { selectScope } = useSettingsScope();
+  const { selectScope, search } = useSettingsScope();
+  const navigate = useNavigate({ from: "/settings" });
   const { environments } = useEnvironments();
+  const groups = useSettingsProjectGroups();
   const choices: { label: string; search: SettingsScopeSearch }[] =
-    target === "environment"
-      ? environments.map((entry) => ({
-          label: environments.some(
-            (other) => other.environmentId !== entry.environmentId && other.label === entry.label,
+    target === "checkout"
+      ? groups
+          .filter((group) => !search.project || group.projectKey === search.project)
+          .flatMap((group) =>
+            group.memberProjects.map((member) => ({
+              label: `${group.displayName} · ${member.environmentLabel} · ${member.workspaceRoot}`,

@@ -41,16 +37,11 @@ export function useAvailableSettingsSearchItems() {
           state: desktopWsl.data,
           error: desktopWsl.error,
         }),
-        hasThreadAutoSettlement:
-          primaryServerConfig?.environment.capabilities.threadAutoSettlement === true,
+        hasThreadAutoSettlement: environments.some(
+          (environment) =>
+            environment.serverConfig?.environment.capabilities.threadAutoSettlement === true,
+        ),

@@ -0,0 +1,48 @@
+import type { ThreadEnvMode } from "@t3tools/contracts";
+
+export interface ProjectSettingSourceEntry {
+  key: string;
+  label: string;
+  value: string;
+  source: string;
+  overridden: boolean;
+  defaultValue?: string;
+}
+
+export function summarizeProjectSettingSources(entries: readonly ProjectSettingSourceEntry[]) {
+  const overrideCount = entries.filter((entry) => entry.overridden).length;
+  if (entries.length === 1) return entries[0]!.source;
+  if (entries.some((entry) => entry.source === "Unavailable")) return "Some sources unavailable";
+  if (overrideCount === 0) return "Inherited per checkout";
+  if (overrideCount === entries.length) return `Overridden in ${overrideCount} checkouts`;
+  return `${overrideCount} overridden · ${entries.length - overrideCount} inherited`;
+}
+
+export function resolveProjectBooleanSource(
+  override: boolean | undefined,
+  environmentDefault: boolean | undefined,
+  legacyOverride = false,
+) {
+  return {
+    value: override ?? (legacyOverride ? true : environmentDefault),
+    overridden: override !== undefined || legacyOverride,
+  };
+}
+
+export function resolveProjectWorkspaceSource(input: {
+  override: ThreadEnvMode | null;
+  environmentDefault: ThreadEnvMode | undefined;
+  repositoryDefault: ThreadEnvMode | null;
+  repositoryResolved: boolean;
+}) {
+  if (input.override !== null) {
+    return { value: input.override, source: "Project override", overridden: true };
+  }
+  if (!input.repositoryResolved) {
+    return { value: undefined, source: "t3.json or environment default", overridden: false };
+  }
+  if (input.repositoryDefault !== null) {
+    return { value: input.repositoryDefault, source: "t3.json", overridden: false };
+  }
+  return { value: input.environmentDefault, source: "Environment default", overridden: false };