@procedures/client 0.0.0-stage → 0.2.0

package/src/procedures/core/object.ts

@@ -0,0 +1,429 @@
+/**
+ * Object Procedures
+ *
+ * Object manipulation operations for procedure aggregation.
+ * All procedures are namespaced under "client" (e.g., client.get, client.set).
+ */
+
+import { z } from "zod";
+import { anyOutput, arrayOutput, booleanOutput, recordOutput } from "./outputs.js";
+import { defineProcedure, namespace } from "../define.js";
+import type { AnyProcedure, Procedure } from "../types.js";
+import { PURE_EFFECTS, withEffects } from "../effects.js";
+
+// =============================================================================
+// Helper: Get nested value by path
+// =============================================================================
+
+function getByPath(obj: unknown, path: string): unknown {
+  const parts = path.split(".");
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current === null || current === undefined) {
+      return undefined;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current;
+}
+
+// =============================================================================
+// Helper: Set nested value by path
+// =============================================================================
+
+function setByPath(obj: Record<string, unknown>, path: string, value: unknown): Record<string, unknown> {
+  const result = { ...obj };
+  const parts = path.split(".");
+  let current: Record<string, unknown> = result;
+
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i]!;
+    if (!(part in current) || typeof current[part] !== "object" || current[part] === null) {
+      current[part] = {};
+    } else {
+      current[part] = { ...(current[part] as Record<string, unknown>) };
+    }
+    current = current[part] as Record<string, unknown>;
+  }
+
+  const lastPart = parts[parts.length - 1];
+  if (lastPart !== undefined) {
+    current[lastPart] = value;
+  }
+  return result;
+}
+
+// =============================================================================
+// Get Procedure
+// =============================================================================
+
+interface GetInput {
+  object: Record<string, unknown>;
+  path: string;
+  default?: unknown | undefined;
+}
+
+const GetInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+  path: z.string().describe("The path of the field, with dots (for example user.name)"),
+  default: z.unknown().optional().describe("The value to give when the path has no value"),
+});
+
+type GetProcedure = Procedure<GetInput, unknown, { description: string; tags: string[] }>;
+
+const getProcedure: GetProcedure = defineProcedure({
+  path: ["get"],
+  input: GetInputSchema,
+  output: anyOutput("The value at the path, or the default"),
+  metadata: {
+    description: "Get nested value from object by dot-separated path",
+    tags: ["core", "object"],
+  },
+  handler: async (input: GetInput): Promise<unknown> => {
+    const value = getByPath(input.object, input.path);
+    return value !== undefined ? value : input.default;
+  },
+});
+
+// =============================================================================
+// Set Procedure
+// =============================================================================
+
+interface SetInput {
+  object: Record<string, unknown>;
+  path: string;
+  value?: unknown;
+}
+
+const SetInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+  path: z.string().describe("The path of the field, with dots (for example user.name)"),
+  value: z.unknown().optional().describe("The value"),
+});
+
+type SetProcedure = Procedure<SetInput, Record<string, unknown>, { description: string; tags: string[] }>;
+
+const setProcedure: SetProcedure = defineProcedure({
+  path: ["set"],
+  input: SetInputSchema,
+  output: recordOutput("The object with the value at the path"),
+  metadata: {
+    description: "Set nested value in object by dot-separated path (immutable)",
+    tags: ["core", "object"],
+  },
+  handler: async (input: SetInput): Promise<Record<string, unknown>> => {
+    return setByPath(input.object, input.path, input.value);
+  },
+});
+
+// =============================================================================
+// Merge Procedure
+// =============================================================================
+
+interface MergeInput {
+  objects: Record<string, unknown>[];
+  deep?: boolean | undefined;
+}
+
+const MergeInputSchema = z.object({
+  objects: z.array(z.record(z.string(), z.unknown())).describe("The objects"),
+  deep: z.boolean().optional().describe("Merge nested objects too"),
+});
+
+type MergeProcedure = Procedure<MergeInput, Record<string, unknown>, { description: string; tags: string[] }>;
+
+function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown> {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      typeof source[key] === "object" &&
+      source[key] !== null &&
+      !Array.isArray(source[key]) &&
+      typeof result[key] === "object" &&
+      result[key] !== null &&
+      !Array.isArray(result[key])
+    ) {
+      result[key] = deepMerge(
+        result[key] as Record<string, unknown>,
+        source[key] as Record<string, unknown>
+      );
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+const mergeProcedure: MergeProcedure = defineProcedure({
+  path: ["merge"],
+  input: MergeInputSchema,
+  output: recordOutput("The merged object"),
+  metadata: {
+    description: "Merge multiple objects (shallow or deep)",
+    tags: ["core", "object"],
+  },
+  handler: async (input: MergeInput): Promise<Record<string, unknown>> => {
+    if (input.deep) {
+      return input.objects.reduce((acc, obj) => deepMerge(acc, obj), {});
+    }
+    return Object.assign({}, ...input.objects);
+  },
+});
+
+// =============================================================================
+// Keys Procedure
+// =============================================================================
+
+interface KeysInput {
+  object: Record<string, unknown>;
+}
+
+const KeysInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+});
+
+type KeysProcedure = Procedure<KeysInput, string[], { description: string; tags: string[] }>;
+
+const keysProcedure: KeysProcedure = defineProcedure({
+  path: ["keys"],
+  input: KeysInputSchema,
+  output: z.array(z.string()).describe("The own keys of the object"),
+  metadata: {
+    description: "Get array of object keys",
+    tags: ["core", "object"],
+  },
+  handler: async (input: KeysInput): Promise<string[]> => {
+    return Object.keys(input.object);
+  },
+});
+
+// =============================================================================
+// Values Procedure
+// =============================================================================
+
+interface ValuesInput {
+  object: Record<string, unknown>;
+}
+
+const ValuesInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+});
+
+type ValuesProcedure = Procedure<ValuesInput, unknown[], { description: string; tags: string[] }>;
+
+const valuesProcedure: ValuesProcedure = defineProcedure({
+  path: ["values"],
+  input: ValuesInputSchema,
+  output: arrayOutput("The own values of the object"),
+  metadata: {
+    description: "Get array of object values",
+    tags: ["core", "object"],
+  },
+  handler: async (input: ValuesInput): Promise<unknown[]> => {
+    return Object.values(input.object);
+  },
+});
+
+// =============================================================================
+// Entries Procedure
+// =============================================================================
+
+interface EntriesInput {
+  object: Record<string, unknown>;
+}
+
+const EntriesInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+});
+
+type EntriesOutput = Array<[string, unknown]>;
+
+type EntriesProcedure = Procedure<EntriesInput, EntriesOutput, { description: string; tags: string[] }>;
+
+const entriesProcedure: EntriesProcedure = defineProcedure({
+  path: ["entries"],
+  input: EntriesInputSchema,
+  output: z.array(z.tuple([z.string(), z.unknown()])).describe("The [key, value] pairs of the object"),
+  metadata: {
+    description: "Get array of [key, value] pairs",
+    tags: ["core", "object"],
+  },
+  handler: async (input: EntriesInput): Promise<EntriesOutput> => {
+    return Object.entries(input.object);
+  },
+});
+
+// =============================================================================
+// FromEntries Procedure
+// =============================================================================
+
+interface FromEntriesInput {
+  entries: Array<[string, unknown]>;
+}
+
+const FromEntriesInputSchema = z.object({
+  entries: z.array(z.tuple([z.string(), z.unknown()])).describe("The [key, value] pairs"),
+});
+
+type FromEntriesProcedure = Procedure<FromEntriesInput, Record<string, unknown>, { description: string; tags: string[] }>;
+
+const fromEntriesProcedure: FromEntriesProcedure = defineProcedure({
+  path: ["fromEntries"],
+  input: FromEntriesInputSchema,
+  output: recordOutput("The object of the pairs"),
+  metadata: {
+    description: "Create object from [key, value] pairs",
+    tags: ["core", "object"],
+  },
+  handler: async (input: FromEntriesInput): Promise<Record<string, unknown>> => {
+    return Object.fromEntries(input.entries);
+  },
+});
+
+// =============================================================================
+// Pick Procedure
+// =============================================================================
+
+interface PickInput {
+  object: Record<string, unknown>;
+  keys: string[];
+}
+
+const PickInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+  keys: z.array(z.string()).describe("The keys"),
+});
+
+type PickProcedure = Procedure<PickInput, Record<string, unknown>, { description: string; tags: string[] }>;
+
+const pickProcedure: PickProcedure = defineProcedure({
+  path: ["pick"],
+  input: PickInputSchema,
+  output: recordOutput("The object with only the given keys"),
+  metadata: {
+    description: "Pick specified keys from object",
+    tags: ["core", "object"],
+  },
+  handler: async (input: PickInput): Promise<Record<string, unknown>> => {
+    const result: Record<string, unknown> = {};
+    for (const key of input.keys) {
+      if (key in input.object) {
+        result[key] = input.object[key];
+      }
+    }
+    return result;
+  },
+});
+
+// =============================================================================
+// Omit Procedure
+// =============================================================================
+
+interface OmitInput {
+  object: Record<string, unknown>;
+  keys: string[];
+}
+
+const OmitInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+  keys: z.array(z.string()).describe("The keys"),
+});
+
+type OmitProcedure = Procedure<OmitInput, Record<string, unknown>, { description: string; tags: string[] }>;
+
+const omitProcedure: OmitProcedure = defineProcedure({
+  path: ["omit"],
+  input: OmitInputSchema,
+  output: recordOutput("The object without the given keys"),
+  metadata: {
+    description: "Omit specified keys from object",
+    tags: ["core", "object"],
+  },
+  handler: async (input: OmitInput): Promise<Record<string, unknown>> => {
+    const keysToOmit = new Set(input.keys);
+    const result: Record<string, unknown> = {};
+    for (const key of Object.keys(input.object)) {
+      if (!keysToOmit.has(key)) {
+        result[key] = input.object[key];
+      }
+    }
+    return result;
+  },
+});
+
+// =============================================================================
+// Has Procedure
+// =============================================================================
+
+interface HasInput {
+  object: Record<string, unknown>;
+  path: string;
+}
+
+const HasInputSchema = z.object({
+  object: z.record(z.string(), z.unknown()).describe("The object"),
+  path: z.string().describe("The path of the field, with dots (for example user.name)"),
+});
+
+type HasProcedure = Procedure<HasInput, boolean, { description: string; tags: string[] }>;
+
+const hasProcedure: HasProcedure = defineProcedure({
+  path: ["has"],
+  input: HasInputSchema,
+  output: booleanOutput("True when the path exists"),
+  metadata: {
+    description: "Check if object has a value at the specified path",
+    tags: ["core", "object"],
+  },
+  handler: async (input: HasInput): Promise<boolean> => {
+    return getByPath(input.object, input.path) !== undefined;
+  },
+});
+
+// =============================================================================
+// Export Object Procedures
+// =============================================================================
+
+/**
+ * All object procedures (before namespacing).
+ */
+const objectProceduresRaw: AnyProcedure[] = [
+  getProcedure as AnyProcedure,
+  setProcedure as AnyProcedure,
+  mergeProcedure as AnyProcedure,
+  keysProcedure as AnyProcedure,
+  valuesProcedure as AnyProcedure,
+  entriesProcedure as AnyProcedure,
+  fromEntriesProcedure as AnyProcedure,
+  pickProcedure as AnyProcedure,
+  omitProcedure as AnyProcedure,
+  hasProcedure as AnyProcedure,
+];
+
+/**
+ * All object procedures namespaced under "client".
+ */
+// Each one calculates its output from its input: no reads, no changes (CAPABILITIES-2026-10)
+export const objectProcedures: AnyProcedure[] = namespace(["client"], withEffects(PURE_EFFECTS, objectProceduresRaw));
+
+/**
+ * Object procedures module for registration.
+ */
+export const objectModule: { name: string; procedures: AnyProcedure[] } = {
+  name: "client-object",
+  procedures: objectProcedures,
+};
+
+// Re-export individual procedures for direct access
+export {
+  getProcedure,
+  setProcedure,
+  mergeProcedure,
+  keysProcedure,
+  valuesProcedure,
+  entriesProcedure,
+  fromEntriesProcedure,
+  pickProcedure,
+  omitProcedure,
+  hasProcedure,
+};

package/src/procedures/core/operands.ts

@@ -0,0 +1,119 @@
+/**
+ * The operands of the control-flow procedures, shared by `client.chain`, `client.conditional`
+ * and the others, and by `client.eval` (`meta.ts`).
+ */
+
+import type { ProcedureContext, ProcedurePath } from "../types.js";
+import { PROCEDURE_REGISTRY } from "../registry.js";
+import {
+  isAnyProcedureRef,
+  normalizeRef,
+  hydrateInput,
+  createRefScope,
+  isOutputRef,
+  lookupOutputRef,
+  rawInputRule,
+  withScope,
+  RUNS_REFS_TAG,
+  type AnyProcedureRef,
+  type RefScope,
+} from "../ref.js";
+
+/**
+ * The operands of a control-flow procedure arrive raw: the procedure runs them itself, with the
+ * same rules as `exec()` (one interpreter, `hydrateInput`). The input of a control-flow procedure
+ * carries the scope of its caller (`withScope`), so an operand can read the names of an outer
+ * chain, `map` or `reduce` (deep dive CORE-13).
+ */
+
+/** The raw-input rule of the caller's registry: the procedure at a path decides (deep dive CORE-5). */
+export function rawRule(ctx: ProcedureContext): (path: ProcedurePath) => boolean {
+  return rawInputRule(ctx.registry ?? PROCEDURE_REGISTRY);
+}
+
+/**
+ * Without a client, a control-flow procedure cannot run refs. This function gives a value with
+ * its known `$ref` values resolved. A name that the scope does not have stays as it is.
+ */
+export function substituteRefs(value: unknown, scope: RefScope): unknown {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (isOutputRef(value)) {
+    const { found, value: resolved } = lookupOutputRef(value.$ref, scope);
+    return found ? resolved : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => substituteRefs(item, scope));
+  }
+  if (isAnyProcedureRef(value)) {
+    return value;
+  }
+  return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, substituteRefs(val, scope)]));
+}
+
+/**
+ * This function gives the value of an operand that is not a ref: it resolves its `$ref` values
+ * in `scope` and runs its nested refs, as `exec()` does for an input.
+ */
+export async function hydrateOperand(value: unknown, ctx: ProcedureContext, scope?: RefScope): Promise<unknown> {
+  return hydrateInput(value, (path, input) => ctx.client.call(path, input), { scope, rawInput: rawRule(ctx), onRef: ctx.onRef });
+}
+
+/**
+ * This function runs an operand ref of a control-flow procedure.
+ *
+ * It resolves the `$ref` values of the ref's input in `scope`, runs the nested refs of the
+ * input and adds `extra` (the parent context, for example `cwd`). Then it calls the procedure.
+ * A procedure that takes its input raw (control flow) gets the input unchanged, with the scope:
+ * that procedure runs its own operands.
+ */
+export async function callOperand(
+  ref: AnyProcedureRef,
+  ctx: ProcedureContext,
+  options: { scope?: RefScope | undefined; extra?: Record<string, unknown> | undefined } = {},
+): Promise<unknown> {
+  const normalized = normalizeRef(ref);
+  const raw = rawRule(ctx)(normalized.path);
+  let input: unknown = raw ? normalized.input : await hydrateOperand(normalized.input, ctx, options.scope);
+  const extra = options.extra ?? {};
+  if (Object.keys(extra).length > 0) {
+    input = { ...(typeof input === "object" && input !== null && !Array.isArray(input) ? input : {}), ...extra };
+  }
+  if (raw) {
+    input = withScope(input, options.scope);
+  }
+  return ctx.client.call(normalized.path, input);
+}
+
+/** This function gives the value of any operand: a ref runs, another value is hydrated. */
+export async function evaluateOperand(
+  value: unknown,
+  ctx: ProcedureContext,
+  options: { scope?: RefScope | undefined; extra?: Record<string, unknown> | undefined } = {},
+): Promise<unknown> {
+  if (isAnyProcedureRef(value)) {
+    return callOperand(value, ctx, options);
+  }
+  return hydrateOperand(value, ctx, options.scope);
+}
+
+/** The parent context that the control-flow procedures give to their operands. */
+export function parentContext(input: { cwd?: string | undefined; node?: unknown }): Record<string, unknown> {
+  return {
+    ...(input.cwd ? { cwd: input.cwd } : {}),
+    ...(input.node ? { node: input.node } : {}),
+  };
+}
+
+/** A child scope of `parent` with the given `$ref` names, for one call of `fn`. */
+export function scopeWith(values: Record<string, unknown>, parent?: RefScope): RefScope {
+  const scope = createRefScope(parent);
+  for (const [name, value] of Object.entries(values)) scope.outputs.set(name, value);
+  return scope;
+}
+
+/** The tags of a control-flow procedure: hydration gives it its input raw. */
+export function controlFlowTags(...tags: string[]): string[] {
+  return ["core", ...tags, RUNS_REFS_TAG];
+}

package/src/procedures/core/outputs.ts

@@ -0,0 +1,48 @@
+/**
+ * The output schemas of the core procedures (roadmap 2.1).
+ *
+ * Before, every core procedure declared a pass-through output, so a wrong output went through,
+ * the MCP tools had no output schema, and `mark --help` could not show the result. These
+ * helpers give each output a real zod 4 schema with a description.
+ */
+
+import { z } from "zod";
+
+/**
+ * Any JavaScript number, also `NaN` and `Infinity`. zod 4's `z.number()` refuses both, but
+ * `client.divide` by 0, `client.sqrt` of a negative number and `client.pow` can give them (the
+ * Composer shows them). The JSON Schema is `{ "type": "number" }`.
+ */
+export function numberOutput(description: string): z.ZodType<number> {
+  return z
+    .custom<number>((value) => typeof value === "number", { message: "Expected a number" })
+    .meta({ type: "number", description });
+}
+
+/** A string result. */
+export function stringOutput(description: string): z.ZodType<string> {
+  return z.string().describe(description);
+}
+
+/** A boolean result. */
+export function booleanOutput(description: string): z.ZodType<boolean> {
+  return z.boolean().describe(description);
+}
+
+/**
+ * A result whose shape depends on the input or on the program: any JSON value (also
+ * `undefined`). Its JSON Schema is `{}`, so an MCP client gets no output schema for it.
+ */
+export function anyOutput(description: string): z.ZodType<unknown> {
+  return z.unknown().describe(description);
+}
+
+/** An array of any values. */
+export function arrayOutput(description: string): z.ZodType<unknown[]> {
+  return z.array(z.unknown()).describe(description);
+}
+
+/** An object with string keys and any values. */
+export function recordOutput(description: string): z.ZodType<Record<string, unknown>> {
+  return z.record(z.string(), z.unknown()).describe(description);
+}