@procedures/procedure 0.0.0-stage → 0.1.0

package/src/procedures/procedure/registry.ts

@@ -0,0 +1,92 @@
+/**
+ * procedure.* Registry Procedures
+ *
+ * Procedures for managing the procedure registry dynamically.
+ * Enables procedure-as-data patterns, remote registration, and persistence.
+ */
+
+import { defineProcedure, PROCEDURE_REGISTRY, 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"],
+    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,19 @@
+/**
+ * Importing this file registers the procedures of @procedures/procedure in the global
+ * registry (DECISIONS-2026-10, "Every package root registers its procedures"). The procedures as
+ * data are in `module.ts`, which registers nothing: a host with its own registry uses that one.
+ */
+
+import { PROCEDURE_REGISTRY } from "@procedures/client";
+import { procedureModule } from "./module.js";
+
+export * from "./module.js";
+
+export function registerProcedureProcedures(): void {
+  // Override makes the registration idempotent. procedure.list and procedure.get are the core
+  // ones: this package does not replace them (docs review DOC-6).
+  PROCEDURE_REGISTRY.registerAll(procedureModule.procedures, { override: true });
+}
+
+// Auto-register
+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"),
+});