@mizchi/k1c 0.1.0

package/dist/providers/r2-bucket.js

@@ -0,0 +1,98 @@
+import { z } from 'zod';
+import { NotFound } from "./types.js";
+import { toProviderError } from "./errors.js";
+export const r2BucketSchema = z.object({
+    bucketName: z.string(),
+    location: z.enum(['wnam', 'enam', 'weur', 'eeur', 'apac', 'oc']).optional(),
+    storageClass: z.enum(['Standard', 'InfrequentAccess']).optional(),
+});
+const NAME_PREFIX = 'k1c-';
+function parseLabel(name) {
+    if (!name.startsWith(NAME_PREFIX))
+        return null;
+    const rest = name.slice(NAME_PREFIX.length);
+    const dash = rest.indexOf('-');
+    if (dash <= 0 || dash === rest.length - 1)
+        return null;
+    const namespace = rest.slice(0, dash);
+    const objectName = rest.slice(dash + 1);
+    return `${namespace}/${objectName}`;
+}
+export const r2BucketProvider = {
+    resourceType: 'R2Bucket',
+    schema: r2BucketSchema,
+    async *list(ctx) {
+        let response;
+        try {
+            response = await ctx.cloudflare.r2.buckets.list({ account_id: ctx.accountId });
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+        for (const bucket of response.buckets ?? []) {
+            const name = bucket.name;
+            if (!name)
+                continue;
+            const label = parseLabel(name);
+            if (label === null)
+                continue;
+            yield { nativeId: name, label };
+        }
+    },
+    async read(ctx, nativeId) {
+        try {
+            const bucket = await ctx.cloudflare.r2.buckets.get(nativeId, { account_id: ctx.accountId });
+            const props = {
+                bucketName: bucket.name ?? nativeId,
+                ...(bucket.location ? { location: bucket.location } : {}),
+                ...(bucket.storage_class ? { storageClass: bucket.storage_class } : {}),
+            };
+            return props;
+        }
+        catch (raw) {
+            const err = toProviderError(raw);
+            if (err.code === 'NotFound')
+                return NotFound;
+            throw err;
+        }
+    },
+    async create(ctx, _label, desired) {
+        try {
+            const result = await ctx.cloudflare.r2.buckets.create({
+                account_id: ctx.accountId,
+                name: desired.bucketName,
+                ...(desired.location ? { locationHint: desired.location } : {}),
+                ...(desired.storageClass ? { storageClass: desired.storageClass } : {}),
+            });
+            return {
+                kind: 'sync',
+                nativeId: result.name ?? desired.bucketName,
+                properties: desired,
+            };
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+    },
+    async update(_ctx, _nativeId, prior, desired) {
+        if (prior.location !== desired.location || prior.storageClass !== desired.storageClass) {
+            throw {
+                code: 'NotUpdatable',
+                recoverable: false,
+                suggest: 'recreate',
+                message: 'R2 bucket location and storage class are immutable; recreate to change.',
+            };
+        }
+        return { kind: 'noop' };
+    },
+    async delete(ctx, nativeId) {
+        try {
+            await ctx.cloudflare.r2.buckets.delete(nativeId, { account_id: ctx.accountId });
+            return { kind: 'sync' };
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+    },
+};
+//# sourceMappingURL=r2-bucket.js.map

package/dist/providers/registry.d.ts

@@ -0,0 +1,9 @@
+import type { CloudflareResourceProvider } from './types.ts';
+export declare class ProviderRegistry {
+    #private;
+    register<P>(provider: CloudflareResourceProvider<P>): void;
+    get(resourceType: string): CloudflareResourceProvider<unknown>;
+    has(resourceType: string): boolean;
+    types(): IterableIterator<string>;
+}
+//# sourceMappingURL=registry.d.ts.map

package/dist/providers/registry.js

@@ -0,0 +1,22 @@
+export class ProviderRegistry {
+    #providers = new Map();
+    register(provider) {
+        if (this.#providers.has(provider.resourceType)) {
+            throw new Error(`provider already registered: ${provider.resourceType}`);
+        }
+        this.#providers.set(provider.resourceType, provider);
+    }
+    get(resourceType) {
+        const p = this.#providers.get(resourceType);
+        if (!p)
+            throw new Error(`no provider for resource type: ${resourceType}`);
+        return p;
+    }
+    has(resourceType) {
+        return this.#providers.has(resourceType);
+    }
+    *types() {
+        yield* this.#providers.keys();
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/providers/secret.d.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+import type { CloudflareResourceProvider } from './types.ts';
+export interface SecretProperties {
+    readonly stringData: Readonly<Record<string, string>>;
+}
+export declare const secretSchema: z.ZodType<SecretProperties>;
+export declare const secretProvider: CloudflareResourceProvider<SecretProperties>;
+//# sourceMappingURL=secret.d.ts.map

package/dist/providers/secret.js

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+import { NotFound } from "./types.js";
+export const secretSchema = z.object({
+    stringData: z.record(z.string()),
+});
+export const secretProvider = {
+    resourceType: 'Secret',
+    schema: secretSchema,
+    async *list(_ctx) {
+        // Secrets are always inferred from referenced Workers and from the manifest itself.
+        return;
+    },
+    async read(_ctx, _nativeId) {
+        // Cloudflare returns secret names but never values. We rely on the manifest as the
+        // source of value truth; drift detection is hash-based via k1c.io/last-applied.
+        throw new Error('secretProvider.read should be served by the reconciler graph, not invoked directly');
+    },
+    async create(_ctx, _label, _desired) {
+        // Actual upload happens in the Worker provider; this records intent only.
+        return { kind: 'sync', nativeId: _label, properties: { keys: Object.keys(_desired.stringData) } };
+    },
+    async update(_ctx, _nativeId, _prior, _desired) {
+        return { kind: 'noop' };
+    },
+    async delete(_ctx, _nativeId) {
+        // Secret deletion is realised by the Worker provider when the binding is removed.
+        return { kind: 'sync' };
+    },
+};
+//# sourceMappingURL=secret.js.map

package/dist/providers/types.d.ts

@@ -0,0 +1,69 @@
+import type Cloudflare from 'cloudflare';
+import type { ZodSchema } from 'zod';
+export interface ProviderContext {
+    readonly cloudflare: Cloudflare;
+    readonly accountId: string;
+    readonly zoneId?: string;
+    readonly namespace: string;
+    readonly managedByLabel: string;
+    readonly signal: AbortSignal;
+    /**
+     * Read a local asset file (Worker entrypoint, etc.). Defaults to fs/promises.readFile.
+     * Tests inject a stub to avoid filesystem coupling.
+     */
+    readonly readFile?: (path: string) => Promise<Uint8Array>;
+}
+export interface ListedResource {
+    readonly nativeId: string;
+    readonly label: string;
+}
+export declare const NotFound: unique symbol;
+export type NotFound = typeof NotFound;
+export type CreateResult = {
+    readonly kind: 'sync';
+    readonly nativeId: string;
+    readonly properties: unknown;
+} | {
+    readonly kind: 'async';
+    readonly nativeId: string;
+    readonly opId: string;
+};
+export type UpdateResult = CreateResult | {
+    readonly kind: 'noop';
+};
+export type DeleteResult = {
+    readonly kind: 'sync';
+} | {
+    readonly kind: 'async';
+    readonly opId: string;
+};
+export type StatusResult = {
+    readonly kind: 'pending';
+} | {
+    readonly kind: 'success';
+    readonly properties: unknown;
+} | {
+    readonly kind: 'failure';
+    readonly error: ProviderError;
+};
+export type ProviderErrorCode = 'Throttling' | 'NotStabilized' | 'NetworkFailure' | 'ServiceInternalError' | 'ServiceTimeout' | 'AccessDenied' | 'NotUpdatable' | 'AlreadyExists' | 'NotFound' | 'InvalidRequest';
+export interface ProviderError {
+    readonly code: ProviderErrorCode;
+    readonly recoverable: boolean;
+    readonly suggest?: 'recreate';
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export declare const RECOVERABLE_CODES: Set<ProviderErrorCode>;
+export declare function isRecoverable(code: ProviderErrorCode): boolean;
+export interface CloudflareResourceProvider<P> {
+    readonly resourceType: string;
+    readonly schema: ZodSchema<P>;
+    list(ctx: ProviderContext): AsyncIterable<ListedResource>;
+    read(ctx: ProviderContext, nativeId: string): Promise<P | NotFound>;
+    create(ctx: ProviderContext, label: string, desired: P): Promise<CreateResult>;
+    update(ctx: ProviderContext, nativeId: string, prior: P, desired: P): Promise<UpdateResult>;
+    delete(ctx: ProviderContext, nativeId: string): Promise<DeleteResult>;
+    status?(ctx: ProviderContext, nativeId: string, opId: string): Promise<StatusResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/providers/types.js

@@ -0,0 +1,12 @@
+export const NotFound = Symbol('NotFound');
+export const RECOVERABLE_CODES = new Set([
+    'Throttling',
+    'NotStabilized',
+    'NetworkFailure',
+    'ServiceInternalError',
+    'ServiceTimeout',
+]);
+export function isRecoverable(code) {
+    return RECOVERABLE_CODES.has(code);
+}
+//# sourceMappingURL=types.js.map

package/dist/providers/vectorize.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { CloudflareResourceProvider } from './types.ts';
+export interface VectorizeProperties {
+    readonly indexName: string;
+    readonly dimensions: number;
+    readonly metric: 'cosine' | 'euclidean' | 'dot-product';
+    readonly description?: string;
+}
+export declare const vectorizePropsSchema: z.ZodType<VectorizeProperties>;
+export declare const vectorizeProvider: CloudflareResourceProvider<VectorizeProperties>;
+//# sourceMappingURL=vectorize.d.ts.map

package/dist/providers/vectorize.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { NotFound } from "./types.js";
+import { toProviderError } from "./errors.js";
+export const vectorizePropsSchema = z.object({
+    indexName: z.string(),
+    dimensions: z.number().int().positive(),
+    metric: z.enum(['cosine', 'euclidean', 'dot-product']),
+    description: z.string().optional(),
+});
+const NAME_PREFIX = 'k1c-';
+function parseLabel(name) {
+    if (!name.startsWith(NAME_PREFIX))
+        return null;
+    const rest = name.slice(NAME_PREFIX.length);
+    const dash = rest.indexOf('-');
+    if (dash <= 0 || dash === rest.length - 1)
+        return null;
+    return `${rest.slice(0, dash)}/${rest.slice(dash + 1)}`;
+}
+export const vectorizeProvider = {
+    resourceType: 'Vectorize',
+    schema: vectorizePropsSchema,
+    async *list(ctx) {
+        let iter;
+        try {
+            iter = ctx.cloudflare.vectorize.indexes.list({ account_id: ctx.accountId });
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+        try {
+            for await (const idx of iter) {
+                const name = idx.name;
+                if (!name)
+                    continue;
+                const label = parseLabel(name);
+                if (label === null)
+                    continue;
+                // Vectorize uses the index name as its identifier; no separate UUID.
+                yield { nativeId: name, label };
+            }
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+    },
+    async read(ctx, nativeId) {
+        try {
+            const idx = await ctx.cloudflare.vectorize.indexes.get(nativeId, {
+                account_id: ctx.accountId,
+            });
+            if (idx === null)
+                return NotFound;
+            const i = idx;
+            if (!i.name || !i.config?.dimensions || !i.config?.metric)
+                return NotFound;
+            return {
+                indexName: i.name,
+                dimensions: i.config.dimensions,
+                metric: i.config.metric,
+                ...(i.description !== undefined ? { description: i.description } : {}),
+            };
+        }
+        catch (raw) {
+            const err = toProviderError(raw);
+            if (err.code === 'NotFound')
+                return NotFound;
+            throw err;
+        }
+    },
+    async create(ctx, _label, desired) {
+        try {
+            const idx = await ctx.cloudflare.vectorize.indexes.create({
+                account_id: ctx.accountId,
+                name: desired.indexName,
+                config: { dimensions: desired.dimensions, metric: desired.metric },
+                ...(desired.description !== undefined ? { description: desired.description } : {}),
+            });
+            const name = idx?.name ?? desired.indexName;
+            return { kind: 'sync', nativeId: name, properties: desired };
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+    },
+    async update(_ctx, _nativeId, prior, desired) {
+        // Vectorize indexes are immutable: dimensions, metric, and name cannot be changed.
+        if (prior.indexName !== desired.indexName ||
+            prior.dimensions !== desired.dimensions ||
+            prior.metric !== desired.metric) {
+            throw {
+                code: 'NotUpdatable',
+                recoverable: false,
+                suggest: 'recreate',
+                message: 'Vectorize index name / dimensions / metric are immutable; recreate to change.',
+            };
+        }
+        return { kind: 'noop' };
+    },
+    async delete(ctx, nativeId) {
+        try {
+            await ctx.cloudflare.vectorize.indexes.delete(nativeId, { account_id: ctx.accountId });
+            return { kind: 'sync' };
+        }
+        catch (raw) {
+            throw toProviderError(raw);
+        }
+    },
+};
+//# sourceMappingURL=vectorize.js.map

package/dist/providers/worker.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+import type { CloudflareResourceProvider } from './types.ts';
+export interface WorkerProperties {
+    readonly scriptName: string;
+    readonly entrypoint: string;
+    readonly compatibilityDate: string;
+    readonly compatibilityFlags?: ReadonlyArray<string>;
+    readonly vars?: Readonly<Record<string, string>>;
+    readonly secrets?: Readonly<Record<string, string>>;
+    readonly bindings?: ReadonlyArray<WorkerBinding>;
+    readonly observability?: {
+        readonly enabled: boolean;
+    };
+    readonly placement?: {
+        readonly mode: 'smart';
+    };
+    /**
+     * If set, the Worker is uploaded to a Workers for Platforms dispatch namespace
+     * (`scripts.update` on the namespace endpoint, no versioned deployment) instead of as a
+     * top-level Worker. Used by canary Rollouts to register the stable / candidate variants.
+     */
+    readonly dispatchNamespace?: string;
+    /**
+     * If set, this string is uploaded as the script body verbatim and `entrypoint` is
+     * ignored for I/O. Used for k1c-generated workers (dispatcher, etc.) whose source is
+     * synthesized in-process rather than read from disk.
+     */
+    readonly entrypointContent?: string;
+    /**
+     * SHA-256 hex of the entrypoint bytes. Computed by lower; round-tripped through
+     * `metadata.tags` as `k1c.io/content-hash=<hash>` so the read path can reconstruct
+     * it from the live script and propertiesEqual catches file-only edits.
+     */
+    readonly entrypointHash?: string;
+    /**
+     * Cron expressions wired to the script via `cloudflare.workers.scripts.schedules`.
+     * Set by lowerCronJob; an empty array (or undefined) means the script has no
+     * cron triggers.
+     */
+    readonly cronSchedules?: ReadonlyArray<string>;
+    /**
+     * Durable Object class names this Worker defines. Lowering a `StatefulSet` populates
+     * this. The Worker provider:
+     *  - emits one `durable_object_namespace` self-binding per class
+     *  - on first deploy (no `k1c.io/do-classes=` tag in prior), declares them via
+     *    `metadata.migrations.new_sqlite_classes`. Adding / removing classes on a
+     *    later apply is **not yet implemented** in v0.2; CF will reject migrations
+     *    that try to redeclare an existing class.
+     */
+    readonly durableObjectClasses?: ReadonlyArray<string>;
+}
+export type WorkerBinding = {
+    readonly type: 'r2_bucket';
+    readonly name: string;
+    readonly bucketName: string;
+} | {
+    readonly type: 'kv_namespace';
+    readonly name: string;
+    readonly namespaceId: string;
+} | {
+    readonly type: 'service';
+    readonly name: string;
+    readonly service: string;
+} | {
+    readonly type: 'dispatch_namespace';
+    readonly name: string;
+    readonly dispatchNamespace: string;
+} | {
+    readonly type: 'hyperdrive';
+    readonly name: string;
+    readonly hyperdriveId: string;
+} | {
+    readonly type: 'd1';
+    readonly name: string;
+    readonly databaseId: string;
+} | {
+    readonly type: 'queue';
+    readonly name: string;
+    readonly queueName: string;
+} | {
+    readonly type: 'durable_object_namespace';
+    readonly name: string;
+    readonly className: string;
+    /** When the DO class lives in another script, set this to that script's name. */
+    readonly scriptName?: string;
+} | {
+    readonly type: 'vectorize';
+    readonly name: string;
+    readonly indexName: string;
+} | {
+    readonly type: 'ai';
+    readonly name: string;
+} | {
+    readonly type: 'browser';
+    readonly name: string;
+} | {
+    readonly type: 'version_metadata';
+    readonly name: string;
+} | {
+    readonly type: 'analytics_engine';
+    readonly name: string;
+    readonly dataset: string;
+};
+export declare const workerSchema: z.ZodType<WorkerProperties>;
+export declare const workerProvider: CloudflareResourceProvider<WorkerProperties>;
+//# sourceMappingURL=worker.d.ts.map