0
Fork 0
mirror of https://github.com/mastra-ai/mastra.git synced 2026-11-17 08:44:46 +00:00
mastra/packages/cli
Damien Schneider 3c7c00383d
fix(factory): let the server decide which repository a card's session starts in (#30609)
**─────── TLDR ───────**
> A card's draft now asks the server which repository its session starts
in, so a card from an unlinked repository is refused instead of started
somewhere else.

The draft carried its own copy of the repository rule, and a looser one:
when the card's repository wasn't linked, it fell back to the
environment's first repository and wrote that slug onto the card before
calling `runs/start`, which then accepted it. The fallback came from
main's `useStartFactoryRun`, not from #30481. Now the draft reads
`resolveRunRepository`, the same function `runs/start` checks with,
through a new route, and shows its hint as is.

### Behavior changed

GitHub card from `acme/docs`, only `acme/app` linked
  ├─ **was** — starts in `acme/app`, card rewritten to
`repository: acme/app`
  └─ **now** — the draft says "Repository acme/docs is not
linked to this Factory.", nothing starts, "Open repository settings"
leads to the fix

card whose repository resolves (linked, Linear mapping, or a single
repository)
  ├─ **was** — starts there, after the draft writes
`repository` onto the card
  └─ **now** — starts there, the card is left as it was

the draft when the server can't answer
  └─ **new** — "Could not find this card's repository: …",
sending stays off, also when an earlier lookup had answered; Retry asks
again

the draft after the repository gets linked, or after the card changes
  └─ **new** — asks the server again on reopen, on tab focus,
and when the card changes

GitHub card in a Factory whose repositories are all on GitLab, or the
reverse
  ├─ **was** — the draft refused it; dispatch and `runs/start`
ran it in the Factory's repository
  └─ **now** — refused everywhere, even when a repository
there has the same name: "This card comes from GitHub, and no GitHub
repository is linked to this Factory."

card naming no repository among several
  └─ **unchanged** — starts in the environment's first one,
the agent picks

### Shape changed

new route the draft reads before the first prompt
    `GET
/web/factory/projects/:id/work-items/:workItemId/session-repository` ·
`{ status: 'resolved', projectRepositoryId, slug }` · `{ status:
'unlinked', hint }`
    CLI: `mastra api factory work-item
session-repository <project-id> <work-item-id>`

one place every run reads its repository from: the draft route, rule
dispatch, `runs/start` and `factory_start_session`
&nbsp;&nbsp;&nbsp;&nbsp;`resolveRunRepositoryFromIntake(intake, args)` ·
reads the Linear mapping, then Ward's `resolveRunRepository`

removed: `cardSessionRepository` · `firstEnvironmentRepository` ·
`cardRepositorySlug` · `cardLinearProjectId` · `useCardRepositorySlug`

### Decisions

- **a GET the draft reads, not one call that resolves and starts** — the
refusal has to show before the first prompt; `runs/start` still checks
on its own.

### Not verified

- [ ] a real Factory with an unlinked GitHub repository: covered by the
route tests and the draft's MSW tests only

---

> ██████████████████ **tests** `+257 −320` — net −63
> ███████████ **source** `+217 −150` — net +67
> ███ **generated** `+83`
> █ **changeset** `+17`





<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
<!-- coderabbit-ai-generated:v1 -->

ELI5: A Factory card used to choose its own code repository in the app,
and that choice could be wrong. Now the server chooses the repository,
and a card starts a session only when the server finds one.

## Summary

This pull request moves repository selection for Factory card sessions
from the client to the server. It changes 26 files, with 534 lines added
and 468 removed.

### Server changes (`mastracode/factory`)

- Adds the `GET
/web/factory/projects/:id/work-items/:workItemId/session-repository`
route. The contract is in `routes/contracts.ts`. The handler is in
`routes/work-items.ts`.
- The response is a discriminated union:
  - A resolved result returns `projectRepositoryId` and `slug`.
  - An unlinked result returns a `hint`.
- The route returns 404 when the card is outside the caller's
organization or project. It returns 503 when no `sessionRepository`
resolver is configured.
- Adds `resolveRunRepositoryFromIntake` in
`session/work-item-repository.ts`. It reads Linear intake configuration
for the organization and passes the `repositoryByLinearProject` map to
`resolveRunRepository`. If intake or the map is absent, it passes no
map.
- Adds a provider check. When the active integration has no matching
provider ID, and card metadata contains an ID for another supported
provider (GitHub or GitLab), the result is unlinked, with a hint naming
that provider. This check runs before the repository slug and Linear
mapping are considered.
- `rules/start-coordinator.ts`, `tools/session-tools.ts`, and
`routes/surface.ts` call `resolveRunRepositoryFromIntake`. They no
longer load intake configuration directly.
- `routes/surface.ts` supplies the `sessionRepository` resolver when
source-control integrations are registered. It returns an unlinked
result when no source-control connection resolves.

### Factory UI changes (`mastracode/factory-ui`)

- Adds the `WorkItemSessionRepository` type, the
`workItemSessionRepository` query key, and
`getWorkItemSessionRepository` in `services/workItems.ts`.
- `useCardSessionRepository` takes `factoryId` and a card with `id` and
`updatedAt`. It fetches the repository from the server. The query uses
`staleTime: 0` and refetches on window focus.
- `useStartCardSessionFromDraft` starts a session only when a resolved
repository is available. It no longer writes the selected repository to
the card.
- `CardDraftPage` shows an error message when the lookup fails. It
offers Retry, which is disabled while the lookup runs. It shows the
server hint and a link to repository settings when the result is
unlinked. Sending stays disabled in both cases.
- Removes client-side repository logic from `boardRepository.ts`:
`cardRepositorySlug`, `cardSessionRepository`,
`firstEnvironmentRepository`, and `cardLinearProjectId`. Removes the
`useCardRepositorySlug` hook.
- Adds the `workItemSessionRepository` CLI command in `packages/cli`. It
shows the repository a card session starts in, or the reason none is
available.

### Tests and changesets

- `work-items.test.ts` adds tests for resolved responses, unlinked
responses, and 404 responses. The 404 test confirms that the resolver is
not called.
- `work-item-repository.test.ts` adds parameterized tests. A GitHub card
is unlinked when only a GitLab repository is linked. A GitHub or GitLab
card whose repository isn't linked is named from its URL in the hint.
- `boardRepository.test.ts` targets `cardProjectRepositoryId` and covers
provider-ID lookup. The old slug, session-repository, and
first-environment tests are removed.
- The UI MSW and unit tests now use the endpoint. Environment-based
repository tests are removed.
- The CLI descriptor test expects the new
`factoryWork-itemSession-repository` entry.
- Two changesets declare patch releases for `@mastra/factory`. A third
declares a patch release for `mastra` and documents the new CLI command.

### Behavior notes

- A card with a resolvable repository starts in that repository. The
card is not rewritten.
- A card with no resolvable repository shows the server hint. Sending
stays disabled.
- If the lookup succeeds and a later lookup fails, sending stays
disabled. The PR description reports this as a tested case.
- The PR description says that cards without a repository among several
keep the first-repository behavior. The diff does not confirm this on
the server. The client-side first-environment selector was removed. The
server-side fallback was not checked.

### Verification

- The PR description reports that the unlinked-GitHub scenario was
covered only by route tests and draft MSW tests. It was not verified in
a real Factory.
- CI and build results are not available.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
History 2026-11-16 19:29:51 -08:00
..
src fix(factory): let the server decide which repository a card's session starts in (#30609) 2026-11-16 19:29:51 -08:00
.prettierignore feat(cli): Add api subcommand (#16128) 2026-05-07 09:49:55 +09:00
AGENTS.md chore: enforce AGENTS.md token limits (#15464) 2026-04-18 19:12:37 -07:00
CHANGELOG.md chore: version packages (alpha) (#30516) 2026-11-16 23:44:41 +01:00
lint-staged.config.js refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
mastra-cli.png feat: update image for readme 2024-11-26 18:25:33 +01:00
oxlint.config.ts feat(cli): add Factory API commands (#23226) 2026-09-08 12:07:25 +02:00
package.json chore: version packages (alpha) (#30516) 2026-11-16 23:44:41 +01:00
README.md chore(*): Update/unify/add READMEs (#22858) 2026-09-02 14:36:59 +02:00
tsconfig.build.json cli playground (#6892) 2025-08-22 11:48:18 +02:00
tsconfig.json refactor(lint): replace ESLint with type-aware oxlint (#27476) 2026-10-18 10:38:35 -07:00
tsdown.config.ts build(cli): stop rebuilding Factory UI inside the CLI build (#28717) 2026-10-28 15:22:55 +01:00
turbo.json fix(create-mastra): Bundle deps (#23972) 2026-09-15 12:20:46 +02:00
vitest.config.ts use exact hash matching (#16873) 2026-05-21 15:22:11 +02:00

Mastra CLI

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

The mastra package is Mastra's command-line interface. Use it to initialize projects, run the local development server and Studio, build production output, start built applications, deploy supported projects, manage environment variables, run migrations, and work with evaluations and scorers.

Installation

Install the CLI globally to use mastra from any directory:

npm install --global mastra

If you prefer not to install packages globally, run it through npx:

npx mastra --help

You can also install the CLI locally in a project:

npm install mastra

Usage

Run commands from a Mastra project:

mastra dev
mastra build
mastra start

Use mastra init to add Mastra to an existing TypeScript project, or use create-mastra to scaffold a new application.

mastra init
npx create-mastra@latest

Documentation

Changelog

See the package changelog for version history and release notes.

Support

We have an open community Discord. Come and say hello and let us know if you have any questions or need any help getting things running.