@vxil/cli 0.6.0 → 0.7.0

package/dist/_vxil-feature-configs-apiState.d.ts

@@ -0,0 +1,179 @@
+import type { DeclaredRlPolicy, DeclaredWebhookSubscription } from './_vxil-feature-configs.js';
+/** The target_url path markers of the platform's function-delivery lanes
+ *  (control-plane fnCmsHooks.ts FN_CMSHOOK_PATH / FN_AUTHHOOK_PATH /
+ *  FN_WEBHOOK_TRIGGER_PATH — mirrored here because this package is
+ *  typebox-only). A subscription on one of them is derived from the functions
+ *  manifest by the deploy reconciler: never declarable, never "undeclared". */
+export declare const FN_TRIGGER_TARGET_MARKERS: readonly ["/v1/internal/fn/cms-hook/", "/v1/internal/fn/auth-hook/", "/v1/internal/fn/trigger/"];
+export declare function isFnTriggerSubscriptionUrl(targetUrl: string): boolean;
+export type ApiStateDatum = 'policies' | 'subscriptions' | 'templates';
+/** feature → the declared-API-state datum its config block may carry. */
+export declare const API_STATE_DATUMS: ReadonlyArray<{
+    feature: string;
+    datum: ApiStateDatum;
+}>;
+export declare function apiStateDatumOf(feature: string): ApiStateDatum | null;
+/** The declared list a validated manifest carries for its feature's datum, or
+ *  null when the feature has no datum / the block is absent. An absent block
+ *  means "not managed by config" (nothing converges, nothing is reported) —
+ *  distinct from an EMPTY array, which declares "there should be none". */
+export declare function declaredApiState(feature: string, manifest: Record<string, unknown> | null | undefined): {
+    datum: ApiStateDatum;
+    declared: unknown[];
+} | null;
+/** ONE row of GET /v1/rate-limits/policies (rate-limits-v1 core.ts Policy). */
+export interface LiveRlPolicy {
+    policy_id: string;
+    name: string;
+    key_template: string;
+    limit: number;
+    window_seconds: number;
+    behavior: string;
+    /** absent on a policy stored before the token-bucket pass → 'sliding_window' */
+    algorithm?: string;
+}
+/** The PUT /v1/rate-limits/policies/:id body the converge sends (core.ts
+ *  UpdateBody minus `name`, which is the key). */
+export interface RlPolicyPatch {
+    limit?: number;
+    window_seconds?: number;
+    behavior?: 'block' | 'shape';
+    algorithm?: 'sliding_window' | 'token_bucket';
+}
+export declare const RL_DEFAULT_BEHAVIOR: "block";
+export declare const RL_DEFAULT_ALGORITHM: "sliding_window";
+export interface RlPolicyPlan {
+    create: DeclaredRlPolicy[];
+    update: Array<{
+        policy_id: string;
+        name: string;
+        patch: RlPolicyPatch;
+        changed: string[];
+    }>;
+    /** `key_template` differs — the update route cannot change it, so the only
+     *  fix is delete+recreate (a NEW policy_id): destructive-shaped. */
+    recreate: Array<{
+        policy_id: string;
+        name: string;
+        declared: DeclaredRlPolicy;
+    }>;
+    unchanged: string[];
+    /** live rows the config does not declare (left in place by default) */
+    undeclared: Array<{
+        policy_id: string;
+        name: string;
+    }>;
+    /** a declared name matched by MORE THAN ONE live row — names are not a
+     *  unique key on the route, so the converge cannot pick; nothing is touched */
+    ambiguous: Array<{
+        name: string;
+        count: number;
+    }>;
+}
+export declare function planRlPolicies(declared: readonly DeclaredRlPolicy[], live: readonly LiveRlPolicy[]): RlPolicyPlan;
+/** ONE row of GET /v1/webhooks/subscriptions (state 'deleted' never listed). */
+export interface LiveWebhookSubscription {
+    sub_id: string;
+    target_url: string;
+    event_prefixes: string[];
+    state?: string;
+}
+export interface WebhookSubscriptionPlan {
+    create: DeclaredWebhookSubscription[];
+    /** the prefix SET differs — there is no update route, so delete+recreate (a
+     *  NEW sub_id, and the watermark restarts at "now"): destructive-shaped. */
+    recreate: Array<{
+        sub_id: string;
+        target_url: string;
+        declared: DeclaredWebhookSubscription;
+    }>;
+    unchanged: string[];
+    /** live rows the config does not declare, EXCLUDING the function-delivery
+     *  lanes (those derive from the functions manifest) — left in place by default */
+    undeclared: Array<{
+        sub_id: string;
+        target_url: string;
+    }>;
+}
+export declare function planWebhookSubscriptions(declared: readonly DeclaredWebhookSubscription[], live: readonly LiveWebhookSubscription[]): WebhookSubscriptionPlan;
+/** ONE row of GET /v1/ai/templates. `content_sha256` is the canonical hash of
+ *  the LATEST version's {system,user,schema} (@vxil/runtime
+ *  aiTemplateContentSha256), stamped by ai-v1 since 2026-09-23; absent on an
+ *  older server. */
+export interface LiveAiTemplate {
+    name: string;
+    latest_version: number;
+    content_sha256?: string;
+}
+/** A declared template with its content hash pre-computed by the caller (the
+ *  hash is async WebCrypto; this planner stays pure/sync). */
+export interface HashedDeclaredAiTemplate {
+    template: string;
+    content_sha256: string;
+}
+export interface AiTemplatePlan {
+    create: string[];
+    /** content differs → POST a new version (monotonic per name) */
+    update: string[];
+    unchanged: string[];
+    /** stored names the config does not declare — there is NO delete route for
+     *  templates, so these are only ever reported, never removed */
+    undeclared: string[];
+    /** live rows with no `content_sha256` (an older server): the content cannot
+     *  be compared, so each is re-put as `update` and named here */
+    unknownContent: string[];
+}
+export declare function planAiTemplates(declared: readonly HashedDeclaredAiTemplate[], live: readonly LiveAiTemplate[]): AiTemplatePlan;
+export interface ApiStateSummary {
+    datum: ApiStateDatum;
+    created: string[];
+    updated: string[];
+    /** destructive-shaped changes APPLIED under allow-destructive (delete+recreate) */
+    recreated: string[];
+    unchanged: string[];
+    /** live rows the config does not declare — left in place (or, under
+     *  allow-destructive, listed in `deleted` instead) */
+    undeclared: string[];
+    /** undeclared rows DELETED under allow-destructive */
+    deleted: string[];
+    /** destructive-shaped changes NOT applied (need allow-destructive) */
+    pending_destructive: string[];
+    /** declared keys the converge could not resolve (duplicate live rows) */
+    ambiguous: string[];
+    /** rows a route refused (a 4xx) — the converge continues past them */
+    failed: Array<{
+        key: string;
+        error: string;
+    }>;
+}
+export declare function emptyApiStateSummary(datum: ApiStateDatum): ApiStateSummary;
+/** The `api_state` object a config-write response carries (`PUT /v1/config/
+ *  :feature` and its dashboard twin, dry-run included — control-plane
+ *  handlers/apiState.ts apiStateResponseField) and the shape `vxil push` /
+ *  `vxil plan` print. `ok:false` + `deferred:true` = not converged for an
+ *  INDEFINITE reason — the feature worker has not seen the config yet, or a
+ *  transient failure (a push asks again through POST /v1/apply after its
+ *  wait); `ok:false` otherwise = a DEFINITE, named refusal (nothing to retry);
+ *  `note` = converged nothing on purpose (a disabled feature). */
+export interface ApiStateResponseField extends ApiStateSummary {
+    ok: boolean;
+    dry_run?: boolean;
+    deferred?: boolean;
+    error?: string;
+    note?: string;
+}
+/** The note every executor reports for a DISABLED feature whose block still
+ *  declares rows: the declaration is kept in the manifest and nothing is
+ *  converged (a parked feature is not a propagation window — review finding 2). */
+export declare const API_STATE_DISABLED_NOTE = "feature disabled \u2014 declaration kept, not converged";
+/** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
+ *  AT the cap is not a complete live set, so planning creates against it would
+ *  re-POST every declared name the cap hid (review finding 5). The server's
+ *  converge and the CLI's read-only plan refuse with this message instead. */
+export declare function rlPolicyListCapError(liveCount: number): string | null;
+export declare const RL_POLICY_LIST_CAP = 100;
+/** `+2 created · ~1 updated · =3 unchanged · 1 undeclared (left in place)` —
+ *  the one-line summary `vxil push` prints and the apply journal notes. */
+export declare function formatApiStateSummary(s: ApiStateSummary): string;
+/** The multi-line detail under the summary: one line per named row. */
+export declare function formatApiStateDetail(s: ApiStateSummary): string[];

package/dist/_vxil-feature-configs-canonicalJson.d.ts

@@ -0,0 +1,7 @@
+/** JSON.stringify with object keys sorted at every depth (arrays keep their
+ *  order; undefined-valued keys are dropped, as JSON.stringify drops them).
+ *  Two values with equal output are equal in CONTENT. A stored manifest comes
+ *  back from storage with its object keys re-ordered, so every declared-vs-
+ *  stored config compare (the server's shallowDiff, the CLI's diffManifest)
+ *  must go through this, never through plain JSON.stringify. */
+export declare function canonicalJson(v: unknown): string | undefined;

package/dist/_vxil-feature-configs-readmodels.d.ts

@@ -0,0 +1,38 @@
+export declare const READ_MODEL_LIMITS: {
+    readonly maxReadModels: 20;
+    readonly maxAggregates: 4;
+    readonly maxGroupBy: 2;
+    readonly maxWindowDays: 366;
+    readonly maxSpecBytes: 4096;
+    readonly maxCdcRules: 25;
+};
+/**
+ * Structural validation of a declared read-model `spec` — shared by the
+ * config-write gate here and re-exported for anyone needing the pure check.
+ * `kind` selects the §3.1 (aggregate) or §4.1 (rank) grammar.
+ */
+export declare function validateReadModelSpecShape(where: string, kind: 'aggregate' | 'rank', spec: unknown): string[];
+/** Shape of one declared read-model (mirrors the CmsConfigSchema Record). */
+interface ReadModelDefLike {
+    collection?: string;
+    kind?: string;
+    spec?: unknown;
+    materialize?: {
+        cron?: string;
+        to?: string;
+    };
+    enabled?: boolean;
+}
+/** Cross-field rule for CmsConfig.readModels (called from validateFeatureConfig). */
+export declare function validateReadModelsConfig(readModels: Record<string, ReadModelDefLike> | undefined): string[];
+/** Shape of one CDC rule (mirrors the CmsConfigSchema Record). */
+interface CdcRuleLike {
+    collection?: string;
+    channel?: string;
+    events?: unknown;
+    payload?: unknown;
+    enabled?: boolean;
+}
+/** Cross-field rule for CmsConfig.cdc (called from validateFeatureConfig). */
+export declare function validateCdcConfig(cdc: Record<string, CdcRuleLike> | undefined): string[];
+export {};

package/dist/_vxil-feature-configs.d.ts

@@ -1,7 +1,8 @@
 import { type Static, type TSchema } from '@sinclair/typebox';
 export * from './_vxil-feature-configs-hooks.js';
-export * from './readmodels.js';
-export * from './apiState.js';
+export * from './_vxil-feature-configs-readmodels.js';
+export * from './_vxil-feature-configs-apiState.js';
+export * from './_vxil-feature-configs-canonicalJson.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** True when a credit_type is a vxil-COGS reserved type (grant/consume/config
  *  of which is restricted to internal platform machinery). */