@procedures/lib 0.0.0-stage → 0.2.0

package/src/module.ts

@@ -0,0 +1,232 @@
+/**
+ * Module (no side effects): the procedures of this package as data, for `createRegistry()`.
+ *
+ * Procedure Registration for lib operations
+ *
+ * This is the canonical home for lib.* procedures.
+ * client-cli no longer registers these to avoid duplicates.
+ */
+
+import { createProcedure, zodAdapter, RUNS_REFS_TAG, defineModule, type ProcedureModule, PROCEDURE_REGISTRY, registerModules, type ProcedureRegistry } from "@procedures/client";
+import gitModule from "@procedures/git/module";
+import fsModule from "@procedures/fs/module";
+import {
+  libScan,
+  libRename,
+  libNew,
+  libAudit,
+} from "./procedures/lib/index.js";
+import {
+  ecosystemProcedures,
+  EcosystemProceduresInputSchema,
+  EcosystemProceduresOutputSchema,
+  type EcosystemProceduresInput,
+  type EcosystemProceduresOutput,
+} from "./procedures/ecosystem/index.js";
+import { dagTraverse } from "./procedures/dag/index.js";
+import { coreCatch } from "./procedures/core/index.js";
+import {
+  LibScanInputSchema,
+  LibRenameInputSchema,
+  LibNewInputSchema,
+  LibAuditInputSchema,
+  DagTraverseInputSchema,
+  CoreCatchInputSchema,
+  type LibScanInput,
+  type LibScanOutput,
+  type LibRenameInput,
+  type LibRenameOutput,
+  type LibNewInput,
+  type LibNewOutput,
+  type LibAuditInput,
+  type LibAuditOutput,
+  type DagTraverseInput,
+  type DagTraverseOutput,
+  type CoreCatchInput,
+  type CoreCatchOutput,
+  LibScanOutputSchema,
+  LibRenameOutputSchema,
+  LibNewOutputSchema,
+  LibAuditOutputSchema,
+  DagTraverseOutputSchema,
+  CoreCatchOutputSchema,
+} from "./types.js";
+import type { ProcedureContext } from "@procedures/client";
+
+// =============================================================================
+// lib.* Procedures
+// =============================================================================
+
+const libScanProcedure = createProcedure()
+  .path(["lib", "scan"])
+  .input(zodAdapter<LibScanInput>(LibScanInputSchema))
+  .output(zodAdapter<LibScanOutput>(LibScanOutputSchema))
+  .meta({
+    description: "Scan for packages in the git directory",
+    calls: ["fs.readdir", "fs.read.json", "git.status", "git.remote"],
+    effects: { reads: ["fs"], writes: [] },
+    args: [],
+    shorts: {},
+    output: "json",
+  })
+  .handler(async (input: LibScanInput, ctx: ProcedureContext): Promise<LibScanOutput> => {
+    return libScan(input, ctx);
+  })
+  .build();
+
+const libRenameProcedure = createProcedure()
+  .path(["lib", "rename"])
+  .input(zodAdapter<LibRenameInput>(LibRenameInputSchema))
+  .output(zodAdapter<LibRenameOutput>(LibRenameOutputSchema))
+  .meta({
+    description: "Rename a package across the ecosystem",
+    calls: ["fs.glob", "fs.read.json", "fs.write", "fs.exists"],
+    // It rewrites package.json files and TypeScript imports of the whole workspace
+    effects: { reads: ["fs"], writes: ["fs"] },
+    args: ["oldName", "newName"],
+    shorts: { dryRun: "n" },
+    output: "json",
+  })
+  .handler(async (input: LibRenameInput, ctx: ProcedureContext): Promise<LibRenameOutput> => {
+    return libRename(input, ctx);
+  })
+  .build();
+
+const libNewProcedure = createProcedure()
+  .path(["lib", "new"])
+  .input(zodAdapter<LibNewInput>(LibNewInputSchema))
+  .output(zodAdapter<LibNewOutput>(LibNewOutputSchema))
+  .meta({
+    description: "Create a new package in the ecosystem",
+    calls: ["shell.run", "fs.exists", "fs.mkdir", "fs.write", "fs.read.json"],
+    // It starts the cue-config CLI from the node_modules of the workspace: code of the project,
+    // so it writes process. That CLI writes only files of the new package folder. An existing
+    // folder is an error, so the procedure overwrites nothing.
+    effects: { reads: ["fs"], writes: ["fs", "process"], destructive: false },
+    args: ["name"],
+    shorts: { dryRun: "n" },
+    output: "json",
+  })
+  .handler(async (input: LibNewInput, ctx: ProcedureContext): Promise<LibNewOutput> => {
+    return libNew(input, ctx);
+  })
+  .build();
+
+const libAuditProcedure = createProcedure()
+  .path(["lib", "audit"])
+  .input(zodAdapter<LibAuditInput>(LibAuditInputSchema))
+  .output(zodAdapter<LibAuditOutput>(LibAuditOutputSchema))
+  .meta({
+    description: "Audit ecosystem packages for issues",
+    calls: ["fs.readdir", "fs.read.json", "git.status", "git.remote", "fs.exists", "fs.mkdir", "fs.write"],
+    // It reads the registry for the flag notices. With `fix`, it makes only the missing folders
+    // and files, so a second call changes nothing more.
+    effects: { reads: ["fs", "registry"], writes: ["fs"], destructive: false, idempotent: true },
+    args: [],
+    shorts: { fix: "f" },
+    output: "json",
+  })
+  .handler(async (input: LibAuditInput, ctx: ProcedureContext): Promise<LibAuditOutput> => {
+    return libAudit(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// ecosystem.* Procedures
+// =============================================================================
+
+const ecosystemProceduresProcedure = createProcedure()
+  .path(["ecosystem", "procedures"])
+  .input(zodAdapter<EcosystemProceduresInput>(EcosystemProceduresInputSchema))
+  .output(zodAdapter<EcosystemProceduresOutput>(EcosystemProceduresOutputSchema))
+  .meta({
+    description: "List all procedures across the ecosystem",
+    // It imports the register file of each package: that code runs, and it registers procedures
+    effects: { reads: ["fs", "registry"], writes: ["process", "registry"] },
+    args: [],
+    shorts: { namespace: "n" },
+    output: "json",
+  })
+  .handler(async (input: EcosystemProceduresInput, ctx: ProcedureContext): Promise<EcosystemProceduresOutput> => {
+    return ecosystemProcedures(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// dag.* Procedures
+// =============================================================================
+
+const dagTraverseProcedure = createProcedure()
+  .path(["dag", "traverse"])
+  .input(zodAdapter<DagTraverseInput>(DagTraverseInputSchema))
+  .output(zodAdapter<DagTraverseOutput>(DagTraverseOutputSchema))
+  .meta({
+    description: "Traverse ecosystem packages in dependency order, executing visit procedure for each",
+    // It runs the procedure refs of its input: a server with an expose rule limits what they call
+    tags: [RUNS_REFS_TAG],
+    // Its own effect is the scan of the workspace. The admission examines each visit call.
+    effects: { reads: ["fs"], writes: [] },
+    args: [],
+    shorts: { root: "r", concurrency: "j", continueOnError: "c", dryRun: "d" },
+    output: "streaming",
+  })
+  .handler(async (input: DagTraverseInput, ctx: ProcedureContext): Promise<DagTraverseOutput> => {
+    return dagTraverse(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// core.* Procedures
+// =============================================================================
+
+const coreCatchProcedure = createProcedure()
+  .path(["core", "catch"])
+  .input(zodAdapter<CoreCatchInput>(CoreCatchInputSchema))
+  .output(zodAdapter<CoreCatchOutput>(CoreCatchOutputSchema))
+  .meta({
+    description: "Execute a procedure with error handling",
+    // It runs the procedure refs of its input: a server with an expose rule limits what they call
+    tags: [RUNS_REFS_TAG],
+    // Control flow: no effects of its own. The admission examines each nested call.
+    effects: { reads: [], writes: [] },
+    args: [],
+    shorts: {},
+    output: "json",
+  })
+  .handler(async (input: CoreCatchInput, ctx: ProcedureContext): Promise<CoreCatchOutput> => {
+    return coreCatch(input, ctx);
+  })
+  .build();
+
+// =============================================================================
+// Registration
+// =============================================================================
+
+/**
+ * The module of this package, for `createRegistry()`: its procedures as data. Importing this
+ * file registers nothing. (`register.ts` registers the same procedures in the global registry.)
+ */
+export const libModule: ProcedureModule = defineModule("@procedures/lib", [
+    // lib.* procedures (canonical home)
+    libScanProcedure,
+    libRenameProcedure,
+    libNewProcedure,
+    libAuditProcedure,
+    // ecosystem.* procedures
+    ecosystemProceduresProcedure,
+    // dag.* procedures (canonical home)
+    dagTraverseProcedure,
+    // core.* procedures
+    coreCatchProcedure,
+  ], [fsModule, gitModule]);
+
+export default libModule;
+
+/**
+ * This function registers the procedures of @procedures/lib, and of the modules that it requires, in
+ * a registry. The default is the global registry. Importing this file registers nothing: the
+ * `./register` entry starts this function (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+export function registerLibProcedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [libModule]);
+}

package/src/procedures/core/catch.ts

@@ -0,0 +1,142 @@
+/**
+ * core.catch procedure
+ *
+ * Wraps a procedure execution with error handling.
+ * The `try` procedure ref should use `$when: "catch"` so it's not
+ * executed during hydration but instead by this procedure.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   $proc: ["core", "catch"],
+ *   input: {
+ *     try: {
+ *       $proc: ["git", "commit"],
+ *       input: { message: "auto" },
+ *       $when: "catch"  // Defer execution to catch procedure
+ *     },
+ *     handler: {
+ *       $proc: ["core", "identity"],
+ *       input: { value: { continue: true } },
+ *       $when: "catch"
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+import type { ProcedureContext, ProcedurePath } from "@procedures/client";
+import {
+  isAnyProcedureRef,
+  normalizeRef,
+  hydrateInput,
+  scopeOf,
+  type StepResultInfo,
+  type ContinueDecision,
+} from "@procedures/client";
+import type { CoreCatchInput, CoreCatchOutput } from "../../types.js";
+
+/**
+ * Execute a procedure with error handling
+ */
+export async function coreCatch(
+  input: CoreCatchInput,
+  ctx: ProcedureContext
+): Promise<CoreCatchOutput> {
+  const { try: tryRef, handler: handlerRef, cwd } = input;
+  // The names of the chain around this procedure: a `$ref` in an operand can read them
+  const scope = scopeOf(input);
+
+  // Validate try is a procedure ref
+  if (!isAnyProcedureRef(tryRef)) {
+    throw new Error("catch: 'try' must be a procedure reference with $when: \"catch\"");
+  }
+
+  // Create executor that uses client.call
+  const executor = async <TIn, TOut>(path: ProcedurePath, inp: TIn): Promise<TOut> => {
+    // Inject cwd if provided
+    const inputWithCwd = cwd && typeof inp === "object" && inp !== null
+      ? { ...inp, cwd }
+      : inp;
+    return ctx.client.call(path, inputWithCwd) as Promise<TOut>;
+  };
+
+  // Normalize the try ref
+  const normalizedTry = normalizeRef(tryRef);
+
+  // Build input for try, merging with cwd
+  const tryInput = {
+    ...(typeof normalizedTry.input === "object" ? normalizedTry.input : {}),
+    ...(cwd ? { cwd } : {}),
+  };
+
+  try {
+    // Hydrate the try input (execute any nested $immediate refs). The hydration is inside the
+    // `try`: a nested ref that throws is an error of the `try` step (deep dive DATA-22).
+    const hydratedTryInput = await hydrateInput(tryInput, executor, {
+      contextStack: ["catch"],
+      onRef: ctx.onRef,
+      scope,
+    });
+
+    // Execute the try procedure
+    const result = await ctx.client.call(normalizedTry.path, hydratedTryInput);
+
+    return {
+      success: true,
+      result,
+      continue: true,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+
+    // If no handler, return error result with continue: false
+    if (!handlerRef || !isAnyProcedureRef(handlerRef)) {
+      return {
+        success: false,
+        error: errorMessage,
+        continue: false,
+      };
+    }
+
+    // Build StepResultInfo for handler
+    const resultInfo: StepResultInfo = {
+      success: false,
+      error: errorMessage,
+      proc: normalizedTry.path,
+    };
+
+    // Execute handler with result info merged into its input
+    const normalizedHandler = normalizeRef(handlerRef);
+    const handlerInput = {
+      ...(typeof normalizedHandler.input === "object" ? normalizedHandler.input : {}),
+      ...resultInfo,
+      ...(cwd ? { cwd } : {}),
+    };
+
+    try {
+      // Hydrate handler input (a failure here is a failure of the handler)
+      const hydratedHandlerInput = await hydrateInput(handlerInput, executor, {
+        contextStack: ["catch"],
+        onRef: ctx.onRef,
+        scope,
+      });
+
+      const decision = await ctx.client.call(normalizedHandler.path, hydratedHandlerInput) as ContinueDecision;
+
+      return {
+        success: false,
+        error: errorMessage,
+        result: decision,
+        continue: decision.continue ?? false,
+      };
+    } catch (handlerError) {
+      // Handler itself failed
+      return {
+        success: false,
+        error: `Handler failed: ${handlerError instanceof Error ? handlerError.message : String(handlerError)}`,
+        continue: false,
+      };
+    }
+  }
+}

package/src/procedures/core/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Core control-flow procedures that require ProcedureContext
+ *
+ * These procedures need access to the client for executing procedure refs
+ * with proper error handling and control flow.
+ */
+
+export { coreCatch } from "./catch.js";
+export type { CoreCatchInput, CoreCatchOutput } from "../../types.js";

package/src/procedures/dag/index.ts

@@ -0,0 +1,5 @@
+/**
+ * DAG Procedures
+ */
+
+export { dagTraverse } from "./traverse.js";

package/src/procedures/dag/traverse.ts

@@ -0,0 +1,281 @@
+/**
+ * dag.traverse procedure
+ *
+ * General-purpose DAG traversal that executes a visit procedure
+ * for each node in dependency order.
+ *
+ * This enables declarative composition of traversals:
+ * ```typescript
+ * // Execute git add on all packages (using $when: "$parent")
+ * await client.exec({
+ *   $proc: ["dag", "traverse"],
+ *   input: {
+ *     visit: {
+ *       $proc: ["git", "add"],
+ *       input: { all: true },
+ *       $when: "$parent"  // Defer to dag.traverse
+ *     }
+ *   }
+ * });
+ *
+ * // Simple form with just procedure path
+ * await client.exec({
+ *   $proc: ["dag", "traverse"],
+ *   input: {
+ *     visit: ["git", "add"]
+ *   }
+ * });
+ * ```
+ *
+ * The `$when` field controls when nested $proc refs are executed:
+ * - "$immediate" (default): Execute during hydration
+ * - "$parent": Defer to parent procedure (dag.traverse executes per-node)
+ * - "$never": Never auto-execute, pass as pure data
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import type { ProcedureContext, ProcedurePath } from "@procedures/client";
+import { isAnyProcedureRef, hydrateInput, scopeOf } from "@procedures/client";
+import type {
+  DAGNode,
+  DagTraverseInput,
+  DagTraverseOutput,
+  TraverseNodeResult,
+} from "../../types.js";
+import { libScan } from "../lib/scan.js";
+import {
+  buildDAGNodes,
+  buildLeveledDAG,
+  executeDAG,
+  createProcessor,
+  filterDAGFromRoot,
+} from "../../dag/index.js";
+
+/** The folder of the git repository that holds `path` (it has `.git`), or `path` itself. */
+export function repositoryRoot(path: string): string {
+  let current = resolve(path);
+  for (;;) {
+    if (existsSync(join(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(path);
+    current = parent;
+  }
+}
+
+/** True when the value names a `git` procedure: a path, or a `$proc` ref at any depth. */
+export function callsGit(value: unknown): boolean {
+  if (Array.isArray(value)) {
+    if (value[0] === "git" && value.every((part) => typeof part === "string")) return true;
+    return value.some(callsGit);
+  }
+  if (typeof value === "object" && value !== null) {
+    return Object.values(value).some(callsGit);
+  }
+  return false;
+}
+
+/**
+ * Run the tasks of one key one at a time, in the order of the calls. Tasks of other keys run
+ * in parallel.
+ */
+export function keyedLock(): <T>(key: string, task: () => Promise<T>) => Promise<T> {
+  const tails = new Map<string, Promise<void>>();
+  return async <T>(key: string, task: () => Promise<T>): Promise<T> => {
+    const previous = tails.get(key) ?? Promise.resolve();
+    let release!: () => void;
+    const done = new Promise<void>((resolveDone) => {
+      release = resolveDone;
+    });
+    const tail = previous.then(() => done);
+    tails.set(key, tail);
+    await previous;
+    try {
+      return await task();
+    } finally {
+      release();
+      if (tails.get(key) === tail) tails.delete(key);
+    }
+  };
+}
+
+/**
+ * Execute a DAG traversal with a custom visit procedure
+ *
+ * The visits of nodes in one git repository run one at a time when the visit calls git (or
+ * with `serialize: "repository"`). All the packages of a workspace share one repository, and
+ * concurrent `git add` calls failed on `index.lock` (deep dive DATA-17).
+ */
+export async function dagTraverse(
+  input: DagTraverseInput,
+  ctx: ProcedureContext
+): Promise<DagTraverseOutput> {
+  const startTime = Date.now();
+  const results: TraverseNodeResult[] = [];
+
+  // Scan for all packages
+  const scanResult = await libScan(input.rootPath !== undefined ? { rootPath: input.rootPath } : {}, ctx);
+  let allNodes = buildDAGNodes(scanResult.packages);
+
+  // Filter to specific packages if requested
+  if (input.filter && input.filter.length > 0) {
+    const filtered = new Map<string, DAGNode>();
+    for (const name of input.filter) {
+      const node = allNodes.get(name);
+      if (node) {
+        filtered.set(name, node);
+      }
+    }
+    allNodes = filtered;
+  }
+
+  // Filter to root and its dependencies if requested
+  if (input.root) {
+    const rootNode = allNodes.get(input.root);
+    if (!rootNode) {
+      return {
+        success: false,
+        results: [],
+        totalDuration: Date.now() - startTime,
+        visited: 0,
+        failed: 0,
+      };
+    }
+    allNodes = filterDAGFromRoot(allNodes, input.root);
+  }
+
+  // Build DAG for dependency-ordered execution
+  const dag = buildLeveledDAG(allNodes);
+
+  // Determine how to execute the visit procedure
+  // visit can be:
+  // - Array: procedure path like ["git", "add"]
+  // - $proc ref: { $proc: [...], input: {...}, $when: "$parent" }
+  const visitIsRef = isAnyProcedureRef(input.visit);
+  let visitPath: ProcedurePath;
+  let baseInput: unknown = {};
+
+  if (Array.isArray(input.visit)) {
+    visitPath = input.visit;
+  } else if (visitIsRef && typeof input.visit === "object" && "$proc" in input.visit) {
+    visitPath = input.visit.$proc;
+    baseInput = input.visit.input ?? {};
+  } else {
+    throw new Error("visit must be a procedure path or $proc reference with $when");
+  }
+
+  const serialize = input.serialize ?? "auto";
+  const oneAtATime = serialize === "repository" || (serialize === "auto" && callsGit(input.visit));
+  const lock = keyedLock();
+
+  // Create processor that executes visit procedure per node
+  const processor = createProcessor(async (node: DAGNode) => {
+    if (oneAtATime) {
+      await lock(repositoryRoot(node.repoPath), () => visit(node));
+    } else {
+      await visit(node);
+    }
+  });
+
+  async function visit(node: DAGNode): Promise<void> {
+    if (input.dryRun) {
+      results.push({
+        name: node.name,
+        path: node.repoPath,
+        success: true,
+        duration: 0,
+        output: { dryRun: true, wouldExecute: visitPath },
+      });
+      return;
+    }
+
+    const nodeStartTime = Date.now();
+
+    try {
+      // Merge base input with node context
+      const visitInput = {
+        ...(typeof baseInput === "object" ? baseInput : {}),
+        cwd: node.repoPath,
+        node: {
+          name: node.name,
+          path: node.repoPath,
+          dependencies: node.dependencies,
+        },
+      };
+
+      // Create executor for hydration that injects cwd into every call
+      const executor = async <TIn, TOut>(path: ProcedurePath, inp: TIn): Promise<TOut> => {
+        // Inject cwd into the input so nested procedures run in correct directory
+        const inputWithCwd = typeof inp === "object" && inp !== null
+          ? { ...inp, cwd: node.repoPath }
+          : inp;
+        return ctx.client.call(path, inputWithCwd) as Promise<TOut>;
+      };
+
+      // Hydrate the input (execute any nested procedure refs like chain steps)
+      // Push "dag.traverse" onto context stack so refs with $when: "dag.traverse" execute
+      const hydratedInput = await hydrateInput(visitInput, executor, {
+        contextStack: ["dag.traverse"],
+        onRef: ctx.onRef,
+        // The names of the chain around this procedure: a `$ref` in the visit can read them
+        scope: scopeOf(input),
+      });
+
+      // Execute visit procedure with hydrated input
+      const output = await ctx.client.call(visitPath, hydratedInput);
+
+      results.push({
+        name: node.name,
+        path: node.repoPath,
+        success: true,
+        duration: Date.now() - nodeStartTime,
+        output,
+      });
+    } catch (error) {
+      const result: TraverseNodeResult = {
+        name: node.name,
+        path: node.repoPath,
+        success: false,
+        duration: Date.now() - nodeStartTime,
+        error: error instanceof Error ? error.message : String(error),
+      };
+      results.push(result);
+      throw error; // Re-throw for DAG executor to handle
+    }
+  }
+
+  // Execute DAG traversal
+  const dagResult = await executeDAG(dag, processor, {
+    concurrency: input.concurrency ?? 4,
+    failFast: !input.continueOnError,
+  });
+
+  // If dry run, we already populated results in the processor
+  if (!input.dryRun) {
+    // Ensure all nodes have results (some may have been skipped due to errors)
+    for (const [name, nodeResult] of dagResult.results) {
+      const existing = results.find((r) => r.name === name);
+      if (!existing) {
+        const node = allNodes.get(name);
+        const result: TraverseNodeResult = {
+          name,
+          path: node?.repoPath ?? "unknown",
+          success: nodeResult.success,
+          duration: nodeResult.duration,
+        };
+        if (nodeResult.error?.message) {
+          result.error = nodeResult.error.message;
+        }
+        results.push(result);
+      }
+    }
+  }
+
+  return {
+    success: dagResult.success,
+    results,
+    totalDuration: Date.now() - startTime,
+    visited: results.filter((r) => r.success).length,
+    failed: results.filter((r) => !r.success).length,
+  };
+}

package/src/procedures/ecosystem/index.ts

@@ -0,0 +1,12 @@
+/**
+ * ecosystem procedures
+ */
+
+export { ecosystemProcedures } from "./procedures.js";
+export type {
+  EcosystemProceduresInput,
+  EcosystemProceduresOutput,
+  ProcedureInfo,
+  PackageProcedures,
+} from "./procedures.js";
+export { EcosystemProceduresInputSchema, EcosystemProceduresOutputSchema } from "./procedures.js";