@gadicc/loom 1.20.0 → 1.21.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,81 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.DEFAULT_JOBS_RUN_REQUEST_METHOD = void 0;
4
+ exports.buildJobsRunSearchParams = buildJobsRunSearchParams;
5
+ exports.getJobsRunResponseErrorMessage = getJobsRunResponseErrorMessage;
6
+ const MAX_JOBS_RUN_ERROR_BODY_LENGTH = 1_000;
7
+ /** The compatibility transport used when a run panel does not choose one. */
8
+ exports.DEFAULT_JOBS_RUN_REQUEST_METHOD = "GET";
9
+ /**
10
+ * Preserves compatibility query values while overlaying declared form fields.
11
+ * Empty non-boolean fields remove an existing value instead of sending it.
12
+ */
13
+ function buildJobsRunSearchParams(queryString, definitions, formValues) {
14
+ const searchParams = new URLSearchParams(queryString ?? "");
15
+ if (!definitions)
16
+ return searchParams;
17
+ for (const [key, definition] of Object.entries(definitions)) {
18
+ const value = formValues[key] ?? "";
19
+ if (definition.type === "boolean") {
20
+ searchParams.set(key, value === "true" ? "true" : "false");
21
+ }
22
+ else if (value !== "") {
23
+ searchParams.set(key, value);
24
+ }
25
+ else {
26
+ searchParams.delete(key);
27
+ }
28
+ }
29
+ return searchParams;
30
+ }
31
+ function safeJsonStringify(value) {
32
+ try {
33
+ return JSON.stringify(value);
34
+ }
35
+ catch {
36
+ return String(value);
37
+ }
38
+ }
39
+ function boundJobsRunErrorBody(value) {
40
+ const normalized = value.trim();
41
+ if (normalized.length <= MAX_JOBS_RUN_ERROR_BODY_LENGTH) {
42
+ return normalized;
43
+ }
44
+ return `${normalized.slice(0, MAX_JOBS_RUN_ERROR_BODY_LENGTH - 3)}...`;
45
+ }
46
+ function getJsonErrorBody(body) {
47
+ try {
48
+ const parsed = JSON.parse(body);
49
+ if (typeof parsed !== "object" ||
50
+ parsed === null ||
51
+ !("error" in parsed)) {
52
+ return null;
53
+ }
54
+ const error = parsed.error;
55
+ return typeof error === "string" ? error : safeJsonStringify(error);
56
+ }
57
+ catch {
58
+ return null;
59
+ }
60
+ }
61
+ /**
62
+ * Builds a bounded plain-text message for a failed jobs runner response.
63
+ * Response content is returned only as text so React escapes it when rendered.
64
+ */
65
+ async function getJobsRunResponseErrorMessage(response) {
66
+ const fallback = `Request failed with status ${response.status}`;
67
+ try {
68
+ const body = await response.text();
69
+ if (!body.trim())
70
+ return fallback;
71
+ const contentType = response.headers.get("content-type")?.toLowerCase();
72
+ const detail = contentType?.includes("application/json")
73
+ ? getJsonErrorBody(body) ?? body
74
+ : body;
75
+ const boundedDetail = boundJobsRunErrorBody(detail);
76
+ return boundedDetail ? `${fallback}: ${boundedDetail}` : fallback;
77
+ }
78
+ catch {
79
+ return fallback;
80
+ }
81
+ }
@@ -80,13 +80,38 @@ Use this skill when working on the shared jobs feature from a consuming app.
80
80
  preserve the existing session/admin branch.
81
81
  - Use `authorizeSessionOrApiKeyRequest` plus `completeApiKeyAuthorizedResponse`
82
82
  for auditable response creation without buffering job streams.
83
- - GET and POST remain supported; a future POST-only change requires a separate
84
- compatibility migration.
83
+ - The shared admin runner accepts `requestMethod: "POST"`; new Loom scaffolds
84
+ prefer POST while the component's omitted/default method remains GET for
85
+ existing consumers. Declared job parameters remain query parameters under
86
+ either method.
87
+ - GET and POST route exports remain supported for external callers; a future
88
+ POST-only change requires a separate compatibility migration.
85
89
  - The direct local runner imports the catalog and executes inside the trusted
86
90
  shell process with local environment/database access. It remains API-key-free.
87
91
  A future command that calls a deployed HTTP route is a remote client and must
88
92
  authenticate.
89
93
 
94
+ ## Browser runner boundaries
95
+
96
+ - Prefer `createJobsRunPage` or `JobsRunPanel` over an app-local executor. The
97
+ shared runner owns streaming, status, cancellation, declarative parameters,
98
+ bounded non-success details, and safe structured rendering hooks.
99
+ - Never import `@gadicc/loom/jobs/format` into a client component or any local
100
+ module reachable beneath a `"use client"` boundary. Its rich formatter uses
101
+ Node's `formatWithOptions` intentionally and remains valid for server routes,
102
+ CLI output, and text/HTML response formatting.
103
+ - Import `formatJobLogTime` from `@gadicc/loom/jobs/log` in browser code. Render
104
+ structured values with `JobsRunPanel`, its `renderLogValue` hook, or another
105
+ helper whose browser support is explicit.
106
+ - Keep executable job catalogs and server-only formatters in server modules. A
107
+ server wrapper may pass serializable job metadata to a client island, but the
108
+ metadata catalog it imports must stay dependency-free so executable or
109
+ Node-only modules cannot enter the browser graph transitively.
110
+ - Record a non-default admin transport in
111
+ `features.jobs.config.ui.requestMethod`; `loom check` follows the configured
112
+ run-page's local server-wrapper/client-island graph, verifies the shared
113
+ runner and request method, and reports browser-unsafe imports.
114
+
90
115
  ## Diagnosing queued work
91
116
 
92
117
  - Distinguish the control-plane action that queues a job from the worker or
@@ -170,7 +195,7 @@ When adding or upgrading a job:
170
195
  - Run `loom check` after changes.
171
196
  - Confirm local wrappers still point at the configured shared modules.
172
197
  - Confirm the jobs modules still use the shared helpers: `createJobsListPage`,
173
- `createJobsRunPage`, and `createJobsRouteHandler`.
198
+ either `createJobsRunPage` or `JobsRunPanel`, and `createJobsRouteHandler`.
174
199
  - Confirm executable catalog entries use `createLazyJob` and the metadata
175
200
  catalog does not import job implementations.
176
201
  - Confirm the authoritative `job` task runs the direct runner through