Codebuilder Laravel Package

Technical Evaluation

Architecture fit. keboola/codebuilder is a narrow, leaf-level utility: it consumes a JSON-defined user script (language, script body, packages/dependencies, parameters) and materializes it into an executable process. It is not a framework, not a service, and not an abstraction layer — it is a thin, opinionated translation from a declarative JSON document to a proc_open-style invocation. It fits our architecture only if we explicitly need Keboola-style code-builder semantics: i.e., we are building Keboola-compatible transformations components or an ETL runner that must accept Keboola's transformation payloads. If we simply need "run a user-provided script from config," this package is a ~200-line concern we should own directly. Nothing in 1.0.1 changes this — it remains a leaf utility, not a platform component.

Integration feasibility. MIT license, PHP, Composer-installable, small surface area — all favorable. New information: version 1.0.1 has been published, the first release since 2022-03-30. It is a single-commit patch (PR #7: "Check for invalid attribute type and its test") authored by a Keboola maintainer — a validation fix plus its test, no new features, no deprecations, no breaking API changes signalled. This is a meaningful correction to the "no release since 2022" signal but not evidence of a maintenance cadence: one commit after ~3 years, with still 1 star and 0 dependents, is a liveness blip, not external validation. Integration remains technically easy and organizationally questionable, marginally less so than before.

Technical risk. The dominant risk is unchanged and is the function itself: the package's entire job is to take user-controlled data and turn it into an executed process. Command injection, argument escaping, environment/credential leakage into child processes, unbounded output, and timeout/zombie handling all remain in scope. The 1.0.1 change is relevant to one specific risk — payload validation — but it is narrow: it validates attribute type rather than performing full schema validation, so unknown keys, missing keys, and semantically invalid combinations are likely still silently tolerated. Note also that adding validation in a patch release can convert previously-accepted (if malformed) payloads into hard failures; we must confirm whether the new check throws or warns. Secondary risks: (a) dormancy rather than abandonment — Keboola maintains this for its own platform, not for external consumers, and will keep doing so episodically; (b) undocumented JSON schema — the contract is internal to Keboola components and will drift; (c) PHP version drift — the 1.0.x line's PHP constraints still need verification against a modern Laravel runtime.

Key questions.

1. Are we integrating because we need Keboola compatibility, or because we need script execution? If the latter, why take the dependency?
2. Who is the internal owner of the JSON schema contract, and how do we version it independently of the vendor?
3. What are our isolation requirements (container, seccomp, network egress, filesystem)? Does the package's execution model meet them, or does it assume it is already inside a sandbox?
4. Does the package expose timeouts, output caps, exit-code propagation, and stderr capture — or do we have to wrap it anyway?
5. New: Is the 1.0.1 attribute-type validation fail-closed (throws) or fail-open (warns/ignores)? Does it break any payload shape we currently emit, and does the behavior change deserve a minor-version bump it did not get?
6. What is the build-vs-fork-vs-adopt cost over 24 months, given that the single 2026 commit is the only upstream signal in three years?

Integration Approach

Stack fit. PHP-native (Laravel-compatible in the sense that it is plain Composer/PHP and does not fight the framework), but it is not Laravel-idiomatic — no service provider, no config publishing, no queue integration. In a polyglot estate, the correct placement is behind a service or job boundary, not inlined into a request path. Never execute user scripts synchronously inside an HTTP request.

Migration path. With 0 dependents there is no incumbent migration to perform — this is greenfield adoption, which is also the risk: no prior art to borrow. Introduce it behind an owned interface (ScriptRunner / TransformationExecutor) so the vendor type never leaks into domain code. Pin to the exact version (1.0.1) in composer.json, commit the lockfile, and vendor-fork into our namespace at first adoption rather than at first breakage. The patch-level validation change is precisely the kind of behavior shift that argues for exact pins over caret constraints.

Compatibility. Verify before anything else: composer.json PHP constraint against our runtime, transitive dependency footprint (does it pull a process/console component we already have at a different version?), PSR-4 autoload correctness, and whether it assumes a Unix shell, specific interpreters, or a Keboola-provided working directory and env vars. Assume Keboola-specific environment assumptions until proven otherwise. Add to this list: the new attribute-type validation — reproduce it against our representative payloads on both 1.0.0 and 1.0.1 to confirm the delta is limited to genuinely invalid input.

Sequencing.

1. Spike (1–2 days): reproduce one representative transformation end-to-end in a scratch branch, inside the actual sandbox target, on 1.0.1.
2. Security review of the execution path — argument construction, escaping, env filtering, output handling. Gate here; do not proceed on a "looks fine."
3. Contract capture: golden-file tests on the JSON schema we intend to support, derived from Keboola's own component fixtures. Run them against 1.0.0 and 1.0.1 to pin down the validation delta.
4. Adapter layer + ownership decision: adopt-as-dependency vs. fork vs. reimplement. Default to reimplement unless we need byte-level Keboola compatibility.
5. Pilot on a non-critical, low-volume workload with a documented rollback to a no-op runner.
6. Hardening: resource limits, timeouts, output truncation, structured failure reporting.

Operational Impact

Maintenance. Treat as dormant, not dead. One patch in ~3 years, single-vendor ownership, no external contributor base. The 1.0.1 release is a positive data point for our quarterly upstream-activity review but does not establish a cadence, and the commit is a maintainer fixing a specific reported issue rather than a roadmap signal. We should still assume we will carry the fork. Keep a named owner and the quarterly review; if the fork diverges, that owner owns the divergence permanently. Treat 1.0.1 as a floor, not a trend.

Support. Community support is nil (1 star, 0 dependents — there is no forum, no Stack Overflow corpus, no third-party blog coverage to lean on). Upstream support exists only as a Keboola vendor relationship, which we do not have. Internal support burden therefore lands entirely on our team, including onboarding, incident triage, and schema questions. The new validation path is now part of what we must be able to explain to operators — "why did this payload that worked last month get rejected?" — and there is no upstream documentation to point at.

Scaling. Execution is process-bound: each run forks an interpreter. There is no pooling, no warm workers, no caching visible in the package's scope. Throughput scales with our job-runner concurrency and host resources, not with the library. The real scaling constraint is isolation density — containers/VMs per execution — plus interpreter/package-dependency cold-start, which for Python/R with dynamic package installs can dominate wall-clock time. Plan capacity around p95 script runtime, not average.

Failure modes. The ones to instrument for explicitly:

• Timeout / hang — child process outlives the request or job lease; orphans accumulate.
• Exit-code masking — a script fails but the wrapper reports success because only stdout is inspected.
• stdout/stderr truncation or interleaving — logs corrupted, root cause invisible.
• Schema drift — a payload shape the package silently ignores or misinterprets (e.g., unknown key dropped) producing a successful run of the wrong script. 1.0.1 narrows this for attribute types only; treat the remaining surface as unvalidated.
• New (from 1.0.1): patch-release rejection — payloads that were tolerated on 1.0.0 now fail validation on 1.0.1. Pin exact versions, and gate dependency bumps behind the golden-file suite rather than relying on semver.
• Environment leakage — host credentials or internal hostnames visible to user-authored code.
• Dependency-install failure inside the sandbox — network-restricted environments plus declared packages equals runtime failure that is not a code bug.
• Resource exhaustion — unbounded output or memory from user code taking down the worker.

Each needs a metric, an alert, and a documented operator runbook before go-live.

Ramp-up. Low for the API (it is small), deceptively high for the semantics: the JSON schema is undocumented outside Keboola's ecosystem, so engineers will reverse-engineer it from Keboola component source and fixtures — and now also from the 1.0.1 diff to learn what "invalid attribute type" means in practice. Estimate 3–5 days for a competent PHP engineer to reach productive use including the security review, plus ongoing cost of ownership of the schema contract. Onboarding a second engineer is harder than usual because there is no external documentation to point them at.

Recommendation. Unchanged in direction, slightly softened in tone: adopt only under an explicit Keboola-compatibility mandate; otherwise reimplement the ~200-line execution core on top of a maintained process abstraction and keep ownership in-house. The 1.0.1 patch is welcome — it shows the upstream is not formally archived and it hardens one input-validation edge — but a single maintainer commit does not convert a 1-star, 0-dependent, security-critical execution utility into a supported dependency. A TPM should still require the compatibility argument in writing before accepting it.