@configbutler/krm-stream 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/** The complete projected Kubernetes object, verbatim.
+ *
+ * Deliberately NOT a schema: a ConfigMap has `data` and no `spec`; a Secret has `type` and
+ * `stringData`; a CRD may define any field at the root. We carry whatever is there. */
+export interface KRMObject {
+    apiVersion: string;
+    kind: string;
+    metadata: {
+        uid: string;
+        name: string;
+        namespace?: string;
+        resourceVersion?: string;
+        labels?: Record<string, string>;
+        annotations?: Record<string, string>;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+/** A field address: an ARRAY of segments — object keys (any string) and array indices.
+ *
+ * Never a dot-joined string. `metadata.labels["app.kubernetes.io/name"]` is THREE segments, the last
+ * of which contains two dots and a slash; joining it produces an address that resolves to nothing,
+ * silently. That bug (R-ID) is why this type exists. */
+export type Path = (string | number)[];
+export type EventType = "reset" | "added" | "modified" | "deleted" | "synced" | "error";
+export type ErrorCode = "FORBIDDEN" | "UNAUTHENTICATED" | "SCOPE_INVALID" | "UPSTREAM_UNAVAILABLE" | "RESYNC_REQUIRED" | "SLOW_CONSUMER" | "INTERNAL";
+/** What the gateway removed from every object in this stream. On the wire, per cycle, because a
+ * consumer must be able to distinguish "absent upstream" from "the gateway took it away". */
+export type Projection = "krm-raw/v1" | "krm-full/v1" | "krm-spec/v1";
+/** A path whose value exists upstream but was withheld by the projection. `rev` starts at one and
+ * increments whenever that hidden value changes during this stream connection. */
+export interface Redaction {
+    path: string;
+    rev: number;
+}
+export interface Scope {
+    target: string;
+    group?: string;
+    version: string;
+    resource: string;
+    namespace?: string;
+    name?: string;
+    labelSelector?: string;
+}
+/** The tombstone. `deleted` is the one event with no complete object — there may not be one — so it
+ * carries an identity instead. `uid` is what the consumer acts on. */
+export interface Identity {
+    uid: string;
+    apiVersion: string;
+    kind: string;
+    namespace?: string;
+    name: string;
+}
+export interface StreamEvent {
+    /** Per-connection event sequence. A gap means the consumer must reconnect for a fresh snapshot. */
+    seq: number;
+    type: EventType;
+    target?: string;
+    scope?: Scope;
+    projection?: Projection;
+    object?: KRMObject;
+    /** Always present on added/modified — empty when nothing is redacted. */
+    redacted?: Redaction[];
+    identity?: Identity;
+    code?: ErrorCode;
+    message?: string;
+    terminal?: boolean;
+    retryAfterMs?: number | null;
+}
+/** One pending edit, derived by comparing the draft to the last server object. Never cached — a
+ * cached dirty set goes stale on the next watch event, which is regression R-DERIVED. */
+export interface Change {
+    path: Path;
+    kind: "add" | "update" | "delete";
+    old: unknown;
+    new: unknown;
+}
+/** "The server moved this field while you were editing it, and to a different value than you
+ * typed." `theirs` is what the cluster says; the user's edit is never silently overwritten. */
+export interface Conflict {
+    path: Path;
+    theirs: unknown;
+}
+/** Which regions of an object a user may edit. `status` is controller-owned and read-only — but
+ * read-only is NOT ignored: it still follows the server live and flashes what changed. That is the
+ * entire live-status-watch use case. */
+export interface EditabilityPolicy {
+    isEditable(obj: KRMObject, path: Path): boolean;
+    /** True for a path that is not editable itself but that an editable region lives UNDER — `[]` and
+     * `["metadata"]` under the default policy.
+     *
+     * The merge needs both questions answered, and they are not each other's negation. `metadata` is
+     * not editable, but replacing it wholesale from the server would clobber the label the user is
+     * editing inside it; `status` is not editable either, and replacing it wholesale is exactly right.
+     * Without this second predicate a store cannot tell those two apart. */
+    containsEditable(obj: KRMObject, path: Path): boolean;
+    /** For an associative Kubernetes list at path, return its identity fields. Omit this to retain the
+     * safe atomic-array behavior. Implementations normally derive it from OpenAPI's
+     * `x-kubernetes-list-type: map` and `x-kubernetes-list-map-keys`. */
+    listMapKeys?(obj: KRMObject, path: Path): readonly string[] | undefined;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+// The wire vocabulary and the client's core types. This file is the TypeScript half of the same
+// contract gateway/event.go declares in Go; see ../../../spec/v1.md, which governs both.
+//
+// Nothing here has a runtime dependency, and nothing here knows about ConfigButler, GitOps, Dex or
+// kcp. It knows KRM. That one-way rule is what makes this library adoptable by someone who has
+// never heard of us.
+export {};

package/dist/url.d.ts

@@ -0,0 +1,26 @@
+import type { Projection, Scope } from "./types.ts";
+/** A scope as a CALLER supplies it. `target` is optional here (a single-cluster host may never set
+ * one) though it is always present on the `reset` event the gateway sends back. */
+export type ScopeQuery = Omit<Scope, "target"> & {
+    target?: string;
+    projection?: Projection;
+};
+/**
+ * Build the URL for a resource stream.
+ *
+ * ```ts
+ * connectResourceStream(resourceStreamURL("/resource-stream/v1", {
+ *   version: "v1", resource: "configmaps", namespace: "app",
+ * }), store);
+ * ```
+ *
+ * The field order is FIXED — target, group, version, resource, namespace, name, labelSelector — so
+ * that the same scope always produces the same URL. That is not tidiness: a URL that varies by key
+ * order is one an HTTP cache, a log aggregator and a human diffing two bug reports all see as two
+ * different URLs.
+ *
+ * Note what this function does NOT take: an API-server address. There is nowhere to put one, which
+ * is spec §8's promise made structural rather than merely stated — and the gateway REFUSES such a
+ * parameter outright if someone appends one by hand.
+ */
+export declare function resourceStreamURL(base: string, scope: ScopeQuery): string;

package/dist/url.js

@@ -0,0 +1,38 @@
+/**
+ * Build the URL for a resource stream.
+ *
+ * ```ts
+ * connectResourceStream(resourceStreamURL("/resource-stream/v1", {
+ *   version: "v1", resource: "configmaps", namespace: "app",
+ * }), store);
+ * ```
+ *
+ * The field order is FIXED — target, group, version, resource, namespace, name, labelSelector — so
+ * that the same scope always produces the same URL. That is not tidiness: a URL that varies by key
+ * order is one an HTTP cache, a log aggregator and a human diffing two bug reports all see as two
+ * different URLs.
+ *
+ * Note what this function does NOT take: an API-server address. There is nowhere to put one, which
+ * is spec §8's promise made structural rather than merely stated — and the gateway REFUSES such a
+ * parameter outright if someone appends one by hand.
+ */
+export function resourceStreamURL(base, scope) {
+    if (!scope.resource)
+        throw new Error("krm-stream: scope needs a `resource` (the plural, lowercase API name)");
+    if (!scope.version)
+        throw new Error("krm-stream: scope needs a `version` (there is no default: v1 and v1beta1 differ)");
+    const q = new URLSearchParams();
+    const set = (k, v) => {
+        if (v)
+            q.append(k, v);
+    };
+    set("target", scope.target);
+    set("group", scope.group);
+    set("version", scope.version);
+    set("resource", scope.resource);
+    set("namespace", scope.namespace);
+    set("name", scope.name);
+    set("labelSelector", scope.labelSelector);
+    set("projection", scope.projection);
+    return `${base}${base.includes("?") ? "&" : "?"}${q.toString()}`;
+}

package/dist/version.d.ts

@@ -0,0 +1,4 @@
+/** The npm package version of this build. Assert it against the copy you vendored. */
+export declare const VERSION = "0.1.0";
+/** The wire protocol this build speaks (spec/v1.md). The gateway sends it as `X-KRM-Stream-Protocol`. */
+export declare const PROTOCOL_VERSION = 1;

package/dist/version.js

@@ -0,0 +1,26 @@
+// The version stamp, and it exists for one failure that is otherwise silent.
+//
+// This library is publishable to npm, but it is also VENDORED — copied, as built ESM, into a host
+// that serves it to a browser (that is what the gateway's `--dist` flag is for). A vendored asset
+// drifts. It keeps working, too: an old client and a new gateway agree about every event they both
+// still understand, right up until the wire changes, and then the failure lands in someone's browser
+// rather than in anyone's test suite.
+//
+// So the bytes carry their own provenance, and a host can assert it:
+//
+//	import { VERSION, PROTOCOL_VERSION } from "@configbutler/krm-stream";
+//	// in the host's own test suite:
+//	assert.equal(PROTOCOL_VERSION, protocolVersionFromMyGoMod);
+//
+// Neither number is hand-maintained in the sense that matters: `task test` fails if VERSION drifts
+// from package.json, and if PROTOCOL_VERSION drifts from the Go constant that DEFINES it (the gateway
+// publishes it into conformance/gen/protocol.json, and the suite reads it back). Neither half of this
+// repo can bump the protocol alone.
+//
+// VERSION is written by release-please, which finds it by the annotation on the line itself (see
+// release-please-config.json). Do not edit it by hand: the release PR bumps package.json and this
+// line together, and version.test.ts fails if they ever disagree.
+/** The npm package version of this build. Assert it against the copy you vendored. */
+export const VERSION = "0.1.0"; // x-release-please-version
+/** The wire protocol this build speaks (spec/v1.md). The gateway sends it as `X-KRM-Stream-Protocol`. */
+export const PROTOCOL_VERSION = 1;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@configbutler/krm-stream",
+  "version": "0.1.0",
+  "description": "A live, honest window onto Kubernetes resources, in the browser: consume a KRM resource stream, three-way merge local edits, build a merge patch.",
+  "keywords": [
+    "kubernetes",
+    "krm",
+    "sse",
+    "watch",
+    "live",
+    "three-way-merge",
+    "resource-stream"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ConfigButler/krm-stream.git",
+    "directory": "packages/krm-stream"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "lint": "biome check",
+    "format": "biome check --write"
+  },
+  "//": "ZERO dependencies, and that one is absolute: the engine emits plain ESM a browser imports with no bundler, and gitops-api has no bundler and is not getting one. devDependencies ship NOTHING and are kept to the three that pay for themselves: typescript (the compiler), @types/node (without it `tsc` cannot see test/ at all, because the tests import node:test — and `node --test` STRIPS types rather than checking them, so the suite that IS the contract check would be the one unverified file in the repo), and biome (lint + format in one binary, the TypeScript half of what gofmt/go vet/golangci-lint do for the gateway).",
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.3",
+    "@types/node": "^26.1.1",
+    "typescript": "^5.9.0"
+  }
+}