link: two-step workspace picker + cross-workspace --app-id

[netanelgilad]

Note

Description

Reworks the existing-app selection in base44 link to be workspace-aware. Interactive linking becomes a two-step flow — pick a workspace (skipped when you belong to only one), then pick an app scoped to that workspace — instead of listing only apps in your personal/active workspace. --app-id is now validated directly via getApp rather than being looked up in the app list, so it links any app you can access, including apps in other workspaces. The server remains the source of truth for permissions; the CLI never filters or validates by role.

Related Issue

Builds on #577 (fix(link): list editor-created apps for linking), which landed on main while this PR was open — editor-created (managed-source) apps stay linkable here. No issue is closed by this PR.

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

• link.ts — extracted the choose branch into two helpers:
  • resolveExplicitAppId() validates --app-id by fetching the app directly (getApp), making cross-workspace apps linkable; 404/403 surface an InvalidInputError with hints ("Check the app ID is correct", "Run base44 link without --app-id to browse apps by workspace").
  • chooseProjectInteractively() resolves the target workspace via resolveWorkspaceId(), then fetches and prompts for an app scoped to that workspace; returns undefined when the workspace has no apps (falls through to the existing "No projects available for linking" outro).
• workspace-select.ts — resolveWorkspaceId() takes an optional { promptMessage } so link can ask "Which workspace is the app in?" instead of the create-oriented wording; the local options variable was renamed to promptOptions to avoid shadowing. Doc comment updated to cover both the create and link cases.
• core/project/api.ts — listProjects() accepts an optional { workspaceId } and forwards it as the workspace_id search param on GET /api/apps; omitted means the server scopes to the caller's active/personal workspace.
• --workspace/-w help text — now documents that the flag also scopes the app picker, not just app creation.
• Tests — added TestAPIServer.mockGetApp() (routes on the response's own id, so tests can mock apps other than the context app); link.spec.ts switched from mockListProjects to mockGetApp for the --app-id / legacy --project-id / --projectId cases, plus new coverage for linking an app in another workspace and for the not-found (404) error path.

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

• Backwards compatible: legacy --project-id / --projectId aliases and the --org alias for --workspace still work, and non-interactive runs are unaffected (resolveWorkspaceId returns undefined, so the server applies its default).
• Behavioral note vs. the pre-rebase version of this PR: the managed-source filter and the --app-id managed-source rejection were dropped to honor fix(link): list editor-created apps for linking #577, so editor-created apps remain linkable. main's editor-created-app test is kept, adapted to mockGetApp.
• No docs/ updates: this is a behavior change inside an existing command rather than an architectural one; command help text was updated in place.
• The test-run boxes are left unchecked because the suite was not executed in this analysis environment — only the diff was reviewed.

---

_{🤖 Generated by Claude | 2026-08-02 09:37 UTC | c08ba20}

[github-actions]

🚀 Package Preview Available!

---

Install this PR's preview build with npm:

npm i @base44-preview/cli@0.1.7-pr.568.c08ba20

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.1.7-pr.568.c08ba20"

Or add it to your package.json dependencies:

{
  "dependencies": {
    "base44": "npm:@base44-preview/cli@0.1.7-pr.568.c08ba20"
  }
}

• 📦 Preview Package: @base44-preview/cli@0.1.7-pr.568.c08ba20
• 🔗 View this commit on GitHub

---

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