@procedures/playground 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,65 @@
 {
+  "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/playground",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "A typed fluent API to write procedure programs in TypeScript (proc, ref, run) with autocomplete, then run them with the client.",
+  "keywords": [
+    "dsl",
+    "fluent-api",
+    "procedures",
+    "typescript",
+    "workflow"
+  ],
+  "homepage": "https://mark1russell7.github.io/client/",
+  "bugs": {
+    "url": "https://github.com/mark1russell7/client/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mark1russell7/client.git",
+    "directory": "packages/client-playground"
+  },
+  "license": "MIT",
+  "author": "Mark Russell (https://github.com/mark1russell7)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@procedures/client": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0",
+    "@mark1russell7/cue": "^1.0.0",
+    "vitest": "^5.0.3"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .tsbuildinfo",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
 }

package/src/index.ts

@@ -0,0 +1,219 @@
+/**
+ * Client Playground
+ *
+ * Type-safe aggregation building for procedure compositions.
+ * Write aggregations in TypeScript with full autocomplete, then run them.
+ *
+ * @example
+ * ```typescript
+ * // my-agg.play.ts
+ * import { proc, ref, run } from "@procedures/playground";
+ *
+ * run(
+ *   proc(["dag", "traverse"]).input({
+ *     visit: [
+ *       proc(["pnpm", "install"]).ref,
+ *       proc(["git", "hasChanges"]).name("changes").ref,
+ *       proc(["client", "conditional"]).input({
+ *         condition: ref("changes.value"),
+ *         then: proc(["git", "add"]).input({ all: true }).ref,
+ *       }).ref,
+ *     ],
+ *   }).ref
+ * );
+ * ```
+ *
+ * Run with: `npx tsx my-agg.play.ts`
+ */
+
+import type { ProcedurePath, ProcedureRefJson } from "@procedures/client";
+
+// =============================================================================
+// Output Reference
+// =============================================================================
+
+/**
+ * An output reference for referencing named stage outputs.
+ */
+export interface OutputRef {
+  readonly $ref: string;
+}
+
+/**
+ * Create an output reference.
+ *
+ * @param path - Reference path (e.g., "stageName.value" or "$last.value")
+ * @returns Output reference object
+ *
+ * @example
+ * ```typescript
+ * ref("changes.value")     // Reference the .value field of "changes" output
+ * ref("$last")             // Reference the previous step's output
+ * ref("$last.success")     // Reference the .success field of previous output
+ * ```
+ */
+export function ref(path: string): OutputRef {
+  return { $ref: path };
+}
+
+// =============================================================================
+// Procedure Reference Builder
+// =============================================================================
+
+/**
+ * Builder for creating procedure references with a fluent API.
+ */
+export interface ProcBuilder<TInput = unknown> {
+  /**
+   * Set the input for this procedure.
+   */
+  input<T>(input: T): ProcBuilder<T>;
+
+  /**
+   * Name this stage for later reference with $ref.
+   */
+  name(name: string): ProcBuilder<TInput>;
+
+  /**
+   * Set when this reference should be executed.
+   * @param when - "$immediate", "$never", "$parent", or a named context
+   */
+  when(when: string): ProcBuilder<TInput>;
+
+  /**
+   * Get the procedure reference object.
+   */
+  readonly ref: ProcedureRefJson<TInput>;
+}
+
+/**
+ * Create a procedure reference builder.
+ *
+ * @param path - Path to the procedure (e.g., ["git", "add"])
+ * @returns Builder for the procedure reference
+ *
+ * @example
+ * ```typescript
+ * // Simple reference
+ * proc(["git", "add"]).input({ all: true }).ref
+ *
+ * // Named reference for $ref
+ * proc(["git", "hasChanges"]).name("changes").ref
+ *
+ * // With execution timing
+ * proc(["git", "add"]).input({ all: true }).when("$parent").ref
+ * ```
+ */
+export function proc(path: ProcedurePath): ProcBuilder<unknown> {
+  let _input: unknown = {};
+  let _name: string | undefined;
+  let _when: string | undefined;
+
+  const builder: ProcBuilder<unknown> = {
+    input<T>(input: T): ProcBuilder<T> {
+      _input = input;
+      return builder as ProcBuilder<T>;
+    },
+
+    name(name: string): ProcBuilder<unknown> {
+      _name = name;
+      return builder;
+    },
+
+    when(when: string): ProcBuilder<unknown> {
+      _when = when;
+      return builder;
+    },
+
+    get ref(): ProcedureRefJson<unknown> {
+      const result: ProcedureRefJson<unknown> = {
+        $proc: path,
+        input: _input,
+      };
+
+      if (_name) {
+        (result as { $name?: string }).$name = _name;
+      }
+      if (_when) {
+        (result as { $when?: string }).$when = _when;
+      }
+
+      return result;
+    },
+  };
+
+  return builder;
+}
+
+// =============================================================================
+// Execution
+// =============================================================================
+
+/**
+ * Options for running a procedure.
+ */
+export interface RunOptions {
+  /** Whether to print the result (default: true) */
+  print?: boolean;
+
+  /** Output format (default: "json") */
+  format?: "json" | "text";
+}
+
+/**
+ * Run a procedure reference.
+ *
+ * This function executes the procedure and prints the result.
+ * Use this in your playground files to execute aggregations.
+ *
+ * @param procedureRef - The procedure reference to execute
+ * @param options - Execution options
+ * @returns The result of the procedure
+ *
+ * @example
+ * ```typescript
+ * // Run and print result
+ * await run(proc(["git", "status"]).ref);
+ *
+ * // Run without printing
+ * const result = await run(proc(["git", "status"]).ref, { print: false });
+ * ```
+ */
+export async function run<T = unknown>(
+  procedureRef: ProcedureRefJson,
+  options: RunOptions = {}
+): Promise<T> {
+  const { print: shouldPrint = true, format = "json" } = options;
+
+  // Dynamic import to avoid bundling all of client
+  const { Client, LocalTransport, PROCEDURE_REGISTRY } = await import(
+    "@procedures/client"
+  );
+
+  // The transport runs each procedure of the registry through invokeProcedure()
+  // (ARCHITECTURE-PROPOSALS P1). Before, this file had its own copy of the bridge, without
+  // input validation.
+  const transport = new LocalTransport({ registry: PROCEDURE_REGISTRY });
+
+  const client = new Client({ transport });
+
+  // Execute the procedure
+  const result = await client.exec(procedureRef);
+
+  // Print result
+  if (shouldPrint) {
+    if (format === "json") {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(result);
+    }
+  }
+
+  return result as T;
+}
+
+// =============================================================================
+// Convenience Exports
+// =============================================================================
+
+export type { ProcedurePath, ProcedureRefJson } from "@procedures/client";