@blokjs/shared 2.1.0 → 2.2.1

package/dist/RuntimeContracts.d.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+/** The JavaScript execution targets that a project may select. */
+export declare const JAVASCRIPT_RUNTIMES: readonly ["node", "bun", "deno"];
+export declare const JavaScriptRuntimeSchema: z.ZodEnum<["node", "bun", "deno"]>;
+export type JavaScriptRuntime = z.infer<typeof JavaScriptRuntimeSchema>;
+/** Package managers are independent from the JavaScript execution target. */
+export declare const PACKAGE_MANAGERS: readonly ["npm", "pnpm", "yarn", "bun"];
+export declare const PackageManagerSchema: z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>;
+export type PackageManager = z.infer<typeof PackageManagerSchema>;
+/** Canonical runtime kinds used by the runner registry and step `type`. */
+export declare const RUNTIME_KINDS: readonly ["nodejs", "bun", "deno", "python3", "kotlin", "go", "java", "rust", "php", "csharp", "ruby", "swift", "dart", "elixir", "docker", "wasm", "wasi"];
+export declare const RuntimeKindSchema: z.ZodEnum<["nodejs", "bun", "deno", "python3", "kotlin", "go", "java", "rust", "php", "csharp", "ruby", "swift", "dart", "elixir", "docker", "wasm", "wasi"]>;
+export type RuntimeKind = z.infer<typeof RuntimeKindSchema>;
+/** Inputs accepted at compatibility boundaries before canonicalization. */
+export declare const RuntimeKindInputSchema: z.ZodEnum<["nodejs", "bun", "deno", "python3", "kotlin", "go", "java", "rust", "php", "csharp", "ruby", "swift", "dart", "elixir", "docker", "wasm", "wasi", "node", "typescript", "ts"]>;
+export type RuntimeKindInput = z.infer<typeof RuntimeKindInputSchema>;
+export type RuntimeDiagnostic = {
+    code: "deprecated-runtime-alias";
+    severity: "warning";
+    input: string;
+    canonical: string;
+    message: string;
+};
+export type RuntimeNormalization = {
+    kind: RuntimeKind;
+    diagnostic?: RuntimeDiagnostic;
+};
+/**
+ * Normalize a runtime kind at a load/registry boundary.
+ *
+ * `runtime.nodejs` is the canonical step spelling. `node`, `typescript`, and
+ * `ts` remain accepted for old workflows and CLI/config bridges, but callers
+ * receive a diagnostic so compatibility never looks like an engine switch.
+ */
+export declare function normalizeRuntimeKind(input: string): RuntimeNormalization;
+/** Normalize the project-level JavaScript selection vocabulary. */
+export declare function normalizeJavaScriptRuntime(input: string): {
+    runtime: JavaScriptRuntime;
+    diagnostic?: RuntimeDiagnostic;
+};
+/** Convert a project selection to the public step/registry kind. */
+export declare function runtimeKindForJavaScriptRuntime(runtime: JavaScriptRuntime): RuntimeKind;
+/** The runtime-specific capability declaration shared by workers and tooling. */
+export declare const RuntimeCapabilityManifestSchema: z.ZodObject<{
+    runtime: z.ZodEnum<["node", "bun", "deno"]>;
+    version: z.ZodString;
+    protocolVersion: z.ZodString;
+    moduleFormats: z.ZodArray<z.ZodEnum<["esm", "commonjs"]>, "many">;
+    typescriptExecution: z.ZodEnum<["native", "transpile", "loader"]>;
+    npmCompatibility: z.ZodEnum<["native", "compatibility", "none"]>;
+    permissions: z.ZodObject<{
+        filesystem: z.ZodEnum<["none", "read", "read-write"]>;
+        network: z.ZodEnum<["none", "restricted", "unrestricted"]>;
+        environment: z.ZodEnum<["none", "declared", "unrestricted"]>;
+        subprocess: z.ZodEnum<["none", "declared", "unrestricted"]>;
+        ffi: z.ZodEnum<["none", "declared", "unrestricted"]>;
+        secrets: z.ZodEnum<["none", "declared"]>;
+    }, "strip", z.ZodTypeAny, {
+        network: "none" | "restricted" | "unrestricted";
+        filesystem: "read" | "none" | "read-write";
+        secrets: "declared" | "none";
+        environment: "declared" | "none" | "unrestricted";
+        subprocess: "declared" | "none" | "unrestricted";
+        ffi: "declared" | "none" | "unrestricted";
+    }, {
+        network: "none" | "restricted" | "unrestricted";
+        filesystem: "read" | "none" | "read-write";
+        secrets: "declared" | "none";
+        environment: "declared" | "none" | "unrestricted";
+        subprocess: "declared" | "none" | "unrestricted";
+        ffi: "declared" | "none" | "unrestricted";
+    }>;
+    cancellation: z.ZodBoolean;
+    streaming: z.ZodBoolean;
+    maxMessageBytes: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    version: string;
+    streaming: boolean;
+    runtime: "node" | "bun" | "deno";
+    protocolVersion: string;
+    moduleFormats: ("esm" | "commonjs")[];
+    typescriptExecution: "native" | "transpile" | "loader";
+    npmCompatibility: "none" | "native" | "compatibility";
+    permissions: {
+        network: "none" | "restricted" | "unrestricted";
+        filesystem: "read" | "none" | "read-write";
+        secrets: "declared" | "none";
+        environment: "declared" | "none" | "unrestricted";
+        subprocess: "declared" | "none" | "unrestricted";
+        ffi: "declared" | "none" | "unrestricted";
+    };
+    cancellation: boolean;
+    maxMessageBytes: number;
+}, {
+    version: string;
+    streaming: boolean;
+    runtime: "node" | "bun" | "deno";
+    protocolVersion: string;
+    moduleFormats: ("esm" | "commonjs")[];
+    typescriptExecution: "native" | "transpile" | "loader";
+    npmCompatibility: "none" | "native" | "compatibility";
+    permissions: {
+        network: "none" | "restricted" | "unrestricted";
+        filesystem: "read" | "none" | "read-write";
+        secrets: "declared" | "none";
+        environment: "declared" | "none" | "unrestricted";
+        subprocess: "declared" | "none" | "unrestricted";
+        ffi: "declared" | "none" | "unrestricted";
+    };
+    cancellation: boolean;
+    maxMessageBytes: number;
+}>;
+export type RuntimeCapabilityManifest = z.infer<typeof RuntimeCapabilityManifestSchema>;
+/** Project configuration fields for JS runtime selection and package policy. */
+export declare const JavaScriptRuntimeSelectionSchema: z.ZodObject<{
+    runtime: z.ZodDefault<z.ZodEnum<["node", "bun", "deno"]>>;
+    packageManager: z.ZodOptional<z.ZodEnum<["npm", "pnpm", "yarn", "bun"]>>;
+}, "strict", z.ZodTypeAny, {
+    runtime: "node" | "bun" | "deno";
+    packageManager?: "bun" | "npm" | "pnpm" | "yarn" | undefined;
+}, {
+    runtime?: "node" | "bun" | "deno" | undefined;
+    packageManager?: "bun" | "npm" | "pnpm" | "yarn" | undefined;
+}>;
+export type JavaScriptRuntimeSelection = z.infer<typeof JavaScriptRuntimeSelectionSchema>;

package/dist/RuntimeContracts.js

@@ -0,0 +1,108 @@
+import { z } from "zod";
+/** The JavaScript execution targets that a project may select. */
+export const JAVASCRIPT_RUNTIMES = ["node", "bun", "deno"];
+export const JavaScriptRuntimeSchema = z.enum(JAVASCRIPT_RUNTIMES);
+/** Package managers are independent from the JavaScript execution target. */
+export const PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
+export const PackageManagerSchema = z.enum(PACKAGE_MANAGERS);
+/** Canonical runtime kinds used by the runner registry and step `type`. */
+export const RUNTIME_KINDS = [
+    "nodejs",
+    "bun",
+    "deno",
+    "python3",
+    "kotlin",
+    "go",
+    "java",
+    "rust",
+    "php",
+    "csharp",
+    "ruby",
+    "swift",
+    "dart",
+    "elixir",
+    "docker",
+    "wasm",
+    "wasi",
+];
+export const RuntimeKindSchema = z.enum(RUNTIME_KINDS);
+/** Inputs accepted at compatibility boundaries before canonicalization. */
+export const RuntimeKindInputSchema = z.enum([...RUNTIME_KINDS, "node", "typescript", "ts"]);
+const RUNTIME_KIND_ALIASES = {
+    node: "nodejs",
+    typescript: "nodejs",
+    ts: "nodejs",
+};
+/**
+ * Normalize a runtime kind at a load/registry boundary.
+ *
+ * `runtime.nodejs` is the canonical step spelling. `node`, `typescript`, and
+ * `ts` remain accepted for old workflows and CLI/config bridges, but callers
+ * receive a diagnostic so compatibility never looks like an engine switch.
+ */
+export function normalizeRuntimeKind(input) {
+    const alias = RUNTIME_KIND_ALIASES[input.toLowerCase()];
+    if (alias) {
+        return {
+            kind: alias,
+            diagnostic: {
+                code: "deprecated-runtime-alias",
+                severity: "warning",
+                input,
+                canonical: alias,
+                message: `Runtime alias "${input}" is deprecated; use "${alias}" for step execution. The selected JavaScript engine is not changed by this compatibility mapping.`,
+            },
+        };
+    }
+    return { kind: RuntimeKindSchema.parse(input) };
+}
+/** Normalize the project-level JavaScript selection vocabulary. */
+export function normalizeJavaScriptRuntime(input) {
+    const normalized = input.toLowerCase();
+    if (normalized === "nodejs" || normalized === "typescript" || normalized === "ts") {
+        return {
+            runtime: "node",
+            diagnostic: {
+                code: "deprecated-runtime-alias",
+                severity: "warning",
+                input,
+                canonical: "node",
+                message: `Project runtime alias "${input}" is deprecated; use "node" in .blok/config.json.`,
+            },
+        };
+    }
+    return { runtime: JavaScriptRuntimeSchema.parse(normalized) };
+}
+/** Convert a project selection to the public step/registry kind. */
+export function runtimeKindForJavaScriptRuntime(runtime) {
+    return runtime === "node" ? "nodejs" : runtime;
+}
+/** The runtime-specific capability declaration shared by workers and tooling. */
+export const RuntimeCapabilityManifestSchema = z
+    .object({
+    runtime: JavaScriptRuntimeSchema,
+    version: z.string().min(1),
+    protocolVersion: z.string().min(1),
+    moduleFormats: z.array(z.enum(["esm", "commonjs"])).min(1),
+    typescriptExecution: z.enum(["native", "transpile", "loader"]),
+    npmCompatibility: z.enum(["native", "compatibility", "none"]),
+    permissions: z.object({
+        filesystem: z.enum(["none", "read", "read-write"]),
+        network: z.enum(["none", "restricted", "unrestricted"]),
+        environment: z.enum(["none", "declared", "unrestricted"]),
+        subprocess: z.enum(["none", "declared", "unrestricted"]),
+        ffi: z.enum(["none", "declared", "unrestricted"]),
+        secrets: z.enum(["none", "declared"]),
+    }),
+    cancellation: z.boolean(),
+    streaming: z.boolean(),
+    maxMessageBytes: z.number().int().positive(),
+})
+    .strict();
+/** Project configuration fields for JS runtime selection and package policy. */
+export const JavaScriptRuntimeSelectionSchema = z
+    .object({
+    runtime: JavaScriptRuntimeSchema.default("node"),
+    packageManager: PackageManagerSchema.optional(),
+})
+    .strict();

package/dist/SecretContracts.d.ts

@@ -0,0 +1,43 @@
+import type { InteractionAttribution, PolicyContext } from "./PolicyContracts.js";
+export declare const SECRET_REFERENCE_VERSION: "1";
+/** An opaque name, never a credential or resolved value. */
+export interface SecretRef {
+    readonly version: typeof SECRET_REFERENCE_VERSION;
+    readonly name: string;
+}
+export interface SecretRequest extends PolicyContext {
+    readonly reference: SecretRef;
+    readonly requestId: string;
+}
+/** A deliberately non-serializable capability for trusted node code. */
+export interface SecretLease {
+    readonly reference: SecretRef;
+    readonly leaseId: string;
+    readonly expiresAt: string;
+    readonly read: () => string;
+}
+export interface SecretResolver {
+    resolve(request: SecretRequest): Promise<SecretLease>;
+}
+export type SecretResolutionFailure = "SECRET_NOT_AUTHORIZED" | "SECRET_NOT_FOUND" | "SECRET_EXPIRED" | "SECRET_REVOKED" | "SECRET_RESOLVER_UNAVAILABLE";
+export interface SecretResolutionAuditEvent {
+    readonly version: "1";
+    readonly eventType: "secret.resolve";
+    readonly eventId: string;
+    readonly timestamp: string;
+    readonly correlationId: string;
+    readonly principalId?: string;
+    readonly sessionId?: string;
+    readonly turnId?: string;
+    readonly attribution?: InteractionAttribution;
+    readonly workflow: PolicyContext["workflow"];
+    readonly step: PolicyContext["step"];
+    readonly reference: SecretRef;
+    readonly leaseId?: string;
+    readonly outcome: "success" | "failure";
+    readonly errorCode?: SecretResolutionFailure;
+    readonly redaction: {
+        readonly redacted: true;
+        readonly fields: readonly ["value"];
+    };
+}

package/dist/SecretContracts.js

@@ -0,0 +1 @@
+export const SECRET_REFERENCE_VERSION = "1";