@procedures/env 0.0.0-stage → 0.2.3

package/src/module.ts

@@ -0,0 +1,186 @@
+/**
+ * The procedures of @procedures/env as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/env
+ *
+ * `envModule` reads `process.env` and masks each secret. `createEnvModule()` gives the same
+ * procedures with more secret patterns, secrets that `env.get` reveals, or other variables
+ * (roadmap R46). These procedures are not MCP tools: a value goes to the model and its provider.
+ */
+
+import { z } from "zod";
+import {
+  defineModule,
+  registerModules,
+  PROCEDURE_REGISTRY,
+  createProcedure,
+  zodAdapter,
+  type AnyProcedure,
+  type Effects,
+  type ProcedureModule,
+  type ProcedureRegistry,
+} from "@procedures/client";
+import { envGet } from "./procedures/env/get.js";
+import { envList } from "./procedures/env/list.js";
+import { envCheck } from "./procedures/env/check.js";
+import { DEFAULT_ENV_SETTINGS, DEFAULT_SECRET_PATTERNS, secretMatcher, type EnvSettings } from "./secrets.js";
+import type { EnvCheckInput, EnvCheckOutput, EnvGetInput, EnvGetOutput, EnvListInput, EnvListOutput, EnvSource } from "./types.js";
+
+// =============================================================================
+// Schemas
+// =============================================================================
+
+/** The name of a variable: not empty, without `=` and without a NUL character. */
+const variableName = z
+  .string()
+  .min(1)
+  .max(1024)
+  .regex(/^[^=\0]+$/, "A name without = and without NUL")
+  .describe("The name of an environment variable");
+
+const EnvGetInputSchema = z.object({ name: variableName });
+
+const EnvGetOutputSchema = z.object({
+  name: z.string().describe("The name of the variable"),
+  set: z.boolean().describe("True when the variable has a value. An empty value counts as set"),
+  secret: z.boolean().describe("True when the name matches a pattern of secret names"),
+  masked: z.boolean().describe("True for a secret that the host does not reveal: the output has no value"),
+  value: z.string().optional().describe("The value. Absent for a variable that is not set and for a masked secret"),
+});
+
+const EnvListInputSchema = z.object({
+  prefix: z.string().max(1024).optional().describe("Only the names that start with this text. The comparison ignores the case"),
+  values: z.boolean().optional().describe("True: give the value of each variable that is not a secret (default false)"),
+});
+
+const EnvListOutputSchema = z.object({
+  variables: z
+    .array(
+      z.object({
+        name: z.string(),
+        secret: z.boolean().describe("True when the name matches a pattern of secret names"),
+        value: z.string().optional().describe("The value: only with values: true, and never for a secret"),
+      }),
+    )
+    .describe("The variables, sorted by name"),
+});
+
+const EnvCheckInputSchema = z.object({
+  required: z.array(variableName).max(1000).describe("The names of the variables that must have a value"),
+  allowEmpty: z.boolean().optional().describe("True: an empty value counts as present (default false)"),
+});
+
+const EnvCheckOutputSchema = z.object({
+  ok: z.boolean().describe("True when no required variable is missing"),
+  missing: z.array(z.string()).describe("The required variables without a value"),
+  present: z.array(z.string()).describe("The required variables with a value"),
+});
+
+// =============================================================================
+// Procedures
+// =============================================================================
+
+/** The effects of each procedure: it reads the environment of the process and changes nothing. */
+const READS_PROCESS: Effects = Object.freeze({ reads: Object.freeze(["process"]), writes: Object.freeze([]) });
+
+/** The three procedures, with handlers that use the settings. */
+function envProcedures(settings: EnvSettings): AnyProcedure[] {
+  const envGetProcedure = createProcedure()
+    .path(["env", "get"])
+    .input(zodAdapter<EnvGetInput>(EnvGetInputSchema))
+    .output(zodAdapter<EnvGetOutput>(EnvGetOutputSchema))
+    .meta({
+      description: "One environment variable. A secret is masked unless the host reveals it",
+      tags: ["env", "secrets"],
+      args: ["name"],
+      shorts: {},
+      output: "json",
+      effects: READS_PROCESS,
+    })
+    .handler(async (input: EnvGetInput): Promise<EnvGetOutput> => envGet(input, settings))
+    .build();
+
+  const envListProcedure = createProcedure()
+    .path(["env", "list"])
+    .input(zodAdapter<EnvListInput>(EnvListInputSchema))
+    .output(zodAdapter<EnvListOutput>(EnvListOutputSchema))
+    .meta({
+      description: "The names of the environment variables, never the values of the secrets",
+      tags: ["env", "secrets"],
+      args: ["prefix"],
+      shorts: {},
+      output: "json",
+      effects: READS_PROCESS,
+    })
+    .handler(async (input: EnvListInput): Promise<EnvListOutput> => envList(input, settings))
+    .build();
+
+  const envCheckProcedure = createProcedure()
+    .path(["env", "check"])
+    .input(zodAdapter<EnvCheckInput>(EnvCheckInputSchema))
+    .output(zodAdapter<EnvCheckOutput>(EnvCheckOutputSchema))
+    .meta({
+      description: "Which required environment variables are missing",
+      tags: ["env"],
+      args: ["required"],
+      shorts: {},
+      output: "json",
+      effects: READS_PROCESS,
+    })
+    .handler(async (input: EnvCheckInput): Promise<EnvCheckOutput> => envCheck(input, settings))
+    .build();
+
+  return [envGetProcedure, envListProcedure, envCheckProcedure];
+}
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. It reads
+ * `process.env` at each call and masks each secret. Importing this file registers nothing.
+ */
+export const envModule: ProcedureModule = defineModule("@procedures/env", envProcedures(DEFAULT_ENV_SETTINGS));
+
+export default envModule;
+
+/** The options of `createEnvModule()`. */
+export interface EnvModuleOptions {
+  /** More patterns of secret names, after the default patterns. `*` matches each sequence of characters. */
+  readonly secretPatterns?: readonly string[] | undefined;
+  /**
+   * The secrets whose value `env.get` gives: `true` for each secret, or a list of names (the
+   * comparison ignores the case). The default is none. `env.list` never gives a secret.
+   */
+  readonly revealSecrets?: boolean | readonly string[] | undefined;
+  /** The variables: a record, or a function that gives them at each call. The default is `process.env`. */
+  readonly env?: EnvSource | (() => EnvSource) | undefined;
+}
+
+/**
+ * This function gives the module of this package with other settings. Without options, it gives
+ * `envModule`. A host gives it to `createRegistry()` before its bundles, so it replaces the
+ * `envModule` that a bundle requires (the first module of a name counts).
+ *
+ * ```ts
+ * createRegistry(createEnvModule({ secretPatterns: ["DATABASE_URL"], revealSecrets: ["NPM_TOKEN"] }));
+ * ```
+ */
+export function createEnvModule(options: EnvModuleOptions = {}): ProcedureModule {
+  if (Object.values(options).every((value) => value === undefined)) return envModule;
+  const env = options.env;
+  const source = env === undefined ? DEFAULT_ENV_SETTINGS.source : typeof env === "function" ? env : () => env;
+  const reveal = options.revealSecrets;
+  const revealed = Array.isArray(reveal) ? new Set(reveal.map((name) => name.toUpperCase())) : undefined;
+  const settings: EnvSettings = {
+    source,
+    isSecret: secretMatcher([...DEFAULT_SECRET_PATTERNS, ...(options.secretPatterns ?? [])]),
+    reveals: reveal === true ? () => true : revealed ? (name) => revealed.has(name.toUpperCase()) : () => false,
+  };
+  return defineModule("@procedures/env", envProcedures(settings));
+}
+
+/**
+ * This function registers the procedures of @procedures/env in a registry. The default is the
+ * global registry. The options are the options of `createEnvModule()`.
+ */
+export function registerEnvProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY, options: EnvModuleOptions = {}): void {
+  registerModules(registry, [createEnvModule(options)]);
+}

package/src/procedures/env/check.ts

@@ -0,0 +1,23 @@
+/**
+ * env.check procedure
+ *
+ * Which required environment variables are missing. The output has names only, never values.
+ */
+
+import { DEFAULT_ENV_SETTINGS, valueOf, type EnvSettings } from "../../secrets.js";
+import type { EnvCheckInput, EnvCheckOutput } from "../../types.js";
+
+/**
+ * Which required environment variables are missing
+ */
+export async function envCheck(input: EnvCheckInput, settings: EnvSettings = DEFAULT_ENV_SETTINGS): Promise<EnvCheckOutput> {
+  const source = settings.source();
+  const missing: string[] = [];
+  const present: string[] = [];
+  for (const name of new Set(input.required)) {
+    const value = valueOf(source, name);
+    const has = value !== undefined && (input.allowEmpty === true || value !== "");
+    (has ? present : missing).push(name);
+  }
+  return { ok: missing.length === 0, missing, present };
+}

package/src/procedures/env/get.ts

@@ -0,0 +1,26 @@
+/**
+ * env.get procedure
+ *
+ * One environment variable. A secret is masked unless the host reveals it: the output then says
+ * that the variable is set, and it has no value.
+ */
+
+import { DEFAULT_ENV_SETTINGS, valueOf, type EnvSettings } from "../../secrets.js";
+import type { EnvGetInput, EnvGetOutput } from "../../types.js";
+
+/**
+ * One environment variable. A secret is masked unless the host reveals it
+ */
+export async function envGet(input: EnvGetInput, settings: EnvSettings = DEFAULT_ENV_SETTINGS): Promise<EnvGetOutput> {
+  const value = valueOf(settings.source(), input.name);
+  const secret = settings.isSecret(input.name);
+  const set = value !== undefined;
+  const masked = set && secret && !settings.reveals(input.name);
+  return {
+    name: input.name,
+    set,
+    secret,
+    masked,
+    ...(set && !masked ? { value } : {}),
+  };
+}

package/src/procedures/env/index.ts

@@ -0,0 +1,3 @@
+export { envGet } from "./get.js";
+export { envList } from "./list.js";
+export { envCheck } from "./check.js";

package/src/procedures/env/list.ts

@@ -0,0 +1,27 @@
+/**
+ * env.list procedure
+ *
+ * The names of the environment variables, never the values of the secrets. With `values: true`,
+ * the output has the values of the other variables. The reveal rule of the host does not apply
+ * here: a list never shows a secret.
+ */
+
+import { DEFAULT_ENV_SETTINGS, type EnvSettings } from "../../secrets.js";
+import type { EnvListEntry, EnvListInput, EnvListOutput } from "../../types.js";
+
+/**
+ * The names of the environment variables, never the values of the secrets
+ */
+export async function envList(input: EnvListInput, settings: EnvSettings = DEFAULT_ENV_SETTINGS): Promise<EnvListOutput> {
+  const source = settings.source();
+  const prefix = input.prefix?.toUpperCase();
+  const variables: EnvListEntry[] = [];
+  for (const [name, value] of Object.entries(source)) {
+    if (typeof value !== "string") continue;
+    if (prefix !== undefined && !name.toUpperCase().startsWith(prefix)) continue;
+    const secret = settings.isSecret(name);
+    variables.push({ name, secret, ...(input.values === true && !secret ? { value } : {}) });
+  }
+  variables.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  return { variables };
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/env in the global registry:
+ * `import "@procedures/env/register"`. The package root registers nothing.
+ */
+
+import { registerEnvProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerEnvProcedures();

package/src/secrets.ts

@@ -0,0 +1,56 @@
+/**
+ * The secret names and the settings of the env procedures.
+ *
+ * A secret is a variable whose name matches a pattern. A pattern is a name with `*` for each
+ * sequence of characters (also an empty one). The comparison ignores the case, because Windows
+ * ignores the case of the names of variables.
+ */
+
+import type { EnvSource } from "./types.js";
+
+/** The default patterns of secret names. */
+export const DEFAULT_SECRET_PATTERNS: readonly string[] = Object.freeze(["*_TOKEN", "*_KEY", "*_SECRET", "*PASSWORD*"]);
+
+/** This function gives the regular expression of a pattern: `*` matches each sequence of characters. */
+function patternExpression(pattern: string): RegExp {
+  const escaped = pattern
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${escaped}$`, "i");
+}
+
+/** This function gives the test of the secret names for a list of patterns. */
+export function secretMatcher(patterns: readonly string[]): (name: string) => boolean {
+  const expressions = patterns.map((pattern) => {
+    if (typeof pattern !== "string" || pattern.trim() === "") throw new TypeError("A secret pattern must be a text that is not empty");
+    return patternExpression(pattern);
+  });
+  return (name) => expressions.some((expression) => expression.test(name));
+}
+
+/** True when the name matches one of the default patterns of secret names. */
+export const isDefaultSecret: (name: string) => boolean = secretMatcher(DEFAULT_SECRET_PATTERNS);
+
+/** What the procedures of a module use: the variables, the secret test and the reveal rule. */
+export interface EnvSettings {
+  /** This function gives the variables at the time of a call. */
+  readonly source: () => EnvSource;
+  /** True when a name is a secret. */
+  readonly isSecret: (name: string) => boolean;
+  /** True when `env.get` gives the value of this secret. */
+  readonly reveals: (name: string) => boolean;
+}
+
+/** The settings of the default module: `process.env`, the default patterns, and no secret revealed. */
+export const DEFAULT_ENV_SETTINGS: EnvSettings = Object.freeze({
+  source: () => process.env,
+  isSecret: isDefaultSecret,
+  reveals: () => false,
+});
+
+/** The value of a variable, or undefined. The lookup is the lookup of the source: `process.env` ignores the case on Windows. */
+export function valueOf(source: EnvSource, name: string): string | undefined {
+  const value = source[name];
+  return typeof value === "string" ? value : undefined;
+}

package/src/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+/** The variables that the procedures read: a name and a value, or undefined for a variable that is not set. */
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+
+// =============================================================================
+// env.get
+// =============================================================================
+
+export interface EnvGetInput {
+  /** The name of the variable. */
+  name: string;
+}
+
+export interface EnvGetOutput {
+  /** The name of the variable. */
+  name: string;
+  /** True when the variable has a value. An empty value counts as set. */
+  set: boolean;
+  /** True when the name matches a pattern of secret names. */
+  secret: boolean;
+  /** True when the variable is a secret and the host does not reveal it: the output has no value. */
+  masked: boolean;
+  /** The value. It is absent for a variable that is not set and for a masked secret. */
+  value?: string | undefined;
+}
+
+// =============================================================================
+// env.list
+// =============================================================================
+
+export interface EnvListInput {
+  /** Only the names that start with this text. The comparison ignores the case. */
+  prefix?: string | undefined;
+  /** True: the output has the value of each variable that is not a secret. The default is false. */
+  values?: boolean | undefined;
+}
+
+/** One variable of `env.list`. */
+export interface EnvListEntry {
+  name: string;
+  /** True when the name matches a pattern of secret names. */
+  secret: boolean;
+  /** The value, only with `values: true` and only for a variable that is not a secret. */
+  value?: string | undefined;
+}
+
+export interface EnvListOutput {
+  /** The variables, sorted by name. */
+  variables: EnvListEntry[];
+}
+
+// =============================================================================
+// env.check
+// =============================================================================
+
+export interface EnvCheckInput {
+  /** The names of the variables that must have a value. */
+  required: string[];
+  /** True: an empty value counts as present. The default is false: an empty value counts as missing. */
+  allowEmpty?: boolean | undefined;
+}
+
+export interface EnvCheckOutput {
+  /** True when no required variable is missing. */
+  ok: boolean;
+  /** The required variables that are not set (or that are empty), in the order of the input. */
+  missing: string[];
+  /** The required variables that have a value, in the order of the input. */
+  present: string[];
+}