@homer0/pi-config 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@homer0/pi-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Config management building block for Pi",
+  "author": "Leonardo Apiwan (@homer0) <me@homer0.com>",
+  "license": "MIT",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "config"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/homer0/packages.git",
+    "directory": "packages/public/pi-config"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "files": [
+    "dist/",
+    "src/",
+    "!src/**/*.test.ts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extensions/config.js"
+    ]
+  },
+  "dependencies": {
+    "@homer0/object-utils": "^6.0.7",
+    "yaml": "2.9.1",
+    "zod": "4.6.7"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">1.0.0",
+    "@earendil-works/pi-tui": ">1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "catalog:",
+    "@earendil-works/pi-tui": "catalog:",
+    "@homer0/oxlint-config": "workspace:*",
+    "@homer0/tsconfig": "workspace:*",
+    "@types/node": "catalog:",
+    "@vitest/coverage-v8": "catalog:",
+    "tsdown": "catalog:",
+    "oxlint": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  },
+  "scripts": {
+    "lint": "oxlint .",
+    "lint:all": "oxlint .",
+    "lint:file": "oxlint $@",
+    "test": "vitest run $@",
+    "types:check": "tsc --noEmit",
+    "build": "tsdown",
+    "prepublishOnly": "pnpm run build"
+  }
+}

package/src/errors.ts

@@ -0,0 +1,35 @@
+/* eslint-disable max-classes-per-file -- The config errors live together. */
+import type { z } from 'zod';
+
+/** The error for the config files that couldn't be read or parsed. */
+export class ConfigReadError extends Error {
+  /** The path of the config file that failed. */
+  readonly filePath: string;
+
+  /**
+   * @param message The description of what failed.
+   * @param filePath The path of the config file that failed.
+   * @param options The error options, to preserve the original `cause`.
+   */
+  constructor(message: string, filePath: string, options?: ErrorOptions) {
+    super(message, options);
+    this.filePath = filePath;
+    this.name = 'ConfigReadError';
+  }
+}
+
+/** The error thrown when the resolved config doesn't match the schema that was provided. */
+export class ConfigValidationError extends Error {
+  /** The Zod issues that explain why the value didn't match the schema. */
+  readonly issues: z.core.$ZodIssue[];
+
+  /**
+   * @param message The description of what failed.
+   * @param issues The Zod issues that explain why the value didn't match the schema.
+   */
+  constructor(message: string, issues: z.core.$ZodIssue[]) {
+    super(message);
+    this.issues = issues;
+    this.name = 'ConfigValidationError';
+  }
+}

package/src/extensions/config.ts

@@ -0,0 +1,238 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Text } from '@earendil-works/pi-tui';
+import { z } from 'zod';
+import { formatValuePreview, getQueryLabel, getUsedSourceCount } from '../format.js';
+import {
+  getConfigParamsSchema,
+  setConfigParamsSchema,
+  type GetConfigParams,
+  type SetConfigParams,
+} from '../schemas.js';
+import type { ConfigQuery, SetConfigDetails } from '../types.js';
+
+/** Module shape of the lazily loaded handlers. */
+type HandlersModule = typeof import('../handlers.js');
+
+/** The promise of the handlers module, shared by every call once it's been requested. */
+let handlersModule: Promise<HandlersModule> | undefined;
+
+/**
+ * Lazy-loads all the handlers through a single shared `import()`. Tools can be called in
+ * parallel by the model, and jiti evaluates lazily loaded modules asynchronously, handing
+ * partial exports to any `import()` of a module (or of a dependency shared by several
+ * handlers) that is still evaluating. Loading everything through one memoized promise
+ * makes overlapping calls wait for the same evaluation. A failed load is not cached, so
+ * the next call retries.
+ *
+ * @returns The module with all the handlers.
+ */
+const loadHandlers = (): Promise<HandlersModule> => {
+  handlersModule ??= import('../handlers.js').catch((error: unknown) => {
+    handlersModule = undefined;
+    throw error;
+  });
+  return handlersModule;
+};
+
+/** Tool definition for reading resolved Pi Core config. */
+const getConfigTool: Parameters<ExtensionAPI['registerTool']>[0] = {
+  name: 'get_config',
+  label: 'Get Config',
+  description:
+    'Read resolved Pi Core config from config.json and config.local.json for local extensions, tools, and skills that explicitly use this convention.',
+  promptSnippet:
+    'Use get_config only when a tool, skill, or extension explicitly calls for Pi Core config.',
+  promptGuidelines: [
+    'Call get_config only when a tool, skill, or extension explicitly calls for Pi Core config.',
+    'Do not infer or guess config support from package names or behavior.',
+    'Prefer the narrowest lookup: path first, then pi or named skill/tool/extension, then namespace, and full config only when necessary.',
+    "Use scope: 'pi' for general Pi/session/agent settings, for example { scope: 'pi' }.",
+    "Use scope: 'skill' with name for local skill preferences, for example { scope: 'skill', name: 'commit' }.",
+    "Use scope: 'tool' with name for local tool defaults, for example { scope: 'tool', name: 'bash' }.",
+    "Use scope: 'extension' with name for local extension settings, for example { scope: 'extension', name: 'config' }.",
+    'Do not expose config values to the user unless necessary for the answer or requested by the user.',
+    'Treat missing config as absence of preference, not as an error.',
+    'Ask the user before relying on unclear or conflicting config.',
+  ],
+  parameters: z.toJSONSchema(getConfigParamsSchema),
+
+  /**
+   * Runs the tool: it lazy-loads the handler and delegates the work to it.
+   *
+   * @param _toolCallId The id of the tool call. It's not used.
+   * @param rawParams The parameters the model sent.
+   * @param signal The signal to abort the lookup.
+   * @param _onUpdate The callback for partial results. It's not used.
+   * @param ctx The context of the session, to know the project directory.
+   * @returns The result of the tool.
+   */
+  async execute(_toolCallId, rawParams, signal, _onUpdate, ctx) {
+    const { handleGetConfig } = await loadHandlers();
+    return handleGetConfig({ params: rawParams as GetConfigParams, signal, ctx });
+  },
+
+  /**
+   * Renders the call of the tool in the TUI.
+   *
+   * @param args The parameters of the call.
+   * @param theme The theme to color the text with.
+   * @returns The text to show: the label of the query and what kind of lookup it is.
+   */
+  renderCall(args, theme) {
+    const query = args as ConfigQuery;
+    const label = getQueryLabel(query);
+    let details = 'full config';
+    if (query.path) details = 'path lookup';
+    else if (query.scope && query.name) details = `${query.scope} scope`;
+    else if (query.scope) details = `${query.scope} namespace`;
+    return new Text(
+      `${theme.fg('toolTitle', theme.bold('get_config '))}${theme.fg(
+        'accent',
+        label,
+      )}\n${theme.fg('dim', `  ${details}`)}`,
+      0,
+      0,
+    );
+  },
+
+  /**
+   * Renders the result of the tool in the TUI.
+   *
+   * @param result The result of the tool.
+   * @param options The render options, to know if the result is partial.
+   * @param theme The theme to color the text with.
+   * @returns The text to show: a preview of the value and how many files it came from, or
+   *   the reason why there's no value.
+   */
+  renderResult(result, options, theme) {
+    const details = result.details as {
+      status?: string;
+      value?: unknown;
+      message?: string;
+      sources?: unknown;
+    };
+    const prefix = options.isPartial ? `${theme.fg('muted', '… ')} ` : '';
+    if (details.status === 'found') {
+      const usedSourceCount = getUsedSourceCount(details.sources);
+      const sourceText =
+        usedSourceCount === 1 ? '1 source' : `${usedSourceCount} sources`;
+      return new Text(
+        `${prefix}${theme.fg('success', '✓')} ${theme.fg(
+          'muted',
+          sourceText,
+        )} ${formatValuePreview(details.value)}`,
+        0,
+        0,
+      );
+    }
+    return new Text(
+      `${prefix}${theme.fg(
+        details.status === 'not_found' ? 'warning' : 'error',
+        details.message ?? 'Config lookup failed',
+      )}`,
+      0,
+      0,
+    );
+  },
+};
+
+/** Tool definition for setting an in-memory session config override. */
+const setConfigTool: Parameters<ExtensionAPI['registerTool']>[0] = {
+  name: 'set_config',
+  label: 'Set Config',
+  description:
+    'Override one Pi Core config value for the rest of this session. In-memory only: never written to config.json/config.local.json/config.yaml/config.local.yaml, and lost when the session ends.',
+  promptSnippet:
+    'Only call set_config when the user explicitly asks to override a config value for this session.',
+  promptGuidelines: [
+    'Only call set_config when the user explicitly asks to override a specific config value for this session.',
+    'Never call set_config speculatively, to work around an error, or to "fix" a config problem the user did not ask you to change.',
+    'set_config only affects this session/process and is never persisted to any config file.',
+    'set_config can only set a value; it cannot remove a file-based value or restore file-only behavior for one path. Tell the user to use /config to clear the whole session override.',
+  ],
+  parameters: z.toJSONSchema(setConfigParamsSchema),
+
+  /**
+   * Runs the tool: it lazy-loads the handler and delegates the work to it.
+   *
+   * @param _toolCallId The id of the tool call. It's not used.
+   * @param rawParams The parameters the model sent.
+   * @returns The result of the tool.
+   */
+  async execute(_toolCallId, rawParams) {
+    const { handleSetConfig } = await loadHandlers();
+    return handleSetConfig({ params: rawParams as SetConfigParams });
+  },
+
+  /**
+   * Renders the call of the tool in the TUI.
+   *
+   * @param args The parameters of the call.
+   * @param theme The theme to color the text with.
+   * @returns The text to show: the path that is being set.
+   */
+  renderCall(args, theme) {
+    const params = args as Partial<SetConfigParams>;
+    return new Text(
+      `${theme.fg('toolTitle', theme.bold('set_config '))}${theme.fg('accent', params.path ?? '')}`,
+      0,
+      0,
+    );
+  },
+
+  /**
+   * Renders the result of the tool in the TUI.
+   *
+   * @param result The result of the tool.
+   * @param options The render options, to know if the result is partial.
+   * @param theme The theme to color the text with.
+   * @returns The text to show: the path and the value that were set, or the reason why it
+   *   failed.
+   */
+  renderResult(result, options, theme) {
+    const details = result.details as SetConfigDetails | undefined;
+    const prefix = options.isPartial ? `${theme.fg('muted', '… ')} ` : '';
+    if (!details || details.status !== 'applied') {
+      return new Text(
+        `${prefix}${theme.fg('error', details?.message ?? 'set_config failed')}`,
+        0,
+        0,
+      );
+    }
+    return new Text(
+      `${prefix}${theme.fg('success', '✓ ')}${theme.fg('accent', details.path)} = ${JSON.stringify(details.value)}`,
+      0,
+      0,
+    );
+  },
+};
+
+/**
+ * Registers config extension tools and the `/config`/`/config-reset` commands with Pi.
+ * The definitions are light; the tools' `execute` and the commands lazy-load their
+ * implementation, through the shared handlers loader.
+ *
+ * @param pi The Pi extension API.
+ */
+const config = (pi: ExtensionAPI): void => {
+  pi.registerTool(getConfigTool);
+  pi.registerTool(setConfigTool);
+
+  pi.registerCommand('config', {
+    description: 'View the effective Pi Core config and edit the session override',
+    handler: async (_args, ctx) => {
+      const { handleConfig } = await loadHandlers();
+      await handleConfig({ ctx });
+    },
+  });
+
+  pi.registerCommand('config-reset', {
+    description: 'Clear the session config override',
+    handler: async (_args, ctx) => {
+      const { handleConfigReset } = await loadHandlers();
+      handleConfigReset({ ctx });
+    },
+  });
+};
+
+export default config;

package/src/format.ts

@@ -0,0 +1,58 @@
+import type { ConfigQuery } from './types.js';
+
+/** The number of spaces used to indent the JSON output. */
+const JSON_INDENT = 2;
+/** The max number of characters of a value preview. */
+const SUMMARY_LIMIT = 120;
+
+/**
+ * Formats config values for model-facing tool output.
+ *
+ * @param value The value to format.
+ * @returns The value as it is if it's a string, or as indented JSON for anything else.
+ */
+export const formatValue = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value, null, JSON_INDENT);
+};
+
+/**
+ * Formats a compact single-line value preview for TUI rendering.
+ *
+ * @param value The value to preview.
+ * @returns The formatted value in a single line, cut with an ellipsis if it's too long.
+ */
+export const formatValuePreview = (value: unknown): string => {
+  const preview = formatValue(value).replaceAll('\n', ' ');
+  if (preview.length <= SUMMARY_LIMIT) return preview;
+  return `${preview.slice(0, SUMMARY_LIMIT - 1)}…`;
+};
+
+/**
+ * Builds a compact label for displaying get_config calls.
+ *
+ * @param query The query of the call.
+ * @returns The path if there's one; `scope:name` for a named integration; the scope for a
+ *   namespace; or `all` for the whole config.
+ */
+export const getQueryLabel = (query: ConfigQuery): string => {
+  if (query.path) return query.path;
+  if (query.scope && query.name) return `${query.scope}:${query.name}`;
+  if (query.scope) return query.scope;
+  return 'all';
+};
+
+/**
+ * Counts config source files that exist and contributed to a lookup.
+ *
+ * @param sources The `sources` of a query result. It comes from the details of a tool
+ *   result, so it can't be trusted to have the right shape.
+ * @returns The number of sources that were used, or `0` if `sources` is not a list.
+ */
+export const getUsedSourceCount = (sources: unknown): number => {
+  if (!Array.isArray(sources)) return 0;
+  return sources.filter(
+    (source) =>
+      source && typeof source === 'object' && 'used' in source && source.used === true,
+  ).length;
+};

package/src/handlers.ts

@@ -0,0 +1,225 @@
+import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent';
+import { set } from '@homer0/object-utils';
+import { ConfigReadError } from './errors.js';
+import { formatValue, getQueryLabel } from './format.js';
+import type { GetConfigParams, SetConfigParams } from './schemas.js';
+import type { ConfigQuery, PiCoreConfig, SetConfigDetails } from './types.js';
+import {
+  clearSessionConfigOverride,
+  EMPTY_PI_CORE_CONFIG,
+  getSessionConfigOverride,
+  queryConfig,
+  setSessionConfigOverride,
+} from './utils.js';
+import { showConfigWindow } from './window.js';
+
+/** The text that replaces a value that looks like a secret. */
+const REDACTED_VALUE = '[REDACTED]';
+/** The pattern of the keys that look like they would contain secrets. */
+const SENSITIVE_KEY_PATTERN =
+  /(?:secret|password|passwd|token|apiKey|api[_-]?key|privateKey|private[_-]?key|accessKey|access[_-]?key|key$)/iu;
+
+/**
+ * Checks whether a config path segment is likely to contain secret material.
+ *
+ * @param key The segment of the path.
+ * @returns Whether it looks like a secret.
+ */
+const isSensitiveKey = (key: string): boolean => SENSITIVE_KEY_PATTERN.test(key);
+
+/**
+ * Redacts model-facing config values while preserving raw access through the Node API.
+ *
+ * @param value The value to redact.
+ * @param path The segments of the path the value is at. If any of them looks like a
+ *   secret, the whole value is redacted.
+ * @returns The value, and whether something was redacted.
+ */
+const redactValue = (
+  value: unknown,
+  path: string[],
+): { value: unknown; redacted: boolean } => {
+  if (path.some(isSensitiveKey)) return { value: REDACTED_VALUE, redacted: true };
+
+  if (Array.isArray(value)) {
+    let redacted = false;
+    const items = value.map((item, index) => {
+      const result = redactValue(item, path.concat(String(index)));
+      redacted ||= result.redacted;
+      return result.value;
+    });
+    return { value: items, redacted };
+  }
+
+  if (!value || typeof value !== 'object') return { value, redacted: false };
+
+  let redacted = false;
+  const entries = Object.entries(value).map(([key, childValue]) => {
+    const result = redactValue(childValue, path.concat(key));
+    redacted ||= result.redacted;
+    return [key, result.value] as const;
+  });
+
+  return { value: Object.fromEntries(entries), redacted };
+};
+
+/**
+ * Gets the segments of the query path, when the lookup targets a specific path.
+ *
+ * @param query The query of the lookup.
+ * @returns The segments, or an empty list if the query doesn't have a path.
+ */
+const getQueryPathSegments = (query: ConfigQuery): string[] =>
+  query.path ? query.path.split('.').filter(Boolean) : [];
+
+/** Options for {@link handleGetConfig}. */
+type HandleGetConfigOptions = {
+  /** The parameters the model sent. */
+  params: GetConfigParams;
+  /** The signal to abort the lookup. */
+  signal: AbortSignal | undefined;
+  /** The context of the session, to know the project directory. */
+  ctx: { cwd: string };
+};
+
+/**
+ * Executes the `get_config` tool: reads, redacts and formats the requested config.
+ *
+ * @param options The parameters of the call and the context it was made in.
+ * @returns The result of the tool, with the text for the model and the details for the
+ *   TUI. Failures are reported in the result, they don't throw.
+ */
+export const handleGetConfig = async ({
+  params,
+  signal,
+  ctx,
+}: HandleGetConfigOptions) => {
+  if (signal?.aborted) {
+    return {
+      content: [{ type: 'text' as const, text: 'Config lookup cancelled.' }],
+      details: {
+        status: 'error',
+        query: params,
+        redacted: false,
+        sources: [],
+        message: 'Config lookup cancelled.',
+      },
+    };
+  }
+
+  try {
+    const result = await queryConfig(params, { cwd: ctx.cwd });
+    const redacted =
+      result.status === 'found'
+        ? redactValue(result.value, getQueryPathSegments(params))
+        : { value: result.value, redacted: false };
+    const text =
+      result.status === 'found'
+        ? `Config value for ${getQueryLabel(params)}:\n${formatValue(redacted.value)}`
+        : (result.message ?? result.status);
+
+    return {
+      content: [{ type: 'text' as const, text }],
+      details: {
+        ...result,
+        value: redacted.value,
+        redacted: redacted.redacted,
+      },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: 'text' as const, text: message }],
+      details: {
+        status: 'error',
+        query: params,
+        redacted: false,
+        sources: [],
+        message,
+        filePath: error instanceof ConfigReadError ? error.filePath : undefined,
+      },
+    };
+  }
+};
+
+/** Options for {@link handleSetConfig}. */
+type HandleSetConfigOptions = {
+  /** The parameters the model sent. */
+  params: SetConfigParams;
+};
+
+/**
+ * Executes the `set_config` tool: applies an in-memory session config override.
+ *
+ * @param options The parameters of the call.
+ * @returns The result of the tool, with the text for the model and the details for the
+ *   TUI. Failures are reported in the result, they don't throw.
+ */
+export const handleSetConfig = ({ params }: HandleSetConfigOptions) => {
+  const path = params.path.trim();
+
+  if (!path) {
+    const message = 'set_config requires a non-empty path.';
+    return {
+      content: [{ type: 'text' as const, text: message }],
+      details: { status: 'error', path, message } satisfies SetConfigDetails,
+    };
+  }
+
+  const current = structuredClone(getSessionConfigOverride() ?? EMPTY_PI_CORE_CONFIG);
+  const updated = set<PiCoreConfig>({ target: current, path, value: params.value });
+
+  if (typeof updated === 'undefined') {
+    const message = `Could not set config path: ${path}`;
+    return {
+      content: [{ type: 'text' as const, text: message }],
+      details: { status: 'error', path, message } satisfies SetConfigDetails,
+    };
+  }
+
+  setSessionConfigOverride(updated);
+  const text = `Session override set: ${path} = ${JSON.stringify(params.value)}`;
+  return {
+    content: [{ type: 'text' as const, text }],
+    details: {
+      status: 'applied',
+      path,
+      value: params.value,
+    } satisfies SetConfigDetails,
+  };
+};
+
+/** Options for {@link handleConfig}. */
+type HandleConfigOptions = {
+  /** The context of the command. */
+  ctx: ExtensionCommandContext;
+};
+
+/**
+ * Handles `/config`: opens the config window.
+ *
+ * @param options The context of the command.
+ */
+export const handleConfig = async ({ ctx }: HandleConfigOptions): Promise<void> => {
+  await showConfigWindow(ctx);
+};
+
+/** Options for {@link handleConfigReset}. */
+type HandleConfigResetOptions = {
+  /** The context of the command. */
+  ctx: ExtensionCommandContext;
+};
+
+/**
+ * Handles `/config-reset`: clears the session config override, and tells the user if
+ * there was one.
+ *
+ * @param options The context of the command.
+ */
+export const handleConfigReset = ({ ctx }: HandleConfigResetOptions): void => {
+  const hadOverride = clearSessionConfigOverride();
+  ctx.ui.notify(
+    hadOverride ? 'Session config override cleared.' : 'No session override was set.',
+    'info',
+  );
+};

package/src/index.ts

@@ -0,0 +1,20 @@
+export { getConfig, getConfigValue, queryConfig } from './utils.js';
+export type {
+  ConfigNamespace,
+  ConfigPath,
+  ConfigPathValue,
+  ConfigQuery,
+  ConfigQueryScope,
+  ConfigSchema,
+  ConfigSource,
+  ExtensionsConfig,
+  GetConfigOptions,
+  PiConfig,
+  PiCoreConfig,
+  QueryConfigOptions,
+  QueryConfigResult,
+  ReadConfigResult,
+  SkillsConfig,
+  ToolsConfig,
+} from './types.js';
+export { ConfigValidationError } from './errors.js';

package/src/schemas.ts

@@ -0,0 +1,39 @@
+import { z } from 'zod';
+
+/** Model-facing schema for the get_config tool. */
+export const getConfigParamsSchema = z.object({
+  path: z
+    .string()
+    .optional()
+    .describe('Dot-path to read, for example skills.commit.runChecks.'),
+  scope: z
+    .enum(['all', 'pi', 'skills', 'tools', 'extensions', 'skill', 'tool', 'extension'])
+    .optional()
+    .describe(
+      'Config scope to read. Use pi for general Pi settings, or skill/tool/extension with name.',
+    ),
+  name: z
+    .string()
+    .optional()
+    .describe('Name for skill, tool, or extension scoped lookups.'),
+});
+
+/** The parameters the model sends to the `get_config` tool. */
+export type GetConfigParams = z.infer<typeof getConfigParamsSchema>;
+
+/** Model-facing schema for the set_config tool. */
+export const setConfigParamsSchema = z.object({
+  path: z
+    .string()
+    .describe(
+      'Dot-path to override for the rest of this session, for example extensions.notifyMe.priority.',
+    ),
+  value: z
+    .unknown()
+    .describe(
+      'Value to set at path. Only this path changes; the rest of the config is unaffected.',
+    ),
+});
+
+/** The parameters the model sends to the `set_config` tool. */
+export type SetConfigParams = z.infer<typeof setConfigParamsSchema>;