@zintrust/core 0.7.0 → 0.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/core",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "description": "Production-grade TypeScript backend framework for JavaScript",
   "homepage": "https://zintrust.com",
   "repository": {
@@ -57,19 +57,21 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cloudflare/containers": "^0.3.0",
+    "@cloudflare/containers": "^0.3.2",
     "bcryptjs": "^3.0.3",
-    "bullmq": "^5.73.4",
+    "bullmq": "^5.74.1",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "inquirer": "^13.4.1",
     "jsonwebtoken": "^9.0.3",
-    "mysql2": "^3.22.0",
-    "pg": "^8.20.0"
+    "mysql2": "^3.22.1",
+    "pg": "^8.20.0",
+    "tsx": "^4.21.0"
   },
   "overrides": {
     "ajv": "^8.18.0",
     "axios": "^1.15.0",
+    "@eslint/plugin-kit": "^0.7.1",
     "follow-redirects": "^1.16.0",
     "@tootallnate/once": "^3.0.1",
     "node-forge": "^1.4.0",

package/src/auth/LoginFlow.d.ts

@@ -0,0 +1,65 @@
+import { type JwtPayload } from '../security/JwtManager';
+export type LoginFlowStage = 'identify' | 'verify' | 'issue' | 'audit';
+export type LoginFlowError = Error & {
+    stage: LoginFlowStage;
+    details?: unknown;
+};
+export type LoginFlowIdentity = Record<string, unknown> | null;
+export type LoginFlowVerifiedRecord = {
+    user?: unknown;
+    subject?: string;
+    claims?: JwtPayload;
+    metadata?: Record<string, unknown>;
+};
+export type LoginFlowResult = {
+    identity: LoginFlowIdentity;
+    verified: LoginFlowVerifiedRecord;
+    issued?: unknown;
+};
+export type LoginFlowProvider<TContext = unknown> = {
+    identify: (input: unknown, context: TContext) => Promise<LoginFlowIdentity>;
+    verify: (identity: LoginFlowIdentity, input: unknown, context: TContext) => Promise<LoginFlowVerifiedRecord>;
+};
+export type LoginFlowIssuerInput<TContext = unknown> = {
+    verified: LoginFlowVerifiedRecord;
+    context: TContext;
+};
+export type LoginFlowIssuer<TContext = unknown> = (input: LoginFlowIssuerInput<TContext>) => Promise<unknown>;
+export type LoginFlowAuditEvent<TContext = unknown> = {
+    status: 'success' | 'failed';
+    stage?: LoginFlowStage;
+    provider: string;
+    issuer?: string;
+    identity?: LoginFlowIdentity;
+    verified?: LoginFlowVerifiedRecord;
+    issued?: unknown;
+    error?: unknown;
+    context: TContext;
+};
+export type LoginFlowAuditor<TContext = unknown> = (event: LoginFlowAuditEvent<TContext>) => Promise<void>;
+export type LoginFlowCreateOptions<TContext = unknown> = {
+    provider: string | LoginFlowProvider<TContext>;
+    context: TContext;
+};
+export type LoginFlowBuilder<TContext = unknown> = {
+    identify: (input: unknown) => LoginFlowBuilder<TContext>;
+    verify: (input: unknown) => LoginFlowBuilder<TContext>;
+    issue: (issuer: string | LoginFlowIssuer<TContext>) => LoginFlowBuilder<TContext>;
+    audit: (auditor?: string | LoginFlowAuditor<TContext>) => LoginFlowBuilder<TContext>;
+    run: () => Promise<LoginFlowResult>;
+};
+export type LoginFlowNamespace = {
+    create: <TContext = unknown>(options: LoginFlowCreateOptions<TContext>) => LoginFlowBuilder<TContext>;
+    registerProvider: <TContext = unknown>(name: string, provider: LoginFlowProvider<TContext>) => void;
+    unregisterProvider: (name: string) => void;
+    hasProvider: (name: string) => boolean;
+    registerIssuer: <TContext = unknown>(name: string, issuer: LoginFlowIssuer<TContext>) => void;
+    unregisterIssuer: (name: string) => void;
+    hasIssuer: (name: string) => boolean;
+    registerAuditor: <TContext = unknown>(name: string, auditor: LoginFlowAuditor<TContext>) => void;
+    unregisterAuditor: (name: string) => void;
+    hasAuditor: (name: string) => boolean;
+    clearRegistrations: () => void;
+};
+export declare const LoginFlow: LoginFlowNamespace;
+//# sourceMappingURL=LoginFlow.d.ts.map

package/src/auth/LoginFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LoginFlow.d.ts","sourceRoot":"","sources":["../../../src/auth/LoginFlow.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEnE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG;IACnC,KAAK,EAAE,cAAc,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;AAE/D,MAAM,MAAM,uBAAuB,GAAG;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,iBAAiB,CAAC,QAAQ,GAAG,OAAO,IAAI;IAClD,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC5E,MAAM,EAAE,CACN,QAAQ,EAAE,iBAAiB,EAC3B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,uBAAuB,CAAC,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,QAAQ,GAAG,OAAO,IAAI;IACrD,QAAQ,EAAE,uBAAuB,CAAC;IAClC,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,CAAC,QAAQ,GAAG,OAAO,IAAI,CAChD,KAAK,EAAE,oBAAoB,CAAC,QAAQ,CAAC,KAClC,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,MAAM,mBAAmB,CAAC,QAAQ,GAAG,OAAO,IAAI;IACpD,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,QAAQ,CAAC,EAAE,uBAAuB,CAAC;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,QAAQ,GAAG,OAAO,IAAI,CACjD,KAAK,EAAE,mBAAmB,CAAC,QAAQ,CAAC,KACjC,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,MAAM,sBAAsB,CAAC,QAAQ,GAAG,OAAO,IAAI;IACvD,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC/C,OAAO,EAAE,QAAQ,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,QAAQ,GAAG,OAAO,IAAI;IACjD,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACvD,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,KAAK,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAClF,KAAK,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,KAAK,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IACrF,GAAG,EAAE,MAAM,OAAO,CAAC,eAAe,CAAC,CAAC;CACrC,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,MAAM,EAAE,CAAC,QAAQ,GAAG,OAAO,EACzB,OAAO,EAAE,sBAAsB,CAAC,QAAQ,CAAC,KACtC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAChC,gBAAgB,EAAE,CAAC,QAAQ,GAAG,OAAO,EACnC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,iBAAiB,CAAC,QAAQ,CAAC,KAClC,IAAI,CAAC;IACV,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACvC,cAAc,EAAE,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IAC9F,gBAAgB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACrC,eAAe,EAAE,CAAC,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC;IACjG,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,kBAAkB,EAAE,MAAM,IAAI,CAAC;CAChC,CAAC;AA8cF,eAAO,MAAM,SAAS,EAAE,kBAYtB,CAAC"}

package/src/auth/LoginFlow.js

@@ -0,0 +1,352 @@
+import { SystemTraceBridge } from '../trace/SystemTraceBridge.js';
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { isFunction, isNonEmptyString, isObject } from '../helper/index.js';
+import { JwtManager } from '../security/JwtManager.js';
+const providerRegistry = new Map();
+const issuerRegistry = new Map();
+const auditorRegistry = new Map();
+const createLoginFlowError = (stage, message, details) => {
+    return Object.assign(ErrorFactory.createValidationError(message, details), {
+        stage,
+        details,
+    });
+};
+const isLoginFlowError = (value) => {
+    if (!isObject(value)) {
+        return false;
+    }
+    return isNonEmptyString(value['stage']);
+};
+const getNamedProvider = (name) => {
+    const provider = providerRegistry.get(name);
+    if (!provider) {
+        throw createLoginFlowError('identify', `LoginFlow provider "${name}" is not registered`, {
+            provider: name,
+        });
+    }
+    return provider;
+};
+const getNamedIssuer = (name) => {
+    const issuer = issuerRegistry.get(name);
+    if (!issuer) {
+        throw createLoginFlowError('issue', `LoginFlow issuer "${name}" is not registered`, {
+            issuer: name,
+        });
+    }
+    return issuer;
+};
+const getNamedAuditor = (name) => {
+    const auditor = auditorRegistry.get(name);
+    if (!auditor) {
+        throw createLoginFlowError('audit', `LoginFlow auditor "${name}" is not registered`, {
+            auditor: name,
+        });
+    }
+    return auditor;
+};
+const resolveProvider = (provider) => {
+    if (typeof provider === 'string') {
+        return getNamedProvider(provider);
+    }
+    return provider;
+};
+const resolveProviderName = (provider) => {
+    if (typeof provider === 'string') {
+        return provider;
+    }
+    return 'inline';
+};
+const resolveIssuer = (issuer) => {
+    if (typeof issuer === 'string') {
+        return getNamedIssuer(issuer);
+    }
+    return issuer;
+};
+const resolveIssuerName = (issuer) => {
+    if (typeof issuer === 'string') {
+        return issuer;
+    }
+    return 'inline';
+};
+const resolveAuditor = (auditor) => {
+    if (typeof auditor === 'string') {
+        return getNamedAuditor(auditor);
+    }
+    return auditor;
+};
+const normalizeVerifiedRecord = (value) => {
+    if (!isObject(value)) {
+        throw createLoginFlowError('verify', 'LoginFlow verify() must return an object', { value });
+    }
+    const record = value;
+    if (record.subject !== undefined && !isNonEmptyString(record.subject)) {
+        throw createLoginFlowError('verify', 'LoginFlow verify() returned an invalid subject', {
+            subject: record.subject,
+        });
+    }
+    if (record.claims !== undefined && !isObject(record.claims)) {
+        throw createLoginFlowError('verify', 'LoginFlow verify() returned invalid claims', {
+            claims: record.claims,
+        });
+    }
+    return record;
+};
+const createJwtIssuer = async ({ verified, }) => {
+    const claims = isObject(verified.claims) ? { ...verified.claims } : {};
+    if (isNonEmptyString(verified.subject) && !isNonEmptyString(claims.sub)) {
+        claims.sub = verified.subject;
+    }
+    return JwtManager.signAccessToken(claims);
+};
+const createTraceAuditor = async (event) => {
+    const subject = typeof event.verified?.subject === 'string' && event.verified.subject.trim() !== ''
+        ? event.verified.subject
+        : undefined;
+    SystemTraceBridge.emitAuth(event.status === 'success' ? 'login' : 'failed', subject);
+    return Promise.resolve();
+};
+const ensureNamedRegistration = (kind, name) => {
+    if (!isNonEmptyString(name)) {
+        throw createLoginFlowError('identify', `LoginFlow ${kind} name must be a non-empty string`, {
+            name,
+            kind,
+        });
+    }
+};
+const ensureProvider = (provider) => {
+    if (!isObject(provider) || !isFunction(provider['identify']) || !isFunction(provider['verify'])) {
+        throw createLoginFlowError('identify', 'LoginFlow provider must expose identify() and verify()', {
+            provider,
+        });
+    }
+};
+const ensureHandler = (stage, kind, handler) => {
+    if (!isFunction(handler)) {
+        throw createLoginFlowError(stage, `LoginFlow ${kind} must be a function`, {
+            handler,
+        });
+    }
+};
+const auditFailureIfNeeded = async (auditorTarget, event) => {
+    if (auditorTarget === undefined) {
+        return;
+    }
+    const auditor = resolveAuditor(auditorTarget);
+    await auditor(event);
+};
+const ensureRequiredInputs = (state) => {
+    if (!state.identifySet) {
+        throw createLoginFlowError('identify', 'LoginFlow identify() must be called before run()', {
+            provider: state.providerName,
+        });
+    }
+    if (!state.verifySet) {
+        throw createLoginFlowError('verify', 'LoginFlow verify() must be called before run()', {
+            provider: state.providerName,
+        });
+    }
+};
+const resolveProviderWithAudit = async (state) => {
+    try {
+        return resolveProvider(state.options.provider);
+    }
+    catch (error) {
+        const wrapped = isLoginFlowError(error)
+            ? error
+            : createLoginFlowError('identify', 'LoginFlow identify() failed', {
+                provider: state.providerName,
+                error,
+            });
+        await auditFailureIfNeeded(state.auditorTarget, {
+            status: 'failed',
+            stage: 'identify',
+            provider: state.providerName,
+            context: state.options.context,
+            error: wrapped,
+        });
+        throw wrapped;
+    }
+};
+const identifyWithAudit = async (state, provider) => {
+    try {
+        return await provider.identify(state.identifyInput, state.options.context);
+    }
+    catch (error) {
+        const wrapped = createLoginFlowError('identify', 'LoginFlow identify() failed', {
+            provider: state.providerName,
+            error,
+        });
+        await auditFailureIfNeeded(state.auditorTarget, {
+            status: 'failed',
+            stage: 'identify',
+            provider: state.providerName,
+            context: state.options.context,
+            error: wrapped,
+        });
+        throw wrapped;
+    }
+};
+const verifyWithAudit = async (state, provider, identity) => {
+    try {
+        return normalizeVerifiedRecord(await provider.verify(identity, state.verifyInput, state.options.context));
+    }
+    catch (error) {
+        const wrapped = isLoginFlowError(error)
+            ? error
+            : createLoginFlowError('verify', 'LoginFlow verify() failed', {
+                provider: state.providerName,
+                error,
+            });
+        await auditFailureIfNeeded(state.auditorTarget, {
+            status: 'failed',
+            stage: 'verify',
+            provider: state.providerName,
+            identity,
+            context: state.options.context,
+            error: wrapped,
+        });
+        throw wrapped;
+    }
+};
+const issueWithAudit = async (state, identity, verified) => {
+    if (state.issueTarget === undefined) {
+        return undefined;
+    }
+    const issuer = resolveIssuer(state.issueTarget);
+    try {
+        return await issuer({ verified, context: state.options.context });
+    }
+    catch (error) {
+        const wrapped = createLoginFlowError('issue', 'LoginFlow issue() failed', {
+            provider: state.providerName,
+            issuer: state.issueName,
+            error,
+        });
+        await auditFailureIfNeeded(state.auditorTarget, {
+            status: 'failed',
+            stage: 'issue',
+            provider: state.providerName,
+            issuer: state.issueName,
+            identity,
+            verified,
+            context: state.options.context,
+            error: wrapped,
+        });
+        throw wrapped;
+    }
+};
+const auditSuccess = async (state, identity, verified, issued) => {
+    if (state.auditorTarget === undefined) {
+        return;
+    }
+    const auditor = resolveAuditor(state.auditorTarget);
+    await auditor({
+        status: 'success',
+        provider: state.providerName,
+        issuer: state.issueName,
+        identity,
+        verified,
+        issued,
+        context: state.options.context,
+    });
+};
+const runLoginFlow = async (state) => {
+    const provider = await resolveProviderWithAudit(state);
+    ensureRequiredInputs(state);
+    const identity = await identifyWithAudit(state, provider);
+    const verified = await verifyWithAudit(state, provider, identity);
+    const issued = await issueWithAudit(state, identity, verified);
+    await auditSuccess(state, identity, verified, issued);
+    return {
+        identity,
+        verified,
+        ...(issued === undefined ? {} : { issued }),
+    };
+};
+const createBuilder = (state) => {
+    return Object.freeze({
+        identify(input) {
+            state.identifyInput = input;
+            state.identifySet = true;
+            return this;
+        },
+        verify(input) {
+            state.verifyInput = input;
+            state.verifySet = true;
+            return this;
+        },
+        issue(issuer) {
+            state.issueTarget = issuer;
+            state.issueName = resolveIssuerName(issuer);
+            return this;
+        },
+        audit(auditor) {
+            state.auditorTarget = auditor ?? 'trace';
+            return this;
+        },
+        async run() {
+            return runLoginFlow(state);
+        },
+    });
+};
+const create = (options) => {
+    return createBuilder({
+        options,
+        providerName: resolveProviderName(options.provider),
+        identifyInput: undefined,
+        verifyInput: undefined,
+        issueTarget: undefined,
+        issueName: undefined,
+        auditorTarget: undefined,
+        identifySet: false,
+        verifySet: false,
+    });
+};
+const registerProvider = (name, provider) => {
+    ensureNamedRegistration('provider', name);
+    ensureProvider(provider);
+    providerRegistry.set(name, provider);
+};
+const unregisterProvider = (name) => {
+    providerRegistry.delete(name);
+};
+const hasProvider = (name) => providerRegistry.has(name);
+const registerIssuer = (name, issuer) => {
+    ensureNamedRegistration('issuer', name);
+    ensureHandler('issue', 'issuer', issuer);
+    issuerRegistry.set(name, issuer);
+};
+const unregisterIssuer = (name) => {
+    issuerRegistry.delete(name);
+};
+const hasIssuer = (name) => issuerRegistry.has(name);
+const registerAuditor = (name, auditor) => {
+    ensureNamedRegistration('auditor', name);
+    ensureHandler('audit', 'auditor', auditor);
+    auditorRegistry.set(name, auditor);
+};
+const unregisterAuditor = (name) => {
+    auditorRegistry.delete(name);
+};
+const hasAuditor = (name) => auditorRegistry.has(name);
+const clearRegistrations = () => {
+    providerRegistry.clear();
+    issuerRegistry.clear();
+    auditorRegistry.clear();
+    issuerRegistry.set('jwt', createJwtIssuer);
+    auditorRegistry.set('trace', createTraceAuditor);
+};
+clearRegistrations();
+export const LoginFlow = Object.freeze({
+    create,
+    registerProvider,
+    unregisterProvider,
+    hasProvider,
+    registerIssuer,
+    unregisterIssuer,
+    hasIssuer,
+    registerAuditor,
+    unregisterAuditor,
+    hasAuditor,
+    clearRegistrations,
+});

package/src/cache/drivers/KVRemoteDriver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"KVRemoteDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/KVRemoteDriver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAqYtD,eAAO,MAAM,cAAc;kBAtFM,WAAW;EAwF1C,CAAC;AAEH,eAAe,cAAc,CAAC"}
+{"version":3,"file":"KVRemoteDriver.d.ts","sourceRoot":"","sources":["../../../../src/cache/drivers/KVRemoteDriver.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AA6YtD,eAAO,MAAM,cAAc;kBAvEM,WAAW;EAyE1C,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/cache/drivers/KVRemoteDriver.js

@@ -206,6 +206,25 @@ const createCloudflareKvApiClient = (resolveNamespaceId) => {
     };
     return { getJson, putJson, deleteKey };
 };
+const logKvRemoteProxyFallback = (operation, error) => {
+    Logger.warn(`KV remote proxy ${operation} failed; falling back to Cloudflare KV API`, Logger.withTraceSkipContext({
+        error: error instanceof Error ? error.message : String(error),
+    }));
+};
+const clearKvRemoteDriver = async () => {
+    Logger.warn('KV remote clear() is not implemented.');
+    await Promise.resolve();
+};
+const createKvRemoteHas = (getJson) => {
+    return async function has(key) {
+        if (!hasCloudflareApiCreds())
+            return (await this.get(key)) !== null;
+        const settings = getSettings();
+        if (!hasProxySigningCreds(settings))
+            return (await getJson(key)) !== null;
+        return (await this.get(key)) !== null;
+    };
+};
 const createKvRemoteDriver = () => {
     const resolveNamespaceId = createCloudflareNamespaceIdResolver();
     const cf = createCloudflareKvApiClient(resolveNamespaceId);
@@ -226,9 +245,7 @@ const createKvRemoteDriver = () => {
             catch (error) {
                 if (!hasCloudflareApiCreds())
                     throw error;
-                Logger.warn('KV remote proxy GET failed; falling back to Cloudflare KV API', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                logKvRemoteProxyFallback('GET', error);
                 return cf.getJson(key);
             }
         },
@@ -250,9 +267,7 @@ const createKvRemoteDriver = () => {
             catch (error) {
                 if (!hasCloudflareApiCreds())
                     throw error;
-                Logger.warn('KV remote proxy PUT failed; falling back to Cloudflare KV API', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                logKvRemoteProxyFallback('PUT', error);
                 await cf.putJson(key, value, ttl);
             }
         },
@@ -272,24 +287,12 @@ const createKvRemoteDriver = () => {
             catch (error) {
                 if (!hasCloudflareApiCreds())
                     throw error;
-                Logger.warn('KV remote proxy DELETE failed; falling back to Cloudflare KV API', {
-                    error: error instanceof Error ? error.message : String(error),
-                });
+                logKvRemoteProxyFallback('DELETE', error);
                 await cf.deleteKey(key);
             }
         },
-        async clear() {
-            Logger.warn('KV remote clear() is not implemented.');
-            await Promise.resolve();
-        },
-        async has(key) {
-            if (!hasCloudflareApiCreds())
-                return (await this.get(key)) !== null;
-            const settings = getSettings();
-            if (!hasProxySigningCreds(settings))
-                return (await cf.getJson(key)) !== null;
-            return (await this.get(key)) !== null;
-        },
+        clear: clearKvRemoteDriver,
+        has: createKvRemoteHas(cf.getJson),
     };
 };
 export const KVRemoteDriver = Object.freeze({

package/src/cli/commands/ScheduleListCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleListCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleListCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0ErE,eAAO,MAAM,mBAAmB;cACpB,YAAY;EAUtB,CAAC;AAEH,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"ScheduleListCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleListCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA8ErE,eAAO,MAAM,mBAAmB;cACpB,YAAY;EAUtB,CAAC;AAEH,eAAe,mBAAmB,CAAC"}

package/src/cli/commands/ScheduleListCommand.js

@@ -3,6 +3,9 @@ import { ScheduleCliSupport } from '../commands/schedule/ScheduleCliSupport.js';
 import { Logger } from '../../config/logger.js';
 import { SchedulerRuntime } from '../../scheduler/SchedulerRuntime.js';
 const execute = async (options) => {
+    if (await ScheduleCliSupport.ensureProjectSourceContext()) {
+        return;
+    }
     try {
         await ScheduleCliSupport.registerAll();
         const toIso = (ms) => typeof ms === 'number' && Number.isFinite(ms) ? new Date(ms).toISOString() : undefined;

package/src/cli/commands/ScheduleRunCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleRunCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleRunCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA0BrE,eAAO,MAAM,kBAAkB;cACnB,YAAY;EAUtB,CAAC;AAEH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"ScheduleRunCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleRunCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA8BrE,eAAO,MAAM,kBAAkB;cACnB,YAAY;EAUtB,CAAC;AAEH,eAAe,kBAAkB,CAAC"}

package/src/cli/commands/ScheduleRunCommand.js

@@ -7,6 +7,9 @@ const execute = async (options) => {
     const name = (options.name ?? '').trim();
     if (name.length === 0)
         throw ErrorFactory.createConfigError('--name is required');
+    if (await ScheduleCliSupport.ensureProjectSourceContext()) {
+        return;
+    }
     try {
         await ScheduleCliSupport.registerAll();
         Logger.info('Running schedule once', { name });

package/src/cli/commands/ScheduleStartCommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleStartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleStartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AA6CrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAOtB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}
+{"version":3,"file":"ScheduleStartCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/ScheduleStartCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAiDrE,eAAO,MAAM,oBAAoB;cACrB,YAAY;EAOtB,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/src/cli/commands/ScheduleStartCommand.js

@@ -18,6 +18,9 @@ const execute = async (_options) => {
         Logger.info('Schedules are disabled (SCHEDULES_ENABLED=false); exiting');
         return;
     }
+    if (await ScheduleCliSupport.ensureProjectSourceContext()) {
+        return;
+    }
     await ScheduleCliSupport.registerAll();
     const registeredCount = SchedulerRuntime.list().length;
     Logger.info('Starting schedules daemon', { registeredCount });

package/src/cli/commands/schedule/ScheduleCliSupport.d.ts

@@ -1,4 +1,5 @@
 export declare const ScheduleCliSupport: Readonly<{
+    ensureProjectSourceContext: () => Promise<boolean>;
     registerAll(): Promise<void>;
     shutdownCliResources: () => Promise<void>;
 }>;

package/src/cli/commands/schedule/ScheduleCliSupport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ScheduleCliSupport.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/schedule/ScheduleCliSupport.ts"],"names":[],"mappings":"AAwDA,eAAO,MAAM,kBAAkB;mBACR,OAAO,CAAC,IAAI,CAAC;gCA1BG,OAAO,CAAC,IAAI,CAAC;EAmClD,CAAC;AAEH,eAAe,kBAAkB,CAAC"}
+{"version":3,"file":"ScheduleCliSupport.d.ts","sourceRoot":"","sources":["../../../../../src/cli/commands/schedule/ScheduleCliSupport.ts"],"names":[],"mappings":"AAsMA,eAAO,MAAM,kBAAkB;sCA1Ec,OAAO,CAAC,OAAO,CAAC;mBA4EtC,OAAO,CAAC,IAAI,CAAC;gCA3BG,OAAO,CAAC,IAAI,CAAC;EAqClD,CAAC;AAEH,eAAe,kBAAkB,CAAC"}