@withandeo/cli 0.19.10 → 0.19.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withandeo/cli",
-  "version": "0.19.10",
+  "version": "0.19.11",
   "description": "Developer CLI for Andeo applications",
   "type": "module",
   "license": "UNLICENSED",
@@ -27,6 +27,8 @@
     "prepack": "npm run sync:starter && npm run check"
   },
   "devDependencies": {
+    "@cloudflare/flagship": "0.5.0",
+    "@openfeature/server-sdk": "1.23.0",
     "@types/node": "^26.2.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11"
@@ -39,7 +41,10 @@
     "smol-toml": "1.8.0"
   },
   "exports": {
-    "./cli": "./dist/main.js"
+    "./cli": "./dist/main.js",
+    "./flagship-runtime": "./dist/flagship-runtime.js",
+    "./flagship-browser": "./dist/flagship-browser.js",
+    "./package": "./dist/workflow-package.js"
   },
   "publishConfig": {
     "access": "public"

package/skill/publication.json

@@ -1,3 +1,3 @@
 {
-  "minimumCliVersion": "0.19.10"
+  "minimumCliVersion": "0.19.11"
 }

package/skill/tender-accounts/SKILL.md

@@ -23,7 +23,7 @@ Use `npx @withandeo/cli` as the merchant platform interface. Keep merchant behav
 | Define or operate background work | [Workflows](references/workflows.md) |
 | Public configuration or private tokens | [Configuration and secrets](references/configuration-secrets.md) |
 | Declare resources or evolve app-owned state | [Storage](references/storage.md) |
-| Guard operations with selected customers or percentage rollouts | [Feature flags](references/feature-flags.md); authenticated `feature-flags` skill |
+| Manage typed feature flags, experiments, collections and runtime guards | [Feature flags](references/feature-flags.md); authenticated `feature-flags` skill |
 | Connect private apps or workflow services | [Services](references/services.md) |
 | Custom domains and customer sign-in | [Domains and authentication](references/domains-auth.md) |
 | Diagnose requests or workflow execution | [Observability](references/observability.md) |

package/skill/tender-accounts/references/feature-flags.md

@@ -1,90 +1,161 @@
-# Tenant feature flags
+# Flexible feature flags
 
-This CLI implements boolean flag management and native Cloudflare Flagship declarations.
-Availability requires tenant enablement, a project grant, provisioned environment apps,
-and configured trusted management. Run `andeo capabilities --json` and `andeo doctor`;
-`implemented_pending_hosted_proof` does not certify a deployed binding. Read the
-authenticated `feature-flags` skill with `andeo skills get feature-flags --json`.
+Andeo wraps native Cloudflare Flagship: boolean/string/number/JSON variants,
+configured defaults, ordered rules, nested targeting and weighted experiments.
+Use `andeo capabilities --json`, `andeo doctor` and the authenticated
+`andeo skills get feature-flags --json`. Local implementation is not hosted proof.
+Use `andeo flagship --help` for this installed version's exact commands.
 
-Use an explicit environment on every command. Administrators connect projects with
-`andeo flagship apps ensure --env preview --json`. That grants only this project to
-the tenant's shared preview app. Developers manage granted nonproduction apps;
-production writes require the credential owner's current merchant-admin role.
-Viewers cannot mutate. A Cloudflare app ID alone gives no permission.
+Every remote command requires explicit `--env development|preview|production`,
+tenant enablement and a project grant. Current administrators connect collections
+and perform lifecycle changes; developers edit granted nonproduction flags;
+production writes require current administrator authority; viewers read only.
+An app ID alone is not authorization. Tenant quota remains at most three apps
+across environments/collections, separate from Cloudflare limits.
 
 ```sh
+andeo flagship apps ensure --collection checkout --env preview --json
 andeo flagship apps list --env preview --json
-andeo flagship flags create APP_ID example-feature --env preview --json
-andeo flagship flags audience APP_ID example-feature --env preview --customer-ids-file ./synthetic-ids.json --json
-andeo flagship flags evaluate APP_ID example-feature --env preview --context customerId=synthetic-customer-a --json
-andeo flagship flags enable APP_ID example-feature --env preview --json
-andeo flagship flags rollout APP_ID example-feature --env preview --to on --percentage 5 --by customerId --json
-andeo flagship flags disable APP_ID example-feature --env preview --json
-andeo flagship flags get APP_ID example-feature --env preview --json
-andeo flagship flags reconcile APP_ID example-feature --env preview --json
-andeo flagship flags changelog APP_ID example-feature --env preview --json
+andeo flagship flags validate --file ./definition.json --json
+andeo flagship flags create APP_ID checkout-layout --file ./definition.json --env preview --json
+andeo flagship flags export APP_ID checkout-layout --env preview --json
+andeo flagship flags diff APP_ID checkout-layout --file ./edited.json --env preview --json
+andeo flagship flags apply APP_ID checkout-layout --file ./edited.json --expected-revision 3 --expected-digest OBSERVED_DIGEST --env preview --json
+andeo flagship flags evaluate APP_ID checkout-layout --context-file ./synthetic-context.json --type string --fallback-file ./fallback.json --env preview --json
+andeo flagship flags enable APP_ID checkout-layout --env preview --json
+andeo flagship flags disable APP_ID checkout-layout --env preview --json
+andeo flagship flags reconcile APP_ID checkout-layout --env preview --json
+andeo flagship flags changelog APP_ID checkout-layout --env preview --json
 ```
 
-Create defaults to disabled, no selected customers, 0%, and false fallback.
-Customer files contain bounded JSON arrays of strings, for example
-`["synthetic-customer-a"]`. Do not commit real customer inventories. 0% still
-admits selected customers when enabled. `audience --all` selects 100% without
-discarding the list. Audience and percentage edits preserve each other and never
-enable a disabled flag. Enable rejects an empty list with 0%.
+Offline validate needs no auth or environment. Definitions use the pinned
+Wrangler 4.135.0 schema: key, description?, enabled, default_variation, variations,
+rules. A rule has priority, conditions, serve_variation and optional rollout
+{percentage, attribute?}; a nested condition has logical_operator and clauses.
+All variants share one type. Create requires `--file` and starts disabled. Apply preserves
+enabled state, requires the observed revision/digest and cannot enable implicitly.
+Export returns an envelope: extract `definition` for editing, retain `observed`
+and compatibility diagnostics for unknown fields. Inspect the complete diff first.
 
-Ordinary edits read a revision first; pass `--expected-revision N` to use a
-previous observation. The service checks it inside durable serialization.
-A stale edit cannot overwrite a newer Disable. Unknown provider outcomes block
-conflicting changes until `reconcile` reads the requested definition back.
-External unsupported rules require operator reconciliation; emergency Disable
-preserves them only when the observed default variation is false.
+Native disabled evaluation returns the configured default, which can be true or
+non-boolean. Choose false defaults/fallbacks for business guards. Caller fallback
+is distinct from default and type mismatch. The official OpenFeature provider
+0.5.0 returns caller fallback on DISABLED; native details return configured default.
 
-In `tender-app.config.json`, preserve the rest of your app contract and add:
+Context files are bounded JSON objects of string/number/boolean properties, including
+{}. Native evaluation supports these types. Current management REST transport only
+verifies strings and rejects numbers/booleans with
+flagship_typed_management_context_unverified; no implicit string coercion occurs.
+Use synthetic fixtures, never commit customer inventories.
+
+Experiments use positive shares totaling 100% of eligible traffic, compiled into
+cumulative thresholds with identical eligibility and bucketing attribute. A 50/50
+split is thresholds 50 then 100, not independent 50/50 rules. Variant names differ
+from returned values. Default control is not enrolled control: inspect reason and
+variant. Missing targetingKey can assign randomly. Use stable server-owned IDs for
+sticky assignment; request IDs deliberately sample requests. Changing app, weights,
+eligibility or attribute can change assignment. Exposure occurs when the experience
+is actually shown. Assignment is not conversion analysis/statistical significance.
+
+All flags use the general definition model. Targeting and rollouts are configured
+through rules in the full definition. Evaluation accepts `--context-file` or empty
+context; customerId is an ordinary attribute. There are no customer-specific
+commands, automatic definitions or old-key validation exceptions.
+
+External changes require explicit reconciliation. Unknown outcomes retain pending
+intent and block conflicting writes; never blindly replay. Disable keeps
+the full compatible typed definition and requires external edits to be reconciled.
+Unknown writable fields block all edits, including Disable. Save/readback means changes are propagating,
+not globally cut over; runtime propagation and browser refresh add delay.
+
+```sh
+andeo flagship apps get APP_ID --env preview --json
+andeo flagship apps rename APP_ID --name reviewed-provider-name --expected-revision 0 --env preview --json
+andeo flagship apps disconnect APP_ID --confirm PROJECT_ID --expected-revision 1 --env preview --json
+andeo flagship flags delete APP_ID KEY --confirm KEY --expected-revision 4 --expected-digest OBSERVED_DIGEST --env preview --json
+andeo flagship apps delete APP_ID --confirm APP_ID --expected-revision 2 --env preview --json
+```
+
+Inspect affected projects and receipts. Retained builds block disconnect; grants
+and flags block app deletion. Deletion has no restore guarantee. Tombstones retain
+revisions; ensure never recreates deleted or pending collections. App reconcile
+requires expected revision. Promotion/history reapplication use an exported exact
+definition, current destination enabled state, current revision/digest and reviewed
+diff/apply, followed by separate Enable. Deployment/rollback never copies flags.
+
+Flag deletion requires a disabled saved provider definition. Disable, observe,
+remove its evaluations from application code, and deploy before using `--confirm
+KEY`. Disabled status alone does not prove that no code still uses the flag;
+Andeo does not detect remaining evaluations automatically. Refresh the revision
+and digest after Disable. Final readback rejects re-enabling or definition changes
+during review; it cannot atomically prevent external provider edits after the read.
+
+Declare the native binding separately for every environment in tender-app.config.json:
 
 ```json
 {
-  "flagship": [{"binding":"FLAGS","app_id":"DEVELOPMENT_APP_ID"}],
-  "env": {
-    "preview": {"flagship":[{"binding":"FLAGS","app_id":"PREVIEW_APP_ID"}]},
-    "production": {"flagship":[{"binding":"FLAGS","app_id":"PRODUCTION_APP_ID"}]}
+  "flagship":[{"binding":"FLAGS","app_id":"DEVELOPMENT_APP_ID"}],
+  "env":{
+    "preview":{"flagship":[{"binding":"FLAGS","app_id":"PREVIEW_APP_ID"}]},
+    "production":{"flagship":[{"binding":"FLAGS","app_id":"PRODUCTION_APP_ID"}]}
   }
 }
 ```
 
-The CLI's artifact packaging retains all three environments under `manifest.flags`.
-The trusted deployer chooses the environment and verifies registry ownership,
-tenant enablement, account and project grants. No environment inherits another ID.
-Binding names cannot conflict with resources, services, workflows, secrets or vars.
-Deploy/rollback never changes flag definitions. Concurrent previews share their app.
+Packaging retains all environments in manifest.flags. Trusted delivery verifies
+registry/account/environment/tenant/project grants. No environment inherits IDs.
+Previews share live definitions. GitHub workflows must run installed
+`andeo artifact finalize --artifact-directory .tender/artifacts/current --json`
+after pack:tender, before OIDC delivery; use a released CLI containing this command.
+Finalization retains workflows, flags and attested source revision without relabeling.
 
-Native Worker usage, immediately before each external write attempt:
+Worker code evaluates env.FLAGS details methods. Optional official OpenFeature:
 
 ```ts
-async function allowed(env: { FLAGS?: Flagship }, customerId: string) {
-  if (!customerId?.trim() || !env.FLAGS) return false;
-  try { return (await env.FLAGS.getBooleanDetails("example-feature", false, { customerId })).value === true; }
-  catch { return false; }
-}
+import {OpenFeature} from "@openfeature/server-sdk";
+import {FlagshipServerProvider} from "@cloudflare/flagship/server";
+await OpenFeature.setProviderAndWait("checkout",new FlagshipServerProvider({binding:env.FLAGS}));
+const result=await OpenFeature.getClient("checkout","1").getStringDetails(
+  "checkout-layout","caller-fallback",{targetingKey:serverOwnedKey,plan:trustedPlan});
 ```
 
-Use the same canonical customer ID in callers and private provider services.
-Recheck on each batch/retry in the credential-holding service; do not cache an
-allow decision in a durable workflow step. Direct workflow evaluation is not
-supported: call a granted private service. Keep business eligibility and
-authorization checks. Flags do not grant permission to use live write credentials.
-
-Changes can take up to 30 seconds to propagate. Disable cannot recall an issued
-request. Record partial effects as `blocked_by_feature_flag`; retain evidence,
-do not mark completion, blindly replay events, or undo provider changes. Authorized
-recovery and readback remain available when ordinary operations are disabled.
-
-Wrangler 4.135.0 supports a local simulator: use development bindings with
-`remote:false`, explicit synthetic definitions, and test credentials. The Andeo
-workflow-local host rejects Flagship declarations until native evaluation is
-supported there; use the application's Wrangler simulator and mock private
-service calls. Never silently substitute production apps or credentials.
-Optional OpenFeature integration is application-owned; no SDK install is required.
-
-References: https://developers.cloudflare.com/flagship/configuration/,
-https://developers.cloudflare.com/flagship/binding/methods/,
-https://developers.cloudflare.com/flagship/reference/wrangler-commands/.
+Pass request-local context, never mutate global client context across requests.
+External Node/Go/Python official providers require a separately approved scoped
+credential path and revocation proof; Andeo does not issue these credentials here
+or share its management token. Direct Workflow binding is unsupported: call an
+explicitly granted private service and recheck each external write/retry there.
+Keep business eligibility, authorization and recovery independent of feature flags.
+
+Browser helpers: import @withandeo/cli/flagship-runtime for createFlagGateway,
+flagVisitorIdentity and optional flagExposure; import @withandeo/cli/flagship-browser
+for createFlagBrowserClient after release. The application authenticates its own
+gateway, selects client-visible keys/environment/binding and enriches trusted
+context server-side. Return bounded values and refresh hints, never private rules,
+raw context or provider tokens. Initial loading uses caller fallbacks; SSR can
+hydrate matching bootstrap. Each client instance isolates caches; invalidate on
+login/logout/tenant/context changes before refresh. The app schedules refreshes.
+Server actions independently guard operations. Optional one-year HttpOnly visitor
+cookie survives login/actions; explicit reset changes identity. Consent, exposure
+deduplication/retention and outcome measurement remain application-owned.
+
+Local simulator uses remote:false and synthetic definitions/test credentials.
+Andeo's Workflow dev host rejects native flags; use app Wrangler simulation plus
+mock private services. Do not swap production IDs into development. New names
+use the pinned syntax and a maximum of 64 characters for every operation. Values are
+finite bounded JSON with safe keys; provider/Andeo limits are separately documented.
+No local check establishes hosted lifecycle, propagation or external SDK readiness.
+
+See repository docs/runbooks/FLEXIBLE_FEATURE_FLAGS.md for the parity matrix,
+migration 0092, exact boundaries and remaining hosted acceptance evidence.
+Official documentation: https://developers.cloudflare.com/flagship/.
+
+External access design: Specified Flagship apps + Flagship App Evaluate, limited
+to the exact approved collection/environment, server-side secret storage, no Read,
+Write or Entire Account permissions. Provisioning/revocation proof is pending.
+Node uses the official appId/accountId/authToken provider; Go uses
+github.com/cloudflare/flagship/sdks/go; Python uses cloudflare-flagship. Go/Python
+evaluate HTTP only and offer sync/details (Python also async), request-local scalar
+context and optional TTL caches; leave caches off for guards until verified.
+See https://developers.cloudflare.com/flagship/sdk/go/,
+https://developers.cloudflare.com/flagship/sdk/python/ and
+https://developers.cloudflare.com/flagship/api-tokens/.