Track HiveGrid Cloud planning reference

This commit is contained in:
david committed 2026-06-26 20:48:01 +02:00
1 parent b3d5ea6764
commit e341c5938a
5784 files changed
+1104929 -3

No files matched your search

@@ -0,0 +1,186 @@
import { describe, expect, it, vi } from "vitest";
import { DefaultFeatures } from "~/application/dtos/shared/DefaultFeatures";
import {
evaluateOnboardingStepGates,
getOnboardingStepDiagnostics,
getVisibleOnboardingSteps,
type OnboardingStepGateDiagnostic,
} from "./gating.server";
import type { OnboardingRegisteredStepDefinition } from "./registry.server";
const request = new Request("https://app.example.com/acme/onboarding?tenantId=tenant_123&token=secret-token");
const params = { tenant: "acme", tenantId: "tenant_123" };
const profileStep = {
id: "profile-basics",
title: "Profile basics",
description: "Ungated profile setup",
} as const satisfies OnboardingRegisteredStepDefinition;
const featureStep = {
id: "team-invites",
title: "Team invites",
description: "Feature gated team invites",
featureFlagKey: "workspace-roles",
} as const satisfies OnboardingRegisteredStepDefinition;
const planStep = {
id: "priority-support-setup",
title: "Priority support setup",
description: "Plan gated priority support",
planFeatureKey: DefaultFeatures.PrioritySupport,
} as const satisfies OnboardingRegisteredStepDefinition;
function entitlementService(allowed: boolean) {
return vi.fn(() => ({
allowed,
reason: allowed ? ("included" as const) : ("missing-subscription" as const),
featureKey: DefaultFeatures.PrioritySupport,
}));
}
const sensitiveSamples = [
"tenant_123",
"secret-token",
"user_456",
"subscription_789",
"provider_api_key_live",
"raw-feature-input=workspace-roles",
"DATABASE_URL",
"bearer jwt-token",
] as const;
function expectSafeStaticPayload(payload: unknown) {
const serialized = JSON.stringify(payload);
for (const sample of sensitiveSamples) {
expect(serialized).not.toContain(sample);
}
expect(serialized).not.toMatch(/user[_-]?\d+|subscription[_-]?\d+|provider[_-]?api[_-]?key|bearer\s+jwt|jwt-token|secret-token/i);
}
function expectDiagnosticsRedacted(diagnostics: readonly OnboardingStepGateDiagnostic[]) {
expectSafeStaticPayload(diagnostics);
}
describe("evaluateOnboardingStepGates", () => {
it("returns visible onboarding steps when all gates allow access", async () => {
const hasFeatureFlag = vi.fn(async () => true);
const evaluateSubscriptionEntitlement = entitlementService(true);
const decisions = await evaluateOnboardingStepGates({
request,
params,
definitions: [profileStep, featureStep, planStep],
services: {
hasFeatureFlag,
evaluateSubscriptionEntitlement,
},
});
expect(getVisibleOnboardingSteps(decisions).map((step) => step.id)).toEqual(["profile-basics", "team-invites", "priority-support-setup"]);
expect(getOnboardingStepDiagnostics(decisions)).toEqual([]);
expect(hasFeatureFlag).toHaveBeenCalledWith({ request, params, flagName: "workspace-roles" });
expect(evaluateSubscriptionEntitlement).toHaveBeenCalledWith({
featureKey: DefaultFeatures.PrioritySupport,
subscription: undefined,
trial: undefined,
});
});
it("denies only a disabled feature-flagged onboarding step", async () => {
const decisions = await evaluateOnboardingStepGates({
request,
params,
definitions: [profileStep, featureStep, planStep],
services: {
hasFeatureFlag: vi.fn(async () => false),
evaluateSubscriptionEntitlement: entitlementService(true),
},
});
expect(getVisibleOnboardingSteps(decisions).map((step) => step.id)).toEqual(["profile-basics", "priority-support-setup"]);
expect(getOnboardingStepDiagnostics(decisions)).toEqual([
{
stepId: "team-invites",
source: "feature-flag",
reason: "feature-disabled",
redirectPath: "/feature-disabled",
},
]);
});
it("denies only the feature-gated onboarding step when feature lookup fails", async () => {
const decisions = await evaluateOnboardingStepGates({
request,
params,
definitions: [profileStep, featureStep],
services: {
hasFeatureFlag: vi.fn(async () => {
throw new Error("backend unavailable for tenant_123 with token secret-token and provider_api_key_live");
}),
},
});
expect(getVisibleOnboardingSteps(decisions).map((step) => step.id)).toEqual(["profile-basics"]);
expect(getOnboardingStepDiagnostics(decisions)).toEqual([
{
stepId: "team-invites",
source: "feature-flag",
reason: "feature-check-failed",
redirectPath: "/feature-disabled",
},
]);
expectDiagnosticsRedacted(getOnboardingStepDiagnostics(decisions));
});
it("denies missing plan entitlement with plan-required diagnostics", async () => {
const evaluateSubscriptionEntitlement = entitlementService(false);
const decisions = await evaluateOnboardingStepGates({
request,
params,
definitions: [profileStep, planStep],
subscription: { products: [] },
services: {
evaluateSubscriptionEntitlement,
},
});
expect(getVisibleOnboardingSteps(decisions).map((step) => step.id)).toEqual(["profile-basics"]);
expect(getOnboardingStepDiagnostics(decisions)).toEqual([
{
stepId: "priority-support-setup",
source: "plan",
reason: "plan-required",
redirectPath: "plan-required",
},
]);
expect(evaluateSubscriptionEntitlement).toHaveBeenCalledWith({
featureKey: DefaultFeatures.PrioritySupport,
subscription: { products: [] },
trial: undefined,
});
});
it("keeps denied diagnostics redacted from tenant, subscription, user, token, and raw gate inputs", async () => {
const decisions = await evaluateOnboardingStepGates({
request,
params,
definitions: [featureStep, planStep],
subscription: { products: [] },
services: {
hasFeatureFlag: vi.fn(async () => false),
evaluateSubscriptionEntitlement: entitlementService(false),
},
redirectPaths: {
"feature-flag": "/feature-disabled",
plan: "plan-required",
},
});
expect(getOnboardingStepDiagnostics(decisions)).toEqual([
expect.objectContaining({ stepId: "team-invites", source: "feature-flag", reason: "feature-disabled" }),
expect.objectContaining({ stepId: "priority-support-setup", source: "plan", reason: "plan-required" }),
]);
expectDiagnosticsRedacted(getOnboardingStepDiagnostics(decisions));
});
});
@@ -0,0 +1,199 @@
import type { Params } from "react-router";
import type { EntitlementDecision } from "@toolctrl/entitlements";
import type {
SubscriptionEntitlementSubscription,
SubscriptionEntitlementTrialState,
} from "~/utils/entitlements/.server/subscriptionEntitlements.server";
import { evaluateSubscriptionEntitlement as defaultEvaluateSubscriptionEntitlement } from "~/utils/entitlements/.server/subscriptionEntitlements.server";
import { isFeatureFlagEnabled } from "~/utils/services/.server/featureFlagsRequest.server";
import { getOnboardingStepDefinitions, type OnboardingRegisteredStepDefinition, type OnboardingRegisteredStepId } from "./registry.server";
export type OnboardingStepGateSource = "feature-flag" | "plan";
export type OnboardingStepGateReason = "feature-disabled" | "feature-check-failed" | "plan-required";
export interface OnboardingStepGateDiagnostic {
readonly stepId: OnboardingRegisteredStepId;
readonly source: OnboardingStepGateSource;
readonly reason: OnboardingStepGateReason;
readonly redirectPath?: string;
}
export interface OnboardingStepGateDecision {
readonly step: OnboardingRegisteredStepDefinition;
readonly allowed: boolean;
readonly diagnostic?: OnboardingStepGateDiagnostic;
}
export interface EvaluateOnboardingStepGatesInput {
readonly request: Request;
readonly params: Params;
readonly subscription?: SubscriptionEntitlementSubscription | null;
readonly trial?: SubscriptionEntitlementTrialState | null;
readonly definitions?: readonly OnboardingRegisteredStepDefinition[];
readonly redirectPaths?: Partial<Record<OnboardingStepGateSource, string>>;
readonly services?: OnboardingStepGateServices;
readonly serviceLoaders?: OnboardingStepGateServiceLoaders;
}
export interface OnboardingStepGateServices {
/**
* Boolean feature-flag check shimmed against the v2 evaluator
* (`isFeatureFlagEnabled`). Callers may inject a stub for tests;
* production wiring resolves the request + tenant context inside
* the v2 helper.
*/
readonly hasFeatureFlag?: (input: { request: Request; params: Params; flagName: string }) => Promise<boolean>;
readonly evaluateSubscriptionEntitlement?: (input: {
featureKey: string;
subscription?: SubscriptionEntitlementSubscription | null;
trial?: SubscriptionEntitlementTrialState | null;
}) => EntitlementDecision;
}
export interface OnboardingStepGateServiceLoaders {
readonly featureFlags?: () => Promise<Pick<Required<OnboardingStepGateServices>, "hasFeatureFlag">>;
readonly entitlements?: () => Promise<Pick<Required<OnboardingStepGateServices>, "evaluateSubscriptionEntitlement">>;
}
const defaultRedirectPaths = Object.freeze({
"feature-flag": "/feature-disabled",
plan: "plan-required",
} satisfies Record<OnboardingStepGateSource, string>);
function diagnostic(input: {
stepId: OnboardingRegisteredStepId;
source: OnboardingStepGateSource;
reason: OnboardingStepGateReason;
redirectPath?: string;
}): OnboardingStepGateDiagnostic {
return {
stepId: input.stepId,
source: input.source,
reason: input.reason,
...(input.redirectPath ? { redirectPath: input.redirectPath } : {}),
};
}
async function evaluateOnboardingStepGate({
step,
request,
params,
subscription,
trial,
redirectPaths,
services,
serviceLoaders,
}: Omit<EvaluateOnboardingStepGatesInput, "definitions"> & { step: OnboardingRegisteredStepDefinition }): Promise<OnboardingStepGateDecision> {
if (step.featureFlagKey) {
try {
if (!services?.hasFeatureFlag) {
const featureFlagService = serviceLoaders?.featureFlags
? await serviceLoaders.featureFlags()
: { hasFeatureFlag: ({ request: req, params: p, flagName }: { request: Request; params: Params; flagName: string }) => isFeatureFlagEnabled(flagName, { request: req, params: p }) };
services = { ...services, hasFeatureFlag: featureFlagService.hasFeatureFlag };
}
const hasFeatureFlag = services.hasFeatureFlag;
if (!hasFeatureFlag) {
throw new Error("Onboarding feature flag service unavailable");
}
const enabled = await hasFeatureFlag({
request,
params,
flagName: step.featureFlagKey,
});
if (!enabled) {
return {
step,
allowed: false,
diagnostic: diagnostic({
stepId: step.id,
source: "feature-flag",
reason: "feature-disabled",
redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"],
}),
};
}
} catch {
return {
step,
allowed: false,
diagnostic: diagnostic({
stepId: step.id,
source: "feature-flag",
reason: "feature-check-failed",
redirectPath: redirectPaths?.["feature-flag"] ?? defaultRedirectPaths["feature-flag"],
}),
};
}
}
if (step.planFeatureKey) {
if (!services?.evaluateSubscriptionEntitlement) {
const entitlementService = serviceLoaders?.entitlements
? await serviceLoaders.entitlements()
: { evaluateSubscriptionEntitlement: defaultEvaluateSubscriptionEntitlement };
services = { ...services, evaluateSubscriptionEntitlement: entitlementService.evaluateSubscriptionEntitlement };
}
const evaluateSubscriptionEntitlement = services.evaluateSubscriptionEntitlement;
if (!evaluateSubscriptionEntitlement) {
throw new Error("Onboarding entitlement service unavailable");
}
const entitlement = evaluateSubscriptionEntitlement({
featureKey: step.planFeatureKey,
subscription,
trial,
});
if (!entitlement.allowed) {
return {
step,
allowed: false,
diagnostic: diagnostic({
stepId: step.id,
source: "plan",
reason: "plan-required",
redirectPath: redirectPaths?.plan ?? defaultRedirectPaths.plan,
}),
};
}
}
return { step, allowed: true };
}
export async function evaluateOnboardingStepGates({
request,
params,
subscription,
trial,
definitions = getOnboardingStepDefinitions(),
redirectPaths,
services,
serviceLoaders,
}: EvaluateOnboardingStepGatesInput): Promise<OnboardingStepGateDecision[]> {
return Promise.all(
definitions.map((step) =>
evaluateOnboardingStepGate({
step,
request,
params,
subscription,
trial,
redirectPaths,
services,
serviceLoaders,
}),
),
);
}
export function getVisibleOnboardingSteps(decisions: readonly OnboardingStepGateDecision[]): OnboardingRegisteredStepDefinition[] {
return decisions.filter((decision) => decision.allowed).map((decision) => decision.step);
}
export function getOnboardingStepDiagnostics(decisions: readonly OnboardingStepGateDecision[]): OnboardingStepGateDiagnostic[] {
return decisions.flatMap((decision) => (decision.diagnostic ? [decision.diagnostic] : []));
}
@@ -0,0 +1,79 @@
import { describe, expect, it } from "vitest";
import { DefaultFeatures } from "~/application/dtos/shared/DefaultFeatures";
import { readRepoFile } from "~/utils/testing/repoPaths";
import { getOnboardingStepDefinitions, onboardingStepRegistryEvidence } from "./registry.server";
const sensitiveSamples = [
"tenant_123",
"secret-token",
"user_456",
"subscription_789",
"provider_api_key_live",
"raw-feature-input=workspace-roles",
"DATABASE_URL",
"bearer jwt-token",
] as const;
function expectSafeStaticPayload(payload: unknown) {
const serialized = JSON.stringify(payload);
for (const sample of sensitiveSamples) {
expect(serialized).not.toContain(sample);
}
expect(serialized).not.toMatch(/user[_-]?\d+|subscription[_-]?\d+|provider[_-]?api[_-]?key|bearer\s+jwt|jwt-token|secret-token/i);
}
describe("onboarding step registry", () => {
it("defines stable onboarding step IDs for ungated, feature-gated, and plan-gated steps", () => {
expect(getOnboardingStepDefinitions()).toEqual(
expect.arrayContaining([
expect.objectContaining({ id: "profile-basics" }),
expect.objectContaining({ id: "team-invites", featureFlagKey: "workspace-roles" }),
expect.objectContaining({ id: "priority-support-setup", planFeatureKey: DefaultFeatures.PrioritySupport }),
]),
);
});
it("exports registry evidence that mirrors stable IDs and represented gate sources", () => {
const definitions = getOnboardingStepDefinitions();
expect(onboardingStepRegistryEvidence.registryName).toBe("Onboarding Step Registry");
expect(onboardingStepRegistryEvidence.registryScope).toBe("source-backed-onboarding-steps");
expect(onboardingStepRegistryEvidence.expectedStepIds).toEqual(definitions.map((step) => step.id));
expect(onboardingStepRegistryEvidence.expectedStepIds).toEqual(["profile-basics", "team-invites", "priority-support-setup"]);
expect(onboardingStepRegistryEvidence.gatingSourcesRepresented).toEqual(["feature-flag", "plan"]);
});
it("keeps gate metadata typed and attached only to gated steps", () => {
const definitions = getOnboardingStepDefinitions();
expect(definitions.find((step) => step.id === "profile-basics")).toEqual(expect.not.objectContaining({ featureFlagKey: expect.any(String) }));
expect(definitions.find((step) => step.id === "profile-basics")).toEqual(expect.not.objectContaining({ planFeatureKey: expect.any(String) }));
expect(definitions.find((step) => step.id === "team-invites")).toEqual(expect.objectContaining({ featureFlagKey: "workspace-roles" }));
expect(definitions.find((step) => step.id === "priority-support-setup")).toEqual(
expect.objectContaining({ planFeatureKey: DefaultFeatures.PrioritySupport }),
);
});
it("keeps registry evidence limited to safe static metadata without sensitive samples", () => {
expect(onboardingStepRegistryEvidence.redactionGuarantee).toContain("static source metadata only");
expect(onboardingStepRegistryEvidence.redactionGuarantee).toContain(
"excludes request, tenant, subscription, user, token, environment, and raw feature input values",
);
expect(onboardingStepRegistryEvidence.expectedStepIds.length).toBe(getOnboardingStepDefinitions().length);
expectSafeStaticPayload(onboardingStepRegistryEvidence);
});
it("keeps registry copy behind semantic onboarding keys", () => {
const source = readRepoFile("apps/web/app/modules/onboarding/services/step-registry/registry.server.ts");
expect(source).toContain("onboarding.stepRegistry.profileBasics.title");
expect(source).toContain("onboarding.stepRegistry.profileBasics.description");
expect(source).toContain("onboarding.stepRegistry.teamInvites.title");
expect(source).toContain("onboarding.stepRegistry.teamInvites.description");
expect(source).toContain("onboarding.stepRegistry.prioritySupportSetup.title");
expect(source).toContain("onboarding.stepRegistry.prioritySupportSetup.description");
expect(source).not.toContain("ui.autogenerated");
});
});
@@ -0,0 +1,49 @@
import { DefaultFeatures } from "~/application/dtos/shared/DefaultFeatures";
import type { FeatureFlagsFilterType } from "~/modules/featureFlags/dtos/FeatureFlagsFilterTypes";
import { t as i18nT } from "i18next";
export type OnboardingRegisteredStepId = "profile-basics" | "team-invites" | "priority-support-setup";
export interface OnboardingRegisteredStepDefinition {
readonly id: OnboardingRegisteredStepId;
readonly title: string;
readonly description: string;
readonly featureFlagKey?: FeatureFlagsFilterType;
readonly planFeatureKey?: DefaultFeatures | string;
}
export const onboardingStepRegistry = Object.freeze([
{
id: "profile-basics",
title: i18nT("onboarding.stepRegistry.profileBasics.title"),
description: i18nT("onboarding.stepRegistry.profileBasics.description"),
},
{
id: "team-invites",
title: i18nT("onboarding.stepRegistry.teamInvites.title"),
description: i18nT("onboarding.stepRegistry.teamInvites.description"),
featureFlagKey: "workspace-roles",
},
{
id: "priority-support-setup",
title: i18nT("onboarding.stepRegistry.prioritySupportSetup.title"),
description: i18nT("onboarding.stepRegistry.prioritySupportSetup.description"),
planFeatureKey: DefaultFeatures.PrioritySupport,
},
] as const satisfies readonly OnboardingRegisteredStepDefinition[]);
const onboardingStepIds = onboardingStepRegistry.map((step) => step.id) as readonly OnboardingRegisteredStepId[];
const onboardingGateSources = Object.freeze(["feature-flag", "plan"] as const);
export const onboardingStepRegistryEvidence = Object.freeze({
registryName: "Onboarding Step Registry",
registryScope: "source-backed-onboarding-steps",
expectedStepIds: onboardingStepIds,
gatingSourcesRepresented: onboardingGateSources,
redactionGuarantee:
"Onboarding step registry evidence is static source metadata only and excludes request, tenant, subscription, user, token, environment, and raw feature input values.",
} as const);
export function getOnboardingStepDefinitions(): readonly OnboardingRegisteredStepDefinition[] {
return onboardingStepRegistry;
}