@fjall/util 12.2.0 → 12.3.0

package/dist/.build-source-hash

@@ -9,7 +9,7 @@
     "package.json",
     "tsconfig.json"
   ],
-  "hash": "3fd0e9f62624556a06f527609beda6b85a29454c95eca244fda37f23e73c52de",
+  "hash": "6bdd5fed222c37914a9331fbb1fa99dce21a102ed9159de858b1b27ae44fc62b",
   "files": {
     "src/async/concurrency.ts": "3c7ebe0222a720f9",
     "src/async/singleton.ts": "7bcc21b0fb920561",
@@ -35,6 +35,8 @@
     "src/deploy/approvalTokenOutput.ts": "4be7b52825d88a37",
     "src/devSubstrate/entrypoint.ts": "0526b88258174aa6",
     "src/devSubstrate/params.ts": "43bf902b57eb9edd",
+    "src/diagnostics/controlSequences.ts": "cb1cc3f29f041371",
+    "src/diagnostics/index.ts": "249d04cb4dd7db35",
     "src/docker/DockerCli.build.ts": "93a74294437cc002",
     "src/docker/DockerCli.daemon.ts": "11b9c3352c957d7c",
     "src/docker/DockerCli.registry.ts": "f8dfcf1d7e413014",
@@ -59,6 +61,7 @@
     "src/docker/result.ts": "2ff0d59a3add8b06",
     "src/environments.ts": "b3d2f2493554cd0f",
     "src/errorUtils.ts": "c601f2905c74b8d0",
+    "src/errors/absence.ts": "390fea350ffbb4e5",
     "src/failure/deploymentFailure.ts": "5824db1d97d01838",
     "src/failure/extractErrorWindow.ts": "ca41f90946fa939c",
     "src/fsHelpers.ts": "0869d9739d523572",
@@ -107,9 +110,9 @@
     "src/securityHelpers.ts": "3f78606079c8f45e",
     "src/targets.ts": "126280f0a5762e21",
     "../scripts/minify-dist.mjs": "6b2e4b0df8aec601",
-    "package.json": "b23ba4269f90691a",
+    "package.json": "da4f5b3991378803",
     "tsconfig.json": "db759831ad95f396"
   },
-  "outputHash": "3fe4db92b87db80c477aee925dc178caae99fab66d37ae0e1d644d9aa6c4f0d6",
-  "outputFileCount": 197
+  "outputHash": "5d7079e0f38bcce1da6411693f11df940a142f138d4bfa6481553998cfaa1aab",
+  "outputFileCount": 203
 }

package/dist/.minified

@@ -1 +1 @@
-98 files minified at 2026-08-15T22:07:25.133Z
+101 files minified at 2026-08-16T01:19:29.355Z

package/dist/diagnostics/controlSequences.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Strip terminal control sequences from a warning message before it is
+ * masked: ESC-introduced ANSI sequences, C1-CSI-introduced sequences, and
+ * every remaining C0/DEL/C1 control character except \t, \n and \r.
+ * Strip BEFORE mask (F-R12): a control character inside a credential-shaped
+ * value splits the mask regex anchors, so masking must see stripped text.
+ */
+export declare function stripControlSequences(value: string): string;

package/dist/diagnostics/controlSequences.js

@@ -0,0 +1 @@
+var C=Object.defineProperty;var u=(e,E)=>C(e,"name",{value:E,configurable:!0});const c=/\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\(B/g,n=/\u009b[0-?]*[ -/]*[@-~]/g,r=/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;function x(e){return e.replace(c,"").replace(n,"").replace(r,"")}u(x,"stripControlSequences");export{x as stripControlSequences};

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Diagnostics spine — the one guaranteed lane for severity=warning
+ * diagnostics. Producers call {@link emitWarning}; the surface that owns the
+ * terminal end of the lane binds a {@link DiagnosticsSink} via
+ * {@link configureDiagnosticsSink}; screen-scoped consumers tap
+ * {@link subscribeWarnings} and replay via {@link consumeWarnings}; and
+ * {@link drainUnconsumed} is the end-of-session backstop that keeps a
+ * warning no surface ever consumed visible rather than silent.
+ *
+ * `consumed` means exactly "this event reached a user-visible surface":
+ * a rendering sink emitted it ({@link DiagnosticsSink.rendersToUser}), a
+ * scope-matched live subscriber received it, or a consuming read replayed
+ * it onto a screen. Nothing else sets the flag, so
+ * {@link drainUnconsumed} is a true complement — everything it returns
+ * was never shown anywhere, and everything shown is never reprinted.
+ *
+ * Masking is owned structurally: emitWarning strips control sequences THEN
+ * masks (F-R12 mechanised — no call-site ordering to get wrong), over the
+ * message AND every string value inside plain-object/array metadata. The
+ * buffer and every subscriber receive the same post-mask event object; the
+ * subscription taps after the mask, never before. Sinks declaring
+ * masksInternally receive the post-strip PRE-mask message and raw metadata
+ * because their own render path masks the whole tree (the agent
+ * renderEvent maskTree, the MCP emitter) — one mask per path, decided by
+ * the sink's declaration. Producers whose payloads are masked at
+ * construction by documented contract (e.g. StepOutput.warnings)
+ * double-mask idempotently — a benign overlap, named here so nobody
+ * deletes the construction masks: they also protect persistence surfaces
+ * this spine never sees.
+ *
+ * Scope binding is explicit (per-package scope constants), never ambient.
+ * AsyncLocalStorage was considered and rejected: ALS would give
+ * per-operation isolation without scope strings, but context propagation
+ * through Ink's React scheduler and AWS SDK callback chains is not
+ * async-hooks-reliable — scope binding would be silently wrong exactly
+ * where it matters. Explicit scope constants and subscriptions are
+ * inspectable.
+ *
+ * The confirm-style warn-and-wait lane (ProgressCallbacks.onWarning(message,
+ * proceedCallback)) is a consent flow, not a diagnostic — it must never be
+ * flattened onto this fire-and-forget spine.
+ */
+export { stripControlSequences } from "./controlSequences.js";
+export interface WarningEvent {
+    /**
+     * Warning text, stored and delivered post-strip+mask. Only a sink
+     * declaring masksInternally sees the post-strip pre-mask spelling.
+     */
+    message: string;
+    /**
+     * Per-package scope constant (diagnosticScopes.ts in each consumer) —
+     * free-form scope literals are forbidden in production code.
+     */
+    scope?: string;
+    code?: string;
+    /**
+     * Agent TOON operation spelling; the bound sink defaults it to the
+     * bound command path when absent. Producer-owned constant (a command
+     * path), never remote text — it bypasses the strip+mask, as does
+     * `code`.
+     */
+    operation?: string;
+    /**
+     * Spread into the agent TOON value by the agent sink. String values in
+     * plain objects/arrays are stripped+masked for the buffered/subscriber
+     * copy; non-plain objects pass through unprocessed and must therefore
+     * never carry sensitive text.
+     */
+    metadata?: Record<string, unknown>;
+}
+export interface DiagnosticsSink {
+    emit(event: WarningEvent): void;
+    /**
+     * true — the sink's render path masks (agent renderEvent maskTree, MCP
+     * emitter) and receives the post-strip PRE-mask message and raw
+     * metadata so credentials are masked exactly once. false — the sink
+     * renders verbatim and receives the post-mask event.
+     */
+    masksInternally: boolean;
+    /**
+     * true — emit() puts the event on a user-visible surface (stderr, the
+     * TOON stream, MCP frames), so emission marks it consumed and the
+     * end-of-session drain never reprints it. false — emit() renders
+     * nothing (the tui/mcp buffer-only defaults); the event stays
+     * unconsumed until a scope-matched subscriber, a consuming read, or
+     * the drain shows it.
+     */
+    rendersToUser: boolean;
+}
+/**
+ * Emit a warning onto the spine. Strips control sequences, masks, buffers
+ * the post-mask event, delivers it to the bound sink synchronously and to
+ * scope-matched subscribers on a microtask. The event is marked consumed
+ * only when a user-visible surface actually shows it: a rendering sink at
+ * emit, or a still-subscribed scope-matched listener at dispatch.
+ */
+export declare function emitWarning(message: string, opts?: Omit<WarningEvent, "message">): void;
+/**
+ * Bind the sink that owns warning rendering. Returns a restore function
+ * that reinstates the previously bound sink — guarded, so a stale restore
+ * (a surface torn down after a later rebind) never clobbers the newer
+ * binding.
+ */
+export declare function configureDiagnosticsSink(sink: DiagnosticsSink): () => void;
+export interface SubscribeWarningsOptions {
+    /**
+     * Deliver only events carrying exactly this scope. The declaration
+     * lives in the spine so delivery to a non-matching listener can never
+     * mark an event consumed — a foreign-scope event stays unconsumed for
+     * its own consumer or the drain. Omitted = every event, any scope.
+     */
+    scope?: string;
+}
+/**
+ * Subscribe to post-mask warning events (screen-scoped capture). Dispatch
+ * is microtask-deferred and scope-filtered by the spine. Returns
+ * unsubscribe.
+ */
+export declare function subscribeWarnings(listener: (event: WarningEvent) => void, options?: SubscribeWarningsOptions): () => void;
+/**
+ * Inspect the buffered warnings for one scope WITHOUT consuming them —
+ * tests and diagnostics only. A screen replaying onto a surface must use
+ * {@link consumeWarnings}, or the drain will reprint what it showed.
+ */
+export declare function readWarnings(scope: string): WarningEvent[];
+/**
+ * Read the buffered warnings for one scope onto a user-visible surface
+ * (replay-on-mount), marking them consumed. Events stay buffered so a
+ * remount replays the same set — {@link clearWarnings} at operation start
+ * deletes the shown ones.
+ */
+export declare function consumeWarnings(scope: string): WarningEvent[];
+/**
+ * Delete one scope's CONSUMED buffered warnings (call when an operation
+ * starts, so back-nav or re-run never re-shows a previous run's
+ * warnings). Never-shown events survive — they belong to the next replay
+ * (where showing them consumes them) or the end-of-session drain, so a
+ * clear can never destroy a warning nobody saw. Scoped only — the full
+ * clear is resetDiagnostics, and that is for tests.
+ */
+export declare function clearWarnings(scope: string): void;
+/**
+ * Return every buffered event no rendering sink, scope-matched
+ * subscriber, or consuming read ever showed, in emission order, marking
+ * them consumed — the end-of-session flush that keeps buffer-only modes
+ * honest. In rendering-sink modes every emission is consumed at emit, so
+ * a drain here is a no-op rather than a double-print.
+ */
+export declare function drainUnconsumed(): WarningEvent[];
+/** Tests only: drop all buffered events and subscribers, restore the default sink. */
+export declare function resetDiagnostics(): void;

package/dist/diagnostics/index.js

@@ -0,0 +1,2 @@
+var b=Object.defineProperty;var r=(e,t)=>b(e,"name",{value:t,configurable:!0});import{maskSensitiveOutput as g}from"../securityHelpers.js";import{stripControlSequences as y}from"./controlSequences.js";import{stripControlSequences as _}from"./controlSequences.js";const h=50,k=Symbol("fjall.diagnostics.unscoped"),o=new Map,f=new Set;let S=0;const x={masksInternally:!1,rendersToUser:!0,emit(e){process.stderr.write(`[warn] ${e.message}
+`)}};let i=x;function m(e){if(typeof e=="string")return g(y(e));if(Array.isArray(e))return e.map(m);if(e!==null&&typeof e=="object"){const t=Object.getPrototypeOf(e);if(t===Object.prototype||t===null)return Object.fromEntries(Object.entries(e).map(([n,s])=>[n,m(s)]))}return e}r(m,"maskMetadataValue");function E(e,t){const n=y(e),s={...t,...t?.metadata!==void 0&&{metadata:m(t.metadata)},message:g(n)},a={event:s,consumed:!1,seq:S++},l=s.scope??k;let c=o.get(l);c||(c=[],o.set(l,c)),c.push(a),c.length>h&&c.shift(),i.masksInternally?i.emit({...t,message:n}):i.emit(s),i.rendersToUser&&(a.consumed=!0);const d=[...f].filter(u=>u.scope===void 0||u.scope===s.scope);d.length>0&&queueMicrotask(()=>{const u=d.filter(p=>f.has(p));if(u.length!==0){a.consumed=!0;for(const{listener:p}of u)p(s)}})}r(E,"emitWarning");function C(e){const t=i;return i=e,()=>{i===e&&(i=t)}}r(C,"configureDiagnosticsSink");function U(e,t={}){const n={listener:e,scope:t.scope};return f.add(n),()=>{f.delete(n)}}r(U,"subscribeWarnings");function W(e){const t=o.get(e);return t?t.map(n=>n.event):[]}r(W,"readWarnings");function w(e){const t=o.get(e);return t?t.map(n=>(n.consumed=!0,n.event)):[]}r(w,"consumeWarnings");function P(e){const t=o.get(e);if(!t)return;const n=t.filter(s=>!s.consumed);n.length===0?o.delete(e):o.set(e,n)}r(P,"clearWarnings");function v(){const e=[];for(const t of o.values())for(const n of t)n.consumed||(n.consumed=!0,e.push(n));return e.sort((t,n)=>t.seq-n.seq).map(t=>t.event)}r(v,"drainUnconsumed");function A(){o.clear(),f.clear(),i=x,S=0}r(A,"resetDiagnostics");export{P as clearWarnings,C as configureDiagnosticsSink,w as consumeWarnings,v as drainUnconsumed,E as emitWarning,W as readWarnings,A as resetDiagnostics,_ as stripControlSequences,U as subscribeWarnings};

package/dist/errors/absence.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared absence vocabulary. Verified absence (the thing looked for is
+ * known not to exist) is a different outcome from failure-to-determine;
+ * consumers that branch on absence probe structurally with
+ * {@link isAbsence} instead of sniffing per-class spellings or message
+ * text.
+ */
+/**
+ * Discriminant literal for verified absence. Error classes spell absence
+ * as errorType "not_found"; wire codes derive from it via the
+ * PREFIX_${errorType.toUpperCase()} minting convention.
+ */
+export declare const NOT_FOUND = "not_found";
+/**
+ * Structural absence probe: errorType "not_found" (typed service errors)
+ * or statusCode 404 (API-boundary errors). Structural rather than
+ * instanceof — class names are presentation, not contract (dist
+ * minification has mangled them before), and the probe must hold across
+ * the cli/deploy-core package boundary.
+ */
+export declare function isAbsence(err: unknown): boolean;

package/dist/errors/absence.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var n=(t,e)=>o(t,"name",{value:e,configurable:!0});const s="not_found";function u(t){if(typeof t!="object"||t===null)return!1;const e=t;return e.errorType===s||e.statusCode===404}n(u,"isAbsence");export{s as NOT_FOUND,u as isAbsence};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjall/util",
-  "version": "12.2.0",
+  "version": "12.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fjall-tech/fjall.git",
@@ -102,6 +102,14 @@
     "./secrets": {
       "types": "./dist/secrets.d.ts",
       "default": "./dist/secrets.js"
+    },
+    "./diagnostics": {
+      "types": "./dist/diagnostics/index.d.ts",
+      "default": "./dist/diagnostics/index.js"
+    },
+    "./errors/absence": {
+      "types": "./dist/errors/absence.d.ts",
+      "default": "./dist/errors/absence.js"
     }
   },
   "files": [