@layers/amba 4.1.2 → 4.1.4

package/dist/api-client.d.ts

@@ -302,6 +302,12 @@ export interface FunctionDomain {
     project_id: string;
     function_name: string;
     hostname: string;
+    /** Required record at authoritative DNS. */
+    dns_record_type?: 'CNAME';
+    /** True for a registrable root rather than a subdomain. */
+    is_apex?: boolean;
+    /** Additive provider-neutral DNS warning, populated for apex hostnames. */
+    dns_note?: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     ownership_status: 'pending' | 'active' | 'error';
     /** True only when certificate/ownership are active and routing reconciliation succeeded. */
@@ -403,6 +409,8 @@ export interface FunctionDeployContext {
      * step skips the storage binding in that case.
      */
     r2_bucket_name: string | null;
+    /** Per-project key prefix for shared storage; empty for a dedicated bucket. */
+    r2_path_prefix: string | null;
 }
 export declare function getFunctionDispatchNamespace(projectId: string): Promise<ApiResponse<FunctionDeployContext>>;
 export interface InternalCredentialsResponse {
@@ -672,6 +680,22 @@ export interface SiteDomainRow {
     provider_hostname_id: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     ownership_status: 'pending' | 'active' | 'error';
+    /** Edge Worker route reconciliation. */
+    route_status: 'pending' | 'active' | 'error';
+    /** Host-to-site KV reconciliation. */
+    kv_status: 'pending' | 'active' | 'error';
+    /** Whether Amba owns and manages the authoritative DNS zone. */
+    dns_managed: boolean;
+    /** Managed-DNS reconciliation, or not_required for externally managed DNS. */
+    dns_status: 'not_required' | 'pending' | 'active' | 'error';
+    /**
+     * Authoritative reachability. True only when certificate, ownership,
+     * Worker route, KV, and (when managed) DNS are all active.
+     */
+    live: boolean;
+    dns_record_type?: 'CNAME';
+    is_apex?: boolean;
+    dns_note?: string | null;
     created_at: string;
     updated_at: string;
 }
@@ -729,8 +753,14 @@ export declare function addSiteDomainViaApi(projectId: string, siteName: string,
     provider_hostname_id: string;
     cert_status: SiteDomainRow["cert_status"];
     ownership_status: SiteDomainRow["ownership_status"];
+    route_status: SiteDomainRow["route_status"];
+    kv_status: SiteDomainRow["kv_status"];
+    dns_managed: SiteDomainRow["dns_managed"];
+    dns_status: SiteDomainRow["dns_status"];
+    live: boolean;
     dns_target: string;
     is_apex: boolean;
+    dns_record_type: "CNAME";
     dns_note: string | null;
     ssl_validation: DomainValidationRecord[];
     ownership_verification: DomainOwnershipVerification | null;
@@ -749,6 +779,16 @@ export declare function removeSiteDomainViaApi(projectId: string, siteName: stri
     hostname: string;
     deleted: true;
 }>>;
+/** Force the provider lifecycle to be re-read and persist both site-domain states. */
+export declare function refreshSiteDomainViaApi(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<SiteDomainRow & {
+    ssl_validation: DomainValidationRecord[];
+    ownership_verification: DomainOwnershipVerification | null;
+    ownership_verification_http: {
+        http_url?: string;
+        http_body?: string;
+    } | null;
+    note?: string;
+}>>;
 /**
  * Roll a live deployment back to a prior `deployment_id`. Rollback creates
  * a NEW deployment that serves the prior bundle (git-revert semantics,
@@ -797,6 +837,12 @@ export interface DomainPurchaseResult {
     provisioned?: boolean;
     cert_status?: string;
     ownership_status?: string;
+    route_status?: string;
+    kv_status?: string;
+    dns_managed?: boolean;
+    dns_status?: string;
+    /** Authoritative reachability across provider, route, KV, and managed DNS. */
+    hostname_live?: boolean;
     dns_autoconfigured?: boolean;
     url?: string;
     public_url?: string;
@@ -813,7 +859,22 @@ export declare function purchaseDomainViaApi(projectId: string, body: {
     privacy?: boolean;
     years?: number;
 }): Promise<ApiResponse<DomainPurchaseResult>>;
-export declare function listPurchasedDomainsViaApi(projectId: string): Promise<ApiListResponse<Record<string, unknown>>>;
+export interface PurchasedDomainStatus extends Record<string, unknown> {
+    domain: string;
+    status: string;
+    site?: string | null;
+    provisioned: boolean;
+    cert_status?: string;
+    ownership_status?: string;
+    route_status?: string;
+    kv_status?: string;
+    dns_managed?: boolean;
+    dns_status?: string;
+    /** Reachability; deliberately separate from purchase/payment completion. */
+    hostname_live: boolean;
+    aliases: Array<Record<string, unknown>>;
+}
+export declare function listPurchasedDomainsViaApi(projectId: string): Promise<ApiListResponse<PurchasedDomainStatus>>;
 /**
  * Delete a function entirely. Cascade: removes the deployed script
  * (backend 404 treated as success), then marks every historical
@@ -833,10 +894,19 @@ export declare function attachSiteDomain(projectId: string, siteName: string, in
     provider_hostname_id?: string;
 }): Promise<ApiResponse<SiteDomainRow>>;
 export declare function listSiteDomains(projectId: string, siteName: string): Promise<ApiListResponse<SiteDomainRow>>;
+/** @deprecated Lifecycle is provider-owned; this delegates to authoritative refresh. */
 export declare function updateSiteDomain(projectId: string, siteName: string, hostname: string, patch: {
     cert_status: SiteDomainRow['cert_status'];
     provider_hostname_id?: string;
-}): Promise<ApiResponse<SiteDomainRow>>;
+}): Promise<ApiResponse<SiteDomainRow & {
+    ssl_validation: DomainValidationRecord[];
+    ownership_verification: DomainOwnershipVerification | null;
+    ownership_verification_http: {
+        http_url?: string;
+        http_body?: string;
+    } | null;
+    note?: string;
+}>>;
 export declare function detachSiteDomain(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     deleted: boolean;
 }>>;

package/dist/commands/sites.d.ts

@@ -36,11 +36,14 @@ export interface SitesDomainAddOptions {
     zoneId?: string;
     /** Skip the cert poll loop. Caller will check status later. */
     noWait?: boolean;
-    /** Max seconds to wait for cert_status='active' before bailing. Default 600. */
+    /** Max seconds to wait for both ownership and certificate activation. Default 600. */
     timeout?: number;
 }
 export declare function sitesDomainAddCommand(hostname: string, options: SitesDomainAddOptions): Promise<void>;
 export declare function sitesDomainListCommand(siteName: string): Promise<void>;
+export declare function sitesDomainRefreshCommand(hostname: string, options: {
+    site: string;
+}): Promise<void>;
 export declare function sitesDomainRemoveCommand(hostname: string, options: {
     site: string;
     zoneId?: string;
@@ -71,6 +74,10 @@ declare function collectFiles(dir: string): Promise<SiteFile[]>;
 export declare class SitesStaticOnlyError extends Error {
     readonly code: "SITES_STATIC_ONLY";
 }
+declare function isProviderTerminalDomainFailure(d: {
+    cert_status: string;
+    ownership_status: string;
+}): boolean;
 /**
  * Test-only re-export of internal helpers. Tests reach in via this
  * namespace so the production module surface stays clean. Not a public
@@ -80,5 +87,6 @@ export declare const __testHelpers: {
     collectFiles: typeof collectFiles;
     BLOCKED_FILE_NAMES: Set<string>;
     BLOCKED_DIR_NAMES: Set<string>;
+    isProviderTerminalDomainFailure: typeof isProviderTerminalDomainFailure;
 };
 export {};

package/dist/index.js

@@ -1137,6 +1137,10 @@ async function addSiteDomainViaApi(projectId, siteName, hostname) {
 async function removeSiteDomainViaApi(projectId, siteName, hostname) {
 	return request("DELETE", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/domains/${encodeURIComponent(hostname)}`);
 }
+/** Force the provider lifecycle to be re-read and persist both site-domain states. */
+async function refreshSiteDomainViaApi(projectId, siteName, hostname) {
+	return request("POST", `/projects/${projectId}/sites/${encodeURIComponent(siteName)}/domains/${encodeURIComponent(hostname.toLowerCase())}/refresh-cert`);
+}
 /**
 * Roll a live deployment back to a prior `deployment_id`. Rollback creates
 * a NEW deployment that serves the prior bundle (git-revert semantics,
@@ -5479,7 +5483,7 @@ async function loadProjectConfig(cwd = process.cwd()) {
 		if (!apiUrl) apiUrl = parsed["AMBA_API_URL"];
 		if (projectId && apiUrl) break;
 	}
-	if (!projectId) throw new Error(`AMBA_PROJECT_ID not found. Run ${pc.cyan("amba init")} or set it in .env.local.`);
+	if (!projectId) throw new Error(`AMBA_PROJECT_ID not found. Export it, pass --project where supported, or run ${pc.cyan("amba init")} in this directory. The CLI reads .env.local/.env from the current working directory and does not search parent directories.`);
 	return {
 		projectId,
 		apiUrl: apiUrl ?? "https://api.amba.dev"
@@ -6473,6 +6477,7 @@ function printDnsInstructions(domain) {
 	if ("cleanup_pending" in domain && domain.cleanup_pending === true) console.log(pc.yellow("    Routing cleanup is incomplete; retry with domains refresh."));
 	if ("dns_autoconfigured" in domain && domain.dns_autoconfigured === true) console.log(pc.dim(`    DNS records published automatically${domain.dns_records_published === void 0 ? "" : ` (${domain.dns_records_published})`}.`));
 	if (domain.dns_target) console.log(pc.dim(`    DNS target: CNAME ${domain.hostname} → ${domain.dns_target}`));
+	if (domain.dns_note) console.log(pc.yellow(`    DNS requirement: ${domain.dns_note}`));
 	for (const record of domain.ssl_validation ?? []) if (record.txt_name && record.txt_value) console.log(pc.dim(`    Certificate TXT: ${record.txt_name} = ${record.txt_value}`));
 	else if (record.http_url && record.http_body) console.log(pc.dim(`    Certificate HTTP: ${record.http_url} → ${record.http_body}`));
 	const ownership = domain.ownership_verification;
@@ -9017,7 +9022,6 @@ async function sitesDomainAddCommand(hostname, options) {
 	console.log(pc.green("  ✓") + ` Custom hostname registered`);
 	const validation = res.data.ssl_validation ?? [];
 	const ownership = res.data.ownership_verification;
-	const isApex = res.data.is_apex ?? false;
 	if (validation.length > 0 || ownership) {
 		console.log();
 		console.log(pc.dim("  1. Publish these DNS records to verify ownership:"));
@@ -9031,10 +9035,8 @@ async function sitesDomainAddCommand(hostname, options) {
 	}
 	console.log(`     ${pc.bold("CNAME")} ${hostname}  →  ${pc.cyan(res.data.dns_target)}`);
 	console.log();
-	if (isApex) {
-		console.log(pc.dim(`  ${hostname} is a root domain — the CNAME above works only if your DNS provider`));
-		console.log(pc.dim(`  flattens CNAME-at-root. If it doesn't, A-record apex support is coming soon;`));
-		console.log(pc.dim(`  use a subdomain like app.${hostname} in the meantime.`));
+	if (res.data.dns_note) {
+		console.log(pc.yellow(`  DNS requirement: ${res.data.dns_note}`));
 		console.log();
 	}
 	if (options.noWait) {
@@ -9052,11 +9054,11 @@ async function sitesDomainAddCommand(hostname, options) {
 			console.log(pc.dim(`  ${line}`));
 			lastLine = line;
 		}
-		if (row.cert_status === "active" && row.ownership_status === "active") {
+		if (row.live === true) {
 			console.log(pc.green("  ✓") + ` ${hostname} is live with a valid certificate.`);
 			return;
 		}
-		if (row.cert_status === "error" || row.ownership_status === "error") throw new Error(`Domain setup failed for ${hostname}. Confirm the TXT record(s) above are published and the CNAME points at ${res.data.dns_target}.`);
+		if (isProviderTerminalDomainFailure(row)) throw new Error(`Domain setup failed for ${hostname}. Confirm the TXT record(s) above are published and the CNAME points at ${res.data.dns_target}.`);
 		await sleep(5e3);
 	}
 	console.log(pc.yellow(`  ! Timed out after ${options.timeout ?? 600}s. Re-run \`amba sites describe ${options.site}\` to check status.`));
@@ -9073,6 +9075,15 @@ async function sitesDomainListCommand(siteName) {
 	for (const d of res.data) console.log(`  ${pc.bold(d.hostname)}  ${formatDomainStatus(d)}`);
 	console.log();
 }
+async function sitesDomainRefreshCommand(hostname, options) {
+	validateSiteName(options.site);
+	validateHostname(hostname);
+	const projectConfig = await loadProjectConfig();
+	const normalisedHostname = hostname.toLowerCase();
+	const res = await refreshSiteDomainViaApi(projectConfig.projectId, options.site, normalisedHostname);
+	console.log(`  ${pc.bold(res.data.hostname)}  ${formatDomainStatus(res.data)}`);
+	if (res.data.note) console.log(pc.dim(`  ${res.data.note}`));
+}
 async function sitesDomainRemoveCommand(hostname, options) {
 	validateSiteName(options.site);
 	validateHostname(hostname);
@@ -9180,12 +9191,18 @@ function formatCertStatus(s) {
 	return pc.yellow(s);
 }
 /**
-* Render BOTH lifecycle states for a domain row. A domain is only live when
-* ownership AND cert are both `active`, so display paths must show both —
-* showing cert alone reads "live" while ownership is still pending.
+* Render every serving plane. Only the server-derived `live` field is
+* authoritative; these states explain what is still converging.
 */
 function formatDomainStatus(d) {
-	return `ownership: ${formatCertStatus(d.ownership_status)}  cert: ${formatCertStatus(d.cert_status)}`;
+	const states = [`ownership: ${formatCertStatus(d.ownership_status)}`, `cert: ${formatCertStatus(d.cert_status)}`];
+	if (d.route_status) states.push(`route: ${formatCertStatus(d.route_status)}`);
+	if (d.kv_status) states.push(`kv: ${formatCertStatus(d.kv_status)}`);
+	if (d.dns_managed && d.dns_status) states.push(`dns: ${formatCertStatus(d.dns_status)}`);
+	return states.join("  ");
+}
+function isProviderTerminalDomainFailure(d) {
+	return d.cert_status === "error" || d.ownership_status === "error";
 }
 function sleep(ms) {
 	return new Promise((r) => setTimeout(r, ms));
@@ -9305,9 +9322,13 @@ async function domainsBuyCommand(domain, options) {
 	}
 	console.log(pc.green("  ✓") + ` Registered ${pc.bold(hostname)}`);
 	if (r.provisioned) {
-		console.log(pc.green("  ✓") + ` Connected to ${options.site}${r.dns_autoconfigured ? " — no DNS setup needed" : ""}.`);
-		if (r.public_url) console.log(pc.green("  ✓") + ` Live at ${pc.underline(r.public_url)}`);
-		console.log(pc.dim("    The TLS certificate is issuing now (usually a minute or two)."));
+		console.log(pc.green("  ✓") + ` Binding created for ${options.site}${r.dns_autoconfigured ? " — no DNS setup needed" : ""}.`);
+		const hostnameLive = r.hostname_live === true;
+		if (r.public_url && hostnameLive) console.log(pc.green("  ✓") + ` Live at ${pc.underline(r.public_url)}`);
+		else if (r.public_url) {
+			console.log(pc.yellow("  !") + ` Pending activation at ${pc.underline(r.public_url)}`);
+			console.log(pc.dim(`    certificate=${r.cert_status ?? "pending"}, ownership=${r.ownership_status ?? "pending"}, route=${r.route_status ?? "pending"}, kv=${r.kv_status ?? "pending"}, dns=${r.dns_status ?? "pending"}; wait for hostname_live=true.`));
+		}
 	} else if (r.message) console.log(pc.dim(`    ${r.message}`));
 	console.log();
 }
@@ -9674,7 +9695,7 @@ async function diffConfigCommand(file = DEFAULT_BUNDLE_FILE, options = {}) {
 //#endregion
 //#region src/index.ts
 const program = new Command();
-program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.2");
+program.name("amba").description("amba — agent-native backend-as-a-service for mobile apps.").version("4.1.4");
 program.option("--token <pat>", "Use a Personal Access Token for headless / CI / agent use (overrides ~/.amba/credentials.json + AMBA_PAT env)");
 program.hook("preAction", (thisCommand) => {
 	setBearerOverride(resolveTokenSource({
@@ -10035,6 +10056,9 @@ sitesDomain.command("add <hostname>").description("Attach a custom hostname (DV
 sitesDomain.command("list <site>").description("List custom hostnames attached to a site").action(async (site) => {
 	await runAction(() => sitesDomainListCommand(site));
 });
+sitesDomain.command("refresh <hostname>").description("Re-check hostname ownership and certificate status").requiredOption("--site <name>", "Site name the hostname is attached to").action(async (hostname, opts) => {
+	await runAction(() => sitesDomainRefreshCommand(hostname, { site: opts.site }));
+});
 sitesDomain.command("remove <hostname>").description("Detach a custom hostname (best-effort edge detach + control-plane row delete)").requiredOption("--site <name>", "Site name the hostname is attached to").option("--zone-id <id>", "DNS zone id (default: env AMBA_DNS_ZONE_ID)").action(async (hostname, opts) => {
 	await runAction(() => sitesDomainRemoveCommand(hostname, {
 		site: opts.site,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layers/amba",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "amba — agent-native backend-as-a-service. Functions, collections, storage, AI, email, queues, sites, and `amba ship` to take an Expo app live on the App Store + Google Play. `npx @layers/amba init` to start.",
   "type": "module",
   "bin": {
@@ -49,8 +49,8 @@
     "tsdown": "^0.12.5",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@layers/amba-shared": "4.0.4",
-    "@layers/amba-mcp": "4.0.6"
+    "@layers/amba-mcp": "4.0.8",
+    "@layers/amba-shared": "4.0.4"
   },
   "scripts": {
     "build": "tsdown && tsc --emitDeclarationOnly",

package/skill-bundle/references/infrastructure.md

@@ -40,6 +40,11 @@ Run user code in a sandbox triggered by HTTP, cron, or webhook. The function get
 | `amba_function_domains_attach` | Attach an exact hostname to a function and return DNS validation records. | `{ project_id, name: "feed", hostname: "feeds.example.com" }` |
 | `amba_function_domains_list` / `amba_function_domains_refresh` | Read or refresh ownership/certificate status. | `{ project_id, name: "feed", hostname: "feeds.example.com" }` |
 | `amba_function_domains_remove` | Detach an exact function hostname. | `{ project_id, name: "feed", hostname: "feeds.example.com" }` |
+
+For every custom hostname, publish a real provider-stored CNAME to the returned target and heed
+the unconditional `dns_note`. Do not substitute ALIAS, ANAME, or copied A/AAAA addresses. Treat Site and Function hostnames
+as ready only when `live=true` (certificate and hostname activation both active), not from a
+successful TLS handshake or `cert_status=active` alone.
 | `amba_functions_list` / `amba_list_functions` | List functions. | `{ project_id }` |
 | `amba_functions_get` / `amba_get_function` | Read function metadata. | `{ project_id, function_id }` |
 | `amba_functions_get_logs` / `amba_get_function_logs` | Recent invocation logs. | `{ project_id, function_id, limit: 100 }` |