@pugi/cli 0.1.0-alpha.17 → 0.1.0-alpha.19

package/README.md

@@ -94,12 +94,45 @@ pugi review --triple --remote
 pugi handoff --web         # hand the session off to the cabinet
 pugi sessions              # list sessions from .pugi/index.json
 pugi sessions --rebuild    # rebuild the index from events.jsonl
+pugi deploy --target vercel my-vercel-project --project proj_42
+                           # trigger a Vercel deploy from the bound Git source
+pugi deploy --status dep_42   # vendor-agnostic status snapshot
+pugi deploy --logs dep_42 --tail
+                           # build-log tail; --tail polls until terminal
 pugi doctor --json         # environment diagnostic
 pugi version               # CLI version
 ```
 
 Run `pugi --help` for the full list.
 
+### Deploy
+
+`pugi deploy` triggers a deployment for the project bound to your Vercel or
+Render integration. Source is resolved from the existing `ProjectGitBinding`
+row on the admin-api side — the CLI never reads local files.
+
+```bash
+# Vercel — production (default)
+pugi deploy --target vercel my-vercel-project --project proj_42
+
+# Vercel — preview from a feature branch
+pugi deploy --target vercel my-vercel-project --project proj_42 \
+  --target-env preview --ref feat/landing-tweaks
+
+# Render (Sprint 2 — endpoint returns 501 today)
+pugi deploy --target render my-render-svc --project proj_42
+
+# Query existing deploys
+pugi deploy --status dep_42
+pugi deploy --logs dep_42 --tail
+```
+
+Exit codes:
+
+- `0` success (queued, ready, building)
+- `1` failed (status=error, refused, not authenticated)
+- `2` transient (rate-limited, runtime down, retry-safe)
+
 ## Privacy
 
 Pugi defaults to `local-only` — no upload happens without an explicit flag.

package/dist/commands/deploy.js

@@ -0,0 +1,439 @@
+/**
+ * `pugi deploy` command surface — Wave 3 P2 (Task #34, 2026-05-25).
+ *
+ * Subcommands:
+ *   pugi deploy --target vercel <vercelProject> [--project <id>] [--ref <ref>] [--target-env production|preview] [--integration <id>]
+ *   pugi deploy --target render <renderService> [--project <id>] [--ref <ref>]
+ *   pugi deploy --status <deployment-id>
+ *   pugi deploy --logs <deployment-id> [--tail]
+ *
+ * Exit codes (per task spec):
+ *   0   success (trigger queued, status terminal=ready, logs printed)
+ *   1   deployment failed (status=error or trigger refused)
+ *   2   transient (rate-limited, runtime down, retry-safe)
+ *
+ * Project resolution:
+ *   `--project <id>` is required for trigger commands because the CLI's
+ *   credential store is tenant-scoped but not project-scoped. A future
+ *   sprint (Wave 4) auto-detects the project from `.pugi/settings.json`
+ *   bound to the workspace; until then the operator passes it explicitly.
+ *
+ * Local-first invariant (ADR-0037):
+ *   `pugi deploy` does NOT read repository files. The Vercel deploy
+ *   resolves source from the existing ProjectGitBinding row on the
+ *   admin-api side — the CLI is only a request initiator + status poller.
+ */
+import { fetchDeployStatus, fetchDeployLogs, submitDeployTrigger, } from '@pugi/sdk';
+/**
+ * Parse `pugi deploy ...` flags + positionals into a structured shape.
+ * Exported so tests can exercise the parser in isolation.
+ */
+export function parseDeployArgs(args) {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? '';
+        if (arg === '--json') {
+            flags.json = true;
+        }
+        else if (arg === '--target') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--target requires a value (vercel|render)' };
+            if (next !== 'vercel' && next !== 'render') {
+                return { flags, positional, error: `--target must be vercel or render, got "${next}"` };
+            }
+            flags.target = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--target=')) {
+            const value = arg.slice('--target='.length);
+            if (value !== 'vercel' && value !== 'render') {
+                return { flags, positional, error: `--target must be vercel or render, got "${value}"` };
+            }
+            flags.target = value;
+        }
+        else if (arg === '--project') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--project requires a value' };
+            flags.project = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--project=')) {
+            flags.project = arg.slice('--project='.length);
+        }
+        else if (arg === '--ref') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--ref requires a value' };
+            flags.ref = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--ref=')) {
+            flags.ref = arg.slice('--ref='.length);
+        }
+        else if (arg === '--target-env') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--target-env requires a value' };
+            if (next !== 'production' && next !== 'preview') {
+                return {
+                    flags,
+                    positional,
+                    error: `--target-env must be production or preview, got "${next}"`,
+                };
+            }
+            flags.targetEnv = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--target-env=')) {
+            const value = arg.slice('--target-env='.length);
+            if (value !== 'production' && value !== 'preview') {
+                return {
+                    flags,
+                    positional,
+                    error: `--target-env must be production or preview, got "${value}"`,
+                };
+            }
+            flags.targetEnv = value;
+        }
+        else if (arg === '--integration') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--integration requires a value' };
+            flags.integration = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--integration=')) {
+            flags.integration = arg.slice('--integration='.length);
+        }
+        else if (arg === '--status') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--status requires a deployment id' };
+            flags.status = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--status=')) {
+            flags.status = arg.slice('--status='.length);
+        }
+        else if (arg === '--logs') {
+            const next = args[i + 1];
+            if (!next)
+                return { flags, positional, error: '--logs requires a deployment id' };
+            flags.logs = next;
+            i += 1;
+        }
+        else if (arg.startsWith('--logs=')) {
+            flags.logs = arg.slice('--logs='.length);
+        }
+        else if (arg === '--tail') {
+            flags.tail = true;
+        }
+        else if (arg.startsWith('--')) {
+            return { flags, positional, error: `unknown flag: ${arg}` };
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { flags, positional };
+}
+export function usage() {
+    return [
+        'Usage:',
+        '  pugi deploy --target vercel <vercelProject> --project <id> [--target-env production|preview] [--ref <git-ref>] [--integration <id>]',
+        '  pugi deploy --target render <renderService> --project <id> [--ref <git-ref>]',
+        '  pugi deploy --status <deployment-id>',
+        '  pugi deploy --logs <deployment-id> [--tail]',
+        '',
+        'Flags:',
+        '  --target vercel|render    Provider to deploy to.',
+        '  --project <id>            Pugi project id (required for trigger).',
+        '  --ref <git-ref>           Optional Git ref. Defaults to the binding default branch.',
+        '  --target-env production|preview',
+        '                            Vercel deploy environment. Defaults to production.',
+        '  --integration <id>        Disambiguate when multiple integrations are active.',
+        '  --status <id>             Show the current status for a deployment.',
+        '  --logs <id> [--tail]      Fetch log tail. With --tail, polls until terminal.',
+        '  --json                    Emit machine-readable JSON envelopes.',
+        '',
+        'Exit codes:',
+        '  0  success',
+        '  1  deployment failed / refused',
+        '  2  transient (rate-limited, runtime down, retry-safe)',
+    ].join('\n');
+}
+/**
+ * Main entry point. Returns the exit code; the CLI shim sets
+ * `process.exitCode = result` so tests can drive this without a child
+ * process and the REPL can poll the value.
+ */
+export async function runDeployCommand(args, io, deps) {
+    const parsed = parseDeployArgs(args);
+    if (parsed.error) {
+        if (parsed.flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy', ok: false, error: parsed.error }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(parsed.error);
+            io.writeError(usage());
+        }
+        return 2;
+    }
+    const { flags, positional } = parsed;
+    // Branch 1: --status <id>
+    if (flags.status) {
+        return runStatus(flags.status, flags, io, deps);
+    }
+    // Branch 2: --logs <id>
+    if (flags.logs) {
+        return runLogs(flags.logs, flags, io, deps);
+    }
+    // Branch 3: trigger via --target <vercel|render>
+    if (!flags.target) {
+        if (flags.json) {
+            io.write(`${JSON.stringify({
+                command: 'deploy',
+                ok: false,
+                error: 'No --target specified. Use --target vercel|render, or --status / --logs to query existing deploys.',
+            }, null, 2)}\n`);
+        }
+        else {
+            io.writeError('No --target specified. Use --target vercel|render, or --status / --logs to query existing deploys.');
+            io.writeError(usage());
+        }
+        return 2;
+    }
+    const projectKey = positional[0];
+    if (!projectKey) {
+        const msg = flags.target === 'vercel'
+            ? 'pugi deploy --target vercel requires a Vercel project name as the positional argument'
+            : 'pugi deploy --target render requires a Render service name as the positional argument';
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy', ok: false, error: msg }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(msg);
+            io.writeError(usage());
+        }
+        return 2;
+    }
+    if (!flags.project) {
+        const msg = 'pugi deploy trigger requires --project <pugi-project-id>';
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy', ok: false, error: msg }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(msg);
+            io.writeError(usage());
+        }
+        return 2;
+    }
+    const config = deps.resolveConfig();
+    if (!config) {
+        const msg = 'Not authenticated. Run `pugi login` first.';
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy', ok: false, error: msg }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(msg);
+        }
+        return 1;
+    }
+    let result;
+    if (flags.target === 'vercel') {
+        result = await submitDeployTrigger(config, 'vercel', {
+            schema: 1,
+            projectId: flags.project,
+            vercelProject: projectKey,
+            ...(flags.integration ? { integrationId: flags.integration } : {}),
+            ...(flags.targetEnv ? { target: flags.targetEnv } : {}),
+            ...(flags.ref ? { ref: flags.ref } : {}),
+        });
+    }
+    else {
+        result = await submitDeployTrigger(config, 'render', {
+            schema: 1,
+            projectId: flags.project,
+            renderService: projectKey,
+            ...(flags.ref ? { ref: flags.ref } : {}),
+        });
+    }
+    return emitTriggerResult(result, flags, io);
+}
+function emitTriggerResult(result, flags, io) {
+    if (result.status === 'ok') {
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy.trigger', ok: true, deployment: result.response }, null, 2)}\n`);
+        }
+        else {
+            io.write(renderStatusTable(result.response, 'queued'));
+        }
+        return 0;
+    }
+    return emitDeployFailure('deploy.trigger', result, flags, io);
+}
+async function runStatus(deploymentId, flags, io, deps) {
+    const config = deps.resolveConfig();
+    if (!config) {
+        const msg = 'Not authenticated. Run `pugi login` first.';
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy.status', ok: false, error: msg }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(msg);
+        }
+        return 1;
+    }
+    const result = await fetchDeployStatus(config, deploymentId);
+    if (result.status === 'ok') {
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy.status', ok: true, deployment: result.response }, null, 2)}\n`);
+        }
+        else {
+            io.write(renderStatusTable(result.response, 'current'));
+        }
+        return statusToExitCode(result.response.status);
+    }
+    return emitDeployFailure('deploy.status', result, flags, io);
+}
+async function runLogs(deploymentId, flags, io, deps) {
+    const config = deps.resolveConfig();
+    if (!config) {
+        const msg = 'Not authenticated. Run `pugi login` first.';
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy.logs', ok: false, error: msg }, null, 2)}\n`);
+        }
+        else {
+            io.writeError(msg);
+        }
+        return 1;
+    }
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let lastTerminal = false;
+    let lastStatus = 'queued';
+    let lastLogs = '';
+    // Single-shot vs --tail. The tail loop is bounded by the 10-minute hard
+    // ceiling so a runaway runtime doesn't keep a CI job pinned forever.
+    const startedAt = Date.now();
+    const maxMs = 10 * 60 * 1000;
+    const pollIntervalMs = 3_000;
+    while (true) {
+        const result = await fetchDeployLogs(config, deploymentId);
+        if (result.status !== 'ok') {
+            return emitDeployFailure('deploy.logs', result, flags, io);
+        }
+        const { response } = result;
+        lastTerminal = response.terminal;
+        lastStatus = response.status;
+        lastLogs = response.logs;
+        if (flags.json) {
+            io.write(`${JSON.stringify({ command: 'deploy.logs', ok: true, snapshot: response }, null, 2)}\n`);
+        }
+        else {
+            io.write(response.logs.endsWith('\n') ? response.logs : `${response.logs}\n`);
+        }
+        if (!flags.tail)
+            break;
+        if (response.terminal)
+            break;
+        if (Date.now() - startedAt > maxMs) {
+            io.writeError(`--tail timed out after ${Math.floor(maxMs / 60_000)} minutes; deployment still ${response.status}. Re-run with --status to confirm.`);
+            return 2;
+        }
+        await sleep(pollIntervalMs);
+    }
+    // Suppress unused-warning safe-guards in single-shot path.
+    void lastTerminal;
+    void lastLogs;
+    return statusToExitCode(lastStatus);
+}
+function emitDeployFailure(command, result, flags, io) {
+    if (result.status === 'ok')
+        return 0;
+    if (flags.json) {
+        io.write(`${JSON.stringify({ command, ok: false, ...result }, null, 2)}\n`);
+    }
+    switch (result.status) {
+        case 'unauthenticated':
+            if (!flags.json) {
+                io.writeError('Runtime rejected credentials. Re-run `pugi login` or refresh your API key.');
+            }
+            return 1;
+        case 'endpoint_missing':
+            if (!flags.json) {
+                io.writeError('Deploy endpoint not deployed on this runtime. Update your runtime or set PUGI_API_URL to a runtime that supports /api/pugi/deploy/*.');
+            }
+            return 2;
+        case 'not_configured':
+            if (!flags.json) {
+                io.writeError('Provider not configured on this runtime. Try `pugi deploy --target vercel` until Render ships in Sprint 2.');
+            }
+            return 2;
+        case 'not_found':
+            if (!flags.json) {
+                io.writeError('Deployment not found for this tenant.');
+            }
+            return 1;
+        case 'rate_limited':
+            if (!flags.json) {
+                const retrySec = Math.max(1, Math.ceil(result.retryAfterMs / 1000));
+                io.writeError(`Runtime rate-limited. Retry in ${retrySec}s. (Vercel Hobby cap is the common cause.)`);
+            }
+            return 2;
+        case 'failed':
+            if (!flags.json) {
+                io.writeError(`Deploy call failed: ${result.message}`);
+            }
+            // Network / 5xx → transient. Schema validation / 4xx → permanent.
+            // We cannot perfectly disambiguate here, so map HTTP < 500 to 1
+            // (caller error, fix and retry) and the rest to 2 (transient).
+            return result.code >= 500 || result.code === 0 ? 2 : 1;
+        default:
+            // Exhaustiveness: TS catches new variants at compile time. Runtime
+            // fall-through keeps the CLI from hanging if a future SDK version
+            // adds a status the CLI doesn't yet know about.
+            if (!flags.json) {
+                io.writeError(`Unknown deploy result.`);
+            }
+            return 2;
+    }
+}
+function statusToExitCode(status) {
+    switch (status) {
+        case 'ready':
+        case 'queued':
+        case 'building':
+            return 0;
+        case 'error':
+            return 1;
+        case 'canceled':
+            return 1;
+        default:
+            return 0;
+    }
+}
+function renderStatusTable(response, context) {
+    const lines = [];
+    lines.push(context === 'queued' ? 'Deployment queued.' : 'Deployment status:');
+    lines.push(`  id:                  ${response.id}`);
+    lines.push(`  provider:            ${response.provider}`);
+    lines.push(`  project:             ${response.projectId}`);
+    lines.push(`  status:              ${response.status}`);
+    if (response.url)
+        lines.push(`  url:                 ${response.url}`);
+    if (response.providerDeploymentId)
+        lines.push(`  providerDeploymentId: ${response.providerDeploymentId}`);
+    lines.push(`  createdAt:           ${response.createdAt}`);
+    lines.push(`  updatedAt:           ${response.updatedAt}`);
+    if (response.error) {
+        lines.push('');
+        lines.push('--- build error tail ---');
+        lines.push(response.error);
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+//# sourceMappingURL=deploy.js.map

package/dist/core/context/index.js

@@ -0,0 +1,21 @@
+/**
+ * Three-tier context model - α6.5 Phase 1 barrel.
+ *
+ * Bundles the four primitives so the REPL bootstrap can import from a
+ * single path:
+ *
+ *   import {
+ *     loadPugiIgnore,
+ *     buildRepoSkeleton,
+ *     renderSkeleton,
+ *     WorkingSet,
+ *     PugiWatcher,
+ *   } from '../context/index.js';
+ *
+ * No new logic lives here - just re-exports.
+ */
+export { BASELINE_IGNORE_PATTERNS, SECRET_IGNORE_PATTERNS, globalPugiIgnorePath, loadPugiIgnore, parsePatternText, readPatternFile, workspaceGitIgnorePath, workspacePugiIgnorePath, } from './pugiignore.js';
+export { COLLAPSE_DIR_ENTRIES, MAX_README_LINES, MAX_SKELETON_BYTES, MAX_TREE_DEPTH, MAX_WALK_NODES, TOP_LANGUAGES, buildRepoSkeleton, detectPackageManager, languageForExtension, readGitBranch, readPackageJson, readReadme, renderSkeleton, topLanguages, } from './repo-skeleton.js';
+export { DEFAULT_WORKING_SET_CAPACITY, WorkingSet, } from './working-set.js';
+export { MAX_WATCHED_PATHS, PugiWatcher, THROTTLE_WINDOW_MS, } from './watcher.js';
+//# sourceMappingURL=index.js.map