blokctl 1.2.0 → 1.4.0

package/dist/scaffold-repo/sdks/php/src/Logging/LogEntry.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Logging;
+
+/**
+ * LogEntry represents a single log entry.
+ */
+final class LogEntry
+{
+    public function __construct(
+        public readonly LogLevel $level,
+        public readonly string $message,
+        public readonly string $timestamp,
+        public readonly ?array $fields = null,
+    ) {}
+
+    /**
+     * Format the entry as a human-readable string.
+     */
+    public function __toString(): string
+    {
+        $base = sprintf('[%s] %s %s', $this->level->value, $this->timestamp, $this->message);
+        if ($this->fields !== null) {
+            $json = json_encode($this->fields, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE);
+            return $base . ' ' . ($json ?: '{}');
+        }
+        return $base;
+    }
+
+    /**
+     * Convert to an associative array for JSON serialization.
+     */
+    public function toArray(): array
+    {
+        $result = [
+            'level' => $this->level->value,
+            'message' => $this->message,
+            'timestamp' => $this->timestamp,
+        ];
+        if ($this->fields !== null) {
+            $result['fields'] = $this->fields;
+        }
+        return $result;
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Logging/LogLevel.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Logging;
+
+/**
+ * LogLevel represents the severity of a log entry.
+ */
+enum LogLevel: string
+{
+    case Debug = 'DEBUG';
+    case Info = 'INFO';
+    case Warn = 'WARN';
+    case Error = 'ERROR';
+
+    /**
+     * Get the numeric priority of this level (lower = less severe).
+     */
+    public function priority(): int
+    {
+        return match ($this) {
+            self::Debug => 0,
+            self::Info => 1,
+            self::Warn => 2,
+            self::Error => 3,
+        };
+    }
+
+    /**
+     * Check if this level is at least as severe as the given level.
+     */
+    public function isAtLeast(self $level): bool
+    {
+        return $this->priority() >= $level->priority();
+    }
+
+    /**
+     * Create a LogLevel from a string, defaulting to Info.
+     */
+    public static function fromString(string $level): self
+    {
+        return match (strtoupper($level)) {
+            'DEBUG' => self::Debug,
+            'WARN', 'WARNING' => self::Warn,
+            'ERROR' => self::Error,
+            default => self::Info,
+        };
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Logging/Logger.php

@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Logging;
+
+/**
+ * Logger captures log entries for inclusion in ExecutionResult.logs.
+ *
+ * Provides level-based filtering and a capture buffer that can be
+ * retrieved as structured entries or formatted lines.
+ */
+final class Logger
+{
+    /** @var LogEntry[] */
+    private array $entries = [];
+
+    public function __construct(
+        private readonly LogLevel $minLevel = LogLevel::Info,
+    ) {}
+
+    /**
+     * Log a message at the given level.
+     */
+    private function log(LogLevel $level, string $message, ?array $fields = null): void
+    {
+        if (!$level->isAtLeast($this->minLevel)) {
+            return;
+        }
+
+        $this->entries[] = new LogEntry(
+            level: $level,
+            message: $message,
+            timestamp: gmdate('Y-m-d\TH:i:s\Z'),
+            fields: $fields,
+        );
+    }
+
+    /**
+     * Log a debug message.
+     */
+    public function debug(string $message): void
+    {
+        $this->log(LogLevel::Debug, $message);
+    }
+
+    /**
+     * Log a debug message with fields.
+     */
+    public function debugWith(string $message, array $fields): void
+    {
+        $this->log(LogLevel::Debug, $message, $fields);
+    }
+
+    /**
+     * Log an info message.
+     */
+    public function info(string $message): void
+    {
+        $this->log(LogLevel::Info, $message);
+    }
+
+    /**
+     * Log an info message with fields.
+     */
+    public function infoWith(string $message, array $fields): void
+    {
+        $this->log(LogLevel::Info, $message, $fields);
+    }
+
+    /**
+     * Log a warning message.
+     */
+    public function warn(string $message): void
+    {
+        $this->log(LogLevel::Warn, $message);
+    }
+
+    /**
+     * Log a warning message with fields.
+     */
+    public function warnWith(string $message, array $fields): void
+    {
+        $this->log(LogLevel::Warn, $message, $fields);
+    }
+
+    /**
+     * Log an error message.
+     */
+    public function error(string $message): void
+    {
+        $this->log(LogLevel::Error, $message);
+    }
+
+    /**
+     * Log an error message with fields.
+     */
+    public function errorWith(string $message, array $fields): void
+    {
+        $this->log(LogLevel::Error, $message, $fields);
+    }
+
+    /**
+     * Get all captured log entries.
+     *
+     * @return LogEntry[]
+     */
+    public function entries(): array
+    {
+        return $this->entries;
+    }
+
+    /**
+     * Get log entries as formatted strings for ExecutionResult.logs.
+     *
+     * @return string[]
+     */
+    public function lines(): array
+    {
+        return array_map(
+            static fn (LogEntry $entry): string => (string) $entry,
+            $this->entries,
+        );
+    }
+
+    /**
+     * Clear all captured entries.
+     */
+    public function clear(): void
+    {
+        $this->entries = [];
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Node/NodeHandler.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Node;
+
+use Blok\Blok\Types\Context;
+
+/**
+ * NodeHandler is the core interface that all Blok nodes must implement.
+ *
+ * Example:
+ * ```php
+ * class MyNode implements NodeHandler
+ * {
+ *     public function execute(Context $ctx, array $config): mixed
+ *     {
+ *         $name = $ctx->request->bodyStr('name') ?? 'World';
+ *         return ['message' => "Hello, {$name}!"];
+ *     }
+ * }
+ * ```
+ */
+interface NodeHandler
+{
+    /**
+     * Execute the node logic with the given workflow context and node configuration.
+     *
+     * @param Context $ctx The workflow execution context
+     * @param array<string, mixed> $config Node-specific configuration
+     * @return mixed The result data to include in the ExecutionResult
+     * @throws \Throwable On execution failure
+     */
+    public function execute(Context $ctx, array $config): mixed;
+}

package/dist/scaffold-repo/sdks/php/src/Node/NodeReflector.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Node;
+
+/**
+ * Implemented by typed nodes (see {@see TypedNode}) to expose a description +
+ * JSON Schema for the node catalog (GET /__blok/nodes) via gRPC ListNodes
+ * (SPEC-B P4). Legacy {@see NodeHandler} nodes don't implement it.
+ */
+interface NodeReflector
+{
+    public function description(): string;
+
+    /** @return array<string, mixed>|null JSON Schema for the input, or null. */
+    public function inputSchema(): ?array;
+
+    /** @return array<string, mixed>|null JSON Schema for the output, or null. */
+    public function outputSchema(): ?array;
+}

package/dist/scaffold-repo/sdks/php/src/Node/NodeRegistry.php

@@ -0,0 +1,172 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Node;
+
+use Blok\Blok\Errors\BlokError;
+use Blok\Blok\Server\Middleware;
+use Blok\Blok\Server\MiddlewarePipeline;
+use Blok\Blok\Types\ExecutionMetrics;
+use Blok\Blok\Types\ExecutionRequest;
+use Blok\Blok\Types\ExecutionResult;
+use Blok\Blok\Types\HealthStatus;
+
+/**
+ * NodeRegistry manages registered node handlers and dispatches execution requests.
+ */
+final class NodeRegistry
+{
+    /** @var array<string, NodeHandler> */
+    private array $nodes = [];
+
+    /** @var Middleware[] */
+    private array $middlewares = [];
+
+    public function __construct(
+        private readonly string $version = '1.0.0',
+    ) {}
+
+    /**
+     * Register a node handler under the given name.
+     */
+    public function register(string $name, NodeHandler $handler): void
+    {
+        $this->nodes[$name] = $handler;
+    }
+
+    /**
+     * Add middleware to the registry.
+     */
+    public function useMiddleware(Middleware $middleware): void
+    {
+        $this->middlewares[] = $middleware;
+    }
+
+    /**
+     * Look up a node handler by name.
+     */
+    public function get(string $name): ?NodeHandler
+    {
+        return $this->nodes[$name] ?? null;
+    }
+
+    /**
+     * Return the names of all registered nodes.
+     *
+     * @return string[]
+     */
+    public function nodeNames(): array
+    {
+        return array_keys($this->nodes);
+    }
+
+    /**
+     * Return the number of registered nodes.
+     */
+    public function count(): int
+    {
+        return count($this->nodes);
+    }
+
+    /**
+     * Return whether the registry is empty.
+     */
+    public function isEmpty(): bool
+    {
+        return empty($this->nodes);
+    }
+
+    /**
+     * Execute a node by dispatching through the registry.
+     */
+    public function execute(ExecutionRequest $req): ExecutionResult
+    {
+        $handler = $this->get($req->node->name);
+        if ($handler === null) {
+            return ExecutionResult::error(
+                sprintf("node '%s' not found in registry", $req->node->name)
+            );
+        }
+
+        // Apply middleware chain
+        if (!empty($this->middlewares)) {
+            $pipeline = new MiddlewarePipeline($this->middlewares);
+            $handler = $pipeline->wrap($handler);
+        }
+
+        $startTime = hrtime(true);
+
+        try {
+            $data = $handler->execute($req->context, $req->node->config);
+            $durationMs = (hrtime(true) - $startTime) / 1_000_000;
+            $memoryBytes = memory_get_peak_usage(true);
+
+            $result = ExecutionResult::successWithMetrics(
+                $data,
+                new ExecutionMetrics(
+                    durationMs: round($durationMs, 3),
+                    memoryBytes: $memoryBytes,
+                ),
+            );
+
+            // Include context vars so the runner can propagate them downstream
+            if (!empty($req->context->vars)) {
+                $result->withVars($req->context->vars);
+            }
+
+            return $result;
+        } catch (BlokError $e) {
+            // Structured BlokError path (master plan §17): pass the instance
+            // through verbatim so the gRPC servicer can serialize every field
+            // (category, severity, remediation, retryable hints, cause chain,
+            // context snapshot, etc.) into the proto NodeError.
+            $durationMs = (hrtime(true) - $startTime) / 1_000_000;
+            $memoryBytes = memory_get_peak_usage(true);
+
+            $result = new ExecutionResult(
+                success: false,
+                data: null,
+                errors: $e,
+            );
+            $result->withMetrics(new ExecutionMetrics(
+                durationMs: round($durationMs, 3),
+                memoryBytes: $memoryBytes,
+            ));
+
+            return $result;
+        } catch (\Throwable $e) {
+            // Preserve the typed Throwable on `errors` so the gRPC servicer's
+            // `internalErrorToProto` can derive `UNCAUGHT_<TYPE>` from the
+            // exception class via `BlokError::fromUnknown` per §17.7.
+            // (PHP's `mixed` type lets us store the instance directly,
+            // mirroring Rust's typed-error preservation.)
+            $durationMs = (hrtime(true) - $startTime) / 1_000_000;
+            $memoryBytes = memory_get_peak_usage(true);
+
+            $result = new ExecutionResult(
+                success: false,
+                data: null,
+                errors: $e,
+            );
+            $result->withMetrics(new ExecutionMetrics(
+                durationMs: round($durationMs, 3),
+                memoryBytes: $memoryBytes,
+            ));
+
+            return $result;
+        }
+    }
+
+    /**
+     * Return the health status.
+     */
+    public function health(): HealthStatus
+    {
+        return new HealthStatus(
+            status: 'healthy',
+            version: $this->version,
+            nodesLoaded: $this->nodeNames(),
+        );
+    }
+}

package/dist/scaffold-repo/sdks/php/src/Node/TypedNode.php

@@ -0,0 +1,159 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Blok\Blok\Node;
+
+use Blok\Blok\Errors\BlokError;
+use Blok\Blok\Types\Context;
+
+/**
+ * Typed node base (SPEC-B P4) — the PHP equivalent of the TypeScript
+ * `defineNode` / Python `@node` / Rust `TypedNode`. Declare a typed input DTO
+ * (a class with constructor-promoted typed properties) via {@see inputClass};
+ * the SDK hydrates the raw config array into it (a type mismatch / missing
+ * required field → structured {@see BlokError}, HTTP 400) BEFORE {@see run},
+ * and reflects the input/output JSON Schemas — instead of a raw `array $config`.
+ *
+ * Register like any handler: `$registry->register('@acme/search', new SearchNode());`
+ *
+ * ```php
+ * final class SearchInput {
+ *     public function __construct(public string $query, public int $limit = 10) {}
+ * }
+ * final class SearchNode extends TypedNode {
+ *     public function name(): string { return '@acme/search'; }
+ *     public function description(): string { return 'Full-text search'; }
+ *     protected function inputClass(): string { return SearchInput::class; }
+ *     protected function run(Context $ctx, object $input): mixed {
+ *         $rows = array_fill(0, $input->limit, $input->query);
+ *         return ['results' => $rows, 'count' => count($rows)];
+ *     }
+ * }
+ * ```
+ */
+abstract class TypedNode implements NodeHandler, NodeReflector
+{
+    /** The node's registered name (e.g. `"@acme/search"`). */
+    abstract public function name(): string;
+
+    /** Human-readable description, surfaced in the node catalog. */
+    public function description(): string
+    {
+        return '';
+    }
+
+    /** @return class-string FQCN of the input DTO. */
+    abstract protected function inputClass(): string;
+
+    /** @return class-string|null FQCN of the output DTO (for schema reflection), or null. */
+    protected function outputClass(): ?string
+    {
+        return null;
+    }
+
+    /**
+     * Run the node with a VALIDATED, hydrated input DTO.
+     *
+     * @param object $input instance of {@see inputClass}
+     * @return mixed the output (array/scalar/object) included in the result
+     */
+    abstract protected function run(Context $ctx, object $input): mixed;
+
+    public function execute(Context $ctx, array $config): mixed
+    {
+        try {
+            $input = $this->hydrate($this->inputClass(), $config);
+        } catch (\Throwable $e) {
+            throw BlokError::validation()
+                ->code('NODE_INPUT_VALIDATION')
+                ->message(sprintf("Input validation failed for node '%s': %s", $this->name(), $e->getMessage()))
+                ->httpStatus(400)
+                ->node($this->name())
+                ->build();
+        }
+
+        return $this->run($ctx, $input);
+    }
+
+    /** Hydrate a config array into the typed DTO; the typed ctor enforces types. */
+    private function hydrate(string $class, array $config): object
+    {
+        $ref = new \ReflectionClass($class);
+        $ctor = $ref->getConstructor();
+        if ($ctor === null) {
+            return $ref->newInstance();
+        }
+
+        $args = [];
+        foreach ($ctor->getParameters() as $param) {
+            $name = $param->getName();
+            if (array_key_exists($name, $config)) {
+                $args[] = $config[$name];
+            } elseif ($param->isDefaultValueAvailable()) {
+                $args[] = $param->getDefaultValue();
+            } elseif ($param->allowsNull()) {
+                $args[] = null;
+            } else {
+                throw new \InvalidArgumentException("missing required field '{$name}'");
+            }
+        }
+
+        // A typed constructor throws TypeError on an unconvertible value.
+        return $ref->newInstanceArgs($args);
+    }
+
+    public function inputSchema(): ?array
+    {
+        return $this->reflectSchema($this->inputClass());
+    }
+
+    public function outputSchema(): ?array
+    {
+        $class = $this->outputClass();
+
+        return $class === null ? null : $this->reflectSchema($class);
+    }
+
+    /** @return array<string, mixed> a minimal JSON Schema from the DTO's typed ctor params. */
+    private function reflectSchema(string $class): array
+    {
+        $ref = new \ReflectionClass($class);
+        $properties = [];
+        $required = [];
+
+        $ctor = $ref->getConstructor();
+        if ($ctor !== null) {
+            foreach ($ctor->getParameters() as $param) {
+                $properties[$param->getName()] = $this->typeToSchema($param->getType());
+                if (!$param->isOptional() && !$param->allowsNull()) {
+                    $required[] = $param->getName();
+                }
+            }
+        }
+
+        $schema = ['type' => 'object', 'properties' => (object) $properties];
+        if ($required !== []) {
+            $schema['required'] = $required;
+        }
+
+        return $schema;
+    }
+
+    /** @return array<string, mixed> */
+    private function typeToSchema(?\ReflectionType $type): array
+    {
+        if ($type instanceof \ReflectionNamedType) {
+            return match ($type->getName()) {
+                'int' => ['type' => 'integer'],
+                'float' => ['type' => 'number'],
+                'bool' => ['type' => 'boolean'],
+                'string' => ['type' => 'string'],
+                'array' => ['type' => 'array'],
+                default => ['type' => 'object'],
+            };
+        }
+
+        return [];
+    }
+}