@xplane/utils 0.0.0

package/dist/xr-watcher-EiWHVp3o.d.mts

@@ -0,0 +1,135 @@
+import { KubeConfig, KubernetesObject } from "@kubernetes/client-node";
+
+//#region src/watcher/types.d.ts
+/**
+ * Reference to a single Crossplane Composite Resource (XR) the watcher should track.
+ */
+interface XrRef {
+  /** API group, e.g. `platform.example.com`. Empty string for the core group. */
+  group: string;
+  /** API version, e.g. `v1alpha1`. */
+  version: string;
+  /** Resource plural, e.g. `xprojects`. */
+  plural: string;
+  /** Resource kind, e.g. `XProject`. */
+  kind: string;
+  /** Whether the resource is namespaced. */
+  namespaced: boolean;
+  /** Object name. */
+  name: string;
+  /** Namespace; required when `namespaced` is true. */
+  namespace?: string;
+}
+/** A composed resource entry as published in `status.xplane.emittedResources`. */
+interface EmittedResource {
+  apiVersion: string;
+  kind: string;
+  /** Construct path within the composition (also the Crossplane composed-resource key). */
+  nodePath: string;
+  /** Kubernetes `metadata.name`, when known. */
+  name?: string;
+  /** Kubernetes `metadata.namespace`, when present. */
+  namespace?: string;
+  ready: boolean;
+}
+/** A blocked resource entry as published in `status.xplane.blockedResources`. */
+interface BlockedResource {
+  apiVersion: string;
+  kind: string;
+  /** Construct path within the composition (also the Crossplane composed-resource key). */
+  nodePath: string;
+  /** Kubernetes `metadata.name`, when known. */
+  name?: string;
+  /** Kubernetes `metadata.namespace`, when present. */
+  namespace?: string;
+  waitingFor?: string[];
+}
+/** The compact observability payload set on the XR when `emitXplaneStatus = true`. */
+interface XplaneStatus {
+  emittedResources: EmittedResource[];
+  blockedResources: BlockedResource[];
+}
+/** A `spec.resourceRefs` / `status.resourceRefs` entry on a Crossplane XR. */
+interface ResourceRef {
+  apiVersion: string;
+  kind: string;
+  name: string;
+}
+/** Snapshot of an XR's state as observed by the watcher. */
+interface XrSnapshot {
+  /** The full XR object from the API server. */
+  object: KubernetesObject;
+  /** True when a `Ready` condition with `status: "True"` is present. */
+  ready: boolean;
+  /** Reason of the `Ready` condition, if any. */
+  readyReason?: string;
+  /** Message of the `Ready` condition, if any. */
+  readyMessage?: string;
+  /** True when a `Responsive` condition reports `status: "False"` with reason `WatchCircuitOpen`. */
+  updatesThrottled?: boolean;
+  /** Present when the `Synced` condition is `status: "False"` with reason `ReconcileError` — a fatal reconcile failure. */
+  syncError?: {
+    reason: string;
+    message: string;
+  };
+  /** Parsed `status.xplane` payload, if present. */
+  xplane?: XplaneStatus;
+  /** Parsed `status.resourceRefs` (composed resources). */
+  resourceRefs: ResourceRef[];
+}
+/** A condensed view of a Kubernetes Event tied to the watched XR. */
+interface KubernetesEvent {
+  type: string;
+  reason: string;
+  message: string;
+  count: number;
+  firstTimestamp?: string;
+  lastTimestamp?: string;
+  involvedKind?: string;
+  involvedName?: string;
+}
+/** Stream item emitted by the XR watcher. */
+type XrEvent = {
+  type: 'snapshot';
+  snapshot: XrSnapshot;
+} | {
+  type: 'k8s-event';
+  event: KubernetesEvent;
+} | {
+  type: 'ready';
+  snapshot: XrSnapshot;
+} | {
+  type: 'error';
+  error: Error;
+} | {
+  type: 'end';
+};
+//#endregion
+//#region src/watcher/xr-watcher.d.ts
+interface CreateXrWatcherOptions {
+  kubeConfig: KubeConfig;
+  ref: XrRef;
+  /** Disable subscribing to Kubernetes Events for the XR. Defaults to `false`. */
+  disableEvents?: boolean;
+  /** Aborts both the XR and Events watches and closes the iterable. */
+  signal?: AbortSignal;
+}
+interface XrWatcher extends AsyncIterable<XrEvent> {
+  /** Resolves with the first ready snapshot. Rejects on error or end-before-ready. */
+  readonly ready: Promise<XrSnapshot>;
+  /** Resolves when the watcher's background tasks have all settled. */
+  readonly done: Promise<void>;
+  /** Aborts the watcher and closes the iterable. Idempotent. */
+  stop(): void;
+}
+/**
+ * Subscribe to live updates of a single XR. Emits a `snapshot` on every observed
+ * change, a one-shot `ready` when the XR's `Ready` condition first becomes True,
+ * and (unless disabled) `k8s-event` items for Kubernetes Events targeting the XR.
+ *
+ * The watcher uses list-then-watch with auto-reconnect — no polling.
+ */
+declare function createXrWatcher(opts: CreateXrWatcherOptions): XrWatcher;
+//#endregion
+export { EmittedResource as a, XplaneStatus as c, XrSnapshot as d, BlockedResource as i, XrEvent as l, XrWatcher as n, KubernetesEvent as o, createXrWatcher as r, ResourceRef as s, CreateXrWatcherOptions as t, XrRef as u };
+//# sourceMappingURL=xr-watcher-EiWHVp3o.d.mts.map

package/dist/xr-watcher-EiWHVp3o.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xr-watcher-EiWHVp3o.d.mts","names":[],"sources":["../src/watcher/types.ts","../src/watcher/xr-watcher.ts"],"mappings":";;;;;AAKA;UAAiB,KAAA;;EAEf,KAAA;EAAA;EAEA,OAAA;EAEA;EAAA,MAAA;EAIA;EAFA,IAAA;EAMA;EAJA,UAAA;EAIS;EAFT,IAAA;EAM8B;EAJ9B,SAAA;AAAA;;UAIe,eAAA;EACf,UAAA;EACA,IAAA;EAMA;EAJA,QAAA;EAKK;EAHL,IAAA;EAOe;EALf,SAAA;EACA,KAAA;AAAA;;UAIe,eAAA;EACf,UAAA;EACA,IAAA;EAMA;EAJA,QAAA;EAKU;EAHV,IAAA;EAOe;EALf,SAAA;EACA,UAAA;AAAA;;UAIe,YAAA;EACf,gBAAA,EAAkB,eAAA;EAClB,gBAAA,EAAkB,eAAe;AAAA;AAAA;AAAA,UAIlB,WAAA;EACf,UAAA;EACA,IAAA;EACA,IAAA;AAAA;;UAIe,UAAA;EAJX;EAMJ,MAAA,EAAQ,gBAAA;EAFO;EAIf,KAAA;;EAEA,WAAA;EAQS;EANT,YAAA;EAQyB;EANzB,gBAAA;EARA;EAUA,SAAA;IAAc,MAAA;IAAgB,OAAA;EAAA;EAF9B;EAIA,MAAA,GAAS,YAAA;EAFK;EAId,YAAA,EAAc,WAAA;AAAA;;UAIC,eAAA;EACf,IAAA;EACA,MAAA;EACA,OAAA;EACA,KAAA;EACA,cAAA;EACA,aAAA;EACA,YAAA;EACA,YAAA;AAAA;;KAIU,OAAA;EACN,IAAA;EAAkB,QAAA,EAAU,UAAA;AAAA;EAC5B,IAAA;EAAmB,KAAA,EAAO,eAAA;AAAA;EAC1B,IAAA;EAAe,QAAA,EAAU,UAAA;AAAA;EACzB,IAAA;EAAe,KAAA,EAAO,KAAA;AAAA;EACtB,IAAA;AAAA;;;UC5FW,sBAAA;EACf,UAAA,EAAY,UAAA;EACZ,GAAA,EAAK,KAAA;;EAEL,aAAA;EDJA;ECMA,MAAA,GAAS,WAAA;AAAA;AAAA,UAGM,SAAA,SAAkB,aAAA,CAAc,OAAA;EDD/C;EAAA,SCGS,KAAA,EAAO,OAAA,CAAQ,UAAA;EDCxB;EAAA,SCCS,IAAA,EAAM,OAAA;EDDN;ECGT,IAAA;AAAA;;;;;;;;iBAUc,eAAA,CAAgB,IAAA,EAAM,sBAAA,GAAyB,SAAS"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@xplane/utils",
+  "version": "0.0.0",
+  "type": "module",
+  "description": "CLI and library to watch Crossplane XRs in real time (events, status.xplane, readiness)",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sv-oss/xplane",
+    "directory": "packages/utils"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "xplane-utils": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    },
+    "./render": {
+      "import": "./dist/render/index.mjs",
+      "types": "./dist/render/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@kubernetes/client-node": "^1.4.0",
+    "chalk": "^5.3.0",
+    "citty": "0.2.2",
+    "log-update": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "@vitest/coverage-v8": "4.1.6",
+    "tsdown": "^0.22.0",
+    "typescript": "6.0.3",
+    "vitest": "4.1.6"
+  }
+}