@procedures/lib 0.0.0-stage → 0.2.0

package/src/procedures/lib/new.ts

@@ -0,0 +1,253 @@
+/**
+ * lib.new procedure
+ *
+ * Creates a new client package in the workspace, at packages/<name>, with the
+ * structure the other client packages have: cue-config files, src/module.ts (the procedures as
+ * data), src/register.ts (the only file with a side effect), src/index.ts, src/types.ts, the
+ * "./module" and "./register" exports and the "client.procedures" field. Importing the package
+ * root registers nothing (ARCHITECTURE-PROPOSALS-2026-10, P9). `mark procedure new` then adds
+ * procedures to the module, and they compile.
+ * Uses fs.* and shell.* procedures via ctx.client.call() for all operations.
+ *
+ * After it, run `pnpm install` and `pnpm build` in the workspace root.
+ */
+
+import { join } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { LibNewInput, LibNewOutput } from "../../types.js";
+import { packagesDir, resolveWorkspaceRoot } from "../../workspace.js";
+
+interface ShellRunOutput {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  success: boolean;
+}
+
+// The root registers nothing: `import "<package>/register"` or `createRegistry()` registers the procedures
+const INDEX_TS = `// The root registers nothing: import "<package>/register", or give the module to createRegistry()
+export * from "./module.js";
+export * from "./types.js";
+`;
+
+// \`mark procedure new\` appends the types of each procedure, and adds the zod import then.
+// An unused import here would fail noUnusedLocals (deep dive CLI-13).
+const TYPES_TS = `/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here.
+ */
+
+export {};
+`;
+
+/** The names of a package folder in code: "my-package" gives "myPackage" and "MyPackage". */
+function codeNames(name: string): { camel: string; pascal: string } {
+  const pascal = name
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean)
+    .map((part) => part[0]!.toUpperCase() + part.slice(1))
+    .join("");
+  return { camel: pascal[0]!.toLowerCase() + pascal.slice(1), pascal };
+}
+
+function moduleTs(name: string, packageName: string): string {
+  const { camel, pascal } = codeNames(name);
+  return `/**
+ * The procedures of ${packageName} as data. Importing this file registers nothing.
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path packages/${name}
+ */
+
+import { defineModule, registerModules, PROCEDURE_REGISTRY, type ProcedureModule, type ProcedureRegistry } from "@procedures/client";
+
+export const ${camel}Module: ProcedureModule = defineModule("${packageName}", []);
+
+export default ${camel}Module;
+
+/**
+ * This function registers the procedures of ${packageName} in a registry. The default is the
+ * global registry.
+ */
+export function register${pascal}Procedures(registry: ProcedureRegistry = PROCEDURE_REGISTRY): void {
+  registerModules(registry, [${camel}Module]);
+}
+`;
+}
+
+function registerTs(name: string, packageName: string): string {
+  const { pascal } = codeNames(name);
+  return `/**
+ * Importing this file registers the procedures of ${packageName} in the global registry:
+ * \`import "${packageName}/register"\`. The package root registers nothing.
+ */
+
+import { register${pascal}Procedures } from "./module.js";
+
+export * from "./module.js";
+
+register${pascal}Procedures();
+`;
+}
+
+/**
+ * Run the workspace's cue-config CLI (not npx: a new package has no node_modules,
+ * and npx would download an unrelated package from the registry).
+ */
+async function runCueConfig(
+  cueCli: string,
+  args: string[],
+  cwd: string,
+  ctx: ProcedureContext
+): Promise<void> {
+  const result = await ctx.client.call<
+    { command: string; args: string[]; cwd: string },
+    ShellRunOutput
+  >(["shell", "run"], { command: process.execPath, args: [cueCli, ...args], cwd });
+  if (!result.success) {
+    throw new Error(`cue-config ${args.join(" ")} failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+  }
+}
+
+/**
+ * Create a new client package in the workspace
+ */
+export async function libNew(input: LibNewInput, ctx: ProcedureContext): Promise<LibNewOutput> {
+  const operations: string[] = [];
+  const created: string[] = [];
+  const errors: string[] = [];
+  const packageName = `@procedures/${input.name}`;
+
+  let rootPath: string;
+  try {
+    rootPath = resolveWorkspaceRoot(input.rootPath);
+  } catch (error) {
+    return {
+      success: false,
+      packageName,
+      packagePath: "",
+      created: [],
+      operations: [],
+      errors: [error instanceof Error ? error.message : String(error)],
+    };
+  }
+
+  const packagePath = join(packagesDir(rootPath), input.name);
+  const cueCli = join(rootPath, "node_modules", "@mark1russell7", "cue", "dist", "cli.js");
+
+  // Check if package already exists
+  const existsResult = await ctx.client.call<{ path: string }, { exists: boolean; path: string }>(
+    ["fs", "exists"],
+    { path: packagePath }
+  );
+  if (existsResult.exists) {
+    return {
+      success: false,
+      packageName,
+      packagePath,
+      created: [],
+      operations: [],
+      errors: [`Package directory already exists: ${packagePath}`],
+    };
+  }
+
+  const files = [
+    join(packagePath, "src", "index.ts"),
+    join(packagePath, "src", "module.ts"),
+    join(packagePath, "src", "register.ts"),
+    join(packagePath, "src", "types.ts"),
+    join(packagePath, "dependencies.json"),
+    join(packagePath, "package.json"),
+    join(packagePath, "tsconfig.json"),
+    join(packagePath, ".gitignore"),
+  ];
+
+  if (input.dryRun) {
+    return {
+      success: true,
+      packageName,
+      packagePath,
+      created: [`${packagePath}/`, `${join(packagePath, "src")}/`, ...files],
+      operations: [
+        "Would create packages/" + input.name + " with src/index.ts, src/module.ts, src/register.ts and src/types.ts",
+        `Would run cue-config init --preset ${input.preset}`,
+        "Would run cue-config generate",
+        `Would set the package name to ${packageName}, the exports, client.procedures and the client dependency`,
+        "Then run pnpm install and pnpm build in the workspace root",
+      ],
+      errors: [],
+    };
+  }
+
+  try {
+    // Step 1: Create the folders and the source files
+    operations.push("Creating directory structure");
+    await ctx.client.call<{ path: string; recursive?: boolean }, { path: string; created: boolean }>(
+      ["fs", "mkdir"],
+      { path: join(packagePath, "src"), recursive: true }
+    );
+    created.push(`${packagePath}/`, `${join(packagePath, "src")}/`);
+
+    for (const [file, content] of [
+      [join(packagePath, "src", "index.ts"), INDEX_TS],
+      [join(packagePath, "src", "module.ts"), moduleTs(input.name, packageName)],
+      [join(packagePath, "src", "register.ts"), registerTs(input.name, packageName)],
+      [join(packagePath, "src", "types.ts"), TYPES_TS],
+    ] as const) {
+      await ctx.client.call<{ path: string; content: string }, { path: string; bytesWritten: number }>(
+        ["fs", "write"],
+        { path: file, content }
+      );
+      created.push(file);
+    }
+
+    // Step 2: cue-config init and generate (dependencies.json, package.json, tsconfig.json, .gitignore)
+    operations.push(`Running cue-config init --preset ${input.preset}`);
+    await runCueConfig(cueCli, ["init", "--preset", input.preset, "--force"], packagePath, ctx);
+    created.push(join(packagePath, "dependencies.json"));
+
+    operations.push("Running cue-config generate");
+    await runCueConfig(cueCli, ["generate"], packagePath, ctx);
+    created.push(join(packagePath, "package.json"), join(packagePath, "tsconfig.json"), join(packagePath, ".gitignore"));
+
+    // Step 3: cue-config writes the CUE default name ("unnamed") and no client fields.
+    // Set what a client package needs (see documentation/BUGS-2026-07.md, C5).
+    operations.push("Setting the package fields");
+    const pkgJsonPath = join(packagePath, "package.json");
+    const pkgReadResult = await ctx.client.call<{ path: string }, { path: string; data: unknown }>(
+      ["fs", "read.json"],
+      { path: pkgJsonPath }
+    );
+    const pkgJson = (pkgReadResult.data ?? {}) as Record<string, unknown>;
+    pkgJson["name"] = packageName;
+    pkgJson["exports"] = {
+      ".": { types: "./dist/index.d.ts", import: "./dist/index.js" },
+      "./module": { types: "./dist/module.d.ts", import: "./dist/module.js" },
+      "./register": { types: "./dist/register.d.ts", import: "./dist/register.js" },
+    };
+    // Only the register entry has a side effect, so a bundler can drop the rest
+    pkgJson["sideEffects"] = ["./dist/register.js"];
+    pkgJson["client"] = { procedures: "./dist/register.js" };
+    pkgJson["dependencies"] = {
+      ...((pkgJson["dependencies"] as Record<string, string> | undefined) ?? {}),
+      "@procedures/client": "workspace:*",
+      zod: "^4.6.5",
+    };
+    await ctx.client.call<{ path: string; content: string }, { path: string; bytesWritten: number }>(
+      ["fs", "write"],
+      { path: pkgJsonPath, content: JSON.stringify(pkgJson, null, 2) + "\n" }
+    );
+    operations.push(`Created ${packageName}. Next: run pnpm install and pnpm build in ${rootPath}`);
+  } catch (error) {
+    errors.push(error instanceof Error ? error.message : String(error));
+  }
+
+  return {
+    success: errors.length === 0,
+    packageName,
+    packagePath,
+    created,
+    operations,
+    errors,
+  };
+}

package/src/procedures/lib/rename.ts

@@ -0,0 +1,355 @@
+/**
+ * lib.rename Procedure
+ *
+ * Renames a package across the entire codebase using ts-morph for AST-based
+ * import updates and direct file manipulation for package.json updates.
+ *
+ * Uses:
+ * - ts-morph: AST manipulation for TypeScript imports
+ * - File system operations for package.json updates
+ *
+ * @example
+ * ```typescript
+ * await client.call(["lib", "rename"], {
+ *   oldName: "client",
+ *   newName: "@procedures/client",
+ *   dryRun: true, // Preview changes without applying
+ * });
+ * ```
+ *
+ * The search root is `rootPath`, or else the workspace that contains client-lib.
+ */
+
+import { Project, SyntaxKind } from "ts-morph";
+import type { ProcedureContext } from "@procedures/client";
+import type { LibRenameInput, LibRenameOutput, RenameChange } from "../../types.js";
+import { resolveWorkspaceRoot } from "../../workspace.js";
+
+interface FsGlobOutput { pattern: string; matches: string[]; }
+interface FsGlobInput { pattern: string; cwd: string; absolute: boolean; ignore: string[]; }
+interface FsExistsOutput { exists: boolean; path: string; }
+interface FsReadJsonOutput { path: string; data: unknown; }
+interface FsWriteOutput { path: string; bytesWritten: number; }
+
+// The folders that hold no source of the workspace
+const IGNORE = ["**/node_modules/**", "**/dist/**", "**/.git/**"];
+
+/**
+ * Find all package.json files under a root path (excluding node_modules)
+ */
+async function findPackageJsonFiles(rootPath: string, ctx: ProcedureContext): Promise<string[]> {
+  const result = await ctx.client.call<FsGlobInput, FsGlobOutput>(
+    ["fs", "glob"],
+    { pattern: "**/package.json", cwd: rootPath, absolute: true, ignore: IGNORE }
+  );
+  // fs.glob returns `matches`. (Before, this read `files`, which does not exist: deep dive DATA-7.)
+  return result.matches;
+}
+
+/**
+ * Find all TypeScript files under a root path (excluding node_modules, dist)
+ */
+async function findTypeScriptFiles(rootPath: string, ctx: ProcedureContext): Promise<string[]> {
+  const result = await ctx.client.call<FsGlobInput, FsGlobOutput>(
+    ["fs", "glob"],
+    { pattern: "**/*.{ts,tsx}", cwd: rootPath, absolute: true, ignore: IGNORE }
+  );
+  return result.matches;
+}
+
+/**
+ * Update package.json name field
+ */
+async function updatePackageJsonName(
+  pkgPath: string,
+  oldName: string,
+  newName: string,
+  dryRun: boolean,
+  ctx: ProcedureContext
+): Promise<RenameChange | null> {
+  try {
+    const result = await ctx.client.call<{ path: string }, FsReadJsonOutput>(
+      ["fs", "read.json"],
+      { path: pkgPath }
+    );
+    const pkg = result.data as { name?: string };
+
+    if (pkg.name === oldName) {
+      if (!dryRun) {
+        pkg.name = newName;
+        await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(
+          ["fs", "write"],
+          { path: pkgPath, content: JSON.stringify(pkg, null, 2) + "\n" }
+        );
+      }
+
+      return {
+        type: "package-name",
+        file: pkgPath,
+        oldValue: oldName,
+        newValue: newName,
+      };
+    }
+  } catch {
+    // Skip files we can't parse
+  }
+
+  return null;
+}
+
+/**
+ * Update package.json dependencies
+ */
+async function updatePackageJsonDependencies(
+  pkgPath: string,
+  oldName: string,
+  newName: string,
+  dryRun: boolean,
+  ctx: ProcedureContext
+): Promise<RenameChange[]> {
+  const changes: RenameChange[] = [];
+
+  try {
+    const result = await ctx.client.call<{ path: string }, FsReadJsonOutput>(
+      ["fs", "read.json"],
+      { path: pkgPath }
+    );
+    const pkg = result.data as Record<string, unknown>;
+    let modified = false;
+
+    const depFields = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+
+    for (const field of depFields) {
+      const deps = pkg[field] as Record<string, string> | undefined;
+      if (deps && oldName in deps) {
+        const oldValue = deps[oldName]!;
+        let newValue = oldValue;
+        // The repository of a git dependency has the name of the package without its scope
+        const bare = (name: string): string => name.replace(/^@[^/]+\//, "");
+        if (oldValue.includes(`github:mark1russell7/${bare(oldName)}`)) {
+          newValue = oldValue.replace(`github:mark1russell7/${bare(oldName)}`, `github:mark1russell7/${bare(newName)}`);
+        }
+
+        if (!dryRun) {
+          delete deps[oldName];
+          deps[newName] = newValue;
+        }
+
+        changes.push({
+          type: "dependency",
+          file: pkgPath,
+          field,
+          oldValue: `"${oldName}": "${oldValue}"`,
+          newValue: `"${newName}": "${newValue}"`,
+        });
+        modified = true;
+      }
+    }
+
+    if (modified && !dryRun) {
+      await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(
+        ["fs", "write"],
+        { path: pkgPath, content: JSON.stringify(pkg, null, 2) + "\n" }
+      );
+    }
+  } catch {
+    // Skip files we can't parse
+  }
+
+  return changes;
+}
+
+/**
+ * Update TypeScript imports using ts-morph
+ */
+function updateTypeScriptImports(
+  tsFiles: string[],
+  oldName: string,
+  newName: string,
+  dryRun: boolean
+): RenameChange[] {
+  const changes: RenameChange[] = [];
+
+  // Create ts-morph project
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  // Add files to project
+  for (const filePath of tsFiles) {
+    try {
+      project.addSourceFileAtPath(filePath);
+    } catch {
+      // Skip files we can't add
+    }
+  }
+
+  // Process each source file
+  for (const sourceFile of project.getSourceFiles()) {
+    let fileModified = false;
+
+    // Find all import declarations
+    const importDecls = sourceFile.getImportDeclarations();
+
+    for (const importDecl of importDecls) {
+      const moduleSpecifier = importDecl.getModuleSpecifierValue();
+
+      // Check if this import matches the old package name
+      // Match exact name or subpath imports (e.g., "client" or "client/something")
+      if (moduleSpecifier === oldName || moduleSpecifier.startsWith(`${oldName}/`)) {
+        const newSpecifier = moduleSpecifier.replace(oldName, newName);
+
+        changes.push({
+          type: "import",
+          file: sourceFile.getFilePath(),
+          line: importDecl.getStartLineNumber(),
+          oldValue: `from "${moduleSpecifier}"`,
+          newValue: `from "${newSpecifier}"`,
+        });
+
+        if (!dryRun) {
+          importDecl.setModuleSpecifier(newSpecifier);
+          fileModified = true;
+        }
+      }
+    }
+
+    // Also check dynamic imports (import())
+    const callExpressions = sourceFile.getDescendantsOfKind(SyntaxKind.CallExpression);
+
+    for (const call of callExpressions) {
+      const expression = call.getExpression();
+      if (expression.getKind() === SyntaxKind.ImportKeyword) {
+        const args = call.getArguments();
+        if (args.length > 0) {
+          const arg = args[0]!;
+          if (arg.getKind() === SyntaxKind.StringLiteral) {
+            const value = arg.getText().slice(1, -1); // Remove quotes
+            if (value === oldName || value.startsWith(`${oldName}/`)) {
+              const newValue = value.replace(oldName, newName);
+
+              changes.push({
+                type: "dynamic-import",
+                file: sourceFile.getFilePath(),
+                line: call.getStartLineNumber(),
+                oldValue: `import("${value}")`,
+                newValue: `import("${newValue}")`,
+              });
+
+              if (!dryRun) {
+                arg.replaceWithText(`"${newValue}"`);
+                fileModified = true;
+              }
+            }
+          }
+        }
+      }
+    }
+
+    // Save if modified
+    if (fileModified && !dryRun) {
+      sourceFile.saveSync();
+    }
+  }
+
+  return changes;
+}
+
+/**
+ * Execute the lib.rename procedure
+ */
+export async function libRename(input: LibRenameInput, ctx: ProcedureContext): Promise<LibRenameOutput> {
+  const { oldName, newName, dryRun = false } = input;
+
+  const changes: RenameChange[] = [];
+  const errors: string[] = [];
+
+  // Resolve path: the given root, else the workspace that contains client-lib
+  let resolvedRoot: string;
+  try {
+    resolvedRoot = resolveWorkspaceRoot(input.rootPath);
+  } catch (error) {
+    return {
+      success: false,
+      changes: [],
+      errors: [error instanceof Error ? error.message : String(error)],
+      summary: { packageNames: 0, dependencies: 0, imports: 0, total: 0 },
+    };
+  }
+
+  const existsResult = await ctx.client.call<{ path: string }, FsExistsOutput>(
+    ["fs", "exists"],
+    { path: resolvedRoot }
+  );
+  if (!existsResult.exists) {
+    return {
+      success: false,
+      changes: [],
+      errors: [`Root path does not exist: ${resolvedRoot}`],
+      summary: { packageNames: 0, dependencies: 0, imports: 0, total: 0 },
+    };
+  }
+
+  console.error(`[lib.rename] ${dryRun ? "[DRY RUN] " : ""}Renaming "${oldName}" → "${newName}"`);
+  console.error(`[lib.rename] Scanning ${resolvedRoot}...`);
+
+  // Find all package.json files
+  const packageJsonFiles = await findPackageJsonFiles(resolvedRoot, ctx);
+  console.error(`[lib.rename] Found ${packageJsonFiles.length} package.json files`);
+
+  // Find all TypeScript files
+  const tsFiles = await findTypeScriptFiles(resolvedRoot, ctx);
+  console.error(`[lib.rename] Found ${tsFiles.length} TypeScript files`);
+
+  // 1. Update package.json name field (find the package being renamed)
+  for (const pkgPath of packageJsonFiles) {
+    const change = await updatePackageJsonName(pkgPath, oldName, newName, dryRun, ctx);
+    if (change) {
+      changes.push(change);
+      console.error(`[lib.rename] ${dryRun ? "Would update" : "Updated"} package name: ${pkgPath}`);
+    }
+  }
+
+  // 2. Update package.json dependencies
+  for (const pkgPath of packageJsonFiles) {
+    const depChanges = await updatePackageJsonDependencies(pkgPath, oldName, newName, dryRun, ctx);
+    changes.push(...depChanges);
+    if (depChanges.length > 0) {
+      console.error(
+        `[lib.rename] ${dryRun ? "Would update" : "Updated"} ${depChanges.length} dependencies in: ${pkgPath}`
+      );
+    }
+  }
+
+  // 3. Update TypeScript imports using ts-morph
+  try {
+    const importChanges = updateTypeScriptImports(tsFiles, oldName, newName, dryRun);
+    changes.push(...importChanges);
+    if (importChanges.length > 0) {
+      console.error(
+        `[lib.rename] ${dryRun ? "Would update" : "Updated"} ${importChanges.length} TypeScript imports`
+      );
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    errors.push(`Error updating TypeScript imports: ${errorMessage}`);
+  }
+
+  // Build summary
+  const summary = {
+    packageNames: changes.filter((c) => c.type === "package-name").length,
+    dependencies: changes.filter((c) => c.type === "dependency").length,
+    imports: changes.filter((c) => c.type === "import" || c.type === "dynamic-import").length,
+    total: changes.length,
+  };
+
+  console.error(`[lib.rename] Summary: ${summary.packageNames} package names, ${summary.dependencies} dependencies, ${summary.imports} imports`);
+
+  return {
+    success: errors.length === 0,
+    changes,
+    errors,
+    summary,
+  };
+}