@withandeo/cli 0.19.13 → 0.19.15

package/dist/main.js

@@ -227,8 +227,10 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await linkProject(cwd, options, runtime) };
         case "doctor":
             return await doctor(cwd, options, runtime);
-        case "preview":
-            return { value: await preview(cwd, options, runtime) };
+        case "preview": {
+            const value = await preview(cwd, options, runtime);
+            return { value, exitCode: value.status === "timeout" ? 3 : 0 };
+        }
         case "preview entries":
             return { value: await previewEntries(cwd, options, runtime) };
         case "preview open":
@@ -1468,6 +1470,12 @@ async function sourceMerge(cwd, options, runtime) {
         throw new CliError("argument_invalid", "Administrator authorization flags require --validation-mode administrator_authorized.");
     }
     const access = await sourceReadAccess(cwd, options, runtime);
+    if (access.repository.assignedFeatureBranch) {
+        if (headBranch && headBranch !== access.repository.assignedFeatureBranch)
+            throw new CliError("agent_branch_scope_mismatch", "This run may merge only its assigned feature branch.");
+        if (validationMode === "administrator_authorized")
+            throw new CliError("agent_merge_mode_invalid", "Persistent agents use the native preview merge workflow under source.merge.");
+    }
     const result = await access.client.sourceMerge(access.repository.id, { headBranch, title, changeId, idempotencyKey,
         expectedHead, expectedSnapshot: expectedSnapshot ? Number(expectedSnapshot) : undefined, dryRun,
         expectedBase, expectedPolicyRevision: policyRevision === undefined ? undefined : Number(policyRevision),
@@ -1487,7 +1495,7 @@ async function sourceMerge(cwd, options, runtime) {
         if (merge.stage === "awaiting_approval")
             return { ...result, merge };
         await runtime.sleep(Math.min(5000, timeout * 1000 - poll * 5000));
-        const current = merge.changeId ? await access.client.sourceChangeRequest(merge.changeId) : await access.client.sourceMergeStatus(merge.id);
+        const current = merge.changeId && !access.repository.assignedFeatureBranch ? await access.client.sourceChangeRequest(merge.changeId) : await access.client.sourceMergeStatus(merge.id);
         if ("changeRequest" in current)
             requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
         if (!current.merge || current.merge.id !== merge.id)
@@ -2120,6 +2128,11 @@ async function preview(cwd, options, runtime, uploadOnly = false) {
     if (!offline && !context.link)
         throw new CliError("project_not_linked", "This app is not linked to an Andeo project.", "andeo link --json");
     const authorized = offline ? null : await authenticatedClient(cwd, context.link, options, runtime);
+    if (authorized?.persistent) {
+        if (uploadOnly)
+            throw new CliError("agent_artifact_upload_unavailable", "Persistent agents create previews from their assigned managed source branch.", "andeo preview --json");
+        return persistentSourcePreview(context, options, runtime, authorized.client);
+    }
     if (authorized && context.link && !uploadOnly) {
         assertPreviewEntry(await authorized.client.previewEntries(context.link.projectId), options.flags.get("through"));
     }
@@ -2158,6 +2171,7 @@ async function preview(cwd, options, runtime, uploadOnly = false) {
     let delivery = await client.createDelivery(context.link.projectId, {
         submissionId: finalized.id,
         idempotencyKey: options.flags.get("delivery-key")
+            ?? options.flags.get("idempotency-key")
             ?? generatedDeliveryKey(context.link.projectId, finalized.id),
     });
     if (options.booleans.has("no-wait")) {
@@ -2190,6 +2204,55 @@ async function preview(cwd, options, runtime, uploadOnly = false) {
         productionChanged: false,
     };
 }
+async function persistentSourcePreview(context, options, runtime, client) {
+    const principal = await client.whoami();
+    if (principal.actorKind !== "persistent_agent")
+        throw new CliError("agent_authentication_failed", "The Cloud credential did not authenticate a persistent agent.");
+    const projectId = context.link.projectId;
+    if (!principal.projects.some(project => project.projectId === projectId))
+        throw new CliError("project_not_found", "This run does not have access to the linked project.");
+    if (options.flags.has("through"))
+        throw new CliError("agent_preview_entry_unsupported", "Persistent previews use their isolated entry; --through is not supported.");
+    const repository = (await client.sourceRepository(projectId)).repository;
+    if (!repository?.assignedFeatureBranch || repository.status !== "active")
+        throw new CliError("source_repository_missing", "An active run-assigned managed repository is required.");
+    const source = await sourceState(context.root, runtime);
+    if (source.dirty)
+        throw new CliError("preview_committed_source_required", "Commit and push the exact source before requesting an isolated preview.", "andeo source push --json");
+    const timeout = Number(options.flags.get("timeout-seconds") ?? "1200");
+    if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 3600)
+        throw new CliError("argument_invalid", "--timeout-seconds must be between 1 and 3600.");
+    const idempotencyKey = options.flags.get("idempotency-key") ?? options.flags.get("delivery-key") ?? `source-preview-${createHash("sha256").update(JSON.stringify({ repositoryId: repository.id, headBranch: repository.assignedFeatureBranch, headSha: source.revision })).digest("hex")}`;
+    if (!/^[A-Za-z0-9:_-]{8,128}$/u.test(idempotencyKey))
+        throw new CliError("argument_invalid", "--idempotency-key must contain 8–128 letters, numbers, colons, underscores or hyphens.");
+    const result = await client.createSourcePreview(repository.id, { headBranch: repository.assignedFeatureBranch, expectedHeadSha: source.revision, idempotencyKey });
+    let preview = result.preview;
+    const assertExact = () => {
+        if (!/^sbl_[A-Za-z0-9_-]+$/u.test(preview.id) || preview.buildId !== preview.id || preview.headBranch !== repository.assignedFeatureBranch || preview.headSha !== source.revision)
+            throw new CliError("source_preview_changed", "The returned preview does not match the exact assigned source.");
+    };
+    assertExact();
+    const summary = () => ({ created: result.created, preview, projectId, sourceRevision: source.revision, releaseId: preview.releaseId, compositionId: preview.previewCompositionId,
+        from: preview.id, productionChanged: false, nextCommand: `andeo preview open --from ${preview.id} --json` });
+    if (options.booleans.has("no-wait"))
+        return { ...summary(), status: preview.status };
+    for (let poll = 0; poll < Math.ceil(timeout / 5) && !["succeeded", "preview_ready", "failed"].includes(preview.status); poll++) {
+        await runtime.sleep(Math.min(5000, timeout * 1000 - poll * 5000));
+        const previousId = preview.id;
+        preview = (await client.sourcePreview(previousId)).preview;
+        assertExact();
+        if (preview.id !== previousId)
+            throw new CliError("source_preview_changed", "The preview operation changed while waiting.");
+    }
+    if (preview.status === "failed")
+        throw new CliError(preview.error?.code ?? "source_preview_failed", preview.error?.message ?? "The isolated preview build failed.", undefined, { from: preview.id });
+    if (!["succeeded", "preview_ready"].includes(preview.status))
+        return { ...summary(), status: "timeout", waitTimedOut: true };
+    const session = await client.openSourcePreview(preview.id, options.flags.get("return-path") ?? context.config.returnPath);
+    if (session.projectId !== projectId || session.from !== preview.id || session.sourceRevision !== source.revision)
+        throw new CliError("source_preview_changed", "The opened preview does not match the exact linked source.");
+    return { ...summary(), status: "succeeded", previewUrl: session.url, previewGrantId: session.grantId, previewExpiresAt: session.expiresAt, sourceVerification: session.sourceVerification };
+}
 async function deliveryStatus(cwd, options, runtime) {
     const context = await loadProjectContext(cwd);
     const { client } = await authenticatedClient(cwd, context.link, options, runtime);
@@ -2223,7 +2286,23 @@ async function previewOpen(cwd, options, runtime) {
     const from = options.flags.get("from");
     if (!from || !/^(dly|sbl)_[A-Za-z0-9_-]+$/.test(from))
         throw new CliError("preview_source_invalid", "Use --from with an exact dly_ delivery or sbl_ source-build ID.");
-    const { client } = await authenticatedClient(cwd, context.link, options, runtime);
+    const access = await authenticatedClient(cwd, context.link, options, runtime);
+    const { client } = access;
+    if (access.persistent) {
+        const principal = await client.whoami();
+        if (principal.actorKind !== "persistent_agent")
+            throw new CliError("agent_authentication_failed", "The Cloud credential did not authenticate a persistent agent.");
+        if (!principal.projects.some(project => project.projectId === context.link.projectId))
+            throw new CliError("project_not_found", "This run does not have access to the linked project.");
+        if (!/^sbl_[A-Za-z0-9_-]+$/u.test(from))
+            throw new CliError("preview_source_invalid", "Persistent preview opening requires an exact sbl_ source-build ID.");
+        if (options.flags.has("through"))
+            throw new CliError("agent_preview_entry_unsupported", "Persistent previews use their isolated entry; --through is not supported.");
+        const session = await client.openSourcePreview(from, options.flags.get("return-path") ?? context.config.returnPath);
+        if (session.projectId !== context.link.projectId || session.from !== from)
+            throw new CliError("source_preview_changed", "The opened preview belongs to another linked source.");
+        return session;
+    }
     return client.openPreview(context.link.projectId, { from, returnPath: options.flags.get("return-path") ?? context.config.returnPath,
         entryProjectId: options.flags.get("through") });
 }
@@ -2238,7 +2317,7 @@ async function authenticatedClient(cwd, link, options, runtime) {
     let apiUrl = selectedApiUrl(options, link, runtime.environment, runtime.defaultApiUrl);
     const cloud = await cloudAgentClient(runtime.environment, cwd, runtime.fetcher, { tokenStdin: options.booleans.has("token-stdin"), profile: options.flags.has("profile"), apiUrl });
     if (cloud)
-        return { client: new AgentApiClient(apiUrl, "task-run", cloud.fetcher), apiUrl, source: "cloud-agent", accessTokenExpiresAt: cloud.accessTokenExpiresAt };
+        return { client: new AgentApiClient(apiUrl, "task-run", cloud.fetcher), apiUrl, source: "cloud-agent", accessTokenExpiresAt: cloud.accessTokenExpiresAt, persistent: true };
     const networkSecret = readNetworkSecret(runtime.environment, apiUrl);
     if (networkSecret !== undefined) {
         if (options.booleans.has("token-stdin") || options.flags.has("profile")) {
@@ -2254,7 +2333,7 @@ async function authenticatedClient(cwd, link, options, runtime) {
             : runtime.environment.TENDER_ACCOUNTS_TOKEN
                 ? "environment"
                 : "dev-vars";
-        return { client: new AgentApiClient(apiUrl, explicit, runtime.fetcher), apiUrl, source };
+        return { client: new AgentApiClient(apiUrl, explicit, runtime.fetcher), apiUrl, source, persistent: /^ta_run_agc_[a-f0-9]{24}\.[A-Za-z0-9_-]{43}$/u.test(explicit) };
     }
     const profile = await selectAuthProfile(cwd, options, runtime);
     if (!options.flags.has("api-url") && !runtime.environment.TENDER_ACCOUNTS_API_URL && !link) {
@@ -2872,6 +2951,7 @@ function assertAllowedOptions(topic, options) {
             "no-wait",
             "submission-key",
             "delivery-key",
+            "idempotency-key",
             "timeout-seconds",
             "return-path",
             "through",
@@ -3156,7 +3236,7 @@ Account workflow entitlement is required for new starts. Run status is authorita
         check: "Usage: andeo check [--json]\n\nRun the app's declared validation command.",
         build: "Usage: andeo build [--json]\n\nRun validation and packaging, then verify the complete portable artifact.",
         upload: "Usage: andeo upload [--dry-run] [--submission-key KEY] [--json]\n\nValidate, package and retain an exact artifact for administrator review. Does not create a preview or publish production.",
-        preview: "Usage: andeo preview [--through PROJECT_ID] [--return-path /account] [--dry-run] [--no-wait] [--json]\n\nBuild an exact app preview. Published connections select its entry automatically. Use preview entries to inspect choices or preview open --from dly_... to reopen without rebuilding.",
+        preview: "Usage: andeo preview [--through PROJECT_ID] [--return-path /account] [--dry-run] [--no-wait] [--idempotency-key KEY] [--json]\n\nBuild an exact app preview. Persistent Cloud agents with preview.build/open request an isolated build of their assigned pushed branch; no local artifact upload is used. Unsupported bindings fail closed. Other credentials use local packaging and published entry selection. Use preview open --from sbl_... (persistent) or dly_... to reopen without rebuilding.",
         production: "Usage: andeo production <releases|rollback> [options]",
         "production releases": "Usage: andeo production releases [--project PROJECT_ID] [--json]\n\nList immutable production releases and rollback eligibility.",
         "production rollback": "Usage: andeo production rollback [--project PROJECT_ID] --release RELEASE_ID --expected-release CURRENT_ID --expected-revision N --idempotency-key KEY [--json]\n\nMerchant administrators restore a previously successful app release without building or uploading code.",
@@ -3181,7 +3261,7 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "source change": "Usage: andeo source change <create|list|show|close|resume|cancel|take-over> [options]\n\nCreate and inspect exact preview-backed changes, or recover an accepted merge intent.",
         "source change cancel": "Usage: andeo source change cancel --change scr_... [--json]\n\nWithdraw new work for an accepted intent. Already-issued effects require readback; source may already be merged.",
         "source change take-over": "Usage: andeo source change take-over --change scr_... --idempotency-key KEY [--json]\n\nAdministrator only. Records a new bounded authorization for the same exact inputs; then use source change resume.",
-        "source merge": "Usage: andeo source merge --head BRANCH --title TITLE --idempotency-key KEY [--dry-run] [--wait] [--timeout-seconds N] [--json]\n       andeo source merge --change scr_... --idempotency-key KEY [--wait] [--json]\n       andeo source merge --head BRANCH --title TITLE --validation-mode administrator_authorized --expected-base SHA --expected-head SHA --expected-policy-revision N --authorize --idempotency-key KEY [--continuation source_only] [--note TEXT] [--wait] [--json]\n       andeo source merge <status|resume|cancel|take-over> --merge smi_... [options]\n\nRequest exact fast-forward landing. Native review remains the default. Administrator-authorized source-only mode requires saved policy and a current administrator; Andeo does not independently verify checks. Inspect refs and blockers with --dry-run before authorizing. Waiting is bounded and never cancels hosted work.\n\nExamples:\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --dry-run --json\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --wait --json",
+        "source merge": "Usage: andeo source merge --head BRANCH --title TITLE --idempotency-key KEY [--dry-run] [--wait] [--timeout-seconds N] [--json]\n       andeo source merge --change scr_... --idempotency-key KEY [--wait] [--json]\n       andeo source merge --head BRANCH --title TITLE --validation-mode administrator_authorized --expected-base SHA --expected-head SHA --expected-policy-revision N --authorize --idempotency-key KEY [--continuation source_only] [--note TEXT] [--wait] [--json]\n       andeo source merge <status|resume|cancel|take-over> --merge smi_... [options]\n\nRequest exact fast-forward landing. Persistent agents require source.merge for the assigned branch and review.prepare for implicit review creation. The grant delegates source approval without per-change administrator approval; a successful exact isolated preview is required. Landing may deploy under the saved publication policy. Human/legacy native review keeps its existing approval contract. Administrator-authorized source-only mode requires saved policy and a current administrator; Andeo does not independently verify checks. Inspect refs and blockers with --dry-run before authorizing. Waiting is bounded and never cancels hosted work.\n\nExamples:\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --dry-run --json\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --wait --json",
         "source merge status": "Usage: andeo source merge status --merge smi_... [--json]\n\nRead the retained source, validation, authorization, continuation and cleanup outcomes. Source-only merged is successful completion.",
         "source merge resume": "Usage: andeo source merge resume --merge smi_... [--json]\n\nResume the same exact eligible intent after revalidating authority. Never substitutes a new source snapshot.",
         "source merge cancel": "Usage: andeo source merge cancel --merge smi_... [--json]\n\nWithdraw new work. Already-issued effects require readback; cancellation cannot undo a merge.",
@@ -3207,7 +3287,7 @@ Account workflow entitlement is required for new starts. Run status is authorita
         delivery: "Usage: andeo delivery <status|retry> --delivery dly_... [--json]\n\nThese commands accept the developer-delivery ID returned by preview. A dwf_ ID is a production workflow managed by merchant administrators in Activity.",
         "delivery status": "Usage: andeo delivery status --delivery dly_... [--json]\n\nRead one developer preview delivery. Do not pass a dwf_ production workflow ID.",
         "preview entries": "Usage: andeo preview entries [--json]\n\nList eligible published entry apps and the selected default for this linked app.",
-        "preview open": "Usage: andeo preview open --from dly_...|sbl_... [--through PROJECT_ID] [--return-path /account] [--json]\n\nOpen the exact deployed preview without rebuilding or uploading. Private apps open through their published connections. Opening again renews access.",
+        "preview open": "Usage: andeo preview open --from dly_...|sbl_... [--through PROJECT_ID] [--return-path /account] [--json]\n\nOpen the exact deployed preview without rebuilding or uploading. Persistent agents require preview.open and an exact permitted sbl_ source preview; --through is unavailable and access remains bounded by the run/derived grant. Other private apps open through their published connections.",
         "delivery retry": "Usage: andeo delivery retry --delivery dly_... [--reauthorize] [--json]\n\nRetry one requested or failed developer preview idempotently. --reauthorize explicitly authorizes a legacy preview for the same owner and linked project using the current CLI login; it cannot replace another login's recorded grant or publish production. Normal credential refresh needs no flag. A dwf_ production workflow is resumed by a merchant administrator from Activity.",
         skill: "Usage: andeo skill <print|install|status|sync> [options]",
         "skill status": "Usage: andeo skill status [--agent codex|claude] [--directory PATH] [--json]\n\nCheck the installed guide against the compatible public revision. Reports local_changes, unmanaged or not_installed without overwriting files. Offline and incompatible checks fail explicitly.",