@procedures/procedure 0.0.0-stage → 0.2.0

package/src/procedures/procedure/new.ts

@@ -0,0 +1,502 @@
+/**
+ * procedure.new - Scaffold a new procedure
+ *
+ * Creates the procedure file, its types and its registration. A dot-notation name such as
+ * "user.create" makes the procedure at ["user", "create"]: the file is
+ * procedures/user/create.ts, and "api.v2.users.create" gives procedures/api/v2/users/create.ts.
+ *
+ * The scaffolded code compiles with the strict options of the workspace (deep dive CLI-13):
+ * - the handler names its unused input `_input` (noUnusedParameters);
+ * - types.ts is created, or gets `import { z } from "zod"`, when it needs it;
+ * - the registration goes into the defineModule([...]) array of src/module.ts. A package of the
+ *   old kind, without module.ts, gets it in the registerProcedures([...]) array of src/register.ts.
+ * A name whose path, file, types or registration exists already is an error, and nothing is
+ * written. Before, "a.b.c" and "a.c" wrote the same file, and existing types were reused silently.
+ */
+
+import { join } from "node:path";
+import { PROCEDURE_REGISTRY, type ProcedureContext } from "@procedures/client";
+import type { ProcedureNewInput, ProcedureNewOutput } from "../../types.js";
+
+interface FsExistsOutput { exists: boolean; path: string; }
+interface FsReadOutput { path: string; content: string; }
+interface FsWriteOutput { path: string; bytesWritten: number; }
+interface FsMkdirOutput { path: string; created: boolean; }
+
+/**
+ * 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;
+  }
+}
+
+async function readText(pathStr: string, ctx: ProcedureContext): Promise<string | undefined> {
+  if (!(await pathExists(pathStr, ctx))) {
+    return undefined;
+  }
+  const result = await ctx.client.call<{ path: string }, FsReadOutput>(["fs", "read"], { path: pathStr });
+  return result.content;
+}
+
+async function writeText(pathStr: string, content: string, ctx: ProcedureContext): Promise<void> {
+  await ctx.client.call<{ path: string; content: string }, FsWriteOutput>(["fs", "write"], { path: pathStr, content });
+}
+
+/**
+ * Convert camelCase to PascalCase
+ */
+function toPascalCase(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+/**
+ * Convert dot.notation to camelCase
+ */
+function toCamelCase(segments: string[]): string {
+  return segments
+    .map((s, i) => (i === 0 ? s : toPascalCase(s)))
+    .join("");
+}
+
+/** The names and files of one procedure */
+export interface ProcedureLayout {
+  segments: string[];
+  namespace: string;
+  /** The folders under procedures/<namespace>/ */
+  folders: string[];
+  /** The file name without ".ts" */
+  fileBase: string;
+  camelName: string;
+  pascalName: string;
+}
+
+/**
+ * The layout of a procedure: procedures/<namespace>/<middle segments>/<last segment>.ts
+ */
+export function procedureLayout(name: string, namespace?: string): ProcedureLayout {
+  const segments = name.split(".");
+  return {
+    segments,
+    namespace: namespace ?? segments[0]!,
+    folders: segments.length > 2 ? segments.slice(1, -1) : [],
+    fileBase: segments[segments.length - 1]!,
+    camelName: toCamelCase(segments),
+    pascalName: segments.map(toPascalCase).join(""),
+  };
+}
+
+/**
+ * Generate procedure file content
+ */
+function generateProcedureFile(layout: ProcedureLayout, description: string): string {
+  const { segments, camelName, pascalName, folders } = layout;
+  // procedures/<namespace>/<folders...>/<file>.ts -> src/types.ts
+  const typesPath = `${"../".repeat(2 + folders.length)}types.js`;
+
+  return `/**
+ * ${segments.join(".")} procedure
+ *
+ * ${description}
+ */
+
+import type { ${pascalName}Input, ${pascalName}Output } from "${typesPath}";
+
+/**
+ * ${description}
+ */
+export async function ${camelName}(_input: ${pascalName}Input): Promise<${pascalName}Output> {
+  // TODO: Implement ${segments.join(".")} (rename _input to input when the code uses it)
+  return {
+    success: true,
+    message: "Hello from ${segments.join(".")}",
+  };
+}
+`;
+}
+
+/**
+ * Generate type definitions
+ */
+function generateTypes(layout: ProcedureLayout, description: string): string {
+  const { segments, pascalName } = layout;
+  const schemaName = `${pascalName}InputSchema`;
+  const outputSchemaName = `${pascalName}OutputSchema`;
+
+  // The output has a real schema too: the registry validates each result with it. (Before, the
+  // output was an interface with a pass-through outputSchema(), so no result was checked.)
+  return `
+// =============================================================================
+// ${segments.join(".")} Types - ${description}
+// =============================================================================
+
+export const ${schemaName}: z.ZodObject<{
+  // TODO: Add input fields
+}> = z.object({
+  // TODO: Add input fields
+});
+
+export type ${pascalName}Input = z.infer<typeof ${schemaName}>;
+
+export const ${outputSchemaName}: z.ZodObject<{
+  success: z.ZodBoolean;
+  message: z.ZodString;
+}> = z.object({
+  /** Whether the operation succeeded */
+  success: z.boolean().describe("Whether the operation succeeded"),
+  /** Response message */
+  message: z.string().describe("Response message"),
+});
+
+export type ${pascalName}Output = z.infer<typeof ${outputSchemaName}>;
+`;
+}
+
+const TYPES_HEADER = `/**
+ * Type definitions of the procedures of this package
+ */
+
+`;
+
+const Z_IMPORT = `import { z } from "zod";\n`;
+
+/** True when the source imports z from "zod" */
+function importsZ(source: string): boolean {
+  return (
+    /import\s*\{[^}]*\bz\b[^}]*\}\s*from\s*["']zod["']/.test(source) ||
+    /import\s+\*\s+as\s+z\s+from\s*["']zod["']/.test(source) ||
+    /import\s+z\s+from\s*["']zod["']/.test(source)
+  );
+}
+
+/**
+ * Add import lines after the last import of a source (or after its leading comment)
+ */
+export function addImports(source: string, lines: string[]): string {
+  if (lines.length === 0) {
+    return source;
+  }
+  const block = lines.join("");
+  const importPattern = /^import[\s\S]*?from\s*["'][^"']+["'];?[ \t]*\r?\n|^import\s*["'][^"']+["'];?[ \t]*\r?\n/gm;
+  let end = -1;
+  for (const match of source.matchAll(importPattern)) {
+    end = match.index + match[0].length;
+  }
+  if (end === -1) {
+    const comment = /^\s*\/\*[\s\S]*?\*\/[ \t]*\r?\n(\r?\n)?/.exec(source);
+    end = comment ? comment[0].length : 0;
+  }
+  return source.slice(0, end) + block + source.slice(end);
+}
+
+/**
+ * Add names to the value import from a module, or add the import
+ */
+export function ensureNamedImports(source: string, moduleName: string, names: string[]): string {
+  const escaped = moduleName.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&");
+  const pattern = new RegExp(`import\\s*\\{([^}]*)\\}\\s*from\\s*["']${escaped}["'];?`);
+  const match = pattern.exec(source);
+  if (match && !/^import\s+type\b/.test(match[0])) {
+    const present = match[1]!
+      .split(",")
+      .map((part) => part.trim())
+      .filter((part) => part.length > 0);
+    const presentNames = new Set(present.map((part) => part.replace(/^type\s+/, "").split(/\s+as\s+/)[0]!.trim()));
+    const missing = names.filter((name) => !presentNames.has(name));
+    if (missing.length === 0) {
+      return source;
+    }
+    const replacement = `import { ${[...present, ...missing].join(", ")} } from "${moduleName}";`;
+    return source.slice(0, match.index) + replacement + source.slice(match.index + match[0].length);
+  }
+  return addImports(source, [`import { ${names.join(", ")} } from "${moduleName}";\n`]);
+}
+
+/** The index of the bracket that closes the bracket at `open` (strings are skipped) */
+function closingBracket(source: string, open: number): number {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let i = open; i < source.length; i++) {
+    const ch = source[i]!;
+    if (quote) {
+      if (ch === "\\") i++;
+      else if (ch === quote) quote = undefined;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+    else if (ch === "[") depth++;
+    else if (ch === "]" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/**
+ * Add an item to the array of the first defineModule("name", [...]), registerProcedures([...]) or
+ * registerAll([...]) call. Returns undefined when the source has no such call.
+ */
+export function addToRegistration(source: string, item: string): string | undefined {
+  // The first call in code, not in a comment
+  const call = [...source.matchAll(/\b(defineModule|registerProcedures|registerAll)\s*\(/g)].find((match) => {
+    const lineStart = source.lastIndexOf("\n", match.index) + 1;
+    const before = source.slice(lineStart, match.index).trim();
+    return !before.startsWith("*") && !before.startsWith("/*") && !before.includes("//");
+  });
+  if (!call) {
+    return undefined;
+  }
+  const open = source.indexOf("[", call.index);
+  const close = open === -1 ? -1 : closingBracket(source, open);
+  if (close === -1) {
+    return undefined;
+  }
+  const content = source.slice(open + 1, close);
+  let updated: string;
+  if (content.trim() === "") {
+    updated = item;
+  } else if (content.includes("\n")) {
+    // One item per line: add a line with the indentation of the last item
+    const trimmed = content.replace(/\s*$/, "");
+    const lastLine = trimmed.slice(trimmed.lastIndexOf("\n") + 1);
+    const indent = /^\s*/.exec(lastLine)?.[0] ?? "  ";
+    const comma = trimmed.endsWith(",") ? "" : ",";
+    updated = `${trimmed}${comma}\n${indent}${item},${content.slice(trimmed.length)}`;
+  } else {
+    updated = `${content.replace(/,?\s*$/, "")}, ${item}`;
+  }
+  return source.slice(0, open + 1) + updated + source.slice(close);
+}
+
+/**
+ * The procedure definition that goes into module.ts (or register.ts)
+ */
+function generateRegistration(layout: ProcedureLayout, description: string): string {
+  const { segments, camelName, pascalName } = layout;
+  return `const ${camelName}Procedure = createProcedure()
+  .path(${JSON.stringify(segments)})
+  .input(zodAdapter<${pascalName}Input>(${pascalName}InputSchema))
+  .output(zodAdapter<${pascalName}Output>(${pascalName}OutputSchema))
+  .meta({
+    description: ${JSON.stringify(description)},
+    args: [],
+    shorts: {},
+    output: "text",
+  })
+  .handler(async (input: ${pascalName}Input): Promise<${pascalName}Output> => ${camelName}(input))
+  .build();
+
+`;
+}
+
+const REGISTER_TEMPLATE = `/**
+ * Procedure registration of this package
+ *
+ * Scaffold a procedure with: mark procedure new <name> --path <this package>
+ */
+
+import { registerProcedures } from "@procedures/client";
+
+export function register(): void {
+  registerProcedures([]);
+}
+
+// Auto-register
+register();
+`;
+
+/**
+ * Put the procedure into module.ts (or register.ts): its imports, its definition, and its place
+ * in the array of the module. Returns undefined when the file has no such array.
+ */
+export function registerSource(source: string, layout: ProcedureLayout, description: string, importPath: string): string | undefined {
+  const { camelName, pascalName } = layout;
+  const withArray = addToRegistration(source, `${camelName}Procedure`);
+  if (withArray === undefined) {
+    return undefined;
+  }
+  let updated = ensureNamedImports(withArray, "@procedures/client", ["createProcedure", "zodAdapter"]);
+  updated = addImports(updated, [
+    `import { ${camelName} } from "${importPath}";\n`,
+    `import { ${pascalName}InputSchema, ${pascalName}OutputSchema, type ${pascalName}Input, type ${pascalName}Output } from "./types.js";\n`,
+  ]);
+  // The definition goes before the module, or before the code that registers the procedures
+  const anchor =
+    /^export\s+const\s+\w+\s*(:\s*\w+\s*)?=\s*defineModule\s*\(|^(export\s+)?(async\s+)?function\s+register\w*\s*\(|^\s*(registerProcedures|PROCEDURE_REGISTRY\.registerAll)\s*\(/m.exec(
+      updated
+    );
+  const at = anchor ? anchor.index : updated.length;
+  return updated.slice(0, at) + generateRegistration(layout, description) + updated.slice(at);
+}
+
+/**
+ * Generate index.ts export
+ */
+function generateIndexExport(relativeFile: string, functionName: string): string {
+  return `export { ${functionName} } from "./${relativeFile}.js";\n`;
+}
+
+/**
+ * Scaffold a new procedure
+ */
+export async function procedureNew(input: ProcedureNewInput, ctx: ProcedureContext): Promise<ProcedureNewOutput> {
+  const operations: string[] = [];
+  const created: string[] = [];
+  const modified: string[] = [];
+  const errors: string[] = [];
+
+  const layout = procedureLayout(input.name, input.namespace);
+  const { segments, namespace, folders, fileBase, camelName, pascalName } = layout;
+
+  // Resolve paths
+  const projectPath = input.path ?? process.cwd();
+  const srcPath = join(projectPath, "src");
+  const namespacePath = join(srcPath, "procedures", namespace);
+  const procedureDir = join(namespacePath, ...folders);
+  const procedureFile = join(procedureDir, `${fileBase}.ts`);
+  const namespaceIndex = join(namespacePath, "index.ts");
+  const typesFile = join(srcPath, "types.ts");
+  const moduleFile = join(srcPath, "module.ts");
+  const relativeFile = [...folders, fileBase].join("/");
+  const importPath = `./procedures/${namespace}/${relativeFile}.js`;
+
+  const description = input.description ?? `${segments.join(".")} procedure`;
+  const fail = (message: string): ProcedureNewOutput => ({
+    success: false,
+    procedurePath: segments,
+    created,
+    modified,
+    operations,
+    errors: [...errors, message],
+  });
+
+  // Check every collision before anything is written
+  // The registry of the invocation (a host with its own registry), else the global one
+  if ((ctx.registry ?? PROCEDURE_REGISTRY).has(segments)) {
+    return fail(`A procedure is registered at ${segments.join(".")} already. Choose another name.`);
+  }
+  if (await pathExists(procedureFile, ctx)) {
+    return fail(`Procedure file already exists: ${procedureFile}`);
+  }
+  const existingTypes = await readText(typesFile, ctx);
+  if (existingTypes !== undefined && new RegExp(`\\b${pascalName}(Input|Output|InputSchema|OutputSchema)\\b`).test(existingTypes)) {
+    return fail(
+      `types.ts already has types named ${pascalName}: the name ${segments.join(".")} collides with another procedure. Choose another name.`
+    );
+  }
+  // The procedures go into module.ts. A package of the old kind, without it, has them in register.ts.
+  const existingModule = await readText(moduleFile, ctx);
+  const registerFile = existingModule !== undefined ? moduleFile : join(srcPath, "register.ts");
+  const registerName = existingModule !== undefined ? "module.ts" : "register.ts";
+  const existingRegister = existingModule ?? (await readText(registerFile, ctx));
+  if (existingRegister !== undefined) {
+    if (existingRegister.includes(JSON.stringify(segments)) || new RegExp(`\\b${camelName}Procedure\\b`).test(existingRegister)) {
+      return fail(`${registerName} already registers ${segments.join(".")} (or ${camelName}Procedure). Choose another name.`);
+    }
+  }
+  const registerBase = existingRegister ?? REGISTER_TEMPLATE;
+  const newRegister = registerSource(registerBase, layout, description, importPath);
+
+  if (input.dryRun) {
+    const [indexExists] = await Promise.all([pathExists(namespaceIndex, ctx)]);
+    return {
+      success: true,
+      procedurePath: segments,
+      created: [
+        procedureFile,
+        ...(indexExists ? [] : [namespaceIndex]),
+        ...(existingTypes === undefined ? [typesFile] : []),
+        ...(existingRegister === undefined ? [registerFile] : []),
+      ],
+      modified: [
+        ...(indexExists ? [namespaceIndex] : []),
+        ...(existingTypes !== undefined ? [typesFile] : []),
+        ...(existingRegister !== undefined && newRegister !== undefined ? [registerFile] : []),
+      ],
+      operations: [
+        `Would create procedure file: ${procedureFile}`,
+        `Would create/update index: ${namespaceIndex}`,
+        existingTypes === undefined ? `Would create ${typesFile}` : `Would append types to: ${typesFile}`,
+        newRegister === undefined
+          ? `Would not change ${registerFile}: it has no defineModule or registerProcedures array`
+          : `Would register the procedure in: ${registerFile}`,
+      ],
+      errors: [],
+    };
+  }
+
+  try {
+    // Step 1: Create the folder and the procedure file
+    if (!(await pathExists(procedureDir, ctx))) {
+      operations.push(`Creating directory: ${procedureDir}`);
+      await ctx.client.call<{ path: string; recursive?: boolean }, FsMkdirOutput>(
+        ["fs", "mkdir"],
+        { path: procedureDir, recursive: true }
+      );
+      created.push(procedureDir);
+    }
+    operations.push(`Creating procedure file: ${procedureFile}`);
+    await writeText(procedureFile, generateProcedureFile(layout, description), ctx);
+    created.push(procedureFile);
+
+    // Step 2: Create/update namespace index.ts
+    const indexExport = generateIndexExport(relativeFile, camelName);
+    const existingIndex = await readText(namespaceIndex, ctx);
+    if (existingIndex !== undefined) {
+      if (!existingIndex.includes(`from "./${relativeFile}.js"`)) {
+        operations.push(`Updating index: ${namespaceIndex}`);
+        await writeText(namespaceIndex, existingIndex + indexExport, ctx);
+        modified.push(namespaceIndex);
+      }
+    } else {
+      operations.push(`Creating index: ${namespaceIndex}`);
+      await writeText(namespaceIndex, indexExport, ctx);
+      created.push(namespaceIndex);
+    }
+
+    // Step 3: Add the types (create types.ts, or add the z import that the types need)
+    const newTypes = generateTypes(layout, description);
+    if (existingTypes === undefined) {
+      operations.push(`Creating types: ${typesFile}`);
+      await writeText(typesFile, TYPES_HEADER + Z_IMPORT + newTypes, ctx);
+      created.push(typesFile);
+    } else {
+      operations.push(`Appending types to: ${typesFile}`);
+      const withImport = importsZ(existingTypes) ? existingTypes : addImports(existingTypes, [Z_IMPORT]);
+      await writeText(typesFile, withImport + newTypes, ctx);
+      modified.push(typesFile);
+    }
+
+    // Step 4: Register the procedure
+    if (newRegister === undefined) {
+      operations.push(
+        `${registerName} has no defineModule or registerProcedures array: add ${camelName}Procedure to the module in ${registerFile}`
+      );
+    } else {
+      operations.push(`${existingRegister === undefined ? "Creating" : "Updating"} registration: ${registerFile}`);
+      await writeText(registerFile, newRegister, ctx);
+      (existingRegister === undefined ? created : modified).push(registerFile);
+      if (existingRegister === undefined) {
+        operations.push(`Export the procedures from src/index.ts, and give the package a "./register" entry (see lib new)`);
+      }
+    }
+
+    operations.push(`Next: implement ${segments.join(".")} in ${procedureFile}, then run pnpm build`);
+
+    return {
+      success: errors.length === 0,
+      procedurePath: segments,
+      created,
+      modified,
+      operations,
+      errors,
+    };
+  } catch (error) {
+    return fail(error instanceof Error ? error.message : String(error));
+  }
+}

package/src/procedures/procedure/registry.ts

@@ -0,0 +1,93 @@
+/**
+ * procedure.* Registry Procedures
+ *
+ * Procedures for managing the procedure registry dynamically.
+ * Enables procedure-as-data patterns, remote registration, and persistence.
+ */
+
+import { defineProcedure, PROCEDURE_REGISTRY, REGISTRY_READ_EFFECTS, pathToKey, keyToPath } from "@procedures/client";
+import type { AnyProcedure, ProcedurePath } from "@procedures/client";
+import { z } from "zod";
+
+// procedure.list and procedure.get are core procedures (`@procedures/client`, in
+// define-procedure.ts). This package gave its own versions for the whole registry and replaced
+// the core ones, so the results depended on the imports of the host (docs review DOC-6). The core
+// versions now list and describe the whole registry of the caller, with a `runtime` flag.
+
+// =============================================================================
+// procedure.export - Export procedure as JSON
+// =============================================================================
+
+const ProcedureExportInputSchema = z.object({
+  /** Procedure path (array or dot-separated) */
+  path: z.union([z.array(z.string()), z.string()]).describe("Procedure path (array or dot-separated)"),
+});
+
+type ProcedureExportInput = z.infer<typeof ProcedureExportInputSchema>;
+
+interface ProcedureExportOutput {
+  /** Whether export succeeded */
+  success: boolean;
+  /** Exported procedure definition */
+  definition?: {
+    $proc: ProcedurePath;
+    metadata?: Record<string, unknown> | undefined;
+  };
+  /** Error if failed */
+  error?: string;
+}
+
+/** The output of `procedure.export` (roadmap 2.1: before, a pass-through schema) */
+const ProcedureExportOutputSchema = z.looseObject({
+  success: z.boolean().describe("True when the registry has the procedure"),
+  definition: z
+    .looseObject({
+      $proc: z.array(z.string()).describe("The path of the procedure"),
+      metadata: z.record(z.string(), z.unknown()).optional().describe("The metadata of the procedure"),
+    })
+    .optional()
+    .describe("The procedure as a procedure reference, when it exists"),
+  error: z.string().optional().describe("The error message when the registry has no such procedure"),
+}) as z.ZodType<ProcedureExportOutput>;
+
+export const procedureExportProcedure: AnyProcedure = defineProcedure({
+  path: ["procedure", "export"],
+  input: ProcedureExportInputSchema,
+  output: ProcedureExportOutputSchema,
+  metadata: {
+    description: "Export a procedure definition as JSON",
+    tags: ["procedure", "registry"],
+    effects: REGISTRY_READ_EFFECTS,
+    args: ["path"],
+    shorts: {},
+    output: "json",
+  },
+  handler: async (input: ProcedureExportInput): Promise<ProcedureExportOutput> => {
+    const path = typeof input.path === "string"
+      ? keyToPath(input.path)
+      : input.path;
+
+    const proc = PROCEDURE_REGISTRY.get(path);
+
+    if (!proc) {
+      return {
+        success: false,
+        error: `Procedure not found: ${pathToKey(path)}`,
+      };
+    }
+
+    return {
+      success: true,
+      definition: {
+        $proc: proc.path,
+        metadata: proc.metadata as Record<string, unknown> | undefined,
+      },
+    };
+  },
+});
+
+// =============================================================================
+// Export all procedure.* procedures
+// =============================================================================
+
+export const procedureRegistryProcedures: AnyProcedure[] = [procedureExportProcedure];

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/procedure, and of the modules that it
+ * requires, in the global registry: `import "@procedures/procedure/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerProcedureProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerProcedureProcedures();

package/src/types.ts

@@ -0,0 +1,63 @@
+/**
+ * Type definitions for client-procedure
+ */
+
+import { z } from "zod";
+
+// =============================================================================
+// procedure.new Types
+// =============================================================================
+
+export const ProcedureNewInputSchema: z.ZodObject<{
+  name: z.ZodString;
+  namespace: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  path: z.ZodOptional<z.ZodString>;
+  dryRun: z.ZodDefault<z.ZodBoolean>;
+}> = z.object({
+  /** Procedure name (e.g., "greet", "user.create" or "fs.readJson") */
+  name: z
+    .string()
+    .regex(
+      /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/,
+      "Name must be dot-separated segments, each starting with a lowercase letter (camelCase is allowed)"
+    ).describe("Procedure name (e.g., \"greet\", \"user.create\" or \"fs.readJson\")"),
+  /** Namespace override (defaults to first segment of name): the folder under src/procedures */
+  namespace: z
+    .string()
+    .regex(/^[a-z][a-zA-Z0-9]*$/, "Namespace must be one segment that starts with a lowercase letter")
+    .optional().describe("Namespace override (defaults to first segment of name): the folder under src/procedures"),
+  /** Procedure description for CLI help */
+  description: z.string().optional().describe("Procedure description for CLI help"),
+  /** Project path (defaults to cwd) */
+  path: z.string().optional().describe("Project path (defaults to cwd)"),
+  /** Preview changes without creating */
+  dryRun: z.boolean().default(false).describe("Preview changes without creating"),
+});
+
+export type ProcedureNewInput = z.infer<typeof ProcedureNewInputSchema>;
+
+export interface ProcedureNewOutput {
+  /** Whether creation succeeded */
+  success: boolean;
+  /** Full procedure path (e.g., ["user", "create"]) */
+  procedurePath: string[];
+  /** Files created */
+  created: string[];
+  /** Files modified */
+  modified: string[];
+  /** Operations performed */
+  operations: string[];
+  /** Any errors encountered */
+  errors: string[];
+}
+
+/** The output schema of procedure.new (roadmap 2.1). Loose: a field that it does not name stays. */
+export const ProcedureNewOutputSchema: z.ZodType<ProcedureNewOutput> = z.looseObject({
+  success: z.boolean().describe("True when the procedure was made"),
+  procedurePath: z.array(z.string()).describe('The path of the new procedure, for example ["user", "create"]'),
+  created: z.array(z.string()).describe("The files that the call made"),
+  modified: z.array(z.string()).describe("The files that the call changed (types.ts, register.ts)"),
+  operations: z.array(z.string()).describe("The steps that the call ran"),
+  errors: z.array(z.string()).describe("The errors"),
+});