feat(logs): add --tail flag for real-time log streaming

[yoavf]

Note

Description

Adds a --tail flag (-f) to the logs command that streams real-time function logs via Server-Sent Events (SSE). The new streamFunctionLogs async generator in the core layer connects to a streaming endpoint, parses SSE data: lines into typed log entries, and handles heartbeat comments and graceful SIGINT shutdown. Multiple functions can be tailed concurrently using Promise.allSettled.

Related Issue

None

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Other (please describe):

Changes Made

• packages/cli/src/cli/commands/project/logs.ts — Added --tail / -f option to the logs command; added tailAction() that builds an AbortController, streams one or more functions concurrently, and prints entries (plain or --json) to stdout; validates that --tail is mutually exclusive with --since, --until, --limit, and --order; updated command description
• packages/cli/src/core/resources/function/api.ts — Added streamFunctionLogs async generator that calls getAppClient().get() with timeout: false, reads the ReadableStream body incrementally, and yields validated FunctionLogEntry objects parsed from SSE data: lines; skips heartbeat comments (: lines) and malformed JSON silently
• packages/cli/src/core/resources/function/schema.ts — Exported FunctionLogEntrySchema and FunctionLogEntry type; added StreamLogFilters interface with optional level filter
• packages/cli/tests/cli/logs.spec.ts — Added 9 new integration tests covering incompatible-flag validation, single/multi-function streaming, --json output, error propagation, stream-ended message, and SSE heartbeat filtering
• packages/cli/tests/cli/testkit/TestAPIServer.ts — Added mockFunctionLogsStream() and mockFunctionLogsStreamError() helpers for SSE stream test routes
• packages/cli/tests/core/stream-function-logs.spec.ts — New unit test file covering SSE parsing, heartbeat skipping, malformed-JSON resilience, null-body error, and level filter query param

Testing

• I have tested these changes locally
• I have added/updated tests as needed
• All tests pass (npm test)

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (if applicable)
• My changes generate no new warnings
• I have updated docs/ (AGENTS.md) if I made architectural changes

Additional Notes

The streamFunctionLogs function deliberately avoids response.json() / response.text() (which buffer the full body) and instead reads from response.body incrementally as a ReadableStream. This is noted in an inline comment to prevent future regressions. The --tail flag intentionally mirrors the familiar tail -f / docker logs -f UX pattern.

---

_{🤖 Generated by Claude | 2026-03-17 00:00 UTC}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.0.45-pr.424.8513daf

Prefer not to change any import paths? Install using npm alias so your code still imports base44:

npm i "base44@npm:@base44-preview/cli@0.0.45-pr.424.8513daf"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.0.45-pr.424.8513daf"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.0.45-pr.424.8513daf
• 🔗 View this commit on GitHub

---

_{Preview published to npm registry — try new features instantly!}