settings_status

Instructions

Implementation Reference

• scripts/tool-registry.js:988-995 (schema)

  Schema definition for the settings_status tool - a read-only tool with no inputs that resolves settings layers with origin metadata.

  readOnlyTool({
    name: 'settings_status',
    description: 'Resolve managed, user, project, and local ThumbGate settings with per-field origin metadata for policy visibility.',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  }),

• scripts/settings-hierarchy.js:194-204 (handler)

  The main handler function that resolves settings hierarchy and returns active layers, origin summary, per-field origins, file paths, resolved settings, and warnings.

  function getSettingsStatus(options = {}) {
    const hierarchy = resolveSettingsHierarchy(options);
    return {
      activeLayers: hierarchy.activeLayers,
      originSummary: hierarchy.originSummary,
      origins: hierarchy.origins,
      paths: hierarchy.paths,
      resolvedSettings: hierarchy.resolvedSettings,
      warnings: hierarchy.warnings,
    };
  }

• scripts/settings-hierarchy.js:120-184 (handler)

  Core settings resolution logic: merges settings from defaults, managed, user, project, and local files in priority order, tracking the origin of each setting.

  function resolveSettingsHierarchy(options = {}) {
    const paths = resolveSettingsPaths(options);
    let settings = cloneValue(DEFAULT_SETTINGS);
    const originsByPath = Object.fromEntries(
      flattenLeafValues(DEFAULT_SETTINGS).map(([settingPath, value]) => [
        settingPath,
        {
          scope: 'defaults',
          sourcePath: null,
          value,
        },
      ]),
    );
  
    const activeLayers = [
      {
        scope: 'defaults',
        sourcePath: null,
        exists: true,
        leafCount: flattenLeafValues(DEFAULT_SETTINGS).length,
      },
    ];
  
    for (const scope of SETTINGS_SCOPE_ORDER.slice(1)) {
      const sourcePath = paths[scope];
      const data = readJsonObject(sourcePath);
      const exists = Boolean(data);
      activeLayers.push({
        scope,
        sourcePath,
        exists,
        leafCount: exists ? flattenLeafValues(data).length : 0,
      });
  
      if (!exists) {
        continue;
      }
  
      settings = mergeSettings(settings, data);
      for (const [settingPath, value] of flattenLeafValues(data)) {
        originsByPath[settingPath] = {
          scope,
          sourcePath,
          value,
        };
      }
    }
  
    const warnings = activeLayers
      .filter((layer) => !layer.exists && layer.scope !== 'defaults')
      .map((layer) => `No ${layer.scope} settings file at ${layer.sourcePath}`);
  
    return {
      resolvedSettings: settings,
      settings,
      originsByPath,
      origins: Object.entries(originsByPath)
        .sort((a, b) => a[0].localeCompare(b[0]))
        .map(([settingPath, origin]) => ({ path: settingPath, ...origin })),
      activeLayers,
      originSummary: summarizeOrigins(originsByPath),
      warnings,
      paths,
    };
  }

• scripts/settings-hierarchy.js:88-98 (helper)

  Helper that resolves the file paths for each settings layer (managed, user, project, local).

  function resolveSettingsPaths(options = {}) {
    const projectRoot = options.projectRoot || PROJECT_ROOT;
    const homeDir = options.homeDir || process.env.HOME || os.homedir();
  
    return {
      managed: path.join(projectRoot, 'config', 'thumbgate-settings.managed.json'),
      user: path.join(homeDir, '.thumbgate', 'settings.json'),
      project: path.join(projectRoot, '.thumbgate', 'settings.json'),
      local: path.join(projectRoot, '.thumbgate', 'settings.local.json'),
    };
  }

• adapters/mcp/server-stdio.js:978-979 (registration)

  Registration in the MCP server dispatch - maps the 'settings_status' case to a call to getSettingsStatus() with no arguments.

  case 'settings_status':
    return toTextResult(getSettingsStatus());