@withandeo/cli 0.12.0 → 0.13.0

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

@@ -0,0 +1,125 @@
+# Build, preview and publish
+
+## Implement and validate
+
+1. Inspect the existing application and tests before changing code.
+2. Use the repository's own development workflow. `npx @withandeo/cli dev` delegates to the committed `commands.dev`, starts local development, and never creates an Andeo deployment.
+3. Make the smallest source change that satisfies the request.
+4. Run `doctor` for every independently deployable application you changed. In a generated repository:
+
+   ```sh
+   npx @withandeo/cli doctor --cwd apps/portal --json
+   npx @withandeo/cli doctor --cwd apps/gateway --json
+   ```
+
+   Do not require gateway access for a portal-only task. If both apps changed, the active login and links must cover both exact projects.
+5. Run the deterministic repository checks:
+
+   ```sh
+   npx @withandeo/cli check --json
+   ```
+
+6. Validate the complete portable artifact without uploading it:
+
+   ```sh
+   npx @withandeo/cli preview --dry-run --json
+   ```
+
+Do not weaken checks, remove declared bindings, or place runtime values in the artifact to make validation pass.
+
+## Retain a local build for administrator publication
+
+When the user requests the manual build path, use `andeo upload --dry-run --json`
+and then `andeo upload --json`. This runs the repository checks and packaging,
+verifies and retains the artifact, and returns its exact release ID and digest.
+It does not create a preview runtime or publish production. An administrator
+reviews the artifact in **Changes → Publish a retained artifact** and approves
+publication explicitly. Local builds do not require a GitHub run for this
+manual path; their source labels remain unverified. The CLI cannot approve
+publication, and automatic source publication still requires trusted main
+evidence. Continue to honor explicit production approval from the user.
+
+## Create an exact preview
+
+After local validation succeeds, preview each changed application. For a portal-only change, run:
+
+```sh
+npx @withandeo/cli preview --cwd apps/portal --json
+```
+
+For a new account stack or a change spanning both apps, package and preview the portal and gateway as separate projects:
+
+```sh
+npx @withandeo/cli preview --cwd apps/portal --json
+npx @withandeo/cli preview --cwd apps/gateway --json
+```
+
+On the first stack preview, the first command may retain its exact release and return `bootstrap_counterpart_release_missing`. This is an expected incomplete stack, not permission to change IDs or bypass Andeo: build the named counterpart once, then rerun the failed side only if the second command did not already seal the composition. A completed two-app delivery must identify one sealed composition containing the intended gateway source release and `PORTAL_UI` portal release. Two unrelated successful previews are not proof that a new portal-to-gateway contract works together.
+
+Treat stdout as one machine-readable JSON object. Preserve and report:
+
+- `previewUrl`;
+- `deliveryId`;
+- `releaseId`;
+- `bundleDigest`;
+- `compositionId` when the delivery sealed one;
+- validation performed before delivery.
+
+The CLI may label an uncommitted local preview with a `local-...` source revision. The immutable bundle digest remains the content identity. Do not claim the change is committed or pushed unless separately verified.
+
+## Prove the customer journey
+
+Local development proves layout and explicitly local behavior; it intentionally stays signed out for the generated Shopify starter. Real Shopify sign-in must be tested on an immutable HTTPS Andeo preview.
+
+Inspect the actual rendered application, not only an HTTP `200` or deployment result. For the requested journey:
+
+- verify `/api/bootstrap`, `/api/session`, and every new same-origin route on the exact preview;
+- prove signed-out and signed-in behavior without reading or exposing tokens;
+- exercise the requested read or mutation and confirm the authoritative response is reflected in the UI;
+- verify a relevant empty or non-subscriber state and a contained provider failure;
+- inspect desktop and 390 x 844 mobile behavior, including keyboard focus and pending/saved feedback.
+
+If the portal shell works but an authenticated route returns `404`, classify it as gateway release or composition evidence. Do not repair it with client-side fallback data. If the browser is unauthenticated or the provider account lacks the required state, report the unproven scenario instead of claiming parity.
+
+## Diagnose a delivery
+
+Read exact workflow state:
+
+```sh
+npx @withandeo/cli delivery status --delivery <delivery-id> --json
+```
+
+Retry only a requested or failed preview workflow:
+
+```sh
+npx @withandeo/cli delivery retry --delivery <delivery-id> --json
+```
+
+CLI 0.12.0 carries artifact/delivery access across automatic token refresh within
+the same login. Logout, session expiry, or revoked owner/project access still
+stop background work. For a pre-session-tracking preview stranded by an expired
+credential, only its original owner may explicitly recover it from the linked
+app with `delivery retry --delivery <delivery-id> --reauthorize --json`. This
+requires current developer access, retains the exact artifact and upload
+receipts, and cannot replace an already tracked login or publish production.
+Do not clear pending provider holds or rewrite credential IDs to recover work.
+
+Mint a new browser session for an already-succeeded delivery without rebuilding:
+
+```sh
+npx @withandeo/cli preview entries --json
+npx @withandeo/cli preview open --from <delivery-id> --json
+npx @withandeo/cli preview open --from sbl_EXAMPLE --return-path /account --json
+```
+
+Preview entry selection follows published app connections automatically. When the response requires a choice, select an eligible app using `--through prj_ENTRY`. Only the previewed app's developer grant is needed. Private apps cannot open directly; a connection administrator must enable an eligible entry. Preserve the exact `from` ID when recovering from a session error and use `preview open` instead of rebuilding. Opening replaces the browser's previous preview selection and preserves sign-in.
+
+`<delivery-id>` is the `dly_` value returned by `preview`. A `dwf_` value is a production workflow ID and must not be passed to developer-delivery commands. If a merchant administrator sees a `dwf_` publish waiting with zero attempts, the supported recovery is **Activity → Resume exact publish**; it resumes the stored exact composition without rebuilding. Use the error code, request ID, and suggested command from the CLI. Do not retry with altered IDs, another project, or raw HTTP requests.
+
+When runtime evidence is needed, stream only the linked project and exact target:
+
+```sh
+npx @withandeo/cli tail --delivery <delivery-id> --status error --json
+```
+
+Use `--production` only when the user is a merchant administrator and explicitly wants current production diagnostics. Tail output is sensitive even though Andeo omits request headers and redacts known secret fields. Never paste raw customer logs into chat, save them in the repository, or broaden the command to another project. Stop the stream as soon as the diagnostic is complete.

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.