@karmaniverous/jeeves
    Preparing search index...

    Function createConfigApplyHandler

    • Create a framework-agnostic config apply handler.

      Parameters

      • descriptor: {
            configFileName: string;
            configSchema: ZodType<
                unknown,
                unknown,
                $ZodTypeInternals<unknown, unknown>,
            >;
            customCliCommands?: $InferOuterFunctionType<
                ZodTuple<
                    readonly [ZodCustom<Command<[], {}, {}>, Command<[], {}, {}>>],
                    null,
                >,
                ZodVoid,
            >;
            customMerge?: $InferOuterFunctionType<
                ZodTuple<
                    readonly [
                        ZodRecord<ZodString, ZodUnknown>,
                        ZodRecord<ZodString, ZodUnknown>,
                    ],
                    null,
                >,
                ZodRecord<ZodString, ZodUnknown>,
            >;
            customPluginTools?: $InferOuterFunctionType<
                ZodTuple<readonly [ZodCustom<PluginApi, PluginApi>], null>,
                ZodArray<ZodUnknown>,
            >;
            defaultPort: number;
            initTemplate: $InferOuterFunctionType<
                ZodTuple<readonly [], null>,
                ZodRecord<ZodString, ZodUnknown>,
            >;
            name: string;
            onConfigApply?: $InferOuterFunctionType<
                ZodTuple<readonly [ZodRecord<ZodString, ZodUnknown>], null>,
                ZodPromise<ZodVoid>,
            >;
            pluginPackage: string;
            run: $InferOuterFunctionType<
                ZodTuple<readonly [ZodString], null>,
                ZodPromise<ZodVoid>,
            >;
            serviceName?: string;
            servicePackage: string;
            startCommand: $InferOuterFunctionType<
                ZodTuple<readonly [ZodString], null>,
                ZodArray<ZodString>,
            >;
            version: string;
        }

        The component descriptor.

        • configFileName: string

          Config file name (e.g., 'jeeves-watcher.config.json').

        • configSchema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

          Zod schema for validating config files.

        • OptionalcustomCliCommands?: $InferOuterFunctionType<
              ZodTuple<
                  readonly [ZodCustom<Command<[], {}, {}>, Command<[], {}, {}>>],
                  null,
              >,
              ZodVoid,
          >

          Extension point: add custom CLI commands to the service CLI.

        • OptionalcustomMerge?: $InferOuterFunctionType<
              ZodTuple<
                  readonly [
                      ZodRecord<ZodString, ZodUnknown>,
                      ZodRecord<ZodString, ZodUnknown>,
                  ],
                  null,
              >,
              ZodRecord<ZodString, ZodUnknown>,
          >

          Custom merge function for config apply. Receives the existing config and the patch, returns the merged result. Optional — if omitted, the default deep-merge (object-recursive, array-replacing) is used.

          Use this to implement domain-specific merge strategies such as name-based array merging for inference rules.

        • OptionalcustomPluginTools?: $InferOuterFunctionType<
              ZodTuple<readonly [ZodCustom<PluginApi, PluginApi>], null>,
              ZodArray<ZodUnknown>,
          >

          Extension point: return additional plugin tool descriptors.

        • defaultPort: number

          Default port for the service's HTTP API.

        • initTemplate: $InferOuterFunctionType<
              ZodTuple<readonly [], null>,
              ZodRecord<ZodString, ZodUnknown>,
          >

          Returns a default config object for init.

        • name: string

          Component name (e.g., 'watcher', 'runner', 'server', 'meta').

        • OptionalonConfigApply?: $InferOuterFunctionType<
              ZodTuple<readonly [ZodRecord<ZodString, ZodUnknown>], null>,
              ZodPromise<ZodVoid>,
          >

          Service-side callback after config apply. Receives the merged, validated config (not the raw patch). Optional — if omitted, write-only (service picks up changes on restart).

        • pluginPackage: string

          npm package name for the plugin.

        • run: $InferOuterFunctionType<
              ZodTuple<readonly [ZodString], null>,
              ZodPromise<ZodVoid>,
          >

          In-process service entry point for the CLI start command.

        • OptionalserviceName?: string

          System service name. Defaults to jeeves-${name} when not provided.

        • servicePackage: string

          npm package name for the service.

        • startCommand: $InferOuterFunctionType<
              ZodTuple<readonly [ZodString], null>,
              ZodArray<ZodString>,
          >

          Returns command + args for launching the service process. Consumed by service install.

        • version: string

          Component version (from package.json).

      • OptionalconfigPath: string

        Optional explicit config file path. When provided, takes precedence over registered and derived paths.

      Returns ConfigApplyHandler

      An async handler returning { status, body }.

      The handler:

      1. Reads the raw config from {configRoot}/jeeves-{name}/{configFileName} (an unreadable file fails with 500 and is left untouched)
      2. Deep-merges the patch into it (or replaces it if replace: true)
      3. Validates the merged object against descriptor.configSchema
      4. Writes the merged object (not the schema's parsed output) atomically, keeping the existing file mode (0600 for a new file)
      5. Calls descriptor.onConfigApply with the validated (parsed) config

      The response config is the validated (parsed) config, as before.

    Settings
    Member Visibility