@withandeo/cli 0.11.0 → 0.13.0

package/skill/tender-accounts/references/domains-auth.md

@@ -0,0 +1,13 @@
+# Domains and customer authentication
+
+Treat three configurations separately:
+
+1. Andeo routing plus merchant DNS and certificate.
+2. The app's exact hostname allowlist; the Shopify starter uses `ACCOUNT_VANITY_HOSTNAMES`.
+3. Shopify's registered JavaScript origins, `/auth/callback` and `/auth/logout/callback` URLs.
+
+Add only the merchant-approved hostname, preserve existing hosts, package configuration and publish through Andeo. Keep generated-host authentication working. Do not introduce wildcard origins or bypass checks after a 404.
+
+Verify `/api/health`, `/api/bootstrap`, `/api/session` and the rendered sign-in/account journey on both domains. HTML 200 does not prove authentication works. In the starter, healthy gateway plus session `not_found` can indicate hostname-policy rejection. Bootstrap should select the custom-domain login URL. Inspect stale browser preview selection before blaming production.
+
+Keep customer authentication, Andeo administrator sign-in, protected app visibility and preview grants separate. Use supported administrator controls; do not assume every custom-domain/visibility combination works. Check signed-out denial, signed-in data, renewal and logout. Preserve provider adapter headers, redirects and timeouts when adding authenticated queries.

package/skill/tender-accounts/references/managed-source.md

@@ -0,0 +1,131 @@
+# Managed source
+
+If the merchant wants Andeo to own the Git transport, use the CLI for either
+the linked gateway or service project:
+
+```sh
+npx @withandeo/cli source connect --publication preview-only --json
+npx @withandeo/cli source status --json
+npx @withandeo/cli source pull --json
+npx @withandeo/cli source push --json
+```
+
+Run these commands from the independently deployable app directory, or use its
+exact `--cwd`. `source connect` derives the project working directory and build
+contract from Git plus `tender-accounts.json`; do not recreate that contract by
+hand in the admin. Protected gateways must stay `preview-only`. Use
+`--publication default-branch` only for an ordinary service when the merchant
+explicitly wants successful default-branch previews promoted automatically.
+
+`source push` includes only the committed revision. On a reviewed repository it
+uploads a bounded Git bundle through Andeo; the trusted runner verifies the
+exact commit and may update only the named non-default branch. The developer
+never receives a provider write credential. On a repository that has not yet
+enabled reviewed changes, the legacy short-lived Git credential path remains
+available during migration. Never copy any credential into a remote URL,
+credential helper, repository file, shell script, or chat. `source pull` is the
+inverse operation for an already connected repository and never creates or
+replaces the source connection. `source token` is read-only.
+
+When `source status` reports `changeRequestProtection: enabled`, use the normal
+reviewed flow:
+
+```sh
+npx @withandeo/cli source push --branch feature/account-copy --json
+npx @withandeo/cli source change create \
+  --head feature/account-copy \
+  --title "Update account copy" --json
+npx @withandeo/cli source change show --change scr_... --json
+```
+
+Return the `scr_` ID and exact preview state to the user. A developer or coding
+agent stops after the exact preview is ready. Approval and **Land in main** are
+merchant-administrator actions in Andeo. Do not push the default branch,
+obtain a raw provider token, call internal APIs, or replace this flow with
+`source promote` after reviewed changes are enabled.
+
+After a successful landing, inspect `branchCleanup` in
+`source change show --change scr_... --json`. `requested` and `running` need no
+developer action. `succeeded` means the exact landed feature ref was deleted or
+already absent. `retained` means Andeo deliberately kept a moved, reused, or
+otherwise unsafe ref. `failed` does not undo landing; ask a merchant
+administrator to retry cleanup in Andeo. Never obtain a provider write token
+or delete the branch directly. All immutable build, release, composition,
+approval, landing, and audit records remain available after cleanup.
+Do not reuse the same feature branch or make it the default while cleanup is
+`requested`, `running`, or retryable: Andeo deliberately fences that ref until
+cleanup succeeds, retains it, or exhausts its bounded retry budget.
+
+Inspect branches and history through read-only ephemeral credentials:
+
+```sh
+npx @withandeo/cli source branches --json
+npx @withandeo/cli source log --branch main --limit 20 --json
+npx @withandeo/cli source compare --base main --head feature/account-copy --json
+```
+
+Use standalone source-administration commands only for repositories where
+reviewed changes are not enabled and when the user explicitly requests a
+default-branch or history change and the active profile belongs to a merchant
+source administrator. First record `source branches`, `source compare`, the
+successful exact preview for the proposed head, and the current production
+composition. Run the exact operation with `--dry-run` before applying it.
+
+For an ordinary checked fast-forward, supply the current target SHA and a
+stable idempotency key:
+
+```sh
+npx @withandeo/cli source promote \
+  --head feature/account-copy \
+  --expected-current <exact-current-default-sha> \
+  --idempotency-key account-copy-v1 \
+  --dry-run --json
+```
+
+For an exceptional migration, use only the guarded history workflow:
+
+```sh
+npx @withandeo/cli source history replace \
+  --head app-only-main \
+  --expected-current <exact-current-default-sha> \
+  --confirm <exact-src-repository-id> \
+  --idempotency-key app-only-history-v1 \
+  --dry-run --json
+```
+
+Inspect the returned `sop_` operation with `source operation status`. Apply the
+same request without `--dry-run` only after the dry-run evidence matches the
+intended repository, project, branches, SHA, preview build, and composition.
+Never substitute a raw token, direct API, Git force push, ref deletion, or database
+edit. Andeo creates and verifies an archive before history replacement and
+uses an expected-SHA compare-and-swap for the target. History migration always
+suppresses automatic production publication; protected gateways always remain
+preview-only.
+
+If a durable source operation fails for a transient provider or runner reason,
+inspect and resume that same reviewed intent by ID:
+
+```sh
+npx @withandeo/cli source operation status --operation sop_... --json
+npx @withandeo/cli source operation retry --operation sop_... --json
+```
+
+Do not create a replacement request merely to retry infrastructure. A stale
+target, missing preview, archive conflict, or rejected permission requires the
+stated remediation and a newly reviewed request instead.
+
+For reviewed repositories, a moved head invalidates the previous approval and
+the newest source build becomes the next exact snapshot. A moved base makes the
+change stale. Rebase or update the feature branch, push a new committed
+revision, wait for its exact preview, and have the administrator review that
+new snapshot. Source landing never calls the production publisher directly;
+after landing, the repository's already configured default-branch policy may
+publish the same successful exact preview. Protected gateways remain
+preview-only.
+
+Treat source administration and production publication as different acts. A
+source operation may create a new immutable preview lineage, but only the
+merchant's established exact-composition control can publish production. For a
+portal and gateway changed together, preview both immutable revisions and
+review the sealed combined composition; do not pretend two repository refs can
+be changed atomically or publish whatever happens to be on each default branch.

package/skill/tender-accounts/references/observability.md

@@ -0,0 +1,18 @@
+# Observability and diagnosis
+
+| Layer | Investigation |
+| --- | --- |
+| Local setup | `andeo doctor --json`, checks, artifact dry-run |
+| Preview delivery | `andeo delivery status --delivery dly_... --json` |
+| Production publication | Exact `dwf_` in administrator Activity |
+| Preview invocation | `andeo tail --delivery dly_... --status error --json` |
+| Production invocation | `andeo tail --production --status error --json`, with merchant-admin authority |
+| App workflow | `andeo workflows status`, `history`, `diagnostics`, `export` for exact scope/run |
+
+Distinguish app runs from deployment workflows. Correlate project, environment, composition/release and safe run/request IDs. Never dump cookies, tokens, customer payloads or full provider errors. Sanitization cannot reliably protect secrets in arbitrary log strings.
+
+Live tail is short-lived, not historical search. Workflow lists are projections; exact run status reads engine state. History/export is bounded/sanitized with cursors, not raw native output or a live stream. Service diagnostics identify service revisions and attempts but do not imply equivalent instrumentation for every direct fetch. Record business receipts with non-secret correlation fields when needed.
+
+OTLP export is a separate administrator operation that can transmit raw telemetry to a merchant-approved destination. Verify deployment/support and destination approval first; do not invent export commands, install a new provider or promise historical dashboards from platform collection alone.
+
+For 503s, distinguish identity lookup, storage, admission/create, execution and callbacks before retrying. Ambiguous create/event/provider outcomes require reconciliation using the same logical operation. Publication or accepted start is not proof of the business effect.

package/skill/tender-accounts/references/releases-recovery.md

@@ -0,0 +1,16 @@
+# Production releases and recovery
+
+Production changes require explicit user authorization and an eligible merchant administrator. Developer preview permission is not production authority. No CLI publish command exists; use the protected policy or administrator console.
+
+```sh
+andeo production releases --json
+andeo production rollback --release TARGET_RELEASE_ID \
+  --expected-release CURRENT_RELEASE_ID --expected-revision N \
+  --idempotency-key approved-restore-001 --json
+```
+
+Only run rollback when explicitly requested. Select an eligible retained target and current release/revision from platform results; never guess or silently replace stale expectations. Rollback creates a new audited activation, not a Git reset, database restore or old secret-value restoration. Reconcile uncertain outcomes before another request.
+
+Recover `dwf_` publications via administrator Activity → Resume exact publish. `delivery retry` accepts `dly_` preview IDs, not production workflows. Preserve the approved intent; never edit platform records or submit duplicates to escape a hold.
+
+Verify final state and actual live composition, same-origin authenticated APIs and relevant generated/custom hostnames. Retained artifacts, preview readiness, stale UI toasts or HTML success are insufficient. Running workflows can retain old definitions and service contracts; code rollback does not cancel them.

package/skill/tender-accounts/references/services.md

@@ -0,0 +1,11 @@
+# Connected apps and service bindings
+
+Use independently published private apps for secret-backed integrations or reusable operations. Declare the portable artifact connection, for example `services: [{ "name": "DELIVERY_SERVICE", "targetProject": "delivery-service" }]`, using the configured target slug. An administrator must allow the connection in Settings; a declaration cannot grant access.
+
+Call `env.DELIVERY_SERVICE.fetch(...)`. Never reference physical Workers, namespaces or platform routing headers. Private apps cannot open directly. Keep browser APIs same-origin through the gateway and authorize business operations server-side.
+
+Publish dependencies before consumers. Workflow targets must publish a public string `WORKFLOW_SERVICE_CONTRACT`, such as `delivery-v1`. Preserve compatibility while definitions/runs retain it; drain dependencies or introduce a separately versioned service for breaking changes. Workflow services support bounded fetch, not arbitrary business RPC.
+
+Use `andeo preview entries --json` and `andeo preview open --from dly_... --json`. Preview-through permission is distinct from call permission. Apps without a selected preview use published revisions; verify the sealed composition, not an assumed collection of latest previews.
+
+Inspect `andeo workflows preview-services --json` and `preview-service-set --help` for explicit workflow preview dependency selection. Never silently cross app/environment boundaries. Verify permitted calls and revoked/unauthorized denial. Revocation does not undo effects or block unrelated direct Internet requests.

package/skill/tender-accounts/references/storage.md

@@ -0,0 +1,13 @@
+# App-owned storage
+
+Use storage for sessions, workflow receipts and app-owned state, not a replacement source of truth for provider business data. Run `andeo capabilities --json`: recognized resource types and enabled quotas do not prove automated provisioning support.
+
+The supported automated database path is D1. Declare a named resource in the portable artifact, for example `resources: [{ "type": "d1", "name": "APP_DB" }]`. Account enablement and quota are prerequisites. Andeo owns trusted provisioning and exact environment bindings; never supply physical IDs or provision through provider credentials.
+
+Hosted preview and production databases are separate. Do not assume preview has production rows. Local schema setup is app-owned; use the repository's schema declaration/packaging conventions and validate through preview/publication.
+
+Prefer additive, backwards-compatible changes while old code/runs remain active. Code rollback does not restore data or undo migrations. Complex schema evolution, destructive changes and restores require an explicit reviewed plan and supported operator path.
+
+KV, R2, Queues and Durable Objects may appear in contracts, entitlements or emulation, but are not automatically provisioned merchant resources without explicit support and hosted proof. Unsupported bindings must fail delivery, never disappear silently. Workflows have their own supported account resource lifecycle; read [Workflows](workflows.md).
+
+Verify persistence after reload, customer-scoped queries, cross-customer denial and environment isolation. Parameterize queries; keep customer data out of logs and fixtures.

package/skill/tender-accounts/references/workflows.md

@@ -0,0 +1,69 @@
+# App-defined workflows
+
+Use workflows for durable multi-step work, delays and event waits. An administrator must enable the account's workflow capability and definition quota first; declarations cannot enable it. No separate feature flag is required. Authenticate and authorize the customer in the app action before starting a run.
+
+## Declare and build
+
+Export the class from the app's Worker entry module and declare it in that app's Wrangler config:
+
+```jsonc
+{ "workflows": [{ "name": "customer-activity", "binding": "CUSTOMER_ACTIVITY", "class_name": "CustomerActivity" }] }
+```
+
+```ts
+import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";
+
+export class CustomerActivity extends WorkflowEntrypoint<{}, { runId: string }> {
+  async run(event: WorkflowEvent<{ runId: string }>, step: WorkflowStep) {
+    await step.do("notify", async () => {
+      // Replace this example with a fixed, approved application endpoint.
+      const response = await fetch("https://gateway.example.com/api/workflow-receipts", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ runId: event.payload.runId, phase: "started" }),
+        redirect: "manual",
+        signal: AbortSignal.timeout(10_000),
+      });
+      await response.body?.cancel();
+      if (!response.ok) throw new Error("Receipt failed");
+      return { sent: true };
+    });
+    await step.sleep("delay", "2 seconds");
+  }
+}
+
+// In an authorized app action, use a stable logical operation ID:
+// const run = await env.CUSTOMER_ACTIVITY.create({ id: runId, params: { runId } });
+// return Response.json({ runId: await run.id }, { status: 202 });
+```
+
+The CLI packages code for Andeo's Dynamic Workflow hosts. Do not deploy a separate Cloudflare workflow. Global `fetch()` works inside durable steps; a service is not required merely for HTTP. Pin approved destinations, validate variable URLs, bound timeouts/redirects, and make external effects idempotent because steps retry. A callback that only knows a run ID is a demo receipt, not sender authentication; use secret-backed verification for trusted callbacks.
+
+## Environment and services
+
+Workflow code receives declared public string vars and scoped service capabilities—not app secrets, direct D1/KV/R2 bindings or the platform dispatcher. Never pass tokens through params, events or step results. Put secret-backed HTTP/storage operations in a connected service; read [Services](services.md) and [Configuration](configuration-secrets.md). Publish its `WORKFLOW_SERVICE_CONTRACT` first. Direct outbound access is independent of service permission revocation.
+
+## Local and hosted validation
+
+Use `andeo dev` for the local Workflow/Loader runtime. Map service bindings to built local artifact directories in `andeo.workflow-dev.json`, for example `{ "DELIVERY_SERVICE": "../delivery-service/dist/andeo" }`. Build services first. Local state is under `.tender/workflows-local`; restart after source changes (no hot reload). Local schema setup is app-owned. Local success does not prove hosted authorization or isolation.
+
+Use normal build/preview delivery. Verify an authenticated start, durable completion, the external effect and persistence after reload. The reference demo writes a requested row and receives started/completed POSTs in its gateway. Customer identity lookups must preserve the provider's required headers; the reference Shopify queries use an explicit User-Agent.
+
+## Inspect and control
+
+```sh
+andeo workflows list --environment preview --json
+andeo workflows runs --scope SCOPE_ID --json
+andeo workflows status --scope SCOPE_ID --run RUN_ID --json
+andeo workflows history --scope SCOPE_ID --run RUN_ID --json
+andeo workflows diagnostics --scope SCOPE_ID --run RUN_ID --json
+andeo workflows export --scope SCOPE_ID --run RUN_ID --limit 100 --offset 0 --json
+```
+
+Read `andeo workflows --help` for start/event/pause/resume/terminate/restart and preview-service selection. Obtain scopes from list results; never invent physical IDs. Identical scoped run IDs and inputs converge; changed inputs conflict. Lists are timestamped projections; single-run status reads the engine. Follow returned cursors/offsets. Exports omit raw payloads, provider errors and free-form logs.
+
+Viewers can read; developers can control runs. Termination/restart and uncertain-event acknowledgement require exact run confirmation. Never replay ambiguous events automatically. Acknowledgement clears a fence; it does not prove delivery. Termination cannot reverse completed or in-flight effects. Disabling entitlement blocks new starts/restarts and workflow-bearing releases, not already running work.
+
+## Limits
+
+Use the supported adapter surface: create/get/status, bounded createBatch, sendEvent, pause/resume/terminate/restart and bounded history. `createBatch` returns per-member acceptance/error records, not native handle-array parity; use `await run.id`. Schedules, custom retention, cross-app `script_name`, arbitrary business RPC and full native API parity are unsupported. Restart requires a terminal run within the supported retention window. Check runtime errors for current payload/admission/service limits; upstream Cloudflare limits are not Andeo's contract.

package/templates/shopify-customer-account/apps/gateway/README.md

@@ -9,3 +9,5 @@ Local HTTP development returns an explicit signed-out state. Real Shopify sign-i
 The generated `.dev` hostname stays the Shopify callback anchor. When a merchant vanity domain is activated, add it to the public comma-separated `ACCOUNT_VANITY_HOSTNAMES` environment value so the exact-host session policy can safely return the shopper there. Do not move Shopify callback configuration to the vanity hostname.
 
 Managed builds retain published settings through `TENDER_PUBLIC_VARS_SOURCE`, which points to the app's verified build envelope and takes precedence over `--vars`. The packager checks the app identity and declared public-variable allowlist. Without that input, local packaging reads `--vars` or `.dev.vars` as usual.
+
+If this app needs runtime secrets, declare their names in its app configuration and ask an app administrator to select shared previews, initialize its targets, and save each app-level secret in Settings. Read a native secret directly as a string, such as `env.API_TOKEN`; do not use a Secrets Store `.get()` binding. One saved value applies to preview and production. A new gateway preview replaces its previous preview. The portal can keep independent previews so multiple portal PRs remain available simultaneously. These are explicit project policies, independent of the app's name or kind.