@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.118

package/dist/core/turn_classifier.js

@@ -0,0 +1,213 @@
+/**
+ * turn_classifier.ts -- Gemini mini-prompt that decides tier for
+ * a turn the reasoning_gate flagged as ambiguous (alpha.55).
+ *
+ * Why eco-model for the classifier itself: the question
+ * "simple verb invocation or complex reasoning?" is a routing
+ * decision, not a content decision. Gemini Flash Lite handles it
+ * in ~400 ms for fractions of a cent. The verdict gates whether
+ * the EXPENSIVE turn (full LLM call) goes to eco or frontier.
+ *
+ * Fallback path when Gemini is not reachable or the key is
+ * missing: the gate's own (low-confidence) tier suggestion is
+ * returned with a "classifier_unreachable" signal so the cost log
+ * shows what happened. The chat NEVER blocks on classifier
+ * availability.
+ *
+ * Cache: LRU keyed by sha256 of the user text + previous tier.
+ * 50 entries / 5 min TTL. Saves the classifier call on repeated
+ * short prompts ("hola", "ok", "si").
+ *
+ * ASCII-only.
+ */
+import { createHash } from 'node:crypto';
+const SYSTEM_PROMPT = ('You are a routing classifier inside a developer tool. Given a ' +
+    'user message, decide which class it belongs to:\n' +
+    '  - "simple": a short request invoking one tool or asking a ' +
+    'trivial question. Examples: "abrime una tab", "show me the ' +
+    'budget", "list pipelines", "hola", "leeme la tabla".\n' +
+    '  - "complex": requires reasoning, design, code generation, or ' +
+    'a multi-step plan. Examples: "design the architecture for X", ' +
+    '"implement a new feature", "refactor this module", "write a ' +
+    'function that does Y".\n' +
+    '  - "destructive": modifies persistent state (delete files, drop ' +
+    'tables, commit + push, send emails, deploy). Examples: "borra ' +
+    'esos archivos", "git push --force", "send the email now".\n\n' +
+    'Reply with exactly one word: simple, complex, or destructive. ' +
+    'No punctuation, no extra text.');
+const CACHE_MAX = 50;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+const _cache = new Map();
+function cacheKey(text, prev) {
+    const h = createHash('sha256');
+    h.update(prev || '');
+    h.update('|');
+    h.update(text);
+    return h.digest('hex');
+}
+function cacheGet(key) {
+    const e = _cache.get(key);
+    if (!e)
+        return null;
+    if (Date.now() - e.ts > CACHE_TTL_MS) {
+        _cache.delete(key);
+        return null;
+    }
+    /* Move to end -> LRU touch. */
+    _cache.delete(key);
+    _cache.set(key, e);
+    return { ...e.result, cached: true };
+}
+function cacheSet(key, result) {
+    if (_cache.size >= CACHE_MAX) {
+        /* Drop oldest (first inserted) -- Map iteration order is
+         *  insertion order. */
+        const first = _cache.keys().next().value;
+        if (first !== undefined)
+            _cache.delete(first);
+    }
+    _cache.set(key, { ts: Date.now(), result: { ...result, cached: false } });
+}
+/** Test hook -- clear cache between specs. */
+export function _resetClassifierCache() {
+    _cache.clear();
+}
+/* ----- classifier core ------------------------------------- */
+function parseVerdict(text) {
+    const t = (text || '').trim().toLowerCase();
+    /* Gemini sometimes wraps the word in markdown or punctuation. */
+    const stripped = t.replace(/[^a-z]/g, '');
+    if (stripped === 'simple')
+        return 'simple';
+    if (stripped === 'complex')
+        return 'complex';
+    if (stripped === 'destructive')
+        return 'destructive';
+    /* Substring fallback for noisy output. */
+    if (stripped.includes('simple'))
+        return 'simple';
+    if (stripped.includes('complex'))
+        return 'complex';
+    if (stripped.includes('destructive'))
+        return 'destructive';
+    return null;
+}
+function verdictToTier(v, gate_tier) {
+    if (v === 'simple')
+        return 'eco';
+    if (v === 'complex')
+        return 'frontier';
+    /* destructive routes to frontier so the user gets the best
+     *  judgment before persistent changes. */
+    if (v === 'destructive')
+        return 'frontier';
+    /* null -> gate fallback. */
+    return gate_tier;
+}
+async function callGemini(text, apiKey, model, fetchImpl, timeoutMs) {
+    const url = 'https://generativelanguage.googleapis.com/v1beta/models/' +
+        encodeURIComponent(model) +
+        ':generateContent?key=' + encodeURIComponent(apiKey);
+    const body = {
+        systemInstruction: { parts: [{ text: SYSTEM_PROMPT }] },
+        contents: [{
+                role: 'user',
+                parts: [{ text: text.slice(0, 2000) }],
+            }],
+        generationConfig: {
+            maxOutputTokens: 8,
+            temperature: 0.0,
+        },
+    };
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const r = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+        if (!r.ok) {
+            throw new Error('gemini http ' + r.status);
+        }
+        const j = await r.json();
+        const candidate = j.candidates && j.candidates[0];
+        const part = candidate?.content?.parts && candidate.content.parts[0];
+        return (part && typeof part.text === 'string') ? part.text : '';
+    }
+    finally {
+        clearTimeout(t);
+    }
+}
+/**
+ * Run the classifier. Never throws -- on any failure, returns
+ * the gate's fallback tier with a "classifier_unreachable"
+ * signal and confidence 0.50.
+ */
+export async function classifyTurn(input) {
+    const text = typeof input.text === 'string' ? input.text : '';
+    const key = cacheKey(text, input.previous_tier);
+    const cached = cacheGet(key);
+    if (cached)
+        return cached;
+    const signals = [];
+    const apiKey = input.api_key ?? null;
+    if (!apiKey) {
+        signals.push('classifier_no_api_key');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const model = input.model ?? 'gemini-2.5-flash-lite';
+    const timeoutMs = input.timeoutMs ?? 2500;
+    let raw = '';
+    try {
+        raw = await callGemini(text, apiKey, model, fetchImpl, timeoutMs);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        signals.push('classifier_unreachable[' + msg.slice(0, 60) + ']');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    const verdict = parseVerdict(raw);
+    if (!verdict) {
+        signals.push('classifier_unparseable[' + raw.slice(0, 30) + ']');
+        const r = {
+            tier: input.gate_tier,
+            confidence: 0.50,
+            verdict: null,
+            signals,
+            cached: false,
+        };
+        cacheSet(key, r);
+        return r;
+    }
+    signals.push('classifier_verdict[' + verdict + ']');
+    const tier = verdictToTier(verdict, input.gate_tier);
+    const r = {
+        tier,
+        confidence: verdict === 'destructive' ? 0.95 : 0.88,
+        verdict,
+        signals,
+        cached: false,
+    };
+    cacheSet(key, r);
+    return r;
+}
+//# sourceMappingURL=turn_classifier.js.map

package/dist/core/turn_classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turn_classifier.js","sourceRoot":"","sources":["../../src/core/turn_classifier.ts"],"names":[],"mappings":"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"}

package/dist/core/whats_new.d.ts

@@ -0,0 +1,42 @@
+export interface WhatsNewEntry {
+    version: string;
+    date: string;
+    summary: string;
+    bullets: string[];
+}
+export declare const CATALOG: WhatsNewEntry[];
+export interface WhatsNewResult {
+    current_version: string;
+    last_seen_version: string | null;
+    entries: WhatsNewEntry[];
+}
+declare function lastSeenPath(): string;
+export declare function readLastSeen(): Promise<string | null>;
+export declare function writeLastSeen(version: string): Promise<void>;
+/**
+ * Parse a semver-ish version into a comparable tuple.
+ * "0.2.0-alpha.59k" -> [0, 2, 0, "alpha", 59, "k"]
+ * Releases without prerelease ("1.0.0") sort AFTER any prerelease
+ * of the same base.
+ */
+export declare function parseVersion(v: string): {
+    base: [number, number, number];
+    preLabel: string | null;
+    preNum: number;
+    preTail: string;
+};
+/** Returns negative when a < b, positive when a > b, 0 when equal. */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Returns the cumulative list of WhatsNewEntry that the user has
+ * not seen yet. Entries strictly greater than last_seen and
+ * <= current_version. When last_seen is null, returns the latest
+ * entry only (avoid wall-of-text on a fresh install).
+ */
+export declare function computeWhatsNew(currentVersion: string): Promise<WhatsNewResult>;
+/** Test seam. */
+export declare const _internal: {
+    lastSeenPath: typeof lastSeenPath;
+};
+export {};
+//# sourceMappingURL=whats_new.d.ts.map

package/dist/core/whats_new.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"whats_new.d.ts","sourceRoot":"","sources":["../../src/core/whats_new.ts"],"names":[],"mappings":"AA0BA,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAK,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,eAAO,MAAM,OAAO,EAAE,aAAa,EAqFlC,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,OAAO,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,iBAAS,YAAY,IAAI,MAAM,CAI9B;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQ3D;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMlE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG;IACvC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAI,MAAM,CAAC;IACjB,OAAO,EAAG,MAAM,CAAC;CAClB,CAaA;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAoB5D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,cAAc,CAAC,CAqBzB;AAED,iBAAiB;AACjB,eAAO,MAAM,SAAS;;CAAmB,CAAC"}

package/dist/core/whats_new.js

@@ -0,0 +1,214 @@
+/**
+ * "What's new" notification (alpha.59l).
+ *
+ * Tracks the version Pablo (or any user) last opened the panel with.
+ * On boot, the server compares with the currently installed version
+ * and returns the cumulative bullet list of changes between the two,
+ * so the panel can show a one-shot dismissable banner.
+ *
+ * Storage:
+ *   ~/.yujin-forge/last_seen_version  -- plain text file with the
+ *                                        version string. Atomic
+ *                                        tmp+rename write. Missing
+ *                                        file = "never seen" -> show
+ *                                        everything from CATALOG.
+ *
+ * Catalog lives inline (`CATALOG` below). Adding a new entry is a
+ * one-line edit per alpha. Versions are compared by tuple of
+ * [major, minor, patch, pre_label, pre_num] so 0.2.0-alpha.59k <
+ * 0.2.0-alpha.59l < 0.2.0-alpha.60 < 0.2.0.
+ *
+ * ASCII-only.
+ */
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+/* The catalog is ordered newest-first. Sumi adds an entry at the
+ *  top with every shipped alpha that has a user-visible change. */
+export const CATALOG = [
+    {
+        version: '0.2.0-alpha.59l',
+        date: '2026-06-01',
+        summary: 'First-run "what changed" banner',
+        bullets: [
+            'New: this banner. Shown once per version upgrade.',
+            'Dismiss to mark seen. Re-shown only on the next yf upgrade.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59k',
+        date: '2026-06-01',
+        summary: 'Server-side cost meter (billing-grade caps)',
+        bullets: [
+            'Authoritative monthly token counter lives in Cloudflare KV.',
+            'Worker enforces plan cap (free-public 200k eco, paid 2M, etc) before upstream call.',
+            '429 monthly_cap_reached when usage projection >= cap.',
+            'New endpoint GET /v1/cost-meter/<handle> exposes the row + caps for the budget UI.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59j',
+        date: '2026-06-01',
+        summary: 'ANSI rendering + reader bookmarks + audit detail',
+        bullets: [
+            'Shell pizarron tabs strip ANSI escapes + collapse \\r progress bars.',
+            'Settings -> Reader bookmarks lists every persisted bookmark; click jumps the reader.',
+            'Audit log row click opens a detail modal with full JSON + copy button.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59i',
+        date: '2026-06-01',
+        summary: 'Approval mid-stream + shell kill button',
+        bullets: [
+            'Approval modal now appears mid-turn via SSE, not after the call.',
+            'Shell pizarron tabs gain a stop button to kill the running process (SIGTERM -> SIGKILL).',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59h',
+        date: '2026-06-01',
+        summary: 'xAI + Mistral + Cohere runtime clients',
+        bullets: [
+            'Brain provider catalog now covers 8/8 runtimes wired.',
+            'BYOK keys for xAI / Mistral / Cohere can be set via yf keys set.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59g',
+        date: '2026-05-31',
+        summary: 'Audit log viewer + DeepSeek client',
+        bullets: [
+            'Settings -> Audit log shows the last 200 entries with kind + approval-mode filters.',
+            'DeepSeek wired as a runtime brain provider.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59f',
+        date: '2026-05-31',
+        summary: 'Shell live stream via SSE',
+        bullets: [
+            'Shell.exec output streams progressively into the pizarron tab as it runs.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59e',
+        date: '2026-05-31',
+        summary: 'SSE streaming + autonomous multi-step',
+        bullets: [
+            'Chat turns now stream tool rounds via Server-Sent Events.',
+            'Autonomous mode lifts the tool-rounds cap to 50 with loop detection.',
+        ],
+    },
+    {
+        version: '0.2.0-alpha.59d',
+        date: '2026-05-31',
+        summary: 'shell.exec verb + Danger Zone',
+        bullets: [
+            'yujin.shell.exec runs commands with safe / destructive / elevation / network classification.',
+            'Danger Zone toggle auto-approves everything for velocity (audit-logged as bypass).',
+            'Audit log persists every gated action to ~/.yujin-forge/cache/audit_log.jsonl.',
+        ],
+    },
+];
+function lastSeenPath() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    const base = process.env.YF_CONFIG_DIR || path.join(home, '.yujin-forge');
+    return path.join(base, 'last_seen_version');
+}
+export async function readLastSeen() {
+    try {
+        const raw = await fs.readFile(lastSeenPath(), 'utf-8');
+        const trimmed = raw.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeLastSeen(version) {
+    const p = lastSeenPath();
+    await fs.mkdir(path.dirname(p), { recursive: true });
+    const tmp = p + '.tmp';
+    await fs.writeFile(tmp, version, 'utf-8');
+    await fs.rename(tmp, p);
+}
+/**
+ * Parse a semver-ish version into a comparable tuple.
+ * "0.2.0-alpha.59k" -> [0, 2, 0, "alpha", 59, "k"]
+ * Releases without prerelease ("1.0.0") sort AFTER any prerelease
+ * of the same base.
+ */
+export function parseVersion(v) {
+    const m = /^(\d+)\.(\d+)\.(\d+)(?:-([a-zA-Z]+)\.(\d+)([a-zA-Z]*))?$/.exec(v);
+    if (!m) {
+        return { base: [0, 0, 0], preLabel: null, preNum: 0, preTail: '' };
+    }
+    const base = [Number(m[1]), Number(m[2]), Number(m[3])];
+    if (!m[4])
+        return { base, preLabel: null, preNum: 0, preTail: '' };
+    return {
+        base,
+        preLabel: m[4],
+        preNum: Number(m[5]),
+        preTail: m[6] || '',
+    };
+}
+/** Returns negative when a < b, positive when a > b, 0 when equal. */
+export function compareVersions(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    for (let i = 0; i < 3; i++) {
+        const ai = pa.base[i] ?? 0;
+        const bi = pb.base[i] ?? 0;
+        if (ai !== bi)
+            return ai - bi;
+    }
+    /* Release (no preLabel) > any prerelease of same base. */
+    if (pa.preLabel === null && pb.preLabel !== null)
+        return 1;
+    if (pa.preLabel !== null && pb.preLabel === null)
+        return -1;
+    if (pa.preLabel === null && pb.preLabel === null)
+        return 0;
+    /* Both have preLabel. Compare label alphabetically. */
+    const la = pa.preLabel ?? '';
+    const lb = pb.preLabel ?? '';
+    if (la !== lb)
+        return la < lb ? -1 : 1;
+    if (pa.preNum !== pb.preNum)
+        return pa.preNum - pb.preNum;
+    /* Both have same preLabel + preNum. Compare tail alphabetically. */
+    if (pa.preTail !== pb.preTail)
+        return pa.preTail < pb.preTail ? -1 : 1;
+    return 0;
+}
+/**
+ * Returns the cumulative list of WhatsNewEntry that the user has
+ * not seen yet. Entries strictly greater than last_seen and
+ * <= current_version. When last_seen is null, returns the latest
+ * entry only (avoid wall-of-text on a fresh install).
+ */
+export async function computeWhatsNew(currentVersion) {
+    const lastSeen = await readLastSeen();
+    if (!lastSeen) {
+        /* Fresh install -- show only the latest entry (avoid scaring
+         *  a first-time user with the full 9-entry backlog). */
+        const newest = CATALOG[0];
+        return {
+            current_version: currentVersion,
+            last_seen_version: null,
+            entries: newest ? [newest] : [],
+        };
+    }
+    if (compareVersions(lastSeen, currentVersion) >= 0) {
+        /* Already at or past current. Nothing to show. */
+        return { current_version: currentVersion, last_seen_version: lastSeen, entries: [] };
+    }
+    const entries = CATALOG.filter((e) => compareVersions(e.version, lastSeen) > 0 &&
+        compareVersions(e.version, currentVersion) <= 0);
+    return { current_version: currentVersion, last_seen_version: lastSeen, entries };
+}
+/** Test seam. */
+export const _internal = { lastSeenPath };
+//# sourceMappingURL=whats_new.js.map

package/dist/core/whats_new.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"whats_new.js","sourceRoot":"","sources":["../../src/core/whats_new.ts"],"names":[],"mappings":"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"}

package/dist/deploy/adapter.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Deploy adapter abstraction.
+ *
+ * Forge supports multiple cloud targets. Each one is encapsulated
+ * as a DeployAdapter implementation. The tier-aware selector
+ * picks the right adapter for a project based on:
+ *
+ *   - workflow.tier        (Simple / Medium / Full)
+ *   - workflow.clarification.nfr_quantitative.volume
+ *   - workflow.clarification.nfr_quantitative.parallelism
+ *   - workflow.clarification.nfr_structural.persistence
+ *   - workflow.clarification.nfr_structural.workers
+ *
+ * Rules of thumb (codified in pickDeployAdapter):
+ *   - Simple tier + no queue + no workers   -> Cloudflare Pages/Workers
+ *   - Medium tier OR has queue OR has workers -> Cloudflare Pages + R2 + Queues
+ *   - Full tier OR persistent stateful workers OR custom infra -> AWS ECS Fargate
+ *
+ * The user can override via `yf operate deploy-guided --adapter <id>`.
+ *
+ * Adapter contract:
+ *   - id: short slug ("cloudflare" | "aws" | "vercel" | ...).
+ *   - description: one-liner for the picker UX.
+ *   - tierFit(): which tiers this adapter is appropriate for.
+ *   - readyToRun(): credentials check (e.g. wrangler logged in).
+ *   - plan(input): dry-run -> { resources, estimated_cost_usd }.
+ *   - apply(input): real deploy -> { url, logs, deployed_at }.
+ *
+ * For alpha.19 only `cloudflare` is wired end-to-end. `aws` keeps
+ * the existing imperative path; the adapter is a thin shell over
+ * it. `vercel` is a stub for future.
+ *
+ * ASCII-only.
+ */
+import type { WorkflowState } from '../workflow/state.js';
+export type DeployAdapterId = 'cloudflare' | 'aws' | 'vercel';
+export type Tier = 'simple' | 'medium' | 'full';
+export interface DeployPlan {
+    resources: string[];
+    estimated_cost_usd: number;
+    estimated_minutes: number;
+    notes: string[];
+}
+export interface DeployResult {
+    url: string;
+    deployed_at: string;
+    build_seconds: number;
+    logs_tail: string[];
+}
+export interface DeployInput {
+    /** Absolute path to the build output (dist/ or .next/ or similar). */
+    buildDir: string;
+    /** Project slug (Cloudflare project name / AWS service name). */
+    projectSlug: string;
+    /** Optional env vars to expose. */
+    env?: Record<string, string>;
+    /** Tenant / user handle for multi-tenant adapters. */
+    userHandle?: string;
+}
+export interface DeployAdapter {
+    id: DeployAdapterId;
+    description: string;
+    tierFit(): Tier[];
+    /** Cheap check -- does the local env have what this adapter
+     *  needs (credentials, CLI tools)? Returns ok + reason. */
+    readyToRun(): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /** Dry-run plan: lists resources + cost estimate. No network
+     *  writes beyond auth pings. */
+    plan(input: DeployInput): Promise<DeployPlan>;
+    /** Real deploy. Should be idempotent: re-running with the same
+     *  input updates an existing deployment rather than creating
+     *  a duplicate. */
+    apply(input: DeployInput): Promise<DeployResult>;
+}
+export interface AdapterSelection {
+    adapter: DeployAdapterId;
+    reason: string;
+    alternatives: DeployAdapterId[];
+}
+/**
+ * Pick the right adapter for a workflow snapshot.
+ *
+ * Conservative heuristic: bias toward Cloudflare for simple +
+ * medium projects (cheap + fast + edge), AWS for heavy or
+ * stateful workloads. Adapters that fail readyToRun() are not
+ * filtered out here -- the caller is expected to surface the
+ * "not ready" message after the pick + offer a fallback.
+ */
+export declare function pickDeployAdapter(wf: Partial<WorkflowState>, override?: DeployAdapterId): AdapterSelection;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/deploy/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/deploy/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,KAAK,GAAG,QAAQ,CAAC;AAE9D,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEhD,MAAM,WAAW,UAAU;IACzB,SAAS,EAAY,MAAM,EAAE,CAAC;IAC9B,kBAAkB,EAAG,MAAM,CAAC;IAC5B,iBAAiB,EAAI,MAAM,CAAC;IAC5B,KAAK,EAAgB,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAY,MAAM,CAAC;IACtB,WAAW,EAAI,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAM,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,sEAAsE;IACtE,QAAQ,EAAK,MAAM,CAAC;IACpB,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,GAAG,CAAC,EAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAW,eAAe,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,IAAM,IAAI,EAAE,CAAC;IACpB;+DAC2D;IAC3D,UAAU,IAAI,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACxD;oCACgC;IAChC,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9C;;uBAEmB;IACnB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAClD;AAMD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAK,eAAe,CAAC;IAC5B,MAAM,EAAM,MAAM,CAAC;IACnB,YAAY,EAAE,eAAe,EAAE,CAAC;CACjC;AAcD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,EAAE,EAAE,OAAO,CAAC,aAAa,CAAC,EAC1B,QAAQ,CAAC,EAAE,eAAe,GACzB,gBAAgB,CAmClB"}

package/dist/deploy/adapter.js

@@ -0,0 +1,42 @@
+/**
+ * Pick the right adapter for a workflow snapshot.
+ *
+ * Conservative heuristic: bias toward Cloudflare for simple +
+ * medium projects (cheap + fast + edge), AWS for heavy or
+ * stateful workloads. Adapters that fail readyToRun() are not
+ * filtered out here -- the caller is expected to surface the
+ * "not ready" message after the pick + offer a fallback.
+ */
+export function pickDeployAdapter(wf, override) {
+    if (override) {
+        return {
+            adapter: override,
+            reason: 'explicit override',
+            alternatives: ['cloudflare', 'aws', 'vercel']
+                .filter((a) => a !== override),
+        };
+    }
+    const tier = (wf.tier ?? 'simple');
+    const nfrS = (wf.clarification?.nfr_structural ?? {});
+    const nfrQ = (wf.clarification?.nfr_quantitative ?? {});
+    /* Hard signals that push to AWS. */
+    const persistentWorkers = nfrS.workers === true
+        || (typeof nfrS.persistence === 'string' && /postgres|mysql|mssql/.test(nfrS.persistence));
+    const heavyParallelism = typeof nfrQ.parallelism === 'string'
+        && /high|heavy|many/i.test(nfrQ.parallelism);
+    if (tier === 'full' || persistentWorkers || heavyParallelism) {
+        return {
+            adapter: 'aws',
+            reason: 'tier=' + tier + (persistentWorkers ? '; persistent workers' : '')
+                + (heavyParallelism ? '; heavy parallelism' : ''),
+            alternatives: ['cloudflare', 'vercel'],
+        };
+    }
+    /* Simple + medium default to Cloudflare. */
+    return {
+        adapter: 'cloudflare',
+        reason: 'tier=' + tier + ' (cheap edge + fast deploys)',
+        alternatives: ['vercel', 'aws'],
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/deploy/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../src/deploy/adapter.ts"],"names":[],"mappings":"AAuGA;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAC/B,EAA0B,EAC1B,QAA0B;IAE1B,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,QAAQ;YACjB,MAAM,EAAE,mBAAmB;YAC3B,YAAY,EAAG,CAAC,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAuB;iBACjE,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC;SACjC,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,IAAI,IAAI,QAAQ,CAAS,CAAC;IAC3C,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,cAAc,IAAI,EAAE,CAAsB,CAAC;IAC3E,MAAM,IAAI,GAAG,CAAC,EAAE,CAAC,aAAa,EAAE,gBAAgB,IAAI,EAAE,CAAwB,CAAC;IAE/E,oCAAoC;IACpC,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI;WAC1C,CAAC,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ,IAAI,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IAC7F,MAAM,gBAAgB,GAAG,OAAO,IAAI,CAAC,WAAW,KAAK,QAAQ;WACxD,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IAE/C,IAAI,IAAI,KAAK,MAAM,IAAI,iBAAiB,IAAI,gBAAgB,EAAE,CAAC;QAC7D,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAC;kBACtE,CAAC,gBAAgB,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,YAAY,EAAE,CAAC,YAAY,EAAE,QAAQ,CAAC;SACvC,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,OAAO;QACL,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,8BAA8B;QACvD,YAAY,EAAE,CAAC,QAAQ,EAAE,KAAK,CAAC;KAChC,CAAC;AACJ,CAAC"}