@tillstack/cli 0.2.2 → 0.3.0

package/dist/index.js

@@ -1,26 +1,54 @@
 #!/usr/bin/env node
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output, exit } from 'node:process';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'node:fs';
 import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
 import { loadConfig, saveConfig, updateConfig, configFilePath } from './config.js';
 import * as api from './api.js';
 import { ApiError } from './api.js';
 import { toDoc, parseDoc, planApply, toApiBody } from './rules.js';
 import { c, table, kv, printJson, ok, info, warn, fail, truncate, ago } from './output.js';
-const VERSION = '0.2.0';
+import { notifyUpdate } from './update-check.js';
+// Read our own version from the package manifest at runtime. The old
+// hand-maintained constant silently drifted from what npm published (it still
+// said 0.2.0 at 0.2.2); resolving it relative to this module means it can never
+// disagree with the installed package again — dev (`tsx src/`), built (`dist/`),
+// and globally-installed layouts all put package.json one directory up.
+function readVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+const VERSION = readVersion();
 function parseArgs(argv) {
     const positional = [];
     const named = {};
     const bool = new Set();
+    let rest = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (!a)
             continue;
+        if (a === '--') {
+            // Passthrough boundary: everything after is a verbatim command/argv.
+            rest = argv.slice(i + 1);
+            break;
+        }
         if (a === '-h') {
             bool.add('help');
             continue;
         }
+        if (a === '-v') {
+            bool.add('version');
+            continue;
+        }
         if (a.startsWith('--')) {
             const eq = a.indexOf('=');
             if (eq !== -1) {
@@ -41,7 +69,7 @@ function parseArgs(argv) {
             positional.push(a);
         }
     }
-    return { positional, named, bool };
+    return { positional, named, bool, rest };
 }
 // ── Prompts ──────────────────────────────────────────────────────────────────
 async function promptInput(promptText, opts = {}) {
@@ -224,6 +252,12 @@ ${c.bold('TILLSECRETS')} ${c.dim('(config + secrets)')}  ${c.gray('tilldev secre
   secrets pull [--env <id>]                    Boot-time bulk pull → ${c.dim('.env on stdout (--json for JSON)')}
   secrets lease <KEY> [--ttl <sec>]            Lease a short-lived dynamic credential ${c.dim('(--backend <id> instead of KEY)')}
   secrets lease revoke <lease-id>              Revoke a lease early
+  ${c.dim('— secretless broker (use a secret without knowing it) —')}
+  secrets refs <file>                          Inspect ${c.dim('secretref://…')} handles (metadata only, no value)
+  secrets exec --env-file <f> -- <cmd>         Run <cmd> with ${c.dim('secretref://')} env values materialised into its process only
+  secrets migrate --ref <ref> --file <sql>     Apply a migration to a DB named only by reference ${c.dim('(conn string never leaves the broker)')}
+  secrets deploy-worker --ref <ref> --account <id> --name <s> --file <js>   Deploy a CF Worker ${c.dim('(API token never leaves the broker)')}
+  secrets broker grants                        List consent grants ${c.dim('(grant create/revoke, allow, spends)')}
   secrets sync ls|add|rm|pause|resume|push --project <id>   ${c.dim('One-way push targets')}
   ${c.dim('pull/lease authenticate with a ts_ service token: --token ts_… or $TILLSECRETS_TOKEN.')}
   ${c.dim('lease targets the dynamic-lease service — override with --lease-url / $TILLSECRETS_LEASE_URL.')}
@@ -252,6 +286,7 @@ ${c.bold('TILLARK')} ${c.dim('(backup & disaster recovery)')}  ${c.gray('tilldev
 ${c.bold('TILLFORGE')} ${c.dim('(sovereign code hosting)')}  ${c.gray('tilldev forge …')}
   forge login [--scope read|write]             Sign in for git via the browser (device flow — no pasting tokens)
   forge clone <org>/<repo> [dir]               Clone over HTTPS (token via helper, never in the URL)
+  forge push [<remote>] [<refspec>] [-u]       Push; if a secret is blocked, resolve it interactively then re-push
   forge setup-git                              Wire git's credential helper for the forge host, once
   forge repos ls | get <slug> | rm <slug>
   forge repos create --name <n> [--slug <s>] [--visibility private|internal|public]
@@ -276,8 +311,11 @@ ${c.bold('TILLFORGE')} ${c.dim('(sovereign code hosting)')}  ${c.gray('tilldev f
   forge release ls <repo> | get <repo> <tag> | rm <repo> <tag>
   forge release create <repo> --tag <t> [--name <n>] [--target <ref>] [--generate|--notes <md>] [--prerelease] [--draft]  ${c.dim('(auto-changelog)')}
   forge asset add <repo> <tag> --name <n> --platform linux|darwin|windows|android|ios --url <u> [--arch <a>] [--sha256 <h>]
-  forge env ls <repo> | set <repo> --name <n> [--production] [--url <u>] [--approvals <n>]
-  forge deploy ls <repo> [--env <e>] | create <repo> --env <e> --ref <r> [--url <u>] | status <repo> <id> --state <s>
+  forge provider ls | connect --name <n> --provider <cloudflare|vercel|netlify|supabase|aws|firebase|surge|azure_swa|railway|fly|desktop> --credential '<k=v,…>' | rm <id>
+    ${c.dim('desktop signing (optional): --credential signing=none | signing=pfx,cert_base64=…,cert_password=… | signing=azure_trusted,tenant_id=…,client_id=…,client_secret=…,endpoint=…,account=…,certificate_profile=…')}
+  forge env ls <repo> | set <repo> --name <n> [--production] [--url <u>] [--approvals <n>] [--provider <p> --credential <id> --target 'project=…' --build '<cmd>' --output <dir> --auto-deploy <branch> | --auto-preview]
+    ${c.dim("desktop target: --provider desktop --credential <id> --target 'framework=electron,platforms=linux,windows' (installers publish to the ref's release with sha256 sums)")}
+  forge deploy ls <repo> [--env <e>] | create <repo> --env <e> --ref <r> | promote <repo> <id> --env <e> | rollback <repo> <id> | logs <repo> <id> | cancel <repo> <id> | status <repo> <id> --state <s>
   forge webhook ls | add --url <u> --events push,release,deployment [--repo <slug>] [--secret <s>] | rm <id> | ping <id> | deliveries <id>
   forge pr diff <repo> <number> | forge compare <repo> --base <ref> --head <ref>  ${c.dim('(changed files)')}
   forge issue ls <repo> [--state open|closed|all] [--label <l>]
@@ -299,7 +337,7 @@ ${c.bold('TILLFORGE')} ${c.dim('(sovereign code hosting)')}  ${c.gray('tilldev f
 
 ${c.bold('TILLAUTH')} ${c.dim('(auth)')}            ${c.gray('tilldev auth …')}
   auth apps                 List auth apps
-  auth apps create <name>   Create an auth app
+  auth apps create <name> [--slug <s>]   Create an auth app
   auth app <appId>          Show an auth app
 
 ${c.bold('WORKSPACE')}
@@ -354,6 +392,19 @@ function need(value, usage) {
         throw new Error(`usage: ${usage}`);
     return value;
 }
+// Parse a `k=v,k2=v2` flag into an object (deploy provider credentials + target
+// config). Empty/absent → undefined so the caller can omit the field.
+function parseKv(s) {
+    if (!s)
+        return undefined;
+    const out = {};
+    for (const pair of s.split(',')) {
+        const i = pair.indexOf('=');
+        if (i > 0)
+            out[pair.slice(0, i).trim()] = pair.slice(i + 1).trim();
+    }
+    return Object.keys(out).length ? out : undefined;
+}
 // Quote a value for dotenv output. Barewords pass through; anything with
 // whitespace/quotes/special chars is double-quoted with escapes, so
 // `tilldev secrets pull > .env` round-trips cleanly.
@@ -370,7 +421,7 @@ async function cmdLogin(flags) {
     let r = await api.login(opts, email, password);
     if (r.totpRequired) {
         const code = await promptInput('2FA code: ');
-        r = await api.login(opts, email, password, code);
+        r = await api.login(opts, email, password, code, r.challengeToken);
     }
     saveConfig({ api_url: apiUrl, token: r.token, org: r.org });
     ok(`Signed in as ${c.bold(email)} — token saved to ${c.dim(configFilePath())} (0600)`);
@@ -683,8 +734,11 @@ async function cmdAuth(flags) {
         case undefined:
         case 'apps': {
             if (flags.positional[2] === 'create') {
-                const name = need(flags.positional[3], 'tilldev auth apps create <name>');
-                const r = await api.createAuthApp(opts, name);
+                const name = need(flags.positional[3], 'tilldev auth apps create <name> [--slug <s>]');
+                // The API requires a URL-safe slug; derive one from the name unless the
+                // operator supplies --slug. (Slug must start with a letter, 2–40 chars.)
+                const slug = (flags.named['slug']?.trim().toLowerCase()) || slugify(name);
+                const r = await api.createAuthApp(opts, name, slug);
                 render(flags, r, () => {
                     ok(`Created auth app ${c.bold(r.app.name)}`);
                     console.log(kv([['id', r.app.id], ['public_id', r.app.public_id ?? '-'], ['slug', r.app.slug ?? '-']]));
@@ -1501,9 +1555,232 @@ async function cmdSecrets(flags) {
             });
             return;
         }
+        case 'refs': {
+            // Inspect the references in a file / --ref / stdin — resolves METADATA only
+            // (resolvable? sensitivity?), never a value. `tilldev secrets refs [file]`.
+            const text = await gatherRefText(flags);
+            if (!text.trim())
+                throw new Error('usage: tilldev secrets refs <file> | --ref <secretref://…>  (or pipe on stdin)');
+            const r = await api.resolveRefs(opts, { text, meta_only: true });
+            render(flags, r, () => {
+                if (r.resolved.length) {
+                    const cols = [
+                        { header: 'REF', get: (x) => c.bold(x.ref) },
+                        { header: 'KEY', get: (x) => x.key },
+                        { header: 'SENSITIVITY', get: (x) => String(x.sensitivity ?? '') },
+                        { header: 'OK', get: () => c.green('resolvable') },
+                    ];
+                    console.log(table(r.resolved, cols));
+                }
+                for (const f of r.refusals)
+                    warn(`${f.ref} — ${f.reason}`);
+                if (!r.resolved.length && !r.refusals.length)
+                    info('No references found.');
+            });
+            return;
+        }
+        case 'exec': {
+            // Run a command with `secretref://…` env values materialised into the CHILD
+            // process's env — never printed, never in this process's env. Fail-closed:
+            // if any referenced value can't resolve, the command does NOT run.
+            //   tilldev secrets exec --env-file .env.refs -- <cmd> [args…]
+            const cmd = flags.rest;
+            if (cmd.length === 0)
+                throw new Error('usage: tilldev secrets exec --env-file <path> -- <command> [args…]');
+            const file = need(flags.named['env-file'], 'tilldev secrets exec --env-file <path> -- <command>');
+            if (!existsSync(file))
+                throw new Error(`env file not found: ${file}`);
+            const entries = parseDotenv(readFileSync(file, 'utf8'));
+            const agentKey = flags.named['agent'] ?? 'cli';
+            // Resolve every reference across all values in ONE audited call.
+            const refText = entries.map((e) => e.value).join('\n');
+            const r = await api.resolveRefs(opts, { text: refText, agent_key: agentKey, command: cmd.join(' ') });
+            if (r.refusals.length && !flags.bool.has('allow-partial')) {
+                for (const f of r.refusals)
+                    warn(`${f.ref} — ${f.reason}`);
+                throw new Error('some references could not be resolved — refusing to exec (pass --allow-partial to run anyway)');
+            }
+            const valueByRef = new Map();
+            for (const rv of r.resolved)
+                if (rv.value != null)
+                    valueByRef.set(rv.ref, rv.value);
+            // Substitute resolved values into each env value (literals pass through).
+            const childEnv = {};
+            let materialised = 0;
+            for (const e of entries) {
+                let v = e.value;
+                let had = false;
+                for (const [ref, val] of valueByRef) {
+                    if (v.includes(ref)) {
+                        v = v.split(ref).join(val);
+                        had = true;
+                    }
+                }
+                if (had)
+                    materialised++;
+                childEnv[e.key] = v;
+            }
+            process.stderr.write(`${c.dim(`materialised ${valueByRef.size} reference(s) into ${materialised} env var(s); running: ${cmd.join(' ')}`)}\n`);
+            const res = spawnSync(cmd[0], cmd.slice(1), { stdio: 'inherit', env: { ...process.env, ...childEnv } });
+            if (res.error)
+                throw res.error;
+            process.exit(res.status ?? 1);
+            return;
+        }
+        case 'migrate': {
+            // Catalog action: apply a migration to a DB named only by reference. The
+            // connection string never reaches this CLI — the broker holds + spends it.
+            //   tilldev secrets migrate --ref secretref://infra/prod/DATABASE_URL --file 0043.sql
+            const secretRef = need(flags.named['ref'], 'tilldev secrets migrate --ref <secretref://…> --file <sql>');
+            const file = need(flags.named['file'], 'tilldev secrets migrate --ref <secretref://…> --file <sql>');
+            if (!existsSync(file))
+                throw new Error(`sql file not found: ${file}`);
+            const sql = readFileSync(file, 'utf8');
+            const body = { secret_ref: secretRef, sql };
+            if (flags.named['agent'])
+                body.agent_key = flags.named['agent'];
+            const r = await api.applyMigrationAction(opts, body);
+            render(flags, r, () => {
+                if (r.refusal) {
+                    fail(`Refused (${r.refusal.code}): ${r.refusal.reason}`);
+                    return;
+                }
+                for (const s of r.results ?? [])
+                    console.log(`  ${s.ok ? c.green('✓') : c.red('✗')} ${s.preview}${s.error ? c.red(`  ${s.error}`) : ''}`);
+                if (r.ok)
+                    ok(`Applied ${r.statements} statement(s) via ${c.bold(secretRef)} — the connection string never left the broker`);
+                else
+                    fail('A statement failed — see above.');
+            });
+            return;
+        }
+        case 'deploy-worker': {
+            // Catalog action: deploy a Cloudflare Worker with the CF API token named only
+            // by reference. The token never reaches this CLI — the broker holds + spends it.
+            //   tilldev secrets deploy-worker --ref secretref://infra/prod/CLOUDFLARE_API_TOKEN \
+            //     --account <32-hex> --name my-worker --file worker.js [--compat-date 2026-07-01]
+            const secretRef = need(flags.named['ref'], 'tilldev secrets deploy-worker --ref <secretref://…> --account <id> --name <script> --file <worker.js>');
+            const accountId = need(flags.named['account'], 'tilldev secrets deploy-worker --account <cloudflare-account-id>');
+            const scriptName = need(flags.named['name'], 'tilldev secrets deploy-worker --name <script-name>');
+            const file = need(flags.named['file'], 'tilldev secrets deploy-worker --file <worker.js>');
+            if (!existsSync(file))
+                throw new Error(`worker file not found: ${file}`);
+            const script = readFileSync(file, 'utf8');
+            const body = { secret_ref: secretRef, account_id: accountId, script_name: scriptName, script };
+            if (flags.named['compat-date'])
+                body.compatibility_date = flags.named['compat-date'];
+            if (flags.bool.has('service-worker'))
+                body.module = false;
+            if (flags.named['agent'])
+                body.agent_key = flags.named['agent'];
+            const r = await api.deployWorkerAction(opts, body);
+            render(flags, r, () => {
+                if (r.refusal) {
+                    fail(`Refused (${r.refusal.code}): ${r.refusal.reason}`);
+                    return;
+                }
+                if (r.ok)
+                    ok(`Deployed ${c.bold(scriptName)} (${r.size} bytes) via ${c.bold(secretRef)} — the CF token never left the broker`);
+                else
+                    fail(`Deploy failed: ${(r.errors ?? []).map((e) => `${e.code}: ${e.message}`).join('; ') || 'unknown error'}`);
+            });
+            return;
+        }
+        case 'broker': {
+            const action = flags.positional[2] ?? 'grants';
+            if (action === 'grants' || (action === 'grant' && (flags.positional[3] ?? 'ls') === 'ls')) {
+                const r = await api.listBrokerGrants(opts);
+                render(flags, r, () => {
+                    const cols = [
+                        { header: 'AGENT', get: (g) => c.bold(g.agent_key) },
+                        { header: 'HOST', get: (g) => g.destination_host },
+                        { header: 'SCOPE', get: (g) => g.scope },
+                        { header: 'USES', get: (g) => `${g.uses}${g.max_uses != null ? `/${g.max_uses}` : ''}` },
+                        { header: 'STATE', get: (g) => (g.revoked_at ? c.red('revoked') : c.green('active')) },
+                        { header: 'ID', get: (g) => c.dim(g.id) },
+                    ];
+                    console.log(table(r.grants, cols));
+                });
+                return;
+            }
+            if (action === 'grant') {
+                const gsub = flags.positional[3];
+                if (gsub === 'revoke') {
+                    const id = need(flags.positional[4], 'tilldev secrets broker grant revoke <grant-id>');
+                    const r = await api.revokeBrokerGrant(opts, id);
+                    render(flags, r, () => ok(`Revoked grant ${c.bold(id)}`));
+                    return;
+                }
+                // grant create
+                const scope = (flags.named['scope'] ?? 'ttl');
+                const body = {
+                    secret_id: need(flags.named['secret'], 'grant create needs --secret <id> --agent <key> --host <host>'),
+                    agent_key: need(flags.named['agent'], 'grant create needs --agent <key>'),
+                    destination_host: need(flags.named['host'], 'grant create needs --host <host>'),
+                    scope,
+                };
+                if (flags.named['session'])
+                    body.session_id = flags.named['session'];
+                if (flags.named['ttl-minutes'])
+                    body.ttl_minutes = Number(flags.named['ttl-minutes']);
+                const r = await api.createBrokerGrant(opts, body);
+                render(flags, r, () => ok(`Granted ${c.bold(body.agent_key)} → ${body.destination_host} (${scope}) — ${c.dim(r.grant.id)}`));
+                return;
+            }
+            if (action === 'allow') {
+                const asub = flags.positional[3];
+                if (asub === 'ls') {
+                    const secretId = need(flags.positional[4], 'tilldev secrets broker allow ls <secret-id>');
+                    const r = await api.listSecretDestinations(opts, secretId);
+                    render(flags, r, () => {
+                        const cols = [
+                            { header: 'HOST', get: (d) => c.bold(d.host) },
+                            { header: 'NOTE', get: (d) => d.note },
+                            { header: 'ID', get: (d) => c.dim(d.id) },
+                        ];
+                        console.log(table(r.destinations, cols));
+                    });
+                    return;
+                }
+                const secretId = need(flags.positional[3], 'tilldev secrets broker allow <secret-id> <host> [--note …]');
+                const host = need(flags.positional[4], 'tilldev secrets broker allow <secret-id> <host>');
+                const r = await api.addSecretDestination(opts, secretId, host, flags.named['note']);
+                render(flags, r, () => ok(`Allowed ${c.bold(host)} for secret ${c.dim(secretId)}`));
+                return;
+            }
+            if (action === 'spends') {
+                const r = await api.listBrokerSpends(opts);
+                render(flags, r, () => {
+                    const cols = [
+                        { header: 'WHEN', get: (s) => truncate(s.created_at, 19) },
+                        { header: 'AGENT', get: (s) => s.agent_key },
+                        { header: 'ACTION', get: (s) => s.action },
+                        { header: 'REF', get: (s) => s.secret_ref ?? '' },
+                        { header: 'HOST', get: (s) => s.destination_host ?? '' },
+                        { header: 'OUTCOME', get: (s) => (s.outcome === 'spent' ? c.green('spent') : c.red(`refused${s.refuse_reason ? `: ${s.refuse_reason}` : ''}`)) },
+                    ];
+                    console.log(table(r.spends, cols));
+                });
+                return;
+            }
+            throw new Error('usage: tilldev secrets broker <grants|grant create|grant revoke|allow|allow ls|spends>');
+        }
         default:
-            throw new Error('usage: tilldev secrets <projects|env|ls|set|get|versions|rollback|rm|pull|lease|sync|tokens>');
+            throw new Error('usage: tilldev secrets <projects|env|ls|set|get|versions|rollback|rm|pull|lease|sync|tokens|refs|exec|migrate|deploy-worker|broker>');
+    }
+}
+/** Collect reference text for `secrets refs` from a file arg, --ref flags, or stdin. */
+async function gatherRefText(flags) {
+    const parts = [];
+    const fileArg = flags.positional[2] ?? flags.named['env-file'];
+    if (fileArg && existsSync(fileArg))
+        parts.push(readFileSync(fileArg, 'utf8'));
+    if (flags.named['ref'])
+        parts.push(flags.named['ref']);
+    if (parts.length === 0 && !process.stdin.isTTY) {
+        parts.push(await readStdin());
     }
+    return parts.join('\n');
 }
 // ── TillArk ────────────────────────────────────────────────────────────────────
 // Backup / disaster-recovery control plane. Dangerous verbs (real restore,
@@ -2302,6 +2579,745 @@ async function cmdForgeSetupGit(flags) {
     info(`Then plain git just works — no token in the URL:`);
     console.log(`  ${c.dim(`git clone https://${host}/<org>/<repo>.git`)}`);
 }
+// Parse ONLY the blocking rejection block. The relayed stderr can ALSO carry a
+// non-blocking "allowlisted (audited, NOT blocking)" block in the same shape,
+// printed BEFORE the rejection — so we start parsing at the "push rejected:"
+// header and stop at its footer, never treating a suppressed hit as a blocker.
+function parseRejectionFindings(stderr) {
+    const lines = stderr.split('\n');
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/tillforge:\s*push rejected:/.test(lines[i])) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return { findings: [], truncated: false };
+    const out = [];
+    const seen = new Set();
+    let truncated = false;
+    const row = /^remote:\s+(.+?):(\d+)\s+(.+?)\s+\(([a-z0-9-]+)\)/;
+    for (let i = start + 1; i < lines.length; i++) {
+        const ln = lines[i];
+        if (/^remote:\s+Remove the secret/.test(ln))
+            break;
+        if (/(?:…|\.\.\.)\s*and\s+\d+\s+more/.test(ln)) {
+            truncated = true;
+            continue;
+        }
+        const m = row.exec(ln);
+        if (!m)
+            continue;
+        const path = m[1].trim();
+        const key = `${path}:${m[2]}:${m[4]}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push({ path, line: parseInt(m[2], 10), desc: m[3].trim(), rule: m[4] });
+    }
+    return { findings: out, truncated };
+}
+// The complete file-level allow marker for a path, in that file's comment
+// syntax so it never breaks the file. Returns null for formats with no comment
+// syntax (e.g. JSON) — those can't carry a marker and must be treated as real.
+function fileMarkerFor(path, reason) {
+    const base = (path.split('/').pop() ?? path).toLowerCase();
+    const ext = base.includes('.') ? base.slice(base.lastIndexOf('.')) : '';
+    const marker = `tillforge:allow-file-secrets — ${reason}`;
+    const hash = new Set(['.py', '.rb', '.sh', '.bash', '.zsh', '.yaml', '.yml', '.toml', '.env', '.ini', '.cfg', '.conf', '.properties', '.tf', '.tfvars', '.pl', '.r', '.gitignore', '.dockerignore']);
+    const slash = new Set(['.go', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.java', '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.rs', '.swift', '.kt', '.kts', '.scala', '.php', '.dart', '.groovy', '.gradle']);
+    if (base === 'dockerfile' || base === 'makefile' || hash.has(ext))
+        return `# ${marker}`;
+    if (slash.has(ext))
+        return `// ${marker}`;
+    if (ext === '.sql' || ext === '.lua' || ext === '.hs' || ext === '.elm')
+        return `-- ${marker}`;
+    if (ext === '.css' || ext === '.scss' || ext === '.less')
+        return `/* ${marker} */`;
+    if (ext === '.html' || ext === '.htm' || ext === '.xml' || ext === '.svg' || ext === '.vue' || ext === '.svelte')
+        return `<!-- ${marker} -->`;
+    if (ext === '.json' || ext === '.json5' || ext === '.lock')
+        return null;
+    return `# ${marker}`; // safe default for plain/config-ish files
+}
+// Insert a marker at the top of a file, after a shebang if present so the file
+// still runs. The marker only needs to exist as text in the blob (the scanner
+// does a substring match), but keeping it a real comment keeps the file valid.
+function insertFileMarker(absPath, markerLine) {
+    const content = readFileSync(absPath, 'utf8');
+    if (content.startsWith('#!')) {
+        const nl = content.indexOf('\n');
+        if (nl >= 0) {
+            writeFileSync(absPath, content.slice(0, nl + 1) + markerLine + '\n' + content.slice(nl + 1));
+            return;
+        }
+    }
+    writeFileSync(absPath, markerLine + '\n' + content);
+}
+function readLineFromFile(absPath, line) {
+    try {
+        return readFileSync(absPath, 'utf8').split('\n')[line - 1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+// Run git in `root`, capturing output. Throws only if git can't be executed.
+function gitCapture(root, args, env) {
+    const res = spawnSync('git', args, { cwd: root, encoding: 'utf8', env: env ?? process.env, maxBuffer: 64 * 1024 * 1024 });
+    if (res.error)
+        throw new Error(`could not run git (${res.error.code ?? res.error.message}). Is git installed?`);
+    return { status: res.status ?? 0, stdout: res.stdout ?? '', stderr: res.stderr ?? '' };
+}
+// ── Remediation primitives (remove / move-to-TillSecrets / history rewrite) ───
+// Every path below keeps the SERVER as the wall: we only ever change the working
+// tree / history so the push-boundary scanner passes honestly. We never fake a
+// pass. A REAL secret in a commit can only leave by rewriting that commit —
+// editing the tree and adding a new commit does NOT remove it from what's pushed,
+// so "remove" amends the tip (fast path) or escalates to a history rewrite.
+function slugify(s) {
+    return (s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'app').slice(0, 60);
+}
+// Normalise an identifier into a valid TillSecrets key: [A-Z_][A-Z0-9_]*.
+function toEnvKey(raw, fallback) {
+    const base = (raw ?? fallback).replace(/[^A-Za-z0-9_]/g, '_').toUpperCase().replace(/^_+|_+$/g, '');
+    const k = base || fallback.toUpperCase().replace(/[^A-Z0-9_]/g, '_');
+    return /^[A-Z_]/.test(k) ? k : '_' + k;
+}
+// Best-effort pull of `KEY <sep> "value"` off a finding line. The REAL value comes
+// from the working tree (server findings are masked), so this is what we store /
+// redact. Returns nothing when the line isn't a simple assignment.
+function extractAssignment(line) {
+    const m = line.match(/(?:export\s+)?([A-Za-z_][A-Za-z0-9_.-]*)\s*(?:=>|[:=])\s*(.+?)\s*[,;]?\s*$/);
+    if (!m)
+        return {};
+    let value = m[2].trim();
+    const q = value[0];
+    if ((q === '"' || q === "'" || q === '`') && value.length >= 2 && value.endsWith(q))
+        value = value.slice(1, -1);
+    const out = { value };
+    if (m[1])
+        out.key = m[1];
+    return out;
+}
+// A whole file that is itself a credential (so removal = git rm + .gitignore,
+// never a line edit). Deliberately excludes *.example / *.sample templates.
+function looksLikeSecretFile(rel) {
+    const base = (rel.split('/').pop() ?? rel).toLowerCase();
+    if (base.endsWith('.example') || base.endsWith('.sample'))
+        return false;
+    if (/^\.env(\..+)?$/.test(base))
+        return true;
+    if (/\.(pem|key|p12|pfx|pkcs12|asc|ppk|keystore|jks)$/.test(base))
+        return true;
+    if (new Set(['id_rsa', 'id_dsa', 'id_ecdsa', 'id_ed25519', 'credentials', '.npmrc', '.pypirc', '.netrc', '.dockercfg']).has(base))
+        return true;
+    if (/(service[-_]?account|serviceaccount|firebase[-_]?adminsdk|gcloud).*\.json$/.test(base))
+        return true;
+    return false;
+}
+// Parse dotenv KEY=VALUE lines (used when moving a whole .env-style file).
+function parseDotenv(text) {
+    const out = [];
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+        if (!m)
+            continue;
+        let v = m[2].trim();
+        const q = v[0];
+        if ((q === '"' || q === "'") && v.length >= 2 && v.endsWith(q))
+            v = v.slice(1, -1);
+        out.push({ key: m[1], value: v });
+    }
+    return out;
+}
+// The line-comment token for a file's language (for breadcrumbs). null = no
+// single-line comment syntax we want to use.
+function commentPrefix(path) {
+    const base = (path.split('/').pop() ?? path).toLowerCase();
+    const ext = base.includes('.') ? base.slice(base.lastIndexOf('.')) : '';
+    if (base === 'dockerfile' || base === 'makefile')
+        return '#';
+    if (new Set(['.py', '.rb', '.sh', '.bash', '.zsh', '.yaml', '.yml', '.toml', '.env', '.ini', '.cfg', '.conf', '.tf', '.tfvars', '.pl', '.r']).has(ext))
+        return '#';
+    if (new Set(['.go', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.java', '.c', '.h', '.cc', '.cpp', '.hpp', '.cs', '.rs', '.swift', '.kt', '.kts', '.scala', '.php', '.dart']).has(ext))
+        return '//';
+    if (new Set(['.sql', '.lua', '.hs', '.elm']).has(ext))
+        return '--';
+    return null;
+}
+function gitignoreAdd(root, rel) {
+    const gi = join(root, '.gitignore');
+    let cur = '';
+    try {
+        cur = readFileSync(gi, 'utf8');
+    }
+    catch { /* no .gitignore yet */ }
+    if (cur.split('\n').some((l) => l.trim() === rel || l.trim() === '/' + rel))
+        return;
+    writeFileSync(gi, cur + (cur && !cur.endsWith('\n') ? '\n' : '') + rel + '\n');
+}
+// Redact a secret literal on one line in the working tree, keeping any quotes so
+// the file stays syntactically valid ('abc' → ''). Returns the before/after line.
+function redactLiteralInTree(absPath, lineNo, value) {
+    const lines = readFileSync(absPath, 'utf8').split('\n');
+    const idx = lineNo - 1;
+    const before = lines[idx];
+    if (before == null || value === '' || !before.includes(value))
+        return null;
+    const after = before.replace(value, '');
+    lines[idx] = after;
+    writeFileSync(absPath, lines.join('\n'));
+    return { before, after };
+}
+// Write/refresh a KEY= template so a removed .env file's shape stays documented.
+function writeEnvExample(root, rel, keys) {
+    const target = /\.example$/.test(rel) ? rel : rel + '.example';
+    const path = join(root, target);
+    let cur = '';
+    try {
+        cur = readFileSync(path, 'utf8');
+    }
+    catch { /* new */ }
+    const have = new Set(cur.split('\n').map((l) => l.split('=')[0].trim()));
+    const add = keys.filter((k) => !have.has(k)).map((k) => `${k}=`).join('\n');
+    if (add)
+        writeFileSync(path, cur + (cur && !cur.endsWith('\n') ? '\n' : '') + add + '\n');
+    return target;
+}
+// Which unpushed commits touch `file`. range is `<remote>/<branch>..HEAD` when an
+// upstream exists, else `HEAD` (a fresh import — every commit is unpushed).
+function commitsTouching(root, range, file) {
+    const r = gitCapture(root, ['log', '--format=%H', range, '--', file]);
+    return r.stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+// The unpushed range and whether the branch already has an upstream on the remote.
+function unpushedRange(root, remote, branch) {
+    const trackingRef = `refs/remotes/${remote}/${branch}`;
+    if (gitCapture(root, ['rev-parse', '--verify', '--quiet', trackingRef]).status === 0) {
+        return { range: `${remote}/${branch}..HEAD`, hasUpstream: true };
+    }
+    return { range: 'HEAD', hasUpstream: false };
+}
+function filterRepoAvailable(root) {
+    return gitCapture(root, ['filter-repo', '--version']).status === 0;
+}
+async function resolveSecretsTarget(opts, repoSlug) {
+    let projects;
+    try {
+        projects = (await api.listSecretsProjects(opts)).projects;
+    }
+    catch (e) {
+        if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
+            warn('Not signed in to TillSecrets (or not an admin/owner) — can’t store it there right now.');
+            info(c.dim('Run `tilldev forge login` for git only; a TillSecrets write needs a dashboard token (TILLDEV_TOKEN) with admin/owner.'));
+            return null;
+        }
+        if (e instanceof ApiError && e.status === 404) {
+            warn('TillSecrets isn’t enabled for this org — can’t store it there right now.');
+            return null;
+        }
+        throw e;
+    }
+    // Prefer a project whose slug matches the repo; else let the user pick or create.
+    let project = projects.find((p) => p.slug === repoSlug || p.slug === slugify(repoSlug));
+    if (!project) {
+        if (projects.length) {
+            console.log(c.dim('  TillSecrets projects:'));
+            projects.forEach((p, i) => console.log(`    ${c.bold(String(i + 1))}. ${p.name} ${c.dim('(' + p.slug + ')')}`));
+            const pick = (await promptInput(`  Pick a project [1-${projects.length}], or ${c.bold('n')} for a new one named "${repoSlug}" > `)).trim().toLowerCase();
+            const n = Number(pick);
+            if (pick !== 'n' && Number.isInteger(n) && n >= 1 && n <= projects.length)
+                project = projects[n - 1];
+        }
+        if (!project) {
+            info(`Creating TillSecrets project ${c.bold(repoSlug)}…`);
+            try {
+                project = (await api.createSecretsProject(opts, repoSlug, slugify(repoSlug), `Secrets for the ${repoSlug} repository (created from tilldev forge push)`)).project;
+            }
+            catch (e) {
+                if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
+                    warn('Your dashboard token can’t create TillSecrets projects (needs admin/owner).');
+                    return null;
+                }
+                throw e;
+            }
+        }
+    }
+    let envs = (await api.listSecretsEnvironments(opts, project.id)).environments;
+    let env = envs.find((e) => e.slug === 'dev' || e.slug === 'development') ?? envs[0];
+    if (!env) {
+        info(`No environments yet — creating ${c.bold('dev')}…`);
+        env = (await api.createSecretsEnvironment(opts, project.id, 'Development', 'dev')).environment;
+    }
+    else if (envs.length > 1) {
+        console.log(c.dim('  Environments:'));
+        envs.forEach((e, i) => console.log(`    ${c.bold(String(i + 1))}. ${e.name} ${c.dim('(' + e.slug + ')')}`));
+        const pick = (await promptInput(`  Which environment? [1-${envs.length}] (default ${env.slug}) > `)).trim();
+        const n = Number(pick);
+        if (pick && Number.isInteger(n) && n >= 1 && n <= envs.length)
+            env = envs[n - 1];
+    }
+    return { project, env };
+}
+async function cmdForgePush(flags) {
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+    if (top.error || top.status !== 0)
+        throw new Error('not inside a git repository (run this from your repo)');
+    const root = (top.stdout ?? '').trim();
+    const repoSlug = slugify(root.split('/').pop() ?? 'repo');
+    const token = forgeGitToken(flags);
+    if (!token)
+        warn('No token found — set TILLDEV_FORGE_TOKEN or run `tilldev forge login`; git will prompt otherwise.');
+    const host = forgeGitHost();
+    const remote = flags.positional[2] ?? 'origin';
+    const refspec = flags.positional[3];
+    const branch = refspec ? refspec.split(':').pop().replace(/^refs\/heads\//, '') : gitCapture(root, ['rev-parse', '--abbrev-ref', 'HEAD']).stdout.trim() || 'main';
+    const setUpstream = flags.bool.has('set-upstream') || flags.bool.has('u');
+    const env = { ...process.env, ...(token ? { TILLDEV_FORGE_TOKEN: token } : {}) };
+    const interactive = Boolean(process.stdin.isTTY) && Boolean(output.isTTY);
+    const { opts } = resolveOpts(flags);
+    let forceNext = false; // set after a history rewrite — the remote needs a lease-guarded force
+    const pushArgs = () => {
+        const a = ['-c', 'credential.helper=', '-c', `credential.helper=${credentialHelperArg()}`, 'push'];
+        if (forceNext)
+            a.push('--force-with-lease');
+        if (setUpstream)
+            a.push('-u');
+        a.push(remote);
+        if (refspec)
+            a.push(refspec);
+        return a;
+    };
+    // Resolved lazily + cached so multiple "move to TillSecrets" reuse one project/env.
+    let secretsTarget;
+    const getSecretsTarget = async () => {
+        if (secretsTarget === undefined)
+            secretsTarget = await resolveSecretsTarget(opts, repoSlug);
+        return secretsTarget;
+    };
+    const resolvedInTree = new Set(); // files we redacted at the tip this run
+    const MAX_ROUNDS = 10;
+    for (let round = 1; round <= MAX_ROUNDS; round++) {
+        info(`Pushing ${refspec ? c.bold(refspec) + ' ' : ''}to ${c.bold(remote)} ${c.dim('(' + host + ')')}…`);
+        const res = gitCapture(root, pushArgs(), env);
+        forceNext = false;
+        const remoteLines = res.stderr.split('\n').filter((l) => l.startsWith('remote:'));
+        if (res.status === 0) {
+            if (remoteLines.length)
+                process.stderr.write(remoteLines.join('\n') + '\n');
+            ok('Pushed to TillForge.');
+            return;
+        }
+        const { findings, truncated } = parseRejectionFindings(res.stderr);
+        if (findings.length === 0) {
+            // Not a secret rejection — a normal git failure (auth, non-fast-forward, …).
+            process.stderr.write(res.stderr);
+            exit(res.status || 1);
+        }
+        console.log('');
+        warn(`The push boundary blocked ${c.bold(String(findings.length))} secret finding${findings.length === 1 ? '' : 's'}${truncated ? c.dim(' (more may follow after these)') : ''}. ${c.dim('Nothing entered history.')}`);
+        if (!interactive) {
+            for (const f of findings)
+                console.error(`  ${c.yellow(f.path + ':' + f.line)}  ${f.desc} ${c.dim('(' + f.rule + ')')}`);
+            fail('Re-run in an interactive terminal to resolve these, or fix them manually.');
+            exit(1);
+        }
+        // Group by file — a file-level marker covers every finding in the file, and a
+        // remove/move resolves them together.
+        const byFile = new Map();
+        for (const f of findings)
+            byFile.set(f.path, [...(byFile.get(f.path) ?? []), f]);
+        const toMark = [];
+        const amendPaths = new Set(); // tree edits to fold into the tip commit
+        const rewriteFiles = []; // files the user chose to purge from history
+        const heldFiles = new Set();
+        let movedCount = 0;
+        let held = false;
+        let excludeRequested = false;
+        for (const [rel, fs] of byFile) {
+            const abs = join(root, rel);
+            const historical = resolvedInTree.has(rel); // we already redacted its tip and it's STILL flagged
+            const range = unpushedRange(root, remote, branch).range;
+            const touching = commitsTouching(root, range, rel);
+            const head = gitCapture(root, ['rev-parse', 'HEAD']).stdout.trim();
+            const tipOnly = touching.length > 0 && touching.every((sha) => sha === head);
+            console.log('');
+            console.log(`${c.bold(rel)} ${c.dim('— ' + fs.length + ' finding' + (fs.length === 1 ? '' : 's'))}`);
+            for (const f of fs) {
+                const ctx = readLineFromFile(abs, f.line);
+                console.log(`  ${c.yellow(':' + f.line)} ${c.dim('(' + f.rule + ')')}${ctx ? '  ' + c.gray(truncate(ctx.trim(), 80)) : ''}`);
+            }
+            if (historical || !tipOnly) {
+                console.log(c.dim(`  This secret is in earlier commit(s), not just the tip — a tree edit can’t remove it; use ${c.bold('[w]')} purge-from-history or ${c.bold('[x]')} push-without-these-commits.`));
+            }
+            const menu = `  ${c.bold('[a]')}llowlist  ${c.bold('[r]')}emove  ${c.bold('[m]')}ove to TillSecrets  ${c.bold('[w]')} purge history  ${c.bold('[x]')} exclude commits  ${c.bold('[h]')}old  ${c.bold('[q]')}uit  > `;
+            const ans = ((await promptInput(menu)).trim().toLowerCase()[0]) ?? '';
+            if (ans === 'q') {
+                fail('Aborted — nothing was pushed.');
+                exit(130);
+            }
+            if (ans === 'h') {
+                held = true;
+                heldFiles.add(rel);
+                info(`Holding ${c.bold(rel)} — nothing pushed for it.`);
+                continue;
+            }
+            if (ans === 'w') {
+                rewriteFiles.push(rel);
+                continue;
+            }
+            if (ans === 'x') {
+                excludeRequested = true;
+                continue;
+            }
+            if (ans === 'a') {
+                if (fileMarkerFor(rel, 'x') === null) {
+                    warn(`${rel} has no comment syntax (e.g. JSON) for a marker — remove it or hold instead. Holding.`);
+                    held = true;
+                    heldFiles.add(rel);
+                    continue;
+                }
+                let reason = (await promptInput('  Reason (why is this a false positive?) > ')).trim();
+                if (!reason)
+                    reason = 'reviewed: false positive (fixture/public/placeholder)';
+                toMark.push({ path: rel, reason });
+                continue;
+            }
+            if (ans === 'r' || ans === 'm') {
+                if (!tipOnly && !looksLikeSecretFile(rel)) {
+                    // Embedded literal that lives in earlier history — a tip edit won't purge it.
+                    warn(`${rel} is touched by earlier commits — a plain remove can’t purge it from history.`);
+                    if (ans === 'm')
+                        info(c.dim('  Storing the value in TillSecrets anyway, then use [w] to purge it from history.'));
+                    else {
+                        held = true;
+                        heldFiles.add(rel);
+                        info('  Choose [w] purge history (or [x]) next round. Holding for now.');
+                        continue;
+                    }
+                }
+                // move: store the value(s) in TillSecrets first (cold-start-aware).
+                if (ans === 'm') {
+                    const target = await getSecretsTarget();
+                    if (!target) {
+                        info(c.dim('  Couldn’t store in TillSecrets — continuing with removal only; store it later with `tilldev secrets set`.'));
+                    }
+                    else if (looksLikeSecretFile(rel) && /\.env(\..+)?$/.test((rel.split('/').pop() ?? '').toLowerCase())) {
+                        // Whole .env-style file: store every KEY=VALUE pair.
+                        const pairs = parseDotenv(readFileSync(abs, 'utf8'));
+                        for (const p of pairs) {
+                            const key = toEnvKey(p.key, p.key);
+                            try {
+                                await api.setSecret(opts, target.env.id, key, p.value, `imported from ${rel} via forge push`);
+                                movedCount++;
+                                ok(`  → TillSecrets ${c.bold(target.project.slug + '/' + target.env.slug + '/' + key)}`);
+                            }
+                            catch (e) {
+                                if (e instanceof ApiError)
+                                    warn(`  couldn’t store ${key}: ${e.message}`);
+                                else
+                                    throw e;
+                            }
+                        }
+                    }
+                    else if (looksLikeSecretFile(rel)) {
+                        // Opaque credential file (PEM, service-account JSON): store as one blob.
+                        const key = toEnvKey(rel.split('/').pop(), 'SECRET_FILE');
+                        try {
+                            await api.setSecret(opts, target.env.id, key, readFileSync(abs, 'utf8'), `imported file ${rel} via forge push`);
+                            movedCount++;
+                            ok(`  → TillSecrets ${c.bold(target.project.slug + '/' + target.env.slug + '/' + key)}`);
+                        }
+                        catch (e) {
+                            if (e instanceof ApiError)
+                                warn(`  couldn’t store ${key}: ${e.message}`);
+                            else
+                                throw e;
+                        }
+                    }
+                    else {
+                        // Embedded literals: store each finding's real value (bottom-up so line
+                        // numbers stay valid as we redact + breadcrumb).
+                        const cp = commentPrefix(rel);
+                        for (const f of [...fs].sort((a, b) => b.line - a.line)) {
+                            const line = readLineFromFile(abs, f.line);
+                            const guessed = line ? extractAssignment(line) : {};
+                            const suggestedKey = toEnvKey(guessed.key, 'SECRET');
+                            const keyIn = (await promptInput(`  Key for :${f.line} in TillSecrets [${suggestedKey}] > `)).trim();
+                            const key = keyIn ? toEnvKey(keyIn, suggestedKey) : suggestedKey;
+                            let value = guessed.value ?? '';
+                            if (!value)
+                                value = await promptInput(`  Paste the secret value for ${key} (hidden) > `, { hidden: true });
+                            else {
+                                const edit = await promptInput(`  Value looks like "${truncate(value, 24)}" — Enter to use it, or paste a different one (hidden) > `, { hidden: true });
+                                if (edit)
+                                    value = edit;
+                            }
+                            try {
+                                await api.setSecret(opts, target.env.id, key, value, `moved from ${rel}:${f.line} via forge push`);
+                                movedCount++;
+                                ok(`  → TillSecrets ${c.bold(target.project.slug + '/' + target.env.slug + '/' + key)}`);
+                                if (value)
+                                    redactLiteralInTree(abs, f.line, value);
+                                if (cp) {
+                                    const lines = readFileSync(abs, 'utf8').split('\n');
+                                    lines.splice(f.line - 1, 0, `${cp} ${key} moved to TillSecrets (${target.project.slug}/${target.env.slug}) — see \`tilldev secrets\``);
+                                    writeFileSync(abs, lines.join('\n'));
+                                }
+                            }
+                            catch (e) {
+                                if (e instanceof ApiError)
+                                    warn(`  couldn’t store ${key}: ${e.message}`);
+                                else
+                                    throw e;
+                            }
+                        }
+                    }
+                }
+                // remove from the working tree (both r and m end here).
+                if (looksLikeSecretFile(rel)) {
+                    // rm --cached stages the removal (kept on disk, now gitignored). We do NOT
+                    // re-add `rel` to the pathspec below — it's ignored now, so `git add` would
+                    // error; the staged deletion is already captured by the --amend.
+                    gitCapture(root, ['rm', '--cached', '--', rel]);
+                    gitignoreAdd(root, rel);
+                    const keys = /\.env/.test(rel) ? parseDotenv((() => { try {
+                        return readFileSync(abs, 'utf8');
+                    }
+                    catch {
+                        return '';
+                    } })()).map((p) => p.key) : [];
+                    if (keys.length) {
+                        const ex = writeEnvExample(root, rel, keys);
+                        amendPaths.add(ex);
+                    }
+                    info(`  Removed ${c.bold(rel)} from the repo + added it to .gitignore${keys.length ? ' (kept a *.example)' : ''}.`);
+                    amendPaths.add('.gitignore');
+                }
+                else if (ans === 'r') {
+                    // plain remove of an embedded literal: redact each finding line
+                    for (const f of [...fs].sort((a, b) => b.line - a.line)) {
+                        const line = readLineFromFile(abs, f.line);
+                        const guessed = line ? extractAssignment(line) : {};
+                        if (guessed.value) {
+                            const r2 = redactLiteralInTree(abs, f.line, guessed.value);
+                            if (r2)
+                                console.log(c.dim(`  :${f.line}  ${truncate(r2.before.trim(), 40)}  →  ${truncate(r2.after.trim(), 40)}`));
+                        }
+                        else
+                            warn(`  couldn’t auto-locate the literal on :${f.line} — edit it by hand, then re-run.`);
+                    }
+                    amendPaths.add(rel);
+                }
+                else {
+                    amendPaths.add(rel); // m already redacted above
+                }
+                if (tipOnly)
+                    resolvedInTree.add(rel);
+                continue;
+            }
+            // Unrecognised answer → treat as hold (safe: nothing is pushed).
+            held = true;
+            heldFiles.add(rel);
+            info(`Holding ${c.bold(rel)} — no action chosen.`);
+        }
+        // 1) Fold tree removals/moves into the tip commit (a NEW commit wouldn't purge
+        //    the secret from HEAD, which is still in the pushed range — so we amend).
+        if (amendPaths.size > 0) {
+            const add = gitCapture(root, ['add', '-A', '--', ...amendPaths]);
+            if (add.status !== 0) {
+                process.stderr.write(add.stderr);
+                throw new Error('git add failed while removing secrets');
+            }
+            const amend = gitCapture(root, ['commit', '--amend', '--no-edit']);
+            if (amend.status !== 0) {
+                process.stderr.write(amend.stdout + amend.stderr);
+                throw new Error('git commit --amend failed while removing secrets');
+            }
+            ok(`Rewrote the tip commit to drop ${amendPaths.size} path${amendPaths.size === 1 ? '' : 's'}.`);
+            if (movedCount > 0) {
+                console.log('');
+                warn(`${movedCount} value${movedCount === 1 ? '' : 's'} now live in TillSecrets. Rotate anything that was ever committed — the old value must be treated as compromised.`);
+                info(c.dim(`  Pull them at deploy: \`tilldev secrets ls --env <id>\`, and wire your app to read them (env injection / secrets pull).`));
+            }
+        }
+        // 2) Persist allowlist decisions as one audited commit (marker is tip-resolved).
+        if (toMark.length > 0) {
+            for (const m of toMark)
+                insertFileMarker(join(root, m.path), fileMarkerFor(m.path, m.reason));
+            const add = gitCapture(root, ['add', ...toMark.map((m) => m.path)]);
+            if (add.status !== 0) {
+                process.stderr.write(add.stderr);
+                throw new Error('git add failed while committing allowlist markers');
+            }
+            const body = toMark.map((m) => `- ${m.path}: ${m.reason}`).join('\n');
+            const commit = gitCapture(root, ['commit', '-m', `chore(forge): allowlist reviewed secret findings\n\n${body}\n\nAudited via tillforge:allow-file-secrets; each finding is still recorded at the push boundary.`]);
+            if (commit.status !== 0) {
+                process.stderr.write(commit.stdout + commit.stderr);
+                throw new Error('git commit failed while committing allowlist markers');
+            }
+            ok(`Committed allowlist marker${toMark.length === 1 ? '' : 's'} for ${toMark.length} file${toMark.length === 1 ? '' : 's'}.`);
+        }
+        // 3) History rewrite (purge across ALL commits) — the last resort for a secret
+        //    already deep in history. Guard-railed: backup ref, typed confirm, rotate.
+        if (rewriteFiles.length > 0) {
+            const done = await runHistoryRewrite(root, remote, rewriteFiles, byFile);
+            if (!done) {
+                held = true;
+                rewriteFiles.forEach((f) => heldFiles.add(f));
+            }
+            else {
+                forceNext = true;
+                ok('History rewritten — re-pushing with a lease-guarded force…');
+                continue;
+            }
+        }
+        // 4) Exclude: push only the commits before the first one that introduces a
+        //    still-blocking secret, holding the rest locally. "Still-blocking" = every
+        //    offending file we did NOT allowlist or resolve in the tree this round.
+        if (excludeRequested) {
+            const stillBlocking = [...byFile.keys()].filter((p) => !amendPaths.has(p) && !toMark.some((m) => m.path === p));
+            await runPartialPush(root, remote, branch, stillBlocking.length ? stillBlocking : [...byFile.keys()], env);
+            exit(2);
+        }
+        if (held) {
+            console.log('');
+            info('Some findings were held — nothing was pushed. Re-run `tilldev forge push` once they’re resolved.');
+            exit(2);
+        }
+        if (toMark.length === 0 && amendPaths.size === 0) {
+            fail('No resolution chosen; nothing was pushed.');
+            exit(2);
+        }
+        ok('Re-pushing…');
+    }
+    fail('Still blocked after several rounds — resolve the remaining findings manually and push again.');
+    exit(1);
+}
+// Purge secrets from ALL history using git-filter-repo. Whole credential files are
+// removed (--invert-paths); a secret embedded in a source file is redacted in place
+// (--replace-text) so the file itself survives — deleting a source file to scrub one
+// literal would be a nasty surprise. Returns true when history was rewritten.
+// Heavily guarded: it's destructive and rewrites every commit SHA.
+async function runHistoryRewrite(root, remote, files, byFile) {
+    console.log('');
+    if (!filterRepoAvailable(root)) {
+        warn('History rewrite needs `git-filter-repo`, which isn’t installed.');
+        info('  Install it, then re-run — it’s the safe, supported tool for this:');
+        console.log(c.dim('    brew install git-filter-repo    # macOS'));
+        console.log(c.dim('    pipx install git-filter-repo    # or: pip install git-filter-repo'));
+        return false;
+    }
+    const deleteFiles = files.filter((f) => looksLikeSecretFile(f));
+    const redactFiles = files.filter((f) => !looksLikeSecretFile(f));
+    // For source files we must know the exact literal(s) to purge — auto-locating a
+    // secret across historical blob versions isn't reliable, so we ask (seeded from
+    // the working tree). The user knows their secret; this keeps us honest.
+    const literals = [];
+    for (const f of redactFiles) {
+        const abs = join(root, f);
+        for (const fnd of byFile.get(f) ?? []) {
+            const line = readLineFromFile(abs, fnd.line);
+            const guess = line ? extractAssignment(line).value : undefined;
+            const entered = (await promptInput(`  Exact secret to purge from ${f}:${fnd.line}${guess ? ` [${truncate(guess, 20)}]` : ''} (blank to skip) > `, { hidden: Boolean(guess) })).trim();
+            const lit = entered || guess;
+            if (lit && lit.length >= 4 && !literals.includes(lit))
+                literals.push(lit);
+        }
+    }
+    if (!deleteFiles.length && !literals.length) {
+        warn('Nothing to purge (no files to remove and no literals given).');
+        return false;
+    }
+    console.log(`${c.bold('History rewrite')} across ${c.bold('every')} commit:`);
+    for (const f of deleteFiles)
+        console.log(`  remove file  ${c.yellow(f)} ${c.dim('(' + commitsTouching(root, 'HEAD', f).length + ' commit(s))')}`);
+    if (literals.length)
+        console.log(`  redact       ${c.yellow(String(literals.length) + ' literal value(s)')} ${c.dim('across ' + redactFiles.join(', '))}`);
+    warn('This rewrites every commit SHA after the first change, needs a force-push, and CANNOT be undone remotely once pushed.');
+    warn('Any secret that was ever committed is COMPROMISED — rotate it regardless of the rewrite.');
+    const confirm = (await promptInput(`  Type ${c.bold('rewrite')} to proceed (anything else cancels) > `)).trim();
+    if (confirm !== 'rewrite') {
+        info('Cancelled the rewrite — nothing changed.');
+        return false;
+    }
+    // Recovery point: a ref at the current tip so the pre-rewrite history is reachable.
+    const head = gitCapture(root, ['rev-parse', 'HEAD']).stdout.trim();
+    gitCapture(root, ['update-ref', 'refs/tilldev/pre-rewrite', head]);
+    // filter-repo drops the remote to prevent accidental pushes — capture + restore it.
+    const remoteUrl = gitCapture(root, ['remote', 'get-url', remote]).stdout.trim();
+    // Redact literals first (a replace-text file kept inside .git, then unlinked).
+    if (literals.length) {
+        const exprPath = join(root, '.git', 'tilldev-replace-text.txt');
+        writeFileSync(exprPath, literals.map((l) => `${l}==>***REMOVED-SECRET***`).join('\n') + '\n');
+        const rw = gitCapture(root, ['filter-repo', '--force', '--replace-text', exprPath]);
+        try {
+            unlinkSync(exprPath);
+        }
+        catch { /* best effort */ }
+        if (rw.status !== 0) {
+            process.stderr.write(rw.stdout + rw.stderr);
+            warn('filter-repo (redact) failed — history is unchanged.');
+            return false;
+        }
+    }
+    // Then remove whole credential files.
+    if (deleteFiles.length) {
+        const args = ['filter-repo', '--force', '--invert-paths'];
+        for (const f of deleteFiles) {
+            args.push('--path', f);
+        }
+        const rw = gitCapture(root, args);
+        if (rw.status !== 0) {
+            process.stderr.write(rw.stdout + rw.stderr);
+            warn('filter-repo (remove) failed — history is partially rewritten; check `git log`.');
+            return false;
+        }
+    }
+    // Restore the remote filter-repo stripped.
+    if (remoteUrl && gitCapture(root, ['remote', 'get-url', remote]).status !== 0) {
+        gitCapture(root, ['remote', 'add', remote, remoteUrl]);
+    }
+    ok('History rewritten.');
+    info(c.dim(`  Recovery: the pre-rewrite tip is kept at refs/tilldev/pre-rewrite (git update-ref -d refs/tilldev/pre-rewrite to drop it).`));
+    return true;
+}
+// Push only up to the parent of the earliest unpushed commit that touches any
+// still-blocking file, leaving those commits (and the secret) local. Lets the rest
+// of the work land now without a rewrite. Terminal for this invocation.
+async function runPartialPush(root, remote, branch, files, env) {
+    const range = unpushedRange(root, remote, branch).range;
+    // Oldest unpushed commit that touches any offending file.
+    const r = gitCapture(root, ['log', '--format=%H', '--reverse', range, '--', ...files]);
+    const earliest = r.stdout.split('\n').map((s) => s.trim()).filter(Boolean)[0];
+    console.log('');
+    if (!earliest) {
+        warn('Couldn’t find the offending commit range — resolve manually.');
+        return;
+    }
+    const parent = gitCapture(root, ['rev-parse', '--verify', '--quiet', earliest + '^']);
+    if (parent.status !== 0) {
+        warn('The secret is in the very first commit — there’s nothing before it to push. Use [w] purge history instead.');
+        return;
+    }
+    const safe = parent.stdout.trim();
+    const behind = gitCapture(root, ['rev-list', '--count', `${safe}..HEAD`]).stdout.trim();
+    info(`Pushing up to ${c.bold(safe.slice(0, 10))} — holding the ${c.bold(behind)} later commit(s) that carry the secret.`);
+    const push = gitCapture(root, ['-c', 'credential.helper=', '-c', `credential.helper=${credentialHelperArg()}`, 'push', remote, `${safe}:refs/heads/${branch}`], env);
+    process.stderr.write(push.stderr.split('\n').filter((l) => l.startsWith('remote:')).join('\n') + (push.stderr ? '\n' : ''));
+    if (push.status === 0) {
+        ok(`Pushed ${c.bold(safe.slice(0, 10))} to ${branch}. Your held commits stay local until you remove/rewrite the secret, then \`tilldev forge push\` again.`);
+    }
+    else {
+        process.stderr.write(push.stderr);
+        fail('Partial push failed.');
+    }
+}
 async function cmdForge(flags) {
     const sub = flags.positional[1] ?? 'repos';
     // Git-ergonomics commands shell out to git rather than the API, and the
@@ -2310,6 +3326,8 @@ async function cmdForge(flags) {
         return cmdForgeCredential(flags);
     if (sub === 'clone')
         return cmdForgeClone(flags);
+    if (sub === 'push')
+        return cmdForgePush(flags);
     if (sub === 'setup-git')
         return cmdForgeSetupGit(flags);
     if (sub === 'login')
@@ -2561,12 +3579,34 @@ async function cmdForge(flags) {
             const action = flags.positional[2] ?? 'ls';
             const repo = need(flags.positional[3], `tilldev forge env ${action} <repo> …`);
             if (action === 'set') {
-                const r = await api.forgeSetEnvironment(opts, repo, {
+                const body = {
                     name: need(flags.named['name'], '--name is required'),
                     production: flags.bool.has('production'),
                     url: flags.named['url'],
                     required_approvals: flags.named['approvals'] ? Number(flags.named['approvals']) : undefined,
-                });
+                };
+                // Deploy target: --provider '' clears it; --credential links a vault entry;
+                // --target 'project=my-site'; build recipe via --root/--install/--build/
+                // --output/--image; --auto-deploy <branch> and --auto-preview.
+                if (flags.named['provider'] !== undefined)
+                    body['provider'] = flags.named['provider'] || null;
+                if (flags.named['credential'])
+                    body['provider_id'] = flags.named['credential'];
+                const target = parseKv(flags.named['target']);
+                if (target)
+                    body['target_config'] = target;
+                const build = {};
+                for (const [flag, key] of [['root', 'root_dir'], ['install', 'install'], ['build', 'build'], ['output', 'output_dir'], ['image', 'image']]) {
+                    if (flags.named[flag] !== undefined)
+                        build[key] = flags.named[flag];
+                }
+                if (Object.keys(build).length)
+                    body['build_config'] = build;
+                if (flags.named['auto-deploy'] !== undefined)
+                    body['auto_deploy_ref'] = flags.named['auto-deploy'] || null;
+                if (flags.bool.has('auto-preview'))
+                    body['auto_preview'] = true;
+                const r = await api.forgeSetEnvironment(opts, repo, body);
                 render(flags, r, () => ok(`environment ${r.environment.name} set`));
                 return;
             }
@@ -2575,6 +3615,7 @@ async function cmdForge(flags) {
                 const cols = [
                     { header: 'NAME', get: (e) => c.bold(e.name) },
                     { header: 'KIND', get: (e) => (e.production ? c.magenta('production') : c.dim('preview')) },
+                    { header: 'PROVIDER', get: (e) => (e.provider ? c.cyan(e.provider) : c.dim('tracking')) },
                     { header: 'URL', get: (e) => e.url || c.dim('-') },
                     { header: 'APPROVALS', get: (e) => String(e.required_approvals) },
                 ];
@@ -2582,6 +3623,37 @@ async function cmdForge(flags) {
             });
             return;
         }
+        case 'provider':
+        case 'providers': {
+            const action = flags.positional[2] ?? 'ls';
+            if (action === 'connect') {
+                const provider = need(flags.named['provider'], '--provider is required (cloudflare|vercel|netlify|supabase|aws|firebase|surge|azure_swa|railway|fly|desktop)');
+                const name = need(flags.named['name'], '--name is required');
+                const credential = parseKv(flags.named['credential']) ?? {};
+                const r = await api.forgeConnectProvider(opts, { name, provider, credential });
+                render(flags, r, () => ok(`connected ${r.provider.provider} credential '${r.provider.name}'`));
+                return;
+            }
+            if (action === 'rm' || action === 'revoke') {
+                const id = need(flags.positional[3], 'tilldev forge provider rm <id>');
+                await api.forgeRevokeProvider(opts, id);
+                render(flags, { ok: true }, () => ok('provider credential revoked'));
+                return;
+            }
+            const r = await api.forgeDeployProviders(opts);
+            render(flags, r, () => {
+                const cols = [
+                    { header: 'NAME', get: (p) => c.bold(p.name) },
+                    { header: 'PROVIDER', get: (p) => c.cyan(p.provider) },
+                    { header: 'HINT', get: (p) => p.hint || c.dim('-') },
+                    { header: 'STATE', get: (p) => (p.revoked_at ? c.red('revoked') : c.green('active')) },
+                ];
+                console.log(table(r.providers, cols));
+                if (!r.providers.length)
+                    console.log(c.dim(`no providers connected — supported: ${r.catalog.map((s) => s.provider).join(', ')}`));
+            });
+            return;
+        }
         case 'deploy':
         case 'deployments': {
             const action = flags.positional[2] ?? 'ls';
@@ -2597,6 +3669,40 @@ async function cmdForge(flags) {
                 render(flags, r, () => ok(`deployment ${r.deployment.state}`));
                 return;
             }
+            if (action === 'promote') {
+                const id = need(flags.positional[4], 'tilldev forge deploy promote <repo> <id> --env <e>');
+                const r = await api.forgePromoteDeployment(opts, repo, id, need(flags.named['env'], '--env is required'));
+                render(flags, r, () => ok(`promoted to ${r.deployment.environment} — ${r.deployment.state}`));
+                return;
+            }
+            if (action === 'rollback') {
+                const id = need(flags.positional[4], 'tilldev forge deploy rollback <repo> <id>');
+                const r = await api.forgeRollbackDeployment(opts, repo, id);
+                render(flags, r, () => ok(`rolling back ${r.deployment.environment} — ${r.deployment.state}`));
+                return;
+            }
+            if (action === 'cancel') {
+                const id = need(flags.positional[4], 'tilldev forge deploy cancel <repo> <id>');
+                const r = await api.forgeCancelDeployment(opts, repo, id);
+                render(flags, r, () => ok(`deployment ${r.deployment.state}`));
+                return;
+            }
+            if (action === 'logs') {
+                const id = need(flags.positional[4], 'tilldev forge deploy logs <repo> <id>');
+                const r = await api.forgeDeployLogs(opts, repo, id);
+                render(flags, r, () => {
+                    if (!r.job) {
+                        console.log(c.dim(`no build job (deployment state: ${r.state})`));
+                        return;
+                    }
+                    console.log(c.dim(`state: ${r.state} · job: ${r.job.status}${r.job.log_truncated ? ' · log truncated (1 MiB cap)' : ''}`));
+                    if (r.job.log)
+                        console.log(r.job.log);
+                    if (r.job.failure_reason)
+                        console.log(c.red(r.job.failure_reason));
+                });
+                return;
+            }
             const r = await api.forgeDeployments(opts, repo, flags.named['env']);
             render(flags, r, () => {
                 const cols = [
@@ -2704,7 +3810,7 @@ async function cmdForge(flags) {
             return;
         }
         default:
-            throw new Error('usage: tilldev forge <clone|setup-git|repos|tree|blob|log|refs|blame|search|policy|reflog|recover|findings|allowlist|pr|compare|issue|label|collab|checks|check|ci|correlation|env|deploy|release|asset|webhook|tokens|keys|keys-account|audit>');
+            throw new Error('usage: tilldev forge <clone|push|setup-git|repos|tree|blob|log|refs|blame|search|policy|reflog|recover|findings|allowlist|pr|compare|issue|label|collab|checks|check|ci|correlation|env|deploy|release|asset|webhook|tokens|keys|keys-account|audit>');
     }
 }
 async function cmdForgeRepos(flags, opts) {
@@ -3310,14 +4416,17 @@ async function main() {
     const argv = process.argv.slice(2);
     const flags = parseArgs(argv);
     const cmd = flags.positional[0];
-    if (!cmd || flags.bool.has('help')) {
-        console.log(HELP);
-        return;
-    }
+    // Version check first: a bare `--version` / `-v` carries no positional
+    // command, so it must win before the `!cmd` help fallback below (otherwise
+    // `tilldev --version` prints the whole help screen instead of the version).
     if (cmd === 'version' || flags.bool.has('version')) {
         console.log(VERSION);
         return;
     }
+    if (!cmd || flags.bool.has('help')) {
+        console.log(HELP);
+        return;
+    }
     switch (cmd) {
         case 'help':
             console.log(HELP);
@@ -3452,7 +4561,12 @@ async function cmdStacks(flags) {
             throw new Error('usage: tilldev stacks <ls|show|create|enable|disable|attach|detach|rm>');
     }
 }
-main().catch((err) => {
+main()
+    // On success, surface an "a newer CLI is on npm" notice (best-effort, stderr,
+    // after the command's own output). notifyUpdate never rejects, so it can't
+    // turn a successful command into a failure.
+    .then(() => notifyUpdate(VERSION))
+    .catch((err) => {
     if (err instanceof ApiError) {
         fail(err.message);
         if (err.status === 401)