@cat-factory/cli 0.10.5 → 0.12.0

package/dist/k3s-handler.js

@@ -1,32 +1,39 @@
+import { ingressHostTemplate, ingressUrlPort } from './k3s-ingress.js';
 import {} from './k3s-provision.js';
 /**
  * The secret-bundle key the Kubernetes env backend reads the ServiceAccount token from. Mirrors
- * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY` — kept inline so the CLI stays free of a
+ * the contracts constant `KUBERNETES_ENV_TOKEN_SECRET_KEY`, kept inline so the CLI stays free of a
  * backend/contract RUNTIME dependency (the unit test validates the built handler against the real
  * `registerEnvironmentHandlerSchema`, so any drift from the contract fails a test).
  */
 export const KUBERNETES_ENV_TOKEN_SECRET_KEY = 'apiToken';
 /** Default per-PR namespace name template written into the handler (rendered with the PR number). */
 export const DEFAULT_NAMESPACE_TEMPLATE = 'cf-env-{{pullNumber}}';
-/**
- * Default ingress host template. `nip.io` is a wildcard DNS service that resolves
- * `<anything>.127.0.0.1.nip.io` to loopback with no local DNS setup, so a per-branch env URL works
- * against a local k3s/k3d/kind ingress out of the box.
- */
-export const DEFAULT_INGRESS_HOST_TEMPLATE = '{{branch}}.127.0.0.1.nip.io';
 /** Human label for the auto-provisioned connection (names the created cluster when there is one). */
 export function handlerLabel(connection) {
     return connection.clusterName ? `Local k3s (${connection.clusterName})` : 'Local k3s';
 }
 /**
- * Build the `local-k3s` infra handler registration input from a provisioned connection. The minted
- * ServiceAccount token rides ONLY in the write-only `secrets` bundle (never in the config, never in
- * the deep-link). Everything else — the loopback apiserver URL, the skip-TLS flag (a local k3s
- * apiserver self-signs its cert), the per-PR namespace + nip.io ingress host defaults — is
- * non-secret config. The result is exactly what the Settings → Infrastructure → Local k3s form's
- * Test/Save posts, so the guided flow reuses the #557 probe + registration unchanged.
+ * Build the `local-k3s` infra handler registration input from a provisioned connection, or `null`
+ * when there is nothing honest to register. The minted ServiceAccount token rides ONLY in the
+ * write-only `secrets` bundle (never in the config, never in the deep-link). Everything else (the
+ * loopback apiserver URL, the skip-TLS flag for a self-signed local apiserver, the per-PR namespace
+ * and the nip.io ingress host) is non-secret config. The result is exactly what the
+ * Settings → Infrastructure → Local k3s form's Test/Save posts, so the guided flow reuses the #557
+ * probe + registration unchanged.
+ *
+ * `null` is the whole point of the return type. The contract REQUIRES a `url` source, and
+ * `ingressTemplate` is the only one the CLI can fill on its own (the status-backed sources name a
+ * Service or Ingress that belongs to the operator's manifests), so a cluster whose ingress path the
+ * probe did not establish has no handler to build: filling the host template in anyway is how the
+ * unserved URL got saved. It used to fall back to the literal template, which was worse than stale
+ * on a `--ingress-port 8080` run, naming a port that run had not even asked for.
  */
 export function buildK3sHandler(connection) {
+    const hostTemplate = ingressHostTemplate(connection.ingress);
+    if (hostTemplate === null)
+        return null;
+    const port = ingressUrlPort(connection.ingress);
     return {
         provisionType: 'kubernetes',
         config: {
@@ -36,29 +43,50 @@ export function buildK3sHandler(connection) {
                 apiServerUrl: connection.apiServerUrl,
                 insecureSkipTlsVerify: true,
                 namespaceTemplate: DEFAULT_NAMESPACE_TEMPLATE,
-                url: { source: 'ingressTemplate', hostTemplate: DEFAULT_INGRESS_HOST_TEMPLATE },
+                url: {
+                    source: 'ingressTemplate',
+                    hostTemplate,
+                    ...(port === null ? {} : { port }),
+                    // A local ingress controller serves TLS with a self-signed certificate, so the derived
+                    // environment URL is plain HTTP: the derivation's own default is `https`, which would
+                    // hand the tester a URL that fails on the certificate rather than on the connection.
+                    scheme: 'http',
+                },
             },
         },
         secrets: { [KUBERNETES_ENV_TOKEN_SECRET_KEY]: connection.apiToken },
     };
 }
 /**
- * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the handler's
- * NON-SECRET fields. The ServiceAccount token is deliberately omitted — a secret in a URL would
- * leak into browser history / server logs — so the user pastes it (printed once to the terminal)
- * before running Test → Save. Slice 4 teaches the SPA to read these params; until then the link
- * simply opens the app. Param names mirror the connect form's fields.
+ * Build the deep-link that opens the SPA's Local k3s connect form pre-filled with the connection's
+ * NON-SECRET fields. The ServiceAccount token is deliberately omitted (a secret in a URL would leak
+ * into browser history / server logs), so the user pastes it (printed once to the terminal) before
+ * running Test → Save. Param names mirror the connect form's fields.
+ *
+ * The URL params are prefilled ONLY when the ingress probe established that the cluster can serve
+ * them, and that is read off the CONNECTION rather than passed in: the withholding used to ride an
+ * `{ ingressVerified }` option DEFAULTED to true, so every caller that forgot it (the integration
+ * spec among them) re-established the promise this exists to remove. The connect form treats the
+ * host template as required for an `ingressTemplate` source, so an operator whose cluster has no
+ * ingress path cannot save a URL nothing answers, and the printed summary tells them what to fix or
+ * which source to pick instead.
  */
-export function buildK3sSetupUrl(spaBaseUrl, handler) {
-    const k = handler.config.kubernetes;
+export function buildK3sSetupUrl(spaBaseUrl, connection) {
     const url = new URL(spaBaseUrl);
     const params = url.searchParams;
     params.set('infraSetup', 'local-k3s');
-    params.set('label', k.label);
-    params.set('apiServerUrl', k.apiServerUrl);
-    params.set('namespaceTemplate', k.namespaceTemplate);
-    params.set('hostTemplate', k.url.hostTemplate);
-    if (k.insecureSkipTlsVerify)
+    params.set('label', handlerLabel(connection));
+    params.set('apiServerUrl', connection.apiServerUrl);
+    params.set('namespaceTemplate', DEFAULT_NAMESPACE_TEMPLATE);
+    const handler = buildK3sHandler(connection);
+    if (handler) {
+        const k = handler.config.kubernetes.url;
+        params.set('hostTemplate', k.hostTemplate);
+        params.set('scheme', k.scheme);
+        if (k.port !== undefined)
+            params.set('ingressPort', String(k.port));
+    }
+    if (connection.insecureSkipTlsVerify)
         params.set('insecureSkipTlsVerify', '1');
     return url.toString();
 }

package/dist/k3s-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"k3s-handler.js","sourceRoot":"","sources":["../src/k3s-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,MAAM,oBAAoB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAU,CAAA;AAEzD,qGAAqG;AACrG,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAA;AAEjE;;;;GAIG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,6BAA6B,CAAA;AAuB1E,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,UAA8B;IACzD,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,UAAU,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,WAAW,CAAA;AACvF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAAC,UAA8B;IAC5D,OAAO;QACL,aAAa,EAAE,YAAY;QAC3B,MAAM,EAAE;YACN,MAAM,EAAE,WAAW;YACnB,UAAU,EAAE;gBACV,KAAK,EAAE,YAAY,CAAC,UAAU,CAAC;gBAC/B,YAAY,EAAE,UAAU,CAAC,YAAY;gBACrC,qBAAqB,EAAE,IAAI;gBAC3B,iBAAiB,EAAE,0BAA0B;gBAC7C,GAAG,EAAE,EAAE,MAAM,EAAE,iBAAiB,EAAE,YAAY,EAAE,6BAA6B,EAAE;aAChF;SACF;QACD,OAAO,EAAE,EAAE,CAAC,+BAA+B,CAAC,EAAE,UAAU,CAAC,QAAQ,EAAE;KACpE,CAAA;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,OAAwB;IAC3E,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAA;IACnC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAA;IAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAA;IAC/B,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IACrC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAA;IAC5B,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,YAAY,CAAC,CAAA;IAC1C,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,CAAC,CAAC,iBAAiB,CAAC,CAAA;IACpD,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAA;IAC9C,IAAI,CAAC,CAAC,qBAAqB;QAAE,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAA;IACrE,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAA;AACvB,CAAC"}
+{"version":3,"file":"k3s-handler.js","sourceRoot":"","sources":["../src/k3s-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAA2B,MAAM,oBAAoB,CAAA;AAE5D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,UAAU,CAAA;AAEzD,qGAAqG;AACrG,MAAM,CAAC,MAAM,0BAA0B,GAAG,uBAAuB,CAAA;AA2BjE,qGAAqG;AACrG,MAAM,UAAU,YAAY,CAAC,UAA8B;IACzD,OAAO,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,cAAc,UAAU,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,WAAW,CAAA;AACvF,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAAC,UAA8B;IAC5D,MAAM,YAAY,GAAG,mBAAmB,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;IAC5D,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,IAAI,CAAA;IACtC,MAAM,IAAI,GAAG,cAAc,CAAC,UAAU,CAAC,OAAO,CAAC,CAAA;IAC/C,OAAO;QACL,aAAa,EAAE,YAAY;QAC3B,MAAM,EAAE;YACN,MAAM,EAAE,WAAW;YACnB,UAAU,EAAE;gBACV,KAAK,EAAE,YAAY,CAAC,UAAU,CAAC;gBAC/B,YAAY,EAAE,UAAU,CAAC,YAAY;gBACrC,qBAAqB,EAAE,IAAI;gBAC3B,iBAAiB,EAAE,0BAA0B;gBAC7C,GAAG,EAAE;oBACH,MAAM,EAAE,iBAAiB;oBACzB,YAAY;oBACZ,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;oBAClC,uFAAuF;oBACvF,sFAAsF;oBACtF,qFAAqF;oBACrF,MAAM,EAAE,MAAM;iBACf;aACF;SACF;QACD,OAAO,EAAE,EAAE,CAAC,+BAA+B,CAAC,EAAE,UAAU,CAAC,QAAQ,EAAE;KACpE,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,UAA8B;IACjF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,CAAA;IAC/B,MAAM,MAAM,GAAG,GAAG,CAAC,YAAY,CAAA;IAC/B,MAAM,CAAC,GAAG,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IACrC,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC,CAAA;IAC7C,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,UAAU,CAAC,YAAY,CAAC,CAAA;IACnD,MAAM,CAAC,GAAG,CAAC,mBAAmB,EAAE,0BAA0B,CAAC,CAAA;IAC3D,MAAM,OAAO,GAAG,eAAe,CAAC,UAAU,CAAC,CAAA;IAC3C,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAA;QACvC,MAAM,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC,YAAY,CAAC,CAAA;QAC1C,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC,CAAA;QAC9B,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;IACrE,CAAC;IACD,IAAI,UAAU,CAAC,qBAAqB;QAAE,MAAM,CAAC,GAAG,CAAC,uBAAuB,EAAE,GAAG,CAAC,CAAA;IAC9E,OAAO,GAAG,CAAC,QAAQ,EAAE,CAAA;AACvB,CAAC"}

package/dist/k3s-ingress.d.ts

@@ -0,0 +1,259 @@
+import { type Command, type HostShell, type ShellResult } from './host-shell.js';
+/**
+ * Whether an environment URL derived from an ingress HOST TEMPLATE can actually be served, which
+ * takes two independent things and not one:
+ *
+ *   1. an ingress CONTROLLER inside the cluster (an `IngressClass` is its observable trace), and
+ *   2. a HOST PORT published into it, because every local distribution runs the cluster inside
+ *      Docker and forwards only the ports it was asked for at create time.
+ *
+ * Both were previously assumed. `cat-factory k3s` printed `{{branch}}.127.0.0.1.nip.io` as wired
+ * on every path, including a reused cluster it had never looked at, and the failure landed at the
+ * `tester` step against a URL that answered nothing: environment readiness is WORKLOAD readiness,
+ * so provisioning still reported success.
+ */
+/**
+ * Default host port published into the ingress controller's plain-HTTP entrypoint.
+ *
+ * ONE port is published and it maps to the controller's plain-HTTP entrypoint, so `http` is the
+ * scheme that port serves and the only one the CLI can claim. Publishing the TLS entrypoint
+ * instead would trade a connection error for a CERTIFICATE error, because a local ingress
+ * controller serves a self-signed default cert: a worse version of the failure this module exists
+ * to remove, since it surfaces at the tester rather than here.
+ */
+export declare const DEFAULT_INGRESS_PORT = 80;
+/**
+ * The host the rendered template resolves to. `nip.io` is wildcard DNS that maps
+ * `<anything>.127.0.0.1.nip.io` to loopback with no local DNS setup, so the port probe below
+ * targets loopback directly rather than resolving a sample hostname.
+ */
+export declare const INGRESS_PROBE_HOST = "127.0.0.1";
+/**
+ * The ingress HOST template, with no port in it. It is deliberately portless: the rendered value
+ * is also the Ingress `spec.rules[].host` a service's manifests declare, and Kubernetes rejects a
+ * `host` carrying a port. A non-default host port travels as the URL source's own `port` field
+ * instead (see {@link ingressUrlPort}).
+ */
+export declare const INGRESS_HOST_TEMPLATE = "{{branch}}.127.0.0.1.nip.io";
+/** The container port an ingress controller serves plain HTTP on (Traefik `web`, nginx `http`). */
+export declare const INGRESS_CONTAINER_HTTP_PORT = 80;
+/** What a TCP connect attempt established. `unknown` is NOT `closed`: see {@link classifyIngress}. */
+export type PortState = 'open' | 'closed' | 'unknown';
+/** Which half of the ingress path is missing. Two halves, two different fixes. */
+export type IngressGap = 'controller' | 'hostPort';
+/**
+ * WHY a probe could not answer. Four causes that need four different things done about them, kept
+ * apart rather than folded into one "could not read the cluster": telling an operator with no
+ * `kubectl` on PATH to "re-run once the cluster has settled" is advice for a problem they do not
+ * have.
+ */
+export type IngressProbeCause = 'kubectl-missing' | 'cluster-unreachable' | 'cluster-refused' | 'unparseable' | 'host-port-filtered';
+/**
+ * What established that the answering host port belongs to THIS cluster.
+ *
+ * A TCP connect proves only that something listens: an unrelated web server on port 80 answers it
+ * exactly as an ingress controller does, which is how a cluster with no published port could be
+ * reported as ready. `cluster` means the container runtime confirmed the cluster publishes its
+ * controller entrypoint on that host port; `unattributed` means the port answers and the check
+ * could not run, which the summary says out loud rather than claiming the stronger fact.
+ */
+export type PortAttribution = 'cluster' | 'unattributed';
+/**
+ * The three-state verdict. `unknown` is its own state rather than folded into `missing` for the
+ * reason the acceptance suite's `preflight.ts` states: a probe that could not read an answer has
+ * not established the negative either, and reporting one as the other sends an operator to fix a
+ * cluster that was fine.
+ */
+export type IngressReadiness = {
+    status: 'ready';
+    port: number;
+    controller: string;
+    attribution: PortAttribution;
+} | {
+    status: 'missing';
+    port: number;
+    gaps: readonly IngressGap[];
+    /**
+     * The host port the cluster DOES publish its controller on, when the runtime reported one
+     * that is not the requested port. It turns "nothing serves 8080" into "the cluster serves
+     * 18080", which is a different (and much shorter) fix.
+     */
+    publishedOn?: number;
+} | {
+    status: 'unknown';
+    port: number;
+    cause: IngressProbeCause;
+    probeFailure: string;
+};
+/**
+ * The outcome of reading the cluster's `IngressClass` list: the names, or the CAUSE that stopped
+ * it. A bare `null` for "no answer" is what collapsed a missing binary, an unreachable apiserver,
+ * an RBAC refusal and a garbled payload into one message.
+ */
+export type IngressClassRead = {
+    ok: true;
+    controllers: readonly string[];
+} | {
+    ok: false;
+    cause: IngressProbeCause;
+    detail: string;
+};
+/** Whether the cluster publishes its controller entrypoint on the host, and where. */
+export type PortPublication = {
+    checked: true;
+    hostPorts: readonly number[];
+}
+/** The check could not run (no such container, no Docker, not a Docker-hosted cluster). */
+ | {
+    checked: false;
+};
+/** The raw facts {@link classifyIngress} reduces. Kept as plain data so the reduction is pure. */
+export interface IngressFacts {
+    port: number;
+    classes: IngressClassRead;
+    hostPort: PortState;
+    publication: PortPublication;
+}
+/** `kubectl get ingressclass -o json`, targeting `context` when one is supplied. */
+export declare function listIngressClassesCommand(context?: string): Command;
+/**
+ * `docker port <cluster container>`: every host port the cluster's own container forwards. This is
+ * the ONLY check that attributes an answering host port to the cluster rather than to whatever
+ * else may be bound there, and it is the same one used by hand to establish that a default k3d
+ * create publishes nothing but the apiserver.
+ *
+ * The container is the one each distribution puts the forward on: k3d's load balancer, kind's
+ * control-plane node. The whole table is asked for rather than one port, because a container that
+ * forwards NOTHING answers that with an empty success, where naming the port makes the same
+ * cluster fail exactly as an unknown container does.
+ */
+export declare function publishedPortsCommand(runtime: 'k3d' | 'kind', clusterName: string): Command;
+/**
+ * Host ports mapped to the ingress container port, out of `docker port` output
+ * (`80/tcp -> 0.0.0.0:18080`, one mapping per line). Reads the text after the LAST colon so an
+ * IPv6 bind address (`[::]:18080`) does not parse as the port.
+ */
+export declare function parsePublishedHostPorts(stdout: string): number[];
+/**
+ * Controller names out of a `kubectl get ingressclass -o json` payload (an `items` list).
+ * Returns `null` for anything unparseable, which the reduction reports as `unknown` rather than
+ * as an absent controller.
+ */
+export declare function parseIngressClasses(stdout: string): string[] | null;
+/**
+ * Turn the `kubectl get ingressclass` result into a read outcome that NAMES its cause.
+ *
+ * The shell already distinguishes a missing binary from a watchdog kill from a real non-zero
+ * exit, and the exit carries the apiserver's own words (an RBAC refusal, a bad context). Throwing
+ * that away and reporting "could not read the cluster's IngressClasses" is the degrade-quietly
+ * failure: four fixes, one message, and a remedy that fits none of them.
+ */
+export declare function readIngressClasses(result: ShellResult): IngressClassRead;
+/**
+ * Reduce the probed facts to one verdict.
+ *
+ * An UNREADABLE cluster is `unknown` outright: with no controller list, neither half is settled.
+ * An EMPTY list is a definitive `missing`, even when the port probe could not tell, because a
+ * cluster with no ingress controller cannot serve the URL whatever the host port does.
+ *
+ * The PUBLICATION check outranks the socket on the port half, in both directions: a runtime that
+ * reports the cluster forwarding no such host port makes an answering socket somebody ELSE'S
+ * listener (the case that used to read as ready), and one that reports the forward makes an
+ * answering socket attributable to the cluster rather than merely coincident with it.
+ */
+export declare function classifyIngress(facts: IngressFacts): IngressReadiness;
+/** Context the remedy lines are rendered from, so each names the operator's actual cluster. */
+export interface IngressRemedyContext {
+    /** The distribution behind the cluster when it is known: it changes the CONTROLLER remedy. */
+    runtime?: 'k3d' | 'kind';
+    /**
+     * The command that rebuilds the cluster with the port published, when there IS one to give.
+     *
+     * Absent means no recreate line is printed at all, and that case is real: on the reuse path the
+     * cluster may be one this CLI cannot name (a bare k3s service, a shared context), and
+     * `--recreate` only ever targets a k3d/kind cluster it can name. Printing it anyway produced a
+     * command the CLI itself refuses, which is worse than printing none.
+     */
+    recreateCommand?: string;
+}
+/**
+ * The remedy for each gap, rendered from what the probe just read.
+ *
+ * A missing HOST PORT has exactly one fix on every local distribution: neither k3d's `-p` nor
+ * kind's `extraPortMappings` can be added to a cluster that already exists, so the cluster has to
+ * be built again. That is why a recreate is named here rather than a `docker` incantation that
+ * does not work.
+ */
+export declare function ingressRemedies(readiness: IngressReadiness, context?: IngressRemedyContext): string[];
+/**
+ * The `hostTemplate` an `ingressTemplate` URL source should carry for a verified ingress, or
+ * `null` when the ingress was not established.
+ *
+ * Always PORTLESS. The rendered value is the Ingress `host` a service's manifests declare, and
+ * Kubernetes rejects a `host` with a port in it, so a non-default port travels as the URL source's
+ * own `port` field ({@link ingressUrlPort}) instead of being smuggled into the host string.
+ */
+export declare function ingressHostTemplate(readiness: Extract<IngressReadiness, {
+    status: 'ready';
+}>): string;
+export declare function ingressHostTemplate(readiness: IngressReadiness): string | null;
+/**
+ * The `port` an `ingressTemplate` URL source should carry: the verified host port when it is not
+ * the scheme's default, else `null` (the derivation composes `scheme://host` with no port).
+ */
+export declare function ingressUrlPort(readiness: IngressReadiness): number | null;
+/**
+ * TCP reachability seam, the sibling of {@link HostShell}: the ingress half that no `kubectl`
+ * command can answer is whether the HOST forwards a port into the cluster.
+ */
+export interface TcpProbe {
+    /** Never rejects: an unreachable port is a {@link PortState}, not an exception. */
+    probe(host: string, port: number, timeoutMs: number): Promise<PortState>;
+}
+/**
+ * The real, socket-backed probe.
+ *
+ * `ECONNREFUSED` is the one error that settles the negative: something answered the SYN with a
+ * reset, so nothing is listening. A timeout or any other error leaves it undecided (a firewall
+ * drops packets silently), and the reduction above keeps that distinct.
+ */
+export declare function createNodeTcpProbe(): TcpProbe;
+/** Injectable dependencies for {@link probeIngress}. */
+export interface IngressProbeDeps {
+    shell: HostShell;
+    tcp: TcpProbe;
+    /** Delay between attempts (real setTimeout; a no-op in tests). */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * The clock the wait is measured against (default `Date.now`). Injected because the budget is
+     * WALL CLOCK: charging only the sleeps let each attempt's own cost (a 2s port timeout plus a 5s
+     * apiserver request) ride for free, so a documented 90s wait ran for minutes.
+     */
+    now?: () => number;
+}
+/** How long a freshly created cluster is given to bring its bundled controller up. */
+export declare const INGRESS_SETTLE_WAIT_MS = 90000;
+/** Which cluster the publication check reads, when the CLI can name one. */
+export interface IngressProbeCluster {
+    runtime: 'k3d' | 'kind';
+    clusterName: string;
+}
+/**
+ * Probe every half and reduce, retrying while `waitMs` of WALL CLOCK remains.
+ *
+ * The wait exists because a k3d cluster's bundled Traefik is installed by a Job that completes
+ * ~20-30s AFTER `k3d cluster create` returns: probing once, immediately, would report a
+ * definitive `missing` for a cluster that is merely still starting, which is the same class of
+ * lie as the promise this replaces. A settled cluster answers on the first attempt, so the wait
+ * costs nothing on the reuse path, where callers pass 0.
+ *
+ * The budget covers the attempts as well as the gaps between them, so a run whose every probe is
+ * slow gives up on time rather than multiplying the deadline by the cost of an attempt.
+ */
+export declare function probeIngress(deps: IngressProbeDeps, options: {
+    context?: string;
+    port: number;
+    waitMs?: number;
+    cluster?: IngressProbeCluster;
+}): Promise<IngressReadiness>;
+//# sourceMappingURL=k3s-ingress.d.ts.map

package/dist/k3s-ingress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3s-ingress.d.ts","sourceRoot":"","sources":["../src/k3s-ingress.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,OAAO,EACZ,KAAK,SAAS,EAEd,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAA;AAExB;;;;;;;;;;;;GAYG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,cAAc,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,gCAAgC,CAAA;AAElE,mGAAmG;AACnG,eAAO,MAAM,2BAA2B,KAAK,CAAA;AAE7C,sGAAsG;AACtG,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAA;AAErD,kFAAkF;AAClF,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,UAAU,CAAA;AAElD;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB,iBAAiB,GACjB,qBAAqB,GACrB,iBAAiB,GACjB,aAAa,GACb,oBAAoB,CAAA;AAExB;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,cAAc,CAAA;AAExD;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,eAAe,CAAA;CAAE,GACnF;IACE,MAAM,EAAE,SAAS,CAAA;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,SAAS,UAAU,EAAE,CAAA;IAC3B;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB,GACD;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvF;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAE3D,sFAAsF;AACtF,MAAM,MAAM,eAAe,GACvB;IAAE,OAAO,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE;AACjD,2FAA2F;GACzF;IAAE,OAAO,EAAE,KAAK,CAAA;CAAE,CAAA;AAEtB,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,gBAAgB,CAAA;IACzB,QAAQ,EAAE,SAAS,CAAA;IACnB,WAAW,EAAE,eAAe,CAAA;CAC7B;AAMD,oFAAoF;AACpF,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,KAAK,GAAG,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAI3F;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAShE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAgBnE;AAWD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,gBAAgB,CA+BxE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,gBAAgB,CAuCrE;AAED,+FAA+F;AAC/F,MAAM,WAAW,oBAAoB;IACnC,8FAA8F;IAC9F,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,gBAAgB,EAC3B,OAAO,GAAE,oBAAyB,GACjC,MAAM,EAAE,CA6BV;AA6CD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,OAAO,CAAC,gBAAgB,EAAE;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,CAAC,GACxD,MAAM,CAAA;AACT,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAAA;AAK/E;;;GAGG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,gBAAgB,GAAG,MAAM,GAAG,IAAI,CAGzE;AAMD;;;GAGG;AACH,MAAM,WAAW,QAAQ;IACvB,mFAAmF;IACnF,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;CACzE;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,IAAI,QAAQ,CAqB7C;AAED,wDAAwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,SAAS,CAAA;IAChB,GAAG,EAAE,QAAQ,CAAA;IACb,kEAAkE;IAClE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,QAAS,CAAA;AAM5C,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,GAAG,MAAM,CAAA;IACvB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,mBAAmB,CAAA;CAAE,GAC1F,OAAO,CAAC,gBAAgB,CAAC,CAmB3B"}