@procedures/lib 0.0.0-stage → 0.2.0

package/src/procedures/ecosystem/procedures.ts

@@ -0,0 +1,317 @@
+/**
+ * ecosystem.procedures
+ *
+ * Enumerates all procedures across the ecosystem by:
+ * 1. Scanning all packages (lib.scan)
+ * 2. Loading each package's procedure registry
+ * 3. Aggregating using the collector pattern (pure)
+ *
+ * This is a composition of dag traversal + procedure discovery.
+ */
+
+import { z } from "zod";
+import type { ProcedureContext } from "@procedures/client";
+import { libScan } from "../lib/scan.js";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { readFile } from "node:fs/promises";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export const EcosystemProceduresInputSchema: z.ZodObject<{
+  rootPath: z.ZodOptional<z.ZodString>;
+  namespace: z.ZodOptional<z.ZodString>;
+  includeMetadata: z.ZodDefault<z.ZodBoolean>;
+}> = z.object({
+  /** Workspace root (defaults to the pnpm workspace that contains client-lib) */
+  rootPath: z.string().optional().describe("Workspace root (defaults to the pnpm workspace that contains client-lib)"),
+  /** Filter by namespace prefix */
+  namespace: z.string().optional().describe("Filter by namespace prefix"),
+  /** Include full metadata */
+  includeMetadata: z.boolean().default(false).describe("Include full metadata"),
+});
+
+export type EcosystemProceduresInput = z.infer<typeof EcosystemProceduresInputSchema>;
+
+export interface ProcedureInfo {
+  /** Procedure path as array */
+  path: string[];
+  /** Procedure path as dot-separated key */
+  key: string;
+  /** Source package */
+  package: string;
+  /** Package path on disk */
+  packagePath: string;
+  /** Description from metadata */
+  description?: string | undefined;
+  /** Tags from metadata */
+  tags?: string[] | undefined;
+}
+
+export interface PackageProcedures {
+  /** Package name */
+  name: string;
+  /** Package path */
+  path: string;
+  /** Procedures defined in this package */
+  procedures: ProcedureInfo[];
+  /** Whether loading succeeded */
+  success: boolean;
+  /** Error if loading failed */
+  error?: string | undefined;
+}
+
+export interface EcosystemProceduresOutput {
+  /** All procedures aggregated */
+  procedures: ProcedureInfo[];
+  /** Procedures grouped by package */
+  byPackage: PackageProcedures[];
+  /** Procedures grouped by namespace */
+  byNamespace: Record<string, ProcedureInfo[]>;
+  /** Summary counts */
+  summary: {
+    totalPackages: number;
+    packagesWithProcedures: number;
+    totalProcedures: number;
+    namespaces: string[];
+  };
+}
+
+const procedureInfoSchema = z.looseObject({
+  path: z.array(z.string()).describe("The procedure path"),
+  key: z.string().describe("The dotted key of the path"),
+  package: z.string().describe("The package that registers the procedure"),
+  packagePath: z.string().describe("The folder of the package"),
+  description: z.string().optional().describe("The description of the procedure"),
+  tags: z.array(z.string()).optional().describe("The tags of the procedure"),
+});
+
+/** The output schema of ecosystem.procedures (roadmap 2.1). Loose: other fields stay. */
+export const EcosystemProceduresOutputSchema: z.ZodType<EcosystemProceduresOutput> = z.looseObject({
+  procedures: z.array(procedureInfoSchema).describe("Every procedure of the workspace packages"),
+  byPackage: z
+    .array(
+      z.looseObject({
+        name: z.string().describe("The package name"),
+        path: z.string().describe("The package folder"),
+        procedures: z.array(procedureInfoSchema).describe("The procedures of the package"),
+        success: z.boolean().describe("False when the package did not load"),
+        error: z.string().optional().describe("Why the package did not load"),
+      })
+    )
+    .describe("The procedures of each package"),
+  byNamespace: z.record(z.string(), z.array(procedureInfoSchema)).describe("The procedures of each namespace"),
+  summary: z
+    .looseObject({
+      totalPackages: z.number().describe("The number of packages that were examined"),
+      packagesWithProcedures: z.number().describe("The number of packages that have procedures"),
+      totalProcedures: z.number().describe("The number of procedures"),
+      namespaces: z.array(z.string()).describe("The namespaces (first path segments)"),
+    })
+    .describe("The counts"),
+});
+
+// =============================================================================
+// Collector Pattern Implementation
+// =============================================================================
+
+interface Collector<T, A, R> {
+  supplier: () => A;
+  accumulator: (acc: A, element: T) => void;
+  finisher: (acc: A) => R;
+}
+
+function collect<T, A, R>(items: Iterable<T>, collector: Collector<T, A, R>): R {
+  const acc = collector.supplier();
+  for (const item of items) {
+    collector.accumulator(acc, item);
+  }
+  return collector.finisher(acc);
+}
+
+// Collector that aggregates PackageProcedures into EcosystemProceduresOutput
+function ecosystemProceduresCollector(namespace?: string): Collector<
+  PackageProcedures,
+  {
+    procedures: ProcedureInfo[];
+    byPackage: PackageProcedures[];
+    byNamespace: Map<string, ProcedureInfo[]>;
+  },
+  EcosystemProceduresOutput
+> {
+  return {
+    supplier: () => ({
+      procedures: [],
+      byPackage: [],
+      byNamespace: new Map<string, ProcedureInfo[]>(),
+    }),
+    accumulator: (acc, pkg) => {
+      acc.byPackage.push(pkg);
+
+      for (const proc of pkg.procedures) {
+        // Filter by namespace if specified
+        if (namespace && proc.path[0] !== namespace) {
+          continue;
+        }
+
+        acc.procedures.push(proc);
+
+        // Group by namespace
+        const ns = proc.path[0] ?? "root";
+        if (!acc.byNamespace.has(ns)) {
+          acc.byNamespace.set(ns, []);
+        }
+        acc.byNamespace.get(ns)!.push(proc);
+      }
+    },
+    finisher: (acc) => {
+      const namespaces = [...acc.byNamespace.keys()].sort();
+      return {
+        procedures: acc.procedures,
+        byPackage: acc.byPackage,
+        byNamespace: Object.fromEntries(acc.byNamespace),
+        summary: {
+          totalPackages: acc.byPackage.length,
+          packagesWithProcedures: acc.byPackage.filter(p => p.procedures.length > 0).length,
+          totalProcedures: acc.procedures.length,
+          namespaces,
+        },
+      };
+    },
+  };
+}
+
+// =============================================================================
+// Package Procedure Discovery
+// =============================================================================
+
+async function discoverPackageProcedures(
+  packageName: string,
+  packagePath: string,
+  _ctx: ProcedureContext
+): Promise<PackageProcedures> {
+  try {
+    // Read package.json to find client.procedures entry
+    const pkgJsonPath = join(packagePath, "package.json");
+    const pkgJsonContent = await readFile(pkgJsonPath, "utf-8");
+    const pkgJson = JSON.parse(pkgJsonContent) as {
+      client?: { procedures?: string };
+    };
+
+    if (!pkgJson.client?.procedures) {
+      return {
+        name: packageName,
+        path: packagePath,
+        procedures: [],
+        success: true,
+      };
+    }
+
+    // Dynamically import the procedures register file
+    const proceduresPath = join(packagePath, pkgJson.client.procedures);
+
+    // Import to trigger registration. import() needs a file:// URL: a Windows path such as
+    // C:\... is not a valid module specifier (BUGS-2026-07 M33)
+    try {
+      await import(pathToFileURL(proceduresPath).href);
+    } catch (importError) {
+      // May already be imported or path issue - continue anyway
+    }
+
+    // Query the global registry for procedures from this package
+    // We identify procedures by checking if they're in a namespace that
+    // matches the package pattern (e.g., client-fs -> fs.*)
+    const { PROCEDURE_REGISTRY } = await import("@procedures/client");
+    const allProcs = PROCEDURE_REGISTRY.getAll();
+
+    // Extract namespace from package name (e.g., @procedures/fs -> fs)
+    const match = packageName.match(/^@procedures\/(\w+)/) ?? packageName.match(/@mark1russell7\/client-(\w+)/);
+    const expectedNamespace = match ? match[1] : null;
+
+    const procedures: ProcedureInfo[] = [];
+
+    for (const proc of allProcs) {
+      // For now, include all procedures but mark their source
+      // A more sophisticated approach would track which package registered which procedure
+      const meta = proc.metadata as Record<string, unknown> | undefined;
+      const description = meta?.["description"] as string | undefined;
+      const tags = meta?.["tags"] as string[] | undefined;
+
+      // Heuristic: if first path segment matches expected namespace, it's from this package
+      if (expectedNamespace && proc.path[0] === expectedNamespace) {
+        procedures.push({
+          path: proc.path,
+          key: proc.path.join("."),
+          package: packageName,
+          packagePath,
+          description,
+          tags,
+        });
+      } else if (packageName === "@procedures/lib" && proc.path[0] === "lib") {
+        procedures.push({
+          path: proc.path,
+          key: proc.path.join("."),
+          package: packageName,
+          packagePath,
+          description,
+          tags,
+        });
+      } else if (packageName === "@procedures/cli-run" &&
+                 (proc.path[0] === "procedure" || proc.path[0] === "dag")) {
+        procedures.push({
+          path: proc.path,
+          key: proc.path.join("."),
+          package: packageName,
+          packagePath,
+          description,
+          tags,
+        });
+      }
+    }
+
+    return {
+      name: packageName,
+      path: packagePath,
+      procedures,
+      success: true,
+    };
+  } catch (error) {
+    return {
+      name: packageName,
+      path: packagePath,
+      procedures: [],
+      success: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+// =============================================================================
+// Main Procedure
+// =============================================================================
+
+export async function ecosystemProcedures(
+  input: EcosystemProceduresInput,
+  ctx: ProcedureContext
+): Promise<EcosystemProceduresOutput> {
+  // Step 1: Scan all packages
+  const scanResult = await libScan({ rootPath: input.rootPath }, ctx);
+
+  // Step 2: Discover procedures in each package
+  const packageResults: PackageProcedures[] = [];
+
+  for (const [name, info] of Object.entries(scanResult.packages)) {
+    // Only process client-* packages (they have procedures)
+    if (name.includes("/client-") || name === "@procedures/client") {
+      const result = await discoverPackageProcedures(name, info.repoPath, ctx);
+      packageResults.push(result);
+    }
+  }
+
+  // Step 3: Aggregate using collector pattern
+  const output = collect(packageResults, ecosystemProceduresCollector(input.namespace));
+
+  return output;
+}

package/src/procedures/lib/audit.ts

@@ -0,0 +1,307 @@
+/**
+ * lib.audit procedure
+ *
+ * Validates the workspace packages against the package template, and checks for
+ * pnpm settings that do not work in a workspace.
+ */
+
+import { basename, join } from "node:path";
+import { PROCEDURE_REGISTRY, type AnyProcedure, type ProcedureContext } from "@procedures/client";
+import type {
+  FlagNotice,
+  LibAuditInput,
+  LibAuditOutput,
+  PackageAuditResult,
+  PnpmIssue,
+} from "../../types.js";
+import { libScan } from "./scan.js";
+import { resolveWorkspaceRoot } from "../../workspace.js";
+import { CLI_GLOBAL_FLAGS } from "../../cli-flags.js";
+
+interface FsExistsOutput { exists: boolean; path: string; }
+interface FsReadJsonOutput { path: string; data: unknown; }
+interface FsWriteOutput { path: string; bytesWritten: number; }
+interface FsMkdirOutput { path: string; created: boolean; }
+
+/**
+ * The files and folders every client package has. dist/ is not in the list:
+ * it is build output and does not exist before `pnpm build`.
+ */
+export const PACKAGE_TEMPLATE: { files: string[]; dirs: string[] } = {
+  files: ["package.json", "tsconfig.json", "dependencies.json", ".gitignore"],
+  dirs: ["src"],
+};
+
+/**
+ * Folders under packages/ that are not client packages.
+ * packages/cli holds the repository tool from the template, which does not use cue-config.
+ */
+const NOT_CLIENT_PACKAGES = new Set(["cli"]);
+
+/**
+ * Check if path exists
+ */
+async function pathExists(pathStr: string, ctx: ProcedureContext): Promise<boolean> {
+  try {
+    const result = await ctx.client.call<{ path: string }, FsExistsOutput>(
+      ["fs", "exists"],
+      { path: pathStr }
+    );
+    return result.exists;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Package.json structure for pnpm validation
+ */
+interface PackageJson {
+  name?: string;
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+  peerDependencies?: Record<string, string>;
+  pnpm?: unknown;
+}
+
+/**
+ * Check for pnpm configuration that does not work in a workspace
+ */
+async function checkPnpmIssues(
+  pkgPath: string,
+  workspacePackages: Set<string>,
+  ctx: ProcedureContext
+): Promise<PnpmIssue[]> {
+  const issues: PnpmIssue[] = [];
+
+  if (await pathExists(join(pkgPath, "package-lock.json"), ctx)) {
+    issues.push({
+      type: "npm-lockfile",
+      message: "Found package-lock.json - the workspace uses the root pnpm-lock.yaml",
+    });
+  }
+  if (await pathExists(join(pkgPath, "pnpm-lock.yaml"), ctx)) {
+    issues.push({
+      type: "package-lockfile",
+      message: "Found a per-package pnpm-lock.yaml - the workspace uses the root pnpm-lock.yaml",
+    });
+  }
+
+  let pkgJson: PackageJson;
+  try {
+    const result = await ctx.client.call<{ path: string }, FsReadJsonOutput>(
+      ["fs", "read.json"],
+      { path: join(pkgPath, "package.json") }
+    );
+    pkgJson = result.data as PackageJson;
+  } catch {
+    return issues;
+  }
+
+  if (pkgJson.pnpm !== undefined) {
+    issues.push({
+      type: "ignored-pnpm-field",
+      message: 'The "pnpm" field of a workspace package is ignored - use the root pnpm-workspace.yaml',
+    });
+  }
+
+  // A dependency on another workspace package must use the workspace link, not a git reference
+  for (const deps of [pkgJson.dependencies, pkgJson.devDependencies, pkgJson.peerDependencies]) {
+    for (const [name, spec] of Object.entries(deps ?? {})) {
+      if (workspacePackages.has(name) && !spec.startsWith("workspace:")) {
+        issues.push({
+          type: "not-workspace-link",
+          message: `"${name}" is a workspace package but the dependency is "${spec}" - use "workspace:*"`,
+          package: name,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Audit a single package against the template
+ */
+async function auditPackage(
+  pkgPath: string,
+  pkgName: string,
+  template: { files: string[]; dirs: string[] },
+  workspacePackages: Set<string>,
+  fix: boolean,
+  ctx: ProcedureContext
+): Promise<PackageAuditResult> {
+  const missingFiles: string[] = [];
+  const missingDirs: string[] = [];
+  const fixedFiles: string[] = [];
+  const fixedDirs: string[] = [];
+
+  // Check required directories
+  for (const dir of template.dirs) {
+    const dirPath = join(pkgPath, dir);
+    if (!(await pathExists(dirPath, ctx))) {
+      missingDirs.push(dir);
+      if (fix) {
+        try {
+          await ctx.client.call<{ path: string; recursive?: boolean }, FsMkdirOutput>(
+            ["fs", "mkdir"],
+            { path: dirPath, recursive: true }
+          );
+          fixedDirs.push(dir);
+        } catch {
+          // Could not fix
+        }
+      }
+    }
+  }
+
+  // Check required files
+  for (const file of template.files) {
+    const filePath = join(pkgPath, file);
+    if (!(await pathExists(filePath, ctx))) {
+      missingFiles.push(file);
+      if (fix) {
+        // Only fix certain files with sensible defaults
+        try {
+          if (file === "dependencies.json") {
+            await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(
+              ["fs", "write"],
+              {
+                path: filePath,
+                content: JSON.stringify(
+                  { $schema: "./node_modules/@mark1russell7/cue/dependencies/schema.json", dependencies: ["ts", "node"] },
+                  null,
+                  2
+                ) + "\n"
+              }
+            );
+            fixedFiles.push(file);
+          } else if (file === ".gitignore") {
+            await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(
+              ["fs", "write"],
+              { path: filePath, content: "node_modules/\ndist/\n.tsbuildinfo\n" }
+            );
+            fixedFiles.push(file);
+          }
+          // Don't auto-create package.json or tsconfig.json - those need cue-config generate
+        } catch {
+          // Could not fix
+        }
+      }
+    }
+  }
+
+  // Check pnpm configuration
+  const pnpmIssues = await checkPnpmIssues(pkgPath, workspacePackages, ctx);
+
+  // Remove fixed items from missing lists
+  const stillMissingFiles = missingFiles.filter((f) => !fixedFiles.includes(f));
+  const stillMissingDirs = missingDirs.filter((d) => !fixedDirs.includes(d));
+
+  // Package is valid only if no missing files/dirs AND no pnpm issues
+  const isValid = stillMissingFiles.length === 0 && stillMissingDirs.length === 0 && pnpmIssues.length === 0;
+
+  return {
+    name: pkgName,
+    path: pkgPath,
+    valid: isValid,
+    missingFiles: stillMissingFiles,
+    missingDirs: stillMissingDirs,
+    pnpmIssues,
+    ...(fix && fixedFiles.length > 0 ? { fixedFiles } : {}),
+    ...(fix && fixedDirs.length > 0 ? { fixedDirs } : {}),
+  };
+}
+
+/**
+ * The field names of a procedure's input schema (a Zod object, also through zodAdapter)
+ */
+function inputFieldNames(schema: unknown): string[] {
+  const node = schema as { shape?: unknown; _def?: { shape?: () => Record<string, unknown> } } | undefined;
+  if (node?.shape && typeof node.shape === "object") {
+    return Object.keys(node.shape);
+  }
+  if (typeof node?._def?.shape === "function") {
+    return Object.keys(node._def.shape());
+  }
+  return [];
+}
+
+/**
+ * The procedure flags that hide a global flag of `mark` after the command path. `mark` gives a
+ * flag after the path to the procedure when the procedure declares it, so the user must give
+ * the global flag before the command. The server options (`--port`, `--host`, `--transport`)
+ * are not reported: they are global only with `--server`, which takes no command.
+ */
+export function findFlagNotices(procedures: readonly AnyProcedure[]): FlagNotice[] {
+  const notices: FlagNotice[] = [];
+  const globals = CLI_GLOBAL_FLAGS.filter((flag) => !flag.serverOption);
+  for (const procedure of procedures) {
+    const name = procedure.path.join(" ");
+    const shorts = ((procedure.metadata ?? {}) as { shorts?: Record<string, string> }).shorts ?? {};
+    for (const [field, letter] of Object.entries(shorts)) {
+      const global = globals.find((flag) => flag.short === letter);
+      if (global) {
+        notices.push({ procedure: name, flag: `-${letter} (${field})`, global: `-${letter} (--${global.long})` });
+      }
+    }
+    for (const field of inputFieldNames(procedure.input)) {
+      const kebab = field.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+      const global = globals.find((flag) => flag.long === field || flag.long === kebab);
+      if (global) {
+        notices.push({ procedure: name, flag: `--${kebab}`, global: `--${global.long}` });
+      }
+    }
+  }
+  return notices;
+}
+
+/**
+ * Audit all client packages of the workspace against the package template. The result also
+ * lists the procedure flags that hide a global flag of `mark` (information only).
+ */
+export async function libAudit(input: LibAuditInput, ctx: ProcedureContext): Promise<LibAuditOutput> {
+  const template = PACKAGE_TEMPLATE;
+  const flagNotices = findFlagNotices(PROCEDURE_REGISTRY.getAll());
+  const empty: LibAuditOutput = {
+    success: false,
+    flagNotices,
+    template,
+    results: [],
+    summary: { total: 0, valid: 0, invalid: 0 },
+  };
+
+  let rootPath: string;
+  try {
+    rootPath = resolveWorkspaceRoot(input.rootPath);
+  } catch {
+    return empty;
+  }
+
+  const scan = await libScan({ rootPath }, ctx);
+  const workspacePackages = new Set(Object.keys(scan.packages));
+  const results: PackageAuditResult[] = [];
+
+  for (const info of Object.values(scan.packages)) {
+    if (NOT_CLIENT_PACKAGES.has(basename(info.repoPath))) {
+      continue;
+    }
+    results.push(await auditPackage(info.repoPath, info.name, template, workspacePackages, input.fix, ctx));
+  }
+
+  const validCount = results.filter((r) => r.valid).length;
+  const invalidCount = results.filter((r) => !r.valid).length;
+
+  return {
+    success: invalidCount === 0,
+    flagNotices,
+    template,
+    results,
+    summary: {
+      total: results.length,
+      valid: validCount,
+      invalid: invalidCount,
+    },
+  };
+}

package/src/procedures/lib/index.ts

@@ -0,0 +1,8 @@
+/**
+ * lib procedures
+ */
+
+export { libScan } from "./scan.js";
+export { libRename } from "./rename.js";
+export { libNew } from "./new.js";
+export { libAudit } from "./audit.js";