@dudousxd/nestjs-catalog 0.8.0 → 0.9.0

package/dist/catalog.events.d.ts

@@ -14,7 +14,7 @@
  */
 export declare const CATALOG_LIB = "catalog";
 /** Every event name this package emits. Exported so a watcher can claim them. */
-export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
+export declare const CATALOG_EVENTS: readonly ["schema.changed", "snapshot.written", "snapshot.committed", "snapshot.dropped", "type.curated", "overlay.reset", "connector.run.started", "connector.run.finished", "transform.changed", "workflow.changed", "query.shared", "dashboard.shared"];
 export type CatalogEvent = (typeof CATALOG_EVENTS)[number];
 /**
  * Where each event sits in the life of one load.
@@ -81,6 +81,77 @@ export interface CatalogEventPayloads {
         property?: string;
         changed: string[];
     };
+    /**
+     * The whole overlay was discarded — every curated label, description, unit,
+     * order, hidden flag and classification in the catalog, in one request.
+     *
+     * An event of its own rather than a `type.curated` with the name left off.
+     * That payload leads with `typeName`, and a recorder lifts it into an indexed
+     * column; a reset has no single type, so it would land as a curation edit
+     * belonging to no type, indistinguishable from a malformed one. It is also a
+     * different act: `type.curated` records a decision about one column, this
+     * records the destruction of every such decision. Without it the trail could
+     * say who renamed one column and not who reverted every name at once — and
+     * both are `catalog:curate`, so the same curator can do either.
+     *
+     * **The classifications are why this is not merely tidy.** A classification is
+     * what `visibleToPrincipal` filters search results on, so a reset silently
+     * re-admits every classified property's *name* to searches by principals who
+     * could not see it an instant earlier. That is a change in who can see what,
+     * made by a route the controller documents as presentation-only.
+     *
+     * WHAT IT CARRIES, AND WHAT IT DELIBERATELY DOES NOT
+     * --------------------------------------------------
+     * The overlay is discarded rather than versioned, so nothing can be looked up
+     * afterwards: what is not in this payload is nowhere. That argues for carrying
+     * all of it, and all of it is the wrong answer — an audit row holding a
+     * verbatim copy of the overlay is a backup, and a backup nobody designed: no
+     * restore path, no retention policy of its own, and a JSON column that grows
+     * with the catalog. It would be read as one, too. The first person who needed
+     * it would find it, and the second would rely on it.
+     *
+     * So: a summary, drawn where the reader's question stops being "what did I
+     * lose" and starts being "give it back".
+     *
+     * - {@link typeNames}, because "somebody reset the catalog" is nearly useless
+     *   six months later and "was the work on `Dispute` in it" is what is actually
+     *   asked. Bounded by how many types anyone had curated.
+     * - {@link properties}, the scale of it as one number. The property *names* are
+     *   where a summary would turn into the dump.
+     * - {@link classifications} in full, values included, despite that line. They
+     *   are the one part of the overlay whose loss changes what the catalog shows
+     *   to whom, they are a small subset of it, and re-typing them is the only
+     *   recovery anybody can perform.
+     *
+     * **No `principalId`, and the absence is a limit rather than a decision that
+     * the actor does not matter.** `resetOverlay()` takes no principal, the route
+     * that calls it resolves none, and `RoutingCatalogRegistry` forwards the call
+     * by hand — so a field here would be `undefined` on every row, and an audit
+     * table lifts `principalId` into a column where empty reads as "nobody did
+     * this" rather than "this was not captured". `type.curated` has the same gap.
+     * Closing it means threading a principal through the controller, the service
+     * and every registry, which is a change to those, not a field on this payload.
+     *
+     * Emitted even when the overlay was empty, with zeroes. A trail that recorded
+     * only destructive resets cannot tell "nobody pressed it" from "somebody
+     * pressed it and nothing was there", and the second is worth seeing.
+     */
+    'overlay.reset': {
+        /** Every type that carried curation, so the trail names what was lost. */
+        typeNames: string[];
+        /** How many per-property entries went with them, across every type. */
+        properties: number;
+        /**
+         * Every classification that stopped applying, with its value — because that
+         * is what somebody restoring one needs, and after the reset there is nowhere
+         * left to read it.
+         */
+        classifications: Array<{
+            typeName: string;
+            property: string;
+            classification: string;
+        }>;
+    };
     /** A connector began pulling. */
     'connector.run.started': {
         connectorId: string;

package/dist/catalog.events.js

@@ -27,6 +27,7 @@ exports.CATALOG_EVENTS = [
     'snapshot.committed',
     'snapshot.dropped',
     'type.curated',
+    'overlay.reset',
     'connector.run.started',
     'connector.run.finished',
     'transform.changed',
@@ -67,6 +68,11 @@ exports.CATALOG_EVENT_PHASE = {
     // be complete is exactly the mechanism that will fail the build the day a new
     // event is added and nobody thinks about where it belongs.
     'type.curated': 2,
+    // The other curation event, ranked with the one it undoes. It carries no
+    // snapshot id either — a reset is not part of any load — so like the rank
+    // above this is never consulted, and it is written out because the `Record`
+    // has to be complete.
+    'overlay.reset': 2,
     // Sharing carries no snapshot id either, for the same reason curation does
     // not: it is a standalone act on a saved query or a board, not a step of any
     // load. So these ranks are never consulted, and they are written out for the

package/dist/catalog.overlay-store.d.ts

@@ -17,7 +17,28 @@ export declare class FileCatalogOverlayStore implements CatalogOverlayStore {
     load(): Promise<CatalogOverlay>;
     save(overlay: CatalogOverlay): Promise<void>;
 }
-/** For tests, and for deployments that want the catalog strictly read-only. */
+/**
+ * For tests, and for a single-process deployment content to lose every curated
+ * value when it restarts.
+ *
+ * **Not a read-only mode**, which is what this used to offer itself as. Nothing
+ * here refuses anything: `save` takes the overlay and keeps it, `PATCH
+ * /catalog/types/:name` answers 200 and emits `type.curated`, and the rename is
+ * real right up until the process ends. What it is not is *shared* — the overlay
+ * lives in one process's heap, so two replicas behind the same load balancer
+ * disagree about what a column is called, and which name a curator sees back
+ * depends on which pod took their request. A deployment that chose this store
+ * because the docblock promised read-only got precisely the writes it was trying
+ * to prevent, and got them inconsistently.
+ *
+ * There is no mode here to turn on instead, because read-only is not a store's
+ * decision. The writes arrive on routes that declare `catalog:curate`, and
+ * whether a deployment grants that scope is its guard's business — see the
+ * declare-and-enforce split in `catalog.route-auth.ts`. A store that threw would
+ * turn a policy answer ("you may not curate here") into a 500 from a route the
+ * library documents as working, and would put a second mechanism beside the one
+ * that already decides.
+ */
 export declare class InMemoryCatalogOverlayStore implements CatalogOverlayStore {
     private overlay;
     load(): Promise<CatalogOverlay>;

package/dist/catalog.overlay-store.js

@@ -13,12 +13,15 @@ class FileCatalogOverlayStore {
         try {
             const raw = await (0, promises_1.readFile)(this.path, 'utf8');
             const parsed = JSON.parse(raw);
-            if (parsed &&
-                typeof parsed === 'object' &&
-                'types' in parsed &&
-                typeof parsed.types === 'object') {
+            // Narrowed by a guard rather than asserted. The file on disk is edited by
+            // hand — that is the whole point of a JSON overlay — so its contents are
+            // exactly as trustworthy as whoever last opened it, and an assertion here
+            // would hand the registry a shape it promised to have rather than one it
+            // was checked for. The failure that buys is quiet: `types` arriving as
+            // `null` (an object, by `typeof`) or as an array reads as an overlay with
+            // no curation, and every label somebody wrote silently stops applying.
+            if (isOverlay(parsed))
                 return parsed;
-            }
             return { types: {} };
         }
         catch {
@@ -31,7 +34,28 @@ class FileCatalogOverlayStore {
     }
 }
 exports.FileCatalogOverlayStore = FileCatalogOverlayStore;
-/** For tests, and for deployments that want the catalog strictly read-only. */
+/**
+ * For tests, and for a single-process deployment content to lose every curated
+ * value when it restarts.
+ *
+ * **Not a read-only mode**, which is what this used to offer itself as. Nothing
+ * here refuses anything: `save` takes the overlay and keeps it, `PATCH
+ * /catalog/types/:name` answers 200 and emits `type.curated`, and the rename is
+ * real right up until the process ends. What it is not is *shared* — the overlay
+ * lives in one process's heap, so two replicas behind the same load balancer
+ * disagree about what a column is called, and which name a curator sees back
+ * depends on which pod took their request. A deployment that chose this store
+ * because the docblock promised read-only got precisely the writes it was trying
+ * to prevent, and got them inconsistently.
+ *
+ * There is no mode here to turn on instead, because read-only is not a store's
+ * decision. The writes arrive on routes that declare `catalog:curate`, and
+ * whether a deployment grants that scope is its guard's business — see the
+ * declare-and-enforce split in `catalog.route-auth.ts`. A store that threw would
+ * turn a policy answer ("you may not curate here") into a 500 from a route the
+ * library documents as working, and would put a second mechanism beside the one
+ * that already decides.
+ */
 class InMemoryCatalogOverlayStore {
     overlay = { types: {} };
     async load() {
@@ -42,3 +66,20 @@ class InMemoryCatalogOverlayStore {
     }
 }
 exports.InMemoryCatalogOverlayStore = InMemoryCatalogOverlayStore;
+/**
+ * Whether a parsed file is an overlay, checked to the depth that matters.
+ *
+ * The nesting below `types` is deliberately NOT walked. Every consumer reads it
+ * defensively — an entry that is missing, or missing the key it wanted, is the
+ * ordinary case for a type nobody has curated — so validating each entry would
+ * be re-implementing a tolerance the readers already have, and refusing the
+ * whole file over one malformed entry would discard every good one beside it.
+ */
+function isOverlay(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const types = Reflect.get(value, 'types');
+    // Not `typeof types === 'object'`, which admits `null` and arrays. Both parse
+    // from a hand-edited file, and both read downstream as "nothing is curated".
+    return Boolean(types) && typeof types === 'object' && !Array.isArray(types);
+}

package/dist/catalog.pipeline.d.ts

@@ -158,7 +158,28 @@ export interface CatalogTransform {
 }
 export interface TransformResult {
     rows: Array<Record<string, unknown>>;
-    /** Anything the code logged. Surfaced in the run, never in the rows. */
+    /**
+     * Anything the code logged. Surfaced in the run, never in the rows.
+     *
+     * "Anything the code logged" is meant literally, and in whichever language the
+     * transform is written: `console.log` and its siblings in JavaScript and
+     * TypeScript, `print` and anything written to `sys.stderr` in Python. A
+     * transform author's first instinct for finding out what their code is doing
+     * has to be the thing that works, because the alternative — an empty panel and
+     * no explanation — reads as "my code never ran" rather than as "you used the
+     * wrong function".
+     *
+     * In call order, with the channels interleaved rather than separated: a reader
+     * is reconstructing a sequence, and two lists cannot be zipped back together.
+     *
+     * **Bounded, by the runner, before it is returned.** These are lines user code
+     * chose and they cross a durable step boundary into the run record, so an
+     * unbounded capture would make the size of a `finishRun` write a property of
+     * somebody's source data. The bundled runner keeps the first 500 lines at
+     * 2,000 characters each and appends a line saying how many it dropped — a
+     * truncation nobody is told about is the same failure as a log nobody is told
+     * about. Consumers cap again for display, more tightly.
+     */
     logs: string[];
     elapsedMs: number;
 }

package/dist/catalog.registry.base.d.ts

@@ -62,5 +62,25 @@ export declare abstract class CatalogRegistry {
     /** Presentation-only edits. Never a schema change. */
     abstract patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
     abstract patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Discard every tier-0 edit at once.
+     *
+     * **An implementation that really discards must emit `overlay.reset`**, and
+     * the reason is an asymmetry this class would otherwise have: the two patches
+     * above are audited one field at a time, so a trail could say who renamed one
+     * column and not who reverted every name in the catalog — while both need only
+     * `catalog:curate`. The summary has to be built before the write; nothing
+     * versions an overlay, so afterwards there is nothing left to read.
+     *
+     * **Refusing is an implementation too, and refusing emits nothing.** A
+     * registry whose curated values have no derived layer underneath them has
+     * nothing to fall back to, so a reset there is destruction rather than a
+     * revert, and the throw is the whole answer — no act, no record of one.
+     * `StoredCatalogRegistry` is that case.
+     *
+     * Which of those a deployment runs is why the event is worth more than the
+     * call it accompanies: a registry that quietly resets without emitting looks
+     * exactly like one that never ran a reset at all.
+     */
     abstract resetOverlay(): Promise<void>;
 }

package/dist/catalog.registry.d.ts

@@ -35,6 +35,17 @@ export declare class MikroOrmCatalogRegistry extends CatalogRegistry implements
     patchType(typeName: string, patch: Partial<CatalogOverlay['types'][string]>): Promise<CatalogObjectTypeDef | undefined>;
     /** Tier-0 edit on a property. Never touches the database. */
     patchProperty(typeName: string, propertyName: string, patch: NonNullable<CatalogOverlay['types'][string]['properties']>[string]): Promise<CatalogObjectTypeDef | undefined>;
+    /**
+     * Drop every tier-0 edit, and leave a record that it happened.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     */
     resetOverlay(): Promise<void>;
     private persist;
     private rebuild;

package/dist/catalog.registry.js

@@ -221,9 +221,22 @@ let MikroOrmCatalogRegistry = MikroOrmCatalogRegistry_1 = class MikroOrmCatalogR
         });
         return this.getType(type.name);
     }
+    /**
+     * Drop every tier-0 edit, and leave a record that it happened.
+     *
+     * The summary is taken before the overlay is cleared because it is the only
+     * record there will ever be: nothing versions an overlay, so the discarded
+     * values are gone the instant the store is written. See `overlay.reset` in
+     * `catalog.events.ts` for why the payload is a summary and not a copy.
+     *
+     * Emitted after the write, like the two patches above, so the trail says what
+     * happened rather than what was about to.
+     */
     async resetOverlay() {
+        const discarded = summariseOverlay(this.overlay);
         this.overlay = { types: {} };
         await this.persist();
+        (0, catalog_events_1.emitCatalog)('overlay.reset', discarded);
     }
     async persist() {
         await this.overlayStore.save(this.overlay);
@@ -368,6 +381,39 @@ exports.MikroOrmCatalogRegistry = MikroOrmCatalogRegistry = MikroOrmCatalogRegis
     __param(2, (0, common_1.Inject)(catalog_overlay_store_token_1.CATALOG_OVERLAY_STORE)),
     __metadata("design:paramtypes", [core_1.MikroORM, Object, Object])
 ], MikroOrmCatalogRegistry);
+/**
+ * What a reset is about to destroy, in the shape the trail keeps it.
+ *
+ * Here rather than in `catalog.events.ts` because it reads a `CatalogOverlay`,
+ * and this is the only registry that has one — the payload type is the contract,
+ * this is one producer of it. Pure and taking the overlay as an argument so the
+ * order is forced: a caller has to hold the old overlay to call it, and cannot
+ * accidentally summarise the empty one it just installed.
+ *
+ * A type entry counts whatever it holds, including an entry that ended up empty.
+ * `buildType` treats a present entry as enrichment on the same terms, and the
+ * honest reading of one is "somebody patched this type" — which is exactly what
+ * the reset undid.
+ */
+function summariseOverlay(overlay) {
+    const typeNames = Object.keys(overlay.types);
+    const classifications = [];
+    let properties = 0;
+    for (const typeName of typeNames) {
+        const patched = overlay.types[typeName]?.properties ?? {};
+        for (const [property, patch] of Object.entries(patched)) {
+            properties += 1;
+            const { classification } = patch;
+            // Only a classification that was actually set. An entry that merely
+            // renamed the column carries the key as `undefined`, and listing it would
+            // report a classification lost that nobody had applied.
+            if (classification !== undefined) {
+                classifications.push({ typeName, property, classification });
+            }
+        }
+    }
+    return { typeNames, properties, classifications };
+}
 /**
  * How one field is presented, resolved across the tiers.
  *

package/dist/transform-runner.js

@@ -17,6 +17,57 @@ const node_path_1 = require("node:path");
 const common_1 = require("@nestjs/common");
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/**
+ * How much of what a transform logged is carried back, on both axes.
+ *
+ * Both, because either one alone leaves the capture unbounded in the dimension
+ * it does not cover, and this capture is *user code writing whatever it likes*.
+ * A transform that logs one line per record — the most natural debugging move
+ * there is — puts a copy of the source's data into `logs`, and `logs` is the one
+ * thing that crosses a durable step boundary and lands in the run record. So the
+ * ceiling is fixed here, in the child, before any of it is serialised: the
+ * alternative is a `finishRun` write whose size is a property of somebody's
+ * data.
+ *
+ * The same two numbers for JavaScript and for Python, applied by the two
+ * harnesses below in the same order. A transform's log behaviour changing
+ * because of the language it happens to be written in is a difference nobody can
+ * predict from reading either one.
+ *
+ * Deliberately far above what anything downstream keeps — the connector runner
+ * takes fifty lines, the workflow runner twenty per node at four hundred
+ * characters — because this is the *safety* bound and those are the *display*
+ * bounds. A harness that truncated at the display limit would decide, in the
+ * child, what a future consumer is allowed to see.
+ *
+ * What is dropped is said out loud, in a final line, rather than dropped
+ * quietly. Silence about a missing log is the exact failure this whole capture
+ * exists to remove; reproducing it at line 501 would only move it.
+ */
+const MAX_LOG_LINES = 500;
+const MAX_LOG_LINE_CHARS = 2_000;
+/**
+ * How much of what a *failing* transform logged is folded into the error.
+ *
+ * A failure throws, and a throw carries a message and nothing else — so the
+ * `logs` of a run that raised never reach the caller at all, and every consumer
+ * records the traceback with none of the output that led to it. Capturing
+ * `print` and then discarding it at the exact moment it is most wanted would be
+ * a fix that stops one step short of the case it was written for.
+ *
+ * The **last** lines, not the first, which is the opposite of what the display
+ * caps downstream do — and deliberately. Those are trimming a successful run's
+ * narrative, where the beginning is the story; this is the approach to a
+ * traceback, where the last thing printed is the one that says where the code
+ * got to.
+ *
+ * Small on both axes because this lands in an error message, and an error
+ * message ends up in a run row, a log line and a console toast. The full set is
+ * still on the result whenever the transform returned at all; this is the
+ * consolation for the path where there is no result.
+ */
+const FAILURE_LOG_LINES = 10;
+const FAILURE_LOG_CHARS = 200;
 /** Packages worth telling the author about, if the environment has them. */
 const REPORTED_PACKAGES = ['pandas', 'numpy', 'pyarrow', 'requests'];
 /**
@@ -111,14 +162,15 @@ let SubprocessTransformRunner = SubprocessTransformRunner_1 = class SubprocessTr
         catch {
             throw new Error(`The transform did not return anything readable. stderr: ${stderr.slice(0, 500)}`);
         }
+        const logs = Array.isArray(parsed.logs) ? parsed.logs.map(String) : [];
         if (parsed.error)
-            throw new Error(parsed.error);
+            throw new Error(withFinalLogs(parsed.error, logs));
         if (!Array.isArray(parsed.rows)) {
             throw new Error('The transform must return an array of rows. Returning anything else would leave the load ambiguous.');
         }
         return {
             rows: parsed.rows.filter((row) => typeof row === 'object' && row !== null && !Array.isArray(row)),
-            logs: Array.isArray(parsed.logs) ? parsed.logs.map(String) : [],
+            logs,
             elapsedMs: Date.now() - started,
         };
     }
@@ -204,18 +256,68 @@ exports.SubprocessTransformRunner = SubprocessTransformRunner = SubprocessTransf
     (0, common_1.Injectable)(),
     __metadata("design:paramtypes", [Object])
 ], SubprocessTransformRunner);
+/**
+ * The traceback, plus the tail of what the code printed on its way to it.
+ *
+ * Named in the message rather than appended bare, and counted rather than
+ * merely truncated: "the last 10 of 57 lines" tells a reader there is more to
+ * find on the run's own log, where a silent tail would let them believe they
+ * were looking at everything the transform said.
+ */
+function withFinalLogs(error, logs) {
+    if (logs.length === 0)
+        return error;
+    const tail = logs
+        .slice(-FAILURE_LOG_LINES)
+        .map((line) => line.length > FAILURE_LOG_CHARS ? `${line.slice(0, FAILURE_LOG_CHARS)}…` : line);
+    const heading = logs.length > tail.length
+        ? `The last ${tail.length} of ${logs.length} lines it logged first:`
+        : `${tail.length === 1 ? 'The line' : `The ${tail.length} lines`} it logged first:`;
+    return `${error}\n${heading}\n${tail.map((line) => `  ${line}`).join('\n')}`;
+}
 /**
  * The JavaScript and TypeScript harness.
  *
  * `console.log` is captured rather than left on stdout so user code cannot
  * corrupt the single JSON line this prints — a transform that logs a `{` would
  * otherwise break its own result parsing, which is a maddening thing to debug.
+ *
+ * Every console channel that reaches a terminal is overridden, not just the four
+ * that were here first. `console.debug` writes to stdout exactly as `console.log`
+ * does, so leaving it alone left one spelling of "log something" that silently
+ * corrupted the result line; `console.trace` writes to stderr, so leaving it
+ * alone left one spelling that silently went nowhere. Both are the same mistake
+ * the Python harness made with `print`, and there is no reading of "anything the
+ * code logged" under which they are not it.
+ *
+ * The channels share one array and keep call order, which is the only ordering
+ * that answers the question logs are read for — what happened, and in what
+ * sequence. Nothing marks which channel a line came from: a reader looking at a
+ * failed run wants the sequence, and splitting it into two lists would make the
+ * interleaving unrecoverable to buy a label the line's own text usually carries.
+ *
+ * Bounded by {@link MAX_LOG_LINES} and {@link MAX_LOG_LINE_CHARS}, applied here
+ * rather than after the fact, so a transform that logs a copy of its input never
+ * gets as far as being serialised.
  */
 function javascriptHarness(code) {
     return `
 const logs = [];
-const write = (...args) => logs.push(args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "));
+let dropped = 0;
+const keep = (line) => {
+  if (logs.length >= ${MAX_LOG_LINES}) { dropped += 1; return; }
+  logs.push(
+    line.length > ${MAX_LOG_LINE_CHARS}
+      ? line.slice(0, ${MAX_LOG_LINE_CHARS}) + "… (" + (line.length - ${MAX_LOG_LINE_CHARS}) + " more characters)"
+      : line,
+  );
+};
+const write = (...args) => keep(args.map(a => typeof a === "string" ? a : JSON.stringify(a)).join(" "));
 console.log = write; console.info = write; console.warn = write; console.error = write;
+console.debug = write; console.trace = write;
+const captured = () => dropped === 0
+  ? logs
+  : logs.concat(["… " + dropped + " more line(s) were logged and dropped: a transform keeps its first ${MAX_LOG_LINES}."]);
 
 let input = "";
 process.stdin.setEncoding("utf8");
@@ -225,11 +327,11 @@ try {
   const records = JSON.parse(input || "[]");
   const transform = async (records) => { ${code} };
   const rows = await transform(records);
-  process.stdout.write(JSON.stringify({ rows: rows ?? [], logs }));
+  process.stdout.write(JSON.stringify({ rows: rows ?? [], logs: captured() }));
 } catch (error) {
   process.stdout.write(JSON.stringify({
     error: error instanceof Error ? \`\${error.name}: \${error.message}\` : String(error),
-    logs,
+    logs: captured(),
   }));
 }
 `;
@@ -241,6 +343,44 @@ try {
  * that reaches for pandas will naturally end with one — making it write
  * `.to_dict("records")` would be a papercut on the only path pandas is worth
  * importing for.
+ *
+ * **`print` is redirected, for the same reason `console.log` is.** It used to go
+ * straight through to the child's real stdout, where the last-line result parse
+ * discarded it — so the single most obvious thing a person writes while working
+ * out what their transform is doing produced an empty log panel and no
+ * explanation. That is not a missing nicety: it costs the author their trust in
+ * the runner before they have written anything real, and the conclusion it
+ * invites ("my code never ran") is the wrong one. `log()` still exists, because
+ * transforms in the wild call it and a `NameError` is a worse answer than a
+ * redundant helper, but it is now literally `print` — one buffer, one ordering,
+ * and nothing that only works if you already knew about it.
+ *
+ * **stderr is captured too**, into the same list and in call order. `warnings`,
+ * a `logging` handler at its default configuration, and a traceback the code
+ * printed itself all land there, and those are precisely the lines somebody is
+ * looking for when a transform misbehaves. It is not marked as stderr, matching
+ * the JavaScript harness, which does not distinguish `console.error` either: the
+ * sequence is what a reader is reconstructing, and two lists would make the
+ * interleaving unrecoverable.
+ *
+ * What was written **before** an exception survives it. The redirect is a
+ * context manager around the call rather than a swap held for the whole script,
+ * so it unwinds on the way out of a traceback with the buffer intact, and the
+ * error branch reports the same lines the success branch would have. A
+ * transform that printed three things and then divided by zero is the case logs
+ * matter most for, and it is the case a naive swap loses.
+ *
+ * Bounded by {@link MAX_LOG_LINES} and {@link MAX_LOG_LINE_CHARS}, the same two
+ * numbers the JavaScript harness applies. Note that this bounds the *sink*, not
+ * only the result: an unterminated write longer than a line's ceiling is flushed
+ * as its own line rather than accumulated, so a transform writing without
+ * newlines cannot grow the child's memory either.
+ *
+ * The limit worth stating: this redirects Python-level writes to `sys.stdout`
+ * and `sys.stderr`. Output from a C extension or a subprocess that writes to the
+ * file descriptors underneath goes to the real streams, exactly as it does past
+ * an overridden `console` in Node. Redirecting the descriptors themselves would
+ * take the result channel with it.
  */
 function pythonHarness(code) {
     const indented = code
@@ -248,11 +388,68 @@ function pythonHarness(code) {
         .map((line) => `    ${line}`)
         .join('\n');
     return `
-import sys, json
+import sys, json, contextlib
 
 logs = []
+# A one-element list rather than a module global reassigned inside the helper,
+# so the counter needs no \`global\` statement in generated code.
+dropped = [0]
+
+def keep(line):
+    if len(logs) >= ${MAX_LOG_LINES}:
+        dropped[0] += 1
+        return
+    if len(line) > ${MAX_LOG_LINE_CHARS}:
+        line = "{}… ({} more characters)".format(
+            line[:${MAX_LOG_LINE_CHARS}], len(line) - ${MAX_LOG_LINE_CHARS}
+        )
+    logs.append(line)
+
+class Sink:
+    """Stands in for stdout and stderr while the transform runs.
+
+    Line-buffered by hand because \`print("a", "b")\` arrives as four separate
+    writes — the parts, the separators and the terminator — and appending each
+    one as its own entry would shred every multi-argument call.
+    """
+
+    def __init__(self):
+        self.partial = ""
+
+    def write(self, text):
+        if not isinstance(text, str):
+            text = str(text)
+        self.partial += text
+        while "\\n" in self.partial:
+            line, self.partial = self.partial.split("\\n", 1)
+            keep(line)
+        # A write with no newline in it is still bounded: past a line's ceiling
+        # there is nothing more to keep, so it is emitted rather than held.
+        if len(self.partial) > ${MAX_LOG_LINE_CHARS}:
+            keep(self.partial)
+            self.partial = ""
+        return len(text)
+
+    def writelines(self, lines):
+        for line in lines:
+            self.write(line)
+
+    def flush(self):
+        pass
+
+    def isatty(self):
+        return False
+
+    def drain(self):
+        """Whatever was written without a trailing newline is still output."""
+        if self.partial:
+            keep(self.partial)
+            self.partial = ""
+
+sink = Sink()
+
 def log(*args):
-    logs.append(" ".join(str(a) for a in args))
+    print(*args)
 
 def transform(records):
 ${indented || '    return records'}
@@ -266,15 +463,31 @@ def to_rows(result):
         return result.to_dict("records")
     return result
 
+def captured():
+    sink.drain()
+    if dropped[0] == 0:
+        return logs
+    return logs + [
+        "… {} more line(s) were logged and dropped: a transform keeps its first {}.".format(
+            dropped[0], ${MAX_LOG_LINES}
+        )
+    ]
+
 try:
     raw = sys.stdin.read()
     records = json.loads(raw) if raw.strip() else []
-    rows = to_rows(transform(records))
-    sys.stdout.write(json.dumps(rows and {"rows": rows, "logs": logs} or {"rows": [], "logs": logs}, default=str))
+    # \`to_rows\` is inside the redirect as well: a lazily-evaluated return value
+    # does its printing here, not before.
+    with contextlib.redirect_stdout(sink), contextlib.redirect_stderr(sink):
+        rows = to_rows(transform(records))
+    # Back on the real stdout by now — the context manager restores on the way
+    # out, including out of an exception — so this is the only thing on it.
+    out = captured()
+    sys.stdout.write(json.dumps(rows and {"rows": rows, "logs": out} or {"rows": [], "logs": out}, default=str))
 except Exception as error:
     sys.stdout.write(json.dumps({
         "error": "{}: {}".format(type(error).__name__, error),
-        "logs": logs,
+        "logs": captured(),
     }))
 `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-catalog",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A metadata registry for NestJS: object types, properties and relations, derived from your ORM and enriched with decorators.",
   "license": "MIT",
   "author": "Davide Carvalho",