typekro 0.12.1 → 0.14.0

package/dist/core/containers/image.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Container Image Utility
+ *
+ * `container()` declares a container image built from source and pushed to a registry. It is the
+ * high-level front door over {@link buildContainer}: a memoized async builder that resolves to a
+ * SHAPED result (`{ imageUri, repository, tag }`) so callers can use the full URI for a resource's
+ * image field OR the split `repository`/`tag` for a Helm chart's image values — without re-splitting.
+ *
+ * An image build is an async, client-side, pre-deploy side effect, so `container()` is honest about
+ * that: you `await` it. It is NOT a deferred reference — resolve images in (async) setup code before
+ * composing, then feed the resulting literals into resources or chart values.
+ *
+ * Memoization: the build is keyed by container identity (`id ?? imageName`) and cached, so awaiting
+ * the same container many times (e.g. several deployments sharing one image) builds it exactly ONCE.
+ *
+ * @example
+ * ```typescript
+ * import { container } from 'typekro/containers';
+ *
+ * const img = await container({ context: './app', imageName: 'app', registry: { type: 'ecr' } });
+ * // img.imageUri  → '123.dkr.ecr.us-east-1.amazonaws.com/app:sha-abc'
+ * // img.repository → '123.dkr.ecr.us-east-1.amazonaws.com/app'   img.tag → 'sha-abc'
+ *
+ * Deployment({ name: 'app', image: img.imageUri, ports: [{ containerPort: 3000 }] });
+ * // or for a Helm chart's split image values: { repository: img.repository, tag: img.tag }
+ * ```
+ */
+import type { ContainerBuildOptions, ContainerBuildResult } from './registries/types.js';
+/** A built container image, resolved to a literal — both the full URI and its split parts. */
+export interface ContainerImage {
+    /** Full image URI, e.g. `123.dkr.ecr.us-east-1.amazonaws.com/app:sha-abc`. */
+    readonly imageUri: string;
+    /** The URI without the tag, e.g. `123.dkr.ecr.us-east-1.amazonaws.com/app`. */
+    readonly repository: string;
+    /** The tag, e.g. `sha-abc`. */
+    readonly tag: string;
+}
+/** Options for {@link container}: the {@link ContainerBuildOptions} plus an optional stable identity. */
+export interface ContainerOptions extends ContainerBuildOptions {
+    /** Stable identity for build memoization; defaults to `imageName`. Set when two containers share one. */
+    id?: string;
+}
+/**
+ * Split a full image URI into `{ repository, tag }`. Handles digest form (`repo@sha256:…`) and tag
+ * form (`repo:tag`), registry-port-colon aware (a colon in `host:port/...` is not the tag separator).
+ */
+export declare function splitImageUri(uri: string): {
+    repository: string;
+    tag: string;
+};
+/** Test seam: the builder `container()` delegates to (defaults to the real {@link buildContainer}). */
+type Builder = (options: ContainerBuildOptions) => Promise<ContainerBuildResult>;
+/**
+ * Build a container image (delegating to {@link buildContainer}) and resolve to its shaped result.
+ * Memoized by identity — see the module doc. `build` is an injectable test seam; production callers
+ * pass only `options`.
+ */
+export declare function container(options: ContainerOptions, build?: Builder): Promise<ContainerImage>;
+/** Clear the build memoization cache. Intended for tests/long-lived processes that need a rebuild. */
+export declare function clearContainerCache(): void;
+export {};
+//# sourceMappingURL=image.d.ts.map

package/dist/core/containers/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/core/containers/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAEzF,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+BAA+B;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,yGAAyG;AACzG,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,yGAAyG;IACzG,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAQ9E;AAKD,uGAAuG;AACvG,KAAK,OAAO,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,oBAAoB,CAAC,CAAC;AASjF;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,OAAO,EAAE,gBAAgB,EACzB,KAAK,GAAE,OAAwB,GAC9B,OAAO,CAAC,cAAc,CAAC,CAQzB;AAED,sGAAsG;AACtG,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C"}

package/dist/core/containers/image.js

@@ -0,0 +1,69 @@
+/**
+ * Container Image Utility
+ *
+ * `container()` declares a container image built from source and pushed to a registry. It is the
+ * high-level front door over {@link buildContainer}: a memoized async builder that resolves to a
+ * SHAPED result (`{ imageUri, repository, tag }`) so callers can use the full URI for a resource's
+ * image field OR the split `repository`/`tag` for a Helm chart's image values — without re-splitting.
+ *
+ * An image build is an async, client-side, pre-deploy side effect, so `container()` is honest about
+ * that: you `await` it. It is NOT a deferred reference — resolve images in (async) setup code before
+ * composing, then feed the resulting literals into resources or chart values.
+ *
+ * Memoization: the build is keyed by container identity (`id ?? imageName`) and cached, so awaiting
+ * the same container many times (e.g. several deployments sharing one image) builds it exactly ONCE.
+ *
+ * @example
+ * ```typescript
+ * import { container } from 'typekro/containers';
+ *
+ * const img = await container({ context: './app', imageName: 'app', registry: { type: 'ecr' } });
+ * // img.imageUri  → '123.dkr.ecr.us-east-1.amazonaws.com/app:sha-abc'
+ * // img.repository → '123.dkr.ecr.us-east-1.amazonaws.com/app'   img.tag → 'sha-abc'
+ *
+ * Deployment({ name: 'app', image: img.imageUri, ports: [{ containerPort: 3000 }] });
+ * // or for a Helm chart's split image values: { repository: img.repository, tag: img.tag }
+ * ```
+ */
+import { buildContainer } from './build.js';
+/**
+ * Split a full image URI into `{ repository, tag }`. Handles digest form (`repo@sha256:…`) and tag
+ * form (`repo:tag`), registry-port-colon aware (a colon in `host:port/...` is not the tag separator).
+ */
+export function splitImageUri(uri) {
+    const at = uri.lastIndexOf('@');
+    if (at !== -1)
+        return { repository: uri.slice(0, at), tag: uri.slice(at + 1) };
+    const colon = uri.lastIndexOf(':');
+    const slash = uri.lastIndexOf('/');
+    return colon > slash
+        ? { repository: uri.slice(0, colon), tag: uri.slice(colon + 1) }
+        : { repository: uri, tag: 'latest' };
+}
+/** Build memoization, keyed by container identity (`id ?? imageName`) — builds each image once. */
+const buildCache = new Map();
+async function buildAndShape(options, build) {
+    const { id: _id, ...buildOptions } = options;
+    const result = await build({ ...buildOptions, tag: buildOptions.tag ?? 'content-hash' });
+    const { repository, tag } = splitImageUri(result.imageUri);
+    return { imageUri: result.imageUri, repository, tag };
+}
+/**
+ * Build a container image (delegating to {@link buildContainer}) and resolve to its shaped result.
+ * Memoized by identity — see the module doc. `build` is an injectable test seam; production callers
+ * pass only `options`.
+ */
+export function container(options, build = buildContainer) {
+    const key = options.id ?? options.imageName;
+    let pending = buildCache.get(key);
+    if (!pending) {
+        pending = buildAndShape(options, build);
+        buildCache.set(key, pending);
+    }
+    return pending;
+}
+/** Clear the build memoization cache. Intended for tests/long-lived processes that need a rebuild. */
+export function clearContainerCache() {
+    buildCache.clear();
+}
+//# sourceMappingURL=image.js.map

package/dist/core/containers/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/core/containers/image.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAmB5C;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW;IACvC,MAAM,EAAE,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,EAAE,KAAK,CAAC,CAAC;QAAE,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IAC/E,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACnC,OAAO,KAAK,GAAG,KAAK;QAClB,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,EAAE;QAChE,CAAC,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC;AACzC,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,GAAG,IAAI,GAAG,EAAmC,CAAC;AAK9D,KAAK,UAAU,aAAa,CAAC,OAAyB,EAAE,KAAc;IACpE,MAAM,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,YAAY,EAAE,GAAG,OAAO,CAAC;IAC7C,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,EAAE,GAAG,YAAY,EAAE,GAAG,EAAE,YAAY,CAAC,GAAG,IAAI,cAAc,EAAE,CAAC,CAAC;IACzF,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,GAAG,aAAa,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CACvB,OAAyB,EACzB,QAAiB,cAAc;IAE/B,MAAM,GAAG,GAAG,OAAO,CAAC,EAAE,IAAI,OAAO,CAAC,SAAS,CAAC;IAC5C,IAAI,OAAO,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QACxC,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,mBAAmB;IACjC,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC"}

package/dist/core/containers/index.d.ts

@@ -4,18 +4,22 @@
  * Build Docker images and push them to container registries.
  * Returns image URIs for use in TypeKro compositions.
  *
+ * The low-level `buildContainer` builds + pushes imperatively and returns a URI. The higher-level
+ * `container()` is a memoized async builder that resolves to a SHAPED result (`{ imageUri,
+ * repository, tag }`) — `await` it in setup code, then feed the full URI to a resource's image field
+ * or the split `repository`/`tag` to a Helm chart's image values.
+ *
  * @example
  * ```typescript
- * import { buildContainer } from 'typekro/containers';
+ * import { container } from 'typekro/containers';
  *
- * const { imageUri } = await buildContainer({
- *   context: './apps/my-app',
- *   imageName: 'my-app',
- *   registry: { type: 'orbstack' },
- * });
+ * const img = await container({ context: './app', imageName: 'app', registry: { type: 'ecr' } });
+ * Deployment({ image: img.imageUri, … });            // full URI
+ * // or chart values:  { repository: img.repository, tag: img.tag }
  * ```
  */
 export { buildContainer } from './build.js';
 export { ContainerBuildError } from './errors.js';
+export { type ContainerImage, type ContainerOptions, clearContainerCache, container, splitImageUri, } from './image.js';
 export type { ContainerBuildOptions, ContainerBuildResult, EcrRegistryConfig, OrbstackRegistryConfig, RegistryConfig, } from './registries/types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/core/containers/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/containers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/containers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,mBAAmB,EACnB,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,sBAAsB,EACtB,cAAc,GACf,MAAM,uBAAuB,CAAC"}

package/dist/core/containers/index.js

@@ -4,17 +4,21 @@
  * Build Docker images and push them to container registries.
  * Returns image URIs for use in TypeKro compositions.
  *
+ * The low-level `buildContainer` builds + pushes imperatively and returns a URI. The higher-level
+ * `container()` is a memoized async builder that resolves to a SHAPED result (`{ imageUri,
+ * repository, tag }`) — `await` it in setup code, then feed the full URI to a resource's image field
+ * or the split `repository`/`tag` to a Helm chart's image values.
+ *
  * @example
  * ```typescript
- * import { buildContainer } from 'typekro/containers';
+ * import { container } from 'typekro/containers';
  *
- * const { imageUri } = await buildContainer({
- *   context: './apps/my-app',
- *   imageName: 'my-app',
- *   registry: { type: 'orbstack' },
- * });
+ * const img = await container({ context: './app', imageName: 'app', registry: { type: 'ecr' } });
+ * Deployment({ image: img.imageUri, … });            // full URI
+ * // or chart values:  { repository: img.repository, tag: img.tag }
  * ```
  */
 export { buildContainer } from './build.js';
 export { ContainerBuildError } from './errors.js';
+export { clearContainerCache, container, splitImageUri, } from './image.js';
 //# sourceMappingURL=index.js.map

package/dist/core/containers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/containers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/containers/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAGL,mBAAmB,EACnB,SAAS,EACT,aAAa,GACd,MAAM,YAAY,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typekro",
-  "version": "0.12.1",
+  "version": "0.14.0",
   "description": "A control plane aware framework for orchestrating kubernetes resources like a programmer.",
   "type": "module",
   "repository": {