unfold-deploy 0.0.0-stage → 0.2.0

package/dist/providers/gcloud/parser.js

@@ -0,0 +1,149 @@
+const START = /^(?:(Building using (\S+) and deploying)|Deploying(?: new)?)\s+(?:container|sources|locally-built source)?\s*to Cloud Run (service|job|worker pool) \[(.+?)\] in project \[(.+?)\](?: region \[(.+?)\])?/;
+const STEP = /^(✓|OK|X|-|\.)?\s*(Creating Container Repository|Validating configuration|Uploading sources|Building Container|Creating Revision(?: in region: \S+)?|Routing traffic|Splitting instances|Setting IAM Policy|Enabling IAP)(?:\.\.\.)?\s*(.*)$/u;
+const SERVED = /Service \[(.+?)\] revision \[(.+?)\] has been deployed and is serving (\d+) percent of traffic/;
+const ERROR = /^ERROR: \((gcloud[\w.-]*)\) (.+)$/;
+const PROMPT = /\((?:y\/N|Y\/n)\)\??\s*$|^Please (?:specify|enter)|^Service name|^Source code location|^Do you want to continue/;
+const LOGS = /Logs are available at \[\s*(https?:\/\/\S+?)\s*\]/;
+const CAUSE = /failed to start|listen on the port|PORT=\d+|HealthCheckContainerError|Container import failed|exited with|\berror\b|failed|denied|not found|quota/i;
+const STEP_STAGE = {
+    'Creating Container Repository': 'prepare',
+    'Validating configuration': 'prepare',
+    'Uploading sources': 'build',
+    'Building Container': 'build',
+    'Creating Revision': 'deploy',
+    'Routing traffic': 'deploy',
+    'Splitting instances': 'deploy',
+    'Setting IAM Policy': 'deploy',
+    'Enabling IAP': 'deploy',
+};
+export class GcloudParser {
+    phase = 'start';
+    /** gcloud sometimes prints an HTML error page after "ERROR: … HTTPError". */
+    inHtmlError = false;
+    sawBuild = false;
+    prebuiltImage = false;
+    feed(line) {
+        const text = line.text.trim();
+        if (!text)
+            return [];
+        let m;
+        if ((m = START.exec(text))) {
+            this.phase = 'prepare';
+            this.prebuiltImage = !m[1] && /container to/.test(text);
+            const out = [
+                { kind: 'fact', key: 'service', label: 'Service', value: m[4], stage: 'prepare' },
+                { kind: 'fact', key: 'project', label: 'Project', value: m[5], stage: 'prepare' },
+                { kind: 'stage', stage: 'prepare', status: 'confirmed', note: `Deploying ${m[3]} ${m[4]} in project ${m[5]}${m[6] ? `, region ${m[6]}` : ''}.` },
+            ];
+            if (m[6])
+                out.push({ kind: 'fact', key: 'region', label: 'Region', value: m[6], stage: 'prepare' });
+            if (m[2])
+                out.push({ kind: 'fact', key: 'buildType', label: 'Build with', value: m[2], stage: 'build' });
+            if (this.prebuiltImage)
+                out.push({ kind: 'evidence', stage: 'build', note: 'Deploying a prebuilt container image, so there is nothing to build.' });
+            return out;
+        }
+        if (PROMPT.test(text))
+            return [{ kind: 'evidence', stage: 'prepare', note: 'gcloud asked a question in your terminal.' }];
+        if ((m = STEP.exec(text))) {
+            const label = m[2].replace(/ in region: .*/, '');
+            const stage = STEP_STAGE[label];
+            const mark = m[1];
+            const rest = m[3] ?? '';
+            const out = [];
+            const logs = LOGS.exec(rest);
+            if (logs)
+                out.push({ kind: 'fact', key: 'logsUrl', label: 'Build logs', value: logs[1], href: logs[1], stage: 'build' });
+            if (stage === 'build')
+                this.sawBuild = true;
+            if (stage !== 'prepare' && this.rank(stage) > this.rank(this.phase))
+                this.phase = stage;
+            if (mark === '✓' || mark === 'OK') {
+                // A finished build step only confirms the stage once the container is built;
+                // a finished revision step only once traffic is routed (or the IAM policy set).
+                if (label === 'Building Container' || label === 'Routing traffic' || label === 'Splitting instances')
+                    out.push({ kind: 'stage', stage, status: 'confirmed', note: `${label} finished.` });
+                else
+                    out.push({ kind: 'evidence', stage, note: `${label} finished.` });
+            }
+            else if (mark === 'X') {
+                out.push({ kind: 'stage', stage, status: 'failed', note: `${label} failed.${rest && !logs ? ` ${rest}` : ''}` });
+                if (rest && !logs)
+                    out.push({ kind: 'error', severity: 'cause', stage, message: rest, priority: 2 });
+            }
+            else if (mark === '-') {
+                out.push({ kind: 'evidence', stage, note: `${label} was interrupted.` });
+            }
+            else if (mark !== '.') {
+                out.push({ kind: 'stage', stage, status: 'active', note: `${label}…` });
+            }
+            return out;
+        }
+        if ((m = SERVED.exec(text))) {
+            this.phase = 'live';
+            const percent = Number(m[3]);
+            return [
+                { kind: 'fact', key: 'revision', label: 'Revision', value: m[2], stage: 'deploy' },
+                { kind: 'fact', key: 'traffic', label: 'Traffic', value: `${percent}%`, stage: 'live' },
+                { kind: 'stage', stage: 'deploy', status: 'confirmed', note: `Revision ${m[2]} is ready.` },
+                percent > 0
+                    ? { kind: 'stage', stage: 'live', status: 'confirmed', note: `Serving ${percent} percent of traffic.` }
+                    : { kind: 'stage', stage: 'live', status: 'unverified', note: 'The revision is deployed but receives no traffic (deployed with --no-traffic).' },
+            ];
+        }
+        if ((m = /^For more troubleshooting guidance, see (https?:\/\/\S+)/.exec(text))) {
+            return [{ kind: 'fact', key: 'troubleshooting', label: 'Troubleshooting', value: m[1], href: m[1], stage: this.currentStage() }];
+        }
+        if ((m = /^Logs URL:\s*(https?:\/\/\S+)/.exec(text))) {
+            return [{ kind: 'fact', key: 'logsUrl', label: 'Logs', value: m[1], href: m[1], stage: this.currentStage() }];
+        }
+        if ((m = /^Service URL:\s*(https?:\/\/\S+)/.exec(text))) {
+            return [{ kind: 'fact', key: 'deploymentUrl', label: 'Service URL', value: m[1], href: m[1], stage: 'live' }];
+        }
+        if ((m = ERROR.exec(text))) {
+            const html = /<!DOCTYPE|<html/i.test(m[2]);
+            this.inHtmlError = html;
+            const message = html ? m[2].replace(/<!DOCTYPE[\s\S]*$|<html[\s\S]*$/i, '').replace(/:\s*$/, '').trim() : m[2];
+            return [{ kind: 'error', severity: 'fatal', stage: this.stageForError(message), message }];
+        }
+        if (this.inHtmlError) {
+            // Keep only the readable sentences of the error page, e.g. "The requested URL … was not found".
+            if (/<\/html>/i.test(text))
+                this.inHtmlError = false;
+            if (/<title>|<style|<meta/i.test(text))
+                return [];
+            const plain = text
+                .replace(/<[^>]*>/g, ' ')
+                .replace(/That[’']s (all we know|an error)\.?/gi, '')
+                .replace(/\s+/g, ' ')
+                .trim();
+            if (/[a-z]{3,} [a-z]{3,}/i.test(plain) && !/[{}]|^[\w-]+:/.test(plain)) {
+                return [{ kind: 'error', severity: 'cause', stage: this.currentStage(), message: plain, priority: 3 }];
+            }
+            return [];
+        }
+        if (/^(Deployment failed|Failed\.|Local build failed)/.test(text)) {
+            return [{ kind: 'evidence', stage: this.currentStage(), note: 'gcloud reported the deployment failed.' }];
+        }
+        // Revision start-up and build errors printed as plain lines.
+        if (this.phase !== 'start' && CAUSE.test(text) && !/^(Done|OK)\b/.test(text)) {
+            return [{ kind: 'error', severity: 'cause', stage: this.currentStage(), message: text, priority: /failed to start|listen on the port|PORT=/.test(text) ? 3 : 1 }];
+        }
+        return [];
+    }
+    rank(p) {
+        return ['start', 'prepare', 'build', 'deploy', 'live'].indexOf(p);
+    }
+    currentStage() {
+        return this.phase === 'start' ? 'prepare' : this.phase;
+    }
+    stageForError(message) {
+        if (/build/i.test(message) && !/revision/i.test(message))
+            return 'build';
+        if (/revision|container failed|failed to start|PORT|health ?check/i.test(message))
+            return 'deploy';
+        if (/permission|denied|not authenticated|auth|project|api .*(not|has not) been (used|enabled)|billing/i.test(message) && this.phase !== 'deploy')
+            return this.phase === 'build' ? 'build' : 'prepare';
+        return this.currentStage();
+    }
+}

package/dist/providers/gcloud/stages.js

@@ -0,0 +1,55 @@
+// General explanations of `gcloud run deploy`. Nothing here is evidence from a run.
+export const GCLOUD_STAGES = [
+    {
+        id: 'prepare',
+        title: 'Prepare',
+        summary: 'gcloud works out which project, region and service to deploy to.',
+        explanation: [
+            'gcloud uses the account you logged in with (`gcloud auth login`) and your configured project and region. Anything missing, such as the service name or region, it asks for in the terminal.',
+            'With `--source`, it also decides how to build: from your Dockerfile if there is one, otherwise with Google Cloud buildpacks.',
+        ],
+        confirmedBy: 'The "Deploying … to Cloud Run service [name] in project [id] region [region]" line, printed once the target is resolved.',
+        docsUrl: 'https://cloud.google.com/sdk/gcloud/reference/run/deploy',
+    },
+    {
+        id: 'build',
+        title: 'Build',
+        summary: 'Your source is uploaded and built into a container image by Cloud Build.',
+        explanation: [
+            'For source deploys, gcloud uploads your code and Cloud Build turns it into a container image, stored in Artifact Registry. The build runs on Google Cloud, not on your machine; the full log is in the Cloud Build link.',
+            'If you deploy a prebuilt image with `--image`, there is nothing to build and this stage is skipped.',
+        ],
+        confirmedBy: 'A "✓ Building Container..." step.',
+        docsUrl: 'https://cloud.google.com/run/docs/deploying-source-code',
+    },
+    {
+        id: 'deploy',
+        title: 'Deploy',
+        summary: 'Cloud Run creates a new revision from the image and starts it.',
+        explanation: [
+            'Each deploy creates an immutable revision. Cloud Run starts a container from the image and waits for it to listen on the port in the PORT environment variable (8080 by default). A container that crashes or listens on the wrong port fails here.',
+            'Once the revision is healthy, traffic is routed to it, and with `--allow-unauthenticated` the public access policy is set.',
+        ],
+        confirmedBy: 'A "✓ Creating Revision..." step, followed by "✓ Routing traffic...".',
+        docsUrl: 'https://cloud.google.com/run/docs/troubleshooting',
+    },
+    {
+        id: 'live',
+        title: 'Live',
+        summary: 'The new revision serves traffic at the service URL.',
+        explanation: [
+            'When the deploy finishes, the new revision receives its share of traffic (normally 100 percent) at the service URL. Older revisions stay available for rollback.',
+            'Whether anyone on the internet can open the URL depends on the service’s authentication setting.',
+        ],
+        confirmedBy: 'The "Service [name] revision [id] has been deployed and is serving … percent of traffic." message.',
+        docsUrl: 'https://cloud.google.com/run/docs/managing/revisions',
+    },
+];
+export const GCLOUD_NOTES = {
+    success: 'Deployed',
+    successHeadline: 'Service is live',
+    docsLabel: 'Cloud Run docs',
+    highlights: ['revision', 'troubleshooting'],
+    interrupted: 'You pressed Ctrl+C while this stage was in progress. That stops gcloud, but Cloud Build or Cloud Run may finish the operation anyway. Check the Cloud Console.',
+    unverified: "This run's output never confirmed this stage, so Unfold does not claim it happened.",
+};

package/dist/providers/index.js

@@ -0,0 +1,5 @@
+import { claude } from './agents/claude.js';
+import { codex } from './agents/codex.js';
+import { gcloud } from './gcloud/index.js';
+import { vercel } from './vercel/index.js';
+export const providers = { vercel, gcloud, claude, codex };

package/dist/providers/provider.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/vercel/index.js

@@ -0,0 +1,56 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { VercelParser } from './parser.js';
+import { VERCEL_NOTES, VERCEL_STAGES } from './stages.js';
+const SUBCOMMANDS = new Set(['deploy']);
+export const vercel = {
+    id: 'vercel',
+    title: 'Vercel preview deploy',
+    stages: VERCEL_STAGES,
+    notes: VERCEL_NOTES,
+    install: 'Install it with `npm i -g vercel`, then run `vercel login`.',
+    launch(userArgs) {
+        const args = [...userArgs];
+        if (!SUBCOMMANDS.has(args[0] ?? ''))
+            args.unshift('deploy');
+        // Ask the CLI to stream build logs so the Build stage has real evidence.
+        if (!args.includes('--logs') && !args.includes('--no-wait') && !args.includes('--json'))
+            args.push('--logs');
+        return { bin: process.env.UNFOLD_VERCEL_BIN || 'vercel', args };
+    },
+    preflight(cwd) {
+        const msgs = [];
+        if (!existsSync(join(cwd, '.vercel', 'project.json')) && !existsSync(join(cwd, '.vercel', 'repo.json'))) {
+            msgs.push('This folder is not linked to a Vercel project yet; the Vercel CLI will ask you to link it in this terminal.');
+        }
+        return msgs;
+    },
+    createParser: () => new VercelParser(),
+    fixHints(state) {
+        const fact = (k) => state.facts.find((f) => f.key === k)?.value;
+        switch (state.failedStage) {
+            case 'prepare':
+                return [
+                    'This failed before any files were sent to Vercel. Login, team scope and project-link problems are fixed with `vercel login` or `vercel link`, not code changes. If that is the cause, say so and stop.',
+                    'Check `.vercel/project.json` and `vercel.json` (or `vercel.ts`) for invalid configuration.',
+                ];
+            case 'upload':
+                return [
+                    'This failed while sending files to Vercel. Too many or too large files usually means something should be in `.vercelignore` (build output, caches, large assets).',
+                    '`vercel deploy --archive=tgz` uploads a single archive and avoids upload limits.',
+                ];
+            case 'build':
+                return [
+                    `The build ran on Vercel's machines, not locally. Reproduce it with \`${fact('buildCommand') ?? 'the build command'}\` (or \`vercel build\`) before and after the fix.`,
+                    'Vercel builds use the environment variables set on the Vercel project for the Preview environment, not local `.env` files. A missing or different variable is a common reason a build passes locally and fails on Vercel; `vercel env ls` lists them.',
+                    'Check the Node.js version (`engines.node` in package.json) and that the lockfile is committed and up to date.',
+                ];
+            case 'preview':
+                return [
+                    'The build finished but the deployment did not become Ready. This is often deployment checks, domain/alias assignment or project settings rather than application code.',
+                ];
+            default:
+                return [];
+        }
+    },
+};

package/dist/providers/vercel/parser.js

@@ -0,0 +1,239 @@
+const BUILD_LOG = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z)(?:\s+(.*))?$/;
+const INSPECT = /^(?:🔍\s*)?Inspect:?\s+(https?:\/\/\S+)/u;
+const DEPLOY_URL = /^(?:[✅🔗▲]\s*)?(Preview|Production):?\s+(https?:\/\/\S+)/u;
+const UPLOAD = /^Uploading\s+\[[^\]]*\]\s*\(([^)]+)\)/;
+const READY = /^(?:✓\s*)?Ready\b(?:\s+in\s+(\S+))?/u;
+const CLI_ERROR = /^(?:Error|❗️?\s*Error|Error!):?\s+(.+)$/u;
+const COMMAND_EXITED = /Command "([^"]+)" exited with (\d+)/;
+// Build output that is probably the real cause of a failure.
+const CAUSE = /(\berror\b|\bERR!|Failed to compile|Type error|SyntaxError|ReferenceError|TypeError|Module not found|Cannot find module|Build failed|ELIFECYCLE|exited with)/i;
+// Summary lines that say a build failed without saying why.
+const GENERIC_CAUSE = /^(Failed to compile|Build failed|.*worker exited with|.*ELIFECYCLE|npm ERR! (code|errno|Lifecycle|A complete log))/i;
+const NOT_CAUSE = /\b0 errors?\b|no errors|error[-_]boundary|errorHandler|\bwarn(ing)?\b/i;
+export class VercelParser {
+    phase = 'start';
+    sawUpload = false;
+    buildStarted = false;
+    feed(line) {
+        const raw = line.text.trim();
+        const m = BUILD_LOG.exec(raw);
+        if (m)
+            return this.buildLine((m[2] ?? '').trim(), true);
+        // Older CLIs prefix spinner build messages with "Building: ".
+        const text = raw.replace(/^Building:\s+/, '');
+        const out = [];
+        if (this.phase === 'start' || this.phase === 'prepare') {
+            const v = /^Vercel CLI (\S+)/.exec(text);
+            if (v) {
+                this.phase = 'prepare';
+                return [
+                    { kind: 'fact', key: 'cliVersion', label: 'Vercel CLI', value: v[1], stage: 'prepare' },
+                    { kind: 'stage', stage: 'prepare', status: 'active', note: 'The Vercel CLI started.' },
+                ];
+            }
+        }
+        // Interactive prompts (linking a project, confirmations).
+        if (/^\?\s+\S/.test(text)) {
+            return [{ kind: 'evidence', stage: 'prepare', note: 'The CLI asked a question in your terminal.' }];
+        }
+        const linked = /^(?:🔗\s*)?Linked to (\S+)/u.exec(text);
+        if (linked) {
+            return [
+                { kind: 'fact', key: 'project', label: 'Project', value: linked[1].replace(/\s*\(.*$/, ''), stage: 'prepare' },
+                { kind: 'evidence', stage: 'prepare', note: 'This folder was linked to a Vercel project.' },
+            ];
+        }
+        if (/^(Retrieving project|Loading scopes|Searching for existing projects)/.test(text) && (this.phase === 'start' || this.phase === 'prepare')) {
+            this.phase = 'prepare';
+            return [{ kind: 'stage', stage: 'prepare', status: 'active', note: 'Resolving the project.' }];
+        }
+        const deploying = /^(Deploying|Setting up project)\s*(.*?)\s*$/.exec(text);
+        if (deploying && (this.phase === 'start' || this.phase === 'prepare')) {
+            this.phase = 'prepare';
+            if (deploying[2])
+                out.push({ kind: 'fact', key: 'project', label: 'Project', value: deploying[2], stage: 'prepare' });
+            out.push({ kind: 'stage', stage: 'prepare', status: 'confirmed', note: 'Login checked and project resolved; the deployment request is starting.' });
+            return out;
+        }
+        const up = UPLOAD.exec(text);
+        if (up) {
+            this.sawUpload = true;
+            this.phase = 'upload';
+            const [done, total] = up[1].split('/');
+            const complete = done && total && done.trim() === total.trim();
+            return [{ kind: 'stage', stage: 'upload', status: 'active', note: complete ? `Uploaded ${total.trim()} of new or changed files.` : `Uploading new or changed files: ${up[1]}.` }];
+        }
+        const inspect = INSPECT.exec(text);
+        if (inspect) {
+            this.phase = 'created';
+            out.push({ kind: 'fact', key: 'inspectUrl', label: 'Inspect', value: inspect[1], href: inspect[1], stage: 'upload' });
+            out.push({ kind: 'stage', stage: 'prepare', status: 'confirmed', note: 'Project resolved and files prepared.' });
+            if (this.sawUpload) {
+                out.push({ kind: 'stage', stage: 'upload', status: 'confirmed', note: 'Files uploaded and the deployment was created.' });
+            }
+            else {
+                out.push({
+                    kind: 'evidence',
+                    stage: 'upload',
+                    note: 'The deployment was created, but no upload appeared in the output. Vercel may already have had every file, so the upload itself is not confirmed.',
+                });
+            }
+            return out;
+        }
+        const dep = DEPLOY_URL.exec(text);
+        if (dep) {
+            const label = dep[1] === 'Production' ? 'Production URL' : 'Preview URL';
+            out.push({ kind: 'fact', key: 'deploymentUrl', label, value: dep[2], href: dep[2], stage: 'preview' });
+            if (dep[1] === 'Production')
+                out.push({ kind: 'fact', key: 'target', label: 'Target', value: 'production', stage: 'preview' });
+            if (this.phase === 'built' || this.phase === 'ready' || (this.buildStarted && /\[\d+(\.\d+)?m?s\]$/.test(text))) {
+                out.push({ kind: 'stage', stage: 'preview', status: 'confirmed', note: 'The deployment is live at its URL.' });
+            }
+            else {
+                out.push({ kind: 'evidence', stage: 'preview', note: 'URL reserved. It will not serve your site until the deployment is Ready.' });
+            }
+            return out;
+        }
+        const aliased = /^(?:▲\s*)?Aliased\s+(https?:\/\/\S+)/u.exec(text);
+        if (aliased) {
+            return [
+                { kind: 'fact', key: 'alias', label: 'Aliased', value: aliased[1], href: aliased[1], stage: 'preview' },
+                { kind: 'evidence', stage: 'preview', note: 'A domain was pointed at this deployment.' },
+            ];
+        }
+        if (/^Queued/.test(text)) {
+            this.phase = 'build';
+            return [{ kind: 'stage', stage: 'build', status: 'active', note: 'Waiting in the queue for a build machine.' }];
+        }
+        if (/^Building…?\.{0,3}$/.test(text)) {
+            this.phase = 'build';
+            this.buildStarted = true;
+            return [{ kind: 'stage', stage: 'build', status: 'active', note: 'Building on Vercel.' }];
+        }
+        if (/^(Running Checks|Completing)/.test(text)) {
+            this.phase = 'built';
+            return [
+                { kind: 'stage', stage: 'build', status: 'confirmed', note: 'Vercel reported the build finished.' },
+                { kind: 'stage', stage: 'preview', status: 'active', note: /^Running Checks/.test(text) ? 'Waiting for deployment checks.' : 'Finishing the deployment.' },
+            ];
+        }
+        const ready = READY.exec(text);
+        if (ready && this.phase !== 'start' && this.phase !== 'prepare') {
+            this.phase = 'ready';
+            if (ready[1])
+                out.push({ kind: 'fact', key: 'duration', label: 'Total time', value: ready[1], stage: 'preview' });
+            out.push({ kind: 'stage', stage: 'build', status: 'confirmed', note: 'The build finished.' });
+            out.push({ kind: 'stage', stage: 'preview', status: 'confirmed', note: 'Vercel reports the deployment is Ready.' });
+            return out;
+        }
+        if (/Deployment Protection is on/.test(text)) {
+            return [
+                { kind: 'fact', key: 'protection', label: 'Deployment Protection', value: 'On', stage: 'preview' },
+                { kind: 'evidence', stage: 'preview', note: 'Visitors may need to sign in to Vercel to view this URL.' },
+            ];
+        }
+        const err = CLI_ERROR.exec(text);
+        if (err) {
+            const stage = this.stageForError();
+            const exited = COMMAND_EXITED.exec(text);
+            if (exited)
+                out.push({ kind: 'fact', key: 'failedCommand', label: 'Failed command', value: `${exited[1]} (exit ${exited[2]})`, stage: 'build' });
+            out.push({ kind: 'error', severity: 'fatal', stage, message: err[1] });
+            return out;
+        }
+        // Non-interactive mode reports errors as a JSON object on one line.
+        if (text.startsWith('{') && /"status"\s*:\s*"error"/.test(text)) {
+            let message = text;
+            try {
+                const j = JSON.parse(text);
+                message = [j.message ?? j.reason, j.hint].filter(Boolean).join(' ') || text;
+            }
+            catch {
+                // keep raw text
+            }
+            return [{ kind: 'error', severity: 'fatal', stage: this.stageForError(), message }];
+        }
+        if (/^Uploading failed|too_many_files|missing_files/.test(text)) {
+            return [{ kind: 'error', severity: 'fatal', stage: 'upload', message: text }];
+        }
+        // After the deployment exists, unprefixed spinner lines are the latest build log line.
+        if (this.phase === 'created' || this.phase === 'build')
+            return this.buildLine(text, false);
+        return out;
+    }
+    stageForError() {
+        switch (this.phase) {
+            case 'start':
+            case 'prepare':
+                return 'prepare';
+            case 'upload':
+                return 'upload';
+            case 'created':
+            case 'build':
+                return 'build';
+            default:
+                return 'preview';
+        }
+    }
+    buildLine(text, timestamped) {
+        if (text === '')
+            return [];
+        const out = [];
+        if (this.phase !== 'built' && this.phase !== 'ready') {
+            if (!this.buildStarted)
+                out.push({ kind: 'stage', stage: 'build', status: 'active', note: timestamped ? 'Build logs are streaming from Vercel.' : 'Building on Vercel.' });
+            this.buildStarted = true;
+            this.phase = 'build';
+        }
+        let r;
+        if ((r = /Running build in (.+)$/.exec(text))) {
+            out.push({ kind: 'fact', key: 'region', label: 'Build region', value: r[1], stage: 'build' });
+            out.push({ kind: 'evidence', stage: 'build', note: 'A build machine picked up the deployment.' });
+        }
+        else if ((r = /Build machine configuration: (.+)$/.exec(text))) {
+            out.push({ kind: 'fact', key: 'machine', label: 'Build machine', value: r[1], stage: 'build' });
+        }
+        else if (/(Downloading \d+ deployment files|Retrieving list of deployment files|Cloning )/.test(text)) {
+            out.push({ kind: 'evidence', stage: 'build', note: 'The build machine fetched your files.' });
+        }
+        else if (/Restored build cache|Build cache/.test(text) && !/Creat|Upload/.test(text)) {
+            out.push({ kind: 'evidence', stage: 'build', note: 'A previous build cache was restored.' });
+        }
+        else if ((r = /^Running "(?!vercel build)(.+)"$/.exec(text))) {
+            out.push({ kind: 'fact', key: 'buildCommand', label: 'Build command', value: r[1], stage: 'build' });
+            out.push({ kind: 'evidence', stage: 'build', note: 'Your build command started.' });
+        }
+        else if (/(Installing dependencies|added \d+ packages|up to date, audited|Lockfile|packages are looking for funding)/.test(text) && /Installing|added/.test(text)) {
+            out.push({ kind: 'evidence', stage: 'build', note: 'Dependencies were installed.' });
+        }
+        else if ((r = /Detected (.+?) version:? (\S+)/.exec(text))) {
+            out.push({ kind: 'fact', key: 'framework', label: 'Framework', value: `${r[1]} ${r[2]}`, stage: 'build' });
+        }
+        else if ((r = /Build Completed in (\S+)(?:\s*\[(.+)\])?/.exec(text))) {
+            this.phase = 'built';
+            out.push({ kind: 'stage', stage: 'build', status: 'confirmed', note: r[2] ? `Build completed in ${r[2]}.` : 'Build completed.' });
+        }
+        else if (/Deploying outputs/.test(text)) {
+            if (this.phase !== 'ready')
+                this.phase = 'built';
+            out.push({ kind: 'stage', stage: 'preview', status: 'active', note: 'Build output is being deployed to Vercel’s network.' });
+        }
+        else if (/^Deployment completed/.test(text)) {
+            out.push({ kind: 'evidence', stage: 'preview', note: 'Build output was deployed.' });
+        }
+        const exited = COMMAND_EXITED.exec(text);
+        if (exited) {
+            out.push({ kind: 'fact', key: 'failedCommand', label: 'Failed command', value: `${exited[1]} (exit ${exited[2]})`, stage: 'build' });
+            out.push({ kind: 'error', severity: 'cause', stage: 'build', message: text.replace(/^Error:\s*/, ''), priority: 0 });
+        }
+        else if (CAUSE.test(text) && !NOT_CAUSE.test(text)) {
+            out.push({ kind: 'error', severity: 'cause', stage: 'build', message: text.replace(/^Error:\s*/, ''), priority: GENERIC_CAUSE.test(text) ? 1 : 2 });
+        }
+        return out;
+    }
+}
+/** Test helper: run lines through a fresh parser. */
+export function parseLines(lines) {
+    const p = new VercelParser();
+    return lines.map((text, i) => p.feed({ seq: i + 1, at: i, text }));
+}

package/dist/providers/vercel/stages.js

@@ -0,0 +1,54 @@
+// General explanations. Nothing here is evidence from a run.
+export const VERCEL_STAGES = [
+    {
+        id: 'prepare',
+        title: 'Prepare',
+        summary: 'The CLI works out who you are, which project this folder belongs to, and which files to send.',
+        explanation: [
+            'The Vercel CLI uses the login saved on your machine and the link in .vercel/project.json. If the folder is not linked yet, it asks you a few questions in the terminal and creates that link.',
+            'It then lists the files to deploy (skipping anything in .vercelignore) and computes a fingerprint (SHA) of each one. Those fingerprints let Vercel skip files it already has.',
+        ],
+        confirmedBy: 'A "Deploying <team>/<project>" line, which the CLI prints only after your login has been checked and the project resolved.',
+        docsUrl: 'https://vercel.com/docs/cli/deploy',
+    },
+    {
+        id: 'upload',
+        title: 'Upload',
+        summary: 'Files Vercel does not already have are sent to Vercel, then a deployment is created.',
+        explanation: [
+            'Only files whose fingerprint Vercel has not seen before are uploaded, so a small change usually means a small upload. If nothing changed, there may be no visible upload at all.',
+            'Once Vercel has every file, the CLI creates the deployment and gets back an Inspect URL (the deployment page in the dashboard) and the URL the preview will live at.',
+        ],
+        confirmedBy: 'An "Uploading [...]" progress line followed by the Inspect URL, which only appears once the deployment has been created.',
+        docsUrl: 'https://vercel.com/docs/deployments/overview',
+    },
+    {
+        id: 'build',
+        title: 'Build',
+        summary: 'Vercel builds your project on its own machines, not on your laptop.',
+        explanation: [
+            'The deployment waits in a queue for a build machine. That machine downloads your files, restores the build cache if there is one, installs dependencies and runs your build command (for example npm run build).',
+            'The build uses the environment variables configured in the Vercel project for the Preview environment, not the .env files on your machine. This is a common reason a build passes locally but fails here.',
+        ],
+        confirmedBy: '"Build Completed" in the build logs, or the CLI reporting the deployment Ready.',
+        docsUrl: 'https://vercel.com/docs/deployments/builds',
+    },
+    {
+        id: 'preview',
+        title: 'Preview',
+        summary: 'The build output is put behind its own unique URL that you can open and share.',
+        explanation: [
+            'Each preview deployment gets an immutable URL. The CLI prints that URL early, but it only serves your site once the deployment is Ready.',
+            'Preview deployments never change your production domain. Many teams keep Deployment Protection on, so visitors may need to sign in to Vercel to see it.',
+        ],
+        confirmedBy: 'The CLI printing "Ready", meaning Vercel reports the deployment as live at its URL.',
+        docsUrl: 'https://vercel.com/docs/deployments/environments#preview-environment-pre-production',
+    },
+];
+export const VERCEL_NOTES = {
+    success: 'Deployed',
+    successHeadline: 'Preview is ready',
+    docsLabel: 'Vercel docs',
+    interrupted: 'You pressed Ctrl+C while this stage was in progress. That stops the CLI, but if the deployment had already been created, Vercel may keep building it. Check the Inspect URL.',
+    unverified: "This run's output never confirmed this stage, so Unfold does not claim it happened.",
+};

package/dist/tui/ansi.js

@@ -0,0 +1,71 @@
+// Minimal ANSI styling and text layout for the terminal views.
+const useColor = () => !process.env.NO_COLOR && (process.env.FORCE_COLOR === '1' || !!process.stdout.isTTY);
+const wrap = (open, close) => (s) => `\x1b[${open}m${s}\x1b[${close}m`;
+const plain = (s) => s;
+export function style(color = useColor()) {
+    return color
+        ? { bold: wrap(1, 22), dim: wrap(2, 22), red: wrap(31, 39), green: wrap(32, 39), yellow: wrap(33, 39), cyan: wrap(36, 39), inverse: wrap(7, 27) }
+        : { bold: plain, dim: plain, red: plain, green: plain, yellow: plain, cyan: plain, inverse: plain };
+}
+const ANSI = /\x1b\[[0-9;?]*[A-Za-z]|\x1b\][^\x07]*\x07/g;
+export const stripAnsi = (s) => s.replace(ANSI, '');
+/** Visible width in terminal columns (good enough for the text Unfold prints). */
+export function width(s) {
+    let w = 0;
+    for (const ch of stripAnsi(s)) {
+        const cp = ch.codePointAt(0);
+        if (cp < 0x20 || (cp >= 0x300 && cp <= 0x36f) || cp === 0x200b)
+            continue;
+        // Emoji and CJK take two columns.
+        w += cp >= 0x1f300 || (cp >= 0x1100 && cp <= 0x115f) || (cp >= 0x2e80 && cp <= 0xa4cf) || (cp >= 0xac00 && cp <= 0xd7a3) || (cp >= 0xff00 && cp <= 0xff60) ? 2 : 1;
+    }
+    return w;
+}
+/** Cuts a (possibly styled) string to `max` visible columns, adding an ellipsis. */
+export function truncate(s, max) {
+    if (max <= 0)
+        return '';
+    if (width(s) <= max)
+        return s;
+    let out = '';
+    let w = 0;
+    let i = 0;
+    while (i < s.length) {
+        ANSI.lastIndex = i;
+        const m = s.startsWith('\x1b', i) ? ANSI.exec(s) : null;
+        if (m && m.index === i) {
+            out += m[0];
+            i += m[0].length;
+            continue;
+        }
+        const ch = String.fromCodePoint(s.codePointAt(i));
+        const cw = width(ch);
+        if (w + cw > max - 1)
+            break;
+        out += ch;
+        w += cw;
+        i += ch.length;
+    }
+    return out + '…' + (/\x1b\[/.test(out) ? '\x1b[0m' : '');
+}
+export const padEnd = (s, n) => s + ' '.repeat(Math.max(0, n - width(s)));
+/** Word-wraps plain text to `max` columns. */
+export function wrapText(text, max) {
+    const lines = [];
+    for (const para of text.split('\n')) {
+        let line = '';
+        for (const word of para.split(/\s+/).filter(Boolean)) {
+            if (line && width(line) + 1 + width(word) > max) {
+                lines.push(line);
+                line = '';
+            }
+            line = line ? `${line} ${word}` : word;
+            while (width(line) > max) {
+                lines.push(line.slice(0, max));
+                line = line.slice(max);
+            }
+        }
+        lines.push(line);
+    }
+    return lines;
+}