@owlmeans/kluster 0.1.7 → 0.1.9

package/README.md

@@ -65,3 +65,20 @@ Extends `ServerConfig` with optional `namespace: string`.
 
 - [`@owlmeans/server-app`](../server-app) — `makeContext` where `klusterize` is typically called
 - [`@owlmeans/mongo`](../mongo) — MongoDB URL can be a `kluster:` directive
+
+<!-- owlmeans:agent-guidance:start -->
+## Agent guidance
+
+This package ships embedded Claude Code skills and GitHub Copilot instructions under
+`agent-meta/`. After installing your `@owlmeans/*` packages, run the OwlMeans
+agent-skills installer to place them into your project's native locations
+(`.claude/skills/` and `.github/instructions/`):
+
+```sh
+npx @owlmeans/agent-skills
+```
+
+The embedded files are version-matched to this package release. Do not edit them
+directly — they are regenerated on each publish. To contribute guidance edits,
+open a PR against the source monorepo.
+<!-- owlmeans:agent-guidance:end -->

package/agent-meta/instructions/kluster.instructions.md

@@ -0,0 +1,104 @@
+---
+description: "How to use @owlmeans/kluster — Kubernetes API client service. Resolve via context.service(DEFAULT_ALIAS) to access the cluster API for service discovery, secrets, config maps, and Gateway API (Gateway/HTTPRoute via CustomObjectsApi)."
+applyTo: "**/*.ts, **/*.tsx"
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/kluster
+
+**Layer:** Infra
+**Install:** `"@owlmeans/kluster": "^0.1.9"` in `dependencies`
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `DEFAULT_ALIAS` | Kluster service alias |
+| `makeKlusterService()` | Kubernetes client service factory |
+| `KlusterService` | Service interface |
+| `isNotFoundError(e)` | Returns true if an API error is HTTP 404 |
+| Helpers | Service discovery, secret resolution |
+
+## Usage
+
+```typescript
+import { DEFAULT_ALIAS as KLUSTER_SERVICE, makeKlusterService } from '@owlmeans/kluster'
+
+context.registerService(makeKlusterService())
+context.kluster = () => context.service(KLUSTER_SERVICE)
+```
+
+## KlusterService API
+
+After `await kluster.ready()`:
+
+| Method | Returns | Purpose |
+|--------|---------|---------|
+| `kluster.api` | `CoreV1Api` | Core APIs — Pods, Services, Secrets, ConfigMaps |
+| `kluster.makeNetworkingApi()` | `NetworkingV1Api` | Legacy networking (kept for compatibility) |
+| `kluster.makeAppsApi()` | `AppsV1Api` | Deployments, StatefulSets |
+| `kluster.makeCustomObjectsApi()` | `CustomObjectsApi` | CRDs — **use for Gateway API resources** |
+| `kluster.getHostnames(selector, ns)` | `string[]` | Pod IPs by label selector |
+| `kluster.getServiceHostname(selector, ns)` | `string \| null` | ClusterIP by label selector |
+
+## Gateway API via CustomObjectsApi
+
+Gateway API resources (`Gateway`, `HTTPRoute`) are Kubernetes CRDs. Access them via `makeCustomObjectsApi()`:
+
+```typescript
+import { DEFAULT_ALIAS as KLUSTER_SERVICE } from '@owlmeans/kluster'
+import type { KlusterService } from '@owlmeans/kluster'
+import { isNotFoundError } from '@owlmeans/kluster'
+
+const kluster = context.service<KlusterService>(KLUSTER_SERVICE)
+await kluster.ready()
+const customObjects = kluster.makeCustomObjectsApi()
+const coreV1 = kluster.api!  // CoreV1Api for port resolution
+
+const GATEWAY_GROUP = 'gateway.networking.k8s.io'
+const GATEWAY_VERSION = 'v1'
+
+// Read a Gateway
+const gw = await customObjects.getNamespacedCustomObject({
+  group: GATEWAY_GROUP, version: GATEWAY_VERSION,
+  namespace: 'default', plural: 'gateways', name: 'my-gateway',
+})
+
+// Create an HTTPRoute
+await customObjects.createNamespacedCustomObject({
+  group: GATEWAY_GROUP, version: GATEWAY_VERSION,
+  namespace: 'default', plural: 'httproutes',
+  body: {
+    apiVersion: 'gateway.networking.k8s.io/v1',
+    kind: 'HTTPRoute',
+    metadata: { name: 'my-route', namespace: 'default' },
+    spec: {
+      parentRefs: [{ name: 'my-gateway', sectionName: 'web-https' }],
+      hostnames: ['example.com'],
+      rules: [{
+        matches: [{ path: { type: 'PathPrefix', value: '/' } }],
+        backendRefs: [{ name: 'my-service', port: 80 }], // numeric port required
+      }],
+    },
+  },
+})
+
+// Handle 404 gracefully
+try {
+  await customObjects.getNamespacedCustomObject({ ... })
+} catch (e) {
+  if (isNotFoundError(e)) { /* resource absent */ }
+  else throw e
+}
+```
+
+**Important**: HTTPRoute `backendRefs[].port` must be **numeric**. Named ports are not supported.
+To resolve a named port, read the Service via `CoreV1Api`:
+```typescript
+const svc = await coreV1.readNamespacedService({ name: 'my-service', namespace })
+const port = svc.spec?.ports?.find(p => p.name === 'backend-port')?.port ?? 80
+```
+
+## Depends On
+
+- `@owlmeans/server-context`, `@owlmeans/config`, `@kubernetes/client-node`

package/agent-meta/manifest.json

@@ -0,0 +1,23 @@
+{
+  "schemaVersion": 1,
+  "package": "@owlmeans/kluster",
+  "version": "0.1.9",
+  "generatedAt": "2026-06-14T13:34:06.138Z",
+  "canonicalRepo": "https://github.com/owlmeans/common",
+  "entries": [
+    {
+      "kind": "skill",
+      "name": "kluster",
+      "category": "package-specific",
+      "file": "skills/kluster/SKILL.md",
+      "canonicalPath": ".claude/skills/kluster/SKILL.md"
+    },
+    {
+      "kind": "instruction",
+      "name": "kluster",
+      "category": "package-specific",
+      "file": "instructions/kluster.instructions.md",
+      "canonicalPath": ".github/instructions/kluster.instructions.md"
+    }
+  ]
+}

package/agent-meta/skills/kluster/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: kluster
+description: How to use @owlmeans/kluster — Kubernetes API client service. Resolve via context.service(DEFAULT_ALIAS) to access the cluster API for service discovery, secrets, config maps. Auto-invoked when interacting with the cluster from app code.
+user-invocable: false
+---
+<!-- AUTO-GENERATED — do not edit. Regenerate via sync-agent-meta. -->
+
+# @owlmeans/kluster
+
+**Layer:** Infra
+**Install:** `"@owlmeans/kluster": "^0.1.9"` in `dependencies`
+
+## Key Exports
+
+| Export | Description |
+|--------|-------------|
+| `DEFAULT_ALIAS` | Service alias for the kluster service |
+| `makeKlusterService()` | Factory for the Kubernetes client service |
+| `Kluster` types | Service interface (k8s API access) |
+| Helpers | Service discovery, secret resolution |
+
+## Usage
+
+```typescript
+import { DEFAULT_ALIAS as KLUSTER_SERVICE } from '@owlmeans/kluster'
+import { makeKlusterService } from '@owlmeans/kluster'
+
+context.registerService(makeKlusterService())
+context.kluster = () => context.service(KLUSTER_SERVICE)
+
+// Later:
+const k8s = ctx.kluster()
+```
+
+## Depends On
+
+- `@owlmeans/server-context`, `@owlmeans/config`
+- `@kubernetes/client-node` (runtime)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/kluster",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -22,10 +22,10 @@
   },
   "dependencies": {
     "@kubernetes/client-node": "^1.4.0",
-    "@owlmeans/config": "^0.1.7",
-    "@owlmeans/context": "^0.1.7",
-    "@owlmeans/server-config": "^0.1.7",
-    "@owlmeans/server-context": "^0.1.7"
+    "@owlmeans/config": "^0.1.9",
+    "@owlmeans/context": "^0.1.9",
+    "@owlmeans/server-config": "^0.1.9",
+    "@owlmeans/server-context": "^0.1.9"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",